{"openapi":"3.1.0","info":{"title":"ConversaLabs","description":"REST API reference for ConversaLabs.","version":"4.17.1","contact":{"name":"ConversaLabs","url":"https://conversalabs.com.br"},"termsOfService":"https://conversalabs.com.br/termos/"},"servers":[{"url":"https://chatwoot.losangosolucoes.com.br"}],"paths":{"/platform/api/v1/accounts":{"post":{"tags":["Accounts"],"operationId":"create-an-account","summary":"Create an Account","description":"Creates an account. RETROCOMPATIBLE: the legacy payload (name/locale/features/limits/…) behaves exactly as before. The ENRICHED one-call payload (spec 073) additionally accepts `user` (an admin user created and linked as administrator; an existing email is reusable only when the PlatformApp already owns that user), `business_profile` (the versioned generative-onboarding context) and `setup` (how to provision the workspace) — creating the account, admin user, permissibles and a provisioning run in a SINGLE call. The response then carries `setup_run` and (when `user` is sent) `user`; follow the run with GET /platform/api/v1/accounts/{id}/setup. An invalid `setup.blueprint` fails the whole call with 422 and creates nothing.","security":[{"platformAppApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Account name."},"locale":{"type":"string","description":"Account locale (e.g. pt_BR, en, es)."},"domain":{"type":["string","null"]},"support_email":{"type":["string","null"]},"status":{"type":["string","null"],"enum":["active","suspended",null],"description":"Account status."},"features":{"type":"object","additionalProperties":false,"description":"Account features this Platform principal may change. Omitted keys preserve their current value; true enables and false disables only the supplied flag. Super-Admin-only flags are not accepted. Use JSON booleans; legacy 1/0 and true/false/on/off strings are normalized. Other values return 422 invalid_feature_values without changing the account.","properties":{"account_brain":{"type":"boolean","description":"Enables the Account Brain feature."},"ads_conversion_tracking":{"type":"boolean","description":"Enables the Ad Conversion Tracking (Meta CAPI) feature."},"ads_manager":{"type":"boolean","description":"Enables the Ads Manager feature."},"advanced_assignment":{"type":"boolean","description":"Enables the Advanced Assignment feature."},"advanced_search":{"type":"boolean","description":"Enables the Advanced Search feature."},"advanced_search_indexing":{"type":"boolean","description":"Enables the Advanced Search Indexing feature."},"affiliate_program":{"type":"boolean","description":"Enables the Affiliate Program feature."},"agent_bots":{"type":"boolean","description":"Enables the Agent Bots feature."},"agent_management":{"type":"boolean","description":"Enables the Agent Management feature."},"ai_onboarding":{"type":"boolean","description":"Enables the AI Onboarding (Generative Setup) feature."},"api_and_webhooks":{"type":"boolean","description":"Enables the API and Webhooks feature."},"assignment_v2":{"type":"boolean","description":"Enables the Assignment V2 feature."},"audit_logs":{"type":"boolean","description":"Enables the Audit Logs feature."},"auto_resolve_conversations":{"type":"boolean","description":"Enables the Auto Resolve Conversations feature."},"automations":{"type":"boolean","description":"Enables the Automations feature."},"branded_email_templates":{"type":"boolean","description":"Enables the Branded Email Templates feature."},"bug_reports":{"type":"boolean","description":"Enables the Bug Reports feature."},"calendar":{"type":"boolean","description":"Enables the Calendar feature."},"campaign_batched_dispatch":{"type":"boolean","description":"Enables the Campaign Batched Dispatch feature."},"campaign_conversation_policy":{"type":"boolean","description":"Enables the Campaign Conversation Policy feature."},"campaigns":{"type":"boolean","description":"Enables the Campaigns feature."},"canned_responses":{"type":"boolean","description":"Enables the Canned Responses feature."},"captain_document_auto_sync":{"type":"boolean","description":"Enables the Captain Document Auto Sync feature."},"captain_integration":{"type":"boolean","description":"Enables the Captain feature."},"captain_integration_v2":{"type":"boolean","description":"Enables the Captain V2 feature."},"captain_tasks":{"type":"boolean","description":"Enables the Captain Tasks feature."},"captain_v1_action_classifier":{"type":"boolean","description":"Enables the Captain V1 Action Classifier feature."},"catalog":{"type":"boolean","description":"Enables the Product Catalog feature."},"channel_email":{"type":"boolean","description":"Enables the Email Channel feature."},"channel_facebook":{"type":"boolean","description":"Enables the Facebook Channel feature."},"channel_instagram":{"type":"boolean","description":"Enables the Instagram Channel feature."},"channel_tiktok":{"type":"boolean","description":"Enables the TikTok Channel feature."},"channel_voice":{"type":"boolean","description":"Enables the Voice Channel feature."},"channel_website":{"type":"boolean","description":"Enables the Website Channel feature."},"chatwoot_v4":{"type":"boolean","description":"Enables the Dashboard V4 feature."},"commerce_recovery":{"type":"boolean","description":"Enables the Commerce Recovery (Sales Recovery) feature."},"companies":{"type":"boolean","description":"Enables the Companies feature."},"contact_chatwoot_support_team":{"type":"boolean","description":"Enables the Contact support feature."},"contracts":{"type":"boolean","description":"Enables the Contracts \u0026 E-signature feature."},"conversation_glance_signals":{"type":"boolean","description":"Enables the Conversation Glance Signals feature."},"conversation_required_attributes":{"type":"boolean","description":"Enables the Required Conversation Attributes feature."},"conversation_unread_counts":{"type":"boolean","description":"Enables the Conversation Unread Counts feature."},"crm":{"type":"boolean","description":"Enables the CRM feature."},"crm_integration":{"type":"boolean","description":"Enables the CRM Integration feature."},"crm_pipelines":{"type":"boolean","description":"Enables the CRM Pipelines feature."},"crm_v2":{"type":"boolean","description":"Enables the CRM V2 feature."},"csat_review_notes":{"type":"boolean","description":"Enables the CSAT Review Notes feature."},"custom_attributes":{"type":"boolean","description":"Enables the Custom Attributes feature."},"custom_reply_domain":{"type":"boolean","description":"Enables the Custom Reply Domain feature."},"custom_reply_email":{"type":"boolean","description":"Enables the Custom Reply Email feature."},"custom_roles":{"type":"boolean","description":"Enables the Custom Roles feature."},"custom_tools":{"type":"boolean","description":"Enables the Custom Tools feature."},"data_import":{"type":"boolean","description":"Enables the Data Import feature."},"delayed_automations":{"type":"boolean","description":"Enables the Delayed Automations feature."},"disable_branding":{"type":"boolean","description":"Enables the Disable Branding feature. Deprecated flag, kept for backwards compatibility."},"email_continuity_on_api_channel":{"type":"boolean","description":"Enables the Email Continuity on API Channel feature."},"engagement_tracking":{"type":"boolean","description":"Enables the Engagement \u0026 Lead Score feature."},"field_level_permissions":{"type":"boolean","description":"Enables the Field-level Permissions feature."},"flow_builder":{"type":"boolean","description":"Enables the Flow Builder feature."},"flow_builder_runtime_v2":{"type":"boolean","description":"Enables the Flow Builder Runtime V2 feature."},"follow_ups":{"type":"boolean","description":"Enables the Follow-up feature."},"governance_lgpd":{"type":"boolean","description":"Enables the Governance \u0026 LGPD feature."},"granular_permissions":{"type":"boolean","description":"Enables the Granular Permissions feature."},"growth_ads":{"type":"boolean","description":"Enables the Growth Ads (CTWA \u0026 Lead Ads) feature."},"growth_social":{"type":"boolean","description":"Enables the Growth Social (Comment-to-DM) feature."},"growth_social_automation":{"type":"boolean","description":"Enables the Growth Social Automation (IG/TikTok/YouTube) feature."},"guided_tours":{"type":"boolean","description":"Enables the Guided Tours feature."},"help_center":{"type":"boolean","description":"Enables the Help Center feature."},"help_center_embedding_search":{"type":"boolean","description":"Enables the Help Center Embedding Search feature."},"inbound_emails":{"type":"boolean","description":"Enables the Inbound Emails feature."},"inbox_management":{"type":"boolean","description":"Enables the Inbox Management feature."},"inbox_view":{"type":"boolean","description":"Enables the Inbox View feature."},"integrations":{"type":"boolean","description":"Enables the Integrations feature."},"internal_chat":{"type":"boolean","description":"Enables the Internal Chat feature."},"ip_lookup":{"type":"boolean","description":"Enables the IP Lookup feature."},"labels":{"type":"boolean","description":"Enables the Labels feature."},"launch_group_distribution":{"type":"boolean","description":"Enables the Launch Group Distribution feature."},"linear_integration":{"type":"boolean","description":"Enables the Linear Integration feature."},"macros":{"type":"boolean","description":"Enables the Macros feature."},"maestro_byok":{"type":"boolean","description":"Enables the Maestro BYOK (Account LLM Keys) feature."},"maestro_global_keys":{"type":"boolean","description":"Enables the Maestro Installation LLM Keys (Global Fallback) feature."},"mcp":{"type":"boolean","description":"Enables the MCP (Model Context Protocol) feature."},"media_library":{"type":"boolean","description":"Enables the Media Library feature."},"message_reply_to":{"type":"boolean","description":"Enables the Message Reply To feature. Deprecated flag, kept for backwards compatibility."},"message_scheduling":{"type":"boolean","description":"Enables the Message Scheduling feature."},"native_advanced_search":{"type":"boolean","description":"Enables the Advanced Search (Native) feature."},"native_audit_trail":{"type":"boolean","description":"Enables the Audit Trail (Native) feature."},"native_event_pipeline_v2":{"type":"boolean","description":"Enables the Native Event Pipeline V2 feature."},"native_twilio_voice":{"type":"boolean","description":"Enables the Twilio Voice feature."},"notion_integration":{"type":"boolean","description":"Enables the Notion Integration feature."},"orders_registry":{"type":"boolean","description":"Enables the CRM Orders Registry feature."},"organizations":{"type":"boolean","description":"Enables the Organizations (Companies \u0026 Relationships) feature."},"outbound_agent_name_header":{"type":"boolean","description":"Enables the Outbound Agent Name Header feature."},"payment_installment_plans":{"type":"boolean","description":"Enables the Payment installment plans feature."},"payments":{"type":"boolean","description":"Enables the Payments feature."},"platform_governance":{"type":"boolean","description":"Enables the Platform Governance feature."},"realtime_translation":{"type":"boolean","description":"Enables the Realtime Translation feature."},"reply_mailer_migration":{"type":"boolean","description":"Enables the Reply Mailer Migration feature."},"report_rollup":{"type":"boolean","description":"Enables the Report Rollup feature."},"reports":{"type":"boolean","description":"Enables the Reports feature."},"sales_management":{"type":"boolean","description":"Enables the Sales Management feature."},"saml":{"type":"boolean","description":"Enables the SAML feature."},"search_with_gin":{"type":"boolean","description":"Enables the Search messages with GIN feature."},"session_analytics":{"type":"boolean","description":"Enables the Session Analytics feature."},"setup_blueprints":{"type":"boolean","description":"Enables the Setup Blueprints feature."},"shopify_integration":{"type":"boolean","description":"Enables the Shopify Integration feature."},"sla":{"type":"boolean","description":"Enables the SLA feature."},"smart_routing":{"type":"boolean","description":"Enables the Smart Routing feature."},"social_collaboration":{"type":"boolean","description":"Enables the Social Collaboration Network (Matrix) feature."},"tasks":{"type":"boolean","description":"Enables the Tasks feature."},"team_management":{"type":"boolean","description":"Enables the Team Management feature."},"unified_revenue_ledger":{"type":"boolean","description":"Enables the Unified Revenue Ledger feature."},"unread_count_for_filters":{"type":"boolean","description":"Enables the Unread Count For Filters feature."},"usage_metering":{"type":"boolean","description":"Enables the Usage Metering feature."},"voice_recorder":{"type":"boolean","description":"Enables the Voice Recorder feature."},"whatsapp_campaign":{"type":"boolean","description":"Enables the WhatsApp Campaign feature."},"whatsapp_cost_center":{"type":"boolean","description":"Enables the WhatsApp cost center feature."},"whatsapp_embedded_signup":{"type":"boolean","description":"Enables the WhatsApp Embedded Signup feature. Deprecated flag, kept for backwards compatibility."},"whatsapp_embedded_signup_inbox_creation":{"type":"boolean","description":"Enables the WhatsApp Embedded Signup Flow feature."},"whatsapp_hub":{"type":"boolean","description":"Enables the WhatsApp Hub feature."},"whatsapp_hybrid_inbox":{"type":"boolean","description":"Enables the WhatsApp Hybrid Inbox feature."},"whatsapp_hybrid_unified_inbox":{"type":"boolean","description":"Enables the WhatsApp Hybrid Unified Inbox feature."},"whatsapp_hybrid_weighted_routing":{"type":"boolean","description":"Enables the WhatsApp Hybrid Weighted Routing feature."},"whatsapp_inbox_suite":{"type":"boolean","description":"Enables the WhatsApp Inbox Suite feature."},"whatsapp_manual_transfer":{"type":"boolean","description":"Enables the WhatsApp Manual Transfer feature."},"whatsapp_mobile_egress":{"type":"boolean","description":"Enables the WhatsApp Web Mobile Connection feature."},"whatsapp_outbound_batching":{"type":"boolean","description":"Enables the WhatsApp Outbound Batching feature."},"whatsapp_outbound_maestro":{"type":"boolean","description":"Enables the WhatsApp Outbound Maestro Review feature."},"whatsapp_outbound_rich_transform":{"type":"boolean","description":"Enables the WhatsApp Outbound Rich Transform feature."},"whatsapp_reconfigure":{"type":"boolean","description":"Enables the WhatsApp Reconfigure feature."},"whatsapp_web_proxy":{"type":"boolean","description":"Enables the WhatsApp Web Global Proxy feature."},"white_label":{"type":"boolean","description":"Enables the White Label feature."},"workforce_management":{"type":"boolean","description":"Enables the Team Management feature."}},"x-example-sparse":"feature-mutation","example":{"inbound_emails":true}},"limits":{"type":"object","additionalProperties":false,"description":"Per-account caps stored on account.limits. Whole numbers of 0 or more; a numeric string (\"10\") is coerced, and an omitted key (or one sent blank) means UNLIMITED — as does a ZERO, which every enforcement point treats as \"no cap\" rather than \"allow none\". Any key outside the set below is rejected with 422 `invalid_limits`. captain_responses, captain_documents and emails are only enforced on the Enterprise build; the `\u003cmetric\u003e_monthly` caps are the soft usage ceilings (spec 073) behind the 80%/100% threshold events and the usage panel.","properties":{"agents":{"type":"integer","minimum":0,"description":"Maximum number of agents."},"inboxes":{"type":"integer","minimum":0,"description":"Maximum number of inboxes."},"media_storage_mb":{"type":"integer","minimum":0,"description":"Media Library storage quota in MB."},"captain_responses":{"type":"integer","minimum":0,"description":"Maximum Captain AI responses (enterprise build only)."},"captain_documents":{"type":"integer","minimum":0,"description":"Maximum Captain knowledge documents (enterprise build only)."},"emails":{"type":"integer","minimum":0,"description":"Maximum outbound conversation emails (enterprise build only)."},"messages_monthly":{"type":"integer","minimum":0,"description":"Soft monthly cap on messages."},"conversations_monthly":{"type":"integer","minimum":0,"description":"Soft monthly cap on conversations."},"contacts_monthly":{"type":"integer","minimum":0,"description":"Soft monthly cap on new contacts."},"ai_requests_monthly":{"type":"integer","minimum":0,"description":"Soft monthly cap on AI requests."},"ai_tokens_monthly":{"type":"integer","minimum":0,"description":"Soft monthly cap on AI tokens."}}},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Arbitrary account custom attributes."},"user":{"type":"object","description":"One-call admin user. A new managed identity is created and linked as administrator; an existing email is accepted only when that user is already explicitly permissible to this PlatformApp. The service generates its internal bootstrap password — callers must not supply a password.","properties":{"name":{"type":"string"},"email":{"type":"string"}}},"business_profile":{"type":"object","additionalProperties":true,"description":"Versioned generative-onboarding context (spec 073 REQ-001): business_name, website, industry, sub_segment, company_size, team_size, sales_model, avg_ticket, products_services, tone_of_voice, locale, timezone, working_hours_hint, social, main_channels, goals. Stored under custom_attributes.business_profile and used to personalize the provisioned workspace."},"setup":{"type":"object","description":"How to provision the workspace. `skip` wins; then an explicit `blueprint`; then `mode`.","properties":{"mode":{"type":"string","enum":["autonomous","interactive"],"description":"autonomous = provision in the background from the context; interactive = the admin lands on the SetupWizard on first login. Both enable the account's ai_onboarding surface."},"template":{"type":"string","enum":["default","clinica","ecommerce","imobiliaria","educacao","servicos"],"description":"Vertical template key used as the deterministic base for the provisioned workspace."},"blueprint":{"type":["object","null"],"additionalProperties":true,"example":{"version":1,"meta":{"source":"api"},"features":{},"limits":{},"sections":{}},"description":"An explicit SetupBlueprint the integrator supplies (envelope version/meta/features/ limits/sections) — re-validated server-side; an operator-triggered run may enable premium features and set limits, but Super-Admin-only rollout flags are always dropped."},"skip":{"type":"boolean","description":"Create the account only — no provisioning run, and the global onboarding mode is suppressed for this account."}}}}},"example":{"name":"Clínica Sorriso","locale":"pt_BR","features":{"inbound_emails":true,"help_center":true,"campaigns":false},"user":{"name":"Dra. Ana","email":"ana@sorriso.com.br"},"business_profile":{"business_name":"Clínica Sorriso","industry":"clinica","company_size":"2-10","main_channels":["whatsapp","instagram"],"goals":["atender_melhor","agendar"]},"setup":{"mode":"autonomous","template":"clinica","blueprint":null,"skip":false},"domain":"example.com","support_email":"agent@example.com","status":"active","limits":{"agents":1,"inboxes":1,"media_storage_mb":1,"captain_responses":1,"captain_documents":1,"emails":1,"messages_monthly":1,"conversations_monthly":1,"contacts_monthly":1,"ai_requests_monthly":1,"ai_tokens_monthly":1},"custom_attributes":{}}}}},"responses":{"200":{"description":"The created account. The one-call payload additionally returns `user` and `setup_run{id,status,mode}` (id is null with status \"scheduled\" for the async autonomous/interactive path; a real id with the run status for the explicit-blueprint path).","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/platform_account"},{"type":"object","properties":{"user":{"$ref":"#/components/schemas/platform_user"},"setup_run":{"type":["object","null"],"description":"The provisioning run created by `setup` (present only on the one-call path).","properties":{"id":{"type":["integer","null"],"description":"Run id, or null for the async scheduled modes."},"status":{"type":"string","enum":["scheduled","pending","running","completed","partial","failed","canceled"],"description":"Run status, or \"scheduled\" for the async autonomous/interactive modes."},"mode":{"type":["string","null"],"enum":["autonomous","interactive","api",null]}}}}}]},"example":{"id":42,"name":"Clínica Sorriso","locale":"pt_BR","setup_run":{"id":null,"status":"scheduled","mode":"autonomous"},"domain":"example.com","support_email":"support@example.com","features":{"inbound_emails":true,"help_center":true},"custom_attributes":{"plan_name":"pro"},"limits":{"agents":10,"inboxes":20,"media_storage_mb":2048,"captain_responses":1000,"captain_documents":100,"emails":5000,"messages_monthly":50000,"conversations_monthly":5000,"contacts_monthly":10000,"ai_requests_monthly":2000,"ai_tokens_monthly":1000000},"status":"active","user":{"id":42,"name":"Ana Costa","display_name":"Ana","email":"ana@example.com","available_name":"Ana Costa","avatar_url":"https://app.example.com/rails/active_storage/blobs/avatar.png","confirmed":true,"message_signature":"Atendimento ConversaLabs","provider":"email","custom_attributes":{"department":"Support"},"ui_settings":{"conversation_display_type":"expanded"},"uid":"ana@example.com"}}}}},"409":{"description":"The requested one-call admin email belongs to an existing user not explicitly permissible to this PlatformApp. No account, membership or permissible row is created.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["existing_user_not_permissible"]}}},"example":{"error":"existing_user_not_permissible"}}}},"422":{"description":"The payload was rejected at the boundary and NOTHING was created. `invalid_features` — a key outside this installation's feature registry; `super_admin_managed_features` — a Platform App attempted to mutate a Super-Admin-only rollout flag; `invalid_feature_values` — a feature value cannot be normalized; `invalid_limits` — a key outside the accepted limit dimensions; `invalid_blueprint` — the one-call setup.blueprint failed validation; `platform_identity_credentials_are_not_mutable` — a caller tried to provide a human password. Exactly one shape is returned, carrying only the list that matches `error`.","content":{"application/json":{"schema":{"oneOf":[{"type":"object","description":"An unknown feature key was sent.","properties":{"error":{"type":"string","enum":["invalid_features"]},"unknown_features":{"type":"array","description":"The feature keys that are not in this installation's registry.","items":{"type":"string"}}}},{"type":"object","description":"Super-Admin-only feature flags were sent.","properties":{"error":{"type":"string","enum":["super_admin_managed_features"]},"features":{"type":"array","description":"Feature keys that can be changed only from Super Admin.","items":{"type":"string"}}}},{"type":"object","description":"Feature values could not be normalized; no account attributes were changed.","required":["error","features"],"properties":{"error":{"type":"string","enum":["invalid_feature_values"]},"features":{"type":"array","description":"Names of the invalid feature values, or features when the map itself is invalid. Values are never echoed.","items":{"type":"string"}}}},{"type":"object","description":"An unknown limit dimension was sent.","properties":{"error":{"type":"string","enum":["invalid_limits"]},"unknown_limits":{"type":"array","description":"The limit keys outside the accepted dimensions.","items":{"type":"string"}}}},{"type":"object","description":"The one-call setup.blueprint failed validation.","properties":{"error":{"type":"string","enum":["invalid_blueprint"]},"details":{"type":"array","description":"One human-readable message per blueprint validation failure.","items":{"type":"string"}}}},{"type":"object","description":"A caller attempted to choose a reusable password for the managed identity.","properties":{"error":{"type":"string","enum":["platform_identity_credentials_are_not_mutable"]},"attributes":{"type":"array","items":{"type":"string"}}}}]},"example":{"error":"invalid_blueprint","details":["labels: 31 items exceeds cap of 30"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"get":{"tags":["Accounts"],"operationId":"auto_get_platform_api_v1_accounts","summary":"List accounts","description":"Returns the list of accounts visible to the authenticated caller.","security":[{"platformAppApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"locale":{"type":"string"},"domain":{"type":"string"},"support_email":{"type":"string","format":"email"},"features":{"type":"string"},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"limits":{"type":"string"},"status":{"type":"string","enum":["active","suspended"]}}}},"example":[{"id":1,"name":"Sample Name","locale":"en","domain":"example.com","support_email":"agent@example.com","features":"sample features","custom_attributes":{},"limits":"sample limits","status":"active"}]}}}},"parameters":[{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."}]}},"/platform/api/v1/accounts/{account_id}":{"parameters":[{"$ref":"#/components/parameters/account_id"}],"get":{"tags":["Accounts"],"operationId":"get-details-of-an-account","summary":"Get an account details","description":"Get the details of an account","security":[{"platformAppApiKey":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/platform_account"},"example":{"id":1,"name":"My Account","locale":"en","domain":"example.com","support_email":"support@example.com","features":{"inbound_emails":true,"help_center":true},"custom_attributes":{"plan_name":"pro"},"limits":{"agents":10,"inboxes":20,"media_storage_mb":2048,"captain_responses":1000,"captain_documents":100,"emails":5000,"messages_monthly":50000,"conversations_monthly":5000,"contacts_monthly":10000,"ai_requests_monthly":2000,"ai_tokens_monthly":1000000},"status":"active"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"The given account does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"patch":{"tags":["Accounts"],"operationId":"update-an-account","summary":"Update an account","description":"Update an account's attributes","security":[{"platformAppApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/account_create_update_payload"},"example":{"name":"My Account","locale":"en","domain":"example.com","support_email":"support@example.com","status":"active","features":{"campaigns":false,"help_center":true,"inbound_emails":true},"limits":{"agents":10,"inboxes":20,"media_storage_mb":2048,"captain_responses":1000,"captain_documents":100,"emails":5000,"messages_monthly":50000,"conversations_monthly":5000,"contacts_monthly":10000,"ai_requests_monthly":2000,"ai_tokens_monthly":1000000},"custom_attributes":{"plan_name":"pro"}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/platform_account"},"example":{"id":1,"name":"My Account","locale":"en","domain":"example.com","support_email":"support@example.com","features":{"inbound_emails":true,"help_center":true},"custom_attributes":{"plan_name":"pro"},"limits":{"agents":10,"inboxes":20,"media_storage_mb":2048,"captain_responses":1000,"captain_documents":100,"emails":5000,"messages_monthly":50000,"conversations_monthly":5000,"contacts_monthly":10000,"ai_requests_monthly":2000,"ai_tokens_monthly":1000000},"status":"active"}}}},"422":{"description":"The payload was rejected at the boundary and nothing was changed. `invalid_features` — a key outside this installation's feature registry; `super_admin_managed_features` — a Platform App attempted to mutate a Super-Admin-only rollout flag; `invalid_feature_values` — a feature value cannot be normalized; `invalid_limits` — a key outside the accepted limit dimensions. Exactly one shape is returned, carrying only the list that matches `error`.","content":{"application/json":{"schema":{"oneOf":[{"type":"object","description":"An unknown feature key was sent.","properties":{"error":{"type":"string","enum":["invalid_features"]},"unknown_features":{"type":"array","description":"The feature keys that are not in this installation's registry.","items":{"type":"string"}}}},{"type":"object","description":"Super-Admin-only feature flags were sent.","properties":{"error":{"type":"string","enum":["super_admin_managed_features"]},"features":{"type":"array","description":"Feature keys that can be changed only from Super Admin.","items":{"type":"string"}}}},{"type":"object","description":"Feature values could not be normalized; no account attributes were changed.","required":["error","features"],"properties":{"error":{"type":"string","enum":["invalid_feature_values"]},"features":{"type":"array","description":"Names of the invalid feature values, or features when the map itself is invalid. Values are never echoed.","items":{"type":"string"}}}},{"type":"object","description":"An unknown limit dimension was sent.","properties":{"error":{"type":"string","enum":["invalid_limits"]},"unknown_limits":{"type":"array","description":"The limit keys outside the accepted dimensions.","items":{"type":"string"}}}}]},"example":{"error":"invalid_limits","unknown_limits":["warp_cores"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"put":{"tags":["Accounts"],"operationId":"auto_put_platform_api_v1_accounts_id","summary":"Update an account","description":"Update an account's attributes","security":[{"platformAppApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/account_create_update_payload"},"example":{"name":"My Account","locale":"en","domain":"example.com","support_email":"support@example.com","status":"active","features":{"campaigns":false,"help_center":true,"inbound_emails":true},"limits":{"agents":10,"inboxes":20,"media_storage_mb":2048,"captain_responses":1000,"captain_documents":100,"emails":5000,"messages_monthly":50000,"conversations_monthly":5000,"contacts_monthly":10000,"ai_requests_monthly":2000,"ai_tokens_monthly":1000000},"custom_attributes":{"plan_name":"pro"}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/platform_account"},"example":{"id":1,"name":"My Account","locale":"en","domain":"example.com","support_email":"support@example.com","features":{"inbound_emails":true,"help_center":true},"custom_attributes":{"plan_name":"pro"},"limits":{"agents":10,"inboxes":20,"media_storage_mb":2048,"captain_responses":1000,"captain_documents":100,"emails":5000,"messages_monthly":50000,"conversations_monthly":5000,"contacts_monthly":10000,"ai_requests_monthly":2000,"ai_tokens_monthly":1000000},"status":"active"}}}},"422":{"description":"The payload was rejected at the boundary and nothing was changed. `invalid_features` — a key outside this installation's feature registry; `super_admin_managed_features` — a Platform App attempted to mutate a Super-Admin-only rollout flag; `invalid_feature_values` — a feature value cannot be normalized; `invalid_limits` — a key outside the accepted limit dimensions. Exactly one shape is returned, carrying only the list that matches `error`.","content":{"application/json":{"schema":{"oneOf":[{"type":"object","description":"An unknown feature key was sent.","properties":{"error":{"type":"string","enum":["invalid_features"]},"unknown_features":{"type":"array","description":"The feature keys that are not in this installation's registry.","items":{"type":"string"}}}},{"type":"object","description":"Super-Admin-only feature flags were sent.","properties":{"error":{"type":"string","enum":["super_admin_managed_features"]},"features":{"type":"array","description":"Feature keys that can be changed only from Super Admin.","items":{"type":"string"}}}},{"type":"object","description":"Feature values could not be normalized; no account attributes were changed.","required":["error","features"],"properties":{"error":{"type":"string","enum":["invalid_feature_values"]},"features":{"type":"array","description":"Names of the invalid feature values, or features when the map itself is invalid. Values are never echoed.","items":{"type":"string"}}}},{"type":"object","description":"An unknown limit dimension was sent.","properties":{"error":{"type":"string","enum":["invalid_limits"]},"unknown_limits":{"type":"array","description":"The limit keys outside the accepted dimensions.","items":{"type":"string"}}}}]},"example":{"error":"invalid_limits","unknown_limits":["warp_cores"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"delete":{"tags":["Accounts"],"operationId":"delete-an-account","summary":"Delete an Account","description":"Requests account deletion. If the existing teardown receipt has exhausted publisher or effect retries, the request is refused with 409 account_teardown_receipt_exhausted. That refusal does not reset or replace the receipt or schedule new processing. Other conflicts retain their existing behavior.","security":[{"platformAppApiKey":[]}],"responses":{"200":{"description":"Success"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"The account does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"409":{"description":"The existing account teardown receipt has exhausted publisher or effect retries.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","enum":["account_teardown_receipt_exhausted"]}}},"example":{"error":"account_teardown_receipt_exhausted"}}}}}}},"/platform/api/v1/accounts/{account_id}/account_users":{"parameters":[{"$ref":"#/components/parameters/account_id"}],"get":{"tags":["Account Users"],"operationId":"list-all-account-users","summary":"List all Account Users","description":"List all account users","security":[{"platformAppApiKey":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/account_user"},"example":[{"account_id":1,"user_id":1,"role":"agent"}]}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"post":{"tags":["Account Users"],"operationId":"create-an-account-user","summary":"Create an Account User","description":"Create an Account User","security":[{"platformAppApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/account_user_create_update_payload"},"example":{"user_id":1,"role":"administrator"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"account_id":{"type":"integer","description":"The ID of the account"},"user_id":{"type":"integer","description":"The ID of the user"},"role":{"type":"string","description":"whether user is an administrator or agent","enum":["administrator","agent"]}}},"example":{"account_id":1,"user_id":1,"role":"administrator"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"delete":{"tags":["Account Users"],"operationId":"delete-an-account-user","summary":"Delete an Account User","description":"Delete an Account User","security":[{"platformAppApiKey":[]}],"responses":{"200":{"description":"Success"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"The account does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/platform/api/v1/agent_bots":{"get":{"tags":["AgentBots"],"operationId":"list-all-agent-bots","summary":"List all AgentBots","description":"Lists only account-bound bots explicitly permissible to the PlatformApp whose account is also permissible to it. System bots and historical cross-account rows are omitted.","security":[{"platformAppApiKey":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"array","description":"Array of agent bots","items":{"$ref":"#/components/schemas/platform_agent_bot"}},"example":[{"id":18,"name":"Support relay","description":"Relays support events to the managed workflow.","outgoing_url":"https://automation.example.com/chatwoot/events","account_id":7,"receive_incoming_when_assigned":false,"receive_incoming_when_assigned_configurable":true}]}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"post":{"tags":["AgentBots"],"operationId":"create-an-agent-bot","summary":"Create an Agent Bot","description":"Creates an account-bound agent bot. `account_id` is required and must be an Account explicitly permissible to the calling PlatformApp; this endpoint cannot create a system-wide bot.","security":[{"platformAppApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/platform_agent_bot_create_payload"},"example":{"name":"Support relay","description":"Relays support events to the managed workflow.","outgoing_url":"https://automation.example.com/chatwoot/events","account_id":7,"avatar":"sample avatar","avatar_url":"https://example.com/assets/support-relay.png","receive_incoming_when_assigned":false}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/platform_agent_bot"},"example":{"id":18,"name":"Support relay","description":"Relays support events to the managed workflow.","outgoing_url":"https://automation.example.com/chatwoot/events","account_id":7,"receive_incoming_when_assigned":false,"receive_incoming_when_assigned_configurable":true}}}},"422":{"description":"`account_id` was absent or blank, or the submitted bot did not satisfy validation.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["account_id is required"]}}},"example":{"error":"account_id is required"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/platform/api/v1/agent_bots/{id}":{"parameters":[{"$ref":"#/components/parameters/agent_bot_id"}],"get":{"tags":["AgentBots"],"operationId":"get-details-of-a-single-agent-bot","summary":"Get an agent bot details","description":"Gets an account-bound bot explicitly permissible to the PlatformApp. Its account must also remain permissible; credentials and webhook secrets are never returned.","security":[{"platformAppApiKey":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/platform_agent_bot"},"example":{"id":18,"name":"Support relay","description":"Relays support events to the managed workflow.","outgoing_url":"https://automation.example.com/chatwoot/events","account_id":7,"receive_incoming_when_assigned":false,"receive_incoming_when_assigned_configurable":true}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"The given agent bot ID does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"patch":{"tags":["AgentBots"],"operationId":"update-an-agent-bot","summary":"Update an agent bot","description":"Updates an account-bound bot. A supplied `account_id` must identify a permissible account; blank/null values are rejected because PlatformApps cannot create system bots.","security":[{"platformAppApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/platform_agent_bot_update_payload"},"example":{"name":"Support relay","description":"Relays support events to the managed workflow.","outgoing_url":"https://automation.example.com/chatwoot/events","account_id":7,"avatar":"sample avatar","avatar_url":"https://example.com/assets/support-relay.png","receive_incoming_when_assigned":true}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/platform_agent_bot"},"example":{"id":18,"name":"Support relay","description":"Relays support events to the managed workflow.","outgoing_url":"https://automation.example.com/chatwoot/events","account_id":7,"receive_incoming_when_assigned":false,"receive_incoming_when_assigned_configurable":true}}}},"422":{"description":"A blank account_id was supplied, or the submitted bot did not satisfy validation.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["account_id is required"]}}},"example":{"error":"account_id is required"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"put":{"tags":["AgentBots"],"operationId":"update-an-agent-bot-via-put","summary":"Update an agent bot via PUT","description":"PUT is accepted with the same partial-update semantics as PATCH for an account-bound bot. A supplied `account_id` must identify a permissible account; blank/null values are rejected because PlatformApps cannot create system bots.","security":[{"platformAppApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/platform_agent_bot_update_payload"},"example":{"name":"Support relay","description":"Relays support events to the managed workflow.","outgoing_url":"https://automation.example.com/chatwoot/events","account_id":7,"avatar":"sample avatar","avatar_url":"https://example.com/assets/support-relay.png","receive_incoming_when_assigned":true}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/platform_agent_bot"},"example":{"id":18,"name":"Support relay","description":"Relays support events to the managed workflow.","outgoing_url":"https://automation.example.com/chatwoot/events","account_id":7,"receive_incoming_when_assigned":false,"receive_incoming_when_assigned_configurable":true}}}},"422":{"description":"A blank account_id was supplied, or the submitted bot did not satisfy validation.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["account_id is required"]}}},"example":{"error":"account_id is required"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"delete":{"tags":["AgentBots"],"operationId":"delete-an-agent-bot","summary":"Delete an AgentBot","description":"Delete an AgentBot","security":[{"platformAppApiKey":[]}],"responses":{"200":{"description":"Success"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"The agent bot does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/platform/api/v1/agent_bots/{id}/avatar":{"parameters":[{"$ref":"#/components/parameters/agent_bot_id"}],"delete":{"tags":["AgentBots"],"operationId":"delete-an-agent-bot-avatar","summary":"Remove an Agent Bot avatar","description":"Removes the avatar from an account-bound bot explicitly permissible to the PlatformApp. The bot's scoped response never contains a bot access token, webhook secret or other credential.","security":[{"platformAppApiKey":[]}],"responses":{"200":{"description":"The avatar was removed (or was already absent) and the scoped bot record is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/platform_agent_bot"},"example":{"id":18,"name":"Support relay","description":"Relays support events to the managed workflow.","outgoing_url":"https://automation.example.com/chatwoot/events","account_id":7,"receive_incoming_when_assigned":false,"receive_incoming_when_assigned_configurable":true}}}},"401":{"description":"Missing/invalid PlatformApp credential, bot permission, or account permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"The agent bot does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/platform/api/v1/users":{"post":{"tags":["Users"],"operationId":"create-a-user","summary":"Create a User","description":"Creates a new PlatformApp-managed identity. An existing email is idempotent only when that user is already explicitly permissible to the same PlatformApp; the endpoint never claims an arbitrary existing person and never accepts a caller-chosen password.","security":[{"platformAppApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/platform_user_create_payload"},"example":{"name":"Ana Costa","display_name":"Ana","email":"ana@example.com","custom_attributes":{"department":"Support"}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/platform_user"},"example":{"id":42,"name":"Ana Costa","display_name":"Ana","email":"ana@example.com","available_name":"Ana Costa","avatar_url":"https://app.example.com/rails/active_storage/blobs/avatar.png","confirmed":true,"message_signature":"Atendimento ConversaLabs","provider":"email","custom_attributes":{"department":"Support"},"ui_settings":{"conversation_display_type":"expanded"},"uid":"ana@example.com"}}}},"409":{"description":"The supplied email already belongs to a user not permissible to this PlatformApp.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["existing_user_not_permissible"]}}},"example":{"error":"existing_user_not_permissible"}}}},"422":{"description":"A caller supplied a password or the new user did not satisfy validation.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"attributes":{"type":"array","items":{"type":"string"}}}},"example":{"error":"platform_identity_credentials_are_not_mutable","attributes":["password"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/platform/api/v1/users/{id}":{"parameters":[{"$ref":"#/components/parameters/platform_user_id"}],"get":{"tags":["Users"],"operationId":"get-details-of-a-user","summary":"Get an user details","description":"Gets a user explicitly permissible to the PlatformApp. The response contains only scoped identity presentation data and never contains credentials or account memberships.","security":[{"platformAppApiKey":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/platform_user"},"example":{"id":42,"name":"Ana Costa","display_name":"Ana","email":"ana@example.com","available_name":"Ana Costa","avatar_url":"https://app.example.com/rails/active_storage/blobs/avatar.png","confirmed":true,"message_signature":"Atendimento ConversaLabs","provider":"email","custom_attributes":{"department":"Support"},"ui_settings":{"conversation_display_type":"expanded"},"uid":"ana@example.com"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"The given user does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"patch":{"tags":["Users"],"operationId":"update-a-user","summary":"Update a user","description":"Updates non-credential attributes of a PlatformApp-managed user. The user must not belong to an account outside the caller's permissible account set; `email` and `password` are intentionally rejected rather than delegated through this API.","security":[{"platformAppApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/platform_user_update_payload"},"example":{"name":"Ana Costa","display_name":"Ana","custom_attributes":{"department":"Customer Success"}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/platform_user"},"example":{"id":42,"name":"Ana Costa","display_name":"Ana","email":"ana@example.com","available_name":"Ana Costa","avatar_url":"https://app.example.com/rails/active_storage/blobs/avatar.png","confirmed":true,"message_signature":"Atendimento ConversaLabs","provider":"email","custom_attributes":{"department":"Support"},"ui_settings":{"conversation_display_type":"expanded"},"uid":"ana@example.com"}}}},"422":{"description":"`email` or `password` was supplied, or the change did not satisfy validation.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["platform_identity_credentials_are_not_mutable"]},"attributes":{"type":"array","items":{"type":"string"}}}},"example":{"error":"platform_identity_credentials_are_not_mutable","attributes":["email"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"The given user does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"put":{"tags":["Users"],"operationId":"update-a-user-via-put","summary":"Update a user via PUT","description":"PUT is accepted with the same partial-update semantics as PATCH for a PlatformApp-managed user. The user must not belong to an account outside the caller's permissible account set; `email` and `password` are intentionally rejected rather than delegated through this API.","security":[{"platformAppApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/platform_user_update_payload"},"example":{"name":"Ana Costa","display_name":"Ana","custom_attributes":{"department":"Customer Success"}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/platform_user"},"example":{"id":42,"name":"Ana Costa","display_name":"Ana","email":"ana@example.com","available_name":"Ana Costa","avatar_url":"https://app.example.com/rails/active_storage/blobs/avatar.png","confirmed":true,"message_signature":"Atendimento ConversaLabs","provider":"email","custom_attributes":{"department":"Support"},"ui_settings":{"conversation_display_type":"expanded"},"uid":"ana@example.com"}}}},"422":{"description":"`email` or `password` was supplied, or the change did not satisfy validation.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["platform_identity_credentials_are_not_mutable"]},"attributes":{"type":"array","items":{"type":"string"}}}},"example":{"error":"platform_identity_credentials_are_not_mutable","attributes":["password"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"The given user does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"delete":{"tags":["Users"],"operationId":"delete-a-user","summary":"Delete a User","description":"Delete a User","security":[{"platformAppApiKey":[]}],"responses":{"200":{"description":"Success"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"The user does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/platform/api/v1/users/{id}/login":{"parameters":[{"$ref":"#/components/parameters/platform_user_id"}],"get":{"tags":["Users"],"operationId":"get-sso-url-of-a-user","summary":"Get User SSO Link","description":"Retired delegation endpoint. A PlatformApp credential is not allowed to mint an SSO session for a user, even when that user is permissible. A future scoped OAuth 2.1 consent flow is the only valid delegation design; it is not provided by this endpoint.","security":[{"platformAppApiKey":[]}],"responses":{"403":{"description":"Platform user delegation is disabled; this endpoint never returns an SSO URL.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["platform_user_delegation_disabled"],"description":"Stable reason the legacy delegation endpoint is unavailable."}}},"example":{"error":"platform_user_delegation_disabled"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"The given user does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/platform/api/v1/users/{id}/token":{"parameters":[{"$ref":"#/components/parameters/platform_user_id"}],"post":{"tags":["Users"],"operationId":"post-user-token","summary":"Get User Access Token","description":"Retired delegation endpoint. A PlatformApp credential is not allowed to mint an installation-wide user access token, even for a permissible user. A future scoped OAuth 2.1 consent flow is the only valid delegation design; it is not provided here.","security":[{"platformAppApiKey":[]}],"responses":{"403":{"description":"Platform user delegation is disabled; this endpoint never returns an access token.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["platform_user_delegation_disabled"],"description":"Stable reason the legacy delegation endpoint is unavailable."}}},"example":{"error":"platform_user_delegation_disabled"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"The given user does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/public/api/v1/inboxes/{inbox_identifier}":{"parameters":[{"$ref":"#/components/parameters/public_inbox_identifier"}],"get":{"tags":["Inbox API"],"operationId":"get-details-of-a-inbox","summary":"Inbox details","description":"Get the details of an inbox","security":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/public_inbox"},"example":{"identifier":"sample-identifier","name":"Sample Name","timezone":"America/Sao_Paulo","working_hours":[{"day_of_week":1,"open_all_day":true,"closed_all_day":true,"open_hour":1,"open_minutes":60,"close_hour":1,"close_minutes":60}],"working_hours_enabled":true,"csat_survey_enabled":true,"greeting_enabled":true,"identity_validation_enabled":true}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"The given inbox does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/public/api/v1/inboxes/{inbox_identifier}/contacts":{"parameters":[{"$ref":"#/components/parameters/public_inbox_identifier"}],"post":{"tags":["Contacts API"],"operationId":"create-a-contact","summary":"Create a contact","description":"Create a contact","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/public_contact_create_update_payload"},"example":{"identifier":"1234567890","identifier_hash":"e93275d4eba0e5679ad55f5360af00444e2a888df9b0afa3e8b691c3173725f9","email":"alice@acme.inc","name":"Alice","phone_number":"+123456789","avatar":"sample avatar","custom_attributes":{}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/public_contact"},"example":{"id":1,"source_id":"sample source id","name":"Sample Name","email":"agent@example.com","phone_number":"+5511999998888","pubsub_token":"sample-token"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/public/api/v1/inboxes/{inbox_identifier}/contacts/{contact_identifier}":{"parameters":[{"$ref":"#/components/parameters/public_inbox_identifier"},{"$ref":"#/components/parameters/public_contact_identifier"}],"get":{"tags":["Contacts API"],"operationId":"get-details-of-a-contact","summary":"Get a contact","description":"Get the details of a contact","security":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/public_contact"},"example":{"id":1,"source_id":"sample source id","name":"Sample Name","email":"agent@example.com","phone_number":"+5511999998888","pubsub_token":"sample-token"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"The given contact does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"patch":{"tags":["Contacts API"],"operationId":"update-a-contact","summary":"Update a contact","description":"Update a contact's attributes. The `name` is treated as an automated name (for example a WhatsApp profile name forwarded by an integration): it replaces a placeholder name — a generated name, a phone number or a masked phone number — but never a real name already set by an agent or the CRM, and a phone number is never accepted as a name. The other attributes are applied as sent. Agents rename a contact through the account contacts API.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/public_contact_create_update_payload"},"example":{"identifier":"1234567890","identifier_hash":"e93275d4eba0e5679ad55f5360af00444e2a888df9b0afa3e8b691c3173725f9","email":"alice@acme.inc","name":"Alice","phone_number":"+123456789","avatar":"sample avatar","custom_attributes":{}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/public_contact_record"},"example":{"id":1,"name":"Sample Name","email":"agent@example.com","phone_number":"+5511999998888","identifier":"sample-identifier","blocked":true,"additional_attributes":{},"custom_attributes":{},"contact_type":"visitor","country_code":"BR","last_activity_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","last_name":"sample last name","middle_name":"sample middle name","location":"sample location","account_id":1,"company_id":1,"label_list":["sample label list"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"put":{"tags":["Public Inboxes"],"operationId":"auto_put_public_api_v1_inboxes_inbox_id_contacts_id","summary":"Update contacts","description":"Updates the contact identified by the path parameters with the submitted attributes.","security":[],"responses":{"200":{"description":"Updated contact (raw model attributes)","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer","example":55},"name":{"type":"string","example":"Jane Doe"},"email":{"type":["string","null"],"example":"jane@example.com"},"phone_number":{"type":["string","null"],"example":"+15550100100"},"account_id":{"type":"integer","example":1},"identifier":{"type":["string","null"],"example":"user-123"},"middle_name":{"type":"string","example":""},"last_name":{"type":"string","example":""},"location":{"type":"string","example":""},"country_code":{"type":"string","example":""},"contact_type":{"type":"string","enum":["visitor","lead","customer"],"example":"visitor"},"blocked":{"type":"boolean","example":false},"company_id":{"type":["integer","null"],"example":null},"organization_id":{"type":["integer","null"],"example":null},"legal_type":{"type":["string","null"],"enum":["individual","business",null],"example":null},"tax_id_type":{"type":["string","null"],"enum":["br_cpf","br_cnpj","us_ein","eu_vat","uk_vat","generic",null],"example":null,"description":"The fiscal identifier scheme used to validate and mask the tax_id (CPF/CNPJ check digits, EIN, EU/UK VAT or a generic fallback)."},"country":{"type":["string","null"],"example":null},"owner_id":{"type":["integer","null"],"example":null},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"additional_attributes":{"type":"object","additionalProperties":true,"description":"Channel- and source-specific metadata for this record (e.g. browser info, referer, social profile identifiers). The key set depends on the originating channel."},"last_activity_at":{"type":["string","null"],"format":"date-time","example":"2026-01-15T10:30:00.000Z"},"created_at":{"type":"string","format":"date-time","example":"2026-01-15T10:30:00.000Z"},"updated_at":{"type":"string","format":"date-time","example":"2026-01-15T10:30:00.000Z"}}},"example":{"id":55,"name":"Jane Doe","email":"jane@example.com","phone_number":"+15550100100","account_id":1,"identifier":"user-123","middle_name":"","last_name":"","location":"","country_code":"","contact_type":"visitor","blocked":false,"company_id":null,"organization_id":null,"legal_type":null,"tax_id_type":null,"country":null,"owner_id":null,"custom_attributes":{},"additional_attributes":{},"last_activity_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"identifier":{"type":"string"},"identifier_hash":{"type":"string"},"email":{"type":"string","format":"email"},"name":{"type":"string"},"avatar_url":{"type":"string"},"phone_number":{"type":"string"},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."}}},"example":{"identifier":"sample-identifier","identifier_hash":"sample identifier hash","email":"agent@example.com","name":"Sample Name","avatar_url":"https://example.com/resource","phone_number":"+5511999998888","custom_attributes":{}}}}}}},"/public/api/v1/inboxes/{inbox_identifier}/contacts/{contact_identifier}/conversations":{"parameters":[{"$ref":"#/components/parameters/public_inbox_identifier"},{"$ref":"#/components/parameters/public_contact_identifier"}],"post":{"tags":["Conversations API"],"operationId":"create-a-conversation","summary":"Create a conversation","description":"Create a conversation","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/public_conversation_create_payload"},"example":{"custom_attributes":{}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/public_conversation"},"example":{"id":1,"uuid":"sample uuid","inbox_id":1,"contact_last_seen_at":1,"status":"open","agent_last_seen_at":1,"messages":[{"id":1,"content":"Sample content text.","message_type":1,"content_type":"text","content_attributes":{"instagram_mention":{"media_id":"sample media id","comment_id":"sample comment id","mention_type":"comment","enrichment_status":"unresolved","replyable":true,"author_id":"sample author id","author_username":"sample author username","text":"sample text","media_type":"sample media type","media_product_type":"sample media product type","permalink":"https://example.com/resource","identity_scope":{"account_id":1,"inbox_id":1,"instagram_id":"sample instagram id"},"recovery":{"state":"scheduled","reason":"Sample reason.","attempts":1,"checked_at":"2026-01-15T10:30:00.000Z","next_retry_at":"2026-01-15T10:30:00.000Z","lease_until":"2026-01-15T10:30:00.000Z"}},"translations":{},"translation":{"original_content":"sample original content","original_html_content":"sample original html content","delivery":{"status":"translated","source_language":"pt","target_language":"en","provider":"google_translate","content_digest":"sample content digest","translated_at":"2026-01-15T10:30:00.000Z","error_code":"translation_failed","cause_code":"provider_not_configured","failed_at":"2026-01-15T10:30:00.000Z"},"views":{}},"external_error":"sample external error","contact_share":{"origin":"contact_request","transport":"cloud","status":"linked","reason":"identity_owned_by_another_contact","other_contact_ids":[1],"reconciliation_id":"sample reconciliation id"}},"created_at":1,"conversation_id":1,"attachments":[{"id":1,"message_id":1,"file_type":"image","account_id":1,"extension":"sample extension","data_url":"https://example.com/resource","media_readiness_revision":"sample media readiness revision","playable_audio_url":"https://example.com/resource","playable_video_url":"https://example.com/resource","video_processing":true,"video_unavailable":true,"thumb_url":"https://example.com/resource","file_size":1,"width":1,"height":1,"coordinates_lat":12.5,"coordinates_long":12.5,"fallback_title":"sample fallback title","meta":{},"transcribed_text":"sample transcribed text","transcript_translations":{"pt-BR":"Você pode me ajudar?","es":"¿Puedes ayudarme?"},"transcript_translation_states":{}}],"sender":{"id":1,"name":"Sample Name","avatar_url":"https://example.com/resource","thumbnail":"sample thumbnail","type":"contact","available_name":"sample available name","availability_status":"online","email":"agent@example.com","phone_number":"+5511999998888","identifier":"sample-identifier","blocked":true,"additional_attributes":{},"custom_attributes":{},"description":"A short description.","created_at":"2026-01-15T10:30:00.000Z"}}],"contact":{"id":1,"name":"Sample Name","email":"agent@example.com","phone_number":"+5511999998888","identifier":"sample-identifier","blocked":true,"additional_attributes":{},"custom_attributes":{},"contact_type":"visitor","country_code":"BR","last_activity_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","last_name":"sample last name","middle_name":"sample middle name","location":"sample location","account_id":1,"company_id":1,"label_list":["sample label list"]}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"get":{"tags":["Conversations API"],"operationId":"list-all-contact-conversations","summary":"List all conversations","description":"List all conversations for the contact","security":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"array","description":"Array of conversations","items":{"$ref":"#/components/schemas/public_conversation"}},"example":[{"id":1,"uuid":"sample uuid","inbox_id":1,"contact_last_seen_at":1,"status":"open","agent_last_seen_at":1,"messages":[{"id":1,"content":"Sample content text.","message_type":1,"content_type":"text","content_attributes":{"instagram_mention":{"media_id":"sample media id","comment_id":"sample comment id","mention_type":"comment","enrichment_status":"unresolved","replyable":true,"author_id":"sample author id","author_username":"sample author username","text":"sample text","media_type":"sample media type","media_product_type":"sample media product type","permalink":"https://example.com/resource","identity_scope":{"account_id":1,"inbox_id":1,"instagram_id":"sample instagram id"},"recovery":{"state":"scheduled","reason":"Sample reason.","attempts":1,"checked_at":"2026-01-15T10:30:00.000Z","next_retry_at":"2026-01-15T10:30:00.000Z","lease_until":"2026-01-15T10:30:00.000Z"}},"translations":{},"translation":{"original_content":"sample original content","original_html_content":"sample original html content","delivery":{"status":"translated","source_language":"pt","target_language":"en","provider":"google_translate","content_digest":"sample content digest","translated_at":"2026-01-15T10:30:00.000Z","error_code":"translation_failed","cause_code":"provider_not_configured","failed_at":"2026-01-15T10:30:00.000Z"},"views":{}},"external_error":"sample external error","contact_share":{"origin":"contact_request","transport":"cloud","status":"linked","reason":"identity_owned_by_another_contact","other_contact_ids":[1],"reconciliation_id":"sample reconciliation id"}},"created_at":1,"conversation_id":1,"attachments":[{"id":1,"message_id":1,"file_type":"image","account_id":1,"extension":"sample extension","data_url":"https://example.com/resource","media_readiness_revision":"sample media readiness revision","playable_audio_url":"https://example.com/resource","playable_video_url":"https://example.com/resource","video_processing":true,"video_unavailable":true,"thumb_url":"https://example.com/resource","file_size":1,"width":1,"height":1,"coordinates_lat":12.5,"coordinates_long":12.5,"fallback_title":"sample fallback title","meta":{},"transcribed_text":"sample transcribed text","transcript_translations":{"pt-BR":"Você pode me ajudar?","es":"¿Puedes ayudarme?"},"transcript_translation_states":{}}],"sender":{"id":1,"name":"Sample Name","avatar_url":"https://example.com/resource","thumbnail":"sample thumbnail","type":"contact","available_name":"sample available name","availability_status":"online","email":"agent@example.com","phone_number":"+5511999998888","identifier":"sample-identifier","blocked":true,"additional_attributes":{},"custom_attributes":{},"description":"A short description.","created_at":"2026-01-15T10:30:00.000Z"}}],"contact":{"id":1,"name":"Sample Name","email":"agent@example.com","phone_number":"+5511999998888","identifier":"sample-identifier","blocked":true,"additional_attributes":{},"custom_attributes":{},"contact_type":"visitor","country_code":"BR","last_activity_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","last_name":"sample last name","middle_name":"sample middle name","location":"sample location","account_id":1,"company_id":1,"label_list":["sample label list"]}}]}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/public/api/v1/inboxes/{inbox_identifier}/contacts/{contact_identifier}/conversations/{conversation_id}":{"parameters":[{"$ref":"#/components/parameters/public_inbox_identifier"},{"$ref":"#/components/parameters/public_contact_identifier"},{"$ref":"#/components/parameters/conversation_id"}],"get":{"tags":["Conversations API"],"operationId":"get-single-conversation","summary":"Get a single conversation","description":"Retrieves the details of a specific conversation","security":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/public_conversation"},"example":{"id":1,"uuid":"sample uuid","inbox_id":1,"contact_last_seen_at":1,"status":"open","agent_last_seen_at":1,"messages":[{"id":1,"content":"Sample content text.","message_type":1,"content_type":"text","content_attributes":{"instagram_mention":{"media_id":"sample media id","comment_id":"sample comment id","mention_type":"comment","enrichment_status":"unresolved","replyable":true,"author_id":"sample author id","author_username":"sample author username","text":"sample text","media_type":"sample media type","media_product_type":"sample media product type","permalink":"https://example.com/resource","identity_scope":{"account_id":1,"inbox_id":1,"instagram_id":"sample instagram id"},"recovery":{"state":"scheduled","reason":"Sample reason.","attempts":1,"checked_at":"2026-01-15T10:30:00.000Z","next_retry_at":"2026-01-15T10:30:00.000Z","lease_until":"2026-01-15T10:30:00.000Z"}},"translations":{},"translation":{"original_content":"sample original content","original_html_content":"sample original html content","delivery":{"status":"translated","source_language":"pt","target_language":"en","provider":"google_translate","content_digest":"sample content digest","translated_at":"2026-01-15T10:30:00.000Z","error_code":"translation_failed","cause_code":"provider_not_configured","failed_at":"2026-01-15T10:30:00.000Z"},"views":{}},"external_error":"sample external error","contact_share":{"origin":"contact_request","transport":"cloud","status":"linked","reason":"identity_owned_by_another_contact","other_contact_ids":[1],"reconciliation_id":"sample reconciliation id"}},"created_at":1,"conversation_id":1,"attachments":[{"id":1,"message_id":1,"file_type":"image","account_id":1,"extension":"sample extension","data_url":"https://example.com/resource","media_readiness_revision":"sample media readiness revision","playable_audio_url":"https://example.com/resource","playable_video_url":"https://example.com/resource","video_processing":true,"video_unavailable":true,"thumb_url":"https://example.com/resource","file_size":1,"width":1,"height":1,"coordinates_lat":12.5,"coordinates_long":12.5,"fallback_title":"sample fallback title","meta":{},"transcribed_text":"sample transcribed text","transcript_translations":{"pt-BR":"Você pode me ajudar?","es":"¿Puedes ayudarme?"},"transcript_translation_states":{}}],"sender":{"id":1,"name":"Sample Name","avatar_url":"https://example.com/resource","thumbnail":"sample thumbnail","type":"contact","available_name":"sample available name","availability_status":"online","email":"agent@example.com","phone_number":"+5511999998888","identifier":"sample-identifier","blocked":true,"additional_attributes":{},"custom_attributes":{},"description":"A short description.","created_at":"2026-01-15T10:30:00.000Z"}}],"contact":{"id":1,"name":"Sample Name","email":"agent@example.com","phone_number":"+5511999998888","identifier":"sample-identifier","blocked":true,"additional_attributes":{},"custom_attributes":{},"contact_type":"visitor","country_code":"BR","last_activity_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","last_name":"sample last name","middle_name":"sample middle name","location":"sample location","account_id":1,"company_id":1,"label_list":["sample label list"]}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"Conversation not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/public/api/v1/inboxes/{inbox_identifier}/contacts/{contact_identifier}/conversations/{conversation_id}/toggle_status":{"parameters":[{"$ref":"#/components/parameters/public_inbox_identifier"},{"$ref":"#/components/parameters/public_contact_identifier"},{"$ref":"#/components/parameters/conversation_id"}],"post":{"tags":["Conversations API"],"operationId":"resolve-conversation","summary":"Resolve a conversation","description":"Marks a conversation as resolved","security":[],"responses":{"200":{"description":"Conversation resolved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/public_conversation"},"example":{"id":1,"uuid":"sample uuid","inbox_id":1,"contact_last_seen_at":1,"status":"open","agent_last_seen_at":1,"messages":[{"id":1,"content":"Sample content text.","message_type":1,"content_type":"text","content_attributes":{"instagram_mention":{"media_id":"sample media id","comment_id":"sample comment id","mention_type":"comment","enrichment_status":"unresolved","replyable":true,"author_id":"sample author id","author_username":"sample author username","text":"sample text","media_type":"sample media type","media_product_type":"sample media product type","permalink":"https://example.com/resource","identity_scope":{"account_id":1,"inbox_id":1,"instagram_id":"sample instagram id"},"recovery":{"state":"scheduled","reason":"Sample reason.","attempts":1,"checked_at":"2026-01-15T10:30:00.000Z","next_retry_at":"2026-01-15T10:30:00.000Z","lease_until":"2026-01-15T10:30:00.000Z"}},"translations":{},"translation":{"original_content":"sample original content","original_html_content":"sample original html content","delivery":{"status":"translated","source_language":"pt","target_language":"en","provider":"google_translate","content_digest":"sample content digest","translated_at":"2026-01-15T10:30:00.000Z","error_code":"translation_failed","cause_code":"provider_not_configured","failed_at":"2026-01-15T10:30:00.000Z"},"views":{}},"external_error":"sample external error","contact_share":{"origin":"contact_request","transport":"cloud","status":"linked","reason":"identity_owned_by_another_contact","other_contact_ids":[1],"reconciliation_id":"sample reconciliation id"}},"created_at":1,"conversation_id":1,"attachments":[{"id":1,"message_id":1,"file_type":"image","account_id":1,"extension":"sample extension","data_url":"https://example.com/resource","media_readiness_revision":"sample media readiness revision","playable_audio_url":"https://example.com/resource","playable_video_url":"https://example.com/resource","video_processing":true,"video_unavailable":true,"thumb_url":"https://example.com/resource","file_size":1,"width":1,"height":1,"coordinates_lat":12.5,"coordinates_long":12.5,"fallback_title":"sample fallback title","meta":{},"transcribed_text":"sample transcribed text","transcript_translations":{"pt-BR":"Você pode me ajudar?","es":"¿Puedes ayudarme?"},"transcript_translation_states":{}}],"sender":{"id":1,"name":"Sample Name","avatar_url":"https://example.com/resource","thumbnail":"sample thumbnail","type":"contact","available_name":"sample available name","availability_status":"online","email":"agent@example.com","phone_number":"+5511999998888","identifier":"sample-identifier","blocked":true,"additional_attributes":{},"custom_attributes":{},"description":"A short description.","created_at":"2026-01-15T10:30:00.000Z"}}],"contact":{"id":1,"name":"Sample Name","email":"agent@example.com","phone_number":"+5511999998888","identifier":"sample-identifier","blocked":true,"additional_attributes":{},"custom_attributes":{},"contact_type":"visitor","country_code":"BR","last_activity_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","last_name":"sample last name","middle_name":"sample middle name","location":"sample location","account_id":1,"company_id":1,"label_list":["sample label list"]}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"Conversation not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/public/api/v1/inboxes/{inbox_identifier}/contacts/{contact_identifier}/conversations/{conversation_id}/toggle_typing":{"parameters":[{"$ref":"#/components/parameters/public_inbox_identifier"},{"$ref":"#/components/parameters/public_contact_identifier"},{"$ref":"#/components/parameters/conversation_id"}],"post":{"tags":["Conversations API"],"operationId":"toggle-typing-status","summary":"Toggle typing status","description":"Toggles the typing status in a conversation","security":[],"parameters":[{"name":"typing_status","in":"query","required":true,"schema":{"type":"string"},"description":"Typing status, either 'on' or 'off'"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"typing_status":{"type":"string","enum":["on","off"],"description":"The typing status to set","example":"on"}}},"example":{"typing_status":"on"}}}},"responses":{"200":{"description":"Typing status toggled successfully"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"Conversation not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/public/api/v1/inboxes/{inbox_identifier}/contacts/{contact_identifier}/conversations/{conversation_id}/update_last_seen":{"parameters":[{"$ref":"#/components/parameters/public_inbox_identifier"},{"$ref":"#/components/parameters/public_contact_identifier"},{"$ref":"#/components/parameters/conversation_id"}],"post":{"tags":["Conversations API"],"operationId":"update-last-seen","summary":"Update last seen and mark messages read","description":"Updates the contact's last seen time for the conversation and marks agent messages\nsent before that time as read. Use this to send read receipts from a custom client\nbuilt on the API channel, so agents can see when the contact has read their messages.\n","security":[],"responses":{"200":{"description":"Last seen updated successfully"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"Conversation not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/public/api/v1/inboxes/{inbox_identifier}/contacts/{contact_identifier}/conversations/{conversation_id}/messages":{"parameters":[{"$ref":"#/components/parameters/public_inbox_identifier"},{"$ref":"#/components/parameters/public_contact_identifier"},{"$ref":"#/components/parameters/conversation_id"}],"post":{"tags":["Messages API"],"operationId":"create-a-message","summary":"Create a message","description":"Create a message","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/public_message_create_payload"},"example":{"content":"Hello, how can I help you?","echo_id":"1234567890"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/public_message"},"example":{"id":1,"content":"Sample content text.","message_type":1,"content_type":"text","content_attributes":{"instagram_mention":{"media_id":"sample media id","comment_id":"sample comment id","mention_type":"comment","enrichment_status":"unresolved","replyable":true,"author_id":"sample author id","author_username":"sample author username","text":"sample text","media_type":"sample media type","media_product_type":"sample media product type","permalink":"https://example.com/resource","identity_scope":{"account_id":1,"inbox_id":1,"instagram_id":"sample instagram id"},"recovery":{"state":"scheduled","reason":"Sample reason.","attempts":1,"checked_at":"2026-01-15T10:30:00.000Z","next_retry_at":"2026-01-15T10:30:00.000Z","lease_until":"2026-01-15T10:30:00.000Z"}},"translations":{},"translation":{"original_content":"sample original content","original_html_content":"sample original html content","delivery":{"status":"translated","source_language":"pt","target_language":"en","provider":"google_translate","content_digest":"sample content digest","translated_at":"2026-01-15T10:30:00.000Z","error_code":"translation_failed","cause_code":"provider_not_configured","failed_at":"2026-01-15T10:30:00.000Z"},"views":{}},"external_error":"sample external error","contact_share":{"origin":"contact_request","transport":"cloud","status":"linked","reason":"identity_owned_by_another_contact","other_contact_ids":[1],"reconciliation_id":"sample reconciliation id"}},"created_at":1,"conversation_id":1,"attachments":[{"id":1,"message_id":1,"file_type":"image","account_id":1,"extension":"sample extension","data_url":"https://example.com/resource","media_readiness_revision":"sample media readiness revision","playable_audio_url":"https://example.com/resource","playable_video_url":"https://example.com/resource","video_processing":true,"video_unavailable":true,"thumb_url":"https://example.com/resource","file_size":1,"width":1,"height":1,"coordinates_lat":12.5,"coordinates_long":12.5,"fallback_title":"sample fallback title","meta":{},"transcribed_text":"sample transcribed text","transcript_translations":{"pt-BR":"Você pode me ajudar?","es":"¿Puedes ayudarme?"},"transcript_translation_states":{}}],"sender":{"id":1,"name":"Sample Name","avatar_url":"https://example.com/resource","thumbnail":"sample thumbnail","type":"contact","available_name":"sample available name","availability_status":"online","email":"agent@example.com","phone_number":"+5511999998888","identifier":"sample-identifier","blocked":true,"additional_attributes":{},"custom_attributes":{},"description":"A short description.","created_at":"2026-01-15T10:30:00.000Z"}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"get":{"tags":["Messages API"],"operationId":"list-all-conversation-messages","summary":"List all messages","description":"List all messages in the conversation","security":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"array","description":"Array of messages","items":{"$ref":"#/components/schemas/public_message"}},"example":[{"id":1,"content":"Sample content text.","message_type":1,"content_type":"text","content_attributes":{"instagram_mention":{"media_id":"sample media id","comment_id":"sample comment id","mention_type":"comment","enrichment_status":"unresolved","replyable":true,"author_id":"sample author id","author_username":"sample author username","text":"sample text","media_type":"sample media type","media_product_type":"sample media product type","permalink":"https://example.com/resource","identity_scope":{"account_id":1,"inbox_id":1,"instagram_id":"sample instagram id"},"recovery":{"state":"scheduled","reason":"Sample reason.","attempts":1,"checked_at":"2026-01-15T10:30:00.000Z","next_retry_at":"2026-01-15T10:30:00.000Z","lease_until":"2026-01-15T10:30:00.000Z"}},"translations":{},"translation":{"original_content":"sample original content","original_html_content":"sample original html content","delivery":{"status":"translated","source_language":"pt","target_language":"en","provider":"google_translate","content_digest":"sample content digest","translated_at":"2026-01-15T10:30:00.000Z","error_code":"translation_failed","cause_code":"provider_not_configured","failed_at":"2026-01-15T10:30:00.000Z"},"views":{}},"external_error":"sample external error","contact_share":{"origin":"contact_request","transport":"cloud","status":"linked","reason":"identity_owned_by_another_contact","other_contact_ids":[1],"reconciliation_id":"sample reconciliation id"}},"created_at":1,"conversation_id":1,"attachments":[{"id":1,"message_id":1,"file_type":"image","account_id":1,"extension":"sample extension","data_url":"https://example.com/resource","media_readiness_revision":"sample media readiness revision","playable_audio_url":"https://example.com/resource","playable_video_url":"https://example.com/resource","video_processing":true,"video_unavailable":true,"thumb_url":"https://example.com/resource","file_size":1,"width":1,"height":1,"coordinates_lat":12.5,"coordinates_long":12.5,"fallback_title":"sample fallback title","meta":{},"transcribed_text":"sample transcribed text","transcript_translations":{"pt-BR":"Você pode me ajudar?","es":"¿Puedes ayudarme?"},"transcript_translation_states":{}}],"sender":{"id":1,"name":"Sample Name","avatar_url":"https://example.com/resource","thumbnail":"sample thumbnail","type":"contact","available_name":"sample available name","availability_status":"online","email":"agent@example.com","phone_number":"+5511999998888","identifier":"sample-identifier","blocked":true,"additional_attributes":{},"custom_attributes":{},"description":"A short description.","created_at":"2026-01-15T10:30:00.000Z"}}]}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/public/api/v1/inboxes/{inbox_identifier}/contacts/{contact_identifier}/conversations/{conversation_id}/messages/{message_id}":{"parameters":[{"$ref":"#/components/parameters/public_inbox_identifier"},{"$ref":"#/components/parameters/public_contact_identifier"},{"$ref":"#/components/parameters/conversation_id"},{"$ref":"#/components/parameters/message_id"}],"patch":{"tags":["Messages API"],"operationId":"update-a-message","summary":"Update a message","description":"Update a message","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/public_message_update_payload"},"example":{"submitted_values":{"name":"My Name","title":"My Title","value":"value","csat_survey_response":{"feedback_message":"Great service!","rating":5}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/public_message"},"example":{"id":1,"content":"Sample content text.","message_type":1,"content_type":"text","content_attributes":{"instagram_mention":{"media_id":"sample media id","comment_id":"sample comment id","mention_type":"comment","enrichment_status":"unresolved","replyable":true,"author_id":"sample author id","author_username":"sample author username","text":"sample text","media_type":"sample media type","media_product_type":"sample media product type","permalink":"https://example.com/resource","identity_scope":{"account_id":1,"inbox_id":1,"instagram_id":"sample instagram id"},"recovery":{"state":"scheduled","reason":"Sample reason.","attempts":1,"checked_at":"2026-01-15T10:30:00.000Z","next_retry_at":"2026-01-15T10:30:00.000Z","lease_until":"2026-01-15T10:30:00.000Z"}},"translations":{},"translation":{"original_content":"sample original content","original_html_content":"sample original html content","delivery":{"status":"translated","source_language":"pt","target_language":"en","provider":"google_translate","content_digest":"sample content digest","translated_at":"2026-01-15T10:30:00.000Z","error_code":"translation_failed","cause_code":"provider_not_configured","failed_at":"2026-01-15T10:30:00.000Z"},"views":{}},"external_error":"sample external error","contact_share":{"origin":"contact_request","transport":"cloud","status":"linked","reason":"identity_owned_by_another_contact","other_contact_ids":[1],"reconciliation_id":"sample reconciliation id"}},"created_at":1,"conversation_id":1,"attachments":[{"id":1,"message_id":1,"file_type":"image","account_id":1,"extension":"sample extension","data_url":"https://example.com/resource","media_readiness_revision":"sample media readiness revision","playable_audio_url":"https://example.com/resource","playable_video_url":"https://example.com/resource","video_processing":true,"video_unavailable":true,"thumb_url":"https://example.com/resource","file_size":1,"width":1,"height":1,"coordinates_lat":12.5,"coordinates_long":12.5,"fallback_title":"sample fallback title","meta":{},"transcribed_text":"sample transcribed text","transcript_translations":{"pt-BR":"Você pode me ajudar?","es":"¿Puedes ayudarme?"},"transcript_translation_states":{}}],"sender":{"id":1,"name":"Sample Name","avatar_url":"https://example.com/resource","thumbnail":"sample thumbnail","type":"contact","available_name":"sample available name","availability_status":"online","email":"agent@example.com","phone_number":"+5511999998888","identifier":"sample-identifier","blocked":true,"additional_attributes":{},"custom_attributes":{},"description":"A short description.","created_at":"2026-01-15T10:30:00.000Z"}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"put":{"tags":["Public Inboxes"],"operationId":"auto_put_public_api_v1_inboxes_inbox_id_contacts_contact_id_conversations_conversation_id_messages_id","summary":"Update messages","description":"Updates the message identified by the path parameters with the submitted attributes.","security":[],"responses":{"200":{"description":"Updated message (e.g. CSAT survey submission)","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer","example":1024},"content":{"type":["string","null"],"example":"Great support!"},"message_type":{"type":"integer","description":"0 incoming, 1 outgoing, 2 activity, 3 template","example":0},"content_type":{"type":"string","example":"input_csat","enum":["text","input_text","input_textarea","input_email","input_select","cards","form","article","incoming_email","input_csat","integrations","sticker","voice_call","poll"],"description":"Structured content type of the message (drives how content_attributes is interpreted)."},"content_attributes":{"type":"object","example":{"submitted_values":{"csat_survey_response":{"rating":5,"feedback_message":"Great support!"}}},"additionalProperties":true,"description":"Structured metadata accompanying the message content; the key set depends on content_type (e.g. select items, CSAT submission values, deletion flags, external delivery errors)."},"created_at":{"type":"integer","description":"unix epoch seconds","example":1737800000},"conversation_id":{"type":"integer","description":"conversation display_id","example":33},"attachments":{"type":"array","items":{"type":"object"},"description":"Present when attachments exist"},"sender":{"type":"object","description":"Present when a sender exists","example":{"id":12,"name":"Visitor"},"additionalProperties":true}}},"example":{"id":1024,"content":"Great support!","message_type":0,"content_type":"input_csat","content_attributes":{"submitted_values":{"csat_survey_response":{"rating":5,"feedback_message":"Great support!"}}},"created_at":1737800000,"conversation_id":33,"attachments":[{}],"sender":{"id":12,"name":"Visitor"}}}}},"422":{"description":"CSAT survey update window elapsed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"You cannot update the CSAT survey after 14 days"}}},"example":{"error":"You cannot update the CSAT survey after 14 days"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"submitted_values":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Free-form object."}}}},"example":{"submitted_values":[{}]}}}}}},"/survey/responses/{conversation_uuid}":{"parameters":[{"$ref":"#/components/parameters/conversation_uuid"}],"get":{"tags":["CSAT Survey Page"],"operationId":"get-csat-survey-page","summary":"Get CSAT survey page","description":"Serves the hosted satisfaction-survey page for a conversation, identified by the conversation's public identifier. Redirect the customer to this URL instead of building the survey component yourself. The response is an HTML document — NOT JSON: it is the shell of the survey application, carrying the installation branding and loading the survey assets, which then read and submit the rating through the public survey endpoints. The page is public and takes no authentication.","security":[],"responses":{"200":{"description":"The survey page. The document is returned for any well-formed identifier; whether a survey actually exists for it is resolved by the page itself once it loads.","content":{"text/html":{"schema":{"type":"string","description":"The survey page as a complete HTML document."},"example":"\u003c!DOCTYPE html\u003e\n\u003chtml\u003e\n  \u003chead\u003e\u003ctitle\u003eConversaLabs\u003c/title\u003e\u003c/head\u003e\n  \u003cbody\u003e\u003cdiv id=\"app\"\u003e\u003c/div\u003e\u003c/body\u003e\n\u003c/html\u003e\n"}}}}}},"/api/v1/accounts/{account_id}":{"parameters":[{"$ref":"#/components/parameters/account_id"}],"get":{"tags":["Account"],"operationId":"get-account-details","summary":"Get account details","description":"Get the details of the current account","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/account_show_response"},"example":{"id":1,"name":"Sample Name","locale":"en","domain":"example.com","support_email":"agent@example.com","status":"active","created_at":"2026-01-15T10:30:00.000Z","cache_keys":{"label":"0000000000","inbox":"0000000000","team":"0000000000"},"features":{"inbound_emails":true,"help_center":true},"settings":{"auto_resolve_after":12.5,"auto_resolve_message":"sample auto resolve message","auto_resolve_ignore_waiting":true,"auto_resolve_allow_waiting":true,"outbound_agent_name_header_required":true},"custom_attributes":{"plan_name":"sample plan name","subscribed_quantity":12.5,"subscription_status":"sample subscription status","subscription_ends_on":"2026-01-15","industry":"sample industry","company_size":"sample company size","timezone":"America/Sao_Paulo","logo":"sample logo","onboarding_step":"sample onboarding step","guided_tours":{"autoplay":true,"reset_at":"2026-08-05T12:30:00.000Z"},"marked_for_deletion_at":"2026-01-15T10:30:00.000Z","marked_for_deletion_reason":"sample marked for deletion reason"},"latest_chatwoot_version":"3.0.0","subscribed_features":["sample subscribed feature"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"Account not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"patch":{"tags":["Account"],"operationId":"update-account","summary":"Update account","description":"Update account details, settings, and custom attributes","security":[{"userApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/account_update_payload"},"example":{"name":"My Account","locale":"en","domain":"example.com","support_email":"support@example.com","auto_resolve_after":1440,"auto_resolve_message":"This conversation has been automatically resolved due to inactivity","auto_resolve_ignore_waiting":false,"auto_resolve_allow_waiting":false,"outbound_agent_name_header_required":false,"industry":"Technology","company_size":"50-100","timezone":"America/Sao_Paulo","guided_tours":{"autoplay":true,"reset":true}}},"application/x-www-form-urlencoded":{"schema":{"$ref":"#/components/schemas/account_update_payload"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/account_detail"},"example":{"id":1,"name":"Sample Name","locale":"en","domain":"example.com","support_email":"agent@example.com","status":"active","created_at":"2026-01-15T10:30:00.000Z","cache_keys":{"label":"0000000000","inbox":"0000000000","team":"0000000000"},"features":{"inbound_emails":true,"help_center":true},"settings":{"auto_resolve_after":12.5,"auto_resolve_message":"sample auto resolve message","auto_resolve_ignore_waiting":true,"auto_resolve_allow_waiting":true,"outbound_agent_name_header_required":true},"custom_attributes":{"plan_name":"sample plan name","subscribed_quantity":12.5,"subscription_status":"sample subscription status","subscription_ends_on":"2026-01-15","industry":"sample industry","company_size":"sample company size","timezone":"America/Sao_Paulo","logo":"sample logo","onboarding_step":"sample onboarding step","guided_tours":{"autoplay":true,"reset_at":"2026-08-05T12:30:00.000Z"},"marked_for_deletion_at":"2026-01-15T10:30:00.000Z","marked_for_deletion_reason":"sample marked for deletion reason"}}}}},"401":{"description":"Unauthorized (requires the administrator role or account_settings_manage permission)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"Account not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"put":{"tags":["Account"],"operationId":"auto_put_api_v1_accounts_id","summary":"Update account","description":"Update account details, settings, and custom attributes","security":[{"userApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/account_update_payload"},"example":{"name":"My Account","locale":"en","domain":"example.com","support_email":"support@example.com","auto_resolve_after":1440,"auto_resolve_message":"This conversation has been automatically resolved due to inactivity","auto_resolve_ignore_waiting":false,"auto_resolve_allow_waiting":false,"outbound_agent_name_header_required":false,"industry":"Technology","company_size":"50-100","timezone":"America/Sao_Paulo","guided_tours":{"autoplay":true,"reset":true}}},"application/x-www-form-urlencoded":{"schema":{"$ref":"#/components/schemas/account_update_payload"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/account_detail"},"example":{"id":1,"name":"Sample Name","locale":"en","domain":"example.com","support_email":"agent@example.com","status":"active","created_at":"2026-01-15T10:30:00.000Z","cache_keys":{"label":"0000000000","inbox":"0000000000","team":"0000000000"},"features":{"inbound_emails":true,"help_center":true},"settings":{"auto_resolve_after":12.5,"auto_resolve_message":"sample auto resolve message","auto_resolve_ignore_waiting":true,"auto_resolve_allow_waiting":true,"outbound_agent_name_header_required":true},"custom_attributes":{"plan_name":"sample plan name","subscribed_quantity":12.5,"subscription_status":"sample subscription status","subscription_ends_on":"2026-01-15","industry":"sample industry","company_size":"sample company size","timezone":"America/Sao_Paulo","logo":"sample logo","onboarding_step":"sample onboarding step","guided_tours":{"autoplay":true,"reset_at":"2026-08-05T12:30:00.000Z"},"marked_for_deletion_at":"2026-01-15T10:30:00.000Z","marked_for_deletion_reason":"sample marked for deletion reason"}}}}},"401":{"description":"Unauthorized (requires the administrator role or account_settings_manage permission)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"Account not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/audit_logs":{"parameters":[{"$ref":"#/components/parameters/account_id"}],"get":{"tags":["Audit Logs"],"operationId":"get-account-audit-logs","summary":"List Audit Logs in Account","description":"Get Details of Audit Log entries for an Account. This endpoint is only available in Enterprise editions and requires the audit_logs feature to be enabled.","security":[{"userApiKey":[]}],"parameters":[{"name":"page","in":"query","description":"Page number for pagination","required":false,"schema":{"type":"integer","default":1}},{"name":"q","in":"query","description":"Filter entries by the name or email of the user who performed the action","required":false,"schema":{"type":"string"}},{"name":"types","in":"query","description":"Filter entries by the type of the audited record","required":false,"schema":{"type":"array","items":{"type":"string","example":"Inbox"}}},{"name":"since","in":"query","description":"Only return entries created at or after this unix timestamp","required":false,"schema":{"type":"integer","example":1755388800}},{"name":"until","in":"query","description":"Only return entries created at or before this unix timestamp","required":false,"schema":{"type":"integer","example":1755993599}},{"name":"sort","in":"query","description":"Order of the entries by creation time","required":false,"schema":{"type":"string","enum":["desc","asc"],"default":"desc"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"per_page":{"type":"integer","description":"Number of items per page","example":25},"total_entries":{"type":"integer","description":"Total number of audit log entries","example":150},"current_page":{"type":"integer","description":"Current page number","example":1},"audit_logs":{"type":"array","description":"Array of audit log entries","items":{"$ref":"#/components/schemas/audit_log"}}}},"example":{"per_page":25,"total_entries":150,"current_page":1,"audit_logs":[{"id":1,"auditable_id":1,"auditable_type":"Account","auditable":{},"associated_id":1,"associated_type":"Account","user_id":1,"user_type":"User","username":"sample username","action":"create","audited_changes":{},"version":1,"comment":"sample comment","request_uuid":"sample request uuid","created_at":1,"remote_address":"sample remote address"}]}}}},"403":{"description":"Access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"422":{"description":"Feature not enabled or not available in current plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/agent_bots":{"parameters":[{"$ref":"#/components/parameters/account_id"}],"get":{"tags":["Account AgentBots"],"operationId":"list-all-account-agent-bots","summary":"List all AgentBots","description":"List all agent bots available for the current account","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"array","description":"Array of agent bots","items":{"$ref":"#/components/schemas/agent_bot"}},"example":[{"id":1,"name":"Sample Name","description":"A short description.","thumbnail":"sample thumbnail","outgoing_url":"https://example.com/resource","bot_type":"webhook","bot_config":{"maestro_agent_id":77},"receive_incoming_when_assigned":true,"receive_incoming_when_assigned_configurable":true,"account_id":1,"access_token":"sample-token","system_bot":true}]}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"post":{"tags":["Account AgentBots"],"operationId":"create-an-account-agent-bot","summary":"Create an Agent Bot","description":"Create an agent bot in the account","security":[{"userApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agent_bot_create_update_payload"},"example":{"name":"My Agent Bot","description":"This is a sample agent bot","outgoing_url":"https://example.com/webhook","avatar":"sample avatar","avatar_url":"https://example.com/avatar.png","bot_type":0,"bot_config":{},"receive_incoming_when_assigned":false}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agent_bot"},"example":{"id":1,"name":"Sample Name","description":"A short description.","thumbnail":"sample thumbnail","outgoing_url":"https://example.com/resource","bot_type":"webhook","bot_config":{"maestro_agent_id":77},"receive_incoming_when_assigned":true,"receive_incoming_when_assigned_configurable":true,"account_id":1,"access_token":"sample-token","system_bot":true}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/agent_bots/{id}":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"$ref":"#/components/parameters/agent_bot_id"}],"get":{"tags":["Account AgentBots"],"operationId":"get-details-of-a-single-account-agent-bot","summary":"Get an agent bot details","description":"Get the details of an agent bot in the account","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agent_bot"},"example":{"id":1,"name":"Sample Name","description":"A short description.","thumbnail":"sample thumbnail","outgoing_url":"https://example.com/resource","bot_type":"webhook","bot_config":{"maestro_agent_id":77},"receive_incoming_when_assigned":true,"receive_incoming_when_assigned_configurable":true,"account_id":1,"access_token":"sample-token","system_bot":true}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"The given agent bot ID does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"patch":{"tags":["Account AgentBots"],"operationId":"update-an-account-agent-bot","summary":"Update an agent bot","description":"Update an agent bot's attributes","security":[{"userApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agent_bot_create_update_payload"},"example":{"name":"My Agent Bot","description":"This is a sample agent bot","outgoing_url":"https://example.com/webhook","avatar":"sample avatar","avatar_url":"https://example.com/avatar.png","bot_type":0,"bot_config":{},"receive_incoming_when_assigned":false}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agent_bot"},"example":{"id":1,"name":"Sample Name","description":"A short description.","thumbnail":"sample thumbnail","outgoing_url":"https://example.com/resource","bot_type":"webhook","bot_config":{"maestro_agent_id":77},"receive_incoming_when_assigned":true,"receive_incoming_when_assigned_configurable":true,"account_id":1,"access_token":"sample-token","system_bot":true}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"delete":{"tags":["Account AgentBots"],"operationId":"delete-an-account-agent-bot","summary":"Delete an AgentBot","description":"Delete an AgentBot from the account","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Success"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"The agent bot does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"put":{"tags":["Account AgentBots"],"operationId":"auto_put_api_v1_accounts_account_id_agent_bots_id","summary":"Update agent bots","description":"Updates the agent bot identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"thumbnail":{"type":"string"},"outgoing_url":{"type":"string"},"bot_type":{"type":"string","enum":["webhook"]},"bot_config":{"type":"string"},"receive_incoming_when_assigned":{"type":"boolean"},"receive_incoming_when_assigned_configurable":{"type":"boolean"},"account_id":{"type":"integer"},"access_token":{"type":"string"},"secret":{"type":"string"},"system_bot":{"type":"boolean"}}},"example":{"id":1,"name":"Sample Name","description":"A short description.","thumbnail":"sample thumbnail","outgoing_url":"https://example.com/resource","bot_type":"webhook","bot_config":"sample bot config","receive_incoming_when_assigned":true,"receive_incoming_when_assigned_configurable":true,"account_id":1,"access_token":"sample-token","secret":"sample-token","system_bot":true}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"outgoing_url":{"type":"string"},"avatar":{"type":"string"},"avatar_url":{"type":"string"},"bot_type":{"type":"string","enum":["webhook"]},"receive_incoming_when_assigned":{"type":"string"},"bot_config":{"type":"object","additionalProperties":true,"description":"Free-form object."}}},"example":{"name":"Sample Name","description":"A short description.","outgoing_url":"https://example.com/resource","avatar":"sample avatar","avatar_url":"https://example.com/resource","bot_type":"webhook","receive_incoming_when_assigned":"sample receive incoming when assigned","bot_config":{}}}}}}},"/api/v1/accounts/{account_id}/agents":{"parameters":[{"$ref":"#/components/parameters/account_id"}],"get":{"tags":["Agents"],"operationId":"get-account-agents","summary":"List Agents in Account","description":"Get Details of Agents in an Account","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"array","description":"Array of all active agents","items":{"$ref":"#/components/schemas/agent"}},"example":[{"id":1,"account_id":1,"account_user_id":1,"availability_status":"online","auto_offline":true,"confirmed":true,"email":"agent@example.com","available_name":"sample available name","name":"Sample Name","role":"agent","outbound_agent_name_header_policy":"inherit","thumbnail":"sample thumbnail","custom_role_id":1}]}}},"403":{"description":"Access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"post":{"tags":["Agents"],"operationId":"add-new-agent-to-account","summary":"Add a New Agent","description":"Add a new Agent to Account","security":[{"userApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agent_create_payload"},"example":{"name":"John Doe","email":"john.doe@acme.inc","role":"agent","availability":"online","auto_offline":true}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agent"},"example":{"id":1,"account_id":1,"account_user_id":1,"availability_status":"online","auto_offline":true,"confirmed":true,"email":"agent@example.com","available_name":"sample available name","name":"Sample Name","role":"agent","outbound_agent_name_header_policy":"inherit","thumbnail":"sample thumbnail","custom_role_id":1}}}},"403":{"description":"Access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/agents/{id}":{"parameters":[{"$ref":"#/components/parameters/account_id"}],"patch":{"tags":["Agents"],"operationId":"update-agent-in-account","summary":"Update Agent in Account","description":"Update an Agent in Account","security":[{"userApiKey":[]}],"parameters":[{"in":"path","name":"id","schema":{"type":"integer"},"required":true,"description":"The ID of the agent to be updated."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agent_update_payload"},"example":{"role":"agent","outbound_agent_name_header_policy":"inherit","availability":"online","auto_offline":true}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agent"},"example":{"id":1,"account_id":1,"account_user_id":1,"availability_status":"online","auto_offline":true,"confirmed":true,"email":"agent@example.com","available_name":"sample available name","name":"Sample Name","role":"agent","outbound_agent_name_header_policy":"inherit","thumbnail":"sample thumbnail","custom_role_id":1}}}},"404":{"description":"Agent not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"403":{"description":"Access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"delete":{"tags":["Agents"],"operationId":"delete-agent-from-account","summary":"Remove an Agent from Account","description":"Remove an Agent from Account","security":[{"userApiKey":[]}],"parameters":[{"in":"path","name":"id","schema":{"type":"integer"},"required":true,"description":"The ID of the agent to be deleted."}],"responses":{"200":{"description":"Success"},"404":{"description":"Agent not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"403":{"description":"Access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"put":{"tags":["Agents"],"operationId":"auto_put_api_v1_accounts_account_id_agents_id","summary":"Update an agent","description":"Updates the agent's user name and the account-membership attributes (role, availability, auto_offline). Only the supplied keys are changed. Requires manage access over users.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":["integer","null"]},"account_user_id":{"type":["integer","null"]},"availability_status":{"type":"string","enum":["online","offline","busy"],"description":"Realtime availability. Contacts report online/offline (presence-based); agents/users additionally report busy (their configured availability)."},"auto_offline":{"type":"boolean"},"confirmed":{"type":"boolean"},"email":{"type":"string","format":"email"},"provider":{"type":"string","enum":["email","google_oauth2","saml"],"description":"Authentication provider the user signed up through."},"available_name":{"type":"string"},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"name":{"type":"string"},"role":{"type":"string","enum":["agent","administrator"]},"outbound_agent_name_header_policy":{"type":["string","null"]},"thumbnail":{"type":"string"},"custom_role_id":{"type":["integer","null"]},"access_role_id":{"type":["integer","null"]}}},"example":{"id":1,"account_id":1,"account_user_id":1,"availability_status":"online","auto_offline":true,"confirmed":true,"email":"agent@example.com","provider":"email","available_name":"sample available name","custom_attributes":{},"name":"Sample Name","role":"agent","outbound_agent_name_header_policy":"sample outbound agent name header policy","thumbnail":"sample thumbnail","custom_role_id":1,"access_role_id":1}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["agent"],"properties":{"agent":{"type":"object","properties":{"name":{"type":"string","example":"Jane Doe"},"role":{"type":"string","enum":["agent","administrator"],"example":"agent"},"availability":{"type":"string","enum":["online","offline","busy"],"example":"online"},"auto_offline":{"type":"boolean","example":true}}}}},"example":{"agent":{"name":"Jane Doe","role":"agent","availability":"online","auto_offline":true}}}}}}},"/api/v1/accounts/{account_id}/canned_responses":{"parameters":[{"$ref":"#/components/parameters/account_id"}],"get":{"tags":["Canned Responses"],"operationId":"get-account-canned-response","summary":"List canned responses visible to the current user","description":"Returns the account's global canned responses and the personal canned responses authored by the authenticated user. Personal responses authored by other users are never returned.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"array","description":"Global canned responses plus the authenticated user's personal responses.","items":{"$ref":"#/components/schemas/canned_response"}},"example":[{"id":1,"account_id":1,"short_code":"sample short code","content":"Sample content text.","visibility":"personal","created_by":{"id":1,"account_id":1,"account_user_id":1,"availability_status":"online","auto_offline":true,"confirmed":true,"email":"agent@example.com","available_name":"sample available name","name":"Sample Name","role":"agent","outbound_agent_name_header_policy":"inherit","thumbnail":"sample thumbnail","custom_role_id":1},"updated_by":{"id":1,"account_id":1,"account_user_id":1,"availability_status":"online","auto_offline":true,"confirmed":true,"email":"agent@example.com","available_name":"sample available name","name":"Sample Name","role":"agent","outbound_agent_name_header_policy":"inherit","thumbnail":"sample thumbnail","custom_role_id":1},"attachments":[{"id":1,"file_type":"image","file_name":"sample file name","content_type":"sample content type","byte_size":1,"data_url":"https://example.com/resource","thumb_url":"https://example.com/resource","media_deleted":true,"deleted_at":"2026-01-15T10:30:00.000Z"}],"content_attributes":{},"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}]}}},"401":{"description":"Authentication is missing or the account is not accessible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"post":{"tags":["Canned Responses"],"operationId":"add-new-canned-response-to-account","summary":"Add a canned response","description":"Creates a personal or global canned response. Agents without canned-response management permission always create personal responses, even if they submit global visibility.","security":[{"userApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/canned_response_create_payload"},"example":{"content":"Hello, {{contact.name}}! Welcome to our service.","short_code":"welcome","visibility":"personal","content_attributes":{"wa_interactive":{"kind":"buttons","body":"Pick one","buttons":[{"id":"b1","text":"Yes","type":"quick_reply"},{"id":"b2","text":"No","type":"quick_reply"}]}},"library_asset_ids":[21,34],"removed_attachment_ids":[18]}},"multipart/form-data":{"schema":{"$ref":"#/components/schemas/canned_response_create_multipart_payload"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/canned_response"},"example":{"id":1,"account_id":1,"short_code":"sample short code","content":"Sample content text.","visibility":"personal","created_by":{"id":1,"account_id":1,"account_user_id":1,"availability_status":"online","auto_offline":true,"confirmed":true,"email":"agent@example.com","available_name":"sample available name","name":"Sample Name","role":"agent","outbound_agent_name_header_policy":"inherit","thumbnail":"sample thumbnail","custom_role_id":1},"updated_by":{"id":1,"account_id":1,"account_user_id":1,"availability_status":"online","auto_offline":true,"confirmed":true,"email":"agent@example.com","available_name":"sample available name","name":"Sample Name","role":"agent","outbound_agent_name_header_policy":"inherit","thumbnail":"sample thumbnail","custom_role_id":1},"attachments":[{"id":1,"file_type":"image","file_name":"sample file name","content_type":"sample content type","byte_size":1,"data_url":"https://example.com/resource","thumb_url":"https://example.com/resource","media_deleted":true,"deleted_at":"2026-01-15T10:30:00.000Z"}],"content_attributes":{},"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}},"401":{"description":"Authentication is missing or the account is not accessible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/canned_responses/{id}":{"parameters":[{"$ref":"#/components/parameters/account_id"}],"patch":{"tags":["Canned Responses"],"operationId":"update-canned-response-in-account","summary":"Update a visible canned response","description":"Updates a personal response owned by the authenticated user, or a global response when the user is an administrator or holds canned-response management permission.","security":[{"userApiKey":[]}],"parameters":[{"in":"path","name":"id","schema":{"type":"integer"},"required":true,"description":"The ID of the canned response to be updated."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/canned_response_create_update_payload"},"example":{"content":"Hello, {{contact.name}}! Welcome to our service.","short_code":"welcome","visibility":"personal","content_attributes":{"wa_interactive":{"kind":"buttons","body":"Pick one","buttons":[{"id":"b1","text":"Yes","type":"quick_reply"},{"id":"b2","text":"No","type":"quick_reply"}]}},"library_asset_ids":[21,34],"removed_attachment_ids":[18]}},"multipart/form-data":{"schema":{"$ref":"#/components/schemas/canned_response_create_update_multipart_payload"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/canned_response"},"example":{"id":1,"account_id":1,"short_code":"sample short code","content":"Sample content text.","visibility":"personal","created_by":{"id":1,"account_id":1,"account_user_id":1,"availability_status":"online","auto_offline":true,"confirmed":true,"email":"agent@example.com","available_name":"sample available name","name":"Sample Name","role":"agent","outbound_agent_name_header_policy":"inherit","thumbnail":"sample thumbnail","custom_role_id":1},"updated_by":{"id":1,"account_id":1,"account_user_id":1,"availability_status":"online","auto_offline":true,"confirmed":true,"email":"agent@example.com","available_name":"sample available name","name":"Sample Name","role":"agent","outbound_agent_name_header_policy":"inherit","thumbnail":"sample thumbnail","custom_role_id":1},"attachments":[{"id":1,"file_type":"image","file_name":"sample file name","content_type":"sample content type","byte_size":1,"data_url":"https://example.com/resource","thumb_url":"https://example.com/resource","media_deleted":true,"deleted_at":"2026-01-15T10:30:00.000Z"}],"content_attributes":{},"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}},"404":{"description":"Canned response not found in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"401":{"description":"Authentication is missing, the account is not accessible, or the response is not manageable by the user","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"put":{"tags":["Canned Responses"],"operationId":"auto_put_api_v1_accounts_account_id_canned_responses_id","summary":"Update a visible canned response using the PUT compatibility alias","description":"Compatibility alias for the PATCH operation. It updates a personal response owned by the authenticated user, or a global response when the user is an administrator or holds canned-response management permission. Omitted attributes keep their current values.","security":[{"userApiKey":[]}],"parameters":[{"in":"path","name":"id","schema":{"type":"integer"},"required":true,"description":"The ID of the canned response to be updated."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/canned_response_create_update_payload"},"example":{"content":"Hello, {{contact.name}}! Welcome to our service.","short_code":"welcome","visibility":"personal","content_attributes":{"wa_interactive":{"kind":"buttons","body":"Pick one","buttons":[{"id":"b1","text":"Yes","type":"quick_reply"},{"id":"b2","text":"No","type":"quick_reply"}]}},"library_asset_ids":[21,34],"removed_attachment_ids":[18]}},"multipart/form-data":{"schema":{"$ref":"#/components/schemas/canned_response_create_update_multipart_payload"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/canned_response"},"example":{"id":1,"account_id":1,"short_code":"sample short code","content":"Sample content text.","visibility":"personal","created_by":{"id":1,"account_id":1,"account_user_id":1,"availability_status":"online","auto_offline":true,"confirmed":true,"email":"agent@example.com","available_name":"sample available name","name":"Sample Name","role":"agent","outbound_agent_name_header_policy":"inherit","thumbnail":"sample thumbnail","custom_role_id":1},"updated_by":{"id":1,"account_id":1,"account_user_id":1,"availability_status":"online","auto_offline":true,"confirmed":true,"email":"agent@example.com","available_name":"sample available name","name":"Sample Name","role":"agent","outbound_agent_name_header_policy":"inherit","thumbnail":"sample thumbnail","custom_role_id":1},"attachments":[{"id":1,"file_type":"image","file_name":"sample file name","content_type":"sample content type","byte_size":1,"data_url":"https://example.com/resource","thumb_url":"https://example.com/resource","media_deleted":true,"deleted_at":"2026-01-15T10:30:00.000Z"}],"content_attributes":{},"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}},"404":{"description":"Canned response not found in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"401":{"description":"Authentication is missing, the account is not accessible, or the response is not manageable by the user","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"delete":{"tags":["Canned Responses"],"operationId":"delete-canned-response-from-account","summary":"Remove a manageable canned response","description":"Deletes a personal response owned by the authenticated user, or a global response when the user is an administrator or holds canned-response management permission.","security":[{"userApiKey":[]}],"parameters":[{"in":"path","name":"id","schema":{"type":"integer"},"required":true,"description":"The ID of the canned response to be deleted"}],"responses":{"200":{"description":"Success"},"404":{"description":"Canned Response not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"401":{"description":"Authentication is missing, the account is not accessible, or the response is not manageable by the user","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/custom_attribute_definitions":{"parameters":[{"$ref":"#/components/parameters/account_id"}],"get":{"tags":["Custom Attributes"],"operationId":"get-account-custom-attribute","summary":"List all custom attributes in an account","parameters":[{"name":"attribute_model","in":"query","schema":{"type":"string","enum":["0","1"]},"description":"conversation_attribute(0)/contact_attribute(1)","required":true}],"description":"Get details of custom attributes in an Account","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"array","description":"Array of all custom attributes","items":{"$ref":"#/components/schemas/custom_attribute"}},"example":[{"id":1,"attribute_display_name":"sample attribute display name","attribute_display_type":"text","attribute_description":"sample attribute description","attribute_key":"sample-token","regex_pattern":"sample regex pattern","regex_cue":"sample regex cue","attribute_values":"sample attribute values","attribute_model":"sample attribute model","default_value":"sample default value","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}]}}},"403":{"description":"Access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"post":{"tags":["Custom Attributes"],"operationId":"add-new-custom-attribute-to-account","summary":"Add a new custom attribute","description":"Add a new custom attribute to account","security":[{"userApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/custom_attribute_create_update_payload"},"example":{"attribute_display_name":"Custom Attribute","attribute_display_type":0,"attribute_description":"This is a custom attribute","attribute_key":"custom_attribute","attribute_values":["value1","value2"],"attribute_model":0,"regex_pattern":"^[a-zA-Z0-9]+$","regex_cue":"Please enter a valid value"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/custom_attribute"},"example":{"id":1,"attribute_display_name":"sample attribute display name","attribute_display_type":"text","attribute_description":"sample attribute description","attribute_key":"sample-token","regex_pattern":"sample regex pattern","regex_cue":"sample regex cue","attribute_values":"sample attribute values","attribute_model":"sample attribute model","default_value":"sample default value","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}},"403":{"description":"Access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/custom_attribute_definitions/{id}":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"id","in":"path","schema":{"type":"number"},"description":"ID of the custom attribute","required":true}],"get":{"tags":["Custom Attributes"],"operationId":"get-details-of-a-single-custom-attribute","summary":"Get a custom attribute details","security":[{"userApiKey":[]}],"description":"Get the details of a custom attribute in the account","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/custom_attribute"},"example":{"id":1,"attribute_display_name":"sample attribute display name","attribute_display_type":"text","attribute_description":"sample attribute description","attribute_key":"sample-token","regex_pattern":"sample regex pattern","regex_cue":"sample regex cue","attribute_values":"sample attribute values","attribute_model":"sample attribute model","default_value":"sample default value","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"The given attribute ID does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"patch":{"tags":["Custom Attributes"],"operationId":"update-custom-attribute-in-account","summary":"Update custom attribute in Account","description":"Update a custom attribute in account","security":[{"userApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/custom_attribute_create_update_payload"},"example":{"attribute_display_name":"Custom Attribute","attribute_display_type":0,"attribute_description":"This is a custom attribute","attribute_key":"custom_attribute","attribute_values":["value1","value2"],"attribute_model":0,"regex_pattern":"^[a-zA-Z0-9]+$","regex_cue":"Please enter a valid value"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/custom_attribute"},"example":{"id":1,"attribute_display_name":"sample attribute display name","attribute_display_type":"text","attribute_description":"sample attribute description","attribute_key":"sample-token","regex_pattern":"sample regex pattern","regex_cue":"sample regex cue","attribute_values":"sample attribute values","attribute_model":"sample attribute model","default_value":"sample default value","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}},"404":{"description":"Agent not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"403":{"description":"Access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"delete":{"tags":["Custom Attributes"],"operationId":"delete-custom-attribute-from-account","summary":"Remove a custom attribute from account","description":"Remove a custom attribute from account","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Success"},"404":{"description":"Custom attribute not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"403":{"description":"Access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"put":{"tags":["Custom Attributes"],"operationId":"auto_put_api_v1_accounts_account_id_custom_attribute_definitions_id","summary":"Update custom attribute definitions","description":"Updates the custom attribute definition identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"attribute_display_name":{"type":"string"},"attribute_display_type":{"type":"string","enum":["text","number","currency","percent","link","date","list","checkbox"]},"attribute_description":{"type":"string"},"attribute_key":{"type":"string"},"regex_pattern":{"type":"string"},"regex_cue":{"type":"string"},"attribute_values":{"type":"string"},"attribute_model":{"type":"string","enum":["conversation_attribute","contact_attribute","company_attribute","crm_item_attribute","catalog_product_attribute","task_attribute","whatsapp_group_attribute","payment_charge_attribute","calendar_event_attribute","follow_up_attribute","contract_attribute"]},"default_value":{"type":"number"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"example":{"id":1,"attribute_display_name":"sample attribute display name","attribute_display_type":"text","attribute_description":"sample attribute description","attribute_key":"sample-token","regex_pattern":"sample regex pattern","regex_cue":"sample regex cue","attribute_values":"sample attribute values","attribute_model":"conversation_attribute","default_value":149.9,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"custom_attribute_definition":{"type":"object","properties":{"attribute_display_name":{"type":"string"},"attribute_description":{"type":"string"},"attribute_display_type":{"type":"string","enum":["text","number","currency","percent","link","date","list","checkbox"]},"attribute_key":{"type":"string"},"attribute_model":{"type":"string","enum":["conversation_attribute","contact_attribute","company_attribute","crm_item_attribute","catalog_product_attribute","task_attribute","whatsapp_group_attribute","payment_charge_attribute","calendar_event_attribute","follow_up_attribute","contract_attribute"]},"regex_pattern":{"type":"string"},"regex_cue":{"type":"string"},"attribute_values":{"type":"array","items":{"type":"string"}}}}},"required":["custom_attribute_definition"]},"example":{"custom_attribute_definition":{"attribute_display_name":"sample attribute display name","attribute_description":"sample attribute description","attribute_display_type":"text","attribute_key":"sample-token","attribute_model":"conversation_attribute","regex_pattern":"sample regex pattern","regex_cue":"sample regex cue","attribute_values":["sample attribute value"]}}}}}}},"/api/v1/accounts/{account_id}/contacts":{"get":{"tags":["Contacts"],"operationId":"contactList","description":"Listing all the resolved contacts with pagination (Page size = 15). Resolved contacts are the ones with a value for identifier, email or phone number","summary":"List Contacts","security":[{"userApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/account_id"},{"$ref":"#/components/parameters/contact_sort_param"},{"$ref":"#/components/parameters/page"},{"name":"directory","in":"query","schema":{"type":"string","enum":["whatsapp_contact"]},"description":"Optional WhatsApp contact-card projection that excludes technical chat identities and returns one canonical contact per normalized phone number."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/contacts_list_response"},"example":{"meta":{"count":5,"current_page":"sample current page"},"payload":[{"additional_attributes":{"city":"São Paulo","country":"BR","country_code":"BR","created_at_ip":"sample created at ip"},"availability_status":"online","email":"agent@example.com","id":1,"name":"Sample Name","phone_number":"+5511999998888","blocked":true,"identifier":"sample-identifier","referred_by_affiliate_id":1,"referred_by_affiliate_name":"sample referred by affiliate name","legal_type":"individual","tax_id":"sample tax id","tax_id_type":"br_cpf","country":"BR","address":{"zip":"sample zip","street":"sample street","number":"sample number","complement":"sample complement","neighborhood":"sample neighborhood","city":"São Paulo","state":"active","country":"BR"},"billing_address":{"zip":"sample zip","street":"sample street","number":"sample number","complement":"sample complement","neighborhood":"sample neighborhood","city":"São Paulo","state":"active","country":"BR"},"thumbnail":"sample thumbnail","custom_attributes":{},"last_activity_at":1,"created_at":1,"contact_inboxes":[{"source_id":"sample source id","inbox":{"id":1,"avatar_url":"https://example.com/resource","channel_id":1,"name":"Sample Name","channel_type":"Channel::Api","provider":"default"}}]}]}}}},"400":{"description":"Bad Request Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"post":{"tags":["Contacts"],"operationId":"contactCreate","description":"Create a new Contact","summary":"Create Contact","security":[{"userApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/account_id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contact_create_payload"},"example":{"inbox_id":1,"name":"Alice","email":"alice@acme.inc","blocked":false,"phone_number":"+123456789","avatar":"sample avatar","avatar_url":"https://example.com/avatar.png","identifier":"1234567890","additional_attributes":{"type":"customer","age":30},"custom_attributes":{},"referred_by_affiliate_id":42}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/extended_contact"},"example":{"payload":[{"additional_attributes":{},"availability_status":"online","email":"agent@example.com","id":1,"name":"Sample Name","phone_number":"+5511999998888","blocked":true,"contact_type":"visitor","identifier":"sample-identifier","referred_by_affiliate_id":1,"referred_by_affiliate_name":"sample referred by affiliate name","legal_type":"individual","tax_id":"sample tax id","tax_id_type":"br_cpf","country":"BR","address":{"zip":"sample zip","street":"sample street","number":"sample number","complement":"sample complement","neighborhood":"sample neighborhood","city":"São Paulo","state":"active","country":"BR"},"billing_address":{"zip":"sample zip","street":"sample street","number":"sample number","complement":"sample complement","neighborhood":"sample neighborhood","city":"São Paulo","state":"active","country":"BR"},"thumbnail":"sample thumbnail","custom_attributes":{"attribute_key":"attribute_value","signed_up_at":"dd/mm/yyyy"},"last_activity_at":1,"created_at":1,"contact_inboxes":[{"source_id":"sample source id","inbox":{"id":1,"avatar_url":"https://example.com/resource","channel_id":1,"name":"Sample Name","channel_type":"Channel::Api","provider":"default"}}]}],"id":1,"availability_status":"online"}}}},"400":{"description":"Bad Request Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/contacts/{id}":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"id","in":"path","required":true,"schema":{"type":"number"},"description":"ID of the contact"}],"get":{"tags":["Contacts"],"operationId":"contactDetails","summary":"Show Contact","security":[{"userApiKey":[]}],"description":"Get a contact belonging to the account using ID","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/contact_show_response"},"example":{"payload":{"additional_attributes":{"city":"São Paulo","country":"BR","country_code":"BR","created_at_ip":"sample created at ip"},"availability_status":"online","email":"agent@example.com","id":1,"name":"Sample Name","phone_number":"+5511999998888","blocked":true,"identifier":"sample-identifier","referred_by_affiliate_id":1,"referred_by_affiliate_name":"sample referred by affiliate name","legal_type":"individual","tax_id":"sample tax id","tax_id_type":"br_cpf","country":"BR","address":{"zip":"sample zip","street":"sample street","number":"sample number","complement":"sample complement","neighborhood":"sample neighborhood","city":"São Paulo","state":"active","country":"BR"},"billing_address":{"zip":"sample zip","street":"sample street","number":"sample number","complement":"sample complement","neighborhood":"sample neighborhood","city":"São Paulo","state":"active","country":"BR"},"thumbnail":"sample thumbnail","custom_attributes":{},"last_activity_at":1,"created_at":1,"contact_inboxes":[{"source_id":"sample source id","inbox":{"id":1,"avatar_url":"https://example.com/resource","channel_id":1,"name":"Sample Name","channel_type":"Channel::Api","provider":"default"}}]}}}}},"404":{"description":"Contact not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"403":{"description":"Access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"put":{"tags":["Contacts"],"operationId":"contactUpdate","summary":"Update Contact","security":[{"userApiKey":[]}],"description":"Update a contact belonging to the account using ID","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contact_update_payload"},"example":{"name":"Alice","email":"alice@acme.inc","blocked":false,"phone_number":"+123456789","avatar":"sample avatar","avatar_url":"https://example.com/avatar.png","identifier":"1234567890","additional_attributes":{"type":"customer","age":30},"custom_attributes":{},"referred_by_affiliate_id":42}}}},"responses":{"204":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/contact_base"},"example":{"id":1,"payload":[{"additional_attributes":{},"availability_status":"online","email":"agent@example.com","id":1,"name":"Sample Name","phone_number":"+5511999998888","blocked":true,"contact_type":"visitor","identifier":"sample-identifier","referred_by_affiliate_id":1,"referred_by_affiliate_name":"sample referred by affiliate name","legal_type":"individual","tax_id":"sample tax id","tax_id_type":"br_cpf","country":"BR","address":{"zip":"sample zip","street":"sample street","number":"sample number","complement":"sample complement","neighborhood":"sample neighborhood","city":"São Paulo","state":"active","country":"BR"},"billing_address":{"zip":"sample zip","street":"sample street","number":"sample number","complement":"sample complement","neighborhood":"sample neighborhood","city":"São Paulo","state":"active","country":"BR"},"thumbnail":"sample thumbnail","custom_attributes":{"attribute_key":"attribute_value","signed_up_at":"dd/mm/yyyy"},"last_activity_at":1,"created_at":1,"contact_inboxes":[{"source_id":"sample source id","inbox":{"id":1,"avatar_url":"https://example.com/resource","channel_id":1,"name":"Sample Name","channel_type":"Channel::Api","provider":"default"}}]}]}}}},"404":{"description":"Contact not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"403":{"description":"Access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"delete":{"tags":["Contacts"],"operationId":"contactDelete","summary":"Delete Contact","security":[{"userApiKey":[]}],"description":"Delete a contact belonging to the account using ID","responses":{"200":{"description":"Success"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"Contact not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"patch":{"tags":["Contacts"],"operationId":"auto_patch_api_v1_accounts_account_id_contacts_id","summary":"Update contacts","description":"Updates the contact identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}},"example":{"error":"sample error"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"identifier":{"type":"string"},"email":{"type":"string","format":"email"},"phone_number":{"type":"string"},"avatar":{"type":"string"},"blocked":{"type":"string"},"avatar_url":{"type":"string"},"legal_type":{"type":"string","enum":["individual","business"]},"tax_id":{"type":"string","description":"The fiscal identifier (CPF/CNPJ/EIN/VAT); validated and stored encrypted on write. Read payloads return the real value to an authenticated human agent, and a type-aware mask (e.g. \"***.***.***-09\") when a role field rule masks it or the caller is a bot; a hidden rule omits the key. Webhooks, exports and message variables always carry the masked form."},"tax_id_type":{"type":"string","enum":["br_cpf","br_cnpj","us_ein","eu_vat","uk_vat","generic"],"description":"The fiscal identifier scheme used to validate and mask the tax_id (CPF/CNPJ check digits, EIN, EU/UK VAT or a generic fallback)."},"country":{"type":"string"},"referred_by_affiliate_id":{"type":"integer"},"additional_attributes":{"type":"object","additionalProperties":true,"description":"Channel- and source-specific metadata for this record (e.g. browser info, referer, social profile identifiers). The key set depends on the originating channel."},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"address":{"type":"object","description":"Native postal address of the contact. Blank components are omitted.","properties":{"zip":{"type":"string","description":"Postal/ZIP code (CEP in Brazil)"},"street":{"type":"string","description":"Street name"},"number":{"type":"string","description":"Street number"},"complement":{"type":"string","description":"Address complement (apartment, suite, block)"},"neighborhood":{"type":"string","description":"Neighborhood/district"},"city":{"type":"string","description":"City name"},"state":{"type":"string","description":"State/province (UF in Brazil)"},"country":{"type":"string","description":"Country of the postal address"}}},"billing_address":{"type":"object","description":"Optional billing address override of the contact. An empty object means billing uses the principal address.","properties":{"zip":{"type":"string","description":"Postal/ZIP code (CEP in Brazil)"},"street":{"type":"string","description":"Street name"},"number":{"type":"string","description":"Street number"},"complement":{"type":"string","description":"Address complement (apartment, suite, block)"},"neighborhood":{"type":"string","description":"Neighborhood/district"},"city":{"type":"string","description":"City name"},"state":{"type":"string","description":"State/province (UF in Brazil)"},"country":{"type":"string","description":"Country of the postal address"}}}}},"example":{"name":"Sample Name","identifier":"sample-identifier","email":"agent@example.com","phone_number":"+5511999998888","avatar":"sample avatar","blocked":"sample blocked","avatar_url":"https://example.com/resource","legal_type":"individual","tax_id":"sample tax id","tax_id_type":"br_cpf","country":"BR","referred_by_affiliate_id":1,"additional_attributes":{},"custom_attributes":{},"address":{"zip":"sample zip","street":"sample street","number":"sample number","complement":"sample complement","neighborhood":"sample neighborhood","city":"São Paulo","state":"active","country":"BR"},"billing_address":{"zip":"sample zip","street":"sample street","number":"sample number","complement":"sample complement","neighborhood":"sample neighborhood","city":"São Paulo","state":"active","country":"BR"}}}}}}},"/api/v1/accounts/{account_id}/contacts/{id}/conversations":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"id","in":"path","required":true,"schema":{"type":"number"},"description":"ID of the contact"}],"get":{"tags":["Contacts"],"operationId":"contactConversations","summary":"Contact Conversations","description":"Get conversations associated with that contact","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/contact_conversations_response"},"example":{"payload":[{"id":1,"messages":[{"client_message_id":"sample client message id","client_message_actor":"User:7","outbound_dispatch":{"state":"queued","retryable":true},"id":1,"content":"Sample content text.","content_readiness":{"state":"waiting","quality":"pending","generation":1,"content_version":1},"account_id":1,"inbox_id":1,"logical_inbox_id":1,"echo_id":"sample echo id","conversation_id":1,"message_type":0,"created_at":1,"updated_at":1,"private":true,"status":"sent","source_id":"sample source id","content_type":"text","content_attributes":{"instagram_mention":{"media_id":"sample media id","comment_id":"sample comment id","mention_type":"comment","enrichment_status":"unresolved","replyable":true,"author_id":"sample author id","author_username":"sample author username","text":"sample text","media_type":"sample media type","media_product_type":"sample media product type","permalink":"https://example.com/resource","identity_scope":{"account_id":1,"inbox_id":1,"instagram_id":"sample instagram id"},"recovery":{"state":"scheduled","reason":"Sample reason.","attempts":1,"checked_at":"2026-01-15T10:30:00.000Z","next_retry_at":"2026-01-15T10:30:00.000Z","lease_until":"2026-01-15T10:30:00.000Z"}},"translations":{},"translation":{"original_content":"sample original content","original_html_content":"sample original html content","delivery":{"status":"translated","source_language":"pt","target_language":"en","provider":"google_translate","content_digest":"sample content digest","translated_at":"2026-01-15T10:30:00.000Z","error_code":"translation_failed","cause_code":"provider_not_configured","failed_at":"2026-01-15T10:30:00.000Z"},"views":{}},"external_error":"sample external error","contact_share":{"origin":"contact_request","transport":"cloud","status":"linked","reason":"identity_owned_by_another_contact","other_contact_ids":[1],"reconciliation_id":"sample reconciliation id"}},"sender_type":"Contact","sender_id":1,"external_source_ids":{},"additional_attributes":{},"processed_message_content":"sample processed message content","sentiment":{},"conversation":{},"attachment":{},"attachments":[{"id":1,"message_id":1,"file_type":"image","account_id":1,"extension":"sample extension","data_url":"https://example.com/resource","media_readiness_revision":"sample media readiness revision","playable_audio_url":"https://example.com/resource","playable_video_url":"https://example.com/resource","video_processing":true,"video_unavailable":true,"thumb_url":"https://example.com/resource","file_size":1,"width":1,"height":1,"coordinates_lat":12.5,"coordinates_long":12.5,"fallback_title":"sample fallback title","meta":{},"transcribed_text":"sample transcribed text","transcript_translations":{"pt-BR":"Você pode me ajudar?","es":"¿Puedes ayudarme?"},"transcript_translation_states":{}}],"sender":{}}],"account_id":1,"uuid":"sample uuid","additional_attributes":{},"agent_last_seen_at":12.5,"assignee_last_seen_at":12.5,"can_reply":true,"contact_last_seen_at":12.5,"custom_attributes":{},"inbox_id":1,"labels":["sample label"],"muted":true,"snoozed_until":12.5,"status":"open","created_at":12.5,"updated_at":12.5,"automation_control_event_cursor":1,"timestamp":12.5,"first_reply_created_at":12.5,"unread_count":5,"last_non_activity_message":{"client_message_id":"sample client message id","client_message_actor":"User:7","outbound_dispatch":{"state":"queued","retryable":true},"id":1,"content":"Sample content text.","content_readiness":{"state":"waiting","quality":"pending","generation":1,"content_version":1},"account_id":1,"inbox_id":1,"logical_inbox_id":1,"echo_id":"sample echo id","conversation_id":1,"message_type":0,"created_at":1,"updated_at":1,"private":true,"status":"sent","source_id":"sample source id","content_type":"text","content_attributes":{"instagram_mention":{"media_id":"sample media id","comment_id":"sample comment id","mention_type":"comment","enrichment_status":"unresolved","replyable":true,"author_id":"sample author id","author_username":"sample author username","text":"sample text","media_type":"sample media type","media_product_type":"sample media product type","permalink":"https://example.com/resource","identity_scope":{"account_id":1,"inbox_id":1,"instagram_id":"sample instagram id"},"recovery":{"state":"scheduled","reason":"Sample reason.","attempts":1,"checked_at":"2026-01-15T10:30:00.000Z","next_retry_at":"2026-01-15T10:30:00.000Z","lease_until":"2026-01-15T10:30:00.000Z"}},"translations":{},"translation":{"original_content":"sample original content","original_html_content":"sample original html content","delivery":{"status":"translated","source_language":"pt","target_language":"en","provider":"google_translate","content_digest":"sample content digest","translated_at":"2026-01-15T10:30:00.000Z","error_code":"translation_failed","cause_code":"provider_not_configured","failed_at":"2026-01-15T10:30:00.000Z"},"views":{}},"external_error":"sample external error","contact_share":{"origin":"contact_request","transport":"cloud","status":"linked","reason":"identity_owned_by_another_contact","other_contact_ids":[1],"reconciliation_id":"sample reconciliation id"}},"sender_type":"Contact","sender_id":1,"external_source_ids":{},"additional_attributes":{},"processed_message_content":"sample processed message content","sentiment":{},"conversation":{},"attachment":{},"attachments":[{"id":1,"message_id":1,"file_type":"image","account_id":1,"extension":"sample extension","data_url":"https://example.com/resource","media_readiness_revision":"sample media readiness revision","playable_audio_url":"https://example.com/resource","playable_video_url":"https://example.com/resource","video_processing":true,"video_unavailable":true,"thumb_url":"https://example.com/resource","file_size":1,"width":1,"height":1,"coordinates_lat":12.5,"coordinates_long":12.5,"fallback_title":"sample fallback title","meta":{},"transcribed_text":"sample transcribed text","transcript_translations":{"pt-BR":"Você pode me ajudar?","es":"¿Puedes ayudarme?"},"transcript_translation_states":{}}],"sender":{}},"last_activity_at":12.5,"priority":"low","waiting_since":12.5,"sla_policy_id":1,"applied_sla":{},"sla_events":[{}],"meta":{"sender":{"additional_attributes":{},"availability_status":"online","email":"agent@example.com","id":1,"name":"Sample Name","phone_number":"+5511999998888","blocked":true,"identifier":"sample-identifier","thumbnail":"sample thumbnail","custom_attributes":{},"last_activity_at":12.5,"created_at":12.5},"channel":"sample channel","assignee":{"id":1,"access_token":"sample-token","account_id":1,"available_name":"sample available name","avatar_url":"https://example.com/resource","confirmed":true,"display_name":"sample display name","message_signature":"sample message signature","email":"agent@example.com","hmac_identifier":"sample hmac identifier","inviter_id":1,"name":"Sample Name","provider":"email","pubsub_token":"sample-token","role":"agent","ui_settings":{"translation_language_by_account":{"1":"pt-BR"}},"uid":"sample uid","type":"sample type","custom_attributes":{},"accounts":[{"id":1,"name":"Sample Name","status":"active","active_at":"2026-01-15T10:30:00.000Z","role":"administrator","outbound_agent_name_header_policy":"inherit","permissions":["sample permission"],"availability":"online","availability_status":"online","auto_offline":true,"custom_role_id":1,"custom_role":{"id":1,"name":"Sample Name","description":"A short description.","permissions":["conversation_manage"]},"onboarding_step":"sample onboarding step","access_role_id":1,"access_role":{"id":1,"name":"Sample Name","field_permissions":{"contact":{},"organization":{}}},"api_and_webhooks":true}]},"hmac_verified":true}}]}}}},"404":{"description":"Contact not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"403":{"description":"Access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/contacts/{id}/labels":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"id","in":"path","required":true,"schema":{"type":"number"},"description":"ID of the contact"}],"get":{"tags":["Contact Labels"],"operationId":"list-all-labels-of-a-contact","summary":"List Labels","description":"Lists all the labels of a contact","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/contact_labels"},"example":{"payload":["sample payload"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"Contact not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"post":{"tags":["Contact Labels"],"operationId":"contact-add-labels","summary":"Add Labels","description":"Add labels to a contact. Note that this API would overwrite the existing list of labels associated to the conversation.","security":[{"userApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["labels"],"properties":{"labels":{"type":"array","description":"Array of labels (comma-separated strings)","items":{"type":"string"},"example":["support","billing"]}}},"example":{"labels":["support","billing"]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/contact_labels"},"example":{"payload":["sample payload"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"Contact not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/contacts/search":{"get":{"tags":["Contacts"],"operationId":"contactSearch","description":"Search the resolved contacts using a search key, currently supports email search (Page size = 15). Resolved contacts are the ones with a value for identifier, email or phone number","summary":"Search Contacts","security":[{"userApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"q","in":"query","schema":{"type":"string"},"description":"Search using contact `name`, `identifier`, `email` or `phone number`"},{"$ref":"#/components/parameters/contact_sort_param"},{"$ref":"#/components/parameters/page"},{"name":"directory","in":"query","schema":{"type":"string","enum":["whatsapp_contact"]},"description":"Optional WhatsApp contact-card projection that excludes technical chat identities and returns one canonical contact per normalized phone number."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/contacts_list_response"},"example":{"meta":{"count":5,"current_page":"sample current page"},"payload":[{"additional_attributes":{"city":"São Paulo","country":"BR","country_code":"BR","created_at_ip":"sample created at ip"},"availability_status":"online","email":"agent@example.com","id":1,"name":"Sample Name","phone_number":"+5511999998888","blocked":true,"identifier":"sample-identifier","referred_by_affiliate_id":1,"referred_by_affiliate_name":"sample referred by affiliate name","legal_type":"individual","tax_id":"sample tax id","tax_id_type":"br_cpf","country":"BR","address":{"zip":"sample zip","street":"sample street","number":"sample number","complement":"sample complement","neighborhood":"sample neighborhood","city":"São Paulo","state":"active","country":"BR"},"billing_address":{"zip":"sample zip","street":"sample street","number":"sample number","complement":"sample complement","neighborhood":"sample neighborhood","city":"São Paulo","state":"active","country":"BR"},"thumbnail":"sample thumbnail","custom_attributes":{},"last_activity_at":1,"created_at":1,"contact_inboxes":[{"source_id":"sample source id","inbox":{"id":1,"avatar_url":"https://example.com/resource","channel_id":1,"name":"Sample Name","channel_type":"Channel::Api","provider":"default"}}]}]}}}},"401":{"description":"Authentication error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/contacts/filter":{"post":{"tags":["Contacts"],"operationId":"contactFilter","description":"Filter contacts with custom filter options and pagination","summary":"Contact Filter","security":[{"userApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"page","in":"query","schema":{"type":"number"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","properties":{"attribute_key":{"type":"string","description":"filter attribute name"},"filter_operator":{"type":"string","description":"filter operator name","enum":["equal_to","not_equal_to","contains","does_not_contain"]},"values":{"type":"array","items":{"type":"string"},"description":"array of the attribute values to filter"},"query_operator":{"type":["string","null"],"description":"query operator name (null on the last condition)","enum":["AND","OR",null]}}},"example":[{"attribute_key":"name","filter_operator":"equal_to","values":["en"],"query_operator":"AND"},{"attribute_key":"country_code","filter_operator":"equal_to","values":["us"],"query_operator":null}]}}},"example":{"payload":[{"attribute_key":"name","filter_operator":"equal_to","values":["en"],"query_operator":"AND"},{"attribute_key":"country_code","filter_operator":"equal_to","values":["us"],"query_operator":null}]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/contacts_list_response"},"example":{"meta":{"count":5,"current_page":"sample current page"},"payload":[{"additional_attributes":{"city":"São Paulo","country":"BR","country_code":"BR","created_at_ip":"sample created at ip"},"availability_status":"online","email":"agent@example.com","id":1,"name":"Sample Name","phone_number":"+5511999998888","blocked":true,"identifier":"sample-identifier","referred_by_affiliate_id":1,"referred_by_affiliate_name":"sample referred by affiliate name","legal_type":"individual","tax_id":"sample tax id","tax_id_type":"br_cpf","country":"BR","address":{"zip":"sample zip","street":"sample street","number":"sample number","complement":"sample complement","neighborhood":"sample neighborhood","city":"São Paulo","state":"active","country":"BR"},"billing_address":{"zip":"sample zip","street":"sample street","number":"sample number","complement":"sample complement","neighborhood":"sample neighborhood","city":"São Paulo","state":"active","country":"BR"},"thumbnail":"sample thumbnail","custom_attributes":{},"last_activity_at":1,"created_at":1,"contact_inboxes":[{"source_id":"sample source id","inbox":{"id":1,"avatar_url":"https://example.com/resource","channel_id":1,"name":"Sample Name","channel_type":"Channel::Api","provider":"default"}}]}]}}}},"400":{"description":"Bad Request Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/contacts/{id}/contact_inboxes":{"post":{"tags":["Contacts"],"operationId":"contactInboxCreation","description":"Create a contact inbox record for an inbox","summary":"Create contact inbox","parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"id","in":"path","schema":{"type":"number"},"description":"ID of the contact","required":true}],"security":[{"userApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["inbox_id"],"properties":{"inbox_id":{"type":"number","description":"The ID of the inbox","example":1},"source_id":{"type":"string","description":"Contact Inbox Source Id"}}},"example":{"inbox_id":1,"source_id":"sample source id"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/contact_inboxes"},"example":{"source_id":"sample source id","inbox":{"id":1,"avatar_url":"https://example.com/resource","channel_id":1,"name":"Sample Name","channel_type":"Channel::Api","provider":"default"}}}}},"401":{"description":"Authentication error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"422":{"description":"Incorrect payload","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/contacts/{id}/contactable_inboxes":{"get":{"tags":["Contacts"],"operationId":"contactableInboxesGet","description":"Get List of contactable Inboxes","summary":"Get Contactable Inboxes","security":[{"userApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"id","in":"path","schema":{"type":"number"},"description":"ID of the contact","required":true}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/contactable_inboxes_response"},"example":{"payload":[{"source_id":"sample source id","inbox":{"id":1,"avatar_url":"https://example.com/resource","channel_id":1,"name":"Sample Name","channel_type":"Channel::Api","provider":"default"}}]}}}},"401":{"description":"Authentication error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"422":{"description":"Incorrect payload","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/actions/contact_merge":{"parameters":[{"$ref":"#/components/parameters/account_id"}],"post":{"tags":["Contacts"],"operationId":"contactMerge","summary":"Merge Contacts","security":[{"userApiKey":[]}],"description":"Merge two contacts into a single contact. The base contact remains and receives all\ndata from the mergee contact. After the merge, the mergee contact is permanently deleted.\n\nThis action is irreversible. All conversations, labels, and custom attributes from the\nmergee contact will be moved to the base contact.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["base_contact_id","mergee_contact_id"],"properties":{"base_contact_id":{"type":"integer","description":"ID of the contact that will remain after the merge and receive all data","example":1},"mergee_contact_id":{"type":"integer","description":"ID of the contact that will be merged into the base contact and deleted","example":2}}},"example":{"base_contact_id":1,"mergee_contact_id":2}}}},"responses":{"200":{"description":"Contacts merged successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/contact_base"},"example":{"id":1,"payload":[{"additional_attributes":{},"availability_status":"online","email":"agent@example.com","id":1,"name":"Sample Name","phone_number":"+5511999998888","blocked":true,"contact_type":"visitor","identifier":"sample-identifier","referred_by_affiliate_id":1,"referred_by_affiliate_name":"sample referred by affiliate name","legal_type":"individual","tax_id":"sample tax id","tax_id_type":"br_cpf","country":"BR","address":{"zip":"sample zip","street":"sample street","number":"sample number","complement":"sample complement","neighborhood":"sample neighborhood","city":"São Paulo","state":"active","country":"BR"},"billing_address":{"zip":"sample zip","street":"sample street","number":"sample number","complement":"sample complement","neighborhood":"sample neighborhood","city":"São Paulo","state":"active","country":"BR"},"thumbnail":"sample thumbnail","custom_attributes":{"attribute_key":"attribute_value","signed_up_at":"dd/mm/yyyy"},"last_activity_at":1,"created_at":1,"contact_inboxes":[{"source_id":"sample source id","inbox":{"id":1,"avatar_url":"https://example.com/resource","channel_id":1,"name":"Sample Name","channel_type":"Channel::Api","provider":"default"}}]}]}}}},"400":{"description":"Bad request - invalid contact IDs or contacts cannot be merged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"One or both contacts not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/automation_rules":{"parameters":[{"$ref":"#/components/parameters/account_id"}],"get":{"tags":["Automation Rule"],"operationId":"get-account-automation-rule","summary":"List all automation rules in an account","parameters":[{"$ref":"#/components/parameters/page"}],"description":"Get details of automation rules in an Account","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/automation_rule"},"example":{"payload":[{"id":1,"account_id":1,"name":"Add label on message create event","description":"Add label support and sales on message create event if incoming message content contains text help","event_name":"message_created","conditions":[{"attribute_key":"content","filter_operator":"contains","values":["help"],"query_operator":"and"}],"execution_delay":1,"actions":[{"action_name":"add_label","action_params":["support","sales"]}],"created_on":1,"active":true}]}}}},"403":{"description":"Access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"post":{"tags":["Automation Rule"],"operationId":"add-new-automation-rule-to-account","summary":"Add a new automation rule","description":"Save a native account automation rule. CRM triggers accept send_attachment and send_meta_conversion against the deal's linked conversation; missing links are recorded as skipped actions. send_webhook_event can execute without that link. crm_item_stage_changed supports execution_delay and durable per-action outcomes. An uncertain external outcome is recorded for reconciliation and is not retried blindly.","security":[{"userApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/automation_rule_create_update_payload"},"example":{"name":"Add label on message create event","description":"Add label support and sales on message create event if incoming message content contains text help","event_name":"message_created","active":true,"execution_delay":1,"actions":[{"action_name":"add_label","action_params":["support"]}],"conditions":[{"attribute_key":"content","filter_operator":"contains","query_operator":"OR","values":["help"]}]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/automation_rule"},"example":{"payload":[{"id":1,"account_id":1,"name":"Add label on message create event","description":"Add label support and sales on message create event if incoming message content contains text help","event_name":"message_created","conditions":[{"attribute_key":"content","filter_operator":"contains","values":["help"],"query_operator":"and"}],"execution_delay":1,"actions":[{"action_name":"add_label","action_params":["support","sales"]}],"created_on":1,"active":true}]}}}},"403":{"description":"Access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"422":{"description":"Invalid rule or an action that is incompatible with the selected trigger","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["actions"],"properties":{"actions":{"type":"array","items":{"type":"string"}}}}}},"example":{"error":{"actions":["Actions send_message are not compatible with trigger crm_item_created. Choose an action for the trigger subject."]}}}}}}}},"/api/v1/accounts/{account_id}/automation_rules/{id}":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"id","in":"path","schema":{"type":"number"},"description":"ID of the Automation Rule","required":true}],"get":{"tags":["Automation Rule"],"operationId":"get-details-of-a-single-automation-rule","summary":"Get a automation rule details","description":"Get the details of a automation rule in the account","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/automation_rule"},"example":{"payload":{"id":90,"account_id":1,"name":"add-label-bug-if-message-contains-bug","description":"add-label-bug-if-message-contains-bug","event_name":"message_created","execution_delay":null,"conditions":[{"values":["incoming"],"attribute_key":"message_type","query_operator":"and","filter_operator":"equal_to"},{"values":["bug"],"attribute_key":"content","filter_operator":"contains"}],"actions":[{"action_name":"add_label","action_params":["bugs","support-query"]}],"created_on":1650555440,"active":true}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"The given rule ID does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"patch":{"tags":["Automation Rule"],"operationId":"update-automation-rule-in-account","summary":"Update automation rule in Account","description":"Save a native account automation rule. CRM triggers accept send_attachment and send_meta_conversion against the deal's linked conversation; missing links are recorded as skipped actions. send_webhook_event can execute without that link. crm_item_stage_changed supports execution_delay and durable per-action outcomes. An uncertain external outcome is recorded for reconciliation and is not retried blindly.","security":[{"userApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/automation_rule_create_update_payload"},"example":{"name":"Add label on message create event","description":"Add label support and sales on message create event if incoming message content contains text help","event_name":"message_created","active":true,"execution_delay":1,"actions":[{"action_name":"add_label","action_params":["support"]}],"conditions":[{"attribute_key":"content","filter_operator":"contains","query_operator":"OR","values":["help"]}]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/automation_rule"},"example":{"payload":[{"id":1,"account_id":1,"name":"Add label on message create event","description":"Add label support and sales on message create event if incoming message content contains text help","event_name":"message_created","conditions":[{"attribute_key":"content","filter_operator":"contains","values":["help"],"query_operator":"and"}],"execution_delay":1,"actions":[{"action_name":"add_label","action_params":["support","sales"]}],"created_on":1,"active":true}]}}}},"403":{"description":"Access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"Rule not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"422":{"description":"Invalid rule or an action that is incompatible with the selected trigger","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["actions"],"properties":{"actions":{"type":"array","items":{"type":"string"}}}}}},"example":{"error":{"actions":["Actions send_message are not compatible with trigger crm_item_created. Choose an action for the trigger subject."]}}}}}}},"delete":{"tags":["Automation Rule"],"operationId":"delete-automation-rule-from-account","summary":"Remove a automation rule from account","description":"Remove a automation rule from account","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Success"},"403":{"description":"Access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"automation rule not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"put":{"tags":["Automation Rule"],"operationId":"auto_put_api_v1_accounts_account_id_automation_rules_id","summary":"Update automation rules","description":"Updates the automation rule identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"event_name":{"type":"string"},"conditions":{"type":"string"},"actions":{"type":"string"},"created_on":{"type":"integer"},"active":{"type":"boolean"},"execution_delay":{"type":"string"},"files":{"type":"string"}}}}},"example":{"payload":{"id":1,"account_id":1,"name":"Sample Name","description":"A short description.","event_name":"sample event name","conditions":"sample conditions","actions":"sample actions","created_on":1,"active":true,"execution_delay":"sample execution delay","files":"sample files"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"conditions":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Free-form object."}},"actions":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Free-form object."}}}},"example":{"conditions":[{}],"actions":[{}]}}}}}},"/api/v1/accounts/{account_id}/portals":{"parameters":[{"$ref":"#/components/parameters/account_id"}],"post":{"tags":["Help Center"],"operationId":"add-new-portal-to-account","summary":"Add a new portal","description":"Add a new portal to account","security":[{"userApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/portal_create_update_payload"},"example":{"portal":{"name":"Handbook","slug":"handbook","config":{"allowed_locales":["en","es"],"default_locale":"en","layout":"classic","draft_locales":["es"],"social_profiles":{"instagram":"https://www.instagram.com/exampleco","facebook":"https://example.com/resource","x":"https://example.com/resource","linkedin":"https://example.com/resource","youtube":"https://example.com/resource","tiktok":"https://example.com/resource","github":"https://example.com/resource","whatsapp":"sample whatsapp"},"locale_translations":{"es":{"name":"Centro de ayuda","page_title":"Centro de ayuda","header_text":"¿Cómo podemos ayudar?"}}},"id":123,"color":"#FFFFFF","custom_domain":"help.example.com","header_text":"Handbook","homepage_link":"https://www.example.com/","page_title":"Handbook","archived":false},"inbox_id":15,"blob_id":"sample blob id"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/portal"},"example":{"payload":[{"id":1,"archived":true,"color":"#1F93FF","config":{"allowed_locales":[{"code":"sample code","articles_count":5,"categories_count":5}]},"custom_domain":"sample custom domain","header_text":"sample header text","homepage_link":"https://example.com/resource","name":"Sample Name","slug":"sample-slug","page_title":"sample page title","account_id":1,"inbox":{"navigation_only":true,"id":1,"name":"Sample Name","website_url":"https://example.com/resource","channel_type":"Channel::Api","avatar_url":"https://example.com/resource","widget_color":"#1F93FF","website_token":"sample-token","enable_auto_assignment":true,"web_widget_script":"sample web widget script","welcome_title":"sample welcome title","welcome_tagline":"sample welcome tagline","greeting_enabled":true,"greeting_message":"sample greeting message","channel_id":1,"working_hours_enabled":true,"enable_email_collect":true,"csat_survey_enabled":true,"auto_assignment_config":{},"out_of_office_message":"sample out of office message","working_hours":[{"day_of_week":12.5,"closed_all_day":true,"open_hour":12.5,"open_minutes":12.5,"close_hour":12.5,"close_minutes":12.5,"open_all_day":true}],"timezone":"America/Sao_Paulo","callback_webhook_url":"https://example.com/resource","allow_messages_after_resolved":true,"lock_to_single_conversation":true,"sender_name_type":"friendly","auto_resolve_config":{"mode":"custom","after":30,"message":"We are closing this conversation due to inactivity.","label":"auto-resolved","allow_waiting":false},"outbound_agent_name_header_policy":"inherit","business_name":"sample business name","branded_email_layout":"agent@example.com","responder_policy":{"mode":"agent_bot","conflict":true},"hmac_mandatory":true,"selected_feature_flags":["sample selected feature flag"],"reply_time":"2026-01-15T10:30:00.000Z","messaging_service_sid":"sample messaging service sid","phone_number":"+5511999998888","bandwidth_callback_state":"active","bandwidth_api_migration_state":"oauth2_configured","medium":"sample medium","provider":"default","whatsapp_web_session_state":{"state":"connected","fresh":true,"observed_at":"2026-01-15T10:30:00.000Z","disconnected_since":null},"hybrid_pair":{"paired":true,"id":4,"role":"cloud","sibling_inbox_id":18,"canonical_phone":"+5521900000000","primary":"cloud","inbound_authority":"cloud","unified_inbox":true,"unified_state":{"state":"complete","scanned":42,"frozen":40,"reconciled_count":2,"completed_at":"2026-10-03T12:00:00.000Z","blocked_conversations":[]},"routing":{"outbound_default":"cloud","out_of_window":"web","fallback":true,"manual_override":true,"weighted":{"mode":"weighted","web_percent":30,"version":2}},"web_channel_id":12,"web_inbox_id":18,"calling_provider":"whatsapp_web","web_voice_enabled":true,"web_inbound_calls_enabled":true,"web_call_config_sync":{"state":"pending","checked_at":"2026-10-03T12:00:00.000Z"},"web_video_calls_enabled":false,"web_group_calls_enabled":false,"web_reauthorization_required":false,"web_session_state":{"state":"connected","fresh":true,"observed_at":"2026-10-03T12:00:00.000Z","disconnected_since":null},"web_allow_message_deletion":true}},"logo":{"id":1,"portal_id":1,"file_type":"image","account_id":1,"file_url":"https://example.com/resource","blob_id":"sample blob id","filename":"sample filename"},"meta":{"all_articles_count":5,"archived_articles_count":5,"published_count":5,"draft_articles_count":5,"categories_count":5,"default_locale":"sample default locale"}}]}}}},"403":{"description":"Access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"422":{"description":"The logo blob is invalid or is not owned by this account","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","enum":["invalid_logo_blob"]}}},"example":{"error":"invalid_logo_blob"}}}}}},"get":{"tags":["Help Center"],"operationId":"get-portal","summary":"List all portals in an account","description":"Get details of portals in an Account","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/portal"},"example":{"payload":[{"id":4,"color":"#1F93FF","custom_domain":"help.example.com","header_text":"Handbook","homepage_link":"https://www.example.com","name":"Handbook","page_title":"Handbook","slug":"handbook","archived":false,"account_id":1,"config":{"allowed_locales":[{"code":"en","articles_count":32,"categories_count":9}]},"inbox":{"id":37,"avatar_url":"https://example.com/avatar.png","channel_id":1,"name":"Acme","channel_type":"Channel::WebWidget","greeting_enabled":true,"widget_color":"#1F93FF","website_url":"example.com","navigation_only":true,"website_token":"sample-token","enable_auto_assignment":true,"web_widget_script":"sample web widget script","welcome_title":"sample welcome title","welcome_tagline":"sample welcome tagline","greeting_message":"sample greeting message","working_hours_enabled":true,"enable_email_collect":true,"csat_survey_enabled":true,"auto_assignment_config":{},"out_of_office_message":"sample out of office message","working_hours":[{"day_of_week":12.5,"closed_all_day":true,"open_hour":12.5,"open_minutes":12.5,"close_hour":12.5,"close_minutes":12.5,"open_all_day":true}],"timezone":"America/Sao_Paulo","callback_webhook_url":"https://example.com/resource","allow_messages_after_resolved":true,"lock_to_single_conversation":true,"sender_name_type":"friendly","auto_resolve_config":{"mode":"custom","after":30,"message":"We are closing this conversation due to inactivity.","label":"auto-resolved","allow_waiting":false},"outbound_agent_name_header_policy":"inherit","business_name":"sample business name","branded_email_layout":"agent@example.com","responder_policy":{"mode":"agent_bot","conflict":true},"hmac_mandatory":true,"selected_feature_flags":["sample selected feature flag"],"reply_time":"2026-01-15T10:30:00.000Z","messaging_service_sid":"sample messaging service sid","phone_number":"+5511999998888","bandwidth_callback_state":"active","bandwidth_api_migration_state":"oauth2_configured","medium":"sample medium","provider":"default","whatsapp_web_session_state":{"state":"connected","fresh":true,"observed_at":"2026-01-15T10:30:00.000Z","disconnected_since":null},"hybrid_pair":{"paired":true,"id":4,"role":"cloud","sibling_inbox_id":18,"canonical_phone":"+5521900000000","primary":"cloud","inbound_authority":"cloud","unified_inbox":true,"unified_state":{"state":"complete","scanned":42,"frozen":40,"reconciled_count":2,"completed_at":"2026-10-03T12:00:00.000Z","blocked_conversations":[]},"routing":{"outbound_default":"cloud","out_of_window":"web","fallback":true,"manual_override":true,"weighted":{"mode":"weighted","web_percent":30,"version":2}},"web_channel_id":12,"web_inbox_id":18,"calling_provider":"whatsapp_web","web_voice_enabled":true,"web_inbound_calls_enabled":true,"web_call_config_sync":{"state":"pending","checked_at":"2026-10-03T12:00:00.000Z"},"web_video_calls_enabled":false,"web_group_calls_enabled":false,"web_reauthorization_required":false,"web_session_state":{"state":"connected","fresh":true,"observed_at":"2026-10-03T12:00:00.000Z","disconnected_since":null},"web_allow_message_deletion":true}},"logo":{"id":19399916,"portal_id":4,"file_type":"image/png","account_id":1,"file_url":"https://example.com/logo.png","blob_id":"eyJfcmFpbHMiOnsiZGF0YSI6MTIzLCJwdXIiOiJibG9iX2lkIn19--signed","filename":"square.png"},"meta":{"all_articles_count":0,"categories_count":9,"default_locale":"en","archived_articles_count":5,"published_count":5,"draft_articles_count":5}}]}}}},"403":{"description":"Access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/portals/{id}":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"$ref":"#/components/parameters/portal_id"}],"patch":{"tags":["Help Center"],"operationId":"update-portal-to-account","summary":"Update a portal","description":"Update a portal to account","security":[{"userApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/portal_update_payload"},"example":{"blob_id":"eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBBQT09In19--signed"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/portal_single"},"example":{"payload":{"id":123,"archived":false,"color":"#1F93FF","config":{"allowed_locales":[{"code":"en","articles_count":32,"categories_count":9}]},"custom_domain":"help.example.com","header_text":"Handbook","homepage_link":"https://www.example.com","name":"Handbook","slug":"handbook","page_title":"Handbook","account_id":123,"inbox":{"id":123,"name":"Acme","website_url":"example.com","channel_type":"Channel::WebWidget","avatar_url":"https://example.com/avatar.png","widget_color":"#1F93FF","website_token":"4cWzuf9i9jxN9tbnv8K9STKU","enable_auto_assignment":true,"web_widget_script":"\u003cscript\u003e...\u003c/script\u003e","welcome_title":"Hi there ! 🙌🏼","welcome_tagline":"We make it simple to connect with us.","greeting_enabled":true,"greeting_message":"Hey there 👋, Thank you for reaching out to us.","channel_id":123,"working_hours_enabled":true,"enable_email_collect":true,"csat_survey_enabled":true,"timezone":"America/Los_Angeles","business_name":"Acme","hmac_mandatory":true,"navigation_only":true,"auto_assignment_config":{},"out_of_office_message":"sample out of office message","working_hours":[{"day_of_week":12.5,"closed_all_day":true,"open_hour":12.5,"open_minutes":12.5,"close_hour":12.5,"close_minutes":12.5,"open_all_day":true}],"callback_webhook_url":"https://example.com/resource","allow_messages_after_resolved":true,"lock_to_single_conversation":true,"sender_name_type":"friendly","auto_resolve_config":{"mode":"custom","after":30,"message":"We are closing this conversation due to inactivity.","label":"auto-resolved","allow_waiting":false},"outbound_agent_name_header_policy":"inherit","branded_email_layout":"agent@example.com","responder_policy":{"mode":"agent_bot","conflict":true},"selected_feature_flags":["sample selected feature flag"],"reply_time":"2026-01-15T10:30:00.000Z","messaging_service_sid":"sample messaging service sid","phone_number":"+5511999998888","bandwidth_callback_state":"active","bandwidth_api_migration_state":"oauth2_configured","medium":"sample medium","provider":"default","whatsapp_web_session_state":{"state":"connected","fresh":true,"observed_at":"2026-01-15T10:30:00.000Z","disconnected_since":null},"hybrid_pair":{"paired":true,"id":4,"role":"cloud","sibling_inbox_id":18,"canonical_phone":"+5521900000000","primary":"cloud","inbound_authority":"cloud","unified_inbox":true,"unified_state":{"state":"complete","scanned":42,"frozen":40,"reconciled_count":2,"completed_at":"2026-10-03T12:00:00.000Z","blocked_conversations":[]},"routing":{"outbound_default":"cloud","out_of_window":"web","fallback":true,"manual_override":true,"weighted":{"mode":"weighted","web_percent":30,"version":2}},"web_channel_id":12,"web_inbox_id":18,"calling_provider":"whatsapp_web","web_voice_enabled":true,"web_inbound_calls_enabled":true,"web_call_config_sync":{"state":"pending","checked_at":"2026-10-03T12:00:00.000Z"},"web_video_calls_enabled":false,"web_group_calls_enabled":false,"web_reauthorization_required":false,"web_session_state":{"state":"connected","fresh":true,"observed_at":"2026-10-03T12:00:00.000Z","disconnected_since":null},"web_allow_message_deletion":true}},"logo":{"id":123,"portal_id":123,"file_type":"image/png","account_id":123,"file_url":"https://example.com/logo.png","blob_id":"eyJfcmFpbHMiOnsiZGF0YSI6MTIzLCJwdXIiOiJibG9iX2lkIn19--signed","filename":"square.png"},"meta":{"all_articles_count":32,"categories_count":9,"default_locale":"en","archived_articles_count":5,"published_count":5,"draft_articles_count":5}}}}}},"403":{"description":"Access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"Portal not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"422":{"description":"The logo blob is invalid or is not owned by this account","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","enum":["invalid_logo_blob"]}}},"example":{"error":"invalid_logo_blob"}}}}}},"get":{"tags":["Help Center"],"operationId":"auto_get_api_v1_accounts_account_id_portals_id","summary":"Get portals","description":"Returns the portal identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"color":{"type":"string"},"custom_domain":{"type":"string"},"header_text":{"type":"string"},"homepage_link":{"type":"string"},"name":{"type":"string"},"page_title":{"type":"string"},"slug":{"type":"string"},"archived":{"type":"boolean"},"account_id":{"type":"integer"},"config":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"articles_count":{"type":"integer"},"categories_count":{"type":"integer"},"draft":{"type":"boolean"}}}},"inbox":{"type":"object","properties":{"id":{"type":"integer"},"avatar_url":{"type":"string"},"channel_id":{"type":"integer"},"name":{"type":"string"},"channel_type":{"type":"string","enum":["Channel::Api","Channel::Email","Channel::FacebookPage","Channel::Instagram","Channel::Line","Channel::Sms","Channel::Telegram","Channel::Tiktok","Channel::TwilioSms","Channel::TwitterProfile","Channel::WebWidget","Channel::Whatsapp"],"description":"The inbox channel class — identifies which messaging channel backs the inbox."},"greeting_enabled":{"type":"boolean"},"greeting_message":{"type":"string"},"working_hours_enabled":{"type":"boolean"},"enable_email_collect":{"type":"string"},"csat_survey_enabled":{"type":"boolean"},"csat_config":{"type":"string"},"enable_auto_assignment":{"type":"string"},"auto_assignment_config":{"type":"string"},"out_of_office_message":{"type":"string"},"working_hours":{"type":"string"},"timezone":{"type":"string","description":"IANA timezone identifier (e.g. \"America/Sao_Paulo\", \"UTC\"). Rails timezone names are also accepted on input; an unrecognized value is ignored in favor of the next fallback.","example":"America/Sao_Paulo"},"callback_webhook_url":{"type":"string"},"allow_messages_after_resolved":{"type":"string"},"lock_to_single_conversation":{"type":"string"},"audio_transcription_enabled":{"type":"boolean"},"preserve_deleted_messages":{"type":"string"},"allow_message_deletion":{"type":"string"},"capture_view_once":{"type":"string"},"sender_name_type":{"type":"string","enum":["friendly","professional"]},"auto_resolve_config":{"type":"object","additionalProperties":true,"oneOf":[{"type":"object","maxProperties":0,"additionalProperties":true,"description":"Empty means inherit the account rule."},{"type":"object","additionalProperties":false,"required":["mode"],"properties":{"mode":{"type":"string","enum":["disabled"],"description":"Disable automatic resolution for this inbox."}},"description":"The disabled rule contains only its mode."},{"type":"object","additionalProperties":false,"required":["mode","after","message","label","allow_waiting"],"properties":{"mode":{"type":"string","enum":["custom"],"description":"Use this complete inbox rule."},"after":{"type":"integer","minimum":10,"maximum":1439856,"description":"Inactivity in minutes; required for custom mode."},"message":{"type":["string","null"],"maxLength":10000,"description":"Optional message; blank normalizes to null."},"label":{"type":["string","null"],"description":"An existing account label title, or null."},"allow_waiting":{"type":"boolean","description":"Whether waiting conversations are included."}},"description":"Complete normalized custom rule."}],"description":"Normalized JSON rule from valid model writes: empty, disabled, or complete custom configuration.","example":{"mode":"custom","after":60,"message":null,"label":null,"allow_waiting":false}},"outbound_agent_name_header_policy":{"type":"string"},"agent_bot_working_hours_mode":{"type":"string","enum":["always","inside_business_hours","outside_business_hours"]},"business_name":{"type":"string"},"responder_policy":{"type":"string"},"help_center":{"type":"object","properties":{"name":{"type":"string"},"slug":{"type":"string"}}},"tweets_enabled":{"type":"boolean"},"allowed_domains":{"type":"string"},"widget_color":{"type":"string"},"website_url":{"type":"string"},"hmac_mandatory":{"type":"string"},"welcome_title":{"type":"string"},"welcome_tagline":{"type":"string"},"web_widget_script":{"type":"string"},"website_token":{"type":"string"},"selected_feature_flags":{"type":"string"},"reply_time":{"type":"string","format":"date-time"},"hmac_token":{"type":"string"},"pre_chat_form_enabled":{"type":"boolean"},"pre_chat_form_options":{"type":"string"},"continuity_via_email":{"type":"string","format":"email"},"page_id":{"type":"integer"},"reauthorization_required":{"type":"string"},"instagram_id":{"type":"integer"},"messaging_service_sid":{"type":"string"},"phone_number":{"type":"string"},"medium":{"type":"string"},"bandwidth_callback_state":{"type":"string","enum":["active","reconnect_required","reconciling","reconciliation_required","encryption_required"]},"bandwidth_api_migration_state":{"type":"string","enum":["oauth2_configured","oauth2_required","configuration_required"]},"bandwidth_legacy_basic_deprecated":{"type":"boolean"},"content_templates":{"type":"string"},"auth_token":{"type":"string"},"account_sid":{"type":"string"},"api_key_sid":{"type":"string"},"twilio_credential_state":{"type":"string","enum":["ready","pending","failed","dead_letter","account_auth_token_required","reconciliation_required"],"description":"Durable Twilio credential lifecycle derived from Channel::TwilioSms. A reconciliation-required state is fail-closed until the provider outcome has been verified."},"api_key_configured":{"type":"boolean"},"email":{"type":"string","format":"email"},"auth_method":{"type":"string"},"forwarding_enabled":{"type":"boolean"},"forward_to_email":{"type":"string","format":"email"},"branded_email_layout":{"type":"string"},"imap_login":{"type":"string"},"imap_password":{"type":"string"},"imap_address":{"type":"string"},"imap_port":{"type":"string"},"imap_enabled":{"type":"boolean"},"imap_enable_ssl":{"type":"string"},"imap_authentication":{"type":"string"},"smtp_login":{"type":"string"},"smtp_password":{"type":"string"},"smtp_address":{"type":"string"},"smtp_port":{"type":"string"},"smtp_enabled":{"type":"boolean"},"smtp_domain":{"type":"string"},"smtp_enable_ssl_tls":{"type":"string"},"smtp_enable_starttls_auto":{"type":"string"},"smtp_openssl_verify_mode":{"type":"string","enum":["none","peer","client_once","fail_if_no_peer_cert"],"description":"OpenSSL peer-certificate verification mode for the email channel's SMTP connection."},"smtp_authentication":{"type":"string"},"secret":{"type":"string"},"webhook_url":{"type":"string"},"inbox_identifier":{"type":"string"},"additional_attributes":{"type":"object","additionalProperties":true,"description":"Channel- and source-specific metadata for this record (e.g. browser info, referer, social profile identifiers). The key set depends on the originating channel."},"provider":{"type":"string","enum":["default","whatsapp_cloud","whatsapp_web","google","microsoft"],"description":"Messaging provider backing the inbox channel (whatsapp_web is the WazMeow gateway; email uses google/microsoft; default otherwise)."},"bot_name":{"type":"string"},"message_templates":{"type":"boolean"},"provider_config":{"type":"string"},"business_management_token_configured":{"type":"boolean"},"hybrid_pair":{"$ref":"#/components/schemas/inbox/properties/hybrid_pair"},"whatsapp_web_session_state":{"$ref":"#/components/schemas/inbox/properties/whatsapp_web_session_state"},"hybrid_hidden":{"type":"string"},"logical_inbox_id":{"type":"integer"},"whatsapp_pending_phone":{"type":"object","nullable":true,"description":"Spec 052 — set only when a WhatsApp phone-number rewrite was REFUSED because a non-sibling channel already holds the number, leaving the inbox on its `pending:` placeholder and inert. `null` in every normal case (including a routine, not-yet-scanned pairing).","additionalProperties":false,"properties":{"awaiting_pair":{"type":"boolean","description":"True while the inbox is still on its `pending:\u003cuuid\u003e` placeholder number."},"phone":{"type":"string","description":"The E.164 number the rewrite tried to claim."},"reason":{"type":"string","enum":["same_account_same_provider","other_account"],"description":"Why the rewrite was refused. `other_account` never carries any identifying detail about the other account."},"sibling_inbox_id":{"type":"integer","nullable":true,"description":"Colliding inbox in the SAME account; absent when the collision is cross-account."},"source":{"type":"string","enum":["pair_success","qr_pump"],"description":"Which path attempted the rewrite."},"at":{"type":"string","format":"date-time","description":"When the refusal was recorded."}}},"whatsapp_sibling_notice":{"type":"string"},"whatsapp_web_contact_request":{"type":"string","enum":["supported","unsupported","unknown"],"description":"WhatsApp Web inboxes only — whether this inbox's WazMeow gateway serves the request that asks a customer to share their phone number. `supported` and `unsupported` come from a no-effect probe of the gateway route, refreshed at most hourly and immediately when a real send finds the route missing; `unknown` means not probed yet or the gateway could not be reached. Only `supported` turns the feature on; with `unknown` the request is refused before any gateway call while the probe runs."},"voice_enabled":{"type":"boolean"},"inbound_calls_enabled":{"type":"boolean"},"voice_configured":{"type":"boolean"},"voice_call_webhook_url":{"type":"string"},"voice_status_webhook_url":{"type":"string"}}},"logo":{"type":"string"},"meta":{"type":"object","properties":{"all_articles_count":{"type":"integer"},"archived_articles_count":{"type":"integer"},"published_count":{"type":"integer"},"draft_articles_count":{"type":"integer"},"mine_articles_count":{"type":"integer"},"categories_count":{"type":"integer"},"default_locale":{"type":"string"}}},"ssl_settings":{"type":"object","properties":{"status":{"type":"string"},"verification_errors":{"type":"string"}}}}},"example":{"id":1,"color":"#1F93FF","custom_domain":"sample custom domain","header_text":"sample header text","homepage_link":"https://example.com/resource","name":"Sample Name","page_title":"sample page title","slug":"sample-slug","archived":true,"account_id":1,"config":[{"code":"sample code","articles_count":5,"categories_count":5,"draft":true}],"inbox":{"id":1,"avatar_url":"https://example.com/resource","channel_id":1,"name":"Sample Name","channel_type":"Channel::Api","greeting_enabled":true,"greeting_message":"sample greeting message","working_hours_enabled":true,"enable_email_collect":"agent@example.com","csat_survey_enabled":true,"csat_config":"sample csat config","enable_auto_assignment":"sample enable auto assignment","auto_assignment_config":"sample auto assignment config","out_of_office_message":"sample out of office message","working_hours":"sample working hours","timezone":"America/Sao_Paulo","callback_webhook_url":"https://example.com/resource","allow_messages_after_resolved":"sample allow messages after resolved","lock_to_single_conversation":"sample lock to single conversation","audio_transcription_enabled":true,"preserve_deleted_messages":"sample preserve deleted messages","allow_message_deletion":"sample allow message deletion","capture_view_once":"sample capture view once","sender_name_type":"friendly","auto_resolve_config":{"mode":"custom","after":60,"message":null,"label":null,"allow_waiting":false},"outbound_agent_name_header_policy":"sample outbound agent name header policy","agent_bot_working_hours_mode":"always","business_name":"sample business name","responder_policy":"sample responder policy","help_center":{"name":"Sample Name","slug":"sample-slug"},"tweets_enabled":true,"allowed_domains":"sample allowed domains","widget_color":"#1F93FF","website_url":"https://example.com/resource","hmac_mandatory":"sample hmac mandatory","welcome_title":"sample welcome title","welcome_tagline":"sample welcome tagline","web_widget_script":"sample web widget script","website_token":"sample-token","selected_feature_flags":"sample selected feature flags","reply_time":"2026-01-15T10:30:00.000Z","hmac_token":"sample-token","pre_chat_form_enabled":true,"pre_chat_form_options":"sample pre chat form options","continuity_via_email":"agent@example.com","page_id":1,"reauthorization_required":"sample reauthorization required","instagram_id":1,"messaging_service_sid":"sample messaging service sid","phone_number":"+5511999998888","medium":"sample medium","bandwidth_callback_state":"active","bandwidth_api_migration_state":"oauth2_configured","bandwidth_legacy_basic_deprecated":true,"content_templates":"sample content templates","auth_token":"sample-token","account_sid":"sample account sid","api_key_sid":"sample api key sid","twilio_credential_state":"ready","api_key_configured":true,"email":"agent@example.com","auth_method":"sample auth method","forwarding_enabled":true,"forward_to_email":"agent@example.com","branded_email_layout":"agent@example.com","imap_login":"sample imap login","imap_password":"sample imap password","imap_address":"sample imap address","imap_port":"sample imap port","imap_enabled":true,"imap_enable_ssl":"sample imap enable ssl","imap_authentication":"sample imap authentication","smtp_login":"sample smtp login","smtp_password":"sample smtp password","smtp_address":"sample smtp address","smtp_port":"sample smtp port","smtp_enabled":true,"smtp_domain":"sample smtp domain","smtp_enable_ssl_tls":"sample smtp enable ssl tls","smtp_enable_starttls_auto":"sample smtp enable starttls auto","smtp_openssl_verify_mode":"none","smtp_authentication":"sample smtp authentication","secret":"sample-token","webhook_url":"https://example.com/resource","inbox_identifier":"sample inbox identifier","additional_attributes":{},"provider":"default","bot_name":"sample bot name","message_templates":true,"provider_config":"sample provider config","business_management_token_configured":true,"hybrid_pair":{"paired":true,"id":4,"role":"cloud","sibling_inbox_id":18,"canonical_phone":"+5521900000000","primary":"cloud","inbound_authority":"cloud","unified_inbox":true,"unified_state":{"state":"complete","scanned":42,"frozen":40,"reconciled_count":2,"completed_at":"2026-10-03T12:00:00.000Z","blocked_conversations":[]},"routing":{"outbound_default":"cloud","out_of_window":"web","fallback":true,"manual_override":true,"weighted":{"mode":"weighted","web_percent":30,"version":2}},"web_channel_id":12,"web_inbox_id":18,"calling_provider":"whatsapp_web","web_voice_enabled":true,"web_inbound_calls_enabled":true,"web_call_config_sync":{"state":"pending","checked_at":"2026-10-03T12:00:00.000Z"},"web_video_calls_enabled":false,"web_group_calls_enabled":false,"web_reauthorization_required":false,"web_session_state":{"state":"connected","fresh":true,"observed_at":"2026-10-03T12:00:00.000Z","disconnected_since":null},"web_allow_message_deletion":true},"whatsapp_web_session_state":{"state":"connected","fresh":true,"observed_at":"2026-01-15T10:30:00.000Z","disconnected_since":null},"hybrid_hidden":"sample hybrid hidden","logical_inbox_id":1,"whatsapp_pending_phone":{"awaiting_pair":true,"phone":"+5511999998888","reason":"same_account_same_provider","sibling_inbox_id":1,"source":"pair_success","at":"2026-01-15T10:30:00.000Z"},"whatsapp_sibling_notice":"sample whatsapp sibling notice","whatsapp_web_contact_request":"supported","voice_enabled":true,"inbound_calls_enabled":true,"voice_configured":true,"voice_call_webhook_url":"https://example.com/resource","voice_status_webhook_url":"https://example.com/resource"},"logo":"sample logo","meta":{"all_articles_count":5,"archived_articles_count":5,"published_count":5,"draft_articles_count":5,"mine_articles_count":5,"categories_count":5,"default_locale":"sample default locale"},"ssl_settings":{"status":"active","verification_errors":"sample verification errors"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"locale","in":"query","required":false,"description":"Restrict the returned articles to one locale.","schema":{"type":"string"},"example":"pt_BR"}]},"put":{"tags":["Help Center"],"operationId":"auto_put_api_v1_accounts_account_id_portals_id","summary":"Update portals","description":"Updates the portal identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Portal updated, including its resolved inbox and logo projection.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/portal_single"},"example":{"payload":{"id":1,"archived":true,"color":"#1F93FF","config":{"allowed_locales":[{"code":"sample code","articles_count":5,"categories_count":5}]},"custom_domain":"sample custom domain","header_text":"sample header text","homepage_link":"https://example.com/resource","name":"Sample Name","slug":"sample-slug","page_title":"sample page title","account_id":1,"inbox":{"navigation_only":true,"id":1,"name":"Sample Name","website_url":"https://example.com/resource","channel_type":"Channel::Api","avatar_url":"https://example.com/resource","widget_color":"#1F93FF","website_token":"sample-token","enable_auto_assignment":true,"web_widget_script":"sample web widget script","welcome_title":"sample welcome title","welcome_tagline":"sample welcome tagline","greeting_enabled":true,"greeting_message":"sample greeting message","channel_id":1,"working_hours_enabled":true,"enable_email_collect":true,"csat_survey_enabled":true,"auto_assignment_config":{},"out_of_office_message":"sample out of office message","working_hours":[{"day_of_week":12.5,"closed_all_day":true,"open_hour":12.5,"open_minutes":12.5,"close_hour":12.5,"close_minutes":12.5,"open_all_day":true}],"timezone":"America/Sao_Paulo","callback_webhook_url":"https://example.com/resource","allow_messages_after_resolved":true,"lock_to_single_conversation":true,"sender_name_type":"friendly","auto_resolve_config":{"mode":"custom","after":30,"message":"We are closing this conversation due to inactivity.","label":"auto-resolved","allow_waiting":false},"outbound_agent_name_header_policy":"inherit","business_name":"sample business name","branded_email_layout":"agent@example.com","responder_policy":{"mode":"agent_bot","conflict":true},"hmac_mandatory":true,"selected_feature_flags":["sample selected feature flag"],"reply_time":"2026-01-15T10:30:00.000Z","messaging_service_sid":"sample messaging service sid","phone_number":"+5511999998888","bandwidth_callback_state":"active","bandwidth_api_migration_state":"oauth2_configured","medium":"sample medium","provider":"default","whatsapp_web_session_state":{"state":"connected","fresh":true,"observed_at":"2026-01-15T10:30:00.000Z","disconnected_since":null},"hybrid_pair":{"paired":true,"id":4,"role":"cloud","sibling_inbox_id":18,"canonical_phone":"+5521900000000","primary":"cloud","inbound_authority":"cloud","unified_inbox":true,"unified_state":{"state":"complete","scanned":42,"frozen":40,"reconciled_count":2,"completed_at":"2026-10-03T12:00:00.000Z","blocked_conversations":[]},"routing":{"outbound_default":"cloud","out_of_window":"web","fallback":true,"manual_override":true,"weighted":{"mode":"weighted","web_percent":30,"version":2}},"web_channel_id":12,"web_inbox_id":18,"calling_provider":"whatsapp_web","web_voice_enabled":true,"web_inbound_calls_enabled":true,"web_call_config_sync":{"state":"pending","checked_at":"2026-10-03T12:00:00.000Z"},"web_video_calls_enabled":false,"web_group_calls_enabled":false,"web_reauthorization_required":false,"web_session_state":{"state":"connected","fresh":true,"observed_at":"2026-10-03T12:00:00.000Z","disconnected_since":null},"web_allow_message_deletion":true}},"logo":{"id":1,"portal_id":1,"file_type":"image","account_id":1,"file_url":"https://example.com/resource","blob_id":"sample blob id","filename":"sample filename"},"meta":{"all_articles_count":5,"archived_articles_count":5,"published_count":5,"draft_articles_count":5,"categories_count":5,"default_locale":"sample default locale"}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/portal_update_payload"},"example":{"blob_id":"eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBBQT09In19--signed"}}}}},"delete":{"tags":["Help Center"],"operationId":"auto_delete_api_v1_accounts_account_id_portals_id","summary":"Delete portals","description":"Deletes the portal identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Success (no content)"},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}}}},"/api/v1/accounts/{account_id}/portals/{id}/categories":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"$ref":"#/components/parameters/portal_id"}],"post":{"tags":["Help Center"],"operationId":"add-new-category-to-account","summary":"Add a new category","description":"Add a new category to portal","security":[{"userApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/category_create_update_payload"},"example":{"name":"Category Name","description":"Category description","position":1,"slug":"category-name","locale":"en","icon":"📚","parent_category_id":1,"associated_category_id":2}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/category"},"example":{"id":1,"description":"A short description.","locale":"en","name":"Sample Name","slug":"sample-slug","position":1,"visibility":"public","portal_id":1,"account_id":1,"associated_category_id":1,"parent_category_id":1}}}},"403":{"description":"Access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"get":{"tags":["Help Center"],"operationId":"auto_get_api_v1_accounts_account_id_portals_portal_id_categories","summary":"List categories","description":"Returns the list of categories visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object"}},"meta":{"type":"object","properties":{"current_page":{"type":"string"},"categories_count":{"type":"integer"}}}}},"example":{"payload":[{}],"meta":{"current_page":"sample current page","categories_count":5}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."}]}},"/api/v1/accounts/{account_id}/portals/{id}/articles":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"$ref":"#/components/parameters/portal_id"}],"post":{"tags":["Help Center"],"operationId":"add-new-article-to-account","summary":"Add a new article","description":"Add a new article to portal","security":[{"userApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/article_create_update_payload"},"example":{"title":"Article Title","slug":"article-title","position":1,"content":"This is the content of the article","description":"This is the description of the article","category_id":1,"author_id":1,"associated_article_id":2,"status":1,"locale":"en","meta":{"tags":["article_name"],"title":"article title","description":"article description"}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/article"},"example":{"id":1,"content":"Sample content text.","meta":{},"position":1,"status":"draft","visibility":"public","title":"Sample title","slug":"sample-slug","views":1,"portal_id":1,"account_id":1,"author_id":1,"category_id":1,"folder_id":1,"associated_article_id":1}}}},"403":{"description":"Access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"get":{"tags":["Help Center"],"operationId":"auto_get_api_v1_accounts_account_id_portals_portal_id_articles","summary":"List articles","description":"Returns the list of articles visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object"}},"meta":{"type":"object","properties":{"all_articles_count":{"type":"integer"},"archived_articles_count":{"type":"integer"},"articles_count":{"type":"integer"},"current_page":{"type":"string"},"draft_articles_count":{"type":"integer"},"mine_articles_count":{"type":"integer"},"published_count":{"type":"integer"}}}}},"example":{"payload":[{}],"meta":{"all_articles_count":5,"archived_articles_count":5,"articles_count":5,"current_page":"sample current page","draft_articles_count":5,"mine_articles_count":5,"published_count":5}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."},{"name":"locale","in":"query","required":false,"schema":{"type":"string","enum":["en","pt_BR","es"]}},{"name":"query","in":"query","required":false,"schema":{"type":"string"}},{"name":"category_slug","in":"query","required":false,"schema":{"type":"string"}},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["draft","published","archived"]}},{"name":"author_id","in":"query","required":false,"schema":{"type":"integer"}}]}},"/api/v1/accounts/{account_id}/conversations/meta":{"parameters":[{"$ref":"#/components/parameters/account_id"}],"get":{"tags":["Conversations"],"operationId":"conversationListMeta","description":"Get open, unassigned and all Conversation counts","summary":"Get Conversation Counts","security":[{"userApiKey":[]}],"parameters":[{"name":"status","in":"query","schema":{"type":"string","enum":["all","open","resolved","pending","snoozed"],"default":"open"},"description":"Filter by one conversation status. Omit this scalar parameter when using status[]."},{"name":"status[]","in":"query","style":"form","explode":true,"schema":{"type":"array","minItems":2,"maxItems":2,"uniqueItems":true,"items":{"type":"string","enum":["open","pending"]}},"example":["open","pending"],"description":"Count the union of open and pending conversations with status[]=open\u0026status[]=pending. Both existing statuses are required, in either order. Do not combine with the scalar status parameter. Inbox, team, label and permission scopes still apply, matching the conversation list counters."},{"name":"q","in":"query","schema":{"type":"string"},"description":"Filters conversations with messages containing the search term"},{"name":"inbox_id","in":"query","schema":{"type":"integer"}},{"name":"team_id","in":"query","schema":{"type":"integer"}},{"name":"labels","in":"query","schema":{"type":"array","items":{"type":"string"}}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"meta":{"type":"object","properties":{"mine_count":{"type":"number"},"unassigned_count":{"type":"number"},"assigned_count":{"type":"number"},"all_count":{"type":"number"},"mine_unread_count":{"type":"number","description":"Conversations assigned to the current user with at least one unread incoming message, across every page of the list."},"unassigned_unread_count":{"type":"number","description":"Unassigned conversations with at least one unread incoming message, across every page of the list."},"all_unread_count":{"type":"number","description":"Conversations of the list with at least one unread incoming message, across every page."}}}}},"example":{"meta":{"mine_count":5,"unassigned_count":5,"assigned_count":5,"all_count":5,"mine_unread_count":5,"unassigned_unread_count":5,"all_unread_count":5}}}}},"400":{"description":"Bad Request Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"422":{"description":"Unsupported status selection or status[] combination","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}},"example":{"error":"sample error"}}}}}}},"/api/v1/accounts/{account_id}/conversations":{"parameters":[{"$ref":"#/components/parameters/account_id"}],"get":{"tags":["Conversations"],"operationId":"conversationList","description":"List all the conversations with pagination","summary":"Conversations List","security":[{"userApiKey":[]}],"parameters":[{"name":"assignee_type","in":"query","schema":{"type":"string","enum":["me","unassigned","all","assigned"],"default":"all"},"description":"Filter conversations by assignee type."},{"name":"status","in":"query","schema":{"type":"string","enum":["all","open","resolved","pending","snoozed"],"default":"open"},"description":"Filter by one conversation status. Omit this scalar parameter when using status[]."},{"name":"status[]","in":"query","style":"form","explode":true,"schema":{"type":"array","minItems":2,"maxItems":2,"uniqueItems":true,"items":{"type":"string","enum":["open","pending"]}},"example":["open","pending"],"description":"List the union of open and pending conversations with status[]=open\u0026status[]=pending. These are existing statuses, not a new persisted status. Both values are required, in either order. Do not combine with the scalar status parameter. Inbox, team, label, assignment and permission scopes still apply; the metadata counters use the same accessible union before the assignment tab filter."},{"name":"q","in":"query","schema":{"type":"string"},"description":"Filters conversations with messages containing the search term"},{"name":"inbox_id","in":"query","schema":{"type":"integer"}},{"name":"team_id","in":"query","schema":{"type":"integer"}},{"name":"labels","in":"query","schema":{"type":"array","items":{"type":"string"}}},{"name":"page","in":"query","schema":{"type":"integer","default":1},"description":"paginate through conversations"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/conversation_list"},"example":{"data":{"meta":{"mine_count":5,"unassigned_count":5,"assigned_count":5,"all_count":5,"mine_unread_count":5,"unassigned_unread_count":5,"all_unread_count":5},"payload":[{"id":1,"messages":[{"client_message_id":"sample client message id","client_message_actor":"User:7","outbound_dispatch":{"state":"queued","retryable":true},"id":1,"content":"Sample content text.","content_readiness":{"state":"waiting","quality":"pending","generation":1,"content_version":1},"account_id":1,"inbox_id":1,"logical_inbox_id":1,"echo_id":"sample echo id","conversation_id":1,"message_type":0,"created_at":1,"updated_at":1,"private":true,"status":"sent","source_id":"sample source id","content_type":"text","content_attributes":{"instagram_mention":{"media_id":"sample media id","comment_id":"sample comment id","mention_type":"comment","enrichment_status":"unresolved","replyable":true,"author_id":"sample author id","author_username":"sample author username","text":"sample text","media_type":"sample media type","media_product_type":"sample media product type","permalink":"https://example.com/resource","identity_scope":{"account_id":1,"inbox_id":1,"instagram_id":"sample instagram id"},"recovery":{"state":"scheduled","reason":"Sample reason.","attempts":1,"checked_at":"2026-01-15T10:30:00.000Z","next_retry_at":"2026-01-15T10:30:00.000Z","lease_until":"2026-01-15T10:30:00.000Z"}},"translations":{},"translation":{"original_content":"sample original content","original_html_content":"sample original html content","delivery":{"status":"translated","source_language":"pt","target_language":"en","provider":"google_translate","content_digest":"sample content digest","translated_at":"2026-01-15T10:30:00.000Z","error_code":"translation_failed","cause_code":"provider_not_configured","failed_at":"2026-01-15T10:30:00.000Z"},"views":{}},"external_error":"sample external error","contact_share":{"origin":"contact_request","transport":"cloud","status":"linked","reason":"identity_owned_by_another_contact","other_contact_ids":[1],"reconciliation_id":"sample reconciliation id"}},"sender_type":"Contact","sender_id":1,"external_source_ids":{},"additional_attributes":{},"processed_message_content":"sample processed message content","sentiment":{},"conversation":{},"attachment":{},"attachments":[{"id":1,"message_id":1,"file_type":"image","account_id":1,"extension":"sample extension","data_url":"https://example.com/resource","media_readiness_revision":"sample media readiness revision","playable_audio_url":"https://example.com/resource","playable_video_url":"https://example.com/resource","video_processing":true,"video_unavailable":true,"thumb_url":"https://example.com/resource","file_size":1,"width":1,"height":1,"coordinates_lat":12.5,"coordinates_long":12.5,"fallback_title":"sample fallback title","meta":{},"transcribed_text":"sample transcribed text","transcript_translations":{"pt-BR":"Você pode me ajudar?","es":"¿Puedes ayudarme?"},"transcript_translation_states":{}}],"sender":{}}],"account_id":1,"uuid":"sample uuid","additional_attributes":{},"agent_last_seen_at":12.5,"assignee_last_seen_at":12.5,"can_reply":true,"contact_last_seen_at":12.5,"custom_attributes":{},"inbox_id":1,"labels":["sample label"],"muted":true,"snoozed_until":12.5,"status":"open","created_at":12.5,"updated_at":12.5,"automation_control_event_cursor":1,"timestamp":12.5,"first_reply_created_at":12.5,"unread_count":5,"last_non_activity_message":{"client_message_id":"sample client message id","client_message_actor":"User:7","outbound_dispatch":{"state":"queued","retryable":true},"id":1,"content":"Sample content text.","content_readiness":{"state":"waiting","quality":"pending","generation":1,"content_version":1},"account_id":1,"inbox_id":1,"logical_inbox_id":1,"echo_id":"sample echo id","conversation_id":1,"message_type":0,"created_at":1,"updated_at":1,"private":true,"status":"sent","source_id":"sample source id","content_type":"text","content_attributes":{"instagram_mention":{"media_id":"sample media id","comment_id":"sample comment id","mention_type":"comment","enrichment_status":"unresolved","replyable":true,"author_id":"sample author id","author_username":"sample author username","text":"sample text","media_type":"sample media type","media_product_type":"sample media product type","permalink":"https://example.com/resource","identity_scope":{"account_id":1,"inbox_id":1,"instagram_id":"sample instagram id"},"recovery":{"state":"scheduled","reason":"Sample reason.","attempts":1,"checked_at":"2026-01-15T10:30:00.000Z","next_retry_at":"2026-01-15T10:30:00.000Z","lease_until":"2026-01-15T10:30:00.000Z"}},"translations":{},"translation":{"original_content":"sample original content","original_html_content":"sample original html content","delivery":{"status":"translated","source_language":"pt","target_language":"en","provider":"google_translate","content_digest":"sample content digest","translated_at":"2026-01-15T10:30:00.000Z","error_code":"translation_failed","cause_code":"provider_not_configured","failed_at":"2026-01-15T10:30:00.000Z"},"views":{}},"external_error":"sample external error","contact_share":{"origin":"contact_request","transport":"cloud","status":"linked","reason":"identity_owned_by_another_contact","other_contact_ids":[1],"reconciliation_id":"sample reconciliation id"}},"sender_type":"Contact","sender_id":1,"external_source_ids":{},"additional_attributes":{},"processed_message_content":"sample processed message content","sentiment":{},"conversation":{},"attachment":{},"attachments":[{"id":1,"message_id":1,"file_type":"image","account_id":1,"extension":"sample extension","data_url":"https://example.com/resource","media_readiness_revision":"sample media readiness revision","playable_audio_url":"https://example.com/resource","playable_video_url":"https://example.com/resource","video_processing":true,"video_unavailable":true,"thumb_url":"https://example.com/resource","file_size":1,"width":1,"height":1,"coordinates_lat":12.5,"coordinates_long":12.5,"fallback_title":"sample fallback title","meta":{},"transcribed_text":"sample transcribed text","transcript_translations":{"pt-BR":"Você pode me ajudar?","es":"¿Puedes ayudarme?"},"transcript_translation_states":{}}],"sender":{}},"last_activity_at":12.5,"priority":"low","waiting_since":12.5,"sla_policy_id":1,"applied_sla":{},"sla_events":[{}],"meta":{"sender":{"additional_attributes":{},"availability_status":"online","email":"agent@example.com","id":1,"name":"Sample Name","phone_number":"+5511999998888","blocked":true,"identifier":"sample-identifier","thumbnail":"sample thumbnail","custom_attributes":{},"last_activity_at":12.5,"created_at":12.5},"channel":"sample channel","assignee":{"id":1,"access_token":"sample-token","account_id":1,"available_name":"sample available name","avatar_url":"https://example.com/resource","confirmed":true,"display_name":"sample display name","message_signature":"sample message signature","email":"agent@example.com","hmac_identifier":"sample hmac identifier","inviter_id":1,"name":"Sample Name","provider":"email","pubsub_token":"sample-token","role":"agent","ui_settings":{"translation_language_by_account":{"1":"pt-BR"}},"uid":"sample uid","type":"sample type","custom_attributes":{},"accounts":[{"id":1,"name":"Sample Name","status":"active","active_at":"2026-01-15T10:30:00.000Z","role":"administrator","outbound_agent_name_header_policy":"inherit","permissions":["sample permission"],"availability":"online","availability_status":"online","auto_offline":true,"custom_role_id":1,"custom_role":{"id":1,"name":"Sample Name","description":"A short description.","permissions":["conversation_manage"]},"onboarding_step":"sample onboarding step","access_role_id":1,"access_role":{"id":1,"name":"Sample Name","field_permissions":{}},"api_and_webhooks":true}]},"hmac_verified":true}}]}}}}},"400":{"description":"Bad Request Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"422":{"description":"Unsupported status selection or status[] combination","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}},"example":{"error":"sample error"}}}}}},"post":{"tags":["Conversations"],"operationId":"newConversation","summary":"Create New Conversation","description":"Creating a conversation requires a source id (the identifier of the contact in the channel).","security":[{"userApiKey":[]},{"agentBotApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/conversation_create_payload"},"example":{"source_id":"1234567890","inbox_id":1,"contact_id":1,"additional_attributes":{"browser":"Chrome","browser_version":"89.0.4389.82","os":"Windows","os_version":"10"},"custom_attributes":{"attribute_key":"attribute_value","priority_conversation_number":3},"status":"open","assignee_id":1,"team_id":1,"snoozed_until":"2030-07-21T17:32:28Z","message":{"content":"Hello, how can I help you?","template_params":{"name":"sample_issue_resolution","category":"UTILITY","language":"en_US","processed_params":{"1":"Acme"}}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"number","description":"ID of the conversation"},"account_id":{"type":"number","description":"Account Id"},"inbox_id":{"type":"number","description":"ID of the inbox"}}},"example":{"id":1,"account_id":1,"inbox_id":1}}}},"403":{"description":"Access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/conversations/filter":{"parameters":[{"$ref":"#/components/parameters/account_id"}],"post":{"tags":["Conversations"],"operationId":"conversationFilter","description":"Filter conversations with custom filter options and pagination","summary":"Conversations Filter","security":[{"userApiKey":[]}],"parameters":[{"name":"page","in":"query","schema":{"type":"number"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","properties":{"attribute_key":{"type":"string","description":"filter attribute name"},"filter_operator":{"type":"string","description":"filter operator name","enum":["equal_to","not_equal_to","contains","does_not_contain"]},"values":{"type":"array","items":{"type":"string"},"description":"array of the attribute values to filter"},"query_operator":{"type":["string","null"],"description":"query operator name (null on the last condition)","enum":["AND","OR",null]}}},"example":[{"attribute_key":"browser_language","filter_operator":"not_equal_to","values":["en"],"query_operator":"AND"},{"attribute_key":"status","filter_operator":"equal_to","values":["pending"],"query_operator":null}]}}},"example":{"payload":[{"attribute_key":"browser_language","filter_operator":"not_equal_to","values":["en"],"query_operator":"AND"},{"attribute_key":"status","filter_operator":"equal_to","values":["pending"],"query_operator":null}]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/conversation_list"},"example":{"data":{"meta":{"mine_count":5,"unassigned_count":5,"assigned_count":5,"all_count":5,"mine_unread_count":5,"unassigned_unread_count":5,"all_unread_count":5},"payload":[{"id":1,"messages":[{"client_message_id":"sample client message id","client_message_actor":"User:7","outbound_dispatch":{"state":"queued","retryable":true},"id":1,"content":"Sample content text.","content_readiness":{"state":"waiting","quality":"pending","generation":1,"content_version":1},"account_id":1,"inbox_id":1,"logical_inbox_id":1,"echo_id":"sample echo id","conversation_id":1,"message_type":0,"created_at":1,"updated_at":1,"private":true,"status":"sent","source_id":"sample source id","content_type":"text","content_attributes":{"instagram_mention":{"media_id":"sample media id","comment_id":"sample comment id","mention_type":"comment","enrichment_status":"unresolved","replyable":true,"author_id":"sample author id","author_username":"sample author username","text":"sample text","media_type":"sample media type","media_product_type":"sample media product type","permalink":"https://example.com/resource","identity_scope":{"account_id":1,"inbox_id":1,"instagram_id":"sample instagram id"},"recovery":{"state":"scheduled","reason":"Sample reason.","attempts":1,"checked_at":"2026-01-15T10:30:00.000Z","next_retry_at":"2026-01-15T10:30:00.000Z","lease_until":"2026-01-15T10:30:00.000Z"}},"translations":{},"translation":{"original_content":"sample original content","original_html_content":"sample original html content","delivery":{"status":"translated","source_language":"pt","target_language":"en","provider":"google_translate","content_digest":"sample content digest","translated_at":"2026-01-15T10:30:00.000Z","error_code":"translation_failed","cause_code":"provider_not_configured","failed_at":"2026-01-15T10:30:00.000Z"},"views":{}},"external_error":"sample external error","contact_share":{"origin":"contact_request","transport":"cloud","status":"linked","reason":"identity_owned_by_another_contact","other_contact_ids":[1],"reconciliation_id":"sample reconciliation id"}},"sender_type":"Contact","sender_id":1,"external_source_ids":{},"additional_attributes":{},"processed_message_content":"sample processed message content","sentiment":{},"conversation":{},"attachment":{},"attachments":[{"id":1,"message_id":1,"file_type":"image","account_id":1,"extension":"sample extension","data_url":"https://example.com/resource","media_readiness_revision":"sample media readiness revision","playable_audio_url":"https://example.com/resource","playable_video_url":"https://example.com/resource","video_processing":true,"video_unavailable":true,"thumb_url":"https://example.com/resource","file_size":1,"width":1,"height":1,"coordinates_lat":12.5,"coordinates_long":12.5,"fallback_title":"sample fallback title","meta":{},"transcribed_text":"sample transcribed text","transcript_translations":{"pt-BR":"Você pode me ajudar?","es":"¿Puedes ayudarme?"},"transcript_translation_states":{}}],"sender":{}}],"account_id":1,"uuid":"sample uuid","additional_attributes":{},"agent_last_seen_at":12.5,"assignee_last_seen_at":12.5,"can_reply":true,"contact_last_seen_at":12.5,"custom_attributes":{},"inbox_id":1,"labels":["sample label"],"muted":true,"snoozed_until":12.5,"status":"open","created_at":12.5,"updated_at":12.5,"automation_control_event_cursor":1,"timestamp":12.5,"first_reply_created_at":12.5,"unread_count":5,"last_non_activity_message":{"client_message_id":"sample client message id","client_message_actor":"User:7","outbound_dispatch":{"state":"queued","retryable":true},"id":1,"content":"Sample content text.","content_readiness":{"state":"waiting","quality":"pending","generation":1,"content_version":1},"account_id":1,"inbox_id":1,"logical_inbox_id":1,"echo_id":"sample echo id","conversation_id":1,"message_type":0,"created_at":1,"updated_at":1,"private":true,"status":"sent","source_id":"sample source id","content_type":"text","content_attributes":{"instagram_mention":{"media_id":"sample media id","comment_id":"sample comment id","mention_type":"comment","enrichment_status":"unresolved","replyable":true,"author_id":"sample author id","author_username":"sample author username","text":"sample text","media_type":"sample media type","media_product_type":"sample media product type","permalink":"https://example.com/resource","identity_scope":{"account_id":1,"inbox_id":1,"instagram_id":"sample instagram id"},"recovery":{"state":"scheduled","reason":"Sample reason.","attempts":1,"checked_at":"2026-01-15T10:30:00.000Z","next_retry_at":"2026-01-15T10:30:00.000Z","lease_until":"2026-01-15T10:30:00.000Z"}},"translations":{},"translation":{"original_content":"sample original content","original_html_content":"sample original html content","delivery":{"status":"translated","source_language":"pt","target_language":"en","provider":"google_translate","content_digest":"sample content digest","translated_at":"2026-01-15T10:30:00.000Z","error_code":"translation_failed","cause_code":"provider_not_configured","failed_at":"2026-01-15T10:30:00.000Z"},"views":{}},"external_error":"sample external error","contact_share":{"origin":"contact_request","transport":"cloud","status":"linked","reason":"identity_owned_by_another_contact","other_contact_ids":[1],"reconciliation_id":"sample reconciliation id"}},"sender_type":"Contact","sender_id":1,"external_source_ids":{},"additional_attributes":{},"processed_message_content":"sample processed message content","sentiment":{},"conversation":{},"attachment":{},"attachments":[{"id":1,"message_id":1,"file_type":"image","account_id":1,"extension":"sample extension","data_url":"https://example.com/resource","media_readiness_revision":"sample media readiness revision","playable_audio_url":"https://example.com/resource","playable_video_url":"https://example.com/resource","video_processing":true,"video_unavailable":true,"thumb_url":"https://example.com/resource","file_size":1,"width":1,"height":1,"coordinates_lat":12.5,"coordinates_long":12.5,"fallback_title":"sample fallback title","meta":{},"transcribed_text":"sample transcribed text","transcript_translations":{"pt-BR":"Você pode me ajudar?","es":"¿Puedes ayudarme?"},"transcript_translation_states":{}}],"sender":{}},"last_activity_at":12.5,"priority":"low","waiting_since":12.5,"sla_policy_id":1,"applied_sla":{},"sla_events":[{}],"meta":{"sender":{"additional_attributes":{},"availability_status":"online","email":"agent@example.com","id":1,"name":"Sample Name","phone_number":"+5511999998888","blocked":true,"identifier":"sample-identifier","thumbnail":"sample thumbnail","custom_attributes":{},"last_activity_at":12.5,"created_at":12.5},"channel":"sample channel","assignee":{"id":1,"access_token":"sample-token","account_id":1,"available_name":"sample available name","avatar_url":"https://example.com/resource","confirmed":true,"display_name":"sample display name","message_signature":"sample message signature","email":"agent@example.com","hmac_identifier":"sample hmac identifier","inviter_id":1,"name":"Sample Name","provider":"email","pubsub_token":"sample-token","role":"agent","ui_settings":{"translation_language_by_account":{"1":"pt-BR"}},"uid":"sample uid","type":"sample type","custom_attributes":{},"accounts":[{"id":1,"name":"Sample Name","status":"active","active_at":"2026-01-15T10:30:00.000Z","role":"administrator","outbound_agent_name_header_policy":"inherit","permissions":["sample permission"],"availability":"online","availability_status":"online","auto_offline":true,"custom_role_id":1,"custom_role":{"id":1,"name":"Sample Name","description":"A short description.","permissions":["conversation_manage"]},"onboarding_step":"sample onboarding step","access_role_id":1,"access_role":{"id":1,"name":"Sample Name","field_permissions":{}},"api_and_webhooks":true}]},"hmac_verified":true}}]}}}}},"400":{"description":"Bad Request Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/conversations/{conversation_id}":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"$ref":"#/components/parameters/conversation_id"}],"get":{"tags":["Conversations"],"operationId":"get-details-of-a-conversation","summary":"Conversation Details","security":[{"userApiKey":[]}],"description":"Get all details regarding a conversation with all messages in the conversation","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/conversation_show"},"example":{"id":1,"messages":[{"client_message_id":"sample client message id","client_message_actor":"User:7","outbound_dispatch":{"state":"queued","retryable":true},"id":1,"content":"Sample content text.","content_readiness":{"state":"waiting","quality":"pending","generation":1,"content_version":1},"account_id":1,"inbox_id":1,"logical_inbox_id":1,"echo_id":"sample echo id","conversation_id":1,"message_type":0,"created_at":1,"updated_at":1,"private":true,"status":"sent","source_id":"sample source id","content_type":"text","content_attributes":{"instagram_mention":{"media_id":"sample media id","comment_id":"sample comment id","mention_type":"comment","enrichment_status":"unresolved","replyable":true,"author_id":"sample author id","author_username":"sample author username","text":"sample text","media_type":"sample media type","media_product_type":"sample media product type","permalink":"https://example.com/resource","identity_scope":{"account_id":1,"inbox_id":1,"instagram_id":"sample instagram id"},"recovery":{"state":"scheduled","reason":"Sample reason.","attempts":1,"checked_at":"2026-01-15T10:30:00.000Z","next_retry_at":"2026-01-15T10:30:00.000Z","lease_until":"2026-01-15T10:30:00.000Z"}},"translations":{},"translation":{"original_content":"sample original content","original_html_content":"sample original html content","delivery":{"status":"translated","source_language":"pt","target_language":"en","provider":"google_translate","content_digest":"sample content digest","translated_at":"2026-01-15T10:30:00.000Z","error_code":"translation_failed","cause_code":"provider_not_configured","failed_at":"2026-01-15T10:30:00.000Z"},"views":{}},"external_error":"sample external error","contact_share":{"origin":"contact_request","transport":"cloud","status":"linked","reason":"identity_owned_by_another_contact","other_contact_ids":[1],"reconciliation_id":"sample reconciliation id"}},"sender_type":"Contact","sender_id":1,"external_source_ids":{},"additional_attributes":{},"processed_message_content":"sample processed message content","sentiment":{},"conversation":{},"attachment":{},"attachments":[{"id":1,"message_id":1,"file_type":"image","account_id":1,"extension":"sample extension","data_url":"https://example.com/resource","media_readiness_revision":"sample media readiness revision","playable_audio_url":"https://example.com/resource","playable_video_url":"https://example.com/resource","video_processing":true,"video_unavailable":true,"thumb_url":"https://example.com/resource","file_size":1,"width":1,"height":1,"coordinates_lat":12.5,"coordinates_long":12.5,"fallback_title":"sample fallback title","meta":{},"transcribed_text":"sample transcribed text","transcript_translations":{"pt-BR":"Você pode me ajudar?","es":"¿Puedes ayudarme?"},"transcript_translation_states":{}}],"sender":{}}],"account_id":1,"uuid":"sample uuid","additional_attributes":{},"agent_last_seen_at":12.5,"assignee_last_seen_at":12.5,"can_reply":true,"contact_last_seen_at":12.5,"custom_attributes":{},"inbox_id":1,"labels":["sample label"],"muted":true,"snoozed_until":12.5,"status":"open","created_at":12.5,"updated_at":12.5,"automation_control_event_cursor":1,"timestamp":12.5,"first_reply_created_at":12.5,"unread_count":5,"last_non_activity_message":{"client_message_id":"sample client message id","client_message_actor":"User:7","outbound_dispatch":{"state":"queued","retryable":true},"id":1,"content":"Sample content text.","content_readiness":{"state":"waiting","quality":"pending","generation":1,"content_version":1},"account_id":1,"inbox_id":1,"logical_inbox_id":1,"echo_id":"sample echo id","conversation_id":1,"message_type":0,"created_at":1,"updated_at":1,"private":true,"status":"sent","source_id":"sample source id","content_type":"text","content_attributes":{"instagram_mention":{"media_id":"sample media id","comment_id":"sample comment id","mention_type":"comment","enrichment_status":"unresolved","replyable":true,"author_id":"sample author id","author_username":"sample author username","text":"sample text","media_type":"sample media type","media_product_type":"sample media product type","permalink":"https://example.com/resource","identity_scope":{"account_id":1,"inbox_id":1,"instagram_id":"sample instagram id"},"recovery":{"state":"scheduled","reason":"Sample reason.","attempts":1,"checked_at":"2026-01-15T10:30:00.000Z","next_retry_at":"2026-01-15T10:30:00.000Z","lease_until":"2026-01-15T10:30:00.000Z"}},"translations":{},"translation":{"original_content":"sample original content","original_html_content":"sample original html content","delivery":{"status":"translated","source_language":"pt","target_language":"en","provider":"google_translate","content_digest":"sample content digest","translated_at":"2026-01-15T10:30:00.000Z","error_code":"translation_failed","cause_code":"provider_not_configured","failed_at":"2026-01-15T10:30:00.000Z"},"views":{}},"external_error":"sample external error","contact_share":{"origin":"contact_request","transport":"cloud","status":"linked","reason":"identity_owned_by_another_contact","other_contact_ids":[1],"reconciliation_id":"sample reconciliation id"}},"sender_type":"Contact","sender_id":1,"external_source_ids":{},"additional_attributes":{},"processed_message_content":"sample processed message content","sentiment":{},"conversation":{},"attachment":{},"attachments":[{"id":1,"message_id":1,"file_type":"image","account_id":1,"extension":"sample extension","data_url":"https://example.com/resource","media_readiness_revision":"sample media readiness revision","playable_audio_url":"https://example.com/resource","playable_video_url":"https://example.com/resource","video_processing":true,"video_unavailable":true,"thumb_url":"https://example.com/resource","file_size":1,"width":1,"height":1,"coordinates_lat":12.5,"coordinates_long":12.5,"fallback_title":"sample fallback title","meta":{},"transcribed_text":"sample transcribed text","transcript_translations":{"pt-BR":"Você pode me ajudar?","es":"¿Puedes ayudarme?"},"transcript_translation_states":{}}],"sender":{}},"last_activity_at":12.5,"priority":"low","waiting_since":12.5,"sla_policy_id":1,"applied_sla":{},"sla_events":[{}],"meta":{"sender":{"additional_attributes":{},"availability_status":"online","email":"agent@example.com","id":1,"name":"Sample Name","phone_number":"+5511999998888","blocked":true,"identifier":"sample-identifier","thumbnail":"sample thumbnail","custom_attributes":{},"last_activity_at":12.5,"created_at":12.5},"channel":"sample channel","assignee":{"id":1,"access_token":"sample-token","account_id":1,"available_name":"sample available name","avatar_url":"https://example.com/resource","confirmed":true,"display_name":"sample display name","message_signature":"sample message signature","email":"agent@example.com","hmac_identifier":"sample hmac identifier","inviter_id":1,"name":"Sample Name","provider":"email","pubsub_token":"sample-token","role":"agent","ui_settings":{"translation_language_by_account":{"1":"pt-BR"}},"uid":"sample uid","type":"sample type","custom_attributes":{},"accounts":[{"id":1,"name":"Sample Name","status":"active","active_at":"2026-01-15T10:30:00.000Z","role":"administrator","outbound_agent_name_header_policy":"inherit","permissions":["sample permission"],"availability":"online","availability_status":"online","auto_offline":true,"custom_role_id":1,"custom_role":{"id":1,"name":"Sample Name","description":"A short description.","permissions":["conversation_manage"]},"onboarding_step":"sample onboarding step","access_role_id":1,"access_role":{"id":1,"name":"Sample Name","field_permissions":{"contact":{},"organization":{}}},"api_and_webhooks":true}]},"hmac_verified":true}}}}},"403":{"description":"Access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"Conversation not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"patch":{"tags":["Conversations"],"operationId":"update-conversation","summary":"Update Conversation","description":"Updates bounded conversation attributes. Assignment fields are not accepted here; use the atomic conversation assignment endpoint instead of sending assignee_id, assignee_type or team_id.","security":[{"userApiKey":[]},{"agentBotApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"priority":{"type":"string","enum":["urgent","high","medium","low","none"],"description":"The priority of the conversation","example":"high"},"sla_policy_id":{"type":"number","description":"The ID of the SLA policy (Available only in Enterprise edition)","example":1}}},"example":{"priority":"high","sla_policy_id":1}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/conversation"},"example":{"id":1,"messages":[{"client_message_id":"sample client message id","client_message_actor":"User:7","outbound_dispatch":{"state":"queued","retryable":true},"id":1,"content":"Sample content text.","content_readiness":{"state":"waiting","quality":"pending","generation":1,"content_version":1},"account_id":1,"inbox_id":1,"logical_inbox_id":1,"echo_id":"sample echo id","conversation_id":1,"message_type":0,"created_at":1,"updated_at":1,"private":true,"status":"sent","source_id":"sample source id","content_type":"text","content_attributes":{"instagram_mention":{"media_id":"sample media id","comment_id":"sample comment id","mention_type":"comment","enrichment_status":"unresolved","replyable":true,"author_id":"sample author id","author_username":"sample author username","text":"sample text","media_type":"sample media type","media_product_type":"sample media product type","permalink":"https://example.com/resource","identity_scope":{"account_id":1,"inbox_id":1,"instagram_id":"sample instagram id"},"recovery":{"state":"scheduled","reason":"Sample reason.","attempts":1,"checked_at":"2026-01-15T10:30:00.000Z","next_retry_at":"2026-01-15T10:30:00.000Z","lease_until":"2026-01-15T10:30:00.000Z"}},"translations":{},"translation":{"original_content":"sample original content","original_html_content":"sample original html content","delivery":{"status":"translated","source_language":"pt","target_language":"en","provider":"google_translate","content_digest":"sample content digest","translated_at":"2026-01-15T10:30:00.000Z","error_code":"translation_failed","cause_code":"provider_not_configured","failed_at":"2026-01-15T10:30:00.000Z"},"views":{}},"external_error":"sample external error","contact_share":{"origin":"contact_request","transport":"cloud","status":"linked","reason":"identity_owned_by_another_contact","other_contact_ids":[1],"reconciliation_id":"sample reconciliation id"}},"sender_type":"Contact","sender_id":1,"external_source_ids":{},"additional_attributes":{},"processed_message_content":"sample processed message content","sentiment":{},"conversation":{},"attachment":{},"attachments":[{"id":1,"message_id":1,"file_type":"image","account_id":1,"extension":"sample extension","data_url":"https://example.com/resource","media_readiness_revision":"sample media readiness revision","playable_audio_url":"https://example.com/resource","playable_video_url":"https://example.com/resource","video_processing":true,"video_unavailable":true,"thumb_url":"https://example.com/resource","file_size":1,"width":1,"height":1,"coordinates_lat":12.5,"coordinates_long":12.5,"fallback_title":"sample fallback title","meta":{},"transcribed_text":"sample transcribed text","transcript_translations":{"pt-BR":"Você pode me ajudar?","es":"¿Puedes ayudarme?"},"transcript_translation_states":{}}],"sender":{}}],"account_id":1,"uuid":"sample uuid","additional_attributes":{},"agent_last_seen_at":12.5,"assignee_last_seen_at":12.5,"can_reply":true,"contact_last_seen_at":12.5,"custom_attributes":{},"inbox_id":1,"labels":["sample label"],"muted":true,"snoozed_until":12.5,"status":"open","created_at":12.5,"updated_at":12.5,"automation_control_event_cursor":1,"timestamp":12.5,"first_reply_created_at":12.5,"unread_count":5,"last_non_activity_message":{"client_message_id":"sample client message id","client_message_actor":"User:7","outbound_dispatch":{"state":"queued","retryable":true},"id":1,"content":"Sample content text.","content_readiness":{"state":"waiting","quality":"pending","generation":1,"content_version":1},"account_id":1,"inbox_id":1,"logical_inbox_id":1,"echo_id":"sample echo id","conversation_id":1,"message_type":0,"created_at":1,"updated_at":1,"private":true,"status":"sent","source_id":"sample source id","content_type":"text","content_attributes":{"instagram_mention":{"media_id":"sample media id","comment_id":"sample comment id","mention_type":"comment","enrichment_status":"unresolved","replyable":true,"author_id":"sample author id","author_username":"sample author username","text":"sample text","media_type":"sample media type","media_product_type":"sample media product type","permalink":"https://example.com/resource","identity_scope":{"account_id":1,"inbox_id":1,"instagram_id":"sample instagram id"},"recovery":{"state":"scheduled","reason":"Sample reason.","attempts":1,"checked_at":"2026-01-15T10:30:00.000Z","next_retry_at":"2026-01-15T10:30:00.000Z","lease_until":"2026-01-15T10:30:00.000Z"}},"translations":{},"translation":{"original_content":"sample original content","original_html_content":"sample original html content","delivery":{"status":"translated","source_language":"pt","target_language":"en","provider":"google_translate","content_digest":"sample content digest","translated_at":"2026-01-15T10:30:00.000Z","error_code":"translation_failed","cause_code":"provider_not_configured","failed_at":"2026-01-15T10:30:00.000Z"},"views":{}},"external_error":"sample external error","contact_share":{"origin":"contact_request","transport":"cloud","status":"linked","reason":"identity_owned_by_another_contact","other_contact_ids":[1],"reconciliation_id":"sample reconciliation id"}},"sender_type":"Contact","sender_id":1,"external_source_ids":{},"additional_attributes":{},"processed_message_content":"sample processed message content","sentiment":{},"conversation":{},"attachment":{},"attachments":[{"id":1,"message_id":1,"file_type":"image","account_id":1,"extension":"sample extension","data_url":"https://example.com/resource","media_readiness_revision":"sample media readiness revision","playable_audio_url":"https://example.com/resource","playable_video_url":"https://example.com/resource","video_processing":true,"video_unavailable":true,"thumb_url":"https://example.com/resource","file_size":1,"width":1,"height":1,"coordinates_lat":12.5,"coordinates_long":12.5,"fallback_title":"sample fallback title","meta":{},"transcribed_text":"sample transcribed text","transcript_translations":{"pt-BR":"Você pode me ajudar?","es":"¿Puedes ayudarme?"},"transcript_translation_states":{}}],"sender":{}},"last_activity_at":12.5,"priority":"low","waiting_since":12.5,"sla_policy_id":1,"applied_sla":{},"sla_events":[{}]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"Conversation not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"422":{"description":"Assignment parameters were sent to the generic conversation endpoint","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error","message","assignment_url"],"properties":{"error":{"type":"string","enum":["assignment_parameters_not_supported"]},"message":{"type":"string"},"assignment_url":{"type":"string"}}},"example":{"error":"assignment_parameters_not_supported","message":"This endpoint does not update assignments. Use the atomic assignment endpoint.","assignment_url":"/api/v1/accounts/1/conversations/99/assignment"}}}}}},"put":{"tags":["Conversations"],"operationId":"update-conversation-put","summary":"Update Conversation","description":"Updates the same bounded conversation attributes as PATCH. PUT is retained as a compatibility alias by the Rails route and does not replace unspecified conversation fields.","security":[{"userApiKey":[]},{"agentBotApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"priority":{"type":"string","enum":["urgent","high","medium","low","none"],"description":"The priority of the conversation.","example":"high"}}},"example":{"priority":"high"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/conversation"},"example":{"id":1,"messages":[{"client_message_id":"sample client message id","client_message_actor":"User:7","outbound_dispatch":{"state":"queued","retryable":true},"id":1,"content":"Sample content text.","content_readiness":{"state":"waiting","quality":"pending","generation":1,"content_version":1},"account_id":1,"inbox_id":1,"logical_inbox_id":1,"echo_id":"sample echo id","conversation_id":1,"message_type":0,"created_at":1,"updated_at":1,"private":true,"status":"sent","source_id":"sample source id","content_type":"text","content_attributes":{"instagram_mention":{"media_id":"sample media id","comment_id":"sample comment id","mention_type":"comment","enrichment_status":"unresolved","replyable":true,"author_id":"sample author id","author_username":"sample author username","text":"sample text","media_type":"sample media type","media_product_type":"sample media product type","permalink":"https://example.com/resource","identity_scope":{"account_id":1,"inbox_id":1,"instagram_id":"sample instagram id"},"recovery":{"state":"scheduled","reason":"Sample reason.","attempts":1,"checked_at":"2026-01-15T10:30:00.000Z","next_retry_at":"2026-01-15T10:30:00.000Z","lease_until":"2026-01-15T10:30:00.000Z"}},"translations":{},"translation":{"original_content":"sample original content","original_html_content":"sample original html content","delivery":{"status":"translated","source_language":"pt","target_language":"en","provider":"google_translate","content_digest":"sample content digest","translated_at":"2026-01-15T10:30:00.000Z","error_code":"translation_failed","cause_code":"provider_not_configured","failed_at":"2026-01-15T10:30:00.000Z"},"views":{}},"external_error":"sample external error","contact_share":{"origin":"contact_request","transport":"cloud","status":"linked","reason":"identity_owned_by_another_contact","other_contact_ids":[1],"reconciliation_id":"sample reconciliation id"}},"sender_type":"Contact","sender_id":1,"external_source_ids":{},"additional_attributes":{},"processed_message_content":"sample processed message content","sentiment":{},"conversation":{},"attachment":{},"attachments":[{"id":1,"message_id":1,"file_type":"image","account_id":1,"extension":"sample extension","data_url":"https://example.com/resource","media_readiness_revision":"sample media readiness revision","playable_audio_url":"https://example.com/resource","playable_video_url":"https://example.com/resource","video_processing":true,"video_unavailable":true,"thumb_url":"https://example.com/resource","file_size":1,"width":1,"height":1,"coordinates_lat":12.5,"coordinates_long":12.5,"fallback_title":"sample fallback title","meta":{},"transcribed_text":"sample transcribed text","transcript_translations":{"pt-BR":"Você pode me ajudar?","es":"¿Puedes ayudarme?"},"transcript_translation_states":{}}],"sender":{}}],"account_id":1,"uuid":"sample uuid","additional_attributes":{},"agent_last_seen_at":12.5,"assignee_last_seen_at":12.5,"can_reply":true,"contact_last_seen_at":12.5,"custom_attributes":{},"inbox_id":1,"labels":["sample label"],"muted":true,"snoozed_until":12.5,"status":"open","created_at":12.5,"updated_at":12.5,"automation_control_event_cursor":1,"timestamp":12.5,"first_reply_created_at":12.5,"unread_count":5,"last_non_activity_message":{"client_message_id":"sample client message id","client_message_actor":"User:7","outbound_dispatch":{"state":"queued","retryable":true},"id":1,"content":"Sample content text.","content_readiness":{"state":"waiting","quality":"pending","generation":1,"content_version":1},"account_id":1,"inbox_id":1,"logical_inbox_id":1,"echo_id":"sample echo id","conversation_id":1,"message_type":0,"created_at":1,"updated_at":1,"private":true,"status":"sent","source_id":"sample source id","content_type":"text","content_attributes":{"instagram_mention":{"media_id":"sample media id","comment_id":"sample comment id","mention_type":"comment","enrichment_status":"unresolved","replyable":true,"author_id":"sample author id","author_username":"sample author username","text":"sample text","media_type":"sample media type","media_product_type":"sample media product type","permalink":"https://example.com/resource","identity_scope":{"account_id":1,"inbox_id":1,"instagram_id":"sample instagram id"},"recovery":{"state":"scheduled","reason":"Sample reason.","attempts":1,"checked_at":"2026-01-15T10:30:00.000Z","next_retry_at":"2026-01-15T10:30:00.000Z","lease_until":"2026-01-15T10:30:00.000Z"}},"translations":{},"translation":{"original_content":"sample original content","original_html_content":"sample original html content","delivery":{"status":"translated","source_language":"pt","target_language":"en","provider":"google_translate","content_digest":"sample content digest","translated_at":"2026-01-15T10:30:00.000Z","error_code":"translation_failed","cause_code":"provider_not_configured","failed_at":"2026-01-15T10:30:00.000Z"},"views":{}},"external_error":"sample external error","contact_share":{"origin":"contact_request","transport":"cloud","status":"linked","reason":"identity_owned_by_another_contact","other_contact_ids":[1],"reconciliation_id":"sample reconciliation id"}},"sender_type":"Contact","sender_id":1,"external_source_ids":{},"additional_attributes":{},"processed_message_content":"sample processed message content","sentiment":{},"conversation":{},"attachment":{},"attachments":[{"id":1,"message_id":1,"file_type":"image","account_id":1,"extension":"sample extension","data_url":"https://example.com/resource","media_readiness_revision":"sample media readiness revision","playable_audio_url":"https://example.com/resource","playable_video_url":"https://example.com/resource","video_processing":true,"video_unavailable":true,"thumb_url":"https://example.com/resource","file_size":1,"width":1,"height":1,"coordinates_lat":12.5,"coordinates_long":12.5,"fallback_title":"sample fallback title","meta":{},"transcribed_text":"sample transcribed text","transcript_translations":{"pt-BR":"Você pode me ajudar?","es":"¿Puedes ayudarme?"},"transcript_translation_states":{}}],"sender":{}},"last_activity_at":12.5,"priority":"low","waiting_since":12.5,"sla_policy_id":1,"applied_sla":{},"sla_events":[{}]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"Conversation not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"delete":{"tags":["Conversations"],"operationId":"auto_delete_api_v1_accounts_account_id_conversations_id","summary":"Delete conversations","description":"Deletes the conversation identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}},"example":{"error":"sample error"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}}}},"/api/v1/accounts/{account_id}/conversations/{conversation_id}/toggle_status":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"$ref":"#/components/parameters/conversation_id"}],"post":{"tags":["Conversations"],"operationId":"toggle-status-of-a-conversation","summary":"Toggle Status","description":"Toggle the status of a conversation. Pass `status` to explicitly set the\nconversation state. Use `snoozed` along with `snoozed_until` to snooze a\nconversation until a specific time. If `snoozed_until` is omitted, the\nconversation is snoozed until the next reply from the contact. Regardless\nof the value provided, snoozed conversations always reopen on the next\nreply from the contact.","security":[{"userApiKey":[]},{"agentBotApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["open","resolved","pending","snoozed"],"description":"The status of the conversation","example":"open"},"snoozed_until":{"type":"number","description":"When status is `snoozed`, schedule the reopen time as a Unix timestamp in seconds. If not provided, the conversation is snoozed until the next customer reply. The conversation always reopens when the customer replies.","example":1757506877}}},"example":{"status":"open","snoozed_until":1757506877}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"meta":{"type":"object","additionalProperties":true,"description":"Conversation metadata (sender, assignee, channel, contact inbox, ...)."},"payload":{"type":"object","properties":{"success":{"type":"boolean"},"current_status":{"type":"string","enum":["open","resolved","pending","snoozed"]},"conversation_id":{"type":"number"}}}}},"example":{"meta":{},"payload":{"success":true,"current_status":"open","conversation_id":1}}}}},"404":{"description":"Conversation not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/conversations/{conversation_id}/toggle_priority":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"$ref":"#/components/parameters/conversation_id"}],"post":{"tags":["Conversations"],"operationId":"toggle-priority-of-a-conversation","summary":"Toggle Priority","description":"Sets the priority of the conversation, replacing whatever was set before. To CLEAR the priority, send the request with NO body — that is the only supported way, and it is what the model does: `toggle_priority` assigns `priority.presence`, so an absent value becomes nil. There is no sentinel string for \"no priority\"; sending one that is not a declared level raises and the request fails. The response carries NO body — re-read the conversation to observe the stored priority.","security":[{"userApiKey":[]},{"agentBotApiKey":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"description":"Omit the whole body to clear the priority. When present, `priority` must be one of the four levels the model declares.","properties":{"priority":{"type":"string","enum":["urgent","high","medium","low"],"description":"Priority level to store. The value set is exactly the model's enum; anything else is rejected by ActiveRecord before the record is saved.","example":"high"}}},"example":{"priority":"high"}}}},"responses":{"200":{"description":"Priority stored (or cleared, when the request carried no body). Empty body."},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"Conversation not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/conversations/{conversation_id}/toggle_typing_status":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"$ref":"#/components/parameters/conversation_id"}],"post":{"tags":["Conversations"],"operationId":"toggle-typing-status-of-a-conversation","summary":"Toggle Typing Status","description":"Broadcasts a live \"typing\" (or \"recording\") indicator for the conversation on behalf of the caller, so the other side sees activity while a reply is being composed. It is a realtime signal only — nothing is stored on the conversation and no message is created — so the response carries NO body. A value other than `on` or `off` is accepted and broadcasts nothing.","security":[{"userApiKey":[]},{"agentBotApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["typing_status"],"properties":{"typing_status":{"type":"string","enum":["on","off"],"description":"Whether to start or stop the indicator.","example":"on"},"is_private":{"type":"boolean","description":"Whether the composition is a private note. Private typing is only surfaced to the other agents on the conversation, never to the contact.","example":false},"is_recording":{"type":"boolean","description":"Whether the caller is recording audio rather than typing, so the indicator reads as recording. Defaults to false.","example":false}}},"example":{"typing_status":"on","is_private":false,"is_recording":false}}}},"responses":{"200":{"description":"Indicator broadcast to the conversation subscribers. Empty body."},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"Conversation not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/conversations/{conversation_id}/custom_attributes":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"$ref":"#/components/parameters/conversation_id"}],"post":{"tags":["Conversations"],"operationId":"update-custom-attributes-of-a-conversation","summary":"Update Custom Attributes","description":"Writes the conversation's custom attribute VALUES. By DEFAULT the whole set is REPLACED: the dashboard deletes an attribute by re-sending the set without that key, so replacing is the behavior the UI depends on. Pass merge=true to write ONLY the keys you send and leave every other key untouched — the right choice for any integration that owns just a few keys, since a replace from such a client silently destroys attributes written by other systems. The write runs under a row lock, so two concurrent merges cannot overwrite each other.","security":[{"userApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["custom_attributes"],"properties":{"custom_attributes":{"type":"object","description":"The custom attributes to be set for the conversation","example":{"order_id":"12345","previous_conversation":"67890"},"additionalProperties":true},"merge":{"type":"boolean","default":false,"description":"When true, only the keys sent in `custom_attributes` are written and every other key is kept intact. Absent or false replaces the whole set (the dashboard's delete-by-omission behavior). Use the destroy_custom_attributes endpoint to remove keys explicitly.","example":true}}},"example":{"custom_attributes":{"order_id":"12345","previous_conversation":"67890"},"merge":true}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"custom_attributes":{"type":"object","description":"The custom attributes of the conversation","additionalProperties":true}}},"example":{"custom_attributes":{}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"Conversation not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/conversations/{conversation_id}/destroy_custom_attributes":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"$ref":"#/components/parameters/conversation_id"}],"post":{"tags":["Conversations"],"operationId":"destroy-custom-attributes-of-a-conversation","summary":"Destroy Custom Attributes","description":"Removes the given custom attribute keys from a conversation","security":[{"userApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["custom_attributes"],"properties":{"custom_attributes":{"type":"array","items":{"type":"string"},"description":"The list of custom attribute keys to remove from the conversation","example":["order_id","previous_conversation"]}}},"example":{"custom_attributes":["order_id","previous_conversation"]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"custom_attributes":{"type":"object","description":"The remaining custom attributes of the conversation","additionalProperties":true}}},"example":{"custom_attributes":{}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"Conversation not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/conversations/{conversation_id}/assignments":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"$ref":"#/components/parameters/conversation_id"}],"post":{"tags":["Conversation Assignments"],"operationId":"assign-a-conversation","summary":"Assign Conversation","description":"Legacy endpoint that assigns a conversation to an agent, to a team, or to an AI Robot (agent bot). Send `assignee_id` with `assignee_type: AgentBot` to choose which AI Robot answers this conversation; the Robot then replaces the inbox default for this conversation only, and a human assignee already on the conversation is cleared (a conversation is handled by a person or by a Robot, never by both). Send `assignee_id` alone to assign a human agent. `team_id` is used only when `assignee_id` is absent. If both `assignee_id` and `team_id` are present, the assignee keeps historical precedence, `team_id` is ignored and the response carries an HTTP `Warning` header. Use `PUT /assignment` to update both dimensions atomically.","security":[{"userApiKey":[]},{"agentBotApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"assignee_id":{"type":"number","description":"Id of the assignee. A user id by default; the id of an agent bot when `assignee_type` is `AgentBot`.","example":1},"assignee_type":{"type":"string","enum":["User","AgentBot"],"description":"What `assignee_id` refers to. Defaults to `User` when omitted, which preserves the historical behaviour of this endpoint.","example":"AgentBot"},"team_id":{"type":"number","description":"Id of the team. If the assignee_id is present, this param would be ignored","example":1}}},"example":{"assignee_id":1,"assignee_type":"AgentBot","team_id":1}}}},"responses":{"200":{"description":"Success","headers":{"Warning":{"description":"Present when team_id was ignored because an assignee was also supplied.","schema":{"type":"string"},"example":"299 ConversaLabs \"team_id ignored; use PUT /api/v1/accounts/1/conversations/99/assignment for atomic assignment\""}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/agent"},{"$ref":"#/components/schemas/agent_bot_slim"},{"$ref":"#/components/schemas/team"},{"type":"null"}]},"example":{"id":1,"name":"AI Robot","description":"Answers pre-sales questions","thumbnail":"https://example.com/robot.png","outgoing_url":"https://example.com/webhook","bot_type":"webhook"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"Conversation not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/conversations/{conversation_id}/assignment":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"$ref":"#/components/parameters/conversation_id"}],"put":{"tags":["Conversation Assignments"],"operationId":"replace-conversation-assignment-state","summary":"Atomically update conversation assignment","description":"Updates the assignee, AI Robot and team as one locked state transition. Omitted fields remain unchanged; `null` clears that dimension, and `team_id: 0` is also accepted as the legacy clear value. A human assignee selected together with a team must belong to that team. Repeating the resulting state is idempotent and does not create another timeline activity.","security":[{"userApiKey":[]},{"agentBotApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"anyOf":[{"required":["assignee_id"]},{"required":["team_id"]}],"properties":{"assignee_id":{"type":["integer","null"],"minimum":1,"description":"Human user or AI Robot id. Null clears either kind of responsible party.","example":42},"assignee_type":{"type":"string","enum":["User","AgentBot"],"description":"Type addressed by assignee_id. Defaults to User and cannot be sent without assignee_id.","default":"User","example":"User"},"team_id":{"type":["integer","null"],"minimum":0,"description":"Team id. Null or zero clears the team; omission preserves the current team.","example":7}}},"example":{"assignee_id":42,"assignee_type":"User","team_id":7}}}},"responses":{"200":{"description":"Actual persisted assignment state","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["assignee","assignee_type","team"],"properties":{"assignee":{"oneOf":[{"$ref":"#/components/schemas/agent"},{"$ref":"#/components/schemas/agent_bot_slim"},{"type":"null"}]},"assignee_type":{"type":["string","null"],"enum":["User","AgentBot",null],"description":"Type of the conversation assignee — an automation bot or a human agent."},"team":{"oneOf":[{"$ref":"#/components/schemas/team"},{"type":"null"}]}}},"example":{"assignee":{"id":42,"name":"Ana Souza","account_id":1,"account_user_id":1,"availability_status":"online","auto_offline":true,"confirmed":true,"email":"agent@example.com","available_name":"sample available name","role":"agent","outbound_agent_name_header_policy":"inherit","thumbnail":"sample thumbnail","custom_role_id":1},"assignee_type":"User","team":{"id":7,"name":"Vendas","description":"A short description.","allow_auto_assign":true,"account_id":1,"is_member":true,"avatar_url":"https://app.example.com/rails/active_storage/representations/team-icon.png","thumbnail":"https://app.example.com/rails/active_storage/representations/team-icon.png"}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"Conversation not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"422":{"description":"Invalid or cross-account assignment state","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error","message","assignment_url"],"properties":{"error":{"type":"string","enum":["assignment_payload_required","invalid_assignee_type","assignee_not_found","team_not_found","assignee_not_in_team"]},"message":{"type":"string"},"assignment_url":{"type":"string"}}},"example":{"error":"assignee_not_in_team","message":"The selected agent does not belong to the selected team.","assignment_url":"/api/v1/accounts/1/conversations/99/assignment"}}}}}}},"/api/v1/accounts/{account_id}/conversations/{conversation_id}/labels":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"$ref":"#/components/parameters/conversation_id"}],"get":{"tags":["Conversations"],"operationId":"list-all-labels-of-a-conversation","summary":"List Labels","security":[{"userApiKey":[]}],"description":"Lists all the labels of a conversation","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/conversation_labels"},"example":{"payload":["sample payload"]}}}},"404":{"description":"Conversation not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"post":{"tags":["Conversations"],"operationId":"conversation-add-labels","summary":"Add Labels","security":[{"userApiKey":[]}],"description":"Add labels to a conversation. Note that this API would overwrite the existing list of labels associated to the conversation.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["labels"],"properties":{"labels":{"type":"array","description":"Array of labels (comma-separated strings)","items":{"type":"string"},"example":["support","billing"]}}},"example":{"labels":["support","billing"]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/conversation_labels"},"example":{"payload":["sample payload"]}}}},"404":{"description":"Conversation not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/conversations/{conversation_id}/reporting_events":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"$ref":"#/components/parameters/conversation_id"}],"get":{"tags":["Conversations"],"operationId":"get-conversation-reporting-events","x-chatwoot-editions":["ee"],"summary":"Conversation Reporting Events","security":[{"userApiKey":[]}],"description":"Get reporting events for a specific conversation. This endpoint returns events such as first response time, resolution time, and other metrics for the conversation, sorted by creation time in ascending order.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/reporting_event"},"description":"Array of reporting events for the conversation"},"example":[{"id":1,"name":"Sample Name","value":149.9,"value_in_business_hours":12.5,"event_start_time":"2026-01-15T10:30:00.000Z","event_end_time":"2026-01-15T10:30:00.000Z","account_id":1,"conversation_id":1,"inbox_id":1,"user_id":1,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}]}}},"403":{"description":"Access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"Conversation not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/branded_email_layout":{"get":{"tags":["Inboxes"],"operationId":"getAccountBrandedEmailLayout","summary":"Get account branded email layout","security":[{"userApiKey":[]}],"description":"Read the saved base email layout and effective inheritance without changing templates. Administrators may select an authorized email inbox with inbox_id. An absent override inherits account, installation, then built-in layout.","parameters":[{"$ref":"#/components/parameters/account_id"},{"in":"query","name":"inbox_id","required":false,"schema":{"type":"integer","minimum":1},"description":"Optional email inbox owned by this account.","example":7}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/branded_email_layout"},"example":{"branded_email_layout":"\u003chtml\u003e\u003cbody\u003e{{ content_for_layout }}\u003c/body\u003e\u003c/html\u003e","effective_layout":"\u003chtml\u003e\u003cbody\u003e{{ content_for_layout }}\u003c/body\u003e\u003c/html\u003e","inherited_layout":"\u003chtml\u003e\u003cbody\u003e{{ content_for_layout }}\u003c/body\u003e\u003c/html\u003e","effective_source":"account","inherited_source":"installation","locale":"en"}}}},"422":{"description":"The selected inbox scope is malformed or not an email inbox.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}},"example":{"error":"Branded email layouts require an email inbox"}}}},"404":{"description":"The selected inbox was not found in this account."},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"patch":{"tags":["Inboxes"],"operationId":"updateAccountBrandedEmailLayout","summary":"Update account branded email layout","security":[{"userApiKey":[]}],"description":"Update or clear the base Liquid HTML layout for the account or optional authorized email inbox. Requires administrator and branded_email_templates. Blank, null or legacy string null clears only that scope override; omitting the body preserves it. Invalid Liquid, missing content_for_layout, structured text input or excessive length returns 422 without changing the saved layout.","parameters":[{"$ref":"#/components/parameters/account_id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/account_branded_email_layout_payload"},"example":{"inbox_id":7,"branded_email_layout":"\u003chtml\u003e\u003cbody\u003e{{ content_for_layout }}\u003c/body\u003e\u003c/html\u003e"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/branded_email_layout"},"example":{"branded_email_layout":"\u003chtml\u003e\u003cbody\u003e{{ content_for_layout }}\u003c/body\u003e\u003c/html\u003e","effective_layout":"\u003chtml\u003e\u003cbody\u003e{{ content_for_layout }}\u003c/body\u003e\u003c/html\u003e","inherited_layout":"\u003chtml\u003e\u003cbody\u003e{{ content_for_layout }}\u003c/body\u003e\u003c/html\u003e","effective_source":"account","inherited_source":"installation","locale":"en"}}}},"404":{"description":"The selected inbox was not found in this account."},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"422":{"description":"The feature is disabled or the Liquid layout is invalid; the saved layout is unchanged.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}},"example":{"error":"Branded email templates feature is not enabled"}}}}}},"put":{"tags":["Inboxes"],"operationId":"auto_put_api_v1_accounts_account_id_branded_email_layout","summary":"Update account branded email layout","security":[{"userApiKey":[]}],"description":"Update or clear the base Liquid HTML layout for the account or optional authorized email inbox. Requires administrator and branded_email_templates. Blank, null or legacy string null clears only that scope override; omitting the body preserves it. Invalid Liquid, missing content_for_layout, structured text input or excessive length returns 422 without changing the saved layout.","parameters":[{"$ref":"#/components/parameters/account_id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/account_branded_email_layout_payload"},"example":{"inbox_id":7,"branded_email_layout":"\u003chtml\u003e\u003cbody\u003e{{ content_for_layout }}\u003c/body\u003e\u003c/html\u003e"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/branded_email_layout"},"example":{"branded_email_layout":"\u003chtml\u003e\u003cbody\u003e{{ content_for_layout }}\u003c/body\u003e\u003c/html\u003e","effective_layout":"\u003chtml\u003e\u003cbody\u003e{{ content_for_layout }}\u003c/body\u003e\u003c/html\u003e","inherited_layout":"\u003chtml\u003e\u003cbody\u003e{{ content_for_layout }}\u003c/body\u003e\u003c/html\u003e","effective_source":"account","inherited_source":"installation","locale":"en"}}}},"404":{"description":"The selected inbox was not found in this account."},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"422":{"description":"The feature is disabled or the Liquid layout is invalid; the saved layout is unchanged.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}},"example":{"error":"Branded email templates feature is not enabled"}}}}}}},"/api/v1/accounts/{account_id}/inboxes":{"get":{"tags":["Inboxes"],"operationId":"listAllInboxes","summary":"List all inboxes","description":"List inboxes available to the current principal. Team-scoped native roles receive minimal member-inbox projections with navigation_only true. These projections contain no credentials or configuration and do not expand conversation or inbox-administration permissions.","security":[{"userApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/account_id"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","description":"Array of inboxes","items":{"$ref":"#/components/schemas/inbox"}}}},"example":{"payload":[{"navigation_only":true,"id":1,"name":"Sample Name","website_url":"https://example.com/resource","channel_type":"Channel::Api","avatar_url":"https://example.com/resource","widget_color":"#1F93FF","website_token":"sample-token","enable_auto_assignment":true,"web_widget_script":"sample web widget script","welcome_title":"sample welcome title","welcome_tagline":"sample welcome tagline","greeting_enabled":true,"greeting_message":"sample greeting message","channel_id":1,"working_hours_enabled":true,"enable_email_collect":true,"csat_survey_enabled":true,"auto_assignment_config":{},"out_of_office_message":"sample out of office message","working_hours":[{"day_of_week":12.5,"closed_all_day":true,"open_hour":12.5,"open_minutes":12.5,"close_hour":12.5,"close_minutes":12.5,"open_all_day":true}],"timezone":"America/Sao_Paulo","callback_webhook_url":"https://example.com/resource","allow_messages_after_resolved":true,"lock_to_single_conversation":true,"sender_name_type":"friendly","auto_resolve_config":{"mode":"custom","after":30,"message":"We are closing this conversation due to inactivity.","label":"auto-resolved","allow_waiting":false},"outbound_agent_name_header_policy":"inherit","business_name":"sample business name","branded_email_layout":"agent@example.com","responder_policy":{"mode":"agent_bot","conflict":true},"hmac_mandatory":true,"selected_feature_flags":["sample selected feature flag"],"reply_time":"2026-01-15T10:30:00.000Z","messaging_service_sid":"sample messaging service sid","phone_number":"+5511999998888","bandwidth_callback_state":"active","bandwidth_api_migration_state":"oauth2_configured","medium":"sample medium","provider":"default","whatsapp_web_session_state":{"state":"connected","fresh":true,"observed_at":"2026-01-15T10:30:00.000Z","disconnected_since":null},"hybrid_pair":{"paired":true,"id":4,"role":"cloud","sibling_inbox_id":18,"canonical_phone":"+5521900000000","primary":"cloud","inbound_authority":"cloud","unified_inbox":true,"unified_state":{"state":"complete","scanned":42,"frozen":40,"reconciled_count":2,"completed_at":"2026-10-03T12:00:00.000Z","blocked_conversations":[]},"routing":{"outbound_default":"cloud","out_of_window":"web","fallback":true,"manual_override":true,"weighted":{"mode":"weighted","web_percent":30,"version":2}},"web_channel_id":12,"web_inbox_id":18,"calling_provider":"whatsapp_web","web_voice_enabled":true,"web_inbound_calls_enabled":true,"web_call_config_sync":{"state":"pending","checked_at":"2026-10-03T12:00:00.000Z"},"web_video_calls_enabled":false,"web_group_calls_enabled":false,"web_reauthorization_required":false,"web_session_state":{"state":"connected","fresh":true,"observed_at":"2026-10-03T12:00:00.000Z","disconnected_since":null},"web_allow_message_deletion":true}}]}}}},"404":{"description":"Inbox not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"403":{"description":"Access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"post":{"tags":["Inboxes"],"operationId":"inboxCreation","summary":"Create an inbox","description":"You can create more than one website inbox in each account","security":[{"userApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/account_id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/inbox_create_payload"},"examples":{"web_widget":{"summary":"Website inbox","value":{"name":"Support","greeting_enabled":true,"greeting_message":"Hello, how can I help you?","enable_email_collect":true,"enable_auto_assignment":true,"working_hours_enabled":true,"timezone":"America/New_York","allow_messages_after_resolved":true,"channel":{"type":"web_widget","website_url":"https://example.com","welcome_title":"Welcome to our support","welcome_tagline":"We are here to help you","widget_color":"#FF5733","reply_time":"in_a_few_minutes","pre_chat_form_enabled":false,"continuity_via_email":true,"hmac_mandatory":false,"selected_feature_flags":["attachments","emoji_picker","end_conversation"],"pre_chat_form_options":{"pre_chat_message":"Share your queries or comments here.","pre_chat_fields":[{"field_type":"standard","label":"Email Id","name":"emailAddress","type":"email","required":true,"enabled":true}]},"allowed_domains":"example.com"},"avatar":"sample avatar","csat_survey_enabled":true,"csat_config":{"display_type":"emoji","message":"Please rate your conversation","button_text":"Please rate us","language":"en","survey_rules":{"operator":"contains","values":["billing"]}},"out_of_office_message":"We are currently out of office. Please leave a message and we will get back to you.","lock_to_single_conversation":true,"portal_id":1,"sender_name_type":"friendly","business_name":"My Business"}},"api":{"summary":"API channel","value":{"name":"API Inbox","greeting_enabled":true,"greeting_message":"Hello, how can I help you?","enable_auto_assignment":true,"working_hours_enabled":true,"timezone":"America/New_York","channel":{"type":"api","webhook_url":"https://example.com/webhook","hmac_mandatory":false,"additional_attributes":{"source":"mobile_app"}},"avatar":"sample avatar","enable_email_collect":true,"csat_survey_enabled":true,"csat_config":{"display_type":"emoji","message":"Please rate your conversation","button_text":"Please rate us","language":"en","survey_rules":{"operator":"contains","values":["billing"]}},"out_of_office_message":"We are currently out of office. Please leave a message and we will get back to you.","allow_messages_after_resolved":true,"lock_to_single_conversation":true,"portal_id":1,"sender_name_type":"friendly","business_name":"My Business"}},"email":{"summary":"Email channel","value":{"name":"Email Inbox","greeting_enabled":true,"greeting_message":"Hello, how can I help you?","enable_auto_assignment":true,"working_hours_enabled":true,"timezone":"America/New_York","channel":{"type":"email","email":"support@example.com","imap_enabled":false,"smtp_enabled":false,"imap_login":"support@example.com","imap_password":"your-imap-password","imap_address":"imap.example.com","imap_port":993,"imap_enable_ssl":true,"imap_authentication":"plain","smtp_login":"support@example.com","smtp_password":"your-smtp-password","smtp_address":"smtp.example.com","smtp_port":587,"smtp_domain":"example.com","smtp_enable_starttls_auto":true,"smtp_enable_ssl_tls":false,"smtp_openssl_verify_mode":"none","smtp_authentication":"login","provider":"google","verified_for_sending":false},"avatar":"sample avatar","enable_email_collect":true,"csat_survey_enabled":true,"csat_config":{"display_type":"emoji","message":"Please rate your conversation","button_text":"Please rate us","language":"en","survey_rules":{"operator":"contains","values":["billing"]}},"out_of_office_message":"We are currently out of office. Please leave a message and we will get back to you.","allow_messages_after_resolved":true,"lock_to_single_conversation":true,"portal_id":1,"sender_name_type":"friendly","business_name":"My Business"}},"line":{"summary":"LINE channel","value":{"name":"LINE Inbox","greeting_enabled":true,"greeting_message":"Hello, how can I help you?","enable_auto_assignment":true,"working_hours_enabled":true,"timezone":"America/New_York","channel":{"type":"line","line_channel_id":"1234567890","line_channel_secret":"line-channel-secret","line_channel_token":"line-channel-token"},"avatar":"sample avatar","enable_email_collect":true,"csat_survey_enabled":true,"csat_config":{"display_type":"emoji","message":"Please rate your conversation","button_text":"Please rate us","language":"en","survey_rules":{"operator":"contains","values":["billing"]}},"out_of_office_message":"We are currently out of office. Please leave a message and we will get back to you.","allow_messages_after_resolved":true,"lock_to_single_conversation":true,"portal_id":1,"sender_name_type":"friendly","business_name":"My Business"}},"telegram":{"summary":"Telegram channel","value":{"name":"Telegram Inbox","greeting_enabled":true,"greeting_message":"Hello, how can I help you?","enable_auto_assignment":true,"working_hours_enabled":true,"timezone":"America/New_York","channel":{"type":"telegram","bot_token":"123456789:telegram-bot-token"},"avatar":"sample avatar","enable_email_collect":true,"csat_survey_enabled":true,"csat_config":{"display_type":"emoji","message":"Please rate your conversation","button_text":"Please rate us","language":"en","survey_rules":{"operator":"contains","values":["billing"]}},"out_of_office_message":"We are currently out of office. Please leave a message and we will get back to you.","allow_messages_after_resolved":true,"lock_to_single_conversation":true,"portal_id":1,"sender_name_type":"friendly","business_name":"My Business"}},"whatsapp":{"summary":"WhatsApp channel","value":{"name":"WhatsApp Inbox","greeting_enabled":true,"greeting_message":"Hello, how can I help you?","enable_auto_assignment":true,"working_hours_enabled":true,"timezone":"America/New_York","channel":{"type":"whatsapp","phone_number":"+15551234567","provider":"whatsapp_cloud","provider_config":{"api_key":"your-api-key","phone_number_id":"your-phone-number-id","business_account_id":"your-business-account-id"}},"avatar":"sample avatar","enable_email_collect":true,"csat_survey_enabled":true,"csat_config":{"display_type":"emoji","message":"Please rate your conversation","button_text":"Please rate us","language":"en","survey_rules":{"operator":"contains","values":["billing"]}},"out_of_office_message":"We are currently out of office. Please leave a message and we will get back to you.","allow_messages_after_resolved":true,"lock_to_single_conversation":true,"portal_id":1,"sender_name_type":"friendly","business_name":"My Business"}},"sms":{"summary":"SMS channel","value":{"name":"SMS Inbox","greeting_enabled":true,"greeting_message":"Hello, how can I help you?","enable_auto_assignment":true,"working_hours_enabled":true,"timezone":"America/New_York","channel":{"type":"sms","phone_number":"+15551234567","provider_config":{"account_id":"1234567","application_id":"e5a9e103-097e-4ec4-87a0-50109fb7b4b1","client_id":"bandwidth-client-123","client_secret":"replace-with-client-secret"}},"avatar":"sample avatar","enable_email_collect":true,"csat_survey_enabled":true,"csat_config":{"display_type":"emoji","message":"Please rate your conversation","button_text":"Please rate us","language":"en","survey_rules":{"operator":"contains","values":["billing"]}},"out_of_office_message":"We are currently out of office. Please leave a message and we will get back to you.","allow_messages_after_resolved":true,"lock_to_single_conversation":true,"portal_id":1,"sender_name_type":"friendly","business_name":"My Business"}}}}}},"responses":{"200":{"description":"Inbox created. For an SMS inbox, the server enables callbacks only after Active Record Encryption is configured and Bandwidth application reconciliation succeeds. Callback credentials are machine-to-machine only and never appear in an inbox response.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/inbox"},{"type":"object","properties":{"bandwidth_callback_state":{"type":"string","enum":["active","reconnect_required","reconciling","reconciliation_required","encryption_required"],"description":"Present for an SMS inbox; contains no credential material.","example":"active"},"bandwidth_api_migration_state":{"type":"string","enum":["oauth2_configured","oauth2_required","configuration_required"],"description":"Present for an SMS inbox; communicates OAuth2 migration posture without credentials or tokens.","example":"oauth2_configured"}}}]},"examples":{"sms_callback_enabled":{"summary":"SMS inbox with protected callback credentials","value":{"id":42,"name":"SMS Inbox","channel_type":"Channel::Sms","phone_number":"+15551234567","bandwidth_callback_state":"active","bandwidth_api_migration_state":"oauth2_configured","navigation_only":true,"website_url":"https://example.com/resource","avatar_url":"https://example.com/resource","widget_color":"#1F93FF","website_token":"sample-token","enable_auto_assignment":true,"web_widget_script":"sample web widget script","welcome_title":"sample welcome title","welcome_tagline":"sample welcome tagline","greeting_enabled":true,"greeting_message":"sample greeting message","channel_id":1,"working_hours_enabled":true,"enable_email_collect":true,"csat_survey_enabled":true,"auto_assignment_config":{},"out_of_office_message":"sample out of office message","working_hours":[{"day_of_week":12.5,"closed_all_day":true,"open_hour":12.5,"open_minutes":12.5,"close_hour":12.5,"close_minutes":12.5,"open_all_day":true}],"timezone":"America/Sao_Paulo","callback_webhook_url":"https://example.com/resource","allow_messages_after_resolved":true,"lock_to_single_conversation":true,"sender_name_type":"friendly","auto_resolve_config":{"mode":"custom","after":30,"message":"We are closing this conversation due to inactivity.","label":"auto-resolved","allow_waiting":false},"outbound_agent_name_header_policy":"inherit","business_name":"sample business name","branded_email_layout":"agent@example.com","responder_policy":{"mode":"agent_bot","conflict":true},"hmac_mandatory":true,"selected_feature_flags":["sample selected feature flag"],"reply_time":"2026-01-15T10:30:00.000Z","messaging_service_sid":"sample messaging service sid","medium":"sample medium","provider":"default","whatsapp_web_session_state":{"state":"connected","fresh":true,"observed_at":"2026-01-15T10:30:00.000Z","disconnected_since":null},"hybrid_pair":{"paired":true,"id":4,"role":"cloud","sibling_inbox_id":18,"canonical_phone":"+5521900000000","primary":"cloud","inbound_authority":"cloud","unified_inbox":true,"unified_state":{"state":"complete","scanned":42,"frozen":40,"reconciled_count":2,"completed_at":"2026-10-03T12:00:00.000Z","blocked_conversations":[]},"routing":{"outbound_default":"cloud","out_of_window":"web","fallback":true,"manual_override":true,"weighted":{"mode":"weighted","web_percent":30,"version":2}},"web_channel_id":12,"web_inbox_id":18,"calling_provider":"whatsapp_web","web_voice_enabled":true,"web_inbound_calls_enabled":true,"web_call_config_sync":{"state":"pending","checked_at":"2026-10-03T12:00:00.000Z"},"web_video_calls_enabled":false,"web_group_calls_enabled":false,"web_reauthorization_required":false,"web_session_state":{"state":"connected","fresh":true,"observed_at":"2026-10-03T12:00:00.000Z","disconnected_since":null},"web_allow_message_deletion":true}}}}}}},"202":{"description":"The structurally valid SMS inbox was created, but a provider callback reconciliation is pending. Retry the administrator-only reconnect endpoint; invalid SMS configuration always returns 422.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/inbox"},{"type":"object","required":["reconciliation_required","bandwidth_callback_state"],"properties":{"reconciliation_required":{"type":"boolean","enum":[true],"example":true},"bandwidth_callback_state":{"type":"string","enum":["encryption_required","reconciliation_required"],"example":"reconciliation_required"},"reconciliation_error":{"type":"string","example":"Bandwidth application update failed (503)"}}}]},"example":{"navigation_only":true,"id":1,"name":"Sample Name","website_url":"https://example.com/resource","channel_type":"Channel::Api","avatar_url":"https://example.com/resource","widget_color":"#1F93FF","website_token":"sample-token","enable_auto_assignment":true,"web_widget_script":"sample web widget script","welcome_title":"sample welcome title","welcome_tagline":"sample welcome tagline","greeting_enabled":true,"greeting_message":"sample greeting message","channel_id":1,"working_hours_enabled":true,"enable_email_collect":true,"csat_survey_enabled":true,"auto_assignment_config":{},"out_of_office_message":"sample out of office message","working_hours":[{"day_of_week":12.5,"closed_all_day":true,"open_hour":12.5,"open_minutes":12.5,"close_hour":12.5,"close_minutes":12.5,"open_all_day":true}],"timezone":"America/Sao_Paulo","callback_webhook_url":"https://example.com/resource","allow_messages_after_resolved":true,"lock_to_single_conversation":true,"sender_name_type":"friendly","auto_resolve_config":{"mode":"custom","after":30,"message":"We are closing this conversation due to inactivity.","label":"auto-resolved","allow_waiting":false},"outbound_agent_name_header_policy":"inherit","business_name":"sample business name","branded_email_layout":"agent@example.com","responder_policy":{"mode":"agent_bot","conflict":true},"hmac_mandatory":true,"selected_feature_flags":["sample selected feature flag"],"reply_time":"2026-01-15T10:30:00.000Z","messaging_service_sid":"sample messaging service sid","phone_number":"+5511999998888","bandwidth_callback_state":"reconciliation_required","bandwidth_api_migration_state":"oauth2_configured","medium":"sample medium","provider":"default","whatsapp_web_session_state":{"state":"connected","fresh":true,"observed_at":"2026-01-15T10:30:00.000Z","disconnected_since":null},"hybrid_pair":{"paired":true,"id":4,"role":"cloud","sibling_inbox_id":18,"canonical_phone":"+5521900000000","primary":"cloud","inbound_authority":"cloud","unified_inbox":true,"unified_state":{"state":"complete","scanned":42,"frozen":40,"reconciled_count":2,"completed_at":"2026-10-03T12:00:00.000Z","blocked_conversations":[]},"routing":{"outbound_default":"cloud","out_of_window":"web","fallback":true,"manual_override":true,"weighted":{"mode":"weighted","web_percent":30,"version":2}},"web_channel_id":12,"web_inbox_id":18,"calling_provider":"whatsapp_web","web_voice_enabled":true,"web_inbound_calls_enabled":true,"web_call_config_sync":{"state":"pending","checked_at":"2026-10-03T12:00:00.000Z"},"web_video_calls_enabled":false,"web_group_calls_enabled":false,"web_reauthorization_required":false,"web_session_state":{"state":"connected","fresh":true,"observed_at":"2026-10-03T12:00:00.000Z","disconnected_since":null},"web_allow_message_deletion":true},"reconciliation_required":true,"reconciliation_error":"Bandwidth application update failed (503)"}}}},"422":{"description":"Invalid inbox data, including incomplete, mixed, invalid-account-ID, or invalid-application-UUID Bandwidth configuration. No inbox is created for this response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"Inbox not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"403":{"description":"Access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/inboxes/{id}":{"get":{"tags":["Inboxes"],"operationId":"GetInbox","summary":"Get an inbox","security":[{"userApiKey":[]}],"description":"Get an inbox available in the current account","parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"id","in":"path","schema":{"type":"number"},"description":"ID of the inbox","required":true}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/inbox"},"example":{"navigation_only":true,"id":1,"name":"Sample Name","website_url":"https://example.com/resource","channel_type":"Channel::Api","avatar_url":"https://example.com/resource","widget_color":"#1F93FF","website_token":"sample-token","enable_auto_assignment":true,"web_widget_script":"sample web widget script","welcome_title":"sample welcome title","welcome_tagline":"sample welcome tagline","greeting_enabled":true,"greeting_message":"sample greeting message","channel_id":1,"working_hours_enabled":true,"enable_email_collect":true,"csat_survey_enabled":true,"auto_assignment_config":{},"out_of_office_message":"sample out of office message","working_hours":[{"day_of_week":12.5,"closed_all_day":true,"open_hour":12.5,"open_minutes":12.5,"close_hour":12.5,"close_minutes":12.5,"open_all_day":true}],"timezone":"America/Sao_Paulo","callback_webhook_url":"https://example.com/resource","allow_messages_after_resolved":true,"lock_to_single_conversation":true,"sender_name_type":"friendly","auto_resolve_config":{"mode":"custom","after":30,"message":"We are closing this conversation due to inactivity.","label":"auto-resolved","allow_waiting":false},"outbound_agent_name_header_policy":"inherit","business_name":"sample business name","branded_email_layout":"agent@example.com","responder_policy":{"mode":"agent_bot","conflict":true},"hmac_mandatory":true,"selected_feature_flags":["sample selected feature flag"],"reply_time":"2026-01-15T10:30:00.000Z","messaging_service_sid":"sample messaging service sid","phone_number":"+5511999998888","bandwidth_callback_state":"active","bandwidth_api_migration_state":"oauth2_configured","medium":"sample medium","provider":"default","whatsapp_web_session_state":{"state":"connected","fresh":true,"observed_at":"2026-01-15T10:30:00.000Z","disconnected_since":null},"hybrid_pair":{"paired":true,"id":4,"role":"cloud","sibling_inbox_id":18,"canonical_phone":"+5521900000000","primary":"cloud","inbound_authority":"cloud","unified_inbox":true,"unified_state":{"state":"complete","scanned":42,"frozen":40,"reconciled_count":2,"completed_at":"2026-10-03T12:00:00.000Z","blocked_conversations":[]},"routing":{"outbound_default":"cloud","out_of_window":"web","fallback":true,"manual_override":true,"weighted":{"mode":"weighted","web_percent":30,"version":2}},"web_channel_id":12,"web_inbox_id":18,"calling_provider":"whatsapp_web","web_voice_enabled":true,"web_inbound_calls_enabled":true,"web_call_config_sync":{"state":"pending","checked_at":"2026-10-03T12:00:00.000Z"},"web_video_calls_enabled":false,"web_group_calls_enabled":false,"web_reauthorization_required":false,"web_session_state":{"state":"connected","fresh":true,"observed_at":"2026-10-03T12:00:00.000Z","disconnected_since":null},"web_allow_message_deletion":true}}}}},"404":{"description":"Inbox not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"403":{"description":"Access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"patch":{"tags":["Inboxes"],"operationId":"updateInbox","summary":"Update Inbox","security":[{"userApiKey":[]}],"description":"Update an existing inbox","parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"id","in":"path","schema":{"type":"number"},"description":"ID of the inbox","required":true}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/inbox_update_payload"},"examples":{"web_widget":{"summary":"Website inbox settings","value":{"name":"Support","greeting_enabled":true,"greeting_message":"Hello, how can I help you?","enable_email_collect":true,"enable_auto_assignment":true,"working_hours_enabled":true,"timezone":"America/New_York","allow_messages_after_resolved":true,"channel":{"website_url":"https://example.com","welcome_title":"Welcome to our support","welcome_tagline":"We are here to help you","widget_color":"#FF5733","reply_time":"in_a_few_minutes","pre_chat_form_enabled":false,"continuity_via_email":true,"hmac_mandatory":false,"selected_feature_flags":["attachments","emoji_picker","end_conversation"],"pre_chat_form_options":{"pre_chat_message":"Share your queries or comments here.","pre_chat_fields":[{"field_type":"standard","label":"Email Id","name":"emailAddress","type":"email","required":true,"enabled":true}]},"allowed_domains":"example.com"},"avatar":"sample avatar","csat_survey_enabled":true,"csat_config":{"display_type":"emoji","message":"Please rate your conversation","button_text":"Please rate us","language":"en","survey_rules":{"operator":"contains","values":["billing"]}},"out_of_office_message":"We are currently out of office. Please leave a message and we will get back to you.","lock_to_single_conversation":true,"portal_id":1,"sender_name_type":"friendly","auto_resolve_config":{"mode":"custom","after":30,"message":"We are closing this conversation due to inactivity.","label":"auto-resolved","allow_waiting":false},"outbound_agent_name_header_policy":"inherit","business_name":"My Business","branded_email_layout":"\u003chtml\u003e\u003cbody\u003e{{ content_for_layout }}\u003c/body\u003e\u003c/html\u003e"}},"api":{"summary":"API channel settings","value":{"name":"API Inbox","greeting_enabled":true,"greeting_message":"Hello, how can I help you?","enable_auto_assignment":true,"working_hours_enabled":true,"timezone":"America/New_York","channel":{"webhook_url":"https://example.com/webhook","hmac_mandatory":false,"additional_attributes":{"source":"mobile_app"}},"avatar":"sample avatar","enable_email_collect":true,"csat_survey_enabled":true,"csat_config":{"display_type":"emoji","message":"Please rate your conversation","button_text":"Please rate us","language":"en","survey_rules":{"operator":"contains","values":["billing"]}},"out_of_office_message":"We are currently out of office. Please leave a message and we will get back to you.","allow_messages_after_resolved":true,"lock_to_single_conversation":true,"portal_id":1,"sender_name_type":"friendly","auto_resolve_config":{"mode":"custom","after":30,"message":"We are closing this conversation due to inactivity.","label":"auto-resolved","allow_waiting":false},"outbound_agent_name_header_policy":"inherit","business_name":"My Business","branded_email_layout":"\u003chtml\u003e\u003cbody\u003e{{ content_for_layout }}\u003c/body\u003e\u003c/html\u003e"}},"email":{"summary":"Email channel settings","value":{"name":"Email Inbox","greeting_enabled":true,"greeting_message":"Hello, how can I help you?","enable_auto_assignment":true,"working_hours_enabled":true,"timezone":"America/New_York","channel":{"email":"support@example.com","imap_enabled":false,"smtp_enabled":false,"imap_login":"support@example.com","imap_password":"your-imap-password","imap_address":"imap.example.com","imap_port":993,"imap_enable_ssl":true,"imap_authentication":"plain","smtp_login":"support@example.com","smtp_password":"your-smtp-password","smtp_address":"smtp.example.com","smtp_port":587,"smtp_domain":"example.com","smtp_enable_starttls_auto":true,"smtp_enable_ssl_tls":false,"smtp_openssl_verify_mode":"none","smtp_authentication":"login","provider":"google","verified_for_sending":false},"avatar":"sample avatar","enable_email_collect":true,"csat_survey_enabled":true,"csat_config":{"display_type":"emoji","message":"Please rate your conversation","button_text":"Please rate us","language":"en","survey_rules":{"operator":"contains","values":["billing"]}},"out_of_office_message":"We are currently out of office. Please leave a message and we will get back to you.","allow_messages_after_resolved":true,"lock_to_single_conversation":true,"portal_id":1,"sender_name_type":"friendly","auto_resolve_config":{"mode":"custom","after":30,"message":"We are closing this conversation due to inactivity.","label":"auto-resolved","allow_waiting":false},"outbound_agent_name_header_policy":"inherit","business_name":"My Business","branded_email_layout":"\u003chtml\u003e\u003cbody\u003e{{ content_for_layout }}\u003c/body\u003e\u003c/html\u003e"}},"line":{"summary":"LINE channel settings","value":{"name":"LINE Inbox","greeting_enabled":true,"greeting_message":"Hello, how can I help you?","enable_auto_assignment":true,"working_hours_enabled":true,"timezone":"America/New_York","channel":{"line_channel_id":"1234567890","line_channel_secret":"line-channel-secret","line_channel_token":"line-channel-token"},"avatar":"sample avatar","enable_email_collect":true,"csat_survey_enabled":true,"csat_config":{"display_type":"emoji","message":"Please rate your conversation","button_text":"Please rate us","language":"en","survey_rules":{"operator":"contains","values":["billing"]}},"out_of_office_message":"We are currently out of office. Please leave a message and we will get back to you.","allow_messages_after_resolved":true,"lock_to_single_conversation":true,"portal_id":1,"sender_name_type":"friendly","auto_resolve_config":{"mode":"custom","after":30,"message":"We are closing this conversation due to inactivity.","label":"auto-resolved","allow_waiting":false},"outbound_agent_name_header_policy":"inherit","business_name":"My Business","branded_email_layout":"\u003chtml\u003e\u003cbody\u003e{{ content_for_layout }}\u003c/body\u003e\u003c/html\u003e"}},"telegram":{"summary":"Telegram channel settings","value":{"name":"Telegram Inbox","greeting_enabled":true,"greeting_message":"Hello, how can I help you?","enable_auto_assignment":true,"working_hours_enabled":true,"timezone":"America/New_York","channel":{"bot_token":"123456789:telegram-bot-token"},"avatar":"sample avatar","enable_email_collect":true,"csat_survey_enabled":true,"csat_config":{"display_type":"emoji","message":"Please rate your conversation","button_text":"Please rate us","language":"en","survey_rules":{"operator":"contains","values":["billing"]}},"out_of_office_message":"We are currently out of office. Please leave a message and we will get back to you.","allow_messages_after_resolved":true,"lock_to_single_conversation":true,"portal_id":1,"sender_name_type":"friendly","auto_resolve_config":{"mode":"custom","after":30,"message":"We are closing this conversation due to inactivity.","label":"auto-resolved","allow_waiting":false},"outbound_agent_name_header_policy":"inherit","business_name":"My Business","branded_email_layout":"\u003chtml\u003e\u003cbody\u003e{{ content_for_layout }}\u003c/body\u003e\u003c/html\u003e"}},"whatsapp":{"summary":"WhatsApp channel settings","value":{"name":"WhatsApp Inbox","greeting_enabled":true,"greeting_message":"Hello, how can I help you?","enable_auto_assignment":true,"working_hours_enabled":true,"timezone":"America/New_York","channel":{"phone_number":"+15551234567","provider":"whatsapp_cloud","provider_config":{"api_key":"your-api-key","phone_number_id":"your-phone-number-id","business_account_id":"your-business-account-id","app_secret":"your-meta-app-secret"}},"avatar":"sample avatar","enable_email_collect":true,"csat_survey_enabled":true,"csat_config":{"display_type":"emoji","message":"Please rate your conversation","button_text":"Please rate us","language":"en","survey_rules":{"operator":"contains","values":["billing"]}},"out_of_office_message":"We are currently out of office. Please leave a message and we will get back to you.","allow_messages_after_resolved":true,"lock_to_single_conversation":true,"portal_id":1,"sender_name_type":"friendly","auto_resolve_config":{"mode":"custom","after":30,"message":"We are closing this conversation due to inactivity.","label":"auto-resolved","allow_waiting":false},"outbound_agent_name_header_policy":"inherit","business_name":"My Business","branded_email_layout":"\u003chtml\u003e\u003cbody\u003e{{ content_for_layout }}\u003c/body\u003e\u003c/html\u003e"}},"sms":{"summary":"SMS channel settings","value":{"name":"SMS Inbox","greeting_enabled":true,"greeting_message":"Hello, how can I help you?","enable_auto_assignment":true,"working_hours_enabled":true,"timezone":"America/New_York","channel":{"phone_number":"+15551234567","provider_config":{"account_id":"1234567","application_id":"e5a9e103-097e-4ec4-87a0-50109fb7b4b1","client_id":"bandwidth-client-123","client_secret":"replace-with-client-secret","api_key":"your-api-key","phone_number_id":"your-phone-number-id","business_account_id":"your-business-account-id","app_secret":"your-meta-app-secret"},"provider":"whatsapp_cloud"},"avatar":"sample avatar","enable_email_collect":true,"csat_survey_enabled":true,"csat_config":{"display_type":"emoji","message":"Please rate your conversation","button_text":"Please rate us","language":"en","survey_rules":{"operator":"contains","values":["billing"]}},"out_of_office_message":"We are currently out of office. Please leave a message and we will get back to you.","allow_messages_after_resolved":true,"lock_to_single_conversation":true,"portal_id":1,"sender_name_type":"friendly","auto_resolve_config":{"mode":"custom","after":30,"message":"We are closing this conversation due to inactivity.","label":"auto-resolved","allow_waiting":false},"outbound_agent_name_header_policy":"inherit","business_name":"My Business","branded_email_layout":"\u003chtml\u003e\u003cbody\u003e{{ content_for_layout }}\u003c/body\u003e\u003c/html\u003e"}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/inbox"},"example":{"navigation_only":true,"id":1,"name":"Sample Name","website_url":"https://example.com/resource","channel_type":"Channel::Api","avatar_url":"https://example.com/resource","widget_color":"#1F93FF","website_token":"sample-token","enable_auto_assignment":true,"web_widget_script":"sample web widget script","welcome_title":"sample welcome title","welcome_tagline":"sample welcome tagline","greeting_enabled":true,"greeting_message":"sample greeting message","channel_id":1,"working_hours_enabled":true,"enable_email_collect":true,"csat_survey_enabled":true,"auto_assignment_config":{},"out_of_office_message":"sample out of office message","working_hours":[{"day_of_week":12.5,"closed_all_day":true,"open_hour":12.5,"open_minutes":12.5,"close_hour":12.5,"close_minutes":12.5,"open_all_day":true}],"timezone":"America/Sao_Paulo","callback_webhook_url":"https://example.com/resource","allow_messages_after_resolved":true,"lock_to_single_conversation":true,"sender_name_type":"friendly","auto_resolve_config":{"mode":"custom","after":30,"message":"We are closing this conversation due to inactivity.","label":"auto-resolved","allow_waiting":false},"outbound_agent_name_header_policy":"inherit","business_name":"sample business name","branded_email_layout":"agent@example.com","responder_policy":{"mode":"agent_bot","conflict":true},"hmac_mandatory":true,"selected_feature_flags":["sample selected feature flag"],"reply_time":"2026-01-15T10:30:00.000Z","messaging_service_sid":"sample messaging service sid","phone_number":"+5511999998888","bandwidth_callback_state":"active","bandwidth_api_migration_state":"oauth2_configured","medium":"sample medium","provider":"default","whatsapp_web_session_state":{"state":"connected","fresh":true,"observed_at":"2026-01-15T10:30:00.000Z","disconnected_since":null},"hybrid_pair":{"paired":true,"id":4,"role":"cloud","sibling_inbox_id":18,"canonical_phone":"+5521900000000","primary":"cloud","inbound_authority":"cloud","unified_inbox":true,"unified_state":{"state":"complete","scanned":42,"frozen":40,"reconciled_count":2,"completed_at":"2026-10-03T12:00:00.000Z","blocked_conversations":[]},"routing":{"outbound_default":"cloud","out_of_window":"web","fallback":true,"manual_override":true,"weighted":{"mode":"weighted","web_percent":30,"version":2}},"web_channel_id":12,"web_inbox_id":18,"calling_provider":"whatsapp_web","web_voice_enabled":true,"web_inbound_calls_enabled":true,"web_call_config_sync":{"state":"pending","checked_at":"2026-10-03T12:00:00.000Z"},"web_video_calls_enabled":false,"web_group_calls_enabled":false,"web_reauthorization_required":false,"web_session_state":{"state":"connected","fresh":true,"observed_at":"2026-10-03T12:00:00.000Z","disconnected_since":null},"web_allow_message_deletion":true}}}}},"202":{"description":"The update was saved, but a provider step is still pending. Two cases answer 202. An SMS inbox whose Bandwidth callback reconciliation is pending returns the inbox with the reconciliation fields. A WhatsApp Cloud inbox being transferred from embedded signup to manual credentials, whose new credentials were saved but whose webhook setup did not finish, returns the configuration-pending object; sending the same request again retries the pending step on the same inbox. Invalid provider configuration returns 422 and does not persist the update.","content":{"application/json":{"schema":{"anyOf":[{"allOf":[{"$ref":"#/components/schemas/inbox"},{"type":"object","required":["reconciliation_required","bandwidth_callback_state"],"properties":{"reconciliation_required":{"type":"boolean","enum":[true],"example":true},"bandwidth_callback_state":{"type":"string","enum":["encryption_required","reconciliation_required"],"example":"reconciliation_required"},"reconciliation_error":{"type":"string","example":"Bandwidth application update failed (503)"}}}]},{"type":"object","additionalProperties":false,"required":["success","state","stage","id","message"],"properties":{"success":{"type":"boolean","enum":[false],"example":false},"state":{"type":"string","enum":["configuration_pending"],"example":"configuration_pending"},"stage":{"type":"string","enum":["webhook","phone_registration"],"description":"Provider setup stage that still needs recovery.","example":"webhook"},"id":{"type":"integer","description":"ID of the inbox whose credentials were saved.","example":42},"message":{"type":"string","description":"Localized explanation of the pending step and how to retry it.","example":"Your credentials were saved, but finishing the WhatsApp transfer is still pending. Open this inbox settings and use Retry transfer in the manual migration banner."}}}]},"example":{"navigation_only":true,"id":1,"name":"Sample Name","website_url":"https://example.com/resource","channel_type":"Channel::Api","avatar_url":"https://example.com/resource","widget_color":"#1F93FF","website_token":"sample-token","enable_auto_assignment":true,"web_widget_script":"sample web widget script","welcome_title":"sample welcome title","welcome_tagline":"sample welcome tagline","greeting_enabled":true,"greeting_message":"sample greeting message","channel_id":1,"working_hours_enabled":true,"enable_email_collect":true,"csat_survey_enabled":true,"auto_assignment_config":{},"out_of_office_message":"sample out of office message","working_hours":[{"day_of_week":12.5,"closed_all_day":true,"open_hour":12.5,"open_minutes":12.5,"close_hour":12.5,"close_minutes":12.5,"open_all_day":true}],"timezone":"America/Sao_Paulo","callback_webhook_url":"https://example.com/resource","allow_messages_after_resolved":true,"lock_to_single_conversation":true,"sender_name_type":"friendly","auto_resolve_config":{"mode":"custom","after":30,"message":"We are closing this conversation due to inactivity.","label":"auto-resolved","allow_waiting":false},"outbound_agent_name_header_policy":"inherit","business_name":"sample business name","branded_email_layout":"agent@example.com","responder_policy":{"mode":"agent_bot","conflict":true},"hmac_mandatory":true,"selected_feature_flags":["sample selected feature flag"],"reply_time":"2026-01-15T10:30:00.000Z","messaging_service_sid":"sample messaging service sid","phone_number":"+5511999998888","bandwidth_callback_state":"reconciliation_required","bandwidth_api_migration_state":"oauth2_configured","medium":"sample medium","provider":"default","whatsapp_web_session_state":{"state":"connected","fresh":true,"observed_at":"2026-01-15T10:30:00.000Z","disconnected_since":null},"hybrid_pair":{"paired":true,"id":4,"role":"cloud","sibling_inbox_id":18,"canonical_phone":"+5521900000000","primary":"cloud","inbound_authority":"cloud","unified_inbox":true,"unified_state":{"state":"complete","scanned":42,"frozen":40,"reconciled_count":2,"completed_at":"2026-10-03T12:00:00.000Z","blocked_conversations":[]},"routing":{"outbound_default":"cloud","out_of_window":"web","fallback":true,"manual_override":true,"weighted":{"mode":"weighted","web_percent":30,"version":2}},"web_channel_id":12,"web_inbox_id":18,"calling_provider":"whatsapp_web","web_voice_enabled":true,"web_inbound_calls_enabled":true,"web_call_config_sync":{"state":"pending","checked_at":"2026-10-03T12:00:00.000Z"},"web_video_calls_enabled":false,"web_group_calls_enabled":false,"web_reauthorization_required":false,"web_session_state":{"state":"connected","fresh":true,"observed_at":"2026-10-03T12:00:00.000Z","disconnected_since":null},"web_allow_message_deletion":true},"reconciliation_required":true,"reconciliation_error":"Bandwidth application update failed (503)"}}}},"422":{"description":"The update was refused and nothing was changed. Three cases answer 422. Invalid inbox data, including incomplete, mixed, invalid-account-ID, or invalid-application-UUID Bandwidth configuration, returns the standard error; the inbox and channel update are rolled back. A WhatsApp Cloud transfer from embedded signup to manual credentials returns `manual_transfer_unavailable` when the inbox is not eligible, when a prerequisite in Meta is missing, or when the submitted credentials do not resolve to the number of this inbox; `message` says which. Any other WhatsApp Cloud update that would change which number the inbox is returns `phone_identity_mismatch` or `phone_identity_unverified`: a Cloud inbox keeps its number. The phone number ID or WhatsApp Business Account ID may change only when Meta resolves the new pair to the inbox's number; `phone_number` may change only when Meta resolves the inbox's own IDs to the number submitted; changing the number and the IDs together is always refused. A number written in another format is the same number.","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/bad_request_error"},{"type":"object","additionalProperties":false,"required":["error","message"],"properties":{"error":{"type":"string","enum":["manual_transfer_unavailable"],"example":"manual_transfer_unavailable"},"message":{"type":"string","description":"Localized reason for the refusal.","example":"The selected WhatsApp number does not match this inbox."}}},{"type":"object","additionalProperties":false,"required":["error","message"],"properties":{"error":{"type":"string","enum":["phone_identity_mismatch","phone_identity_unverified"],"description":"`phone_identity_mismatch` when the update would leave the inbox's number and its phone number ID pointing at different numbers, or changes both at once. `phone_identity_unverified` when Meta could not be asked which number the IDs are - wrong ID, WhatsApp Business Account or token, or a network failure - so the same request can be corrected and retried.","example":"phone_identity_mismatch"},"message":{"type":"string","description":"Localized reason for the refusal.","example":"The selected WhatsApp number does not match this inbox."}}}]},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"Inbox not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"403":{"description":"Access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"put":{"tags":["Inboxes"],"operationId":"auto_put_api_v1_accounts_account_id_inboxes_id","summary":"Update inboxes","description":"Updates the inbox identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"state":{"type":"string","example":"configuration_pending"},"stage":{"type":"string"},"id":{"type":"integer"},"message":{"type":"string"}}},"example":{"success":false,"state":"configuration_pending","stage":"sample stage","id":1,"message":"Sample message text."}}}},"202":{"description":"The inbox was saved but provider configuration still needs recovery.","content":{"application/json":{"schema":{"anyOf":[{"type":"object","required":["success","state","stage","id","message"],"properties":{"success":{"type":"boolean","enum":[false]},"state":{"type":"string","enum":["configuration_pending"]},"stage":{"type":"string","enum":["webhook","phone_registration"],"description":"Provider setup stage that still needs recovery."},"id":{"type":"integer"},"message":{"type":"string"}}},{"$ref":"#/components/schemas/inbox"}]},"example":{"success":false,"state":"configuration_pending","stage":"webhook","id":1,"message":"Sample message text."}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"422":{"description":"The submitted inbox or channel attributes are invalid and were not accepted.","content":{"application/json":{"schema":{"oneOf":[{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","example":"param is missing or the value is empty: inbox"}}},{"type":"object","additionalProperties":false,"required":["message","attributes"],"properties":{"message":{"type":"string","example":"Name cannot be blank"},"attributes":{"type":"array","items":{"type":"string","example":"name"},"example":["name"]}}},{"type":"object","additionalProperties":false,"required":["message"],"properties":{"message":{"type":"string","example":"The submitted channel configuration is invalid"}}},{"type":"object","additionalProperties":false,"required":["error","message"],"properties":{"error":{"type":"string","enum":["manual_transfer_unavailable"]},"message":{"type":"string"}}}]},"example":{"message":"Name cannot be blank","attributes":["name"]}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"avatar":{"type":"string"},"greeting_enabled":{"type":"boolean"},"greeting_message":{"type":"string"},"enable_email_collect":{"type":"string"},"csat_survey_enabled":{"type":"boolean"},"enable_auto_assignment":{"type":"string"},"working_hours_enabled":{"type":"boolean"},"out_of_office_message":{"type":"string"},"timezone":{"type":"string","description":"IANA timezone identifier (e.g. \"America/Sao_Paulo\", \"UTC\"). Rails timezone names are also accepted on input; an unrecognized value is ignored in favor of the next fallback.","example":"America/Sao_Paulo"},"allow_messages_after_resolved":{"type":"string"},"lock_to_single_conversation":{"type":"string"},"portal_id":{"type":"integer"},"sender_name_type":{"type":"string","enum":["friendly","professional"]},"business_name":{"type":"string"},"agent_bot_working_hours_mode":{"type":"string","enum":["always","inside_business_hours","outside_business_hours"]},"audio_transcription_enabled":{"type":"boolean"},"preserve_deleted_messages":{"type":"string"},"allow_message_deletion":{"type":"string"},"capture_view_once":{"type":"string"},"outbound_agent_name_header_policy":{"type":"string"},"csat_config":{"type":"object","additionalProperties":true,"description":"Free-form object."},"channel":{"type":"object","additionalProperties":true,"description":"Free-form object."},"branded_email_layout":{"type":"string"},"auto_resolve_config":{"type":["object","null"],"additionalProperties":false,"properties":{"mode":{"type":["string","null"],"enum":["inherit","custom","disabled",null],"description":"How this inbox inherits, overrides or disables the account inactivity rule."},"after":{"type":["integer","null"],"minimum":10,"maximum":1439856,"description":"Inactivity in minutes; required for custom mode."},"message":{"type":["string","null"],"maxLength":10000,"description":"Optional message; blank normalizes to null."},"label":{"type":["string","null"],"description":"An existing account label title, or null."},"allow_waiting":{"type":["boolean","null"],"description":"Whether waiting conversations are included."}},"if":{"required":["mode"],"properties":{"mode":{"const":"custom"}}},"then":{"required":["after"],"properties":{"after":{"type":"integer"}}},"description":"Optional per-inbox JSON rule. Null, absent mode and inherit reset to the account rule; custom requires a bounded integer after. Unknown keys and non-boolean waiting values are rejected.","example":{"mode":"custom","after":60,"message":null,"label":null,"allow_waiting":false}}}},"example":{"name":"Sample Name","avatar":"sample avatar","greeting_enabled":true,"greeting_message":"sample greeting message","enable_email_collect":"agent@example.com","csat_survey_enabled":true,"enable_auto_assignment":"sample enable auto assignment","working_hours_enabled":true,"out_of_office_message":"sample out of office message","timezone":"America/Sao_Paulo","allow_messages_after_resolved":"sample allow messages after resolved","lock_to_single_conversation":"sample lock to single conversation","portal_id":1,"sender_name_type":"friendly","business_name":"sample business name","agent_bot_working_hours_mode":"always","audio_transcription_enabled":true,"preserve_deleted_messages":"sample preserve deleted messages","allow_message_deletion":"sample allow message deletion","capture_view_once":"sample capture view once","outbound_agent_name_header_policy":"sample outbound agent name header policy","csat_config":{},"channel":{},"branded_email_layout":"agent@example.com","auto_resolve_config":{"mode":"custom","after":60,"message":null,"label":null,"allow_waiting":false}}}}}},"delete":{"tags":["Inboxes"],"operationId":"auto_delete_api_v1_accounts_account_id_inboxes_id","summary":"Delete inboxes","description":"Deletes the inbox identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Inbox deletion scheduled","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"Your inbox deletion request will be processed in some time."}}},"example":{"message":"Your inbox deletion request will be processed in some time."}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/inboxes/{id}/message_templates":{"get":{"tags":["Inboxes"],"operationId":"listWhatsappMessageTemplates","summary":"List WhatsApp message templates","security":[{"userApiKey":[]}],"description":"List the cached message templates available for a native or Twilio WhatsApp inbox","parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"id","in":"path","schema":{"type":"number"},"description":"ID of the native or Twilio WhatsApp inbox","required":true},{"name":"name","in":"query","schema":{"type":"string"},"description":"Exact template name to filter by","required":false}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","description":"Native or Twilio WhatsApp message templates available for the inbox","items":{"type":"object","description":"One template, in the provider's own vocabulary. WhatsApp Cloud and 360dialog entries are the provider's template object verbatim (commonly id, name, language, category, status and components, plus a reason written by template-status webhooks); Twilio-backed WhatsApp entries are keyed by content_sid and friendly_name and carry the raw Twilio types map. The three vocabularies share no required key, and inbound status webhooks patch extra keys into the cached entry, so the item is open on purpose rather than normalised into a union this API does not guarantee.","additionalProperties":true}},"meta":{"type":"object","properties":{"template_owner":{"type":"object","additionalProperties":false,"required":["key","inbox_id","projection_inbox_id","unified"],"description":"Account-scoped catalog owner used to de-duplicate Cloud/Web catalogs of the same WABA.","properties":{"key":{"type":"string","description":"Opaque account-scoped catalog owner key; contains no provider credentials or raw WABA identifier.","example":"84a1629b0cc4e0a9"},"inbox_id":{"type":"integer","description":"Physical catalog owner inbox identifier.","example":12},"projection_inbox_id":{"type":"integer","description":"Logical Cloud inbox only when unified routing is enabled; otherwise the requested inbox.","example":12},"unified":{"type":"boolean","example":false}}},"last_sync_attempt_at":{"type":["string","null"],"format":"date-time","description":"Time when template synchronization was last attempted"}}}}},"example":{"payload":[{}],"meta":{"template_owner":{"key":"84a1629b0cc4e0a9","inbox_id":12,"projection_inbox_id":12,"unified":false},"last_sync_attempt_at":"2026-01-15T10:30:00.000Z"}}}}},"404":{"description":"Inbox not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"403":{"description":"Access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"422":{"description":"The inbox is not a WhatsApp inbox","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/inboxes/{id}/agent_bot":{"get":{"tags":["Inboxes"],"operationId":"getInboxAgentBot","summary":"Show Inbox Agent Bot","description":"See if an agent bot is associated to the Inbox","security":[{"userApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"id","in":"path","schema":{"type":"number"},"description":"ID of the inbox","required":true}],"responses":{"200":{"description":"The agent bot associated with the inbox, wrapped under `agent_bot`. The wrapper is present and empty when the inbox has no bot associated — a 200 with `{\"agent_bot\": {}}`, not a 404.","content":{"application/json":{"schema":{"type":"object","properties":{"agent_bot":{"$ref":"#/components/schemas/agent_bot"}}},"example":{"agent_bot":{"id":1,"name":"Sample Name","description":"A short description.","thumbnail":"sample thumbnail","outgoing_url":"https://example.com/resource","bot_type":"webhook","bot_config":{"maestro_agent_id":77},"receive_incoming_when_assigned":true,"receive_incoming_when_assigned_configurable":true,"account_id":1,"access_token":"sample-token","system_bot":true}}}}},"404":{"description":"Inbox not found, Agent bot not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"403":{"description":"Access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/inboxes/{id}/set_agent_bot":{"post":{"tags":["Inboxes"],"operationId":"updateAgentBot","summary":"Add or remove agent bot","security":[{"userApiKey":[]}],"description":"To add an agent bot pass agent_bot id, to remove agent bot from an inbox pass null","parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"id","in":"path","schema":{"type":"number"},"description":"ID of the inbox","required":true}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["agent_bot"],"properties":{"agent_bot":{"type":"number","description":"Agent bot ID","example":1},"responder_mode":{"type":"string","enum":["agent_bot"],"description":"Required when Captain is already connected; explicitly selects AgentBot as the responder allowed to reply."}}},"example":{"agent_bot":1,"responder_mode":"agent_bot"}}}},"responses":{"200":{"description":"Success"},"404":{"description":"Inbox not found, Agent bot not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"403":{"description":"Access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"422":{"description":"An explicit responder choice is required or invalid","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error","message"],"properties":{"error":{"type":"string","enum":["explicit_choice_required","invalid_choice"]},"message":{"type":"string","description":"Localized explanation of the responder conflict."}}},"example":{"error":"explicit_choice_required","message":"Sample message text."}}}}}}},"/api/v1/accounts/{account_id}/inbox_members/{inbox_id}":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"$ref":"#/components/parameters/inbox_id"}],"get":{"tags":["Inboxes"],"operationId":"get-inbox-members","summary":"List Agents in Inbox","description":"Get Details of Agents in an Inbox","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","description":"Array of all active agents","items":{"$ref":"#/components/schemas/agent"}}}},"example":{"payload":[{"id":1,"account_id":1,"account_user_id":1,"availability_status":"online","auto_offline":true,"confirmed":true,"email":"agent@example.com","available_name":"sample available name","name":"Sample Name","role":"agent","outbound_agent_name_header_policy":"inherit","thumbnail":"sample thumbnail","custom_role_id":1}]}}}},"404":{"description":"Inbox not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"403":{"description":"Access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/inbox_members":{"parameters":[{"$ref":"#/components/parameters/account_id"}],"post":{"tags":["Inboxes"],"operationId":"add-new-agent-to-inbox","summary":"Add a New Agent","description":"Add a new Agent to Inbox","security":[{"userApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["inbox_id","user_ids"],"properties":{"inbox_id":{"type":"integer","description":"The ID of the inbox","example":1},"user_ids":{"type":"array","items":{"type":"integer"},"description":"IDs of users to be added to the inbox","example":[1]}}},"example":{"inbox_id":1,"user_ids":[1]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","description":"Array of all active agents","items":{"$ref":"#/components/schemas/agent"}}}},"example":{"payload":[{"id":1,"account_id":1,"account_user_id":1,"availability_status":"online","auto_offline":true,"confirmed":true,"email":"agent@example.com","available_name":"sample available name","name":"Sample Name","role":"agent","outbound_agent_name_header_policy":"inherit","thumbnail":"sample thumbnail","custom_role_id":1}]}}}},"404":{"description":"Inbox not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"403":{"description":"Access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"422":{"description":"User must exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"patch":{"tags":["Inboxes"],"operationId":"update-agents-in-inbox","summary":"Update Agents in Inbox","description":"All agents except the one passed in params will be removed","security":[{"userApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["inbox_id","user_ids"],"properties":{"inbox_id":{"type":"integer","description":"The ID of the inbox","example":1},"user_ids":{"type":"array","items":{"type":"integer"},"description":"IDs of users to be added to the inbox","example":[1]}}},"example":{"inbox_id":1,"user_ids":[1]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","description":"Array of all active agents","items":{"$ref":"#/components/schemas/agent"}}}},"example":{"payload":[{"id":1,"account_id":1,"account_user_id":1,"availability_status":"online","auto_offline":true,"confirmed":true,"email":"agent@example.com","available_name":"sample available name","name":"Sample Name","role":"agent","outbound_agent_name_header_policy":"inherit","thumbnail":"sample thumbnail","custom_role_id":1}]}}}},"404":{"description":"Inbox not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"403":{"description":"Access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"422":{"description":"User must exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"delete":{"tags":["Inboxes"],"operationId":"delete-agent-in-inbox","summary":"Remove an Agent from Inbox","description":"Remove an Agent from Inbox","security":[{"userApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["inbox_id","user_ids"],"properties":{"inbox_id":{"type":"string","description":"The ID of the inbox"},"user_ids":{"type":"array","items":{"type":"integer"},"description":"IDs of users to be deleted from the inbox"}}},"example":{"inbox_id":"sample inbox id","user_ids":[1]}}}},"responses":{"200":{"description":"Success"},"404":{"description":"Inbox not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"403":{"description":"Access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"422":{"description":"User must exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/labels":{"parameters":[{"$ref":"#/components/parameters/account_id"}],"get":{"tags":["Labels"],"operationId":"list-all-labels","summary":"List all labels","security":[{"userApiKey":[]}],"description":"List all labels available in the current account","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","description":"Array of labels","items":{"$ref":"#/components/schemas/label"}}}},"example":{"payload":[{"id":1,"title":"Sample title","description":"A short description.","color":"#1F93FF","show_on_sidebar":true}]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"post":{"tags":["Labels"],"operationId":"create-a-label","summary":"Create a label","security":[{"userApiKey":[]}],"description":"Create a label in the account","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/label_create_update_payload"},"example":{"title":"support","description":"Conversations that need support follow-up","color":"#1f93ff","show_on_sidebar":true}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/label"},"example":{"id":1,"title":"Sample title","description":"A short description.","color":"#1F93FF","show_on_sidebar":true}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/labels/{id}":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"id","in":"path","required":true,"schema":{"type":"number"},"description":"ID of the label"}],"get":{"tags":["Labels"],"operationId":"get-details-of-a-single-label","summary":"Get a label","security":[{"userApiKey":[]}],"description":"Get the details of a label in the account","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/label"},"example":{"id":1,"title":"Sample title","description":"A short description.","color":"#1F93FF","show_on_sidebar":true}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"The given label ID does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"patch":{"tags":["Labels"],"operationId":"update-a-label","summary":"Update a label","security":[{"userApiKey":[]}],"description":"Update a label's attributes","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/label_create_update_payload"},"example":{"title":"support","description":"Conversations that need support follow-up","color":"#1f93ff","show_on_sidebar":true}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/label"},"example":{"id":1,"title":"Sample title","description":"A short description.","color":"#1F93FF","show_on_sidebar":true}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"delete":{"tags":["Labels"],"operationId":"delete-a-label","summary":"Delete a label","security":[{"userApiKey":[]}],"description":"Delete a label from the account","responses":{"200":{"description":"Success"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"The label does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"put":{"tags":["Labels"],"operationId":"auto_put_api_v1_accounts_account_id_labels_id","summary":"Update labels","description":"Updates the label identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"title":{"type":"string"},"description":{"type":"string"},"color":{"type":"string"},"show_on_sidebar":{"type":"string"}}},"example":{"id":1,"title":"Sample title","description":"A short description.","color":"#1F93FF","show_on_sidebar":"sample show on sidebar"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"label":{"type":"object","properties":{"title":{"type":"string"},"description":{"type":"string"},"color":{"type":"string"},"show_on_sidebar":{"type":"string"}}}},"required":["label"]},"example":{"label":{"title":"Sample title","description":"A short description.","color":"#1F93FF","show_on_sidebar":"sample show on sidebar"}}}}}}},"/api/v1/accounts/{account_id}/conversations/{conversation_id}/messages":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"$ref":"#/components/parameters/conversation_id"}],"get":{"tags":["Messages"],"operationId":"list-all-messages","summary":"Get messages","security":[{"userApiKey":[]}],"description":"List all messages of a conversation","parameters":[{"name":"after","in":"query","schema":{"type":"integer"},"description":"Fetch messages after the message with this ID. Returns up to 100 messages in ascending order."},{"name":"before","in":"query","schema":{"type":"integer"},"description":"Fetch messages before the message with this ID. Returns up to 20 messages in ascending order."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"meta":{"type":"object","properties":{"labels":{"type":"array","items":{"type":"string"}},"additional_attributes":{"type":"object","additionalProperties":true,"description":"Channel- and source-specific metadata for this record (e.g. browser info, referer, social profile identifiers). The key set depends on the originating channel."},"contact":{"$ref":"#/components/schemas/contact"},"assignee":{"$ref":"#/components/schemas/agent"},"agent_last_seen_at":{"type":["string","null"],"format":"date-time"},"assignee_last_seen_at":{"type":["string","null"],"format":"date-time"}}},"payload":{"type":"array","description":"Array of messages","items":{"$ref":"#/components/schemas/message"}}}},"example":{"meta":{"labels":["sample label"],"additional_attributes":{},"contact":{"payload":[{"additional_attributes":{},"availability_status":"online","email":"agent@example.com","id":1,"name":"Sample Name","phone_number":"+5511999998888","blocked":true,"contact_type":"visitor","identifier":"sample-identifier","referred_by_affiliate_id":1,"referred_by_affiliate_name":"sample referred by affiliate name","legal_type":"individual","tax_id":"sample tax id","tax_id_type":"br_cpf","country":"BR","address":{"zip":"sample zip","street":"sample street","number":"sample number","complement":"sample complement","neighborhood":"sample neighborhood","city":"São Paulo","state":"active","country":"BR"},"billing_address":{"zip":"sample zip","street":"sample street","number":"sample number","complement":"sample complement","neighborhood":"sample neighborhood","city":"São Paulo","state":"active","country":"BR"},"thumbnail":"sample thumbnail","custom_attributes":{"attribute_key":"attribute_value","signed_up_at":"dd/mm/yyyy"},"last_activity_at":1,"created_at":1,"contact_inboxes":[{"source_id":"sample source id","inbox":{"id":1,"avatar_url":"https://example.com/resource","channel_id":1,"name":"Sample Name","channel_type":"Channel::Api","provider":"default"}}]}]},"assignee":{"id":1,"account_id":1,"account_user_id":1,"availability_status":"online","auto_offline":true,"confirmed":true,"email":"agent@example.com","available_name":"sample available name","name":"Sample Name","role":"agent","outbound_agent_name_header_policy":"inherit","thumbnail":"sample thumbnail","custom_role_id":1},"agent_last_seen_at":"2026-01-15T10:30:00.000Z","assignee_last_seen_at":"2026-01-15T10:30:00.000Z"},"payload":[{"client_message_id":"sample client message id","client_message_actor":"User:7","outbound_dispatch":{"state":"queued","retryable":true},"id":1,"content":"Sample content text.","content_readiness":{"state":"waiting","quality":"pending","generation":1,"content_version":1},"account_id":1,"inbox_id":1,"logical_inbox_id":1,"echo_id":"sample echo id","conversation_id":1,"message_type":0,"created_at":1,"updated_at":1,"private":true,"status":"sent","source_id":"sample source id","content_type":"text","content_attributes":{"instagram_mention":{"media_id":"sample media id","comment_id":"sample comment id","mention_type":"comment","enrichment_status":"unresolved","replyable":true,"author_id":"sample author id","author_username":"sample author username","text":"sample text","media_type":"sample media type","media_product_type":"sample media product type","permalink":"https://example.com/resource","identity_scope":{"account_id":1,"inbox_id":1,"instagram_id":"sample instagram id"},"recovery":{"state":"scheduled","reason":"Sample reason.","attempts":1,"checked_at":"2026-01-15T10:30:00.000Z","next_retry_at":"2026-01-15T10:30:00.000Z","lease_until":"2026-01-15T10:30:00.000Z"}},"translations":{},"translation":{"original_content":"sample original content","original_html_content":"sample original html content","delivery":{"status":"translated","source_language":"pt","target_language":"en","provider":"google_translate","content_digest":"sample content digest","translated_at":"2026-01-15T10:30:00.000Z","error_code":"translation_failed","cause_code":"provider_not_configured","failed_at":"2026-01-15T10:30:00.000Z"},"views":{}},"external_error":"sample external error","contact_share":{"origin":"contact_request","transport":"cloud","status":"linked","reason":"identity_owned_by_another_contact","other_contact_ids":[1],"reconciliation_id":"sample reconciliation id"}},"sender_type":"Contact","sender_id":1,"external_source_ids":{},"additional_attributes":{},"processed_message_content":"sample processed message content","sentiment":{},"conversation":{},"attachment":{},"attachments":[{"id":1,"message_id":1,"file_type":"image","account_id":1,"extension":"sample extension","data_url":"https://example.com/resource","media_readiness_revision":"sample media readiness revision","playable_audio_url":"https://example.com/resource","playable_video_url":"https://example.com/resource","video_processing":true,"video_unavailable":true,"thumb_url":"https://example.com/resource","file_size":1,"width":1,"height":1,"coordinates_lat":12.5,"coordinates_long":12.5,"fallback_title":"sample fallback title","meta":{},"transcribed_text":"sample transcribed text","transcript_translations":{"pt-BR":"Você pode me ajudar?","es":"¿Puedes ayudarme?"},"transcript_translation_states":{}}],"sender":{}}]}}}},"404":{"description":"Conversation not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"post":{"tags":["Messages"],"operationId":"create-a-new-message-in-a-conversation","summary":"Create New Message","description":"Create a new message in the conversation.\n\nSupply a new `client_message_id` for each deliberate send and preserve it when retrying\na lost response. The same author/account, identity and request content returns the persisted\nmessage. HTTP 409 rejects incompatible reuse; HTTP 410 means its message was deleted.\n`GET .../messages/by_client_id?client_message_id=...` retrieves a committed result without sending.\n\nUse `application/json` for text messages and `multipart/form-data` when the\nmessage includes file attachments.\n\n### Multipart attachment request\n\nSend files with the `attachments[]` form field. `curl -F` sets the\n`multipart/form-data` content type and boundary automatically.\n\n```bash\ncurl -X POST \"https://app.example.com/api/v1/accounts/{account_id}/conversations/{conversation_id}/messages\" \\\n  -H \"api_access_token: \u003cyour-api-token\u003e\" \\\n  -F \"content=Here is the screenshot\" \\\n  -F \"message_type=outgoing\" \\\n  -F \"private=false\" \\\n  -F \"attachments[]=@/path/to/screenshot.png\"\n```\n\n## WhatsApp Template Messages\n\nFor WhatsApp channels, you can send structured template messages using the `template_params` field. \nTemplates must be pre-approved in WhatsApp Business Manager.\n\nBy default, `content` is treated as the already-rendered transcript text for\ncompatibility with existing API and mobile clients. To submit the original\ntemplate body instead, set `template_params.content_mode` to `raw_template`;\nThe platform will substitute `processed_params.body` before saving the transcript.\n\n### Example Templates\n\n**Text with Image Header:**\n```json\n{\n  \"content\": \"Hi your order 121212 is confirmed. Please wait for further updates\",\n  \"template_params\": {\n    \"name\": \"order_confirmation\",\n    \"category\": \"MARKETING\",\n    \"language\": \"en\",\n    \"processed_params\": {\n      \"body\": {\n        \"1\": \"121212\"\n      },\n      \"header\": {\n        \"media_url\": \"https://picsum.photos/200/300\",\n        \"media_type\": \"image\"\n      }\n    }\n  }\n}\n```\n\n**Text with Copy Code Button:**\n```json\n{\n  \"content\": \"Special offer! Get 30% off your next purchase. Use the code below\",\n  \"template_params\": {\n    \"name\": \"discount_coupon\",\n    \"category\": \"MARKETING\",\n    \"language\": \"en\",\n    \"processed_params\": {\n      \"body\": {\n        \"discount_percentage\": \"30\"\n      },\n      \"buttons\": [{\n        \"type\": \"copy_code\",\n        \"parameter\": \"SAVE20\"\n      }]\n    }\n  }\n}\n```\n","security":[{"userApiKey":[]},{"agentBotApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/conversation_message_create_payload"},"example":{"client_message_id":"2ca48246-20d5-4c17-a5e3-2b5c80c20875","echo_id":"sample echo id","content":"Hello, how can I help you?","message_type":"outgoing","private":false,"content_type":"text","content_attributes":{},"campaign_id":1,"template_params":{"name":"purchase_receipt","category":"UTILITY","language":"en_US","content_mode":"rendered","processed_params":{"body":{"1":"Visa","2":"Nike","3":"Bill"},"header":{"media_url":"https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf","media_type":"document"},"buttons":[{"type":"url","parameter":"SSFSDFSD"}]}}}},"multipart/form-data":{"schema":{"type":"object","description":"Form data payload for creating a message with file attachments.","example":{"content":"Here is the screenshot","message_type":"outgoing","private":false,"attachments[]":["screenshot.png"]},"properties":{"client_message_id":{"type":"string","minLength":1,"maxLength":128,"pattern":"^[a-zA-Z0-9_.:-]+$","description":"Durable send identity; retain across multipart retries."},"echo_id":{"type":"string","description":"Transient optimistic UI correlation."},"content":{"type":"string","description":"The content of the message","example":"Here is the screenshot"},"message_type":{"type":"string","enum":["outgoing","incoming"],"description":"The type of the message","example":"outgoing"},"private":{"type":"boolean","description":"Flag to identify if it is a private note","example":false},"content_type":{"type":"string","enum":["text","input_email","cards","input_select","form","article"],"description":"Content type of the message","example":"text"},"content_attributes":{"type":"object","description":"Attributes based on the content type","example":{},"additionalProperties":true},"attachments[]":{"type":"array","description":"Files to attach to the message","items":{"type":"string","format":"binary"}}}},"encoding":{"attachments[]":{"style":"form","explode":true}},"examples":{"attachment_message":{"summary":"Message with an attachment","value":{"content":"Here is the screenshot","message_type":"outgoing","private":false,"attachments[]":["screenshot.png"]}}}}}},"responses":{"409":{"description":"client_message_id was already used for incompatible request content or destination.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"410":{"description":"The message originally created by this identity was deleted. It will not be recreated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"422":{"description":"Invalid identity, content, attachment or conversation state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"200":{"description":"Success","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/generic_id"},{"$ref":"#/components/schemas/message"}]},"example":{"id":1,"client_message_id":"sample client message id","client_message_actor":"User:7","outbound_dispatch":{"state":"queued","retryable":true},"content":"Sample content text.","content_readiness":{"state":"waiting","quality":"pending","generation":1,"content_version":1},"account_id":1,"inbox_id":1,"logical_inbox_id":1,"echo_id":"sample echo id","conversation_id":1,"message_type":0,"created_at":1,"updated_at":1,"private":true,"status":"sent","source_id":"sample source id","content_type":"text","content_attributes":{"instagram_mention":{"media_id":"sample media id","comment_id":"sample comment id","mention_type":"comment","enrichment_status":"unresolved","replyable":true,"author_id":"sample author id","author_username":"sample author username","text":"sample text","media_type":"sample media type","media_product_type":"sample media product type","permalink":"https://example.com/resource","identity_scope":{"account_id":1,"inbox_id":1,"instagram_id":"sample instagram id"},"recovery":{"state":"scheduled","reason":"Sample reason.","attempts":1,"checked_at":"2026-01-15T10:30:00.000Z","next_retry_at":"2026-01-15T10:30:00.000Z","lease_until":"2026-01-15T10:30:00.000Z"}},"translations":{},"translation":{"original_content":"sample original content","original_html_content":"sample original html content","delivery":{"status":"translated","source_language":"pt","target_language":"en","provider":"google_translate","content_digest":"sample content digest","translated_at":"2026-01-15T10:30:00.000Z","error_code":"translation_failed","cause_code":"provider_not_configured","failed_at":"2026-01-15T10:30:00.000Z"},"views":{}},"external_error":"sample external error","contact_share":{"origin":"contact_request","transport":"cloud","status":"linked","reason":"identity_owned_by_another_contact","other_contact_ids":[1],"reconciliation_id":"sample reconciliation id"}},"sender_type":"Contact","sender_id":1,"external_source_ids":{},"additional_attributes":{},"processed_message_content":"sample processed message content","sentiment":{},"conversation":{},"attachment":{},"attachments":[{"id":1,"message_id":1,"file_type":"image","account_id":1,"extension":"sample extension","data_url":"https://example.com/resource","media_readiness_revision":"sample media readiness revision","playable_audio_url":"https://example.com/resource","playable_video_url":"https://example.com/resource","video_processing":true,"video_unavailable":true,"thumb_url":"https://example.com/resource","file_size":1,"width":1,"height":1,"coordinates_lat":12.5,"coordinates_long":12.5,"fallback_title":"sample fallback title","meta":{},"transcribed_text":"sample transcribed text","transcript_translations":{"pt-BR":"Você pode me ajudar?","es":"¿Puedes ayudarme?"},"transcript_translation_states":{}}],"sender":{}}}}},"404":{"description":"Conversation not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"403":{"description":"Access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/conversations/{conversation_id}/messages/{message_id}":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"$ref":"#/components/parameters/conversation_id"},{"$ref":"#/components/parameters/message_id"}],"patch":{"tags":["Messages"],"operationId":"update-message-status","summary":"Update message status","security":[{"userApiKey":[]}],"description":"Updates the delivery status of a single message. Available only for messages in\nAPI channel inboxes, where your own system is responsible for delivering messages\nand reporting what happened. Use this to push `sent`, `delivered`, and `read`\nreceipts into the platform, for example, to mark an agent's message as read when the\nend user views it in your client, so the agent sees the read indicator on the\nmessage.\n\nA message already marked `read` cannot be moved back to `delivered`. When\nreporting a failure, include `external_error` with the reason, which is shown to\nthe agent along with the failed indicator.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["sent","delivered","read","failed"],"description":"The new status of the message"},"external_error":{"type":"string","description":"Error description, stored only when status is failed"}}},"example":{"status":"sent","external_error":"sample external error"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/generic_id"},{"$ref":"#/components/schemas/message"}]},"example":{"id":1,"client_message_id":"sample client message id","client_message_actor":"User:7","outbound_dispatch":{"state":"queued","retryable":true},"content":"Sample content text.","content_readiness":{"state":"waiting","quality":"pending","generation":1,"content_version":1},"account_id":1,"inbox_id":1,"logical_inbox_id":1,"echo_id":"sample echo id","conversation_id":1,"message_type":0,"created_at":1,"updated_at":1,"private":true,"status":"sent","source_id":"sample source id","content_type":"text","content_attributes":{"instagram_mention":{"media_id":"sample media id","comment_id":"sample comment id","mention_type":"comment","enrichment_status":"unresolved","replyable":true,"author_id":"sample author id","author_username":"sample author username","text":"sample text","media_type":"sample media type","media_product_type":"sample media product type","permalink":"https://example.com/resource","identity_scope":{"account_id":1,"inbox_id":1,"instagram_id":"sample instagram id"},"recovery":{"state":"scheduled","reason":"Sample reason.","attempts":1,"checked_at":"2026-01-15T10:30:00.000Z","next_retry_at":"2026-01-15T10:30:00.000Z","lease_until":"2026-01-15T10:30:00.000Z"}},"translations":{},"translation":{"original_content":"sample original content","original_html_content":"sample original html content","delivery":{"status":"translated","source_language":"pt","target_language":"en","provider":"google_translate","content_digest":"sample content digest","translated_at":"2026-01-15T10:30:00.000Z","error_code":"translation_failed","cause_code":"provider_not_configured","failed_at":"2026-01-15T10:30:00.000Z"},"views":{}},"external_error":"sample external error","contact_share":{"origin":"contact_request","transport":"cloud","status":"linked","reason":"identity_owned_by_another_contact","other_contact_ids":[1],"reconciliation_id":"sample reconciliation id"}},"sender_type":"Contact","sender_id":1,"external_source_ids":{},"additional_attributes":{},"processed_message_content":"sample processed message content","sentiment":{},"conversation":{},"attachment":{},"attachments":[{"id":1,"message_id":1,"file_type":"image","account_id":1,"extension":"sample extension","data_url":"https://example.com/resource","media_readiness_revision":"sample media readiness revision","playable_audio_url":"https://example.com/resource","playable_video_url":"https://example.com/resource","video_processing":true,"video_unavailable":true,"thumb_url":"https://example.com/resource","file_size":1,"width":1,"height":1,"coordinates_lat":12.5,"coordinates_long":12.5,"fallback_title":"sample fallback title","meta":{},"transcribed_text":"sample transcribed text","transcript_translations":{"pt-BR":"Você pode me ajudar?","es":"¿Puedes ayudarme?"},"transcript_translation_states":{}}],"sender":{}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"403":{"description":"The message does not belong to an API channel inbox","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"The message or conversation does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"delete":{"tags":["Messages"],"operationId":"delete-a-message","summary":"Delete a message","security":[{"userApiKey":[]}],"description":"Delete a message and it's attachments from the conversation.","responses":{"200":{"description":"Success"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"The message or conversation does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"put":{"tags":["Conversations"],"operationId":"auto_put_api_v1_accounts_account_id_conversations_conversation_id_messages_id","summary":"Update the delivery status of an API inbox message","description":"PUT and PATCH share the same delivery status operation for API channel inboxes. A read message cannot move back to delivered. The external error is stored only for a failed status. The response is the canonical serialized message.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The updated message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/message"},"example":{"client_message_id":"sample client message id","client_message_actor":"User:7","outbound_dispatch":{"state":"queued","retryable":true},"id":1,"content":"Sample content text.","content_readiness":{"state":"waiting","quality":"pending","generation":1,"content_version":1},"account_id":1,"inbox_id":1,"logical_inbox_id":1,"echo_id":"sample echo id","conversation_id":1,"message_type":0,"created_at":1,"updated_at":1,"private":true,"status":"sent","source_id":"sample source id","content_type":"text","content_attributes":{"instagram_mention":{"media_id":"sample media id","comment_id":"sample comment id","mention_type":"comment","enrichment_status":"unresolved","replyable":true,"author_id":"sample author id","author_username":"sample author username","text":"sample text","media_type":"sample media type","media_product_type":"sample media product type","permalink":"https://example.com/resource","identity_scope":{"account_id":1,"inbox_id":1,"instagram_id":"sample instagram id"},"recovery":{"state":"scheduled","reason":"Sample reason.","attempts":1,"checked_at":"2026-01-15T10:30:00.000Z","next_retry_at":"2026-01-15T10:30:00.000Z","lease_until":"2026-01-15T10:30:00.000Z"}},"translations":{},"translation":{"original_content":"sample original content","original_html_content":"sample original html content","delivery":{"status":"translated","source_language":"pt","target_language":"en","provider":"google_translate","content_digest":"sample content digest","translated_at":"2026-01-15T10:30:00.000Z","error_code":"translation_failed","cause_code":"provider_not_configured","failed_at":"2026-01-15T10:30:00.000Z"},"views":{}},"external_error":"sample external error","contact_share":{"origin":"contact_request","transport":"cloud","status":"linked","reason":"identity_owned_by_another_contact","other_contact_ids":[1],"reconciliation_id":"sample reconciliation id"}},"sender_type":"Contact","sender_id":1,"external_source_ids":{},"additional_attributes":{},"processed_message_content":"sample processed message content","sentiment":{},"conversation":{},"attachment":{},"attachments":[{"id":1,"message_id":1,"file_type":"image","account_id":1,"extension":"sample extension","data_url":"https://example.com/resource","media_readiness_revision":"sample media readiness revision","playable_audio_url":"https://example.com/resource","playable_video_url":"https://example.com/resource","video_processing":true,"video_unavailable":true,"thumb_url":"https://example.com/resource","file_size":1,"width":1,"height":1,"coordinates_lat":12.5,"coordinates_long":12.5,"fallback_title":"sample fallback title","meta":{},"transcribed_text":"sample transcribed text","transcript_translations":{"pt-BR":"Você pode me ajudar?","es":"¿Puedes ayudarme?"},"transcript_translation_states":{}}],"sender":{}}}}},"401":{"description":"Authentication required."},"404":{"description":"The message or conversation is unavailable in the account."},"403":{"description":"The message does not belong to an API channel inbox."}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["sent","delivered","read","failed"]},"external_error":{"type":"string"}}},"example":{"status":"sent","external_error":"sample external error"}}}}}},"/api/v1/accounts/{account_id}/integrations/apps":{"parameters":[{"$ref":"#/components/parameters/account_id"}],"get":{"tags":["Integrations"],"operationId":"get-details-of-all-integrations","summary":"List all the Integrations","security":[{"userApiKey":[]}],"description":"Get the details of all Integrations available for the account","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","description":"Array of Integration apps","items":{"$ref":"#/components/schemas/integrations_app"}}}},"example":{"payload":[{"id":"sample id","name":"Sample Name","description":"A short description.","hook_type":"account","enabled":true,"allow_multiple_hooks":true,"token_url":"https://example.com/resource","console_url":"https://example.com/resource","documentation_url":"https://example.com/resource","hooks":[{}]}]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"Url not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/integrations/hooks":{"post":{"tags":["Integrations"],"operationId":"create-an-integration-hook","summary":"Create an integration hook","description":"Create an integration hook","security":[{"userApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/account_id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/integrations_hook_create_payload"},"example":{"app_id":1,"inbox_id":1,"status":1,"settings":{}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/integrations_hook"},"example":{"id":"sample id","app_id":"sample app id","inbox_id":"sample inbox id","account_id":"sample account id","status":true,"hook_type":true,"settings":{}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/integrations/hooks/{hook_id}":{"patch":{"tags":["Integrations"],"operationId":"update-an-integrations-hook","summary":"Update an Integration Hook","description":"Update an Integration Hook","security":[{"userApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/account_id"},{"$ref":"#/components/parameters/hook_id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/integrations_hook_update_payload"},"example":{"status":1,"settings":{}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/integrations_hook"},"example":{"id":"sample id","app_id":"sample app id","inbox_id":"sample inbox id","account_id":"sample account id","status":true,"hook_type":true,"settings":{}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"delete":{"tags":["Integrations"],"operationId":"delete-an-integration-hook","summary":"Delete an Integration Hook","description":"Delete an Integration Hook","security":[{"userApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/account_id"},{"$ref":"#/components/parameters/hook_id"}],"responses":{"200":{"description":"Success"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"The hook does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"put":{"tags":["Integrations"],"operationId":"auto_put_api_v1_accounts_account_id_integrations_hooks_id","summary":"Update hooks","description":"Updates the hook identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"app_id":{"type":"integer"},"status":{"type":"boolean"},"inbox":{"type":["string","null"]},"logical_inbox_id":{"type":"integer"},"logical_inbox":{"type":["string","null"]},"account_id":{"type":"integer"},"hook_type":{"type":"string","enum":["account","inbox"]},"settings":{"type":"string"},"reference_id":{"type":"integer"}}},"example":{"id":1,"app_id":1,"status":true,"inbox":"sample inbox","logical_inbox_id":1,"logical_inbox":"sample logical inbox","account_id":1,"hook_type":"account","settings":"sample settings","reference_id":1}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"hook_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"hook":{"type":"object","properties":{"app_id":{"type":"integer"},"inbox_id":{"type":"integer"},"status":{"type":"string","enum":["disabled","enabled"]},"settings":{"type":"object","additionalProperties":true,"description":"Free-form object."}}}},"required":["hook"]},"example":{"hook":{"app_id":1,"inbox_id":1,"status":"disabled","settings":{}}}}}}}},"/api/v1/profile":{"get":{"tags":["Profile"],"operationId":"fetchProfile","summary":"Fetch user profile","description":"Get the user profile details","security":[{"userApiKey":[]}],"x-authentication":{"kind":"credential","scheme":"userApiKey","location":"header","name":"api_access_token","verification_boundary":"Api::V1::ProfilesController authentication filter","algorithm":"opaque"},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/user"},"example":{"id":1,"access_token":"sample-token","account_id":1,"available_name":"sample available name","avatar_url":"https://example.com/resource","confirmed":true,"display_name":"sample display name","message_signature":"sample message signature","email":"agent@example.com","hmac_identifier":"sample hmac identifier","inviter_id":1,"name":"Sample Name","provider":"email","pubsub_token":"sample-token","role":"agent","ui_settings":{"translation_language_by_account":{"1":"pt-BR"}},"uid":"sample uid","type":"sample type","custom_attributes":{},"accounts":[{"id":1,"name":"Sample Name","status":"active","active_at":"2026-01-15T10:30:00.000Z","role":"administrator","outbound_agent_name_header_policy":"inherit","permissions":["sample permission"],"availability":"online","availability_status":"online","auto_offline":true,"custom_role_id":1,"custom_role":{"id":1,"name":"Sample Name","description":"A short description.","permissions":["conversation_manage"]},"onboarding_step":"sample onboarding step","access_role_id":1,"access_role":{"id":1,"name":"Sample Name","field_permissions":{"contact":{},"organization":{}}},"api_and_webhooks":true}]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"put":{"tags":["Profile"],"operationId":"updateProfile","summary":"Update user profile","description":"Update the user profile details","security":[{"userApiKey":[]}],"x-authentication":{"kind":"credential","scheme":"userApiKey","location":"header","name":"api_access_token","verification_boundary":"Api::V1::ProfilesController authentication filter","algorithm":"opaque"},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["profile"],"properties":{"profile":{"type":"object","properties":{"name":{"type":"string"},"email":{"type":"string"},"display_name":{"type":"string"},"message_signature":{"type":"string"},"phone_number":{"type":"string"},"current_password":{"type":"string"},"password":{"type":"string"},"password_confirmation":{"type":"string"},"ui_settings":{"type":"object","additionalProperties":true,"properties":{"translation_language_by_account":{"type":"object","description":"Per-account BCP-47 viewer language preferences, keyed by numeric account id.","propertyNames":{"pattern":"^\\d+$"},"additionalProperties":{"type":"string","pattern":"^[A-Za-z]{2,3}(?:-[A-Za-z]{4})?(?:-(?:[A-Za-z]{2}|[0-9]{3}))?$"},"example":{"1":"pt-BR"}}},"description":"The user's persisted dashboard UI preferences."}}}}},"example":{"profile":{"name":"Sample Name","email":"agent@example.com","display_name":"sample display name","message_signature":"sample message signature","phone_number":"+5511999998888","current_password":"sample current password","password":"sample-password","password_confirmation":"sample password confirmation","ui_settings":{"translation_language_by_account":{"1":"pt-BR"}}}}},"multipart/form-data":{"schema":{"type":"object","required":["profile"],"properties":{"profile":{"type":"object","properties":{"name":{"type":"string"},"email":{"type":"string"},"display_name":{"type":"string"},"message_signature":{"type":"string"},"phone_number":{"type":"string"},"current_password":{"type":"string"},"password":{"type":"string"},"password_confirmation":{"type":"string"},"avatar":{"type":"string","format":"binary"},"ui_settings":{"type":"object","additionalProperties":true,"properties":{"translation_language_by_account":{"type":"object","description":"Per-account BCP-47 viewer language preferences, keyed by numeric account id.","propertyNames":{"pattern":"^\\d+$"},"additionalProperties":{"type":"string","pattern":"^[A-Za-z]{2,3}(?:-[A-Za-z]{4})?(?:-(?:[A-Za-z]{2}|[0-9]{3}))?$"},"example":{"1":"pt-BR"}}},"description":"The user's persisted dashboard UI preferences."}}}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/user"},"example":{"id":1,"access_token":"sample-token","account_id":1,"available_name":"sample available name","avatar_url":"https://example.com/resource","confirmed":true,"display_name":"sample display name","message_signature":"sample message signature","email":"agent@example.com","hmac_identifier":"sample hmac identifier","inviter_id":1,"name":"Sample Name","provider":"email","pubsub_token":"sample-token","role":"agent","ui_settings":{"translation_language_by_account":{"1":"pt-BR"}},"uid":"sample uid","type":"sample type","custom_attributes":{},"accounts":[{"id":1,"name":"Sample Name","status":"active","active_at":"2026-01-15T10:30:00.000Z","role":"administrator","outbound_agent_name_header_policy":"inherit","permissions":["sample permission"],"availability":"online","availability_status":"online","auto_offline":true,"custom_role_id":1,"custom_role":{"id":1,"name":"Sample Name","description":"A short description.","permissions":["conversation_manage"]},"onboarding_step":"sample onboarding step","access_role_id":1,"access_role":{"id":1,"name":"Sample Name","field_permissions":{"contact":{},"organization":{}}},"api_and_webhooks":true}]}}}},"401":{"description":"Unauthorized"}}},"patch":{"tags":["Profile"],"operationId":"auto_patch_api_v1_profile","summary":"Update profiles","description":"Updates the profile identified by the path parameters with the submitted attributes.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/user"},"example":{"id":1,"access_token":"sample-token","account_id":1,"available_name":"sample available name","avatar_url":"https://example.com/resource","confirmed":true,"display_name":"sample display name","message_signature":"sample message signature","email":"agent@example.com","hmac_identifier":"sample hmac identifier","inviter_id":1,"name":"Sample Name","provider":"email","pubsub_token":"sample-token","role":"agent","ui_settings":{"translation_language_by_account":{"1":"pt-BR"}},"uid":"sample uid","type":"sample type","custom_attributes":{},"accounts":[{"id":1,"name":"Sample Name","status":"active","active_at":"2026-01-15T10:30:00.000Z","role":"administrator","outbound_agent_name_header_policy":"inherit","permissions":["sample permission"],"availability":"online","availability_status":"online","auto_offline":true,"custom_role_id":1,"custom_role":{"id":1,"name":"Sample Name","description":"A short description.","permissions":["conversation_manage"]},"onboarding_step":"sample onboarding step","access_role_id":1,"access_role":{"id":1,"name":"Sample Name","field_permissions":{"contact":{},"organization":{}}},"api_and_webhooks":true}]}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"profile":{"type":"object","properties":{"current_password":{"type":"string"},"password":{"type":"string"},"password_confirmation":{"type":"string"},"email":{"type":"string","format":"email"},"name":{"type":"string"},"display_name":{"type":"string"},"avatar":{"type":"string"},"message_signature":{"type":"string"},"ui_settings":{"type":"object","additionalProperties":true,"description":"The user's persisted dashboard UI preferences."},"phone_number":{"type":"string"}}}},"required":["profile"]},"example":{"profile":{"current_password":"sample current password","password":"sample-password","password_confirmation":"sample password confirmation","email":"agent@example.com","name":"Sample Name","display_name":"sample display name","avatar":"sample avatar","message_signature":"sample message signature","ui_settings":{},"phone_number":"+5511999998888"}}}}},"x-authentication":{"kind":"credential","scheme":"userApiKey","location":"header","name":"api_access_token","verification_boundary":"Api::V1::ProfilesController authentication filter","algorithm":"opaque"}}},"/api/v1/accounts/{account_id}/teams":{"parameters":[{"$ref":"#/components/parameters/account_id"}],"get":{"tags":["Teams"],"operationId":"list-all-teams","summary":"List all teams","security":[{"userApiKey":[]}],"description":"List all teams available in the current account","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"array","description":"Array of teams","items":{"$ref":"#/components/schemas/team"}},"example":[{"id":1,"name":"Sample Name","description":"A short description.","allow_auto_assign":true,"account_id":1,"is_member":true,"avatar_url":"https://app.example.com/rails/active_storage/representations/team-icon.png","thumbnail":"https://app.example.com/rails/active_storage/representations/team-icon.png"}]}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"post":{"tags":["Teams"],"operationId":"create-a-team","summary":"Create a team","security":[{"userApiKey":[]}],"description":"Create a team in the account","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/team_create_update_payload"},"example":{"name":"Support Team","description":"This is a team of support agents","allow_auto_assign":true,"remove_avatar":false}},"multipart/form-data":{"schema":{"$ref":"#/components/schemas/team_create_update_multipart_payload"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/team"},"example":{"id":1,"name":"Sample Name","description":"A short description.","allow_auto_assign":true,"account_id":1,"is_member":true,"avatar_url":"https://app.example.com/rails/active_storage/representations/team-icon.png","thumbnail":"https://app.example.com/rails/active_storage/representations/team-icon.png"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/teams/{team_id}":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"$ref":"#/components/parameters/team_id"}],"get":{"tags":["Teams"],"operationId":"get-details-of-a-single-team","summary":"Get a team details","security":[{"userApiKey":[]}],"description":"Get the details of a team in the account","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/team"},"example":{"id":1,"name":"Sample Name","description":"A short description.","allow_auto_assign":true,"account_id":1,"is_member":true,"avatar_url":"https://app.example.com/rails/active_storage/representations/team-icon.png","thumbnail":"https://app.example.com/rails/active_storage/representations/team-icon.png"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"The given team ID does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"patch":{"tags":["Teams"],"operationId":"update-a-team","summary":"Update a team","security":[{"userApiKey":[]}],"description":"Update a team's attributes","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/team_create_update_payload"},"example":{"name":"Support Team","description":"This is a team of support agents","allow_auto_assign":true,"remove_avatar":false}},"multipart/form-data":{"schema":{"$ref":"#/components/schemas/team_create_update_multipart_payload"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/team"},"example":{"id":1,"name":"Sample Name","description":"A short description.","allow_auto_assign":true,"account_id":1,"is_member":true,"avatar_url":"https://app.example.com/rails/active_storage/representations/team-icon.png","thumbnail":"https://app.example.com/rails/active_storage/representations/team-icon.png"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"put":{"tags":["Teams"],"operationId":"update-a-team-with-put","summary":"Update a team using PUT","security":[{"userApiKey":[]}],"description":"Update a team's attributes using the PUT compatibility route","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/team_create_update_payload"},"example":{"name":"Support Team","description":"This is a team of support agents","allow_auto_assign":true,"remove_avatar":false}},"multipart/form-data":{"schema":{"$ref":"#/components/schemas/team_create_update_multipart_payload"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/team"},"example":{"id":1,"name":"Sample Name","description":"A short description.","allow_auto_assign":true,"account_id":1,"is_member":true,"avatar_url":"https://app.example.com/rails/active_storage/representations/team-icon.png","thumbnail":"https://app.example.com/rails/active_storage/representations/team-icon.png"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"delete":{"tags":["Teams"],"operationId":"delete-a-team","summary":"Delete a team","security":[{"userApiKey":[]}],"description":"Delete a team from the account","responses":{"200":{"description":"Success"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"The team does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/teams/{team_id}/team_members":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"$ref":"#/components/parameters/team_id"}],"get":{"tags":["Teams"],"operationId":"get-team-members","summary":"List Agents in Team","description":"Get Details of Agents in an Team","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"array","description":"Array of all agents in the team","items":{"$ref":"#/components/schemas/agent"}},"example":[{"id":1,"account_id":1,"account_user_id":1,"availability_status":"online","auto_offline":true,"confirmed":true,"email":"agent@example.com","available_name":"sample available name","name":"Sample Name","role":"agent","outbound_agent_name_header_policy":"inherit","thumbnail":"sample thumbnail","custom_role_id":1}]}}},"403":{"description":"Access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"Team not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"post":{"tags":["Teams"],"operationId":"add-new-agent-to-team","summary":"Add a New Agent","description":"Add a new Agent to Team","security":[{"userApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["user_ids"],"properties":{"user_ids":{"type":"array","items":{"type":"integer"},"description":"IDs of users to be added to the team","example":[1]}}},"example":{"user_ids":[1]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"array","description":"Array of all active agents","items":{"$ref":"#/components/schemas/agent"}},"example":[{"id":1,"account_id":1,"account_user_id":1,"availability_status":"online","auto_offline":true,"confirmed":true,"email":"agent@example.com","available_name":"sample available name","name":"Sample Name","role":"agent","outbound_agent_name_header_policy":"inherit","thumbnail":"sample thumbnail","custom_role_id":1}]}}},"403":{"description":"Access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"Team not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"422":{"description":"User must exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"patch":{"tags":["Teams"],"operationId":"update-agents-in-team","summary":"Update Agents in Team","description":"All agents except the one passed in params will be removed","security":[{"userApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["user_ids"],"properties":{"user_ids":{"type":"array","items":{"type":"integer"},"description":"IDs of users to be added to the team","example":[1]}}},"example":{"user_ids":[1]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"array","description":"Array of all agents in the team","items":{"$ref":"#/components/schemas/agent"}},"example":[{"id":1,"account_id":1,"account_user_id":1,"availability_status":"online","auto_offline":true,"confirmed":true,"email":"agent@example.com","available_name":"sample available name","name":"Sample Name","role":"agent","outbound_agent_name_header_policy":"inherit","thumbnail":"sample thumbnail","custom_role_id":1}]}}},"403":{"description":"Access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"Team not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"422":{"description":"User must exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"delete":{"tags":["Teams"],"operationId":"delete-agent-in-team","summary":"Remove an Agent from Team","description":"Remove an Agent from Team","security":[{"userApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["user_ids"],"properties":{"user_ids":{"type":"array","items":{"type":"integer"},"description":"IDs of users to be deleted from the team"}}},"example":{"user_ids":[1]}}}},"responses":{"200":{"description":"Success"},"403":{"description":"Access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"Team not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"422":{"description":"User must exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/custom_filters":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"in":"query","name":"filter_type","schema":{"type":["string","integer"],"enum":["conversation","contact","report","crm_item","crm_report","catalog_product","catalog_report","task","organization",0,1,2,3,4,5,6,7,8]},"required":false,"description":"Which listing to read the saved filters of. Defaults to `conversation` when omitted. Accepts either the name or its integer position."}],"get":{"tags":["Custom Filters"],"operationId":"list-all-filters","summary":"List all custom filters","description":"List saved filters owned by the authenticated user in this account, in one resource category. Native access roles require the permission of that category: conversation views use conversation_manage, conversation_unassigned_manage or conversation_participating_manage; contact views use contact_manage, contact_export or contact_delete. Report views use a report permission, CRM views crm_manage, catalog views catalog_manage, task views tasks_manage and organization views organizations_manage. Built-in agent/administrator access is preserved. A saved view never widens the resource query permission or team/inbox scope.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"array","description":"Array of custom filters","items":{"$ref":"#/components/schemas/custom_filter"}},"example":[{"id":1,"name":"Sample Name","filter_type":"conversation","query":{},"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}]}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"422":{"description":"Invalid filter_type. No saved views were read or changed.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","enum":["invalid_filter_type"],"example":"invalid_filter_type"}}},"example":{"error":"invalid_filter_type"}}}}}},"post":{"tags":["Custom Filters"],"operationId":"create-a-custom-filter","summary":"Create a custom filter","description":"Create a saved filter owned by the authenticated user in this account. Native access roles require the permission for filter_type: conversation, contact, report, CRM, catalog, task or organization. A conversation permission never grants contact views. The underlying resource query still enforces its own permissions and operational scope. Omitted filter_type defaults to conversation; invalid types return 422 without saving.","security":[{"userApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/custom_filter_create_update_payload"},"example":{"name":"My Custom Filter","filter_type":"conversation","query":{}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/custom_filter"},"example":{"id":1,"name":"Sample Name","filter_type":"conversation","query":{},"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"422":{"description":"Invalid filter_type, or model validation failure. No record was partially changed.","content":{"application/json":{"schema":{"oneOf":[{"type":"object","required":["error"],"properties":{"error":{"type":"string","enum":["invalid_filter_type"],"example":"invalid_filter_type"}}},{"type":"object","required":["message"],"properties":{"message":{"type":"string","description":"Validation error for the submitted saved view.","example":"Account Limit reached. The maximum number of allowed custom filters for a user per account is 1000."}}}]},"examples":{"invalid_type":{"value":{"error":"invalid_filter_type"}},"validation":{"value":{"message":"Account Limit reached. The maximum number of allowed custom filters for a user per account is 1000."}}}}}}}}},"/api/v1/accounts/{account_id}/custom_filters/{custom_filter_id}":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"$ref":"#/components/parameters/custom_filter_id"}],"get":{"tags":["Custom Filters"],"operationId":"get-details-of-a-single-custom-filter","summary":"Get a custom filter details","description":"Read a saved filter owned by the authenticated user in this account. Native access roles require permission for its resource type. Another user or account filter is not found, including for an administrator. Reading the filter does not grant access to conversations or contacts outside the caller scope.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/custom_filter"},"example":{"id":1,"name":"Sample Name","filter_type":"conversation","query":{},"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"The given team ID does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"patch":{"tags":["Custom Filters"],"operationId":"update-a-custom-filter","summary":"Update a custom filter","security":[{"userApiKey":[]}],"description":"Update a saved filter owned by the authenticated user in this account. Native access roles require permission for the stored resource type. Changing filter_type additionally requires permission for the new resource type; authorization or validation failure leaves the record unchanged. Another user or account filter is not found, including for an administrator. PATCH and PUT accept the documented flat JSON object or that same object nested under custom_filter. Omitted editable fields are preserved; unknown top-level fields and attempted ownership changes are ignored, while query remains an opaque JSON object. Empty payloads and invalid filter_type return 422; malformed JSON returns 400 before the action runs.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/custom_filter_create_update_payload"},"example":{"name":"My Custom Filter","filter_type":"conversation","query":{}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/custom_filter"},"example":{"id":1,"name":"Sample Name","filter_type":"conversation","query":{},"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}},"400":{"description":"Malformed JSON rejected by the HTTP parser before the action runs. The framework negotiates the error representation; it is not a saved-view JSON payload."},"401":{"description":"Invalid access token or missing permission for the current or proposed resource type.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","example":"You are not authorized to do this action"}}},"example":{"error":"You are not authorized to do this action"}}}},"403":{"description":"The account API policy denies access. Native self-hosted API availability is preserved even when the optional API feature bitmap is off. No saved view was changed on a policy denial.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","example":"API access is not enabled for this account"}}},"example":{"error":"API access is not enabled for this account"}}}},"404":{"description":"The saved view is not owned by this actor in this account, or does not exist.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","example":"Resource could not be found"}}},"example":{"error":"Resource could not be found"}}}},"422":{"description":"Missing or empty custom_filter payload, invalid filter_type, or model validation failure. No record was partially changed.","content":{"application/json":{"schema":{"oneOf":[{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"invalid_filter_type for an unrecognized resource type, or a parameter-missing message for a missing or empty custom_filter payload.","example":"invalid_filter_type"}}},{"type":"object","required":["message","attributes"],"properties":{"message":{"type":"string","description":"Validation error for the submitted saved view.","example":"Account Limit reached. The maximum number of allowed custom filters for a user per account is 1000."},"attributes":{"type":"array","description":"Names of the fields that failed model validation.","items":{"type":"string"},"example":["account_id"]}}}]},"examples":{"invalid_type":{"value":{"error":"invalid_filter_type"}},"missing_payload":{"value":{"error":"param is missing or the value is empty: custom_filter"}},"validation":{"value":{"message":"Account Limit reached. The maximum number of allowed custom filters for a user per account is 1000.","attributes":["account_id"]}}}}}}}},"delete":{"tags":["Custom Filters"],"operationId":"delete-a-custom-filter","summary":"Delete a custom filter","security":[{"userApiKey":[]}],"description":"Delete a saved filter owned by the authenticated user in this account. Native access roles require permission for its resource type; this only deletes the saved view, not the underlying conversations, contacts or other records. Another user or account filter is not found, including for an administrator.","responses":{"200":{"description":"Success"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"The custom filter does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"put":{"tags":["Custom Filters"],"operationId":"auto_put_api_v1_accounts_account_id_custom_filters_id","summary":"Update a custom filter","description":"Update a saved filter owned by the authenticated user in this account. Native access roles require permission for the stored resource type. Changing filter_type additionally requires permission for the new resource type; authorization or validation failure leaves the record unchanged. Another user or account filter is not found, including for an administrator. PATCH and PUT accept the documented flat JSON object or that same object nested under custom_filter. Omitted editable fields are preserved; unknown top-level fields and attempted ownership changes are ignored, while query remains an opaque JSON object. Empty payloads and invalid filter_type return 422; malformed JSON returns 400 before the action runs.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/custom_filter"},"example":{"id":1,"name":"Sample Name","filter_type":"conversation","query":{},"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}},"401":{"description":"Invalid access token or missing permission for the current or proposed resource type.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","example":"You are not authorized to do this action"}}},"example":{"error":"You are not authorized to do this action"}}}},"404":{"description":"The saved view is not owned by this actor in this account, or does not exist.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","example":"Resource could not be found"}}},"example":{"error":"Resource could not be found"}}}},"400":{"description":"Malformed JSON rejected by the HTTP parser before the action runs. The framework negotiates the error representation; it is not a saved-view JSON payload."},"403":{"description":"The account API policy denies access. Native self-hosted API availability is preserved even when the optional API feature bitmap is off. No saved view was changed on a policy denial.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","example":"API access is not enabled for this account"}}},"example":{"error":"API access is not enabled for this account"}}}},"422":{"description":"Missing or empty custom_filter payload, invalid filter_type, or model validation failure. No record was partially changed.","content":{"application/json":{"schema":{"oneOf":[{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"invalid_filter_type for an unrecognized resource type, or a parameter-missing message for a missing or empty custom_filter payload.","example":"invalid_filter_type"}}},{"type":"object","required":["message","attributes"],"properties":{"message":{"type":"string","description":"Validation error for the submitted saved view.","example":"Account Limit reached. The maximum number of allowed custom filters for a user per account is 1000."},"attributes":{"type":"array","description":"Names of the fields that failed model validation.","items":{"type":"string"},"example":["account_id"]}}}]},"examples":{"invalid_type":{"value":{"error":"invalid_filter_type"}},"missing_payload":{"value":{"error":"param is missing or the value is empty: custom_filter"}},"validation":{"value":{"message":"Account Limit reached. The maximum number of allowed custom filters for a user per account is 1000.","attributes":["account_id"]}}}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/custom_filter_create_update_payload"},"example":{"name":"My Custom Filter","filter_type":"conversation","query":{}}}}}}},"/api/v1/accounts/{account_id}/webhooks":{"parameters":[{"$ref":"#/components/parameters/account_id"}],"get":{"tags":["Webhooks"],"operationId":"list-all-webhooks","summary":"List all webhooks","security":[{"userApiKey":[]}],"description":"List all webhooks in the account","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"array","description":"Array of webhook objects","items":{"$ref":"#/components/schemas/webhook"}},"example":[{"id":1,"url":"https://example.com/resource","name":"Sample Name","subscriptions":["conversation_status_changed"],"include_commerce_details":false,"secret_configured":true,"secret":"sample-token","account_id":1}]}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"post":{"tags":["Webhooks"],"operationId":"create-a-webhook","summary":"Add a webhook","security":[{"userApiKey":[]}],"description":"Add a webhook subscription to the account","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/webhook_create_update_payload"},"example":{"url":"https://example.com/webhook","name":"Sample Name","subscriptions":["conversation_created","conversation_status_changed"],"include_commerce_details":false}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/webhook"},"example":{"id":1,"url":"https://example.com/resource","name":"Sample Name","subscriptions":["conversation_status_changed"],"include_commerce_details":false,"secret_configured":true,"secret":"sample-token","account_id":1}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/webhooks/{webhook_id}":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"$ref":"#/components/parameters/webhook_id"}],"patch":{"tags":["Webhooks"],"operationId":"update-a-webhook","summary":"Update a webhook object","security":[{"userApiKey":[]}],"description":"Update a webhook object in the account","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/webhook_create_update_payload"},"example":{"url":"https://example.com/webhook","name":"Sample Name","subscriptions":["conversation_created","conversation_status_changed"],"include_commerce_details":false}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/webhook"},"example":{"id":1,"url":"https://example.com/resource","name":"Sample Name","subscriptions":["conversation_status_changed"],"include_commerce_details":false,"secret_configured":true,"secret":"sample-token","account_id":1}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"delete":{"tags":["Webhooks"],"operationId":"delete-a-webhook","summary":"Delete a webhook","security":[{"userApiKey":[]}],"description":"Delete a webhook from the account","responses":{"200":{"description":"Success"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"The webhook does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"put":{"tags":["Webhooks"],"operationId":"auto_put_api_v1_accounts_account_id_webhooks_id","summary":"Update webhooks","description":"Updates the webhook identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"webhook":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"url":{"type":"string"},"account_id":{"type":"integer"},"subscriptions":{"type":"string"},"include_commerce_details":{"type":"string"},"secret_configured":{"type":"boolean"},"secret":{"type":"string"},"inbox":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"}}},"logical_inbox_id":{"type":"integer"}}}}}}},"example":{"payload":{"webhook":{"id":1,"name":"Sample Name","url":"https://example.com/resource","account_id":1,"subscriptions":"sample subscriptions","include_commerce_details":"sample include commerce details","secret_configured":true,"secret":"sample-token","inbox":{"id":1,"name":"Sample Name"},"logical_inbox_id":1}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"webhook":{"type":"object","properties":{"inbox_id":{"type":"integer"},"name":{"type":"string"},"url":{"type":"string"},"include_commerce_details":{"type":"string"},"subscriptions":{"type":"array","items":{"type":"string"}}}}},"required":["webhook"]},"example":{"webhook":{"inbox_id":1,"name":"Sample Name","url":"https://example.com/resource","include_commerce_details":"sample include commerce details","subscriptions":["sample subscription"]}}}}}}},"/api/v1/accounts/{account_id}/reporting_events":{"parameters":[{"$ref":"#/components/parameters/account_id"}],"get":{"tags":["Reports"],"operationId":"get-account-reporting-events","x-chatwoot-editions":["ee"],"summary":"Account Reporting Events","security":[{"userApiKey":[]}],"description":"Get paginated reporting events for the account. This endpoint returns reporting events such as first response time, resolution time, and other metrics. Only administrators can access this endpoint. Results are paginated with 25 items per page.","parameters":[{"$ref":"#/components/parameters/page"},{"in":"query","name":"since","schema":{"type":"string"},"description":"The timestamp from where events should start (Unix timestamp in seconds)"},{"in":"query","name":"until","schema":{"type":"string"},"description":"The timestamp from where events should stop (Unix timestamp in seconds)"},{"in":"query","name":"inbox_id","schema":{"type":"number"},"description":"Filter events by inbox ID"},{"in":"query","name":"user_id","schema":{"type":"number"},"description":"Filter events by user/agent ID"},{"in":"query","name":"name","schema":{"type":"string"},"description":"Filter events by event name (e.g., first_response, resolution, reply_time)"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/reporting_events_list_response"},"example":{"meta":{"count":5,"current_page":1,"total_pages":1},"payload":[{"id":1,"name":"Sample Name","value":149.9,"value_in_business_hours":12.5,"event_start_time":"2026-01-15T10:30:00.000Z","event_end_time":"2026-01-15T10:30:00.000Z","account_id":1,"conversation_id":1,"inbox_id":1,"user_id":1,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}]}}}},"403":{"description":"Access denied - Only administrators can access this endpoint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v2/accounts/{account_id}/reports":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"$ref":"#/components/parameters/report_metric"},{"$ref":"#/components/parameters/report_type"},{"in":"query","name":"id","schema":{"type":"string"},"description":"The Id of specific object in case of agent/inbox/label"},{"in":"query","name":"since","schema":{"type":"string"},"description":"The timestamp from where report should start."},{"in":"query","name":"until","schema":{"type":"string"},"description":"The timestamp from where report should stop."}],"get":{"tags":["Reports"],"operationId":"list-all-conversation-statistics","summary":"Get Account reports","security":[{"userApiKey":[]}],"description":"Get Account reports for a specific type, metric and date range","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"array","description":"Array of date based conversation statistics","items":{"type":"object","properties":{"value":{"type":"string"},"timestamp":{"type":"number"}}}},"example":[{"value":"sample value","timestamp":12.5}]}}},"404":{"description":"reports not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"403":{"description":"Access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v2/accounts/{account_id}/reports/summary":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"$ref":"#/components/parameters/report_type"},{"in":"query","name":"id","schema":{"type":"string"},"description":"The Id of specific object in case of agent/inbox/label"},{"in":"query","name":"since","schema":{"type":"string"},"description":"The timestamp from where report should start."},{"in":"query","name":"until","schema":{"type":"string"},"description":"The timestamp from where report should stop."}],"get":{"tags":["Reports"],"operationId":"list-all-conversation-statistics-summary","summary":"Get Account reports summary","security":[{"userApiKey":[]}],"description":"Get Account reports summary for a specific type and date range","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/account_summary"},"example":{"avg_first_response_time":"2026-01-15T10:30:00.000Z","avg_resolution_time":"2026-01-15T10:30:00.000Z","conversations_count":5,"incoming_messages_count":5,"outgoing_messages_count":5,"resolutions_count":5,"previous":{"avg_first_response_time":"2026-01-15T10:30:00.000Z","avg_resolution_time":"2026-01-15T10:30:00.000Z","conversations_count":5,"incoming_messages_count":5,"outgoing_messages_count":5,"resolutions_count":5}}}}},"404":{"description":"reports not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"403":{"description":"Access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v2/accounts/{account_id}/reports/conversations":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"in":"query","name":"type","schema":{"type":"string","enum":["account","agent"]},"required":true,"description":"Type of report (account-wide object or per-agent array)"},{"in":"query","name":"user_id","schema":{"type":"string"},"description":"The numeric ID of the user (only with type=agent)"}],"get":{"tags":["Reports"],"operationId":"get-conversation-metrics","summary":"Conversation Metrics","security":[{"userApiKey":[]}],"description":"Get open/unattended/unassigned conversation counts. With `type=account` the response is the account-wide metrics object; with `type=agent` it is an array of per-agent metrics (optionally narrowed with `user_id`).\n","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"oneOf":[{"type":"object","title":"Account conversation metrics (type=account)","properties":{"open":{"type":"number"},"unattended":{"type":"number"},"unassigned":{"type":"number"}}},{"type":"array","title":"Agent conversation metrics (type=agent)","description":"Array of agent based conversation metrics","items":{"$ref":"#/components/schemas/agent_conversation_metrics"}}]},"example":{"open":12.5,"unattended":12.5,"unassigned":12.5}}}},"404":{"description":"reports not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"403":{"description":"Access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v2/accounts/{account_id}/summary_reports/channel":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"in":"query","name":"since","schema":{"type":"string"},"description":"The timestamp from where report should start (Unix timestamp)."},{"in":"query","name":"until","schema":{"type":"string"},"description":"The timestamp from where report should stop (Unix timestamp)."}],"get":{"tags":["Reports"],"operationId":"get-channel-summary-report","summary":"Get conversation statistics grouped by channel type","security":[{"userApiKey":[]}],"description":"Get conversation counts grouped by channel type and status for a given date range.\nReturns statistics for each channel type including open, resolved, pending, snoozed, and total conversation counts.\n\n**Note:** This API endpoint is available only in platform version 4.10.0 and above. The date range is limited to a maximum of 6 months.\n","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/channel_summary"},"example":{"Channel::WebWidget":{"open":10,"resolved":20,"pending":5,"snoozed":2,"total":37},"Channel::Api":{"open":5,"resolved":15,"pending":3,"snoozed":1,"total":24}}}}},"400":{"description":"Date range exceeds 6 months limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"403":{"description":"Access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v2/accounts/{account_id}/summary_reports/inbox":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"in":"query","name":"since","schema":{"type":"string"},"description":"The timestamp from where report should start (Unix timestamp)."},{"in":"query","name":"until","schema":{"type":"string"},"description":"The timestamp from where report should stop (Unix timestamp)."},{"in":"query","name":"business_hours","schema":{"type":"boolean"},"description":"Whether to calculate metrics using business hours only."}],"get":{"tags":["Reports"],"operationId":"get-inbox-summary-report","summary":"Get conversation statistics grouped by inbox","security":[{"userApiKey":[]}],"description":"Get conversation statistics grouped by inbox for a given date range.\nReturns metrics for each inbox including conversation counts, resolution counts,\naverage first response time, average resolution time, and average reply time.\n","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/inbox_summary"},"example":[{"id":1,"conversations_count":150,"resolved_conversations_count":120,"avg_resolution_time":3600,"avg_first_response_time":300,"avg_reply_time":600},{"id":2,"conversations_count":75,"resolved_conversations_count":60,"avg_resolution_time":1800,"avg_first_response_time":180,"avg_reply_time":420}]}}},"403":{"description":"Access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v2/accounts/{account_id}/summary_reports/agent":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"in":"query","name":"since","schema":{"type":"string"},"description":"The timestamp from where report should start (Unix timestamp)."},{"in":"query","name":"until","schema":{"type":"string"},"description":"The timestamp from where report should stop (Unix timestamp)."},{"in":"query","name":"business_hours","schema":{"type":"boolean"},"description":"Whether to calculate metrics using business hours only."}],"get":{"tags":["Reports"],"operationId":"get-agent-summary-report","summary":"Get conversation statistics grouped by agent","security":[{"userApiKey":[]}],"description":"Get conversation statistics grouped by agent for a given date range.\nReturns metrics for each agent including conversation counts, resolution counts,\naverage first response time, average resolution time, and average reply time.\n","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agent_summary"},"example":[{"id":1,"conversations_count":150,"resolved_conversations_count":120,"avg_resolution_time":3600,"avg_first_response_time":300,"avg_reply_time":600},{"id":2,"conversations_count":75,"resolved_conversations_count":60,"avg_resolution_time":1800,"avg_first_response_time":180,"avg_reply_time":420}]}}},"403":{"description":"Access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v2/accounts/{account_id}/summary_reports/team":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"in":"query","name":"since","schema":{"type":"string"},"description":"The timestamp from where report should start (Unix timestamp)."},{"in":"query","name":"until","schema":{"type":"string"},"description":"The timestamp from where report should stop (Unix timestamp)."},{"in":"query","name":"business_hours","schema":{"type":"boolean"},"description":"Whether to calculate metrics using business hours only."}],"get":{"tags":["Reports"],"operationId":"get-team-summary-report","summary":"Get conversation statistics grouped by team","security":[{"userApiKey":[]}],"description":"Get conversation statistics grouped by team for a given date range.\nReturns metrics for each team including conversation counts, resolution counts,\naverage first response time, average resolution time, and average reply time.\n","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/team_summary"},"example":[{"id":1,"conversations_count":250,"resolved_conversations_count":200,"avg_resolution_time":2800,"avg_first_response_time":240,"avg_reply_time":500},{"id":2,"conversations_count":180,"resolved_conversations_count":150,"avg_resolution_time":2400,"avg_first_response_time":200,"avg_reply_time":450}]}}},"403":{"description":"Access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v2/accounts/{account_id}/reports/first_response_time_distribution":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"in":"query","name":"since","schema":{"type":"string"},"description":"The timestamp from where report should start (Unix timestamp)."},{"in":"query","name":"until","schema":{"type":"string"},"description":"The timestamp from where report should stop (Unix timestamp)."}],"get":{"tags":["Reports"],"operationId":"get-first-response-time-distribution","summary":"Get first response time distribution by channel","security":[{"userApiKey":[]}],"description":"Get the distribution of first response times grouped by channel type.\nReturns conversation counts in different time buckets (0-1h, 1-4h, 4-8h, 8-24h, 24h+) for each channel type.\n\n**Note:** This API endpoint is available only in platform version 4.11.0 and above.\n","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/first_response_time_distribution"},"example":{"Channel::WebWidget":{"0-1h":150,"1-4h":80,"4-8h":45,"8-24h":30,"24h+":15},"Channel::Api":{"0-1h":75,"1-4h":40,"4-8h":20,"8-24h":10,"24h+":5}}}}},"403":{"description":"Access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v2/accounts/{account_id}/reports/inbox_label_matrix":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"in":"query","name":"since","schema":{"type":"string"},"description":"The timestamp from where report should start (Unix timestamp)."},{"in":"query","name":"until","schema":{"type":"string"},"description":"The timestamp from where report should stop (Unix timestamp)."},{"in":"query","name":"inbox_ids","schema":{"type":"array","items":{"type":"integer"}},"description":"Filter by specific inbox IDs."},{"in":"query","name":"label_ids","schema":{"type":"array","items":{"type":"integer"}},"description":"Filter by specific label IDs."}],"get":{"tags":["Reports"],"operationId":"get-inbox-label-matrix","summary":"Get inbox-label matrix report","security":[{"userApiKey":[]}],"description":"Get a matrix showing the count of conversations for each inbox-label combination.\nReturns a list of inboxes, labels, and a 2D matrix where each cell contains the count of conversations\nin a specific inbox that have a specific label applied.\n\n**Note:** This API endpoint is available only in platform version 4.11.0 and above.\n","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/inbox_label_matrix"},"example":{"inboxes":[{"id":1,"name":"Website Chat"},{"id":2,"name":"Email Support"}],"labels":[{"id":1,"title":"bug"},{"id":2,"title":"feature-request"},{"id":3,"title":"urgent"}],"matrix":[[10,5,3],[8,12,2]]}}}},"403":{"description":"Access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v2/accounts/{account_id}/reports/outgoing_messages_count":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"in":"query","name":"since","schema":{"type":"string"},"description":"The timestamp from where report should start (Unix timestamp)."},{"in":"query","name":"until","schema":{"type":"string"},"description":"The timestamp from where report should stop (Unix timestamp)."}],"get":{"tags":["Reports"],"operationId":"get-outgoing-messages-count","summary":"Get outgoing messages count grouped by entity","security":[{"userApiKey":[]}],"description":"Get the count of outgoing messages grouped by a specified entity (agent, team, inbox, or label).\nWhen grouped by agent, messages sent by bots (AgentBot, Captain::Assistant) are excluded.\n\n**Note:** This API endpoint is available only in platform version 4.11.0 and above.\n","parameters":[{"in":"query","name":"group_by","required":true,"schema":{"type":"string","enum":["agent","team","inbox","label"]},"description":"The entity to group outgoing message counts by."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/outgoing_messages_count"},"example":[{"id":1,"name":"Agent One","outgoing_messages_count":42},{"id":2,"name":"Agent Two","outgoing_messages_count":18}]}}},"403":{"description":"Access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/crm/demo":{"parameters":[{"$ref":"#/components/parameters/account_id"}],"post":{"tags":["CRM Templates"],"operationId":"seed-crm-demo-data","summary":"Seed CRM demo data","security":[{"userApiKey":[]}],"description":"Enqueue the CRM demo seed (admin-only). A demo pipeline with stages, deals, contacts, conversations, notes, checklist and attachments is created asynchronously — the endpoint returns 202 immediately with an empty body. Poll the pipelines list until the demo pipeline appears.","responses":{"202":{"description":"Accepted — the seed job was enqueued. Empty body."},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"delete":{"tags":["CRM Templates"],"operationId":"teardown-crm-demo-data","summary":"Tear down CRM demo data","security":[{"userApiKey":[]}],"description":"Remove the sample CRM demo data previously seeded into the account","responses":{"200":{"description":"Success"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/crm/pipeline_templates":{"parameters":[{"$ref":"#/components/parameters/account_id"}],"get":{"tags":["CRM Templates"],"operationId":"list-all-crm-pipeline-templates","summary":"List all pipeline templates","security":[{"userApiKey":[]}],"description":"List the available pipeline templates (catalog used to scaffold new pipelines)","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","description":"Array of pipeline templates","items":{"$ref":"#/components/schemas/crm_pipeline_template"}},"meta":{"type":"object","properties":{"count":{"type":"number"}}}}},"example":{"payload":[{"id":"sample id","name":"Sample Name","description":"A short description.","pipeline_type":"sales","stages":[{"name":"Sample Name","color":"#1F93FF","stage_type":"open","probability":12.5}]}],"meta":{"count":5}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"post":{"tags":["CRM Templates"],"operationId":"create-pipeline-from-template","summary":"Create a pipeline from a template","security":[{"userApiKey":[]}],"description":"Instantiate a pipeline (with its predefined stages) from a template","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"template_id":{"type":"string","description":"The template identifier to instantiate"}},"required":["template_id"]},"example":{"template_id":"sample template id"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"$ref":"#/components/schemas/crm_pipeline"}}},"example":{"payload":{"id":1,"name":"Sample Name","description":"A short description.","pipeline_type":"sales","default":true,"position":1,"settings":{},"field_ids":[1],"required_field_ids":[1],"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/crm/pipelines":{"parameters":[{"$ref":"#/components/parameters/account_id"}],"get":{"tags":["CRM Pipelines"],"operationId":"list-all-crm-pipelines","summary":"List all pipelines","security":[{"userApiKey":[]}],"description":"List all CRM pipelines in the account","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","description":"Array of pipelines","items":{"$ref":"#/components/schemas/crm_pipeline"}},"meta":{"type":"object","properties":{"count":{"type":"number"},"current_page":{"type":"number"}}}}},"example":{"payload":[{"id":1,"name":"Sample Name","description":"A short description.","pipeline_type":"sales","default":true,"position":1,"settings":{},"field_ids":[1],"required_field_ids":[1],"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}],"meta":{"count":5,"current_page":12.5}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"post":{"tags":["CRM Pipelines"],"operationId":"create-a-crm-pipeline","summary":"Create a pipeline","security":[{"userApiKey":[]}],"description":"Create a CRM pipeline in the account","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"pipeline":{"$ref":"#/components/schemas/crm_pipeline_payload"}}},"example":{"pipeline":{"name":"Sales","description":"A short description.","pipeline_type":"sales","default":true,"settings":{}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"$ref":"#/components/schemas/crm_pipeline"}}},"example":{"payload":{"id":1,"name":"Sample Name","description":"A short description.","pipeline_type":"sales","default":true,"position":1,"settings":{},"field_ids":[1],"required_field_ids":[1],"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/crm/pipelines/{id}":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"id","in":"path","required":true,"schema":{"type":"number"},"description":"ID of the pipeline"}],"get":{"tags":["CRM Pipelines"],"operationId":"get-details-of-a-crm-pipeline","summary":"Get a pipeline","security":[{"userApiKey":[]}],"description":"Get the details of a CRM pipeline","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"$ref":"#/components/schemas/crm_pipeline"}}},"example":{"payload":{"id":1,"name":"Sample Name","description":"A short description.","pipeline_type":"sales","default":true,"position":1,"settings":{},"field_ids":[1],"required_field_ids":[1],"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"The given pipeline ID does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"patch":{"tags":["CRM Pipelines"],"operationId":"update-a-crm-pipeline","summary":"Update a pipeline","security":[{"userApiKey":[]}],"description":"Update a CRM pipeline's attributes","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"pipeline":{"$ref":"#/components/schemas/crm_pipeline_payload"}}},"example":{"pipeline":{"name":"Sales","description":"A short description.","pipeline_type":"sales","default":true,"settings":{}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"$ref":"#/components/schemas/crm_pipeline"}}},"example":{"payload":{"id":1,"name":"Sample Name","description":"A short description.","pipeline_type":"sales","default":true,"position":1,"settings":{},"field_ids":[1],"required_field_ids":[1],"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"The given pipeline ID does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"delete":{"tags":["CRM Pipelines"],"operationId":"delete-a-crm-pipeline","summary":"Delete a pipeline","security":[{"userApiKey":[]}],"description":"Delete a CRM pipeline from the account","responses":{"200":{"description":"Success"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"The pipeline does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"put":{"tags":["CRM Pipelines"],"operationId":"auto_put_api_v1_accounts_account_id_crm_pipelines_id","summary":"Update pipelines","description":"Updates the pipeline identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"pipeline_type":{"type":"string","enum":["sales","customer_success","onboarding","renewal","support","custom"],"description":"The business process a CRM pipeline models."},"default":{"type":"boolean"},"position":{"type":"integer"},"settings":{"type":"string"},"field_ids":{"type":"array","items":{"type":"integer"}},"required_field_ids":{"type":"array","items":{"type":"integer"}},"archived_at":{"type":"string","format":"date-time"},"archived":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"commercial_terms_config":{"type":"string"}}}}},"example":{"payload":{"id":1,"name":"Sample Name","description":"A short description.","pipeline_type":"sales","default":true,"position":1,"settings":"sample settings","field_ids":[1],"required_field_ids":[1],"archived_at":"2026-01-15T10:30:00.000Z","archived":true,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","commercial_terms_config":"sample commercial terms config"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"pipeline":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"pipeline_type":{"type":"string","enum":["sales","customer_success","onboarding","renewal","support","custom"],"description":"The business process a CRM pipeline models."},"default":{"type":"boolean"},"position":{"type":"integer"},"settings":{"type":"object","additionalProperties":true,"description":"Free-form object."}}}},"required":["pipeline"]},"example":{"pipeline":{"name":"Sample Name","description":"A short description.","pipeline_type":"sales","default":true,"position":1,"settings":{}}}}}}}},"/api/v1/accounts/{account_id}/crm/pipelines/{id}/metrics":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"id","in":"path","required":true,"schema":{"type":"number"},"description":"ID of the pipeline"}],"get":{"tags":["CRM Pipelines"],"operationId":"get-crm-pipeline-metrics","summary":"Get pipeline metrics","security":[{"userApiKey":[]}],"description":"Get forecast, conversion rate, win rate and average cycle time for a pipeline","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"metrics":{"type":"object","properties":{"pipeline_id":{"type":"number"},"forecast":{"type":"object","description":"Weighted forecast by currency","additionalProperties":{"type":"number"}},"conversion_rate":{"type":"number"},"win_rate":{"type":"number"},"avg_cycle_time":{"type":"number","description":"Average time-to-close in seconds"}}}}},"example":{"metrics":{"pipeline_id":1,"forecast":{},"conversion_rate":12.5,"win_rate":12.5,"avg_cycle_time":12.5}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"The given pipeline ID does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/crm/pipelines/{id}/reposition":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"id","in":"path","required":true,"schema":{"type":"number"},"description":"ID of the pipeline"}],"patch":{"tags":["CRM Pipelines"],"operationId":"reposition-a-crm-pipeline","summary":"Reposition a pipeline","security":[{"userApiKey":[]}],"description":"Change the sort position of a pipeline","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/crm_item_reposition_payload"},"example":{"position":1}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"$ref":"#/components/schemas/crm_pipeline"}}},"example":{"payload":{"id":1,"name":"Sample Name","description":"A short description.","pipeline_type":"sales","default":true,"position":1,"settings":{},"field_ids":[1],"required_field_ids":[1],"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"The given pipeline ID does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/crm/pipelines/{id}/purge":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"id","in":"path","required":true,"schema":{"type":"number"},"description":"ID of the pipeline"}],"delete":{"tags":["CRM Pipelines"],"operationId":"purge-a-crm-pipeline","summary":"Permanently delete an archived pipeline","security":[{"userApiKey":[]}],"description":"Permanently delete an archived CRM pipeline and all of its stages (active and archived). The pipeline must already be archived, and it must have no deals left in either bin (active or archived) — transfer or purge them first.","responses":{"200":{"description":"Success"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"422":{"description":"The pipeline must be archived first, or it still has deals (active or archived)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"The pipeline does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/crm/pipelines/{id}/restore":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"id","in":"path","required":true,"schema":{"type":"number"},"description":"ID of the pipeline"}],"patch":{"tags":["CRM Pipelines"],"operationId":"restore-a-crm-pipeline","summary":"Restore an archived pipeline","security":[{"userApiKey":[]}],"description":"Bring a soft-deleted (archived) CRM pipeline back to the active list. The pipeline is re-positioned at the end of the kept pipelines (its original slot may have been taken).","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"$ref":"#/components/schemas/crm_pipeline"}}},"example":{"payload":{"id":1,"name":"Sample Name","description":"A short description.","pipeline_type":"sales","default":true,"position":1,"settings":{},"field_ids":[1],"required_field_ids":[1],"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"The pipeline does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"422":{"description":"An active pipeline with the same name already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/crm/pipelines/{pipeline_id}/stages":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"pipeline_id","in":"path","required":true,"schema":{"type":"number"},"description":"ID of the pipeline"}],"get":{"tags":["CRM Stages"],"operationId":"list-all-crm-stages","summary":"List all stages","security":[{"userApiKey":[]}],"description":"List all stages in a pipeline","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","description":"Array of stages","items":{"$ref":"#/components/schemas/crm_stage"}},"meta":{"type":"object","properties":{"count":{"type":"number"},"current_page":{"type":"number"}}}}},"example":{"payload":[{"id":1,"account_id":1,"pipeline_id":1,"name":"Sample Name","color":"#1F93FF","position":1,"stage_type":"open","probability":12.5,"sla_in_hours":12.5,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}],"meta":{"count":5,"current_page":12.5}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"post":{"tags":["CRM Stages"],"operationId":"create-a-crm-stage","summary":"Create a stage","security":[{"userApiKey":[]}],"description":"Create a stage in a pipeline","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"stage":{"$ref":"#/components/schemas/crm_stage_payload"}}},"example":{"stage":{"name":"Qualified","color":"#1f93ff","position":1,"stage_type":"open","probability":12.5,"sla_in_hours":12.5}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"$ref":"#/components/schemas/crm_stage"}}},"example":{"payload":{"id":1,"account_id":1,"pipeline_id":1,"name":"Sample Name","color":"#1F93FF","position":1,"stage_type":"open","probability":12.5,"sla_in_hours":12.5,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/crm/pipelines/{pipeline_id}/stages/{id}":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"pipeline_id","in":"path","required":true,"schema":{"type":"number"},"description":"ID of the pipeline"},{"name":"id","in":"path","required":true,"schema":{"type":"number"},"description":"ID of the stage"}],"get":{"tags":["CRM Stages"],"operationId":"get-details-of-a-crm-stage","summary":"Get a stage","security":[{"userApiKey":[]}],"description":"Get the details of a stage","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"$ref":"#/components/schemas/crm_stage"}}},"example":{"payload":{"id":1,"account_id":1,"pipeline_id":1,"name":"Sample Name","color":"#1F93FF","position":1,"stage_type":"open","probability":12.5,"sla_in_hours":12.5,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"The given stage ID does not exist in the pipeline","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"patch":{"tags":["CRM Stages"],"operationId":"update-a-crm-stage","summary":"Update a stage","security":[{"userApiKey":[]}],"description":"Update a stage's attributes","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"stage":{"$ref":"#/components/schemas/crm_stage_payload"}}},"example":{"stage":{"name":"Qualified","color":"#1f93ff","position":1,"stage_type":"open","probability":12.5,"sla_in_hours":12.5}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"$ref":"#/components/schemas/crm_stage"}}},"example":{"payload":{"id":1,"account_id":1,"pipeline_id":1,"name":"Sample Name","color":"#1F93FF","position":1,"stage_type":"open","probability":12.5,"sla_in_hours":12.5,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"The given stage ID does not exist in the pipeline","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"delete":{"tags":["CRM Stages"],"operationId":"delete-a-crm-stage","summary":"Delete a stage","security":[{"userApiKey":[]}],"description":"Delete a stage from a pipeline. Open items in the stage are reassigned to the stage given by move_items_to_stage_id.","parameters":[{"name":"move_items_to_stage_id","in":"query","required":false,"schema":{"type":"number"},"description":"The stage to reassign open items to before deletion"}],"responses":{"200":{"description":"Success"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"The stage does not exist in the pipeline","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"put":{"tags":["CRM Stages"],"operationId":"auto_put_api_v1_accounts_account_id_crm_pipelines_pipeline_id_stages_id","summary":"Update stages","description":"Updates the stage identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"pipeline_id":{"type":"integer"},"name":{"type":"string"},"color":{"type":"string"},"position":{"type":"integer"},"stage_type":{"type":"string","enum":["open","won","lost"],"description":"The lifecycle bucket a pipeline stage maps a deal onto."},"probability":{"type":"string"},"sla_in_hours":{"type":"string"},"archived_at":{"type":"string","format":"date-time"},"archived":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}},"example":{"payload":{"id":1,"account_id":1,"pipeline_id":1,"name":"Sample Name","color":"#1F93FF","position":1,"stage_type":"open","probability":"sample probability","sla_in_hours":"sample sla in hours","archived_at":"2026-01-15T10:30:00.000Z","archived":true,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"stage":{"type":"object","properties":{"name":{"type":"string"},"color":{"type":"string"},"position":{"type":"integer"},"stage_type":{"type":"string","enum":["open","won","lost"],"description":"The lifecycle bucket a pipeline stage maps a deal onto."},"probability":{"type":"string"},"sla_in_hours":{"type":"string"}}}},"required":["stage"]},"example":{"stage":{"name":"Sample Name","color":"#1F93FF","position":1,"stage_type":"open","probability":"sample probability","sla_in_hours":"sample sla in hours"}}}}}}},"/api/v1/accounts/{account_id}/crm/pipelines/{pipeline_id}/stages/{id}/reposition":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"pipeline_id","in":"path","required":true,"schema":{"type":"number"},"description":"ID of the pipeline"},{"name":"id","in":"path","required":true,"schema":{"type":"number"},"description":"ID of the stage"}],"patch":{"tags":["CRM Stages"],"operationId":"reposition-a-crm-stage","summary":"Reposition a stage","security":[{"userApiKey":[]}],"description":"Change the sort position of a stage within its pipeline","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/crm_item_reposition_payload"},"example":{"position":1}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"$ref":"#/components/schemas/crm_stage"}}},"example":{"payload":{"id":1,"account_id":1,"pipeline_id":1,"name":"Sample Name","color":"#1F93FF","position":1,"stage_type":"open","probability":12.5,"sla_in_hours":12.5,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"The given stage ID does not exist in the pipeline","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/crm/pipelines/{pipeline_id}/stages/{id}/purge":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"pipeline_id","in":"path","required":true,"schema":{"type":"number"},"description":"ID of the pipeline"},{"name":"id","in":"path","required":true,"schema":{"type":"number"},"description":"ID of the stage"}],"delete":{"tags":["CRM Stages"],"operationId":"purge-a-crm-stage","summary":"Permanently delete an archived stage","security":[{"userApiKey":[]}],"description":"Permanently delete an archived stage from a pipeline. The stage must already be archived, and no deal in either bin (active or archived) may still reference it — move or purge them first.","responses":{"200":{"description":"Success"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"422":{"description":"The stage must be archived first, or deals (active or archived) still reference it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"The stage does not exist in the pipeline","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/crm/pipelines/{pipeline_id}/stages/{id}/restore":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"pipeline_id","in":"path","required":true,"schema":{"type":"number"},"description":"ID of the pipeline"},{"name":"id","in":"path","required":true,"schema":{"type":"number"},"description":"ID of the stage"}],"patch":{"tags":["CRM Stages"],"operationId":"restore-a-crm-stage","summary":"Restore an archived stage","security":[{"userApiKey":[]}],"description":"Bring a soft-deleted (archived) stage back to the pipeline. The stage is re-positioned at the end of the pipeline's kept stages (its original slot may have been taken).","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"$ref":"#/components/schemas/crm_stage"}}},"example":{"payload":{"id":1,"account_id":1,"pipeline_id":1,"name":"Sample Name","color":"#1F93FF","position":1,"stage_type":"open","probability":12.5,"sla_in_hours":12.5,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"The stage does not exist in the pipeline","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/crm/items":{"parameters":[{"$ref":"#/components/parameters/account_id"}],"get":{"tags":["CRM Items"],"operationId":"list-all-crm-items","summary":"List all items","security":[{"userApiKey":[]}],"description":"List CRM items (deals) in the account with filtering, sorting and pagination. Set archived=true to list the soft-deleted (archived) bin instead of the active list.","parameters":[{"name":"pipeline_id","in":"query","required":false,"schema":{"type":"number"},"description":"Filter by pipeline"},{"name":"stage_id","in":"query","required":false,"schema":{"type":"number"},"description":"Filter by stage"},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["open","won","lost"]},"description":"Filter by status"},{"name":"assignee_id","in":"query","required":false,"schema":{"type":"number"},"description":"Filter by assigned agent"},{"name":"team_id","in":"query","required":false,"schema":{"type":"number"},"description":"Filter by assigned team"},{"name":"health_status","in":"query","required":false,"schema":{"type":"string","enum":["healthy","at_risk","critical"]},"description":"Filter by health bucket"},{"name":"contact_id","in":"query","required":false,"schema":{"type":"number"},"description":"Filter by linked contact (global FK)"},{"name":"conversation_id","in":"query","required":false,"schema":{"type":"number"},"description":"Filter by linked conversation (accepts display_id or global id)"},{"name":"q","in":"query","required":false,"schema":{"type":"string"},"description":"Free-text search over title and description"},{"name":"sort","in":"query","required":false,"schema":{"type":"string","enum":["created_at_asc","created_at_desc","position_asc","position_desc","value_amount_asc","value_amount_desc","expected_close_on_asc","expected_close_on_desc","health_score_asc","health_score_desc"]},"description":"Sort order (defaults to created_at_desc)"},{"name":"page","in":"query","required":false,"schema":{"type":"number"},"description":"The page number"},{"name":"archived","in":"query","required":false,"schema":{"type":"boolean"},"description":"When true, list the archived (soft-deleted) bin instead of the active list"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","description":"Array of items","items":{"$ref":"#/components/schemas/crm_item"}},"meta":{"type":"object","properties":{"count":{"type":"number"},"current_page":{"type":"number"},"total_pages":{"type":"number"},"per_page":{"type":"number"},"has_more":{"type":"boolean"}}}}},"example":{"payload":[{"id":1,"account_id":1,"pipeline_id":1,"stage_id":1,"title":"Sample title","description":"A short description.","status":"open","priority":"low","value_amount":149.9,"currency":"BRL","expected_close_on":"2026-01-15","opened_at":"2026-01-15T10:30:00.000Z","closed_at":"2026-01-15T10:30:00.000Z","stage_entered_at":"2026-01-15T10:30:00.000Z","position":1,"health_score":12.5,"health_status":"healthy","health_computed_at":"2026-01-15T10:30:00.000Z","custom_attributes":{},"additional_attributes":{},"contact_id":1,"conversation_id":1,"organization_id":1,"crm_organization_id":1,"assignee_id":1,"team_id":1,"pipeline_name":"sample pipeline name","stage_name":"sample stage name","stage_sla_in_hours":12.5,"assignee":{"id":1,"name":"Sample Name","available_name":"sample available name","thumbnail":"sample thumbnail"},"contact":{"id":1,"name":"Sample Name"},"participants":[{"id":1,"name":"Sample Name","available_name":"sample available name","thumbnail":"sample thumbnail"}],"organization":{"id":1,"name":"Sample Name"},"crm_organization":{"id":1,"name":"Sample Name"},"conversation":{"id":1,"display_id":1,"inbox":{"id":1,"name":"Sample Name","channel_type":"Channel::Api","provider":"default","medium":"sample medium","voice_enabled":true}},"notes_count":5,"attachments_count":5,"checklist_progress":{"done":12.5,"total":149.9},"archived_at":"2026-01-15T10:30:00.000Z","archived":true,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}],"meta":{"count":5,"current_page":12.5,"total_pages":12.5,"per_page":12.5,"has_more":true}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"post":{"tags":["CRM Items"],"operationId":"create-a-crm-item","summary":"Create an item","security":[{"userApiKey":[]}],"description":"Create a CRM item (deal) in the account. With item.idempotent=true the call becomes a find-or-create keyed on the linked conversation: if that conversation already has an OPEN deal, that deal is returned and `reused` is true instead of a second deal being created. Won and lost deals are never reused, so a new sales cycle on the same conversation still creates a new deal.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"item":{"allOf":[{"$ref":"#/components/schemas/crm_item_payload"},{"type":"object","properties":{"idempotent":{"type":"boolean","description":"Find-or-create keyed on the conversation link, instead of always creating. Ignored when no conversation is linked. Concurrent idempotent creates on the same conversation are serialized, so two simultaneous requests cannot both create. An EXPLICIT value always wins, true or false. There is deliberately NO static default: when the field is ABSENT the target pipeline decides via its own `dedup_conversation_deals` setting — pipelines created before that setting existed carry no such key and keep the historical \"every call creates\" behavior, while a newly created pipeline defaults to deduplicating, which is what stops duplicate cards appearing for the same conversation.","example":true}}}]}}},"example":{"item":{"title":"Acme Corp - Annual contract","description":"A short description.","value_amount":149.9,"currency":"USD","priority":"low","expected_close_on":"2026-01-15","opened_at":"2026-01-15T10:30:00.000Z","closed_at":"2026-01-15T10:30:00.000Z","close_reason":"sample close reason","pipeline_id":1,"stage_id":1,"contact_id":1,"conversation_id":1,"organization_id":1,"crm_organization_id":1,"assignee_id":1,"team_id":1,"custom_attributes":{},"additional_attributes":{},"participant_ids":[1],"idempotent":true}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"$ref":"#/components/schemas/crm_item"},"reused":{"type":"boolean","description":"True when an idempotent request matched an existing open deal on the same conversation instead of creating one. Always false on an ordinary create.","example":false}}},"example":{"payload":{"id":1,"account_id":1,"pipeline_id":1,"stage_id":1,"title":"Sample title","description":"A short description.","status":"open","priority":"low","value_amount":149.9,"currency":"BRL","expected_close_on":"2026-01-15","opened_at":"2026-01-15T10:30:00.000Z","closed_at":"2026-01-15T10:30:00.000Z","stage_entered_at":"2026-01-15T10:30:00.000Z","position":1,"health_score":12.5,"health_status":"healthy","health_computed_at":"2026-01-15T10:30:00.000Z","custom_attributes":{},"additional_attributes":{},"contact_id":1,"conversation_id":1,"organization_id":1,"crm_organization_id":1,"assignee_id":1,"team_id":1,"pipeline_name":"sample pipeline name","stage_name":"sample stage name","stage_sla_in_hours":12.5,"assignee":{"id":1,"name":"Sample Name","available_name":"sample available name","thumbnail":"sample thumbnail"},"contact":{"id":1,"name":"Sample Name"},"participants":[{"id":1,"name":"Sample Name","available_name":"sample available name","thumbnail":"sample thumbnail"}],"organization":{"id":1,"name":"Sample Name"},"crm_organization":{"id":1,"name":"Sample Name"},"conversation":{"id":1,"display_id":1,"inbox":{"id":1,"name":"Sample Name","channel_type":"Channel::Api","provider":"default","medium":"sample medium","voice_enabled":true}},"notes_count":5,"attachments_count":5,"checklist_progress":{"done":12.5,"total":149.9},"archived_at":"2026-01-15T10:30:00.000Z","archived":true,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"},"reused":false}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/crm/items/{id}":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"id","in":"path","required":true,"schema":{"type":"number"},"description":"ID of the item"}],"get":{"tags":["CRM Items"],"operationId":"get-details-of-a-crm-item","summary":"Get an item","security":[{"userApiKey":[]}],"description":"Get the details of a CRM item (resolves both active and archived items)","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"$ref":"#/components/schemas/crm_item"}}},"example":{"payload":{"id":1,"account_id":1,"pipeline_id":1,"stage_id":1,"title":"Sample title","description":"A short description.","status":"open","priority":"low","value_amount":149.9,"currency":"BRL","expected_close_on":"2026-01-15","opened_at":"2026-01-15T10:30:00.000Z","closed_at":"2026-01-15T10:30:00.000Z","stage_entered_at":"2026-01-15T10:30:00.000Z","position":1,"health_score":12.5,"health_status":"healthy","health_computed_at":"2026-01-15T10:30:00.000Z","custom_attributes":{},"additional_attributes":{},"contact_id":1,"conversation_id":1,"organization_id":1,"crm_organization_id":1,"assignee_id":1,"team_id":1,"pipeline_name":"sample pipeline name","stage_name":"sample stage name","stage_sla_in_hours":12.5,"assignee":{"id":1,"name":"Sample Name","available_name":"sample available name","thumbnail":"sample thumbnail"},"contact":{"id":1,"name":"Sample Name"},"participants":[{"id":1,"name":"Sample Name","available_name":"sample available name","thumbnail":"sample thumbnail"}],"organization":{"id":1,"name":"Sample Name"},"crm_organization":{"id":1,"name":"Sample Name"},"conversation":{"id":1,"display_id":1,"inbox":{"id":1,"name":"Sample Name","channel_type":"Channel::Api","provider":"default","medium":"sample medium","voice_enabled":true}},"notes_count":5,"attachments_count":5,"checklist_progress":{"done":12.5,"total":149.9},"archived_at":"2026-01-15T10:30:00.000Z","archived":true,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"The given item ID does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"patch":{"tags":["CRM Items"],"operationId":"update-a-crm-item","summary":"Update an item","security":[{"userApiKey":[]}],"description":"Update a CRM item's attributes","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"item":{"$ref":"#/components/schemas/crm_item_payload"}}},"example":{"item":{"title":"Acme Corp - Annual contract","description":"A short description.","value_amount":149.9,"currency":"USD","priority":"low","expected_close_on":"2026-01-15","opened_at":"2026-01-15T10:30:00.000Z","closed_at":"2026-01-15T10:30:00.000Z","close_reason":"sample close reason","pipeline_id":1,"stage_id":1,"contact_id":1,"conversation_id":1,"organization_id":1,"crm_organization_id":1,"assignee_id":1,"team_id":1,"custom_attributes":{},"additional_attributes":{},"participant_ids":[1]}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"$ref":"#/components/schemas/crm_item"}}},"example":{"payload":{"id":1,"account_id":1,"pipeline_id":1,"stage_id":1,"title":"Sample title","description":"A short description.","status":"open","priority":"low","value_amount":149.9,"currency":"BRL","expected_close_on":"2026-01-15","opened_at":"2026-01-15T10:30:00.000Z","closed_at":"2026-01-15T10:30:00.000Z","stage_entered_at":"2026-01-15T10:30:00.000Z","position":1,"health_score":12.5,"health_status":"healthy","health_computed_at":"2026-01-15T10:30:00.000Z","custom_attributes":{},"additional_attributes":{},"contact_id":1,"conversation_id":1,"organization_id":1,"crm_organization_id":1,"assignee_id":1,"team_id":1,"pipeline_name":"sample pipeline name","stage_name":"sample stage name","stage_sla_in_hours":12.5,"assignee":{"id":1,"name":"Sample Name","available_name":"sample available name","thumbnail":"sample thumbnail"},"contact":{"id":1,"name":"Sample Name"},"participants":[{"id":1,"name":"Sample Name","available_name":"sample available name","thumbnail":"sample thumbnail"}],"organization":{"id":1,"name":"Sample Name"},"crm_organization":{"id":1,"name":"Sample Name"},"conversation":{"id":1,"display_id":1,"inbox":{"id":1,"name":"Sample Name","channel_type":"Channel::Api","provider":"default","medium":"sample medium","voice_enabled":true}},"notes_count":5,"attachments_count":5,"checklist_progress":{"done":12.5,"total":149.9},"archived_at":"2026-01-15T10:30:00.000Z","archived":true,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"The given item ID does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"delete":{"tags":["CRM Items"],"operationId":"delete-a-crm-item","summary":"Archive an item","security":[{"userApiKey":[]}],"description":"Soft-delete (archive) a CRM item. The item is hidden from the active list and can be restored or purged.","responses":{"200":{"description":"Success"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"The item does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"put":{"tags":["CRM Items"],"operationId":"auto_put_api_v1_accounts_account_id_crm_items_id","summary":"Update a CRM deal","description":"Updates the editable attributes of a deal. Every field is optional and only the keys present in the request are changed. Moving a deal between stages through this endpoint keeps the append-only history in sync, and the same account-scoped validation applies to every link. Requires CRM item write authorization (administrator or agent).","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}},"example":{"error":"sample error"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["item"],"properties":{"item":{"type":"object","required":[],"properties":{"title":{"type":"string","description":"Deal name shown on the card and in the timeline."},"description":{"type":"string","description":"Free-text detail about the deal."},"pipeline_id":{"type":"integer","description":"Target pipeline. Omit to use the account default pipeline."},"stage_id":{"type":"integer","description":"Target stage within the pipeline. Omit to use its first open stage."},"value_amount":{"type":"number","format":"float","description":"Deal value in major currency units (4.97 means 4 units and 97 cents)."},"currency":{"type":"string","maxLength":3,"description":"ISO 4217 three-letter code. Not restricted to a fixed list."},"priority":{"type":"string","enum":["low","medium","high","urgent","normal"],"description":"Deal priority."},"expected_close_on":{"type":"string","format":"date","description":"Forecast close date."},"opened_at":{"type":"string","format":"date-time","description":"Business opening date. Defaults to the creation time and stays editable."},"closed_at":{"type":"string","format":"date-time","description":"When the deal was won or lost. On create, applies only to a won/lost stage and defaults to the current time when omitted. Cleared when the deal is reopened."},"close_reason":{"type":"string","description":"Why the deal was won or lost. Required for a terminal-stage create when the selected pipeline enables require_close_reason; ignored for an open stage."},"contact_id":{"type":"integer","description":"Contact this deal belongs to."},"conversation_id":{"type":"integer","description":"Linked conversation, given as the per-account display number."},"organization_id":{"type":"integer","description":"Organization this deal belongs to."},"crm_organization_id":{"type":"integer","deprecated":true,"description":"Legacy alias for organization_id, still accepted. Ignored when organization_id is present."},"assignee_id":{"type":"integer","description":"Agent responsible for the deal."},"team_id":{"type":"integer","description":"Team the deal is assigned to."},"participant_ids":{"type":"array","items":{"type":"integer"},"description":"Collaborators added at creation. Ids outside the account are dropped."},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Pipeline-scoped custom fields, keyed by attribute key. When the pipeline configures a custom-field set, keys outside that set are discarded on write; when it configures none, all keys are kept."},"additional_attributes":{"type":"object","additionalProperties":true,"description":"Free-form metadata kept alongside the deal, keyed by attribute name."},"idempotent":{"type":"boolean","default":false,"description":"Opt-in find-or-create keyed on the conversation link. When true and the linked conversation already has an OPEN deal, that deal is returned instead of a new one being created, and the top-level `reused` field of the response is true. Won and lost deals are never reused, so a new sales cycle on the same conversation still creates a new deal. Ignored when no conversation is linked. Concurrent idempotent creates on the same conversation are serialized, so two simultaneous requests cannot both create. Absent or false keeps the historical behavior: every call creates a deal."}}}}},"example":{"item":{"title":"Acme renewal (expanded)","description":"Renewal plus two extra seats.","pipeline_id":7,"stage_id":43,"value_amount":7200.0,"currency":"USD","priority":"urgent","expected_close_on":"2026-10-15","opened_at":"2026-07-01T10:00:00Z","closed_at":"2026-10-14T12:00:00Z","close_reason":"Upsell accepted.","contact_id":1201,"conversation_id":173,"organization_id":88,"crm_organization_id":88,"assignee_id":15,"team_id":3,"participant_ids":[15,22],"custom_attributes":{"origem":"webhook","score":"95"},"additional_attributes":{"utm_source":"meta"},"idempotent":false}}}}}}},"/api/v1/accounts/{account_id}/crm/items/{id}/move":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"id","in":"path","required":true,"schema":{"type":"number"},"description":"ID of the item"}],"patch":{"tags":["CRM Items"],"operationId":"move-a-crm-item","summary":"Move an item to a stage","security":[{"userApiKey":[]}],"description":"Move a CRM item to another stage within its pipeline, at an optional position","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/crm_item_move_payload"},"example":{"stage_id":1,"position":1}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"$ref":"#/components/schemas/crm_item"}}},"example":{"payload":{"id":1,"account_id":1,"pipeline_id":1,"stage_id":1,"title":"Sample title","description":"A short description.","status":"open","priority":"low","value_amount":149.9,"currency":"BRL","expected_close_on":"2026-01-15","opened_at":"2026-01-15T10:30:00.000Z","closed_at":"2026-01-15T10:30:00.000Z","stage_entered_at":"2026-01-15T10:30:00.000Z","position":1,"health_score":12.5,"health_status":"healthy","health_computed_at":"2026-01-15T10:30:00.000Z","custom_attributes":{},"additional_attributes":{},"contact_id":1,"conversation_id":1,"organization_id":1,"crm_organization_id":1,"assignee_id":1,"team_id":1,"pipeline_name":"sample pipeline name","stage_name":"sample stage name","stage_sla_in_hours":12.5,"assignee":{"id":1,"name":"Sample Name","available_name":"sample available name","thumbnail":"sample thumbnail"},"contact":{"id":1,"name":"Sample Name"},"participants":[{"id":1,"name":"Sample Name","available_name":"sample available name","thumbnail":"sample thumbnail"}],"organization":{"id":1,"name":"Sample Name"},"crm_organization":{"id":1,"name":"Sample Name"},"conversation":{"id":1,"display_id":1,"inbox":{"id":1,"name":"Sample Name","channel_type":"Channel::Api","provider":"default","medium":"sample medium","voice_enabled":true}},"notes_count":5,"attachments_count":5,"checklist_progress":{"done":12.5,"total":149.9},"archived_at":"2026-01-15T10:30:00.000Z","archived":true,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"The item or target stage does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/crm/items/{id}/reposition":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"id","in":"path","required":true,"schema":{"type":"number"},"description":"ID of the item"}],"patch":{"tags":["CRM Items"],"operationId":"reposition-a-crm-item","summary":"Reposition an item","security":[{"userApiKey":[]}],"description":"Reorder a CRM item within its current stage (no stage change)","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/crm_item_reposition_payload"},"example":{"position":1}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"$ref":"#/components/schemas/crm_item"}}},"example":{"payload":{"id":1,"account_id":1,"pipeline_id":1,"stage_id":1,"title":"Sample title","description":"A short description.","status":"open","priority":"low","value_amount":149.9,"currency":"BRL","expected_close_on":"2026-01-15","opened_at":"2026-01-15T10:30:00.000Z","closed_at":"2026-01-15T10:30:00.000Z","stage_entered_at":"2026-01-15T10:30:00.000Z","position":1,"health_score":12.5,"health_status":"healthy","health_computed_at":"2026-01-15T10:30:00.000Z","custom_attributes":{},"additional_attributes":{},"contact_id":1,"conversation_id":1,"organization_id":1,"crm_organization_id":1,"assignee_id":1,"team_id":1,"pipeline_name":"sample pipeline name","stage_name":"sample stage name","stage_sla_in_hours":12.5,"assignee":{"id":1,"name":"Sample Name","available_name":"sample available name","thumbnail":"sample thumbnail"},"contact":{"id":1,"name":"Sample Name"},"participants":[{"id":1,"name":"Sample Name","available_name":"sample available name","thumbnail":"sample thumbnail"}],"organization":{"id":1,"name":"Sample Name"},"crm_organization":{"id":1,"name":"Sample Name"},"conversation":{"id":1,"display_id":1,"inbox":{"id":1,"name":"Sample Name","channel_type":"Channel::Api","provider":"default","medium":"sample medium","voice_enabled":true}},"notes_count":5,"attachments_count":5,"checklist_progress":{"done":12.5,"total":149.9},"archived_at":"2026-01-15T10:30:00.000Z","archived":true,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"The item does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/crm/items/{id}/transfer":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"id","in":"path","required":true,"schema":{"type":"number"},"description":"ID of the item"}],"patch":{"tags":["CRM Items"],"operationId":"transfer-a-crm-item","summary":"Transfer an item to a pipeline","security":[{"userApiKey":[]}],"description":"Transfer a CRM item into another pipeline","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/crm_item_transfer_payload"},"example":{"pipeline_id":1}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"$ref":"#/components/schemas/crm_item"}}},"example":{"payload":{"id":1,"account_id":1,"pipeline_id":1,"stage_id":1,"title":"Sample title","description":"A short description.","status":"open","priority":"low","value_amount":149.9,"currency":"BRL","expected_close_on":"2026-01-15","opened_at":"2026-01-15T10:30:00.000Z","closed_at":"2026-01-15T10:30:00.000Z","stage_entered_at":"2026-01-15T10:30:00.000Z","position":1,"health_score":12.5,"health_status":"healthy","health_computed_at":"2026-01-15T10:30:00.000Z","custom_attributes":{},"additional_attributes":{},"contact_id":1,"conversation_id":1,"organization_id":1,"crm_organization_id":1,"assignee_id":1,"team_id":1,"pipeline_name":"sample pipeline name","stage_name":"sample stage name","stage_sla_in_hours":12.5,"assignee":{"id":1,"name":"Sample Name","available_name":"sample available name","thumbnail":"sample thumbnail"},"contact":{"id":1,"name":"Sample Name"},"participants":[{"id":1,"name":"Sample Name","available_name":"sample available name","thumbnail":"sample thumbnail"}],"organization":{"id":1,"name":"Sample Name"},"crm_organization":{"id":1,"name":"Sample Name"},"conversation":{"id":1,"display_id":1,"inbox":{"id":1,"name":"Sample Name","channel_type":"Channel::Api","provider":"default","medium":"sample medium","voice_enabled":true}},"notes_count":5,"attachments_count":5,"checklist_progress":{"done":12.5,"total":149.9},"archived_at":"2026-01-15T10:30:00.000Z","archived":true,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"The item or target pipeline does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/crm/items/{id}/status":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"id","in":"path","required":true,"schema":{"type":"number"},"description":"ID of the item"}],"patch":{"tags":["CRM Items"],"operationId":"change-crm-item-status","summary":"Change item status","security":[{"userApiKey":[]}],"description":"Mark a CRM item as won, lost, or reopen it","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/crm_item_status_payload"},"example":{"status":"won"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"$ref":"#/components/schemas/crm_item"}}},"example":{"payload":{"id":1,"account_id":1,"pipeline_id":1,"stage_id":1,"title":"Sample title","description":"A short description.","status":"open","priority":"low","value_amount":149.9,"currency":"BRL","expected_close_on":"2026-01-15","opened_at":"2026-01-15T10:30:00.000Z","closed_at":"2026-01-15T10:30:00.000Z","stage_entered_at":"2026-01-15T10:30:00.000Z","position":1,"health_score":12.5,"health_status":"healthy","health_computed_at":"2026-01-15T10:30:00.000Z","custom_attributes":{},"additional_attributes":{},"contact_id":1,"conversation_id":1,"organization_id":1,"crm_organization_id":1,"assignee_id":1,"team_id":1,"pipeline_name":"sample pipeline name","stage_name":"sample stage name","stage_sla_in_hours":12.5,"assignee":{"id":1,"name":"Sample Name","available_name":"sample available name","thumbnail":"sample thumbnail"},"contact":{"id":1,"name":"Sample Name"},"participants":[{"id":1,"name":"Sample Name","available_name":"sample available name","thumbnail":"sample thumbnail"}],"organization":{"id":1,"name":"Sample Name"},"crm_organization":{"id":1,"name":"Sample Name"},"conversation":{"id":1,"display_id":1,"inbox":{"id":1,"name":"Sample Name","channel_type":"Channel::Api","provider":"default","medium":"sample medium","voice_enabled":true}},"notes_count":5,"attachments_count":5,"checklist_progress":{"done":12.5,"total":149.9},"archived_at":"2026-01-15T10:30:00.000Z","archived":true,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"422":{"description":"Invalid status value (no write performed)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/crm/items/{id}/restore":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"id","in":"path","required":true,"schema":{"type":"number"},"description":"ID of the item"}],"patch":{"tags":["CRM Items"],"operationId":"restore-a-crm-item","summary":"Restore an archived item","security":[{"userApiKey":[]}],"description":"Bring a soft-deleted (archived) CRM item back to the active list","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"$ref":"#/components/schemas/crm_item"}}},"example":{"payload":{"id":1,"account_id":1,"pipeline_id":1,"stage_id":1,"title":"Sample title","description":"A short description.","status":"open","priority":"low","value_amount":149.9,"currency":"BRL","expected_close_on":"2026-01-15","opened_at":"2026-01-15T10:30:00.000Z","closed_at":"2026-01-15T10:30:00.000Z","stage_entered_at":"2026-01-15T10:30:00.000Z","position":1,"health_score":12.5,"health_status":"healthy","health_computed_at":"2026-01-15T10:30:00.000Z","custom_attributes":{},"additional_attributes":{},"contact_id":1,"conversation_id":1,"organization_id":1,"crm_organization_id":1,"assignee_id":1,"team_id":1,"pipeline_name":"sample pipeline name","stage_name":"sample stage name","stage_sla_in_hours":12.5,"assignee":{"id":1,"name":"Sample Name","available_name":"sample available name","thumbnail":"sample thumbnail"},"contact":{"id":1,"name":"Sample Name"},"participants":[{"id":1,"name":"Sample Name","available_name":"sample available name","thumbnail":"sample thumbnail"}],"organization":{"id":1,"name":"Sample Name"},"crm_organization":{"id":1,"name":"Sample Name"},"conversation":{"id":1,"display_id":1,"inbox":{"id":1,"name":"Sample Name","channel_type":"Channel::Api","provider":"default","medium":"sample medium","voice_enabled":true}},"notes_count":5,"attachments_count":5,"checklist_progress":{"done":12.5,"total":149.9},"archived_at":"2026-01-15T10:30:00.000Z","archived":true,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"The item does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/crm/items/{id}/purge":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"id","in":"path","required":true,"schema":{"type":"number"},"description":"ID of the item"}],"delete":{"tags":["CRM Items"],"operationId":"purge-a-crm-item","summary":"Permanently delete an archived item","security":[{"userApiKey":[]}],"description":"Permanently delete an archived CRM item (and its owned notes, attachments, checklist items, participants and events). The item must already be archived; linked conversation/contact/organization are not touched.","responses":{"200":{"description":"Success"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"422":{"description":"The item must be archived before it can be purged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"The item does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/crm/items/{id}/events":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"id","in":"path","required":true,"schema":{"type":"number"},"description":"ID of the item"}],"get":{"tags":["CRM Items"],"operationId":"list-crm-item-events","summary":"List item events","security":[{"userApiKey":[]}],"description":"List the transition/activity history of a CRM item (paginated, newest first)","parameters":[{"name":"page","in":"query","required":false,"schema":{"type":"number"},"description":"The page number"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number"},"crm_item_id":{"type":"number"},"event_type":{"type":"string","enum":["created","stage_changed","value_changed","won","lost","assigned","reopened","archived","note_added","note_deleted","priority_changed","restored"],"description":"The kind of CRM deal timeline event."},"user_id":{"type":"number"},"from_stage_id":{"type":"number"},"to_stage_id":{"type":"number"},"from_stage_name":{"type":"string"},"to_stage_name":{"type":"string"},"user":{"type":"object","properties":{"id":{"type":"number"},"name":{"type":"string"}}},"metadata":{"type":"object","additionalProperties":true,"description":"Free-form metadata bag; the key set depends on the record and context."},"created_at":{"type":"string","format":"date-time"}}}},"meta":{"type":"object","properties":{"count":{"type":"number"},"current_page":{"type":"number"},"total_pages":{"type":"number"},"has_more":{"type":"boolean"}}}}},"example":{"payload":[{"id":1,"crm_item_id":1,"event_type":"created","user_id":1,"from_stage_id":1,"to_stage_id":1,"from_stage_name":"sample from stage name","to_stage_name":"sample to stage name","user":{"id":1,"name":"Sample Name"},"metadata":{},"created_at":"2026-01-15T10:30:00.000Z"}],"meta":{"count":5,"current_page":12.5,"total_pages":12.5,"has_more":true}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/crm/items/{id}/execute_macro":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"id","in":"path","required":true,"schema":{"type":"number"},"description":"ID of the item"}],"post":{"tags":["CRM Items"],"operationId":"execute-macro-on-a-crm-item","summary":"Execute a macro on an item","security":[{"userApiKey":[]}],"description":"Run a macro's CRM actions on a single CRM item (executed asynchronously)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"macro_id":{"type":"number","description":"The macro to execute"}},"required":["macro_id"]},"example":{"macro_id":1}}}},"responses":{"200":{"description":"Accepted — the macro execution job was enqueued for the item. Empty body."},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"The item or macro does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"503":{"description":"The operator is holding Maestro macros for an update or rollback and the caller is the Maestro service identity. Nothing was queued. People, and accounts the operator released from the hold, are not affected.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","enum":["human_capability_unavailable"],"description":"Refusal code from the versioned human macro delegation contract."}}},"example":{"error":"human_capability_unavailable"}}}}}}},"/api/v1/accounts/{account_id}/crm/items/{id}/recompute":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"id","in":"path","required":true,"schema":{"type":"number"},"description":"ID of the item"}],"patch":{"tags":["CRM Items"],"operationId":"recompute-a-crm-item-value","summary":"Recompute the item value from line items","security":[{"userApiKey":[]}],"description":"Re-enable line-item-driven value on a CRM item (deal): sets value_is_auto to true and value_amount to the sum of the line totals, overriding any prior manual value edit. Returns the updated item so clients can refresh the live total and auto badge.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"$ref":"#/components/schemas/crm_item"}}},"example":{"payload":{"id":1,"account_id":1,"pipeline_id":1,"stage_id":1,"title":"Sample title","description":"A short description.","status":"open","priority":"low","value_amount":149.9,"currency":"BRL","expected_close_on":"2026-01-15","opened_at":"2026-01-15T10:30:00.000Z","closed_at":"2026-01-15T10:30:00.000Z","stage_entered_at":"2026-01-15T10:30:00.000Z","position":1,"health_score":12.5,"health_status":"healthy","health_computed_at":"2026-01-15T10:30:00.000Z","custom_attributes":{},"additional_attributes":{},"contact_id":1,"conversation_id":1,"organization_id":1,"crm_organization_id":1,"assignee_id":1,"team_id":1,"pipeline_name":"sample pipeline name","stage_name":"sample stage name","stage_sla_in_hours":12.5,"assignee":{"id":1,"name":"Sample Name","available_name":"sample available name","thumbnail":"sample thumbnail"},"contact":{"id":1,"name":"Sample Name"},"participants":[{"id":1,"name":"Sample Name","available_name":"sample available name","thumbnail":"sample thumbnail"}],"organization":{"id":1,"name":"Sample Name"},"crm_organization":{"id":1,"name":"Sample Name"},"conversation":{"id":1,"display_id":1,"inbox":{"id":1,"name":"Sample Name","channel_type":"Channel::Api","provider":"default","medium":"sample medium","voice_enabled":true}},"notes_count":5,"attachments_count":5,"checklist_progress":{"done":12.5,"total":149.9},"archived_at":"2026-01-15T10:30:00.000Z","archived":true,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"The item does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/crm/items/bulk_update":{"parameters":[{"$ref":"#/components/parameters/account_id"}],"patch":{"tags":["CRM Items"],"operationId":"bulk-update-crm-items","summary":"Bulk update items","security":[{"userApiKey":[]}],"description":"Apply shared fields (priority, assignee, team) to a selection of CRM items. Best-effort per item; failures are isolated and returned in meta.failed_ids. Capped at 500 ids per request.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/crm_item_bulk_update_payload"},"example":{"item_ids":[1],"fields":{"priority":"low","assignee_id":1,"team_id":1}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"$ref":"#/components/schemas/crm_item"}},"meta":{"$ref":"#/components/schemas/crm_bulk_meta"}}},"example":{"payload":[{"id":1,"account_id":1,"pipeline_id":1,"stage_id":1,"title":"Sample title","description":"A short description.","status":"open","priority":"low","value_amount":149.9,"currency":"BRL","expected_close_on":"2026-01-15","opened_at":"2026-01-15T10:30:00.000Z","closed_at":"2026-01-15T10:30:00.000Z","stage_entered_at":"2026-01-15T10:30:00.000Z","position":1,"health_score":12.5,"health_status":"healthy","health_computed_at":"2026-01-15T10:30:00.000Z","custom_attributes":{},"additional_attributes":{},"contact_id":1,"conversation_id":1,"organization_id":1,"crm_organization_id":1,"assignee_id":1,"team_id":1,"pipeline_name":"sample pipeline name","stage_name":"sample stage name","stage_sla_in_hours":12.5,"assignee":{"id":1,"name":"Sample Name","available_name":"sample available name","thumbnail":"sample thumbnail"},"contact":{"id":1,"name":"Sample Name"},"participants":[{"id":1,"name":"Sample Name","available_name":"sample available name","thumbnail":"sample thumbnail"}],"organization":{"id":1,"name":"Sample Name"},"crm_organization":{"id":1,"name":"Sample Name"},"conversation":{"id":1,"display_id":1,"inbox":{"id":1,"name":"Sample Name","channel_type":"Channel::Api","provider":"default","medium":"sample medium","voice_enabled":true}},"notes_count":5,"attachments_count":5,"checklist_progress":{"done":12.5,"total":149.9},"archived_at":"2026-01-15T10:30:00.000Z","archived":true,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}],"meta":{"requested":12,"updated":9,"failed":1,"failed_ids":[41],"skipped":2,"skipped_ids":[58,63],"skipped_details":[{"id":58,"reason":"archived"},{"id":63,"reason":"not_permitted"}]}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"422":{"description":"No fields provided or bulk limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/crm/items/bulk_move":{"parameters":[{"$ref":"#/components/parameters/account_id"}],"patch":{"tags":["CRM Items"],"operationId":"bulk-move-crm-items","summary":"Bulk move items","security":[{"userApiKey":[]}],"description":"Move a selection of CRM items into one stage. Items whose pipeline differs from the stage's pipeline are reported in meta.failed_ids. Capped at 500 ids per request.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"item_ids":{"type":"array","items":{"type":"number"}},"stage_id":{"type":"number","description":"The target stage"}},"required":["item_ids","stage_id"]},"example":{"item_ids":[1],"stage_id":1}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"$ref":"#/components/schemas/crm_item"}},"meta":{"$ref":"#/components/schemas/crm_bulk_meta"}}},"example":{"payload":[{"id":1,"account_id":1,"pipeline_id":1,"stage_id":1,"title":"Sample title","description":"A short description.","status":"open","priority":"low","value_amount":149.9,"currency":"BRL","expected_close_on":"2026-01-15","opened_at":"2026-01-15T10:30:00.000Z","closed_at":"2026-01-15T10:30:00.000Z","stage_entered_at":"2026-01-15T10:30:00.000Z","position":1,"health_score":12.5,"health_status":"healthy","health_computed_at":"2026-01-15T10:30:00.000Z","custom_attributes":{},"additional_attributes":{},"contact_id":1,"conversation_id":1,"organization_id":1,"crm_organization_id":1,"assignee_id":1,"team_id":1,"pipeline_name":"sample pipeline name","stage_name":"sample stage name","stage_sla_in_hours":12.5,"assignee":{"id":1,"name":"Sample Name","available_name":"sample available name","thumbnail":"sample thumbnail"},"contact":{"id":1,"name":"Sample Name"},"participants":[{"id":1,"name":"Sample Name","available_name":"sample available name","thumbnail":"sample thumbnail"}],"organization":{"id":1,"name":"Sample Name"},"crm_organization":{"id":1,"name":"Sample Name"},"conversation":{"id":1,"display_id":1,"inbox":{"id":1,"name":"Sample Name","channel_type":"Channel::Api","provider":"default","medium":"sample medium","voice_enabled":true}},"notes_count":5,"attachments_count":5,"checklist_progress":{"done":12.5,"total":149.9},"archived_at":"2026-01-15T10:30:00.000Z","archived":true,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}],"meta":{"requested":12,"updated":9,"failed":1,"failed_ids":[41],"skipped":2,"skipped_ids":[58,63],"skipped_details":[{"id":58,"reason":"archived"},{"id":63,"reason":"not_permitted"}]}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"422":{"description":"Bulk limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/crm/items/bulk_transfer":{"parameters":[{"$ref":"#/components/parameters/account_id"}],"patch":{"tags":["CRM Items"],"operationId":"bulk-transfer-crm-items","summary":"Bulk transfer items","security":[{"userApiKey":[]}],"description":"Transfer a selection of CRM items into another pipeline. Best-effort per item; failures are returned in meta.failed_ids. Capped at 500 ids per request.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"item_ids":{"type":"array","items":{"type":"number"}},"pipeline_id":{"type":"number","description":"The target pipeline"}},"required":["item_ids","pipeline_id"]},"example":{"item_ids":[1],"pipeline_id":1}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"$ref":"#/components/schemas/crm_item"}},"meta":{"$ref":"#/components/schemas/crm_bulk_meta"}}},"example":{"payload":[{"id":1,"account_id":1,"pipeline_id":1,"stage_id":1,"title":"Sample title","description":"A short description.","status":"open","priority":"low","value_amount":149.9,"currency":"BRL","expected_close_on":"2026-01-15","opened_at":"2026-01-15T10:30:00.000Z","closed_at":"2026-01-15T10:30:00.000Z","stage_entered_at":"2026-01-15T10:30:00.000Z","position":1,"health_score":12.5,"health_status":"healthy","health_computed_at":"2026-01-15T10:30:00.000Z","custom_attributes":{},"additional_attributes":{},"contact_id":1,"conversation_id":1,"organization_id":1,"crm_organization_id":1,"assignee_id":1,"team_id":1,"pipeline_name":"sample pipeline name","stage_name":"sample stage name","stage_sla_in_hours":12.5,"assignee":{"id":1,"name":"Sample Name","available_name":"sample available name","thumbnail":"sample thumbnail"},"contact":{"id":1,"name":"Sample Name"},"participants":[{"id":1,"name":"Sample Name","available_name":"sample available name","thumbnail":"sample thumbnail"}],"organization":{"id":1,"name":"Sample Name"},"crm_organization":{"id":1,"name":"Sample Name"},"conversation":{"id":1,"display_id":1,"inbox":{"id":1,"name":"Sample Name","channel_type":"Channel::Api","provider":"default","medium":"sample medium","voice_enabled":true}},"notes_count":5,"attachments_count":5,"checklist_progress":{"done":12.5,"total":149.9},"archived_at":"2026-01-15T10:30:00.000Z","archived":true,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}],"meta":{"requested":12,"updated":9,"failed":1,"failed_ids":[41],"skipped":2,"skipped_ids":[58,63],"skipped_details":[{"id":58,"reason":"archived"},{"id":63,"reason":"not_permitted"}]}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"422":{"description":"Bulk limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/crm/items/bulk_status":{"parameters":[{"$ref":"#/components/parameters/account_id"}],"patch":{"tags":["CRM Items"],"operationId":"bulk-change-crm-item-status","summary":"Bulk change item status","security":[{"userApiKey":[]}],"description":"Mark a selection of CRM items as won, lost, or reopen them. Best-effort per item; failures are returned in meta.failed_ids. Capped at 500 ids per request.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"item_ids":{"type":"array","items":{"type":"number"}},"status":{"type":"string","enum":["won","lost","reopen"]}},"required":["item_ids","status"]},"example":{"item_ids":[1],"status":"won"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"$ref":"#/components/schemas/crm_item"}},"meta":{"$ref":"#/components/schemas/crm_bulk_meta"}}},"example":{"payload":[{"id":1,"account_id":1,"pipeline_id":1,"stage_id":1,"title":"Sample title","description":"A short description.","status":"open","priority":"low","value_amount":149.9,"currency":"BRL","expected_close_on":"2026-01-15","opened_at":"2026-01-15T10:30:00.000Z","closed_at":"2026-01-15T10:30:00.000Z","stage_entered_at":"2026-01-15T10:30:00.000Z","position":1,"health_score":12.5,"health_status":"healthy","health_computed_at":"2026-01-15T10:30:00.000Z","custom_attributes":{},"additional_attributes":{},"contact_id":1,"conversation_id":1,"organization_id":1,"crm_organization_id":1,"assignee_id":1,"team_id":1,"pipeline_name":"sample pipeline name","stage_name":"sample stage name","stage_sla_in_hours":12.5,"assignee":{"id":1,"name":"Sample Name","available_name":"sample available name","thumbnail":"sample thumbnail"},"contact":{"id":1,"name":"Sample Name"},"participants":[{"id":1,"name":"Sample Name","available_name":"sample available name","thumbnail":"sample thumbnail"}],"organization":{"id":1,"name":"Sample Name"},"crm_organization":{"id":1,"name":"Sample Name"},"conversation":{"id":1,"display_id":1,"inbox":{"id":1,"name":"Sample Name","channel_type":"Channel::Api","provider":"default","medium":"sample medium","voice_enabled":true}},"notes_count":5,"attachments_count":5,"checklist_progress":{"done":12.5,"total":149.9},"archived_at":"2026-01-15T10:30:00.000Z","archived":true,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}],"meta":{"requested":12,"updated":9,"failed":1,"failed_ids":[41],"skipped":2,"skipped_ids":[58,63],"skipped_details":[{"id":58,"reason":"archived"},{"id":63,"reason":"not_permitted"}]}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"422":{"description":"Invalid status value or bulk limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/crm/items/bulk_destroy":{"parameters":[{"$ref":"#/components/parameters/account_id"}],"post":{"tags":["CRM Items"],"operationId":"bulk-archive-crm-items","summary":"Bulk archive items","security":[{"userApiKey":[]}],"description":"Soft-delete (archive) a selection of CRM items. Best-effort per item; failures are returned in meta.failed_ids. Capped at 500 ids per request.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/crm_item_bulk_ids_payload"},"example":{"item_ids":[1]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"destroyed_ids":{"type":"array","items":{"type":"number"}}}},"meta":{"$ref":"#/components/schemas/crm_bulk_meta"}}},"example":{"payload":{"destroyed_ids":[1]},"meta":{"requested":12,"updated":9,"failed":1,"failed_ids":[41],"skipped":2,"skipped_ids":[58,63],"skipped_details":[{"id":58,"reason":"archived"},{"id":63,"reason":"not_permitted"}]}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"422":{"description":"Bulk limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/crm/items/bulk_restore":{"parameters":[{"$ref":"#/components/parameters/account_id"}],"post":{"tags":["CRM Items"],"operationId":"bulk-restore-crm-items","summary":"Bulk restore items","security":[{"userApiKey":[]}],"description":"Un-archive a selection of archived CRM items. Best-effort per item; failures are returned in meta.failed_ids. Capped at 500 ids per request.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/crm_item_bulk_ids_payload"},"example":{"item_ids":[1]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"restored_ids":{"type":"array","items":{"type":"number"}}}},"meta":{"$ref":"#/components/schemas/crm_bulk_meta_archived_scope"}}},"example":{"payload":{"restored_ids":[1]},"meta":{"requested":12,"updated":9,"failed":1,"failed_ids":[41],"skipped":2,"skipped_ids":[58,63],"skipped_details":[{"id":58,"reason":"not_archived"},{"id":63,"reason":"not_permitted"}]}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"422":{"description":"Bulk limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/crm/items/bulk_purge":{"parameters":[{"$ref":"#/components/parameters/account_id"}],"post":{"tags":["CRM Items"],"operationId":"bulk-purge-crm-items","summary":"Bulk purge items","security":[{"userApiKey":[]}],"description":"Permanently delete a selection of archived CRM items (and their owned records). Best-effort per item; failures are returned in meta.failed_ids. Capped at 500 ids per request.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/crm_item_bulk_ids_payload"},"example":{"item_ids":[1]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"purged_ids":{"type":"array","items":{"type":"number"}}}},"meta":{"$ref":"#/components/schemas/crm_bulk_meta_archived_scope"}}},"example":{"payload":{"purged_ids":[1]},"meta":{"requested":12,"updated":9,"failed":1,"failed_ids":[41],"skipped":2,"skipped_ids":[58,63],"skipped_details":[{"id":58,"reason":"not_archived"},{"id":63,"reason":"not_permitted"}]}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"422":{"description":"Bulk limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/crm/items/execute_macro":{"parameters":[{"$ref":"#/components/parameters/account_id"}],"post":{"tags":["CRM Items"],"operationId":"bulk-execute-macro-on-crm-items","summary":"Bulk execute a macro on items","security":[{"userApiKey":[]}],"description":"Run a macro's CRM actions on a selection of CRM items (executed asynchronously). Capped at 500 ids per request.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"item_ids":{"type":"array","items":{"type":"number"}},"macro_id":{"type":"number","description":"The macro to execute"}},"required":["item_ids","macro_id"]},"example":{"item_ids":[1],"macro_id":1}}}},"responses":{"200":{"description":"The macro execution job was enqueued. The body reports which of the requested ids were handed to the queue and which were refused — selecting ids that are archived, outside your visibility, or foreign to the account narrows the selection, and this is where that narrowing is reported.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","description":"The ids actually handed to the background job.","properties":{"enqueued_ids":{"type":"array","items":{"type":"number"},"example":[41,42,43,44]}},"example":{"enqueued_ids":[41,42,43,44]}},"meta":{"$ref":"#/components/schemas/crm_bulk_meta_async"}}},"example":{"payload":{"enqueued_ids":[41,42,43,44]},"meta":{"requested":12,"enqueued":4,"skipped":8,"skipped_ids":[58,63,64,65,66,67,68,69],"skipped_details":[{"id":58,"reason":"archived"},{"id":63,"reason":"not_permitted"}]}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"The macro does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"422":{"description":"Bulk limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"503":{"description":"The operator is holding Maestro macros for an update or rollback and the caller is the Maestro service identity. Nothing was queued. People, and accounts the operator released from the hold, are not affected.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","enum":["human_capability_unavailable"],"description":"Refusal code from the versioned human macro delegation contract."}}},"example":{"error":"human_capability_unavailable"}}}}}}},"/api/v1/accounts/{account_id}/crm/items/{item_id}/notes":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"item_id","in":"path","required":true,"schema":{"type":"number"},"description":"ID of the item"}],"get":{"tags":["CRM Item Notes"],"operationId":"list-crm-item-notes","summary":"List item notes","security":[{"userApiKey":[]}],"description":"List the notes on a CRM item (returned as a bare array, no payload wrapper)","parameters":[{"name":"page","in":"query","required":false,"description":"Page of notes, newest first.","schema":{"type":"integer","default":1},"example":1}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/crm_note"}},"example":[{"id":1,"content":"Sample content text.","account_id":1,"crm_item_id":1,"user":{"id":1,"account_id":1,"account_user_id":1,"availability_status":"online","auto_offline":true,"confirmed":true,"email":"agent@example.com","available_name":"sample available name","name":"Sample Name","role":"agent","outbound_agent_name_header_policy":"inherit","thumbnail":"sample thumbnail","custom_role_id":1},"created_at":12.5,"updated_at":12.5}]}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"post":{"tags":["CRM Item Notes"],"operationId":"create-a-crm-item-note","summary":"Create an item note","security":[{"userApiKey":[]}],"description":"Create a note on a CRM item (returns the bare note object, no payload wrapper)","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/crm_note_payload"},"example":{"content":"Customer requested a follow-up call next week"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/crm_note"},"example":{"id":1,"content":"Sample content text.","account_id":1,"crm_item_id":1,"user":{"id":1,"account_id":1,"account_user_id":1,"availability_status":"online","auto_offline":true,"confirmed":true,"email":"agent@example.com","available_name":"sample available name","name":"Sample Name","role":"agent","outbound_agent_name_header_policy":"inherit","thumbnail":"sample thumbnail","custom_role_id":1},"created_at":12.5,"updated_at":12.5}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/crm/items/{item_id}/notes/{id}":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"item_id","in":"path","required":true,"schema":{"type":"number"},"description":"ID of the item"},{"name":"id","in":"path","required":true,"schema":{"type":"number"},"description":"ID of the note"}],"get":{"tags":["CRM Item Notes"],"operationId":"get-a-crm-item-note","summary":"Get an item note","security":[{"userApiKey":[]}],"description":"Get one note from a CRM item (returns the bare note object, no payload wrapper)","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/crm_note"},"example":{"id":1,"content":"Sample content text.","account_id":1,"crm_item_id":1,"user":{"id":1,"account_id":1,"account_user_id":1,"availability_status":"online","auto_offline":true,"confirmed":true,"email":"agent@example.com","available_name":"sample available name","name":"Sample Name","role":"agent","outbound_agent_name_header_policy":"inherit","thumbnail":"sample thumbnail","custom_role_id":1},"created_at":12.5,"updated_at":12.5}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"The note or CRM item does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"patch":{"tags":["CRM Item Notes"],"operationId":"update-a-crm-item-note","summary":"Update an item note","security":[{"userApiKey":[]}],"description":"Update a note on a CRM item (returns the bare note object, no payload wrapper)","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/crm_note_payload"},"example":{"content":"Customer requested a follow-up call next week"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/crm_note"},"example":{"id":1,"content":"Sample content text.","account_id":1,"crm_item_id":1,"user":{"id":1,"account_id":1,"account_user_id":1,"availability_status":"online","auto_offline":true,"confirmed":true,"email":"agent@example.com","available_name":"sample available name","name":"Sample Name","role":"agent","outbound_agent_name_header_policy":"inherit","thumbnail":"sample thumbnail","custom_role_id":1},"created_at":12.5,"updated_at":12.5}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"The note does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"delete":{"tags":["CRM Item Notes"],"operationId":"delete-a-crm-item-note","summary":"Delete an item note","security":[{"userApiKey":[]}],"description":"Delete a note from a CRM item","responses":{"200":{"description":"Success"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"The note does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"put":{"tags":["CRM Item Notes"],"operationId":"auto_put_api_v1_accounts_account_id_crm_items_item_id_notes_id","summary":"Update notes","description":"Updates the note identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"content":{"type":"string"},"account_id":{"type":"integer"},"crm_item_id":{"type":"integer"},"user":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":["integer","null"]},"account_user_id":{"type":["integer","null"]},"availability_status":{"type":"string","enum":["online","offline","busy"],"description":"Realtime availability. Contacts report online/offline (presence-based); agents/users additionally report busy (their configured availability)."},"auto_offline":{"type":"boolean"},"confirmed":{"type":"boolean"},"email":{"type":"string","format":"email"},"provider":{"type":"string","enum":["email","google_oauth2","saml"],"description":"Authentication provider the user signed up through."},"available_name":{"type":"string"},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"name":{"type":"string"},"role":{"type":"string","enum":["agent","administrator"]},"outbound_agent_name_header_policy":{"type":["string","null"]},"thumbnail":{"type":"string"},"custom_role_id":{"type":["integer","null"]},"access_role_id":{"type":["integer","null"]}}},"created_at":{"type":"integer"},"updated_at":{"type":"integer"}}},"example":{"id":1,"content":"Sample content text.","account_id":1,"crm_item_id":1,"user":{"id":1,"account_id":1,"account_user_id":1,"availability_status":"online","auto_offline":true,"confirmed":true,"email":"agent@example.com","provider":"email","available_name":"sample available name","custom_attributes":{},"name":"Sample Name","role":"agent","outbound_agent_name_header_policy":"sample outbound agent name header policy","thumbnail":"sample thumbnail","custom_role_id":1,"access_role_id":1},"created_at":1,"updated_at":1}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"note":{"type":"object","properties":{"content":{"type":"string"}}}},"required":["note"]},"example":{"note":{"content":"Sample content text."}}}}}}},"/api/v1/accounts/{account_id}/crm/items/{item_id}/attachments":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"item_id","in":"path","required":true,"schema":{"type":"number"},"description":"ID of the item"}],"get":{"tags":["CRM Item Attachments"],"operationId":"list-crm-item-attachments","summary":"List item attachments","security":[{"userApiKey":[]}],"description":"List the file attachments on a CRM item (returned as a bare array, no payload wrapper)","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/crm_attachment"}},"example":[{"id":1,"crm_item_id":1,"account_id":1,"file_name":"sample file name","file_type":"image","content_type":"sample content type","byte_size":12.5,"file_url":"https://example.com/resource","download_url":"https://example.com/resource","thumb_url":"https://example.com/resource","created_at":12.5}]}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"post":{"tags":["CRM Item Attachments"],"operationId":"create-a-crm-item-attachment","summary":"Create an item attachment","security":[{"userApiKey":[]}],"description":"Upload a file attachment to a CRM item (returns the bare attachment object, no payload wrapper)","requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"attachment[file]":{"type":"string","format":"binary","description":"The file to attach"}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/crm_attachment"},"example":{"id":1,"crm_item_id":1,"account_id":1,"file_name":"sample file name","file_type":"image","content_type":"sample content type","byte_size":12.5,"file_url":"https://example.com/resource","download_url":"https://example.com/resource","thumb_url":"https://example.com/resource","created_at":12.5}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/crm/items/{item_id}/attachments/{id}":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"item_id","in":"path","required":true,"schema":{"type":"number"},"description":"ID of the item"},{"name":"id","in":"path","required":true,"schema":{"type":"number"},"description":"ID of the attachment"}],"delete":{"tags":["CRM Item Attachments"],"operationId":"delete-a-crm-item-attachment","summary":"Delete an item attachment","security":[{"userApiKey":[]}],"description":"Delete a file attachment from a CRM item","responses":{"200":{"description":"Success"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"The attachment does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/crm/items/{item_id}/participants":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"item_id","in":"path","required":true,"schema":{"type":"number"},"description":"ID of the item"}],"get":{"tags":["CRM Item Participants"],"operationId":"list-crm-item-participants","summary":"List item participants","security":[{"userApiKey":[]}],"description":"List the participants (agent collaborators) of a CRM item (returned as a bare array of agent objects, no payload wrapper)","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/agent"}},"example":[{"id":1,"account_id":1,"account_user_id":1,"availability_status":"online","auto_offline":true,"confirmed":true,"email":"agent@example.com","available_name":"sample available name","name":"Sample Name","role":"agent","outbound_agent_name_header_policy":"inherit","thumbnail":"sample thumbnail","custom_role_id":1}]}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"post":{"tags":["CRM Item Participants"],"operationId":"add-crm-item-participants","summary":"Add item participants","security":[{"userApiKey":[]}],"description":"Add participants (agent collaborators) to a CRM item (returns the bare array of participant agent objects, no payload wrapper)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"user_ids":{"type":"array","description":"The user IDs to add as participants","items":{"type":"number"}}}},"example":{"user_ids":[1]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/agent"}},"example":[{"id":1,"account_id":1,"account_user_id":1,"availability_status":"online","auto_offline":true,"confirmed":true,"email":"agent@example.com","available_name":"sample available name","name":"Sample Name","role":"agent","outbound_agent_name_header_policy":"inherit","thumbnail":"sample thumbnail","custom_role_id":1}]}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"patch":{"tags":["CRM Item Participants"],"operationId":"replace-crm-item-participants","summary":"Replace item participants","security":[{"userApiKey":[]}],"description":"Replace the full set of participants on a CRM item (returns the bare array of participant agent objects, no payload wrapper)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"user_ids":{"type":"array","description":"The full set of user IDs to be participants","items":{"type":"number"}}}},"example":{"user_ids":[1]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/agent"}},"example":[{"id":1,"account_id":1,"account_user_id":1,"availability_status":"online","auto_offline":true,"confirmed":true,"email":"agent@example.com","available_name":"sample available name","name":"Sample Name","role":"agent","outbound_agent_name_header_policy":"inherit","thumbnail":"sample thumbnail","custom_role_id":1}]}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"delete":{"tags":["CRM Item Participants"],"operationId":"remove-crm-item-participants","summary":"Remove item participants","security":[{"userApiKey":[]}],"description":"Remove participants from a CRM item","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"user_ids":{"type":"array","description":"The user IDs to remove as participants","items":{"type":"number"}}}},"example":{"user_ids":[1]}}}},"responses":{"200":{"description":"Success"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"put":{"tags":["CRM Item Participants"],"operationId":"auto_put_api_v1_accounts_account_id_crm_items_item_id_participants","summary":"Update participants","description":"Updates the participant identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":["integer","null"]},"account_user_id":{"type":["integer","null"]},"availability_status":{"type":"string","enum":["online","offline","busy"],"description":"Realtime availability. Contacts report online/offline (presence-based); agents/users additionally report busy (their configured availability)."},"auto_offline":{"type":"boolean"},"confirmed":{"type":"boolean"},"email":{"type":"string","format":"email"},"provider":{"type":"string","enum":["email","google_oauth2","saml"],"description":"The authentication provider the user account was created with."},"available_name":{"type":"string"},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"name":{"type":"string"},"role":{"type":"string","enum":["agent","administrator"]},"outbound_agent_name_header_policy":{"type":["string","null"]},"thumbnail":{"type":"string"},"custom_role_id":{"type":["integer","null"]},"access_role_id":{"type":["integer","null"]}}}},"example":[{"id":1,"account_id":1,"account_user_id":1,"availability_status":"online","auto_offline":true,"confirmed":true,"email":"agent@example.com","provider":"email","available_name":"sample available name","custom_attributes":{},"name":"Sample Name","role":"agent","outbound_agent_name_header_policy":"sample outbound agent name header policy","thumbnail":"sample thumbnail","custom_role_id":1,"access_role_id":1}]}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"user_ids":{"type":"array","items":{"type":"integer"}}}},"example":{"user_ids":[1]}}}}}},"/api/v1/accounts/{account_id}/crm/items/{item_id}/checklist_items":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"item_id","in":"path","required":true,"schema":{"type":"number"},"description":"ID of the item"}],"get":{"tags":["CRM Item Checklist"],"operationId":"list-crm-item-checklist-items","summary":"List checklist items","security":[{"userApiKey":[]}],"description":"List the checklist items on a CRM item (returned as a bare array, no payload wrapper)","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/crm_checklist_item"}},"example":[{"id":1,"account_id":1,"record_type":"Crm::Item","record_id":1,"title":"Sample title","completed":true,"completed_at":12.5,"completed_by_id":1,"assignee_id":1,"due_on":"2026-01-15","position":1,"assignee":{"id":1,"account_id":1,"account_user_id":1,"availability_status":"online","auto_offline":true,"confirmed":true,"email":"agent@example.com","available_name":"sample available name","name":"Sample Name","role":"agent","outbound_agent_name_header_policy":"inherit","thumbnail":"sample thumbnail","custom_role_id":1},"created_at":12.5,"updated_at":12.5}]}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"post":{"tags":["CRM Item Checklist"],"operationId":"create-a-crm-item-checklist-item","summary":"Create a checklist item","security":[{"userApiKey":[]}],"description":"Create a checklist item on a CRM item (returns the bare checklist item object, no payload wrapper)","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/crm_checklist_item_payload"},"example":{"title":"Send proposal","assignee_id":12,"due_on":"2026-08-15"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/crm_checklist_item"},"example":{"id":1,"account_id":1,"record_type":"Crm::Item","record_id":1,"title":"Sample title","completed":true,"completed_at":12.5,"completed_by_id":1,"assignee_id":1,"due_on":"2026-01-15","position":1,"assignee":{"id":1,"account_id":1,"account_user_id":1,"availability_status":"online","auto_offline":true,"confirmed":true,"email":"agent@example.com","available_name":"sample available name","name":"Sample Name","role":"agent","outbound_agent_name_header_policy":"inherit","thumbnail":"sample thumbnail","custom_role_id":1},"created_at":12.5,"updated_at":12.5}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/crm/items/{item_id}/checklist_items/{id}":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"item_id","in":"path","required":true,"schema":{"type":"number"},"description":"ID of the item"},{"name":"id","in":"path","required":true,"schema":{"type":"number"},"description":"ID of the checklist item"}],"patch":{"tags":["CRM Item Checklist"],"operationId":"update-a-crm-item-checklist-item","summary":"Update a checklist item","security":[{"userApiKey":[]}],"description":"Update a checklist item on a CRM item (returns the bare checklist item object, no payload wrapper)","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/crm_checklist_item_payload"},"example":{"title":"Send proposal","assignee_id":12,"due_on":"2026-08-15"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/crm_checklist_item"},"example":{"id":1,"account_id":1,"record_type":"Crm::Item","record_id":1,"title":"Sample title","completed":true,"completed_at":12.5,"completed_by_id":1,"assignee_id":1,"due_on":"2026-01-15","position":1,"assignee":{"id":1,"account_id":1,"account_user_id":1,"availability_status":"online","auto_offline":true,"confirmed":true,"email":"agent@example.com","available_name":"sample available name","name":"Sample Name","role":"agent","outbound_agent_name_header_policy":"inherit","thumbnail":"sample thumbnail","custom_role_id":1},"created_at":12.5,"updated_at":12.5}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"The checklist item does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"delete":{"tags":["CRM Item Checklist"],"operationId":"delete-a-crm-item-checklist-item","summary":"Delete a checklist item","security":[{"userApiKey":[]}],"description":"Delete a checklist item from a CRM item","responses":{"200":{"description":"Success"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"The checklist item does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"put":{"tags":["CRM Item Checklist"],"operationId":"auto_put_api_v1_accounts_account_id_crm_items_item_id_checklist_items_id","summary":"Update checklist items","description":"Updates the checklist item identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"record_type":{"type":"string","enum":["Crm::Item"],"description":"The polymorphic owner type of the checklist item (a CRM deal)."},"record_id":{"type":"integer"},"title":{"type":"string"},"completed":{"type":"string"},"completed_at":{"type":["integer","null"]},"completed_by_id":{"type":"integer"},"assignee_id":{"type":"integer"},"due_on":{"type":"string"},"position":{"type":"integer"},"assignee":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":["integer","null"]},"account_user_id":{"type":["integer","null"]},"availability_status":{"type":"string","enum":["online","offline","busy"],"description":"Realtime availability. Contacts report online/offline (presence-based); agents/users additionally report busy (their configured availability)."},"auto_offline":{"type":"boolean"},"confirmed":{"type":"boolean"},"email":{"type":"string","format":"email"},"provider":{"type":"string","enum":["email","google_oauth2","saml"],"description":"Authentication provider the user signed up through."},"available_name":{"type":"string"},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"name":{"type":"string"},"role":{"type":"string","enum":["agent","administrator"]},"outbound_agent_name_header_policy":{"type":["string","null"]},"thumbnail":{"type":"string"},"custom_role_id":{"type":["integer","null"]},"access_role_id":{"type":["integer","null"]}}},"created_at":{"type":"integer"},"updated_at":{"type":"integer"}}},"example":{"id":1,"account_id":1,"record_type":"Crm::Item","record_id":1,"title":"Sample title","completed":"sample completed","completed_at":1,"completed_by_id":1,"assignee_id":1,"due_on":"sample due on","position":1,"assignee":{"id":1,"account_id":1,"account_user_id":1,"availability_status":"online","auto_offline":true,"confirmed":true,"email":"agent@example.com","provider":"email","available_name":"sample available name","custom_attributes":{},"name":"Sample Name","role":"agent","outbound_agent_name_header_policy":"sample outbound agent name header policy","thumbnail":"sample thumbnail","custom_role_id":1,"access_role_id":1},"created_at":1,"updated_at":1}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"checklist_item":{"type":"object","properties":{"title":{"type":"string"},"assignee_id":{"type":"integer"},"due_on":{"type":"string"}}}},"required":["checklist_item"]},"example":{"checklist_item":{"title":"Sample title","assignee_id":1,"due_on":"sample due on"}}}}}}},"/api/v1/accounts/{account_id}/crm/items/{item_id}/checklist_items/{id}/toggle":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"item_id","in":"path","required":true,"schema":{"type":"number"},"description":"ID of the item"},{"name":"id","in":"path","required":true,"schema":{"type":"number"},"description":"ID of the checklist item"}],"patch":{"tags":["CRM Item Checklist"],"operationId":"toggle-a-crm-item-checklist-item","summary":"Toggle a checklist item","security":[{"userApiKey":[]}],"description":"Toggle the completed state of a checklist item (returns the bare checklist item object, no payload wrapper)","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/crm_checklist_item"},"example":{"id":1,"account_id":1,"record_type":"Crm::Item","record_id":1,"title":"Sample title","completed":true,"completed_at":12.5,"completed_by_id":1,"assignee_id":1,"due_on":"2026-01-15","position":1,"assignee":{"id":1,"account_id":1,"account_user_id":1,"availability_status":"online","auto_offline":true,"confirmed":true,"email":"agent@example.com","available_name":"sample available name","name":"Sample Name","role":"agent","outbound_agent_name_header_policy":"inherit","thumbnail":"sample thumbnail","custom_role_id":1},"created_at":12.5,"updated_at":12.5}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"The checklist item does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/crm/items/{item_id}/checklist_items/{id}/reposition":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"item_id","in":"path","required":true,"schema":{"type":"number"},"description":"ID of the item"},{"name":"id","in":"path","required":true,"schema":{"type":"number"},"description":"ID of the checklist item"}],"patch":{"tags":["CRM Item Checklist"],"operationId":"reposition-a-crm-item-checklist-item","summary":"Reposition a checklist item","security":[{"userApiKey":[]}],"description":"Change the sort position of a checklist item (returns the bare checklist item object, no payload wrapper)","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/crm_item_reposition_payload"},"example":{"position":1}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/crm_checklist_item"},"example":{"id":1,"account_id":1,"record_type":"Crm::Item","record_id":1,"title":"Sample title","completed":true,"completed_at":12.5,"completed_by_id":1,"assignee_id":1,"due_on":"2026-01-15","position":1,"assignee":{"id":1,"account_id":1,"account_user_id":1,"availability_status":"online","auto_offline":true,"confirmed":true,"email":"agent@example.com","available_name":"sample available name","name":"Sample Name","role":"agent","outbound_agent_name_header_policy":"inherit","thumbnail":"sample thumbnail","custom_role_id":1},"created_at":12.5,"updated_at":12.5}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"The checklist item does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/crm/items/{item_id}/line_items/{id}":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"item_id","in":"path","required":true,"schema":{"type":"number"},"description":"ID of the item"},{"name":"id","in":"path","required":true,"schema":{"type":"number"},"description":"ID of the line item"}],"patch":{"tags":["CRM Item Line Items"],"operationId":"update-a-crm-item-line-item","summary":"Update a line item","security":[{"userApiKey":[]}],"description":"Update a line item on a CRM item (deal) — quantity, discount, unit price, etc. Editing the snapshot fields (unit_price, name_snapshot) is allowed: the snapshot belongs to the quote, not the catalog. The line total and the deal's auto value are recomputed automatically.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"line_item":{"$ref":"#/components/schemas/crm_line_item_payload"}}},"example":{"line_item":{"catalog_variant_id":1,"catalog_product_id":1,"quantity":2,"unit_price":149.9,"discount":12.5,"discount_type":"fixed","currency":"USD","name_snapshot":"sample name snapshot"}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"$ref":"#/components/schemas/crm_line_item"}}},"example":{"payload":{"id":1,"account_id":1,"crm_item_id":1,"catalog_variant_id":1,"catalog_product_id":1,"quantity":12.5,"unit_price":149.9,"discount":12.5,"discount_type":"fixed","currency":"BRL","line_total":149.9,"position":1,"name_snapshot":"sample name snapshot","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"The item or the line item does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"422":{"description":"Validation failed — quantity must be greater than 0, and the currency must match the deal's currency","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"delete":{"tags":["CRM Item Line Items"],"operationId":"delete-a-crm-item-line-item","summary":"Delete a line item","security":[{"userApiKey":[]}],"description":"Delete a line item from a CRM item (deal). The deal's auto value is recomputed from the remaining line totals","responses":{"200":{"description":"Success"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"The item or the line item does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"put":{"tags":["CRM Item Line Items"],"operationId":"auto_put_api_v1_accounts_account_id_crm_items_item_id_line_items_id","summary":"Update line items","description":"Updates the line item identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"crm_item_id":{"type":"integer"},"catalog_variant_id":{"type":"integer"},"catalog_product_id":{"type":"integer"},"quantity":{"type":"string"},"unit_price":{"type":"number"},"discount":{"type":"string"},"discount_type":{"type":"string","enum":["fixed","percent"],"description":"Whether the discount is an absolute amount or a percentage."},"currency":{"type":"string"},"line_total":{"type":"number"},"position":{"type":"integer"},"name_snapshot":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}},"example":{"payload":{"id":1,"account_id":1,"crm_item_id":1,"catalog_variant_id":1,"catalog_product_id":1,"quantity":"sample quantity","unit_price":149.9,"discount":"sample discount","discount_type":"fixed","currency":"BRL","line_total":149.9,"position":1,"name_snapshot":"sample name snapshot","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"line_item":{"type":"object","properties":{"catalog_variant_id":{"type":"integer"},"catalog_product_id":{"type":"integer"},"quantity":{"type":"string"},"unit_price":{"type":"number"},"discount":{"type":"string"},"discount_type":{"type":"string","enum":["fixed","percent"],"description":"Whether the discount is an absolute amount or a percentage."},"currency":{"type":"string"},"name_snapshot":{"type":"string"}}}},"required":["line_item"]},"example":{"line_item":{"catalog_variant_id":1,"catalog_product_id":1,"quantity":"sample quantity","unit_price":149.9,"discount":"sample discount","discount_type":"fixed","currency":"BRL","name_snapshot":"sample name snapshot"}}}}}}},"/api/v1/accounts/{account_id}/crm/items/{item_id}/line_items":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"item_id","in":"path","required":true,"schema":{"type":"number"},"description":"ID of the item"}],"get":{"tags":["CRM Item Line Items"],"operationId":"list-crm-item-line-items","summary":"List line items","security":[{"userApiKey":[]}],"description":"List the catalog line items on a CRM item (deal), ordered by position","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"$ref":"#/components/schemas/crm_line_item"}}}},"example":{"payload":[{"id":1,"account_id":1,"crm_item_id":1,"catalog_variant_id":1,"catalog_product_id":1,"quantity":12.5,"unit_price":149.9,"discount":12.5,"discount_type":"fixed","currency":"BRL","line_total":149.9,"position":1,"name_snapshot":"sample name snapshot","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"The item does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"post":{"tags":["CRM Item Line Items"],"operationId":"create-a-crm-item-line-item","summary":"Add a line item","security":[{"userApiKey":[]}],"description":"Add a catalog line item to a CRM item (deal). The variant's name, currency and price are snapshotted at add-time; the first line seeds the deal's currency. The deal's auto value is recomputed from the line totals.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"line_item":{"$ref":"#/components/schemas/crm_line_item_payload"}}},"example":{"line_item":{"catalog_variant_id":1,"catalog_product_id":1,"quantity":2,"unit_price":149.9,"discount":12.5,"discount_type":"fixed","currency":"USD","name_snapshot":"sample name snapshot"}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"$ref":"#/components/schemas/crm_line_item"}}},"example":{"payload":{"id":1,"account_id":1,"crm_item_id":1,"catalog_variant_id":1,"catalog_product_id":1,"quantity":12.5,"unit_price":149.9,"discount":12.5,"discount_type":"fixed","currency":"BRL","line_total":149.9,"position":1,"name_snapshot":"sample name snapshot","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"The item (or the given catalog variant) does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"422":{"description":"Validation failed — quantity must be greater than 0, and the currency must match the deal's currency","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/crm/organizations":{"parameters":[{"$ref":"#/components/parameters/account_id"}],"get":{"tags":["CRM Organizations"],"operationId":"list-all-crm-organizations","deprecated":true,"summary":"List all organizations","security":[{"userApiKey":[]}],"description":"Deprecated permanent alias — use the canonical list-all-organizations operation; the response payload is identical.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","description":"Array of organizations","items":{"$ref":"#/components/schemas/crm_organization"}},"meta":{"type":"object","properties":{"count":{"type":"number"},"current_page":{"type":"number"}}}}},"example":{"payload":[{"id":1,"account_id":1,"name":"Sample Name","legal_name":"sample legal name","legal_type":"individual","tax_id":"sample tax id","tax_id_type":"br_cpf","country":"BR","domain":"example.com","domains":[{"domain":"example.com","primary":true}],"website":"sample website","industry":"sample industry","size":"11-50","lifecycle_stage":"sample lifecycle stage","parent_id":1,"parent_name":"sample parent name","children_count":5,"children":[{"id":1,"name":"Sample Name","legal_name":"sample legal name","lifecycle_stage":"sample lifecycle stage","domain":"example.com"}],"owner_id":1,"owner_name":"sample owner name","thumbnail":"https://cdn.example.com/orgs/42.png","avatar_url":"https://cdn.example.com/orgs/42.png","email":"agent@example.com","phone":"+5511999998888","address":{"zip_code":"13338-705","street_name":"Av. Paulista","street_number":"1000","complement":"Sala 42","neighborhood":"Bela Vista","city":"Indaiatuba","federal_unit":"SP"},"registrations":{"state_registration":"110042490114","municipal_registration":"1234567"},"timezone":"America/Sao_Paulo","description":"A short description.","custom_attributes":{},"additional_attributes":{},"contacts_count":5,"health_score":12.5,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","field_visibility":{"tax_id":"masked","address":"hidden","email":"masked","phone":"masked"}}],"meta":{"count":5,"current_page":12.5}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"post":{"tags":["CRM Organizations"],"operationId":"create-a-crm-organization","deprecated":true,"summary":"Create an organization","security":[{"userApiKey":[]}],"description":"Deprecated permanent alias — use the canonical create-an-organization operation; the response payload is identical.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"organization":{"allOf":[{"$ref":"#/components/schemas/crm_organization_payload"},{"type":"object","properties":{"idempotent":{"type":"boolean","default":false,"description":"When true, an existing company whose name matches (trimmed, case-insensitive, among non-archived companies of this account) is RETURNED instead of a second row being created, and `reused` comes back true.","example":true}}}]}}},"example":{"organization":{"name":"Acme Corp","legal_name":"Acme Corporation LTDA","legal_type":"business","tax_id":"12.345.678/0001-95","tax_id_type":"br_cnpj","country":"BR","domain":"acme.com","domains":[{"domain":"acme.com","primary":true}],"website":"https://acme.com","avatar":"sample avatar","avatar_url":"https://cdn.example.com/orgs/42.png","industry":"SaaS","size":"11-50","lifecycle_stage":"customer","parent_id":1,"owner_id":1,"email":"contato@acme.com","phone":"+5511999999999","address":{"zip_code":"13338-705","street_name":"Av. Paulista","street_number":"1000","complement":"Sala 42","neighborhood":"Bela Vista","city":"Indaiatuba","federal_unit":"SP"},"registrations":{"state_registration":"110042490114","municipal_registration":"1234567"},"timezone":"America/Sao_Paulo","description":"A short description.","custom_attributes":{},"additional_attributes":{},"idempotent":true}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"$ref":"#/components/schemas/crm_organization"},"reused":{"type":"boolean","description":"True when an `idempotent` create matched an existing company and nothing was created.","example":false}}},"example":{"payload":{"id":1,"account_id":1,"name":"Sample Name","legal_name":"sample legal name","legal_type":"individual","tax_id":"sample tax id","tax_id_type":"br_cpf","country":"BR","domain":"example.com","domains":[{"domain":"example.com","primary":true}],"website":"sample website","industry":"sample industry","size":"11-50","lifecycle_stage":"sample lifecycle stage","parent_id":1,"parent_name":"sample parent name","children_count":5,"children":[{"id":1,"name":"Sample Name","legal_name":"sample legal name","lifecycle_stage":"sample lifecycle stage","domain":"example.com"}],"owner_id":1,"owner_name":"sample owner name","thumbnail":"https://cdn.example.com/orgs/42.png","avatar_url":"https://cdn.example.com/orgs/42.png","email":"agent@example.com","phone":"+5511999998888","address":{"zip_code":"13338-705","street_name":"Av. Paulista","street_number":"1000","complement":"Sala 42","neighborhood":"Bela Vista","city":"Indaiatuba","federal_unit":"SP"},"registrations":{"state_registration":"110042490114","municipal_registration":"1234567"},"timezone":"America/Sao_Paulo","description":"A short description.","custom_attributes":{},"additional_attributes":{},"contacts_count":5,"health_score":12.5,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","field_visibility":{"tax_id":"masked","address":"hidden","email":"masked","phone":"masked"}},"reused":false}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/crm/organizations/{id}":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"id","in":"path","required":true,"schema":{"type":"number"},"description":"ID of the organization"}],"get":{"tags":["CRM Organizations"],"operationId":"get-details-of-a-crm-organization","deprecated":true,"summary":"Get an organization","security":[{"userApiKey":[]}],"description":"Deprecated permanent alias — use the canonical get-details-of-an-organization operation; the response payload is identical.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"$ref":"#/components/schemas/crm_organization"}}},"example":{"payload":{"id":1,"account_id":1,"name":"Sample Name","legal_name":"sample legal name","legal_type":"individual","tax_id":"sample tax id","tax_id_type":"br_cpf","country":"BR","domain":"example.com","domains":[{"domain":"example.com","primary":true}],"website":"sample website","industry":"sample industry","size":"11-50","lifecycle_stage":"sample lifecycle stage","parent_id":1,"parent_name":"sample parent name","children_count":5,"children":[{"id":1,"name":"Sample Name","legal_name":"sample legal name","lifecycle_stage":"sample lifecycle stage","domain":"example.com"}],"owner_id":1,"owner_name":"sample owner name","thumbnail":"https://cdn.example.com/orgs/42.png","avatar_url":"https://cdn.example.com/orgs/42.png","email":"agent@example.com","phone":"+5511999998888","address":{"zip_code":"13338-705","street_name":"Av. Paulista","street_number":"1000","complement":"Sala 42","neighborhood":"Bela Vista","city":"Indaiatuba","federal_unit":"SP"},"registrations":{"state_registration":"110042490114","municipal_registration":"1234567"},"timezone":"America/Sao_Paulo","description":"A short description.","custom_attributes":{},"additional_attributes":{},"contacts_count":5,"health_score":12.5,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","field_visibility":{"tax_id":"masked","address":"hidden","email":"masked","phone":"masked"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"The given organization ID does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"patch":{"tags":["CRM Organizations"],"operationId":"update-a-crm-organization","deprecated":true,"summary":"Update an organization","security":[{"userApiKey":[]}],"description":"Deprecated permanent alias — use the canonical update-an-organization operation; the response payload is identical.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"organization":{"$ref":"#/components/schemas/crm_organization_payload"}}},"example":{"organization":{"name":"Acme Corp","legal_name":"Acme Corporation LTDA","legal_type":"business","tax_id":"12.345.678/0001-95","tax_id_type":"br_cnpj","country":"BR","domain":"acme.com","domains":[{"domain":"acme.com","primary":true}],"website":"https://acme.com","avatar":"sample avatar","avatar_url":"https://cdn.example.com/orgs/42.png","industry":"SaaS","size":"11-50","lifecycle_stage":"customer","parent_id":1,"owner_id":1,"email":"contato@acme.com","phone":"+5511999999999","address":{"zip_code":"13338-705","street_name":"Av. Paulista","street_number":"1000","complement":"Sala 42","neighborhood":"Bela Vista","city":"Indaiatuba","federal_unit":"SP"},"registrations":{"state_registration":"110042490114","municipal_registration":"1234567"},"timezone":"America/Sao_Paulo","description":"A short description.","custom_attributes":{},"additional_attributes":{}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"$ref":"#/components/schemas/crm_organization"}}},"example":{"payload":{"id":1,"account_id":1,"name":"Sample Name","legal_name":"sample legal name","legal_type":"individual","tax_id":"sample tax id","tax_id_type":"br_cpf","country":"BR","domain":"example.com","domains":[{"domain":"example.com","primary":true}],"website":"sample website","industry":"sample industry","size":"11-50","lifecycle_stage":"sample lifecycle stage","parent_id":1,"parent_name":"sample parent name","children_count":5,"children":[{"id":1,"name":"Sample Name","legal_name":"sample legal name","lifecycle_stage":"sample lifecycle stage","domain":"example.com"}],"owner_id":1,"owner_name":"sample owner name","thumbnail":"https://cdn.example.com/orgs/42.png","avatar_url":"https://cdn.example.com/orgs/42.png","email":"agent@example.com","phone":"+5511999998888","address":{"zip_code":"13338-705","street_name":"Av. Paulista","street_number":"1000","complement":"Sala 42","neighborhood":"Bela Vista","city":"Indaiatuba","federal_unit":"SP"},"registrations":{"state_registration":"110042490114","municipal_registration":"1234567"},"timezone":"America/Sao_Paulo","description":"A short description.","custom_attributes":{},"additional_attributes":{},"contacts_count":5,"health_score":12.5,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","field_visibility":{"tax_id":"masked","address":"hidden","email":"masked","phone":"masked"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"The given organization ID does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"delete":{"tags":["CRM Organizations"],"operationId":"delete-a-crm-organization","deprecated":true,"summary":"Delete an organization","security":[{"userApiKey":[]}],"description":"Deprecated permanent alias — use the canonical delete-an-organization operation (archives the organization); the response is identical.","responses":{"200":{"description":"Success"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"The organization does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"put":{"tags":["CRM Organizations"],"operationId":"auto_put_api_v1_accounts_account_id_crm_organizations_id","summary":"Update organizations","description":"Updates the organization identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"$ref":"#/components/schemas/crm_organization"}}},"example":{"payload":{"id":1,"account_id":1,"name":"Sample Name","legal_name":"sample legal name","legal_type":"individual","tax_id":"sample tax id","tax_id_type":"br_cpf","country":"BR","domain":"example.com","domains":[{"domain":"example.com","primary":true}],"website":"sample website","industry":"sample industry","size":"11-50","lifecycle_stage":"sample lifecycle stage","parent_id":1,"parent_name":"sample parent name","children_count":5,"children":[{"id":1,"name":"Sample Name","legal_name":"sample legal name","lifecycle_stage":"sample lifecycle stage","domain":"example.com"}],"owner_id":1,"owner_name":"sample owner name","thumbnail":"https://cdn.example.com/orgs/42.png","avatar_url":"https://cdn.example.com/orgs/42.png","email":"agent@example.com","phone":"+5511999998888","address":{"zip_code":"13338-705","street_name":"Av. Paulista","street_number":"1000","complement":"Sala 42","neighborhood":"Bela Vista","city":"Indaiatuba","federal_unit":"SP"},"registrations":{"state_registration":"110042490114","municipal_registration":"1234567"},"timezone":"America/Sao_Paulo","description":"A short description.","custom_attributes":{},"additional_attributes":{},"contacts_count":5,"health_score":12.5,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","field_visibility":{"tax_id":"masked","address":"hidden","email":"masked","phone":"masked"}}}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"organization":{"$ref":"#/components/schemas/crm_organization_payload"}}},"example":{"organization":{"name":"Acme Corp","legal_name":"Acme Corporation LTDA","legal_type":"business","tax_id":"12.345.678/0001-95","tax_id_type":"br_cnpj","country":"BR","domain":"acme.com","domains":[{"domain":"acme.com","primary":true}],"website":"https://acme.com","avatar":"sample avatar","avatar_url":"https://cdn.example.com/orgs/42.png","industry":"SaaS","size":"11-50","lifecycle_stage":"customer","parent_id":1,"owner_id":1,"email":"contato@acme.com","phone":"+5511999999999","address":{"zip_code":"13338-705","street_name":"Av. Paulista","street_number":"1000","complement":"Sala 42","neighborhood":"Bela Vista","city":"Indaiatuba","federal_unit":"SP"},"registrations":{"state_registration":"110042490114","municipal_registration":"1234567"},"timezone":"America/Sao_Paulo","description":"A short description.","custom_attributes":{},"additional_attributes":{}}}}}},"deprecated":true}},"/api/v1/accounts/{account_id}/organizations":{"parameters":[{"$ref":"#/components/parameters/account_id"}],"get":{"tags":["Organizations"],"operationId":"list-all-organizations","summary":"List all organizations","security":[{"userApiKey":[]}],"description":"List organizations in the account. Supports quick filters (search over name/domain, lifecycle_stage, industry, country, owner_id, parent_id), saved-segment payloads and whitelisted sorting. Without the page parameter the full list is returned (legacy contract); sending page opts into 25-per-page pagination.","parameters":[{"name":"search","in":"query","schema":{"type":"string"},"description":"Case-insensitive search over name and domain"},{"name":"lifecycle_stage","in":"query","schema":{"type":"string"},"description":"Filter by lifecycle stage label"},{"name":"industry","in":"query","schema":{"type":"string"},"description":"Filter by industry label"},{"name":"country","in":"query","schema":{"type":"string"},"description":"Filter by ISO 3166-1 alpha-2 country code"},{"name":"owner_id","in":"query","schema":{"type":"number"},"description":"Filter by owning agent ID"},{"name":"parent_id","in":"query","schema":{"type":"number"},"description":"Filter by parent organization ID (branches of a matriz)"},{"name":"sort","in":"query","schema":{"type":"string","enum":["name","created_at","updated_at","contacts_count","lifecycle_stage","health_score"]},"description":"Sort column (defaults to name)"},{"name":"order","in":"query","schema":{"type":"string","enum":["asc","desc"]},"description":"Sort direction (defaults to asc)"},{"name":"page","in":"query","schema":{"type":"number"},"description":"Page number — opts into 25-per-page pagination; omit for the full list"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","description":"Array of organizations","items":{"$ref":"#/components/schemas/organization"}},"meta":{"type":"object","properties":{"count":{"type":"number","description":"Total organizations matching the filters (pre-pagination)"},"current_page":{"type":"number","description":"The current page (1 when pagination was not requested)"}}}}},"example":{"payload":[{"id":1,"account_id":1,"name":"Sample Name","legal_name":"sample legal name","legal_type":"individual","tax_id":"sample tax id","tax_id_type":"br_cpf","country":"BR","domain":"example.com","domains":[{"domain":"example.com","primary":true}],"website":"sample website","industry":"sample industry","size":"11-50","lifecycle_stage":"sample lifecycle stage","parent_id":1,"parent_name":"sample parent name","children_count":5,"children":[{"id":1,"name":"Sample Name","legal_name":"sample legal name","lifecycle_stage":"sample lifecycle stage","domain":"example.com"}],"owner_id":1,"owner_name":"sample owner name","thumbnail":"https://cdn.example.com/orgs/42.png","avatar_url":"https://cdn.example.com/orgs/42.png","email":"agent@example.com","phone":"+5511999998888","address":{"zip_code":"13338-705","street_name":"Av. Paulista","street_number":"1000","complement":"Sala 42","neighborhood":"Bela Vista","city":"Indaiatuba","federal_unit":"SP"},"registrations":{"state_registration":"110042490114","municipal_registration":"1234567"},"timezone":"America/Sao_Paulo","description":"A short description.","custom_attributes":{},"additional_attributes":{},"contacts_count":5,"health_score":12.5,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","field_visibility":{"tax_id":"masked","address":"hidden","email":"masked","phone":"masked"}}],"meta":{"count":5,"current_page":12.5}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"post":{"tags":["Organizations"],"operationId":"create-an-organization","summary":"Create an organization","security":[{"userApiKey":[]}],"description":"Create an organization in the account. The fiscal identifier (tax_id) is validated against tax_id_type/country (CPF/CNPJ check digits, EIN, VAT), stored encrypted and always returned masked.\n\nSend `idempotent: true` to find-or-create by company name instead of creating blindly, and read `reused` in the response to tell the two apart.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"organization":{"allOf":[{"$ref":"#/components/schemas/organization_payload"},{"type":"object","properties":{"idempotent":{"type":"boolean","default":false,"description":"When true, an existing company whose name matches (trimmed, case-insensitive, among non-archived companies of this account) is RETURNED instead of a second row being created, and `reused` comes back true. Omitted or false keeps the historical blind create. Recommended for automated callers: `name` has neither a normalizer nor a unique index, so one trailing space or one capital letter is enough to split a company's contacts, conversations and deals between two rows.","example":true}}}]}}},"example":{"organization":{"name":"Acme Corp","legal_name":"Acme Corporation LTDA","legal_type":"business","tax_id":"12.345.678/0001-95","tax_id_type":"br_cnpj","country":"BR","domain":"acme.com","domains":[{"domain":"acme.com","primary":true}],"website":"https://acme.com","avatar":"sample avatar","avatar_url":"https://cdn.example.com/orgs/42.png","industry":"SaaS","size":"11-50","lifecycle_stage":"customer","parent_id":1,"owner_id":1,"email":"contato@acme.com","phone":"+5511999999999","address":{"zip_code":"13338-705","street_name":"Av. Paulista","street_number":"1000","complement":"Sala 42","neighborhood":"Bela Vista","city":"Indaiatuba","federal_unit":"SP"},"registrations":{"state_registration":"110042490114","municipal_registration":"1234567"},"timezone":"America/Sao_Paulo","description":"A short description.","custom_attributes":{},"additional_attributes":{},"idempotent":true}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"$ref":"#/components/schemas/organization"},"reused":{"type":"boolean","description":"True when `idempotent: true` MATCHED an existing company and nothing was created. Always present — false on every ordinary create. Callers that announce the outcome (an AI agent, an automation) must branch on it rather than assume a creation.","example":false}}},"example":{"payload":{"id":1,"account_id":1,"name":"Sample Name","legal_name":"sample legal name","legal_type":"individual","tax_id":"sample tax id","tax_id_type":"br_cpf","country":"BR","domain":"example.com","domains":[{"domain":"example.com","primary":true}],"website":"sample website","industry":"sample industry","size":"11-50","lifecycle_stage":"sample lifecycle stage","parent_id":1,"parent_name":"sample parent name","children_count":5,"children":[{"id":1,"name":"Sample Name","legal_name":"sample legal name","lifecycle_stage":"sample lifecycle stage","domain":"example.com"}],"owner_id":1,"owner_name":"sample owner name","thumbnail":"https://cdn.example.com/orgs/42.png","avatar_url":"https://cdn.example.com/orgs/42.png","email":"agent@example.com","phone":"+5511999998888","address":{"zip_code":"13338-705","street_name":"Av. Paulista","street_number":"1000","complement":"Sala 42","neighborhood":"Bela Vista","city":"Indaiatuba","federal_unit":"SP"},"registrations":{"state_registration":"110042490114","municipal_registration":"1234567"},"timezone":"America/Sao_Paulo","description":"A short description.","custom_attributes":{},"additional_attributes":{},"contacts_count":5,"health_score":12.5,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","field_visibility":{"tax_id":"masked","address":"hidden","email":"masked","phone":"masked"}},"reused":false}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"422":{"description":"Invalid attributes (e.g. fiscal identifier fails validation, hierarchy cycle)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/organizations/bulk_update":{"parameters":[{"$ref":"#/components/parameters/account_id"}],"patch":{"tags":["Organizations"],"operationId":"bulk-update-organizations","summary":"Bulk update organizations","security":[{"userApiKey":[]}],"description":"Apply one field set to many organizations at once (administrators only). Ids are account-scoped — foreign ids are simply absent from the result; a per-record failure lands in failed_ids while the rest commit. Batches are capped at 100 ids.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ids":{"type":"array","description":"Organization ids to update (capped at 100)","items":{"type":"number"}},"fields":{"type":"object","description":"The field set applied to every organization","properties":{"lifecycle_stage":{"type":"string","description":"Lifecycle stage label to set","example":"customer"},"owner_id":{"type":"number","description":"Owning agent (user) id to set"},"industry":{"type":"string","description":"Industry label to set"},"size":{"type":"string","description":"Company-size label to set"},"country":{"type":"string","description":"ISO 3166-1 alpha-2 country code to set"}}}},"required":["ids","fields"]},"example":{"ids":[1],"fields":{"lifecycle_stage":"customer","owner_id":1,"industry":"sample industry","size":"sample size","country":"BR"}}}}},"responses":{"200":{"description":"Success — the updated organizations plus the ids that failed","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","description":"The organizations updated in this batch","items":{"$ref":"#/components/schemas/organization"}},"meta":{"type":"object","properties":{"failed_ids":{"type":"array","description":"Ids whose update failed validation (the rest committed)","items":{"type":"number"}}}}}},"example":{"payload":[{"id":1,"account_id":1,"name":"Sample Name","legal_name":"sample legal name","legal_type":"individual","tax_id":"sample tax id","tax_id_type":"br_cpf","country":"BR","domain":"example.com","domains":[{"domain":"example.com","primary":true}],"website":"sample website","industry":"sample industry","size":"11-50","lifecycle_stage":"sample lifecycle stage","parent_id":1,"parent_name":"sample parent name","children_count":5,"children":[{"id":1,"name":"Sample Name","legal_name":"sample legal name","lifecycle_stage":"sample lifecycle stage","domain":"example.com"}],"owner_id":1,"owner_name":"sample owner name","thumbnail":"https://cdn.example.com/orgs/42.png","avatar_url":"https://cdn.example.com/orgs/42.png","email":"agent@example.com","phone":"+5511999998888","address":{"zip_code":"13338-705","street_name":"Av. Paulista","street_number":"1000","complement":"Sala 42","neighborhood":"Bela Vista","city":"Indaiatuba","federal_unit":"SP"},"registrations":{"state_registration":"110042490114","municipal_registration":"1234567"},"timezone":"America/Sao_Paulo","description":"A short description.","custom_attributes":{},"additional_attributes":{},"contacts_count":5,"health_score":12.5,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","field_visibility":{"tax_id":"masked","address":"hidden","email":"masked","phone":"masked"}}],"meta":{"failed_ids":[1]}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"422":{"description":"No fields to update were provided, OR the id list is over the 100-id bulk cap — in the latter case the batch is REFUSED whole and no organization is updated (the cap is never applied by silently trimming the list).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"The rejection reason"}}},"example":{"error":"sample error"}}}}}}},"/api/v1/accounts/{account_id}/organizations/bulk_archive":{"parameters":[{"$ref":"#/components/parameters/account_id"}],"post":{"tags":["Organizations"],"operationId":"bulk-archive-organizations","summary":"Bulk archive organizations","security":[{"userApiKey":[]}],"description":"Archive (soft-delete) many organizations at once (administrators only). Ids are account-scoped — foreign ids are simply absent; a per-record failure lands in failed_ids while the rest commit. Batches are capped at 100 ids — a larger list is REFUSED with 422, never silently trimmed.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ids":{"type":"array","description":"Organization ids to archive (capped at 100)","items":{"type":"number"}}},"required":["ids"]},"example":{"ids":[1]}}}},"responses":{"200":{"description":"Success — the archived organizations plus the ids that failed","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","description":"The organizations archived in this batch","items":{"$ref":"#/components/schemas/organization"}},"meta":{"type":"object","properties":{"failed_ids":{"type":"array","description":"Ids whose archive failed (the rest committed)","items":{"type":"number"}}}}}},"example":{"payload":[{"id":1,"account_id":1,"name":"Sample Name","legal_name":"sample legal name","legal_type":"individual","tax_id":"sample tax id","tax_id_type":"br_cpf","country":"BR","domain":"example.com","domains":[{"domain":"example.com","primary":true}],"website":"sample website","industry":"sample industry","size":"11-50","lifecycle_stage":"sample lifecycle stage","parent_id":1,"parent_name":"sample parent name","children_count":5,"children":[{"id":1,"name":"Sample Name","legal_name":"sample legal name","lifecycle_stage":"sample lifecycle stage","domain":"example.com"}],"owner_id":1,"owner_name":"sample owner name","thumbnail":"https://cdn.example.com/orgs/42.png","avatar_url":"https://cdn.example.com/orgs/42.png","email":"agent@example.com","phone":"+5511999998888","address":{"zip_code":"13338-705","street_name":"Av. Paulista","street_number":"1000","complement":"Sala 42","neighborhood":"Bela Vista","city":"Indaiatuba","federal_unit":"SP"},"registrations":{"state_registration":"110042490114","municipal_registration":"1234567"},"timezone":"America/Sao_Paulo","description":"A short description.","custom_attributes":{},"additional_attributes":{},"contacts_count":5,"health_score":12.5,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","field_visibility":{"tax_id":"masked","address":"hidden","email":"masked","phone":"masked"}}],"meta":{"failed_ids":[1]}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"422":{"description":"Unprocessable Entity — the id list is over the 100-id bulk cap. The batch is REFUSED whole; no organization is archived (the cap is never applied by silently trimming the list).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/organizations/{id}":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"id","in":"path","required":true,"schema":{"type":"number"},"description":"ID of the organization"}],"get":{"tags":["Organizations"],"operationId":"get-details-of-an-organization","summary":"Get an organization","security":[{"userApiKey":[]}],"description":"Get the details of an organization","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"$ref":"#/components/schemas/organization"}}},"example":{"payload":{"id":1,"account_id":1,"name":"Sample Name","legal_name":"sample legal name","legal_type":"individual","tax_id":"sample tax id","tax_id_type":"br_cpf","country":"BR","domain":"example.com","domains":[{"domain":"example.com","primary":true}],"website":"sample website","industry":"sample industry","size":"11-50","lifecycle_stage":"sample lifecycle stage","parent_id":1,"parent_name":"sample parent name","children_count":5,"children":[{"id":1,"name":"Sample Name","legal_name":"sample legal name","lifecycle_stage":"sample lifecycle stage","domain":"example.com"}],"owner_id":1,"owner_name":"sample owner name","thumbnail":"https://cdn.example.com/orgs/42.png","avatar_url":"https://cdn.example.com/orgs/42.png","email":"agent@example.com","phone":"+5511999998888","address":{"zip_code":"13338-705","street_name":"Av. Paulista","street_number":"1000","complement":"Sala 42","neighborhood":"Bela Vista","city":"Indaiatuba","federal_unit":"SP"},"registrations":{"state_registration":"110042490114","municipal_registration":"1234567"},"timezone":"America/Sao_Paulo","description":"A short description.","custom_attributes":{},"additional_attributes":{},"contacts_count":5,"health_score":12.5,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","field_visibility":{"tax_id":"masked","address":"hidden","email":"masked","phone":"masked"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"The given organization ID does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"patch":{"tags":["Organizations"],"operationId":"update-an-organization","summary":"Update an organization","security":[{"userApiKey":[]}],"description":"Update an organization's attributes. Changing parent_id re-validates the matriz/filial hierarchy (cycles and self-parenting are rejected).","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"organization":{"$ref":"#/components/schemas/organization_payload"}}},"example":{"organization":{"name":"Acme Corp","legal_name":"Acme Corporation LTDA","legal_type":"business","tax_id":"12.345.678/0001-95","tax_id_type":"br_cnpj","country":"BR","domain":"acme.com","domains":[{"domain":"acme.com","primary":true}],"website":"https://acme.com","avatar":"sample avatar","avatar_url":"https://cdn.example.com/orgs/42.png","industry":"SaaS","size":"11-50","lifecycle_stage":"customer","parent_id":1,"owner_id":1,"email":"contato@acme.com","phone":"+5511999999999","address":{"zip_code":"13338-705","street_name":"Av. Paulista","street_number":"1000","complement":"Sala 42","neighborhood":"Bela Vista","city":"Indaiatuba","federal_unit":"SP"},"registrations":{"state_registration":"110042490114","municipal_registration":"1234567"},"timezone":"America/Sao_Paulo","description":"A short description.","custom_attributes":{},"additional_attributes":{}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"$ref":"#/components/schemas/organization"}}},"example":{"payload":{"id":1,"account_id":1,"name":"Sample Name","legal_name":"sample legal name","legal_type":"individual","tax_id":"sample tax id","tax_id_type":"br_cpf","country":"BR","domain":"example.com","domains":[{"domain":"example.com","primary":true}],"website":"sample website","industry":"sample industry","size":"11-50","lifecycle_stage":"sample lifecycle stage","parent_id":1,"parent_name":"sample parent name","children_count":5,"children":[{"id":1,"name":"Sample Name","legal_name":"sample legal name","lifecycle_stage":"sample lifecycle stage","domain":"example.com"}],"owner_id":1,"owner_name":"sample owner name","thumbnail":"https://cdn.example.com/orgs/42.png","avatar_url":"https://cdn.example.com/orgs/42.png","email":"agent@example.com","phone":"+5511999998888","address":{"zip_code":"13338-705","street_name":"Av. Paulista","street_number":"1000","complement":"Sala 42","neighborhood":"Bela Vista","city":"Indaiatuba","federal_unit":"SP"},"registrations":{"state_registration":"110042490114","municipal_registration":"1234567"},"timezone":"America/Sao_Paulo","description":"A short description.","custom_attributes":{},"additional_attributes":{},"contacts_count":5,"health_score":12.5,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","field_visibility":{"tax_id":"masked","address":"hidden","email":"masked","phone":"masked"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"The given organization ID does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"422":{"description":"Invalid attributes (e.g. fiscal identifier fails validation, hierarchy cycle)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"delete":{"tags":["Organizations"],"operationId":"delete-an-organization","summary":"Delete an organization","security":[{"userApiKey":[]}],"description":"Archive (soft-delete) an organization. Contact and conversation links are preserved; the organization disappears from all reads.","responses":{"200":{"description":"Success"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"The organization does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"put":{"tags":["Organizations"],"operationId":"auto_put_api_v1_accounts_account_id_organizations_id","summary":"Update organizations","description":"Updates the organization identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"$ref":"#/components/schemas/organization"}}},"example":{"payload":{"id":1,"account_id":1,"name":"Sample Name","legal_name":"sample legal name","legal_type":"individual","tax_id":"sample tax id","tax_id_type":"br_cpf","country":"BR","domain":"example.com","domains":[{"domain":"example.com","primary":true}],"website":"sample website","industry":"sample industry","size":"11-50","lifecycle_stage":"sample lifecycle stage","parent_id":1,"parent_name":"sample parent name","children_count":5,"children":[{"id":1,"name":"Sample Name","legal_name":"sample legal name","lifecycle_stage":"sample lifecycle stage","domain":"example.com"}],"owner_id":1,"owner_name":"sample owner name","thumbnail":"https://cdn.example.com/orgs/42.png","avatar_url":"https://cdn.example.com/orgs/42.png","email":"agent@example.com","phone":"+5511999998888","address":{"zip_code":"13338-705","street_name":"Av. Paulista","street_number":"1000","complement":"Sala 42","neighborhood":"Bela Vista","city":"Indaiatuba","federal_unit":"SP"},"registrations":{"state_registration":"110042490114","municipal_registration":"1234567"},"timezone":"America/Sao_Paulo","description":"A short description.","custom_attributes":{},"additional_attributes":{},"contacts_count":5,"health_score":12.5,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","field_visibility":{"tax_id":"masked","address":"hidden","email":"masked","phone":"masked"}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"organization":{"$ref":"#/components/schemas/organization_payload"}}},"example":{"organization":{"name":"Acme Corp","legal_name":"Acme Corporation LTDA","legal_type":"business","tax_id":"12.345.678/0001-95","tax_id_type":"br_cnpj","country":"BR","domain":"acme.com","domains":[{"domain":"acme.com","primary":true}],"website":"https://acme.com","avatar":"sample avatar","avatar_url":"https://cdn.example.com/orgs/42.png","industry":"SaaS","size":"11-50","lifecycle_stage":"customer","parent_id":1,"owner_id":1,"email":"contato@acme.com","phone":"+5511999999999","address":{"zip_code":"13338-705","street_name":"Av. Paulista","street_number":"1000","complement":"Sala 42","neighborhood":"Bela Vista","city":"Indaiatuba","federal_unit":"SP"},"registrations":{"state_registration":"110042490114","municipal_registration":"1234567"},"timezone":"America/Sao_Paulo","description":"A short description.","custom_attributes":{},"additional_attributes":{}}}}}}}},"/api/v1/accounts/{account_id}/organizations/{id}/overview":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"id","in":"path","required":true,"schema":{"type":"number"},"description":"ID of the organization"}],"get":{"tags":["Organizations"],"operationId":"get-organization-overview","summary":"Get the 360 overview of an organization","security":[{"userApiKey":[]}],"description":"Get the organization together with direct 360-degree rollups computed on read. The scope includes records linked to the organization itself or to one of its contact memberships; hierarchy totals remain separate per company.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"organization":{"$ref":"#/components/schemas/organization"},"rollups":{"type":"object","description":"Direct cross-module aggregates for the organization","properties":{"scope":{"type":"object","description":"Records included in the direct 360-degree calculation","properties":{"mode":{"type":"string","enum":["direct_360"],"description":"Stable identifier for the rollup scope"},"organization_ids":{"type":"array","description":"Organization identifiers included directly","items":{"type":"integer"}},"contact_ids":{"type":"array","description":"Contact membership identifiers included in linked modules","items":{"type":"integer"}}}},"contacts":{"type":"object","properties":{"count":{"type":"integer","description":"Linked contacts count"}}},"conversations":{"type":"object","properties":{"count":{"type":"integer","description":"Conversations linked through the organization or its contacts"},"open":{"type":"integer","description":"Open conversations count"}}},"deals":{"type":"object","properties":{"open_count":{"type":"integer","description":"Open (non-archived) deals count"},"won_count":{"type":"integer","description":"Won deals count"},"open_value":{"type":"number","description":"Sum of open deals' value"}}},"tasks":{"type":"object","description":"Tasks linked to the organization, its contacts, or its deals","properties":{"count":{"type":"integer","description":"Linked non-archived tasks count"},"open":{"type":"integer","description":"Linked tasks not completed or cancelled"}}},"contracts":{"type":"object","description":"Contracts linked to the organization or its contacts","properties":{"count":{"type":"integer","description":"Linked non-archived contracts count"},"pending":{"type":"integer","description":"Linked contracts that are not in a terminal status"}}},"orders":{"type":"object","description":"Commerce orders linked to the organization or its contacts","properties":{"count":{"type":"integer","description":"Linked orders count"},"paid":{"type":"integer","description":"Paid linked orders count"},"paid_values":{"type":"object","description":"Paid order totals grouped by ISO currency code","additionalProperties":{"type":"number"}}}},"payments":{"type":"object","description":"Payment charges linked to the organization or its contacts","properties":{"count":{"type":"integer","description":"Linked non-archived charges count"},"open":{"type":"integer","description":"Pending, awaiting-payment, or overdue charges count"},"paid":{"type":"integer","description":"Confirmed or paid charges count"},"paid_values":{"type":"object","description":"Paid charge totals grouped by ISO currency code","additionalProperties":{"type":"number"}}}},"subscriptions":{"type":"object","description":"Recurring subscriptions linked to the organization or its contacts","properties":{"count":{"type":"integer","description":"Linked non-archived subscriptions count"},"live":{"type":"integer","description":"Subscriptions currently considered live"}}},"follow_ups":{"type":"object","description":"Follow-up enrollments linked through organization contacts","properties":{"count":{"type":"integer","description":"Linked follow-up enrollments count"},"live":{"type":"integer","description":"Active linked follow-up enrollments count"}}},"calendar":{"type":"object","description":"Calendar events linked to the organization or its contacts","properties":{"count":{"type":"integer","description":"Linked non-archived calendar events count"},"upcoming":{"type":"integer","description":"Future linked calendar events that are not cancelled"}}},"relationships":{"type":"object","description":"Typed relationships where the organization is either endpoint","properties":{"count":{"type":"integer","description":"Direct typed relationship count"}}},"hierarchy":{"type":"object","description":"Direct organization hierarchy summary","properties":{"children_count":{"type":"integer","description":"Non-archived direct child organizations count"}}}}}}}}},"example":{"payload":{"organization":{"id":1,"account_id":1,"name":"Sample Name","legal_name":"sample legal name","legal_type":"individual","tax_id":"sample tax id","tax_id_type":"br_cpf","country":"BR","domain":"example.com","domains":[{"domain":"example.com","primary":true}],"website":"sample website","industry":"sample industry","size":"11-50","lifecycle_stage":"sample lifecycle stage","parent_id":1,"parent_name":"sample parent name","children_count":5,"children":[{"id":1,"name":"Sample Name","legal_name":"sample legal name","lifecycle_stage":"sample lifecycle stage","domain":"example.com"}],"owner_id":1,"owner_name":"sample owner name","thumbnail":"https://cdn.example.com/orgs/42.png","avatar_url":"https://cdn.example.com/orgs/42.png","email":"agent@example.com","phone":"+5511999998888","address":{"zip_code":"13338-705","street_name":"Av. Paulista","street_number":"1000","complement":"Sala 42","neighborhood":"Bela Vista","city":"Indaiatuba","federal_unit":"SP"},"registrations":{"state_registration":"110042490114","municipal_registration":"1234567"},"timezone":"America/Sao_Paulo","description":"A short description.","custom_attributes":{},"additional_attributes":{},"contacts_count":5,"health_score":12.5,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","field_visibility":{"tax_id":"masked","address":"hidden","email":"masked","phone":"masked"}},"rollups":{"scope":{"mode":"direct_360","organization_ids":[1],"contact_ids":[1]},"contacts":{"count":5},"conversations":{"count":5,"open":1},"deals":{"open_count":5,"won_count":5,"open_value":149.9},"tasks":{"count":5,"open":1},"contracts":{"count":5,"pending":1},"orders":{"count":5,"paid":1,"paid_values":{}},"payments":{"count":5,"open":1,"paid":1,"paid_values":{}},"subscriptions":{"count":5,"live":1},"follow_ups":{"count":5,"live":1},"calendar":{"count":5,"upcoming":1},"relationships":{"count":5},"hierarchy":{"children_count":5}}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"The given organization ID does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/organizations/{organization_id}/memberships":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"organization_id","in":"path","required":true,"schema":{"type":"number"},"description":"ID of the organization"}],"get":{"tags":["Organization Memberships"],"operationId":"list-organization-memberships","summary":"List memberships of an organization","security":[{"userApiKey":[]}],"description":"List the contact memberships of an organization, primary first, with a denormalized contact summary per entry.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","description":"Array of memberships (primary first)","items":{"$ref":"#/components/schemas/organization_membership"}}}},"example":{"payload":[{"id":1,"account_id":1,"organization_id":1,"contact_id":1,"role":"sample role","title":"Sample title","primary":true,"started_on":"2026-01-15","ended_on":"2026-01-15","created_at":"2026-01-15T10:30:00.000Z","contact":{"id":1,"name":"Sample Name","email":"agent@example.com","phone_number":"+5511999998888","thumbnail":"sample thumbnail"}}]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"The given organization ID does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"post":{"tags":["Organization Memberships"],"operationId":"create-an-organization-membership","summary":"Link a contact to an organization","security":[{"userApiKey":[]}],"description":"Create a membership linking a contact to the organization with an optional role and title. Passing primary true makes it the contact's primary organization; otherwise a contact's first membership becomes primary automatically.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"membership":{"$ref":"#/components/schemas/organization_membership_payload"}}},"example":{"membership":{"contact_id":42,"role":"Responsável financeiro","title":"CFO","primary":true,"started_on":"2026-01-15","ended_on":"2026-01-15"}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"$ref":"#/components/schemas/organization_membership"}}},"example":{"payload":{"id":1,"account_id":1,"organization_id":1,"contact_id":1,"role":"sample role","title":"Sample title","primary":true,"started_on":"2026-01-15","ended_on":"2026-01-15","created_at":"2026-01-15T10:30:00.000Z","contact":{"id":1,"name":"Sample Name","email":"agent@example.com","phone_number":"+5511999998888","thumbnail":"sample thumbnail"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"The organization or the contact does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"422":{"description":"The contact is already a member of the organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/organizations/{organization_id}/memberships/{id}":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"organization_id","in":"path","required":true,"schema":{"type":"number"},"description":"ID of the organization"},{"name":"id","in":"path","required":true,"schema":{"type":"number"},"description":"ID of the membership"}],"patch":{"tags":["Organization Memberships"],"operationId":"update-an-organization-membership","summary":"Update a membership","security":[{"userApiKey":[]}],"description":"Update a membership's role, title or period. Passing primary true promotes it to the contact's primary organization; the contact cannot be changed after creation.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"membership":{"$ref":"#/components/schemas/organization_membership_payload"}}},"example":{"membership":{"contact_id":42,"role":"Responsável financeiro","title":"CFO","primary":true,"started_on":"2026-01-15","ended_on":"2026-01-15"}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"$ref":"#/components/schemas/organization_membership"}}},"example":{"payload":{"id":1,"account_id":1,"organization_id":1,"contact_id":1,"role":"sample role","title":"Sample title","primary":true,"started_on":"2026-01-15","ended_on":"2026-01-15","created_at":"2026-01-15T10:30:00.000Z","contact":{"id":1,"name":"Sample Name","email":"agent@example.com","phone_number":"+5511999998888","thumbnail":"sample thumbnail"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"The membership does not exist in the organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"delete":{"tags":["Organization Memberships"],"operationId":"delete-an-organization-membership","summary":"Unlink a contact from an organization","security":[{"userApiKey":[]}],"description":"Remove a membership. When the removed membership was the contact's primary organization, the oldest remaining membership (if any) is promoted automatically.","responses":{"200":{"description":"Success"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"The membership does not exist in the organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"put":{"tags":["Organization Memberships"],"operationId":"auto_put_api_v1_accounts_account_id_organizations_organization_id_memberships_id","summary":"Update memberships","description":"Updates the membership identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"organization_id":{"type":"integer"},"contact_id":{"type":"integer"},"role":{"type":"string","enum":["member","captain","admin"]},"title":{"type":"string"},"primary":{"type":"string"},"started_on":{"type":"string"},"ended_on":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"contact":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"email":{"type":"string","format":"email"},"phone_number":{"type":"string"},"thumbnail":{"type":"string"}}}}}}},"example":{"payload":{"id":1,"account_id":1,"organization_id":1,"contact_id":1,"role":"member","title":"Sample title","primary":"sample primary","started_on":"sample started on","ended_on":"sample ended on","created_at":"2026-01-15T10:30:00.000Z","contact":{"id":1,"name":"Sample Name","email":"agent@example.com","phone_number":"+5511999998888","thumbnail":"sample thumbnail"}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"membership":{"type":"object","properties":{"contact_id":{"type":"integer"},"role":{"type":"string","enum":["member","captain","admin"]},"title":{"type":"string"},"primary":{"type":"string","enum":["cloud","web"]},"started_on":{"type":"string"},"ended_on":{"type":"string"}}}},"required":["membership"]},"example":{"membership":{"contact_id":1,"role":"member","title":"Sample title","primary":"cloud","started_on":"sample started on","ended_on":"sample ended on"}}}}}}},"/api/v1/accounts/{account_id}/organizations/{organization_id}/memberships/{id}/set_primary":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"organization_id","in":"path","required":true,"schema":{"type":"number"},"description":"ID of the organization"},{"name":"id","in":"path","required":true,"schema":{"type":"number"},"description":"ID of the membership"}],"post":{"tags":["Organization Memberships"],"operationId":"set-primary-organization-membership","summary":"Set a membership as the contact's primary organization","security":[{"userApiKey":[]}],"description":"Promote this membership to primary for its contact. Any other primary membership of the same contact is demoted; the contact's organization link mirrors the new primary.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"$ref":"#/components/schemas/organization_membership"}}},"example":{"payload":{"id":1,"account_id":1,"organization_id":1,"contact_id":1,"role":"sample role","title":"Sample title","primary":true,"started_on":"2026-01-15","ended_on":"2026-01-15","created_at":"2026-01-15T10:30:00.000Z","contact":{"id":1,"name":"Sample Name","email":"agent@example.com","phone_number":"+5511999998888","thumbnail":"sample thumbnail"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"The membership does not exist in the organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/relationships":{"parameters":[{"$ref":"#/components/parameters/account_id"}],"get":{"tags":["Relationships"],"operationId":"list-relationships","summary":"List relationships of a subject","security":[{"userApiKey":[]}],"description":"List every relationship involving a subject (contact or organization), in both directions. Each entry includes the label seen from the subject's side and the counterpart record on the other end of the edge.","parameters":[{"name":"subject_type","in":"query","required":true,"schema":{"type":"string","enum":["Contact","Organization"]},"description":"The subject kind"},{"name":"subject_id","in":"query","required":true,"schema":{"type":"number"},"description":"The subject ID"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","description":"Array of relationships involving the subject","items":{"$ref":"#/components/schemas/relationship"}}}},"example":{"payload":[{"id":1,"account_id":1,"relationship_type":{"id":1,"name":"Sample Name","inverse_name":"sample inverse name","category":"sample category"},"source":{"type":"Contact","id":1,"name":"Sample Name"},"target":{"type":"Contact","id":1,"name":"Sample Name"},"label":"sample label","counterpart":{"type":"Contact","id":1,"name":"Sample Name"},"notes":"sample notes","started_on":"2026-01-15","ended_on":"2026-01-15","created_at":"2026-01-15T10:30:00.000Z"}]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"The subject does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"post":{"tags":["Relationships"],"operationId":"create-a-relationship","summary":"Create a relationship","security":[{"userApiKey":[]}],"description":"Create a typed edge between two subjects (contact or organization) of the account — e.g. parent ⟷ child, guarantor ⟷ tenant. Both subjects and the relationship type must belong to the account.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"relationship":{"$ref":"#/components/schemas/relationship_payload"}}},"example":{"relationship":{"relationship_type_id":7,"source_type":"Contact","source_id":42,"target_type":"Contact","target_id":43,"notes":"Responsável financeiro do aluno","started_on":"2026-02-01","ended_on":"2026-01-15"}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"$ref":"#/components/schemas/relationship"}}},"example":{"payload":{"id":1,"account_id":1,"relationship_type":{"id":1,"name":"Sample Name","inverse_name":"sample inverse name","category":"sample category"},"source":{"type":"Contact","id":1,"name":"Sample Name"},"target":{"type":"Contact","id":1,"name":"Sample Name"},"label":"sample label","counterpart":{"type":"Contact","id":1,"name":"Sample Name"},"notes":"sample notes","started_on":"2026-01-15","ended_on":"2026-01-15","created_at":"2026-01-15T10:30:00.000Z"}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"A subject or the relationship type does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"422":{"description":"Invalid edge (e.g. duplicate or self-referencing relationship)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/relationships/{id}":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"id","in":"path","required":true,"schema":{"type":"number"},"description":"ID of the relationship"}],"patch":{"tags":["Relationships"],"operationId":"update-a-relationship","summary":"Update a relationship","security":[{"userApiKey":[]}],"description":"Update a relationship's notes or period. The edge itself (type, source, target) is immutable — delete and recreate to change it.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"relationship":{"type":"object","properties":{"notes":{"type":"string","description":"Free-form notes about the relationship","example":"Responsável financeiro do aluno"},"started_on":{"type":"string","format":"date","description":"When the relationship started","example":"2026-02-01"},"ended_on":{"type":"string","format":"date","description":"When the relationship ended"}}}}},"example":{"relationship":{"notes":"Responsável financeiro do aluno","started_on":"2026-02-01","ended_on":"2026-01-15"}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"$ref":"#/components/schemas/relationship"}}},"example":{"payload":{"id":1,"account_id":1,"relationship_type":{"id":1,"name":"Sample Name","inverse_name":"sample inverse name","category":"sample category"},"source":{"type":"Contact","id":1,"name":"Sample Name"},"target":{"type":"Contact","id":1,"name":"Sample Name"},"label":"sample label","counterpart":{"type":"Contact","id":1,"name":"Sample Name"},"notes":"sample notes","started_on":"2026-01-15","ended_on":"2026-01-15","created_at":"2026-01-15T10:30:00.000Z"}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"The relationship does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"delete":{"tags":["Relationships"],"operationId":"delete-a-relationship","summary":"Delete a relationship","security":[{"userApiKey":[]}],"description":"Delete a relationship edge between two subjects","responses":{"200":{"description":"Success"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"The relationship does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"put":{"tags":["Relationships"],"operationId":"auto_put_api_v1_accounts_account_id_relationships_id","summary":"Update relationships","description":"Updates the relationship identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"relationship_type":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"inverse_name":{"type":"string"},"category":{"type":"string"}}},"source":{"type":"object","properties":{"type":{"type":"string"},"id":{"type":"integer"},"name":{"type":"string"}}},"target":{"type":"object","properties":{"type":{"type":"string"},"id":{"type":"integer"},"name":{"type":"string"}}},"label":{"type":"string"},"counterpart":{"type":"object","properties":{"type":{"type":"string"},"id":{"type":"integer"},"name":{"type":"string"}}},"notes":{"type":"string"},"started_on":{"type":"string"},"ended_on":{"type":"string"},"created_at":{"type":"string","format":"date-time"}}}}},"example":{"payload":{"id":1,"account_id":1,"relationship_type":{"id":1,"name":"Sample Name","inverse_name":"sample inverse name","category":"sample category"},"source":{"type":"sample type","id":1,"name":"Sample Name"},"target":{"type":"sample type","id":1,"name":"Sample Name"},"label":"sample label","counterpart":{"type":"sample type","id":1,"name":"Sample Name"},"notes":"sample notes","started_on":"sample started on","ended_on":"sample ended on","created_at":"2026-01-15T10:30:00.000Z"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"relationship":{"type":"object","properties":{"relationship_type_id":{"type":"integer"},"source_type":{"type":"string","enum":["Contact","Organization"]},"source_id":{"type":"integer"},"target_type":{"type":"string","enum":["Contact","Organization"]},"target_id":{"type":"integer"},"notes":{"type":"string"},"started_on":{"type":"string"},"ended_on":{"type":"string"}}}},"required":["relationship"]},"example":{"relationship":{"relationship_type_id":1,"source_type":"Contact","source_id":1,"target_type":"Contact","target_id":1,"notes":"sample notes","started_on":"sample started on","ended_on":"sample ended on"}}}}}}},"/api/v1/accounts/{account_id}/relationship_types":{"parameters":[{"$ref":"#/components/parameters/account_id"}],"get":{"tags":["Relationship Types"],"operationId":"list-relationship-types","summary":"List relationship types","security":[{"userApiKey":[]}],"description":"List the account's relationship-type catalog, ordered by name","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","description":"Array of relationship types","items":{"$ref":"#/components/schemas/relationship_type"}}}},"example":{"payload":[{"id":1,"account_id":1,"name":"Sample Name","inverse_name":"sample inverse name","category":"sample category","created_at":"2026-01-15T10:30:00.000Z"}]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"post":{"tags":["Relationship Types"],"operationId":"create-a-relationship-type","summary":"Create a relationship type","security":[{"userApiKey":[]}],"description":"Create a named relationship type with an optional inverse label (administrators only)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"relationship_type":{"$ref":"#/components/schemas/relationship_type_payload"}}},"example":{"relationship_type":{"name":"Responsável","inverse_name":"Dependente","category":"family"}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"$ref":"#/components/schemas/relationship_type"}}},"example":{"payload":{"id":1,"account_id":1,"name":"Sample Name","inverse_name":"sample inverse name","category":"sample category","created_at":"2026-01-15T10:30:00.000Z"}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"422":{"description":"Invalid attributes (e.g. duplicate name in the account)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/relationship_types/apply_preset":{"parameters":[{"$ref":"#/components/parameters/account_id"}],"post":{"tags":["Relationship Types"],"operationId":"apply-relationship-type-preset","summary":"Apply a niche preset of relationship types","security":[{"userApiKey":[]}],"description":"Idempotently seed the account with a niche-specific set of relationship types in the account's language (administrators only). Existing types with the same name are kept untouched; the full catalog is returned.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"preset":{"type":"string","enum":["escola","contabilidade","imobiliaria","clinica","agencia","b2b"],"description":"The niche preset to apply","example":"escola"}},"required":["preset"]},"example":{"preset":"escola"}}}},"responses":{"200":{"description":"Success — the full relationship-type catalog after applying the preset","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","description":"Array of relationship types","items":{"$ref":"#/components/schemas/relationship_type"}}}},"example":{"payload":[{"id":1,"account_id":1,"name":"Sample Name","inverse_name":"sample inverse name","category":"sample category","created_at":"2026-01-15T10:30:00.000Z"}]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"422":{"description":"Unknown preset","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"The rejection reason"}}},"example":{"error":"sample error"}}}}}}},"/api/v1/accounts/{account_id}/relationship_types/{id}":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"id","in":"path","required":true,"schema":{"type":"number"},"description":"ID of the relationship type"}],"patch":{"tags":["Relationship Types"],"operationId":"update-a-relationship-type","summary":"Update a relationship type","security":[{"userApiKey":[]}],"description":"Update a relationship type's labels or category (administrators only)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"relationship_type":{"$ref":"#/components/schemas/relationship_type_payload"}}},"example":{"relationship_type":{"name":"Responsável","inverse_name":"Dependente","category":"family"}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"$ref":"#/components/schemas/relationship_type"}}},"example":{"payload":{"id":1,"account_id":1,"name":"Sample Name","inverse_name":"sample inverse name","category":"sample category","created_at":"2026-01-15T10:30:00.000Z"}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"The relationship type does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"delete":{"tags":["Relationship Types"],"operationId":"delete-a-relationship-type","summary":"Delete a relationship type","security":[{"userApiKey":[]}],"description":"Delete a relationship type (administrators only). Types in use by existing relationships are refused — relationships are user data.","responses":{"200":{"description":"Success"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"The relationship type does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"422":{"description":"The type is in use by existing relationships","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Why the type could not be deleted"}}},"example":{"error":"sample error"}}}}}},"put":{"tags":["Relationship Types"],"operationId":"auto_put_api_v1_accounts_account_id_relationship_types_id","summary":"Update relationship types","description":"Updates the relationship type identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"name":{"type":"string"},"inverse_name":{"type":"string"},"category":{"type":"string"},"created_at":{"type":"string","format":"date-time"}}}}},"example":{"payload":{"id":1,"account_id":1,"name":"Sample Name","inverse_name":"sample inverse name","category":"sample category","created_at":"2026-01-15T10:30:00.000Z"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"relationship_type":{"type":"object","properties":{"name":{"type":"string"},"inverse_name":{"type":"string"},"category":{"type":"string","enum":["MARKETING","UTILITY","AUTHENTICATION"]}}}},"required":["relationship_type"]},"example":{"relationship_type":{"name":"Sample Name","inverse_name":"sample inverse name","category":"MARKETING"}}}}}}},"/api/v1/accounts/{account_id}/crm/reports":{"parameters":[{"$ref":"#/components/parameters/account_id"}],"get":{"tags":["CRM Reports"],"operationId":"get-crm-report","summary":"Get CRM analytics report","security":[{"userApiKey":[]}],"description":"Get the complete CRM analytics payload (overview, funnel, SLA, health, priority and assignee breakdowns), optionally scoped to a pipeline and a created_at date range.","parameters":[{"name":"pipeline_id","in":"query","required":false,"schema":{"type":"number"},"description":"Scope the report to a single pipeline (required for the funnel section)"},{"name":"since","in":"query","required":false,"schema":{"type":"string","format":"date"},"description":"Start of the created_at range (inclusive)"},{"name":"until","in":"query","required":false,"schema":{"type":"string","format":"date"},"description":"End of the created_at range (inclusive)"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"$ref":"#/components/schemas/crm_report"}}},"example":{"payload":{"pipeline_id":1,"since":"2026-01-15","until":"2026-01-15","overview":{"total_count":5,"open_count":5,"won_count":5,"lost_count":5,"conversion_rate":12.5,"win_rate":12.5,"avg_cycle_time":12.5,"open_value_by_currency":{},"won_value_by_currency":{},"forecast_by_currency":{}},"funnel":[{"stage_id":1,"name":"Sample Name","color":"#1F93FF","stage_type":"open","probability":12.5,"sla_in_hours":12.5,"count":5,"open_count":5,"value_by_currency":{},"forecast_by_currency":{}}],"sla":{"on_track":12.5,"due_soon":12.5,"breached":12.5,"no_sla":12.5},"health":{"healthy":12.5,"at_risk":12.5,"critical":12.5},"by_priority":{"low":12.5,"medium":12.5,"high":12.5,"urgent":12.5},"by_assignee":[{"assignee_id":1,"name":"Sample Name","open_count":5,"open_value_by_currency":{}}]}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/catalog/products":{"parameters":[{"$ref":"#/components/parameters/account_id"}],"get":{"tags":["Catalog Products"],"operationId":"list-catalog-products","summary":"List products","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"$ref":"#/components/schemas/catalog_product"}},"meta":{"type":"object","properties":{"count":{"type":"number"},"current_page":{"type":"number"}}}}},"example":{"payload":[{"id":1,"account_id":1,"name":"Sample Name","description":"A short description.","kind":"product","status":"draft","slug":"sample-slug","position":1,"external_id":"sample external id","external_source":"sample external source","catalog_category_id":1,"default_variant_id":1,"category_name":"sample category name","variants_count":5,"images_count":5,"attachments_count":5,"custom_attributes":{},"additional_attributes":{},"archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","variants":[{"id":1,"account_id":1,"catalog_product_id":1,"sku":"sample sku","name":"Sample Name","price":149.9,"currency":"BRL","compare_at_price":149.9,"track_inventory":true,"stock_quantity":1,"barcode":"sample barcode","position":1,"options":{},"default":true,"image_id":1,"image":{"id":1,"alt_text":"sample alt text","primary":true,"file_url":"https://example.com/resource","thumb_url":"https://example.com/resource"},"external_id":"sample external id","external_source":"sample external source","retailer_id":"sample retailer id","meta_validation":{},"available":true,"prices":[{"id":1,"currency":"BRL","amount":149.9,"compare_at_amount":149.9}],"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}]}],"meta":{"count":5,"current_page":12.5}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}},"description":"List products. Returns Products data for the current context."},"post":{"tags":["Catalog Products"],"operationId":"create-catalog-product","summary":"Create a product","security":[{"userApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/product_payload_wrapper"},"example":{"product":{"name":"Sample Name","description":"A short description.","kind":"product","status":"draft","catalog_category_id":1,"default_variant_id":1,"slug":"sample-slug","custom_attributes":{},"additional_attributes":{},"variants_attributes":[{"id":1,"sku":"sample sku","name":"Sample Name","price":149.9,"currency":"BRL","compare_at_price":149.9,"track_inventory":true,"stock_quantity":12.5,"barcode":"sample barcode","position":1,"options":{},"catalog_product_image_id":1,"default":true,"_destroy":true}]}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"$ref":"#/components/schemas/catalog_product"}}},"example":{"payload":{"id":1,"account_id":1,"name":"Sample Name","description":"A short description.","kind":"product","status":"draft","slug":"sample-slug","position":1,"external_id":"sample external id","external_source":"sample external source","catalog_category_id":1,"default_variant_id":1,"category_name":"sample category name","variants_count":5,"images_count":5,"attachments_count":5,"custom_attributes":{},"additional_attributes":{},"archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","variants":[{"id":1,"account_id":1,"catalog_product_id":1,"sku":"sample sku","name":"Sample Name","price":149.9,"currency":"BRL","compare_at_price":149.9,"track_inventory":true,"stock_quantity":1,"barcode":"sample barcode","position":1,"options":{},"default":true,"image_id":1,"image":{"id":1,"alt_text":"sample alt text","primary":true,"file_url":"https://example.com/resource","thumb_url":"https://example.com/resource"},"external_id":"sample external id","external_source":"sample external source","retailer_id":"sample retailer id","meta_validation":{},"available":true,"prices":[{"id":1,"currency":"BRL","amount":149.9,"compare_at_amount":149.9}],"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}]}}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}},"description":"Create a product. Submits the request payload to the Products resource and returns the result."}},"/api/v1/accounts/{account_id}/catalog/products/search":{"parameters":[{"$ref":"#/components/parameters/account_id"}],"get":{"tags":["Catalog Products"],"operationId":"search-catalog-products","summary":"Search products (read-only, Maestro)","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"$ref":"#/components/schemas/catalog_product"}},"meta":{"type":"object","properties":{"count":{"type":"number"},"current_page":{"type":"number"}}}}},"example":{"payload":[{"id":1,"account_id":1,"name":"Sample Name","description":"A short description.","kind":"product","status":"draft","slug":"sample-slug","position":1,"external_id":"sample external id","external_source":"sample external source","catalog_category_id":1,"default_variant_id":1,"category_name":"sample category name","variants_count":5,"images_count":5,"attachments_count":5,"custom_attributes":{},"additional_attributes":{},"archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","variants":[{"id":1,"account_id":1,"catalog_product_id":1,"sku":"sample sku","name":"Sample Name","price":149.9,"currency":"BRL","compare_at_price":149.9,"track_inventory":true,"stock_quantity":1,"barcode":"sample barcode","position":1,"options":{},"default":true,"image_id":1,"image":{"id":1,"alt_text":"sample alt text","primary":true,"file_url":"https://example.com/resource","thumb_url":"https://example.com/resource"},"external_id":"sample external id","external_source":"sample external source","retailer_id":"sample retailer id","meta_validation":{},"available":true,"prices":[{"id":1,"currency":"BRL","amount":149.9,"compare_at_amount":149.9}],"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}]}],"meta":{"count":5,"current_page":12.5}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}},"description":"Search products (read-only, Maestro). Returns Search data for the current context."}},"/api/v1/accounts/{account_id}/catalog/products/bulk_destroy":{"parameters":[{"$ref":"#/components/parameters/account_id"}],"post":{"tags":["Catalog Products"],"operationId":"bulk-destroy-catalog-products","summary":"Soft-delete many products","description":"Archives every product whose id is submitted, moving it out of the active listing and into the archived view. Only products currently active or draft are affected — ids that are already archived, or that belong to another account, are silently skipped. The response echoes the ids that were actually archived, so a client can reconcile its selection against what really changed. At most 500 ids per call.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The ids of the products that were archived.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"destroyed_ids":{"type":"array","description":"Ids archived by this call. Skipped ids are absent.","items":{"type":"integer"}}}}}},"example":{"payload":{"destroyed_ids":[88,91,104]}}}}},"422":{"description":"More than 500 ids were submitted in a single call.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Why the bulk request was rejected."}}},"example":{"error":"You can only perform this action on up to 500 records at a time."}}}}}}},"/api/v1/accounts/{account_id}/catalog/products/bulk_purge":{"parameters":[{"$ref":"#/components/parameters/account_id"}],"post":{"tags":["Catalog Products"],"operationId":"bulk-purge-catalog-products","summary":"Permanently delete many archived products","security":[{"userApiKey":[]}],"description":"Permanently delete a selection of archived products (and their owned records). Scoped to the archived bin; capped at 500 ids per request.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"purged_ids":{"type":"array","items":{"type":"number"}}}},"meta":{"type":"object","properties":{"updated":{"type":"number"},"failed":{"type":"number"},"failed_ids":{"type":"array","items":{"type":"number"}}}}}},"example":{"payload":{"purged_ids":[1]},"meta":{"updated":12.5,"failed":12.5,"failed_ids":[1]}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/catalog/products/import":{"parameters":[{"$ref":"#/components/parameters/account_id"}],"post":{"tags":["Catalog Products"],"operationId":"import-catalog","summary":"Import products from a CSV/JSONL file (admin)","description":"Accepts an uploaded CSV or JSONL file and registers a sync run that processes it in the background, so the call returns `202 Accepted` immediately instead of waiting for the import. The response carries the id of that run — poll the sync runs resource with it to follow progress, counters and per-row errors. Sending `dry_run` validates the file and reports what would happen without writing any product.","security":[{"userApiKey":[]}],"responses":{"202":{"description":"Import accepted. The returned run id tracks the background processing.","content":{"application/json":{"schema":{"type":"object","properties":{"run_id":{"type":"integer","description":"Id of the sync run created for this import; poll it for status and counters."}}},"example":{"run_id":3312}}}},"422":{"description":"No file was attached to the request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Why the import could not be started."}}},"example":{"error":"Select a file to import."}}}}}}},"/api/v1/accounts/{account_id}/catalog/products/export":{"parameters":[{"$ref":"#/components/parameters/account_id"}],"post":{"tags":["Catalog Products"],"operationId":"export-catalog","summary":"Export the catalog to CSV/JSONL (admin)","description":"Registers a sync run that builds the export off the request and delivers it to the requesting user, so the call returns `202 Accepted` immediately rather than streaming a file. The same filters the product listing accepts (kind, status, category, archived) narrow what is exported. The response carries the id of that run — poll the sync runs resource with it to follow progress and to reach the produced file.","security":[{"userApiKey":[]}],"responses":{"202":{"description":"Export accepted. The returned run id tracks the background generation.","content":{"application/json":{"schema":{"type":"object","properties":{"run_id":{"type":"integer","description":"Id of the sync run created for this export; poll it for status and the produced file."}}},"example":{"run_id":3317}}}}}}},"/api/v1/accounts/{account_id}/catalog/products/import_template":{"parameters":[{"$ref":"#/components/parameters/account_id"}],"get":{"tags":["Catalog Products"],"operationId":"catalog-import-template","summary":"Download a sample import file (admin)","description":"Returns a ready-to-edit sample file showing every column the product import understands, filled with one example row. This is a FILE DOWNLOAD, not a JSON document — the body is the file itself, served as an attachment. Asking for the `jsonl` format yields newline-delimited JSON; any other value yields CSV.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The sample file, served as a download attachment.","content":{"text/csv":{"schema":{"type":"string","description":"Comma-separated sample, one product per row, header line first."},"example":"name,description,kind,status,sku,price,currency,stock_quantity\nCamiseta Premium,Algodão penteado 30.1,product,active,CAM-PRETA-M,129.90,BRL,24\n"},"application/x-ndjson":{"schema":{"type":"string","description":"Newline-delimited JSON sample, one product object per line."},"example":"{\"name\":\"Camiseta Premium\",\"kind\":\"product\",\"status\":\"active\",\"sku\":\"CAM-PRETA-M\",\"price\":\"129.90\",\"currency\":\"BRL\",\"stock_quantity\":24}\n"}}}}}},"/api/v1/accounts/{account_id}/catalog/products/{id}":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"id","in":"path","required":true,"schema":{"type":"number"}}],"get":{"tags":["Catalog Products"],"operationId":"get-catalog-product","summary":"Get a product","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"$ref":"#/components/schemas/catalog_product"}}},"example":{"payload":{"id":1,"account_id":1,"name":"Sample Name","description":"A short description.","kind":"product","status":"draft","slug":"sample-slug","position":1,"external_id":"sample external id","external_source":"sample external source","catalog_category_id":1,"default_variant_id":1,"category_name":"sample category name","variants_count":5,"images_count":5,"attachments_count":5,"custom_attributes":{},"additional_attributes":{},"archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","variants":[{"id":1,"account_id":1,"catalog_product_id":1,"sku":"sample sku","name":"Sample Name","price":149.9,"currency":"BRL","compare_at_price":149.9,"track_inventory":true,"stock_quantity":1,"barcode":"sample barcode","position":1,"options":{},"default":true,"image_id":1,"image":{"id":1,"alt_text":"sample alt text","primary":true,"file_url":"https://example.com/resource","thumb_url":"https://example.com/resource"},"external_id":"sample external id","external_source":"sample external source","retailer_id":"sample retailer id","meta_validation":{},"available":true,"prices":[{"id":1,"currency":"BRL","amount":149.9,"compare_at_amount":149.9}],"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}]}}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}},"description":"Get a product. Returns the requested Products resource."},"patch":{"tags":["Catalog Products"],"operationId":"update-catalog-product","summary":"Update a product","security":[{"userApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/product_payload_wrapper"},"example":{"product":{"name":"Sample Name","description":"A short description.","kind":"product","status":"draft","catalog_category_id":1,"default_variant_id":1,"slug":"sample-slug","custom_attributes":{},"additional_attributes":{},"variants_attributes":[{"id":1,"sku":"sample sku","name":"Sample Name","price":149.9,"currency":"BRL","compare_at_price":149.9,"track_inventory":true,"stock_quantity":12.5,"barcode":"sample barcode","position":1,"options":{},"catalog_product_image_id":1,"default":true,"_destroy":true}]}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"$ref":"#/components/schemas/catalog_product"}}},"example":{"payload":{"id":1,"account_id":1,"name":"Sample Name","description":"A short description.","kind":"product","status":"draft","slug":"sample-slug","position":1,"external_id":"sample external id","external_source":"sample external source","catalog_category_id":1,"default_variant_id":1,"category_name":"sample category name","variants_count":5,"images_count":5,"attachments_count":5,"custom_attributes":{},"additional_attributes":{},"archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","variants":[{"id":1,"account_id":1,"catalog_product_id":1,"sku":"sample sku","name":"Sample Name","price":149.9,"currency":"BRL","compare_at_price":149.9,"track_inventory":true,"stock_quantity":1,"barcode":"sample barcode","position":1,"options":{},"default":true,"image_id":1,"image":{"id":1,"alt_text":"sample alt text","primary":true,"file_url":"https://example.com/resource","thumb_url":"https://example.com/resource"},"external_id":"sample external id","external_source":"sample external source","retailer_id":"sample retailer id","meta_validation":{},"available":true,"prices":[{"id":1,"currency":"BRL","amount":149.9,"compare_at_amount":149.9}],"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}]}}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}},"description":"Update a product. Applies the submitted changes to the Products resource."},"delete":{"tags":["Catalog Products"],"operationId":"delete-catalog-product","summary":"Soft-delete (archive) a product","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Success"}},"description":"Soft-delete (archive) a product. Removes the targeted Products resource."},"put":{"tags":["Catalog Products"],"operationId":"auto_put_api_v1_accounts_account_id_catalog_products_id","summary":"Update products","description":"Updates the product identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"kind":{"type":"string","enum":["product","service"]},"status":{"type":"string","enum":["draft","active","archived"]},"slug":{"type":"string"},"position":{"type":"integer"},"external_id":{"type":"integer"},"external_source":{"type":"string"},"external_url":{"type":"string"},"condition":{"type":"string"},"brand":{"type":"string"},"catalog_category_id":{"type":"integer"},"default_variant_id":{"type":"integer"},"variants_count":{"type":"integer"},"images_count":{"type":"integer"},"attachments_count":{"type":"integer"},"checklist_progress":{"type":"object","properties":{"done":{"type":"string"},"total":{"type":"number"}}},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"additional_attributes":{"type":"object","additionalProperties":true,"description":"Channel- and source-specific metadata for this record (e.g. browser info, referer, social profile identifiers). The key set depends on the originating channel."},"archived_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"category_name":{"type":["string","null"]},"variants":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"catalog_product_id":{"type":"integer"},"sku":{"type":"string"},"name":{"type":"string"},"price":{"type":"number"},"currency":{"type":"string"},"compare_at_price":{"type":"number"},"track_inventory":{"type":"string"},"stock_quantity":{"type":"string"},"barcode":{"type":"string"},"position":{"type":"integer"},"options":{"type":"string"},"default":{"type":"integer"},"image_id":{"type":"integer"},"external_id":{"type":"integer"},"external_source":{"type":"string"},"retailer_id":{"type":"integer"},"meta_validation":{"type":"object","properties":{"set":{"type":"object","properties":{"merge":{"type":"boolean"},"source_name":{"type":"string"}}}}},"available":{"type":"boolean"},"image":{"type":"string"},"prices":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"currency":{"type":"string"},"amount":{"type":"number"},"compare_at_amount":{"type":"number"}}}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}},"images":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"catalog_product_id":{"type":"integer"},"primary":{"type":"string"},"position":{"type":"integer"},"alt_text":{"type":"string"},"file_url":{"type":"string"},"thumb_url":{"type":"string"},"media_deleted":{"type":["boolean","null"]},"deleted_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}}}}},"example":{"payload":{"id":1,"account_id":1,"name":"Sample Name","description":"A short description.","kind":"product","status":"draft","slug":"sample-slug","position":1,"external_id":1,"external_source":"sample external source","external_url":"https://example.com/resource","condition":"sample condition","brand":"sample brand","catalog_category_id":1,"default_variant_id":1,"variants_count":5,"images_count":5,"attachments_count":5,"checklist_progress":{"done":"sample done","total":149.9},"custom_attributes":{},"additional_attributes":{},"archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","category_name":"sample category name","variants":[{"id":1,"account_id":1,"catalog_product_id":1,"sku":"sample sku","name":"Sample Name","price":149.9,"currency":"BRL","compare_at_price":149.9,"track_inventory":"sample track inventory","stock_quantity":"sample stock quantity","barcode":"sample barcode","position":1,"options":"sample options","default":1,"image_id":1,"external_id":1,"external_source":"sample external source","retailer_id":1,"meta_validation":{"set":{"merge":true,"source_name":"sample source name"}},"available":true,"image":"sample image","prices":[{"id":1,"currency":"BRL","amount":149.9,"compare_at_amount":149.9}],"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}],"images":[{"id":1,"account_id":1,"catalog_product_id":1,"primary":"sample primary","position":1,"alt_text":"sample alt text","file_url":"https://example.com/resource","thumb_url":"https://example.com/resource","media_deleted":true,"deleted_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"product":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"kind":{"type":"string","enum":["product","service"]},"status":{"type":"string","enum":["draft","active","archived"]},"catalog_category_id":{"type":"integer"},"default_variant_id":{"type":"integer"},"slug":{"type":"string"},"position":{"type":"integer"},"brand":{"type":"string"},"external_url":{"type":"string"},"condition":{"type":"string"},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"additional_attributes":{"type":"object","additionalProperties":true,"description":"Channel- and source-specific metadata for this record (e.g. browser info, referer, social profile identifiers). The key set depends on the originating channel."},"variants_attributes":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Free-form object."}}}}},"required":["product"]},"example":{"product":{"name":"Sample Name","description":"A short description.","kind":"product","status":"draft","catalog_category_id":1,"default_variant_id":1,"slug":"sample-slug","position":1,"brand":"sample brand","external_url":"https://example.com/resource","condition":"sample condition","custom_attributes":{},"additional_attributes":{},"variants_attributes":[{}]}}}}}}},"/api/v1/accounts/{account_id}/catalog/products/{id}/purge":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"id","in":"path","required":true,"schema":{"type":"number"}}],"delete":{"tags":["Catalog Products"],"operationId":"purge-a-catalog-product","summary":"Permanently delete an archived product","security":[{"userApiKey":[]}],"description":"Permanently delete an archived product (and its owned variants, images, attachments, checklist items and events). The product must already be archived; catalog references on existing quote line items are nullified, preserving the quote snapshot.","responses":{"200":{"description":"Success"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"422":{"description":"The product must be archived before it can be purged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"The product does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/catalog/products/{id}/send_to_conversation":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"id","in":"path","required":true,"schema":{"type":"number"}}],"post":{"tags":["Catalog Products"],"operationId":"send-product-to-conversation","summary":"Send a product into a conversation","description":"Posts this product into the given conversation as an outgoing message. Sending extra `product_ids` turns it into a multi-product message with the path product first. For one product, `variant_id` and `currency` select the exact variation and price. For multiple products, `variant_ids` and `currencies` are aligned with `product_ids`, so each displayed option is the one sent. `mode` chooses between a single item, a list or the whole catalog. On a WhatsApp Cloud inbox bound to a commerce catalog the message goes out as a native product message only when every selected variation has its own retailer id and uses its published currency; otherwise it degrades to the exact rich card. WhatsApp Web uses an interactive product card with reply and optional product-link buttons. The conversation is addressed by its display id and resolved inside the account. Returns the queued message JSON including its id and commercial validation snapshot. Human callers must have access to the conversation and its writable target. Bot callers must authenticate as the active bot bound to the logical inbox.","security":[{"userApiKey":[]}],"parameters":[{"name":"X-Chatwoot-Message-Author","in":"header","required":false,"schema":{"type":"string","enum":["agent_bot"]},"description":"Optional assertion requiring authenticated AgentBot credentials. This header alone does not authenticate a caller."},{"name":"X-Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Stable caller key for retrying this exact product-card send without creating another message."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["conversation_id"],"properties":{"conversation_id":{"oneOf":[{"type":"integer"},{"type":"string"}],"description":"Conversation display id or account-scoped database id."},"variant_id":{"type":"integer","description":"Kept variation selected for a single-product send."},"currency":{"type":"string","pattern":"^[A-Z]{3}$","description":"Currency selected for the single variation."},"product_ids":{"type":"array","maxItems":30,"uniqueItems":true,"items":{"type":"integer"},"description":"Ordered product selection, including the product from the path."},"variant_ids":{"type":"array","maxItems":30,"items":{"type":["integer","null"]},"description":"Variation ids aligned by index with product_ids; null uses that product's kept default."},"currencies":{"type":"array","maxItems":30,"items":{"type":["string","null"],"pattern":"^[A-Z]{3}$"},"description":"Currency codes aligned by index with product_ids; null uses that variation's base currency."},"mode":{"type":"string","enum":["single","list","catalog"]}}},"example":{"conversation_id":1042,"product_ids":[81,96],"variant_ids":[303,418],"currencies":["BRL","BRL"],"mode":"list","variant_id":1,"currency":"BRL"}}}},"responses":{"200":{"description":"Message queued, not delivery confirmation. Returns the message including id, content and content_attributes.catalog_product. commercial_validation contains validated (boolean), source (catalog), checked_at (ISO 8601), and products (the rendered catalog snapshots, with id, variant_id, price, currency and available). Rejected stock, price or media creates no message.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/message"},{"type":"object","properties":{"content_attributes":{"type":"object","properties":{"catalog_product":{"type":"object","properties":{"commercial_validation":{"type":"object","required":["validated","source","checked_at","products"],"properties":{"validated":{"type":"boolean"},"source":{"type":"string","enum":["catalog"]},"checked_at":{"type":"string","format":"date-time"},"products":{"type":"array","items":{"type":"object","required":["id","available"],"properties":{"id":{"type":"integer"},"variant_id":{"type":"integer"},"available":{"type":"boolean"},"price":{"oneOf":[{"type":"number"},{"type":"string"}]},"currency":{"type":"string"}}}}}}}}}}}}]},"example":{"id":2048,"content":"Available product — BRL 149.90","message_type":1,"private":false,"sender_type":"AgentBot","content_attributes":{"catalog_product":{"commercial_validation":{"validated":true,"source":"catalog","checked_at":"2026-09-07T10:30:00Z","products":[{"id":81,"variant_id":303,"available":true,"price":"149.90","currency":"BRL"}]}},"instagram_mention":{"media_id":"sample media id","comment_id":"sample comment id","mention_type":"comment","enrichment_status":"unresolved","replyable":true,"author_id":"sample author id","author_username":"sample author username","text":"sample text","media_type":"sample media type","media_product_type":"sample media product type","permalink":"https://example.com/resource","identity_scope":{"account_id":1,"inbox_id":1,"instagram_id":"sample instagram id"},"recovery":{"state":"scheduled","reason":"Sample reason.","attempts":1,"checked_at":"2026-01-15T10:30:00.000Z","next_retry_at":"2026-01-15T10:30:00.000Z","lease_until":"2026-01-15T10:30:00.000Z"}},"translations":{},"translation":{"original_content":"sample original content","original_html_content":"sample original html content","delivery":{"status":"translated","source_language":"pt","target_language":"en","provider":"google_translate","content_digest":"sample content digest","translated_at":"2026-01-15T10:30:00.000Z","error_code":"translation_failed","cause_code":"provider_not_configured","failed_at":"2026-01-15T10:30:00.000Z"},"views":{}},"external_error":"sample external error","contact_share":{"origin":"contact_request","transport":"cloud","status":"linked","reason":"identity_owned_by_another_contact","other_contact_ids":[1],"reconciliation_id":"sample reconciliation id"}},"client_message_id":"sample client message id","client_message_actor":"User:7","outbound_dispatch":{"state":"queued","retryable":true},"content_readiness":{"state":"waiting","quality":"pending","generation":1,"content_version":1},"account_id":1,"inbox_id":1,"logical_inbox_id":1,"echo_id":"sample echo id","conversation_id":1,"created_at":1,"updated_at":1,"status":"sent","source_id":"sample source id","content_type":"text","sender_id":1,"external_source_ids":{},"additional_attributes":{},"processed_message_content":"sample processed message content","sentiment":{},"conversation":{},"attachment":{},"attachments":[{"id":1,"message_id":1,"file_type":"image","account_id":1,"extension":"sample extension","data_url":"https://example.com/resource","media_readiness_revision":"sample media readiness revision","playable_audio_url":"https://example.com/resource","playable_video_url":"https://example.com/resource","video_processing":true,"video_unavailable":true,"thumb_url":"https://example.com/resource","file_size":1,"width":1,"height":1,"coordinates_lat":12.5,"coordinates_long":12.5,"fallback_title":"sample fallback title","meta":{},"transcribed_text":"sample transcribed text","transcript_translations":{"pt-BR":"Você pode me ajudar?","es":"¿Puedes ayudarme?"},"transcript_translation_states":{}}],"sender":{}}}}},"401":{"description":"Missing or invalid credentials, unauthorized conversation, inactive bot binding, or invalid author assertion."},"404":{"description":"The conversation, a selected kept product, or a selected kept variation does not belong to this account/selection."},"422":{"description":"The selection is unavailable, its price is invalid, or its image cannot be prepared for the channel. No message is created.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Localized explanation for the operator."},"code":{"type":"string","enum":["catalog_variant_unavailable","catalog_product_unavailable","catalog_image_unprocessable","catalog_price_invalid"]}}},"example":{"error":"The selected variation is unavailable. Choose an available variation.","code":"catalog_variant_unavailable"}}}}}}},"/api/v1/accounts/{account_id}/catalog/products/{product_id}/variants":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"product_id","in":"path","required":true,"schema":{"type":"number"}}],"get":{"tags":["Catalog Variants"],"operationId":"list-catalog-variants","summary":"List variants of a product","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"$ref":"#/components/schemas/catalog_variant"}}}},"example":{"payload":[{"id":1,"account_id":1,"catalog_product_id":1,"sku":"sample sku","name":"Sample Name","price":149.9,"currency":"BRL","compare_at_price":149.9,"track_inventory":true,"stock_quantity":1,"barcode":"sample barcode","position":1,"options":{},"default":true,"image_id":1,"image":{"id":1,"alt_text":"sample alt text","primary":true,"file_url":"https://example.com/resource","thumb_url":"https://example.com/resource"},"external_id":"sample external id","external_source":"sample external source","retailer_id":"sample retailer id","meta_validation":{},"available":true,"prices":[{"id":1,"currency":"BRL","amount":149.9,"compare_at_amount":149.9}],"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}},"description":"List variants of a product. Returns Variants data for the current context."},"post":{"tags":["Catalog Variants"],"operationId":"create-catalog-variant","summary":"Create a variant","description":"Adds a sellable variant (name, named options, display position, SKU, price and optional stock) to the product named in the path and records a `variant_added` entry on the product timeline. The optional `catalog_product_image_id` must identify an image in that same product; otherwise the primary product image is used. `default: true` selects the new row as the product default, while the first variant becomes the default automatically. Per-currency overrides can be created in the same call through nested price rows. Answers `200 OK` with the persisted variant wrapped in `payload`. Requires update permission on the parent product.","security":[{"userApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/variant_payload_wrapper"},"example":{"variant":{"sku":"KIT-PREM-500","name":"500ml","price":149.9,"currency":"BRL","compare_at_price":189.9,"track_inventory":true,"stock_quantity":24,"barcode":"7891234567895","position":0,"catalog_product_image_id":731,"default":true,"options":{"Size":"500ml"},"prices_attributes":[{"currency":"USD","amount":29.9,"compare_at_amount":37.9,"id":1,"_destroy":true}]}}}}},"responses":{"200":{"description":"Variant created. The body carries the persisted row.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["payload"],"properties":{"payload":{"$ref":"#/components/schemas/catalog_variant"}}},"example":{"payload":{"id":8871,"account_id":41,"catalog_product_id":3312,"sku":"KIT-PREM-500","name":"500ml","price":149.9,"currency":"BRL","compare_at_price":189.9,"track_inventory":true,"stock_quantity":24,"barcode":"7891234567895","position":0,"options":{"Size":"500ml"},"default":true,"image_id":731,"image":{"id":731,"alt_text":"Premium kit bottle","primary":false,"file_url":"https://app.example.test/rails/active_storage/blobs/variant.png","thumb_url":"https://app.example.test/rails/active_storage/representations/variant.png"},"external_id":null,"external_source":null,"retailer_id":null,"meta_validation":{},"available":true,"prices":[{"id":512,"currency":"USD","amount":29.9,"compare_at_amount":37.9}],"created_at":"2026-07-27T12:04:31.000Z","updated_at":"2026-07-27T12:04:31.000Z"}}}}},"401":{"description":"The current user may not update this product.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","description":"Why the request was refused."}}},"example":{"error":"You are not authorized to do this action"}}}},"404":{"description":"No such product in this account.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","description":"Why the record could not be resolved."}}},"example":{"error":"Resource could not be found"}}}},"422":{"description":"The submitted variant failed validation and was not created.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["message","attributes"],"properties":{"message":{"type":"string","description":"All validation failures joined into one sentence."},"attributes":{"type":"array","description":"The variant attributes that failed validation.","items":{"type":"string"}}}},"example":{"message":"Image must belong to this product and account","attributes":["image"]}}}}}}},"/api/v1/accounts/{account_id}/catalog/products/{product_id}/variants/{id}":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"product_id","in":"path","required":true,"schema":{"type":"number"}},{"name":"id","in":"path","required":true,"schema":{"type":"number"}}],"patch":{"tags":["Catalog Variants"],"operationId":"update-catalog-variant","summary":"Update a variant","description":"Applies the submitted attributes to one variant of the product named in the path, including its name, named options, position and an image from that same product gallery. `default: true` selects this active row as the product default. Nested price rows can be added, edited or removed in the same call. Whenever the base price actually changes, a `price_changed` entry carrying the previous and new amounts is appended to the product timeline. Answers `200 OK` with the variant after the write, wrapped in `payload`. Requires update permission on the parent product.","security":[{"userApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/variant_payload_wrapper"},"example":{"variant":{"sku":"KIT-PREM-500","name":"500ml","price":129.9,"currency":"BRL","compare_at_price":189.9,"track_inventory":true,"stock_quantity":24,"barcode":"7891234567895","position":0,"catalog_product_image_id":731,"default":true,"options":{"Size":"500ml"},"prices_attributes":[{"id":512,"currency":"USD","amount":25.9,"compare_at_amount":37.9,"_destroy":false}]}}}}},"responses":{"200":{"description":"Variant updated. The body carries the row as it stands after the write.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["payload"],"properties":{"payload":{"$ref":"#/components/schemas/catalog_variant"}}},"example":{"payload":{"id":8871,"account_id":41,"catalog_product_id":3312,"sku":"KIT-PREM-500","name":"500ml","price":129.9,"currency":"BRL","compare_at_price":189.9,"track_inventory":true,"stock_quantity":24,"barcode":"7891234567895","position":0,"options":{"Size":"500ml"},"default":true,"image_id":731,"image":{"id":731,"alt_text":"Premium kit bottle","primary":false,"file_url":"https://app.example.test/rails/active_storage/blobs/variant.png","thumb_url":"https://app.example.test/rails/active_storage/representations/variant.png"},"external_id":null,"external_source":null,"retailer_id":"cw_v_8871","meta_validation":{"meta_catalog_91":{"status":"validated","error":null,"handle":"batch-4b7f","checked_at":"2026-07-27T12:04:20.000Z","source_name":"WhatsApp Business"}},"available":true,"prices":[{"id":512,"currency":"USD","amount":25.9,"compare_at_amount":37.9}],"created_at":"2026-07-20T09:11:02.000Z","updated_at":"2026-07-27T12:04:31.000Z"}}}}},"401":{"description":"The current user may not update this product.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","description":"Why the request was refused."}}},"example":{"error":"You are not authorized to do this action"}}}},"404":{"description":"No such product in this account, or no such variant under it.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","description":"Why the record could not be resolved."}}},"example":{"error":"Resource could not be found"}}}},"422":{"description":"The submitted attributes failed validation and nothing was written.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["message","attributes"],"properties":{"message":{"type":"string","description":"All validation failures joined into one sentence."},"attributes":{"type":"array","description":"The variant attributes that failed validation.","items":{"type":"string"}}}},"example":{"message":"Options must contain bounded named text values","attributes":["options"]}}}}}},"delete":{"tags":["Catalog Variants"],"operationId":"delete-catalog-variant","summary":"Archive a variant","description":"Archives this active variant under the account-scoped parent product. The product's current default variant cannot be archived: select another active default first. The operation never deletes the product or another product's variation.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Variant archived."},"404":{"description":"No such product in this account, or no such variant under it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"422":{"description":"The current default variant must be reassigned before it can be archived.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"attributes":{"type":"array","items":{"type":"string"}}}},"example":{"message":"Archived at cannot be archived or deleted until another default variant is selected","attributes":["archived_at"]}}}}}},"get":{"tags":["Catalog Variants"],"operationId":"auto_get_api_v1_accounts_account_id_catalog_products_product_id_variants_id","summary":"Get variants","description":"Returns the variant identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"catalog_product_id":{"type":"integer"},"sku":{"type":"string"},"name":{"type":"string"},"price":{"type":"number"},"currency":{"type":"string"},"compare_at_price":{"type":"number"},"track_inventory":{"type":"string"},"stock_quantity":{"type":"string"},"barcode":{"type":"string"},"position":{"type":"integer"},"options":{"type":"string"},"default":{"type":"integer"},"image_id":{"type":"integer"},"external_id":{"type":"integer"},"external_source":{"type":"string"},"retailer_id":{"type":"integer"},"meta_validation":{"type":"object","properties":{"set":{"type":"object","properties":{"merge":{"type":"boolean"},"source_name":{"type":"string"}}}}},"available":{"type":"boolean"},"image":{"type":"string"},"prices":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"currency":{"type":"string"},"amount":{"type":"number"},"compare_at_amount":{"type":"number"}}}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}},"example":{"payload":{"id":1,"account_id":1,"catalog_product_id":1,"sku":"sample sku","name":"Sample Name","price":149.9,"currency":"BRL","compare_at_price":149.9,"track_inventory":"sample track inventory","stock_quantity":"sample stock quantity","barcode":"sample barcode","position":1,"options":"sample options","default":1,"image_id":1,"external_id":1,"external_source":"sample external source","retailer_id":1,"meta_validation":{"set":{"merge":true,"source_name":"sample source name"}},"available":true,"image":"sample image","prices":[{"id":1,"currency":"BRL","amount":149.9,"compare_at_amount":149.9}],"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}}},"put":{"tags":["Catalog Variants"],"operationId":"auto_put_api_v1_accounts_account_id_catalog_products_product_id_variants_id","summary":"Update variants","description":"Updates the variant identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"catalog_product_id":{"type":"integer"},"sku":{"type":"string"},"name":{"type":"string"},"price":{"type":"number"},"currency":{"type":"string"},"compare_at_price":{"type":"number"},"track_inventory":{"type":"string"},"stock_quantity":{"type":"string"},"barcode":{"type":"string"},"position":{"type":"integer"},"options":{"type":"string"},"default":{"type":"integer"},"image_id":{"type":"integer"},"external_id":{"type":"integer"},"external_source":{"type":"string"},"retailer_id":{"type":"integer"},"meta_validation":{"type":"object","properties":{"set":{"type":"object","properties":{"merge":{"type":"boolean"},"source_name":{"type":"string"}}}}},"available":{"type":"boolean"},"image":{"type":"string"},"prices":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"currency":{"type":"string"},"amount":{"type":"number"},"compare_at_amount":{"type":"number"}}}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}},"example":{"payload":{"id":1,"account_id":1,"catalog_product_id":1,"sku":"sample sku","name":"Sample Name","price":149.9,"currency":"BRL","compare_at_price":149.9,"track_inventory":"sample track inventory","stock_quantity":"sample stock quantity","barcode":"sample barcode","position":1,"options":"sample options","default":1,"image_id":1,"external_id":1,"external_source":"sample external source","retailer_id":1,"meta_validation":{"set":{"merge":true,"source_name":"sample source name"}},"available":true,"image":"sample image","prices":[{"id":1,"currency":"BRL","amount":149.9,"compare_at_amount":149.9}],"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"variant":{"type":"object","properties":{"sku":{"type":"string"},"name":{"type":"string"},"price":{"type":"number"},"currency":{"type":"string"},"compare_at_price":{"type":"number"},"track_inventory":{"type":"string"},"stock_quantity":{"type":"string"},"barcode":{"type":"string"},"position":{"type":"integer"},"catalog_product_image_id":{"type":"integer"},"default":{"type":"boolean"},"options":{"type":"object","additionalProperties":true,"description":"Free-form object."},"prices_attributes":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Free-form object."}}}}},"required":["variant"]},"example":{"variant":{"sku":"sample sku","name":"Sample Name","price":149.9,"currency":"BRL","compare_at_price":149.9,"track_inventory":"sample track inventory","stock_quantity":"sample stock quantity","barcode":"sample barcode","position":1,"catalog_product_image_id":1,"default":true,"options":{},"prices_attributes":[{}]}}}}}}},"/api/v1/accounts/{account_id}/catalog/products/{product_id}/variants/{id}/adjust_stock":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"product_id","in":"path","required":true,"schema":{"type":"number"}},{"name":"id","in":"path","required":true,"schema":{"type":"number"}}],"patch":{"tags":["Catalog Variants"],"operationId":"adjust-catalog-variant-stock","summary":"Adjust a variant's stock","description":"Moves the stock of one variant, either relatively (`delta`, positive to receive units, negative to consume them) or absolutely (`set`, which wins whenever it is supplied). The result is floored at zero, so stock never goes negative. Reaching zero raises an out-of-stock event and landing at or below the low-stock threshold of five units raises a low-stock event, which is what feeds the replenishment alerts. A variant that does not track inventory is returned untouched instead of being rejected, and a movement that changes nothing writes no timeline entry. Answers `200 OK` with the variant as it stands after the movement, wrapped in `payload`. Requires update permission on the parent product.","security":[{"userApiKey":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"delta":{"type":"integer","description":"Relative stock movement; ignored when set is present."},"set":{"type":"integer","description":"Absolute stock quantity. Values below zero are stored as zero."}}},"example":{"delta":-2,"set":1}}}},"responses":{"200":{"description":"The variant after the movement — read `stock_quantity` and `available` here rather than recomputing them.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","description":"The variant after the stock movement.","properties":{"id":{"type":"integer","description":"Variant identifier."},"account_id":{"type":"integer","description":"Account the variant belongs to."},"catalog_product_id":{"type":"integer","description":"Product this variant is sold under."},"sku":{"type":"string","description":"Stock keeping unit. May be null."},"name":{"type":"string","description":"Variant label shown next to the product name. May be null."},"price":{"type":"number","description":"Base price in `currency`. Unchanged by a stock movement."},"currency":{"type":"string","description":"ISO-4217 code the base price is expressed in. May be null."},"compare_at_price":{"type":"number","description":"Reference (\"was\") price used to show a discount. May be null."},"track_inventory":{"type":"boolean","description":"Whether stock is counted for this variant. When false the movement was a no-op and the row is returned exactly as it was."},"stock_quantity":{"type":"integer","description":"Units on hand after the movement. Never negative."},"barcode":{"type":"string","description":"Barcode (EAN/UPC) printed on the item. May be null."},"position":{"type":"integer","description":"Ordering of this variant inside the product, ascending."},"options":{"type":"object","description":"Named values that identify this combination, such as Color and Size.","maxProperties":20,"additionalProperties":{"type":"string","minLength":1,"maxLength":200}},"default":{"type":"boolean","description":"Whether this is the product's active default variant."},"image_id":{"type":["integer","null"],"description":"Explicit image from this product's gallery; null uses the primary image."},"image":{"type":["object","null"],"description":"Resolved variant image, including the primary-image fallback.","properties":{"id":{"type":"integer"},"alt_text":{"type":["string","null"]},"primary":{"type":"boolean"},"file_url":{"type":"string"},"thumb_url":{"type":"string"}}},"external_id":{"type":"string","description":"Identifier this variant carries on the external platform it was synced from. Null for variants created directly here."},"external_source":{"type":"string","description":"The external platform the variant was synced from. Null for variants created directly here."},"available":{"type":"boolean","description":"Whether the variant can still be sold — always true when inventory is not tracked, otherwise true only while units remain."},"prices":{"type":"array","description":"Per-currency overrides of the base price. Unchanged by a stock movement.","items":{"type":"object","properties":{"id":{"type":"integer","description":"Price row identifier."},"currency":{"type":"string","description":"ISO-4217 code this override applies to."},"amount":{"type":"number","description":"Selling price in that currency."},"compare_at_amount":{"type":"number","description":"Reference (\"was\") price in that currency. May be null."}}}},"created_at":{"type":"string","format":"date-time","description":"When the variant was created."},"updated_at":{"type":"string","format":"date-time","description":"When the variant was last changed."}}}}},"example":{"payload":{"id":8871,"account_id":41,"catalog_product_id":3312,"sku":"KIT-PREM-500","name":"500ml","price":149.9,"currency":"BRL","compare_at_price":189.9,"track_inventory":true,"stock_quantity":3,"barcode":"7891234567895","position":0,"options":{"Size":"500ml"},"default":true,"image_id":731,"image":{"id":731,"alt_text":"Premium kit bottle","primary":false,"file_url":"https://app.example.test/rails/active_storage/blobs/variant.png","thumb_url":"https://app.example.test/rails/active_storage/representations/variant.png"},"external_id":null,"external_source":null,"available":true,"prices":[{"id":512,"currency":"USD","amount":29.9,"compare_at_amount":37.9}],"created_at":"2026-07-20T09:11:02.000Z","updated_at":"2026-07-27T12:04:31.000Z"}}}}},"401":{"description":"The current user may not update this product.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Why the request was refused."}}},"example":{"error":"You are not authorized to do this action"}}}},"404":{"description":"No such product in this account, or no such variant under it.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Why the record could not be resolved."}}},"example":{"error":"Resource could not be found"}}}}}}},"/api/v1/accounts/{account_id}/catalog/categories":{"parameters":[{"$ref":"#/components/parameters/account_id"}],"get":{"tags":["Catalog Categories"],"operationId":"list-catalog-categories","summary":"List categories","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"$ref":"#/components/schemas/catalog_category"}}}},"example":{"payload":[{"id":1,"account_id":1,"parent_id":1,"name":"Sample Name","slug":"sample-slug","position":1,"products_count":5,"depth":12.5,"external_id":"sample external id","external_source":"sample external source","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}},"description":"List categories. Returns Categories data for the current context."},"post":{"tags":["Catalog Categories"],"operationId":"create-catalog-category","summary":"Create a category","security":[{"userApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/category_payload_wrapper"},"example":{"category":{"name":"Sample Name","parent_id":1,"position":1}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"$ref":"#/components/schemas/catalog_category"}}},"example":{"payload":{"id":1,"account_id":1,"parent_id":1,"name":"Sample Name","slug":"sample-slug","position":1,"products_count":5,"depth":12.5,"external_id":"sample external id","external_source":"sample external source","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}},"description":"Create a category. Submits the request payload to the Categories resource and returns the result."}},"/api/v1/accounts/{account_id}/catalog/categories/{id}":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"id","in":"path","required":true,"schema":{"type":"number"}}],"get":{"tags":["Catalog Categories"],"operationId":"get-catalog-category","summary":"Get a category","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"$ref":"#/components/schemas/catalog_category"}}},"example":{"payload":{"id":1,"account_id":1,"parent_id":1,"name":"Sample Name","slug":"sample-slug","position":1,"products_count":5,"depth":12.5,"external_id":"sample external id","external_source":"sample external source","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}},"description":"Get a category. Returns the requested Categories resource."},"patch":{"tags":["Catalog Categories"],"operationId":"update-catalog-category","summary":"Update a category","security":[{"userApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/category_payload_wrapper"},"example":{"category":{"name":"Sample Name","parent_id":1,"position":1}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"$ref":"#/components/schemas/catalog_category"}}},"example":{"payload":{"id":1,"account_id":1,"parent_id":1,"name":"Sample Name","slug":"sample-slug","position":1,"products_count":5,"depth":12.5,"external_id":"sample external id","external_source":"sample external source","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}},"description":"Update a category. Applies the submitted changes to the Categories resource."},"delete":{"tags":["Catalog Categories"],"operationId":"delete-catalog-category","summary":"Delete a category (admin)","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Success"}},"description":"Delete a category (admin). Removes the targeted Categories resource."},"put":{"tags":["Catalog Categories"],"operationId":"auto_put_api_v1_accounts_account_id_catalog_categories_id","summary":"Update categories","description":"Updates the category identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"parent_id":{"type":"integer"},"name":{"type":"string"},"slug":{"type":"string"},"position":{"type":"integer"},"products_count":{"type":"integer"},"depth":{"type":"string"},"external_id":{"type":"integer"},"external_source":{"type":"string"},"additional_attributes":{"type":"object","additionalProperties":true,"description":"Channel- and source-specific metadata for this record (e.g. browser info, referer, social profile identifiers). The key set depends on the originating channel."},"archived_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}},"example":{"payload":{"id":1,"account_id":1,"parent_id":1,"name":"Sample Name","slug":"sample-slug","position":1,"products_count":5,"depth":"sample depth","external_id":1,"external_source":"sample external source","additional_attributes":{},"archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"category":{"type":"object","properties":{"name":{"type":"string"},"slug":{"type":"string"},"parent_id":{"type":"integer"},"position":{"type":"integer"},"additional_attributes":{"type":"object","additionalProperties":true,"description":"Channel- and source-specific metadata for this record (e.g. browser info, referer, social profile identifiers). The key set depends on the originating channel."}}}},"required":["category"]},"example":{"category":{"name":"Sample Name","slug":"sample-slug","parent_id":1,"position":1,"additional_attributes":{}}}}}}}},"/api/v1/accounts/{account_id}/catalog/reports":{"parameters":[{"$ref":"#/components/parameters/account_id"}],"get":{"tags":["Catalog Reports"],"operationId":"catalog-reports","summary":"Catalog analytics (admin): KPIs, status/category distribution, revenue, low stock","description":"Returns the catalog analytics dashboard for the account as a single pre-aggregated document: headline counters, the status and category distributions, the best selling products by revenue and the variants running out of stock. Every product-derived metric honours the same optional filters (`kind`, `category_id`, `since`, `until`), so the whole answer reacts to the period and segment the operator selected — except `categories_count`, which always counts the account's live categories. Revenue is read from the sales line items that reference the filtered products. Administrator only.","security":[{"userApiKey":[]}],"parameters":[{"name":"kind","in":"query","required":false,"description":"Restrict every product-derived metric to a single catalog kind.","schema":{"type":"string","enum":["product","service"]}},{"name":"category_id","in":"query","required":false,"description":"Restrict every product-derived metric to a single category.","schema":{"type":"integer"}},{"name":"since","in":"query","required":false,"description":"Start of the reporting period (`YYYY-MM-DD`, inclusive, expanded to the beginning of that day). Filters products by creation date and revenue by line-item date. An unparseable value is ignored rather than rejected.","schema":{"type":"string","format":"date"}},{"name":"until","in":"query","required":false,"description":"End of the reporting period (`YYYY-MM-DD`, inclusive, expanded to the end of that day). Supplying only one bound leaves the other side open.","schema":{"type":"string","format":"date"}}],"responses":{"200":{"description":"The assembled analytics document.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","description":"The analytics document, already aggregated server side.","properties":{"overview":{"type":"object","description":"Headline counters for the filtered catalog.","properties":{"total_products":{"type":"integer","description":"Live products matching the filters."},"categories_count":{"type":"integer","description":"Live categories in the account. Not affected by the filters."},"variant_count":{"type":"integer","description":"Live variants belonging to the filtered products."},"active_count":{"type":"integer","description":"Filtered products currently published."},"draft_count":{"type":"integer","description":"Filtered products still in draft."},"archived_count":{"type":"integer","description":"Always 0. The report counts only KEPT products — the scope excludes archived ones before any filter is applied — so an archived product can never reach this total. Kept in the payload because the key is always present."},"product_count":{"type":"integer","description":"Filtered entries sold as goods."},"service_count":{"type":"integer","description":"Filtered entries sold as services."},"tracked_variant_count":{"type":"integer","description":"Filtered variants that track inventory."},"out_of_stock_count":{"type":"integer","description":"Tracked variants whose stock reached zero or less."},"low_stock_count":{"type":"integer","description":"Tracked variants still in stock but at or below the low-stock threshold of five units."},"total_stock_units":{"type":"integer","description":"Sum of the stock quantities of every tracked variant."},"without_image_count":{"type":"integer","description":"Filtered products carrying no image."},"without_category_count":{"type":"integer","description":"Filtered products not assigned to a category."},"inventory_value_by_currency":{"type":"object","description":"Stock valuation (unit price times quantity on hand) of the tracked variants, keyed by the ISO-4217 code the variant is priced in. Variants stored without a currency are reported under `BRL`. Only currencies actually present appear.","additionalProperties":{"type":"number"}},"revenue_by_currency":{"type":"object","description":"Total sold value of the filtered products, keyed by the ISO-4217 code of the sale. Line items stored without a currency are reported under `BRL`. Only currencies actually present appear.","additionalProperties":{"type":"number"}}}},"revenue_by_product":{"type":"array","description":"Best selling products, one row per product and currency pair, sorted by revenue descending and capped at twenty-five rows.","items":{"type":"object","properties":{"id":{"type":"integer","description":"Product identifier."},"name":{"type":"string","description":"Product name at the time of the report."},"currency":{"type":"string","description":"ISO-4217 code the sales were recorded in. May be null on rows stored without one."},"revenue":{"type":"number","description":"Sum of the line totals for this product and currency."}}}},"low_stock":{"type":"array","description":"Tracked variants at or below the low-stock threshold, sorted by remaining stock ascending and capped at twenty-five rows. Rows carry no product name.","items":{"type":"object","properties":{"id":{"type":"integer","description":"Variant identifier."},"sku":{"type":"string","description":"Variant SKU. May be null when the variant was created without one."},"stock_quantity":{"type":"integer","description":"Units still on hand. Zero or negative means sold out."}}}},"by_status":{"type":"object","description":"Filtered product count per publication status. Keys are the product status values (`draft`, `active`); `archived` can never appear, because the report's scope excludes archived products before counting. A status with no products is omitted entirely rather than reported as zero.","additionalProperties":{"type":"integer"}},"by_category":{"type":"array","description":"Filtered product count per category, sorted by count descending and capped at twenty-five rows. Products without a category are excluded.","items":{"type":"object","properties":{"id":{"type":"integer","description":"Category identifier."},"name":{"type":"string","description":"Category name at the time of the report."},"count":{"type":"integer","description":"Filtered products in this category."}}}}}}}},"example":{"payload":{"overview":{"total_products":128,"categories_count":9,"variant_count":214,"active_count":96,"draft_count":24,"archived_count":0,"product_count":119,"service_count":9,"tracked_variant_count":173,"out_of_stock_count":6,"low_stock_count":11,"total_stock_units":4820,"without_image_count":14,"without_category_count":7,"inventory_value_by_currency":{"BRL":184320.5},"revenue_by_currency":{"BRL":51240.9}},"revenue_by_product":[{"id":3312,"name":"Kit Premium 500ml","currency":"BRL","revenue":18420.0}],"low_stock":[{"id":8871,"sku":"KIT-PREM-500","stock_quantity":3}],"by_status":{"active":96,"draft":24},"by_category":[{"id":51,"name":"Skincare","count":37}]}}}}},"401":{"description":"The current user is not an administrator of this account, so the analytics surface is refused.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Why the request was refused."}}},"example":{"error":"You are not authorized to do this action"}}}}}}},"/api/v1/accounts/{account_id}/catalog/sync_sources":{"parameters":[{"$ref":"#/components/parameters/account_id"}],"get":{"tags":["Catalog Sync Sources"],"operationId":"list-catalog-sync-sources","summary":"List sync sources (admin)","security":[{"userApiKey":[]}],"parameters":[{"name":"q","in":"query","required":false,"description":"Case-insensitive search by source name or connector type.","schema":{"type":"string","maxLength":200}},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["disabled","enabled"]}},{"name":"direction","in":"query","required":false,"schema":{"type":"string","enum":["inbound","outbound","bidirectional"]}},{"name":"source_type","in":"query","required":false,"schema":{"type":"string","enum":["generic","shopify","woocommerce","magento","prestashop","medusa","local","meta_catalog","nuvemshop","mercado_livre","hotmart","kiwify","olx"]}},{"name":"sort","in":"query","required":false,"schema":{"type":"string","enum":["name","source_type","status","last_synced_at","updated_at"],"default":"name"}},{"name":"order","in":"query","required":false,"schema":{"type":"string","enum":["asc","desc"],"default":"asc"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1}},{"name":"per_page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":25}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","required":["payload","meta"],"properties":{"payload":{"type":"array","items":{"$ref":"#/components/schemas/catalog_sync_source"}},"meta":{"type":"object","required":["count","current_page","per_page","total_pages"],"properties":{"count":{"type":"integer","minimum":0},"current_page":{"type":"integer","minimum":1},"per_page":{"type":"integer","minimum":1,"maximum":100},"total_pages":{"type":"integer","minimum":0}}}}},"example":{"payload":[{"id":1,"account_id":1,"name":"Sample Name","source_type":"generic","direction":"inbound","status":"disabled","schedule_minutes":60,"settings":{"external_source":"sample external source","http_method":"get","base_url":"https://example.com/resource","products_path":"sample products path","products_root":"sample products root","format":"json","request_body":"sample request body","catalog_id":"sample catalog id","phone_number_id":"+5511999998888","waba_id":"sample waba id","inbox_id":1,"store_id":"sample store id","user_id":"sample user id","user_agent":"Mozilla/5.0","environment":"production","api_version":"sample api version","base_host":"https://example.com/resource","locale":"en","mapping":{"name":"Sample Name","external_id":"sample external id","description":"A short description.","slug":"sample-slug","status":"active","category":"sample category","price":"sample price","compare_at_price":"sample compare at price","currency":"BRL","sku":"sample sku","stock":"sample stock","brand":"sample brand","external_url":"https://example.com/resource","variants":"sample variants","images":"sample images","attachments":"sample attachments","kind":"sample kind","custom_attributes":{}},"auth":{"type":"none","header":"sample header","param":"sample param","user_agent":"Mozilla/5.0","token":"sample-token","username":"sample username","password":"sample-password"},"pagination":{"style":"link","param":"sample param","cursor_path":"sample cursor path"},"generic_webhook":{"event_path":"event","external_id_path":"id","amount_path":"sample amount path","currency_path":"sample currency path","payment_method_path":"sample payment method path","checkout_url_path":"sample checkout url path","contact_email_path":"agent@example.com","contact_name_path":"sample contact name path","contact_phone_path":"+5511999998888","product_id_path":"sample product id path","product_name_path":"sample product name path","product_sku_path":"sample product sku path","variation_id_path":"sample variation id path","variation_name_path":"sample variation name path","variation_sku_path":"sample variation sku path","items_path":"sample items path","item_id_path":"sample item id path","item_product_id_path":"sample item product id path","item_variant_id_path":"sample item variant id path","item_name_path":"sample item name path","item_sku_path":"sample item sku path","item_quantity_path":"sample item quantity path","item_unit_price_path":"sample item unit price path","item_total_price_path":"sample item total price path","item_currency_path":"sample item currency path","replay_window_seconds":300,"outbound_url":"https://example.com/resource","events":{}},"hotmart":{"events":{"PURCHASE_APPROVED":"sample PURCHASE APPROVED","PURCHASE_COMPLETE":"sample PURCHASE COMPLETE","PURCHASE_CANCELED":"sample PURCHASE CANCELED","PURCHASE_EXPIRED":"sample PURCHASE EXPIRED","PURCHASE_REFUNDED":"sample PURCHASE REFUNDED","PURCHASE_CHARGEBACK":"sample PURCHASE CHARGEBACK","PURCHASE_PROTEST":"sample PURCHASE PROTEST","PURCHASE_BILLET_PRINTED":"sample PURCHASE BILLET PRINTED","PURCHASE_DELAYED":"sample PURCHASE DELAYED","PURCHASE_OUT_OF_SHOPPING_CART":"sample PURCHASE OUT OF SHOPPING CART","SUBSCRIPTION_CANCELLATION":"sample SUBSCRIPTION CANCELLATION","SWITCH_PLAN":"sample SWITCH PLAN","UPDATE_SUBSCRIPTION_CHARGE_DATE":"sample UPDATE SUBSCRIPTION CHARGE DATE","CLUB_FIRST_ACCESS":"sample CLUB FIRST ACCESS","CLUB_MODULE_COMPLETED":"sample CLUB MODULE COMPLETED"}},"kiwify":{"events":{"compra_aprovada":"sample compra aprovada","compra_recusada":"sample compra recusada","compra_reembolsada":"sample compra reembolsada","chargeback":"sample chargeback","pix_gerado":"sample pix gerado","boleto_gerado":"sample boleto gerado","carrinho_abandonado":"sample carrinho abandonado","subscription_canceled":"sample subscription canceled","subscription_late":"sample subscription late","subscription_renewed":"sample subscription renewed"}},"nuvemshop":{"events":{"paid":"sample paid","authorized":"sample authorized","pending":"sample pending","refunded":"sample refunded","partially_refunded":"sample partially refunded","abandoned":"sample abandoned"}}},"last_synced_at":"2026-01-15T10:30:00.000Z","last_pushed_at":"2026-01-15T10:30:00.000Z","last_status":"pending","last_error":"sample last error","stats":{"total":1,"scanned":1,"selected":1,"created":1,"updated":1,"skipped":1,"failed":1,"repaired":1,"meta_validated":1,"meta_rejected":1,"dry_run":true,"truncated":true,"failed_ids":[{"external_id":"sample external id","name":"Sample Name","reason":"Sample reason."}],"warning_ids":[{"external_id":"sample external id","name":"Sample Name","reason":"Sample reason."}],"skipped_ids":[{"external_id":"sample external id","name":"Sample Name","reason":"Sample reason."}]},"capabilities":{},"meta_catalog":true,"event_map":{},"environment":"production","external_source_key":"sample-token","inbound_url":"https://example.com/resource","commerce_webhook_url":"https://example.com/resource","webhook_configured":true,"access_token_preview":"sample access token preview","access_token":"sample-token","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}],"meta":{"count":5,"current_page":1,"per_page":1,"total_pages":1}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"403":{"description":"Administrator access required"}},"description":"List sync sources (admin). Returns Sync sources data for the current context."},"post":{"tags":["Catalog Sync Sources"],"operationId":"create-catalog-sync-source","summary":"Create a sync source (admin)","security":[{"userApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/sync_source_payload_wrapper"},"example":{"sync_source":{"name":"Sample Name","source_type":"generic","direction":"inbound","status":"disabled","schedule_minutes":60,"webhook_secret":"sample-token","credentials":{"graph_token":"sample-token","access_token":"sample-token","store_id":"sample store id","user_id":"sample user id","client_id":"sample client id","client_secret":"sample-token","account_id":"sample account id","basic_token":"sample-token","sync_auth_token":"sample-token","sync_auth_username":"sample sync auth username","sync_auth_password":"sample sync auth password"},"settings":{"external_source":"sample external source","http_method":"get","base_url":"https://example.com/resource","products_path":"sample products path","products_root":"sample products root","format":"json","request_body":"sample request body","catalog_id":"sample catalog id","phone_number_id":"+5511999998888","waba_id":"sample waba id","inbox_id":1,"store_id":"sample store id","user_id":"sample user id","user_agent":"Mozilla/5.0","environment":"production","api_version":"sample api version","base_host":"https://example.com/resource","locale":"en","mapping":{"name":"Sample Name","external_id":"sample external id","description":"A short description.","slug":"sample-slug","status":"active","category":"sample category","price":"sample price","compare_at_price":"sample compare at price","currency":"BRL","sku":"sample sku","stock":"sample stock","brand":"sample brand","external_url":"https://example.com/resource","variants":"sample variants","images":"sample images","attachments":"sample attachments","kind":"sample kind","custom_attributes":{}},"auth":{"type":"none","header":"sample header","param":"sample param","user_agent":"Mozilla/5.0","token":"sample-token","username":"sample username","password":"sample-password"},"pagination":{"style":"link","param":"sample param","cursor_path":"sample cursor path"},"generic_webhook":{"event_path":"event","external_id_path":"id","amount_path":"sample amount path","currency_path":"sample currency path","payment_method_path":"sample payment method path","checkout_url_path":"sample checkout url path","contact_email_path":"agent@example.com","contact_name_path":"sample contact name path","contact_phone_path":"+5511999998888","product_id_path":"sample product id path","product_name_path":"sample product name path","product_sku_path":"sample product sku path","variation_id_path":"sample variation id path","variation_name_path":"sample variation name path","variation_sku_path":"sample variation sku path","items_path":"sample items path","item_id_path":"sample item id path","item_product_id_path":"sample item product id path","item_variant_id_path":"sample item variant id path","item_name_path":"sample item name path","item_sku_path":"sample item sku path","item_quantity_path":"sample item quantity path","item_unit_price_path":"sample item unit price path","item_total_price_path":"sample item total price path","item_currency_path":"sample item currency path","replay_window_seconds":300,"outbound_url":"https://example.com/resource","events":{}},"hotmart":{"events":{"PURCHASE_APPROVED":"sample PURCHASE APPROVED","PURCHASE_COMPLETE":"sample PURCHASE COMPLETE","PURCHASE_CANCELED":"sample PURCHASE CANCELED","PURCHASE_EXPIRED":"sample PURCHASE EXPIRED","PURCHASE_REFUNDED":"sample PURCHASE REFUNDED","PURCHASE_CHARGEBACK":"sample PURCHASE CHARGEBACK","PURCHASE_PROTEST":"sample PURCHASE PROTEST","PURCHASE_BILLET_PRINTED":"sample PURCHASE BILLET PRINTED","PURCHASE_DELAYED":"sample PURCHASE DELAYED","PURCHASE_OUT_OF_SHOPPING_CART":"sample PURCHASE OUT OF SHOPPING CART","SUBSCRIPTION_CANCELLATION":"sample SUBSCRIPTION CANCELLATION","SWITCH_PLAN":"sample SWITCH PLAN","UPDATE_SUBSCRIPTION_CHARGE_DATE":"sample UPDATE SUBSCRIPTION CHARGE DATE","CLUB_FIRST_ACCESS":"sample CLUB FIRST ACCESS","CLUB_MODULE_COMPLETED":"sample CLUB MODULE COMPLETED"}},"kiwify":{"events":{"compra_aprovada":"sample compra aprovada","compra_recusada":"sample compra recusada","compra_reembolsada":"sample compra reembolsada","chargeback":"sample chargeback","pix_gerado":"sample pix gerado","boleto_gerado":"sample boleto gerado","carrinho_abandonado":"sample carrinho abandonado","subscription_canceled":"sample subscription canceled","subscription_late":"sample subscription late","subscription_renewed":"sample subscription renewed"}},"nuvemshop":{"events":{"paid":"sample paid","authorized":"sample authorized","pending":"sample pending","refunded":"sample refunded","partially_refunded":"sample partially refunded","abandoned":"sample abandoned"}}}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"$ref":"#/components/schemas/catalog_sync_source"}}},"example":{"payload":{"id":1,"account_id":1,"name":"Sample Name","source_type":"generic","direction":"inbound","status":"disabled","schedule_minutes":60,"settings":{"external_source":"sample external source","http_method":"get","base_url":"https://example.com/resource","products_path":"sample products path","products_root":"sample products root","format":"json","request_body":"sample request body","catalog_id":"sample catalog id","phone_number_id":"+5511999998888","waba_id":"sample waba id","inbox_id":1,"store_id":"sample store id","user_id":"sample user id","user_agent":"Mozilla/5.0","environment":"production","api_version":"sample api version","base_host":"https://example.com/resource","locale":"en","mapping":{"name":"Sample Name","external_id":"sample external id","description":"A short description.","slug":"sample-slug","status":"active","category":"sample category","price":"sample price","compare_at_price":"sample compare at price","currency":"BRL","sku":"sample sku","stock":"sample stock","brand":"sample brand","external_url":"https://example.com/resource","variants":"sample variants","images":"sample images","attachments":"sample attachments","kind":"sample kind","custom_attributes":{}},"auth":{"type":"none","header":"sample header","param":"sample param","user_agent":"Mozilla/5.0","token":"sample-token","username":"sample username","password":"sample-password"},"pagination":{"style":"link","param":"sample param","cursor_path":"sample cursor path"},"generic_webhook":{"event_path":"event","external_id_path":"id","amount_path":"sample amount path","currency_path":"sample currency path","payment_method_path":"sample payment method path","checkout_url_path":"sample checkout url path","contact_email_path":"agent@example.com","contact_name_path":"sample contact name path","contact_phone_path":"+5511999998888","product_id_path":"sample product id path","product_name_path":"sample product name path","product_sku_path":"sample product sku path","variation_id_path":"sample variation id path","variation_name_path":"sample variation name path","variation_sku_path":"sample variation sku path","items_path":"sample items path","item_id_path":"sample item id path","item_product_id_path":"sample item product id path","item_variant_id_path":"sample item variant id path","item_name_path":"sample item name path","item_sku_path":"sample item sku path","item_quantity_path":"sample item quantity path","item_unit_price_path":"sample item unit price path","item_total_price_path":"sample item total price path","item_currency_path":"sample item currency path","replay_window_seconds":300,"outbound_url":"https://example.com/resource","events":{}},"hotmart":{"events":{"PURCHASE_APPROVED":"sample PURCHASE APPROVED","PURCHASE_COMPLETE":"sample PURCHASE COMPLETE","PURCHASE_CANCELED":"sample PURCHASE CANCELED","PURCHASE_EXPIRED":"sample PURCHASE EXPIRED","PURCHASE_REFUNDED":"sample PURCHASE REFUNDED","PURCHASE_CHARGEBACK":"sample PURCHASE CHARGEBACK","PURCHASE_PROTEST":"sample PURCHASE PROTEST","PURCHASE_BILLET_PRINTED":"sample PURCHASE BILLET PRINTED","PURCHASE_DELAYED":"sample PURCHASE DELAYED","PURCHASE_OUT_OF_SHOPPING_CART":"sample PURCHASE OUT OF SHOPPING CART","SUBSCRIPTION_CANCELLATION":"sample SUBSCRIPTION CANCELLATION","SWITCH_PLAN":"sample SWITCH PLAN","UPDATE_SUBSCRIPTION_CHARGE_DATE":"sample UPDATE SUBSCRIPTION CHARGE DATE","CLUB_FIRST_ACCESS":"sample CLUB FIRST ACCESS","CLUB_MODULE_COMPLETED":"sample CLUB MODULE COMPLETED"}},"kiwify":{"events":{"compra_aprovada":"sample compra aprovada","compra_recusada":"sample compra recusada","compra_reembolsada":"sample compra reembolsada","chargeback":"sample chargeback","pix_gerado":"sample pix gerado","boleto_gerado":"sample boleto gerado","carrinho_abandonado":"sample carrinho abandonado","subscription_canceled":"sample subscription canceled","subscription_late":"sample subscription late","subscription_renewed":"sample subscription renewed"}},"nuvemshop":{"events":{"paid":"sample paid","authorized":"sample authorized","pending":"sample pending","refunded":"sample refunded","partially_refunded":"sample partially refunded","abandoned":"sample abandoned"}}},"last_synced_at":"2026-01-15T10:30:00.000Z","last_pushed_at":"2026-01-15T10:30:00.000Z","last_status":"pending","last_error":"sample last error","stats":{"total":1,"scanned":1,"selected":1,"created":1,"updated":1,"skipped":1,"failed":1,"repaired":1,"meta_validated":1,"meta_rejected":1,"dry_run":true,"truncated":true,"failed_ids":[{"external_id":"sample external id","name":"Sample Name","reason":"Sample reason."}],"warning_ids":[{"external_id":"sample external id","name":"Sample Name","reason":"Sample reason."}],"skipped_ids":[{"external_id":"sample external id","name":"Sample Name","reason":"Sample reason."}]},"capabilities":{},"meta_catalog":true,"event_map":{},"environment":"production","external_source_key":"sample-token","inbound_url":"https://example.com/resource","commerce_webhook_url":"https://example.com/resource","webhook_configured":true,"access_token_preview":"sample access token preview","access_token":"sample-token","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}},"description":"Create a sync source (admin). Submits the request payload to the Sync sources resource and returns the result."}},"/api/v1/accounts/{account_id}/catalog/sync_sources/preview":{"parameters":[{"$ref":"#/components/parameters/account_id"}],"post":{"tags":["Catalog Sync Sources"],"operationId":"preview-catalog-sync","summary":"Live test a connection config: status, detected fields, mapped preview (admin)","description":"Resolves the selected generic connector through the same connector factory as a scheduled pull, then performs its real `fetch_page` and `map` path with the submitted connection settings — which do not have to be saved yet — and reports back everything needed to validate the configuration on screen: the request line that went out, the upstream response status, the detected real response format, how many records were found, the flattened field paths detected in the first record, server-side mapping suggestions with confidence, a small raw sample and the first record run through the current field mapping. Secrets are never echoed: any authorization, token or key header comes back masked. The call is bounded (short timeout, truncated raw body) so it is safe to run interactively. A connection failure is still `200 OK` — read `ok` to tell success from failure rather than relying on the status code. Administrator only.","security":[{"userApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["settings"],"properties":{"settings":{"type":"object","description":"Unsaved generic-source settings used only for this bounded preview. Authentication values are accepted to make the upstream request but are masked in the response and never persisted.","properties":{"source_type":{"type":"string","enum":["generic","shopify","woocommerce","magento","prestashop","medusa","local"],"description":"Generic connector template whose real fetch_page/map path is exercised. Omit for generic; this preview does not accept managed-provider credentials.","example":"shopify"},"base_url":{"type":"string","format":"uri","example":"https://erp.example.com"},"products_path":{"type":"string","example":"/api/products"},"products_root":{"type":"string","description":"Dot path for JSON/NDJSON/CSV/TSV; XPath when format is xml.","example":"data.products"},"format":{"type":"string","enum":["json","ndjson","xml","csv","tsv"],"description":"Optional parser override. When omitted, the response Content-Type/body is detected.","example":"csv"},"http_method":{"type":"string","enum":["get","post"],"example":"get"},"request_body":{"type":"string","description":"Optional body for a POST upstream request.","example":"{\"active\":true}"},"mapping":{"type":"object","description":"Local catalog field to returned-record path. Review the suggested_mapping response before saving it.","additionalProperties":{"type":"string"},"example":{"name":"nome","price":"preco"}},"auth":{"type":"object","description":"Optional upstream authentication. basic uses username/password; query uses param/token.","properties":{"type":{"type":"string","enum":["none","bearer","header","basic","query"],"example":"query"},"header":{"type":"string","description":"Header name when type is header.","example":"X-Api-Key"},"param":{"type":"string","description":"Query parameter name when type is query.","example":"api_key"},"token":{"type":"string","description":"Secret for bearer, header or query authentication.","example":"sample-token"},"username":{"type":"string","description":"Username when type is basic.","example":"sync-user"},"password":{"type":"string","description":"Password when type is basic.","example":"sample-password"}}}}}}},"example":{"settings":{"source_type":"shopify","base_url":"https://erp.example.com","products_path":"/api/products.csv","format":"csv","mapping":{"name":"nome","price":"preco"},"auth":{"type":"query","param":"api_key","token":"sample-token","header":"X-Api-Key","username":"sync-user","password":"sample-password"},"products_root":"data.products","http_method":"get","request_body":"{\"active\":true}"}}}}},"responses":{"200":{"description":"The outcome of the live attempt. An upstream HTTP/parser failure also carries its bounded response/raw evidence and empty record diagnostics; failures before a request can be built carry only `ok`, `error` and a reduced `request`.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","description":"Whether the upstream call succeeded. False both when the request could not be made at all and when the platform answered with an error status."},"error":{"type":"string","description":"Why the attempt failed. Present only when the request could not be completed; absent on success."},"request":{"type":"object","description":"The request that was actually sent, for the operator to confirm.","properties":{"method":{"type":"string","description":"HTTP method used, upper-cased."},"url":{"type":"string","description":"Full URL that was called (base URL joined with the products path)."},"headers":{"type":"object","description":"Headers sent with the request, keyed by header name. Any authorization, token or key header is replaced by a mask, so the secret is never returned. Absent when the request could not be built.","additionalProperties":{"type":"string"}}}},"response":{"type":"object","description":"What the platform answered. Absent when the request could not be completed.","properties":{"status":{"type":"integer","description":"HTTP status code returned by the platform."},"ok":{"type":"boolean","description":"Whether that status is a success status."},"content_type":{"type":"string","description":"Media type the platform declared for its response. Null when it sent no such header."}}},"products_count":{"type":"integer","description":"How many records were found at the configured root. Zero usually means the products root points at the wrong node."},"format":{"type":"string","enum":["json","ndjson","xml","csv","tsv"],"description":"The format actually parsed from the response Content-Type or body, unless the submitted settings supplied an explicit supported format override. XML uses products_root as XPath; JSON, NDJSON, CSV and TSV use the configured dot-path root where applicable."},"detected_fields":{"type":"array","description":"Every field path found in the first record, flattened with dots (array positions appear as numeric segments). These are the paths the field mapping can target. Empty when the first record is not an object.","items":{"type":"string"}},"suggested_mapping":{"type":"array","description":"Non-persisted server suggestions inferred from the first three real records. They cover Portuguese, English and Spanish field names; the operator must still review and save a mapping.","items":{"type":"object","required":["target","source","confidence"],"properties":{"target":{"type":"string","enum":["name","external_id","description","slug","status","category","price","compare_at_price","currency","sku","stock","brand","external_url","variants","images","attachments"],"example":"price"},"source":{"type":"string","description":"Dot path or XML-derived field path proposed from the returned record.","example":"pricing.0.valor"},"confidence":{"type":"number","enum":[1.0,0.8],"description":"1.0 means the canonical field name matched; 0.8 means a documented multilingual or platform synonym matched.","example":0.8}}}},"sample":{"type":"array","description":"Up to three records exactly as the platform returned them, before any mapping. Shape is whatever that platform sends.","items":{"description":"One untouched record from the platform, with its own arbitrary keys. No type is asserted: the preview forwards whatever the configured records root produced, and a misconfigured root yields scalars rather than objects — declaring `object` here would make a strict client reject a response the server really sends.","additionalProperties":true}},"raw":{"type":"string","description":"The raw response body, serialized and truncated at twenty thousand characters (an ellipsis marks a truncated body). Empty when it could not be serialized."},"mapped_preview":{"type":"object","description":"The first record after the current field mapping is applied — what would actually be imported. Keys are the catalog fields the mapping targets; with no mapping the record passes through unchanged. Null when the first record is not an object.","additionalProperties":true}}},"example":{"ok":true,"request":{"method":"GET","url":"https://shop.example.com/api/v1/products","headers":{"Accept":"application/json","Authorization":"Bearer sample-token"}},"response":{"status":200,"ok":true,"content_type":"application/json; charset=utf-8"},"products_count":3,"format":"json","detected_fields":["id","title","variants.0.price"],"suggested_mapping":[{"target":"name","source":"title","confidence":0.8}],"sample":[{"id":991,"title":"Kit Premium 500ml"}],"raw":"{\"products\":[{\"id\":991,\"title\":\"Kit Premium 500ml\"}]}","mapped_preview":{"name":"Kit Premium 500ml","external_id":"991"},"error":"sample error"}}}},"401":{"description":"The current user is not an administrator of this account.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Why the request was refused."}}},"example":{"error":"You are not authorized to do this action"}}}},"422":{"description":"The `settings` object was not supplied, so there was nothing to test.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Which required parameter was missing."}}},"example":{"error":"param is missing or the value is empty or invalid: settings"}}}}}}},"/api/v1/accounts/{account_id}/catalog/sync_sources/{id}":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"id","in":"path","required":true,"schema":{"type":"number"}}],"get":{"tags":["Catalog Sync Sources"],"operationId":"get-catalog-sync-source","summary":"Get a sync source (admin)","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"$ref":"#/components/schemas/catalog_sync_source"}}},"example":{"payload":{"id":1,"account_id":1,"name":"Sample Name","source_type":"generic","direction":"inbound","status":"disabled","schedule_minutes":60,"settings":{"external_source":"sample external source","http_method":"get","base_url":"https://example.com/resource","products_path":"sample products path","products_root":"sample products root","format":"json","request_body":"sample request body","catalog_id":"sample catalog id","phone_number_id":"+5511999998888","waba_id":"sample waba id","inbox_id":1,"store_id":"sample store id","user_id":"sample user id","user_agent":"Mozilla/5.0","environment":"production","api_version":"sample api version","base_host":"https://example.com/resource","locale":"en","mapping":{"name":"Sample Name","external_id":"sample external id","description":"A short description.","slug":"sample-slug","status":"active","category":"sample category","price":"sample price","compare_at_price":"sample compare at price","currency":"BRL","sku":"sample sku","stock":"sample stock","brand":"sample brand","external_url":"https://example.com/resource","variants":"sample variants","images":"sample images","attachments":"sample attachments","kind":"sample kind","custom_attributes":{}},"auth":{"type":"none","header":"sample header","param":"sample param","user_agent":"Mozilla/5.0","token":"sample-token","username":"sample username","password":"sample-password"},"pagination":{"style":"link","param":"sample param","cursor_path":"sample cursor path"},"generic_webhook":{"event_path":"event","external_id_path":"id","amount_path":"sample amount path","currency_path":"sample currency path","payment_method_path":"sample payment method path","checkout_url_path":"sample checkout url path","contact_email_path":"agent@example.com","contact_name_path":"sample contact name path","contact_phone_path":"+5511999998888","product_id_path":"sample product id path","product_name_path":"sample product name path","product_sku_path":"sample product sku path","variation_id_path":"sample variation id path","variation_name_path":"sample variation name path","variation_sku_path":"sample variation sku path","items_path":"sample items path","item_id_path":"sample item id path","item_product_id_path":"sample item product id path","item_variant_id_path":"sample item variant id path","item_name_path":"sample item name path","item_sku_path":"sample item sku path","item_quantity_path":"sample item quantity path","item_unit_price_path":"sample item unit price path","item_total_price_path":"sample item total price path","item_currency_path":"sample item currency path","replay_window_seconds":300,"outbound_url":"https://example.com/resource","events":{}},"hotmart":{"events":{"PURCHASE_APPROVED":"sample PURCHASE APPROVED","PURCHASE_COMPLETE":"sample PURCHASE COMPLETE","PURCHASE_CANCELED":"sample PURCHASE CANCELED","PURCHASE_EXPIRED":"sample PURCHASE EXPIRED","PURCHASE_REFUNDED":"sample PURCHASE REFUNDED","PURCHASE_CHARGEBACK":"sample PURCHASE CHARGEBACK","PURCHASE_PROTEST":"sample PURCHASE PROTEST","PURCHASE_BILLET_PRINTED":"sample PURCHASE BILLET PRINTED","PURCHASE_DELAYED":"sample PURCHASE DELAYED","PURCHASE_OUT_OF_SHOPPING_CART":"sample PURCHASE OUT OF SHOPPING CART","SUBSCRIPTION_CANCELLATION":"sample SUBSCRIPTION CANCELLATION","SWITCH_PLAN":"sample SWITCH PLAN","UPDATE_SUBSCRIPTION_CHARGE_DATE":"sample UPDATE SUBSCRIPTION CHARGE DATE","CLUB_FIRST_ACCESS":"sample CLUB FIRST ACCESS","CLUB_MODULE_COMPLETED":"sample CLUB MODULE COMPLETED"}},"kiwify":{"events":{"compra_aprovada":"sample compra aprovada","compra_recusada":"sample compra recusada","compra_reembolsada":"sample compra reembolsada","chargeback":"sample chargeback","pix_gerado":"sample pix gerado","boleto_gerado":"sample boleto gerado","carrinho_abandonado":"sample carrinho abandonado","subscription_canceled":"sample subscription canceled","subscription_late":"sample subscription late","subscription_renewed":"sample subscription renewed"}},"nuvemshop":{"events":{"paid":"sample paid","authorized":"sample authorized","pending":"sample pending","refunded":"sample refunded","partially_refunded":"sample partially refunded","abandoned":"sample abandoned"}}},"last_synced_at":"2026-01-15T10:30:00.000Z","last_pushed_at":"2026-01-15T10:30:00.000Z","last_status":"pending","last_error":"sample last error","stats":{"total":1,"scanned":1,"selected":1,"created":1,"updated":1,"skipped":1,"failed":1,"repaired":1,"meta_validated":1,"meta_rejected":1,"dry_run":true,"truncated":true,"failed_ids":[{"external_id":"sample external id","name":"Sample Name","reason":"Sample reason."}],"warning_ids":[{"external_id":"sample external id","name":"Sample Name","reason":"Sample reason."}],"skipped_ids":[{"external_id":"sample external id","name":"Sample Name","reason":"Sample reason."}]},"capabilities":{},"meta_catalog":true,"event_map":{},"environment":"production","external_source_key":"sample-token","inbound_url":"https://example.com/resource","commerce_webhook_url":"https://example.com/resource","webhook_configured":true,"access_token_preview":"sample access token preview","access_token":"sample-token","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}},"description":"Get a sync source (admin). Returns the requested Sync sources resource."},"patch":{"tags":["Catalog Sync Sources"],"operationId":"update-catalog-sync-source","summary":"Update a sync source (admin)","security":[{"userApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/sync_source_payload_wrapper"},"example":{"sync_source":{"name":"Sample Name","source_type":"generic","direction":"inbound","status":"disabled","schedule_minutes":60,"webhook_secret":"sample-token","credentials":{"graph_token":"sample-token","access_token":"sample-token","store_id":"sample store id","user_id":"sample user id","client_id":"sample client id","client_secret":"sample-token","account_id":"sample account id","basic_token":"sample-token","sync_auth_token":"sample-token","sync_auth_username":"sample sync auth username","sync_auth_password":"sample sync auth password"},"settings":{"external_source":"sample external source","http_method":"get","base_url":"https://example.com/resource","products_path":"sample products path","products_root":"sample products root","format":"json","request_body":"sample request body","catalog_id":"sample catalog id","phone_number_id":"+5511999998888","waba_id":"sample waba id","inbox_id":1,"store_id":"sample store id","user_id":"sample user id","user_agent":"Mozilla/5.0","environment":"production","api_version":"sample api version","base_host":"https://example.com/resource","locale":"en","mapping":{"name":"Sample Name","external_id":"sample external id","description":"A short description.","slug":"sample-slug","status":"active","category":"sample category","price":"sample price","compare_at_price":"sample compare at price","currency":"BRL","sku":"sample sku","stock":"sample stock","brand":"sample brand","external_url":"https://example.com/resource","variants":"sample variants","images":"sample images","attachments":"sample attachments","kind":"sample kind","custom_attributes":{}},"auth":{"type":"none","header":"sample header","param":"sample param","user_agent":"Mozilla/5.0","token":"sample-token","username":"sample username","password":"sample-password"},"pagination":{"style":"link","param":"sample param","cursor_path":"sample cursor path"},"generic_webhook":{"event_path":"event","external_id_path":"id","amount_path":"sample amount path","currency_path":"sample currency path","payment_method_path":"sample payment method path","checkout_url_path":"sample checkout url path","contact_email_path":"agent@example.com","contact_name_path":"sample contact name path","contact_phone_path":"+5511999998888","product_id_path":"sample product id path","product_name_path":"sample product name path","product_sku_path":"sample product sku path","variation_id_path":"sample variation id path","variation_name_path":"sample variation name path","variation_sku_path":"sample variation sku path","items_path":"sample items path","item_id_path":"sample item id path","item_product_id_path":"sample item product id path","item_variant_id_path":"sample item variant id path","item_name_path":"sample item name path","item_sku_path":"sample item sku path","item_quantity_path":"sample item quantity path","item_unit_price_path":"sample item unit price path","item_total_price_path":"sample item total price path","item_currency_path":"sample item currency path","replay_window_seconds":300,"outbound_url":"https://example.com/resource","events":{}},"hotmart":{"events":{"PURCHASE_APPROVED":"sample PURCHASE APPROVED","PURCHASE_COMPLETE":"sample PURCHASE COMPLETE","PURCHASE_CANCELED":"sample PURCHASE CANCELED","PURCHASE_EXPIRED":"sample PURCHASE EXPIRED","PURCHASE_REFUNDED":"sample PURCHASE REFUNDED","PURCHASE_CHARGEBACK":"sample PURCHASE CHARGEBACK","PURCHASE_PROTEST":"sample PURCHASE PROTEST","PURCHASE_BILLET_PRINTED":"sample PURCHASE BILLET PRINTED","PURCHASE_DELAYED":"sample PURCHASE DELAYED","PURCHASE_OUT_OF_SHOPPING_CART":"sample PURCHASE OUT OF SHOPPING CART","SUBSCRIPTION_CANCELLATION":"sample SUBSCRIPTION CANCELLATION","SWITCH_PLAN":"sample SWITCH PLAN","UPDATE_SUBSCRIPTION_CHARGE_DATE":"sample UPDATE SUBSCRIPTION CHARGE DATE","CLUB_FIRST_ACCESS":"sample CLUB FIRST ACCESS","CLUB_MODULE_COMPLETED":"sample CLUB MODULE COMPLETED"}},"kiwify":{"events":{"compra_aprovada":"sample compra aprovada","compra_recusada":"sample compra recusada","compra_reembolsada":"sample compra reembolsada","chargeback":"sample chargeback","pix_gerado":"sample pix gerado","boleto_gerado":"sample boleto gerado","carrinho_abandonado":"sample carrinho abandonado","subscription_canceled":"sample subscription canceled","subscription_late":"sample subscription late","subscription_renewed":"sample subscription renewed"}},"nuvemshop":{"events":{"paid":"sample paid","authorized":"sample authorized","pending":"sample pending","refunded":"sample refunded","partially_refunded":"sample partially refunded","abandoned":"sample abandoned"}}}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"$ref":"#/components/schemas/catalog_sync_source"}}},"example":{"payload":{"id":1,"account_id":1,"name":"Sample Name","source_type":"generic","direction":"inbound","status":"disabled","schedule_minutes":60,"settings":{"external_source":"sample external source","http_method":"get","base_url":"https://example.com/resource","products_path":"sample products path","products_root":"sample products root","format":"json","request_body":"sample request body","catalog_id":"sample catalog id","phone_number_id":"+5511999998888","waba_id":"sample waba id","inbox_id":1,"store_id":"sample store id","user_id":"sample user id","user_agent":"Mozilla/5.0","environment":"production","api_version":"sample api version","base_host":"https://example.com/resource","locale":"en","mapping":{"name":"Sample Name","external_id":"sample external id","description":"A short description.","slug":"sample-slug","status":"active","category":"sample category","price":"sample price","compare_at_price":"sample compare at price","currency":"BRL","sku":"sample sku","stock":"sample stock","brand":"sample brand","external_url":"https://example.com/resource","variants":"sample variants","images":"sample images","attachments":"sample attachments","kind":"sample kind","custom_attributes":{}},"auth":{"type":"none","header":"sample header","param":"sample param","user_agent":"Mozilla/5.0","token":"sample-token","username":"sample username","password":"sample-password"},"pagination":{"style":"link","param":"sample param","cursor_path":"sample cursor path"},"generic_webhook":{"event_path":"event","external_id_path":"id","amount_path":"sample amount path","currency_path":"sample currency path","payment_method_path":"sample payment method path","checkout_url_path":"sample checkout url path","contact_email_path":"agent@example.com","contact_name_path":"sample contact name path","contact_phone_path":"+5511999998888","product_id_path":"sample product id path","product_name_path":"sample product name path","product_sku_path":"sample product sku path","variation_id_path":"sample variation id path","variation_name_path":"sample variation name path","variation_sku_path":"sample variation sku path","items_path":"sample items path","item_id_path":"sample item id path","item_product_id_path":"sample item product id path","item_variant_id_path":"sample item variant id path","item_name_path":"sample item name path","item_sku_path":"sample item sku path","item_quantity_path":"sample item quantity path","item_unit_price_path":"sample item unit price path","item_total_price_path":"sample item total price path","item_currency_path":"sample item currency path","replay_window_seconds":300,"outbound_url":"https://example.com/resource","events":{}},"hotmart":{"events":{"PURCHASE_APPROVED":"sample PURCHASE APPROVED","PURCHASE_COMPLETE":"sample PURCHASE COMPLETE","PURCHASE_CANCELED":"sample PURCHASE CANCELED","PURCHASE_EXPIRED":"sample PURCHASE EXPIRED","PURCHASE_REFUNDED":"sample PURCHASE REFUNDED","PURCHASE_CHARGEBACK":"sample PURCHASE CHARGEBACK","PURCHASE_PROTEST":"sample PURCHASE PROTEST","PURCHASE_BILLET_PRINTED":"sample PURCHASE BILLET PRINTED","PURCHASE_DELAYED":"sample PURCHASE DELAYED","PURCHASE_OUT_OF_SHOPPING_CART":"sample PURCHASE OUT OF SHOPPING CART","SUBSCRIPTION_CANCELLATION":"sample SUBSCRIPTION CANCELLATION","SWITCH_PLAN":"sample SWITCH PLAN","UPDATE_SUBSCRIPTION_CHARGE_DATE":"sample UPDATE SUBSCRIPTION CHARGE DATE","CLUB_FIRST_ACCESS":"sample CLUB FIRST ACCESS","CLUB_MODULE_COMPLETED":"sample CLUB MODULE COMPLETED"}},"kiwify":{"events":{"compra_aprovada":"sample compra aprovada","compra_recusada":"sample compra recusada","compra_reembolsada":"sample compra reembolsada","chargeback":"sample chargeback","pix_gerado":"sample pix gerado","boleto_gerado":"sample boleto gerado","carrinho_abandonado":"sample carrinho abandonado","subscription_canceled":"sample subscription canceled","subscription_late":"sample subscription late","subscription_renewed":"sample subscription renewed"}},"nuvemshop":{"events":{"paid":"sample paid","authorized":"sample authorized","pending":"sample pending","refunded":"sample refunded","partially_refunded":"sample partially refunded","abandoned":"sample abandoned"}}},"last_synced_at":"2026-01-15T10:30:00.000Z","last_pushed_at":"2026-01-15T10:30:00.000Z","last_status":"pending","last_error":"sample last error","stats":{"total":1,"scanned":1,"selected":1,"created":1,"updated":1,"skipped":1,"failed":1,"repaired":1,"meta_validated":1,"meta_rejected":1,"dry_run":true,"truncated":true,"failed_ids":[{"external_id":"sample external id","name":"Sample Name","reason":"Sample reason."}],"warning_ids":[{"external_id":"sample external id","name":"Sample Name","reason":"Sample reason."}],"skipped_ids":[{"external_id":"sample external id","name":"Sample Name","reason":"Sample reason."}]},"capabilities":{},"meta_catalog":true,"event_map":{},"environment":"production","external_source_key":"sample-token","inbound_url":"https://example.com/resource","commerce_webhook_url":"https://example.com/resource","webhook_configured":true,"access_token_preview":"sample access token preview","access_token":"sample-token","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}},"description":"Update a sync source (admin). Applies the submitted changes to the Sync sources resource."},"put":{"tags":["Catalog Sync Sources"],"operationId":"update-catalog-sync-source-via-put","summary":"Update a sync source via PUT (admin)","description":"PUT is accepted with the same partial-update semantics as PATCH for an account-scoped sync source. Unknown configuration keys are discarded; connector credentials and webhook secrets are encrypted and never serialized back.","security":[{"userApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/sync_source_payload_wrapper"},"example":{"sync_source":{"name":"Sample Name","source_type":"generic","direction":"inbound","status":"disabled","schedule_minutes":60,"webhook_secret":"sample-token","credentials":{"graph_token":"sample-token","access_token":"sample-token","store_id":"sample store id","user_id":"sample user id","client_id":"sample client id","client_secret":"sample-token","account_id":"sample account id","basic_token":"sample-token","sync_auth_token":"sample-token","sync_auth_username":"sample sync auth username","sync_auth_password":"sample sync auth password"},"settings":{"external_source":"sample external source","http_method":"get","base_url":"https://example.com/resource","products_path":"sample products path","products_root":"sample products root","format":"json","request_body":"sample request body","catalog_id":"sample catalog id","phone_number_id":"+5511999998888","waba_id":"sample waba id","inbox_id":1,"store_id":"sample store id","user_id":"sample user id","user_agent":"Mozilla/5.0","environment":"production","api_version":"sample api version","base_host":"https://example.com/resource","locale":"en","mapping":{"name":"Sample Name","external_id":"sample external id","description":"A short description.","slug":"sample-slug","status":"active","category":"sample category","price":"sample price","compare_at_price":"sample compare at price","currency":"BRL","sku":"sample sku","stock":"sample stock","brand":"sample brand","external_url":"https://example.com/resource","variants":"sample variants","images":"sample images","attachments":"sample attachments","kind":"sample kind","custom_attributes":{}},"auth":{"type":"none","header":"sample header","param":"sample param","user_agent":"Mozilla/5.0","token":"sample-token","username":"sample username","password":"sample-password"},"pagination":{"style":"link","param":"sample param","cursor_path":"sample cursor path"},"generic_webhook":{"event_path":"event","external_id_path":"id","amount_path":"sample amount path","currency_path":"sample currency path","payment_method_path":"sample payment method path","checkout_url_path":"sample checkout url path","contact_email_path":"agent@example.com","contact_name_path":"sample contact name path","contact_phone_path":"+5511999998888","product_id_path":"sample product id path","product_name_path":"sample product name path","product_sku_path":"sample product sku path","variation_id_path":"sample variation id path","variation_name_path":"sample variation name path","variation_sku_path":"sample variation sku path","items_path":"sample items path","item_id_path":"sample item id path","item_product_id_path":"sample item product id path","item_variant_id_path":"sample item variant id path","item_name_path":"sample item name path","item_sku_path":"sample item sku path","item_quantity_path":"sample item quantity path","item_unit_price_path":"sample item unit price path","item_total_price_path":"sample item total price path","item_currency_path":"sample item currency path","replay_window_seconds":300,"outbound_url":"https://example.com/resource","events":{}},"hotmart":{"events":{"PURCHASE_APPROVED":"sample PURCHASE APPROVED","PURCHASE_COMPLETE":"sample PURCHASE COMPLETE","PURCHASE_CANCELED":"sample PURCHASE CANCELED","PURCHASE_EXPIRED":"sample PURCHASE EXPIRED","PURCHASE_REFUNDED":"sample PURCHASE REFUNDED","PURCHASE_CHARGEBACK":"sample PURCHASE CHARGEBACK","PURCHASE_PROTEST":"sample PURCHASE PROTEST","PURCHASE_BILLET_PRINTED":"sample PURCHASE BILLET PRINTED","PURCHASE_DELAYED":"sample PURCHASE DELAYED","PURCHASE_OUT_OF_SHOPPING_CART":"sample PURCHASE OUT OF SHOPPING CART","SUBSCRIPTION_CANCELLATION":"sample SUBSCRIPTION CANCELLATION","SWITCH_PLAN":"sample SWITCH PLAN","UPDATE_SUBSCRIPTION_CHARGE_DATE":"sample UPDATE SUBSCRIPTION CHARGE DATE","CLUB_FIRST_ACCESS":"sample CLUB FIRST ACCESS","CLUB_MODULE_COMPLETED":"sample CLUB MODULE COMPLETED"}},"kiwify":{"events":{"compra_aprovada":"sample compra aprovada","compra_recusada":"sample compra recusada","compra_reembolsada":"sample compra reembolsada","chargeback":"sample chargeback","pix_gerado":"sample pix gerado","boleto_gerado":"sample boleto gerado","carrinho_abandonado":"sample carrinho abandonado","subscription_canceled":"sample subscription canceled","subscription_late":"sample subscription late","subscription_renewed":"sample subscription renewed"}},"nuvemshop":{"events":{"paid":"sample paid","authorized":"sample authorized","pending":"sample pending","refunded":"sample refunded","partially_refunded":"sample partially refunded","abandoned":"sample abandoned"}}}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"$ref":"#/components/schemas/catalog_sync_source"}}},"example":{"payload":{"id":1,"account_id":1,"name":"Sample Name","source_type":"generic","direction":"inbound","status":"disabled","schedule_minutes":60,"settings":{"external_source":"sample external source","http_method":"get","base_url":"https://example.com/resource","products_path":"sample products path","products_root":"sample products root","format":"json","request_body":"sample request body","catalog_id":"sample catalog id","phone_number_id":"+5511999998888","waba_id":"sample waba id","inbox_id":1,"store_id":"sample store id","user_id":"sample user id","user_agent":"Mozilla/5.0","environment":"production","api_version":"sample api version","base_host":"https://example.com/resource","locale":"en","mapping":{"name":"Sample Name","external_id":"sample external id","description":"A short description.","slug":"sample-slug","status":"active","category":"sample category","price":"sample price","compare_at_price":"sample compare at price","currency":"BRL","sku":"sample sku","stock":"sample stock","brand":"sample brand","external_url":"https://example.com/resource","variants":"sample variants","images":"sample images","attachments":"sample attachments","kind":"sample kind","custom_attributes":{}},"auth":{"type":"none","header":"sample header","param":"sample param","user_agent":"Mozilla/5.0","token":"sample-token","username":"sample username","password":"sample-password"},"pagination":{"style":"link","param":"sample param","cursor_path":"sample cursor path"},"generic_webhook":{"event_path":"event","external_id_path":"id","amount_path":"sample amount path","currency_path":"sample currency path","payment_method_path":"sample payment method path","checkout_url_path":"sample checkout url path","contact_email_path":"agent@example.com","contact_name_path":"sample contact name path","contact_phone_path":"+5511999998888","product_id_path":"sample product id path","product_name_path":"sample product name path","product_sku_path":"sample product sku path","variation_id_path":"sample variation id path","variation_name_path":"sample variation name path","variation_sku_path":"sample variation sku path","items_path":"sample items path","item_id_path":"sample item id path","item_product_id_path":"sample item product id path","item_variant_id_path":"sample item variant id path","item_name_path":"sample item name path","item_sku_path":"sample item sku path","item_quantity_path":"sample item quantity path","item_unit_price_path":"sample item unit price path","item_total_price_path":"sample item total price path","item_currency_path":"sample item currency path","replay_window_seconds":300,"outbound_url":"https://example.com/resource","events":{}},"hotmart":{"events":{"PURCHASE_APPROVED":"sample PURCHASE APPROVED","PURCHASE_COMPLETE":"sample PURCHASE COMPLETE","PURCHASE_CANCELED":"sample PURCHASE CANCELED","PURCHASE_EXPIRED":"sample PURCHASE EXPIRED","PURCHASE_REFUNDED":"sample PURCHASE REFUNDED","PURCHASE_CHARGEBACK":"sample PURCHASE CHARGEBACK","PURCHASE_PROTEST":"sample PURCHASE PROTEST","PURCHASE_BILLET_PRINTED":"sample PURCHASE BILLET PRINTED","PURCHASE_DELAYED":"sample PURCHASE DELAYED","PURCHASE_OUT_OF_SHOPPING_CART":"sample PURCHASE OUT OF SHOPPING CART","SUBSCRIPTION_CANCELLATION":"sample SUBSCRIPTION CANCELLATION","SWITCH_PLAN":"sample SWITCH PLAN","UPDATE_SUBSCRIPTION_CHARGE_DATE":"sample UPDATE SUBSCRIPTION CHARGE DATE","CLUB_FIRST_ACCESS":"sample CLUB FIRST ACCESS","CLUB_MODULE_COMPLETED":"sample CLUB MODULE COMPLETED"}},"kiwify":{"events":{"compra_aprovada":"sample compra aprovada","compra_recusada":"sample compra recusada","compra_reembolsada":"sample compra reembolsada","chargeback":"sample chargeback","pix_gerado":"sample pix gerado","boleto_gerado":"sample boleto gerado","carrinho_abandonado":"sample carrinho abandonado","subscription_canceled":"sample subscription canceled","subscription_late":"sample subscription late","subscription_renewed":"sample subscription renewed"}},"nuvemshop":{"events":{"paid":"sample paid","authorized":"sample authorized","pending":"sample pending","refunded":"sample refunded","partially_refunded":"sample partially refunded","abandoned":"sample abandoned"}}},"last_synced_at":"2026-01-15T10:30:00.000Z","last_pushed_at":"2026-01-15T10:30:00.000Z","last_status":"pending","last_error":"sample last error","stats":{"total":1,"scanned":1,"selected":1,"created":1,"updated":1,"skipped":1,"failed":1,"repaired":1,"meta_validated":1,"meta_rejected":1,"dry_run":true,"truncated":true,"failed_ids":[{"external_id":"sample external id","name":"Sample Name","reason":"Sample reason."}],"warning_ids":[{"external_id":"sample external id","name":"Sample Name","reason":"Sample reason."}],"skipped_ids":[{"external_id":"sample external id","name":"Sample Name","reason":"Sample reason."}]},"capabilities":{},"meta_catalog":true,"event_map":{},"environment":"production","external_source_key":"sample-token","inbound_url":"https://example.com/resource","commerce_webhook_url":"https://example.com/resource","webhook_configured":true,"access_token_preview":"sample access token preview","access_token":"sample-token","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"delete":{"tags":["Catalog Sync Sources"],"operationId":"delete-catalog-sync-source","summary":"Delete a sync source (admin)","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Success"}},"description":"Delete a sync source (admin). Removes the targeted Sync sources resource."}},"/api/v1/accounts/{account_id}/catalog/sync_sources/{id}/run_now":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"id","in":"path","required":true,"schema":{"type":"number"}}],"post":{"tags":["Catalog Sync Sources"],"operationId":"run-catalog-sync-now","summary":"Enqueue an immediate pull (admin)","description":"Starts an out-of-band inbound pull for an enabled, readable inbound or bidirectional sync source without waiting for its schedule. A run is opened immediately in the `pending` state and marked as manually triggered, then the import itself happens in the background — which is why the answer is `202 Accepted` rather than a result. The body carries the identifier of the run that was opened, so the caller can follow it through the sync runs of this account instead of polling the source. Administrator only.","security":[{"userApiKey":[]}],"responses":{"202":{"description":"Pull accepted. The run row already exists; its status and statistics are filled in as the background import progresses.","content":{"application/json":{"schema":{"type":"object","properties":{"run_id":{"type":"integer","description":"Identifier of the sync run that was opened for this pull. Use it to follow the run to completion and to read the resulting statistics."}}},"example":{"run_id":90412}}}},"401":{"description":"The current user is not an administrator of this account.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Why the request was refused."}}},"example":{"error":"You are not authorized to do this action"}}}},"404":{"description":"No such sync source in this account.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Why the record could not be resolved."}}},"example":{"error":"Resource could not be found"}}}},"422":{"description":"The source is disabled, read-only, or no longer configured for inbound synchronization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Why the source cannot execute this pull."}}},"example":{"error":"The source is disabled or cannot run an inbound synchronization."}}}}}}},"/api/v1/accounts/{account_id}/catalog/sync_sources/{id}/push_now":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"id","in":"path","required":true,"schema":{"type":"number"}}],"post":{"tags":["Catalog Sync Sources"],"operationId":"push-catalog-sync-now","summary":"Enqueue an immediate outbound publication (admin)","description":"Queues every active account product for publication through an enabled, writable outbound or bidirectional sync source. Each product is resolved again inside the source account when its job executes, and a source that was disabled or reconfigured after enqueue is skipped. The response is `202 Accepted` because publication and provider validation continue in background jobs.","security":[{"userApiKey":[]}],"responses":{"202":{"description":"Products accepted for asynchronous publication.","content":{"application/json":{"schema":{"type":"object","properties":{"enqueued":{"type":"integer","minimum":0,"description":"Number of active account products queued for this source."}}},"example":{"enqueued":24}}}},"401":{"description":"The current user is not an administrator of this account.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Why the request was refused."}}},"example":{"error":"You are not authorized to do this action"}}}},"404":{"description":"No such sync source in this account.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Why the record could not be resolved."}}},"example":{"error":"Resource could not be found"}}}},"422":{"description":"The source is disabled, read-only, or no longer configured for outbound synchronization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Why the source cannot execute this publication."}}},"example":{"error":"The source is disabled or cannot run an outbound synchronization."}}}}}}},"/api/v1/accounts/{account_id}/catalog/sync_sources/{id}/rotate_token":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"id","in":"path","required":true,"schema":{"type":"number"}}],"post":{"tags":["Catalog Sync Sources"],"operationId":"rotate-catalog-sync-token","summary":"Rotate the inbound HMAC secret (admin)","description":"Invalidates the previous inbound bulk-sync secret immediately, requests native audit capture without secret material when that account feature is enabled, and returns the new secret exactly in this response. Ordinary reads return only a masked preview. This does not rotate a provider-managed commerce webhook secret.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Source with the newly generated inbound secret revealed once.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/catalog_sync_source"},{"type":"object","required":["access_token"]}]},"example":{"id":1,"account_id":1,"name":"Sample Name","source_type":"generic","direction":"inbound","status":"disabled","schedule_minutes":60,"settings":{"external_source":"sample external source","http_method":"get","base_url":"https://example.com/resource","products_path":"sample products path","products_root":"sample products root","format":"json","request_body":"sample request body","catalog_id":"sample catalog id","phone_number_id":"+5511999998888","waba_id":"sample waba id","inbox_id":1,"store_id":"sample store id","user_id":"sample user id","user_agent":"Mozilla/5.0","environment":"production","api_version":"sample api version","base_host":"https://example.com/resource","locale":"en","mapping":{"name":"Sample Name","external_id":"sample external id","description":"A short description.","slug":"sample-slug","status":"active","category":"sample category","price":"sample price","compare_at_price":"sample compare at price","currency":"BRL","sku":"sample sku","stock":"sample stock","brand":"sample brand","external_url":"https://example.com/resource","variants":"sample variants","images":"sample images","attachments":"sample attachments","kind":"sample kind","custom_attributes":{}},"auth":{"type":"none","header":"sample header","param":"sample param","user_agent":"Mozilla/5.0","token":"sample-token","username":"sample username","password":"sample-password"},"pagination":{"style":"link","param":"sample param","cursor_path":"sample cursor path"},"generic_webhook":{"event_path":"event","external_id_path":"id","amount_path":"sample amount path","currency_path":"sample currency path","payment_method_path":"sample payment method path","checkout_url_path":"sample checkout url path","contact_email_path":"agent@example.com","contact_name_path":"sample contact name path","contact_phone_path":"+5511999998888","product_id_path":"sample product id path","product_name_path":"sample product name path","product_sku_path":"sample product sku path","variation_id_path":"sample variation id path","variation_name_path":"sample variation name path","variation_sku_path":"sample variation sku path","items_path":"sample items path","item_id_path":"sample item id path","item_product_id_path":"sample item product id path","item_variant_id_path":"sample item variant id path","item_name_path":"sample item name path","item_sku_path":"sample item sku path","item_quantity_path":"sample item quantity path","item_unit_price_path":"sample item unit price path","item_total_price_path":"sample item total price path","item_currency_path":"sample item currency path","replay_window_seconds":300,"outbound_url":"https://example.com/resource","events":{}},"hotmart":{"events":{"PURCHASE_APPROVED":"sample PURCHASE APPROVED","PURCHASE_COMPLETE":"sample PURCHASE COMPLETE","PURCHASE_CANCELED":"sample PURCHASE CANCELED","PURCHASE_EXPIRED":"sample PURCHASE EXPIRED","PURCHASE_REFUNDED":"sample PURCHASE REFUNDED","PURCHASE_CHARGEBACK":"sample PURCHASE CHARGEBACK","PURCHASE_PROTEST":"sample PURCHASE PROTEST","PURCHASE_BILLET_PRINTED":"sample PURCHASE BILLET PRINTED","PURCHASE_DELAYED":"sample PURCHASE DELAYED","PURCHASE_OUT_OF_SHOPPING_CART":"sample PURCHASE OUT OF SHOPPING CART","SUBSCRIPTION_CANCELLATION":"sample SUBSCRIPTION CANCELLATION","SWITCH_PLAN":"sample SWITCH PLAN","UPDATE_SUBSCRIPTION_CHARGE_DATE":"sample UPDATE SUBSCRIPTION CHARGE DATE","CLUB_FIRST_ACCESS":"sample CLUB FIRST ACCESS","CLUB_MODULE_COMPLETED":"sample CLUB MODULE COMPLETED"}},"kiwify":{"events":{"compra_aprovada":"sample compra aprovada","compra_recusada":"sample compra recusada","compra_reembolsada":"sample compra reembolsada","chargeback":"sample chargeback","pix_gerado":"sample pix gerado","boleto_gerado":"sample boleto gerado","carrinho_abandonado":"sample carrinho abandonado","subscription_canceled":"sample subscription canceled","subscription_late":"sample subscription late","subscription_renewed":"sample subscription renewed"}},"nuvemshop":{"events":{"paid":"sample paid","authorized":"sample authorized","pending":"sample pending","refunded":"sample refunded","partially_refunded":"sample partially refunded","abandoned":"sample abandoned"}}},"last_synced_at":"2026-01-15T10:30:00.000Z","last_pushed_at":"2026-01-15T10:30:00.000Z","last_status":"pending","last_error":"sample last error","stats":{"total":1,"scanned":1,"selected":1,"created":1,"updated":1,"skipped":1,"failed":1,"repaired":1,"meta_validated":1,"meta_rejected":1,"dry_run":true,"truncated":true,"failed_ids":[{"external_id":"sample external id","name":"Sample Name","reason":"Sample reason."}],"warning_ids":[{"external_id":"sample external id","name":"Sample Name","reason":"Sample reason."}],"skipped_ids":[{"external_id":"sample external id","name":"Sample Name","reason":"Sample reason."}]},"capabilities":{},"meta_catalog":true,"event_map":{},"environment":"production","external_source_key":"sample-token","inbound_url":"https://example.com/resource","commerce_webhook_url":"https://example.com/resource","webhook_configured":true,"access_token_preview":"sample access token preview","access_token":"sample-token","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}},"403":{"description":"Administrator access required"},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/catalog/sync_sources/{id}/meta_reconciliation":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"id","in":"path","required":true,"schema":{"type":"number"}}],"get":{"tags":["Catalog Sync Sources"],"operationId":"preview-meta-catalog-orphans","summary":"Preview remote Meta catalog orphans (admin)","description":"Reads every available page of the bound Meta catalog and returns only remote retailer ids that do not have a local product variation. This endpoint never removes an item. Rows without a retailer_id are reported only as an unmanaged count because they cannot be safely targeted. Administrator only.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"A read-only reconciliation preview.","content":{"application/json":{"schema":{"type":"object","required":["remote_total","orphan_count","deletion_threshold_percent","orphans"],"properties":{"remote_total":{"type":"integer","example":120},"orphan_count":{"type":"integer","example":3},"orphan_percent":{"type":"number","format":"float","example":2.5},"deletion_threshold_percent":{"type":"number","format":"float","example":10},"unmanaged_remote_count":{"type":"integer","description":"Remote rows with no retailer_id","never offered for deletion.":null,"example":1},"orphans":{"type":"array","items":{"type":"object","required":["retailer_id","name"],"properties":{"retailer_id":{"type":"string","example":"cw_v_812"},"name":{"type":"string","example":"Archived product variation"}}}}}},"example":{"remote_total":120,"orphan_count":3,"orphan_percent":2.5,"deletion_threshold_percent":10,"unmanaged_remote_count":1,"orphans":[{"retailer_id":"cw_v_812","name":"Archived product variation"}]}}}},"422":{"description":"The source is not an outbound Meta catalog, or a complete safe preview could not be produced.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"502":{"description":"Meta could not be queried. No remote write was attempted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/catalog/sync_sources/{id}/delete_meta_orphans":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"id","in":"path","required":true,"schema":{"type":"number"}}],"post":{"tags":["Catalog Sync Sources"],"operationId":"submit-meta-catalog-orphan-removal","summary":"Submit explicitly selected Meta catalog orphan removals (admin)","description":"Re-reads the remote catalog, verifies that every requested retailer id is still orphaned, and refuses a request above the source's configured safety threshold (10% by default) of the complete remote catalog. Meta validates the asynchronous batch afterwards; `202 Accepted` means only that the request was submitted, never that the products have already been deleted. Administrator only.","security":[{"userApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["retailer_ids"],"properties":{"retailer_ids":{"type":"array","minItems":1,"uniqueItems":true,"description":"Retailer ids selected by the administrator from a reconciliation preview.","items":{"type":"string"},"example":["cw_v_812"]}}},"example":{"retailer_ids":["cw_v_812"]}}}},"responses":{"202":{"description":"Removal batch submitted to Meta for asynchronous validation; no deletion is claimed yet.","content":{"application/json":{"schema":{"type":"object","required":["submitted_retailer_ids","handle","status"],"properties":{"submitted_retailer_ids":{"type":"array","items":{"type":"string"},"example":["cw_v_812"]},"handle":{"type":"string","description":"Meta batch-validation handle.","example":"batch_abc123"},"status":{"type":"string","enum":["pending_validation"],"example":"pending_validation"}}},"example":{"submitted_retailer_ids":["cw_v_812"],"handle":"batch_abc123","status":"pending_validation"}}}},"422":{"description":"Empty, stale or too-large selection; no remote write was attempted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"502":{"description":"Meta could not be queried or did not accept a verifiable batch; no deletion is confirmed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/catalog/sync_runs":{"parameters":[{"$ref":"#/components/parameters/account_id"}],"get":{"tags":["Catalog Sync Runs"],"operationId":"list-catalog-sync-runs","summary":"List import/export/sync runs (admin)","security":[{"userApiKey":[]}],"parameters":[{"name":"q","in":"query","required":false,"description":"Case-insensitive search by source name, trigger, or format.","schema":{"type":"string","maxLength":200}},{"name":"direction","in":"query","required":false,"description":"Restrict to runs of one direction.","schema":{"type":"string","enum":["import","export","inbound","outbound"]},"example":"import"},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["pending","processing","completed","failed","partial"]}},{"name":"trigger","in":"query","required":false,"schema":{"type":"string","enum":["manual","scheduled","webhook","api","event","backfill","hotmart_sales_backfill","kiwify_sales_backfill","inventory_decrement"]}},{"name":"source_id","in":"query","required":false,"schema":{"type":"integer","minimum":1}},{"name":"sort","in":"query","required":false,"schema":{"type":"string","enum":["created_at","started_at","finished_at","status","direction"],"default":"created_at"}},{"name":"order","in":"query","required":false,"schema":{"type":"string","enum":["asc","desc"],"default":"desc"}},{"name":"page","in":"query","required":false,"description":"Page of runs, newest first.","schema":{"type":"integer","default":1},"example":1},{"name":"per_page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":25}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","required":["payload","meta"],"properties":{"payload":{"type":"array","items":{"$ref":"#/components/schemas/catalog_sync_run"}},"meta":{"type":"object","required":["count","current_page","per_page","total_pages"],"properties":{"count":{"type":"integer","minimum":0},"current_page":{"type":"integer","minimum":1},"per_page":{"type":"integer","minimum":1,"maximum":100},"total_pages":{"type":"integer","minimum":0}}}}},"example":{"payload":[{"id":1,"account_id":1,"catalog_sync_source_id":1,"source_name":"sample source name","direction":"import","trigger":"manual","status":"pending","format":"sample format","stats":{"total":1,"scanned":1,"selected":1,"created":1,"updated":1,"skipped":1,"failed":1,"repaired":1,"meta_validated":1,"meta_rejected":1,"dry_run":true,"truncated":true,"failed_ids":[{"external_id":"sample external id","name":"Sample Name","reason":"Sample reason."}],"warning_ids":[{"external_id":"sample external id","name":"Sample Name","reason":"Sample reason."}],"skipped_ids":[{"external_id":"sample external id","name":"Sample Name","reason":"Sample reason."}]},"error":"sample error","started_at":"2026-01-15T10:30:00.000Z","finished_at":"2026-01-15T10:30:00.000Z","window_from":"2026-01-15T10:30:00.000Z","window_to":"2026-01-15T10:30:00.000Z","undoable":true,"undone_at":"2026-01-15T10:30:00.000Z","undone_by_id":1,"inventory_failure":true,"inventory_sale_type":"payment_charge","inventory_sale_id":1,"inventory_retryable":true,"result_file_url":"https://example.com/resource","error_file_url":"https://example.com/resource","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}],"meta":{"count":5,"current_page":1,"per_page":1,"total_pages":1}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"403":{"description":"Administrator access required"}},"description":"List import/export/sync runs (admin). Returns Sync runs data for the current context."}},"/api/v1/accounts/{account_id}/catalog/sync_runs/export":{"parameters":[{"$ref":"#/components/parameters/account_id"}],"get":{"tags":["Catalog Sync Runs"],"operationId":"export-catalog-sync-runs","summary":"Export filtered or selected sync runs as CSV (admin)","description":"Exports the complete account-scoped ledger matching the same filters as the list endpoint. When ids are supplied, only those selected records are exported. Missing, foreign, or no-longer-matching ids are reported in the X-Failed-Ids header; diagnostic text is redacted and spreadsheet formulas are escaped.","security":[{"userApiKey":[]}],"parameters":[{"name":"ids","in":"query","required":false,"description":"Optional explicit selection. Omit to export every row matching the filters.","style":"form","explode":true,"schema":{"type":"array","minItems":1,"maxItems":500,"uniqueItems":true,"items":{"type":"integer","minimum":1}}},{"name":"q","in":"query","required":false,"schema":{"type":"string","maxLength":200}},{"name":"direction","in":"query","required":false,"schema":{"type":"string","enum":["import","export","inbound","outbound"]}},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["pending","processing","completed","failed","partial"]}},{"name":"trigger","in":"query","required":false,"schema":{"type":"string","enum":["manual","scheduled","webhook","api","event","backfill","hotmart_sales_backfill","kiwify_sales_backfill","inventory_decrement"]}},{"name":"source_id","in":"query","required":false,"schema":{"type":"integer","minimum":1}},{"name":"sort","in":"query","required":false,"schema":{"type":"string","enum":["created_at","started_at","finished_at","status","direction"],"default":"created_at"}},{"name":"order","in":"query","required":false,"schema":{"type":"string","enum":["asc","desc"],"default":"desc"}}],"responses":{"200":{"description":"CSV generated; X-Failed-Ids is empty on a complete selected export.","headers":{"X-Failed-Ids":{"description":"Comma-separated selected ids that were not visible in the filtered account scope.","schema":{"type":"string"}}},"content":{"text/csv":{"schema":{"type":"string","format":"binary"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"403":{"description":"Administrator access required"},"422":{"description":"Empty, malformed, duplicate, or oversized explicit selection","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/catalog/sync_runs/{id}":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"id","in":"path","required":true,"schema":{"type":"number"}}],"get":{"tags":["Catalog Sync Runs"],"operationId":"get-catalog-sync-run","summary":"Get a sync run (admin)","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"$ref":"#/components/schemas/catalog_sync_run"}}},"example":{"payload":{"id":1,"account_id":1,"catalog_sync_source_id":1,"source_name":"sample source name","direction":"import","trigger":"manual","status":"pending","format":"sample format","stats":{"total":1,"scanned":1,"selected":1,"created":1,"updated":1,"skipped":1,"failed":1,"repaired":1,"meta_validated":1,"meta_rejected":1,"dry_run":true,"truncated":true,"failed_ids":[{"external_id":"sample external id","name":"Sample Name","reason":"Sample reason."}],"warning_ids":[{"external_id":"sample external id","name":"Sample Name","reason":"Sample reason."}],"skipped_ids":[{"external_id":"sample external id","name":"Sample Name","reason":"Sample reason."}]},"error":"sample error","started_at":"2026-01-15T10:30:00.000Z","finished_at":"2026-01-15T10:30:00.000Z","window_from":"2026-01-15T10:30:00.000Z","window_to":"2026-01-15T10:30:00.000Z","undoable":true,"undone_at":"2026-01-15T10:30:00.000Z","undone_by_id":1,"inventory_failure":true,"inventory_sale_type":"payment_charge","inventory_sale_id":1,"inventory_retryable":true,"result_file_url":"https://example.com/resource","error_file_url":"https://example.com/resource","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}},"description":"Get a sync run (admin). Returns the requested Sync runs resource."}},"/api/v1/accounts/{account_id}/catalog/sync_runs/{id}/retry_inventory":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1}}],"post":{"tags":["Catalog Sync Runs"],"operationId":"retry-inventory-catalog-sync-run","summary":"Retry a terminal inventory decrement (admin)","description":"Re-enqueues the account-scoped charge or CRM order stored by a terminal automatic stock-decrement failure. The background worker reloads the sale inside this account and reuses the canonical stock movement receipt, so retrying after an ambiguous attempt cannot decrement the same sale twice. The response never contains a provider payload, credential, or raw exception message.","security":[{"userApiKey":[]}],"responses":{"202":{"description":"Retry accepted; the durable run is pending and can be followed in the run history.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/catalog_sync_run"},"example":{"id":381,"account_id":1,"catalog_sync_source_id":null,"source_name":null,"direction":"inbound","trigger":"inventory_decrement","status":"pending","format":"payment_charge","stats":{"total":1,"repaired":0,"skipped":0,"failed":0,"failed_ids":[{"external_id":"sample external id","name":"Sample Name","reason":"Sample reason."}],"scanned":1,"selected":1,"created":1,"updated":1,"meta_validated":1,"meta_rejected":1,"dry_run":true,"truncated":true,"warning_ids":[{"external_id":"sample external id","name":"Sample Name","reason":"Sample reason."}],"skipped_ids":[{"external_id":"sample external id","name":"Sample Name","reason":"Sample reason."}]},"error":null,"started_at":null,"finished_at":null,"window_from":null,"window_to":null,"undoable":false,"undone_at":null,"undone_by_id":null,"inventory_failure":true,"inventory_sale_type":"payment_charge","inventory_sale_id":912,"inventory_retryable":false,"result_file_url":null,"error_file_url":null,"created_at":"2026-08-05T12:00:00Z","updated_at":"2026-08-05T12:05:00Z"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Administrator or catalog_manage access is required."},"404":{"description":"The run does not exist in this account."},"409":{"description":"The run is not a failed inventory decrement or a retry is already in progress.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"error":"inventory_retry_not_available","description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"503":{"description":"The retry could not be queued; the run remains durably failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"error":"inventory_retry_enqueue_failed","description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/catalog/sync/inbound":{"parameters":[{"$ref":"#/components/parameters/account_id"}],"post":{"tags":["Catalog Sync Inbound"],"operationId":"catalog-sync-inbound","summary":"Inbound bulk product upsert (HMAC-authenticated, machine-to-machine)","security":[{"catalogSyncHmac":[]}],"description":"Machine-to-machine endpoint: it is NOT session-authenticated and carries none of the account API keys. Each delivery is authenticated by the per-source HMAC secret, addressed to a single sync source, and de-duplicated for one hour, then the products are upserted asynchronously and a run id is returned. The body is a JSON array of normalized product payloads; an object of the form `{ \"products\": [ ... ] }` wrapping the same array is also accepted. Anything else is rejected as unprocessable.\n","parameters":[{"name":"X-Catalog-Sync-Source","in":"header","required":true,"description":"Id of the catalog sync source this delivery belongs to. It selects the secret the signature is verified against, so it must be sent before anything else can be checked. The `source_id` query parameter below is the fallback carrier; an id that does not belong to the account in the path is rejected with 404.","schema":{"type":"string","example":"12"}},{"name":"source_id","in":"query","required":false,"description":"Fallback carrier for the sync source id, used only when the X-Catalog-Sync-Source header is absent.","schema":{"type":"string"}},{"name":"X-Catalog-Signature","in":"header","required":true,"description":"`sha256=` followed by the hex-encoded `HMAC_SHA256(\u003csync source access token\u003e, \"\u003cX-Catalog-Timestamp\u003e.\u003craw request body\u003e\")`. Compared in constant time; a missing or mismatching value is rejected with 401.","schema":{"type":"string","example":"sha256=6f3a1c9d05b7e2a48c1f0d63b8e57a92d4c1b0f7e39a6c25d81f4b70a2e6c318"}},{"name":"X-Catalog-Timestamp","in":"header","required":true,"description":"Unix time in seconds at which the delivery was signed. It is the first half of the signed string above, so a delivery signed without it will not verify.","schema":{"type":"string","example":"1778735498"}},{"name":"X-Catalog-Delivery","in":"header","required":false,"description":"Per-delivery identifier used to de-duplicate the upsert for one hour. A repeat of an id already seen is answered 200 and dropped rather than upserted a second time. When the header is absent the delivery is not de-duplicated, so a sender retry upserts twice.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/product_payload"}},"example":[{"name":"Sample Name","description":"A short description.","kind":"product","status":"draft","catalog_category_id":1,"default_variant_id":1,"slug":"sample-slug","custom_attributes":{},"additional_attributes":{},"variants_attributes":[{"id":1,"sku":"sample sku","name":"Sample Name","price":149.9,"currency":"BRL","compare_at_price":149.9,"track_inventory":true,"stock_quantity":12.5,"barcode":"sample barcode","position":1,"options":{},"catalog_product_image_id":1,"default":true,"_destroy":true}]}]}}},"responses":{"202":{"description":"Accepted. The products were queued for asynchronous bulk upsert and a sync run was opened; poll the sync run identified by `run_id` for the outcome.","content":{"application/json":{"schema":{"type":"object","properties":{"run_id":{"type":"number","description":"Id of the sync run opened for this delivery."},"accepted":{"type":"number","description":"Number of product payloads queued for upsert."}}},"example":{"run_id":4821,"accepted":37}}}},"200":{"description":"Duplicate delivery — the X-Catalog-Delivery id was already seen inside the one-hour window, so nothing was upserted. Deliberately a success: the sender must clear the delivery from its retry buffer rather than keep retrying it.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Always `duplicate delivery` for this status."}}},"example":{"error":"duplicate delivery"}}}},"401":{"description":"The X-Catalog-Signature header is missing or does not match the signature recomputed from the source's access token, the timestamp and the raw body.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Always `invalid signature` for this status."}}},"example":{"error":"invalid signature"}}}},"403":{"description":"The sync source exists but cannot ingest: it is disabled (`sync source disabled`), or it is configured for outbound push only, so inbound deliveries are refused (`inbound not allowed for this source`).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["sync source disabled","inbound not allowed for this source"]}}},"example":{"error":"sync source disabled"}}}},"404":{"description":"No account matches the id in the path (`account not found`), or the account has no sync source with the id presented in X-Catalog-Sync-Source / `source_id` (`sync source not found`).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["account not found","sync source not found"]}}},"example":{"error":"sync source not found"}}}},"422":{"description":"The body is not valid JSON, or it is neither a JSON array of products nor an object with a `products` array.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Always `payload must be a JSON array of products` for this status."}}},"example":{"error":"payload must be a JSON array of products"}}}}}}},"/api/v1/accounts/{account_id}/whatsapp_web_calls/{id}/stream":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Id of the WhatsApp Web call being streamed."}],"get":{"tags":["WhatsApp Web Calls"],"operationId":"whatsapp-web-call-media-stream","summary":"WhatsApp Web call media-stream WebSocket","security":[{"whatsappCallTicket":[]}],"description":"WebSocket-upgrade endpoint that bridges the browser's raw PCM audio to the WazMeow call media stream. It does NOT accept the account API key — a WebSocket upgrade cannot carry authentication headers, so the only credential is the short-lived signed `ticket` query parameter minted by the authenticated REST call action. On a valid WS upgrade the socket is hijacked and no HTTP body is returned; a non-WebSocket request receives 426 Upgrade Required. Failure modes: 401 (missing, bad or expired ticket, or id mismatch), 404 (call not found), 422 (inbox is not a whatsapp_web channel), 500.","parameters":[{"name":"ticket","in":"query","required":true,"description":"Short-lived signed ticket minted by the authenticated REST call action — it is the sole credential for this endpoint. It carries the `call_id` and `account_id` claims, lives 60 seconds, and its `call_id` claim must equal the `id` in the path. A missing, malformed, expired, badly-signed or mismatched ticket is rejected with 401.","schema":{"type":"string","example":"eyJjYWxsX2lkIjoxNDgyLCJhY2NvdW50X2lkIjo0MX0.9f2c1d7a4b6e8130a5c2f7e0d4b9a1c8"}}],"responses":{"200":{"description":"WebSocket upgrade accepted — the connection is hijacked for the PCM media stream; no HTTP response body is sent. The browser leg completes the handshake with a `101 Switching Protocols` frame written directly to the hijacked socket, after which binary s16le 16 kHz PCM frames are piped verbatim in both directions until either leg closes. This status is what the application layer reports once the bridge has finished; it never carries a payload."},"401":{"description":"The `ticket` query parameter is missing, malformed, expired (the ticket lives 60 seconds) or its signature does not verify, or the `call_id` claim inside the ticket does not match the `id` in the path. No body."},"404":{"description":"No WhatsApp Web call exists for the `call_id` and `account_id` claims carried by the ticket. No body."},"422":{"description":"The call's inbox is not backed by a WhatsApp channel using the `whatsapp_web` provider, so there is no media stream to bridge. No body."},"426":{"description":"The request is not a WebSocket upgrade (or the running web server does not support socket hijacking), so no bridge could be established. Plain HTTP clients always receive this. No body."},"500":{"description":"The media-stream target could not be resolved or the bridge failed while connecting to the gateway. No body."}}}},"/api/v1/accounts/{account_id}/whatsapp_web_calls/{id}/video_stream":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Id of the WhatsApp Web call being streamed."}],"get":{"tags":["WhatsApp Web Calls"],"operationId":"whatsapp-web-call-video-stream","summary":"WhatsApp Web call video-stream WebSocket","security":[{"whatsappCallTicket":[]}],"description":"WebSocket-upgrade endpoint that bridges the browser's H.264 video plane to the WazMeow call video stream (participant-framed). Inbound binary messages carry one access unit each, prefixed `[1 byte version=2][1 byte idLen][idLen bytes participant id UTF-8][Annex-B access unit]` so a group call can run one decoder per camera; a message without the prefix is the legacy single-stream framing. Outbound messages are bare Annex-B access units from the agent's camera or screen share. Text frames are the JSON control channel (server to client: participant, orientation, video-ready, keyframe; client to server: hello, client-log). The only credential is the short-lived signed `ticket` minted with the `video` kind by the authenticated REST call action — an audio/events ticket is rejected. On a valid WS upgrade the socket is hijacked and no HTTP body is returned; a non-WebSocket request receives 426 Upgrade Required.","parameters":[{"name":"ticket","in":"query","required":true,"description":"Short-lived signed ticket minted by the authenticated REST call action with the `video` stream kind. It carries the `call_id`, `account_id` and `kind` claims, lives 60 seconds, and its `call_id` claim must equal the `id` in the path. A missing, malformed, expired, badly-signed, mismatched or wrong-kind ticket is rejected with 401.","schema":{"type":"string","example":"eyJjYWxsX2lkIjoxNDgyLCJraW5kIjoidmlkZW8ifQ.4b6e8130a5c2f7e0d4b9a1c89f2c1d7a"}}],"responses":{"200":{"description":"WebSocket upgrade accepted — the connection is hijacked for the video plane; no HTTP response body is sent. Binary H.264 frames and JSON control text are piped verbatim in both directions until either leg closes. This status is what the application layer reports once the bridge has finished; it never carries a payload."},"401":{"description":"The `ticket` query parameter is missing, malformed, expired (60-second life), badly signed, carries a different stream kind, or its `call_id` claim does not match the `id` in the path. No body."},"404":{"description":"No WhatsApp Web call exists for the `call_id` and `account_id` claims carried by the ticket. No body."},"422":{"description":"The call's inbox is not backed by a WhatsApp channel using the `whatsapp_web` provider, so there is no video stream to bridge. No body."},"426":{"description":"The request is not a WebSocket upgrade (or the running web server does not support socket hijacking), so no bridge could be established. Plain HTTP clients always receive this. No body."},"500":{"description":"The video-stream target could not be resolved or the bridge failed while connecting to the gateway. No body."}}}},"/api/v1/accounts/{account_id}/whatsapp_web_calls/{id}/events_stream":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Id of the WhatsApp Web call whose in-call events are relayed."}],"get":{"tags":["WhatsApp Web Calls"],"operationId":"whatsapp-web-call-events-stream","summary":"WhatsApp Web in-call events SSE","security":[{"whatsappCallTicket":[]}],"description":"Server-Sent Events relay of the gateway's in-call event stream. On connect the gateway replays a sticky snapshot of the current call state, then streams live events; a heartbeat keeps the EventSource alive every 15 seconds. Each event's JSON data carries a `type` field — reaction, hand, mute, screenshare, group-state, waiting-room or phase — plus the type-specific fields (participant, emoji, removed, raised, muted, active, phase, state). The only credential is the short-lived signed `ticket` minted with the `events` kind by the authenticated REST call action. Because tickets live 60 seconds, clients reconnect with a FRESH ticket instead of relying on the EventSource built-in retry.","parameters":[{"name":"ticket","in":"query","required":true,"description":"Short-lived signed ticket minted by the authenticated REST call action with the `events` stream kind. It carries the `call_id`, `account_id` and `kind` claims, lives 60 seconds, and its `call_id` claim must equal the `id` in the path. A missing, malformed, expired, badly-signed, mismatched or wrong-kind ticket is rejected with 401.","schema":{"type":"string","example":"eyJjYWxsX2lkIjoxNDgyLCJraW5kIjoiZXZlbnRzIn0.a5c2f7e0d4b9a1c89f2c1d7a4b6e8130"}}],"responses":{"200":{"description":"SSE stream (`text/event-stream`) relaying the gateway's in-call events verbatim — sticky snapshot on connect, then live events and 15-second heartbeats — until the call ends or either side disconnects.","content":{"text/event-stream":{"schema":{"type":"string","description":"Raw SSE frames. Each data payload is a JSON object shaped `{\"seq\":12,\"type\":\"mute\",\"participant\":\"5521999999999@s.whatsapp.net\",\"muted\":true}`; group-state and waiting-room events nest their roster under `state`.","example":"data: {\"seq\":12,\"type\":\"mute\",\"participant\":\"5521999999999@s.whatsapp.net\",\"muted\":true}\n\n"}}}},"401":{"description":"The `ticket` query parameter is missing, malformed, expired (60-second life), badly signed, carries a different stream kind, or its `call_id` claim does not match the `id` in the path. No body."},"404":{"description":"No WhatsApp Web call exists for the `call_id` and `account_id` claims carried by the ticket. No body."},"422":{"description":"The call's inbox is not backed by a WhatsApp channel using the `whatsapp_web` provider, so there is no event stream to relay. No body."}}}},"/api/v1/accounts/{account_id}/whatsapp_web_calls/{id}/video_state_stream":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Id of the 1-to-1 WhatsApp Web call whose video state is relayed."}],"get":{"tags":["WhatsApp Web Calls"],"operationId":"whatsapp-web-call-video-state-stream","summary":"WhatsApp Web 1-to-1 video-state SSE","security":[{"whatsappCallTicket":[]}],"description":"Server-Sent Events relay of the gateway's 1-to-1 video-state stream: the peer's camera turning on or off, the audio-to-video upgrade handshake, and the call-level picture orientation (0-3, in 90-degree steps; an ABSENT orientation means unknown, not zero). Group calls do not use this stream — their per-participant state rides the in-call events SSE instead, because this stream's orientation carries no participant attribution. The only credential is the short-lived signed `ticket` minted with the `video_state` kind by the authenticated REST call action.","parameters":[{"name":"ticket","in":"query","required":true,"description":"Short-lived signed ticket minted by the authenticated REST call action with the `video_state` stream kind. It carries the `call_id`, `account_id` and `kind` claims, lives 60 seconds, and its `call_id` claim must equal the `id` in the path. A missing, malformed, expired, badly-signed, mismatched or wrong-kind ticket is rejected with 401.","schema":{"type":"string","example":"eyJjYWxsX2lkIjoxNDgyLCJraW5kIjoidmlkZW9fc3RhdGUifQ.f7e0d4b9a1c89f2c1d7a4b6e8130a5c2"}}],"responses":{"200":{"description":"SSE stream (`text/event-stream`) relaying the gateway's video-state updates verbatim until the call ends or either side disconnects.","content":{"text/event-stream":{"schema":{"type":"string","description":"Raw SSE frames. Each data payload is a JSON object such as `{\"video\":true,\"orientation\":1}` — `video` reports the peer camera state and `orientation` the call-level rotation in 90-degree steps.","example":"data: {\"video\":true,\"orientation\":1}\n\n"}}}},"401":{"description":"The `ticket` query parameter is missing, malformed, expired (60-second life), badly signed, carries a different stream kind, or its `call_id` claim does not match the `id` in the path. No body."},"404":{"description":"No WhatsApp Web call exists for the `call_id` and `account_id` claims carried by the ticket. No body."},"422":{"description":"The call's inbox is not backed by a WhatsApp channel using the `whatsapp_web` provider, so there is no video-state stream to relay. No body."}}}},"/api/v1/accounts/{account_id}/mcp/c/{public_id}":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"$ref":"#/components/parameters/mcp_public_id"},{"$ref":"#/components/parameters/mcp_protocol_version"},{"$ref":"#/components/parameters/mcp_modern_method"},{"$ref":"#/components/parameters/mcp_modern_name"}],"post":{"tags":["Mcp"],"operationId":"call-account-mcp-connection","summary":"Call an account MCP connection (JSON-RPC)","security":[{"mcpProfileBearer":[]}],"description":"Model Context Protocol endpoint for one access profile. The body is a single JSON-RPC 2.0 message (batched arrays are rejected with -32600) — typically `initialize`, `tools/list`, `tools/call`, `resources/list` or `resources/read`. Authenticate with the PROFILE's bearer secret via `Authorization: Bearer \u003csecret\u003e` (created under Settings → MCP; shown once on create/rotate). The transport is stateless, so every POST is self-contained (no session id). Legacy requests send `Accept: application/json`; modern 2026-07-28 requests must send `Accept: application/json, text/event-stream`. Every request sends `Content-Type: application/json`. This is a Streamable HTTP MCP protocol transport, not a REST tool collection: legacy clients negotiate in `initialize.params.protocolVersion`, while modern 2026-07-28 clients send the documented MCP headers and matching `_meta` envelope fields. The exposed tool list is the profile's toolset selection intersected with the super-admin ceiling, minus write tools when the profile is read-only, and bounded by both a tool COUNT cap and a response BYTE-SIZE budget for client ergonomics and transport safety — the `search_tools` and `call_tool` meta-tools and the `mcp://catalog/inventory` resource reach every tool beyond that bound, under the same policy. `tools/list` supports cursor pagination (`params.cursor` in the request, `result.nextCursor` in the response when more pages remain) for clients that follow it; the bound above is what actually protects a client that does not. Each call runs AS the profile's acting_user. A request carrying an `id` gets a JSON-RPC response; a notification (no `id`) gets 202. A request is capped at 1 MiB and a chunked request body is rejected before authentication or profile lookup. When `initialize` negotiates MCP protocol `2025-11-25`, `result.serverInfo` follows `mcp_initialize_result` and carries the safe installation title, description, website and brand icons. Older protocol versions cannot carry all visual fields; client UIs may cache or choose not to render them. `WWW-Authenticate` (RFC 9728) is only ever sent alongside a 401/403/404 — never on a 2xx success.","requestBody":{"required":true,"description":"A single JSON-RPC 2.0 request or notification (Model Context Protocol).","content":{"application/json":{"schema":{"type":"object","required":["jsonrpc","method"],"properties":{"jsonrpc":{"type":"string","enum":["2.0"],"description":"JSON-RPC protocol version — always \"2.0\".","example":"2.0"},"id":{"type":["integer","null"],"description":"Request id echoed back on the response. Omit it (or send null) to send a notification, which is acknowledged with 202 and no body.","example":1},"method":{"type":"string","description":"The MCP method to invoke — e.g. `initialize`, `tools/list`, `tools/call`, `resources/list`, `resources/read`, `ping`, or a `notifications/*` message.","example":"tools/call"},"params":{"type":"object","additionalProperties":true,"description":"Method parameters, shaped by the method — e.g. `{ \"name\": \"\u003ctool\u003e\", \"arguments\": {...} }` for `tools/call`.","example":{}}}},"example":{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"conversations_list","arguments":{"status":"open"}}}}}},"responses":{"200":{"description":"JSON-RPC 2.0 response. `result` is present on success and `error` on failure — never both. The JSON-RPC layer answers 200 even for a protocol-level `error` object.","content":{"application/json":{"schema":{"type":"object","required":["jsonrpc"],"properties":{"jsonrpc":{"type":"string","enum":["2.0"],"description":"JSON-RPC protocol version — always \"2.0\".","example":"2.0"},"id":{"type":["integer","null"],"description":"The id of the request this responds to (null when the request id could not be read).","example":1},"result":{"anyOf":[{"$ref":"#/components/schemas/mcp_initialize_result"},{"type":"object","additionalProperties":true,"description":"Result object for another supported MCP method, such as tools/list or resources/read."}],"description":"The method result, shaped by the method. For `initialize`, see `mcp_initialize_result`, including optional title, websiteUrl and icons. Absent when `error` is present.","example":{}},"error":{"type":["object","null"],"description":"JSON-RPC error object. Absent on success.","properties":{"code":{"type":"integer","description":"JSON-RPC error code — -32600 invalid request, -32601 method/tool not found, -32602 invalid params, -32603 internal error, -32700 parse error.","example":-32601},"message":{"type":"string","description":"Human-readable error message.","example":"Method not found"}}}}},"example":{"jsonrpc":"2.0","id":1,"result":{"content":[{"type":"text","text":"{\"payload\":[{\"id\":42,\"status\":\"open\"}]}"}],"isError":false,"protocolVersion":"2025-11-25","capabilities":{"tools":{"listChanged":false}},"serverInfo":{"name":"exampleco","version":"1.0.0","title":"ExampleCo Account MCP","description":"ExampleCo Account MCP server.","websiteUrl":"https://app.example.com","icons":[{"src":"https://app.example.com/brand-assets/logo_thumbnail.svg","mimeType":"image/svg+xml","sizes":["512x512"],"theme":"dark"},{"src":"https://app.example.com/brand-assets/logo.svg","mimeType":"image/svg+xml","theme":"light","sizes":["512x512"]},{"src":"https://app.example.com/brand-assets/logo_dark.svg","mimeType":"image/svg+xml","theme":"dark","sizes":["512x512"]}]}},"error":null}}}},"400":{"description":"A modern request used an unsupported MCP-Protocol-Version (-32022) or inconsistent mirrored routing headers/body values (-32020).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/mcp_modern_transport_error"},"example":{"jsonrpc":"2.0","id":1,"error":{"code":-32022,"message":"Unsupported protocol version","data":{"supported":["2026-07-28"],"requested":"2099-01-01"}}}}}},"401":{"description":"Missing profile secret, wrong secret, disabled profile, or an acting_user that is no longer a member of the account. The response advertises the OAuth Protected Resource Metadata (RFC 9728) in the `WWW-Authenticate` header."},"403":{"description":"Forbidden"},"404":{"description":"MCP is not enabled for this account/installation, or an authenticated modern client requested `subscriptions/listen`. This deployment is stateless per request and rejects that process-local streaming method explicitly with JSON-RPC -32601. Dark-shipped availability remains indistinguishable from a missing route.","content":{"application/json":{"schema":{"oneOf":[{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Why the MCP surface is unavailable.","example":"MCP is not enabled for this account"}}},{"$ref":"#/components/schemas/mcp_stateless_subscription_error"}]},"example":{"jsonrpc":"2.0","id":73,"error":{"code":-32601,"message":"Method not found","data":"subscriptions/listen is unavailable on this stateless transport"}}}}},"413":{"description":"The JSON-RPC request or generated transport response exceeds the 1 MiB MCP transport limit. An oversized request is rejected before profile lookup or authentication; a caller must inspect the underlying resource or audit trail before retrying a write after an oversized generated response.","headers":{"Cache-Control":{"description":"MCP transport errors must not be stored by an intermediary.","schema":{"type":"string","enum":["no-store"],"example":"no-store"}}},"content":{"application/json":{"schema":{"type":"object","required":["error"],"additionalProperties":false,"properties":{"error":{"type":"string","enum":["MCP payload exceeds the supported size"],"example":"MCP payload exceeds the supported size"}}},"example":{"error":"MCP payload exceeds the supported size"}}}},"422":{"description":"Unprocessable entity"},"202":{"description":"Notification accepted (a JSON-RPC message without an `id`). No response body."}}},"get":{"tags":["Mcp"],"operationId":"open-account-mcp-connection-stream","summary":"Open an account MCP connection stream (not available — stateless server)","security":[{"mcpProfileBearer":[]}],"description":"The Streamable HTTP transport reserves GET for the server-initiated SSE stream, which requires a session. This server runs stateless (multi-worker safe), so no session is ever issued and every GET is answered with a JSON-RPC \"Method not allowed\" error under HTTP 405. All MCP traffic must go over POST. The endpoint is kept so MCP clients that probe the stream fail cleanly instead of hanging. There is no success response: the route never returns 2xx.","responses":{"401":{"description":"Missing or invalid profile secret (the `WWW-Authenticate` header points at the Protected Resource Metadata)."},"403":{"description":"Forbidden"},"404":{"description":"MCP is not enabled for this account, or disabled for the whole installation. The feature is dark-shipped, so an unavailable surface is indistinguishable from a missing route.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Why the MCP surface is unavailable.","example":"MCP is not enabled for this account"}}},"example":{"error":"MCP is not enabled for this account"}}}},"405":{"description":"Method not allowed — the SSE stream is unavailable on a stateless MCP server.","content":{"application/json":{"schema":{"type":"object","required":["jsonrpc"],"properties":{"jsonrpc":{"type":"string","enum":["2.0"],"description":"JSON-RPC protocol version — always \"2.0\".","example":"2.0"},"id":{"type":["integer","null"],"description":"Always null — a GET carries no JSON-RPC request id.","example":null},"error":{"type":"object","description":"JSON-RPC error object.","properties":{"code":{"type":"integer","description":"JSON-RPC invalid-request code.","example":-32600},"message":{"type":"string","example":"Method not allowed"}}}}},"example":{"jsonrpc":"2.0","id":null,"error":{"code":-32600,"message":"Method not allowed"}}}}}}},"delete":{"tags":["Mcp"],"operationId":"close-account-mcp-connection","summary":"Terminate an account MCP connection session (no-op)","security":[{"mcpProfileBearer":[]}],"description":"MCP clients call DELETE to end a session. This server is stateless — no session is ever issued — so the call is acknowledged as a no-op. Kept for client compatibility. If an `MCP-Protocol-Version` header is sent it must name a supported protocol version, otherwise the transport answers 400.","responses":{"200":{"description":"Teardown acknowledged (no-op — the server holds no session state).","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Always true — a stateless server has no session to discard.","example":true}}},"example":{"success":true}}}},"401":{"description":"Missing or invalid profile secret."},"403":{"description":"Forbidden"},"404":{"description":"MCP is not enabled for this account, or disabled for the whole installation. The feature is dark-shipped, so an unavailable surface is indistinguishable from a missing route.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Why the MCP surface is unavailable.","example":"MCP is not enabled for this account"}}},"example":{"error":"MCP is not enabled for this account"}}}},"400":{"description":"The `MCP-Protocol-Version` header names a protocol version this server does not support.","content":{"application/json":{"schema":{"type":"object","properties":{"jsonrpc":{"type":"string","enum":["2.0"],"example":"2.0"},"id":{"type":["integer","null"],"description":"Always null — a DELETE carries no JSON-RPC request id.","example":null},"error":{"type":"object","description":"JSON-RPC error object.","properties":{"code":{"type":"integer","example":-32600},"message":{"type":"string","example":"Bad Request: Unsupported protocol version"}}}}},"example":{"jsonrpc":"2.0","id":null,"error":{"code":-32600,"message":"Bad Request: Unsupported protocol version"}}}}}}}},"/api/v1/accounts/{account_id}/mcp/oauth/c/{public_id}":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"$ref":"#/components/parameters/mcp_public_id"},{"$ref":"#/components/parameters/mcp_protocol_version"},{"$ref":"#/components/parameters/mcp_modern_method"},{"$ref":"#/components/parameters/mcp_modern_name"}],"post":{"tags":["Mcp"],"operationId":"call-account-mcp-oauth-connection","summary":"Call an OAuth-protected account MCP connection (JSON-RPC)","security":[{"mcpOauth":["mcp:read"]}],"description":"Streamable HTTP MCP endpoint for one account access profile, authenticated with a native OAuth 2.1 bearer issued for this exact URL. This is a Streamable HTTP MCP protocol transport, not a REST tool collection. The profile still bounds the selected toolsets, installation ceiling and read-only mode; every call executes as the human account member who approved the OAuth grant, never as the profile's static acting user. `mcp:write` is additionally required for a write-capable tool. Static profile secrets, personal API tokens, PlatformApp tokens and Super Admin credentials do not authenticate this endpoint. The server is stateless: send one JSON-RPC 2.0 message per POST with `Content-Type: application/json`. Legacy requests send `Accept: application/json`; modern 2026-07-28 requests must send `Accept: application/json, text/event-stream`. Legacy clients negotiate in `initialize.params.protocolVersion`; modern 2026-07-28 clients send the documented MCP headers and matching `_meta` envelope fields. An `initialize` negotiated at protocol `2025-11-25` returns the safe branded `result.serverInfo` described by `mcp_initialize_result`; a client may cache or choose not to render its optional visual fields. Every transport response carries `Cache-Control: no-store`; its Bearer challenge identifies this exact resource's Protected Resource Metadata and becomes an OAuth error challenge only on rejection.","requestBody":{"required":true,"description":"One JSON-RPC 2.0 MCP request or notification. Batched arrays are rejected.","content":{"application/json":{"schema":{"type":"object","required":["jsonrpc","method"],"additionalProperties":false,"properties":{"jsonrpc":{"type":"string","enum":["2.0"],"description":"JSON-RPC protocol version.","example":"2.0"},"id":{"type":["integer","null"],"description":"Request id echoed in a response. Omit it for a notification.","example":1},"method":{"type":"string","description":"MCP method, for example `initialize`, `tools/list`, `tools/call`, `resources/list` or `resources/read`.","example":"tools/list"},"params":{"type":"object","additionalProperties":true,"description":"Parameters defined by the selected MCP method.","example":{}}}},"example":{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}}}},"responses":{"200":{"description":"JSON-RPC 2.0 response. Exactly one of `result` and `error` is present.","content":{"application/json":{"schema":{"type":"object","required":["jsonrpc","id"],"additionalProperties":false,"properties":{"jsonrpc":{"type":"string","enum":["2.0"],"description":"JSON-RPC protocol version.","example":"2.0"},"id":{"type":["integer","null"],"description":"The request id, or null when no usable id was supplied.","example":1},"result":{"anyOf":[{"$ref":"#/components/schemas/mcp_initialize_result"},{"type":"object","additionalProperties":true,"description":"Result object for another supported MCP method, such as tools/list or resources/read."}],"description":"Result defined by the MCP method. For `initialize`, see `mcp_initialize_result`, including optional title, websiteUrl and icons; absent when `error` is present.","example":{"tools":[]}},"error":{"type":"object","additionalProperties":false,"description":"JSON-RPC error; absent on success.","properties":{"code":{"type":"integer","description":"JSON-RPC error code.","example":-32601},"message":{"type":"string","description":"Human-readable JSON-RPC error message.","example":"Method not found"}}}}},"example":{"jsonrpc":"2.0","id":1,"result":{"tools":[],"protocolVersion":"2025-11-25","capabilities":{"tools":{"listChanged":false}},"serverInfo":{"name":"exampleco","version":"1.0.0","title":"ExampleCo Account MCP","description":"ExampleCo Account MCP server.","websiteUrl":"https://app.example.com","icons":[{"src":"https://app.example.com/brand-assets/logo_thumbnail.svg","mimeType":"image/svg+xml","sizes":["512x512"],"theme":"dark"},{"src":"https://app.example.com/brand-assets/logo.svg","mimeType":"image/svg+xml","theme":"light","sizes":["512x512"]},{"src":"https://app.example.com/brand-assets/logo_dark.svg","mimeType":"image/svg+xml","theme":"dark","sizes":["512x512"]}]}},"error":{"code":-32601,"message":"Method not found"}}}}},"202":{"description":"Notification accepted. A JSON-RPC notification has no response body."},"400":{"description":"A modern request used an unsupported MCP-Protocol-Version (-32022) or inconsistent mirrored routing headers/body values (-32020).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/mcp_modern_transport_error"},"example":{"jsonrpc":"2.0","id":1,"error":{"code":-32022,"message":"Unsupported protocol version","data":{"supported":["2026-07-28"],"requested":"2099-01-01"}}}}}},"401":{"description":"Missing, expired, revoked, cross-resource or cross-plane OAuth bearer; disabled profile; or a subject who is no longer an account member. The Bearer challenge always identifies the Protected Resource Metadata for this exact resource. It includes `error=\"invalid_token\"` only when a bearer was supplied but rejected, and advertises the initial `mcp:read` scope.","headers":{"WWW-Authenticate":{"description":"OAuth Bearer challenge for this exact protected resource.","schema":{"type":"string"},"example":"Bearer resource_metadata=\"https://app.example.com/.well-known/oauth-protected-resource/mcp/oauth/accounts/31/connections/a1b2c3d4e5f6g7h8i9j0\", error=\"invalid_token\", scope=\"mcp:read\""},"Cache-Control":{"description":"MCP authentication responses must not be stored by an intermediary.","schema":{"type":"string","enum":["no-store"],"example":"no-store"}}},"content":{"application/json":{"schema":{"type":"object","required":["error"],"additionalProperties":false,"properties":{"error":{"type":"string","enum":["Unauthorized"],"description":"Safe HTTP authentication error; OAuth detail is carried in WWW-Authenticate.","example":"Unauthorized"}}},"example":{"error":"Unauthorized"}}}},"403":{"description":"A valid bearer attempted a write-capable MCP tool without `mcp:write`. The Bearer challenge names the exact protected resource and returns `error=\"insufficient_scope\"` with `scope=\"mcp:write\"`. A profile in read-only mode remains read-only even when its grant contains `mcp:write`.","headers":{"WWW-Authenticate":{"description":"OAuth Bearer insufficient-scope challenge for this exact protected resource.","schema":{"type":"string"},"example":"Bearer resource_metadata=\"https://app.example.com/.well-known/oauth-protected-resource/mcp/oauth/accounts/31/connections/a1b2c3d4e5f6g7h8i9j0\", error=\"insufficient_scope\", scope=\"mcp:write\""},"Cache-Control":{"description":"MCP authorization responses must not be stored by an intermediary.","schema":{"type":"string","enum":["no-store"],"example":"no-store"}}},"content":{"application/json":{"schema":{"type":"object","required":["error"],"additionalProperties":false,"properties":{"error":{"type":"string","enum":["Forbidden"],"description":"Safe HTTP authorization error; OAuth detail is carried in WWW-Authenticate.","example":"Forbidden"}}},"example":{"error":"Forbidden"}}}},"413":{"description":"The JSON-RPC request or generated transport response exceeds the 1 MiB MCP transport limit. An oversized request is rejected before dispatch. A generated response is measured after its MCP operation returns, so a client must not blindly retry a write after this status: inspect the underlying resource or audit trail first.","headers":{"Cache-Control":{"description":"MCP transport errors must not be stored by an intermediary.","schema":{"type":"string","enum":["no-store"],"example":"no-store"}}},"content":{"application/json":{"schema":{"type":"object","required":["error"],"additionalProperties":false,"properties":{"error":{"type":"string","enum":["MCP payload exceeds the supported size"],"example":"MCP payload exceeds the supported size"}}},"example":{"error":"MCP payload exceeds the supported size"}}}},"404":{"description":"The account MCP/native OAuth resource is unavailable, or an authenticated modern client requested `subscriptions/listen`. Per-request stateless deployments reject that process-local streaming method explicitly with JSON-RPC -32601. Dark-shipped responses do not disclose profile existence.","content":{"application/json":{"schema":{"oneOf":[{"type":"object","required":["error"],"additionalProperties":false,"properties":{"error":{"type":"string","description":"Availability message.","example":"MCP OAuth connection is unavailable"}}},{"$ref":"#/components/schemas/mcp_stateless_subscription_error"}]},"example":{"jsonrpc":"2.0","id":73,"error":{"code":-32601,"message":"Method not found","data":"subscriptions/listen is unavailable on this stateless transport"}}}}}}},"get":{"tags":["Mcp"],"operationId":"open-account-mcp-oauth-connection-stream","summary":"Open an OAuth account MCP event stream (not available — stateless server)","security":[{"mcpOauth":["mcp:read"]}],"description":"Streamable HTTP reserves GET for a server-initiated SSE stream. This native OAuth MCP endpoint is stateless and never issues a session, so GET always returns a JSON-RPC method-not-allowed error. Send MCP traffic over POST instead.","responses":{"401":{"description":"Missing or rejected OAuth bearer for this exact account resource. The Bearer challenge points to its Protected Resource Metadata and includes `error=\"invalid_token\"` only when a bearer was supplied but rejected.","headers":{"WWW-Authenticate":{"description":"OAuth Bearer challenge for this exact protected resource.","schema":{"type":"string"},"example":"Bearer resource_metadata=\"https://app.example.com/.well-known/oauth-protected-resource/mcp/oauth/accounts/31/connections/a1b2c3d4e5f6g7h8i9j0\", error=\"invalid_token\", scope=\"mcp:read\""},"Cache-Control":{"description":"MCP authentication responses must not be stored by an intermediary.","schema":{"type":"string","enum":["no-store"],"example":"no-store"}}},"content":{"application/json":{"schema":{"type":"object","required":["error"],"additionalProperties":false,"properties":{"error":{"type":"string","enum":["Unauthorized"],"example":"Unauthorized"}}},"example":{"error":"Unauthorized"}}}},"404":{"description":"The account MCP or native OAuth server is unavailable."},"405":{"description":"Stateless MCP servers do not expose an SSE stream.","content":{"application/json":{"schema":{"type":"object","required":["jsonrpc","id","error"],"additionalProperties":false,"properties":{"jsonrpc":{"type":"string","enum":["2.0"],"example":"2.0"},"id":{"type":"null","description":"GET does not carry a JSON-RPC request id.","example":null},"error":{"type":"object","required":["code","message"],"additionalProperties":false,"properties":{"code":{"type":"integer","example":-32600},"message":{"type":"string","example":"Method not allowed"}}}}},"example":{"jsonrpc":"2.0","id":null,"error":{"code":-32600,"message":"Method not allowed"}}}}}}},"delete":{"tags":["Mcp"],"operationId":"close-account-mcp-oauth-connection","summary":"Terminate an OAuth account MCP connection session (no-op)","security":[{"mcpOauth":["mcp:read"]}],"description":"A Streamable HTTP client may send DELETE when it is finished. This server is stateless, so no MCP session is stored; the request is acknowledged as a no-op. Revoking the OAuth grant is a separate action at the OAuth revocation endpoint.","responses":{"200":{"description":"Teardown acknowledged. No server-side MCP session existed.","content":{"application/json":{"schema":{"type":"object","required":["success"],"additionalProperties":false,"properties":{"success":{"type":"boolean","description":"Always true for a valid stateless teardown request.","example":true}}},"example":{"success":true}}}},"400":{"description":"An unsupported `MCP-Protocol-Version` header was supplied."},"401":{"description":"Missing or rejected OAuth bearer for this exact account resource. The Bearer challenge points to its Protected Resource Metadata and includes `error=\"invalid_token\"` only when a bearer was supplied but rejected.","headers":{"WWW-Authenticate":{"description":"OAuth Bearer challenge for this exact protected resource.","schema":{"type":"string"},"example":"Bearer resource_metadata=\"https://app.example.com/.well-known/oauth-protected-resource/mcp/oauth/accounts/31/connections/a1b2c3d4e5f6g7h8i9j0\", error=\"invalid_token\", scope=\"mcp:read\""},"Cache-Control":{"description":"MCP authentication responses must not be stored by an intermediary.","schema":{"type":"string","enum":["no-store"],"example":"no-store"}}},"content":{"application/json":{"schema":{"type":"object","required":["error"],"additionalProperties":false,"properties":{"error":{"type":"string","enum":["Unauthorized"],"example":"Unauthorized"}}},"example":{"error":"Unauthorized"}}}},"404":{"description":"The account MCP or native OAuth server is unavailable."}}}},"/super_admin/mcp":{"parameters":[{"$ref":"#/components/parameters/mcp_protocol_version"},{"$ref":"#/components/parameters/mcp_modern_method"},{"$ref":"#/components/parameters/mcp_modern_name"}],"get":{"tags":["Mcp"],"operationId":"open-static-super-admin-mcp-stream","summary":"Open the static Super Admin MCP event stream (not available — stateless server)","security":[{"superAdminMcpBearer":[]}],"description":"Dedicated Super Admin MCP protocol transport, not an Operator REST API operation. Streamable HTTP reserves GET for an SSE stream; this server is stateless in both compatible eras, so it never issues a session and always returns a JSON-RPC method-not-allowed error. Use POST for legacy 2025-11-25 `initialize`/JSON-RPC traffic and modern 2026-07-28 per-request JSON-RPC traffic instead.","responses":{"401":{"description":"Missing, revoked, expired, or invalid dedicated SuperAdminAccessToken. Account, Platform App, OAuth MCP, and Operator REST bearer credentials all receive the same response and the WWW-Authenticate challenge identifies the static Super Admin protected-resource metadata.","headers":{"Cache-Control":{"description":"MCP authentication responses must not be stored by an intermediary.","schema":{"type":"string","enum":["no-store"],"example":"no-store"}},"WWW-Authenticate":{"description":"Bearer challenge naming the static Super Admin protected-resource metadata.","schema":{"type":"string"},"example":"Bearer resource_metadata=\"https://app.example.com/.well-known/oauth-protected-resource/mcp/super-admin\""}},"content":{"application/json":{"schema":{"type":"object","required":["error"],"additionalProperties":false,"properties":{"error":{"type":"string","enum":["Unauthorized"],"example":"Unauthorized"}}},"example":{"error":"Unauthorized"}}}},"404":{"description":"The general MCP server or independent Super Admin MCP server is disabled; the dark-shipped route does not disclose which gate is off.","headers":{"Cache-Control":{"description":"MCP availability responses must not be stored by an intermediary.","schema":{"type":"string","enum":["no-store"],"example":"no-store"}},"WWW-Authenticate":{"description":"Bearer discovery challenge for the static Super Admin protected-resource metadata.","schema":{"type":"string"},"example":"Bearer resource_metadata=\"https://app.example.com/.well-known/oauth-protected-resource/mcp/super-admin\""}},"content":{"application/json":{"schema":{"type":"object","required":["error"],"additionalProperties":false,"properties":{"error":{"type":"string","example":"Super Admin MCP server is disabled on this installation"}}},"example":{"error":"Super Admin MCP server is disabled on this installation"}}}},"405":{"description":"Stateless MCP servers do not expose an SSE stream.","content":{"application/json":{"schema":{"type":"object","required":["jsonrpc","id","error"],"additionalProperties":false,"properties":{"jsonrpc":{"type":"string","enum":["2.0"],"example":"2.0"},"id":{"type":"null","description":"GET carries no JSON-RPC request id.","example":null},"error":{"type":"object","required":["code","message"],"additionalProperties":false,"properties":{"code":{"type":"integer","enum":[-32600],"example":-32600},"message":{"type":"string","enum":["Method not allowed"],"example":"Method not allowed"}}}}},"example":{"jsonrpc":"2.0","id":null,"error":{"code":-32600,"message":"Method not allowed"}}}}}}},"post":{"tags":["Mcp"],"operationId":"call-static-super-admin-mcp","summary":"Call the static Super Admin MCP transport (JSON-RPC)","security":[{"superAdminMcpBearer":[]}],"description":"Dedicated Super Admin MCP protocol transport, not an Operator REST API operation or a callable REST tool. Authenticate only with `Authorization: Bearer \u003cSuperAdminAccessToken\u003e`; account access tokens (including a Super Admin's ordinary account token), Platform App credentials, OAuth MCP bearers, and the separate Operator REST API bearer never authenticate it. Legacy 2025-11-25 clients negotiate through `initialize.params.protocolVersion` and use the JSON-RPC envelope. Modern 2026-07-28 clients send `MCP-Protocol-Version`, `Mcp-Method`, optional `Mcp-Name`, matching `_meta` values, and `Accept: application/json, text/event-stream` on each JSON-RPC request; legacy requests send `Accept: application/json`. No `Mcp-Session-Id` is issued. A request or response is bounded to 1 MiB and chunked request bodies are rejected before authentication or dispatch.","requestBody":{"required":true,"description":"One JSON-RPC 2.0 MCP request or notification. Batched arrays are rejected. For legacy initialize, `params.protocolVersion` is `2025-11-25`; modern clients use the documented headers and `_meta` envelope values instead of turning MCP methods into REST paths.","content":{"application/json":{"schema":{"type":"object","required":["jsonrpc","method"],"additionalProperties":false,"properties":{"jsonrpc":{"type":"string","enum":["2.0"],"description":"JSON-RPC protocol version.","example":"2.0"},"id":{"type":["integer","null"],"description":"Request id echoed in a response. Omit it for a notification.","example":1},"method":{"type":"string","description":"MCP protocol method, such as initialize, server/discover, tools/list, or tools/call.","example":"server/discover"},"params":{"type":"object","additionalProperties":true,"description":"Parameters defined by the selected MCP method, including legacy protocolVersion or modern _meta when applicable.","example":{}}}},"example":{"jsonrpc":"2.0","id":1,"method":"server/discover","params":{"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientCapabilities":{}}}}}}},"responses":{"200":{"description":"JSON-RPC 2.0 response. Legacy initialize returns its negotiated protocol version; modern discovery returns its supported modern version and result type. Exactly one of result and error is present, and successful stateless responses never issue Mcp-Session-Id or WWW-Authenticate.","headers":{"Cache-Control":{"description":"MCP responses must not be stored by an intermediary.","schema":{"type":"string","enum":["no-store"],"example":"no-store"}}},"content":{"application/json":{"schema":{"type":"object","required":["jsonrpc","id"],"additionalProperties":false,"properties":{"jsonrpc":{"type":"string","enum":["2.0"],"example":"2.0"},"id":{"type":["integer","null"],"example":1},"result":{"type":"object","additionalProperties":true,"description":"Result defined by the selected MCP method; legacy initialize and modern server/discover use their respective MCP envelopes.","example":{"supportedVersions":["2026-07-28"],"resultType":"complete"}},"error":{"type":["object","null"],"additionalProperties":false,"description":"JSON-RPC protocol error; absent on success.","properties":{"code":{"type":"integer","example":-32600},"message":{"type":"string","example":"Invalid request"}}}}},"example":{"jsonrpc":"2.0","id":1,"result":{"supportedVersions":["2026-07-28"],"resultType":"complete"},"error":{"code":-32600,"message":"Invalid request"}}}}},"202":{"description":"Notification accepted. A JSON-RPC notification has no response body."},"400":{"description":"Unsupported MCP-Protocol-Version or an invalid modern header/body pairing, including an Mcp-Method that does not match the JSON-RPC method. The JSON-RPC error code is -32020 for a modern routing mismatch and -32022 for an unsupported protocol version.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/mcp_modern_transport_error"},"example":{"jsonrpc":"2.0","id":1,"error":{"code":-32020,"message":"MCP header does not match JSON-RPC method","data":{"supported":["2026-07-28"],"requested":"2099-01-01"}}}}}},"401":{"description":"Missing, revoked, expired, or invalid dedicated SuperAdminAccessToken. Other bearer planes are never accepted.","headers":{"Cache-Control":{"description":"MCP authentication responses must not be stored by an intermediary.","schema":{"type":"string","enum":["no-store"],"example":"no-store"}},"WWW-Authenticate":{"description":"Bearer challenge naming the static Super Admin protected-resource metadata.","schema":{"type":"string"},"example":"Bearer resource_metadata=\"https://app.example.com/.well-known/oauth-protected-resource/mcp/super-admin\""}},"content":{"application/json":{"schema":{"type":"object","required":["error"],"additionalProperties":false,"properties":{"error":{"type":"string","enum":["Unauthorized"],"example":"Unauthorized"}}},"example":{"error":"Unauthorized"}}}},"404":{"description":"The general/independent Super Admin MCP server is disabled, or an authenticated modern client requested `subscriptions/listen`. Per-request stateless deployments reject that process-local streaming method explicitly with JSON-RPC -32601. Availability does not disclose which gate is off.","headers":{"Cache-Control":{"description":"MCP availability responses must not be stored by an intermediary.","schema":{"type":"string","enum":["no-store"],"example":"no-store"}},"WWW-Authenticate":{"description":"Bearer discovery challenge for the static Super Admin protected-resource metadata.","schema":{"type":"string"},"example":"Bearer resource_metadata=\"https://app.example.com/.well-known/oauth-protected-resource/mcp/super-admin\""}},"content":{"application/json":{"schema":{"oneOf":[{"type":"object","required":["error"],"additionalProperties":false,"properties":{"error":{"type":"string","example":"Super Admin MCP server is disabled on this installation"}}},{"$ref":"#/components/schemas/mcp_stateless_subscription_error"}]},"example":{"jsonrpc":"2.0","id":73,"error":{"code":-32601,"message":"Method not found","data":"subscriptions/listen is unavailable on this stateless transport"}}}}},"413":{"description":"The JSON-RPC request or generated transport response exceeds the 1 MiB MCP transport limit.","headers":{"Cache-Control":{"description":"MCP transport errors must not be stored by an intermediary.","schema":{"type":"string","enum":["no-store"],"example":"no-store"}}},"content":{"application/json":{"schema":{"type":"object","required":["error"],"additionalProperties":false,"properties":{"error":{"type":"string","enum":["MCP payload exceeds the supported size"],"example":"MCP payload exceeds the supported size"}}},"example":{"error":"MCP payload exceeds the supported size"}}}}}},"delete":{"tags":["Mcp"],"operationId":"close-static-super-admin-mcp","summary":"Terminate the static Super Admin MCP connection (no-op)","security":[{"superAdminMcpBearer":[]}],"description":"Streamable HTTP clients may send DELETE after either legacy 2025-11-25 or modern 2026-07-28 traffic. This server is stateless in both eras, so no session exists to remove and a valid request is acknowledged as a no-op. This remains an MCP protocol compatibility action, not an Operator REST API deletion.","responses":{"200":{"description":"Teardown acknowledged; no server-side MCP session existed.","headers":{"Cache-Control":{"description":"MCP responses must not be stored by an intermediary.","schema":{"type":"string","enum":["no-store"],"example":"no-store"}}},"content":{"application/json":{"schema":{"type":"object","required":["success"],"additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[true],"example":true}}},"example":{"success":true}}}},"400":{"description":"The MCP-Protocol-Version header names a protocol revision this static transport does not support."},"401":{"description":"Missing, revoked, expired, or invalid dedicated SuperAdminAccessToken. Other bearer planes are never accepted.","headers":{"Cache-Control":{"description":"MCP authentication responses must not be stored by an intermediary.","schema":{"type":"string","enum":["no-store"],"example":"no-store"}},"WWW-Authenticate":{"description":"Bearer challenge naming the static Super Admin protected-resource metadata.","schema":{"type":"string"},"example":"Bearer resource_metadata=\"https://app.example.com/.well-known/oauth-protected-resource/mcp/super-admin\""}},"content":{"application/json":{"schema":{"type":"object","required":["error"],"additionalProperties":false,"properties":{"error":{"type":"string","enum":["Unauthorized"],"example":"Unauthorized"}}},"example":{"error":"Unauthorized"}}}},"404":{"description":"The general MCP server or independent Super Admin MCP server is disabled.","headers":{"Cache-Control":{"description":"MCP availability responses must not be stored by an intermediary.","schema":{"type":"string","enum":["no-store"],"example":"no-store"}},"WWW-Authenticate":{"description":"Bearer discovery challenge for the static Super Admin protected-resource metadata.","schema":{"type":"string"},"example":"Bearer resource_metadata=\"https://app.example.com/.well-known/oauth-protected-resource/mcp/super-admin\""}},"content":{"application/json":{"schema":{"type":"object","required":["error"],"additionalProperties":false,"properties":{"error":{"type":"string","example":"Super Admin MCP server is disabled on this installation"}}},"example":{"error":"Super Admin MCP server is disabled on this installation"}}}}}}},"/super_admin/mcp/oauth":{"parameters":[{"$ref":"#/components/parameters/mcp_protocol_version"},{"$ref":"#/components/parameters/mcp_modern_method"},{"$ref":"#/components/parameters/mcp_modern_name"}],"get":{"tags":["Mcp"],"operationId":"open-super-admin-mcp-oauth-connection-stream","summary":"Open a Super Admin OAuth MCP event stream (not available — stateless server)","security":[{"mcpOauth":["mcp:read"]}],"description":"Streamable HTTP reserves GET for a server-initiated SSE stream. This native OAuth MCP endpoint is stateless and never issues an MCP session, so GET always returns a JSON-RPC method-not-allowed error. Send MCP traffic over POST instead. The OAuth bearer must have been issued for this exact Super Admin resource; a static Super Admin operator credential does not authenticate this endpoint.","responses":{"401":{"description":"Missing, expired, revoked, cross-resource or cross-plane OAuth bearer; or an inactive Super Admin subject who is no longer active and confirmed. The Bearer challenge always identifies the Protected Resource Metadata for this exact resource. It includes `error=\"invalid_token\"` only when a bearer was supplied but rejected, and advertises the initial `mcp:read` scope.","headers":{"WWW-Authenticate":{"description":"OAuth Bearer challenge for this exact protected resource.","schema":{"type":"string"},"example":"Bearer resource_metadata=\"https://app.example.com/.well-known/oauth-protected-resource/mcp/oauth/super-admin\", error=\"invalid_token\", scope=\"mcp:read\""},"Cache-Control":{"description":"MCP authentication responses must not be stored by an intermediary.","schema":{"type":"string","enum":["no-store"],"example":"no-store"}}},"content":{"application/json":{"schema":{"type":"object","required":["error"],"additionalProperties":false,"properties":{"error":{"type":"string","enum":["Unauthorized"],"description":"Safe HTTP authentication error; OAuth detail is carried in WWW-Authenticate.","example":"Unauthorized"}}},"example":{"error":"Unauthorized"}}}},"404":{"description":"Native MCP OAuth, the general MCP server or the independently gated Super Admin MCP server is unavailable. The endpoint does not disclose which gate is disabled."},"405":{"description":"Stateless MCP servers do not expose an SSE stream.","content":{"application/json":{"schema":{"type":"object","required":["jsonrpc","id","error"],"additionalProperties":false,"properties":{"jsonrpc":{"type":"string","enum":["2.0"],"example":"2.0"},"id":{"type":"null","description":"GET does not carry a JSON-RPC request id.","example":null},"error":{"type":"object","required":["code","message"],"additionalProperties":false,"properties":{"code":{"type":"integer","example":-32600},"message":{"type":"string","example":"Method not allowed"}}}}},"example":{"jsonrpc":"2.0","id":null,"error":{"code":-32600,"message":"Method not allowed"}}}}}}},"post":{"tags":["Mcp"],"operationId":"call-super-admin-mcp-oauth-connection","summary":"Call the Super Admin OAuth MCP connection (JSON-RPC)","security":[{"mcpOauth":["mcp:read"]}],"description":"Streamable HTTP MCP endpoint for the installation-wide Super Admin authority, authenticated with a native OAuth 2.1 bearer issued for this exact URL. This is a Streamable HTTP MCP protocol transport, not a REST tool collection. The resulting request is replayed only through the curated Super Admin operator surface; it never becomes an account API token. The grant was approved by a valid Super Admin after the consent flow's fresh password step (and MFA when enrolled). `mcp:write` is additionally required for a write-capable tool, and the operator policy still rejects writes that are not explicitly allowed. Static Super Admin credentials, account API tokens, profile secrets and PlatformApp credentials do not authenticate this endpoint. Send one JSON-RPC 2.0 message per POST with Content-Type: application/json; batched arrays are rejected. Legacy requests send `Accept: application/json`; modern 2026-07-28 requests must send `Accept: application/json, text/event-stream`. Legacy clients negotiate in `initialize.params.protocolVersion`; modern 2026-07-28 clients send the documented MCP headers and matching `_meta` envelope fields. An `initialize` negotiated at protocol `2025-11-25` returns the safe branded `result.serverInfo` described by `mcp_initialize_result`; a client may cache or choose not to render its optional visual fields. Every transport response carries `Cache-Control: no-store`; its Bearer challenge identifies this exact resource's Protected Resource Metadata and becomes an OAuth error challenge only on rejection.","requestBody":{"required":true,"description":"One JSON-RPC 2.0 MCP request or notification.","content":{"application/json":{"schema":{"type":"object","required":["jsonrpc","method"],"additionalProperties":false,"properties":{"jsonrpc":{"type":"string","enum":["2.0"],"description":"JSON-RPC protocol version.","example":"2.0"},"id":{"type":["integer","null"],"description":"Request id echoed in a response. Omit it for a notification.","example":1},"method":{"type":"string","description":"MCP method, for example initialize, tools/list, tools/call, resources/list or resources/read.","example":"tools/list"},"params":{"type":"object","additionalProperties":true,"description":"Parameters defined by the selected MCP method.","example":{}}}},"example":{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}}}},"responses":{"200":{"description":"JSON-RPC 2.0 response. Exactly one of result and error is present.","content":{"application/json":{"schema":{"type":"object","required":["jsonrpc","id"],"additionalProperties":false,"properties":{"jsonrpc":{"type":"string","enum":["2.0"],"example":"2.0"},"id":{"type":["integer","null"],"description":"The request id, or null when no usable id was supplied.","example":1},"result":{"anyOf":[{"$ref":"#/components/schemas/mcp_initialize_result"},{"type":"object","additionalProperties":true,"description":"Result object for another supported MCP method, such as tools/list or resources/read."}],"description":"Result defined by the MCP method. For `initialize`, see `mcp_initialize_result`, including optional title, websiteUrl and icons; absent when error is present.","example":{"tools":[]}},"error":{"type":"object","additionalProperties":false,"description":"JSON-RPC error; absent on success.","properties":{"code":{"type":"integer","description":"JSON-RPC error code.","example":-32601},"message":{"type":"string","description":"Human-readable JSON-RPC error message.","example":"Method not found"}}}}},"example":{"jsonrpc":"2.0","id":1,"result":{"tools":[],"protocolVersion":"2025-11-25","capabilities":{"tools":{"listChanged":false}},"serverInfo":{"name":"exampleco","version":"1.0.0","title":"ExampleCo Account MCP","description":"ExampleCo Account MCP server.","websiteUrl":"https://app.example.com","icons":[{"src":"https://app.example.com/brand-assets/logo_thumbnail.svg","mimeType":"image/svg+xml","sizes":["512x512"],"theme":"dark"},{"src":"https://app.example.com/brand-assets/logo.svg","mimeType":"image/svg+xml","theme":"light","sizes":["512x512"]},{"src":"https://app.example.com/brand-assets/logo_dark.svg","mimeType":"image/svg+xml","theme":"dark","sizes":["512x512"]}]}},"error":{"code":-32601,"message":"Method not found"}}}}},"202":{"description":"Notification accepted. A JSON-RPC notification has no response body."},"400":{"description":"A modern request used an unsupported MCP-Protocol-Version (-32022) or inconsistent mirrored routing headers/body values (-32020).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/mcp_modern_transport_error"},"example":{"jsonrpc":"2.0","id":1,"error":{"code":-32022,"message":"Unsupported protocol version","data":{"supported":["2026-07-28"],"requested":"2099-01-01"}}}}}},"401":{"description":"Missing, expired, revoked, cross-resource or cross-plane OAuth bearer; or an inactive Super Admin subject who is no longer active and confirmed. The Bearer challenge always identifies the Protected Resource Metadata for this exact resource. It includes `error=\"invalid_token\"` only when a bearer was supplied but rejected, and advertises the initial `mcp:read` scope.","headers":{"WWW-Authenticate":{"description":"OAuth Bearer challenge for this exact protected resource.","schema":{"type":"string"},"example":"Bearer resource_metadata=\"https://app.example.com/.well-known/oauth-protected-resource/mcp/oauth/super-admin\", error=\"invalid_token\", scope=\"mcp:read\""},"Cache-Control":{"description":"MCP authentication responses must not be stored by an intermediary.","schema":{"type":"string","enum":["no-store"],"example":"no-store"}}},"content":{"application/json":{"schema":{"type":"object","required":["error"],"additionalProperties":false,"properties":{"error":{"type":"string","enum":["Unauthorized"],"description":"Safe HTTP authentication error; OAuth detail is carried in WWW-Authenticate.","example":"Unauthorized"}}},"example":{"error":"Unauthorized"}}}},"403":{"description":"A valid bearer attempted a write-capable MCP tool without `mcp:write`. The Bearer challenge names the exact protected resource and returns `error=\"insufficient_scope\"` with `scope=\"mcp:write\"`. A `mcp:write` grant still cannot invoke an operator write that the curated policy does not allow.","headers":{"WWW-Authenticate":{"description":"OAuth Bearer insufficient-scope challenge for this exact protected resource.","schema":{"type":"string"},"example":"Bearer resource_metadata=\"https://app.example.com/.well-known/oauth-protected-resource/mcp/oauth/super-admin\", error=\"insufficient_scope\", scope=\"mcp:write\""},"Cache-Control":{"description":"MCP authorization responses must not be stored by an intermediary.","schema":{"type":"string","enum":["no-store"],"example":"no-store"}}},"content":{"application/json":{"schema":{"type":"object","required":["error"],"additionalProperties":false,"properties":{"error":{"type":"string","enum":["Forbidden"],"description":"Safe HTTP authorization error; OAuth detail is carried in WWW-Authenticate.","example":"Forbidden"}}},"example":{"error":"Forbidden"}}}},"413":{"description":"The JSON-RPC request or generated transport response exceeds the 1 MiB MCP transport limit. An oversized request is rejected before dispatch. A generated response is measured after its MCP operation returns, so a client must not blindly retry a write after this status: inspect the underlying resource or audit trail first.","headers":{"Cache-Control":{"description":"MCP transport errors must not be stored by an intermediary.","schema":{"type":"string","enum":["no-store"],"example":"no-store"}}},"content":{"application/json":{"schema":{"type":"object","required":["error"],"additionalProperties":false,"properties":{"error":{"type":"string","enum":["MCP payload exceeds the supported size"],"example":"MCP payload exceeds the supported size"}}},"example":{"error":"MCP payload exceeds the supported size"}}}},"404":{"description":"Native MCP OAuth/the Super Admin MCP server is unavailable, or an authenticated modern client requested `subscriptions/listen`. Per-request stateless deployments reject that process-local streaming method explicitly with JSON-RPC -32601. Availability does not disclose which gate is off.","content":{"application/json":{"schema":{"oneOf":[{"type":"object","required":["error"],"additionalProperties":false,"properties":{"error":{"type":"string","description":"Availability message.","example":"Super Admin MCP OAuth connection is unavailable"}}},{"$ref":"#/components/schemas/mcp_stateless_subscription_error"}]},"example":{"jsonrpc":"2.0","id":73,"error":{"code":-32601,"message":"Method not found","data":"subscriptions/listen is unavailable on this stateless transport"}}}}}}},"delete":{"tags":["Mcp"],"operationId":"close-super-admin-mcp-oauth-connection","summary":"Terminate a Super Admin OAuth MCP connection session (no-op)","security":[{"mcpOauth":["mcp:read"]}],"description":"A Streamable HTTP client may send DELETE when it is finished. This server is stateless, so no MCP session is stored; the request is acknowledged as a no-op. Revoking the OAuth grant is a separate action at the OAuth revocation endpoint.","responses":{"200":{"description":"Teardown acknowledged. No server-side MCP session existed.","content":{"application/json":{"schema":{"type":"object","required":["success"],"additionalProperties":false,"properties":{"success":{"type":"boolean","description":"Always true for a valid stateless teardown request.","example":true}}},"example":{"success":true}}}},"400":{"description":"An unsupported MCP-Protocol-Version header was supplied."},"401":{"description":"Missing or rejected OAuth bearer for this exact Super Admin resource. The Bearer challenge points to its Protected Resource Metadata and includes `error=\"invalid_token\"` only when a bearer was supplied but rejected.","headers":{"WWW-Authenticate":{"description":"OAuth Bearer challenge for this exact protected resource.","schema":{"type":"string"},"example":"Bearer resource_metadata=\"https://app.example.com/.well-known/oauth-protected-resource/mcp/oauth/super-admin\", error=\"invalid_token\", scope=\"mcp:read\""},"Cache-Control":{"description":"MCP authentication responses must not be stored by an intermediary.","schema":{"type":"string","enum":["no-store"],"example":"no-store"}}},"content":{"application/json":{"schema":{"type":"object","required":["error"],"additionalProperties":false,"properties":{"error":{"type":"string","enum":["Unauthorized"],"example":"Unauthorized"}}},"example":{"error":"Unauthorized"}}}},"404":{"description":"Native MCP OAuth, the general MCP server or the independently gated Super Admin MCP server is unavailable."}}}},"/api/v1/accounts/{account_id}/mcp/oauth/authorizations":{"parameters":[{"$ref":"#/components/parameters/account_id"}],"get":{"tags":["Mcp"],"operationId":"list-account-mcp-oauth-authorizations","summary":"List account MCP OAuth authorizations visible to the current member","security":[{"userApiKey":[]}],"description":"Reviews safe metadata for native account MCP OAuth consents through the ordinary account API identity. A regular account member receives only their own account-plane authorizations. An account administrator receives every account-plane authorization in the current account and is told which closed revocation reasons are required for an administrator-initiated revocation. This endpoint remains available while native MCP OAuth is dark-shipped or disabled so existing grants can still be reviewed and revoked. It never returns an access token, refresh token, authorization code, client secret or token digest.","responses":{"200":{"description":"Safe authorization review data for the current user scope.","content":{"application/json":{"schema":{"type":"object","required":["oauth_enabled","can_manage_all","revocation_reasons","authorizations"],"additionalProperties":false,"properties":{"oauth_enabled":{"type":"boolean","description":"Whether the account-plane native MCP OAuth server is currently available. Existing grants remain revocable when false.","example":true},"can_manage_all":{"type":"boolean","description":"Whether the current account member is an administrator and can review all grants in this account.","example":false},"revocation_reasons":{"type":"array","description":"Closed reason vocabulary supplied only to an account administrator for an administrator-initiated revocation.","items":{"type":"string","enum":["account_admin_security_review","account_admin_access_removed","account_admin_client_decommissioned","account_admin_incident_response"]},"example":[]},"authorizations":{"type":"array","items":{"$ref":"#/components/schemas/mcp_oauth_authorization"}}}},"example":{"oauth_enabled":true,"can_manage_all":false,"revocation_reasons":[],"authorizations":[{"id":42,"plane":"account","status":"active","client":{"name":"Support desktop client","software_id":"com.example.support-desktop","software_version":"1.4.0"},"subject":{"name":"Ana Support","email":"ana@example.com"},"resource":{"uri":"https://app.example.com/api/v1/accounts/31/mcp/oauth/c/a1b2c3d4e5f6g7h8i9j0","profile_name":"support-read-only","profile_enabled":true,"effective_read_only":true,"toolsets":["Conversations","Contacts"],"tool_count":18},"scopes":["mcp:read"],"decided_at":"2026-08-05T12:00:00Z","last_used_at":"2026-08-05T12:10:00Z","access_token_expires_at":"2026-08-05T12:15:00Z","revoked_at":null,"can_revoke":true}]}}}},"401":{"description":"Missing or invalid account API credential."},"403":{"description":"The authenticated user is not a member of this account."},"404":{"description":"The account does not exist or is not visible to the authenticated user."}}}},"/api/v1/accounts/{account_id}/mcp/oauth/authorizations/{id}":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"id","in":"path","required":true,"description":"Authorization record id returned by the authorization list for the current account scope.","schema":{"type":"integer"},"example":42}],"delete":{"tags":["Mcp"],"operationId":"revoke-account-mcp-oauth-authorization","summary":"Revoke a visible account MCP OAuth authorization","security":[{"userApiKey":[]}],"description":"Revokes the durable account-plane OAuth consent and all related authorization codes, access tokens and refresh tokens. A regular account member may revoke only their own visible grant and the server records subject_revoked. An account administrator may revoke any visible grant in the current account only with one of the documented closed reasons. Cross-account and peer grants are not disclosed through this endpoint. The response contains safe review data, never OAuth credential material.","requestBody":{"required":false,"description":"An account administrator must send one closed revocation reason. A regular member revoking their own authorization omits the body and the server records subject_revoked. A regular member cannot revoke a peer authorization even if a reason is supplied.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"reason":{"type":"string","enum":["account_admin_security_review","account_admin_access_removed","account_admin_client_decommissioned","account_admin_incident_response"],"description":"Closed account-administrator reason for revoking a visible authorization.","example":"account_admin_security_review"}}},"example":{"reason":"account_admin_security_review"}}}},"responses":{"200":{"description":"The consent and its related OAuth credential family were revoked.","content":{"application/json":{"schema":{"type":"object","required":["authorization"],"additionalProperties":false,"properties":{"authorization":{"$ref":"#/components/schemas/mcp_oauth_authorization"}}},"example":{"authorization":{"id":42,"plane":"account","status":"revoked","client":{"name":"Support desktop client","software_id":"com.example.support-desktop","software_version":"1.4.0"},"subject":{"name":"Ana Support","email":"ana@example.com"},"resource":{"uri":"https://app.example.com/api/v1/accounts/31/mcp/oauth/c/a1b2c3d4e5f6g7h8i9j0","profile_name":"support-read-only","profile_enabled":true,"effective_read_only":true,"toolsets":["Conversations","Contacts"],"tool_count":18},"scopes":["mcp:read"],"decided_at":"2026-08-05T12:00:00Z","last_used_at":"2026-08-05T12:10:00Z","access_token_expires_at":"2026-08-05T12:15:00Z","revoked_at":"2026-08-05T12:12:00Z","can_revoke":false}}}}},"401":{"description":"Missing or invalid account API credential."},"403":{"description":"The authenticated user is not a member of this account."},"404":{"description":"The authorization does not exist in the current user's account-scoped visible set. This includes another member's authorization for a regular member."},"422":{"description":"An account administrator omitted a revocation reason or submitted a reason outside the closed vocabulary.","content":{"application/json":{"schema":{"type":"object","required":["error"],"additionalProperties":false,"properties":{"error":{"type":"string","enum":["invalid_revocation_reason"],"example":"invalid_revocation_reason"}}},"example":{"error":"invalid_revocation_reason"}}}}}}},"/.well-known/oauth-protected-resource/mcp/accounts/{account_id}/connections/{public_id}":{"parameters":[{"name":"account_id","in":"path","required":true,"description":"Numeric account id in the exact static bearer MCP connection URL.","schema":{"type":"integer"},"example":31},{"name":"public_id","in":"path","required":true,"description":"Public, non-secret MCP access profile id in the exact static bearer MCP connection URL.","schema":{"type":"string"},"example":"profile-abc"}],"get":{"tags":["Mcp"],"operationId":"get-static-account-mcp-protected-resource-metadata","summary":"Get static bearer metadata for an account MCP resource","security":[],"description":"Public RFC 9728 Protected Resource Metadata for one concrete account MCP static-bearer URL. It never advertises an OAuth authorization server: the profile secret is a distinct, non-refreshable credential. This document does not authenticate a caller and does not reveal whether the profile exists.","responses":{"200":{"description":"Static-bearer Protected Resource Metadata for the requested account connection URL.","headers":{"Cache-Control":{"description":"Discovery metadata must not be stored by an intermediary.","schema":{"type":"string","enum":["no-store"],"example":"no-store"}}},"content":{"application/json":{"schema":{"type":"object","required":["resource","bearer_methods_supported","resource_documentation","mcp_protocol_version","mcp_protocol_versions_supported","x_mcp","x_chatwoot_mcp"],"additionalProperties":false,"properties":{"resource":{"type":"string","format":"uri","description":"Exact static bearer MCP resource URL for this account/profile pair.","example":"https://app.example.com/api/v1/accounts/31/mcp/c/profile-abc"},"bearer_methods_supported":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"string","enum":["header"],"example":"header"},"description":"Static bearer credentials are presented in the Authorization header.","example":["header"]},"resource_documentation":{"type":"string","format":"uri","description":"Installation documentation URL.","example":"https://app.example.com/"},"mcp_protocol_version":{"type":"string","enum":["2026-07-28"],"description":"Latest MCP protocol revision implemented by this resource.","example":"2026-07-28"},"mcp_protocol_versions_supported":{"type":"array","minItems":5,"maxItems":5,"uniqueItems":true,"items":{"type":"string","enum":["2026-07-28","2025-11-25","2025-06-18","2025-03-26","2024-11-05"]},"description":"SDK-supported protocol revisions, including the stateless 2026 lifecycle and compatible initialize-handshake revisions.","example":["2026-07-28","2025-11-25","2025-06-18","2025-03-26","2024-11-05"]},"x_mcp":{"type":"object","required":["note","account_endpoint"],"additionalProperties":false,"description":"Installation-specific static connection hints; this extension does not widen authorization.","properties":{"note":{"type":"string","description":"Human-readable static bearer credential guidance, branded per installation.","example":"Authenticate with this ExampleCo account profile's static bearer secret. This legacy resource deliberately does not advertise OAuth; use its separate OAuth resource when native MCP OAuth is enabled."},"account_endpoint":{"type":"string","format":"uri","description":"Exact static bearer MCP endpoint to use with the profile secret.","example":"https://app.example.com/api/v1/accounts/31/mcp/c/profile-abc"}}},"x_chatwoot_mcp":{"type":"object","required":["note","account_endpoint"],"additionalProperties":false,"deprecated":true,"description":"Deprecated legacy alias of `x_mcp`; it is always structurally and semantically identical.","properties":{"note":{"type":"string","description":"Human-readable static bearer credential guidance, branded per installation.","example":"Authenticate with this ExampleCo account profile's static bearer secret. This legacy resource deliberately does not advertise OAuth; use its separate OAuth resource when native MCP OAuth is enabled."},"account_endpoint":{"type":"string","format":"uri","description":"Exact static bearer MCP endpoint to use with the profile secret.","example":"https://app.example.com/api/v1/accounts/31/mcp/c/profile-abc"}}}}},"example":{"resource":"https://app.example.com/api/v1/accounts/31/mcp/c/profile-abc","bearer_methods_supported":["header"],"resource_documentation":"https://app.example.com/","mcp_protocol_version":"2026-07-28","mcp_protocol_versions_supported":["2026-07-28","2025-11-25","2025-06-18","2025-03-26","2024-11-05"],"x_mcp":{"note":"Authenticate with this ExampleCo account profile's static bearer secret. This legacy resource deliberately does not advertise OAuth; use its separate OAuth resource when native MCP OAuth is enabled.","account_endpoint":"https://app.example.com/api/v1/accounts/31/mcp/c/profile-abc"},"x_chatwoot_mcp":{"note":"Authenticate with this ExampleCo account profile's static bearer secret. This legacy resource deliberately does not advertise OAuth; use its separate OAuth resource when native MCP OAuth is enabled.","account_endpoint":"https://app.example.com/api/v1/accounts/31/mcp/c/profile-abc"}}}}},"404":{"description":"No safe canonical public HTTPS origin is configured. The response does not disclose profile existence.","headers":{"Cache-Control":{"description":"Discovery metadata must not be stored by an intermediary.","schema":{"type":"string","enum":["no-store"],"example":"no-store"}}}}}}},"/.well-known/oauth-protected-resource/mcp/platform":{"get":{"tags":["Mcp"],"operationId":"get-platform-mcp-protected-resource-metadata","summary":"Get static bearer metadata for the Platform MCP resource","security":[],"description":"Public RFC 9728 Protected Resource Metadata for the technical Platform MCP static-bearer URL. It does not advertise OAuth because a PlatformApp credential is not a human OAuth bearer and cannot be refreshed through the native OAuth server.","responses":{"200":{"description":"Static-bearer Protected Resource Metadata for the Platform MCP resource.","headers":{"Cache-Control":{"description":"Discovery metadata must not be stored by an intermediary.","schema":{"type":"string","enum":["no-store"],"example":"no-store"}}},"content":{"application/json":{"schema":{"type":"object","required":["resource","bearer_methods_supported","resource_documentation","mcp_protocol_version","mcp_protocol_versions_supported","x_mcp","x_chatwoot_mcp"],"additionalProperties":false,"properties":{"resource":{"type":"string","format":"uri","description":"Exact Platform MCP static bearer resource URL.","example":"https://app.example.com/platform/api/v1/mcp"},"bearer_methods_supported":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"string","enum":["header"],"example":"header"},"description":"PlatformApp bearer credentials are presented in the Authorization header.","example":["header"]},"resource_documentation":{"type":"string","format":"uri","description":"Installation documentation URL.","example":"https://app.example.com/"},"mcp_protocol_version":{"type":"string","enum":["2026-07-28"],"description":"Latest MCP protocol revision implemented by this resource.","example":"2026-07-28"},"mcp_protocol_versions_supported":{"type":"array","minItems":5,"maxItems":5,"uniqueItems":true,"items":{"type":"string","enum":["2026-07-28","2025-11-25","2025-06-18","2025-03-26","2024-11-05"]},"description":"SDK-supported protocol revisions, including the stateless 2026 lifecycle and compatible initialize-handshake revisions.","example":["2026-07-28","2025-11-25","2025-06-18","2025-03-26","2024-11-05"]},"x_mcp":{"type":"object","required":["note","platform_endpoint"],"additionalProperties":false,"description":"Installation-specific static connection hints; this extension does not widen authorization.","properties":{"note":{"type":"string","description":"Human-readable PlatformApp credential guidance, branded per installation.","example":"Authenticate with this ExampleCo PlatformApp bearer credential. This technical Platform resource deliberately does not advertise human OAuth."},"platform_endpoint":{"type":"string","format":"uri","description":"Exact Platform MCP endpoint to use with a PlatformApp bearer credential.","example":"https://app.example.com/platform/api/v1/mcp"}}},"x_chatwoot_mcp":{"type":"object","required":["note","platform_endpoint"],"additionalProperties":false,"deprecated":true,"description":"Deprecated legacy alias of `x_mcp`; it is always structurally and semantically identical.","properties":{"note":{"type":"string","description":"Human-readable PlatformApp credential guidance, branded per installation.","example":"Authenticate with this ExampleCo PlatformApp bearer credential. This technical Platform resource deliberately does not advertise human OAuth."},"platform_endpoint":{"type":"string","format":"uri","description":"Exact Platform MCP endpoint to use with a PlatformApp bearer credential.","example":"https://app.example.com/platform/api/v1/mcp"}}}}},"example":{"resource":"https://app.example.com/platform/api/v1/mcp","bearer_methods_supported":["header"],"resource_documentation":"https://app.example.com/","mcp_protocol_version":"2026-07-28","mcp_protocol_versions_supported":["2026-07-28","2025-11-25","2025-06-18","2025-03-26","2024-11-05"],"x_mcp":{"note":"Authenticate with this ExampleCo PlatformApp bearer credential. This technical Platform resource deliberately does not advertise human OAuth.","platform_endpoint":"https://app.example.com/platform/api/v1/mcp"},"x_chatwoot_mcp":{"note":"Authenticate with this ExampleCo PlatformApp bearer credential. This technical Platform resource deliberately does not advertise human OAuth.","platform_endpoint":"https://app.example.com/platform/api/v1/mcp"}}}}},"404":{"description":"No safe canonical public HTTPS origin is configured.","headers":{"Cache-Control":{"description":"Discovery metadata must not be stored by an intermediary.","schema":{"type":"string","enum":["no-store"],"example":"no-store"}}}}}}},"/.well-known/oauth-protected-resource/mcp/super-admin":{"get":{"tags":["Mcp"],"operationId":"get-static-super-admin-mcp-protected-resource-metadata","summary":"Get static bearer metadata for the Super Admin MCP resource","security":[],"description":"Public RFC 9728 Protected Resource Metadata for the dedicated Super Admin MCP static-bearer URL. Its operator credential is separate from every account token and never advertises an OAuth authorization server; the separate Super Admin OAuth resource is used only when native OAuth is enabled.","responses":{"200":{"description":"Static-bearer Protected Resource Metadata for the Super Admin MCP resource.","headers":{"Cache-Control":{"description":"Discovery metadata must not be stored by an intermediary.","schema":{"type":"string","enum":["no-store"],"example":"no-store"}}},"content":{"application/json":{"schema":{"type":"object","required":["resource","bearer_methods_supported","resource_documentation","mcp_protocol_version","mcp_protocol_versions_supported","x_mcp","x_chatwoot_mcp"],"additionalProperties":false,"properties":{"resource":{"type":"string","format":"uri","description":"Exact dedicated Super Admin MCP static bearer resource URL.","example":"https://app.example.com/super_admin/mcp"},"bearer_methods_supported":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"string","enum":["header"],"example":"header"},"description":"Dedicated Super Admin operator credentials are presented in the Authorization header.","example":["header"]},"resource_documentation":{"type":"string","format":"uri","description":"Installation documentation URL.","example":"https://app.example.com/"},"mcp_protocol_version":{"type":"string","enum":["2026-07-28"],"description":"Latest MCP protocol revision implemented by this resource.","example":"2026-07-28"},"mcp_protocol_versions_supported":{"type":"array","minItems":5,"maxItems":5,"uniqueItems":true,"items":{"type":"string","enum":["2026-07-28","2025-11-25","2025-06-18","2025-03-26","2024-11-05"]},"description":"SDK-supported protocol revisions, including the stateless 2026 lifecycle and compatible initialize-handshake revisions.","example":["2026-07-28","2025-11-25","2025-06-18","2025-03-26","2024-11-05"]},"x_mcp":{"type":"object","required":["note","super_admin_endpoint"],"additionalProperties":false,"description":"Installation-specific static connection hints; this extension does not widen authorization.","properties":{"note":{"type":"string","description":"Human-readable Super Admin operator credential guidance, branded per installation.","example":"Authenticate with a dedicated ExampleCo Super Admin operator bearer credential. It is not an account access token. This static operator resource deliberately does not advertise OAuth; use the separate OAuth operator resource when enabled."},"super_admin_endpoint":{"type":"string","format":"uri","description":"Exact Super Admin MCP endpoint to use with the dedicated operator credential.","example":"https://app.example.com/super_admin/mcp"}}},"x_chatwoot_mcp":{"type":"object","required":["note","super_admin_endpoint"],"additionalProperties":false,"deprecated":true,"description":"Deprecated legacy alias of `x_mcp`; it is always structurally and semantically identical.","properties":{"note":{"type":"string","description":"Human-readable Super Admin operator credential guidance, branded per installation.","example":"Authenticate with a dedicated ExampleCo Super Admin operator bearer credential. It is not an account access token. This static operator resource deliberately does not advertise OAuth; use the separate OAuth operator resource when enabled."},"super_admin_endpoint":{"type":"string","format":"uri","description":"Exact Super Admin MCP endpoint to use with the dedicated operator credential.","example":"https://app.example.com/super_admin/mcp"}}}}},"example":{"resource":"https://app.example.com/super_admin/mcp","bearer_methods_supported":["header"],"resource_documentation":"https://app.example.com/","mcp_protocol_version":"2026-07-28","mcp_protocol_versions_supported":["2026-07-28","2025-11-25","2025-06-18","2025-03-26","2024-11-05"],"x_mcp":{"note":"Authenticate with a dedicated ExampleCo Super Admin operator bearer credential. It is not an account access token. This static operator resource deliberately does not advertise OAuth; use the separate OAuth operator resource when enabled.","super_admin_endpoint":"https://app.example.com/super_admin/mcp"},"x_chatwoot_mcp":{"note":"Authenticate with a dedicated ExampleCo Super Admin operator bearer credential. It is not an account access token. This static operator resource deliberately does not advertise OAuth; use the separate OAuth operator resource when enabled.","super_admin_endpoint":"https://app.example.com/super_admin/mcp"}}}}},"404":{"description":"No safe canonical public HTTPS origin is configured.","headers":{"Cache-Control":{"description":"Discovery metadata must not be stored by an intermediary.","schema":{"type":"string","enum":["no-store"],"example":"no-store"}}}}}}},"/.well-known/oauth-protected-resource/mcp/oauth/accounts/{account_id}/connections/{public_id}":{"parameters":[{"name":"account_id","in":"path","required":true,"description":"Numeric account id in the exact OAuth MCP resource URL.","schema":{"type":"integer"},"example":31},{"name":"public_id","in":"path","required":true,"description":"Public, non-secret MCP access profile id in the exact OAuth MCP resource URL.","schema":{"type":"string"},"example":"a1b2c3d4e5f6g7h8i9j0"}],"get":{"tags":["Mcp"],"operationId":"get-account-mcp-oauth-protected-resource-metadata","summary":"Get OAuth metadata for an account MCP resource","security":[],"description":"Public RFC 9728 Protected Resource Metadata for one concrete account MCP OAuth URL. It advertises the canonical authorization server only after the native OAuth server is enabled. Reading this document does not authenticate a caller and does not reveal whether the account profile exists; clients must still use the exact resource URL in authorization and token requests. This is an exact formatless route: do not append `.json`.","responses":{"200":{"description":"OAuth Protected Resource Metadata for the requested account resource URL.","headers":{"Cache-Control":{"description":"Protected Resource Metadata must not be stored by an intermediary.","schema":{"type":"string","enum":["no-store"],"example":"no-store"}}},"content":{"application/json":{"schema":{"type":"object","required":["resource","bearer_methods_supported","resource_documentation","mcp_protocol_version","mcp_protocol_versions_supported","authorization_servers","scopes_supported","x_mcp","x_chatwoot_mcp"],"additionalProperties":false,"properties":{"resource":{"type":"string","format":"uri","description":"Exact OAuth MCP resource audience for this account/profile pair.","example":"https://app.example.com/api/v1/accounts/31/mcp/oauth/c/a1b2c3d4e5f6g7h8i9j0"},"bearer_methods_supported":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"string","enum":["header"],"example":"header"},"description":"OAuth bearer tokens are presented in the Authorization header.","example":["header"]},"resource_documentation":{"type":"string","format":"uri","description":"Installation documentation URL.","example":"https://app.example.com/"},"mcp_protocol_version":{"type":"string","enum":["2026-07-28"],"description":"Latest MCP protocol revision implemented by this resource.","example":"2026-07-28"},"mcp_protocol_versions_supported":{"type":"array","minItems":5,"maxItems":5,"uniqueItems":true,"items":{"type":"string","enum":["2026-07-28","2025-11-25","2025-06-18","2025-03-26","2024-11-05"]},"description":"SDK-supported protocol revisions, including the stateless 2026 lifecycle and compatible initialize-handshake revisions.","example":["2026-07-28","2025-11-25","2025-06-18","2025-03-26","2024-11-05"]},"authorization_servers":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"string","format":"uri","example":"https://app.example.com/oauth/mcp"},"description":"Canonical authorization-server issuer for this resource.","example":["https://app.example.com/oauth/mcp"]},"scopes_supported":{"type":"array","minItems":3,"maxItems":3,"items":{"type":"string","enum":["mcp:read","mcp:write","offline_access"],"example":"mcp:read"},"description":"OAuth scopes the resource can accept. Clients should request only the minimum needed.","example":["mcp:read","mcp:write","offline_access"]},"x_mcp":{"type":"object","required":["note","account_oauth_endpoint"],"additionalProperties":false,"description":"Installation-specific connection hints; the extension does not widen OAuth authorization.","properties":{"note":{"type":"string","description":"Human-readable resource binding note, branded per installation.","example":"Authenticate this ExampleCo account MCP connection with OAuth 2.1. The authorization server and resource are exact audiences."},"account_oauth_endpoint":{"type":"string","format":"uri","description":"Exact OAuth MCP endpoint to use after authorization.","example":"https://app.example.com/api/v1/accounts/31/mcp/oauth/c/a1b2c3d4e5f6g7h8i9j0"}}},"x_chatwoot_mcp":{"type":"object","required":["note","account_oauth_endpoint"],"additionalProperties":false,"deprecated":true,"description":"Deprecated legacy alias of `x_mcp`; it is always structurally and semantically identical.","properties":{"note":{"type":"string","description":"Human-readable resource binding note, branded per installation.","example":"Authenticate this ExampleCo account MCP connection with OAuth 2.1. The authorization server and resource are exact audiences."},"account_oauth_endpoint":{"type":"string","format":"uri","description":"Exact OAuth MCP endpoint to use after authorization.","example":"https://app.example.com/api/v1/accounts/31/mcp/oauth/c/a1b2c3d4e5f6g7h8i9j0"}}}}},"example":{"resource":"https://app.example.com/api/v1/accounts/31/mcp/oauth/c/a1b2c3d4e5f6g7h8i9j0","bearer_methods_supported":["header"],"resource_documentation":"https://app.example.com/","mcp_protocol_version":"2026-07-28","mcp_protocol_versions_supported":["2026-07-28","2025-11-25","2025-06-18","2025-03-26","2024-11-05"],"authorization_servers":["https://app.example.com/oauth/mcp"],"scopes_supported":["mcp:read","mcp:write","offline_access"],"x_mcp":{"note":"Authenticate this ExampleCo account MCP connection with OAuth 2.1. The authorization server and resource are exact audiences.","account_oauth_endpoint":"https://app.example.com/api/v1/accounts/31/mcp/oauth/c/a1b2c3d4e5f6g7h8i9j0"},"x_chatwoot_mcp":{"note":"Authenticate this ExampleCo account MCP connection with OAuth 2.1. The authorization server and resource are exact audiences.","account_oauth_endpoint":"https://app.example.com/api/v1/accounts/31/mcp/oauth/c/a1b2c3d4e5f6g7h8i9j0"}}}}},"404":{"description":"Native MCP OAuth is disabled for this installation or its configured issuer is invalid. The response does not disclose profile existence.","headers":{"Cache-Control":{"description":"Protected Resource Metadata responses must not be stored by an intermediary.","schema":{"type":"string","enum":["no-store"],"example":"no-store"}}}}}}},"/.well-known/oauth-protected-resource/mcp/oauth/super-admin":{"get":{"tags":["Mcp"],"operationId":"get-super-admin-mcp-oauth-protected-resource-metadata","summary":"Get OAuth metadata for the Super Admin MCP resource","security":[],"description":"Public RFC 9728 Protected Resource Metadata for the separate Super Admin OAuth MCP resource. It is not an account resource and its OAuth bearer never authenticates an account API or MCP endpoint. The document is available only while both native OAuth and the independently gated Super Admin MCP server are enabled. This is an exact formatless route: do not append `.json`.","responses":{"200":{"description":"OAuth Protected Resource Metadata for the Super Admin MCP OAuth resource.","headers":{"Cache-Control":{"description":"Protected Resource Metadata must not be stored by an intermediary.","schema":{"type":"string","enum":["no-store"],"example":"no-store"}}},"content":{"application/json":{"schema":{"type":"object","required":["resource","bearer_methods_supported","resource_documentation","mcp_protocol_version","mcp_protocol_versions_supported","authorization_servers","scopes_supported","x_mcp","x_chatwoot_mcp"],"additionalProperties":false,"properties":{"resource":{"type":"string","format":"uri","description":"Exact Super Admin OAuth MCP resource audience.","example":"https://app.example.com/super_admin/mcp/oauth"},"bearer_methods_supported":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"string","enum":["header"],"example":"header"},"description":"OAuth bearer tokens are presented in the Authorization header.","example":["header"]},"resource_documentation":{"type":"string","format":"uri","description":"Installation documentation URL.","example":"https://app.example.com/"},"mcp_protocol_version":{"type":"string","enum":["2026-07-28"],"description":"Latest MCP protocol revision implemented by this resource.","example":"2026-07-28"},"mcp_protocol_versions_supported":{"type":"array","minItems":5,"maxItems":5,"uniqueItems":true,"items":{"type":"string","enum":["2026-07-28","2025-11-25","2025-06-18","2025-03-26","2024-11-05"]},"description":"SDK-supported protocol revisions, including the stateless 2026 lifecycle and compatible initialize-handshake revisions.","example":["2026-07-28","2025-11-25","2025-06-18","2025-03-26","2024-11-05"]},"authorization_servers":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"string","format":"uri","example":"https://app.example.com/oauth/mcp"},"description":"Canonical authorization-server issuer for this resource.","example":["https://app.example.com/oauth/mcp"]},"scopes_supported":{"type":"array","minItems":3,"maxItems":3,"items":{"type":"string","enum":["mcp:read","mcp:write","offline_access"],"example":"mcp:read"},"description":"OAuth scopes the resource can accept. Clients should request only the minimum needed.","example":["mcp:read","mcp:write","offline_access"]},"x_mcp":{"type":"object","required":["note","super_admin_oauth_endpoint"],"additionalProperties":false,"description":"Installation-specific connection hints; the extension does not widen OAuth authorization.","properties":{"note":{"type":"string","description":"Human-readable operator-plane isolation note, branded per installation.","example":"Authenticate this ExampleCo Super Admin MCP connection with OAuth 2.1. It is a separate operator authority, not an account token."},"super_admin_oauth_endpoint":{"type":"string","format":"uri","description":"Exact Super Admin OAuth MCP endpoint to use after authorization.","example":"https://app.example.com/super_admin/mcp/oauth"}}},"x_chatwoot_mcp":{"type":"object","required":["note","super_admin_oauth_endpoint"],"additionalProperties":false,"deprecated":true,"description":"Deprecated legacy alias of `x_mcp`; it is always structurally and semantically identical.","properties":{"note":{"type":"string","description":"Human-readable operator-plane isolation note, branded per installation.","example":"Authenticate this ExampleCo Super Admin MCP connection with OAuth 2.1. It is a separate operator authority, not an account token."},"super_admin_oauth_endpoint":{"type":"string","format":"uri","description":"Exact Super Admin OAuth MCP endpoint to use after authorization.","example":"https://app.example.com/super_admin/mcp/oauth"}}}}},"example":{"resource":"https://app.example.com/super_admin/mcp/oauth","bearer_methods_supported":["header"],"resource_documentation":"https://app.example.com/","mcp_protocol_version":"2026-07-28","mcp_protocol_versions_supported":["2026-07-28","2025-11-25","2025-06-18","2025-03-26","2024-11-05"],"authorization_servers":["https://app.example.com/oauth/mcp"],"scopes_supported":["mcp:read","mcp:write","offline_access"],"x_mcp":{"note":"Authenticate this ExampleCo Super Admin MCP connection with OAuth 2.1. It is a separate operator authority, not an account token.","super_admin_oauth_endpoint":"https://app.example.com/super_admin/mcp/oauth"},"x_chatwoot_mcp":{"note":"Authenticate this ExampleCo Super Admin MCP connection with OAuth 2.1. It is a separate operator authority, not an account token.","super_admin_oauth_endpoint":"https://app.example.com/super_admin/mcp/oauth"}}}}},"404":{"description":"Native OAuth, the general MCP server, or the independent Super Admin MCP server is disabled; alternatively, the configured issuer is invalid.","headers":{"Cache-Control":{"description":"Protected Resource Metadata responses must not be stored by an intermediary.","schema":{"type":"string","enum":["no-store"],"example":"no-store"}}}}}}},"/.well-known/oauth-protected-resource/api/v1/accounts/{account_id}/mcp/c/{public_id}":{"parameters":[{"name":"account_id","in":"path","required":true,"description":"Numeric account id in the exact static bearer MCP connection URL.","schema":{"type":"integer"},"example":31},{"name":"public_id","in":"path","required":true,"description":"Public, non-secret MCP access profile id in the exact static bearer MCP connection URL.","schema":{"type":"string"},"example":"profile-abc"}],"get":{"tags":["Mcp"],"operationId":"get-static-account-mcp-protected-resource-metadata-derived","summary":"Get static bearer metadata at the RFC 9728 derived path","security":[],"description":"Identical response to the curated `/mcp/accounts/{account_id}/connections/{public_id}` metadata path, served at the URL a client builds by inserting `/.well-known/oauth-protected-resource` before the static bearer resource's own path. Both paths describe the same resource and the same static bearer authentication; neither advertises an OAuth authorization server. This is an exact formatless route: do not append `.json`.","responses":{"200":{"description":"Static-bearer Protected Resource Metadata for the requested account connection URL.","headers":{"Cache-Control":{"description":"Discovery metadata must not be stored by an intermediary.","schema":{"type":"string","enum":["no-store"],"example":"no-store"}}},"content":{"application/json":{"schema":{"type":"object","required":["resource","bearer_methods_supported","resource_documentation","mcp_protocol_version","mcp_protocol_versions_supported","x_mcp","x_chatwoot_mcp"],"additionalProperties":false,"properties":{"resource":{"type":"string","format":"uri","description":"Exact static bearer MCP resource URL for this account/profile pair.","example":"https://app.example.com/api/v1/accounts/31/mcp/c/profile-abc"},"bearer_methods_supported":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"string","enum":["header"],"example":"header"},"description":"Static bearer credentials are presented in the Authorization header.","example":["header"]},"resource_documentation":{"type":"string","format":"uri","description":"Installation documentation URL.","example":"https://app.example.com/"},"mcp_protocol_version":{"type":"string","enum":["2026-07-28"],"description":"Latest MCP protocol revision implemented by this resource.","example":"2026-07-28"},"mcp_protocol_versions_supported":{"type":"array","minItems":5,"maxItems":5,"uniqueItems":true,"items":{"type":"string","enum":["2026-07-28","2025-11-25","2025-06-18","2025-03-26","2024-11-05"]},"description":"SDK-supported protocol revisions, including the stateless 2026 lifecycle and compatible initialize-handshake revisions.","example":["2026-07-28","2025-11-25","2025-06-18","2025-03-26","2024-11-05"]},"x_mcp":{"type":"object","required":["note","account_endpoint"],"additionalProperties":false,"description":"Installation-specific static connection hints; this extension does not widen authorization.","properties":{"note":{"type":"string","description":"Human-readable static bearer credential guidance, branded per installation.","example":"Authenticate with this ExampleCo account profile's static bearer secret. This legacy resource deliberately does not advertise OAuth; use its separate OAuth resource when native MCP OAuth is enabled."},"account_endpoint":{"type":"string","format":"uri","description":"Exact static bearer MCP endpoint to use with the profile secret.","example":"https://app.example.com/api/v1/accounts/31/mcp/c/profile-abc"}}},"x_chatwoot_mcp":{"type":"object","required":["note","account_endpoint"],"additionalProperties":false,"deprecated":true,"description":"Deprecated legacy alias of `x_mcp`; it is always structurally and semantically identical.","properties":{"note":{"type":"string","description":"Human-readable static bearer credential guidance, branded per installation.","example":"Authenticate with this ExampleCo account profile's static bearer secret. This legacy resource deliberately does not advertise OAuth; use its separate OAuth resource when native MCP OAuth is enabled."},"account_endpoint":{"type":"string","format":"uri","description":"Exact static bearer MCP endpoint to use with the profile secret.","example":"https://app.example.com/api/v1/accounts/31/mcp/c/profile-abc"}}}}},"example":{"resource":"https://app.example.com/api/v1/accounts/31/mcp/c/profile-abc","bearer_methods_supported":["header"],"resource_documentation":"https://app.example.com/","mcp_protocol_version":"2026-07-28","mcp_protocol_versions_supported":["2026-07-28","2025-11-25","2025-06-18","2025-03-26","2024-11-05"],"x_mcp":{"note":"Authenticate with this ExampleCo account profile's static bearer secret. This legacy resource deliberately does not advertise OAuth; use its separate OAuth resource when native MCP OAuth is enabled.","account_endpoint":"https://app.example.com/api/v1/accounts/31/mcp/c/profile-abc"},"x_chatwoot_mcp":{"note":"Authenticate with this ExampleCo account profile's static bearer secret. This legacy resource deliberately does not advertise OAuth; use its separate OAuth resource when native MCP OAuth is enabled.","account_endpoint":"https://app.example.com/api/v1/accounts/31/mcp/c/profile-abc"}}}}},"404":{"description":"No safe canonical public HTTPS origin is configured. The response does not disclose profile existence.","headers":{"Cache-Control":{"description":"Discovery metadata must not be stored by an intermediary.","schema":{"type":"string","enum":["no-store"],"example":"no-store"}}}}}}},"/.well-known/oauth-protected-resource/api/v1/accounts/{account_id}/mcp/oauth/c/{public_id}":{"parameters":[{"name":"account_id","in":"path","required":true,"description":"Numeric account id in the exact OAuth MCP resource URL.","schema":{"type":"integer"},"example":31},{"name":"public_id","in":"path","required":true,"description":"Public, non-secret MCP access profile id in the exact OAuth MCP resource URL.","schema":{"type":"string"},"example":"a1b2c3d4e5f6g7h8i9j0"}],"get":{"tags":["Mcp"],"operationId":"get-account-mcp-oauth-protected-resource-metadata-derived","summary":"Get account OAuth metadata at the RFC 9728 derived path","security":[],"description":"Identical response to the curated `/mcp/oauth/accounts/{account_id}/connections/{public_id}` metadata path, served at the URL a client builds by inserting `/.well-known/oauth-protected-resource` before the OAuth resource's own path. It advertises the canonical authorization server only while the native OAuth server is enabled, and returns 404 otherwise — exactly like the curated path. Reading it does not authenticate a caller and does not reveal whether the profile exists. This is an exact formatless route: do not append `.json`.","responses":{"200":{"description":"OAuth Protected Resource Metadata for the requested account resource URL.","headers":{"Cache-Control":{"description":"Protected Resource Metadata must not be stored by an intermediary.","schema":{"type":"string","enum":["no-store"],"example":"no-store"}}},"content":{"application/json":{"schema":{"type":"object","required":["resource","bearer_methods_supported","resource_documentation","mcp_protocol_version","mcp_protocol_versions_supported","authorization_servers","scopes_supported","x_mcp","x_chatwoot_mcp"],"additionalProperties":false,"properties":{"resource":{"type":"string","format":"uri","description":"Exact OAuth MCP resource audience for this account/profile pair.","example":"https://app.example.com/api/v1/accounts/31/mcp/oauth/c/a1b2c3d4e5f6g7h8i9j0"},"bearer_methods_supported":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"string","enum":["header"],"example":"header"},"description":"OAuth bearer tokens are presented in the Authorization header.","example":["header"]},"resource_documentation":{"type":"string","format":"uri","description":"Installation documentation URL.","example":"https://app.example.com/"},"mcp_protocol_version":{"type":"string","enum":["2026-07-28"],"description":"Latest MCP protocol revision implemented by this resource.","example":"2026-07-28"},"mcp_protocol_versions_supported":{"type":"array","minItems":5,"maxItems":5,"uniqueItems":true,"items":{"type":"string","enum":["2026-07-28","2025-11-25","2025-06-18","2025-03-26","2024-11-05"]},"description":"SDK-supported protocol revisions, including the stateless 2026 lifecycle and compatible initialize-handshake revisions.","example":["2026-07-28","2025-11-25","2025-06-18","2025-03-26","2024-11-05"]},"authorization_servers":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"string","format":"uri","example":"https://app.example.com/oauth/mcp"},"description":"Canonical authorization-server issuer for this resource.","example":["https://app.example.com/oauth/mcp"]},"scopes_supported":{"type":"array","minItems":3,"maxItems":3,"items":{"type":"string","enum":["mcp:read","mcp:write","offline_access"],"example":"mcp:read"},"description":"OAuth scopes the resource can accept. Clients should request only the minimum needed.","example":["mcp:read","mcp:write","offline_access"]},"x_mcp":{"type":"object","required":["note","account_oauth_endpoint"],"additionalProperties":false,"description":"Installation-specific connection hints; the extension does not widen OAuth authorization.","properties":{"note":{"type":"string","description":"Human-readable resource binding note, branded per installation.","example":"Authenticate this ExampleCo account MCP connection with OAuth 2.1. The authorization server and resource are exact audiences."},"account_oauth_endpoint":{"type":"string","format":"uri","description":"Exact OAuth MCP endpoint to use after authorization.","example":"https://app.example.com/api/v1/accounts/31/mcp/oauth/c/a1b2c3d4e5f6g7h8i9j0"}}},"x_chatwoot_mcp":{"type":"object","required":["note","account_oauth_endpoint"],"additionalProperties":false,"deprecated":true,"description":"Deprecated legacy alias of `x_mcp`; it is always structurally and semantically identical.","properties":{"note":{"type":"string","description":"Human-readable resource binding note, branded per installation.","example":"Authenticate this ExampleCo account MCP connection with OAuth 2.1. The authorization server and resource are exact audiences."},"account_oauth_endpoint":{"type":"string","format":"uri","description":"Exact OAuth MCP endpoint to use after authorization.","example":"https://app.example.com/api/v1/accounts/31/mcp/oauth/c/a1b2c3d4e5f6g7h8i9j0"}}}}},"example":{"resource":"https://app.example.com/api/v1/accounts/31/mcp/oauth/c/a1b2c3d4e5f6g7h8i9j0","bearer_methods_supported":["header"],"resource_documentation":"https://app.example.com/","mcp_protocol_version":"2026-07-28","mcp_protocol_versions_supported":["2026-07-28","2025-11-25","2025-06-18","2025-03-26","2024-11-05"],"authorization_servers":["https://app.example.com/oauth/mcp"],"scopes_supported":["mcp:read","mcp:write","offline_access"],"x_mcp":{"note":"Authenticate this ExampleCo account MCP connection with OAuth 2.1. The authorization server and resource are exact audiences.","account_oauth_endpoint":"https://app.example.com/api/v1/accounts/31/mcp/oauth/c/a1b2c3d4e5f6g7h8i9j0"},"x_chatwoot_mcp":{"note":"Authenticate this ExampleCo account MCP connection with OAuth 2.1. The authorization server and resource are exact audiences.","account_oauth_endpoint":"https://app.example.com/api/v1/accounts/31/mcp/oauth/c/a1b2c3d4e5f6g7h8i9j0"}}}}},"404":{"description":"Native MCP OAuth is disabled for this installation or its configured issuer is invalid. The response does not disclose profile existence.","headers":{"Cache-Control":{"description":"Protected Resource Metadata responses must not be stored by an intermediary.","schema":{"type":"string","enum":["no-store"],"example":"no-store"}}}}}}},"/.well-known/oauth-protected-resource/super_admin/mcp":{"get":{"tags":["Mcp"],"operationId":"get-static-super-admin-mcp-protected-resource-metadata-derived","summary":"Get static bearer Super Admin metadata at the RFC 9728 derived path","security":[],"description":"Identical response to the curated `/mcp/super-admin` metadata path, served at the URL a client builds by inserting `/.well-known/oauth-protected-resource` before the operator resource's own path. Both paths describe the same dedicated Super Admin static-bearer resource and neither advertises an OAuth authorization server. This is an exact formatless route: do not append `.json`.","responses":{"200":{"description":"Static-bearer Protected Resource Metadata for the Super Admin MCP resource.","headers":{"Cache-Control":{"description":"Discovery metadata must not be stored by an intermediary.","schema":{"type":"string","enum":["no-store"],"example":"no-store"}}},"content":{"application/json":{"schema":{"type":"object","required":["resource","bearer_methods_supported","resource_documentation","mcp_protocol_version","mcp_protocol_versions_supported","x_mcp","x_chatwoot_mcp"],"additionalProperties":false,"properties":{"resource":{"type":"string","format":"uri","description":"Exact dedicated Super Admin MCP static bearer resource URL.","example":"https://app.example.com/super_admin/mcp"},"bearer_methods_supported":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"string","enum":["header"],"example":"header"},"description":"Dedicated Super Admin operator credentials are presented in the Authorization header.","example":["header"]},"resource_documentation":{"type":"string","format":"uri","description":"Installation documentation URL.","example":"https://app.example.com/"},"mcp_protocol_version":{"type":"string","enum":["2026-07-28"],"description":"Latest MCP protocol revision implemented by this resource.","example":"2026-07-28"},"mcp_protocol_versions_supported":{"type":"array","minItems":5,"maxItems":5,"uniqueItems":true,"items":{"type":"string","enum":["2026-07-28","2025-11-25","2025-06-18","2025-03-26","2024-11-05"]},"description":"SDK-supported protocol revisions, including the stateless 2026 lifecycle and compatible initialize-handshake revisions.","example":["2026-07-28","2025-11-25","2025-06-18","2025-03-26","2024-11-05"]},"x_mcp":{"type":"object","required":["note","super_admin_endpoint"],"additionalProperties":false,"description":"Installation-specific static connection hints; this extension does not widen authorization.","properties":{"note":{"type":"string","description":"Human-readable Super Admin operator credential guidance, branded per installation.","example":"Authenticate with a dedicated ExampleCo Super Admin operator bearer credential. It is not an account access token. This static operator resource deliberately does not advertise OAuth; use the separate OAuth operator resource when enabled."},"super_admin_endpoint":{"type":"string","format":"uri","description":"Exact Super Admin MCP endpoint to use with the dedicated operator credential.","example":"https://app.example.com/super_admin/mcp"}}},"x_chatwoot_mcp":{"type":"object","required":["note","super_admin_endpoint"],"additionalProperties":false,"deprecated":true,"description":"Deprecated legacy alias of `x_mcp`; it is always structurally and semantically identical.","properties":{"note":{"type":"string","description":"Human-readable Super Admin operator credential guidance, branded per installation.","example":"Authenticate with a dedicated ExampleCo Super Admin operator bearer credential. It is not an account access token. This static operator resource deliberately does not advertise OAuth; use the separate OAuth operator resource when enabled."},"super_admin_endpoint":{"type":"string","format":"uri","description":"Exact Super Admin MCP endpoint to use with the dedicated operator credential.","example":"https://app.example.com/super_admin/mcp"}}}}},"example":{"resource":"https://app.example.com/super_admin/mcp","bearer_methods_supported":["header"],"resource_documentation":"https://app.example.com/","mcp_protocol_version":"2026-07-28","mcp_protocol_versions_supported":["2026-07-28","2025-11-25","2025-06-18","2025-03-26","2024-11-05"],"x_mcp":{"note":"Authenticate with a dedicated ExampleCo Super Admin operator bearer credential. It is not an account access token. This static operator resource deliberately does not advertise OAuth; use the separate OAuth operator resource when enabled.","super_admin_endpoint":"https://app.example.com/super_admin/mcp"},"x_chatwoot_mcp":{"note":"Authenticate with a dedicated ExampleCo Super Admin operator bearer credential. It is not an account access token. This static operator resource deliberately does not advertise OAuth; use the separate OAuth operator resource when enabled.","super_admin_endpoint":"https://app.example.com/super_admin/mcp"}}}}},"404":{"description":"No safe canonical public HTTPS origin is configured.","headers":{"Cache-Control":{"description":"Discovery metadata must not be stored by an intermediary.","schema":{"type":"string","enum":["no-store"],"example":"no-store"}}}}}}},"/.well-known/oauth-protected-resource/super_admin/mcp/oauth":{"get":{"tags":["Mcp"],"operationId":"get-super-admin-mcp-oauth-protected-resource-metadata-derived","summary":"Get Super Admin OAuth metadata at the RFC 9728 derived path","security":[],"description":"Identical response to the curated `/mcp/oauth/super-admin` metadata path, served at the URL a client builds by inserting `/.well-known/oauth-protected-resource` before the operator OAuth resource's own path. The document is available only while both native OAuth and the independently gated Super Admin MCP server are enabled, and returns 404 otherwise — exactly like the curated path. This is an exact formatless route: do not append `.json`.","responses":{"200":{"description":"OAuth Protected Resource Metadata for the Super Admin MCP OAuth resource.","headers":{"Cache-Control":{"description":"Protected Resource Metadata must not be stored by an intermediary.","schema":{"type":"string","enum":["no-store"],"example":"no-store"}}},"content":{"application/json":{"schema":{"type":"object","required":["resource","bearer_methods_supported","resource_documentation","mcp_protocol_version","mcp_protocol_versions_supported","authorization_servers","scopes_supported","x_mcp","x_chatwoot_mcp"],"additionalProperties":false,"properties":{"resource":{"type":"string","format":"uri","description":"Exact Super Admin OAuth MCP resource audience.","example":"https://app.example.com/super_admin/mcp/oauth"},"bearer_methods_supported":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"string","enum":["header"],"example":"header"},"description":"OAuth bearer tokens are presented in the Authorization header.","example":["header"]},"resource_documentation":{"type":"string","format":"uri","description":"Installation documentation URL.","example":"https://app.example.com/"},"mcp_protocol_version":{"type":"string","enum":["2026-07-28"],"description":"Latest MCP protocol revision implemented by this resource.","example":"2026-07-28"},"mcp_protocol_versions_supported":{"type":"array","minItems":5,"maxItems":5,"uniqueItems":true,"items":{"type":"string","enum":["2026-07-28","2025-11-25","2025-06-18","2025-03-26","2024-11-05"]},"description":"SDK-supported protocol revisions, including the stateless 2026 lifecycle and compatible initialize-handshake revisions.","example":["2026-07-28","2025-11-25","2025-06-18","2025-03-26","2024-11-05"]},"authorization_servers":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"string","format":"uri","example":"https://app.example.com/oauth/mcp"},"description":"Canonical authorization-server issuer for this resource.","example":["https://app.example.com/oauth/mcp"]},"scopes_supported":{"type":"array","minItems":3,"maxItems":3,"items":{"type":"string","enum":["mcp:read","mcp:write","offline_access"],"example":"mcp:read"},"description":"OAuth scopes the resource can accept. Clients should request only the minimum needed.","example":["mcp:read","mcp:write","offline_access"]},"x_mcp":{"type":"object","required":["note","super_admin_oauth_endpoint"],"additionalProperties":false,"description":"Installation-specific connection hints; the extension does not widen OAuth authorization.","properties":{"note":{"type":"string","description":"Human-readable operator-plane isolation note, branded per installation.","example":"Authenticate this ExampleCo Super Admin MCP connection with OAuth 2.1. It is a separate operator authority, not an account token."},"super_admin_oauth_endpoint":{"type":"string","format":"uri","description":"Exact Super Admin OAuth MCP endpoint to use after authorization.","example":"https://app.example.com/super_admin/mcp/oauth"}}},"x_chatwoot_mcp":{"type":"object","required":["note","super_admin_oauth_endpoint"],"additionalProperties":false,"deprecated":true,"description":"Deprecated legacy alias of `x_mcp`; it is always structurally and semantically identical.","properties":{"note":{"type":"string","description":"Human-readable operator-plane isolation note, branded per installation.","example":"Authenticate this ExampleCo Super Admin MCP connection with OAuth 2.1. It is a separate operator authority, not an account token."},"super_admin_oauth_endpoint":{"type":"string","format":"uri","description":"Exact Super Admin OAuth MCP endpoint to use after authorization.","example":"https://app.example.com/super_admin/mcp/oauth"}}}}},"example":{"resource":"https://app.example.com/super_admin/mcp/oauth","bearer_methods_supported":["header"],"resource_documentation":"https://app.example.com/","mcp_protocol_version":"2026-07-28","mcp_protocol_versions_supported":["2026-07-28","2025-11-25","2025-06-18","2025-03-26","2024-11-05"],"authorization_servers":["https://app.example.com/oauth/mcp"],"scopes_supported":["mcp:read","mcp:write","offline_access"],"x_mcp":{"note":"Authenticate this ExampleCo Super Admin MCP connection with OAuth 2.1. It is a separate operator authority, not an account token.","super_admin_oauth_endpoint":"https://app.example.com/super_admin/mcp/oauth"},"x_chatwoot_mcp":{"note":"Authenticate this ExampleCo Super Admin MCP connection with OAuth 2.1. It is a separate operator authority, not an account token.","super_admin_oauth_endpoint":"https://app.example.com/super_admin/mcp/oauth"}}}}},"404":{"description":"Native OAuth, the general MCP server, or the independent Super Admin MCP server is disabled; alternatively, the configured issuer is invalid.","headers":{"Cache-Control":{"description":"Protected Resource Metadata responses must not be stored by an intermediary.","schema":{"type":"string","enum":["no-store"],"example":"no-store"}}}}}}},"/.well-known/oauth-protected-resource/platform/api/v1/mcp":{"get":{"tags":["Mcp"],"operationId":"get-platform-mcp-protected-resource-metadata-derived","summary":"Get Platform metadata at the RFC 9728 derived path","security":[],"description":"Identical response to the curated `/mcp/platform` metadata path, served at the URL a client builds by inserting `/.well-known/oauth-protected-resource` before the Platform resource's own path. Both paths describe the same PlatformApp bearer resource and neither advertises an OAuth authorization server: a PlatformApp token is a technical provisioning credential, not a human OAuth grant. This is an exact formatless route: do not append `.json`.","responses":{"200":{"description":"Static-bearer Protected Resource Metadata for the Platform MCP resource.","headers":{"Cache-Control":{"description":"Discovery metadata must not be stored by an intermediary.","schema":{"type":"string","enum":["no-store"],"example":"no-store"}}},"content":{"application/json":{"schema":{"type":"object","required":["resource","bearer_methods_supported","resource_documentation","mcp_protocol_version","mcp_protocol_versions_supported","x_mcp","x_chatwoot_mcp"],"additionalProperties":false,"properties":{"resource":{"type":"string","format":"uri","description":"Exact Platform MCP static bearer resource URL.","example":"https://app.example.com/platform/api/v1/mcp"},"bearer_methods_supported":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"string","enum":["header"],"example":"header"},"description":"PlatformApp bearer credentials are presented in the Authorization header.","example":["header"]},"resource_documentation":{"type":"string","format":"uri","description":"Installation documentation URL.","example":"https://app.example.com/"},"mcp_protocol_version":{"type":"string","enum":["2026-07-28"],"description":"Latest MCP protocol revision implemented by this resource.","example":"2026-07-28"},"mcp_protocol_versions_supported":{"type":"array","minItems":5,"maxItems":5,"uniqueItems":true,"items":{"type":"string","enum":["2026-07-28","2025-11-25","2025-06-18","2025-03-26","2024-11-05"]},"description":"SDK-supported protocol revisions, including the stateless 2026 lifecycle and compatible initialize-handshake revisions.","example":["2026-07-28","2025-11-25","2025-06-18","2025-03-26","2024-11-05"]},"x_mcp":{"type":"object","required":["note","platform_endpoint"],"additionalProperties":false,"description":"Installation-specific static connection hints; this extension does not widen authorization.","properties":{"note":{"type":"string","description":"Human-readable PlatformApp credential guidance, branded per installation.","example":"Authenticate with this ExampleCo PlatformApp bearer credential. This technical Platform resource deliberately does not advertise human OAuth."},"platform_endpoint":{"type":"string","format":"uri","description":"Exact Platform MCP endpoint to use with a PlatformApp bearer credential.","example":"https://app.example.com/platform/api/v1/mcp"}}},"x_chatwoot_mcp":{"type":"object","required":["note","platform_endpoint"],"additionalProperties":false,"deprecated":true,"description":"Deprecated legacy alias of `x_mcp`; it is always structurally and semantically identical.","properties":{"note":{"type":"string","description":"Human-readable PlatformApp credential guidance, branded per installation.","example":"Authenticate with this ExampleCo PlatformApp bearer credential. This technical Platform resource deliberately does not advertise human OAuth."},"platform_endpoint":{"type":"string","format":"uri","description":"Exact Platform MCP endpoint to use with a PlatformApp bearer credential.","example":"https://app.example.com/platform/api/v1/mcp"}}}}},"example":{"resource":"https://app.example.com/platform/api/v1/mcp","bearer_methods_supported":["header"],"resource_documentation":"https://app.example.com/","mcp_protocol_version":"2026-07-28","mcp_protocol_versions_supported":["2026-07-28","2025-11-25","2025-06-18","2025-03-26","2024-11-05"],"x_mcp":{"note":"Authenticate with this ExampleCo PlatformApp bearer credential. This technical Platform resource deliberately does not advertise human OAuth.","platform_endpoint":"https://app.example.com/platform/api/v1/mcp"},"x_chatwoot_mcp":{"note":"Authenticate with this ExampleCo PlatformApp bearer credential. This technical Platform resource deliberately does not advertise human OAuth.","platform_endpoint":"https://app.example.com/platform/api/v1/mcp"}}}}},"404":{"description":"No safe canonical public HTTPS origin is configured.","headers":{"Cache-Control":{"description":"Discovery metadata must not be stored by an intermediary.","schema":{"type":"string","enum":["no-store"],"example":"no-store"}}}}}}},"/.well-known/oauth-authorization-server/oauth/mcp":{"get":{"tags":["Mcp"],"operationId":"get-mcp-oauth-authorization-server-metadata","summary":"Discover the native MCP OAuth authorization server","security":[],"description":"Canonical RFC 8414 metadata for the native MCP OAuth authorization server. The issuer contains the /oauth/mcp path; clients should use this path-aware discovery URL or the issuer advertised by a Protected Resource Metadata document. The endpoint is deliberately undiscoverable while native MCP OAuth is disabled or the configured production issuer is invalid. This is an exact formatless route: do not append `.json` or construct it from an arbitrary request host.","responses":{"200":{"description":"Native MCP OAuth authorization-server metadata. Responses are not cacheable.","headers":{"Cache-Control":{"description":"OAuth discovery responses must not be stored by an intermediary.","schema":{"type":"string","enum":["no-store"],"example":"no-store"}}},"content":{"application/json":{"schema":{"type":"object","required":["issuer","authorization_endpoint","token_endpoint","revocation_endpoint","response_types_supported","grant_types_supported","token_endpoint_auth_methods_supported","code_challenge_methods_supported","client_id_metadata_document_supported","authorization_response_iss_parameter_supported","scopes_supported"],"additionalProperties":false,"properties":{"issuer":{"type":"string","format":"uri","description":"Canonical authorization-server issuer, ending in /oauth/mcp.","example":"https://app.example.com/oauth/mcp"},"authorization_endpoint":{"type":"string","format":"uri","description":"Browser authorization and consent endpoint.","example":"https://app.example.com/oauth/mcp/authorize"},"token_endpoint":{"type":"string","format":"uri","description":"Authorization-code and refresh-token exchange endpoint.","example":"https://app.example.com/oauth/mcp/token"},"revocation_endpoint":{"type":"string","format":"uri","description":"OAuth token and consent-family revocation endpoint.","example":"https://app.example.com/oauth/mcp/revoke"},"registration_endpoint":{"type":"string","format":"uri","description":"Optional Dynamic Client Registration endpoint for public MCP clients. It is present only when the installation's separate MCP OAuth DCR gate is enabled.","example":"https://app.example.com/oauth/mcp/register"},"response_types_supported":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"string","enum":["code"],"example":"code"},"example":["code"]},"grant_types_supported":{"type":"array","minItems":2,"maxItems":2,"items":{"type":"string","enum":["authorization_code","refresh_token"],"example":"authorization_code"},"example":["authorization_code","refresh_token"]},"token_endpoint_auth_methods_supported":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"string","enum":["none"],"example":"none"},"description":"Public clients identify with client_id; client secrets are not supported.","example":["none"]},"code_challenge_methods_supported":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"string","enum":["S256"],"example":"S256"},"description":"S256 PKCE is mandatory for every supported client.","example":["S256"]},"client_id_metadata_document_supported":{"type":"boolean","enum":[true],"description":"Verified public Client ID Metadata Documents (CIMD) are supported independently of whether Dynamic Client Registration is advertised.","example":true},"authorization_response_iss_parameter_supported":{"type":"boolean","enum":[true],"description":"Every redirectable authorization response includes the canonical issuer in its iss query parameter (RFC 9207).","example":true},"scopes_supported":{"type":"array","minItems":3,"maxItems":3,"items":{"type":"string","enum":["mcp:read","mcp:write","offline_access"],"example":"mcp:read"},"example":["mcp:read","mcp:write","offline_access"]}}},"example":{"issuer":"https://app.example.com/oauth/mcp","authorization_endpoint":"https://app.example.com/oauth/mcp/authorize","token_endpoint":"https://app.example.com/oauth/mcp/token","revocation_endpoint":"https://app.example.com/oauth/mcp/revoke","registration_endpoint":"https://app.example.com/oauth/mcp/register","response_types_supported":["code"],"grant_types_supported":["authorization_code","refresh_token"],"token_endpoint_auth_methods_supported":["none"],"code_challenge_methods_supported":["S256"],"client_id_metadata_document_supported":true,"authorization_response_iss_parameter_supported":true,"scopes_supported":["mcp:read","mcp:write","offline_access"]}}}},"404":{"description":"Native MCP OAuth is disabled or the configured issuer is invalid. No issuer detail is returned."}}}},"/.well-known/oauth-authorization-server":{"get":{"tags":["Mcp"],"operationId":"get-mcp-oauth-authorization-server-root-metadata","summary":"Discover the native MCP OAuth authorization server (compatibility alias)","security":[],"description":"Compatibility alias for native OAuth metadata. It returns the same canonical issuer and endpoints as the path-aware document at /.well-known/oauth-authorization-server/oauth/mcp. New clients should use the issuer advertised by Protected Resource Metadata rather than constructing discovery from a host. This is an exact formatless route: do not append `.json`.","responses":{"200":{"description":"Native MCP OAuth authorization-server metadata. Responses are not cacheable.","headers":{"Cache-Control":{"description":"OAuth discovery responses must not be stored by an intermediary.","schema":{"type":"string","enum":["no-store"],"example":"no-store"}}},"content":{"application/json":{"schema":{"type":"object","required":["issuer","authorization_endpoint","token_endpoint","revocation_endpoint","response_types_supported","grant_types_supported","token_endpoint_auth_methods_supported","code_challenge_methods_supported","client_id_metadata_document_supported","authorization_response_iss_parameter_supported","scopes_supported"],"additionalProperties":false,"properties":{"issuer":{"type":"string","format":"uri","description":"Canonical issuer, ending in /oauth/mcp.","example":"https://app.example.com/oauth/mcp"},"authorization_endpoint":{"type":"string","format":"uri","example":"https://app.example.com/oauth/mcp/authorize"},"token_endpoint":{"type":"string","format":"uri","example":"https://app.example.com/oauth/mcp/token"},"revocation_endpoint":{"type":"string","format":"uri","example":"https://app.example.com/oauth/mcp/revoke"},"registration_endpoint":{"type":"string","format":"uri","description":"Optional Dynamic Client Registration endpoint. It is present only when the installation's separate MCP OAuth DCR gate is enabled.","example":"https://app.example.com/oauth/mcp/register"},"response_types_supported":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"string","enum":["code"],"example":"code"},"example":["code"]},"grant_types_supported":{"type":"array","minItems":2,"maxItems":2,"items":{"type":"string","enum":["authorization_code","refresh_token"],"example":"authorization_code"},"example":["authorization_code","refresh_token"]},"token_endpoint_auth_methods_supported":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"string","enum":["none"],"example":"none"},"example":["none"]},"code_challenge_methods_supported":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"string","enum":["S256"],"example":"S256"},"example":["S256"]},"client_id_metadata_document_supported":{"type":"boolean","enum":[true],"description":"Verified public Client ID Metadata Documents (CIMD) are supported independently of whether Dynamic Client Registration is advertised.","example":true},"authorization_response_iss_parameter_supported":{"type":"boolean","enum":[true],"description":"Every redirectable authorization response includes the canonical issuer in its iss query parameter (RFC 9207).","example":true},"scopes_supported":{"type":"array","minItems":3,"maxItems":3,"items":{"type":"string","enum":["mcp:read","mcp:write","offline_access"],"example":"mcp:read"},"example":["mcp:read","mcp:write","offline_access"]}}},"example":{"issuer":"https://app.example.com/oauth/mcp","authorization_endpoint":"https://app.example.com/oauth/mcp/authorize","token_endpoint":"https://app.example.com/oauth/mcp/token","revocation_endpoint":"https://app.example.com/oauth/mcp/revoke","registration_endpoint":"https://app.example.com/oauth/mcp/register","response_types_supported":["code"],"grant_types_supported":["authorization_code","refresh_token"],"token_endpoint_auth_methods_supported":["none"],"code_challenge_methods_supported":["S256"],"client_id_metadata_document_supported":true,"authorization_response_iss_parameter_supported":true,"scopes_supported":["mcp:read","mcp:write","offline_access"]}}}},"404":{"description":"Native MCP OAuth is disabled or the configured issuer is invalid. No issuer detail is returned."}}}},"/oauth/mcp/authorize":{"get":{"tags":["Mcp"],"operationId":"start-mcp-oauth-authorization","summary":"Start a native MCP OAuth authorization request","security":[],"description":"Starts an OAuth 2.1 Authorization Code request for one exact OAuth MCP resource URL. The browser authenticates freshly, displays the client, plane, requested scopes and redirect URI, then either redirects to the registered callback with a short-lived code or returns the denial. Every redirectable callback response also includes the canonical OAuth issuer as its RFC 9207 `iss` query parameter. Every client is public, so S256 PKCE is mandatory. A client id may be one created through Dynamic Client Registration or a public HTTPS Client ID Metadata Document that passes the server validation policy. The required parameters below describe the initial client request. Subsequent browser hops use only the opaque server-issued `flow_id`; they must not replay or combine a second authorization request. The request URI is capped at 16 KiB before any OAuth parameter is parsed or browser handoff is stored. Because the one-tab handoff is signed-browser state, the combined UTF-8 byte length of the persisted authorization parameter values is additionally capped at 1,024 bytes; the per-field limits below do not increase that aggregate budget. An optional UI locale is canonicalized to `pt_BR`, `en` or `es` and is retained by the signed browser handoff across sign-in and consent; later hops cannot replace it.","parameters":[{"name":"flow_id","in":"query","required":false,"description":"Opaque, short-lived browser flow handle. Omit it on the initial client authorization request; every server-directed return to this endpoint requires it and rejects a missing, expired or mismatched value locally.","schema":{"type":"string","maxLength":2048},"example":"6e5991d5df9845b8a9d95f7cbec5c8a4"},{"name":"client_id","in":"query","required":true,"description":"Registered public client id or HTTPS Client ID Metadata Document URL.","schema":{"type":"string","maxLength":2048},"example":"lFzHUuO95lsS9_nxtwLHCoSDFn_2bYgPkoBqr4GsK3E"},{"name":"response_type","in":"query","required":true,"description":"Only the authorization-code response type is supported.","schema":{"type":"string","enum":["code"],"maxLength":32},"example":"code"},{"name":"redirect_uri","in":"query","required":true,"description":"Exact registered redirect URI. It must be byte-for-byte equal during the code exchange.","schema":{"type":"string","format":"uri","maxLength":2048},"example":"http://127.0.0.1:8787/oauth/callback"},{"name":"scope","in":"query","required":false,"description":"Space-delimited requested scopes. Omitted defaults to mcp:read; mcp:write requires mcp:read.","schema":{"type":"string","maxLength":256},"example":"mcp:read"},{"name":"state","in":"query","required":false,"description":"Opaque CSRF correlation value returned unchanged to the redirect URI. It participates in the 1,024-byte total browser-handoff budget.","schema":{"type":"string","maxLength":2048},"example":"client-state-9f7a"},{"name":"code_challenge","in":"query","required":true,"description":"Base64url SHA-256 PKCE challenge derived from the client code verifier.","schema":{"type":"string","minLength":43,"maxLength":128,"pattern":"^[A-Za-z0-9_-]+$"},"example":"E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM"},{"name":"code_challenge_method","in":"query","required":true,"description":"Only S256 PKCE is supported.","schema":{"type":"string","enum":["S256"]},"example":"S256"},{"name":"resource","in":"query","required":true,"description":"Exact OAuth MCP resource URL from Protected Resource Metadata; templates, a different account/profile, query strings and fragments are refused.","schema":{"type":"string","format":"uri","maxLength":2048},"example":"https://app.example.com/api/v1/accounts/31/mcp/oauth/c/a1b2c3d4e5f6g7h8i9j0"},{"name":"response_mode","in":"query","required":false,"description":"Optional response mode. Omit it or use query; no fragment response mode is supported.","schema":{"type":"string","enum":["query"],"maxLength":32},"example":"query"},{"name":"locale","in":"query","required":false,"description":"Optional consent-screen locale. Only pt_BR, en and es are retained; equivalent pt-BR and pt normalize to pt_BR, while another value falls back to the installation default.","schema":{"type":"string","enum":["pt_BR","en","es"],"maxLength":16},"example":"pt_BR"}],"responses":{"200":{"description":"Interactive HTML consent page after fresh browser authentication.","headers":{"Cache-Control":{"description":"Browser authorization pages must not be stored by an intermediary.","schema":{"type":"string","enum":["no-store"],"example":"no-store"}}},"content":{"text/html":{"schema":{"type":"string","description":"HTML document that identifies the client, authority plane, requested scopes and redirect URI.","example":"\u003c!doctype html\u003e\u003ctitle\u003eAuthorize MCP connection\u003c/title\u003e"}}}},"302":{"description":"Redirect to the temporary OAuth sign-in page with the server-issued opaque flow_id.","headers":{"Location":{"description":"Temporary sign-in URL with the server-issued flow_id.","schema":{"type":"string","format":"uri-reference","example":"/oauth/mcp/session?flow_id=6e5991d5df9845b8a9d95f7cbec5c8a4"}},"Cache-Control":{"description":"Browser authorization redirects must not be stored by an intermediary.","schema":{"type":"string","enum":["no-store"],"example":"no-store"}}}},"400":{"description":"Invalid initial authorization request, a combined authorization-parameter value length above 1,024 bytes, or a missing, expired or mismatched browser flow handle. The error is local: no consent decision or client callback is performed.","headers":{"Cache-Control":{"description":"Browser authorization errors must not be stored by an intermediary.","schema":{"type":"string","enum":["no-store"],"example":"no-store"}}},"content":{"text/html":{"schema":{"type":"string","description":"HTML error page without client-metadata network or topology details.","example":"\u003c!doctype html\u003e\u003ctitle\u003eAuthorization request could not be completed\u003c/title\u003e"}}}},"404":{"description":"Native MCP OAuth is disabled or the requested authority plane is unavailable."},"414":{"description":"The OAuth request URI exceeds 16 KiB and is rejected before a browser handoff or OAuth parameters are processed.","headers":{"Cache-Control":{"description":"OAuth transport errors must not be stored by an intermediary.","schema":{"type":"string","enum":["no-store"],"example":"no-store"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/mcp_oauth_transport_error"},"example":{"error":"invalid_request","error_description":"The OAuth request URI exceeds the supported size."}}}}}},"post":{"tags":["Mcp"],"operationId":"decide-mcp-oauth-authorization","summary":"Approve, deny or cancel a native MCP OAuth authorization request","security":[],"description":"Submits the decision from the OAuth consent page. The original authorization parameters and fresh subject are held only in the short-lived browser handoff; callers must not resend them in this form. Approving creates a code bound to the exact resource, client, issuer, scopes and S256 challenge. A cancellation clears the browser state and returns `access_denied` only to the already-validated pending redirect URI; it never accepts a callback URL from the form. The opaque `flow_id` must match this browser tab; a missing, expired or mismatched value stops locally without a consent decision or callback. The form must use a fixed decimal Content-Length no greater than 16 KiB; missing, malformed or chunked bodies are rejected before parameters are parsed.","parameters":[{"$ref":"#/components/parameters/mcp_oauth_content_length"}],"requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","required":["flow_id","decision"],"additionalProperties":false,"properties":{"flow_id":{"type":"string","description":"Opaque, short-lived browser flow handle issued by the initial authorization request.","example":"6e5991d5df9845b8a9d95f7cbec5c8a4"},"authenticity_token":{"type":"string","description":"Browser-only Rails CSRF proof rendered by the consent page. An OAuth client must not construct or submit this field itself.","example":"csrf-token-rendered-by-browser"},"decision":{"type":"string","enum":["approve","deny","cancel"],"description":"Explicit consent decision from the human; cancel clears the browser flow and emits access_denied only to its registered pending callback.","example":"approve"}}},"example":{"flow_id":"6e5991d5df9845b8a9d95f7cbec5c8a4","decision":"approve"}}}},"responses":{"302":{"description":"Redirect to the exact registered pending callback with an authorization code, OAuth denial, or cancellation access_denied response, plus the canonical RFC 9207 iss parameter.","headers":{"Location":{"description":"Registered redirect URI. Successful responses include code, preserve state when supplied, and every redirectable response includes canonical iss.","schema":{"type":"string","format":"uri","example":"http://127.0.0.1:8787/oauth/callback?code=opaque-code\u0026state=client-state-9f7a\u0026iss=https%3A%2F%2Fapp.example.com%2Foauth%2Fmcp"}},"Cache-Control":{"description":"Browser authorization redirects must not be stored by an intermediary.","schema":{"type":"string","enum":["no-store"],"example":"no-store"}}}},"400":{"description":"Invalid, expired, already-consumed or mismatched browser authorization handoff. The error is local: no consent decision or callback is performed. A missing, malformed or chunked form body is also rejected locally before OAuth parameters are parsed.","headers":{"Cache-Control":{"description":"Browser authorization errors must not be stored by an intermediary.","schema":{"type":"string","enum":["no-store"],"example":"no-store"}}},"content":{"text/html":{"schema":{"type":"string","example":"\u003c!doctype html\u003e\u003ctitle\u003eAuthorization request could not be completed\u003c/title\u003e"}},"application/json":{"schema":{"$ref":"#/components/schemas/mcp_oauth_transport_error"},"example":{"error":"invalid_request","error_description":"The OAuth request cannot be processed."}}}},"413":{"description":"The OAuth form body exceeds 16 KiB and is rejected before OAuth parameters or a consent decision are processed.","headers":{"Cache-Control":{"description":"OAuth transport errors must not be stored by an intermediary.","schema":{"type":"string","enum":["no-store"],"example":"no-store"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/mcp_oauth_transport_error"},"example":{"error":"invalid_request","error_description":"The OAuth request exceeds the supported size."}}}},"414":{"description":"The OAuth request URI exceeds 16 KiB and is rejected before OAuth parameters or a consent decision are processed.","headers":{"Cache-Control":{"description":"OAuth transport errors must not be stored by an intermediary.","schema":{"type":"string","enum":["no-store"],"example":"no-store"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/mcp_oauth_transport_error"},"example":{"error":"invalid_request","error_description":"The OAuth request URI exceeds the supported size."}}}},"404":{"description":"Native MCP OAuth is disabled or the requested authority plane is unavailable."}}}},"/oauth/mcp/session":{"get":{"tags":["Mcp"],"operationId":"show-mcp-oauth-session","summary":"Show the native MCP OAuth sign-in page","security":[],"description":"Shows the short-lived, browser-only sign-in form associated with an authorization request. It does not create a dashboard session or API token. Account resources require a current account member; Super Admin resources require a fresh password-verified Super Admin session (with MFA if enrolled). The server-generated `flow_id` is an opaque one-tab browser handoff: it is required on every sign-in and consent hop and cannot be replaced with authorization parameters from another tab. The request URI is capped at 16 KiB before the browser handoff is loaded.","parameters":[{"name":"flow_id","in":"query","required":true,"description":"Opaque, short-lived browser flow handle issued by the initial authorization request.","schema":{"type":"string"},"example":"6e5991d5df9845b8a9d95f7cbec5c8a4"}],"responses":{"200":{"description":"Interactive HTML sign-in form for the pending OAuth authorization request.","headers":{"Cache-Control":{"description":"Browser authorization pages must not be stored by an intermediary.","schema":{"type":"string","enum":["no-store"],"example":"no-store"}}},"content":{"text/html":{"schema":{"type":"string","description":"HTML form with email, password and optional MFA fields.","example":"\u003c!doctype html\u003e\u003ctitle\u003eSign in to authorize an MCP connection\u003c/title\u003e"}}}},"302":{"description":"A valid unexpired OAuth browser subject already exists, so the browser is redirected to consent.","headers":{"Location":{"description":"Native OAuth authorization page.","schema":{"type":"string","format":"uri-reference","example":"/oauth/mcp/authorize?flow_id=6e5991d5df9845b8a9d95f7cbec5c8a4"}},"Cache-Control":{"description":"Browser authorization redirects must not be stored by an intermediary.","schema":{"type":"string","enum":["no-store"],"example":"no-store"}}}},"400":{"description":"The required browser flow handle is missing, expired, invalid or belongs to another authorization request. No consent or callback is performed.","headers":{"Cache-Control":{"description":"Browser authorization errors must not be stored by an intermediary.","schema":{"type":"string","enum":["no-store"],"example":"no-store"}}},"content":{"text/html":{"schema":{"type":"string","example":"\u003c!doctype html\u003e\u003ctitle\u003eAuthorization request could not be completed\u003c/title\u003e"}}}},"404":{"description":"Native MCP OAuth is disabled or the pending authority plane is unavailable."},"414":{"description":"The OAuth request URI exceeds 16 KiB and is rejected before the browser handoff is loaded.","headers":{"Cache-Control":{"description":"OAuth transport errors must not be stored by an intermediary.","schema":{"type":"string","enum":["no-store"],"example":"no-store"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/mcp_oauth_transport_error"},"example":{"error":"invalid_request","error_description":"The OAuth request URI exceeds the supported size."}}}}}},"post":{"tags":["Mcp"],"operationId":"authenticate-mcp-oauth-session","summary":"Authenticate a browser subject for native MCP OAuth consent","security":[],"description":"Verifies credentials for the pending OAuth request and creates only a short-lived signed browser handoff. Passwords, OTPs, backup codes, authorization codes and bearer tokens are never returned. For a Super Admin resource, the password must be freshly verified. MFA enrollment is optional; enrolled operators must also verify a current factor before consent can continue. The form must carry the opaque `flow_id` issued for this browser tab; a missing, expired or mismatched value stops locally without consent or callback. The form must use a fixed decimal Content-Length no greater than 16 KiB; missing, malformed or chunked bodies are rejected before credentials are parsed.","parameters":[{"$ref":"#/components/parameters/mcp_oauth_content_length"}],"requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","required":["flow_id","email","password"],"additionalProperties":false,"properties":{"flow_id":{"type":"string","description":"Opaque, short-lived browser flow handle issued by the initial authorization request.","example":"6e5991d5df9845b8a9d95f7cbec5c8a4"},"authenticity_token":{"type":"string","description":"Browser-only Rails CSRF proof rendered by the sign-in page. An OAuth client must not construct or submit this field itself.","example":"csrf-token-rendered-by-browser"},"email":{"type":"string","format":"email","description":"Account or Super Admin email address for the requested authority plane.","example":"operator@example.com"},"password":{"type":"string","format":"password","description":"Password for the submitted email address.","example":"sample-password"},"otp_code":{"type":"string","description":"Optional MFA one-time password. Required only when the user enabled MFA, unless a valid backup code is supplied.","example":"123456"},"backup_code":{"type":"string","description":"Optional MFA backup code. Use instead of otp_code when applicable.","example":"AB12-CD34"}}},"example":{"flow_id":"6e5991d5df9845b8a9d95f7cbec5c8a4","email":"operator@example.com","password":"sample-password","otp_code":"123456"}}}},"responses":{"302":{"description":"Credentials satisfied the requested authority boundary; redirect to the consent page.","headers":{"Location":{"description":"Native OAuth authorization page.","schema":{"type":"string","format":"uri-reference","example":"/oauth/mcp/authorize?flow_id=6e5991d5df9845b8a9d95f7cbec5c8a4"}},"Cache-Control":{"description":"Browser authorization redirects must not be stored by an intermediary.","schema":{"type":"string","enum":["no-store"],"example":"no-store"}}}},"422":{"description":"Credentials or required MFA proof were not accepted. The page returns one generic error and does not disclose which field failed.","headers":{"Cache-Control":{"description":"Browser authorization pages must not be stored by an intermediary.","schema":{"type":"string","enum":["no-store"],"example":"no-store"}}},"content":{"text/html":{"schema":{"type":"string","example":"\u003c!doctype html\u003e\u003ctitle\u003eSign in to authorize an MCP connection\u003c/title\u003e"}}}},"400":{"description":"The required browser flow handle is missing, expired, invalid or belongs to another authorization request; or the form body is missing, malformed or chunked. No consent or callback is performed.","headers":{"Cache-Control":{"description":"Browser authorization errors must not be stored by an intermediary.","schema":{"type":"string","enum":["no-store"],"example":"no-store"}}},"content":{"text/html":{"schema":{"type":"string","example":"\u003c!doctype html\u003e\u003ctitle\u003eAuthorization request could not be completed\u003c/title\u003e"}},"application/json":{"schema":{"$ref":"#/components/schemas/mcp_oauth_transport_error"},"example":{"error":"invalid_request","error_description":"The OAuth request cannot be processed."}}}},"413":{"description":"The OAuth sign-in form exceeds 16 KiB and is rejected before credentials or browser state are processed.","headers":{"Cache-Control":{"description":"OAuth transport errors must not be stored by an intermediary.","schema":{"type":"string","enum":["no-store"],"example":"no-store"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/mcp_oauth_transport_error"},"example":{"error":"invalid_request","error_description":"The OAuth request exceeds the supported size."}}}},"414":{"description":"The OAuth request URI exceeds 16 KiB and is rejected before the browser handoff is loaded.","headers":{"Cache-Control":{"description":"OAuth transport errors must not be stored by an intermediary.","schema":{"type":"string","enum":["no-store"],"example":"no-store"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/mcp_oauth_transport_error"},"example":{"error":"invalid_request","error_description":"The OAuth request URI exceeds the supported size."}}}},"404":{"description":"Native MCP OAuth is disabled or the pending authority plane is unavailable."}}}},"/oauth/mcp/token":{"post":{"tags":["Mcp"],"operationId":"exchange-mcp-oauth-token","summary":"Exchange a native MCP OAuth authorization code or refresh token","security":[],"description":"OAuth 2.1 token endpoint for public MCP clients. The client identifies itself with client_id and never sends a client secret. Every code or refresh exchange must carry the exact resource URL that was approved; a code exchange also repeats the redirect URI byte-for-byte and proves the S256 verifier. Access tokens are opaque and short-lived. A rotating refresh token is issued only for an explicit offline_access grant; replay of a revoked refresh token revokes the complete consent family. The source consumption, exactly one durable secret-free `token_issued` or `token_refreshed` audit record, and its successor token commit atomically; unavailable audit storage returns invalid_grant without consuming the source credential. The form must use a fixed decimal Content-Length no greater than 16 KiB; missing, malformed or chunked bodies are rejected before OAuth parameters are parsed.","parameters":[{"$ref":"#/components/parameters/mcp_oauth_content_length"}],"requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"oneOf":[{"title":"Authorization code exchange","type":"object","required":["grant_type","client_id","code","redirect_uri","code_verifier","resource"],"additionalProperties":false,"properties":{"grant_type":{"type":"string","enum":["authorization_code"],"example":"authorization_code"},"client_id":{"type":"string","description":"Registered public client id or validated Client ID Metadata URI.","example":"lFzHUuO95lsS9_nxtwLHCoSDFn_2bYgPkoBqr4GsK3E"},"code":{"type":"string","description":"One-time authorization code returned to the exact registered callback.","example":"opaque-code"},"redirect_uri":{"type":"string","format":"uri","description":"Exact redirect URI used at authorization time.","example":"http://127.0.0.1:8787/oauth/callback"},"code_verifier":{"type":"string","minLength":43,"maxLength":128,"pattern":"^[A-Za-z0-9._~-]+$","description":"Original RFC 7636 high-entropy PKCE verifier for the S256 challenge. A verifier outside this grammar is rejected as invalid_grant.","example":"dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk"},"resource":{"type":"string","format":"uri","description":"Exact OAuth MCP resource URL approved by the human.","example":"https://app.example.com/api/v1/accounts/31/mcp/oauth/c/a1b2c3d4e5f6g7h8i9j0"}}},{"title":"Refresh-token exchange","type":"object","required":["grant_type","client_id","refresh_token","resource"],"additionalProperties":false,"properties":{"grant_type":{"type":"string","enum":["refresh_token"],"example":"refresh_token"},"client_id":{"type":"string","description":"Same public client that received the refresh token.","example":"lFzHUuO95lsS9_nxtwLHCoSDFn_2bYgPkoBqr4GsK3E"},"refresh_token":{"type":"string","description":"Current rotating refresh token. Send it only to this exact token endpoint.","example":"sample-refresh-token"},"resource":{"type":"string","format":"uri","description":"Exact OAuth MCP resource URL approved by the human.","example":"https://app.example.com/api/v1/accounts/31/mcp/oauth/c/a1b2c3d4e5f6g7h8i9j0"}}}]},"examples":{"authorization_code":{"value":{"grant_type":"authorization_code","client_id":"lFzHUuO95lsS9_nxtwLHCoSDFn_2bYgPkoBqr4GsK3E","code":"opaque-code","redirect_uri":"http://127.0.0.1:8787/oauth/callback","code_verifier":"dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk","resource":"https://app.example.com/api/v1/accounts/31/mcp/oauth/c/a1b2c3d4e5f6g7h8i9j0"}},"refresh_token":{"value":{"grant_type":"refresh_token","client_id":"lFzHUuO95lsS9_nxtwLHCoSDFn_2bYgPkoBqr4GsK3E","refresh_token":"sample-refresh-token","resource":"https://app.example.com/api/v1/accounts/31/mcp/oauth/c/a1b2c3d4e5f6g7h8i9j0"}}}}}},"responses":{"200":{"description":"OAuth bearer response. The refresh_token field is returned only for an approved offline_access grant.","headers":{"Cache-Control":{"description":"Token responses must not be stored by an intermediary.","schema":{"type":"string","enum":["no-store"],"example":"no-store"}},"Pragma":{"description":"Legacy cache-control directive required alongside Cache-Control for OAuth token responses.","schema":{"type":"string","enum":["no-cache"],"example":"no-cache"}}},"content":{"application/json":{"schema":{"type":"object","required":["access_token","token_type","expires_in","scope"],"additionalProperties":false,"properties":{"access_token":{"type":"string","description":"Opaque bearer token for the exact approved MCP OAuth resource.","example":"sample-access-token"},"token_type":{"type":"string","enum":["Bearer"],"description":"OAuth bearer token type.","example":"Bearer"},"expires_in":{"type":"integer","minimum":1,"description":"Access-token lifetime in seconds. The native server currently issues a 15-minute token.","example":900},"refresh_token":{"type":"string","description":"Opaque rotating refresh token, present only when offline_access was approved.","example":"sample-refresh-token"},"scope":{"type":"string","description":"Space-delimited scopes actually granted for the exact resource.","example":"mcp:read"}}},"example":{"access_token":"sample-access-token","token_type":"Bearer","expires_in":900,"scope":"mcp:read","refresh_token":"sample-refresh-token"}}}},"400":{"description":"OAuth request failed. invalid_request also covers a missing, malformed or chunked body. invalid_target means the exact MCP resource is unavailable or does not match the submitted credential; invalid_grant includes a consumed code, redirect mismatch, PKCE failure, revoked refresh token or refresh replay.","headers":{"Cache-Control":{"description":"Error responses must not be stored by an intermediary.","schema":{"type":"string","enum":["no-store"],"example":"no-store"}},"Pragma":{"description":"Legacy cache-control directive required alongside Cache-Control for OAuth token responses.","schema":{"type":"string","enum":["no-cache"],"example":"no-cache"}}},"content":{"application/json":{"schema":{"type":"object","required":["error","error_description"],"additionalProperties":false,"properties":{"error":{"type":"string","enum":["invalid_request","invalid_client","invalid_grant","invalid_scope","invalid_target","unsupported_grant_type"],"description":"Stable OAuth error code.","example":"invalid_target"},"error_description":{"type":"string","description":"Safe client-facing error description. It never contains issuer, DNS, account or credential topology detail.","example":"The requested MCP resource is unavailable."}}},"example":{"error":"invalid_target","error_description":"The requested MCP resource is unavailable."}}}},"413":{"description":"The OAuth form body exceeds 16 KiB and is rejected before token, refresh or client parameters are processed.","headers":{"Cache-Control":{"description":"Error responses must not be stored by an intermediary.","schema":{"type":"string","enum":["no-store"],"example":"no-store"}},"Pragma":{"description":"Legacy cache-control directive required alongside Cache-Control for OAuth token responses.","schema":{"type":"string","enum":["no-cache"],"example":"no-cache"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/mcp_oauth_transport_error"},"example":{"error":"invalid_request","error_description":"The OAuth request exceeds the supported size."}}}},"414":{"description":"The OAuth request URI exceeds 16 KiB and is rejected before token parameters are processed.","headers":{"Cache-Control":{"description":"Error responses must not be stored by an intermediary.","schema":{"type":"string","enum":["no-store"],"example":"no-store"}},"Pragma":{"description":"Legacy cache-control directive required alongside Cache-Control for OAuth token responses.","schema":{"type":"string","enum":["no-cache"],"example":"no-cache"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/mcp_oauth_transport_error"},"example":{"error":"invalid_request","error_description":"The OAuth request URI exceeds the supported size."}}}},"404":{"description":"Native MCP OAuth is disabled or the submitted resource authority plane is unavailable.","headers":{"Cache-Control":{"description":"Token responses must not be stored by an intermediary.","schema":{"type":"string","enum":["no-store"],"example":"no-store"}},"Pragma":{"description":"Legacy cache-control directive required alongside Cache-Control for OAuth token responses.","schema":{"type":"string","enum":["no-cache"],"example":"no-cache"}}}}}}},"/oauth/mcp/revoke":{"post":{"tags":["Mcp"],"operationId":"revoke-mcp-oauth-token","summary":"Revoke a native MCP OAuth token and its consent family","security":[],"description":"OAuth token revocation endpoint for the public client that owns the token. A valid request revokes the durable authorization decision and all related codes, access tokens and refresh tokens for that decision. Unknown tokens still receive the RFC-compatible success response; another client cannot revoke a token it did not receive. Static profile secrets and Super Admin static operator credentials are not OAuth tokens and cannot be revoked here. The form must use a fixed decimal Content-Length no greater than 16 KiB; missing, malformed or chunked bodies are rejected before token parameters are parsed.","parameters":[{"$ref":"#/components/parameters/mcp_oauth_content_length"}],"requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","required":["client_id","token"],"additionalProperties":false,"properties":{"client_id":{"type":"string","description":"Public client id that originally received the token.","example":"lFzHUuO95lsS9_nxtwLHCoSDFn_2bYgPkoBqr4GsK3E"},"token":{"type":"string","description":"Access token or refresh token to revoke.","example":"sample-token"},"token_type_hint":{"type":"string","enum":["access_token","refresh_token"],"description":"Optional token type hint. It does not alter token ownership checks.","example":"refresh_token"}}},"example":{"client_id":"lFzHUuO95lsS9_nxtwLHCoSDFn_2bYgPkoBqr4GsK3E","token":"sample-token","token_type_hint":"refresh_token"}}}},"responses":{"200":{"description":"Revocation request accepted. The response is the same for an already-revoked or unknown token to avoid a token-validity oracle.","headers":{"Cache-Control":{"description":"Revocation responses must not be stored by an intermediary.","schema":{"type":"string","enum":["no-store"],"example":"no-store"}},"Pragma":{"description":"Legacy cache-control directive paired with Cache-Control for this sensitive OAuth response.","schema":{"type":"string","enum":["no-cache"],"example":"no-cache"}}},"content":{"application/json":{"schema":{"type":"object","maxProperties":0,"additionalProperties":false,"description":"RFC 7009 success response body.","example":{}},"example":{}}}},"403":{"description":"The submitted public client is absent, invalid or does not own the supplied token.","headers":{"Cache-Control":{"description":"Revocation responses must not be stored by an intermediary.","schema":{"type":"string","enum":["no-store"],"example":"no-store"}},"Pragma":{"description":"Legacy cache-control directive paired with Cache-Control for this sensitive OAuth response.","schema":{"type":"string","enum":["no-cache"],"example":"no-cache"}}},"content":{"application/json":{"schema":{"type":"object","required":["error","error_description"],"additionalProperties":false,"properties":{"error":{"type":"string","enum":["unauthorized_client"],"example":"unauthorized_client"},"error_description":{"type":"string","description":"Safe OAuth client error description.","example":"The client is not authorized to revoke this token."}}},"example":{"error":"unauthorized_client","error_description":"The client is not authorized to revoke this token."}}}},"400":{"description":"The OAuth revocation form is missing, malformed or chunked and was rejected before token parameters were parsed.","headers":{"Cache-Control":{"description":"Revocation responses must not be stored by an intermediary.","schema":{"type":"string","enum":["no-store"],"example":"no-store"}},"Pragma":{"description":"Legacy cache-control directive paired with Cache-Control for this sensitive OAuth response.","schema":{"type":"string","enum":["no-cache"],"example":"no-cache"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/mcp_oauth_transport_error"},"example":{"error":"invalid_request","error_description":"The OAuth request cannot be processed."}}}},"413":{"description":"The OAuth revocation form exceeds 16 KiB and is rejected before token parameters are processed.","headers":{"Cache-Control":{"description":"Revocation responses must not be stored by an intermediary.","schema":{"type":"string","enum":["no-store"],"example":"no-store"}},"Pragma":{"description":"Legacy cache-control directive paired with Cache-Control for this sensitive OAuth response.","schema":{"type":"string","enum":["no-cache"],"example":"no-cache"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/mcp_oauth_transport_error"},"example":{"error":"invalid_request","error_description":"The OAuth request exceeds the supported size."}}}},"414":{"description":"The OAuth request URI exceeds 16 KiB and is rejected before token parameters are processed.","headers":{"Cache-Control":{"description":"Revocation responses must not be stored by an intermediary.","schema":{"type":"string","enum":["no-store"],"example":"no-store"}},"Pragma":{"description":"Legacy cache-control directive paired with Cache-Control for this sensitive OAuth response.","schema":{"type":"string","enum":["no-cache"],"example":"no-cache"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/mcp_oauth_transport_error"},"example":{"error":"invalid_request","error_description":"The OAuth request URI exceeds the supported size."}}}},"404":{"description":"Native MCP OAuth is disabled.","headers":{"Cache-Control":{"description":"Revocation responses must not be stored by an intermediary.","schema":{"type":"string","enum":["no-store"],"example":"no-store"}},"Pragma":{"description":"Legacy cache-control directive paired with Cache-Control for this sensitive OAuth response.","schema":{"type":"string","enum":["no-cache"],"example":"no-cache"}}}}}}},"/oauth/mcp/register":{"post":{"tags":["Mcp"],"operationId":"register-mcp-oauth-client","summary":"Register a public native MCP OAuth client","security":[],"description":"RFC 7591 Dynamic Client Registration for public MCP clients. This endpoint is available only when the installation operator has enabled the separate MCP OAuth Dynamic Client Registration gate; otherwise it returns 404 and is omitted from authorization-server discovery. The request is JSON-only and accepts only the listed public metadata. The server generates an opaque client_id and never issues a client secret, registration-management token, plane binding or resource binding. A client still supplies the exact MCP OAuth resource URL when it starts authorization. Unknown or sensitive metadata is rejected rather than stored. It accepts one fixed-length JSON body only: `Content-Length` is required, must match the received body and may not exceed 16 KiB. Chunked (`Transfer-Encoding`) requests are rejected before registration so an unbounded client body never reaches the metadata validator.","parameters":[{"name":"Content-Length","in":"header","required":true,"description":"Exact decimal byte length of the JSON body. The server rejects a missing, malformed, mismatched or value greater than 16 KiB.","schema":{"type":"integer","minimum":0,"maximum":16384},"example":243}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["redirect_uris"],"additionalProperties":false,"properties":{"client_name":{"type":"string","minLength":1,"maxLength":200,"description":"Optional printable display name shown on the consent page.","example":"Support MCP Desktop"},"application_type":{"type":"string","enum":["web","native"],"description":"Optional public OAuth client form. It is recorded only for compatibility and never changes the public-client security model.","example":"web"},"redirect_uris":{"type":"array","minItems":1,"maxItems":16,"uniqueItems":true,"description":"Registered callback URIs. Each must be public HTTPS or an approved HTTP loopback callback; fragments and embedded credentials are refused.","items":{"type":"string","format":"uri","maxLength":2048,"example":"http://127.0.0.1:8787/oauth/callback"},"example":["http://127.0.0.1:8787/oauth/callback"]},"response_types":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"string","enum":["code"],"example":"code"},"default":["code"],"description":"Optional; when present it must be exactly [code].","example":["code"]},"grant_types":{"type":"array","minItems":1,"maxItems":2,"uniqueItems":true,"items":{"type":"string","enum":["authorization_code","refresh_token"],"example":"authorization_code"},"default":["authorization_code"],"description":"Optional; must include authorization_code and may additionally include refresh_token.","example":["authorization_code","refresh_token"]},"token_endpoint_auth_method":{"type":"string","enum":["none"],"default":"none","description":"Optional; public clients use none and do not receive a secret.","example":"none"},"scope":{"type":"string","maxLength":256,"description":"Optional requested scope string. Omitted defaults to mcp:read; mcp:write requires mcp:read.","example":"mcp:read"}}},"example":{"client_name":"Support MCP Desktop","application_type":"native","redirect_uris":["http://127.0.0.1:8787/oauth/callback"],"response_types":["code"],"grant_types":["authorization_code","refresh_token"],"token_endpoint_auth_method":"none","scope":"mcp:read offline_access"}}}},"responses":{"201":{"description":"Generated public-client registration. No client secret or privileged resource binding is returned.","headers":{"Cache-Control":{"description":"Registration responses must not be stored by an intermediary.","schema":{"type":"string","enum":["no-store"],"example":"no-store"}}},"content":{"application/json":{"schema":{"type":"object","required":["client_id","client_id_issued_at","redirect_uris","response_types","grant_types","token_endpoint_auth_method","scope"],"additionalProperties":false,"properties":{"client_id":{"type":"string","description":"Server-generated opaque public client identifier.","example":"lFzHUuO95lsS9_nxtwLHCoSDFn_2bYgPkoBqr4GsK3E"},"client_id_issued_at":{"type":"integer","format":"int64","description":"Unix timestamp when the public client identifier was issued.","example":1754377200},"client_name":{"type":"string","description":"Display name when one was supplied at registration.","example":"Support MCP Desktop"},"application_type":{"type":"string","enum":["web","native"],"description":"Public OAuth client form when one was supplied at registration.","example":"native"},"redirect_uris":{"type":"array","minItems":1,"maxItems":16,"items":{"type":"string","format":"uri","example":"http://127.0.0.1:8787/oauth/callback"},"example":["http://127.0.0.1:8787/oauth/callback"]},"response_types":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"string","enum":["code"],"example":"code"},"example":["code"]},"grant_types":{"type":"array","minItems":1,"maxItems":2,"items":{"type":"string","enum":["authorization_code","refresh_token"],"example":"authorization_code"},"example":["authorization_code","refresh_token"]},"token_endpoint_auth_method":{"type":"string","enum":["none"],"example":"none"},"scope":{"type":"string","description":"Normalized requested scopes for this public client.","example":"mcp:read offline_access"}}},"example":{"client_id":"lFzHUuO95lsS9_nxtwLHCoSDFn_2bYgPkoBqr4GsK3E","client_id_issued_at":1754377200,"client_name":"Support MCP Desktop","application_type":"native","redirect_uris":["http://127.0.0.1:8787/oauth/callback"],"response_types":["code"],"grant_types":["authorization_code","refresh_token"],"token_endpoint_auth_method":"none","scope":"mcp:read offline_access"}}}},"400":{"description":"Missing, malformed, mismatched or oversized Content-Length; Transfer-Encoding; invalid, non-JSON, unsafe or unsupported public client metadata. The response intentionally contains no network or validation topology detail.","headers":{"Cache-Control":{"description":"Registration responses must not be stored by an intermediary.","schema":{"type":"string","enum":["no-store"],"example":"no-store"}}},"content":{"application/json":{"schema":{"type":"object","required":["error"],"additionalProperties":false,"properties":{"error":{"type":"string","enum":["invalid_client_metadata"],"example":"invalid_client_metadata"}}},"example":{"error":"invalid_client_metadata"}}}},"503":{"description":"Registration could not allocate a server-generated public client id, or the canonical OAuth issuer is temporarily unavailable. Retry later; no client secret was created.","headers":{"Cache-Control":{"description":"Registration responses must not be stored by an intermediary.","schema":{"type":"string","enum":["no-store"],"example":"no-store"}}},"content":{"application/json":{"schema":{"type":"object","required":["error"],"additionalProperties":false,"properties":{"error":{"type":"string","enum":["server_error"],"example":"server_error"}}},"example":{"error":"server_error"}}}},"404":{"description":"Native MCP OAuth or its separate Dynamic Client Registration gate is disabled.","headers":{"Cache-Control":{"description":"Registration responses must not be stored by an intermediary.","schema":{"type":"string","enum":["no-store"],"example":"no-store"}}}}}}},"/api/v1/accounts/{account_id}/tasks/tasks":{"get":{"tags":["Tasks"],"operationId":"list-tasks","summary":"List tasks","description":"List/filter tasks. Filters status/priority/assignee_id/task_list_id/due_before/due_after/overdue/label/linkable_type+linkable_id/q; sort + pagination.","security":[{"userApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/account_id"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"$ref":"#/components/schemas/task"}},"meta":{"type":"object","properties":{"count":{"type":"number"},"current_page":{"type":"number"},"per_page":{"type":"number"},"has_more":{"type":"boolean"}}}}},"example":{"payload":[{"id":1,"account_id":1,"title":"Sample title","description":"A short description.","status":"backlog","priority":"none","start_on":"2026-01-15","due_at":"2026-01-15T10:30:00.000Z","completed_at":"2026-01-15T10:30:00.000Z","position":1,"task_list_id":1,"parent_task_id":1,"recurrence":{},"custom_attributes":{},"comments_count":5,"attachments_count":5,"attachments":[{"id":1,"filename":"sample filename","byte_size":12.5,"content_type":"sample content type","url":"https://example.com/resource","created_at":"2026-01-15T10:30:00.000Z","media_deleted":true}],"subtasks_count":5,"overdue":true,"labels":["sample label"],"assignees":[{"id":1,"name":"Sample Name","thumbnail":"sample thumbnail"}],"archived":true,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}],"meta":{"count":5,"current_page":12.5,"per_page":12.5,"has_more":true}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"post":{"tags":["Tasks"],"operationId":"create-task","summary":"Create a task","security":[{"userApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/account_id"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"task":{"type":"object","properties":{"title":{"type":"string"},"description":{"type":"string"},"status":{"type":"string","enum":["backlog","todo","in_progress","in_review","done","cancelled"],"description":"The workflow status of the task."},"priority":{"type":"string","enum":["none","low","medium","high","urgent"],"description":"The priority of the task."},"due_at":{"type":"string","format":"date-time"},"task_list_id":{"type":"number"},"assignee_ids":{"type":"array","items":{"type":"number"}},"label_list":{"type":"array","items":{"type":"string"}},"links":{"type":"array","items":{"type":"object","properties":{"linkable_type":{"type":"string","enum":["Conversation","Contact","Organization","Crm::Item"],"description":"The kind of record a task can be linked to."},"linkable_id":{"type":"number"}}}}},"required":["title"]}}},"example":{"task":{"title":"Sample title","description":"A short description.","status":"backlog","priority":"none","due_at":"2026-01-15T10:30:00.000Z","task_list_id":1,"assignee_ids":[1],"label_list":["sample label list"],"links":[{"linkable_type":"Conversation","linkable_id":1}]}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"$ref":"#/components/schemas/task"}}},"example":{"payload":{"id":1,"account_id":1,"title":"Sample title","description":"A short description.","status":"backlog","priority":"none","start_on":"2026-01-15","due_at":"2026-01-15T10:30:00.000Z","completed_at":"2026-01-15T10:30:00.000Z","position":1,"task_list_id":1,"parent_task_id":1,"recurrence":{},"custom_attributes":{},"comments_count":5,"attachments_count":5,"attachments":[{"id":1,"filename":"sample filename","byte_size":12.5,"content_type":"sample content type","url":"https://example.com/resource","created_at":"2026-01-15T10:30:00.000Z","media_deleted":true}],"subtasks_count":5,"overdue":true,"labels":["sample label"],"assignees":[{"id":1,"name":"Sample Name","thumbnail":"sample thumbnail"}],"archived":true,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}},"description":"Create a task. Submits the request payload to the Tasks resource and returns the result."}},"/api/v1/accounts/{account_id}/tasks/tasks/{id}":{"get":{"tags":["Tasks"],"operationId":"get-task","summary":"Get a task (with subtasks, dependencies, reminders, links, attachments)","security":[{"userApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"id","in":"path","required":true,"schema":{"type":"number"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"$ref":"#/components/schemas/task"}}},"example":{"payload":{"id":1,"account_id":1,"title":"Sample title","description":"A short description.","status":"backlog","priority":"none","start_on":"2026-01-15","due_at":"2026-01-15T10:30:00.000Z","completed_at":"2026-01-15T10:30:00.000Z","position":1,"task_list_id":1,"parent_task_id":1,"recurrence":{},"custom_attributes":{},"comments_count":5,"attachments_count":5,"attachments":[{"id":1,"filename":"sample filename","byte_size":12.5,"content_type":"sample content type","url":"https://example.com/resource","created_at":"2026-01-15T10:30:00.000Z","media_deleted":true}],"subtasks_count":5,"overdue":true,"labels":["sample label"],"assignees":[{"id":1,"name":"Sample Name","thumbnail":"sample thumbnail"}],"archived":true,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}},"description":"Get a task (with subtasks, dependencies, reminders, links, attachments). Returns the requested Tasks resource."},"patch":{"tags":["Tasks"],"operationId":"update-task","summary":"Update a task (status=done stamps completed_at + materializes recurrence + unblocks dependents)","security":[{"userApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"id","in":"path","required":true,"schema":{"type":"number"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"task":{"type":"object","properties":{"title":{"type":"string"},"status":{"type":"string","enum":["backlog","todo","in_progress","in_review","done","cancelled"],"description":"The workflow status of the task."},"priority":{"type":"string","enum":["none","low","medium","high","urgent"],"description":"The priority of the task."},"due_at":{"type":"string","format":"date-time"},"task_list_id":{"type":"number"},"assignee_ids":{"type":"array","items":{"type":"number"}},"label_list":{"type":"array","items":{"type":"string"}}}}}},"example":{"task":{"title":"Sample title","status":"backlog","priority":"none","due_at":"2026-01-15T10:30:00.000Z","task_list_id":1,"assignee_ids":[1],"label_list":["sample label list"]}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"$ref":"#/components/schemas/task"}}},"example":{"payload":{"id":1,"account_id":1,"title":"Sample title","description":"A short description.","status":"backlog","priority":"none","start_on":"2026-01-15","due_at":"2026-01-15T10:30:00.000Z","completed_at":"2026-01-15T10:30:00.000Z","position":1,"task_list_id":1,"parent_task_id":1,"recurrence":{},"custom_attributes":{},"comments_count":5,"attachments_count":5,"attachments":[{"id":1,"filename":"sample filename","byte_size":12.5,"content_type":"sample content type","url":"https://example.com/resource","created_at":"2026-01-15T10:30:00.000Z","media_deleted":true}],"subtasks_count":5,"overdue":true,"labels":["sample label"],"assignees":[{"id":1,"name":"Sample Name","thumbnail":"sample thumbnail"}],"archived":true,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}}}},"description":"Update a task (status=done stamps completed_at + materializes recurrence + unblocks dependents). Applies the submitted changes to the Tasks resource."},"delete":{"tags":["Tasks"],"operationId":"delete-task","summary":"Archive a task","security":[{"userApiKey":[]}],"description":"Soft-delete (archive) a task. The task is hidden from the active list/board and can be restored or purged. Dispatches a task-updated event so webhooks and automation react.","parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"id","in":"path","required":true,"schema":{"type":"number"}}],"responses":{"200":{"description":"Success"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"The task does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"put":{"tags":["Tasks"],"operationId":"auto_put_api_v1_accounts_account_id_tasks_tasks_id","summary":"Update tasks","description":"Updates the task identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"title":{"type":"string"},"description":{"type":"string"},"status":{"type":"string","enum":["backlog","todo","in_progress","in_review","done","cancelled"],"description":"The workflow status of the task."},"priority":{"type":"string","enum":["none","low","medium","high","urgent"],"description":"The priority of the task."},"start_on":{"type":"string"},"due_at":{"type":"string","format":"date-time"},"completed_at":{"type":"string","format":"date-time"},"position":{"type":"integer"},"task_list_id":{"type":"integer"},"team_id":{"type":"integer"},"parent_task_id":{"type":"integer"},"recurrence":{"type":"object","additionalProperties":true,"description":"JSONB recurrence rule: frequency (daily|weekly|monthly|yearly), interval, until, count, days."},"recurrence_parent_id":{"type":"integer"},"created_by_id":{"type":"integer"},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"additional_attributes":{"type":"object","additionalProperties":true,"description":"Channel- and source-specific metadata for this record (e.g. browser info, referer, social profile identifiers). The key set depends on the originating channel."},"comments_count":{"type":"integer"},"attachments_count":{"type":"integer"},"subtasks_count":{"type":"integer"},"checklist_progress":{"type":"object","properties":{"done":{"type":"string"},"total":{"type":"number"}}},"labels":{"type":"array","items":{"type":"string"}},"overdue":{"type":"boolean"},"blocked":{"type":"boolean"},"sla_status":{"type":"string","enum":["active","hit","missed","active_with_misses"],"description":"Outcome of the SLA attached to this record."},"task_list":{"type":"string"},"assignees":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"available_name":{"type":"string"},"thumbnail":{"type":"string"}}}},"links":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"task_id":{"type":"integer"},"linkable_type":{"type":"string","enum":["Conversation","Contact","Crm::Item"],"description":"The kind of record a task can be linked to."},"linkable_id":{"type":"integer"},"created_at":{"type":"string","format":"date-time"},"linkable":{"type":"object","properties":{"type":{"type":"string"},"id":{"type":"integer"},"display_id":{"type":"integer"},"label":{"type":"string"}}}}}},"archived_at":{"type":"string","format":"date-time"},"archived":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}},"example":{"payload":{"id":1,"account_id":1,"title":"Sample title","description":"A short description.","status":"backlog","priority":"none","start_on":"sample start on","due_at":"2026-01-15T10:30:00.000Z","completed_at":"2026-01-15T10:30:00.000Z","position":1,"task_list_id":1,"team_id":1,"parent_task_id":1,"recurrence":{},"recurrence_parent_id":1,"created_by_id":1,"custom_attributes":{},"additional_attributes":{},"comments_count":5,"attachments_count":5,"subtasks_count":5,"checklist_progress":{"done":"sample done","total":149.9},"labels":["sample label"],"overdue":true,"blocked":true,"sla_status":"active","task_list":"sample task list","assignees":[{"id":1,"name":"Sample Name","available_name":"sample available name","thumbnail":"sample thumbnail"}],"links":[{"id":1,"task_id":1,"linkable_type":"Conversation","linkable_id":1,"created_at":"2026-01-15T10:30:00.000Z","linkable":{"type":"sample type","id":1,"display_id":1,"label":"sample label"}}],"archived_at":"2026-01-15T10:30:00.000Z","archived":true,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"task":{"type":"object","properties":{"title":{"type":"string"},"description":{"type":"string"},"status":{"type":"string","enum":["backlog","todo","in_progress","in_review","done","cancelled"],"description":"The workflow status of the task."},"priority":{"type":"string","enum":["none","low","medium","high","urgent"],"description":"The priority of the task."},"start_on":{"type":"string"},"due_at":{"type":"string","format":"date-time"},"task_list_id":{"type":"integer"},"parent_task_id":{"type":"integer"},"team_id":{"type":"integer"},"archived_at":{"type":"string","format":"date-time"},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"additional_attributes":{"type":"object","additionalProperties":true,"description":"Channel- and source-specific metadata for this record (e.g. browser info, referer, social profile identifiers). The key set depends on the originating channel."},"recurrence":{"type":"object","additionalProperties":true,"description":"JSONB recurrence rule: frequency (daily|weekly|monthly|yearly), interval, until, count, days."},"assignee_ids":{"type":"array","items":{"type":"integer"}},"label_list":{"type":"array","items":{"type":"string"}},"links":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Free-form object."}}}}},"required":["task"]},"example":{"task":{"title":"Sample title","description":"A short description.","status":"backlog","priority":"none","start_on":"sample start on","due_at":"2026-01-15T10:30:00.000Z","task_list_id":1,"parent_task_id":1,"team_id":1,"archived_at":"2026-01-15T10:30:00.000Z","custom_attributes":{},"additional_attributes":{},"recurrence":{},"assignee_ids":[1],"label_list":["sample label list"],"links":[{}]}}}}}}},"/api/v1/accounts/{account_id}/tasks/tasks/{id}/complete":{"patch":{"tags":["Tasks"],"operationId":"complete-task","summary":"Mark a task done","security":[{"userApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"id","in":"path","required":true,"schema":{"type":"number"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"$ref":"#/components/schemas/task"}}},"example":{"payload":{"id":1,"account_id":1,"title":"Sample title","description":"A short description.","status":"backlog","priority":"none","start_on":"2026-01-15","due_at":"2026-01-15T10:30:00.000Z","completed_at":"2026-01-15T10:30:00.000Z","position":1,"task_list_id":1,"parent_task_id":1,"recurrence":{},"custom_attributes":{},"comments_count":5,"attachments_count":5,"attachments":[{"id":1,"filename":"sample filename","byte_size":12.5,"content_type":"sample content type","url":"https://example.com/resource","created_at":"2026-01-15T10:30:00.000Z","media_deleted":true}],"subtasks_count":5,"overdue":true,"labels":["sample label"],"assignees":[{"id":1,"name":"Sample Name","thumbnail":"sample thumbnail"}],"archived":true,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}}}},"description":"Mark a task done. Applies the submitted changes to the Complete resource."}},"/api/v1/accounts/{account_id}/tasks/tasks/{task_id}/watchers/{id}":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"task_id","in":"path","required":true,"schema":{"type":"number"},"description":"The numeric ID of the task"},{"name":"id","in":"path","required":true,"schema":{"type":"number"},"description":"The USER id to remove from the watchers (not the watcher row id)"}],"delete":{"tags":["Task Watchers"],"operationId":"delete-task-watcher","summary":"Remove a task watcher","security":[{"userApiKey":[]}],"description":"Stop a user from watching a task. NOTE — the path `id` is the USER id (not the watcher row id). Removing a non-watching user is a no-op (still 200).","responses":{"200":{"description":"Success"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"The task does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/tasks/tasks/{task_id}/watchers":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"task_id","in":"path","required":true,"schema":{"type":"number"},"description":"The numeric ID of the task"}],"get":{"tags":["Task Watchers"],"operationId":"list-task-watchers","summary":"List task watchers","security":[{"userApiKey":[]}],"description":"List the watchers on a task (non-assignees who watch receive the task's notifications)","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"$ref":"#/components/schemas/task_watcher"}}}},"example":{"payload":[{"id":1,"task_id":1,"user_id":1,"user":{"id":1,"name":"Sample Name","available_name":"sample available name","thumbnail":"sample thumbnail"},"created_at":"2026-01-15T10:30:00.000Z"}]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"The task does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"post":{"tags":["Task Watchers"],"operationId":"create-task-watcher","summary":"Add a task watcher","security":[{"userApiKey":[]}],"description":"Add a watcher to a task. NOTE — user_id is sent at the TOP LEVEL of the body (no wrapper object) and is optional: omitted, the current user starts watching. Deduped by the unique [task, user] pair (re-adding returns the existing watcher).","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"user_id":{"type":"number","description":"The user to add as watcher (defaults to the current user)"}}},"example":{"user_id":1}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"$ref":"#/components/schemas/task_watcher"}}},"example":{"payload":{"id":1,"task_id":1,"user_id":1,"user":{"id":1,"name":"Sample Name","available_name":"sample available name","thumbnail":"sample thumbnail"},"created_at":"2026-01-15T10:30:00.000Z"}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"The task does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/tasks/tasks/{task_id}/reminders/{id}":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"task_id","in":"path","required":true,"schema":{"type":"number"},"description":"The numeric ID of the task"},{"name":"id","in":"path","required":true,"schema":{"type":"number"},"description":"The numeric ID of the reminder"}],"delete":{"tags":["Task Reminders"],"operationId":"delete-task-reminder","summary":"Delete a task reminder","security":[{"userApiKey":[]}],"description":"Remove a scheduled reminder from a task","responses":{"200":{"description":"Success"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"The task or reminder does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/tasks/tasks/{task_id}/reminders":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"task_id","in":"path","required":true,"schema":{"type":"number"},"description":"The numeric ID of the task"}],"get":{"tags":["Task Reminders"],"operationId":"list-task-reminders","summary":"List task reminders","security":[{"userApiKey":[]}],"description":"List the scheduled reminders on a task (soonest first)","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"$ref":"#/components/schemas/task_reminder"}}}},"example":{"payload":[{"id":1,"task_id":1,"remind_at":"2026-01-15T10:30:00.000Z","channel":"in_app","user_id":1,"sent_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z"}]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"The task does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"post":{"tags":["Task Reminders"],"operationId":"create-task-reminder","summary":"Create a task reminder","security":[{"userApiKey":[]}],"description":"Schedule a reminder on a task. NOTE — the attributes are sent at the TOP LEVEL of the body (no wrapper object). user_id is optional (null reminds the task's assignees). Delivery is idempotent on sent_at via the reminder cron.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"remind_at":{"type":"string","format":"date-time","description":"When to fire the reminder"},"channel":{"type":"string","enum":["in_app","email"],"description":"Delivery channel (defaults to in_app)"},"user_id":{"type":"number","description":"Target user; null reminds the task's assignees"}},"required":["remind_at"]},"example":{"remind_at":"2026-01-15T10:30:00.000Z","channel":"in_app","user_id":1}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"$ref":"#/components/schemas/task_reminder"}}},"example":{"payload":{"id":1,"task_id":1,"remind_at":"2026-01-15T10:30:00.000Z","channel":"in_app","user_id":1,"sent_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z"}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"The task does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/tasks/tasks/{task_id}/links/{id}":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"task_id","in":"path","required":true,"schema":{"type":"number"},"description":"The numeric ID of the task"},{"name":"id","in":"path","required":true,"schema":{"type":"number"},"description":"The numeric ID of the link"}],"delete":{"tags":["Task Links"],"operationId":"delete-task-link","summary":"Delete a task link","security":[{"userApiKey":[]}],"description":"Remove a polymorphic link from a task","responses":{"200":{"description":"Success"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"The task or link does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/tasks/tasks/{task_id}/links":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"task_id","in":"path","required":true,"schema":{"type":"number"},"description":"The numeric ID of the task"}],"get":{"tags":["Task Links"],"operationId":"list-task-links","summary":"List task links","security":[{"userApiKey":[]}],"description":"List the polymorphic links from a task to Conversations/Contacts/CRM items (newest first)","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"$ref":"#/components/schemas/task_link"}}}},"example":{"payload":[{"id":1,"task_id":1,"linkable_type":"Conversation","linkable_id":1,"linkable":{"type":"sample type","id":1,"display_id":1,"label":"sample label"},"created_at":"2026-01-15T10:30:00.000Z"}]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"The task does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"post":{"tags":["Task Links"],"operationId":"create-task-link","summary":"Create a task link","security":[{"userApiKey":[]}],"description":"Link a task to an account-scoped Conversation, Contact, Organization or CRM item (deduped — re-linking the same record returns the existing link). Conversations resolve display_id-first, falling back to the global id. A foreign or unknown record is rejected with 422.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"linkable_type":{"type":"string","enum":["Conversation","Contact","Organization","Crm::Item"],"description":"The linked record type"},"linkable_id":{"type":"number","description":"The linked record ID (Conversation accepts display_id or global id)"}},"required":["linkable_type","linkable_id"]},"example":{"linkable_type":"Conversation","linkable_id":1}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"$ref":"#/components/schemas/task_link"}}},"example":{"payload":{"id":1,"task_id":1,"linkable_type":"Conversation","linkable_id":1,"linkable":{"type":"sample type","id":1,"display_id":1,"label":"sample label"},"created_at":"2026-01-15T10:30:00.000Z"}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"The task does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"422":{"description":"The linkable record is invalid or not in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/tasks/tasks/{task_id}/dependencies/{id}":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"task_id","in":"path","required":true,"schema":{"type":"number"},"description":"The numeric ID of the task"},{"name":"id","in":"path","required":true,"schema":{"type":"number"},"description":"The numeric ID of the dependency edge"}],"delete":{"tags":["Task Dependencies"],"operationId":"delete-task-dependency","summary":"Delete a task dependency","security":[{"userApiKey":[]}],"description":"Delete a dependency edge touching this task (works for blocking and blocked_by rows)","responses":{"200":{"description":"Success"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"The task or dependency does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/tasks/tasks/{task_id}/dependencies":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"task_id","in":"path","required":true,"schema":{"type":"number"},"description":"The numeric ID of the task"}],"get":{"tags":["Task Dependencies"],"operationId":"list-task-dependencies","summary":"List task dependencies","security":[{"userApiKey":[]}],"description":"List the dependency edges touching a task, in both directions — `blocking` (this task blocks others) and `blocked_by` (others block this task).","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"blocking":{"type":"array","items":{"$ref":"#/components/schemas/task_dependency"}},"blocked_by":{"type":"array","items":{"$ref":"#/components/schemas/task_dependency"}}}}}},"example":{"payload":{"blocking":[{"id":1,"task_id":1,"blocks_task_id":1,"blocker":{"id":1,"title":"Sample title","status":"backlog"},"blocks":{"id":1,"title":"Sample title","status":"backlog"},"created_at":"2026-01-15T10:30:00.000Z"}],"blocked_by":[{"id":1,"task_id":1,"blocks_task_id":1,"blocker":{"id":1,"title":"Sample title","status":"backlog"},"blocks":{"id":1,"title":"Sample title","status":"backlog"},"created_at":"2026-01-15T10:30:00.000Z"}]}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"The task does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"post":{"tags":["Task Dependencies"],"operationId":"create-task-dependency","summary":"Create a task dependency","security":[{"userApiKey":[]}],"description":"Create a dependency edge between this task and another account task. By default this task BLOCKS the target; pass direction=blocked_by to make the target block this task. Cycles are rejected with 422.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"blocks_task_id":{"type":"number","description":"The other task in the edge"},"direction":{"type":"string","enum":["blocks","blocked_by"],"description":"blocked_by → the target blocks THIS task; default (blocks) → this task blocks the target"}},"required":["blocks_task_id"]},"example":{"blocks_task_id":1,"direction":"blocks"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"$ref":"#/components/schemas/task_dependency"}}},"example":{"payload":{"id":1,"task_id":1,"blocks_task_id":1,"blocker":{"id":1,"title":"Sample title","status":"backlog"},"blocks":{"id":1,"title":"Sample title","status":"backlog"},"created_at":"2026-01-15T10:30:00.000Z"}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"The task or target task does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"422":{"description":"The dependency would create a cycle","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/tasks/tasks/{task_id}/comments/{id}":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"task_id","in":"path","required":true,"schema":{"type":"number"},"description":"The numeric ID of the task"},{"name":"id","in":"path","required":true,"schema":{"type":"number"},"description":"The numeric ID of the comment"}],"patch":{"tags":["Task Comments"],"operationId":"update-task-comment","summary":"Update a task comment","security":[{"userApiKey":[]}],"description":"Edit a comment on a task","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"comment":{"type":"object","properties":{"content":{"type":"string"}},"required":["content"]}}},"example":{"comment":{"content":"Sample content text."}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"$ref":"#/components/schemas/task_comment"}}},"example":{"payload":{"id":1,"task_id":1,"content":"Sample content text.","user_id":1,"user":{"id":1,"name":"Sample Name","available_name":"sample available name","thumbnail":"sample thumbnail"},"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"The task or comment does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"delete":{"tags":["Task Comments"],"operationId":"delete-task-comment","summary":"Delete a task comment","security":[{"userApiKey":[]}],"description":"Delete a comment from a task","responses":{"200":{"description":"Success"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"The task or comment does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"put":{"tags":["Task Comments"],"operationId":"auto_put_api_v1_accounts_account_id_tasks_tasks_task_id_comments_id","summary":"Update comments","description":"Updates the comment identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"task_id":{"type":"integer"},"content":{"type":"string"},"user_id":{"type":"integer"},"user":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"available_name":{"type":"string"},"thumbnail":{"type":"string"}}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}},"example":{"payload":{"id":1,"task_id":1,"content":"Sample content text.","user_id":1,"user":{"id":1,"name":"Sample Name","available_name":"sample available name","thumbnail":"sample thumbnail"},"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"comment":{"type":"object","properties":{"content":{"type":"string"}}}},"required":["comment"]},"example":{"comment":{"content":"Sample content text."}}}}}}},"/api/v1/accounts/{account_id}/tasks/tasks/{task_id}/comments":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"task_id","in":"path","required":true,"schema":{"type":"number"},"description":"The numeric ID of the task"}],"get":{"tags":["Task Comments"],"operationId":"list-task-comments","summary":"List task comments","security":[{"userApiKey":[]}],"description":"List the comments on a task (paginated, newest first)","parameters":[{"name":"page","in":"query","required":false,"schema":{"type":"number"},"description":"The page number"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"$ref":"#/components/schemas/task_comment"}}}},"example":{"payload":[{"id":1,"task_id":1,"content":"Sample content text.","user_id":1,"user":{"id":1,"name":"Sample Name","available_name":"sample available name","thumbnail":"sample thumbnail"},"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"The task does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"post":{"tags":["Task Comments"],"operationId":"create-task-comment","summary":"Create a task comment","security":[{"userApiKey":[]}],"description":"Add a comment to a task (authored by the current user; dispatches the task-comment-added event)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"comment":{"type":"object","properties":{"content":{"type":"string"}},"required":["content"]}}},"example":{"comment":{"content":"Sample content text."}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"$ref":"#/components/schemas/task_comment"}}},"example":{"payload":{"id":1,"task_id":1,"content":"Sample content text.","user_id":1,"user":{"id":1,"name":"Sample Name","available_name":"sample available name","thumbnail":"sample thumbnail"},"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"The task does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/tasks/tasks/{task_id}/checklist_items/{id}/reposition":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"task_id","in":"path","required":true,"schema":{"type":"number"},"description":"The numeric ID of the task"},{"name":"id","in":"path","required":true,"schema":{"type":"number"},"description":"The numeric ID of the checklist item"}],"patch":{"tags":["Task Checklist"],"operationId":"reposition-task-checklist-item","summary":"Reposition a task checklist item","security":[{"userApiKey":[]}],"description":"Reorder a checklist item within the task's checklist","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"position":{"type":"number","description":"The target position"}},"required":["position"]},"example":{"position":1}}}},"responses":{"200":{"description":"The checklist item was moved to the requested position. Empty body — refetch the checklist to read the new ordering."},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"The task or checklist item does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/tasks/tasks/{task_id}/checklist_items/{id}/toggle":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"task_id","in":"path","required":true,"schema":{"type":"number"},"description":"The numeric ID of the task"},{"name":"id","in":"path","required":true,"schema":{"type":"number"},"description":"The numeric ID of the checklist item"}],"patch":{"tags":["Task Checklist"],"operationId":"toggle-task-checklist-item","summary":"Toggle a task checklist item","security":[{"userApiKey":[]}],"description":"Flip a checklist item's completed state (stamps completed_by with the current user when completing). Returns the bare checklist item, no payload wrapper.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/task_checklist_item"},"example":{"id":1,"account_id":1,"record_type":"Task","record_id":1,"title":"Sample title","completed":true,"completed_at":12.5,"completed_by_id":1,"assignee_id":1,"due_on":"2026-01-15","position":1,"assignee":{"id":1,"account_id":1,"account_user_id":1,"availability_status":"online","auto_offline":true,"confirmed":true,"email":"agent@example.com","available_name":"sample available name","name":"Sample Name","role":"agent","outbound_agent_name_header_policy":"inherit","thumbnail":"sample thumbnail","custom_role_id":1},"created_at":12.5,"updated_at":12.5}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"The task or checklist item does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/tasks/tasks/{task_id}/checklist_items/{id}":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"task_id","in":"path","required":true,"schema":{"type":"number"},"description":"The numeric ID of the task"},{"name":"id","in":"path","required":true,"schema":{"type":"number"},"description":"The numeric ID of the checklist item"}],"patch":{"tags":["Task Checklist"],"operationId":"update-task-checklist-item","summary":"Update a task checklist item","security":[{"userApiKey":[]}],"description":"Edit a checklist item's title/assignee/due date (returns the bare checklist item). Completion goes through the toggle endpoint; ordering through reposition.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"checklist_item":{"type":"object","properties":{"title":{"type":"string"},"assignee_id":{"type":"number"},"due_on":{"type":"string","format":"date"}}}}},"example":{"checklist_item":{"title":"Sample title","assignee_id":1,"due_on":"2026-01-15"}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/task_checklist_item"},"example":{"id":1,"account_id":1,"record_type":"Task","record_id":1,"title":"Sample title","completed":true,"completed_at":12.5,"completed_by_id":1,"assignee_id":1,"due_on":"2026-01-15","position":1,"assignee":{"id":1,"account_id":1,"account_user_id":1,"availability_status":"online","auto_offline":true,"confirmed":true,"email":"agent@example.com","available_name":"sample available name","name":"Sample Name","role":"agent","outbound_agent_name_header_policy":"inherit","thumbnail":"sample thumbnail","custom_role_id":1},"created_at":12.5,"updated_at":12.5}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"The task or checklist item does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"delete":{"tags":["Task Checklist"],"operationId":"delete-task-checklist-item","summary":"Delete a task checklist item","security":[{"userApiKey":[]}],"description":"Delete a checklist item from a task","responses":{"200":{"description":"Success"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"The task or checklist item does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"put":{"tags":["Task Checklist"],"operationId":"auto_put_api_v1_accounts_account_id_tasks_tasks_task_id_checklist_items_id","summary":"Update checklist items","description":"Updates the checklist item identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"record_type":{"type":"string","enum":["Task"],"description":"The polymorphic owner type of the checklist item (a task)."},"record_id":{"type":"integer"},"title":{"type":"string"},"completed":{"type":"string"},"completed_at":{"type":["integer","null"]},"completed_by_id":{"type":"integer"},"assignee_id":{"type":"integer"},"due_on":{"type":"string"},"position":{"type":"integer"},"assignee":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":["integer","null"]},"account_user_id":{"type":["integer","null"]},"availability_status":{"type":"string","enum":["online","offline","busy"],"description":"Realtime availability. Contacts report online/offline (presence-based); agents/users additionally report busy (their configured availability)."},"auto_offline":{"type":"boolean"},"confirmed":{"type":"boolean"},"email":{"type":"string","format":"email"},"provider":{"type":"string","enum":["email","google_oauth2","saml"],"description":"Authentication provider the user signed up through."},"available_name":{"type":"string"},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"name":{"type":"string"},"role":{"type":"string","enum":["agent","administrator"]},"outbound_agent_name_header_policy":{"type":["string","null"]},"thumbnail":{"type":"string"},"custom_role_id":{"type":["integer","null"]},"access_role_id":{"type":["integer","null"]}}},"created_at":{"type":"integer"},"updated_at":{"type":"integer"}}},"example":{"id":1,"account_id":1,"record_type":"Task","record_id":1,"title":"Sample title","completed":"sample completed","completed_at":1,"completed_by_id":1,"assignee_id":1,"due_on":"sample due on","position":1,"assignee":{"id":1,"account_id":1,"account_user_id":1,"availability_status":"online","auto_offline":true,"confirmed":true,"email":"agent@example.com","provider":"email","available_name":"sample available name","custom_attributes":{},"name":"Sample Name","role":"agent","outbound_agent_name_header_policy":"sample outbound agent name header policy","thumbnail":"sample thumbnail","custom_role_id":1,"access_role_id":1},"created_at":1,"updated_at":1}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"checklist_item":{"type":"object","properties":{"title":{"type":"string"},"assignee_id":{"type":"integer"},"due_on":{"type":"string"}}}},"required":["checklist_item"]},"example":{"checklist_item":{"title":"Sample title","assignee_id":1,"due_on":"sample due on"}}}}}}},"/api/v1/accounts/{account_id}/tasks/tasks/{task_id}/checklist_items":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"task_id","in":"path","required":true,"schema":{"type":"number"},"description":"The numeric ID of the task"}],"get":{"tags":["Task Checklist"],"operationId":"list-task-checklist-items","summary":"List task checklist items","security":[{"userApiKey":[]}],"description":"List the checklist items on a task (returned as a bare array, no payload wrapper)","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/task_checklist_item"}},"example":[{"id":1,"account_id":1,"record_type":"Task","record_id":1,"title":"Sample title","completed":true,"completed_at":12.5,"completed_by_id":1,"assignee_id":1,"due_on":"2026-01-15","position":1,"assignee":{"id":1,"account_id":1,"account_user_id":1,"availability_status":"online","auto_offline":true,"confirmed":true,"email":"agent@example.com","available_name":"sample available name","name":"Sample Name","role":"agent","outbound_agent_name_header_policy":"inherit","thumbnail":"sample thumbnail","custom_role_id":1},"created_at":12.5,"updated_at":12.5}]}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"The task does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"post":{"tags":["Task Checklist"],"operationId":"create-task-checklist-item","summary":"Create a task checklist item","security":[{"userApiKey":[]}],"description":"Add a checklist item to a task (returns the bare checklist item, no payload wrapper)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"checklist_item":{"type":"object","properties":{"title":{"type":"string"},"assignee_id":{"type":"number"},"due_on":{"type":"string","format":"date"}},"required":["title"]}}},"example":{"checklist_item":{"title":"Sample title","assignee_id":1,"due_on":"2026-01-15"}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/task_checklist_item"},"example":{"id":1,"account_id":1,"record_type":"Task","record_id":1,"title":"Sample title","completed":true,"completed_at":12.5,"completed_by_id":1,"assignee_id":1,"due_on":"2026-01-15","position":1,"assignee":{"id":1,"account_id":1,"account_user_id":1,"availability_status":"online","auto_offline":true,"confirmed":true,"email":"agent@example.com","available_name":"sample available name","name":"Sample Name","role":"agent","outbound_agent_name_header_policy":"inherit","thumbnail":"sample thumbnail","custom_role_id":1},"created_at":12.5,"updated_at":12.5}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"The task does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/tasks/tasks/{task_id}/attachments/{id}":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"task_id","in":"path","required":true,"schema":{"type":"number"},"description":"The numeric ID of the task"},{"name":"id","in":"path","required":true,"schema":{"type":"number"},"description":"The numeric ID of the attachment"}],"delete":{"tags":["Task Attachments"],"operationId":"delete-task-attachment","summary":"Delete a task attachment","security":[{"userApiKey":[]}],"description":"Delete a file attachment from a task","responses":{"200":{"description":"Success"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"The task or attachment does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/tasks/tasks/{task_id}/attachments":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"task_id","in":"path","required":true,"schema":{"type":"number"},"description":"The numeric ID of the task"}],"get":{"tags":["Task Attachments"],"operationId":"list-task-attachments","summary":"List task attachments","security":[{"userApiKey":[]}],"description":"List the file attachments on a task (payload-wrapped)","parameters":[{"name":"include_deleted","in":"query","required":false,"description":"Include redacted attachment tombstones in the separate deleted_payload array.","schema":{"type":"boolean","default":false}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number"},"filename":{"type":"string"},"byte_size":{"type":"number"},"content_type":{"type":"string"},"url":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"media_deleted":{"type":"boolean","enum":[false]}}}},"deleted_payload":{"type":"array","description":"Redacted tombstones, returned only when include_deleted is true.","items":{"type":"object","properties":{"id":{"type":"number"},"byte_size":{"type":["number","null"]},"created_at":{"type":"string","format":"date-time"},"media_deleted":{"type":"boolean","enum":[true]},"deleted_at":{"type":"string","format":"date-time"}}}}}},"example":{"payload":[{"id":1,"filename":"sample filename","byte_size":12.5,"content_type":"sample content type","url":"https://example.com/resource","created_at":"2026-01-15T10:30:00.000Z","media_deleted":false}],"deleted_payload":[{"id":1,"byte_size":12.5,"created_at":"2026-01-15T10:30:00.000Z","media_deleted":true,"deleted_at":"2026-01-15T10:30:00.000Z"}]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"The task does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"post":{"tags":["Task Attachments"],"operationId":"create-task-attachment","summary":"Upload a task attachment","security":[{"userApiKey":[]}],"description":"Upload a file attachment to a task (Active Storage). Honors the shared MAXIMUM_FILE_UPLOAD_SIZE limit (default 40 MB) and appends an attachment_added row to the task activity timeline.","requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"attachment[file]":{"type":"string","format":"binary","description":"The file to attach"}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"number"},"filename":{"type":"string"},"byte_size":{"type":"number"},"content_type":{"type":"string"},"url":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"media_deleted":{"type":"boolean","enum":[false]}}}}},"example":{"payload":{"id":1,"filename":"sample filename","byte_size":12.5,"content_type":"sample content type","url":"https://example.com/resource","created_at":"2026-01-15T10:30:00.000Z","media_deleted":false}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"The task does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"422":{"description":"The file exceeds the upload size limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/tasks/tasks/bulk_purge":{"parameters":[{"$ref":"#/components/parameters/account_id"}],"post":{"tags":["Tasks"],"operationId":"bulk-purge-tasks","summary":"Bulk purge tasks","security":[{"userApiKey":[]}],"description":"Permanently delete a selection of ARCHIVED tasks and their owned records (same cascade as the single purge). Only ids already in the archived bin are purged. Capped at 500 ids per request.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"task_ids":{"type":"array","items":{"type":"number"},"description":"The archived tasks to purge (max 500)"}},"required":["task_ids"]},"example":{"task_ids":[1]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"purged_ids":{"type":"array","items":{"type":"number"}},"failed_ids":{"type":"array","items":{"type":"number"}}}},"meta":{"type":"object","properties":{"updated":{"type":"number"},"failed":{"type":"number"},"failed_ids":{"type":"array","items":{"type":"number"}}}}}},"example":{"payload":{"purged_ids":[1],"failed_ids":[1]},"meta":{"updated":12.5,"failed":12.5,"failed_ids":[1]}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"422":{"description":"Bulk limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/tasks/tasks/bulk_restore":{"parameters":[{"$ref":"#/components/parameters/account_id"}],"post":{"tags":["Tasks"],"operationId":"bulk-restore-tasks","summary":"Bulk restore tasks","security":[{"userApiKey":[]}],"description":"Un-archive a selection of archived tasks. Best-effort per task; failures are returned in failed_ids. Capped at 500 ids per request.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"task_ids":{"type":"array","items":{"type":"number"},"description":"The archived tasks to restore (max 500)"}},"required":["task_ids"]},"example":{"task_ids":[1]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"restored_ids":{"type":"array","items":{"type":"number"}},"failed_ids":{"type":"array","items":{"type":"number"}}}}}},"example":{"payload":{"restored_ids":[1],"failed_ids":[1]}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"422":{"description":"Bulk limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/tasks/tasks/bulk_destroy":{"parameters":[{"$ref":"#/components/parameters/account_id"}],"post":{"tags":["Tasks"],"operationId":"bulk-archive-tasks","summary":"Bulk archive tasks","security":[{"userApiKey":[]}],"description":"Soft-delete (archive) a selection of tasks. Best-effort per task; failures are returned in failed_ids. Capped at 500 ids per request.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"task_ids":{"type":"array","items":{"type":"number"},"description":"The tasks to archive (max 500)"}},"required":["task_ids"]},"example":{"task_ids":[1]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"destroyed_ids":{"type":"array","items":{"type":"number"}},"failed_ids":{"type":"array","items":{"type":"number"}}}}}},"example":{"payload":{"destroyed_ids":[1],"failed_ids":[1]}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"422":{"description":"Bulk limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/tasks/tasks/bulk_complete":{"parameters":[{"$ref":"#/components/parameters/account_id"}],"patch":{"tags":["Tasks"],"operationId":"bulk-complete-tasks","summary":"Bulk complete tasks","security":[{"userApiKey":[]}],"description":"Mark a selection of tasks done (stamps completed_at, materializes recurrence and unblocks dependents per task). Best-effort per task; failures are returned in failed_ids. Capped at 500 ids per request.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"task_ids":{"type":"array","items":{"type":"number"},"description":"The tasks to complete (max 500)"}},"required":["task_ids"]},"example":{"task_ids":[1]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"updated":{"type":"array","items":{"$ref":"#/components/schemas/task"}},"failed_ids":{"type":"array","items":{"type":"number"}}}}}},"example":{"payload":{"updated":[{"id":1,"account_id":1,"title":"Sample title","description":"A short description.","status":"backlog","priority":"none","start_on":"2026-01-15","due_at":"2026-01-15T10:30:00.000Z","completed_at":"2026-01-15T10:30:00.000Z","position":1,"task_list_id":1,"parent_task_id":1,"recurrence":{},"custom_attributes":{},"comments_count":5,"attachments_count":5,"attachments":[{"id":1,"filename":"sample filename","byte_size":12.5,"content_type":"sample content type","url":"https://example.com/resource","created_at":"2026-01-15T10:30:00.000Z","media_deleted":true}],"subtasks_count":5,"overdue":true,"labels":["sample label"],"assignees":[{"id":1,"name":"Sample Name","thumbnail":"sample thumbnail"}],"archived":true,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}],"failed_ids":[1]}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"422":{"description":"Bulk limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/tasks/tasks/bulk_update":{"parameters":[{"$ref":"#/components/parameters/account_id"}],"patch":{"tags":["Tasks"],"operationId":"bulk-update-tasks","summary":"Bulk update tasks","security":[{"userApiKey":[]}],"description":"Apply shared fields (status, priority, list, assignees) to a selection of tasks. Best-effort per task; failures are isolated and returned in failed_ids. Capped at 500 ids per request. `task_list_id: null` is the intentional \"remove from list\" signal.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"task_ids":{"type":"array","items":{"type":"number"},"description":"The tasks to update (max 500)"},"fields":{"type":"object","description":"At least one field is required","properties":{"status":{"type":"string","enum":["backlog","todo","in_progress","in_review","done","cancelled"],"description":"The workflow status of the task."},"priority":{"type":"string","enum":["none","low","medium","high","urgent"],"description":"The priority of the task."},"task_list_id":{"type":["number","null"],"description":"Destination list (null removes the tasks from their list)"},"assignee_ids":{"type":"array","items":{"type":"number"}}}}},"required":["task_ids","fields"]},"example":{"task_ids":[1],"fields":{"status":"backlog","priority":"none","task_list_id":1,"assignee_ids":[1]}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"updated":{"type":"array","items":{"$ref":"#/components/schemas/task"}},"failed_ids":{"type":"array","items":{"type":"number"}}}}}},"example":{"payload":{"updated":[{"id":1,"account_id":1,"title":"Sample title","description":"A short description.","status":"backlog","priority":"none","start_on":"2026-01-15","due_at":"2026-01-15T10:30:00.000Z","completed_at":"2026-01-15T10:30:00.000Z","position":1,"task_list_id":1,"parent_task_id":1,"recurrence":{},"custom_attributes":{},"comments_count":5,"attachments_count":5,"attachments":[{"id":1,"filename":"sample filename","byte_size":12.5,"content_type":"sample content type","url":"https://example.com/resource","created_at":"2026-01-15T10:30:00.000Z","media_deleted":true}],"subtasks_count":5,"overdue":true,"labels":["sample label"],"assignees":[{"id":1,"name":"Sample Name","thumbnail":"sample thumbnail"}],"archived":true,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}],"failed_ids":[1]}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"422":{"description":"No fields provided or bulk limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/tasks/tasks/{id}/events":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"id","in":"path","required":true,"schema":{"type":"number"},"description":"The numeric ID of the task"}],"get":{"tags":["Tasks"],"operationId":"list-task-events","summary":"List task events (activity timeline)","security":[{"userApiKey":[]}],"description":"List the append-only activity history of a task (paginated, newest first)","parameters":[{"name":"page","in":"query","required":false,"schema":{"type":"number"},"description":"The page number"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"$ref":"#/components/schemas/task_event"}},"meta":{"type":"object","properties":{"count":{"type":"number"},"current_page":{"type":"number"},"total_pages":{"type":"number"},"has_more":{"type":"boolean"}}}}},"example":{"payload":[{"id":1,"task_id":1,"event_type":"created","user_id":1,"user":{"id":1,"name":"Sample Name"},"metadata":{},"created_at":"2026-01-15T10:30:00.000Z"}],"meta":{"count":5,"current_page":12.5,"total_pages":12.5,"has_more":true}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"The task does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/tasks/tasks/{id}/reposition":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"id","in":"path","required":true,"schema":{"type":"number"},"description":"The numeric ID of the task"}],"patch":{"tags":["Tasks"],"operationId":"reposition-task","summary":"Reposition a task (board drag)","security":[{"userApiKey":[]}],"description":"Reorder a task within its group, optionally relocating it to another status column and/or list first (relocations dispatch task-updated events; a same-column reorder is event-free).","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"position":{"type":"number","description":"The target position within the destination group"},"status":{"type":"string","enum":["backlog","todo","in_progress","in_review","done","cancelled"],"description":"Optional destination status column"},"task_list_id":{"type":["number","null"],"description":"Optional destination list (null detaches the task from its list)"}}},"example":{"position":1,"status":"backlog","task_list_id":1}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"$ref":"#/components/schemas/task"}}},"example":{"payload":{"id":1,"account_id":1,"title":"Sample title","description":"A short description.","status":"backlog","priority":"none","start_on":"2026-01-15","due_at":"2026-01-15T10:30:00.000Z","completed_at":"2026-01-15T10:30:00.000Z","position":1,"task_list_id":1,"parent_task_id":1,"recurrence":{},"custom_attributes":{},"comments_count":5,"attachments_count":5,"attachments":[{"id":1,"filename":"sample filename","byte_size":12.5,"content_type":"sample content type","url":"https://example.com/resource","created_at":"2026-01-15T10:30:00.000Z","media_deleted":true}],"subtasks_count":5,"overdue":true,"labels":["sample label"],"assignees":[{"id":1,"name":"Sample Name","thumbnail":"sample thumbnail"}],"archived":true,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"The task does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/tasks/tasks/{id}/restore":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"id","in":"path","required":true,"schema":{"type":"number"},"description":"The numeric ID of the task"}],"patch":{"tags":["Tasks"],"operationId":"restore-task","summary":"Restore an archived task","security":[{"userApiKey":[]}],"description":"Bring a soft-deleted (archived) task back to the active list/board","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"$ref":"#/components/schemas/task"}}},"example":{"payload":{"id":1,"account_id":1,"title":"Sample title","description":"A short description.","status":"backlog","priority":"none","start_on":"2026-01-15","due_at":"2026-01-15T10:30:00.000Z","completed_at":"2026-01-15T10:30:00.000Z","position":1,"task_list_id":1,"parent_task_id":1,"recurrence":{},"custom_attributes":{},"comments_count":5,"attachments_count":5,"attachments":[{"id":1,"filename":"sample filename","byte_size":12.5,"content_type":"sample content type","url":"https://example.com/resource","created_at":"2026-01-15T10:30:00.000Z","media_deleted":true}],"subtasks_count":5,"overdue":true,"labels":["sample label"],"assignees":[{"id":1,"name":"Sample Name","thumbnail":"sample thumbnail"}],"archived":true,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"The task does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/tasks/tasks/{id}/purge":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"id","in":"path","required":true,"schema":{"type":"number"},"description":"The numeric ID of the task"}],"delete":{"tags":["Tasks"],"operationId":"purge-task","summary":"Permanently delete an archived task","security":[{"userApiKey":[]}],"description":"Permanently delete an archived task and everything that belongs to it (assignees, comments, reminders, links, dependencies, events, watchers, applied SLAs, checklist items and attachments). The task must already be archived; subtasks and recurrence occurrences survive as top-level tasks.","responses":{"200":{"description":"Success"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"The task does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"422":{"description":"The task must be archived before it can be purged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/tasks/lists":{"get":{"tags":["Task Lists"],"operationId":"list-task-lists","summary":"List task lists/boards","security":[{"userApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/account_id"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number"},"name":{"type":"string"},"color":{"type":"string"},"position":{"type":"number"},"tasks_count":{"type":"number"}}}}}},"example":{"payload":[{"id":1,"name":"Sample Name","color":"#1F93FF","position":1,"tasks_count":5}]}}}}},"description":"List task lists/boards. Returns Lists data for the current context."},"post":{"tags":["Task Lists"],"operationId":"create-task-list","summary":"Create a task list","security":[{"userApiKey":[]}],"description":"Create a task list/board in the account","parameters":[{"$ref":"#/components/parameters/account_id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"list":{"type":"object","properties":{"name":{"type":"string"},"color":{"type":"string"},"description":{"type":"string"},"position":{"type":"number"}},"required":["name"]}}},"example":{"list":{"name":"Sample Name","color":"#1F93FF","description":"A short description.","position":1}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"$ref":"#/components/schemas/task_list"}}},"example":{"payload":{"id":1,"account_id":1,"name":"Sample Name","color":"#1F93FF","description":"A short description.","position":1,"tasks_count":5,"archived_at":"2026-01-15T10:30:00.000Z","archived":true,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/tasks/lists/{id}/reposition":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"id","in":"path","required":true,"schema":{"type":"number"},"description":"The numeric ID of the task list"}],"patch":{"tags":["Task Lists"],"operationId":"reposition-task-list","summary":"Reposition a task list","security":[{"userApiKey":[]}],"description":"Reorder a task list in the sidebar (pure ordering, no event)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"position":{"type":"number","description":"The target position"}},"required":["position"]},"example":{"position":1}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"$ref":"#/components/schemas/task_list"}}},"example":{"payload":{"id":1,"account_id":1,"name":"Sample Name","color":"#1F93FF","description":"A short description.","position":1,"tasks_count":5,"archived_at":"2026-01-15T10:30:00.000Z","archived":true,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"The list does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/tasks/lists/{id}/restore":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"id","in":"path","required":true,"schema":{"type":"number"},"description":"The numeric ID of the task list"}],"patch":{"tags":["Task Lists"],"operationId":"restore-task-list","summary":"Restore an archived task list","security":[{"userApiKey":[]}],"description":"Bring an archived task list back to the active set (admin-only). Tasks detached at archive time stay list-less — restore brings the LIST back, not its former membership.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"$ref":"#/components/schemas/task_list"}}},"example":{"payload":{"id":1,"account_id":1,"name":"Sample Name","color":"#1F93FF","description":"A short description.","position":1,"tasks_count":5,"archived_at":"2026-01-15T10:30:00.000Z","archived":true,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"The list does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/tasks/lists/{id}/purge":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"id","in":"path","required":true,"schema":{"type":"number"},"description":"The numeric ID of the task list"}],"delete":{"tags":["Task Lists"],"operationId":"purge-task-list","summary":"Permanently delete an archived task list","security":[{"userApiKey":[]}],"description":"Permanently delete an archived task list (admin-only). Remaining tasks are detached (task_list_id set to null) and list-targeted SLA policies widen to \"any list\". The list must already be archived.","responses":{"200":{"description":"Success"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"The list does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"422":{"description":"The list must be archived before it can be purged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/tasks/lists/{id}":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"id","in":"path","required":true,"schema":{"type":"number"},"description":"The numeric ID of the task list"}],"get":{"tags":["Task Lists"],"operationId":"get-task-list","summary":"Get a task list","security":[{"userApiKey":[]}],"description":"Get a single task list/board (kept or archived)","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"$ref":"#/components/schemas/task_list"}}},"example":{"payload":{"id":1,"account_id":1,"name":"Sample Name","color":"#1F93FF","description":"A short description.","position":1,"tasks_count":5,"archived_at":"2026-01-15T10:30:00.000Z","archived":true,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"The list does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"patch":{"tags":["Task Lists"],"operationId":"update-task-list","summary":"Update a task list","security":[{"userApiKey":[]}],"description":"Update a task list/board. Archiving is NOT mass-assignable here — archive via DELETE and un-archive via the restore endpoint.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"list":{"type":"object","properties":{"name":{"type":"string"},"color":{"type":"string"},"description":{"type":"string"},"position":{"type":"number"}}}}},"example":{"list":{"name":"Sample Name","color":"#1F93FF","description":"A short description.","position":1}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"$ref":"#/components/schemas/task_list"}}},"example":{"payload":{"id":1,"account_id":1,"name":"Sample Name","color":"#1F93FF","description":"A short description.","position":1,"tasks_count":5,"archived_at":"2026-01-15T10:30:00.000Z","archived":true,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"The list does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"delete":{"tags":["Task Lists"],"operationId":"delete-task-list","summary":"Archive a task list","security":[{"userApiKey":[]}],"description":"Soft-delete (archive) a task list. Its kept tasks are detached (task_list_id set to null) so they survive list-less; the list can later be restored or purged.","responses":{"200":{"description":"Success"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"The list does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"put":{"tags":["Task Lists"],"operationId":"auto_put_api_v1_accounts_account_id_tasks_lists_id","summary":"Update lists","description":"Updates the list identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"name":{"type":"string"},"color":{"type":"string"},"description":{"type":"string"},"position":{"type":"integer"},"tasks_count":{"type":"integer"},"archived_at":{"type":"string","format":"date-time"},"archived":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}},"example":{"payload":{"id":1,"account_id":1,"name":"Sample Name","color":"#1F93FF","description":"A short description.","position":1,"tasks_count":5,"archived_at":"2026-01-15T10:30:00.000Z","archived":true,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"list":{"type":"object","properties":{"name":{"type":"string"},"color":{"type":"string"},"description":{"type":"string"},"position":{"type":"integer"}}}},"required":["list"]},"example":{"list":{"name":"Sample Name","color":"#1F93FF","description":"A short description.","position":1}}}}}}},"/api/v1/accounts/{account_id}/tasks/reports":{"get":{"tags":["Tasks"],"operationId":"task-reports","summary":"Tasks analytics (by status/priority, completion rate, pending work, overdue, on-time, avg cycle, by assignee, SLA)","description":"Read-only task analytics for the account, optionally windowed by task creation date. Archived tasks are INCLUDED in the historical metrics (`total`, `by_status`, `by_priority`, `completion_rate`, `avg_cycle_days`, `on_time_count`, `by_assignee`, `sla`): archiving is a filing action, not a workflow status, so archiving a finished task must not change what the team delivered. The two ACTIONABLE metrics — `pending_work_count` and `overdue_count` — exclude archived tasks, because an archived task is not work anyone still has to do.","security":[{"userApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"since","in":"query","required":false,"description":"Start of the window, matched against `tasks.created_at` from the beginning of that day. Omit for no lower bound.","schema":{"type":"string","format":"date","example":"2026-07-01"}},{"name":"until","in":"query","required":false,"description":"End of the window, matched against `tasks.created_at` through the end of that day. Omit for no upper bound.","schema":{"type":"string","format":"date","example":"2026-07-31"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","description":"The assembled analytics for the requested window.","properties":{"total":{"type":"number","description":"Tasks in the window, archived included.","example":184},"by_status":{"type":"object","description":"Task count per workflow status, archived included. Keys are the Task status enum: backlog, todo, in_progress, in_review, done, cancelled.","additionalProperties":{"type":"number"},"example":{"backlog":12,"todo":30,"in_progress":17,"in_review":7,"done":118,"cancelled":7}},"by_priority":{"type":"object","description":"Task count per priority, archived included. Keys are the Task priority enum: none, low, medium, high, urgent.","additionalProperties":{"type":"number"},"example":{"none":5,"low":60,"medium":84,"high":33,"urgent":7}},"completion_rate":{"type":"number","description":"Share of tasks in the window that are done, as a FRACTION between 0 and 1 rounded to 4 decimals — not a percentage. `0` when the window holds no tasks.","example":0.6413},"pending_work_count":{"type":"number","description":"Tasks still to be worked — not done, not cancelled, and NOT archived. Deliberately excludes archived tasks so filing the board cannot inflate outstanding work.","example":59},"overdue_count":{"type":"number","description":"Subset of `pending_work_count` whose `due_at` has passed. Archived tasks are excluded on the same reasoning.","example":12},"on_time_count":{"type":"number","description":"Done tasks delivered on or before their due date (or with no due date). Archived included — archiving a delivered task does not un-deliver it.","example":101},"avg_cycle_days":{"type":"number","description":"Mean days from creation to completion across done tasks, rounded to one decimal. `0` when nothing has completed.","example":4.3},"by_assignee":{"type":"array","description":"Top owners by task count, descending.","items":{"type":"object","description":"One assignee and their task count in the window.","properties":{"assignee_id":{"type":"number","example":214},"name":{"type":["string","null"],"description":"Null when the user record no longer resolves.","example":"Ana Ribeiro"},"count":{"type":"number","example":38}}},"example":[{"assignee_id":214,"name":"Ana Ribeiro","count":38},{"assignee_id":87,"name":"Marco Dias","count":25}]},"sla":{"type":"object","description":"Applied-SLA counts by status, over the SAME window as every other metric. Keys are the Task::AppliedSla status enum: active, at_risk, breached, met. Empty object when no SLA policy applies to the window.","additionalProperties":{"type":"number"},"example":{"active":23,"at_risk":6,"breached":11,"met":96}}}}}},"example":{"payload":{"total":184,"by_status":{"backlog":12,"todo":30,"in_progress":17,"in_review":7,"done":118,"cancelled":7},"by_priority":{"none":5,"low":60,"medium":84,"high":33,"urgent":7},"completion_rate":0.6413,"pending_work_count":59,"overdue_count":12,"on_time_count":101,"avg_cycle_days":4.3,"by_assignee":[{"assignee_id":214,"name":"Ana Ribeiro","count":38},{"assignee_id":87,"name":"Marco Dias","count":25}],"sla":{"active":23,"at_risk":6,"breached":11,"met":96}}}}}}}}},"/api/v1/accounts/{account_id}/tasks/demo":{"parameters":[{"$ref":"#/components/parameters/account_id"}],"post":{"tags":["Task Templates"],"operationId":"seed-tasks-demo-data","summary":"Seed Tasks demo data","security":[{"userApiKey":[]}],"description":"Enqueue the Tasks demo seed (admin-only). A demo list with sample tasks across every status (plus comments, checklist and reminders) is created asynchronously — the endpoint returns 202 immediately.","responses":{"202":{"description":"Accepted — the seed job was enqueued"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"delete":{"tags":["Task Templates"],"operationId":"teardown-tasks-demo-data","summary":"Tear down Tasks demo data","security":[{"userApiKey":[]}],"description":"Enqueue the Tasks demo teardown (admin-only). The previously seeded demo list and its tasks are removed asynchronously — the endpoint returns 202 immediately.","responses":{"202":{"description":"Accepted — the teardown job was enqueued"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/tasks/templates/{id}":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"id","in":"path","required":true,"schema":{"type":"number"},"description":"The numeric ID of the task template"}],"get":{"tags":["Task Templates"],"operationId":"get-task-template","summary":"Get a task template","security":[{"userApiKey":[]}],"description":"Get a single task template","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"$ref":"#/components/schemas/task_template"}}},"example":{"payload":{"id":1,"account_id":1,"name":"Sample Name","description":"A short description.","blueprint":{},"active":true,"position":1,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"The template does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"patch":{"tags":["Task Templates"],"operationId":"update-task-template","summary":"Update a task template","security":[{"userApiKey":[]}],"description":"Update a task template (admin-only)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"template":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"active":{"type":"boolean"},"position":{"type":"number"},"blueprint":{"type":"object","description":"JSON prefill. Known keys: title, description, priority, task_list_id, labels[], custom_attributes{}, subtasks[]","additionalProperties":true}}}}},"example":{"template":{"name":"Sample Name","description":"A short description.","active":true,"position":1,"blueprint":{}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"$ref":"#/components/schemas/task_template"}}},"example":{"payload":{"id":1,"account_id":1,"name":"Sample Name","description":"A short description.","blueprint":{},"active":true,"position":1,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"The template does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"delete":{"tags":["Task Templates"],"operationId":"delete-task-template","summary":"Delete a task template","security":[{"userApiKey":[]}],"description":"Delete a task template (admin-only)","responses":{"200":{"description":"Success"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"The template does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"put":{"tags":["Task Templates"],"operationId":"auto_put_api_v1_accounts_account_id_tasks_templates_id","summary":"Update templates","description":"Updates the template identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"blueprint":{"type":"object","additionalProperties":true,"description":"Task blueprint prefill payload. Known keys: title, description, priority, task_list_id, labels, custom_attributes, subtasks."},"active":{"type":"boolean"},"position":{"type":"integer"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}},"example":{"payload":{"id":1,"account_id":1,"name":"Sample Name","description":"A short description.","blueprint":{},"active":true,"position":1,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"template":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"active":{"type":"boolean"},"position":{"type":"integer"},"blueprint":{"type":"object","additionalProperties":true,"description":"Task blueprint prefill payload. Known keys: title, description, priority, task_list_id, labels, custom_attributes, subtasks."}}}},"required":["template"]},"example":{"template":{"name":"Sample Name","description":"A short description.","active":true,"position":1,"blueprint":{}}}}}}}},"/api/v1/accounts/{account_id}/tasks/templates":{"parameters":[{"$ref":"#/components/parameters/account_id"}],"get":{"tags":["Task Templates"],"operationId":"list-task-templates","summary":"List task templates","security":[{"userApiKey":[]}],"description":"List the account's task templates (read = agent+admin so the create form can list them)","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"$ref":"#/components/schemas/task_template"}}}},"example":{"payload":[{"id":1,"account_id":1,"name":"Sample Name","description":"A short description.","blueprint":{},"active":true,"position":1,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"post":{"tags":["Task Templates"],"operationId":"create-task-template","summary":"Create a task template","security":[{"userApiKey":[]}],"description":"Create a reusable task template (admin-only). The blueprint is applied as a prefill at task-create time.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"template":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"active":{"type":"boolean"},"position":{"type":"number"},"blueprint":{"type":"object","description":"JSON prefill. Known keys: title, description, priority, task_list_id, labels[], custom_attributes{}, subtasks[]","additionalProperties":true}},"required":["name"]}}},"example":{"template":{"name":"Sample Name","description":"A short description.","active":true,"position":1,"blueprint":{}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"$ref":"#/components/schemas/task_template"}}},"example":{"payload":{"id":1,"account_id":1,"name":"Sample Name","description":"A short description.","blueprint":{},"active":true,"position":1,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/tasks/sla_policies/{id}":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"id","in":"path","required":true,"schema":{"type":"number"},"description":"The numeric ID of the task SLA policy"}],"get":{"tags":["Task SLA Policies"],"operationId":"get-task-sla-policy","summary":"Get a task SLA policy","security":[{"userApiKey":[]}],"description":"Get a single native Task SLA policy (admin-only)","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"$ref":"#/components/schemas/task_sla_policy"}}},"example":{"payload":{"id":1,"account_id":1,"name":"Sample Name","description":"A short description.","due_offset_minutes":12.5,"time_to_first_action_minutes":12.5,"time_to_completion_minutes":12.5,"priority":12.5,"task_list_id":1,"active":true,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"The SLA policy does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"patch":{"tags":["Task SLA Policies"],"operationId":"update-task-sla-policy","summary":"Update a task SLA policy","security":[{"userApiKey":[]}],"description":"Update a native Task SLA policy (admin-only)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"sla_policy":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"due_offset_minutes":{"type":"number"},"time_to_first_action_minutes":{"type":"number"},"time_to_completion_minutes":{"type":"number"},"priority":{"type":"number","description":"Targeted task priority as the Task.priorities integer (none: 0 … urgent: 4); null = any"},"task_list_id":{"type":"number","description":"Targeted list ID; null = any list"},"active":{"type":"boolean"}}}}},"example":{"sla_policy":{"name":"Sample Name","description":"A short description.","due_offset_minutes":12.5,"time_to_first_action_minutes":12.5,"time_to_completion_minutes":12.5,"priority":12.5,"task_list_id":1,"active":true}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"$ref":"#/components/schemas/task_sla_policy"}}},"example":{"payload":{"id":1,"account_id":1,"name":"Sample Name","description":"A short description.","due_offset_minutes":12.5,"time_to_first_action_minutes":12.5,"time_to_completion_minutes":12.5,"priority":12.5,"task_list_id":1,"active":true,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"The SLA policy does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"delete":{"tags":["Task SLA Policies"],"operationId":"delete-task-sla-policy","summary":"Delete a task SLA policy","security":[{"userApiKey":[]}],"description":"Delete a native Task SLA policy (admin-only). Its applied-SLA rows are removed asynchronously.","responses":{"200":{"description":"Success"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"The SLA policy does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"put":{"tags":["Task SLA Policies"],"operationId":"auto_put_api_v1_accounts_account_id_tasks_sla_policies_id","summary":"Update sla policies","description":"Updates the sla policy identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"due_offset_minutes":{"type":"integer"},"time_to_first_action_minutes":{"type":"integer"},"time_to_completion_minutes":{"type":"integer"},"priority":{"type":"string"},"task_list_id":{"type":"integer"},"active":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}},"example":{"payload":{"id":1,"account_id":1,"name":"Sample Name","description":"A short description.","due_offset_minutes":60,"time_to_first_action_minutes":60,"time_to_completion_minutes":60,"priority":"sample priority","task_list_id":1,"active":true,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"sla_policy":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"due_offset_minutes":{"type":"integer"},"time_to_first_action_minutes":{"type":"integer"},"time_to_completion_minutes":{"type":"integer"},"priority":{"type":"string"},"task_list_id":{"type":"integer"},"active":{"type":"boolean"}}}},"required":["sla_policy"]},"example":{"sla_policy":{"name":"Sample Name","description":"A short description.","due_offset_minutes":60,"time_to_first_action_minutes":60,"time_to_completion_minutes":60,"priority":"sample priority","task_list_id":1,"active":true}}}}}}},"/api/v1/accounts/{account_id}/tasks/sla_policies":{"parameters":[{"$ref":"#/components/parameters/account_id"}],"get":{"tags":["Task SLA Policies"],"operationId":"list-task-sla-policies","summary":"List task SLA policies","security":[{"userApiKey":[]}],"description":"List the account's native Task SLA policies (admin-only, newest first)","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"$ref":"#/components/schemas/task_sla_policy"}}}},"example":{"payload":[{"id":1,"account_id":1,"name":"Sample Name","description":"A short description.","due_offset_minutes":12.5,"time_to_first_action_minutes":12.5,"time_to_completion_minutes":12.5,"priority":12.5,"task_list_id":1,"active":true,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"post":{"tags":["Task SLA Policies"],"operationId":"create-task-sla-policy","summary":"Create a task SLA policy","security":[{"userApiKey":[]}],"description":"Create a native Task SLA policy (admin-only). All thresholds are optional minutes, but at least one threshold must be present.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"sla_policy":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"due_offset_minutes":{"type":"number"},"time_to_first_action_minutes":{"type":"number"},"time_to_completion_minutes":{"type":"number"},"priority":{"type":"number","description":"Targeted task priority as the Task.priorities integer (none: 0 … urgent: 4); null = any"},"task_list_id":{"type":"number","description":"Targeted list ID; null = any list"},"active":{"type":"boolean"}},"required":["name"]}}},"example":{"sla_policy":{"name":"Sample Name","description":"A short description.","due_offset_minutes":12.5,"time_to_first_action_minutes":12.5,"time_to_completion_minutes":12.5,"priority":12.5,"task_list_id":1,"active":true}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"$ref":"#/components/schemas/task_sla_policy"}}},"example":{"payload":{"id":1,"account_id":1,"name":"Sample Name","description":"A short description.","due_offset_minutes":12.5,"time_to_first_action_minutes":12.5,"time_to_completion_minutes":12.5,"priority":12.5,"task_list_id":1,"active":true,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"422":{"description":"Unprocessable Entity (e.g. no threshold provided)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/payments/connections":{"get":{"tags":["Payment Connections"],"operationId":"list-payment-connections","summary":"List payment gateway connections","description":"List the account gateway connections (Asaas / Mercado Pago). Secrets are never returned — only has_* booleans.","security":[{"userApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/account_id"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"$ref":"#/components/schemas/payment_connection"}}}},"example":{"payload":[{"id":1,"account_id":1,"name":"Sample Name","gateway":"asaas","environment":"sandbox","status":"pending","is_default":true,"capabilities":{},"has_api_key":true,"has_secret_key":true,"has_webhook_token":true,"last_reconciliation":{"status":"success","started_at":"2026-01-15T10:30:00.000Z","finished_at":"2026-01-15T10:30:00.000Z","processed_count":5,"failed_count":5,"failed_ids":[{"resource":"charge","external_id":"sample external id","local_id":1,"reason":"gateway_error"}]},"settings":{"orphan_adoption_policy":"disabled","import_from":"2026-07-01T00:00:00Z"},"archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","max_installments_by_type":{"credit_card":1,"boleto":1,"pix":1},"installable_billing_types":["credit_card"],"installment_cycles":{"native_installment":["monthly"],"native_recurrence_capped":["weekly"]},"plan_creation_released":{"credit_card":false,"boleto":false,"pix":false},"plan_send_released":{"credit_card":false,"boleto":false,"pix":false},"gateway_option_defaults":{},"money_unit":"major","webhook_signature_scheme":"header_token","client_certificate":{"present":true,"status":"missing","days_remaining":1,"subject":"Sample subject","issuer":"sample issuer","fingerprint":"sample fingerprint","expires_at":"2026-01-15T10:30:00.000Z"},"capabilities_v2":{"money_unit":"major","webhook_signature_scheme":"header_token","methods":{}}}]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"post":{"tags":["Payment Connections"],"operationId":"create-payment-connection","summary":"Connect a payment gateway","description":"Creates a connection, verifies the credentials against the gateway and registers the webhook. Admin only.","security":[{"userApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/account_id"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"connection":{"type":"object","properties":{"name":{"type":"string"},"gateway":{"type":"string","enum":["asaas","mercado_pago"]},"environment":{"type":"string","enum":["sandbox","production"]},"api_key":{"type":"string","description":"Gateway API key (write-only; never returned)."},"secret_key":{"type":"string","description":"Mercado Pago signing secret (write-only)."},"webhook_token":{"type":"string","description":"Asaas authToken / webhook secret (write-only)."},"is_default":{"type":"boolean"}},"required":["gateway","environment"]}}},"example":{"connection":{"name":"Sample Name","gateway":"asaas","environment":"sandbox","api_key":"sample-token","secret_key":"sample-token","webhook_token":"sample-token","is_default":true}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/payment_connection"},"example":{"id":1,"account_id":1,"name":"Sample Name","gateway":"asaas","environment":"sandbox","status":"pending","is_default":true,"capabilities":{},"has_api_key":true,"has_secret_key":true,"has_webhook_token":true,"last_reconciliation":{"status":"success","started_at":"2026-01-15T10:30:00.000Z","finished_at":"2026-01-15T10:30:00.000Z","processed_count":5,"failed_count":5,"failed_ids":[{"resource":"charge","external_id":"sample external id","local_id":1,"reason":"gateway_error"}]},"settings":{"orphan_adoption_policy":"disabled","import_from":"2026-07-01T00:00:00Z"},"archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","max_installments_by_type":{"credit_card":1,"boleto":1,"pix":1},"installable_billing_types":["credit_card"],"installment_cycles":{"native_installment":["monthly"],"native_recurrence_capped":["weekly"]},"plan_creation_released":{"credit_card":false,"boleto":false,"pix":false},"plan_send_released":{"credit_card":false,"boleto":false,"pix":false},"gateway_option_defaults":{},"money_unit":"major","webhook_signature_scheme":"header_token","client_certificate":{"present":true,"status":"missing","days_remaining":1,"subject":"Sample subject","issuer":"sample issuer","fingerprint":"sample fingerprint","expires_at":"2026-01-15T10:30:00.000Z"},"capabilities_v2":{"money_unit":"major","webhook_signature_scheme":"header_token","methods":{}}}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/payments/connections/{id}":{"get":{"tags":["Payment Connections"],"operationId":"get-payment-connection","summary":"Get a payment connection","security":[{"userApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"id","in":"path","required":true,"schema":{"type":"number"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/payment_connection"},"example":{"id":1,"account_id":1,"name":"Sample Name","gateway":"asaas","environment":"sandbox","status":"pending","is_default":true,"capabilities":{},"has_api_key":true,"has_secret_key":true,"has_webhook_token":true,"last_reconciliation":{"status":"success","started_at":"2026-01-15T10:30:00.000Z","finished_at":"2026-01-15T10:30:00.000Z","processed_count":5,"failed_count":5,"failed_ids":[{"resource":"charge","external_id":"sample external id","local_id":1,"reason":"gateway_error"}]},"settings":{"orphan_adoption_policy":"disabled","import_from":"2026-07-01T00:00:00Z"},"archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","max_installments_by_type":{"credit_card":1,"boleto":1,"pix":1},"installable_billing_types":["credit_card"],"installment_cycles":{"native_installment":["monthly"],"native_recurrence_capped":["weekly"]},"plan_creation_released":{"credit_card":false,"boleto":false,"pix":false},"plan_send_released":{"credit_card":false,"boleto":false,"pix":false},"gateway_option_defaults":{},"money_unit":"major","webhook_signature_scheme":"header_token","client_certificate":{"present":true,"status":"missing","days_remaining":1,"subject":"Sample subject","issuer":"sample issuer","fingerprint":"sample fingerprint","expires_at":"2026-01-15T10:30:00.000Z"},"capabilities_v2":{"money_unit":"major","webhook_signature_scheme":"header_token","methods":{}}}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}},"description":"Get a payment connection. Returns the requested Connections resource."},"patch":{"tags":["Payment Connections"],"operationId":"update-payment-connection","summary":"Update a payment connection","security":[{"userApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"id","in":"path","required":true,"schema":{"type":"number"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"connection":{"type":"object","properties":{"name":{"type":"string"},"gateway":{"type":"string","enum":["asaas","mercado_pago"]},"environment":{"type":"string","enum":["sandbox","production"]},"api_key":{"type":"string","description":"Gateway API key (write-only; never returned)."},"secret_key":{"type":"string","description":"Mercado Pago signing secret (write-only)."},"webhook_token":{"type":"string","description":"Asaas authToken / webhook secret (write-only)."},"is_default":{"type":"boolean"}},"required":["gateway","environment"]}}},"example":{"connection":{"name":"Sample Name","gateway":"asaas","environment":"sandbox","api_key":"sample-token","secret_key":"sample-token","webhook_token":"sample-token","is_default":true}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/payment_connection"},"example":{"id":1,"account_id":1,"name":"Sample Name","gateway":"asaas","environment":"sandbox","status":"pending","is_default":true,"capabilities":{},"has_api_key":true,"has_secret_key":true,"has_webhook_token":true,"last_reconciliation":{"status":"success","started_at":"2026-01-15T10:30:00.000Z","finished_at":"2026-01-15T10:30:00.000Z","processed_count":5,"failed_count":5,"failed_ids":[{"resource":"charge","external_id":"sample external id","local_id":1,"reason":"gateway_error"}]},"settings":{"orphan_adoption_policy":"disabled","import_from":"2026-07-01T00:00:00Z"},"archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","max_installments_by_type":{"credit_card":1,"boleto":1,"pix":1},"installable_billing_types":["credit_card"],"installment_cycles":{"native_installment":["monthly"],"native_recurrence_capped":["weekly"]},"plan_creation_released":{"credit_card":false,"boleto":false,"pix":false},"plan_send_released":{"credit_card":false,"boleto":false,"pix":false},"gateway_option_defaults":{},"money_unit":"major","webhook_signature_scheme":"header_token","client_certificate":{"present":true,"status":"missing","days_remaining":1,"subject":"Sample subject","issuer":"sample issuer","fingerprint":"sample fingerprint","expires_at":"2026-01-15T10:30:00.000Z"},"capabilities_v2":{"money_unit":"major","webhook_signature_scheme":"header_token","methods":{}}}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}},"description":"Update a payment connection. Applies the submitted changes to the Connections resource."},"delete":{"tags":["Payment Connections"],"operationId":"delete-payment-connection","summary":"Archive a payment connection (soft delete; stops webhook ingestion)","security":[{"userApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"id","in":"path","required":true,"schema":{"type":"number"}}],"responses":{"200":{"description":"Success"},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}},"description":"Archive a payment connection (soft delete; stops webhook ingestion). Removes the targeted Connections resource."},"put":{"tags":["Payment Connections"],"operationId":"auto_put_api_v1_accounts_account_id_payments_connections_id","summary":"Update connections","description":"Updates the connection identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Updated payment connection with masked credentials and gateway capabilities.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/payment_connection"},"example":{"id":1,"account_id":1,"name":"Sample Name","gateway":"asaas","environment":"sandbox","status":"pending","is_default":true,"capabilities":{},"has_api_key":true,"has_secret_key":true,"has_webhook_token":true,"last_reconciliation":{"status":"success","started_at":"2026-01-15T10:30:00.000Z","finished_at":"2026-01-15T10:30:00.000Z","processed_count":5,"failed_count":5,"failed_ids":[{"resource":"charge","external_id":"sample external id","local_id":1,"reason":"gateway_error"}]},"settings":{"orphan_adoption_policy":"disabled","import_from":"2026-07-01T00:00:00Z"},"archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","max_installments_by_type":{"credit_card":1,"boleto":1,"pix":1},"installable_billing_types":["credit_card"],"installment_cycles":{"native_installment":["monthly"],"native_recurrence_capped":["weekly"]},"plan_creation_released":{"credit_card":false,"boleto":false,"pix":false},"plan_send_released":{"credit_card":false,"boleto":false,"pix":false},"gateway_option_defaults":{},"money_unit":"major","webhook_signature_scheme":"header_token","client_certificate":{"present":true,"status":"missing","days_remaining":1,"subject":"Sample subject","issuer":"sample issuer","fingerprint":"sample fingerprint","expires_at":"2026-01-15T10:30:00.000Z"},"capabilities_v2":{"money_unit":"major","webhook_signature_scheme":"header_token","methods":{}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"connection":{"type":"object","properties":{"name":{"type":"string"},"gateway":{"type":"string","enum":["asaas","mercado_pago"]},"environment":{"type":"string","enum":["sandbox","production"]},"is_default":{"type":"boolean"},"api_key":{"type":"string"},"secret_key":{"type":"string"},"webhook_token":{"type":"string"},"webhook_email":{"type":"string","format":"email"}}}},"required":["connection"]},"example":{"connection":{"name":"Sample Name","gateway":"asaas","environment":"sandbox","is_default":true,"api_key":"sample-token","secret_key":"sample-token","webhook_token":"sample-token","webhook_email":"agent@example.com"}}}}}}},"/api/v1/accounts/{account_id}/payments/connections/{id}/verify":{"post":{"tags":["Payment Connections"],"operationId":"verify-payment-connection","summary":"Re-verify the gateway credentials (flips status active/errored)","security":[{"userApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"id","in":"path","required":true,"schema":{"type":"number"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/payment_connection"},"example":{"id":1,"account_id":1,"name":"Sample Name","gateway":"asaas","environment":"sandbox","status":"pending","is_default":true,"capabilities":{},"has_api_key":true,"has_secret_key":true,"has_webhook_token":true,"last_reconciliation":{"status":"success","started_at":"2026-01-15T10:30:00.000Z","finished_at":"2026-01-15T10:30:00.000Z","processed_count":5,"failed_count":5,"failed_ids":[{"resource":"charge","external_id":"sample external id","local_id":1,"reason":"gateway_error"}]},"settings":{"orphan_adoption_policy":"disabled","import_from":"2026-07-01T00:00:00Z"},"archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","max_installments_by_type":{"credit_card":1,"boleto":1,"pix":1},"installable_billing_types":["credit_card"],"installment_cycles":{"native_installment":["monthly"],"native_recurrence_capped":["weekly"]},"plan_creation_released":{"credit_card":false,"boleto":false,"pix":false},"plan_send_released":{"credit_card":false,"boleto":false,"pix":false},"gateway_option_defaults":{},"money_unit":"major","webhook_signature_scheme":"header_token","client_certificate":{"present":true,"status":"missing","days_remaining":1,"subject":"Sample subject","issuer":"sample issuer","fingerprint":"sample fingerprint","expires_at":"2026-01-15T10:30:00.000Z"},"capabilities_v2":{"money_unit":"major","webhook_signature_scheme":"header_token","methods":{}}}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}},"description":"Re-verify the gateway credentials (flips status active/errored). Submits the request payload to the Verify resource and returns the result."}},"/api/v1/accounts/{account_id}/payments/connections/{id}/set_default":{"post":{"tags":["Payment Connections"],"operationId":"set-default-payment-connection","summary":"Make this the default connection (exactly one default per account)","security":[{"userApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"id","in":"path","required":true,"schema":{"type":"number"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/payment_connection"},"example":{"id":1,"account_id":1,"name":"Sample Name","gateway":"asaas","environment":"sandbox","status":"pending","is_default":true,"capabilities":{},"has_api_key":true,"has_secret_key":true,"has_webhook_token":true,"last_reconciliation":{"status":"success","started_at":"2026-01-15T10:30:00.000Z","finished_at":"2026-01-15T10:30:00.000Z","processed_count":5,"failed_count":5,"failed_ids":[{"resource":"charge","external_id":"sample external id","local_id":1,"reason":"gateway_error"}]},"settings":{"orphan_adoption_policy":"disabled","import_from":"2026-07-01T00:00:00Z"},"archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","max_installments_by_type":{"credit_card":1,"boleto":1,"pix":1},"installable_billing_types":["credit_card"],"installment_cycles":{"native_installment":["monthly"],"native_recurrence_capped":["weekly"]},"plan_creation_released":{"credit_card":false,"boleto":false,"pix":false},"plan_send_released":{"credit_card":false,"boleto":false,"pix":false},"gateway_option_defaults":{},"money_unit":"major","webhook_signature_scheme":"header_token","client_certificate":{"present":true,"status":"missing","days_remaining":1,"subject":"Sample subject","issuer":"sample issuer","fingerprint":"sample fingerprint","expires_at":"2026-01-15T10:30:00.000Z"},"capabilities_v2":{"money_unit":"major","webhook_signature_scheme":"header_token","methods":{}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}},"description":"Make this the default connection (exactly one default per account). Submits the request payload to the Set default resource and returns the result."}},"/api/v1/accounts/{account_id}/payments/connections/{id}/restore":{"post":{"tags":["Payment Connections"],"operationId":"restore-payment-connection","summary":"Restore an archived connection","security":[{"userApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"id","in":"path","required":true,"schema":{"type":"number"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/payment_connection"},"example":{"id":1,"account_id":1,"name":"Sample Name","gateway":"asaas","environment":"sandbox","status":"pending","is_default":true,"capabilities":{},"has_api_key":true,"has_secret_key":true,"has_webhook_token":true,"last_reconciliation":{"status":"success","started_at":"2026-01-15T10:30:00.000Z","finished_at":"2026-01-15T10:30:00.000Z","processed_count":5,"failed_count":5,"failed_ids":[{"resource":"charge","external_id":"sample external id","local_id":1,"reason":"gateway_error"}]},"settings":{"orphan_adoption_policy":"disabled","import_from":"2026-07-01T00:00:00Z"},"archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","max_installments_by_type":{"credit_card":1,"boleto":1,"pix":1},"installable_billing_types":["credit_card"],"installment_cycles":{"native_installment":["monthly"],"native_recurrence_capped":["weekly"]},"plan_creation_released":{"credit_card":false,"boleto":false,"pix":false},"plan_send_released":{"credit_card":false,"boleto":false,"pix":false},"gateway_option_defaults":{},"money_unit":"major","webhook_signature_scheme":"header_token","client_certificate":{"present":true,"status":"missing","days_remaining":1,"subject":"Sample subject","issuer":"sample issuer","fingerprint":"sample fingerprint","expires_at":"2026-01-15T10:30:00.000Z"},"capabilities_v2":{"money_unit":"major","webhook_signature_scheme":"header_token","methods":{}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}},"description":"Restore an archived connection. Submits the request payload to the Restore resource and returns the result."}},"/api/v1/accounts/{account_id}/payments/connections/{id}/register_webhook":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"id","in":"path","required":true,"schema":{"type":"number"},"description":"ID of the payment connection"}],"post":{"tags":["Payment Connections"],"operationId":"register-payment-connection-webhook","summary":"(Re)register the gateway webhook","security":[{"userApiKey":[]}],"description":"Explicitly (re)register the gateway webhook for this connection. Unlike the best-effort registration at create time, a gateway failure here is surfaced as 422 (never a false \"registered\"). On success the registration is cached in settings and any prior registration error is cleared.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"webhook_email":{"type":"string","description":"Failure-notification email — persisted on the connection before calling the gateway."}}},"example":{"webhook_email":"agent@example.com"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/payment_connection"},"example":{"id":1,"account_id":1,"name":"Sample Name","gateway":"asaas","environment":"sandbox","status":"pending","is_default":true,"capabilities":{},"has_api_key":true,"has_secret_key":true,"has_webhook_token":true,"last_reconciliation":{"status":"success","started_at":"2026-01-15T10:30:00.000Z","finished_at":"2026-01-15T10:30:00.000Z","processed_count":5,"failed_count":5,"failed_ids":[{"resource":"charge","external_id":"sample external id","local_id":1,"reason":"gateway_error"}]},"settings":{"orphan_adoption_policy":"disabled","import_from":"2026-07-01T00:00:00Z"},"archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","max_installments_by_type":{"credit_card":1,"boleto":1,"pix":1},"installable_billing_types":["credit_card"],"installment_cycles":{"native_installment":["monthly"],"native_recurrence_capped":["weekly"]},"plan_creation_released":{"credit_card":false,"boleto":false,"pix":false},"plan_send_released":{"credit_card":false,"boleto":false,"pix":false},"gateway_option_defaults":{},"money_unit":"major","webhook_signature_scheme":"header_token","client_certificate":{"present":true,"status":"missing","days_remaining":1,"subject":"Sample subject","issuer":"sample issuer","fingerprint":"sample fingerprint","expires_at":"2026-01-15T10:30:00.000Z"},"capabilities_v2":{"money_unit":"major","webhook_signature_scheme":"header_token","methods":{}}}}}},"422":{"description":"Unprocessable Entity (gateway rejected the webhook registration)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/payments/connections/{id}/purge":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"id","in":"path","required":true,"schema":{"type":"number"},"description":"ID of the payment connection"}],"delete":{"tags":["Payment Connections"],"operationId":"purge-payment-connection","summary":"Permanently delete an archived connection","security":[{"userApiKey":[]}],"description":"Permanently delete an archived payment connection (customers and plans are cleaned up with it). The connection must already be archived (archive first, then delete forever). A connection that still has charges or subscriptions cannot be purged — those are kept for financial audit.","responses":{"200":{"description":"Success"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"422":{"description":"The connection must be archived first, or it still has charges/subscriptions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"The connection does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/payments/charges":{"get":{"tags":["Payment Charges"],"operationId":"list-payment-charges","summary":"List, search, filter and sort charges","description":"Account-scoped registry query. Search matches the charge description, gateway/external ids, customer name/email and connection name; a canonical positive integer also matches the exact local charge id. The created date window is interpreted in the account timezone. Invalid status, date or sort values are ignored or fall back to safe defaults.","security":[{"userApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"q","in":"query","description":"Search description, gateway/external id, customer name/email, connection name or exact local id.","schema":{"type":"string","maxLength":200}},{"name":"status","in":"query","schema":{"type":"string","enum":["pending","awaiting_payment","confirmed","paid","overdue","refunded","partially_refunded","canceled","failed"]}},{"name":"contact_id","in":"query","schema":{"type":"integer"}},{"name":"connection_id","in":"query","schema":{"type":"integer"}},{"name":"crm_item_id","in":"query","description":"Filter by the account-scoped linked CRM deal id.","schema":{"type":"integer"}},{"name":"conversation_id","in":"query","description":"Filter by the account-scoped conversation display id (internal id fallback).","schema":{"type":"integer"}},{"name":"from","in":"query","description":"Inclusive created-at start date in the account timezone.","schema":{"type":"string","format":"date"}},{"name":"to","in":"query","description":"Inclusive created-at end date in the account timezone.","schema":{"type":"string","format":"date"}},{"name":"archived","in":"query","schema":{"type":"boolean"}},{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1}},{"name":"per_page","in":"query","description":"Page size, clamped server-side to 1..100.","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"sort","in":"query","schema":{"type":"string","enum":["created_at","due_date","amount","status","description"],"default":"created_at"}},{"name":"direction","in":"query","schema":{"type":"string","enum":["asc","desc"],"default":"desc"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"$ref":"#/components/schemas/payment_charge"}},"meta":{"type":"object","properties":{"count":{"type":"number"},"current_page":{"type":"number"},"total_pages":{"type":"number"},"per_page":{"type":"number"},"has_more":{"type":"boolean"}}}}},"example":{"payload":[{"id":1,"account_id":1,"payments_connection_id":1,"contact_id":1,"organization_id":1,"organization_name":"sample organization name","conversation_id":1,"crm_item_id":1,"crm_item_title":"sample crm item title","payments_subscription_id":1,"gateway_charge_id":"sample gateway charge id","external_reference":"sample external reference","billing_type":"pix","status":"pending","amount":149.9,"amount_refunded":12.5,"subtotal_amount":149.9,"discount":12.5,"discount_type":"fixed","discount_reason":"sample discount reason","currency":"BRL","original_amount":149.9,"original_currency":"sample original currency","fx_rate":12.5,"installments":1,"installment_mode":"absorb","installment_interest_rate":12.5,"due_date":"2026-01-15","paid_at":"2026-01-15T10:30:00.000Z","refunded_at":"2026-01-15T10:30:00.000Z","description":"A short description.","hosted_url":"https://example.com/resource","pix_payload":"sample pix payload","pix_qr_base64":"sample pix qr base64","boleto_url":"https://example.com/resource","metadata":{"origin":"external_gateway"},"gateway_options":{},"custom_attributes":{},"settled":true,"contact_name":"sample contact name","contact_email":"agent@example.com","payer_email":"agent@example.com","contact_phone_number":"+5511999998888","gateway_customer_id":"sample gateway customer id","gateway":"hotmart","can_mark_as_paid":true,"manually_paid":true,"conversation_display_id":1,"archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","line_items":[{"id":1,"catalog_variant_id":1,"catalog_product_id":1,"name_snapshot":"sample name snapshot","quantity":12.5,"unit_price":149.9,"discount":12.5,"discount_type":"fixed","line_total":149.9,"currency":"BRL","position":1,"metadata":{}}],"installment_plan_id":1,"installment_number":1,"installments_count":5,"installment_plan":{"id":1,"account_id":1,"payments_connection_id":1,"contact_id":1,"organization_id":1,"conversation_id":1,"crm_item_id":1,"payments_subscription_id":1,"installments_count":5,"paid_count":5,"total_amount":"sample total amount","installment_amount":"sample installment amount","last_installment_amount":"sample last installment amount","paid_amount":"sample paid amount","refunded_amount":"sample refunded amount","installment_interest_rate":"sample installment interest rate","strategy":"native_installment","status":"pending","billing_type":"pix","cycle":"weekly","installment_mode":"absorb","currency":"BRL","gateway_installment_id":"sample gateway installment id","gateway":"sample gateway","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","archived_at":"2026-01-15T10:30:00.000Z","first_due_date":"2026-01-15","projected_schedule":[{"number":1,"due_date":"2026-01-15","amount":149.9}],"payment_book":{"state":"pending","degraded":true,"stale":true,"refresh_failed":true,"stalled":true,"url":"https://example.com/resource"},"allowed_actions":{"payment_book":true,"send_to_conversation":true,"send_installment":true,"update":true,"cancel":true,"destroy":true,"refund":true,"update_notification_preferences":true},"payment_book_degraded":true,"conversation_display_id":1,"contact_name":"sample contact name","next_due_date":"2026-01-15","gateway_payment_book":{"url":"https://example.com/resource"},"open_installments_count":5,"financial_evidence":{},"notification_preferences":{"payment_charge_paid":false,"installment_plan_completed":true}},"can_undo_mark_as_paid":true,"can_refund":true}],"meta":{"count":5,"current_page":12.5,"total_pages":12.5,"per_page":12.5,"has_more":true}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"post":{"tags":["Payment Charges"],"operationId":"create-payment-charge","summary":"Create a charge (avulsa / catalog / order / deal)","description":"Creates and durably identifies a local charge before gateway I/O (PIX copia-e-cola + QR / boleto / hosted link). A retry with the same key and material payload resumes or returns that row; reuse with different data is rejected. An uncertain timeout is recovered by exact external reference and never blindly recharged. PCI-safe: never raw card data.","security":[{"userApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"X-Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Stable per logical charge (at most 255 UTF-8 bytes; no control characters). Preserve it across network retries; reusing it with different payment data returns 422."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["charge"],"properties":{"charge":{"type":"object","properties":{"connection_id":{"type":"number","description":"Gateway connection; defaults to the account default."},"contact_id":{"type":"number"},"organization_id":{"type":["integer","null"],"minimum":1,"description":"Optional company payer from this account. The contact must be a member; company fiscal data is required without contact fallback."},"conversation_id":{"type":"number"},"billing_type":{"type":"string","enum":["pix","boleto","credit_card","hosted_link","undefined","debit_card"],"description":"How the payer is charged. `undefined` lets the payer pick on the hosted invoice."},"amount":{"type":"number","description":"Major units (decimal). Ignored when source is catalog/order/deal."},"currency":{"type":"string","example":"BRL"},"due_date":{"type":"string","format":"date"},"installments":{"type":"integer","minimum":1,"description":"Method-specific installments (card, boleto or Pix where supported). The selected connection is capability-gated and provider-specific limits are enforced before persistence."},"installment_cycle":{"type":"string","enum":["weekly","biweekly","monthly","bimonthly","quarterly","semiannually","yearly"]},"installment_mode":{"type":"string","enum":["absorb","passthrough"]},"installment_interest_rate":{"type":"number","minimum":0},"gateway_options":{"type":"object","description":"Gateway-native options. Every key is rejected unless the selected connection advertises its matching capability. Values are persisted in the charge audit.","properties":{"fine":{"type":"object","description":"Asaas late fee as a percentage; omit it to preserve the account default, or send zero to disable it for this charge.","properties":{"type":{"type":"string","enum":["fixed","percentage"]},"value":{"type":"number","minimum":0,"example":2}}},"interest":{"type":"object","description":"Asaas monthly interest percentage; omit it to preserve the account default, or send zero to disable it for this charge.","properties":{"value":{"type":"number","minimum":0,"example":1}}},"discount":{"type":"object","description":"Asaas percentage discount for payment before the due date.","properties":{"type":{"type":"string","enum":["fixed","percentage"]},"value":{"type":"number","exclusiveMinimum":0,"example":8},"due_date_limit_days":{"type":"integer","minimum":0,"example":3}},"required":["value","due_date_limit_days"]},"postal_service":{"type":"boolean","description":"Asaas boleto postal delivery; boleto only."},"callback":{"type":"object","properties":{"success_url":{"type":"string","format":"uri","description":"Public HTTPS URL."},"auto_redirect":{"type":"boolean"}},"required":["success_url"]},"back_urls":{"type":"object","description":"Mercado Pago Checkout Pro return URLs; hosted payment methods only.","properties":{"success":{"type":"string","format":"uri"},"failure":{"type":"string","format":"uri"},"pending":{"type":"string","format":"uri"}}},"auto_return":{"type":"boolean","description":"Mercado Pago automatic return after approval; requires back_urls.success."}}},"description":{"type":"string"},"doc":{"type":"string","description":"Payer CPF/CNPJ (required by Asaas)."},"source":{"type":"string","enum":["manual","catalog","order","deal"],"default":"manual"},"catalog_variant_ids":{"type":"array","items":{"type":"number"},"description":"When source=catalog."},"order_items":{"type":"array","minItems":1,"description":"Exact customer-agreed cart lines required when source=order. Quantities, prices, currencies and discounts are snapshotted rather than re-derived from current catalog prices.","items":{"type":"object","properties":{"catalog_product_id":{"type":"integer","minimum":1},"catalog_variant_id":{"type":"integer","minimum":1},"name":{"type":"string"},"quantity":{"type":"number","exclusiveMinimum":0},"unit_price":{"type":"number","minimum":0},"currency":{"type":"string","example":"BRL"},"discount":{"type":"number","minimum":0,"default":0},"discount_type":{"type":"string","enum":["fixed","percent"],"default":"fixed","description":"Whether the discount is an absolute amount or a percentage."}}}},"crm_item_id":{"type":"number","description":"When source=deal (quote total)."},"idempotency_key":{"type":"string","maxLength":255,"description":"Body alternative to X-Idempotency-Key (at most 255 UTF-8 bytes; no control characters). Preserve it across retries of the same material request."}},"required":["contact_id","billing_type"]}}},"example":{"charge":{"connection_id":1,"contact_id":1,"organization_id":1,"conversation_id":1,"billing_type":"pix","amount":149.9,"currency":"BRL","due_date":"2026-01-15","installments":1,"installment_cycle":"weekly","installment_mode":"absorb","installment_interest_rate":12.5,"gateway_options":{"fine":{"type":"fixed","value":2},"interest":{"value":1},"discount":{"type":"fixed","value":8,"due_date_limit_days":3},"postal_service":true,"callback":{"success_url":"https://example.com/resource","auto_redirect":true},"back_urls":{"success":"https://example.com/resource","failure":"https://example.com/resource","pending":"https://example.com/resource"},"auto_return":true},"description":"A short description.","doc":"sample doc","source":"manual","catalog_variant_ids":[1],"order_items":[{"catalog_product_id":1,"catalog_variant_id":1,"name":"Sample Name","quantity":12.5,"unit_price":149.9,"currency":"BRL","discount":0,"discount_type":"fixed"}],"crm_item_id":1,"idempotency_key":"sample-token"}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"$ref":"#/components/schemas/payment_charge"}}},"example":{"payload":{"id":1,"account_id":1,"payments_connection_id":1,"contact_id":1,"organization_id":1,"organization_name":"sample organization name","conversation_id":1,"crm_item_id":1,"crm_item_title":"sample crm item title","payments_subscription_id":1,"gateway_charge_id":"sample gateway charge id","external_reference":"sample external reference","billing_type":"pix","status":"pending","amount":149.9,"amount_refunded":12.5,"subtotal_amount":149.9,"discount":12.5,"discount_type":"fixed","discount_reason":"sample discount reason","currency":"BRL","original_amount":149.9,"original_currency":"sample original currency","fx_rate":12.5,"installments":1,"installment_mode":"absorb","installment_interest_rate":12.5,"due_date":"2026-01-15","paid_at":"2026-01-15T10:30:00.000Z","refunded_at":"2026-01-15T10:30:00.000Z","description":"A short description.","hosted_url":"https://example.com/resource","pix_payload":"sample pix payload","pix_qr_base64":"sample pix qr base64","boleto_url":"https://example.com/resource","metadata":{"origin":"external_gateway"},"gateway_options":{},"custom_attributes":{},"settled":true,"contact_name":"sample contact name","contact_email":"agent@example.com","payer_email":"agent@example.com","contact_phone_number":"+5511999998888","gateway_customer_id":"sample gateway customer id","gateway":"hotmart","can_mark_as_paid":true,"manually_paid":true,"conversation_display_id":1,"archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","line_items":[{"id":1,"catalog_variant_id":1,"catalog_product_id":1,"name_snapshot":"sample name snapshot","quantity":12.5,"unit_price":149.9,"discount":12.5,"discount_type":"fixed","line_total":149.9,"currency":"BRL","position":1,"metadata":{}}],"installment_plan_id":1,"installment_number":1,"installments_count":5,"installment_plan":{"id":1,"account_id":1,"payments_connection_id":1,"contact_id":1,"organization_id":1,"conversation_id":1,"crm_item_id":1,"payments_subscription_id":1,"installments_count":5,"paid_count":5,"total_amount":"sample total amount","installment_amount":"sample installment amount","last_installment_amount":"sample last installment amount","paid_amount":"sample paid amount","refunded_amount":"sample refunded amount","installment_interest_rate":"sample installment interest rate","strategy":"native_installment","status":"pending","billing_type":"pix","cycle":"weekly","installment_mode":"absorb","currency":"BRL","gateway_installment_id":"sample gateway installment id","gateway":"sample gateway","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","archived_at":"2026-01-15T10:30:00.000Z","first_due_date":"2026-01-15","projected_schedule":[{"number":1,"due_date":"2026-01-15","amount":149.9}],"payment_book":{"state":"pending","degraded":true,"stale":true,"refresh_failed":true,"stalled":true,"url":"https://example.com/resource"},"allowed_actions":{"payment_book":true,"send_to_conversation":true,"send_installment":true,"update":true,"cancel":true,"destroy":true,"refund":true,"update_notification_preferences":true},"payment_book_degraded":true,"conversation_display_id":1,"contact_name":"sample contact name","next_due_date":"2026-01-15","gateway_payment_book":{"url":"https://example.com/resource"},"open_installments_count":5,"financial_evidence":{},"notification_preferences":{"payment_charge_paid":false,"installment_plan_completed":true}},"can_undo_mark_as_paid":true,"can_refund":true}}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/payments/charges/export":{"get":{"tags":["Payment Charges"],"operationId":"export-payment-charges","summary":"Export the filtered or selected charge registry as CSV","description":"Uses the same account-scoped search and filters as the list endpoint, without page truncation. When ids[] is present, the result is narrowed to at most 500 selected charge ids. Text cells are protected against spreadsheet formula injection.","security":[{"userApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"q","in":"query","schema":{"type":"string","maxLength":200}},{"name":"status","in":"query","schema":{"type":"string","enum":["pending","awaiting_payment","confirmed","paid","overdue","refunded","partially_refunded","canceled","failed"]}},{"name":"contact_id","in":"query","schema":{"type":"integer"}},{"name":"connection_id","in":"query","schema":{"type":"integer"}},{"name":"crm_item_id","in":"query","schema":{"type":"integer"}},{"name":"conversation_id","in":"query","schema":{"type":"integer"}},{"name":"from","in":"query","schema":{"type":"string","format":"date"}},{"name":"to","in":"query","schema":{"type":"string","format":"date"}},{"name":"archived","in":"query","schema":{"type":"boolean"}},{"name":"sort","in":"query","schema":{"type":"string","enum":["created_at","due_date","amount","status","description"],"default":"created_at"}},{"name":"direction","in":"query","schema":{"type":"string","enum":["asc","desc"],"default":"desc"}},{"name":"ids","in":"query","description":"Optional current selection; foreign or missing ids are omitted by account scope.","style":"form","explode":true,"schema":{"type":"array","maxItems":500,"uniqueItems":true,"items":{"type":"integer","minimum":1}}}],"responses":{"200":{"description":"UTF-8 CSV attachment.","content":{"text/csv":{"schema":{"type":"string","format":"binary"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/payments/charges/{id}":{"get":{"tags":["Payment Charges"],"operationId":"get-payment-charge","summary":"Get a charge","security":[{"userApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"id","in":"path","required":true,"schema":{"type":"number"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"$ref":"#/components/schemas/payment_charge"}}},"example":{"payload":{"id":1,"account_id":1,"payments_connection_id":1,"contact_id":1,"organization_id":1,"organization_name":"sample organization name","conversation_id":1,"crm_item_id":1,"crm_item_title":"sample crm item title","payments_subscription_id":1,"gateway_charge_id":"sample gateway charge id","external_reference":"sample external reference","billing_type":"pix","status":"pending","amount":149.9,"amount_refunded":12.5,"subtotal_amount":149.9,"discount":12.5,"discount_type":"fixed","discount_reason":"sample discount reason","currency":"BRL","original_amount":149.9,"original_currency":"sample original currency","fx_rate":12.5,"installments":1,"installment_mode":"absorb","installment_interest_rate":12.5,"due_date":"2026-01-15","paid_at":"2026-01-15T10:30:00.000Z","refunded_at":"2026-01-15T10:30:00.000Z","description":"A short description.","hosted_url":"https://example.com/resource","pix_payload":"sample pix payload","pix_qr_base64":"sample pix qr base64","boleto_url":"https://example.com/resource","metadata":{"origin":"external_gateway"},"gateway_options":{},"custom_attributes":{},"settled":true,"contact_name":"sample contact name","contact_email":"agent@example.com","payer_email":"agent@example.com","contact_phone_number":"+5511999998888","gateway_customer_id":"sample gateway customer id","gateway":"hotmart","can_mark_as_paid":true,"manually_paid":true,"conversation_display_id":1,"archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","line_items":[{"id":1,"catalog_variant_id":1,"catalog_product_id":1,"name_snapshot":"sample name snapshot","quantity":12.5,"unit_price":149.9,"discount":12.5,"discount_type":"fixed","line_total":149.9,"currency":"BRL","position":1,"metadata":{}}],"installment_plan_id":1,"installment_number":1,"installments_count":5,"installment_plan":{"id":1,"account_id":1,"payments_connection_id":1,"contact_id":1,"organization_id":1,"conversation_id":1,"crm_item_id":1,"payments_subscription_id":1,"installments_count":5,"paid_count":5,"total_amount":"sample total amount","installment_amount":"sample installment amount","last_installment_amount":"sample last installment amount","paid_amount":"sample paid amount","refunded_amount":"sample refunded amount","installment_interest_rate":"sample installment interest rate","strategy":"native_installment","status":"pending","billing_type":"pix","cycle":"weekly","installment_mode":"absorb","currency":"BRL","gateway_installment_id":"sample gateway installment id","gateway":"sample gateway","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","archived_at":"2026-01-15T10:30:00.000Z","first_due_date":"2026-01-15","projected_schedule":[{"number":1,"due_date":"2026-01-15","amount":149.9}],"payment_book":{"state":"pending","degraded":true,"stale":true,"refresh_failed":true,"stalled":true,"url":"https://example.com/resource"},"allowed_actions":{"payment_book":true,"send_to_conversation":true,"send_installment":true,"update":true,"cancel":true,"destroy":true,"refund":true,"update_notification_preferences":true},"payment_book_degraded":true,"conversation_display_id":1,"contact_name":"sample contact name","next_due_date":"2026-01-15","gateway_payment_book":{"url":"https://example.com/resource"},"open_installments_count":5,"financial_evidence":{},"notification_preferences":{"payment_charge_paid":false,"installment_plan_completed":true}},"can_undo_mark_as_paid":true,"can_refund":true}}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}},"description":"Get a charge. Returns the requested Charges resource."},"delete":{"tags":["Payment Charges"],"operationId":"delete-payment-charge","summary":"Delete a charge (settled charges cannot be deleted — archive instead)","security":[{"userApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"id","in":"path","required":true,"schema":{"type":"number"}}],"responses":{"200":{"description":"Success"},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}},"description":"Delete a charge (settled charges cannot be deleted — archive instead). Removes the targeted Charges resource."},"patch":{"tags":["Payment Charges"],"operationId":"update-payment-charge","summary":"Edit a not-yet-settled charge","security":[{"userApiKey":[]}],"description":"Edit a pending charge at the gateway and locally (only the supplied fields are changed). A settled charge (money moved) is never edited — refund it instead (422). Asaas supports editing while pending/overdue; Mercado Pago charges are immutable (the gateway error is surfaced as 422 — cancel and recreate). Contact/connection/source are immutable post-creation.","parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"id","in":"path","required":true,"schema":{"type":"number"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"charge":{"type":"object","properties":{"amount":{"type":"number","description":"Major units (decimal)."},"due_date":{"type":"string","format":"date"},"description":{"type":"string"},"billing_type":{"type":"string","enum":["pix","boleto","credit_card","hosted_link","undefined","debit_card"],"description":"How the payer is charged. `undefined` lets the payer pick on the hosted invoice."},"gateway_options":{"$ref":"#/components/schemas/payment_gateway_options"}}}}},"example":{"charge":{"amount":149.9,"due_date":"2026-01-15","description":"A short description.","billing_type":"pix","gateway_options":{}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"$ref":"#/components/schemas/payment_charge"}}},"example":{"payload":{"id":1,"account_id":1,"payments_connection_id":1,"contact_id":1,"organization_id":1,"organization_name":"sample organization name","conversation_id":1,"crm_item_id":1,"crm_item_title":"sample crm item title","payments_subscription_id":1,"gateway_charge_id":"sample gateway charge id","external_reference":"sample external reference","billing_type":"pix","status":"pending","amount":149.9,"amount_refunded":12.5,"subtotal_amount":149.9,"discount":12.5,"discount_type":"fixed","discount_reason":"sample discount reason","currency":"BRL","original_amount":149.9,"original_currency":"sample original currency","fx_rate":12.5,"installments":1,"installment_mode":"absorb","installment_interest_rate":12.5,"due_date":"2026-01-15","paid_at":"2026-01-15T10:30:00.000Z","refunded_at":"2026-01-15T10:30:00.000Z","description":"A short description.","hosted_url":"https://example.com/resource","pix_payload":"sample pix payload","pix_qr_base64":"sample pix qr base64","boleto_url":"https://example.com/resource","metadata":{"origin":"external_gateway"},"gateway_options":{},"custom_attributes":{},"settled":true,"contact_name":"sample contact name","contact_email":"agent@example.com","payer_email":"agent@example.com","contact_phone_number":"+5511999998888","gateway_customer_id":"sample gateway customer id","gateway":"hotmart","can_mark_as_paid":true,"manually_paid":true,"conversation_display_id":1,"archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","line_items":[{"id":1,"catalog_variant_id":1,"catalog_product_id":1,"name_snapshot":"sample name snapshot","quantity":12.5,"unit_price":149.9,"discount":12.5,"discount_type":"fixed","line_total":149.9,"currency":"BRL","position":1,"metadata":{}}],"installment_plan_id":1,"installment_number":1,"installments_count":5,"installment_plan":{"id":1,"account_id":1,"payments_connection_id":1,"contact_id":1,"organization_id":1,"conversation_id":1,"crm_item_id":1,"payments_subscription_id":1,"installments_count":5,"paid_count":5,"total_amount":"sample total amount","installment_amount":"sample installment amount","last_installment_amount":"sample last installment amount","paid_amount":"sample paid amount","refunded_amount":"sample refunded amount","installment_interest_rate":"sample installment interest rate","strategy":"native_installment","status":"pending","billing_type":"pix","cycle":"weekly","installment_mode":"absorb","currency":"BRL","gateway_installment_id":"sample gateway installment id","gateway":"sample gateway","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","archived_at":"2026-01-15T10:30:00.000Z","first_due_date":"2026-01-15","projected_schedule":[{"number":1,"due_date":"2026-01-15","amount":149.9}],"payment_book":{"state":"pending","degraded":true,"stale":true,"refresh_failed":true,"stalled":true,"url":"https://example.com/resource"},"allowed_actions":{"payment_book":true,"send_to_conversation":true,"send_installment":true,"update":true,"cancel":true,"destroy":true,"refund":true,"update_notification_preferences":true},"payment_book_degraded":true,"conversation_display_id":1,"contact_name":"sample contact name","next_due_date":"2026-01-15","gateway_payment_book":{"url":"https://example.com/resource"},"open_installments_count":5,"financial_evidence":{},"notification_preferences":{"payment_charge_paid":false,"installment_plan_completed":true}},"can_undo_mark_as_paid":true,"can_refund":true}}}}},"422":{"description":"Unprocessable Entity (settled charge, or the gateway rejected the edit)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"put":{"tags":["Payment Charges"],"operationId":"auto_put_api_v1_accounts_account_id_payments_charges_id","summary":"Update charges","description":"Updates the charge identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"payments_connection_id":{"type":"integer"},"contact_id":{"type":"integer"},"organization_id":{"type":"integer"},"organization_name":{"type":["string","null"]},"conversation_id":{"type":"integer"},"crm_item_id":{"type":"integer"},"crm_item_title":{"type":["string","null"]},"payments_subscription_id":{"type":"integer"},"gateway_charge_id":{"type":"integer"},"external_reference":{"type":"string"},"billing_type":{"type":"string","enum":["pix","boleto","credit_card","hosted_link","undefined","debit_card"],"description":"How the payer is charged. `undefined` lets the payer pick on the hosted invoice."},"status":{"type":"string","enum":["pending","awaiting_payment","confirmed","paid","overdue","refunded","partially_refunded","canceled","failed"]},"amount":{"type":"number"},"amount_refunded":{"type":"string"},"subtotal_amount":{"type":"number"},"discount":{"type":"string"},"discount_type":{"type":"string","enum":["fixed","percent"],"description":"Whether the discount is an absolute amount or a percentage."},"discount_reason":{"type":"string"},"currency":{"type":"string"},"original_amount":{"type":"number"},"original_currency":{"type":"string"},"fx_rate":{"type":"number"},"installments":{"type":"string"},"installment_mode":{"type":"string","enum":["absorb","passthrough"]},"installment_interest_rate":{"type":["number","null"]},"due_date":{"type":"string","format":"date"},"paid_at":{"type":"string","format":"date-time"},"refunded_at":{"type":"string","format":"date-time"},"description":{"type":"string"},"hosted_url":{"type":"string"},"pix_payload":{"type":"string"},"pix_qr_base64":{"type":"string"},"boleto_url":{"type":"string"},"metadata":{"type":"object","additionalProperties":true,"description":"Free-form metadata bag; the key set depends on the record and context."},"gateway_options":{"type":["string","null"]},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"settled":{"type":"boolean"},"archived_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"contact_name":{"type":"string"},"contact_email":{"type":"string","format":"email"},"payer_email":{"type":"string","format":"email"},"contact_phone_number":{"type":"string"},"gateway_customer_id":{"type":"integer"},"gateway":{"type":["string","null"]},"can_mark_as_paid":{"type":["boolean","null"]},"manually_paid":{"type":["string","null"]},"conversation_display_id":{"type":["integer","null"]},"line_items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"catalog_variant_id":{"type":"integer"},"catalog_product_id":{"type":"integer"},"name_snapshot":{"type":"string"},"quantity":{"type":"string"},"unit_price":{"type":"number"},"discount":{"type":"string"},"discount_type":{"type":"string","enum":["fixed","percent"],"description":"Whether the discount is an absolute amount or a percentage."},"line_total":{"type":"number"},"currency":{"type":"string"},"position":{"type":"integer"},"metadata":{"type":"object","additionalProperties":true,"description":"Free-form metadata bag; the key set depends on the record and context."}}}},"installment_plan_id":{"type":"integer"},"installment_number":{"type":"string"},"installments_count":{"type":["integer","null"]},"installment_plan":{"type":"object","properties":{"extract":{"type":"string"},"open_installments_count":{"type":"integer"},"notification_preferences":{"type":"string"},"gateway":{"type":["string","null"]},"conversation_display_id":{"type":["integer","null"]},"contact_name":{"type":"string"},"next_due_date":{"type":["string","null"],"format":"date"},"projected_schedule":{"type":"string"},"materialized_installment_numbers":{"type":"array","items":{"type":"string"}},"payment_book_degraded":{"type":"boolean"},"payment_book":{"type":"object","properties":{"state":{"type":"string"},"degraded":{"type":"boolean"},"stale":{"type":"boolean"},"refresh_failed":{"type":"boolean"},"stalled":{"type":"string"},"url":{"type":"string"}}},"financial_evidence":{"type":"object","properties":{"set":{"type":"string"}}},"gateway_payment_book":{"type":"object","properties":{"url":{"type":"string"}}},"allowed_actions":{"type":"object","properties":{"update_notification_preferences":{"type":"string"},"payment_book":{"type":"string"},"send_to_conversation":{"type":"string"},"send_installment":{"type":"string"},"update":{"type":"boolean"},"cancel":{"type":"string"},"destroy":{"type":"boolean"},"refund":{"type":"string"}}}}},"can_undo_mark_as_paid":{"type":["boolean","null"]},"can_refund":{"type":["boolean","null"]}}}}},"example":{"payload":{"id":1,"account_id":1,"payments_connection_id":1,"contact_id":1,"organization_id":1,"organization_name":"sample organization name","conversation_id":1,"crm_item_id":1,"crm_item_title":"sample crm item title","payments_subscription_id":1,"gateway_charge_id":1,"external_reference":"sample external reference","billing_type":"pix","status":"pending","amount":149.9,"amount_refunded":"sample amount refunded","subtotal_amount":149.9,"discount":"sample discount","discount_type":"fixed","discount_reason":"sample discount reason","currency":"BRL","original_amount":149.9,"original_currency":"sample original currency","fx_rate":12.5,"installments":"sample installments","installment_mode":"absorb","installment_interest_rate":12.5,"due_date":"2026-01-15","paid_at":"2026-01-15T10:30:00.000Z","refunded_at":"2026-01-15T10:30:00.000Z","description":"A short description.","hosted_url":"https://example.com/resource","pix_payload":"sample pix payload","pix_qr_base64":"sample pix qr base64","boleto_url":"https://example.com/resource","metadata":{},"gateway_options":"sample gateway options","custom_attributes":{},"settled":true,"archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","contact_name":"sample contact name","contact_email":"agent@example.com","payer_email":"agent@example.com","contact_phone_number":"+5511999998888","gateway_customer_id":1,"gateway":"sample gateway","can_mark_as_paid":true,"manually_paid":"sample manually paid","conversation_display_id":1,"line_items":[{"id":1,"catalog_variant_id":1,"catalog_product_id":1,"name_snapshot":"sample name snapshot","quantity":"sample quantity","unit_price":149.9,"discount":"sample discount","discount_type":"fixed","line_total":149.9,"currency":"BRL","position":1,"metadata":{}}],"installment_plan_id":1,"installment_number":"sample installment number","installments_count":5,"installment_plan":{"extract":"sample extract","open_installments_count":5,"notification_preferences":"sample notification preferences","gateway":"sample gateway","conversation_display_id":1,"contact_name":"sample contact name","next_due_date":"2026-01-15","projected_schedule":"sample projected schedule","materialized_installment_numbers":["sample materialized installment number"],"payment_book_degraded":true,"payment_book":{"state":"active","degraded":true,"stale":true,"refresh_failed":true,"stalled":"sample stalled","url":"https://example.com/resource"},"financial_evidence":{"set":"sample set"},"gateway_payment_book":{"url":"https://example.com/resource"},"allowed_actions":{"update_notification_preferences":"sample update notification preferences","payment_book":"sample payment book","send_to_conversation":"sample send to conversation","send_installment":"sample send installment","update":true,"cancel":"sample cancel","destroy":true,"refund":"sample refund"}},"can_undo_mark_as_paid":true,"can_refund":true}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"charge":{"type":"object","properties":{"amount":{"type":"number"},"due_date":{"type":"string","format":"date"},"description":{"type":"string"},"billing_type":{"type":"string","enum":["pix","boleto","credit_card","hosted_link","undefined","debit_card"],"description":"How the payer is charged. `undefined` lets the payer pick on the hosted invoice."},"discount":{"type":"string"},"discount_type":{"type":"string","enum":["fixed","percent"],"description":"Whether the discount is an absolute amount or a percentage."},"discount_reason":{"type":"string"},"gateway_options":{"type":"object","additionalProperties":true,"description":"Free-form object."}}}},"required":["charge"]},"example":{"charge":{"amount":149.9,"due_date":"2026-01-15","description":"A short description.","billing_type":"pix","discount":"sample discount","discount_type":"fixed","discount_reason":"sample discount reason","gateway_options":{}}}}}}}},"/api/v1/accounts/{account_id}/payments/charges/{id}/refund":{"post":{"tags":["Payment Charges"],"operationId":"refund-payment-charge","summary":"Refund a settled charge in full or in part","description":"Administrator-only financial operation. Calls the charge's configured gateway, accumulates the refunded amount, records an immutable audit event and synchronizes the linked CRM order. Omit amount to refund the full remaining balance. Never expose this operation to autonomous agents.","security":[{"userApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"id","in":"path","required":true,"schema":{"type":"number"}},{"name":"X-Idempotency-Key","in":"header","required":false,"description":"Stable refund intention across retries; a new intention requires a distinct key. A replay returns current charge without a new gateway POST. Changed amount with the same key is rejected. Without a key, a conservative amount/remaining identity is used.","schema":{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9._:-]+$"},"example":"refund-123-attempt-1"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"number","exclusiveMinimum":0,"description":"Omit to refund the full remaining balance."},"reason":{"type":"string","maxLength":1000,"description":"Optional operator justification retained in the audit event."}}},"example":{"amount":149.9,"reason":"Sample reason."}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"$ref":"#/components/schemas/payment_charge"}}},"example":{"payload":{"id":1,"account_id":1,"payments_connection_id":1,"contact_id":1,"organization_id":1,"organization_name":"sample organization name","conversation_id":1,"crm_item_id":1,"crm_item_title":"sample crm item title","payments_subscription_id":1,"gateway_charge_id":"sample gateway charge id","external_reference":"sample external reference","billing_type":"pix","status":"pending","amount":149.9,"amount_refunded":12.5,"subtotal_amount":149.9,"discount":12.5,"discount_type":"fixed","discount_reason":"sample discount reason","currency":"BRL","original_amount":149.9,"original_currency":"sample original currency","fx_rate":12.5,"installments":1,"installment_mode":"absorb","installment_interest_rate":12.5,"due_date":"2026-01-15","paid_at":"2026-01-15T10:30:00.000Z","refunded_at":"2026-01-15T10:30:00.000Z","description":"A short description.","hosted_url":"https://example.com/resource","pix_payload":"sample pix payload","pix_qr_base64":"sample pix qr base64","boleto_url":"https://example.com/resource","metadata":{"origin":"external_gateway"},"gateway_options":{},"custom_attributes":{},"settled":true,"contact_name":"sample contact name","contact_email":"agent@example.com","payer_email":"agent@example.com","contact_phone_number":"+5511999998888","gateway_customer_id":"sample gateway customer id","gateway":"hotmart","can_mark_as_paid":true,"manually_paid":true,"conversation_display_id":1,"archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","line_items":[{"id":1,"catalog_variant_id":1,"catalog_product_id":1,"name_snapshot":"sample name snapshot","quantity":12.5,"unit_price":149.9,"discount":12.5,"discount_type":"fixed","line_total":149.9,"currency":"BRL","position":1,"metadata":{}}],"installment_plan_id":1,"installment_number":1,"installments_count":5,"installment_plan":{"id":1,"account_id":1,"payments_connection_id":1,"contact_id":1,"organization_id":1,"conversation_id":1,"crm_item_id":1,"payments_subscription_id":1,"installments_count":5,"paid_count":5,"total_amount":"sample total amount","installment_amount":"sample installment amount","last_installment_amount":"sample last installment amount","paid_amount":"sample paid amount","refunded_amount":"sample refunded amount","installment_interest_rate":"sample installment interest rate","strategy":"native_installment","status":"pending","billing_type":"pix","cycle":"weekly","installment_mode":"absorb","currency":"BRL","gateway_installment_id":"sample gateway installment id","gateway":"sample gateway","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","archived_at":"2026-01-15T10:30:00.000Z","first_due_date":"2026-01-15","projected_schedule":[{"number":1,"due_date":"2026-01-15","amount":149.9}],"payment_book":{"state":"pending","degraded":true,"stale":true,"refresh_failed":true,"stalled":true,"url":"https://example.com/resource"},"allowed_actions":{"payment_book":true,"send_to_conversation":true,"send_installment":true,"update":true,"cancel":true,"destroy":true,"refund":true,"update_notification_preferences":true},"payment_book_degraded":true,"conversation_display_id":1,"contact_name":"sample contact name","next_due_date":"2026-01-15","gateway_payment_book":{"url":"https://example.com/resource"},"open_installments_count":5,"financial_evidence":{},"notification_preferences":{"payment_charge_paid":false,"installment_plan_completed":true}},"can_undo_mark_as_paid":true,"can_refund":true}}}}},"422":{"description":"Refund refused or uncertain. Only an explicit not_started or definitively_rejected outcome proves safe abandonment; missing outcome remains uncertain.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"outcome":{"type":"string","enum":["not_started","definitively_rejected","uncertain","completed"]},"error_code":{"type":"string","enum":["refund_operation_not_started","refund_operation_definitively_rejected","refund_operation_uncertain","refund_operation_completed"]}}},"example":{"error":"The refund outcome is uncertain; reconcile before retrying.","outcome":"uncertain","error_code":"refund_operation_uncertain"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/payments/charges/{id}/cancel":{"post":{"tags":["Payment Charges"],"operationId":"cancel-payment-charge","summary":"Cancel a pending charge at the gateway","description":"Administrator-only financial operation for pending, awaiting-payment or overdue charges. Cancels the provider charge, records an immutable audit event and synchronizes the linked CRM order.","security":[{"userApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"id","in":"path","required":true,"schema":{"type":"number"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","maxLength":1000,"description":"Optional operator justification retained in the audit event."}}},"example":{"reason":"Sample reason."}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"$ref":"#/components/schemas/payment_charge"}}},"example":{"payload":{"id":1,"account_id":1,"payments_connection_id":1,"contact_id":1,"organization_id":1,"organization_name":"sample organization name","conversation_id":1,"crm_item_id":1,"crm_item_title":"sample crm item title","payments_subscription_id":1,"gateway_charge_id":"sample gateway charge id","external_reference":"sample external reference","billing_type":"pix","status":"pending","amount":149.9,"amount_refunded":12.5,"subtotal_amount":149.9,"discount":12.5,"discount_type":"fixed","discount_reason":"sample discount reason","currency":"BRL","original_amount":149.9,"original_currency":"sample original currency","fx_rate":12.5,"installments":1,"installment_mode":"absorb","installment_interest_rate":12.5,"due_date":"2026-01-15","paid_at":"2026-01-15T10:30:00.000Z","refunded_at":"2026-01-15T10:30:00.000Z","description":"A short description.","hosted_url":"https://example.com/resource","pix_payload":"sample pix payload","pix_qr_base64":"sample pix qr base64","boleto_url":"https://example.com/resource","metadata":{"origin":"external_gateway"},"gateway_options":{},"custom_attributes":{},"settled":true,"contact_name":"sample contact name","contact_email":"agent@example.com","payer_email":"agent@example.com","contact_phone_number":"+5511999998888","gateway_customer_id":"sample gateway customer id","gateway":"hotmart","can_mark_as_paid":true,"manually_paid":true,"conversation_display_id":1,"archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","line_items":[{"id":1,"catalog_variant_id":1,"catalog_product_id":1,"name_snapshot":"sample name snapshot","quantity":12.5,"unit_price":149.9,"discount":12.5,"discount_type":"fixed","line_total":149.9,"currency":"BRL","position":1,"metadata":{}}],"installment_plan_id":1,"installment_number":1,"installments_count":5,"installment_plan":{"id":1,"account_id":1,"payments_connection_id":1,"contact_id":1,"organization_id":1,"conversation_id":1,"crm_item_id":1,"payments_subscription_id":1,"installments_count":5,"paid_count":5,"total_amount":"sample total amount","installment_amount":"sample installment amount","last_installment_amount":"sample last installment amount","paid_amount":"sample paid amount","refunded_amount":"sample refunded amount","installment_interest_rate":"sample installment interest rate","strategy":"native_installment","status":"pending","billing_type":"pix","cycle":"weekly","installment_mode":"absorb","currency":"BRL","gateway_installment_id":"sample gateway installment id","gateway":"sample gateway","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","archived_at":"2026-01-15T10:30:00.000Z","first_due_date":"2026-01-15","projected_schedule":[{"number":1,"due_date":"2026-01-15","amount":149.9}],"payment_book":{"state":"pending","degraded":true,"stale":true,"refresh_failed":true,"stalled":true,"url":"https://example.com/resource"},"allowed_actions":{"payment_book":true,"send_to_conversation":true,"send_installment":true,"update":true,"cancel":true,"destroy":true,"refund":true,"update_notification_preferences":true},"payment_book_degraded":true,"conversation_display_id":1,"contact_name":"sample contact name","next_due_date":"2026-01-15","gateway_payment_book":{"url":"https://example.com/resource"},"open_installments_count":5,"financial_evidence":{},"notification_preferences":{"payment_charge_paid":false,"installment_plan_completed":true}},"can_undo_mark_as_paid":true,"can_refund":true}}}}},"422":{"description":"Unsupported gateway or a status that can no longer be canceled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/payments/charges/{id}/archive":{"post":{"tags":["Payment Charges"],"operationId":"archive-payment-charge","summary":"Archive a charge (soft delete)","security":[{"userApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"id","in":"path","required":true,"schema":{"type":"number"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"$ref":"#/components/schemas/payment_charge"}}},"example":{"payload":{"id":1,"account_id":1,"payments_connection_id":1,"contact_id":1,"organization_id":1,"organization_name":"sample organization name","conversation_id":1,"crm_item_id":1,"crm_item_title":"sample crm item title","payments_subscription_id":1,"gateway_charge_id":"sample gateway charge id","external_reference":"sample external reference","billing_type":"pix","status":"pending","amount":149.9,"amount_refunded":12.5,"subtotal_amount":149.9,"discount":12.5,"discount_type":"fixed","discount_reason":"sample discount reason","currency":"BRL","original_amount":149.9,"original_currency":"sample original currency","fx_rate":12.5,"installments":1,"installment_mode":"absorb","installment_interest_rate":12.5,"due_date":"2026-01-15","paid_at":"2026-01-15T10:30:00.000Z","refunded_at":"2026-01-15T10:30:00.000Z","description":"A short description.","hosted_url":"https://example.com/resource","pix_payload":"sample pix payload","pix_qr_base64":"sample pix qr base64","boleto_url":"https://example.com/resource","metadata":{"origin":"external_gateway"},"gateway_options":{},"custom_attributes":{},"settled":true,"contact_name":"sample contact name","contact_email":"agent@example.com","payer_email":"agent@example.com","contact_phone_number":"+5511999998888","gateway_customer_id":"sample gateway customer id","gateway":"hotmart","can_mark_as_paid":true,"manually_paid":true,"conversation_display_id":1,"archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","line_items":[{"id":1,"catalog_variant_id":1,"catalog_product_id":1,"name_snapshot":"sample name snapshot","quantity":12.5,"unit_price":149.9,"discount":12.5,"discount_type":"fixed","line_total":149.9,"currency":"BRL","position":1,"metadata":{}}],"installment_plan_id":1,"installment_number":1,"installments_count":5,"installment_plan":{"id":1,"account_id":1,"payments_connection_id":1,"contact_id":1,"organization_id":1,"conversation_id":1,"crm_item_id":1,"payments_subscription_id":1,"installments_count":5,"paid_count":5,"total_amount":"sample total amount","installment_amount":"sample installment amount","last_installment_amount":"sample last installment amount","paid_amount":"sample paid amount","refunded_amount":"sample refunded amount","installment_interest_rate":"sample installment interest rate","strategy":"native_installment","status":"pending","billing_type":"pix","cycle":"weekly","installment_mode":"absorb","currency":"BRL","gateway_installment_id":"sample gateway installment id","gateway":"sample gateway","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","archived_at":"2026-01-15T10:30:00.000Z","first_due_date":"2026-01-15","projected_schedule":[{"number":1,"due_date":"2026-01-15","amount":149.9}],"payment_book":{"state":"pending","degraded":true,"stale":true,"refresh_failed":true,"stalled":true,"url":"https://example.com/resource"},"allowed_actions":{"payment_book":true,"send_to_conversation":true,"send_installment":true,"update":true,"cancel":true,"destroy":true,"refund":true,"update_notification_preferences":true},"payment_book_degraded":true,"conversation_display_id":1,"contact_name":"sample contact name","next_due_date":"2026-01-15","gateway_payment_book":{"url":"https://example.com/resource"},"open_installments_count":5,"financial_evidence":{},"notification_preferences":{"payment_charge_paid":false,"installment_plan_completed":true}},"can_undo_mark_as_paid":true,"can_refund":true}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}},"description":"Archive a charge (soft delete). Submits the request payload to the Archive resource and returns the result."}},"/api/v1/accounts/{account_id}/payments/charges/{id}/restore":{"post":{"tags":["Payment Charges"],"operationId":"restore-payment-charge","summary":"Restore an archived charge","security":[{"userApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"id","in":"path","required":true,"schema":{"type":"number"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"$ref":"#/components/schemas/payment_charge"}}},"example":{"payload":{"id":1,"account_id":1,"payments_connection_id":1,"contact_id":1,"organization_id":1,"organization_name":"sample organization name","conversation_id":1,"crm_item_id":1,"crm_item_title":"sample crm item title","payments_subscription_id":1,"gateway_charge_id":"sample gateway charge id","external_reference":"sample external reference","billing_type":"pix","status":"pending","amount":149.9,"amount_refunded":12.5,"subtotal_amount":149.9,"discount":12.5,"discount_type":"fixed","discount_reason":"sample discount reason","currency":"BRL","original_amount":149.9,"original_currency":"sample original currency","fx_rate":12.5,"installments":1,"installment_mode":"absorb","installment_interest_rate":12.5,"due_date":"2026-01-15","paid_at":"2026-01-15T10:30:00.000Z","refunded_at":"2026-01-15T10:30:00.000Z","description":"A short description.","hosted_url":"https://example.com/resource","pix_payload":"sample pix payload","pix_qr_base64":"sample pix qr base64","boleto_url":"https://example.com/resource","metadata":{"origin":"external_gateway"},"gateway_options":{},"custom_attributes":{},"settled":true,"contact_name":"sample contact name","contact_email":"agent@example.com","payer_email":"agent@example.com","contact_phone_number":"+5511999998888","gateway_customer_id":"sample gateway customer id","gateway":"hotmart","can_mark_as_paid":true,"manually_paid":true,"conversation_display_id":1,"archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","line_items":[{"id":1,"catalog_variant_id":1,"catalog_product_id":1,"name_snapshot":"sample name snapshot","quantity":12.5,"unit_price":149.9,"discount":12.5,"discount_type":"fixed","line_total":149.9,"currency":"BRL","position":1,"metadata":{}}],"installment_plan_id":1,"installment_number":1,"installments_count":5,"installment_plan":{"id":1,"account_id":1,"payments_connection_id":1,"contact_id":1,"organization_id":1,"conversation_id":1,"crm_item_id":1,"payments_subscription_id":1,"installments_count":5,"paid_count":5,"total_amount":"sample total amount","installment_amount":"sample installment amount","last_installment_amount":"sample last installment amount","paid_amount":"sample paid amount","refunded_amount":"sample refunded amount","installment_interest_rate":"sample installment interest rate","strategy":"native_installment","status":"pending","billing_type":"pix","cycle":"weekly","installment_mode":"absorb","currency":"BRL","gateway_installment_id":"sample gateway installment id","gateway":"sample gateway","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","archived_at":"2026-01-15T10:30:00.000Z","first_due_date":"2026-01-15","projected_schedule":[{"number":1,"due_date":"2026-01-15","amount":149.9}],"payment_book":{"state":"pending","degraded":true,"stale":true,"refresh_failed":true,"stalled":true,"url":"https://example.com/resource"},"allowed_actions":{"payment_book":true,"send_to_conversation":true,"send_installment":true,"update":true,"cancel":true,"destroy":true,"refund":true,"update_notification_preferences":true},"payment_book_degraded":true,"conversation_display_id":1,"contact_name":"sample contact name","next_due_date":"2026-01-15","gateway_payment_book":{"url":"https://example.com/resource"},"open_installments_count":5,"financial_evidence":{},"notification_preferences":{"payment_charge_paid":false,"installment_plan_completed":true}},"can_undo_mark_as_paid":true,"can_refund":true}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}},"description":"Restore an archived charge. Submits the request payload to the Restore resource and returns the result."}},"/api/v1/accounts/{account_id}/payments/charges/{id}/send_to_conversation":{"post":{"tags":["Payment Charges"],"operationId":"send-payment-charge-to-conversation","summary":"Send the charge into a conversation (rich card + PIX/boleto codes as separate copyable messages)","description":"Posts the charge into the conversation (addressed by its display id and resolved inside the account) and links the charge to it. Human callers send as themselves. Bot callers must authenticate as the active bot bound to the conversation's inbox; the messages are then authored by that bot. Any other bot, or a user credential asserting bot authorship, is refused.","security":[{"userApiKey":[]},{"agentBotApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"X-Chatwoot-Message-Author","in":"header","required":false,"schema":{"type":"string","enum":["agent_bot"]},"description":"Optional assertion requiring authenticated AgentBot credentials. This header alone does not authenticate a caller."},{"name":"id","in":"path","required":true,"schema":{"type":"number"}},{"name":"X-Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Stable key for this charge-delivery sequence. Each summary, interactive, media and copy-code step receives a deterministic sub-key, so retrying fills missing steps without duplicating ones already created."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"conversation_id":{"type":"number","description":"Conversation display_id."}},"required":["conversation_id"]},"example":{"conversation_id":1}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"$ref":"#/components/schemas/payment_charge"}}},"example":{"payload":{"id":1,"account_id":1,"payments_connection_id":1,"contact_id":1,"organization_id":1,"organization_name":"sample organization name","conversation_id":1,"crm_item_id":1,"crm_item_title":"sample crm item title","payments_subscription_id":1,"gateway_charge_id":"sample gateway charge id","external_reference":"sample external reference","billing_type":"pix","status":"pending","amount":149.9,"amount_refunded":12.5,"subtotal_amount":149.9,"discount":12.5,"discount_type":"fixed","discount_reason":"sample discount reason","currency":"BRL","original_amount":149.9,"original_currency":"sample original currency","fx_rate":12.5,"installments":1,"installment_mode":"absorb","installment_interest_rate":12.5,"due_date":"2026-01-15","paid_at":"2026-01-15T10:30:00.000Z","refunded_at":"2026-01-15T10:30:00.000Z","description":"A short description.","hosted_url":"https://example.com/resource","pix_payload":"sample pix payload","pix_qr_base64":"sample pix qr base64","boleto_url":"https://example.com/resource","metadata":{"origin":"external_gateway"},"gateway_options":{},"custom_attributes":{},"settled":true,"contact_name":"sample contact name","contact_email":"agent@example.com","payer_email":"agent@example.com","contact_phone_number":"+5511999998888","gateway_customer_id":"sample gateway customer id","gateway":"hotmart","can_mark_as_paid":true,"manually_paid":true,"conversation_display_id":1,"archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","line_items":[{"id":1,"catalog_variant_id":1,"catalog_product_id":1,"name_snapshot":"sample name snapshot","quantity":12.5,"unit_price":149.9,"discount":12.5,"discount_type":"fixed","line_total":149.9,"currency":"BRL","position":1,"metadata":{}}],"installment_plan_id":1,"installment_number":1,"installments_count":5,"installment_plan":{"id":1,"account_id":1,"payments_connection_id":1,"contact_id":1,"organization_id":1,"conversation_id":1,"crm_item_id":1,"payments_subscription_id":1,"installments_count":5,"paid_count":5,"total_amount":"sample total amount","installment_amount":"sample installment amount","last_installment_amount":"sample last installment amount","paid_amount":"sample paid amount","refunded_amount":"sample refunded amount","installment_interest_rate":"sample installment interest rate","strategy":"native_installment","status":"pending","billing_type":"pix","cycle":"weekly","installment_mode":"absorb","currency":"BRL","gateway_installment_id":"sample gateway installment id","gateway":"sample gateway","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","archived_at":"2026-01-15T10:30:00.000Z","first_due_date":"2026-01-15","projected_schedule":[{"number":1,"due_date":"2026-01-15","amount":149.9}],"payment_book":{"state":"pending","degraded":true,"stale":true,"refresh_failed":true,"stalled":true,"url":"https://example.com/resource"},"allowed_actions":{"payment_book":true,"send_to_conversation":true,"send_installment":true,"update":true,"cancel":true,"destroy":true,"refund":true,"update_notification_preferences":true},"payment_book_degraded":true,"conversation_display_id":1,"contact_name":"sample contact name","next_due_date":"2026-01-15","gateway_payment_book":{"url":"https://example.com/resource"},"open_installments_count":5,"financial_evidence":{},"notification_preferences":{"payment_charge_paid":false,"installment_plan_completed":true}},"can_undo_mark_as_paid":true,"can_refund":true}}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/payments/charges/{id}/events":{"get":{"tags":["Payment Charges"],"operationId":"list-payment-charge-events","summary":"List a charge lifecycle / audit events","security":[{"userApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"id","in":"path","required":true,"schema":{"type":"number"}},{"name":"page","in":"query","required":false,"description":"Page of charge events, newest first.","schema":{"type":"integer","default":1},"example":1}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"$ref":"#/components/schemas/payment_charge_event"}},"meta":{"type":"object","properties":{"count":{"type":"number"},"current_page":{"type":"number"},"total_pages":{"type":"number"},"per_page":{"type":"number"},"has_more":{"type":"boolean"}}}}},"example":{"payload":[{"id":1,"payments_charge_id":1,"event_type":"created","user_id":1,"actor":{"type":"user","id":1,"name":"Sample Name"},"metadata":{},"occurred_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z"}],"meta":{"count":5,"current_page":12.5,"total_pages":12.5,"per_page":12.5,"has_more":true}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}},"description":"List a charge lifecycle / audit events. Returns Events data for the current context."}},"/api/v1/accounts/{account_id}/payments/charges/bulk_destroy":{"post":{"tags":["Payment Charges"],"operationId":"bulk-delete-payment-charges","summary":"Bulk delete charges (max 500/request; settled charges are skipped)","description":"Best-effort and account-scoped over the archived bin. Every normalized requested id appears in destroyed_ids or failed_ids; settled, kept, absent and foreign ids are reported only as failed.","security":[{"userApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/account_id"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"charge_ids":{"type":"array","minItems":1,"maxItems":500,"uniqueItems":true,"items":{"type":"integer","minimum":1}}},"required":["charge_ids"]},"example":{"charge_ids":[1]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","description":"{ destroyed_ids: [number] }","additionalProperties":{"type":"array","items":{"type":"integer"}}},"meta":{"type":"object","description":"{ destroyed: number, failed: number, failed_ids: [number] }","additionalProperties":true}}},"example":{"payload":{},"meta":{}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"422":{"description":"Unprocessable Entity (invalid ids or over the 500-id bulk cap)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/payments/charges/bulk_archive":{"post":{"tags":["Payment Charges"],"operationId":"bulk-archive-payment-charges","summary":"Bulk archive charges (max 500/request)","description":"Best-effort and account-scoped. Every normalized requested id appears in exactly one result list: archived_ids when processed or failed_ids otherwise, without disclosing why an unavailable id failed.","security":[{"userApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/account_id"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"charge_ids":{"type":"array","minItems":1,"maxItems":500,"uniqueItems":true,"items":{"type":"integer","minimum":1}}},"required":["charge_ids"]},"example":{"charge_ids":[1]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","description":"{ archived_ids: [number] }","additionalProperties":{"type":"array","items":{"type":"integer"}}},"meta":{"type":"object","description":"{ archived: number, failed: number, failed_ids: [number] }","additionalProperties":true}}},"example":{"payload":{},"meta":{}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"422":{"description":"Unprocessable Entity (invalid ids or over the 500-id bulk cap)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/payments/charges/preview":{"parameters":[{"$ref":"#/components/parameters/account_id"}],"post":{"tags":["Payment Charges"],"operationId":"preview-payment-charge","summary":"Preview the settlement amount (FX) without persisting","security":[{"userApiKey":[]}],"description":"Resolve the settlement amount + converted line items for a prospective charge WITHOUT persisting it, so the composer total matches the eventual charge exactly (no client-side FX drift). The connection is resolved like create: explicit id, then the default active one, then any active one. A missing FX rate is surfaced as 422 (same as create).","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["charge"],"properties":{"charge":{"type":"object","properties":{"connection_id":{"type":"number","description":"Gateway connection; defaults to the account default."},"source":{"type":"string","enum":["manual","catalog","order","deal"],"default":"manual"},"amount":{"type":"number","description":"Major units (decimal). Ignored when source is catalog/order/deal."},"currency":{"type":"string","example":"BRL"},"crm_item_id":{"type":"number","description":"When source=deal (quote total)."},"catalog_variant_ids":{"type":"array","items":{"type":"number"},"description":"When source=catalog."},"order_items":{"type":"array","minItems":1,"description":"Exact customer-agreed cart lines required when source=order. The preview applies the same quantity, price, currency and discount rules used by charge creation.","items":{"type":"object","properties":{"catalog_product_id":{"type":"integer","minimum":1},"catalog_variant_id":{"type":"integer","minimum":1},"name":{"type":"string"},"quantity":{"type":"number","exclusiveMinimum":0},"unit_price":{"type":"number","minimum":0},"currency":{"type":"string","example":"BRL"},"discount":{"type":"number","minimum":0,"default":0},"discount_type":{"type":"string","enum":["fixed","percent"],"default":"fixed","description":"Whether the discount is an absolute amount or a percentage."}}}}}}}},"example":{"charge":{"connection_id":1,"source":"manual","amount":149.9,"currency":"BRL","crm_item_id":1,"catalog_variant_ids":[1],"order_items":[{"catalog_product_id":1,"catalog_variant_id":1,"name":"Sample Name","quantity":12.5,"unit_price":149.9,"currency":"BRL","discount":0,"discount_type":"fixed"}]}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","required":["currency","subtotal","discount","discount_type","discount_reason","total","original_amount","original_currency","fx_rate","line_items"],"properties":{"currency":{"type":"string","description":"Settlement currency of the resolved connection."},"subtotal":{"type":"number","minimum":0,"description":"Gross settlement-currency total before the charge-level discount."},"discount":{"type":"number","minimum":0},"discount_type":{"type":"string","enum":["fixed","percent"],"description":"Whether the discount is an absolute amount or a percentage."},"discount_reason":{"type":["string","null"]},"total":{"type":"number","description":"Settlement-currency total the charge would be created with."},"original_amount":{"type":["number","null"]},"original_currency":{"type":["string","null"]},"fx_rate":{"type":["number","null"]},"line_items":{"type":"array","items":{"type":"object","required":["catalog_variant_id","catalog_product_id","name_snapshot","quantity","unit_price","discount","discount_type","line_total","currency","original_unit_price","original_currency","fx_rate"],"properties":{"catalog_variant_id":{"type":["integer","null"],"minimum":1},"catalog_product_id":{"type":["integer","null"],"minimum":1},"name_snapshot":{"type":["string","null"]},"quantity":{"type":"number","exclusiveMinimum":0},"unit_price":{"type":"number","minimum":0},"discount":{"type":"number","minimum":0},"discount_type":{"type":"string","enum":["fixed","percent"],"description":"Whether the discount is an absolute amount or a percentage."},"line_total":{"type":"number","minimum":0},"currency":{"type":"string"},"original_unit_price":{"type":["string","null"],"description":"Decimal source-currency unit price retained in fixed notation for audit."},"original_currency":{"type":["string","null"]},"fx_rate":{"type":["string","null"],"description":"Decimal per-line exchange rate retained in fixed notation for audit."}}}}}}}},"example":{"payload":{"currency":"BRL","subtotal":149.9,"discount":12.5,"discount_type":"fixed","discount_reason":"sample discount reason","total":149.9,"original_amount":149.9,"original_currency":"sample original currency","fx_rate":12.5,"line_items":[{"catalog_variant_id":1,"catalog_product_id":1,"name_snapshot":"sample name snapshot","quantity":12.5,"unit_price":149.9,"discount":12.5,"discount_type":"fixed","line_total":149.9,"currency":"BRL","original_unit_price":"sample original unit price","original_currency":"sample original currency","fx_rate":"sample fx rate"}]}}}}},"422":{"description":"Unprocessable Entity (FX rate unavailable, or invalid source)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/payments/charges/bulk_restore":{"parameters":[{"$ref":"#/components/parameters/account_id"}],"post":{"tags":["Payment Charges"],"operationId":"bulk-restore-payment-charges","summary":"Bulk restore archived charges (max 500/request)","security":[{"userApiKey":[]}],"description":"Bring many archived charges back to the active list (body ids). Scoped to the archived bin — every normalized requested id appears in restored_ids or failed_ids. A kept, absent, foreign or failing id is reported only as failed, without disclosing why it was unavailable; the rest commit.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"charge_ids":{"type":"array","minItems":1,"maxItems":500,"uniqueItems":true,"items":{"type":"integer","minimum":1}}},"required":["charge_ids"]},"example":{"charge_ids":[1]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","description":"{ restored_ids: [number] }","additionalProperties":{"type":"array","items":{"type":"integer"}}},"meta":{"type":"object","description":"{ restored: number, failed: number, failed_ids: [number] }","additionalProperties":true}}},"example":{"payload":{},"meta":{}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"422":{"description":"Unprocessable Entity (invalid ids or over the 500-id bulk cap)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/payments/subscriptions":{"get":{"tags":["Payment Subscriptions"],"operationId":"list-payment-subscriptions","summary":"List / filter subscriptions (assinantes)","description":"Filters: status, contact_id, connection_id, archived, page.","security":[{"userApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"contact_id","in":"query","schema":{"type":"number"}},{"name":"status","in":"query","schema":{"type":"string"}},{"name":"page","in":"query","schema":{"type":"number"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"$ref":"#/components/schemas/payment_subscription"}},"meta":{"type":"object","properties":{"count":{"type":"number"},"current_page":{"type":"number"},"total_pages":{"type":"number"},"per_page":{"type":"number"},"has_more":{"type":"boolean"}}}}},"example":{"payload":[{"id":1,"account_id":1,"payments_connection_id":1,"contact_id":1,"conversation_id":1,"conversation_display_id":1,"payments_plan_id":1,"gateway_subscription_id":"sample gateway subscription id","status":"pending","cycle":"weekly","billing_type":"pix","amount":149.9,"subtotal_amount":149.9,"discount":12.5,"discount_type":"fixed","discount_reason":"sample discount reason","currency":"BRL","next_due_date":"2026-01-15","max_payments":1,"end_date":"2026-01-15","started_at":"2026-01-15T10:30:00.000Z","canceled_at":"2026-01-15T10:30:00.000Z","metadata":{},"contact_name":"sample contact name","gateway":"asaas","capabilities":{},"plan_name":"sample plan name","archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}],"meta":{"count":5,"current_page":12.5,"total_pages":12.5,"per_page":12.5,"has_more":true}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"post":{"tags":["Payment Subscriptions"],"operationId":"create-payment-subscription","summary":"Create a subscription (gateway-delegated recurrence)","description":"Persists a pending local subscription and its external reference before provider I/O. A replay with the same key and material payload returns or recovers the same subscription; different data is rejected and an uncertain gateway outcome is never blindly recreated.","security":[{"userApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"X-Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Stable per logical subscription (at most 255 UTF-8 bytes; no control characters). Preserve it across network retries; body idempotency_key is the fallback."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["subscription"],"properties":{"subscription":{"type":"object","properties":{"connection_id":{"type":"integer","minimum":1},"contact_id":{"type":"integer","minimum":1},"organization_id":{"type":"integer","minimum":1},"conversation_id":{"type":"integer","minimum":1,"description":"Optional conversation the subscription is sold in, addressed by its display id (internal id accepted as fallback) and resolved inside the account; an unknown or foreign conversation returns 404. Every charge the gateway generates for the subscription is linked to it, and it is part of the idempotency payload."},"plan_id":{"type":"number","description":"Optional account-scoped, non-archived local plan template. When present, its connection, amount, currency and cycle are authoritative; repeated request values must match exactly. This does not assert that a reusable plan already exists at the gateway."},"billing_type":{"type":"string","enum":["pix","boleto","credit_card","hosted_link"],"description":"Local classification. Mercado Pago pending preapproval uses hosted_link and lets the payer choose an available method on its approval page."},"amount":{"type":"number"},"currency":{"type":"string","example":"BRL"},"cycle":{"type":"string","enum":["weekly","biweekly","monthly","bimonthly","quarterly","semiannually","yearly"]},"description":{"type":"string"},"doc":{"type":"string"},"payer_email":{"type":"string","format":"email"},"next_due_date":{"type":"string","format":"date"},"max_payments":{"type":"integer","minimum":1,"description":"Asaas-only maximum number of billing cycles; capability-gated."},"end_date":{"type":"string","format":"date","description":"Asaas-only subscription end date, on or after next_due_date; capability-gated."},"back_url":{"type":"string","format":"uri","description":"Optional public HTTPS return URL for Mercado Pago approval. Defaults to this account's Payments subscriptions page."},"idempotency_key":{"type":"string","maxLength":255,"description":"Body alternative to X-Idempotency-Key (at most 255 UTF-8 bytes; no control characters). Reuse is accepted only for the exact same subscription payload."},"discount":{"type":"number","minimum":0,"description":"Fixed amount or percentage applied on every cycle."},"discount_type":{"type":"string","enum":["fixed","percent"],"default":"fixed","description":"Whether the discount is an absolute amount or a percentage."},"discount_reason":{"type":"string"},"metadata":{"type":"object","additionalProperties":true,"description":"Caller metadata copied to the local subscription; internal recovery keys are reserved."}},"required":["billing_type"],"allOf":[{"anyOf":[{"required":["contact_id"]},{"required":["organization_id"]}]},{"anyOf":[{"required":["plan_id"]},{"required":["amount","cycle"]}]}]}}},"example":{"subscription":{}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"$ref":"#/components/schemas/payment_subscription"}}},"example":{"payload":{"id":1,"account_id":1,"payments_connection_id":1,"contact_id":1,"conversation_id":1,"conversation_display_id":1,"payments_plan_id":1,"gateway_subscription_id":"sample gateway subscription id","status":"pending","cycle":"weekly","billing_type":"pix","amount":149.9,"subtotal_amount":149.9,"discount":12.5,"discount_type":"fixed","discount_reason":"sample discount reason","currency":"BRL","next_due_date":"2026-01-15","max_payments":1,"end_date":"2026-01-15","started_at":"2026-01-15T10:30:00.000Z","canceled_at":"2026-01-15T10:30:00.000Z","metadata":{},"contact_name":"sample contact name","gateway":"asaas","capabilities":{},"plan_name":"sample plan name","archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"The referenced conversation, connection, contact, organization or plan does not exist in this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/payments/subscriptions/{id}":{"get":{"tags":["Payment Subscriptions"],"operationId":"get-payment-subscription","summary":"Get a subscription","security":[{"userApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"id","in":"path","required":true,"schema":{"type":"number"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"$ref":"#/components/schemas/payment_subscription"}}},"example":{"payload":{"id":1,"account_id":1,"payments_connection_id":1,"contact_id":1,"conversation_id":1,"conversation_display_id":1,"payments_plan_id":1,"gateway_subscription_id":"sample gateway subscription id","status":"pending","cycle":"weekly","billing_type":"pix","amount":149.9,"subtotal_amount":149.9,"discount":12.5,"discount_type":"fixed","discount_reason":"sample discount reason","currency":"BRL","next_due_date":"2026-01-15","max_payments":1,"end_date":"2026-01-15","started_at":"2026-01-15T10:30:00.000Z","canceled_at":"2026-01-15T10:30:00.000Z","metadata":{},"contact_name":"sample contact name","gateway":"asaas","capabilities":{},"plan_name":"sample plan name","archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}},"description":"Get a subscription. Returns the requested Subscriptions resource."},"delete":{"tags":["Payment Subscriptions"],"operationId":"delete-payment-subscription","summary":"Delete a subscription","security":[{"userApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"id","in":"path","required":true,"schema":{"type":"number"}}],"responses":{"200":{"description":"Success"},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}},"description":"Delete a subscription. Removes the targeted Subscriptions resource."},"patch":{"tags":["Payment Subscriptions"],"operationId":"update-payment-subscription","summary":"Edit a subscription's recurring fields","security":[{"userApiKey":[]}],"description":"Edit amount/cycle/next-due-date/description at the gateway and locally (only the supplied fields are changed). Asaas also accepts an end date on or after the effective next charge date. Mercado Pago rejects a cycle change (the gateway error is surfaced as 422). Contact/connection/plan are immutable post-creation.","parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"id","in":"path","required":true,"schema":{"type":"number"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"subscription":{"type":"object","properties":{"amount":{"type":"number","description":"Major units (decimal)."},"currency":{"type":"string","example":"BRL"},"cycle":{"type":"string","enum":["weekly","biweekly","monthly","bimonthly","quarterly","semiannually","yearly"]},"next_due_date":{"type":"string","format":"date"},"end_date":{"type":"string","format":"date","description":"Asaas-only subscription end date, on or after the effective next_due_date; capability-gated."},"discount":{"type":"number","minimum":0,"description":"Fixed amount or percentage applied on every cycle."},"discount_type":{"type":"string","enum":["fixed","percent"],"description":"How the supplied or existing discount is interpreted."},"discount_reason":{"type":["string","null"],"description":"Operator justification required by connections configured to require a discount reason."},"description":{"type":"string"},"billing_type":{"type":"string","enum":["pix","boleto","credit_card","hosted_link","undefined","debit_card"],"description":"How the payer is charged. `undefined` lets the payer pick on the hosted invoice."}}}}},"example":{"subscription":{"amount":149.9,"currency":"BRL","cycle":"weekly","next_due_date":"2026-01-15","end_date":"2026-01-15","discount":12.5,"discount_type":"fixed","discount_reason":"sample discount reason","description":"A short description.","billing_type":"pix"}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"$ref":"#/components/schemas/payment_subscription"}}},"example":{"payload":{"id":1,"account_id":1,"payments_connection_id":1,"contact_id":1,"conversation_id":1,"conversation_display_id":1,"payments_plan_id":1,"gateway_subscription_id":"sample gateway subscription id","status":"pending","cycle":"weekly","billing_type":"pix","amount":149.9,"subtotal_amount":149.9,"discount":12.5,"discount_type":"fixed","discount_reason":"sample discount reason","currency":"BRL","next_due_date":"2026-01-15","max_payments":1,"end_date":"2026-01-15","started_at":"2026-01-15T10:30:00.000Z","canceled_at":"2026-01-15T10:30:00.000Z","metadata":{},"contact_name":"sample contact name","gateway":"asaas","capabilities":{},"plan_name":"sample plan name","archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}}},"422":{"description":"Unprocessable Entity (gateway rejected the edit, e.g. a Mercado Pago cycle change)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"put":{"tags":["Payment Subscriptions"],"operationId":"auto_put_api_v1_accounts_account_id_payments_subscriptions_id","summary":"Update subscriptions","description":"Updates the subscription identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"payments_connection_id":{"type":"integer"},"contact_id":{"type":"integer"},"organization_id":{"type":"integer"},"organization_name":{"type":["string","null"]},"conversation_id":{"type":"integer"},"conversation_display_id":{"type":["integer","null"]},"payments_plan_id":{"type":"integer"},"gateway_subscription_id":{"type":"integer"},"status":{"type":"string","enum":["active","paused","overdue","canceled","expired","pending"]},"cycle":{"type":"string","enum":["weekly","biweekly","monthly","quarterly","semiannually","yearly","bimonthly"]},"billing_type":{"type":"string","enum":["pix","boleto","credit_card","hosted_link","undefined","debit_card"],"description":"How the payer is charged. `undefined` lets the payer pick on the hosted invoice."},"amount":{"type":"number"},"subtotal_amount":{"type":"number"},"discount":{"type":"string"},"discount_type":{"type":"string","enum":["fixed","percent"],"description":"Whether the discount is an absolute amount or a percentage."},"discount_reason":{"type":"string"},"currency":{"type":"string"},"next_due_date":{"type":"string","format":"date"},"max_payments":{"type":"string"},"end_date":{"type":"string","format":"date"},"started_at":{"type":"string","format":"date-time"},"canceled_at":{"type":"string","format":"date-time"},"metadata":{"type":"object","additionalProperties":true,"description":"Free-form metadata bag; the key set depends on the record and context."},"gateway_options":{"type":["string","null"]},"archived_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"contact_name":{"type":"string"},"contact_email":{"type":"string","format":"email"},"payer_email":{"type":"string","format":"email"},"contact_phone_number":{"type":"string"},"gateway":{"type":["string","null"],"enum":["asaas","mercado_pago",null],"description":"Native payment gateway of the required connection that owns this plan or subscription."},"capabilities":{"type":["string","null"]},"plan_name":{"type":["string","null"]},"link_state":{"type":"string","enum":["linked","unlinked"],"description":"Whether the subscription resolves to a Contact. `linked` carries one; `unlinked` does not, and is kept visible on purpose so an unmatched payer can be reconciled later instead of disappearing. The list filter and the badge read this key; `association_status` is the same truth in the older matched/unmatched spelling."},"association_status":{"type":"string","enum":["matched","unmatched"],"description":"Whether the subscription resolves to a Contact. `matched` carries one; `unmatched` does not, because no gateway customer, e-mail, phone or document matched exactly when the subscription was imported or adopted. Always one of the two: it is derived from the current link, so a manually-created subscription and a row that predates the key both answer correctly. This is the long-standing spelling of the same truth as `link_state`."}}}}},"example":{"payload":{"id":1,"account_id":1,"payments_connection_id":1,"contact_id":1,"organization_id":1,"organization_name":"sample organization name","conversation_id":1,"conversation_display_id":1,"payments_plan_id":1,"gateway_subscription_id":1,"status":"active","cycle":"weekly","billing_type":"pix","amount":149.9,"subtotal_amount":149.9,"discount":"sample discount","discount_type":"fixed","discount_reason":"sample discount reason","currency":"BRL","next_due_date":"2026-01-15","max_payments":"sample max payments","end_date":"2026-01-15","started_at":"2026-01-15T10:30:00.000Z","canceled_at":"2026-01-15T10:30:00.000Z","metadata":{},"gateway_options":"sample gateway options","archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","contact_name":"sample contact name","contact_email":"agent@example.com","payer_email":"agent@example.com","contact_phone_number":"+5511999998888","gateway":"asaas","capabilities":"sample capabilities","plan_name":"sample plan name","link_state":"linked","association_status":"matched"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"subscription":{"type":"object","properties":{"amount":{"type":"number"},"currency":{"type":"string"},"cycle":{"type":"string","enum":["weekly","biweekly","monthly","quarterly","semiannually","yearly","bimonthly"]},"next_due_date":{"type":"string","format":"date"},"description":{"type":"string"},"billing_type":{"type":"string","enum":["pix","boleto","credit_card","hosted_link","undefined","debit_card"],"description":"How the payer is charged. `undefined` lets the payer pick on the hosted invoice."},"end_date":{"type":"string","format":"date"},"discount":{"type":"string"},"discount_type":{"type":"string","enum":["fixed","percent"],"description":"Whether the discount is an absolute amount or a percentage."},"discount_reason":{"type":"string"},"gateway_options":{"type":"object","additionalProperties":true,"description":"Free-form object."}}}},"required":["subscription"]},"example":{"subscription":{"amount":149.9,"currency":"BRL","cycle":"weekly","next_due_date":"2026-01-15","description":"A short description.","billing_type":"pix","end_date":"2026-01-15","discount":"sample discount","discount_type":"fixed","discount_reason":"sample discount reason","gateway_options":{}}}}}}}},"/api/v1/accounts/{account_id}/payments/subscriptions/{id}/cancel":{"post":{"tags":["Payment Subscriptions"],"operationId":"cancel-payment-subscription","summary":"Cancel a subscription at the gateway","security":[{"userApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"id","in":"path","required":true,"schema":{"type":"number"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"$ref":"#/components/schemas/payment_subscription"}}},"example":{"payload":{"id":1,"account_id":1,"payments_connection_id":1,"contact_id":1,"conversation_id":1,"conversation_display_id":1,"payments_plan_id":1,"gateway_subscription_id":"sample gateway subscription id","status":"pending","cycle":"weekly","billing_type":"pix","amount":149.9,"subtotal_amount":149.9,"discount":12.5,"discount_type":"fixed","discount_reason":"sample discount reason","currency":"BRL","next_due_date":"2026-01-15","max_payments":1,"end_date":"2026-01-15","started_at":"2026-01-15T10:30:00.000Z","canceled_at":"2026-01-15T10:30:00.000Z","metadata":{},"contact_name":"sample contact name","gateway":"asaas","capabilities":{},"plan_name":"sample plan name","archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}},"description":"Cancel a subscription at the gateway. Submits the request payload to the Cancel resource and returns the result."}},"/api/v1/accounts/{account_id}/payments/subscriptions/{id}/archive":{"post":{"tags":["Payment Subscriptions"],"operationId":"archive-payment-subscription","summary":"Archive a subscription","description":"Soft-deletes the local subscription and returns an empty success response.","security":[{"userApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"id","in":"path","required":true,"schema":{"type":"number"}}],"responses":{"200":{"description":"Subscription archived successfully (empty response body)."},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/payments/subscriptions/{id}/restore":{"post":{"tags":["Payment Subscriptions"],"operationId":"restore-payment-subscription","summary":"Restore an archived subscription","security":[{"userApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"id","in":"path","required":true,"schema":{"type":"number"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"$ref":"#/components/schemas/payment_subscription"}}},"example":{"payload":{"id":1,"account_id":1,"payments_connection_id":1,"contact_id":1,"conversation_id":1,"conversation_display_id":1,"payments_plan_id":1,"gateway_subscription_id":"sample gateway subscription id","status":"pending","cycle":"weekly","billing_type":"pix","amount":149.9,"subtotal_amount":149.9,"discount":12.5,"discount_type":"fixed","discount_reason":"sample discount reason","currency":"BRL","next_due_date":"2026-01-15","max_payments":1,"end_date":"2026-01-15","started_at":"2026-01-15T10:30:00.000Z","canceled_at":"2026-01-15T10:30:00.000Z","metadata":{},"contact_name":"sample contact name","gateway":"asaas","capabilities":{},"plan_name":"sample plan name","archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}},"description":"Restore an archived subscription. Submits the request payload to the Restore resource and returns the result."}},"/api/v1/accounts/{account_id}/payments/subscriptions/{id}/resume":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"id","in":"path","required":true,"schema":{"type":"number"},"description":"ID of the subscription"}],"post":{"tags":["Payment Subscriptions"],"operationId":"resume-payment-subscription","summary":"Resume a paused subscription at the gateway","security":[{"userApiKey":[]}],"description":"Resume recurring billing at the gateway (Asaas active, Mercado Pago authorized) and mirror the local status back to active.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"$ref":"#/components/schemas/payment_subscription"}}},"example":{"payload":{"id":1,"account_id":1,"payments_connection_id":1,"contact_id":1,"conversation_id":1,"conversation_display_id":1,"payments_plan_id":1,"gateway_subscription_id":"sample gateway subscription id","status":"pending","cycle":"weekly","billing_type":"pix","amount":149.9,"subtotal_amount":149.9,"discount":12.5,"discount_type":"fixed","discount_reason":"sample discount reason","currency":"BRL","next_due_date":"2026-01-15","max_payments":1,"end_date":"2026-01-15","started_at":"2026-01-15T10:30:00.000Z","canceled_at":"2026-01-15T10:30:00.000Z","metadata":{},"contact_name":"sample contact name","gateway":"asaas","capabilities":{},"plan_name":"sample plan name","archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/payments/subscriptions/{id}/pause":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"id","in":"path","required":true,"schema":{"type":"number"},"description":"ID of the subscription"}],"post":{"tags":["Payment Subscriptions"],"operationId":"pause-payment-subscription","summary":"Pause recurring billing at the gateway","security":[{"userApiKey":[]}],"description":"Pause recurring billing at the gateway (Asaas inactive, Mercado Pago paused) and mirror the local status to paused. Resume it later with /resume.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"$ref":"#/components/schemas/payment_subscription"}}},"example":{"payload":{"id":1,"account_id":1,"payments_connection_id":1,"contact_id":1,"conversation_id":1,"conversation_display_id":1,"payments_plan_id":1,"gateway_subscription_id":"sample gateway subscription id","status":"pending","cycle":"weekly","billing_type":"pix","amount":149.9,"subtotal_amount":149.9,"discount":12.5,"discount_type":"fixed","discount_reason":"sample discount reason","currency":"BRL","next_due_date":"2026-01-15","max_payments":1,"end_date":"2026-01-15","started_at":"2026-01-15T10:30:00.000Z","canceled_at":"2026-01-15T10:30:00.000Z","metadata":{},"contact_name":"sample contact name","gateway":"asaas","capabilities":{},"plan_name":"sample plan name","archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/payments/plans":{"get":{"tags":["Payment Plans"],"operationId":"list-payment-plans","summary":"List reusable plans","security":[{"userApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"page","in":"query","schema":{"type":"number"}},{"name":"per_page","in":"query","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"q","in":"query","schema":{"type":"string"}},{"name":"archived","in":"query","schema":{"type":"boolean"}},{"name":"connection_id","in":"query","schema":{"type":"integer"}},{"name":"cycle","in":"query","schema":{"type":"string","enum":["weekly","biweekly","monthly","bimonthly","quarterly","semiannually","yearly"]}},{"name":"sort","in":"query","schema":{"type":"string","enum":["created_at","name","amount","cycle"]}},{"name":"direction","in":"query","schema":{"type":"string","enum":["asc","desc"]}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"$ref":"#/components/schemas/payment_plan"}},"meta":{"type":"object","properties":{"count":{"type":"number"},"current_page":{"type":"number"},"total_pages":{"type":"number"},"per_page":{"type":"number"},"has_more":{"type":"boolean"}}}}},"example":{"payload":[{"id":1,"account_id":1,"payments_connection_id":1,"gateway_plan_id":"sample gateway plan id","name":"Sample Name","cycle":"weekly","amount":149.9,"currency":"BRL","metadata":{},"gateway":"asaas","connection_name":"sample connection name","capabilities":{},"archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}],"meta":{"count":5,"current_page":12.5,"total_pages":12.5,"per_page":12.5,"has_more":true}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}},"description":"List reusable plans. Returns Plans data for the current context."},"post":{"tags":["Payment Plans"],"operationId":"create-payment-plan","summary":"Create a reusable local plan template","security":[{"userApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/account_id"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"plan":{"type":"object","properties":{"connection_id":{"type":"number"},"name":{"type":"string"},"amount":{"type":"number"},"currency":{"type":"string","example":"BRL","description":"Must match the selected connection settlement currency."},"cycle":{"type":"string","enum":["weekly","biweekly","monthly","bimonthly","quarterly","semiannually","yearly"]},"metadata":{"type":"object","additionalProperties":true,"description":"Free-form gateway metadata."}},"required":["connection_id","name","amount","currency","cycle"]}}},"example":{"plan":{"connection_id":1,"name":"Sample Name","amount":149.9,"currency":"BRL","cycle":"weekly","metadata":{}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"$ref":"#/components/schemas/payment_plan"}}},"example":{"payload":{"id":1,"account_id":1,"payments_connection_id":1,"gateway_plan_id":"sample gateway plan id","name":"Sample Name","cycle":"weekly","amount":149.9,"currency":"BRL","metadata":{},"gateway":"asaas","connection_name":"sample connection name","capabilities":{},"archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}},"description":"Create a reusable local plan template. Submits the request payload to the Plans resource and returns the result."}},"/api/v1/accounts/{account_id}/payments/plans/export":{"get":{"tags":["Payment Plans"],"operationId":"export-payment-plans","summary":"Export the filtered or selected payment plans as CSV","description":"Uses the same account-scoped search, archive view, connection and cycle filters as the list endpoint, without page truncation. When ids[] is present, only selected matching plans are exported. Text cells are protected against spreadsheet formula injection.","security":[{"userApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"q","in":"query","schema":{"type":"string"}},{"name":"archived","in":"query","schema":{"type":"boolean"}},{"name":"connection_id","in":"query","schema":{"type":"integer"}},{"name":"cycle","in":"query","schema":{"type":"string","enum":["weekly","biweekly","monthly","bimonthly","quarterly","semiannually","yearly"]}},{"name":"sort","in":"query","schema":{"type":"string","enum":["created_at","name","amount","cycle"]}},{"name":"direction","in":"query","schema":{"type":"string","enum":["asc","desc"]}},{"name":"ids","in":"query","description":"Optional current selection; foreign or missing ids are omitted by account scope.","style":"form","explode":true,"schema":{"type":"array","maxItems":500,"uniqueItems":true,"items":{"type":"integer","minimum":1}}}],"responses":{"200":{"description":"UTF-8 CSV attachment.","content":{"text/csv":{"schema":{"type":"string","format":"binary"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/payments/plans/{id}":{"get":{"tags":["Payment Plans"],"operationId":"get-payment-plan","summary":"Get a plan","security":[{"userApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"id","in":"path","required":true,"schema":{"type":"number"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"$ref":"#/components/schemas/payment_plan"}}},"example":{"payload":{"id":1,"account_id":1,"payments_connection_id":1,"gateway_plan_id":"sample gateway plan id","name":"Sample Name","cycle":"weekly","amount":149.9,"currency":"BRL","metadata":{},"gateway":"asaas","connection_name":"sample connection name","capabilities":{},"archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}},"description":"Get a plan. Returns the requested Plans resource."},"patch":{"tags":["Payment Plans"],"operationId":"update-payment-plan","summary":"Update a plan","security":[{"userApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"id","in":"path","required":true,"schema":{"type":"number"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"plan":{"type":"object","properties":{"connection_id":{"type":"number"},"name":{"type":"string"},"amount":{"type":"number"},"currency":{"type":"string","example":"BRL","description":"Must match the selected connection settlement currency."},"cycle":{"type":"string","enum":["weekly","biweekly","monthly","bimonthly","quarterly","semiannually","yearly"]},"metadata":{"type":"object","additionalProperties":true,"description":"Free-form gateway metadata."}}}}},"example":{"plan":{"connection_id":1,"name":"Sample Name","amount":149.9,"currency":"BRL","cycle":"weekly","metadata":{}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"$ref":"#/components/schemas/payment_plan"}}},"example":{"payload":{"id":1,"account_id":1,"payments_connection_id":1,"gateway_plan_id":"sample gateway plan id","name":"Sample Name","cycle":"weekly","amount":149.9,"currency":"BRL","metadata":{},"gateway":"asaas","connection_name":"sample connection name","capabilities":{},"archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}},"description":"Update a plan. Applies the submitted changes to the Plans resource."},"delete":{"tags":["Payment Plans"],"operationId":"delete-payment-plan","summary":"Delete a plan","security":[{"userApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"id","in":"path","required":true,"schema":{"type":"number"}}],"responses":{"200":{"description":"Success"},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}},"description":"Delete a plan. Removes the targeted Plans resource."},"put":{"tags":["Payment Plans"],"operationId":"auto_put_api_v1_accounts_account_id_payments_plans_id","summary":"Update a reusable payment plan","description":"Updates the plan identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"payments_connection_id":{"type":"integer"},"gateway_plan_id":{"type":"integer"},"name":{"type":"string"},"cycle":{"type":"string","enum":["weekly","biweekly","monthly","quarterly","semiannually","yearly","bimonthly"]},"amount":{"type":"number"},"currency":{"type":"string"},"metadata":{"type":"object","additionalProperties":true,"description":"Free-form metadata bag; the key set depends on the record and context."},"archived_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"gateway":{"type":["string","null"],"enum":["asaas","mercado_pago",null],"description":"Native payment gateway of the required connection that owns this plan or subscription."},"connection_name":{"type":["string","null"]},"capabilities":{"type":["string","null"]}}}}},"example":{"payload":{"id":1,"account_id":1,"payments_connection_id":1,"gateway_plan_id":1,"name":"Sample Name","cycle":"weekly","amount":149.9,"currency":"BRL","metadata":{},"archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","gateway":"asaas","connection_name":"sample connection name","capabilities":"sample capabilities"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"plan":{"type":"object","properties":{"connection_id":{"type":"integer"},"name":{"type":"string"},"cycle":{"type":"string","enum":["weekly","biweekly","monthly","quarterly","semiannually","yearly","bimonthly"]},"amount":{"type":"number"},"currency":{"type":"string"},"metadata":{"type":"object","additionalProperties":true,"description":"Free-form metadata bag; the key set depends on the record and context."}}}},"required":["plan"]},"example":{"plan":{"connection_id":1,"name":"Sample Name","cycle":"weekly","amount":149.9,"currency":"BRL","metadata":{}}}}}}}},"/api/v1/accounts/{account_id}/payments/plans/{id}/archive":{"post":{"tags":["Payment Plans"],"operationId":"archive-payment-plan","summary":"Archive a plan","security":[{"userApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"id","in":"path","required":true,"schema":{"type":"number"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"$ref":"#/components/schemas/payment_plan"}}},"example":{"payload":{"id":1,"account_id":1,"payments_connection_id":1,"gateway_plan_id":"sample gateway plan id","name":"Sample Name","cycle":"weekly","amount":149.9,"currency":"BRL","metadata":{},"gateway":"asaas","connection_name":"sample connection name","capabilities":{},"archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}},"description":"Archive a plan. Submits the request payload to the Archive resource and returns the result."}},"/api/v1/accounts/{account_id}/payments/plans/{id}/restore":{"post":{"tags":["Payment Plans"],"operationId":"restore-payment-plan","summary":"Restore an archived plan","security":[{"userApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"id","in":"path","required":true,"schema":{"type":"number"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"$ref":"#/components/schemas/payment_plan"}}},"example":{"payload":{"id":1,"account_id":1,"payments_connection_id":1,"gateway_plan_id":"sample gateway plan id","name":"Sample Name","cycle":"weekly","amount":149.9,"currency":"BRL","metadata":{},"gateway":"asaas","connection_name":"sample connection name","capabilities":{},"archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}},"description":"Restore an archived plan. Submits the request payload to the Restore resource and returns the result."}},"/api/v1/accounts/{account_id}/payments/offers/export":{"get":{"tags":["Payment Offers"],"operationId":"export-payment-offers","summary":"Export the filtered or selected payment offers as CSV","description":"Uses the same account-scoped search, archive view, kind, status, connection and product filters as the list endpoint, without page truncation. When ids[] is present, only selected matching offers are exported. Text cells are protected against spreadsheet formula injection.","security":[{"userApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"q","in":"query","schema":{"type":"string"}},{"name":"archived","in":"query","schema":{"type":"boolean"}},{"name":"kind","in":"query","schema":{"type":"string","enum":["order_bump","upsell","downsell"]}},{"name":"active","in":"query","schema":{"type":"boolean"}},{"name":"connection_id","in":"query","schema":{"type":"integer"}},{"name":"catalog_product_id","in":"query","schema":{"type":"integer"}},{"name":"sort","in":"query","schema":{"type":"string","enum":["created_at","name","amount","kind","active"]}},{"name":"direction","in":"query","schema":{"type":"string","enum":["asc","desc"]}},{"name":"ids","in":"query","description":"Optional current selection; foreign or missing ids are omitted by account scope.","style":"form","explode":true,"schema":{"type":"array","maxItems":500,"uniqueItems":true,"items":{"type":"integer","minimum":1}}}],"responses":{"200":{"description":"UTF-8 CSV attachment.","content":{"text/csv":{"schema":{"type":"string","format":"binary"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/payments/reports":{"get":{"tags":["Payment Reports"],"operationId":"payment-reports","summary":"Payments analytics (revenue, by_status, by_gateway, by_currency, MRR, churn)","security":[{"userApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"since","in":"query","schema":{"type":"string","format":"date"}},{"name":"until","in":"query","schema":{"type":"string","format":"date"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","additionalProperties":true,"description":"Payments analytics: revenue, by_status, by_gateway, by_currency, MRR and churn for the selected window."}}},"example":{"payload":{}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}},"description":"Payments analytics (revenue, by_status, by_gateway, by_currency, MRR, churn). Returns Reports data for the current context."}},"/api/v1/accounts/{account_id}/payments/demo":{"post":{"tags":["Payment Demo"],"operationId":"seed-payment-demo","summary":"[admin] Seed demo payments data (sandbox connections / charges / subscriptions)","security":[{"userApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/account_id"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}}},"example":{"success":true}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"403":{"description":"Forbidden (administrator only)"}},"description":"[admin] Seed demo payments data (sandbox connections / charges / subscriptions). Submits the request payload to the Demo resource and returns the result."},"delete":{"tags":["Payment Demo"],"operationId":"teardown-payment-demo","summary":"[admin] Remove demo payments data","security":[{"userApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/account_id"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}}},"example":{"success":true}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"403":{"description":"Forbidden (administrator only)"}},"description":"[admin] Remove demo payments data. Removes the targeted Demo resource."}},"/api/v1/accounts/{account_id}/calendar/calendars":{"get":{"tags":["Calendar"],"operationId":"list-calendars","summary":"List calendars","description":"List account calendars. Pass `archived=true` to retrieve archived calendars.","security":[{"userApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"archived","in":"query","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"$ref":"#/components/schemas/calendar_calendar"}}}},"example":{"payload":[{"id":1,"account_id":1,"name":"Sample Name","color":"#1F93FF","kind":"native","timezone":"America/Sao_Paulo","description":"A short description.","is_default":true,"connection_id":1,"google_calendar_id":"sample google calendar id","google_backed":true,"prevent_double_booking":true,"assignments":[{"id":1,"assignable_type":"User","assignable_id":1}],"archived_at":"2026-01-15T10:30:00.000Z","archived":true,"custom_attributes":{},"additional_attributes":{},"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"post":{"tags":["Calendar"],"operationId":"create-calendar","summary":"Create a calendar","security":[{"userApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/account_id"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"calendar":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"color":{"type":"string"},"kind":{"type":"string","enum":["native","google"]},"timezone":{"type":"string","description":"IANA timezone identifier (e.g. \"America/Sao_Paulo\", \"UTC\"). Rails timezone names are also accepted on input; an unrecognized value is ignored in favor of the next fallback.","example":"America/Sao_Paulo"},"description":{"type":"string"},"is_default":{"type":"boolean"},"prevent_double_booking":{"type":["boolean","null"],"description":"Refuse a booking that overlaps an existing event on this calendar. Omitted or `null`, the calendar inherits the account-wide setting; `true`/`false` is a deliberate per-calendar decision that overrides the account default. With it on, a create or reschedule that collides is rejected instead of double-booking.","example":true},"connection_id":{"type":"number"},"google_calendar_id":{"type":"string"},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"additional_attributes":{"type":"object","additionalProperties":true,"description":"Channel- and source-specific metadata for this record (e.g. browser info, referer, social profile identifiers). The key set depends on the originating channel."},"assignments":{"type":"array","description":"Who the calendar belongs to. Sending none keeps it account-wide (visible to everyone). An entry whose target does not exist in the account is dropped, never an error.","items":{"type":"object","properties":{"assignable_type":{"type":"string","enum":["User","Team","Inbox"],"example":"User","description":"Calendar assignment target type — an agent, team, or logical inbox."},"assignable_id":{"type":"number","example":7}}},"example":[{"assignable_type":"User","assignable_id":7}]},"availability_rules":{"type":"array","description":"Weekly availability windows seeded on the new calendar. An entry missing any of the three fields is skipped. Accepted only on create — send them through the availability endpoints afterwards.","items":{"type":"object","properties":{"day_of_week":{"type":"integer","description":"0 = Sunday through 6 = Saturday.","example":1},"start_minute":{"type":"integer","description":"Minutes from midnight when the window opens.","example":540},"end_minute":{"type":"integer","description":"Minutes from midnight when the window closes.","example":1080}}},"example":[{"day_of_week":1,"start_minute":540,"end_minute":1080}]}}}}},"example":{"calendar":{"name":"Sample Name","color":"#1F93FF","kind":"native","timezone":"America/Sao_Paulo","description":"A short description.","is_default":true,"prevent_double_booking":true,"connection_id":1,"google_calendar_id":"sample google calendar id","custom_attributes":{},"additional_attributes":{},"assignments":[{"assignable_type":"User","assignable_id":7}],"availability_rules":[{"day_of_week":1,"start_minute":540,"end_minute":1080}]}}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"$ref":"#/components/schemas/calendar_calendar"}}},"example":{"payload":{"id":1,"account_id":1,"name":"Sample Name","color":"#1F93FF","kind":"native","timezone":"America/Sao_Paulo","description":"A short description.","is_default":true,"connection_id":1,"google_calendar_id":"sample google calendar id","google_backed":true,"prevent_double_booking":true,"assignments":[{"id":1,"assignable_type":"User","assignable_id":1}],"archived_at":"2026-01-15T10:30:00.000Z","archived":true,"custom_attributes":{},"additional_attributes":{},"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}},"description":"Create a calendar. Submits the request payload to the Calendars resource and returns the result."}},"/api/v1/accounts/{account_id}/calendar/calendars/{id}":{"get":{"tags":["Calendar"],"operationId":"get-calendar","summary":"Get a calendar","security":[{"userApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"id","in":"path","required":true,"schema":{"type":"number"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"$ref":"#/components/schemas/calendar_calendar"}}},"example":{"payload":{"id":1,"account_id":1,"name":"Sample Name","color":"#1F93FF","kind":"native","timezone":"America/Sao_Paulo","description":"A short description.","is_default":true,"connection_id":1,"google_calendar_id":"sample google calendar id","google_backed":true,"prevent_double_booking":true,"assignments":[{"id":1,"assignable_type":"User","assignable_id":1}],"archived_at":"2026-01-15T10:30:00.000Z","archived":true,"custom_attributes":{},"additional_attributes":{},"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}},"description":"Get a calendar. Returns the requested Calendars resource."},"patch":{"tags":["Calendar"],"operationId":"update-calendar","summary":"Update a calendar","security":[{"userApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"id","in":"path","required":true,"schema":{"type":"number"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"calendar":{"type":"object","properties":{"name":{"type":"string"},"color":{"type":"string"},"kind":{"type":"string","enum":["native","google"]},"timezone":{"type":"string","description":"IANA timezone identifier (e.g. \"America/Sao_Paulo\", \"UTC\"). Rails timezone names are also accepted on input; an unrecognized value is ignored in favor of the next fallback.","example":"America/Sao_Paulo"},"description":{"type":"string"},"is_default":{"type":"boolean"},"prevent_double_booking":{"type":["boolean","null"],"description":"Refuse a booking that overlaps an existing event on this calendar. `null` restores inheritance of the account-wide setting; `true`/`false` is a deliberate per-calendar decision that overrides the account default. With it on, a create or reschedule that collides is rejected instead of double-booking.","example":true},"connection_id":{"type":"number"},"google_calendar_id":{"type":"string"},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"additional_attributes":{"type":"object","additionalProperties":true,"description":"Channel- and source-specific metadata for this record (e.g. browser info, referer, social profile identifiers). The key set depends on the originating channel."},"assignments":{"type":"array","description":"Replaces the whole assignment set. Omit the key to leave the current owners untouched; send `[]` to clear them and make the calendar account-wide again. An entry whose target does not exist in the account is dropped, never an error.","items":{"type":"object","properties":{"assignable_type":{"type":"string","enum":["User","Team","Inbox"],"example":"User","description":"Calendar assignment target type — an agent, team, or logical inbox."},"assignable_id":{"type":"number","example":7}}},"example":[{"assignable_type":"User","assignable_id":7}]}}}}},"example":{"calendar":{"name":"Sample Name","color":"#1F93FF","kind":"native","timezone":"America/Sao_Paulo","description":"A short description.","is_default":true,"prevent_double_booking":true,"connection_id":1,"google_calendar_id":"sample google calendar id","custom_attributes":{},"additional_attributes":{},"assignments":[{"assignable_type":"User","assignable_id":7}]}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"$ref":"#/components/schemas/calendar_calendar"}}},"example":{"payload":{"id":1,"account_id":1,"name":"Sample Name","color":"#1F93FF","kind":"native","timezone":"America/Sao_Paulo","description":"A short description.","is_default":true,"connection_id":1,"google_calendar_id":"sample google calendar id","google_backed":true,"prevent_double_booking":true,"assignments":[{"id":1,"assignable_type":"User","assignable_id":1}],"archived_at":"2026-01-15T10:30:00.000Z","archived":true,"custom_attributes":{},"additional_attributes":{},"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}}}},"description":"Update a calendar. Applies the submitted changes to the Calendars resource."},"delete":{"tags":["Calendar"],"operationId":"delete-calendar","summary":"Archive (soft-delete) a calendar","security":[{"userApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"id","in":"path","required":true,"schema":{"type":"number"}}],"responses":{"200":{"description":"Success"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"Calendar not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}},"description":"Archive (soft-delete) a calendar. Removes the targeted Calendars resource."},"put":{"tags":["Calendar"],"operationId":"auto_put_api_v1_accounts_account_id_calendar_calendars_id","summary":"Update calendars","description":"Updates the calendar identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"name":{"type":"string"},"color":{"type":"string"},"kind":{"type":"string","enum":["native","google"]},"timezone":{"type":"string","description":"IANA timezone identifier (e.g. \"America/Sao_Paulo\", \"UTC\"). Rails timezone names are also accepted on input; an unrecognized value is ignored in favor of the next fallback.","example":"America/Sao_Paulo"},"description":{"type":"string"},"is_default":{"type":"boolean"},"prevent_double_booking":{"type":"string"},"connection_id":{"type":"integer"},"google_calendar_id":{"type":"integer"},"google_backed":{"type":"boolean"},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"additional_attributes":{"type":"object","additionalProperties":true,"description":"Channel- and source-specific metadata for this record (e.g. browser info, referer, social profile identifiers). The key set depends on the originating channel."},"assignments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"assignable_type":{"type":"string","enum":["User","Team","Inbox"],"description":"Calendar assignment target type — an agent, team, or logical inbox."},"assignable_id":{"type":"integer"}}}},"archived_at":{"type":"string","format":"date-time"},"archived":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}},"example":{"payload":{"id":1,"account_id":1,"name":"Sample Name","color":"#1F93FF","kind":"native","timezone":"America/Sao_Paulo","description":"A short description.","is_default":true,"prevent_double_booking":"sample prevent double booking","connection_id":1,"google_calendar_id":1,"google_backed":true,"custom_attributes":{},"additional_attributes":{},"assignments":[{"id":1,"assignable_type":"User","assignable_id":1}],"archived_at":"2026-01-15T10:30:00.000Z","archived":true,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["calendar"],"properties":{"calendar":{"type":"object","properties":{"name":{"type":"string","example":"Sales team"},"color":{"type":"string","example":"#1F93FF"},"kind":{"type":"string","enum":["native","google"],"example":"native"},"timezone":{"type":"string","description":"IANA timezone identifier (e.g. \"America/Sao_Paulo\", \"UTC\").","example":"America/Sao_Paulo"},"description":{"type":"string","example":"Shared agenda for the sales team."},"is_default":{"type":"boolean","description":"Promoting a calendar to default demotes the account's previous default.","example":true},"prevent_double_booking":{"type":["boolean","null"],"description":"Refuse a booking that overlaps an existing event on this calendar. `null` restores inheritance of the account-wide setting; `true`/`false` is a deliberate per-calendar decision that overrides the account default. With it on, a create or reschedule that collides is rejected instead of double-booking.","example":true},"connection_id":{"type":"integer","description":"Google connection backing a mirrored calendar.","example":3},"google_calendar_id":{"type":"string","description":"Identifier of the mirrored Google calendar.","example":"primary"},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this calendar, keyed by the attribute key defined by the account.","example":{}},"additional_attributes":{"type":"object","additionalProperties":true,"description":"Source-specific metadata carried with the calendar.","example":{}},"assignments":{"type":"array","description":"Replaces the whole assignment set. Omit the key to leave the current owners untouched; send `[]` to clear them and make the calendar account-wide again. An entry whose target does not exist in the account is dropped, never an error.","items":{"type":"object","properties":{"assignable_type":{"type":"string","enum":["User","Team","Inbox"],"example":"User","description":"Calendar assignment target type — an agent, team, or logical inbox."},"assignable_id":{"type":"number","example":7}}},"example":[{"assignable_type":"User","assignable_id":7}]}}}}},"example":{"calendar":{"name":"Sales team","color":"#1F93FF","kind":"native","timezone":"America/Sao_Paulo","description":"Shared agenda for the sales team.","is_default":true,"prevent_double_booking":true,"connection_id":3,"google_calendar_id":"primary","custom_attributes":{},"additional_attributes":{},"assignments":[{"assignable_type":"User","assignable_id":7}]}}}}}}},"/api/v1/accounts/{account_id}/calendar/calendars/{id}/purge":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"id","in":"path","required":true,"schema":{"type":"number"},"description":"ID of the calendar"}],"delete":{"tags":["Calendar"],"operationId":"purge-a-calendar","summary":"Permanently delete an archived, empty calendar","security":[{"userApiKey":[]}],"description":"Permanently delete an ARCHIVED calendar with zero events (admin-only). Owned config is cascaded (its event types, assignments, availability windows/overrides, sync state and scoped settings). Google-mirrored data is never touched — no Google API call is made.","responses":{"200":{"description":"Success"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"422":{"description":"The calendar must be archived and have zero events before it can be purged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"Calendar not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/calendar/calendars/{id}/restore":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"id","in":"path","required":true,"schema":{"type":"number"},"description":"ID of the calendar"}],"post":{"tags":["Calendar"],"operationId":"restore-a-calendar","summary":"Restore an archived calendar","security":[{"userApiKey":[]}],"description":"Bring a soft-deleted (archived) calendar back to the active list.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"$ref":"#/components/schemas/calendar_calendar"}}},"example":{"payload":{"id":1,"account_id":1,"name":"Sample Name","color":"#1F93FF","kind":"native","timezone":"America/Sao_Paulo","description":"A short description.","is_default":true,"connection_id":1,"google_calendar_id":"sample google calendar id","google_backed":true,"prevent_double_booking":true,"assignments":[{"id":1,"assignable_type":"User","assignable_id":1}],"archived_at":"2026-01-15T10:30:00.000Z","archived":true,"custom_attributes":{},"additional_attributes":{},"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"Calendar not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/calendar/events":{"get":{"tags":["Calendar Events"],"operationId":"list-calendar-events","summary":"List calendar events","description":"List and filter agenda events. Every filter is optional and they combine with AND. A window given as `starts_after` + `starts_before` matches events that OVERLAP it, not only events that start inside it, so an appointment already in progress at the window's start is included. Unparseable dates and unknown `sort` values are ignored rather than rejected, and `per_page` above the cap is silently clamped — this endpoint backs a calendar grid, where a malformed query should degrade to a sane view instead of an error.","security":[{"userApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"starts_after","in":"query","required":false,"description":"Window start. Combined with `starts_before` this is an overlap match.","schema":{"type":"string","format":"date-time"}},{"name":"starts_before","in":"query","required":false,"description":"Window end. Combined with `starts_after` this is an overlap match.","schema":{"type":"string","format":"date-time"}},{"name":"calendar_id","in":"query","required":false,"description":"Only events on this calendar.","schema":{"type":"number"}},{"name":"contact_id","in":"query","required":false,"description":"Only events linked to this contact.","schema":{"type":"number"}},{"name":"conversation_id","in":"query","required":false,"description":"Only events linked to this conversation.","schema":{"type":"number"}},{"name":"crm_item_id","in":"query","required":false,"description":"Only events linked to this CRM deal.","schema":{"type":"number"}},{"name":"event_type_id","in":"query","required":false,"description":"Only events booked through these event types. Accepts a single id (`?event_type_id=3`) or a repeated array (`?event_type_id[]=3\u0026event_type_id[]=7`); both forms mean the same thing, and an empty value is treated as no filter at all rather than as \"match nothing\".\n\nAn event has no `event_type_id` column of its own — the filter resolves through the booking that created it. So while it is active, natively-created and Google-imported events (which have no booking and therefore no type) drop out of the result entirely. A type id belonging to another account matches nothing; the query is already account-scoped.","schema":{"oneOf":[{"type":"number"},{"type":"array","items":{"type":"number"}}]}},{"name":"status","in":"query","required":false,"description":"Only events in this state.","schema":{"type":"string","enum":["confirmed","tentative","cancelled"]}},{"name":"q","in":"query","required":false,"description":"Case-insensitive substring match over the event title and description only.","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"Ordering. An unrecognised value falls back to `starts_at_asc` instead of erroring.","schema":{"type":"string","default":"starts_at_asc","enum":["starts_at_asc","starts_at_desc","ends_at_asc","ends_at_desc","created_at_asc","created_at_desc","title_asc","title_desc"]}},{"name":"page","in":"query","required":false,"description":"1-based page number.","schema":{"type":"number","default":1}},{"name":"per_page","in":"query","required":false,"description":"Page size. A larger request is clamped to the maximum, not rejected.","schema":{"type":"number","default":50,"maximum":100}},{"name":"custom_attributes","in":"query","required":false,"description":"Containment match against the event's `custom_attributes` JSON. Every key/value given must be present on the event.","schema":{"type":"object","description":"Arbitrary operator-defined attribute keys and the values to match.","additionalProperties":true}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"$ref":"#/components/schemas/calendar_event"}},"meta":{"type":"object","properties":{"count":{"type":"number","description":"Size of the WHOLE filtered set, not of this page."},"current_page":{"type":"number"},"per_page":{"type":"number"},"has_more":{"type":"boolean"}}}}},"example":{"payload":[{"id":1,"account_id":1,"calendar_id":1,"title":"Sample title","description":"A short description.","location":"sample location","starts_at":"2026-01-15T10:30:00.000Z","ends_at":"2026-01-15T10:30:00.000Z","all_day":true,"timezone":"America/Sao_Paulo","status":"tentative","source":"native","transparency":"opaque","event_type":{"id":1,"name":"Sample Name","color":"#1F93FF"},"event_type_id":1,"contact_id":1,"conversation_id":1,"crm_item_id":1,"task_id":1,"recurrence":{},"conferencing":{},"meet_url":"https://example.com/resource","custom_attributes":{},"additional_attributes":{},"attendees":[{"id":1,"event_id":1,"contact_id":1,"user_id":1,"email":"agent@example.com","response_status":"accepted","organizer":true,"optional":true,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}],"archived":true,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}],"meta":{"count":5,"current_page":12.5,"per_page":12.5,"has_more":true}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"post":{"tags":["Calendar Events"],"operationId":"create-calendar-event","summary":"Create a calendar event","description":"Creates an appointment. Creating an event does NOT message the contact by default. Send `send_confirmation: true` to post the booking confirmation right after the save — into the linked conversation when there is one, otherwise through the channel configured in the Agenda notification settings when the contact can be reached there. Every resolved target must match the appointment's contact, and a user requesting the confirmation must have access to the final destination conversation. The event remains created even if this guard or message creation refuses the confirmation: `confirmation.status` is `failed` and `confirmation.reason` names the refusal. `confirmation.status: sent` means a message is recorded in the conversation; it does not confirm receipt by the contact, including when post-save publication is still pending. Confirmation admission is serialized per event and a replayed create does not request another copy. Reminders follow the account settings regardless of this flag.","security":[{"userApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"X-Idempotency-Key","in":"header","required":false,"description":"Stable create-intent key. Retrying the same account/key with identical normalized event data returns the original event; reusing it for different data returns 409. Omit it only when two intentionally identical appointments must remain distinct.","schema":{"type":"string","maxLength":128,"pattern":"^[A-Za-z0-9._:-]+$"},"example":"calendar-event-550e8400-e29b-41d4-a716-446655440000"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"event":{"type":"object","required":["title","starts_at","ends_at"],"properties":{"title":{"type":"string"},"description":{"type":"string"},"location":{"type":"string"},"starts_at":{"type":"string","format":"date-time"},"ends_at":{"type":"string","format":"date-time"},"all_day":{"type":"boolean"},"timezone":{"type":"string","description":"IANA timezone identifier (e.g. \"America/Sao_Paulo\", \"UTC\"). Rails timezone names are also accepted on input; an unrecognized value is ignored in favor of the next fallback.","example":"America/Sao_Paulo"},"status":{"type":"string","enum":["tentative","confirmed","cancelled"]},"source":{"type":"string"},"contact_id":{"type":"number"},"conversation_id":{"type":"number"},"crm_item_id":{"type":"number"},"task_id":{"type":"number"},"send_confirmation":{"type":"boolean","default":false,"description":"Record the booking confirmation in the contact's conversation after the event is saved. Absent or false, no confirmation is sent (the historical behaviour). It is a choice about this request, never stored on the event.","example":false},"reminders":{"type":"array","description":"Per-event reminder lead times, in MINUTES BEFORE the start. Omit the key to inherit the account / event-type default; send `[]` to silence this event's reminders entirely. The values land in `additional_attributes.reminders.lead_times_minutes`, which is where the reminder job reads them.","items":{"type":"integer"},"example":[60,1440]},"recurrence":{"type":"object","additionalProperties":true,"description":"JSONB recurrence rule: frequency (daily|weekly|monthly|yearly), interval, until, count, days."},"conferencing":{"type":"object","additionalProperties":true,"description":"JSONB conferencing details (provider, join link, entry points)."},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"additional_attributes":{"type":"object","additionalProperties":true,"description":"Channel- and source-specific metadata for this record (e.g. browser info, referer, social profile identifiers). The key set depends on the originating channel."},"attendees":{"type":"array","items":{"type":"object","properties":{"contact_id":{"type":"number"},"user_id":{"type":"number"},"email":{"type":"string"},"response_status":{"type":"string","enum":["needs_action","accepted","declined","tentative","needsAction"],"description":"Attendee RSVP input. Google Calendar's needsAction alias is accepted and stored as needs_action; any other value is rejected with 422."},"organizer":{"type":"boolean"},"optional":{"type":"boolean"}}}}}}}},"example":{"event":{"title":"Sample title","description":"A short description.","location":"sample location","starts_at":"2026-01-15T10:30:00.000Z","ends_at":"2026-01-15T10:30:00.000Z","all_day":true,"timezone":"America/Sao_Paulo","status":"tentative","source":"sample source","contact_id":1,"conversation_id":1,"crm_item_id":1,"task_id":1,"send_confirmation":false,"reminders":[60,1440],"recurrence":{},"conferencing":{},"custom_attributes":{},"additional_attributes":{},"attendees":[{"contact_id":1,"user_id":1,"email":"agent@example.com","response_status":"needs_action","organizer":true,"optional":true}]}}}}},"responses":{"200":{"description":"An identical create intent was already persisted; the original event is returned. If confirmation was requested, the existing confirmation or its refusal is reported without requesting a new copy.","headers":{"X-Idempotent-Replayed":{"description":"Fixed to true when this response replays an earlier successful create.","schema":{"type":"string","enum":["true"]}}},"content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"$ref":"#/components/schemas/calendar_event"},"confirmation":{"type":"object","description":"Present only when the request carried `send_confirmation: true`: the outcome of posting the confirmation in the conversation. The saved event remains regardless of a recipient or conversation access refusal. No publication-status field is included.","properties":{"requested":{"type":"boolean","example":true},"status":{"type":"string","enum":["sent","failed"],"description":"`sent` = a confirmation is recorded in the conversation, without confirming receipt by the contact; `failed` = the event was saved but no confirmation was recorded for this request (see `reason`).","example":"sent"},"reason":{"type":"string","enum":["no_conversation","whatsapp_window_closed","event_ended","event_cancelled","conversation_mismatch","conversation_forbidden","delivery_failed"],"description":"Why no confirmation was recorded. `conversation_mismatch` means the resolved target does not match the appointment's contact; `conversation_forbidden` means the user cannot access that conversation. Absent when `status` is `sent`.","example":"no_conversation"},"message":{"type":"string","description":"Localized explanation of `reason`. Absent when `status` is `sent`.","example":"This appointment is not linked to any conversation. Open it from the contact's conversation to send it."},"message_id":{"type":"integer","description":"Id of the recorded confirmation message. Absent when none is returned.","example":9001},"sent_at":{"type":"string","format":"date-time","description":"When the confirmation was recorded in the conversation. Absent when unavailable.","example":"2026-10-06T14:59:28Z"}}}}},"example":{"payload":{"id":1,"account_id":1,"calendar_id":1,"title":"Sample title","description":"A short description.","location":"sample location","starts_at":"2026-01-15T10:30:00.000Z","ends_at":"2026-01-15T10:30:00.000Z","all_day":true,"timezone":"America/Sao_Paulo","status":"tentative","source":"native","transparency":"opaque","event_type":{"id":1,"name":"Sample Name","color":"#1F93FF"},"event_type_id":1,"contact_id":1,"conversation_id":1,"crm_item_id":1,"task_id":1,"recurrence":{},"conferencing":{},"meet_url":"https://example.com/resource","custom_attributes":{},"additional_attributes":{},"attendees":[{"id":1,"event_id":1,"contact_id":1,"user_id":1,"email":"agent@example.com","response_status":"accepted","organizer":true,"optional":true,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}],"archived":true,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"},"confirmation":{"requested":true,"status":"sent","reason":"no_conversation","message":"This appointment is not linked to any conversation. Open it from the contact's conversation to send it.","message_id":9001,"sent_at":"2026-10-06T14:59:28Z"}}}}},"201":{"description":"The event is created. A requested confirmation refusal does not undo it: the optional `confirmation` object reports the result separately from the saved event.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"$ref":"#/components/schemas/calendar_event"},"confirmation":{"type":"object","description":"Present only when the request carried `send_confirmation: true`: the outcome of posting the confirmation in the conversation. The saved event remains regardless of a recipient or conversation access refusal. No publication-status field is included.","properties":{"requested":{"type":"boolean","example":true},"status":{"type":"string","enum":["sent","failed"],"description":"`sent` = a confirmation is recorded in the conversation, without confirming receipt by the contact; `failed` = the event was saved but no confirmation was recorded for this request (see `reason`).","example":"sent"},"reason":{"type":"string","enum":["no_conversation","whatsapp_window_closed","event_ended","event_cancelled","conversation_mismatch","conversation_forbidden","delivery_failed"],"description":"Why no confirmation was recorded. `conversation_mismatch` means the resolved target does not match the appointment's contact; `conversation_forbidden` means the user cannot access that conversation. Absent when `status` is `sent`.","example":"no_conversation"},"message":{"type":"string","description":"Localized explanation of `reason`. Absent when `status` is `sent`.","example":"This appointment is not linked to any conversation. Open it from the contact's conversation to send it."},"message_id":{"type":"integer","description":"Id of the recorded confirmation message. Absent when none is returned.","example":9001},"sent_at":{"type":"string","format":"date-time","description":"When the confirmation was recorded in the conversation. Absent when unavailable.","example":"2026-10-06T14:59:28Z"}}}}},"example":{"payload":{"id":1,"account_id":1,"calendar_id":1,"title":"Sample title","description":"A short description.","location":"sample location","starts_at":"2026-01-15T10:30:00.000Z","ends_at":"2026-01-15T10:30:00.000Z","all_day":true,"timezone":"America/Sao_Paulo","status":"tentative","source":"native","transparency":"opaque","event_type":{"id":1,"name":"Sample Name","color":"#1F93FF"},"event_type_id":1,"contact_id":1,"conversation_id":1,"crm_item_id":1,"task_id":1,"recurrence":{},"conferencing":{},"meet_url":"https://example.com/resource","custom_attributes":{},"additional_attributes":{},"attendees":[{"id":1,"event_id":1,"contact_id":1,"user_id":1,"email":"agent@example.com","response_status":"accepted","organizer":true,"optional":true,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}],"archived":true,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"},"confirmation":{"requested":true,"status":"sent","reason":"no_conversation","message":"This appointment is not linked to any conversation. Open it from the contact's conversation to send it.","message_id":9001,"sent_at":"2026-10-06T14:59:28Z"}}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"409":{"description":"Either the requested time overlaps an existing event while the double-booking guard is on, or the supplied idempotency key already belongs to a create intent with different normalized data.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable overlap reason or the fixed `idempotency_key_reused` code.","example":"idempotency_key_reused"},"message":{"type":["string","null"],"description":"Localized explanation for an idempotency-key conflict.","example":"This idempotency key was already used with different event data."},"conflicting_event_id":{"type":["number","null"],"description":"Id of the event already occupying the slot.","example":812}},"additionalProperties":false},"example":{"error":"idempotency_key_reused","message":"This idempotency key was already used with different event data.","conflicting_event_id":812}}}}}}},"/api/v1/accounts/{account_id}/calendar/events/{id}":{"get":{"tags":["Calendar Events"],"operationId":"get-calendar-event","summary":"Get a calendar event","security":[{"userApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"id","in":"path","required":true,"schema":{"type":"number"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"$ref":"#/components/schemas/calendar_event"}}},"example":{"payload":{"id":1,"account_id":1,"calendar_id":1,"title":"Sample title","description":"A short description.","location":"sample location","starts_at":"2026-01-15T10:30:00.000Z","ends_at":"2026-01-15T10:30:00.000Z","all_day":true,"timezone":"America/Sao_Paulo","status":"tentative","source":"native","transparency":"opaque","event_type":{"id":1,"name":"Sample Name","color":"#1F93FF"},"event_type_id":1,"contact_id":1,"conversation_id":1,"crm_item_id":1,"task_id":1,"recurrence":{},"conferencing":{},"meet_url":"https://example.com/resource","custom_attributes":{},"additional_attributes":{},"attendees":[{"id":1,"event_id":1,"contact_id":1,"user_id":1,"email":"agent@example.com","response_status":"accepted","organizer":true,"optional":true,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}],"archived":true,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}},"description":"Get a calendar event. Returns the requested Events resource."},"patch":{"tags":["Calendar Events"],"operationId":"update-calendar-event","summary":"Update a calendar event","security":[{"userApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"id","in":"path","required":true,"schema":{"type":"number"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"event":{"type":"object","properties":{"title":{"type":"string"},"description":{"type":"string"},"location":{"type":"string"},"starts_at":{"type":"string","format":"date-time"},"ends_at":{"type":"string","format":"date-time"},"all_day":{"type":"boolean"},"timezone":{"type":"string","description":"IANA timezone identifier (e.g. \"America/Sao_Paulo\", \"UTC\"). Rails timezone names are also accepted on input; an unrecognized value is ignored in favor of the next fallback.","example":"America/Sao_Paulo"},"status":{"type":"string","enum":["tentative","confirmed","cancelled"]},"contact_id":{"type":"number"},"conversation_id":{"type":"number"},"crm_item_id":{"type":"number"},"task_id":{"type":"number"},"notify_contact":{"type":"boolean","default":true,"description":"Whether the contact is told when this update moves the date/time or cancels the appointment. Absent or true, the contact is notified through the Agenda notification channels (the historical behaviour); false applies the change silently. Edits that do not move the slot never notify anyone. It is a choice about this request, never stored.","example":true},"reminders":{"type":"array","description":"Per-event reminder lead times, in MINUTES BEFORE the start. Omit the key to inherit the account / event-type default; send `[]` to silence this event's reminders entirely. The values land in `additional_attributes.reminders.lead_times_minutes`, which is where the reminder job reads them.","items":{"type":"integer"},"example":[60,1440]},"recurrence":{"type":"object","additionalProperties":true,"description":"JSONB recurrence rule: frequency (daily|weekly|monthly|yearly), interval, until, count, days."},"conferencing":{"type":"object","additionalProperties":true,"description":"JSONB conferencing details (provider, join link, entry points)."},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"additional_attributes":{"type":"object","additionalProperties":true,"description":"Channel- and source-specific metadata for this record (e.g. browser info, referer, social profile identifiers). The key set depends on the originating channel."}}}}},"example":{"event":{"title":"Sample title","description":"A short description.","location":"sample location","starts_at":"2026-01-15T10:30:00.000Z","ends_at":"2026-01-15T10:30:00.000Z","all_day":true,"timezone":"America/Sao_Paulo","status":"tentative","contact_id":1,"conversation_id":1,"crm_item_id":1,"task_id":1,"notify_contact":true,"reminders":[60,1440],"recurrence":{},"conferencing":{},"custom_attributes":{},"additional_attributes":{}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"$ref":"#/components/schemas/calendar_event"}}},"example":{"payload":{"id":1,"account_id":1,"calendar_id":1,"title":"Sample title","description":"A short description.","location":"sample location","starts_at":"2026-01-15T10:30:00.000Z","ends_at":"2026-01-15T10:30:00.000Z","all_day":true,"timezone":"America/Sao_Paulo","status":"tentative","source":"native","transparency":"opaque","event_type":{"id":1,"name":"Sample Name","color":"#1F93FF"},"event_type_id":1,"contact_id":1,"conversation_id":1,"crm_item_id":1,"task_id":1,"recurrence":{},"conferencing":{},"meet_url":"https://example.com/resource","custom_attributes":{},"additional_attributes":{},"attendees":[{"id":1,"event_id":1,"contact_id":1,"user_id":1,"email":"agent@example.com","response_status":"accepted","organizer":true,"optional":true,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}],"archived":true,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}}},"409":{"description":"The requested time overlaps an existing event and the calendar's double-booking guard is on (`calendars.prevent_double_booking`, or the account default it inherits). The conflicting event's id comes back so the caller can show what is in the way.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable reason naming the conflicting event.","example":"Conflicts with: Weekly sync"},"conflicting_event_id":{"type":"number","description":"Id of the event already occupying the slot.","example":812}},"additionalProperties":false},"example":{"error":"Conflicts with: Weekly sync","conflicting_event_id":812}}}}},"description":"Update a calendar event. Applies the submitted changes to the Events resource."},"delete":{"tags":["Calendar Events"],"operationId":"delete-calendar-event","summary":"Permanently delete a calendar event","description":"Permanently deletes the event and, when it is mirrored to Google, also deletes it from Google Calendar first. This is irreversible. To keep the record instead (a soft cancellation that round-trips to Google as a delete and can be reactivated), use the dedicated cancel action rather than this one.","security":[{"userApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"id","in":"path","required":true,"schema":{"type":"number"}}],"responses":{"200":{"description":"Success"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"Event not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"put":{"tags":["Calendar Events"],"operationId":"auto_put_api_v1_accounts_account_id_calendar_events_id","summary":"Update events","description":"Updates the event identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The updated event. Update does not request a new confirmation.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"calendar_id":{"type":"integer"},"title":{"type":"string"},"description":{"type":"string"},"location":{"type":"string"},"starts_at":{"type":"string","format":"date-time"},"ends_at":{"type":"string","format":"date-time"},"all_day":{"type":"boolean"},"timezone":{"type":"string","description":"IANA timezone identifier (e.g. \"America/Sao_Paulo\", \"UTC\"). Rails timezone names are also accepted on input; an unrecognized value is ignored in favor of the next fallback.","example":"America/Sao_Paulo"},"status":{"type":"string","enum":["confirmed","tentative","cancelled"]},"source":{"type":"string","enum":["native","google","booking"]},"transparency":{"type":"string","enum":["opaque","transparent"]},"sync_status":{"type":"string","enum":["synced","pending","sync_error"]},"recurrence":{"type":"object","additionalProperties":true,"description":"JSONB recurrence rule: frequency (daily|weekly|monthly|yearly), interval, until, count, days."},"conferencing":{"type":"object","additionalProperties":true,"description":"JSONB conferencing details (provider, join link, entry points)."},"meet_url":{"type":"string"},"google_event_id":{"type":"integer"},"recurring":{"type":"boolean"},"contact_id":{"type":"integer"},"conversation_id":{"type":"integer"},"crm_item_id":{"type":"integer"},"task_id":{"type":"integer"},"created_by_id":{"type":"integer"},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"additional_attributes":{"type":"object","additionalProperties":true,"description":"Channel- and source-specific metadata for this record (e.g. browser info, referer, social profile identifiers). The key set depends on the originating channel."},"calendar":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"color":{"type":"string"}}},"event_type":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"color":{"type":"string"}}},"event_type_id":{"type":"integer"},"contact":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"}}},"attendees":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"contact_id":{"type":"integer"},"user_id":{"type":"integer"},"email":{"type":"string","format":"email"}}}},"response_status":{"type":"string","enum":["needs_action","accepted","declined","tentative"],"description":"Canonical attendee RSVP state. The needsAction input alias is returned as needs_action."},"organizer":{"type":"string"},"optional":{"type":"string"},"archived_at":{"type":"string","format":"date-time"},"archived":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"booking_manage_token":{"type":["string","null"]},"booking_selected_location":{"type":["string","null"]},"booking_answers":{"type":"array","description":"The public booker's intake answers (each event-type question mapped to its answer), shown read-only to the agent on the appointment. Absent for a non-booking event.","items":{"type":"object","properties":{"label":{"type":"string","description":"The event-type question text."},"value":{"type":"string","description":"The booker's answer to that question."}}}}}}}},"example":{"payload":{"id":1,"account_id":1,"calendar_id":1,"title":"Sample title","description":"A short description.","location":"sample location","starts_at":"2026-01-15T10:30:00.000Z","ends_at":"2026-01-15T10:30:00.000Z","all_day":true,"timezone":"America/Sao_Paulo","status":"confirmed","source":"native","transparency":"opaque","sync_status":"synced","recurrence":{},"conferencing":{},"meet_url":"https://example.com/resource","google_event_id":1,"recurring":true,"contact_id":1,"conversation_id":1,"crm_item_id":1,"task_id":1,"created_by_id":1,"custom_attributes":{},"additional_attributes":{},"calendar":{"id":1,"name":"Sample Name","color":"#1F93FF"},"event_type":{"id":1,"name":"Sample Name","color":"#1F93FF"},"event_type_id":1,"contact":{"id":1,"name":"Sample Name"},"attendees":[{"id":1,"contact_id":1,"user_id":1,"email":"agent@example.com"}],"response_status":"needs_action","organizer":"sample organizer","optional":"sample optional","archived_at":"2026-01-15T10:30:00.000Z","archived":true,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","booking_manage_token":"sample-token","booking_selected_location":"sample booking selected location","booking_answers":[{"label":"sample label","value":"sample value"}]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"event":{"type":"object","properties":{"calendar_id":{"type":"integer"},"title":{"type":"string"},"description":{"type":"string"},"location":{"type":"string"},"starts_at":{"type":"string","format":"date-time"},"ends_at":{"type":"string","format":"date-time"},"all_day":{"type":"boolean"},"timezone":{"type":"string","description":"IANA timezone identifier (e.g. \"America/Sao_Paulo\", \"UTC\"). Rails timezone names are also accepted on input; an unrecognized value is ignored in favor of the next fallback.","example":"America/Sao_Paulo"},"status":{"type":"string","enum":["confirmed","tentative","cancelled"]},"source":{"type":"string","enum":["native","google","booking"]},"contact_id":{"type":"integer"},"conversation_id":{"type":"integer"},"crm_item_id":{"type":"integer"},"task_id":{"type":"integer"},"send_confirmation":{"type":"boolean","description":"Creation-only option accepted by the shared whitelist; ignored by update. It does not request a confirmation here."},"notify_contact":{"type":"boolean","default":true,"description":"Whether a committed time or status change should notify the contact. Omitted or blank uses true."},"reminders":{"type":"array","items":{"type":"integer"}},"recurrence":{"type":"object","additionalProperties":true,"description":"JSONB recurrence rule: frequency (daily|weekly|monthly|yearly), interval, until, count, days."},"conferencing":{"type":"object","additionalProperties":true,"description":"JSONB conferencing details (provider, join link, entry points)."},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"additional_attributes":{"type":"object","additionalProperties":true,"description":"Channel- and source-specific metadata for this record (e.g. browser info, referer, social profile identifiers). The key set depends on the originating channel."},"attendees":{"type":"object","additionalProperties":true,"description":"Free-form object."}}}},"required":["event"]},"example":{"event":{"calendar_id":1,"title":"Sample title","description":"A short description.","location":"sample location","starts_at":"2026-01-15T10:30:00.000Z","ends_at":"2026-01-15T10:30:00.000Z","all_day":true,"timezone":"America/Sao_Paulo","status":"confirmed","source":"native","contact_id":1,"conversation_id":1,"crm_item_id":1,"task_id":1,"send_confirmation":false,"notify_contact":true,"reminders":[60],"recurrence":{},"conferencing":{},"custom_attributes":{},"additional_attributes":{},"attendees":{}}}}}}}},"/api/v1/accounts/{account_id}/calendar/events/{id}/reschedule":{"patch":{"tags":["Calendar Events"],"operationId":"reschedule-calendar-event","summary":"Reschedule a calendar event (Maestro sensitive)","description":"Update starts_at and ends_at. Propagates to Google and linked records. The linked contact is told about the new time through the Agenda notification channels unless `notify_contact` is false.","security":[{"userApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"id","in":"path","required":true,"schema":{"type":"number"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"starts_at":{"type":"string","format":"date-time"},"ends_at":{"type":"string","format":"date-time"},"notify_contact":{"type":"boolean","default":true,"description":"Whether the contact is told about the new time. Absent or true, the contact is notified (the historical behaviour); false moves the appointment silently.","example":true}}},"example":{"starts_at":"2026-01-15T10:30:00.000Z","ends_at":"2026-01-15T10:30:00.000Z","notify_contact":true}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"$ref":"#/components/schemas/calendar_event"}}},"example":{"payload":{"id":1,"account_id":1,"calendar_id":1,"title":"Sample title","description":"A short description.","location":"sample location","starts_at":"2026-01-15T10:30:00.000Z","ends_at":"2026-01-15T10:30:00.000Z","all_day":true,"timezone":"America/Sao_Paulo","status":"tentative","source":"native","transparency":"opaque","event_type":{"id":1,"name":"Sample Name","color":"#1F93FF"},"event_type_id":1,"contact_id":1,"conversation_id":1,"crm_item_id":1,"task_id":1,"recurrence":{},"conferencing":{},"meet_url":"https://example.com/resource","custom_attributes":{},"additional_attributes":{},"attendees":[{"id":1,"event_id":1,"contact_id":1,"user_id":1,"email":"agent@example.com","response_status":"accepted","organizer":true,"optional":true,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}],"archived":true,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}}},"404":{"description":"Event not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"409":{"description":"The requested time overlaps an existing event and the calendar's double-booking guard is on (`calendars.prevent_double_booking`, or the account default it inherits). The conflicting event's id comes back so the caller can show what is in the way.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable reason naming the conflicting event.","example":"Conflicts with: Weekly sync"},"conflicting_event_id":{"type":"number","description":"Id of the event already occupying the slot.","example":812}},"additionalProperties":false},"example":{"error":"Conflicts with: Weekly sync","conflicting_event_id":812}}}}}}},"/api/v1/accounts/{account_id}/calendar/events/{id}/cancel":{"patch":{"tags":["Calendar Events"],"operationId":"cancel-calendar-event","summary":"Cancel a calendar event (Maestro sensitive)","description":"Soft-cancels the event: its status becomes cancelled (the record is kept for history and reactivatable), it is removed from Google Calendar, and the contact is notified (email + channel-aware message) unless `notify_contact` is false. An optional cancellation reason is persisted with the event for the account's own history; it is not included in the message to the contact.","security":[{"userApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"id","in":"path","required":true,"schema":{"type":"number"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","description":"Optional cancellation reason, persisted with the event. Not sent to the contact."},"notify_contact":{"type":"boolean","default":true,"description":"Whether the contact is told about the cancellation. Absent or true, the contact is notified (the historical behaviour); false cancels silently."}},"example":{"reason":"Client requested a different day","notify_contact":true}},"example":{"reason":"Client requested a different day","notify_contact":true}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"$ref":"#/components/schemas/calendar_event"}}},"example":{"payload":{"id":1,"account_id":1,"calendar_id":1,"title":"Sample title","description":"A short description.","location":"sample location","starts_at":"2026-01-15T10:30:00.000Z","ends_at":"2026-01-15T10:30:00.000Z","all_day":true,"timezone":"America/Sao_Paulo","status":"tentative","source":"native","transparency":"opaque","event_type":{"id":1,"name":"Sample Name","color":"#1F93FF"},"event_type_id":1,"contact_id":1,"conversation_id":1,"crm_item_id":1,"task_id":1,"recurrence":{},"conferencing":{},"meet_url":"https://example.com/resource","custom_attributes":{},"additional_attributes":{},"attendees":[{"id":1,"event_id":1,"contact_id":1,"user_id":1,"email":"agent@example.com","response_status":"accepted","organizer":true,"optional":true,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}],"archived":true,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}}},"404":{"description":"Event not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/calendar/events/{event_id}/attendees/{id}":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"event_id","in":"path","required":true,"schema":{"type":"number"},"description":"ID of the calendar event"},{"name":"id","in":"path","required":true,"schema":{"type":"number"},"description":"ID of the attendee"}],"delete":{"tags":["Calendar Events"],"operationId":"remove-calendar-event-attendee","summary":"Remove an attendee from a calendar event","security":[{"userApiKey":[]}],"description":"Remove one invitee from the event by attendee id. The remaining attendee set is untouched.","responses":{"200":{"description":"Success"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"Event or attendee not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/calendar/events/{event_id}/attendees":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"event_id","in":"path","required":true,"schema":{"type":"number"},"description":"ID of the calendar event"}],"get":{"tags":["Calendar Events"],"operationId":"list-calendar-event-attendees","summary":"List the attendees of a calendar event","security":[{"userApiKey":[]}],"description":"The event's current participants (contacts, agents or plain emails), ordered by id.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/calendar_attendee"}},"example":[{"id":1,"event_id":1,"contact_id":1,"user_id":1,"email":"agent@example.com","response_status":"accepted","organizer":true,"optional":true,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}]}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"Event not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"post":{"tags":["Calendar Events"],"operationId":"add-calendar-event-attendee","summary":"Add an attendee to a calendar event","security":[{"userApiKey":[]}],"description":"Add one invitee (identified by contact_id, user_id or email) to the event. The new invitee is merged into the existing attendee set — adding never drops the others, and a duplicate identity is idempotent. Returns the event's full attendee list.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["attendee"],"properties":{"attendee":{"type":"object","description":"Identify the invitee via contact_id, user_id or email.","properties":{"contact_id":{"type":"number"},"user_id":{"type":"number"},"email":{"type":"string"},"response_status":{"type":"string","enum":["needs_action","accepted","declined","tentative","needsAction"],"description":"Attendee RSVP input. Google Calendar's needsAction alias is accepted and stored as needs_action; any other value is rejected with 422."},"organizer":{"type":"boolean"},"optional":{"type":"boolean"}}}}},"example":{"attendee":{"contact_id":1,"user_id":1,"email":"agent@example.com","response_status":"needs_action","organizer":true,"optional":true}}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/calendar_attendee"}},"example":[{"id":1,"event_id":1,"contact_id":1,"user_id":1,"email":"agent@example.com","response_status":"accepted","organizer":true,"optional":true,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}]}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"Event not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/calendar/events/{id}/restore":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"id","in":"path","required":true,"schema":{"type":"number"},"description":"ID of the event"}],"post":{"tags":["Calendar Events"],"operationId":"restore-a-calendar-event","summary":"Restore a cancelled calendar event","security":[{"userApiKey":[]}],"description":"Reverse a cancellation — transitions the event status from cancelled back to confirmed. This only reverses the cancel action; it does not recover a permanently deleted event (a delete is irreversible).","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"$ref":"#/components/schemas/calendar_event"}}},"example":{"payload":{"id":1,"account_id":1,"calendar_id":1,"title":"Sample title","description":"A short description.","location":"sample location","starts_at":"2026-01-15T10:30:00.000Z","ends_at":"2026-01-15T10:30:00.000Z","all_day":true,"timezone":"America/Sao_Paulo","status":"tentative","source":"native","transparency":"opaque","event_type":{"id":1,"name":"Sample Name","color":"#1F93FF"},"event_type_id":1,"contact_id":1,"conversation_id":1,"crm_item_id":1,"task_id":1,"recurrence":{},"conferencing":{},"meet_url":"https://example.com/resource","custom_attributes":{},"additional_attributes":{},"attendees":[{"id":1,"event_id":1,"contact_id":1,"user_id":1,"email":"agent@example.com","response_status":"accepted","organizer":true,"optional":true,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}],"archived":true,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"Event not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"409":{"description":"The requested time overlaps an existing event and the calendar's double-booking guard is on (`calendars.prevent_double_booking`, or the account default it inherits). The conflicting event's id comes back so the caller can show what is in the way.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable reason naming the conflicting event.","example":"Conflicts with: Weekly sync"},"conflicting_event_id":{"type":"number","description":"Id of the event already occupying the slot.","example":812}},"additionalProperties":false},"example":{"error":"Conflicts with: Weekly sync","conflicting_event_id":812}}}}}}},"/api/v1/accounts/{account_id}/calendar/events/{id}/send_to_conversation":{"post":{"tags":["Calendar Events"],"operationId":"send-calendar-event-to-conversation","summary":"Send a calendar event's confirmation to a conversation","description":"Posts the appointment's confirmation into a conversation as an outgoing message authored by the caller. It is the same message a public booking produces: the same operator template and settings, with native buttons where the channel has them and plain text where it does not. Without `conversation_id` the appointment's own linked conversation is used. Both named and linked destinations must match the appointment's contact. The caller must also have access to the final destination conversation: a conversation access refusal answers 403 with `error_code: conversation_forbidden`, while a different contact answers 422 with `error_code: conversation_mismatch`.\nHTTP 200 means a confirmation message is durably recorded in the conversation, including when a post-save publication failed; it does not confirm that the channel delivered it to the contact. Retry the same appointment/key to recover that recorded result instead of requesting another copy. An appointment whose confirmation was already recorded answers 409 until the caller explicitly requests a new copy with `resend: true`. Send intents are serialized per appointment; the last recorded confirmation is exposed at `additional_attributes.contact_notifications.confirmation`. No reachable conversation, a closed WhatsApp 24-hour window with no approved template, a cancelled or finished appointment and a message that could not be created answer 422 with a machine-readable `error_code`. Event creation only requests this confirmation with `send_confirmation: true`; event updates do not implicitly request a confirmation.","security":[{"userApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"id","in":"path","required":true,"schema":{"type":"number"},"description":"ID of the calendar event"},{"name":"X-Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Stable caller key for one send intent, scoped to this appointment. Retrying the same event/key returns the recorded result (with `X-Idempotent-Replayed: true`) instead of creating another message; using the same caller key for another event does not reuse this event's message. Replays still enforce the current recipient and conversation access checks. Use a new key for an intentionally new copy with `resend: true`.","example":"calendar-event-550e8400-e29b-41d4-a716-446655440000"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"conversation_id":{"type":"number","description":"Conversation to post into (display id; an internal id is accepted as a fallback). Omit it to use the appointment's own linked conversation. When the appointment has a contact, both the named and linked target must resolve to that contact (including the canonical WhatsApp contact identity). The caller must have access to the final target conversation.","example":42},"resend":{"type":"boolean","default":false,"description":"Confirms that a new copy is intended. Required once a confirmation was already recorded for this appointment; false by default. Reusing the same idempotency key remains a retry, even with this flag set; use a new key to request a new copy.","example":false}},"example":{"conversation_id":42,"resend":false}},"example":{"conversation_id":42,"resend":false}}}},"responses":{"200":{"description":"A confirmation message is durably recorded in the conversation, or the same intent is replayed. The reconciled event is returned. Publication or channel delivery may still be pending; this payload does not expose a publication-status field or confirm receipt by the contact.","headers":{"X-Idempotent-Replayed":{"description":"Present and fixed to true when this response replays an earlier send made with the same key.","schema":{"type":"string","enum":["true"]}}},"content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"$ref":"#/components/schemas/calendar_event"}}},"example":{"payload":{"id":1,"account_id":1,"calendar_id":1,"title":"Sample title","description":"A short description.","location":"sample location","starts_at":"2026-01-15T10:30:00.000Z","ends_at":"2026-01-15T10:30:00.000Z","all_day":true,"timezone":"America/Sao_Paulo","status":"tentative","source":"native","transparency":"opaque","event_type":{"id":1,"name":"Sample Name","color":"#1F93FF"},"event_type_id":1,"contact_id":1,"conversation_id":1,"crm_item_id":1,"task_id":1,"recurrence":{},"conferencing":{},"meet_url":"https://example.com/resource","custom_attributes":{},"additional_attributes":{},"attendees":[{"id":1,"event_id":1,"contact_id":1,"user_id":1,"email":"agent@example.com","response_status":"accepted","organizer":true,"optional":true,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}],"archived":true,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"403":{"description":"The authenticated caller is not allowed to access the final destination conversation. No new confirmation message is created, including for a replay of an earlier request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Localized conversation access refusal.","example":"You do not have permission to send messages in this conversation."},"error_code":{"type":"string","enum":["conversation_forbidden"],"example":"conversation_forbidden"}},"additionalProperties":false},"example":{"error":"You do not have permission to send messages in this conversation.","error_code":"conversation_forbidden"}}}},"404":{"description":"Event or conversation not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"409":{"description":"A confirmation was already recorded for this appointment and this is not a replay of that intent or an explicitly confirmed new copy with `resend: true`. No new message is created.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Localized explanation.","example":"The confirmation for this appointment was already sent to the contact. Confirm the resend to send it again."},"error_code":{"type":"string","enum":["confirmation_already_sent"],"example":"confirmation_already_sent"},"sent_at":{"type":"string","format":"date-time","description":"When the previous confirmation was recorded in the conversation.","example":"2026-10-06T14:59:28Z"}},"additionalProperties":false},"example":{"error":"The confirmation for this appointment was already sent to the contact. Confirm the resend to send it again.","error_code":"confirmation_already_sent","sent_at":"2026-10-06T14:59:28Z"}}}},"422":{"description":"No new confirmation message is created for this request. `error_code` names why.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Localized explanation.","example":"This appointment is not linked to any conversation. Open it from the contact's conversation to send it."},"error_code":{"type":"string","enum":["no_conversation","conversation_mismatch","event_cancelled","event_ended","whatsapp_window_closed","delivery_failed"],"description":"`no_conversation`: no conversation was named and the appointment has none. `conversation_mismatch`: the named or linked target does not match the appointment's contact. `event_cancelled` / `event_ended`: the appointment is cancelled or already over. `whatsapp_window_closed`: the 24-hour window is closed and no approved template is configured for the confirmation. `delivery_failed`: the message could not be created.","example":"no_conversation"}},"additionalProperties":false},"example":{"error":"This appointment is not linked to any conversation. Open it from the contact's conversation to send it.","error_code":"no_conversation"}}}}}}},"/api/v1/accounts/{account_id}/calendar/event_types":{"get":{"tags":["Calendar Event Types"],"operationId":"list-calendar-event-types","summary":"List bookable event types","description":"List event types. Pass `archived=true` for archived types.","security":[{"userApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"archived","in":"query","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"$ref":"#/components/schemas/calendar_event_type"}},"meta":{"type":"object","properties":{"count":{"type":"number"},"current_page":{"type":"number"},"per_page":{"type":"number"},"has_more":{"type":"boolean"}}}}},"example":{"payload":[{"id":1,"account_id":1,"name":"Sample Name","slug":"sample-slug","public_token":"sample-token","duration_minutes":12.5,"occupancy":"slot","buffer_before":12.5,"buffer_after":12.5,"min_notice_minutes":12.5,"max_advance_days":12.5,"min_cancel_notice_minutes":12.5,"max_reschedules":12.5,"auto_no_show_minutes":12.5,"resolved_scheduling_limits":{"buffer_before":12.5,"buffer_after":12.5,"min_notice_minutes":12.5,"min_cancel_notice_minutes":12.5,"max_advance_days":12.5},"inherited_scheduling_limits":["buffer_before"],"location_type":"in_person","location_options":["in_person"],"host_assignment":"sample host assignment","is_public":true,"color":"#1F93FF","confirmation_message":"sample confirmation message","redirect_url":"https://example.com/resource","catalog_product_id":1,"questions":[{"id":"sample id","label":"sample label","type":"text","required":true,"placeholder":"sample placeholder","options":["sample option"]}],"location_details":{},"intake_phone_required":true,"guest_emails_enabled":true,"max_guests":12.5,"google_conflict_calendar_ids":[1],"google_destination_calendar_id":1,"side_effects":{},"archived":true,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}],"meta":{"count":5,"current_page":12.5,"per_page":12.5,"has_more":true}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"post":{"tags":["Calendar Event Types"],"operationId":"create-calendar-event-type","summary":"Create a bookable event type","description":"Creates a Calendly-style bookable event type. The response carries the full event type, including the opaque `public_token` its public booking page is keyed by. Returns 201 Created.","security":[{"userApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/account_id"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"event_type":{"allOf":[{"$ref":"#/components/schemas/calendar_event_type_write"},{"type":"object","description":"The two fields that have no server-side default and must therefore be supplied on create. Everything else is optional and falls back to the account's calendar settings.","required":["name","duration_minutes"],"properties":{"name":{"type":"string","description":"Operator-facing name of the event type."},"duration_minutes":{"type":"number","description":"Length of the appointment in minutes."}}}]}}},"example":{"event_type":{"name":"Sample Name","slug":"sample-slug","duration_minutes":12.5,"buffer_before":12.5,"buffer_after":12.5,"occupancy":"slot","min_notice_minutes":12.5,"max_advance_days":12.5,"min_cancel_notice_minutes":12.5,"max_reschedules":12.5,"auto_no_show_minutes":12.5,"location_type":"in_person","location_options":["in_person"],"location_details":{"in_person":"sample in person","phone":"+5511999998888","custom":"sample custom"},"host_assignment":"round_robin","is_public":true,"color":"#1F93FF","confirmation_message":"sample confirmation message","redirect_url":"https://example.com/resource","catalog_product_id":1,"intake_phone_required":true,"guest_emails_enabled":true,"max_guests":12.5,"google_conflict_calendar_ids":[1],"google_destination_calendar_id":1,"host_user_ids":[1],"questions":[{"id":"sample id","label":"sample label","type":"text","required":true,"placeholder":"sample placeholder","options":["sample option"]}],"payment_mode":"none","payment_hold_mode":"reserve_and_hold","payment_amount":"sample payment amount","payment_currency":"sample payment currency","payments_connection_id":1,"payments_plan_id":1,"payment_billing_types":["sample payment billing type"],"payment_hold_minutes":12.5,"payment_deposit_amount":"sample payment deposit amount","availability_rules":[{"day_of_week":12.5,"start_minute":12.5,"end_minute":12.5}]}}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"$ref":"#/components/schemas/calendar_event_type"}}},"example":{"payload":{"id":1,"account_id":1,"name":"Sample Name","slug":"sample-slug","public_token":"sample-token","duration_minutes":12.5,"occupancy":"slot","buffer_before":12.5,"buffer_after":12.5,"min_notice_minutes":12.5,"max_advance_days":12.5,"min_cancel_notice_minutes":12.5,"max_reschedules":12.5,"auto_no_show_minutes":12.5,"resolved_scheduling_limits":{"buffer_before":12.5,"buffer_after":12.5,"min_notice_minutes":12.5,"min_cancel_notice_minutes":12.5,"max_advance_days":12.5},"inherited_scheduling_limits":["buffer_before"],"location_type":"in_person","location_options":["in_person"],"host_assignment":"sample host assignment","is_public":true,"color":"#1F93FF","confirmation_message":"sample confirmation message","redirect_url":"https://example.com/resource","catalog_product_id":1,"questions":[{"id":"sample id","label":"sample label","type":"text","required":true,"placeholder":"sample placeholder","options":["sample option"]}],"location_details":{},"intake_phone_required":true,"guest_emails_enabled":true,"max_guests":12.5,"google_conflict_calendar_ids":[1],"google_destination_calendar_id":1,"side_effects":{},"archived":true,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/calendar/event_types/{id}":{"get":{"tags":["Calendar Event Types"],"operationId":"get-calendar-event-type","summary":"Get a bookable event type","security":[{"userApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"id","in":"path","required":true,"schema":{"type":"number"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"$ref":"#/components/schemas/calendar_event_type"}}},"example":{"payload":{"id":1,"account_id":1,"name":"Sample Name","slug":"sample-slug","public_token":"sample-token","duration_minutes":12.5,"occupancy":"slot","buffer_before":12.5,"buffer_after":12.5,"min_notice_minutes":12.5,"max_advance_days":12.5,"min_cancel_notice_minutes":12.5,"max_reschedules":12.5,"auto_no_show_minutes":12.5,"resolved_scheduling_limits":{"buffer_before":12.5,"buffer_after":12.5,"min_notice_minutes":12.5,"min_cancel_notice_minutes":12.5,"max_advance_days":12.5},"inherited_scheduling_limits":["buffer_before"],"location_type":"in_person","location_options":["in_person"],"host_assignment":"sample host assignment","is_public":true,"color":"#1F93FF","confirmation_message":"sample confirmation message","redirect_url":"https://example.com/resource","catalog_product_id":1,"questions":[{"id":"sample id","label":"sample label","type":"text","required":true,"placeholder":"sample placeholder","options":["sample option"]}],"location_details":{},"intake_phone_required":true,"guest_emails_enabled":true,"max_guests":12.5,"google_conflict_calendar_ids":[1],"google_destination_calendar_id":1,"side_effects":{},"archived":true,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}},"description":"Get a bookable event type. Returns the requested Event types resource."},"patch":{"tags":["Calendar Event Types"],"operationId":"update-calendar-event-type","summary":"Update a bookable event type","description":"Partial update. Keys that are absent are left untouched; this matters for the collection-valued fields — sending `availability_rules: []`, `google_conflict_calendar_ids: []` or `location_options: []` CLEARS that set, while omitting the key leaves it as it is.","security":[{"userApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"id","in":"path","required":true,"schema":{"type":"number"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"event_type":{"$ref":"#/components/schemas/calendar_event_type_write"}}},"example":{"event_type":{"name":"Sample Name","slug":"sample-slug","duration_minutes":12.5,"buffer_before":12.5,"buffer_after":12.5,"occupancy":"slot","min_notice_minutes":12.5,"max_advance_days":12.5,"min_cancel_notice_minutes":12.5,"max_reschedules":12.5,"auto_no_show_minutes":12.5,"location_type":"in_person","location_options":["in_person"],"location_details":{"in_person":"sample in person","phone":"+5511999998888","custom":"sample custom"},"host_assignment":"round_robin","is_public":true,"color":"#1F93FF","confirmation_message":"sample confirmation message","redirect_url":"https://example.com/resource","catalog_product_id":1,"intake_phone_required":true,"guest_emails_enabled":true,"max_guests":12.5,"google_conflict_calendar_ids":[1],"google_destination_calendar_id":1,"host_user_ids":[1],"questions":[{"id":"sample id","label":"sample label","type":"text","required":true,"placeholder":"sample placeholder","options":["sample option"]}],"payment_mode":"none","payment_hold_mode":"reserve_and_hold","payment_amount":"sample payment amount","payment_currency":"sample payment currency","payments_connection_id":1,"payments_plan_id":1,"payment_billing_types":["sample payment billing type"],"payment_hold_minutes":12.5,"payment_deposit_amount":"sample payment deposit amount","availability_rules":[{"day_of_week":12.5,"start_minute":12.5,"end_minute":12.5}]}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"$ref":"#/components/schemas/calendar_event_type"}}},"example":{"payload":{"id":1,"account_id":1,"name":"Sample Name","slug":"sample-slug","public_token":"sample-token","duration_minutes":12.5,"occupancy":"slot","buffer_before":12.5,"buffer_after":12.5,"min_notice_minutes":12.5,"max_advance_days":12.5,"min_cancel_notice_minutes":12.5,"max_reschedules":12.5,"auto_no_show_minutes":12.5,"resolved_scheduling_limits":{"buffer_before":12.5,"buffer_after":12.5,"min_notice_minutes":12.5,"min_cancel_notice_minutes":12.5,"max_advance_days":12.5},"inherited_scheduling_limits":["buffer_before"],"location_type":"in_person","location_options":["in_person"],"host_assignment":"sample host assignment","is_public":true,"color":"#1F93FF","confirmation_message":"sample confirmation message","redirect_url":"https://example.com/resource","catalog_product_id":1,"questions":[{"id":"sample id","label":"sample label","type":"text","required":true,"placeholder":"sample placeholder","options":["sample option"]}],"location_details":{},"intake_phone_required":true,"guest_emails_enabled":true,"max_guests":12.5,"google_conflict_calendar_ids":[1],"google_destination_calendar_id":1,"side_effects":{},"archived":true,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"delete":{"tags":["Calendar Event Types"],"operationId":"delete-calendar-event-type","summary":"Archive (soft-delete) a bookable event type","security":[{"userApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"id","in":"path","required":true,"schema":{"type":"number"}}],"responses":{"200":{"description":"Success"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"Event type not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}},"description":"Archive (soft-delete) a bookable event type. Removes the targeted Event types resource."},"put":{"tags":["Calendar Event Types"],"operationId":"auto_put_api_v1_accounts_account_id_calendar_event_types_id","summary":"Update event types","description":"Updates the event type identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"calendar_id":{"type":"integer"},"name":{"type":"string"},"slug":{"type":"string"},"public_token":{"type":"string"},"duration_minutes":{"type":"integer"},"occupancy":{"type":"string","enum":["slot","availability_window"]},"buffer_before":{"type":"string"},"buffer_after":{"type":"string"},"min_notice_minutes":{"type":"integer"},"max_advance_days":{"type":"integer"},"min_cancel_notice_minutes":{"type":"integer"},"max_reschedules":{"type":"string"},"auto_no_show_minutes":{"type":"integer"},"resolved_scheduling_limits":{"type":"string"},"inherited_scheduling_limits":{"type":"string"},"location_type":{"type":"string","enum":["in_person","phone","google_meet","custom"],"description":"Where a bookable meeting takes place."},"location_options":{"type":"string"},"location_details":{"type":"object","additionalProperties":true,"description":"Resolved conferencing/location info for a booking (no host-only PII)."},"host_assignment":{"type":"string","enum":["round_robin","collective","fixed"]},"host_user_ids":{"type":"array","items":{"type":"integer"}},"questions":{"type":"string"},"intake_phone_required":{"type":"string"},"guest_emails_enabled":{"type":"boolean"},"max_guests":{"type":"string"},"google_conflict_calendar_ids":{"type":"array","items":{"type":"integer"}},"google_destination_calendar_id":{"type":"integer"},"side_effects":{"type":"object","additionalProperties":true,"description":"JSONB automation side-effect toggles (conversation, task, crm_deal, meet, ics_email, whatsapp_web_event)."},"is_public":{"type":"boolean"},"color":{"type":"string"},"confirmation_message":{"type":"string"},"redirect_url":{"type":"string"},"catalog_product_id":{"type":"integer"},"payment_mode":{"type":"string","enum":["none","one_off","subscription_gate","recurring"]},"payment_hold_mode":{"type":"string","enum":["reserve_and_hold","pay_first"]},"payment_amount":{"type":"number"},"payment_currency":{"type":"string"},"payments_connection_id":{"type":"integer"},"payments_plan_id":{"type":"integer"},"payment_billing_types":{"type":"string"},"payment_hold_minutes":{"type":"integer"},"payment_deposit_amount":{"type":"number"},"resolved_payment_amount":{"type":"number"},"resolved_payment_currency":{"type":"string"},"availability_rules":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"day_of_week":{"type":"string"},"start_minute":{"type":"string"},"end_minute":{"type":"string"}}}},"archived_at":{"type":"string","format":"date-time"},"archived":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}},"example":{"payload":{"id":1,"account_id":1,"calendar_id":1,"name":"Sample Name","slug":"sample-slug","public_token":"sample-token","duration_minutes":60,"occupancy":"slot","buffer_before":"sample buffer before","buffer_after":"sample buffer after","min_notice_minutes":60,"max_advance_days":7,"min_cancel_notice_minutes":60,"max_reschedules":"sample max reschedules","auto_no_show_minutes":60,"resolved_scheduling_limits":"sample resolved scheduling limits","inherited_scheduling_limits":"sample inherited scheduling limits","location_type":"in_person","location_options":"sample location options","location_details":{},"host_assignment":"round_robin","host_user_ids":[1],"questions":"sample questions","intake_phone_required":"+5511999998888","guest_emails_enabled":true,"max_guests":"sample max guests","google_conflict_calendar_ids":[1],"google_destination_calendar_id":1,"side_effects":{},"is_public":true,"color":"#1F93FF","confirmation_message":"sample confirmation message","redirect_url":"https://example.com/resource","catalog_product_id":1,"payment_mode":"none","payment_hold_mode":"reserve_and_hold","payment_amount":149.9,"payment_currency":"sample payment currency","payments_connection_id":1,"payments_plan_id":1,"payment_billing_types":"sample payment billing types","payment_hold_minutes":60,"payment_deposit_amount":149.9,"resolved_payment_amount":149.9,"resolved_payment_currency":"sample resolved payment currency","availability_rules":[{"id":1,"day_of_week":"sample day of week","start_minute":"sample start minute","end_minute":"sample end minute"}],"archived_at":"2026-01-15T10:30:00.000Z","archived":true,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"event_type":{"type":"object","properties":{"calendar_id":{"type":"integer"},"name":{"type":"string"},"slug":{"type":"string"},"duration_minutes":{"type":"integer"},"occupancy":{"type":"string","enum":["slot","availability_window"]},"buffer_before":{"type":"string"},"buffer_after":{"type":"string"},"min_notice_minutes":{"type":"integer"},"max_advance_days":{"type":"integer"},"min_cancel_notice_minutes":{"type":"integer"},"max_reschedules":{"type":"string"},"auto_no_show_minutes":{"type":"integer"},"location_type":{"type":"string","enum":["in_person","phone","google_meet","custom"],"description":"Where a bookable meeting takes place."},"host_assignment":{"type":"string","enum":["round_robin","collective","fixed"]},"is_public":{"type":"boolean"},"color":{"type":"string"},"confirmation_message":{"type":"string"},"redirect_url":{"type":"string"},"catalog_product_id":{"type":"integer"},"payment_mode":{"type":"string","enum":["none","one_off","subscription_gate","recurring"]},"payment_hold_mode":{"type":"string","enum":["reserve_and_hold","pay_first"]},"payment_amount":{"type":"number"},"payment_currency":{"type":"string"},"payments_connection_id":{"type":"integer"},"payments_plan_id":{"type":"integer"},"payment_hold_minutes":{"type":"integer"},"payment_deposit_amount":{"type":"number"},"intake_phone_required":{"type":"string"},"guest_emails_enabled":{"type":"boolean"},"max_guests":{"type":"string"},"google_destination_calendar_id":{"type":"integer"},"host_user_ids":{"type":"array","items":{"type":"integer"}},"payment_billing_types":{"type":"array","items":{"type":"string"}},"questions":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Free-form object."}},"location_options":{"type":"array","items":{"type":"string"}},"location_details":{"type":"object","additionalProperties":true,"description":"Resolved conferencing/location info for a booking (no host-only PII)."},"google_conflict_calendar_ids":{"type":"array","items":{"type":"integer"}},"availability_rules":{"type":"object","additionalProperties":true,"description":"Free-form object."}}}},"required":["event_type"]},"example":{"event_type":{"calendar_id":1,"name":"Sample Name","slug":"sample-slug","duration_minutes":60,"occupancy":"slot","buffer_before":"sample buffer before","buffer_after":"sample buffer after","min_notice_minutes":60,"max_advance_days":7,"min_cancel_notice_minutes":60,"max_reschedules":"sample max reschedules","auto_no_show_minutes":60,"location_type":"in_person","host_assignment":"round_robin","is_public":true,"color":"#1F93FF","confirmation_message":"sample confirmation message","redirect_url":"https://example.com/resource","catalog_product_id":1,"payment_mode":"none","payment_hold_mode":"reserve_and_hold","payment_amount":149.9,"payment_currency":"sample payment currency","payments_connection_id":1,"payments_plan_id":1,"payment_hold_minutes":60,"payment_deposit_amount":149.9,"intake_phone_required":"+5511999998888","guest_emails_enabled":true,"max_guests":"sample max guests","google_destination_calendar_id":1,"host_user_ids":[1],"payment_billing_types":["sample payment billing type"],"questions":[{}],"location_options":["sample location option"],"location_details":{},"google_conflict_calendar_ids":[1],"availability_rules":{}}}}}}}},"/api/v1/accounts/{account_id}/calendar/event_types/{id}/slots":{"get":{"tags":["Calendar Event Types"],"operationId":"get-calendar-event-type-slots","summary":"Get available booking slots for an event type","description":"Returns free time slots within the requested window and timezone. The window is BOUNDED: with no `from`/`to` the next 7 days are scanned, a range wider than 31 days is clamped (never rejected), and at most 200 starts come back. `meta` says what was scanned and, when something was left out, where to resume — so ask one day at a time rather than for a whole horizon.","security":[{"userApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"id","in":"path","required":true,"schema":{"type":"number"}},{"name":"from","in":"query","required":false,"description":"Window start. Omitted, the scan starts now.","schema":{"type":"string","format":"date-time"},"example":"2026-08-05T00:00:00Z"},{"name":"to","in":"query","required":false,"description":"Window end. Omitted, 7 days after `from`. Clamped to at most 31 days after it.","schema":{"type":"string","format":"date-time"},"example":"2026-08-06T00:00:00Z"},{"name":"timezone","in":"query","required":false,"description":"IANA timezone the slots are computed and rendered in. Omitted, the account/event-type timezone applies.","schema":{"type":"string"},"example":"America/Sao_Paulo"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","description":"Free start instants, ascending, ISO-8601.","items":{"type":"string","format":"date-time"},"example":["2026-08-05T13:00:00Z","2026-08-05T13:30:00Z"]},"timezone":{"type":["string","null"],"description":"Echo of the requested `timezone` query param; null when none was sent.","example":"America/Sao_Paulo"},"meta":{"type":"object","description":"What the server actually scanned and whether anything was left out. The window is bounded so a wide-open event type cannot answer with thousands of instants (which overflowed the AI agent that consumes this endpoint, and made the public route a cheap amplification vector).","properties":{"truncated":{"type":"boolean","description":"True when more free slots exist in the scanned window than `max_slots` allows."},"window_clamped":{"type":"boolean","description":"True when the requested range was wider than `max_window_days` and was shortened."},"max_slots":{"type":"integer","description":"Hard ceiling on how many starts one response may carry.","example":200},"max_window_days":{"type":"integer","description":"Hard ceiling on how many days one request may scan.","example":31},"next_from":{"type":["string","null"],"format":"date-time","description":"Where to resume to get what this response left out — the first start that did not fit when `truncated`, the end of the scanned window when `window_clamped`, and null when this response is the complete answer for the requested window.","example":"2026-08-12T13:00:00Z"},"window":{"type":"object","description":"The range that was actually scanned, after defaulting and clamping.","properties":{"from":{"type":"string","format":"date-time","description":"Start of the scanned window.","example":"2026-08-05T12:00:00Z"},"to":{"type":"string","format":"date-time","description":"End of the scanned window.","example":"2026-08-12T12:00:00Z"}},"additionalProperties":false}},"additionalProperties":false}}},"example":{"payload":["2026-08-05T13:00:00Z","2026-08-05T13:30:00Z"],"timezone":"America/Sao_Paulo","meta":{"truncated":true,"window_clamped":true,"max_slots":200,"max_window_days":31,"next_from":"2026-08-12T13:00:00Z","window":{"from":"2026-08-05T12:00:00Z","to":"2026-08-12T12:00:00Z"}}}}}},"404":{"description":"Event type not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/calendar/event_types/{id}/send_link":{"post":{"tags":["Calendar Event Types"],"operationId":"send-calendar-booking-link","summary":"Post the public booking URL into a conversation (Maestro calendar_send_booking_link)","description":"Posts the event type's public booking URL into the conversation as an outgoing message and returns the URL. When `conversation_id` is omitted nothing is posted and only the URL is returned. With a `conversation_id`, HTTP 200 means the message was created: an unknown conversation answers 404 and a message that could not be created answers 422. Human callers send as themselves. Bot callers must name a conversation and authenticate as the active bot bound to the conversation's inbox; the message is then authored by that bot. Any other bot, or a user credential asserting bot authorship, is refused.","security":[{"userApiKey":[]},{"agentBotApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"X-Chatwoot-Message-Author","in":"header","required":false,"schema":{"type":"string","enum":["agent_bot"]},"description":"Optional assertion requiring authenticated AgentBot credentials. This header alone does not authenticate a caller."},{"name":"id","in":"path","required":true,"schema":{"type":"number"}},{"name":"X-Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Stable caller key for retrying this exact booking-link send without creating another message."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"conversation_id":{"type":"number","description":"The conversation to post the booking link into."}}},"example":{"conversation_id":1}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"url":{"type":"string","description":"The public booking URL."},"public_token":{"type":"string"}}}}},"example":{"payload":{"url":"https://example.com/resource","public_token":"sample-token"}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"Event type or conversation not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"422":{"description":"The booking link message could not be created in the conversation; nothing was sent.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/calendar/event_types/{id}/purge":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"id","in":"path","required":true,"schema":{"type":"number"},"description":"ID of the event type"}],"delete":{"tags":["Calendar Event Types"],"operationId":"purge-a-calendar-event-type","summary":"Permanently delete an archived event type","security":[{"userApiKey":[]}],"description":"Permanently delete an ARCHIVED event type (admin-only). Owned config is cascaded (its availability windows/overrides and scoped settings). Bookings are operational history and are NOT cascaded. Deleting the row frees the (account, slug) unique key for reuse.","responses":{"200":{"description":"Success"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"422":{"description":"The event type must be archived before it can be purged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"Event type not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/calendar/event_types/{id}/restore":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"id","in":"path","required":true,"schema":{"type":"number"},"description":"ID of the event type"}],"post":{"tags":["Calendar Event Types"],"operationId":"restore-a-calendar-event-type","summary":"Restore an archived event type","security":[{"userApiKey":[]}],"description":"Bring a soft-deleted (archived) event type back to the active list and public booking.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"$ref":"#/components/schemas/calendar_event_type"}}},"example":{"payload":{"id":1,"account_id":1,"name":"Sample Name","slug":"sample-slug","public_token":"sample-token","duration_minutes":12.5,"occupancy":"slot","buffer_before":12.5,"buffer_after":12.5,"min_notice_minutes":12.5,"max_advance_days":12.5,"min_cancel_notice_minutes":12.5,"max_reschedules":12.5,"auto_no_show_minutes":12.5,"resolved_scheduling_limits":{"buffer_before":12.5,"buffer_after":12.5,"min_notice_minutes":12.5,"min_cancel_notice_minutes":12.5,"max_advance_days":12.5},"inherited_scheduling_limits":["buffer_before"],"location_type":"in_person","location_options":["in_person"],"host_assignment":"sample host assignment","is_public":true,"color":"#1F93FF","confirmation_message":"sample confirmation message","redirect_url":"https://example.com/resource","catalog_product_id":1,"questions":[{"id":"sample id","label":"sample label","type":"text","required":true,"placeholder":"sample placeholder","options":["sample option"]}],"location_details":{},"intake_phone_required":true,"guest_emails_enabled":true,"max_guests":12.5,"google_conflict_calendar_ids":[1],"google_destination_calendar_id":1,"side_effects":{},"archived":true,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"Event type not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/calendar/connections":{"get":{"tags":["Calendar Connections"],"operationId":"list-calendar-connections","summary":"List Google OAuth connections","security":[{"userApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/account_id"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"$ref":"#/components/schemas/calendar_connection"}}}},"example":{"payload":[{"id":1,"account_id":1,"provider":"google","google_account_email":"agent@example.com","status":"active","healthy":true,"requires_reconnect":true,"last_error":"sample last error","last_error_at":"2026-01-15T10:30:00.000Z","recent_error_count":5,"connected_by_user_id":1,"poll_interval_minutes":12.5,"calendars_count":5,"calendars":[{"id":1,"name":"Sample Name","google_calendar_id":"sample google calendar id","archived":true,"sync":{"direction":"two_way","status":"idle","last_synced_at":"2026-01-15T10:30:00.000Z","last_full_sync_at":"2026-01-15T10:30:00.000Z","watch_active":true,"watch_error":"sample watch error","last_error":"sample last error","last_error_at":"2026-01-15T10:30:00.000Z","recent_error_count":5}}],"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}},"description":"List Google OAuth connections. Returns Connections data for the current context."}},"/api/v1/accounts/{account_id}/calendar/connections/{id}":{"get":{"tags":["Calendar Connections"],"operationId":"get-calendar-connection","summary":"Get a Google OAuth connection","security":[{"userApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"id","in":"path","required":true,"schema":{"type":"number"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"$ref":"#/components/schemas/calendar_connection"}}},"example":{"payload":{"id":1,"account_id":1,"provider":"google","google_account_email":"agent@example.com","status":"active","healthy":true,"requires_reconnect":true,"last_error":"sample last error","last_error_at":"2026-01-15T10:30:00.000Z","recent_error_count":5,"connected_by_user_id":1,"poll_interval_minutes":12.5,"calendars_count":5,"calendars":[{"id":1,"name":"Sample Name","google_calendar_id":"sample google calendar id","archived":true,"sync":{"direction":"two_way","status":"idle","last_synced_at":"2026-01-15T10:30:00.000Z","last_full_sync_at":"2026-01-15T10:30:00.000Z","watch_active":true,"watch_error":"sample watch error","last_error":"sample last error","last_error_at":"2026-01-15T10:30:00.000Z","recent_error_count":5}}],"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}},"description":"Get a Google OAuth connection. Returns the requested Connections resource."},"delete":{"tags":["Calendar Connections"],"operationId":"delete-calendar-connection","summary":"Revoke and disconnect a Google OAuth connection","description":"Revokes the Google grant (best-effort) and destroys the connection. Mirrored calendars have their connection_id nullified.","security":[{"userApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"id","in":"path","required":true,"schema":{"type":"number"}}],"responses":{"200":{"description":"Success"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"Connection not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/calendar/connections/{id}/select_calendars":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"id","in":"path","required":true,"schema":{"type":"number"},"description":"ID of the connection"}],"post":{"tags":["Calendar Connections"],"operationId":"select-google-calendars-on-connection","summary":"Mirror the chosen Google calendars on a connection","security":[{"userApiKey":[]}],"description":"Mirror the operator-chosen Google calendars — creates (or un-archives) a local Calendar of kind google for each selection and seeds its sync state. Entries without a google_calendar_id are skipped. Returns the created/updated calendars.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["calendars"],"properties":{"calendars":{"type":"array","items":{"type":"object","required":["google_calendar_id"],"properties":{"google_calendar_id":{"type":"string"},"name":{"type":"string"},"timezone":{"type":"string","description":"IANA timezone identifier (e.g. \"America/Sao_Paulo\", \"UTC\"). Rails timezone names are also accepted on input; an unrecognized value is ignored in favor of the next fallback.","example":"America/Sao_Paulo"},"description":{"type":"string"}}}}}},"example":{"calendars":[{"google_calendar_id":"sample google calendar id","name":"Sample Name","timezone":"America/Sao_Paulo","description":"A short description."}]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number"},"name":{"type":"string"},"google_calendar_id":{"type":"string"}}}}}},"example":{"payload":[{"id":1,"name":"Sample Name","google_calendar_id":"sample google calendar id"}]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"Connection not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/calendar/connections/{id}/google_calendars":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"id","in":"path","required":true,"schema":{"type":"number"},"description":"ID of the connection"}],"get":{"tags":["Calendar Connections"],"operationId":"list-google-calendars-on-connection","summary":"List the Google calendars available on a connection","security":[{"userApiKey":[]}],"description":"The raw Google calendar list for the connection (the mirror picker). Each entry is flagged with whether it is already mirrored as a local calendar.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","properties":{"google_calendar_id":{"type":"string"},"name":{"type":"string"},"summary":{"type":"string"},"color":{"type":"string"},"description":{"type":"string"},"timezone":{"type":"string","description":"IANA timezone identifier (e.g. \"America/Sao_Paulo\", \"UTC\"). Rails timezone names are also accepted on input; an unrecognized value is ignored in favor of the next fallback.","example":"America/Sao_Paulo"},"primary":{"type":"boolean"},"access_role":{"type":"string"},"writable":{"type":"boolean","description":"Whether this account can WRITE to the calendar (`access_role` owner/writer). A read-only calendar can still be mirrored for free/busy, but confirmed bookings pushed to it are refused by Google — surface it before the operator picks one.\n"},"supports_meet":{"type":"boolean","description":"Whether Google allows creating a Meet conference on this calendar. false means an event type using `google_meet` as its location would never get a link, and the customer would be told \"Google Meet\" with nothing to join.\n"},"allowed_conference_solution_types":{"type":["array","null"],"description":"The conference solutions Google reports for this calendar. null when Google did not report the field — unknown, not empty; do not read null as \"no Meet\".\n","items":{"type":"string"}},"mirrored":{"type":"boolean","description":"Whether this Google calendar is already mirrored as a local calendar."}}}}}},"example":{"payload":[{"google_calendar_id":"sample google calendar id","name":"Sample Name","summary":"sample summary","color":"#1F93FF","description":"A short description.","timezone":"America/Sao_Paulo","primary":true,"access_role":"sample access role","writable":true,"supports_meet":true,"allowed_conference_solution_types":["sample allowed conference solution type"],"mirrored":true}]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"Connection not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/calendar/availability":{"get":{"tags":["Calendar Availability"],"operationId":"get-calendar-availability","summary":"Get availability rules and date overrides for a booking owner","description":"GET returns weekly rules + date overrides; PUT replaces the entire rule set. owner_type can be Calendar, Calendar::EventType or User. One entry per WINDOW, so a weekday with a lunch break comes back twice (08:00-12:00 and 14:00-18:00). Rows are stored as given; windows that touch or overlap are coalesced only when slots are computed.","security":[{"userApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"owner_type","in":"query","required":true,"schema":{"type":"string","enum":["Calendar","Calendar::EventType","User"]}},{"name":"owner_id","in":"query","required":true,"schema":{"type":"number"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"rules":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number"},"day_of_week":{"type":"number"},"start_minute":{"type":"number"},"end_minute":{"type":"number"}}}},"overrides":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number"},"date":{"type":"string","format":"date"},"blocked":{"type":"boolean"},"start_minute":{"type":"number"},"end_minute":{"type":"number"}}}}}}}},"example":{"payload":{"rules":[{"id":1,"day_of_week":12.5,"start_minute":12.5,"end_minute":12.5}],"overrides":[{"id":1,"date":"2026-01-15","blocked":true,"start_minute":12.5,"end_minute":12.5}]}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"Owner not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"patch":{"tags":["Calendar Availability"],"operationId":"update-calendar-availability","summary":"Replace availability rules and date overrides for a booking owner","security":[{"userApiKey":[]}],"description":"Replace the owner's weekly windows in one shot (Calendly-style editor saves the whole grid). An empty rules array clears all windows (closed). Overrides are replaced only when the overrides key is present. Omit owner_type/owner_id to edit the account-level default availability.\n\nA weekday may carry SEVERAL rules — that is how a lunch break is expressed (Monday 08:00-12:00 plus Monday 14:00-18:00). Send every window you want; anything you omit is deleted.\n\nWindows that touch or overlap are COALESCED into one before slots are computed: 08:00-12:00 next to 12:00-18:00 becomes a single 08:00-18:00 window. Leave a real gap between two shifts. This matters beyond cosmetics for an event type with occupancy=availability_window, where one booking reserves the whole window it falls in — two touching windows make the entire day one shift.","parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"owner_type","in":"query","required":false,"schema":{"type":"string","enum":["Calendar","Calendar::EventType","User"]},"description":"Omit to target the account-level default availability."},{"name":"owner_id","in":"query","required":false,"schema":{"type":"number"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"rules":{"type":"array","description":"The full desired weekly window set — one entry PER WINDOW, so a weekday appears as many times as it has windows. [] clears all windows.","items":{"type":"object","required":["day_of_week","start_minute","end_minute"],"properties":{"day_of_week":{"type":"number","minimum":0,"maximum":6,"description":"0 = Sunday through 6 = Saturday."},"start_minute":{"type":"number","minimum":0,"maximum":1439,"description":"Minutes from local midnight (540 = 09:00), in the owner's calendar time zone."},"end_minute":{"type":"number","minimum":1,"maximum":1440,"description":"Minutes from local midnight; 1440 = end of day. Must be greater than start_minute — a single row cannot cross midnight. An overnight shift is written as two rows (Monday 1320-1440 plus Tuesday 0-120 for 22:00-02:00); because they touch at midnight they are read back as ONE continuous shift, so an appointment may start at 23:30 and a booking under occupancy=availability_window reserves the whole night."}}}},"overrides":{"type":"array","description":"Date-specific exceptions (holiday / one-off open window). [] clears them.","items":{"type":"object","required":["date"],"properties":{"date":{"type":"string","format":"date"},"blocked":{"type":"boolean"},"start_minute":{"type":"number"},"end_minute":{"type":"number"}}}}}},"example":{"rules":[{"day_of_week":12.5,"start_minute":12.5,"end_minute":12.5}],"overrides":[{"date":"2026-01-15","blocked":true,"start_minute":12.5,"end_minute":12.5}]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"owner_type":{"type":"string","enum":["Calendar","Calendar::EventType","User"],"description":"The kind of record that owns the availability window."},"owner_id":{"type":"number"},"rules":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number"},"day_of_week":{"type":"number"},"start_minute":{"type":"number"},"end_minute":{"type":"number"}}}},"overrides":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number"},"date":{"type":"string","format":"date"},"blocked":{"type":"boolean"},"start_minute":{"type":"number"},"end_minute":{"type":"number"}}}}}}}},"example":{"payload":{"owner_type":"Calendar","owner_id":1,"rules":[{"id":1,"day_of_week":12.5,"start_minute":12.5,"end_minute":12.5}],"overrides":[{"id":1,"date":"2026-01-15","blocked":true,"start_minute":12.5,"end_minute":12.5}]}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"Owner not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"put":{"tags":["Calendar Availability"],"operationId":"auto_put_api_v1_accounts_account_id_calendar_availability","summary":"Replace a booking owner's availability","description":"Replaces the owner's weekly availability windows in one shot (Calendly-style grid save). The owner is resolved account-scoped from owner_type/owner_id (Calendar / Calendar::EventType / User; absent = the account default). An empty rules array clears all windows. When `overrides` is present, date overrides are replaced too. Returns the owner's resolved rules + overrides.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"owner_type":{"type":"string","enum":["Calendar","Calendar::EventType","User"],"description":"The kind of record that owns the availability window."},"owner_id":{"type":"integer"},"rules":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"day_of_week":{"type":"string"},"start_minute":{"type":"string"},"end_minute":{"type":"string"}}}},"overrides":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"date":{"type":"string","format":"date"},"blocked":{"type":"string"},"start_minute":{"type":"string"},"end_minute":{"type":"string"}}}}}}}},"example":{"payload":{"owner_type":"Calendar","owner_id":1,"rules":[{"id":1,"day_of_week":"sample day of week","start_minute":"sample start minute","end_minute":"sample end minute"}],"overrides":[{"id":1,"date":"2026-01-15","blocked":"sample blocked","start_minute":"sample start minute","end_minute":"sample end minute"}]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"owner_type":{"type":["string","null"],"enum":["Calendar","Calendar::EventType","User",null],"description":"Owner class; absent = the account-level default availability.","example":"Calendar"},"owner_id":{"type":["integer","null"],"example":4},"rules":{"type":"array","description":"Weekly windows; incomplete entries are dropped; [] clears all windows.","items":{"type":"object","properties":{"day_of_week":{"type":"integer","description":"0=Sunday.. 6=Saturday","example":1},"start_minute":{"type":"integer","description":"minutes from midnight","example":540},"end_minute":{"type":"integer","description":"minutes from midnight","example":1020}}},"example":[{"day_of_week":1,"start_minute":540,"end_minute":1020}]},"overrides":{"type":"array","description":"Date-specific overrides (holidays / one-off windows). [] clears them.","items":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"2026-12-25"},"blocked":{"type":"boolean","example":true},"start_minute":{"type":["integer","null"],"example":null},"end_minute":{"type":["integer","null"],"example":null}}}}}},"example":{"owner_type":"Calendar","owner_id":4,"rules":[{"day_of_week":1,"start_minute":540,"end_minute":1020}],"overrides":[{"date":"2026-12-25","blocked":true,"start_minute":null,"end_minute":null}]}}}}}},"/api/v1/accounts/{account_id}/calendar/availability/sync_holidays":{"parameters":[{"$ref":"#/components/parameters/account_id"}],"post":{"tags":["Calendar Availability"],"operationId":"sync-calendar-availability-holidays","summary":"Load a country's public holidays as blocked date overrides","security":[{"userApiKey":[]}],"description":"Load a country's public holidays for a year and add them as blocked availability overrides (offline holidays library, idempotent). Returns the updated config plus how many holidays were added. Omit owner_type/owner_id to target the account-level default availability.","parameters":[{"name":"owner_type","in":"query","required":false,"schema":{"type":"string","enum":["Calendar","Calendar::EventType","User"]},"description":"Omit to target the account-level default availability."},{"name":"owner_id","in":"query","required":false,"schema":{"type":"number"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["country_code"],"properties":{"country_code":{"type":"string","description":"Country code of the holiday calendar to load (e.g. br, us)."},"year":{"type":"number","description":"Year to load. Defaults server-side to the current year."}}},"example":{"country_code":"BR","year":12.5}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"owner_type":{"type":"string","enum":["Calendar","Calendar::EventType","User"],"description":"The kind of record that owns the availability window."},"owner_id":{"type":"number"},"rules":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number"},"day_of_week":{"type":"number"},"start_minute":{"type":"number"},"end_minute":{"type":"number"}}}},"overrides":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number"},"date":{"type":"string","format":"date"},"blocked":{"type":"boolean"},"start_minute":{"type":"number"},"end_minute":{"type":"number"}}}}}},"meta":{"type":"object","properties":{"holidays_added":{"type":"number","description":"How many holidays were added (vs already present)."},"holidays_total":{"type":"number"},"country_code":{"type":"string"},"year":{"type":"number"}}}}},"example":{"payload":{"owner_type":"Calendar","owner_id":1,"rules":[{"id":1,"day_of_week":12.5,"start_minute":12.5,"end_minute":12.5}],"overrides":[{"id":1,"date":"2026-01-15","blocked":true,"start_minute":12.5,"end_minute":12.5}]},"meta":{"holidays_added":12.5,"holidays_total":149.9,"country_code":"BR","year":12.5}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"422":{"description":"Country not selected, unsupported, or the holidays library is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"Owner not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/calendar/availability/seed_from_inbox":{"parameters":[{"$ref":"#/components/parameters/account_id"}],"post":{"tags":["Calendar Availability"],"operationId":"seed-calendar-availability-from-inbox","summary":"Copy an inbox's working hours into a booking owner's availability","security":[{"userApiKey":[]}],"description":"Copy the inbox's WorkingHour configuration into the owner's weekly availability rules (idempotent replace). Omit owner_type/owner_id to seed the account-level default availability.\n\nDESTRUCTIVE for split days. An inbox stores ONE open/close pair per weekday, while availability stores one row per window, so this REPLACES the whole grid and a weekday that had two windows (a lunch break, a morning and an afternoon shift, an overnight shift) comes back as a single window. Read the current grid first if you need to preserve it, or write the windows directly with PUT /api/v1/accounts/{account_id}/calendar/availability.","parameters":[{"name":"owner_type","in":"query","required":false,"schema":{"type":"string","enum":["Calendar","Calendar::EventType","User"]},"description":"Omit to target the account-level default availability."},{"name":"owner_id","in":"query","required":false,"schema":{"type":"number"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["inbox_id"],"properties":{"inbox_id":{"type":"number","description":"The account inbox whose working hours are copied."}}},"example":{"inbox_id":1}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"owner_type":{"type":"string","enum":["Calendar","Calendar::EventType","User"],"description":"The kind of record that owns the availability window."},"owner_id":{"type":"number"},"rules":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number"},"day_of_week":{"type":"number"},"start_minute":{"type":"number"},"end_minute":{"type":"number"}}}},"overrides":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number"},"date":{"type":"string","format":"date"},"blocked":{"type":"boolean"},"start_minute":{"type":"number"},"end_minute":{"type":"number"}}}}}}}},"example":{"payload":{"owner_type":"Calendar","owner_id":1,"rules":[{"id":1,"day_of_week":12.5,"start_minute":12.5,"end_minute":12.5}],"overrides":[{"id":1,"date":"2026-01-15","blocked":true,"start_minute":12.5,"end_minute":12.5}]}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"Owner or inbox not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/calendar/settings":{"get":{"tags":["Calendar Settings"],"operationId":"get-calendar-settings","summary":"Get account calendar settings","description":"Returns the fully resolved calendar/booking config (seed defaults -\u003e account default -\u003e scoped override) for the account, or for a specific scope. With `raw=true` and a `scope`, returns ONLY that scope's stored override (null per section when it inherits) instead of the resolved config — which is how a client tells a real override apart from an inherited default.","security":[{"userApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"scope","in":"query","required":false,"schema":{"type":"string"},"description":"Optional scope key (e.g. \"event_type:123\"). Defaults to the account-level config."},{"name":"raw","in":"query","required":false,"schema":{"type":"boolean"},"description":"When true (and `scope` is given), return only that scope's stored override instead of the resolved config. Sections with no override come back null."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"scope":{"type":["string","null"],"description":"The scope this config was read for, or null for the account default.","example":"event_type:123"},"payload":{"$ref":"#/components/schemas/calendar_settings_config"}}},"example":{"scope":"event_type:123","payload":{"booking":{"slot_minutes":30,"buffer_before":0,"buffer_after":0,"min_notice_minutes":60,"max_advance_days":60,"min_cancel_notice_minutes":60,"first_day_of_week":0,"timezone":"UTC","host_assignment":"round_robin","branding":{"logo_url":"https://cdn.example.com/logo.png","brand_color":"#1f93ff","display_name":"Acme Studio"},"crm":{"create_if_missing":false,"default_pipeline_id":12,"default_stage_id":34},"task":{"title_template":"Appointment: {{title}}","assignee":"host","reminder_offset_minutes":0,"reminder_channel":"in_app"},"payment":{"enabled":false,"default_hold_minutes":15,"default_connection_id":7,"default_billing_types":["pix"],"gate_fallback":"recurring","cancellation_refund":"manual"}},"side_effects":{"conversation":true,"task":false,"crm_deal":false,"meet":true,"ics_email":true,"whatsapp_web_event":false},"reminders":{"lead_times_minutes":[60],"channels":["email"],"auto_no_show_minutes":15,"reminder_template":"Hi {{contact_name}}, your appointment is on {{datetime}}.","confirmation_template":"Your appointment {{title}} is confirmed for {{datetime}}.","reschedule_template":"Your appointment moved to {{datetime}}.","cancel_template":"Your appointment on {{datetime}} was cancelled.","labels":{"manage_button":{"pt_BR":"Gerenciar agendamento"},"reminder_interactive_title":"sample reminder interactive title","confirmation_interactive_title":"sample confirmation interactive title","reschedule_interactive_title":"sample reschedule interactive title","cancel_interactive_title":"sample cancel interactive title"},"delivery":{"email":true,"whatsapp":false,"whatsapp_inbox_id":42,"templates":{"reminder":{"pt_BR":{"name":"agenda_reminder_pt_br","language":"pt_BR","params":["contact_name","title","datetime"],"url_button":true},"name":"agenda_confirmation_pt_br","language":"pt_BR","namespace":null,"params":["contact_name"],"body_params":["contact_name"],"url_button":true},"confirmation":{"pt_BR":{"name":"agenda_reminder_pt_br","language":"pt_BR","params":["contact_name","title","datetime"],"url_button":true},"name":"agenda_confirmation_pt_br","language":"pt_BR","namespace":null,"params":["contact_name"],"body_params":["contact_name"],"url_button":true},"reschedule":{"pt_BR":{"name":"agenda_reminder_pt_br","language":"pt_BR","params":["contact_name","title","datetime"],"url_button":true},"name":"agenda_confirmation_pt_br","language":"pt_BR","namespace":null,"params":["contact_name"],"body_params":["contact_name"],"url_button":true},"cancel":{"pt_BR":{"name":"agenda_reminder_pt_br","language":"pt_BR","params":["contact_name","title","datetime"],"url_button":true},"name":"agenda_confirmation_pt_br","language":"pt_BR","namespace":null,"params":["contact_name"],"body_params":["contact_name"],"url_button":true}},"interactive_buttons":{"cancel":false}}},"sync":{"conflict_strategy":"last_write_wins","default_direction":"two_way","poll_interval_minutes":2}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"patch":{"tags":["Calendar Settings"],"operationId":"update-calendar-settings","summary":"Update account calendar settings","description":"Deep-merges the provided sections into the existing config, so a PATCH of one key never clobbers the rest. With a `scope` (e.g. \"event_type:123\") the merge writes that scope's override instead of the account default; anything not sent keeps inheriting. Returns the re-resolved config.","security":[{"userApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"scope","in":"query","required":false,"schema":{"type":"string"},"description":"Optional scope key (e.g. \"event_type:123\"). Defaults to the account-level config."}],"requestBody":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/calendar_settings_config"},{"type":"object","properties":{"clear":{"type":"array","description":"Dot-paths the operator RESTORED to the shipped default, e.g. `reminders.reminder_template.pt_BR`. A deep merge can only ADD or REPLACE a key, never remove one, so without these a restored body would live on in jsonb forever — \"Restore default\" on the account row would be purely cosmetic. Only paths rooted at one of the config's own sections are honoured, and the row itself is never destroyed here (the scoped DELETE is what drops a whole override).","items":{"type":"string"},"example":["reminders.reminder_template.pt_BR"]}}}]},"example":{"booking":{"slot_minutes":30,"buffer_before":0,"buffer_after":0,"min_notice_minutes":60,"max_advance_days":60,"min_cancel_notice_minutes":60,"first_day_of_week":0,"timezone":"UTC","host_assignment":"round_robin","branding":{"logo_url":"https://cdn.example.com/logo.png","brand_color":"#1f93ff","display_name":"Acme Studio"},"crm":{"create_if_missing":false,"default_pipeline_id":12,"default_stage_id":34},"task":{"title_template":"Appointment: {{title}}","assignee":"host","reminder_offset_minutes":0,"reminder_channel":"in_app"},"payment":{"enabled":false,"default_hold_minutes":15,"default_connection_id":7,"default_billing_types":["pix"],"gate_fallback":"recurring","cancellation_refund":"manual"}},"side_effects":{"conversation":true,"task":false,"crm_deal":false,"meet":true,"ics_email":true,"whatsapp_web_event":false},"reminders":{"lead_times_minutes":[60],"channels":["email"],"auto_no_show_minutes":15,"reminder_template":"Hi {{contact_name}}, your appointment is on {{datetime}}.","confirmation_template":"Your appointment {{title}} is confirmed for {{datetime}}.","reschedule_template":"Your appointment moved to {{datetime}}.","cancel_template":"Your appointment on {{datetime}} was cancelled.","labels":{"manage_button":{"pt_BR":"Gerenciar agendamento"},"reminder_interactive_title":"sample reminder interactive title","confirmation_interactive_title":"sample confirmation interactive title","reschedule_interactive_title":"sample reschedule interactive title","cancel_interactive_title":"sample cancel interactive title"},"delivery":{"email":true,"whatsapp":false,"whatsapp_inbox_id":42,"templates":{"reminder":{"pt_BR":{"name":"agenda_reminder_pt_br","language":"pt_BR","params":["contact_name","title","datetime"],"url_button":true},"name":"agenda_confirmation_pt_br","language":"pt_BR","namespace":null,"params":["contact_name"],"body_params":["contact_name"],"url_button":true},"confirmation":{"pt_BR":{"name":"agenda_reminder_pt_br","language":"pt_BR","params":["contact_name","title","datetime"],"url_button":true},"name":"agenda_confirmation_pt_br","language":"pt_BR","namespace":null,"params":["contact_name"],"body_params":["contact_name"],"url_button":true},"reschedule":{"pt_BR":{"name":"agenda_reminder_pt_br","language":"pt_BR","params":["contact_name","title","datetime"],"url_button":true},"name":"agenda_confirmation_pt_br","language":"pt_BR","namespace":null,"params":["contact_name"],"body_params":["contact_name"],"url_button":true},"cancel":{"pt_BR":{"name":"agenda_reminder_pt_br","language":"pt_BR","params":["contact_name","title","datetime"],"url_button":true},"name":"agenda_confirmation_pt_br","language":"pt_BR","namespace":null,"params":["contact_name"],"body_params":["contact_name"],"url_button":true}},"interactive_buttons":{"cancel":false}}},"sync":{"conflict_strategy":"last_write_wins","default_direction":"two_way","poll_interval_minutes":2},"clear":["reminders.reminder_template.pt_BR"]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"scope":{"type":["string","null"],"description":"The scope that was written, or null for the account default.","example":"event_type:123"},"payload":{"$ref":"#/components/schemas/calendar_settings_config"}}},"example":{"scope":"event_type:123","payload":{"booking":{"slot_minutes":30,"buffer_before":0,"buffer_after":0,"min_notice_minutes":60,"max_advance_days":60,"min_cancel_notice_minutes":60,"first_day_of_week":0,"timezone":"UTC","host_assignment":"round_robin","branding":{"logo_url":"https://cdn.example.com/logo.png","brand_color":"#1f93ff","display_name":"Acme Studio"},"crm":{"create_if_missing":false,"default_pipeline_id":12,"default_stage_id":34},"task":{"title_template":"Appointment: {{title}}","assignee":"host","reminder_offset_minutes":0,"reminder_channel":"in_app"},"payment":{"enabled":false,"default_hold_minutes":15,"default_connection_id":7,"default_billing_types":["pix"],"gate_fallback":"recurring","cancellation_refund":"manual"}},"side_effects":{"conversation":true,"task":false,"crm_deal":false,"meet":true,"ics_email":true,"whatsapp_web_event":false},"reminders":{"lead_times_minutes":[60],"channels":["email"],"auto_no_show_minutes":15,"reminder_template":"Hi {{contact_name}}, your appointment is on {{datetime}}.","confirmation_template":"Your appointment {{title}} is confirmed for {{datetime}}.","reschedule_template":"Your appointment moved to {{datetime}}.","cancel_template":"Your appointment on {{datetime}} was cancelled.","labels":{"manage_button":{"pt_BR":"Gerenciar agendamento"},"reminder_interactive_title":"sample reminder interactive title","confirmation_interactive_title":"sample confirmation interactive title","reschedule_interactive_title":"sample reschedule interactive title","cancel_interactive_title":"sample cancel interactive title"},"delivery":{"email":true,"whatsapp":false,"whatsapp_inbox_id":42,"templates":{"reminder":{"pt_BR":{"name":"agenda_reminder_pt_br","language":"pt_BR","params":["contact_name","title","datetime"],"url_button":true},"name":"agenda_confirmation_pt_br","language":"pt_BR","namespace":null,"params":["contact_name"],"body_params":["contact_name"],"url_button":true},"confirmation":{"pt_BR":{"name":"agenda_reminder_pt_br","language":"pt_BR","params":["contact_name","title","datetime"],"url_button":true},"name":"agenda_confirmation_pt_br","language":"pt_BR","namespace":null,"params":["contact_name"],"body_params":["contact_name"],"url_button":true},"reschedule":{"pt_BR":{"name":"agenda_reminder_pt_br","language":"pt_BR","params":["contact_name","title","datetime"],"url_button":true},"name":"agenda_confirmation_pt_br","language":"pt_BR","namespace":null,"params":["contact_name"],"body_params":["contact_name"],"url_button":true},"cancel":{"pt_BR":{"name":"agenda_reminder_pt_br","language":"pt_BR","params":["contact_name","title","datetime"],"url_button":true},"name":"agenda_confirmation_pt_br","language":"pt_BR","namespace":null,"params":["contact_name"],"body_params":["contact_name"],"url_button":true}},"interactive_buttons":{"cancel":false}}},"sync":{"conflict_strategy":"last_write_wins","default_direction":"two_way","poll_interval_minutes":2}}}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"delete":{"tags":["Calendar Settings"],"operationId":"delete-calendar-settings","summary":"Revert a scoped calendar settings override","description":"Reverts a scope (e.g. \"event_type:123\") to inheriting the account default. Without `clear`, the whole scoped override is dropped. With `clear`, only the listed dot-paths are removed — so one section can go back to inheriting while the scope keeps its other overrides; the override row is deleted once nothing is left. The account default (no scope) is never destroyable here. Returns the re-resolved config.","security":[{"userApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"scope","in":"query","required":true,"schema":{"type":"string"},"description":"The scope whose override is reverted (e.g. \"event_type:123\"). Required."},{"name":"clear","in":"query","required":false,"style":"form","explode":true,"schema":{"type":"array","items":{"type":"string","example":"booking.branding"}},"description":"Dot-paths to remove from the scoped override (e.g. \"booking.branding\", \"side_effects\", \"reminders.delivery\"). Omit to drop the entire scoped override."}],"responses":{"200":{"description":"Success — the config re-resolved after the revert.","content":{"application/json":{"schema":{"type":"object","properties":{"scope":{"type":["string","null"],"description":"The scope that was reverted.","example":"event_type:123"},"payload":{"$ref":"#/components/schemas/calendar_settings_config"}}},"example":{"scope":"event_type:123","payload":{"booking":{"slot_minutes":30,"buffer_before":0,"buffer_after":0,"min_notice_minutes":60,"max_advance_days":60,"min_cancel_notice_minutes":60,"first_day_of_week":0,"timezone":"UTC","host_assignment":"round_robin","branding":{"logo_url":"https://cdn.example.com/logo.png","brand_color":"#1f93ff","display_name":"Acme Studio"},"crm":{"create_if_missing":false,"default_pipeline_id":12,"default_stage_id":34},"task":{"title_template":"Appointment: {{title}}","assignee":"host","reminder_offset_minutes":0,"reminder_channel":"in_app"},"payment":{"enabled":false,"default_hold_minutes":15,"default_connection_id":7,"default_billing_types":["pix"],"gate_fallback":"recurring","cancellation_refund":"manual"}},"side_effects":{"conversation":true,"task":false,"crm_deal":false,"meet":true,"ics_email":true,"whatsapp_web_event":false},"reminders":{"lead_times_minutes":[60],"channels":["email"],"auto_no_show_minutes":15,"reminder_template":"Hi {{contact_name}}, your appointment is on {{datetime}}.","confirmation_template":"Your appointment {{title}} is confirmed for {{datetime}}.","reschedule_template":"Your appointment moved to {{datetime}}.","cancel_template":"Your appointment on {{datetime}} was cancelled.","labels":{"manage_button":{"pt_BR":"Gerenciar agendamento"},"reminder_interactive_title":"sample reminder interactive title","confirmation_interactive_title":"sample confirmation interactive title","reschedule_interactive_title":"sample reschedule interactive title","cancel_interactive_title":"sample cancel interactive title"},"delivery":{"email":true,"whatsapp":false,"whatsapp_inbox_id":42,"templates":{"reminder":{"pt_BR":{"name":"agenda_reminder_pt_br","language":"pt_BR","params":["contact_name","title","datetime"],"url_button":true},"name":"agenda_confirmation_pt_br","language":"pt_BR","namespace":null,"params":["contact_name"],"body_params":["contact_name"],"url_button":true},"confirmation":{"pt_BR":{"name":"agenda_reminder_pt_br","language":"pt_BR","params":["contact_name","title","datetime"],"url_button":true},"name":"agenda_confirmation_pt_br","language":"pt_BR","namespace":null,"params":["contact_name"],"body_params":["contact_name"],"url_button":true},"reschedule":{"pt_BR":{"name":"agenda_reminder_pt_br","language":"pt_BR","params":["contact_name","title","datetime"],"url_button":true},"name":"agenda_confirmation_pt_br","language":"pt_BR","namespace":null,"params":["contact_name"],"body_params":["contact_name"],"url_button":true},"cancel":{"pt_BR":{"name":"agenda_reminder_pt_br","language":"pt_BR","params":["contact_name","title","datetime"],"url_button":true},"name":"agenda_confirmation_pt_br","language":"pt_BR","namespace":null,"params":["contact_name"],"body_params":["contact_name"],"url_button":true}},"interactive_buttons":{"cancel":false}}},"sync":{"conflict_strategy":"last_write_wins","default_direction":"two_way","poll_interval_minutes":2}}}}}},"422":{"description":"Unprocessable Entity (a scope is required)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}},"put":{"tags":["Calendar Settings"],"operationId":"auto_put_api_v1_accounts_account_id_calendar_settings","summary":"Update settings","description":"Updates the setting identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"scope":{"type":"string"},"side_effects":{"type":"object","additionalProperties":true,"description":"JSONB automation side-effect toggles (conversation, task, crm_deal, meet, ics_email, whatsapp_web_event)."},"reminders":{"type":"object","additionalProperties":true,"description":"Reminder defaults (lead times in minutes, channels, auto-no-show)."},"sync":{"type":"object","additionalProperties":true,"description":"Google-sync defaults (conflict strategy, default direction, poll interval)."},"booking":{"type":"object","additionalProperties":true,"description":"Booking-engine defaults (slot length, buffers, notice windows, timezone, payment)."}}}}},"example":{"payload":{"scope":"sample scope","side_effects":{},"reminders":{},"sync":{},"booking":{}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"reminders":{"type":"object","additionalProperties":true,"description":"Reminder defaults (lead times in minutes, channels, auto-no-show)."},"scope":{"type":"string"},"clear":{"type":"array","items":{"type":"string"}}},"additionalProperties":true},"example":{"reminders":{},"scope":"sample scope","clear":["sample clear"]}}}}}},"/api/v1/accounts/{account_id}/calendar/reports":{"get":{"tags":["Calendar Reports"],"operationId":"calendar-reports","summary":"Calendar analytics (bookings per type/agent, no-show rate, lead time, occupancy, cancellation, sync health)","security":[{"userApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"calendar_id","in":"query","required":false,"schema":{"type":"number"},"description":"Scope the report to a specific calendar. Omit for account-wide."},{"name":"since","in":"query","required":false,"schema":{"type":"string","format":"date"}},{"name":"until","in":"query","required":false,"schema":{"type":"string","format":"date"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","additionalProperties":true,"description":"Aggregate calendar/booking report metrics."}}},"example":{"payload":{}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}},"description":"Calendar analytics (bookings per type/agent, no-show rate, lead time, occupancy, cancellation, sync health). Returns Reports data for the current context."}},"/api/v1/accounts/{account_id}/calendar/bookings":{"get":{"tags":["Calendar Bookings"],"operationId":"list-calendar-bookings","summary":"List calendar bookings","description":"List the account's bookings (public-page, agent, Maestro, automation or WhatsApp Flow originated) so the operator can inspect each one and copy its opaque manage link. `period` sorts upcoming/past bookings by their event's start time; `all` also includes bookings without an event (expired holds, failed payments) ordered by creation. Filter by status, event type and creation window; paginated.\n","security":[{"userApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["confirmed","rescheduled","cancelled","no_show","pending_payment","payment_failed","expired"]},"description":"Filter by booking status."},{"name":"event_type_id","in":"query","required":false,"schema":{"type":"number"},"description":"Filter by the bookable event type."},{"name":"period","in":"query","required":false,"schema":{"type":"string","enum":["upcoming","past","all"],"default":"upcoming"},"description":"Upcoming/past (by event start, event required) or all (includes event-less bookings)."},{"name":"since","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"Only bookings created at or after this time."},{"name":"until","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"Only bookings created at or before this time."},{"name":"page","in":"query","required":false,"schema":{"type":"number"}},{"name":"per_page","in":"query","required":false,"schema":{"type":"number"},"description":"Page size (default 25, capped at 100)."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number"},"status":{"type":"string","enum":["confirmed","rescheduled","cancelled","no_show","pending_payment","payment_failed","expired"]},"selected_location":{"type":["string","null"],"description":"What the booker picked when the event type offered a location menu; null when no choice was offered (the event type's own location_type applies).\n","enum":["in_person","phone","google_meet","custom",null]},"created_source":{"type":"string","enum":["public_page","agent","maestro","automation","whatsapp_flow"]},"visitor_timezone":{"type":["string","null"],"description":"IANA timezone the visitor booked in."},"created_at":{"type":"string","format":"date-time"},"manage_token":{"type":"string","description":"Opaque token — the public manage URL is /book/manage/{manage_token}."},"event":{"type":"object","description":"The scheduled event slice. Absent when the booking has no event (expired hold / failed payment).","properties":{"id":{"type":"number"},"title":{"type":"string"},"starts_at":{"type":"string","format":"date-time"},"ends_at":{"type":"string","format":"date-time"},"status":{"type":"string"},"conversation_id":{"type":["number","null"],"description":"GLOBAL Conversation id. Correct for linking and lookups, but NOT what the dashboard conversation route takes — use conversation_display_id to navigate."},"conversation_display_id":{"type":["number","null"],"description":"The conversation's per-account display_id — the value the `inbox_conversation` route expects. Navigating with the global `conversation_id` opens whichever conversation happens to hold that number inside the account, i.e. the wrong chat."},"crm_item_id":{"type":["number","null"]},"location":{"type":["string","null"],"description":"The CONCRETE location of the appointment, copied onto the event when the booking was confirmed: the address, phone number or custom text configured for the chosen location_type. Null for a google_meet booking (its location is the Meet link below) and for bookings made before that copy existed — fall back to event_type.location_details in that case."},"meet_url":{"type":["string","null"],"description":"The Google Meet link, stamped on the event by the Google push. Null when the appointment is not a video call, or when the calendar has no Google connection (the booking still confirms; only the link is missing)."}}},"event_type":{"type":"object","description":"The bookable event type this booking was made against.","properties":{"id":{"type":"number"},"name":{"type":"string"},"location_type":{"type":"string","description":"Where this event type happens. Read it as the booking's location WHENEVER selected_location is null: a type with a single option offered no menu, so nothing is persisted per booking and the type's own location_type describes the location completely.","enum":["in_person","phone","google_meet","custom"]},"location_details":{"type":"object","additionalProperties":{"type":"string"},"description":"One address per location_type key, e.g. { \"in_person\": \"Rua das Flores, 123\" }. The booking copies the matching entry into event.location at confirmation time, so this is the fallback for older bookings that carry no event.location."}}},"contact":{"type":"object","description":"The booker's contact slice. Absent when no contact was resolved.","properties":{"id":{"type":"number"},"name":{"type":["string","null"]},"email":{"type":["string","null"]},"phone_number":{"type":["string","null"]}}},"host_user_id":{"type":["number","null"],"description":"The agent who runs this appointment. Emitted on EVERY row (null when the type has no host) so a listing can filter or group by host without the key disappearing on part of the page — unlike the `host` block below, which is genuinely absent then. With round-robin assignment each row can belong to a different agent.\n"},"host":{"type":"object","description":"The assigned host user. Absent when unassigned.","properties":{"id":{"type":"number"},"name":{"type":"string"},"available_name":{"type":"string","description":"The operator's display name — what every other surface renders (task assignees, calendar attendees). Added alongside `name`, which keeps its original meaning.\n"}}},"payment":{"type":"object","description":"The gating charge slice. Absent for free bookings.","properties":{"status":{"type":"string","description":"The normalized charge status.","enum":["pending","awaiting_payment","confirmed","paid","overdue","refunded","partially_refunded","canceled","failed"]},"amount":{"type":"string","description":"Decimal amount in major units (e.g. \"100.0\")."},"currency":{"type":"string"}}}}}},"meta":{"type":"object","properties":{"count":{"type":"number"},"current_page":{"type":"number"},"total_pages":{"type":"number"},"per_page":{"type":"number"},"has_more":{"type":"boolean"}}}}},"example":{"payload":[{"id":1,"status":"confirmed","selected_location":"in_person","created_source":"public_page","visitor_timezone":"sample visitor timezone","created_at":"2026-01-15T10:30:00.000Z","manage_token":"sample-token","event":{"id":1,"title":"Sample title","starts_at":"2026-01-15T10:30:00.000Z","ends_at":"2026-01-15T10:30:00.000Z","status":"active","conversation_id":1,"conversation_display_id":1,"crm_item_id":1,"location":"sample location","meet_url":"https://example.com/resource"},"event_type":{"id":1,"name":"Sample Name","location_type":"in_person","location_details":{}},"contact":{"id":1,"name":"Sample Name","email":"agent@example.com","phone_number":"+5511999998888"},"host_user_id":1,"host":{"id":1,"name":"Sample Name","available_name":"sample available name"},"payment":{"status":"pending","amount":"sample amount","currency":"BRL"}}],"meta":{"count":5,"current_page":12.5,"total_pages":12.5,"per_page":12.5,"has_more":true}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}}}}},"/api/v1/accounts/{account_id}/calendar/event_types/{event_type_id}/bookings":{"post":{"tags":["Calendar Bookings"],"operationId":"create-calendar-booking","summary":"Book a slot of an event type on a customer's behalf","description":"Books one of an event type's free slots from the dashboard or from an AI agent, instead of sending the customer a link. It runs the SAME Calendar::BookingService the public booking page runs, so the host resolution, the advisory-lock double-book guard, the Google push, the notifications and the paid scheduling flow are identical. Read the free slots with the event type's `slots` endpoint first and pass one of the returned instants verbatim as `starts_at`. A paid event type creates the booking as `pending_payment` and starts the charge.","security":[{"userApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"event_type_id","in":"path","required":true,"description":"Id of the bookable event type. Must be a kept (non-archived) type in this account.","schema":{"type":"number"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"The same visitor-shaped inputs the public page posts. May be sent flat (documented here) or wrapped in a `booking` key — both are accepted.","required":["starts_at"],"properties":{"starts_at":{"type":"string","format":"date-time","description":"Slot start, exactly as returned by the event type's `slots` endpoint.","example":"2026-08-05T13:00:00Z"},"ends_at":{"type":"string","format":"date-time","description":"Slot end. Omitted, the event type's duration is added to `starts_at`.","example":"2026-08-05T13:30:00Z"},"contact_id":{"type":"number","description":"The customer this booking belongs to, resolved account-scoped. A foreign id is DROPPED rather than raising, and the service then matches or creates a contact from the e-mail / phone below.","example":4211},"source":{"type":"string","enum":["agent","maestro"],"description":"Who acted. `maestro` when the AI agent booked it, `agent` when a human did. Anything else falls back to `agent` — never `public_page`, which would make an assisted booking look like a self-service one in the reports.","example":"maestro"},"name":{"type":"string","description":"Booker name. Omitted, the resolved contact's own name is used.","example":"Ana Souza"},"email":{"type":"string","format":"email","description":"Booker e-mail, used to dedupe the contact and to send the confirmation.","example":"ana@example.com"},"phone_number":{"type":"string","description":"Best-effort normalised to E.164. A number that still fails validation, or that already belongs to another contact, is dropped without failing the booking.","example":"+5511999998888"},"timezone":{"type":"string","description":"The customer's IANA timezone, stored on the booking and used in their messages.","example":"America/Sao_Paulo"},"selected_location":{"type":"string","enum":["in_person","phone","google_meet","custom"],"description":"The chosen location, only meaningful when the event type exposes a `location_options` menu. Validated against that menu server-side; anything else falls back to the type's own `location_type`.","example":"google_meet"},"answers":{"type":"object","description":"Answers to the event type's intake questions, keyed by each question's `id`.","additionalProperties":true,"example":{"q0":"Renewal of the annual plan"}},"guest_emails":{"type":"array","description":"Extra invitees, accepted only when the event type has `guest_emails_enabled` and capped at its `max_guests`.","items":{"type":"string","format":"email"},"example":["colleague@example.com"]}}},"example":{"starts_at":"2026-08-05T13:00:00Z","ends_at":"2026-08-05T13:30:00Z","contact_id":4211,"source":"maestro","name":"Ana Souza","email":"ana@example.com","phone_number":"+5511999998888","timezone":"America/Sao_Paulo","selected_location":"google_meet","answers":{"q0":"Renewal of the annual plan"},"guest_emails":["colleague@example.com"]}}}},"responses":{"201":{"description":"Booking created (confirmed, or pending_payment for a paid event type)","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"$ref":"#/components/schemas/calendar_booking"}}},"example":{"payload":{"server_now":"2026-01-15T10:30:00.000Z","manage_token":"sample-token","status":"confirmed","locale":"en","visitor_timezone":"sample visitor timezone","selected_location":"in_person","answers":{},"created_at":"2026-01-15T10:30:00.000Z","payment":{"payable":true,"status":"pending","amount":"sample amount","currency":"BRL","billing_type":"pix","pix_payload":"sample pix payload","pix_qr_base64":"sample pix qr base64","boleto_url":"https://example.com/resource","hosted_url":"https://example.com/resource","hold_expires_at":"2026-01-15T10:30:00.000Z","is_deposit":true,"full_amount":"sample full amount","balance_amount":"sample balance amount","subscription":true,"checkout_url":"https://example.com/resource"},"event":{"title":"Sample title","starts_at":"2026-01-15T10:30:00.000Z","ends_at":"2026-01-15T10:30:00.000Z","timezone":"America/Sao_Paulo","location":"sample location","meet_url":"https://example.com/resource","status":"confirmed"},"event_type":{"public_token":"sample-token","name":"Sample Name","duration_minutes":60,"location_type":"in_person","confirmation_message":"sample confirmation message","redirect_url":"https://example.com/resource"}}}}}},"409":{"description":"The slot was taken between reading the availability and confirming. Nothing was written — read the slots again and pick another one.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"The guard's own message.","example":"slot no longer available"}},"additionalProperties":false},"example":{"error":"slot no longer available"}}}},"422":{"description":"Policy violation (a required phone number missing, outside the booking window), a subscription-gated type booked by a non-member, an unresolvable payer, or a paid type whose gateway is not configured.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable reason, or the guard's own message.","example":"payer_required"},"details":{"type":"object","description":"Present only for `needs_subscription` — how the customer can subscribe.","additionalProperties":true}},"additionalProperties":false},"example":{"error":"payer_required","details":{}}}}},"404":{"description":"Event type not found in this account, or archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"503":{"description":"The payment gateway was unreachable or errored while starting the charge. Transient — the booking was rolled back and the slot freed, so the call can simply be retried.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["payment_gateway_error"],"description":"Machine-readable reason."}},"additionalProperties":false},"example":{"error":"payment_gateway_error"}}}}}}},"/api/v1/accounts/{account_id}/calendar/google/authorization":{"parameters":[{"$ref":"#/components/parameters/account_id"}],"post":{"tags":["Calendar Connections"],"operationId":"create-calendar-google-authorization","summary":"Begin the Google Calendar OAuth flow (admin-only)","security":[{"userApiKey":[]}],"description":"Build the Google OAuth consent URL for the Calendar scope (calendar + calendar.events + identity) using the installation-level GOOGLE_OAUTH_CLIENT_ID/SECRET. The flow requests offline access with forced consent so a long-lived refresh_token is always captured. The browser is redirected to the returned URL; Google calls back at the top-level /google_calendar/callback route.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"url":{"type":"string","description":"The Google OAuth consent URL to redirect the operator to."}}},"example":{"success":true,"url":"https://example.com/resource"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"422":{"description":"Google OAuth is not configured on this installation","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"string"}}},"example":{"success":true,"error":"sample error"}}}}}}},"/google_calendar/callback":{"get":{"tags":["Calendar Connections"],"operationId":"show-calendar-google-callback","summary":"Google Calendar OAuth callback (browser redirect target)","description":"Where Google sends the operator's browser after they consent to the Calendar scopes. Not a JSON API — it is the fixed `redirect_uri` registered with Google, which is why it lives at the top level instead of under an account-scoped prefix. The owning account is recovered from the signed `state` parameter minted when the flow started, the authorization code is exchanged for tokens off-channel, and the connected Google account's e-mail is read from the id_token (falling back to the userinfo endpoint when Google omits it). The resulting {access_token, refresh_token, expires_on} blob is stored encrypted on the calendar connection and is never rendered or logged.\n\nEvery outcome is a 302 back into the dashboard: success lands on the Agenda connections page so the operator can immediately pick which calendars to mirror; a failure lands on the same page carrying `calendar_error` (a stable machine code) and `calendar_error_message` (already translated into the account's language), because the redirect leaves the Rails request cycle and the reason has to travel with it.","parameters":[{"name":"code","in":"query","required":false,"description":"The one-time authorization code issued by Google, exchanged for tokens.","schema":{"type":"string"}},{"name":"state","in":"query","required":true,"description":"The signed global id of the account that started the flow. Missing or unresolvable state fails the callback with `missing_state` / `invalid_state` — there is no session fallback.","schema":{"type":"string"}},{"name":"error","in":"query","required":false,"description":"Set by Google when the operator declined consent or the request was rejected.","schema":{"type":"string"}}],"responses":{"302":{"description":"Always a redirect. On success, to the Agenda connections page. On failure, to the same page with `calendar_error` and `calendar_error_message` query parameters, or to the dashboard root when the account could not be resolved at all.","headers":{"Location":{"description":"The dashboard URL the operator is sent to.","schema":{"type":"string"}}}}}}},"/public/api/v1/calendar/event_types/{public_token}":{"get":{"tags":["Calendar Public Booking"],"operationId":"public-get-calendar-event-type","summary":"Get a public bookable event type by its opaque token","description":"Returns a PII-free subset of the event type for the white-label booking page, keyed by the opaque public_token: the type, the host brand (name / logo / accent / locale — per-event-type branding overrides applied), the intake questions, the booking-window hints, the first day of week for the slot picker, and — when the type requires payment — the public price hints. No account_id, no host emails. Only kept + public types are reachable.","security":[],"parameters":[{"name":"public_token","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The public event-type landing payload.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","description":"The public booking landing data for this event type.","properties":{"public_token":{"type":"string","description":"The opaque public identifier for the event type (the only public id).","example":"tok_ab12cd34ef"},"name":{"type":"string","description":"The event type's display name.","example":"Discovery call"},"slug":{"type":"string","description":"The event type's URL slug.","example":"discovery-call"},"duration_minutes":{"type":"integer","description":"The appointment length in minutes.","example":30},"location_type":{"type":"string","description":"Where the appointment happens.","enum":["in_person","phone","google_meet","custom"],"example":"google_meet"},"location_options":{"type":"array","description":"The location menu the visitor may choose from, posted back as `selected_location`. Empty when the operator offers no choice — `location_type` then applies (a one-item menu is collapsed to empty server-side, so this is never a choice of one).\n","items":{"type":"string","enum":["in_person","phone","google_meet","custom"]},"example":["google_meet","in_person"]},"color":{"type":["string","null"],"description":"The event type's accent color (hex), or null.","example":"#1f93ff"},"confirmation_message":{"type":["string","null"],"description":"The message shown after booking, or null.","example":"Thanks for booking! See you soon."},"redirect_url":{"type":["string","null"],"description":"An optional post-booking redirect URL, or null.","example":"https://example.com/thank-you"},"account_name":{"type":"string","description":"The host display name (branding.display_name override, else the account name).","example":"Acme Studio"},"locale":{"type":"string","description":"The account locale used to localize the public page.","example":"pt_BR"},"logo_url":{"type":"string","description":"The host logo (branding override, else the account avatar, else the global logo).","example":"https://cdn.example.com/logo.png"},"brand_color":{"type":["string","null"],"description":"The public page accent (branding override, else the event type color), or null.","example":"#1f93ff"},"questions":{"type":"array","description":"The intake questions the visitor answers (PII-free schema, no answers). Legacy JSONB rows are projected through the event type's canonical type allowlist and boolean required cast without rewriting the stored definition.","items":{"type":"object","properties":{"id":{"type":"string","description":"A stable question id.","example":"q0"},"label":{"type":"string","description":"The question text shown to the visitor.","example":"What would you like to discuss?"},"type":{"type":"string","enum":["text","textarea","select","radio","checkbox","number","email","phone","date"],"description":"The canonical input type; legacy case is normalized and unsupported values become text.","example":"text"},"required":{"type":"boolean","description":"Whether an answer is required after the canonical boolean cast.","example":true},"placeholder":{"type":["string","null"],"description":"Hint text shown inside the field, or null when the operator set none.","example":"Tell us what you would like to cover"},"options":{"type":"array","description":"The choices a select / radio / checkbox question renders. EMPTY for every other type. Without them the public form has nothing to build the control from.","items":{"type":"string"},"example":["Support","Sales"]}},"additionalProperties":false}},"intake_phone_required":{"type":"boolean","description":"Whether the form must collect a phone / WhatsApp number. The endpoint enforces it too — a booking without a usable number is refused, so this is not merely a client-side hint.","example":true},"guest_emails_enabled":{"type":"boolean","description":"Whether the booker may invite extra guests by e-mail.","example":false},"max_guests":{"type":"integer","description":"Upper bound on extra guests, applied server-side when guests are enabled.","example":5},"occupancy":{"type":"string","enum":["slot","availability_window"],"description":"What one booking takes off the host's calendar. `slot` blocks only the chosen time; `availability_window` reserves the WHOLE shift that time falls in, so every other time in that shift stops being offered. The page shows a notice for `availability_window` — the visitor has to know before choosing, or the rest of the morning simply vanishes after they book. Only the enum is published; the shift bounds are deliberately NOT exposed, since they would reveal the host's schedule structure to anyone holding the booking link.","example":"availability_window"},"min_notice_minutes":{"type":"integer","description":"Minimum minutes before start a slot can be booked. RESOLVED: the event type's own value when set, otherwise the account default — never the raw nullable column, so the page never has to invent a fallback of its own.","example":60},"max_advance_days":{"type":"integer","description":"How many days into the future slots are offered. Resolved the same way as `min_notice_minutes`.","example":60},"min_cancel_notice_minutes":{"type":"integer","description":"Minimum minutes before start a booking can still be cancelled or rescheduled. Resolved the same way as `min_notice_minutes`.","example":60},"first_day_of_week":{"type":"integer","description":"First day of the week for the public slot picker (0 = Sunday … 6 = Saturday), resolved per event type (override) then the account default.","example":0},"payment":{"type":"object","description":"Public price hints — present ONLY when the event type requires payment.","properties":{"mode":{"type":"string","description":"The paid-scheduling mode.","enum":["none","one_off","subscription_gate","recurring"],"example":"one_off"},"hold_mode":{"type":"string","description":"When payment is collected relative to confirmation.","enum":["reserve_and_hold","pay_first"],"example":"reserve_and_hold"},"amount":{"type":["number","null"],"description":"The resolved charge amount, or null.","example":99.9},"deposit_amount":{"type":["number","null"],"description":"The up-front deposit (one_off), or null for the full amount.","example":30.0},"currency":{"type":"string","description":"ISO currency code.","example":"BRL"},"required_fields":{"type":"array","description":"Billing inputs required by the resolved active gateway and default payment method. Contains field names only, never contact data.","items":{"type":"string","enum":["document","email","address"]},"example":["document"]},"billing_types":{"type":"array","description":"The accepted payment methods.","items":{"type":"string","enum":["pix","boleto","credit_card","hosted_link"],"example":"pix"}}}}}}}},"example":{"payload":{"public_token":"tok_ab12cd34ef","name":"Discovery call","slug":"discovery-call","duration_minutes":30,"location_type":"google_meet","location_options":["google_meet","in_person"],"color":"#1f93ff","confirmation_message":"Thanks for booking! See you soon.","redirect_url":"https://example.com/thank-you","account_name":"Acme Studio","locale":"pt_BR","logo_url":"https://cdn.example.com/logo.png","brand_color":"#1f93ff","questions":[{"id":"q0","label":"What would you like to discuss?","type":"text","required":true,"placeholder":"Tell us what you would like to cover","options":["Support","Sales"]}],"intake_phone_required":true,"guest_emails_enabled":false,"max_guests":5,"occupancy":"availability_window","min_notice_minutes":60,"max_advance_days":60,"min_cancel_notice_minutes":60,"first_day_of_week":0,"payment":{"mode":"one_off","hold_mode":"reserve_and_hold","amount":99.9,"deposit_amount":30.0,"currency":"BRL","required_fields":["document"],"billing_types":["pix"]}}}}}},"404":{"description":"Event type not found or not publicly bookable"}}}},"/public/api/v1/calendar/event_types/{public_token}/slots":{"get":{"tags":["Calendar Public Booking"],"operationId":"public-get-calendar-slots","summary":"Get available booking slots (public)","description":"Returns free time slots for the event type in the visitor's timezone. No host PII returned. The booking page sends `date` + `timezone` (one day at a time); `from`/`to` are the explicit-window form. The window is BOUNDED: with none of them the next 7 days are scanned, a range wider than 31 days is clamped (never rejected), and at most 200 starts come back — `meta` says what was scanned and where to resume.","security":[],"parameters":[{"name":"public_token","in":"path","required":true,"schema":{"type":"string"}},{"name":"date","in":"query","required":false,"description":"A single day (YYYY-MM-DD) expanded to that day's bounds in the visitor timezone. This is what the public booking page actually sends. Ignored when `from`/`to` are given.","schema":{"type":"string","format":"date"},"example":"2026-08-05"},{"name":"from","in":"query","required":false,"description":"Window start. Wins over `date`. Omitted, the scan starts now.","schema":{"type":"string","format":"date-time"},"example":"2026-08-05T00:00:00Z"},{"name":"to","in":"query","required":false,"description":"Window end. Omitted, 7 days after `from`. Clamped to at most 31 days after it.","schema":{"type":"string","format":"date-time"},"example":"2026-08-06T00:00:00Z"},{"name":"timezone","in":"query","required":false,"description":"The visitor's IANA timezone, from the browser. Omitted, the event type's own zone applies.","schema":{"type":"string"},"example":"America/Sao_Paulo"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","description":"Free start instants, ascending, ISO-8601.","items":{"type":"string","format":"date-time"},"example":["2026-08-05T13:00:00Z","2026-08-05T13:30:00Z"]},"timezone":{"type":["string","null"],"description":"Echo of the requested `timezone` query param; null when the visitor sent none.","example":"America/Sao_Paulo"},"meta":{"type":"object","description":"What the server actually scanned and whether anything was left out. The window is bounded so a wide-open event type cannot answer with thousands of instants (which overflowed the AI agent that consumes this endpoint, and made the public route a cheap amplification vector).","properties":{"truncated":{"type":"boolean","description":"True when more free slots exist in the scanned window than `max_slots` allows."},"window_clamped":{"type":"boolean","description":"True when the requested range was wider than `max_window_days` and was shortened."},"max_slots":{"type":"integer","description":"Hard ceiling on how many starts one response may carry.","example":200},"max_window_days":{"type":"integer","description":"Hard ceiling on how many days one request may scan.","example":31},"next_from":{"type":["string","null"],"format":"date-time","description":"Where to resume to get what this response left out — the first start that did not fit when `truncated`, the end of the scanned window when `window_clamped`, and null when this response is the complete answer for the requested window.","example":"2026-08-12T13:00:00Z"},"window":{"type":"object","description":"The range that was actually scanned, after defaulting and clamping.","properties":{"from":{"type":"string","format":"date-time","description":"Start of the scanned window.","example":"2026-08-05T12:00:00Z"},"to":{"type":"string","format":"date-time","description":"End of the scanned window.","example":"2026-08-12T12:00:00Z"}},"additionalProperties":false}},"additionalProperties":false}}},"example":{"payload":["2026-08-05T13:00:00Z","2026-08-05T13:30:00Z"],"timezone":"America/Sao_Paulo","meta":{"truncated":true,"window_clamped":true,"max_slots":200,"max_window_days":31,"next_from":"2026-08-12T13:00:00Z","window":{"from":"2026-08-05T12:00:00Z","to":"2026-08-12T12:00:00Z"}}}}}},"404":{"description":"Event type not found"}}}},"/public/api/v1/calendar/event_types/{public_token}/bookings":{"post":{"tags":["Calendar Public Booking"],"operationId":"public-create-booking","summary":"Book a slot (public)","description":"Create a booking for the given event type. The visitor is identified by name + email; the contact is deduped server-side. The body may be sent flat (documented below) or wrapped in a `booking` key — the booking page posts the wrapped form and the endpoint accepts either.","security":[],"parameters":[{"name":"public_token","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["starts_at","ends_at","name","email"],"properties":{"starts_at":{"type":"string","format":"date-time"},"ends_at":{"type":"string","format":"date-time"},"name":{"type":"string"},"email":{"type":"string","format":"email","description":"Required. Surrounding whitespace is trimmed and the value is normalized for contact lookup. Blank, whitespace-only, or malformed values are rejected with 422. This validates address syntax only; it does not verify mailbox ownership, DNS/MX, or message delivery."},"timezone":{"type":"string","description":"IANA timezone identifier (e.g. \"America/Sao_Paulo\", \"UTC\"). Rails timezone names are also accepted on input; an unrecognized value is ignored in favor of the next fallback.","example":"America/Sao_Paulo"},"phone_number":{"type":"string","description":"Optional. If supplied, must be a valid direct international number. A leading + or 00 and formatting characters are normalized to E.164; a countryless number, an extension, or an invalid value is rejected with 422 and is never silently dropped or reinterpreted. Empty is allowed only when the event type does not require a phone number. The booking page converts national input to E.164 only after the visitor explicitly chooses a country. A valid number can be used by existing contact and WhatsApp flows; this contract does not promise delivery.\n","example":"+5511999998888"},"selected_location":{"type":"string","enum":["in_person","phone","google_meet","custom"],"description":"The location the visitor picked, only meaningful when the event type exposes a `location_options` menu. Validated against that menu server-side; anything else falls back to the event type's own `location_type`. Choosing google_meet is what requests the conference link.\n","example":"google_meet"},"recovery_token":{"type":"string","minLength":48,"maxLength":48,"pattern":"^[0-9a-f]{48}$","writeOnly":true,"description":"Optional cryptographically random 192-bit capability retained before submission. Exact retries return the same booking and charge; changed inputs conflict. Bound to this event and account. Omit for a server-generated manage token. Never include payer data in this capability."},"payer_document":{"type":"string","writeOnly":true,"description":"CPF/CNPJ required by payment.required_fields, POST body only. Never returned or saved as intake answers."},"payer_address":{"type":"object","writeOnly":true,"description":"Full direct-boleto billing address when required by the active gateway.","additionalProperties":false,"properties":{"zip_code":{"type":"string"},"street_name":{"type":"string"},"street_number":{"type":"string"},"neighborhood":{"type":"string"},"city":{"type":"string"},"federal_unit":{"type":"string"}}},"answers":{"type":"object","description":"Visitor answers to the event type's intake questions, keyed by each question's `id`. Configured `email` and `phone` questions honor their required setting; supplied email values are trimmed and normalized, and supplied phone values must normalize to E.164. Invalid or missing required values are rejected with 422. Other question types keep their existing values and schema.","additionalProperties":true,"example":{"q0":"Renewal of the annual plan"}},"guest_emails":{"type":"array","description":"Extra people the booker invites, accepted ONLY when the event type has `guest_emails_enabled`. Each address is validated, lower-cased, de-duplicated, the booker's own address is dropped, and the list is capped at the type's `max_guests` — none of which is trusted from the client.","items":{"type":"string","format":"email"},"example":["colleague@example.com"]}}},"example":{"starts_at":"2026-01-15T10:30:00.000Z","ends_at":"2026-01-15T10:30:00.000Z","name":"Sample Name","email":"agent@example.com","timezone":"America/Sao_Paulo","phone_number":"+5511999998888","selected_location":"google_meet","recovery_token":"sample-token","payer_document":"sample payer document","payer_address":{"zip_code":"sample zip code","street_name":"sample street name","street_number":"sample street number","neighborhood":"sample neighborhood","city":"São Paulo","federal_unit":"sample federal unit"},"answers":{"q0":"Renewal of the annual plan"},"guest_emails":["colleague@example.com"]}}}},"responses":{"201":{"description":"Booking confirmed","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"$ref":"#/components/schemas/calendar_booking"}}},"example":{"payload":{"server_now":"2026-01-15T10:30:00.000Z","manage_token":"sample-token","status":"confirmed","locale":"en","visitor_timezone":"sample visitor timezone","selected_location":"in_person","answers":{},"created_at":"2026-01-15T10:30:00.000Z","payment":{"payable":true,"status":"pending","amount":"sample amount","currency":"BRL","billing_type":"pix","pix_payload":"sample pix payload","pix_qr_base64":"sample pix qr base64","boleto_url":"https://example.com/resource","hosted_url":"https://example.com/resource","hold_expires_at":"2026-01-15T10:30:00.000Z","is_deposit":true,"full_amount":"sample full amount","balance_amount":"sample balance amount","subscription":true,"checkout_url":"https://example.com/resource"},"event":{"title":"Sample title","starts_at":"2026-01-15T10:30:00.000Z","ends_at":"2026-01-15T10:30:00.000Z","timezone":"America/Sao_Paulo","location":"sample location","meet_url":"https://example.com/resource","status":"confirmed"},"event_type":{"public_token":"sample-token","name":"Sample Name","duration_minutes":60,"location_type":"in_person","confirmation_message":"sample confirmation message","redirect_url":"https://example.com/resource"}}}}}},"409":{"description":"Recovery capability was already used with different booking inputs. Recover with GET; do not create a new attempt.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["recovery_conflict"]}}},"example":{"error":"recovery_conflict"}}}},"422":{"description":"Invalid recovery capability (recovery_token_invalid), slot unavailable, policy violation (including a blank, whitespace-only, or malformed primary email; an invalid supplied phone number; or an invalid/missing required configured email or phone answer), past the cancellation window, reschedule limit reached, a subscription-gated type booked by a non-member, an unresolvable payer, or a paid type whose gateway is not configured.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Localized validation or guard message for a slot or policy refusal. Use the HTTP status, not this display message, as the stable control signal.","example":"Enter a valid email address for this booking."},"fields":{"type":"object","description":"Present for payer_fields_invalid before any booking or hold is created. Values are required or invalid; contains no submitted or stored payer values.","additionalProperties":{"type":"string","enum":["required","invalid"]}},"details":{"type":"object","description":"Present only for `needs_subscription` — how the visitor can subscribe.","additionalProperties":true}},"additionalProperties":false},"example":{"error":"Enter a valid email address for this booking.","fields":{},"details":{}}}}},"404":{"description":"Event type not found"},"503":{"description":"The payment gateway was unreachable or errored while starting the charge for a paid event type. Transient — the booking was rolled back and the slot freed, so the visitor can simply retry.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["payment_gateway_error"],"description":"Machine-readable reason."}},"additionalProperties":false},"example":{"error":"payment_gateway_error"}}}}}}},"/public/api/v1/calendar/bookings/{manage_token}":{"get":{"tags":["Calendar Public Booking"],"operationId":"public-manage-booking","summary":"Show, reschedule or cancel an existing booking by manage_token (public)","description":"The visitor's own booking is resolved ONLY by its opaque manage_token. No other booking data is accessible.","security":[],"parameters":[{"name":"manage_token","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"$ref":"#/components/schemas/calendar_booking"}}},"example":{"payload":{"server_now":"2026-01-15T10:30:00.000Z","manage_token":"sample-token","status":"confirmed","locale":"en","visitor_timezone":"sample visitor timezone","selected_location":"in_person","answers":{},"created_at":"2026-01-15T10:30:00.000Z","payment":{"payable":true,"status":"pending","amount":"sample amount","currency":"BRL","billing_type":"pix","pix_payload":"sample pix payload","pix_qr_base64":"sample pix qr base64","boleto_url":"https://example.com/resource","hosted_url":"https://example.com/resource","hold_expires_at":"2026-01-15T10:30:00.000Z","is_deposit":true,"full_amount":"sample full amount","balance_amount":"sample balance amount","subscription":true,"checkout_url":"https://example.com/resource"},"event":{"title":"Sample title","starts_at":"2026-01-15T10:30:00.000Z","ends_at":"2026-01-15T10:30:00.000Z","timezone":"America/Sao_Paulo","location":"sample location","meet_url":"https://example.com/resource","status":"confirmed"},"event_type":{"public_token":"sample-token","name":"Sample Name","duration_minutes":60,"location_type":"in_person","confirmation_message":"sample confirmation message","redirect_url":"https://example.com/resource"}}}}}},"404":{"description":"Booking not found"}}}},"/public/api/v1/calendar/bookings/{manage_token}/cancel":{"parameters":[{"name":"manage_token","in":"path","required":true,"schema":{"type":"string"},"description":"Opaque manage token of the booking"}],"patch":{"tags":["Calendar Public Booking"],"operationId":"public-cancel-booking","summary":"Cancel an existing booking by manage_token (public)","description":"Cancel the visitor's own booking. The booking is resolved ONLY by its opaque manage_token and must still be manageable (policy — e.g. min cancel notice).","security":[],"responses":{"200":{"description":"Booking cancelled","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"$ref":"#/components/schemas/calendar_booking"}}},"example":{"payload":{"server_now":"2026-01-15T10:30:00.000Z","manage_token":"sample-token","status":"confirmed","locale":"en","visitor_timezone":"sample visitor timezone","selected_location":"in_person","answers":{},"created_at":"2026-01-15T10:30:00.000Z","payment":{"payable":true,"status":"pending","amount":"sample amount","currency":"BRL","billing_type":"pix","pix_payload":"sample pix payload","pix_qr_base64":"sample pix qr base64","boleto_url":"https://example.com/resource","hosted_url":"https://example.com/resource","hold_expires_at":"2026-01-15T10:30:00.000Z","is_deposit":true,"full_amount":"sample full amount","balance_amount":"sample balance amount","subscription":true,"checkout_url":"https://example.com/resource"},"event":{"title":"Sample title","starts_at":"2026-01-15T10:30:00.000Z","ends_at":"2026-01-15T10:30:00.000Z","timezone":"America/Sao_Paulo","location":"sample location","meet_url":"https://example.com/resource","status":"confirmed"},"event_type":{"public_token":"sample-token","name":"Sample Name","duration_minutes":60,"location_type":"in_person","confirmation_message":"sample confirmation message","redirect_url":"https://example.com/resource"}}}}}},"422":{"description":"Booking not manageable or policy violation","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}},"example":{"error":"sample error"}}}},"404":{"description":"Booking not found"}}}},"/public/api/v1/calendar/bookings/{manage_token}/reschedule":{"parameters":[{"name":"manage_token","in":"path","required":true,"schema":{"type":"string"},"description":"Opaque manage token of the booking"}],"patch":{"tags":["Calendar Public Booking"],"operationId":"public-reschedule-booking","summary":"Reschedule an existing booking by manage_token (public)","description":"Move the visitor's own booking to a new slot. The booking is resolved ONLY by its opaque manage_token; the new slot is re-validated against availability and policy (min cancel notice, max reschedules).","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["starts_at","ends_at"],"properties":{"starts_at":{"type":"string","format":"date-time"},"ends_at":{"type":"string","format":"date-time"}}},"example":{"starts_at":"2026-01-15T10:30:00.000Z","ends_at":"2026-01-15T10:30:00.000Z"}}}},"responses":{"200":{"description":"Booking rescheduled","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"$ref":"#/components/schemas/calendar_booking"}}},"example":{"payload":{"server_now":"2026-01-15T10:30:00.000Z","manage_token":"sample-token","status":"confirmed","locale":"en","visitor_timezone":"sample visitor timezone","selected_location":"in_person","answers":{},"created_at":"2026-01-15T10:30:00.000Z","payment":{"payable":true,"status":"pending","amount":"sample amount","currency":"BRL","billing_type":"pix","pix_payload":"sample pix payload","pix_qr_base64":"sample pix qr base64","boleto_url":"https://example.com/resource","hosted_url":"https://example.com/resource","hold_expires_at":"2026-01-15T10:30:00.000Z","is_deposit":true,"full_amount":"sample full amount","balance_amount":"sample balance amount","subscription":true,"checkout_url":"https://example.com/resource"},"event":{"title":"Sample title","starts_at":"2026-01-15T10:30:00.000Z","ends_at":"2026-01-15T10:30:00.000Z","timezone":"America/Sao_Paulo","location":"sample location","meet_url":"https://example.com/resource","status":"confirmed"},"event_type":{"public_token":"sample-token","name":"Sample Name","duration_minutes":60,"location_type":"in_person","confirmation_message":"sample confirmation message","redirect_url":"https://example.com/resource"}}}}}},"422":{"description":"Slot unavailable, booking not manageable, or policy violation","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}},"example":{"error":"sample error"}}}},"404":{"description":"Booking not found"}}}},"/api/v1/accounts/{account_id}/payments/installment_plans":{"get":{"tags":["Payment Installment Plans"],"operationId":"index-payment-installment-plan","summary":"Index installment plan","security":[{"userApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"page","in":"query","schema":{"type":"integer","minimum":1}},{"name":"per_page","in":"query","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"contact_id","in":"query","schema":{"type":"integer"}},{"name":"crm_item_id","in":"query","schema":{"type":"integer"}},{"name":"conversation_id","in":"query","schema":{"type":"integer"}},{"name":"status","in":"query","schema":{"type":"string","enum":["pending","active","partially_paid","completed","overdue","canceled"]}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","required":["payload","meta"],"properties":{"payload":{"type":"array","items":{"$ref":"#/components/schemas/payment_installment_plan"}},"meta":{"type":"object","required":["count","page","per_page"],"properties":{"count":{"type":"integer"},"page":{"type":"integer"},"per_page":{"type":"integer"}}}}},"example":{"payload":[{"id":1,"account_id":1,"payments_connection_id":1,"contact_id":1,"organization_id":1,"conversation_id":1,"crm_item_id":1,"payments_subscription_id":1,"installments_count":5,"paid_count":5,"total_amount":"sample total amount","installment_amount":"sample installment amount","last_installment_amount":"sample last installment amount","paid_amount":"sample paid amount","refunded_amount":"sample refunded amount","installment_interest_rate":"sample installment interest rate","strategy":"native_installment","status":"pending","billing_type":"pix","cycle":"weekly","installment_mode":"absorb","currency":"BRL","gateway_installment_id":"sample gateway installment id","gateway":"sample gateway","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","archived_at":"2026-01-15T10:30:00.000Z","first_due_date":"2026-01-15","projected_schedule":[{"number":1,"due_date":"2026-01-15","amount":149.9}],"payment_book":{"state":"pending","degraded":true,"stale":true,"refresh_failed":true,"stalled":true,"url":"https://example.com/resource"},"allowed_actions":{"payment_book":true,"send_to_conversation":true,"send_installment":true,"update":true,"cancel":true,"destroy":true,"refund":true,"update_notification_preferences":true},"payment_book_degraded":true,"conversation_display_id":1,"contact_name":"sample contact name","next_due_date":"2026-01-15","gateway_payment_book":{"url":"https://example.com/resource"},"open_installments_count":5,"financial_evidence":{},"notification_preferences":{"payment_charge_paid":false,"installment_plan_completed":true}}],"meta":{"count":5,"page":1,"per_page":1}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"422":{"description":"Validation or gateway refusal","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}},"example":{"error":"sample error"}}}}},"description":"Index installment plan. Returns Installment plans data for the current context."},"post":{"tags":["Payment Installment Plans"],"operationId":"create-payment-installment-plan","summary":"Create installment plan","security":[{"userApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/account_id"}],"responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"type":"object","required":["kind","payload"],"properties":{"kind":{"type":"string","enum":["installment_plan"]},"payload":{"$ref":"#/components/schemas/payment_installment_plan"}}},"example":{"kind":"installment_plan","payload":{"id":1,"account_id":1,"payments_connection_id":1,"contact_id":1,"organization_id":1,"conversation_id":1,"crm_item_id":1,"payments_subscription_id":1,"installments_count":5,"paid_count":5,"total_amount":"sample total amount","installment_amount":"sample installment amount","last_installment_amount":"sample last installment amount","paid_amount":"sample paid amount","refunded_amount":"sample refunded amount","installment_interest_rate":"sample installment interest rate","strategy":"native_installment","status":"pending","billing_type":"pix","cycle":"weekly","installment_mode":"absorb","currency":"BRL","gateway_installment_id":"sample gateway installment id","gateway":"sample gateway","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","archived_at":"2026-01-15T10:30:00.000Z","first_due_date":"2026-01-15","projected_schedule":[{"number":1,"due_date":"2026-01-15","amount":149.9}],"payment_book":{"state":"pending","degraded":true,"stale":true,"refresh_failed":true,"stalled":true,"url":"https://example.com/resource"},"allowed_actions":{"payment_book":true,"send_to_conversation":true,"send_installment":true,"update":true,"cancel":true,"destroy":true,"refund":true,"update_notification_preferences":true},"payment_book_degraded":true,"conversation_display_id":1,"contact_name":"sample contact name","next_due_date":"2026-01-15","gateway_payment_book":{"url":"https://example.com/resource"},"open_installments_count":5,"financial_evidence":{},"notification_preferences":{"payment_charge_paid":false,"installment_plan_completed":true}}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"422":{"description":"Validation or gateway refusal","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}},"example":{"error":"sample error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["installment_plan"],"properties":{"installment_plan":{"type":"object","required":["installments_count","total_amount","billing_type"],"properties":{"connection_id":{"type":"integer"},"contact_id":{"type":"integer"},"organization_id":{"type":"integer"},"conversation_id":{"type":"integer"},"crm_item_id":{"type":"integer"},"installments_count":{"type":"integer"},"currency":{"type":"string"},"description":{"type":"string"},"idempotency_key":{"type":"string"},"doc":{"type":"string"},"payer_email":{"type":"string"},"billing_type":{"type":"string","enum":["pix","boleto","credit_card","debit_card","hosted_link","undefined"],"description":"How the payer is charged. `undefined` lets the payer pick on the hosted invoice."},"total_amount":{"type":"number","exclusiveMinimum":0},"first_due_date":{"type":"string","format":"date"},"cycle":{"type":["string","null"],"enum":["weekly","biweekly","monthly","bimonthly","quarterly","semiannually","yearly",null]},"gateway_options":{"$ref":"#/components/schemas/payment_gateway_options"},"installment_mode":{"type":["string","null"],"enum":["absorb","passthrough",null]},"installment_interest_rate":{"type":"number"},"strategy":{"type":"string","enum":["native_installment","native_recurrence_capped","local_schedule"]}}}}},"example":{"installment_plan":{"connection_id":1,"contact_id":1,"organization_id":1,"conversation_id":1,"crm_item_id":1,"installments_count":5,"currency":"BRL","description":"A short description.","idempotency_key":"sample-token","doc":"sample doc","payer_email":"agent@example.com","billing_type":"pix","total_amount":149.9,"first_due_date":"2026-01-15","cycle":"weekly","gateway_options":{},"installment_mode":"absorb","installment_interest_rate":12.5,"strategy":"native_installment"}}}}},"description":"Create installment plan. Submits the request payload to the Installment plans resource and returns the result."}},"/api/v1/accounts/{account_id}/payments/installment_plans/{id}":{"get":{"tags":["Payment Installment Plans"],"operationId":"show-payment-installment-plan","summary":"Show installment plan","security":[{"userApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","required":["kind","payload"],"properties":{"kind":{"type":"string","enum":["installment_plan"]},"payload":{"$ref":"#/components/schemas/payment_installment_plan"}}},"example":{"kind":"installment_plan","payload":{"id":1,"account_id":1,"payments_connection_id":1,"contact_id":1,"organization_id":1,"conversation_id":1,"crm_item_id":1,"payments_subscription_id":1,"installments_count":5,"paid_count":5,"total_amount":"sample total amount","installment_amount":"sample installment amount","last_installment_amount":"sample last installment amount","paid_amount":"sample paid amount","refunded_amount":"sample refunded amount","installment_interest_rate":"sample installment interest rate","strategy":"native_installment","status":"pending","billing_type":"pix","cycle":"weekly","installment_mode":"absorb","currency":"BRL","gateway_installment_id":"sample gateway installment id","gateway":"sample gateway","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","archived_at":"2026-01-15T10:30:00.000Z","first_due_date":"2026-01-15","projected_schedule":[{"number":1,"due_date":"2026-01-15","amount":149.9}],"payment_book":{"state":"pending","degraded":true,"stale":true,"refresh_failed":true,"stalled":true,"url":"https://example.com/resource"},"allowed_actions":{"payment_book":true,"send_to_conversation":true,"send_installment":true,"update":true,"cancel":true,"destroy":true,"refund":true,"update_notification_preferences":true},"payment_book_degraded":true,"conversation_display_id":1,"contact_name":"sample contact name","next_due_date":"2026-01-15","gateway_payment_book":{"url":"https://example.com/resource"},"open_installments_count":5,"financial_evidence":{},"notification_preferences":{"payment_charge_paid":false,"installment_plan_completed":true}}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"422":{"description":"Validation or gateway refusal","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}},"example":{"error":"sample error"}}}}},"description":"Show installment plan. Returns the requested Installment plans resource."},"patch":{"tags":["Payment Installment Plans"],"operationId":"update-payment-installment-plan","summary":"Update installment plan","security":[{"userApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","required":["kind","payload"],"properties":{"kind":{"type":"string","enum":["installment_plan"]},"payload":{"$ref":"#/components/schemas/payment_installment_plan"}}},"example":{"kind":"installment_plan","payload":{"id":1,"account_id":1,"payments_connection_id":1,"contact_id":1,"organization_id":1,"conversation_id":1,"crm_item_id":1,"payments_subscription_id":1,"installments_count":5,"paid_count":5,"total_amount":"sample total amount","installment_amount":"sample installment amount","last_installment_amount":"sample last installment amount","paid_amount":"sample paid amount","refunded_amount":"sample refunded amount","installment_interest_rate":"sample installment interest rate","strategy":"native_installment","status":"pending","billing_type":"pix","cycle":"weekly","installment_mode":"absorb","currency":"BRL","gateway_installment_id":"sample gateway installment id","gateway":"sample gateway","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","archived_at":"2026-01-15T10:30:00.000Z","first_due_date":"2026-01-15","projected_schedule":[{"number":1,"due_date":"2026-01-15","amount":149.9}],"payment_book":{"state":"pending","degraded":true,"stale":true,"refresh_failed":true,"stalled":true,"url":"https://example.com/resource"},"allowed_actions":{"payment_book":true,"send_to_conversation":true,"send_installment":true,"update":true,"cancel":true,"destroy":true,"refund":true,"update_notification_preferences":true},"payment_book_degraded":true,"conversation_display_id":1,"contact_name":"sample contact name","next_due_date":"2026-01-15","gateway_payment_book":{"url":"https://example.com/resource"},"open_installments_count":5,"financial_evidence":{},"notification_preferences":{"payment_charge_paid":false,"installment_plan_completed":true}}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"422":{"description":"Validation or gateway refusal","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"installments":{"type":"array","description":"Present after partial term updates. Successful installments were already updated; inspect every result before retrying.","items":{"type":"object","required":["charge_id","status"],"properties":{"charge_id":{"type":"integer"},"status":{"type":"string","enum":["updated","failed"]},"error_code":{"type":"string","enum":["conditions_update_failed"]}}}}}},"example":{"error":"sample error","installments":[{"charge_id":1,"status":"updated","error_code":"conditions_update_failed"}]}}}},"400":{"description":"Mixed local and financial fields or malformed preference object"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["installment_plan"],"properties":{"installment_plan":{"oneOf":[{"type":"object","additionalProperties":false,"required":["gateway_options"],"properties":{"gateway_options":{"$ref":"#/components/schemas/payment_gateway_options"}}},{"type":"object","additionalProperties":false,"required":["notification_preferences"],"properties":{"notification_preferences":{"type":"object","additionalProperties":false,"properties":{"payment_charge_paid":{"type":"boolean","default":false},"installment_plan_completed":{"type":"boolean","default":true}}}}}]}}},"example":{"installment_plan":{"notification_preferences":{"payment_charge_paid":false,"installment_plan_completed":true}}}}}},"description":"Update gateway conditions OR local notification preferences, never both in one request. Local preferences do not call a gateway and do not require financial release. Delivery channels continue honoring user preferences."},"delete":{"tags":["Payment Installment Plans"],"operationId":"destroy-payment-installment-plan","summary":"Destroy installment plan","security":[{"userApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"204":{"description":"Deleted; canceled financial audit rows are preserved"},"403":{"description":"Forbidden"},"422":{"description":"Payment history or unsupported strategy"}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string"}}},"example":{"reason":"Sample reason."}}}},"description":"Destroy installment plan. Removes the targeted Installment plans resource."},"put":{"tags":["Payment Installment Plans"],"operationId":"auto_put_api_v1_accounts_account_id_payments_installment_plans_id","summary":"Update installment plans","description":"Updates the installment plan identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Updated installment plan envelope.","content":{"application/json":{"schema":{"type":"object","required":["kind","payload"],"properties":{"kind":{"type":"string","enum":["installment_plan"]},"payload":{"$ref":"#/components/schemas/payment_installment_plan"}}},"example":{"kind":"installment_plan","payload":{"id":1,"account_id":1,"payments_connection_id":1,"contact_id":1,"organization_id":1,"conversation_id":1,"crm_item_id":1,"payments_subscription_id":1,"installments_count":5,"paid_count":5,"total_amount":"sample total amount","installment_amount":"sample installment amount","last_installment_amount":"sample last installment amount","paid_amount":"sample paid amount","refunded_amount":"sample refunded amount","installment_interest_rate":"sample installment interest rate","strategy":"native_installment","status":"pending","billing_type":"pix","cycle":"weekly","installment_mode":"absorb","currency":"BRL","gateway_installment_id":"sample gateway installment id","gateway":"sample gateway","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","archived_at":"2026-01-15T10:30:00.000Z","first_due_date":"2026-01-15","projected_schedule":[{"number":1,"due_date":"2026-01-15","amount":149.9}],"payment_book":{"state":"pending","degraded":true,"stale":true,"refresh_failed":true,"stalled":true,"url":"https://example.com/resource"},"allowed_actions":{"payment_book":true,"send_to_conversation":true,"send_installment":true,"update":true,"cancel":true,"destroy":true,"refund":true,"update_notification_preferences":true},"payment_book_degraded":true,"conversation_display_id":1,"contact_name":"sample contact name","next_due_date":"2026-01-15","gateway_payment_book":{"url":"https://example.com/resource"},"open_installments_count":5,"financial_evidence":{},"notification_preferences":{"payment_charge_paid":false,"installment_plan_completed":true}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"installment_plan":{"type":"object","properties":{"gateway_options":{"type":"object","additionalProperties":true,"description":"Free-form object."}}}},"required":["installment_plan"]},"example":{"installment_plan":{"gateway_options":{}}}}}}}},"/api/v1/accounts/{account_id}/payments/installment_plans/{id}/cancel":{"post":{"tags":["Payment Installment Plans"],"operationId":"cancel-payment-installment-plan","summary":"Cancel installment plan","security":[{"userApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","required":["kind","payload"],"properties":{"kind":{"type":"string","enum":["installment_plan"]},"payload":{"$ref":"#/components/schemas/payment_installment_plan"}}},"example":{"kind":"installment_plan","payload":{"id":1,"account_id":1,"payments_connection_id":1,"contact_id":1,"organization_id":1,"conversation_id":1,"crm_item_id":1,"payments_subscription_id":1,"installments_count":5,"paid_count":5,"total_amount":"sample total amount","installment_amount":"sample installment amount","last_installment_amount":"sample last installment amount","paid_amount":"sample paid amount","refunded_amount":"sample refunded amount","installment_interest_rate":"sample installment interest rate","strategy":"native_installment","status":"pending","billing_type":"pix","cycle":"weekly","installment_mode":"absorb","currency":"BRL","gateway_installment_id":"sample gateway installment id","gateway":"sample gateway","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","archived_at":"2026-01-15T10:30:00.000Z","first_due_date":"2026-01-15","projected_schedule":[{"number":1,"due_date":"2026-01-15","amount":149.9}],"payment_book":{"state":"pending","degraded":true,"stale":true,"refresh_failed":true,"stalled":true,"url":"https://example.com/resource"},"allowed_actions":{"payment_book":true,"send_to_conversation":true,"send_installment":true,"update":true,"cancel":true,"destroy":true,"refund":true,"update_notification_preferences":true},"payment_book_degraded":true,"conversation_display_id":1,"contact_name":"sample contact name","next_due_date":"2026-01-15","gateway_payment_book":{"url":"https://example.com/resource"},"open_installments_count":5,"financial_evidence":{},"notification_preferences":{"payment_charge_paid":false,"installment_plan_completed":true}}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"422":{"description":"Validation or gateway refusal","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}},"example":{"error":"sample error"}}}}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string"}}},"example":{"reason":"Sample reason."}}}},"description":"Cancel installment plan. Submits the request payload to the Cancel resource and returns the result."}},"/api/v1/accounts/{account_id}/payments/installment_plans/{id}/refund":{"post":{"tags":["Payment Installment Plans"],"operationId":"refund-payment-installment-plan","summary":"Refund installment plan","security":[{"userApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"id","in":"path","required":true,"schema":{"type":"integer"}},{"name":"X-Idempotency-Key","in":"header","required":false,"description":"Stable refund operation identity. Preserve across retries and reconciliation; use a different key only for a new intention. Same key with changed amount is rejected. Missing key uses a conservative stable amount/remaining identity.","schema":{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9._:-]+$"},"example":"refund-123-attempt-1"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","required":["kind","payload"],"properties":{"kind":{"type":"string","enum":["installment_plan"]},"payload":{"$ref":"#/components/schemas/payment_installment_plan"}}},"example":{"kind":"installment_plan","payload":{"id":1,"account_id":1,"payments_connection_id":1,"contact_id":1,"organization_id":1,"conversation_id":1,"crm_item_id":1,"payments_subscription_id":1,"installments_count":5,"paid_count":5,"total_amount":"sample total amount","installment_amount":"sample installment amount","last_installment_amount":"sample last installment amount","paid_amount":"sample paid amount","refunded_amount":"sample refunded amount","installment_interest_rate":"sample installment interest rate","strategy":"native_installment","status":"pending","billing_type":"pix","cycle":"weekly","installment_mode":"absorb","currency":"BRL","gateway_installment_id":"sample gateway installment id","gateway":"sample gateway","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","archived_at":"2026-01-15T10:30:00.000Z","first_due_date":"2026-01-15","projected_schedule":[{"number":1,"due_date":"2026-01-15","amount":149.9}],"payment_book":{"state":"pending","degraded":true,"stale":true,"refresh_failed":true,"stalled":true,"url":"https://example.com/resource"},"allowed_actions":{"payment_book":true,"send_to_conversation":true,"send_installment":true,"update":true,"cancel":true,"destroy":true,"refund":true,"update_notification_preferences":true},"payment_book_degraded":true,"conversation_display_id":1,"contact_name":"sample contact name","next_due_date":"2026-01-15","gateway_payment_book":{"url":"https://example.com/resource"},"open_installments_count":5,"financial_evidence":{},"notification_preferences":{"payment_charge_paid":false,"installment_plan_completed":true}}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"422":{"description":"Validation or gateway refusal","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"outcome":{"type":"string","enum":["not_started","definitively_rejected","uncertain","completed"],"description":"Only not_started or definitively_rejected proves safe abandonment of this operation key. Missing outcome is uncertain. completed requires refresh, never an automatic new operation."},"error_code":{"type":"string","enum":["refund_operation_not_started","refund_operation_definitively_rejected","refund_operation_uncertain","refund_operation_completed"]}}},"example":{"error":"The refund outcome is uncertain; reconcile before retrying.","error_code":"refund_operation_uncertain","outcome":"uncertain"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["charge_id"],"properties":{"charge_id":{"type":"integer"},"amount":{"type":"number","exclusiveMinimum":0},"reason":{"type":"string"}}},"example":{"charge_id":1,"amount":149.9,"reason":"Sample reason."}}}},"description":"Refund one selected installment. A completed or reconciled operation replay returns the current plan without another gateway POST; unresolved outcomes remain refused pending reconciliation."}},"/api/v1/accounts/{account_id}/payments/installment_plans/{id}/installments":{"get":{"tags":["Payment Installment Plans"],"operationId":"installments-payment-installment-plan","summary":"Installments installment plan","security":[{"userApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"id","in":"path","required":true,"schema":{"type":"integer"}},{"name":"page","in":"query","schema":{"type":"integer","minimum":1}},{"name":"per_page","in":"query","schema":{"type":"integer","minimum":1,"maximum":100}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","required":["payload","meta"],"properties":{"payload":{"type":"array","items":{"$ref":"#/components/schemas/payment_charge"}},"meta":{"type":"object","required":["count","page","per_page"],"properties":{"count":{"type":"integer"},"page":{"type":"integer"},"per_page":{"type":"integer"}}},"projected_schedule":{"type":"array","items":{"type":"object","required":["number","due_date","amount"],"properties":{"number":{"type":"integer"},"due_date":{"type":"string","format":"date"},"amount":{"type":["number","string"]}}}}}},"example":{"payload":[{"id":1,"account_id":1,"payments_connection_id":1,"contact_id":1,"organization_id":1,"organization_name":"sample organization name","conversation_id":1,"crm_item_id":1,"crm_item_title":"sample crm item title","payments_subscription_id":1,"gateway_charge_id":"sample gateway charge id","external_reference":"sample external reference","billing_type":"pix","status":"pending","amount":149.9,"amount_refunded":12.5,"subtotal_amount":149.9,"discount":12.5,"discount_type":"fixed","discount_reason":"sample discount reason","currency":"BRL","original_amount":149.9,"original_currency":"sample original currency","fx_rate":12.5,"installments":1,"installment_mode":"absorb","installment_interest_rate":12.5,"due_date":"2026-01-15","paid_at":"2026-01-15T10:30:00.000Z","refunded_at":"2026-01-15T10:30:00.000Z","description":"A short description.","hosted_url":"https://example.com/resource","pix_payload":"sample pix payload","pix_qr_base64":"sample pix qr base64","boleto_url":"https://example.com/resource","metadata":{"origin":"external_gateway"},"gateway_options":{},"custom_attributes":{},"settled":true,"contact_name":"sample contact name","contact_email":"agent@example.com","payer_email":"agent@example.com","contact_phone_number":"+5511999998888","gateway_customer_id":"sample gateway customer id","gateway":"hotmart","can_mark_as_paid":true,"manually_paid":true,"conversation_display_id":1,"archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","line_items":[{"id":1,"catalog_variant_id":1,"catalog_product_id":1,"name_snapshot":"sample name snapshot","quantity":12.5,"unit_price":149.9,"discount":12.5,"discount_type":"fixed","line_total":149.9,"currency":"BRL","position":1,"metadata":{}}],"installment_plan_id":1,"installment_number":1,"installments_count":5,"installment_plan":{"id":1,"account_id":1,"payments_connection_id":1,"contact_id":1,"organization_id":1,"conversation_id":1,"crm_item_id":1,"payments_subscription_id":1,"installments_count":5,"paid_count":5,"total_amount":"sample total amount","installment_amount":"sample installment amount","last_installment_amount":"sample last installment amount","paid_amount":"sample paid amount","refunded_amount":"sample refunded amount","installment_interest_rate":"sample installment interest rate","strategy":"native_installment","status":"pending","billing_type":"pix","cycle":"weekly","installment_mode":"absorb","currency":"BRL","gateway_installment_id":"sample gateway installment id","gateway":"sample gateway","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","archived_at":"2026-01-15T10:30:00.000Z","first_due_date":"2026-01-15","projected_schedule":[{"number":1,"due_date":"2026-01-15","amount":149.9}],"payment_book":{"state":"pending","degraded":true,"stale":true,"refresh_failed":true,"stalled":true,"url":"https://example.com/resource"},"allowed_actions":{"payment_book":true,"send_to_conversation":true,"send_installment":true,"update":true,"cancel":true,"destroy":true,"refund":true,"update_notification_preferences":true},"payment_book_degraded":true,"conversation_display_id":1,"contact_name":"sample contact name","next_due_date":"2026-01-15","gateway_payment_book":{"url":"https://example.com/resource"},"open_installments_count":5,"financial_evidence":{},"notification_preferences":{"payment_charge_paid":false,"installment_plan_completed":true}},"can_undo_mark_as_paid":true,"can_refund":true}],"meta":{"count":5,"page":1,"per_page":1},"projected_schedule":[{"number":1,"due_date":"2026-01-15","amount":149.9}]}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"422":{"description":"Validation or gateway refusal","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}},"example":{"error":"sample error"}}}}},"description":"Installments installment plan. Returns Installments data for the current context."}},"/api/v1/accounts/{account_id}/payments/installment_plans/{id}/payment_book":{"get":{"tags":["Payment Installment Plans"],"operationId":"payment-book-payment-installment-plan","summary":"Download or request an installment payment book","security":[{"userApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"id","in":"path","required":true,"schema":{"type":"integer"}},{"name":"source","in":"query","required":false,"schema":{"type":"string","enum":["native","gateway"],"default":"native"},"description":"Gateway selects the authenticated operator-only Asaas document. It never replaces the native customer attachment."},{"name":"month","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":12},"description":"Required together with year for gateway subscription booklets."},{"name":"year","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":9999},"description":"Required together with month for gateway subscription booklets."}],"responses":{"200":{"description":"Native branded PDF by default, or secondary operator-only gateway PDF when source=gateway","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}}},"headers":{"Content-Disposition":{"description":"PDF attachment filename.","schema":{"type":"string"},"example":"attachment; filename=\"carne-42.pdf\""}}},"202":{"description":"Current native generation state when no downloadable PDF is available. A POST on a ready but outdated book (payment_book.stale) rebuilds it in place and answers ready; the previous PDF stays downloadable meanwhile.","content":{"application/json":{"schema":{"type":"object","properties":{"state":{"type":"string","enum":["pending","ready","failed","unavailable"]}},"required":["state"]},"example":{"state":"pending"}}}},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"400":{"description":"Invalid or missing gateway subscription period"}},"description":"Returns a branded PDF when the native book is ready. Otherwise returns the current generation state as JSON with HTTP 202. Source gateway downloads the secondary provider document for the authenticated operator; it does not replace the customer attachment."},"post":{"tags":["Payment Installment Plans"],"operationId":"auto_post_api_v1_accounts_account_id_payments_installment_plans_id_payment_book","summary":"Payment book installment plans","description":"Performs the payment book operation on the targeted installment plan resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"202":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"state":{"type":"string"}}},"example":{"state":"active"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"source":{"type":"string"},"month":{"type":"string"},"year":{"type":"string"}}},"example":{"source":"sample source","month":"sample month","year":"sample year"}}}}}},"/api/v1/accounts/{account_id}/payments/installment_plans/{id}/send_to_conversation":{"post":{"tags":["Payment Installment Plans"],"operationId":"send-to-conversation-payment-installment-plan","summary":"Send to conversation installment plan","security":[{"userApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","required":["kind","payload"],"properties":{"kind":{"type":"string","enum":["installment_plan"]},"payload":{"$ref":"#/components/schemas/payment_installment_plan"}}},"example":{"kind":"installment_plan","payload":{"id":1,"account_id":1,"payments_connection_id":1,"contact_id":1,"organization_id":1,"conversation_id":1,"crm_item_id":1,"payments_subscription_id":1,"installments_count":5,"paid_count":5,"total_amount":"sample total amount","installment_amount":"sample installment amount","last_installment_amount":"sample last installment amount","paid_amount":"sample paid amount","refunded_amount":"sample refunded amount","installment_interest_rate":"sample installment interest rate","strategy":"native_installment","status":"pending","billing_type":"pix","cycle":"weekly","installment_mode":"absorb","currency":"BRL","gateway_installment_id":"sample gateway installment id","gateway":"sample gateway","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","archived_at":"2026-01-15T10:30:00.000Z","first_due_date":"2026-01-15","projected_schedule":[{"number":1,"due_date":"2026-01-15","amount":149.9}],"payment_book":{"state":"pending","degraded":true,"stale":true,"refresh_failed":true,"stalled":true,"url":"https://example.com/resource"},"allowed_actions":{"payment_book":true,"send_to_conversation":true,"send_installment":true,"update":true,"cancel":true,"destroy":true,"refund":true,"update_notification_preferences":true},"payment_book_degraded":true,"conversation_display_id":1,"contact_name":"sample contact name","next_due_date":"2026-01-15","gateway_payment_book":{"url":"https://example.com/resource"},"open_installments_count":5,"financial_evidence":{},"notification_preferences":{"payment_charge_paid":false,"installment_plan_completed":true}}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"422":{"description":"Validation or gateway refusal","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}},"example":{"error":"sample error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["conversation_id"],"properties":{"conversation_id":{"type":"integer"}}},"example":{"conversation_id":1}}}},"description":"Send to conversation installment plan. Submits the request payload to the Send to conversation resource and returns the result."}},"/api/v1/accounts/{account_id}/payments/connections/{id}/option_defaults":{"patch":{"tags":["Payment Connections"],"operationId":"update-payment-connection-option-defaults","summary":"Set connection payment condition defaults","security":[{"userApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"gateway_option_defaults":{"$ref":"#/components/schemas/payment_gateway_options"}}},"example":{"gateway_option_defaults":{}}}}},"responses":{"200":{"description":"Updated connection","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"$ref":"#/components/schemas/payment_connection"}}},"example":{"payload":{"id":1,"account_id":1,"name":"Sample Name","gateway":"asaas","environment":"sandbox","status":"pending","is_default":true,"capabilities":{},"has_api_key":true,"has_secret_key":true,"has_webhook_token":true,"last_reconciliation":{"status":"success","started_at":"2026-01-15T10:30:00.000Z","finished_at":"2026-01-15T10:30:00.000Z","processed_count":5,"failed_count":5,"failed_ids":[{"resource":"charge","external_id":"sample external id","local_id":1,"reason":"gateway_error"}]},"settings":{"orphan_adoption_policy":"disabled","import_from":"2026-07-01T00:00:00Z"},"archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","max_installments_by_type":{"credit_card":1,"boleto":1,"pix":1},"installable_billing_types":["credit_card"],"installment_cycles":{"native_installment":["monthly"],"native_recurrence_capped":["weekly"]},"plan_creation_released":{"credit_card":false,"boleto":false,"pix":false},"plan_send_released":{"credit_card":false,"boleto":false,"pix":false},"gateway_option_defaults":{},"money_unit":"major","webhook_signature_scheme":"header_token","client_certificate":{"present":true,"status":"missing","days_remaining":1,"subject":"Sample subject","issuer":"sample issuer","fingerprint":"sample fingerprint","expires_at":"2026-01-15T10:30:00.000Z"},"capabilities_v2":{"money_unit":"major","webhook_signature_scheme":"header_token","methods":{}}}}}}},"403":{"description":"Forbidden"},"422":{"description":"Unsupported or invalid conditions"}},"description":"Set connection payment condition defaults. Applies the submitted changes to the Option defaults resource."}},"/api/v1/accounts/{account_id}/payments/charges/simulate":{"post":{"tags":["Payment Charges"],"operationId":"simulate-payment-charge","summary":"Simulate explicit billing method installment costs","security":[{"userApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/account_id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["charge"],"properties":{"charge":{"type":"object","required":["billing_type","amount"],"properties":{"connection_id":{"type":"integer"},"amount":{"type":"number"},"billing_type":{"type":"string","enum":["pix","boleto","credit_card","hosted_link","undefined","debit_card"],"description":"How the payer is charged. `undefined` lets the payer pick on the hosted invoice."},"installments":{"type":"integer"},"installment_mode":{"type":"string","enum":["absorb","passthrough"]},"installment_interest_rate":{"type":"number"}}}}},"example":{"charge":{"connection_id":1,"amount":149.9,"billing_type":"pix","installments":1,"installment_mode":"absorb","installment_interest_rate":12.5}}}}},"responses":{"200":{"description":"Simulation with explicit unavailability reasons when a net amount is unknown","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"amount":{"type":"number"},"interest_rate":{"type":"number"},"max_installments":{"type":"number"},"currency":{"type":"string"},"billing_type":{"type":["string","null"],"enum":["pix","boleto","credit_card","hosted_link","undefined","debit_card",null],"description":"How the payer is charged. `undefined` lets the payer pick on the hosted invoice."},"mode":{"type":"string","enum":["absorb","passthrough"],"description":"Which side pays the installment interest in this simulation, AFTER the gateway's own limits were applied — a `passthrough` requested of a gateway that cannot bill the payer for it comes back as `absorb`, so the value always reflects what would actually happen. Traces to Payments::InstallmentPricing::MODES."},"net_available":{"type":"boolean"},"net_unavailable_reason":{"type":["string","null"]},"fee_source":{"type":["string","null"]},"plans":{"type":"array","items":{"type":"object","properties":{"per_installment":{"type":["number","null"]},"last_installment":{"type":["number","null"]},"customer_total":{"type":["number","null"]},"merchant_net":{"type":["number","null"]},"fee_amount":{"type":["number","null"]},"effective_rate":{"type":["number","null"]},"installments":{"type":"integer"},"unavailable":{"type":"boolean"},"uniform":{"type":"boolean"},"reason":{"type":"string"},"source":{"type":"string","enum":["rate","fee_table","absorb","gateway"]}}}},"confirmation":{"type":["object","null"],"properties":{"per_installment":{"type":["number","null"]},"customer_total":{"type":["number","null"]},"merchant_net":{"type":["number","null"]},"fee_amount":{"type":["number","null"]},"installments":{"type":"integer"},"source":{"type":"string","enum":["rate","fee_table","absorb","gateway"]}}}}}}},"example":{"payload":{"amount":149.9,"interest_rate":12.5,"max_installments":12.5,"currency":"BRL","billing_type":"pix","mode":"absorb","net_available":true,"net_unavailable_reason":"sample net unavailable reason","fee_source":"sample fee source","plans":[{"per_installment":12.5,"last_installment":12.5,"customer_total":149.9,"merchant_net":12.5,"fee_amount":149.9,"effective_rate":12.5,"installments":1,"unavailable":true,"uniform":true,"reason":"Sample reason.","source":"rate"}],"confirmation":{"per_installment":12.5,"customer_total":149.9,"merchant_net":12.5,"fee_amount":149.9,"installments":1,"source":"rate"}}}}}},"403":{"description":"Forbidden"},"422":{"description":"Validation refused"}},"description":"Simulate explicit billing method installment costs. Submits the request payload to the Simulate resource and returns the result."}},"/api/v1/accounts/{account_id}/payments/connections/{id}/certificate":{"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"patch":{"tags":["Payment Connections"],"summary":"Update a payment connection certificate","description":"Administrator-only, account-scoped certificate management. Only public metadata is returned in the connection projection. Certificate material is accepted only when encryption is configured and the certificate matches its private key. No gateway is contacted.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Connection with public certificate metadata; no cryptographic material is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/payment_connection"},"example":{"id":1,"account_id":1,"name":"Sample Name","gateway":"asaas","environment":"sandbox","status":"pending","is_default":true,"capabilities":{},"has_api_key":true,"has_secret_key":true,"has_webhook_token":true,"last_reconciliation":{"status":"success","started_at":"2026-01-15T10:30:00.000Z","finished_at":"2026-01-15T10:30:00.000Z","processed_count":5,"failed_count":5,"failed_ids":[{"resource":"charge","external_id":"sample external id","local_id":1,"reason":"gateway_error"}]},"settings":{"orphan_adoption_policy":"disabled","import_from":"2026-07-01T00:00:00Z"},"archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","max_installments_by_type":{"credit_card":1,"boleto":1,"pix":1},"installable_billing_types":["credit_card"],"installment_cycles":{"native_installment":["monthly"],"native_recurrence_capped":["weekly"]},"plan_creation_released":{"credit_card":false,"boleto":false,"pix":false},"plan_send_released":{"credit_card":false,"boleto":false,"pix":false},"gateway_option_defaults":{},"money_unit":"major","webhook_signature_scheme":"header_token","client_certificate":{"present":true,"status":"missing","days_remaining":1,"subject":"Sample subject","issuer":"sample issuer","fingerprint":"sample fingerprint","expires_at":"2026-01-15T10:30:00.000Z"},"capabilities_v2":{"money_unit":"major","webhook_signature_scheme":"header_token","methods":{}}}}}},"422":{"description":"Certificate cannot be accepted","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"type":"string","description":"Localized validation message."},"code":{"type":"string","enum":["certificate_invalid"]}}},"example":{"error":"The certificate, key or password is invalid.","code":"certificate_invalid"}}}},"400":{"description":"certificate_settings_not_permitted","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}},"example":{"error":"certificate_settings_not_permitted"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["connection"],"properties":{"connection":{"type":"object","description":"Certificate fields to update. Generic connection settings are rejected.","properties":{"client_certificate":{"type":"string","writeOnly":true,"description":"PEM-encoded X.509 certificate."},"client_certificate_key":{"type":"string","writeOnly":true,"description":"Matching PEM private key."},"client_certificate_password":{"type":["string","null"],"writeOnly":true,"description":"Private-key password when required."}}}}},"example":{"connection":{"client_certificate":"sample client certificate","client_certificate_key":"sample-token","client_certificate_password":"sample client certificate password"}}}}},"operationId":"auto_patch_api_v1_accounts_account_id_payments_connections_id_certificate"},"delete":{"tags":["Payment Connections"],"summary":"Remove a payment connection certificate","description":"Clears all three private material fields and their derived metadata. Returns the updated connection.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Connection with public certificate metadata; no cryptographic material is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/payment_connection"},"example":{"id":1,"account_id":1,"name":"Sample Name","gateway":"asaas","environment":"sandbox","status":"pending","is_default":true,"capabilities":{},"has_api_key":true,"has_secret_key":true,"has_webhook_token":true,"last_reconciliation":{"status":"success","started_at":"2026-01-15T10:30:00.000Z","finished_at":"2026-01-15T10:30:00.000Z","processed_count":5,"failed_count":5,"failed_ids":[{"resource":"charge","external_id":"sample external id","local_id":1,"reason":"gateway_error"}]},"settings":{"orphan_adoption_policy":"disabled","import_from":"2026-07-01T00:00:00Z"},"archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","max_installments_by_type":{"credit_card":1,"boleto":1,"pix":1},"installable_billing_types":["credit_card"],"installment_cycles":{"native_installment":["monthly"],"native_recurrence_capped":["weekly"]},"plan_creation_released":{"credit_card":false,"boleto":false,"pix":false},"plan_send_released":{"credit_card":false,"boleto":false,"pix":false},"gateway_option_defaults":{},"money_unit":"major","webhook_signature_scheme":"header_token","client_certificate":{"present":true,"status":"missing","days_remaining":1,"subject":"Sample subject","issuer":"sample issuer","fingerprint":"sample fingerprint","expires_at":"2026-01-15T10:30:00.000Z"},"capabilities_v2":{"money_unit":"major","webhook_signature_scheme":"header_token","methods":{}}}}}},"422":{"description":"Certificate cannot be accepted","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"type":"string","description":"Localized validation message."},"code":{"type":"string","enum":["certificate_invalid"]}}},"example":{"error":"The certificate, key or password is invalid.","code":"certificate_invalid"}}}}},"operationId":"auto_delete_api_v1_accounts_account_id_payments_connections_id_certificate"}},"/public/api/v1/payments/charges/{token}":{"get":{"tags":["Payment Public Page"],"summary":"Read one publicly shared payment charge","description":"Reads only the charge identified by the bearer token. No provider request is made. The status timestamp is the locally persisted update time, not a fresh provider check. Invalid, missing, expired and revoked links return the same unavailable response. Responses must not be cached.","security":[],"parameters":[{"name":"token","in":"path","required":true,"description":"Read-only bearer token. Treat the URL as sensitive.","schema":{"type":"string","minLength":24,"maxLength":24}}],"responses":{"200":{"description":"Minimal public charge projection","headers":{"Cache-Control":{"schema":{"type":"string"},"example":"no-store"},"Referrer-Policy":{"schema":{"type":"string"},"example":"no-referrer"},"X-Robots-Tag":{"schema":{"type":"string"},"example":"noindex, nofollow"}},"content":{"application/json":{"schema":{"type":"object","required":["amount","currency","due_date","status","billing_type","boleto_line","boleto_url","pix_payload","pix_qr_base64","status_checked_at","brand"],"properties":{"amount":{"type":"string","description":"Amount in major currency units, encoded as a decimal string."},"currency":{"type":"string"},"due_date":{"type":["string","null"],"format":"date"},"status":{"type":"string","enum":["pending","awaiting_payment","confirmed","paid","overdue","refunded","partially_refunded","canceled","failed"]},"billing_type":{"type":"string","enum":["pix","boleto","credit_card","hosted_link","undefined","debit_card"],"description":"How the payer is charged. `undefined` lets the payer pick on the hosted invoice."},"boleto_line":{"type":["string","null"]},"boleto_url":{"type":["string","null"]},"pix_payload":{"type":["string","null"]},"pix_qr_base64":{"type":["string","null"]},"status_checked_at":{"type":"string","format":"date-time"},"brand":{"type":"object","required":["name"],"properties":{"name":{"type":"string"}}}}},"example":{"amount":"100.0","currency":"BRL","due_date":"2026-09-30","status":"paid","billing_type":"boleto","boleto_line":null,"boleto_url":null,"pix_payload":null,"pix_qr_base64":null,"status_checked_at":"2026-09-07T12:00:00Z","brand":{"name":"Example organization"}}}}},"404":{"description":"payment_unavailable","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}},"example":{"error":"payment_unavailable"}}}}},"operationId":"auto_get_public_api_v1_payments_charges_token"}},"/auth/sign_in":{"get":{"tags":["Authentication"],"operationId":"auto_get_auth_sign_in","summary":"Legacy GET sign-in redirect","description":"HTML-era route kept by the devise mount — redirects to the login SPA with error=access-denied. The JSON API uses POST /auth/sign_in.","security":[],"responses":{"302":{"description":"Redirect to the frontend login page."}}},"post":{"tags":["Authentication"],"operationId":"auto_post_auth_sign_in","summary":"Sign in (email + password)","description":"Authenticates a user and returns the profile under `data` plus the devise-token-auth credential headers (`access-token`, `client`, `uid`, `expiry`, `token-type`) that authenticate subsequent requests. Accounts with MFA enabled receive an MFA challenge instead of credentials; SSO logins send `sso_auth_token`. Rate-limited per email/IP.","security":[],"responses":{"200":{"description":"Authenticated — user profile under data; token credential headers set.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","description":"The authenticated user (api/v1/models/user shape)","properties":{"id":{"type":"integer","example":1},"name":{"type":"string","example":"Sample Name"},"display_name":{"type":"string","example":"Sample Name"},"email":{"type":"string","format":"email","example":"agent@example.com"},"role":{"type":"string","enum":["agent","administrator"],"example":"administrator"},"confirmed":{"type":"boolean","example":true},"access_token":{"type":"string","example":"sample-token"},"pubsub_token":{"type":"string","example":"sample-token"},"avatar_url":{"type":"string","example":"https://example.com/avatar.png"},"accounts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","example":1},"name":{"type":"string","example":"My Account"},"role":{"type":"string","example":"administrator","enum":["administrator","agent"],"description":"The user's role within the account."}}}}}}}},"example":{"data":{"id":1,"name":"Sample Name","display_name":"Sample Name","email":"agent@example.com","role":"administrator","confirmed":true,"access_token":"sample-token","pubsub_token":"sample-token","avatar_url":"https://example.com/avatar.png","accounts":[{"id":1,"name":"My Account","role":"administrator"}]}}}}},"401":{"description":"Invalid credentials / unconfirmed user (error_code user_not_confirmed) / MFA required."}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email","password"],"properties":{"email":{"type":"string","format":"email","example":"agent@example.com"},"password":{"type":"string","example":"sample-password"},"sso_auth_token":{"type":"string","description":"One-time SSO token minted by /auth/{provider}/callback (replaces password auth when present)"},"mfa_code":{"type":"string","description":"TOTP/backup code when finishing an MFA challenge"}}},"example":{"email":"agent@example.com","password":"sample-password","sso_auth_token":"sample-token","mfa_code":"sample mfa code"}}}},"x-authentication":{"kind":"credential","scheme":"passwordCredentials","location":"body","name":"email,password","verification_boundary":"DeviseOverrides::SessionsController#create","algorithm":"opaque"}}},"/auth/sign_out":{"delete":{"tags":["Authentication"],"operationId":"auto_delete_auth_sign_out","summary":"Sign out","description":"Revokes the current devise-token-auth credentials (headers access-token/client/uid identify the session).","security":[],"responses":{"204":{"description":"Success (no content)"},"200":{"description":"Session revoked.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true}}},"example":{"success":true}}}}},"x-authentication":{"kind":"credential","scheme":"userApiKey","location":"headers","name":"access-token, client, uid","verification_boundary":"DeviseTokenAuth#set_user_by_token","algorithm":"opaque"}}},"/auth/password":{"patch":{"tags":["Authentication"],"operationId":"auto_patch_auth_password","summary":"Set a new password","description":"Sets a new password. Authenticated by the reset-token credential headers issued by the email link (or a signed-in session).","security":[],"responses":{"200":{"description":"Password updated — user profile under data.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","additionalProperties":true,"properties":{"id":{"type":"integer","example":1},"email":{"type":"string","format":"email","example":"agent@example.com"}}}}},"example":{"success":true,"data":{"id":1,"email":"agent@example.com"}}}}},"422":{"description":"Password mismatch / policy violation."}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["password","password_confirmation"],"properties":{"password":{"type":"string","example":"sample-password"},"password_confirmation":{"type":"string","example":"sample-password"}}},"example":{"password":"sample-password","password_confirmation":"sample-password"}}}},"x-authentication":{"kind":"credential","scheme":"passwordResetToken","location":"body","name":"reset_password_token","verification_boundary":"DeviseOverrides::PasswordsController#update","algorithm":"opaque"}},"put":{"tags":["Authentication"],"operationId":"auto_put_auth_password","summary":"Set a new password","description":"Sets a new password. Authenticated by the reset-token credential headers issued by the email link (or a signed-in session).","security":[],"responses":{"200":{"description":"Password updated — user profile under data.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","additionalProperties":true,"properties":{"id":{"type":"integer","example":1},"email":{"type":"string","format":"email","example":"agent@example.com"}}}}},"example":{"success":true,"data":{"id":1,"email":"agent@example.com"}}}}},"422":{"description":"Password mismatch / policy violation."}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["password","password_confirmation"],"properties":{"password":{"type":"string","example":"sample-password"},"password_confirmation":{"type":"string","example":"sample-password"}}},"example":{"password":"sample-password","password_confirmation":"sample-password"}}}},"x-authentication":{"kind":"credential","scheme":"passwordResetToken","location":"body","name":"reset_password_token","verification_boundary":"DeviseOverrides::PasswordsController#update","algorithm":"opaque"}},"post":{"tags":["Authentication"],"operationId":"auto_post_auth_password","summary":"Request password reset email","description":"Creates a new password from the request payload.","security":[],"responses":{"200":{"description":"Reset instructions dispatched (response is intentionally the same for unknown emails).","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"An email has been sent containing instructions for resetting your password."}}},"example":{"success":true,"message":"An email has been sent containing instructions for resetting your password."}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email"],"properties":{"email":{"type":"string","format":"email","example":"agent@example.com"},"redirect_url":{"type":"string","description":"Frontend URL the reset link returns to"}}},"example":{"email":"agent@example.com","redirect_url":"https://example.com/resource"}}}},"x-authentication":{"kind":"credential","scheme":"passwordResetRequest","location":"body","name":"email","verification_boundary":"DeviseOverrides::PasswordsController#create","algorithm":"opaque"}}},"/auth/confirmation":{"post":{"tags":["Authentication"],"operationId":"auto_post_auth_confirmation","summary":"Resend account confirmation email","description":"Creates a new confirmation from the request payload.","security":[],"responses":{"200":{"description":"Confirmation email dispatched.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"You will receive an email with instructions for how to confirm your email address in a few minutes."}}},"example":{"success":true,"message":"You will receive an email with instructions for how to confirm your email address in a few minutes."}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email"],"properties":{"email":{"type":"string","format":"email","example":"agent@example.com"},"redirect_url":{"type":"string","description":"Frontend URL the confirmation link returns to"}}},"example":{"email":"agent@example.com","redirect_url":"https://example.com/resource"}}}},"x-authentication":{"kind":"credential","scheme":"confirmationRequest","location":"body","name":"email","verification_boundary":"DeviseOverrides::ConfirmationsController#create","algorithm":"opaque"}}},"/auth/validate_token":{"get":{"tags":["Authentication"],"operationId":"auto_get_auth_validate_token","summary":"Validate token credentials","description":"Validates the devise-token-auth credential headers and returns the current user under data.","security":[],"responses":{"200":{"description":"Token valid.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","description":"The authenticated user (api/v1/models/user shape)","additionalProperties":true,"properties":{"id":{"type":"integer","example":1},"email":{"type":"string","format":"email","example":"agent@example.com"}}}}},"example":{"success":true,"data":{"id":1,"email":"agent@example.com"}}}}},"401":{"description":"Invalid or expired credentials."}},"x-authentication":{"kind":"credential","scheme":"userApiKey","location":"headers","name":"access-token, client, uid","verification_boundary":"DeviseTokenAuth#set_user_by_token","algorithm":"opaque"}}},"/auth/failure":{"get":{"tags":["Authentication"],"operationId":"auto_get_auth_failure","summary":"OAuth failure callback","description":"OmniAuth failure landing — redirects back to the login page with the provider error.","security":[],"responses":{"302":{"description":"Redirect to the login page with the failure reason."}}},"post":{"tags":["Authentication"],"operationId":"auto_post_auth_failure","summary":"OAuth failure callback","description":"OmniAuth failure landing — redirects back to the login page with the provider error.","security":[],"responses":{"302":{"description":"Redirect to the login page with the failure reason."}},"requestBody":{"required":false,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Provider or middleware failure code rendered in the redirect."},"strategy":{"type":"string","description":"OmniAuth strategy name; `saml` selects the tenant-aware SAML failure flow."},"RelayState":{"type":"string","description":"Opaque SAML relay state; `mobile` selects the mobile deep-link result."},"omniauth_window_type":{"type":"string","enum":["inAppBrowser","newWindow"],"description":"Devise Token Auth window mode for non-SAML provider failures."},"auth_origin_url":{"type":"string","format":"uri","description":"Reviewed frontend return URL for the non-SAML provider flow."}}}}}}}},"/auth/{provider}/callback":{"get":{"tags":["Authentication"],"operationId":"auto_get_auth_provider_callback","summary":"OAuth provider callback","description":"Completes the OmniAuth flow (for example, an OAuth authorization-code callback by GET or a SAML assertion-consumer callback by POST) and redirects to the dashboard with a one-time sso_auth_token exchanged at POST /auth/sign_in.","security":[],"responses":{"302":{"description":"Redirect to the frontend with sso_auth_token (or signup when the user is unknown)."}},"parameters":[{"name":"provider","in":"path","required":true,"schema":{"type":"string"}}],"x-authentication":{"kind":"conditional","condition":"The selected OmniAuth provider determines the callback credential envelope.","alternatives":[{"kind":"capability","scheme":"oauthProviderCallback","location":"query","name":"code,state","verification_boundary":"OmniAuth OAuth strategy callback middleware","algorithm":"opaque"},{"kind":"capability","scheme":"samlProviderCallback","location":"body","name":"SAMLResponse,RelayState","verification_boundary":"OmniAuth SAML strategy callback middleware","algorithm":"opaque"}]}},"post":{"tags":["Authentication"],"operationId":"auto_post_auth_provider_callback","summary":"OAuth provider callback","description":"Completes the OmniAuth flow (for example, an OAuth authorization-code callback by GET or a SAML assertion-consumer callback by POST) and redirects to the dashboard with a one-time sso_auth_token exchanged at POST /auth/sign_in.","security":[],"responses":{"302":{"description":"Redirect to the frontend with sso_auth_token (or signup when the user is unknown)."}},"parameters":[{"name":"provider","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","required":["SAMLResponse"],"properties":{"SAMLResponse":{"type":"string","minLength":1,"description":"Base64-encoded SAML response posted by the identity provider."},"RelayState":{"type":"string","description":"Opaque state returned unchanged by the identity provider; `mobile` selects the mobile deep-link result."}}}}}},"x-authentication":{"kind":"conditional","condition":"The selected OmniAuth provider determines the callback credential envelope.","alternatives":[{"kind":"capability","scheme":"oauthProviderCallback","location":"query","name":"code,state","verification_boundary":"OmniAuth OAuth strategy callback middleware","algorithm":"opaque"},{"kind":"capability","scheme":"samlProviderCallback","location":"body","name":"SAMLResponse,RelayState","verification_boundary":"OmniAuth SAML strategy callback middleware","algorithm":"opaque"}]}}},"/resend_confirmation":{"post":{"tags":["API"],"operationId":"auto_post_resend_confirmation","summary":"Create resend confirmations","description":"Creates a new resend confirmation from the request payload.","security":[],"responses":{"200":{"description":"Success (no content)"}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"h_captcha_client_response":{"type":"string"},"email":{"type":"string","format":"email"}}},"example":{"h_captcha_client_response":"sample h captcha client response","email":"agent@example.com"}}}},"x-authentication":{"kind":"conditional","condition":"Captcha is checked before the confirmation dispatch.","alternatives":[{"kind":"capability","scheme":"hCaptcha","location":"body","name":"h_captcha_client_response","verification_boundary":"Auth::ResendConfirmationsController#create","algorithm":"opaque"}]}}},"/health":{"get":{"tags":["Health"],"operationId":"auto_get_health","summary":"Get health","description":"Returns the health identified by the path parameters.","security":[],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","example":"woot","enum":["woot"],"description":"Liveness marker returned by the health endpoint."}}},"example":{"status":"woot"}}}}}}},"/health/ready":{"get":{"tags":["Health"],"operationId":"auto_get_health_ready","summary":"Ready health","description":"Performs the ready operation on the targeted health resource.","security":[],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ready","degraded"],"description":"Readiness verdict — ready when every dependency check passes, degraded otherwise (the HTTP status code mirrors it)."},"checks":{"type":"string"}}},"example":{"status":"ready","checks":"sample checks"}}}}}}},"/dashboard-app-sdk/v2.js":{"get":{"tags":["Dashboard App SDK"],"operationId":"auto_get_dashboard_app_sdk_v2_js","summary":"Resolve the public Dashboard App SDK v2 module","description":"Stable, unauthenticated module URL for embedded Dashboard Apps. Redirects to the current content-hashed ES module built for the SDK, so integrations never depend on build-specific filenames and a rebuilt SDK reaches them immediately. The module exposes named exports (`connect`, `DashboardAppSDKError`, the `DASHBOARD_APP_*` constants) and also assigns the `window.ConversaLabsDashboardAppSDK` global for apps that cannot consume them.","security":[],"responses":{"302":{"description":"Redirect to the current content-hashed JavaScript module.","headers":{"Location":{"required":true,"description":"Absolute or host-relative URL of the current SDK module asset.","schema":{"type":"string","format":"uri-reference"}}}},"404":{"description":"The SDK module is unavailable because its build has not run for this deployment."}}}},"/dashboard-apps/v2/assertions/introspect":{"post":{"tags":["Dashboard App SDK"],"operationId":"auto_post_dashboard_apps_v2_assertions_introspect","summary":"Introspect a Dashboard App identity assertion","description":"Public server-to-server verification for the short-lived assertion returned by `identity.get_assertion`. It revalidates signature, issuer, expiry, app origin, feature flag, installation state, account membership, audience, and live capabilities on every request. Invalid, expired, revoked, or mismatched assertions always return `{ \"active\": false }` without disclosing which check failed. This assertion proves identity only and never authorizes the platform REST or MCP calls.","security":[],"responses":{"200":{"description":"Introspection result. Inactive assertions intentionally return no claims.","content":{"application/json":{"schema":{"oneOf":[{"type":"object","additionalProperties":false,"required":["active"],"properties":{"active":{"type":"boolean","enum":[false]}}},{"type":"object","additionalProperties":false,"required":["active","token_type","claims"],"properties":{"active":{"type":"boolean","enum":[true]},"token_type":{"type":"string","enum":["urn:conversalabs:dashboard-app-identity:v1"]},"claims":{"type":"object","additionalProperties":false,"required":["iss","aud","sub","iat","nbf","exp","jti","account","user","installation","capabilities"],"properties":{"iss":{"type":"string","format":"uri"},"aud":{"type":"string","format":"uri"},"sub":{"type":"string","pattern":"^user:[1-9][0-9]*$"},"iat":{"type":"integer"},"nbf":{"type":"integer"},"exp":{"type":"integer"},"jti":{"type":"string","format":"uuid"},"account":{"type":"object","additionalProperties":false,"required":["id","name"],"properties":{"id":{"type":"integer","minimum":1},"name":{"type":"string"}}},"user":{"type":"object","additionalProperties":false,"required":["id","name","type","role"],"properties":{"id":{"type":"integer","minimum":1},"name":{"type":"string"},"type":{"type":"string"},"role":{"type":"string","enum":["agent","administrator"]},"email":{"type":"string","format":"email"}}},"installation":{"type":"object","additionalProperties":false,"required":["id","dashboard_app_id","surface"],"properties":{"id":{"type":"integer","minimum":1},"dashboard_app_id":{"type":"integer","minimum":1},"surface":{"type":"string","enum":["conversation","sidebar"]}}},"capabilities":{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"string","enum":["account:read","current_user:read","current_user:email","permissions:read","appearance:read","installation:read","conversation:read","contact:read","contact:email","contact:phone","messages:read","identity:assertion"]}}}}}}]},"examples":{"active":{"value":{"active":true,"token_type":"urn:conversalabs:dashboard-app-identity:v1","claims":{"iss":"https://dashboard.example.com","aud":"https://erp.example","sub":"user:42","iat":1787328000,"nbf":1787327995,"exp":1787328120,"jti":"11111111-1111-4111-8111-111111111111","account":{"id":1,"name":"ConversaLabs"},"user":{"id":42,"name":"Ana","type":"User","role":"agent","email":"ana@example.com"},"installation":{"id":9,"dashboard_app_id":3,"surface":"sidebar"},"capabilities":["account:read","current_user:read","current_user:email","permissions:read","appearance:read","installation:read","identity:assertion"]}}},"inactive":{"value":{"active":false}}}}}},"429":{"description":"Per-IP introspection rate limit exceeded."}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["assertion"],"properties":{"assertion":{"type":"string","minLength":64,"maxLength":16384,"description":"Opaque assertion received from the embedded app frontend. The runtime enforces a 16 KiB UTF-8 byte limit before signature verification."},"expected_origin":{"type":"string","format":"uri","pattern":"^https?://[^/]+$","description":"Optional exact origin the app backend expects for this assertion."}}},"example":{"assertion":"eyJhbGciOiJIUzI1NiIsInR5cCI6InVybjp...","expected_origin":"https://erp.example"}}}}}},"/monitoring/metrics":{"get":{"tags":["Monitoring"],"operationId":"auto_get_monitoring_metrics","summary":"Scrape operations metrics (Prometheus)","description":"Prometheus text exposition (format 0.0.4) of the fleet-wide saturation aggregate — web thread occupancy, request backlog, replica/process counts, the connection pool summed across replicas, Sidekiq queue latency and depth, and the Redis memory ratio. Values are computed at scrape time from the Redis-published fleet snapshots; nothing is persisted to serve the route and only aggregates are exposed (no PII or credential). It also carries the execution cost per background-job class and per event listener (runs, summed and slowest duration in milliseconds, runs that raised) for the current and the previous UTC hour; the same four series per campaign dispatch stage, measured per sent campaign recipient with an exclusive wall and CPU clock (`stage` = throttle, render, conversation, build_stamp, send, graph, events_sync, events_enqueue, other or total; `clock` = wall or cpu; the `total`/`wall` runs are the recipients sent) and per WhatsApp Cloud media id cache outcome (`result` = hit, miss, bypass or evict; a miss carries the upload it ran); the live gauges of the campaigns dispatching now or paused/completed and updated in the last hour (status, recipients per delivery status, campaign messages created in the last complete minute, failed recipients per Meta error code or local reason code — labelled by the campaign number shown in the dashboard, the internal campaign id and the account id only), and the resident memory of the answering web process and of every live Sidekiq process. Authenticate with the operator bearer token from the OPERATIONS_METRICS_TOKEN environment variable (`Authorization: Bearer \u003ctoken\u003e`). The endpoint is inert — it returns 404 — until that variable is configured, so an install that has not opted in does not advertise it. When no web process is reporting, only `chatwoot_telemetry_fleet_available 0` is emitted; a fabricated zero saturation is deliberately avoided.","security":[{"operationsMetricsBearer":[]}],"responses":{"200":{"description":"Prometheus text exposition of the fleet-wide saturation aggregate.","content":{"text/plain":{"schema":{"type":"string","description":"Prometheus exposition format 0.0.4 — one gauge per line, with HELP/TYPE headers."},"example":"# HELP chatwoot_telemetry_fleet_available At least one web process is reporting (1) or none (0).\n# TYPE chatwoot_telemetry_fleet_available gauge\nchatwoot_telemetry_fleet_available 1\n# HELP chatwoot_web_saturation_ratio Fleet-wide Puma thread occupancy, 0..1.\n# TYPE chatwoot_web_saturation_ratio gauge\nchatwoot_web_saturation_ratio 0.425\n# HELP chatwoot_web_max_threads Total Puma threads across the reporting fleet.\n# TYPE chatwoot_web_max_threads gauge\nchatwoot_web_max_threads 40\n# HELP chatwoot_web_busy_threads Puma threads currently serving a request across the fleet.\n# TYPE chatwoot_web_busy_threads gauge\nchatwoot_web_busy_threads 17\n# HELP chatwoot_web_backlog Requests accepted and waiting for a thread across the fleet.\n# TYPE chatwoot_web_backlog gauge\nchatwoot_web_backlog 0\n# HELP chatwoot_web_replicas Reporting web replicas.\n# TYPE chatwoot_web_replicas gauge\nchatwoot_web_replicas 3\n# HELP chatwoot_web_processes Puma worker processes reporting across the fleet.\n# TYPE chatwoot_web_processes gauge\nchatwoot_web_processes 12\n# HELP chatwoot_web_configured_processes Puma worker processes the reporting replicas run by configuration (WEB_CONCURRENCY).\n# TYPE chatwoot_web_configured_processes gauge\nchatwoot_web_configured_processes 12\n# HELP chatwoot_web_unclustered Web processes running without cluster mode (WEB_CONCURRENCY unset).\n# TYPE chatwoot_web_unclustered gauge\nchatwoot_web_unclustered 0\n# HELP chatwoot_db_pool_size Active Record connection pool size across the fleet.\n# TYPE chatwoot_db_pool_size gauge\nchatwoot_db_pool_size 10\n# HELP chatwoot_db_pool_busy Checked-out Active Record connections across the fleet.\n# TYPE chatwoot_db_pool_busy gauge\nchatwoot_db_pool_busy 3\n# HELP chatwoot_db_pool_waiting Threads blocked waiting for a connection across the fleet.\n# TYPE chatwoot_db_pool_waiting gauge\nchatwoot_db_pool_waiting 0\n# HELP chatwoot_sidekiq_queue_latency_seconds Age of the oldest job per Sidekiq queue.\n# TYPE chatwoot_sidekiq_queue_latency_seconds gauge\nchatwoot_sidekiq_queue_latency_seconds{queue=\"default\"} 1.2\n# HELP chatwoot_sidekiq_queue_size Depth per Sidekiq queue.\n# TYPE chatwoot_sidekiq_queue_size gauge\nchatwoot_sidekiq_queue_size{queue=\"default\"} 3\n# HELP chatwoot_sidekiq_retry_size Jobs currently in the retry set.\n# TYPE chatwoot_sidekiq_retry_size gauge\nchatwoot_sidekiq_retry_size 0\n# HELP chatwoot_sidekiq_dead_size Jobs currently in the dead set.\n# TYPE chatwoot_sidekiq_dead_size gauge\nchatwoot_sidekiq_dead_size 0\n# HELP chatwoot_redis_memory_ratio Redis used memory over maxmemory, 0..1.\n# TYPE chatwoot_redis_memory_ratio gauge\nchatwoot_redis_memory_ratio 0.12\n# HELP chatwoot_job_runs Job runs in the UTC hour window.\n# TYPE chatwoot_job_runs gauge\nchatwoot_job_runs{job=\"SendReplyJob\",window=\"current_hour\"} 5231\n# HELP chatwoot_job_duration_ms_sum Summed job wall time in milliseconds in the UTC hour window.\n# TYPE chatwoot_job_duration_ms_sum gauge\nchatwoot_job_duration_ms_sum{job=\"SendReplyJob\",window=\"current_hour\"} 1843220.512\n# HELP chatwoot_job_duration_ms_max Slowest single job run in milliseconds in the UTC hour window.\n# TYPE chatwoot_job_duration_ms_max gauge\nchatwoot_job_duration_ms_max{job=\"SendReplyJob\",window=\"current_hour\"} 4120.33\n# HELP chatwoot_job_errors Job runs that raised in the UTC hour window.\n# TYPE chatwoot_job_errors gauge\nchatwoot_job_errors{job=\"SendReplyJob\",window=\"current_hour\"} 2\n# HELP chatwoot_listener_runs Listener runs in the UTC hour window.\n# TYPE chatwoot_listener_runs gauge\nchatwoot_listener_runs{listener=\"NotificationListener\",event=\"conversation_created\",window=\"current_hour\"} 4988\n# HELP chatwoot_listener_duration_ms_sum Summed listener wall time in milliseconds in the UTC hour window.\n# TYPE chatwoot_listener_duration_ms_sum gauge\nchatwoot_listener_duration_ms_sum{listener=\"NotificationListener\",event=\"conversation_created\",window=\"current_hour\"} 912344.2\n# HELP chatwoot_listener_duration_ms_max Slowest single listener run in milliseconds in the UTC hour window.\n# TYPE chatwoot_listener_duration_ms_max gauge\nchatwoot_listener_duration_ms_max{listener=\"NotificationListener\",event=\"conversation_created\",window=\"current_hour\"} 1203.7\n# HELP chatwoot_listener_errors Listener runs that raised in the UTC hour window.\n# TYPE chatwoot_listener_errors gauge\nchatwoot_listener_errors{listener=\"NotificationListener\",event=\"conversation_created\",window=\"current_hour\"} 0\n# HELP chatwoot_campaign_stage_runs Campaign_stage runs in the UTC hour window.\n# TYPE chatwoot_campaign_stage_runs gauge\nchatwoot_campaign_stage_runs{stage=\"total\",clock=\"wall\",window=\"current_hour\"} 12840\nchatwoot_campaign_stage_runs{stage=\"send\",clock=\"cpu\",window=\"current_hour\"} 12840\n# HELP chatwoot_campaign_stage_duration_ms_sum Summed campaign_stage wall time in milliseconds in the UTC hour window.\n# TYPE chatwoot_campaign_stage_duration_ms_sum gauge\nchatwoot_campaign_stage_duration_ms_sum{stage=\"total\",clock=\"wall\",window=\"current_hour\"} 17305120.4\nchatwoot_campaign_stage_duration_ms_sum{stage=\"send\",clock=\"cpu\",window=\"current_hour\"} 655112.8\n# HELP chatwoot_campaign_stage_duration_ms_max Slowest single campaign_stage run in milliseconds in the UTC hour window.\n# TYPE chatwoot_campaign_stage_duration_ms_max gauge\nchatwoot_campaign_stage_duration_ms_max{stage=\"total\",clock=\"wall\",window=\"current_hour\"} 3531.8\nchatwoot_campaign_stage_duration_ms_max{stage=\"send\",clock=\"cpu\",window=\"current_hour\"} 74.2\n# HELP chatwoot_campaign_stage_errors Campaign_stage runs that raised in the UTC hour window.\n# TYPE chatwoot_campaign_stage_errors gauge\nchatwoot_campaign_stage_errors{stage=\"total\",clock=\"wall\",window=\"current_hour\"} 0\nchatwoot_campaign_stage_errors{stage=\"send\",clock=\"cpu\",window=\"current_hour\"} 0\n# HELP chatwoot_whatsapp_media_id_cache_runs Whatsapp_media_id_cache runs in the UTC hour window.\n# TYPE chatwoot_whatsapp_media_id_cache_runs gauge\nchatwoot_whatsapp_media_id_cache_runs{result=\"hit\",window=\"current_hour\"} 4180\nchatwoot_whatsapp_media_id_cache_runs{result=\"miss\",window=\"current_hour\"} 2\n# HELP chatwoot_whatsapp_media_id_cache_duration_ms_sum Summed whatsapp_media_id_cache wall time in milliseconds in the UTC hour window.\n# TYPE chatwoot_whatsapp_media_id_cache_duration_ms_sum gauge\nchatwoot_whatsapp_media_id_cache_duration_ms_sum{result=\"hit\",window=\"current_hour\"} 0.0\nchatwoot_whatsapp_media_id_cache_duration_ms_sum{result=\"miss\",window=\"current_hour\"} 3120.5\n# HELP chatwoot_whatsapp_media_id_cache_duration_ms_max Slowest single whatsapp_media_id_cache run in milliseconds in the UTC hour window.\n# TYPE chatwoot_whatsapp_media_id_cache_duration_ms_max gauge\nchatwoot_whatsapp_media_id_cache_duration_ms_max{result=\"hit\",window=\"current_hour\"} 0.0\nchatwoot_whatsapp_media_id_cache_duration_ms_max{result=\"miss\",window=\"current_hour\"} 1810.2\n# HELP chatwoot_whatsapp_media_id_cache_errors Whatsapp_media_id_cache runs that raised in the UTC hour window.\n# TYPE chatwoot_whatsapp_media_id_cache_errors gauge\nchatwoot_whatsapp_media_id_cache_errors{result=\"hit\",window=\"current_hour\"} 0\nchatwoot_whatsapp_media_id_cache_errors{result=\"miss\",window=\"current_hour\"} 0\n# HELP chatwoot_campaign_metrics_available Campaign dispatch gauges are queryable (1) or unavailable (0).\n# TYPE chatwoot_campaign_metrics_available gauge\nchatwoot_campaign_metrics_available 1\n# HELP chatwoot_campaign_status Campaigns dispatching now, or paused/completed and updated in the last hour, by status.\n# TYPE chatwoot_campaign_status gauge\nchatwoot_campaign_status{campaign=\"16\",campaign_id=\"241\",account=\"3\",status=\"processing\"} 1\n# HELP chatwoot_campaign_recipients Campaign recipients per delivery status.\n# TYPE chatwoot_campaign_recipients gauge\nchatwoot_campaign_recipients{campaign=\"16\",campaign_id=\"241\",account=\"3\",status=\"sent\"} 2140\nchatwoot_campaign_recipients{campaign=\"16\",campaign_id=\"241\",account=\"3\",status=\"failed\"} 18\n# HELP chatwoot_campaign_messages_last_minute Campaign messages created in the last complete minute (dispatch pace).\n# TYPE chatwoot_campaign_messages_last_minute gauge\nchatwoot_campaign_messages_last_minute{campaign=\"16\",campaign_id=\"241\",account=\"3\"} 131\n# HELP chatwoot_campaign_failures Failed campaign recipients by Meta error code or local reason code.\n# TYPE chatwoot_campaign_failures gauge\nchatwoot_campaign_failures{campaign=\"16\",campaign_id=\"241\",account=\"3\",code=\"131026\"} 15\nchatwoot_campaign_failures{campaign=\"16\",campaign_id=\"241\",account=\"3\",code=\"blank_template_render\"} 3\n# HELP chatwoot_web_process_rss_bytes Resident memory of the web process that answered this scrape.\n# TYPE chatwoot_web_process_rss_bytes gauge\nchatwoot_web_process_rss_bytes 412352512\n# HELP chatwoot_sidekiq_process_rss_bytes Resident memory of each live Sidekiq process, from its own heartbeat.\n# TYPE chatwoot_sidekiq_process_rss_bytes gauge\nchatwoot_sidekiq_process_rss_bytes{identity=\"worker-campaigns:7:3f1c9a0b2d4e\",queues=\"campaigns\"} 734003200\n"}}},"401":{"description":"Missing or invalid operator token."},"404":{"description":"Endpoint is inert — OPERATIONS_METRICS_TOKEN is not configured on this installation."}},"parameters":[{"name":"Authorization","in":"header","required":true,"description":"Operator bearer token matching OPERATIONS_METRICS_TOKEN. Configure your Prometheus scrape job with this bearer token.","schema":{"type":"string","example":"Bearer sample-token"}}]}},"/api/v1/accounts/{id}/update_active_at":{"post":{"tags":["Account"],"operationId":"auto_post_api_v1_accounts_id_update_active_at","summary":"Stamp the account as recently used","description":"Records that the calling user is active in this account right now, which is what keeps the account ordering and the last-used account of the dashboard current. It takes no body and always stamps the present moment. The response carries no body.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Membership stamped as active at the current time. Empty body."}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{id}/cache_keys":{"get":{"tags":["Account"],"operationId":"auto_get_api_v1_accounts_id_cache_keys","summary":"Get account collection cache fingerprints","description":"Returns opaque String fingerprints for the account collections cached by the dashboard. Values are compared for equality, not interpreted as timestamps. Every HTTP reuse requires revalidation; send the previous ETag in If-None-Match to receive a bodyless 304 if the keys have not changed. A changed collection key returns 200 with the current map and a new ETag.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Current account collection cache fingerprints.","headers":{"Cache-Control":{"description":"Private storage is allowed, but every reuse must be revalidated.","schema":{"type":"string","enum":["private, no-cache"]},"example":"private, no-cache"},"ETag":{"description":"Validator derived from the current collection key map.","schema":{"type":"string"},"example":"W/\"current-fingerprint\""}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["cache_keys"],"properties":{"cache_keys":{"type":"object","additionalProperties":{"type":"string"},"description":"Opaque collection fingerprints keyed by label, inbox, team, and canned_response."}}},"example":{"cache_keys":{"label":"1791291600000","inbox":"1791291600001","team":"1791291600002","canned_response":"0000000000"}}}}},"304":{"description":"The collection keys have not changed; this response has no body.","headers":{"Cache-Control":{"description":"Private storage is allowed, but every reuse must be revalidated.","schema":{"type":"string","enum":["private, no-cache"]},"example":"private, no-cache"},"ETag":{"description":"Validator derived from the current collection key map.","schema":{"type":"string"},"example":"W/\"current-fingerprint\""}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"If-None-Match","in":"header","required":false,"description":"ETag from a previous successful response for this account.","schema":{"type":"string"},"example":"W/\"previous-fingerprint\""}]}},"/api/v1/accounts/{account_id}/conversation_sidebar_layout":{"get":{"tags":["Conversation Sidebar Layout"],"operationId":"auto_get_api_v1_accounts_account_id_conversation_sidebar_layout","summary":"Read the conversation panel layout default","description":"A human account member can read the account layout. Enforced mode overrides personal presentation without erasing stored personal layouts. No service permission is changed.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Effective account default and compare-and-set revision. Personal overrides are stored separately in the current user profile.","content":{"application/json":{"schema":{"type":"object","required":["layout","revision","source","can_manage","presets"],"properties":{"layout":{"type":"object","required":["version","mode","order","hidden"],"properties":{"version":{"type":"integer","enum":[1]},"mode":{"type":"string","enum":["customizable","enforced"]},"order":{"type":"array","description":"Stable panel IDs in saved order. New registered IDs are appended and unknown IDs are ignored. Applicability never deletes preferences.","items":{"type":"string","pattern":"^[a-z][a-z0-9_]*$"}},"hidden":{"type":"array","description":"Hidden panel IDs only affect presentation, not service permissions.","items":{"type":"string","pattern":"^[a-z][a-z0-9_]*$"}},"appearance":{"type":"object","additionalProperties":false,"description":"Sparse presentation preferences. Omission preserves saved values on updates; an explicit empty object resets system defaults. Never grants service or field access.","properties":{"list_avatar":{"type":"boolean"},"list_preview":{"type":"boolean"},"list_labels":{"type":"boolean"},"list_timestamp":{"type":"boolean"},"header_avatar":{"type":"boolean"},"header_id":{"type":"boolean"},"header_inbox":{"type":"boolean"},"contact_avatar":{"type":"boolean"},"contact_email":{"type":"boolean"},"contact_phone":{"type":"boolean"},"contact_identifier":{"type":"boolean"},"contact_company":{"type":"boolean"},"contact_social":{"type":"boolean"},"density":{"type":"string","enum":["comfortable","compact"]},"list_inbox":{"type":"string","enum":["auto","show","hide"]},"list_assignee":{"type":"string","enum":["auto","show","hide"]},"list_width":{"type":"string","enum":["narrow","standard","wide"]},"contact_width":{"type":"string","enum":["narrow","standard","wide"]},"header_actions":{"type":"string","enum":["inline","menu"]},"contact_actions":{"type":"string","enum":["icons","labels"]},"list_preview_lines":{"type":"integer","enum":[1,2]}}}}},"revision":{"type":"string","pattern":"^[0-9a-f]{64}$","description":"Opaque layout revision. Return this value when updating the account default."},"source":{"type":"string","enum":["system","account"]},"can_manage":{"type":"boolean","description":"Only a real account administrator may change the account default."},"presets":{"type":"array","maxItems":20,"items":{"type":"object","required":["id","name","version","surface","layout"],"properties":{"id":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$"},"name":{"type":"string","minLength":1,"maxLength":60,"description":"Trimmed plain-text name; markup and control characters are refused."},"version":{"type":"integer","enum":[1]},"surface":{"type":"string","enum":["conversation_sidebar"]},"layout":{"type":"object","required":["version","order","hidden"],"properties":{"version":{"type":"integer","enum":[1]},"order":{"type":"array","items":{"type":"string"}},"hidden":{"type":"array","items":{"type":"string"}},"appearance":{"type":"object","additionalProperties":false,"description":"Sparse presentation preferences. Omission preserves saved values on updates; an explicit empty object resets system defaults. Never grants service or field access.","properties":{"list_avatar":{"type":"boolean"},"list_preview":{"type":"boolean"},"list_labels":{"type":"boolean"},"list_timestamp":{"type":"boolean"},"header_avatar":{"type":"boolean"},"header_id":{"type":"boolean"},"header_inbox":{"type":"boolean"},"contact_avatar":{"type":"boolean"},"contact_email":{"type":"boolean"},"contact_phone":{"type":"boolean"},"contact_identifier":{"type":"boolean"},"contact_company":{"type":"boolean"},"contact_social":{"type":"boolean"},"density":{"type":"string","enum":["comfortable","compact"]},"list_inbox":{"type":"string","enum":["auto","show","hide"]},"list_assignee":{"type":"string","enum":["auto","show","hide"]},"list_width":{"type":"string","enum":["narrow","standard","wide"]},"contact_width":{"type":"string","enum":["narrow","standard","wide"]},"header_actions":{"type":"string","enum":["inline","menu"]},"contact_actions":{"type":"string","enum":["icons","labels"]},"list_preview_lines":{"type":"integer","enum":[1,2]}}}}}}},"description":"Full replacement of named account sets. IDs must be unique. Sets change presentation only."}}},"example":{"layout":{"version":1,"order":["translation","audio_transcription","maestro","engagement","organization","conversation_actions","macros","conversation_info","contact_attributes","contact_notes","shared_files","previous_conversation","conversation_participants","linear_issues","shopify_orders","whatsapp_group_settings","whatsapp_group_participants","whatsapp_newsletter_details","crm_pipelines","catalog","tasks","payments","message_scheduling","follow_up","sales","ads","agenda","conversation_calls","contracts","commerce","whatsapp_cost"],"hidden":[],"mode":"customizable","appearance":{"list_avatar":true,"list_preview":true,"list_labels":true,"list_timestamp":true,"header_avatar":true,"header_id":true,"header_inbox":true,"contact_avatar":true,"contact_email":true,"contact_phone":true,"contact_identifier":true,"contact_company":true,"contact_social":true,"density":"comfortable","list_inbox":"auto","list_assignee":"auto","list_width":"narrow","contact_width":"narrow","header_actions":"inline","contact_actions":"icons","list_preview_lines":1}},"revision":"63f7af58b43aa8b6c3c2ca737d3520eae44cd74518b6f7ad30442ae9c6a7f364","source":"system","can_manage":true,"presets":[{"id":"sample id","name":"Sample Name","version":1,"surface":"conversation_sidebar","layout":{"version":1,"order":["sample order"],"hidden":["sample hidden"],"appearance":{"list_avatar":true,"list_preview":true,"list_labels":true,"list_timestamp":true,"header_avatar":true,"header_id":true,"header_inbox":true,"contact_avatar":true,"contact_email":true,"contact_phone":true,"contact_identifier":true,"contact_company":true,"contact_social":true,"density":"comfortable","list_inbox":"auto","list_assignee":"auto","list_width":"narrow","contact_width":"narrow","header_actions":"inline","contact_actions":"icons","list_preview_lines":1}}}]}}}},"401":{"description":"Not signed in, not a member of this account (including a revoked membership), or not a human account member. Bots and service principals are refused. Nothing is read."},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]},"patch":{"tags":["Conversation Sidebar Layout"],"operationId":"auto_patch_api_v1_accounts_account_id_conversation_sidebar_layout","summary":"Update the conversation panel layout default","description":"Only an account administrator may update this default. The supplied revision is compared under the account row lock. A stale revision returns 409 without saving or auditing a change. Only this layout setting is merged; other account settings are preserved. Named sets share the same compare-and-set revision. A presets-only update preserves the default; a layout-only update preserves sets. At least one must be supplied.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Effective account default and compare-and-set revision. Personal overrides are stored separately in the current user profile.","content":{"application/json":{"schema":{"type":"object","required":["layout","revision","source","can_manage","presets"],"properties":{"layout":{"type":"object","required":["version","mode","order","hidden"],"properties":{"version":{"type":"integer","enum":[1]},"mode":{"type":"string","enum":["customizable","enforced"]},"order":{"type":"array","description":"Stable panel IDs in saved order. New registered IDs are appended and unknown IDs are ignored. Applicability never deletes preferences.","items":{"type":"string","pattern":"^[a-z][a-z0-9_]*$"}},"hidden":{"type":"array","description":"Hidden panel IDs only affect presentation, not service permissions.","items":{"type":"string","pattern":"^[a-z][a-z0-9_]*$"}},"appearance":{"type":"object","additionalProperties":false,"description":"Sparse presentation preferences. Omission preserves saved values on updates; an explicit empty object resets system defaults. Never grants service or field access.","properties":{"list_avatar":{"type":"boolean"},"list_preview":{"type":"boolean"},"list_labels":{"type":"boolean"},"list_timestamp":{"type":"boolean"},"header_avatar":{"type":"boolean"},"header_id":{"type":"boolean"},"header_inbox":{"type":"boolean"},"contact_avatar":{"type":"boolean"},"contact_email":{"type":"boolean"},"contact_phone":{"type":"boolean"},"contact_identifier":{"type":"boolean"},"contact_company":{"type":"boolean"},"contact_social":{"type":"boolean"},"density":{"type":"string","enum":["comfortable","compact"]},"list_inbox":{"type":"string","enum":["auto","show","hide"]},"list_assignee":{"type":"string","enum":["auto","show","hide"]},"list_width":{"type":"string","enum":["narrow","standard","wide"]},"contact_width":{"type":"string","enum":["narrow","standard","wide"]},"header_actions":{"type":"string","enum":["inline","menu"]},"contact_actions":{"type":"string","enum":["icons","labels"]},"list_preview_lines":{"type":"integer","enum":[1,2]}}}}},"revision":{"type":"string","pattern":"^[0-9a-f]{64}$","description":"Opaque layout revision. Return this value when updating the account default."},"source":{"type":"string","enum":["system","account"]},"can_manage":{"type":"boolean","description":"Only a real account administrator may change the account default."},"presets":{"type":"array","maxItems":20,"items":{"type":"object","required":["id","name","version","surface","layout"],"properties":{"id":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$"},"name":{"type":"string","minLength":1,"maxLength":60,"description":"Trimmed plain-text name; markup and control characters are refused."},"version":{"type":"integer","enum":[1]},"surface":{"type":"string","enum":["conversation_sidebar"]},"layout":{"type":"object","required":["version","order","hidden"],"properties":{"version":{"type":"integer","enum":[1]},"order":{"type":"array","items":{"type":"string"}},"hidden":{"type":"array","items":{"type":"string"}},"appearance":{"type":"object","additionalProperties":false,"description":"Sparse presentation preferences. Omission preserves saved values on updates; an explicit empty object resets system defaults. Never grants service or field access.","properties":{"list_avatar":{"type":"boolean"},"list_preview":{"type":"boolean"},"list_labels":{"type":"boolean"},"list_timestamp":{"type":"boolean"},"header_avatar":{"type":"boolean"},"header_id":{"type":"boolean"},"header_inbox":{"type":"boolean"},"contact_avatar":{"type":"boolean"},"contact_email":{"type":"boolean"},"contact_phone":{"type":"boolean"},"contact_identifier":{"type":"boolean"},"contact_company":{"type":"boolean"},"contact_social":{"type":"boolean"},"density":{"type":"string","enum":["comfortable","compact"]},"list_inbox":{"type":"string","enum":["auto","show","hide"]},"list_assignee":{"type":"string","enum":["auto","show","hide"]},"list_width":{"type":"string","enum":["narrow","standard","wide"]},"contact_width":{"type":"string","enum":["narrow","standard","wide"]},"header_actions":{"type":"string","enum":["inline","menu"]},"contact_actions":{"type":"string","enum":["icons","labels"]},"list_preview_lines":{"type":"integer","enum":[1,2]}}}}}}},"description":"Full replacement of named account sets. IDs must be unique. Sets change presentation only."}}},"example":{"layout":{"version":1,"order":["translation","audio_transcription","maestro","engagement","organization","conversation_actions","macros","conversation_info","contact_attributes","contact_notes","shared_files","previous_conversation","conversation_participants","linear_issues","shopify_orders","whatsapp_group_settings","whatsapp_group_participants","whatsapp_newsletter_details","crm_pipelines","catalog","tasks","payments","message_scheduling","follow_up","sales","ads","agenda","conversation_calls","contracts","commerce","whatsapp_cost"],"hidden":[],"mode":"customizable","appearance":{"list_avatar":true,"list_preview":true,"list_labels":true,"list_timestamp":true,"header_avatar":true,"header_id":true,"header_inbox":true,"contact_avatar":true,"contact_email":true,"contact_phone":true,"contact_identifier":true,"contact_company":true,"contact_social":true,"density":"comfortable","list_inbox":"auto","list_assignee":"auto","list_width":"narrow","contact_width":"narrow","header_actions":"inline","contact_actions":"icons","list_preview_lines":1}},"revision":"cef7b19f8107a8f8f8bec21fc1fac6a0fa35a3aaa95a9d049f32da217fc20d46","source":"account","can_manage":true,"presets":[{"id":"sample id","name":"Sample Name","version":1,"surface":"conversation_sidebar","layout":{"version":1,"order":["sample order"],"hidden":["sample hidden"],"appearance":{"list_avatar":true,"list_preview":true,"list_labels":true,"list_timestamp":true,"header_avatar":true,"header_id":true,"header_inbox":true,"contact_avatar":true,"contact_email":true,"contact_phone":true,"contact_identifier":true,"contact_company":true,"contact_social":true,"density":"comfortable","list_inbox":"auto","list_assignee":"auto","list_width":"narrow","contact_width":"narrow","header_actions":"inline","contact_actions":"icons","list_preview_lines":1}}}]}}}},"401":{"description":"Not signed in, not a member of this account (including a revoked membership), not a human account member, or not an account administrator. Nothing is saved or audited."},"404":{"description":"Account or resource not found"},"409":{"description":"Another administrator saved this layout after the caller read it. Reload and review before saving. No write or audit is performed.","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"type":"string"},"code":{"type":"string","enum":["sidebar_layout_conflict"]}}},"example":{"error":"Another administrator changed this layout. Reload and review the account default.","code":"sidebar_layout_conflict"}}}},"422":{"description":"The layout or revision has an invalid type, version, mode or identifier.","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"type":"string"},"code":{"type":"string","enum":["invalid_sidebar_layout"]}}},"example":{"error":"Invalid panel layout. Reload and try again.","code":"invalid_sidebar_layout"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["revision"],"properties":{"layout":{"type":"object","required":["version","mode","order","hidden"],"properties":{"version":{"type":"integer","enum":[1]},"mode":{"type":"string","enum":["customizable","enforced"]},"order":{"type":"array","description":"Stable panel IDs in saved order. New registered IDs are appended and unknown IDs are ignored. Applicability never deletes preferences.","items":{"type":"string","pattern":"^[a-z][a-z0-9_]*$"}},"hidden":{"type":"array","description":"Hidden panel IDs only affect presentation, not service permissions.","items":{"type":"string","pattern":"^[a-z][a-z0-9_]*$"}},"appearance":{"type":"object","additionalProperties":false,"description":"Sparse presentation preferences. Omission preserves saved values on updates; an explicit empty object resets system defaults. Never grants service or field access.","properties":{"list_avatar":{"type":"boolean"},"list_preview":{"type":"boolean"},"list_labels":{"type":"boolean"},"list_timestamp":{"type":"boolean"},"header_avatar":{"type":"boolean"},"header_id":{"type":"boolean"},"header_inbox":{"type":"boolean"},"contact_avatar":{"type":"boolean"},"contact_email":{"type":"boolean"},"contact_phone":{"type":"boolean"},"contact_identifier":{"type":"boolean"},"contact_company":{"type":"boolean"},"contact_social":{"type":"boolean"},"density":{"type":"string","enum":["comfortable","compact"]},"list_inbox":{"type":"string","enum":["auto","show","hide"]},"list_assignee":{"type":"string","enum":["auto","show","hide"]},"list_width":{"type":"string","enum":["narrow","standard","wide"]},"contact_width":{"type":"string","enum":["narrow","standard","wide"]},"header_actions":{"type":"string","enum":["inline","menu"]},"contact_actions":{"type":"string","enum":["icons","labels"]},"list_preview_lines":{"type":"integer","enum":[1,2]}}}}},"revision":{"type":"string","pattern":"^[0-9a-f]{64}$","description":"Opaque layout revision. Return this value when updating the account default."},"presets":{"type":"array","maxItems":20,"items":{"type":"object","required":["id","name","version","surface","layout"],"properties":{"id":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$"},"name":{"type":"string","minLength":1,"maxLength":60,"description":"Trimmed plain-text name; markup and control characters are refused."},"version":{"type":"integer","enum":[1]},"surface":{"type":"string","enum":["conversation_sidebar"]},"layout":{"type":"object","required":["version","order","hidden"],"properties":{"version":{"type":"integer","enum":[1]},"order":{"type":"array","items":{"type":"string"}},"hidden":{"type":"array","items":{"type":"string"}},"appearance":{"type":"object","additionalProperties":false,"description":"Sparse presentation preferences. Omission preserves saved values on updates; an explicit empty object resets system defaults. Never grants service or field access.","properties":{"list_avatar":{"type":"boolean"},"list_preview":{"type":"boolean"},"list_labels":{"type":"boolean"},"list_timestamp":{"type":"boolean"},"header_avatar":{"type":"boolean"},"header_id":{"type":"boolean"},"header_inbox":{"type":"boolean"},"contact_avatar":{"type":"boolean"},"contact_email":{"type":"boolean"},"contact_phone":{"type":"boolean"},"contact_identifier":{"type":"boolean"},"contact_company":{"type":"boolean"},"contact_social":{"type":"boolean"},"density":{"type":"string","enum":["comfortable","compact"]},"list_inbox":{"type":"string","enum":["auto","show","hide"]},"list_assignee":{"type":"string","enum":["auto","show","hide"]},"list_width":{"type":"string","enum":["narrow","standard","wide"]},"contact_width":{"type":"string","enum":["narrow","standard","wide"]},"header_actions":{"type":"string","enum":["inline","menu"]},"contact_actions":{"type":"string","enum":["icons","labels"]},"list_preview_lines":{"type":"integer","enum":[1,2]}}}}}}},"description":"Full replacement of named account sets. IDs must be unique. Sets change presentation only."}},"anyOf":[{"required":["layout"]},{"required":["presets"]}]},"example":{"layout":{"version":1,"order":["translation","audio_transcription","maestro","engagement","organization","conversation_actions","macros","conversation_info","contact_attributes","contact_notes","shared_files","previous_conversation","conversation_participants","linear_issues","shopify_orders","whatsapp_group_settings","whatsapp_group_participants","whatsapp_newsletter_details","crm_pipelines","catalog","tasks","payments","message_scheduling","follow_up","sales","ads","agenda","conversation_calls","contracts","commerce","whatsapp_cost"],"hidden":[],"mode":"customizable"},"revision":"63f7af58b43aa8b6c3c2ca737d3520eae44cd74518b6f7ad30442ae9c6a7f364"}}}}},"put":{"tags":["Conversation Sidebar Layout"],"operationId":"auto_put_api_v1_accounts_account_id_conversation_sidebar_layout","summary":"Update the conversation panel layout default","description":"Only an account administrator may update this default. The supplied revision is compared under the account row lock. A stale revision returns 409 without saving or auditing a change. Only this layout setting is merged; other account settings are preserved. Named sets share the same compare-and-set revision. A presets-only update preserves the default; a layout-only update preserves sets. At least one must be supplied.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Effective account default and compare-and-set revision. Personal overrides are stored separately in the current user profile.","content":{"application/json":{"schema":{"type":"object","required":["layout","revision","source","can_manage","presets"],"properties":{"layout":{"type":"object","required":["version","mode","order","hidden"],"properties":{"version":{"type":"integer","enum":[1]},"mode":{"type":"string","enum":["customizable","enforced"]},"order":{"type":"array","description":"Stable panel IDs in saved order. New registered IDs are appended and unknown IDs are ignored. Applicability never deletes preferences.","items":{"type":"string","pattern":"^[a-z][a-z0-9_]*$"}},"hidden":{"type":"array","description":"Hidden panel IDs only affect presentation, not service permissions.","items":{"type":"string","pattern":"^[a-z][a-z0-9_]*$"}},"appearance":{"type":"object","additionalProperties":false,"description":"Sparse presentation preferences. Omission preserves saved values on updates; an explicit empty object resets system defaults. Never grants service or field access.","properties":{"list_avatar":{"type":"boolean"},"list_preview":{"type":"boolean"},"list_labels":{"type":"boolean"},"list_timestamp":{"type":"boolean"},"header_avatar":{"type":"boolean"},"header_id":{"type":"boolean"},"header_inbox":{"type":"boolean"},"contact_avatar":{"type":"boolean"},"contact_email":{"type":"boolean"},"contact_phone":{"type":"boolean"},"contact_identifier":{"type":"boolean"},"contact_company":{"type":"boolean"},"contact_social":{"type":"boolean"},"density":{"type":"string","enum":["comfortable","compact"]},"list_inbox":{"type":"string","enum":["auto","show","hide"]},"list_assignee":{"type":"string","enum":["auto","show","hide"]},"list_width":{"type":"string","enum":["narrow","standard","wide"]},"contact_width":{"type":"string","enum":["narrow","standard","wide"]},"header_actions":{"type":"string","enum":["inline","menu"]},"contact_actions":{"type":"string","enum":["icons","labels"]},"list_preview_lines":{"type":"integer","enum":[1,2]}}}}},"revision":{"type":"string","pattern":"^[0-9a-f]{64}$","description":"Opaque layout revision. Return this value when updating the account default."},"source":{"type":"string","enum":["system","account"]},"can_manage":{"type":"boolean","description":"Only a real account administrator may change the account default."},"presets":{"type":"array","maxItems":20,"items":{"type":"object","required":["id","name","version","surface","layout"],"properties":{"id":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$"},"name":{"type":"string","minLength":1,"maxLength":60,"description":"Trimmed plain-text name; markup and control characters are refused."},"version":{"type":"integer","enum":[1]},"surface":{"type":"string","enum":["conversation_sidebar"]},"layout":{"type":"object","required":["version","order","hidden"],"properties":{"version":{"type":"integer","enum":[1]},"order":{"type":"array","items":{"type":"string"}},"hidden":{"type":"array","items":{"type":"string"}},"appearance":{"type":"object","additionalProperties":false,"description":"Sparse presentation preferences. Omission preserves saved values on updates; an explicit empty object resets system defaults. Never grants service or field access.","properties":{"list_avatar":{"type":"boolean"},"list_preview":{"type":"boolean"},"list_labels":{"type":"boolean"},"list_timestamp":{"type":"boolean"},"header_avatar":{"type":"boolean"},"header_id":{"type":"boolean"},"header_inbox":{"type":"boolean"},"contact_avatar":{"type":"boolean"},"contact_email":{"type":"boolean"},"contact_phone":{"type":"boolean"},"contact_identifier":{"type":"boolean"},"contact_company":{"type":"boolean"},"contact_social":{"type":"boolean"},"density":{"type":"string","enum":["comfortable","compact"]},"list_inbox":{"type":"string","enum":["auto","show","hide"]},"list_assignee":{"type":"string","enum":["auto","show","hide"]},"list_width":{"type":"string","enum":["narrow","standard","wide"]},"contact_width":{"type":"string","enum":["narrow","standard","wide"]},"header_actions":{"type":"string","enum":["inline","menu"]},"contact_actions":{"type":"string","enum":["icons","labels"]},"list_preview_lines":{"type":"integer","enum":[1,2]}}}}}}},"description":"Full replacement of named account sets. IDs must be unique. Sets change presentation only."}}},"example":{"layout":{"version":1,"order":["translation","audio_transcription","maestro","engagement","organization","conversation_actions","macros","conversation_info","contact_attributes","contact_notes","shared_files","previous_conversation","conversation_participants","linear_issues","shopify_orders","whatsapp_group_settings","whatsapp_group_participants","whatsapp_newsletter_details","crm_pipelines","catalog","tasks","payments","message_scheduling","follow_up","sales","ads","agenda","conversation_calls","contracts","commerce","whatsapp_cost"],"hidden":[],"mode":"customizable","appearance":{"list_avatar":true,"list_preview":true,"list_labels":true,"list_timestamp":true,"header_avatar":true,"header_id":true,"header_inbox":true,"contact_avatar":true,"contact_email":true,"contact_phone":true,"contact_identifier":true,"contact_company":true,"contact_social":true,"density":"comfortable","list_inbox":"auto","list_assignee":"auto","list_width":"narrow","contact_width":"narrow","header_actions":"inline","contact_actions":"icons","list_preview_lines":1}},"revision":"cef7b19f8107a8f8f8bec21fc1fac6a0fa35a3aaa95a9d049f32da217fc20d46","source":"account","can_manage":true,"presets":[{"id":"sample id","name":"Sample Name","version":1,"surface":"conversation_sidebar","layout":{"version":1,"order":["sample order"],"hidden":["sample hidden"],"appearance":{"list_avatar":true,"list_preview":true,"list_labels":true,"list_timestamp":true,"header_avatar":true,"header_id":true,"header_inbox":true,"contact_avatar":true,"contact_email":true,"contact_phone":true,"contact_identifier":true,"contact_company":true,"contact_social":true,"density":"comfortable","list_inbox":"auto","list_assignee":"auto","list_width":"narrow","contact_width":"narrow","header_actions":"inline","contact_actions":"icons","list_preview_lines":1}}}]}}}},"401":{"description":"Not signed in, not a member of this account (including a revoked membership), not a human account member, or not an account administrator. Nothing is saved or audited."},"404":{"description":"Account or resource not found"},"409":{"description":"Another administrator saved this layout after the caller read it. Reload and review before saving. No write or audit is performed.","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"type":"string"},"code":{"type":"string","enum":["sidebar_layout_conflict"]}}},"example":{"error":"Another administrator changed this layout. Reload and review the account default.","code":"sidebar_layout_conflict"}}}},"422":{"description":"The layout or revision has an invalid type, version, mode or identifier.","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"type":"string"},"code":{"type":"string","enum":["invalid_sidebar_layout"]}}},"example":{"error":"Invalid panel layout. Reload and try again.","code":"invalid_sidebar_layout"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["revision"],"properties":{"layout":{"type":"object","required":["version","mode","order","hidden"],"properties":{"version":{"type":"integer","enum":[1]},"mode":{"type":"string","enum":["customizable","enforced"]},"order":{"type":"array","description":"Stable panel IDs in saved order. New registered IDs are appended and unknown IDs are ignored. Applicability never deletes preferences.","items":{"type":"string","pattern":"^[a-z][a-z0-9_]*$"}},"hidden":{"type":"array","description":"Hidden panel IDs only affect presentation, not service permissions.","items":{"type":"string","pattern":"^[a-z][a-z0-9_]*$"}},"appearance":{"type":"object","additionalProperties":false,"description":"Sparse presentation preferences. Omission preserves saved values on updates; an explicit empty object resets system defaults. Never grants service or field access.","properties":{"list_avatar":{"type":"boolean"},"list_preview":{"type":"boolean"},"list_labels":{"type":"boolean"},"list_timestamp":{"type":"boolean"},"header_avatar":{"type":"boolean"},"header_id":{"type":"boolean"},"header_inbox":{"type":"boolean"},"contact_avatar":{"type":"boolean"},"contact_email":{"type":"boolean"},"contact_phone":{"type":"boolean"},"contact_identifier":{"type":"boolean"},"contact_company":{"type":"boolean"},"contact_social":{"type":"boolean"},"density":{"type":"string","enum":["comfortable","compact"]},"list_inbox":{"type":"string","enum":["auto","show","hide"]},"list_assignee":{"type":"string","enum":["auto","show","hide"]},"list_width":{"type":"string","enum":["narrow","standard","wide"]},"contact_width":{"type":"string","enum":["narrow","standard","wide"]},"header_actions":{"type":"string","enum":["inline","menu"]},"contact_actions":{"type":"string","enum":["icons","labels"]},"list_preview_lines":{"type":"integer","enum":[1,2]}}}}},"revision":{"type":"string","pattern":"^[0-9a-f]{64}$","description":"Opaque layout revision. Return this value when updating the account default."},"presets":{"type":"array","maxItems":20,"items":{"type":"object","required":["id","name","version","surface","layout"],"properties":{"id":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$"},"name":{"type":"string","minLength":1,"maxLength":60,"description":"Trimmed plain-text name; markup and control characters are refused."},"version":{"type":"integer","enum":[1]},"surface":{"type":"string","enum":["conversation_sidebar"]},"layout":{"type":"object","required":["version","order","hidden"],"properties":{"version":{"type":"integer","enum":[1]},"order":{"type":"array","items":{"type":"string"}},"hidden":{"type":"array","items":{"type":"string"}},"appearance":{"type":"object","additionalProperties":false,"description":"Sparse presentation preferences. Omission preserves saved values on updates; an explicit empty object resets system defaults. Never grants service or field access.","properties":{"list_avatar":{"type":"boolean"},"list_preview":{"type":"boolean"},"list_labels":{"type":"boolean"},"list_timestamp":{"type":"boolean"},"header_avatar":{"type":"boolean"},"header_id":{"type":"boolean"},"header_inbox":{"type":"boolean"},"contact_avatar":{"type":"boolean"},"contact_email":{"type":"boolean"},"contact_phone":{"type":"boolean"},"contact_identifier":{"type":"boolean"},"contact_company":{"type":"boolean"},"contact_social":{"type":"boolean"},"density":{"type":"string","enum":["comfortable","compact"]},"list_inbox":{"type":"string","enum":["auto","show","hide"]},"list_assignee":{"type":"string","enum":["auto","show","hide"]},"list_width":{"type":"string","enum":["narrow","standard","wide"]},"contact_width":{"type":"string","enum":["narrow","standard","wide"]},"header_actions":{"type":"string","enum":["inline","menu"]},"contact_actions":{"type":"string","enum":["icons","labels"]},"list_preview_lines":{"type":"integer","enum":[1,2]}}}}}}},"description":"Full replacement of named account sets. IDs must be unique. Sets change presentation only."}},"anyOf":[{"required":["layout"]},{"required":["presets"]}]},"example":{"layout":{"version":1,"order":["translation","audio_transcription","maestro","engagement","organization","conversation_actions","macros","conversation_info","contact_attributes","contact_notes","shared_files","previous_conversation","conversation_participants","linear_issues","shopify_orders","whatsapp_group_settings","whatsapp_group_participants","whatsapp_newsletter_details","crm_pipelines","catalog","tasks","payments","message_scheduling","follow_up","sales","ads","agenda","conversation_calls","contracts","commerce","whatsapp_cost"],"hidden":[],"mode":"customizable"},"revision":"63f7af58b43aa8b6c3c2ca737d3520eae44cd74518b6f7ad30442ae9c6a7f364"}}}}}},"/api/v1/accounts/{account_id}/bulk_actions":{"post":{"tags":["Bulk Actions"],"operationId":"auto_post_api_v1_accounts_account_id_bulk_actions","summary":"Create bulk actions","description":"Conversation requests with request_id return a durable HTTP 202 receipt. Check status_url and paginated results_url before reporting success. Identical retries reuse the operation; incompatible reuse returns 409. Missing request_id preserves legacy HTTP 200 and the Contact workflow. Assignment targets are validated before enqueue and again at execution.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Bulk action accepted and handed to a background job (one job for the whole selection). The response carries NO body — the selection is resolved and mutated asynchronously, so per-record outcomes are not known at request time and reach the dashboard over the realtime channel instead."},"401":{"description":"Authentication or authorization failure — the caller is not a member of the account, the account is suspended, or the effective role is not allowed to run the requested action (deleting records and exporting contacts are restricted to administrators or to roles carrying the matching grant). Returned as `{ error: \u003cmessage\u003e }`.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"You are not authorized to do this action"}}},"example":{"error":"You are not authorized to do this action"}}}},"404":{"description":"No account matches `account_id`.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Resource could not be found"}}},"example":{"error":"Resource could not be found"}}}},"422":{"description":"Unsupported resource type, invalid selection, invalid fields, unavailable conversation or incompatible destination.","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"error":{"type":"string"}}},{"type":"object","properties":{"success":{"type":"boolean","enum":[false]}}}]},"example":{"error":"sample error"}}}},"202":{"description":"Durable operation accepted or replayed. Acceptance does not mean the changes have completed.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["id","request_id","status","action","total","succeeded","failed","pending","retry_available","status_url","results_url"],"properties":{"id":{"type":"integer"},"request_id":{"type":"string"},"status":{"type":"string","enum":["queued","running","completed","partial","failed","paused"]},"action":{"type":"string","enum":["assignment","status","labels","delete"]},"total":{"type":"integer"},"succeeded":{"type":"integer"},"failed":{"type":"integer"},"pending":{"type":"integer"},"retry_available":{"type":"boolean","description":"True only for a paused execution. Resuming preserves all completed per-conversation receipts."},"error_code":{"type":["string","null"],"enum":["execution_interrupted",null]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"completed_at":{"type":["string","null"],"format":"date-time"},"status_url":{"type":"string","description":"Account-relative path for polling this operation; visible only to its requesting actor."},"results_url":{"type":"string","description":"Account-relative path for paginated per-conversation receipts."}}},"example":{"id":1,"request_id":"sample request id","status":"queued","action":"assignment","total":1,"succeeded":1,"failed":1,"pending":1,"retry_available":true,"error_code":"execution_interrupted","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","completed_at":"2026-01-15T10:30:00.000Z","status_url":"https://example.com/resource","results_url":"https://example.com/resource"}}},"headers":{"Location":{"description":"Status URL for this operation.","schema":{"type":"string"}}}},"409":{"description":"request_id was already used by this actor with incompatible normalized content.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}},"example":{"error":"sample error"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["Conversation","Contact"],"description":"Target resource type (case-insensitively camelized)","example":"Conversation"},"ids":{"type":"array","description":"Conversation display IDs, or Contact IDs. Durable Conversation requests require 1–1000 explicit IDs; hybrid projections resolve to each canonical conversation once. Only Contact select_all ignores this field.","items":{"type":"integer"},"example":[101,102,103]},"action_name":{"type":"string","enum":["delete","update_contact_type","assign_owner","block","unblock","export"],"description":"Operation to run over the selection. Conversation supports 'delete' only (other conversation mutations use fields/snoozed_until/labels). Contact supports the full set — 'delete' (authorized against destroy?, administrators only), 'update_contact_type' and 'assign_owner' (values in action_attributes), 'block'/'unblock', and 'export' (authorized against export?, administrators only — enqueues the standard CSV export e-mailed to the requester, scoped to the selection). Omit action_name to run a label add/remove operation via the labels object.","example":"assign_owner"},"action_attributes":{"type":"object","description":"Values consumed by the chosen action_name (Contact bulk actions only)","properties":{"contact_type":{"type":"string","enum":["visitor","lead","customer"],"description":"New contact type applied to every selected contact (action_name update_contact_type)","example":"customer"},"owner_id":{"type":["integer","null"],"description":"Agent id to assign as owner of every selected contact — must belong to the account; null (or omitted) unassigns (action_name assign_owner)","example":7}}},"select_all":{"type":"boolean","description":"When true, the action targets the WHOLE view the operator was looking at (Gmail-style \"select all N\"), resolved server-side at execution time — the label view when selection_scope carries a label, else every resolved contact of the account. Explicit ids are ignored. Contact bulk actions only.","example":false},"selection_scope":{"type":"object","description":"Narrows a select_all selection to the view it was made from (Contact bulk actions only)","properties":{"label":{"type":["string","null"],"description":"Label whose contact view the select-all selection came from; null/omitted means the full contact list","example":"vip"}}},"labels":{"type":"object","description":"Labels to add/remove across the selected records","properties":{"add":{"type":"array","items":{"type":"string"},"example":["priority"]},"remove":{"type":"array","items":{"type":"string"},"example":[]}}},"snoozed_until":{"oneOf":[{"type":"integer","description":"Unix seconds used by dashboard snooze actions.","example":1790000000},{"type":"string","format":"date-time","description":"ISO 8601 timestamp."},{"type":"null","description":"Explicit null clears an existing snooze deadline; until next reply."}],"description":"Conversation snooze deadline. Omission preserves the current value."},"fields":{"type":"object","description":"Conversation-only mutable fields","properties":{"status":{"type":"string","example":"resolved","enum":["open","resolved","pending","snoozed"],"description":"Conversation status to apply in the bulk action."},"assignee_id":{"type":["integer","null"],"example":7},"team_id":{"type":["integer","null"],"example":2}}},"request_id":{"type":"string","maxLength":128,"pattern":"^[A-Za-z0-9_.:-]{1,128}$","description":"Optional durable identity for a Conversation action, scoped to this account and actor. Reuse after a lost response. Omit for legacy operations.","example":"assignment-20260912-1"}}},"example":{"type":"Conversation","ids":[101,102,103],"action_name":"assign_owner","action_attributes":{"contact_type":"customer","owner_id":7},"select_all":false,"selection_scope":{"label":"vip"},"labels":{"add":["priority"],"remove":[]},"snoozed_until":1790000000,"fields":{"status":"resolved","assignee_id":7,"team_id":2},"request_id":"assignment-20260912-1"}}}}}},"/api/v1/accounts/{account_id}/bulk_actions/operations":{"get":{"tags":["Bulk Actions"],"operationId":"auto_get_api_v1_accounts_account_id_bulk_actions_operations","summary":"List my bulk operations","description":"Lists the latest 20 operations for this account and the current actor. request_id recovers a lost POST response. before_id paginates older operations. Other administrators cannot read another actor’s receipts.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"A page of operations belonging to the current actor.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["id","request_id","status","action","total","succeeded","failed","pending","retry_available","status_url","results_url"],"properties":{"id":{"type":"integer"},"request_id":{"type":"string"},"status":{"type":"string","enum":["queued","running","completed","partial","failed","paused"]},"action":{"type":"string","enum":["assignment","status","labels","delete"]},"total":{"type":"integer"},"succeeded":{"type":"integer"},"failed":{"type":"integer"},"pending":{"type":"integer"},"retry_available":{"type":"boolean","description":"True only for a paused execution. Resuming preserves all completed per-conversation receipts."},"error_code":{"type":["string","null"],"enum":["execution_interrupted",null]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"completed_at":{"type":["string","null"],"format":"date-time"},"status_url":{"type":"string","description":"Account-relative path for polling this operation; visible only to its requesting actor."},"results_url":{"type":"string","description":"Account-relative path for paginated per-conversation receipts."}}}},"next_before_id":{"type":["integer","null"]}}},"example":{"payload":[{"id":1,"request_id":"sample request id","status":"queued","action":"assignment","total":1,"succeeded":1,"failed":1,"pending":1,"retry_available":true,"error_code":"execution_interrupted","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","completed_at":"2026-01-15T10:30:00.000Z","status_url":"https://example.com/resource","results_url":"https://example.com/resource"}],"next_before_id":1}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"request_id","in":"query","schema":{"type":"string"},"description":"Optional exact request identity."},{"name":"before_id","in":"query","schema":{"type":"integer"},"description":"Exclusive cursor from next_before_id."}]}},"/api/v1/accounts/{account_id}/bulk_actions/operations/{operation_id}":{"get":{"tags":["Bulk Actions"],"operationId":"auto_get_api_v1_accounts_account_id_bulk_actions_operations_operation_id","summary":"Get my bulk operation","description":"Returns the actual queued, running or terminal state. Counts distinguish pending, successful and failed canonical conversations. HTTP 404 hides other actors and tenants.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Current durable execution state.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["id","request_id","status","action","total","succeeded","failed","pending","retry_available","status_url","results_url"],"properties":{"id":{"type":"integer"},"request_id":{"type":"string"},"status":{"type":"string","enum":["queued","running","completed","partial","failed","paused"]},"action":{"type":"string","enum":["assignment","status","labels","delete"]},"total":{"type":"integer"},"succeeded":{"type":"integer"},"failed":{"type":"integer"},"pending":{"type":"integer"},"retry_available":{"type":"boolean","description":"True only for a paused execution. Resuming preserves all completed per-conversation receipts."},"error_code":{"type":["string","null"],"enum":["execution_interrupted",null]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"completed_at":{"type":["string","null"],"format":"date-time"},"status_url":{"type":"string","description":"Account-relative path for polling this operation; visible only to its requesting actor."},"results_url":{"type":"string","description":"Account-relative path for paginated per-conversation receipts."}}},"example":{"id":1,"request_id":"sample request id","status":"queued","action":"assignment","total":1,"succeeded":1,"failed":1,"pending":1,"retry_available":true,"error_code":"execution_interrupted","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","completed_at":"2026-01-15T10:30:00.000Z","status_url":"https://example.com/resource","results_url":"https://example.com/resource"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"operation_id","in":"path","required":true,"schema":{"type":"integer","minimum":1},"description":"Identifier of an operation owned by the authenticated actor in this account."}]}},"/api/v1/accounts/{account_id}/bulk_actions/operations/{operation_id}/results":{"get":{"tags":["Bulk Actions"],"operationId":"auto_get_api_v1_accounts_account_id_bulk_actions_operations_operation_id_results","summary":"Get bulk operation results","description":"Lists at most 100 per-conversation receipts, including failures and canonical hybrid destinations. after_id is an exclusive cursor from next_after_id. Only the requesting actor can read these results.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Per-conversation results and next cursor.","content":{"application/json":{"schema":{"type":"object","properties":{"operation":{"type":"object","additionalProperties":false,"required":["id","request_id","status","action","total","succeeded","failed","pending","retry_available","status_url","results_url"],"properties":{"id":{"type":"integer"},"request_id":{"type":"string"},"status":{"type":"string","enum":["queued","running","completed","partial","failed","paused"]},"action":{"type":"string","enum":["assignment","status","labels","delete"]},"total":{"type":"integer"},"succeeded":{"type":"integer"},"failed":{"type":"integer"},"pending":{"type":"integer"},"retry_available":{"type":"boolean","description":"True only for a paused execution. Resuming preserves all completed per-conversation receipts."},"error_code":{"type":["string","null"],"enum":["execution_interrupted",null]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"completed_at":{"type":["string","null"],"format":"date-time"},"status_url":{"type":"string","description":"Account-relative path for polling this operation; visible only to its requesting actor."},"results_url":{"type":"string","description":"Account-relative path for paginated per-conversation receipts."}}},"payload":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"conversation_id":{"type":"integer","description":"Canonical conversation display ID, preserved after deletion."},"requested_ids":{"type":"array","items":{"type":"integer"},"description":"Selected display IDs that resolve to this one canonical target."},"status":{"type":"string","enum":["pending","succeeded","failed"]},"error_code":{"type":["string","null"],"enum":["actor_unavailable","conversation_unavailable","agent_unavailable","agent_not_in_inbox","agent_not_in_team","team_unavailable","delete_forbidden","frozen_conversation","target_changed","assignment_changed","validation_failed",null]},"completed_at":{"type":["string","null"],"format":"date-time"}}}},"next_after_id":{"type":["integer","null"]}}},"example":{"operation":{"id":1,"request_id":"sample request id","status":"queued","action":"assignment","total":1,"succeeded":1,"failed":1,"pending":1,"retry_available":true,"error_code":"execution_interrupted","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","completed_at":"2026-01-15T10:30:00.000Z","status_url":"https://example.com/resource","results_url":"https://example.com/resource"},"payload":[{"conversation_id":1,"requested_ids":[1],"status":"pending","error_code":"actor_unavailable","completed_at":"2026-01-15T10:30:00.000Z"}],"next_after_id":1}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"operation_id","in":"path","required":true,"schema":{"type":"integer","minimum":1},"description":"Identifier of an operation owned by the authenticated actor in this account."},{"name":"after_id","in":"query","schema":{"type":"integer"},"description":"Exclusive cursor from next_after_id."}]}},"/api/v1/accounts/{account_id}/bulk_actions/operations/{operation_id}/retry":{"post":{"tags":["Bulk Actions"],"operationId":"auto_post_api_v1_accounts_account_id_bulk_actions_operations_operation_id_retry","summary":"Resume a paused bulk operation","description":"Requeues only pending items of an interrupted execution. Completed and failed receipts are retained. Permissions and destination membership are rechecked in the worker. A running or terminal operation cannot be resumed.","security":[{"userApiKey":[]}],"responses":{"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"202":{"description":"Pending items have been queued for recovery.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["id","request_id","status","action","total","succeeded","failed","pending","retry_available","status_url","results_url"],"properties":{"id":{"type":"integer"},"request_id":{"type":"string"},"status":{"type":"string","enum":["queued","running","completed","partial","failed","paused"]},"action":{"type":"string","enum":["assignment","status","labels","delete"]},"total":{"type":"integer"},"succeeded":{"type":"integer"},"failed":{"type":"integer"},"pending":{"type":"integer"},"retry_available":{"type":"boolean","description":"True only for a paused execution. Resuming preserves all completed per-conversation receipts."},"error_code":{"type":["string","null"],"enum":["execution_interrupted",null]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"completed_at":{"type":["string","null"],"format":"date-time"},"status_url":{"type":"string","description":"Account-relative path for polling this operation; visible only to its requesting actor."},"results_url":{"type":"string","description":"Account-relative path for paginated per-conversation receipts."}}},"example":{"id":1,"request_id":"sample request id","status":"queued","action":"assignment","total":1,"succeeded":1,"failed":1,"pending":1,"retry_available":true,"error_code":"execution_interrupted","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","completed_at":"2026-01-15T10:30:00.000Z","status_url":"https://example.com/resource","results_url":"https://example.com/resource"}}}},"409":{"description":"The operation is not paused; retry_unavailable.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}},"example":{"error":"sample error"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"operation_id","in":"path","required":true,"schema":{"type":"integer","minimum":1},"description":"Identifier of an operation owned by the authenticated actor in this account."}]}},"/api/v1/accounts/{account_id}/direct_uploads":{"post":{"tags":["Upload"],"operationId":"auto_post_api_v1_accounts_account_id_direct_uploads","summary":"Reserve an account-owned storage blob","description":"Registers file metadata and returns a pre-signed object-storage PUT target. Reserved tenant and conversation metadata supplied by the client is discarded; the server stamps the authenticated account. This browser capability must be uploaded before its `signed_id` is submitted to an account attachment consumer and is intentionally unavailable as an MCP tool.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Blob reserved; upload the raw bytes using the returned URL and headers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/active_storage_direct_upload"},"example":{"id":4821,"key":"xf9pdq0k7z2m4bn6vc1a3s5d","filename":"attachment.pdf","content_type":"application/pdf","metadata":{},"service_name":"amazon","byte_size":20451,"checksum":"qLNbHUmZ6vC0FpHZjkQeBQ==","created_at":"2026-01-15T10:30:00.000Z","signed_id":"sample signed id","direct_upload":{"url":"https://example.com/resource","headers":{}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"422":{"description":"Required blob metadata is absent or invalid."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/active_storage_direct_upload_payload"},"example":{"blob":{"filename":"attachment.pdf","byte_size":20451,"checksum":"qLNbHUmZ6vC0FpHZjkQeBQ==","content_type":"application/pdf","metadata":{}}}}}}}},"/api/v1/accounts/{account_id}/setup/templates":{"get":{"tags":["Setup"],"operationId":"auto_get_api_v1_accounts_account_id_setup_templates","summary":"List the vertical setup templates","description":"The vertical template catalog the wizard gallery renders, localized to the requested (or account) locale. Each entry is a complete, deterministic workspace baseline for a business segment.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Localized template catalog.","content":{"application/json":{"schema":{"type":"object","properties":{"templates":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string","description":"Stable template key (default, clinica, ecommerce, imobiliaria, educacao, servicos)."},"name":{"type":"string","description":"Localized display name."},"description":{"type":"string","description":"Localized one-line description."},"icon":{"type":["string","null"],"description":"Icon token (lucide id) for the gallery card."}}}}}},"example":{"templates":[{"key":"clinica","name":"Clínica \u0026 Saúde","description":"Para clínicas, consultórios e práticas de saúde — funil de pacientes, lembretes de consulta e recuperação de faltas.","icon":"i-lucide-stethoscope"}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"locale","in":"query","required":false,"description":"Locale the template copy is resolved to. Omitted, the account locale is used.","schema":{"type":"string"},"example":"pt_BR"}]}},"/api/v1/accounts/{account_id}/setup/generate":{"post":{"tags":["Setup"],"operationId":"auto_post_api_v1_accounts_account_id_setup_generate","summary":"Generate a setup blueprint (async)","description":"Persists the business profile, stamps a draft run and enqueues asynchronous blueprint generation (vertical template + AI personalization; the AI being unavailable degrades to the template — the wizard never blocks). Poll GET setup until `report.generating` turns false; the draft blueprint then rides the payload for review. Admin-only; throttled per account (5/min).","security":[{"userApiKey":[]}],"responses":{"202":{"description":"Draft run stamped; generation enqueued. Body is the run payload (see GET setup — same shape) with `draft` true and `report.generating` true.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":["integer","null"],"description":"Run id."},"status":{"type":"string","enum":["none","pending","running","completed","partial","failed","canceled"],"description":"Run lifecycle."},"source":{"type":"string","enum":["maestro","template","merged","api","clone"],"description":"Where the blueprint came from."},"mode":{"type":"string","enum":["autonomous","interactive","api"],"description":"How the run was driven."},"template_key":{"type":["string","null"],"description":"Vertical template used as the base."},"stats":{"type":"object","additionalProperties":true,"description":"Per-section counters keyed by section name."},"report":{"type":"object","additionalProperties":true,"description":"Run report (warnings, generating, fallback, teardown summary)."},"draft":{"type":"boolean","description":"True while the run is a generated blueprint awaiting review/apply."},"blueprint":{"type":["object","null"],"additionalProperties":true,"description":"The generated SetupBlueprint — present only while draft is true."},"error":{"type":["string","null"],"description":"Engine-level failure message."},"started_at":{"type":["string","null"],"format":"date-time"},"finished_at":{"type":["string","null"],"format":"date-time"},"updated_at":{"type":["string","null"],"format":"date-time"},"items":{"type":"array","description":"The provisioning ledger in application order.","items":{"type":"object","properties":{"id":{"type":"integer"},"section":{"type":"string","description":"Blueprint section the item belongs to."},"key":{"type":"string","description":"The item's stable slug (idempotency key)."},"name":{"type":"string","description":"Human display name."},"status":{"type":"string","enum":["pending","applied","skipped","failed"],"description":"Ledger state of the item."},"error":{"type":["string","null"]},"record_type":{"type":["string","null"],"description":"Class of the materialized record."},"record_id":{"type":["integer","null"]}}}}}},"example":{"id":12,"status":"pending","source":"template","mode":"interactive","template_key":"clinica","stats":{},"report":{"generating":true},"draft":true,"blueprint":null,"error":null,"started_at":null,"finished_at":null,"updated_at":"2026-07-17T12:00:00.000Z","items":[{"id":301,"section":"labels","key":"vip","name":"vip","status":"pending","error":null,"record_type":null,"record_id":null}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"409":{"description":"A non-draft run is already in flight on this account.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["setup_already_running"],"description":"Conflict code."}}},"example":{"error":"setup_already_running"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"description":"Generation inputs — all optional; absent fields keep what signup/enrichment stored.","content":{"application/json":{"schema":{"type":"object","properties":{"template_key":{"type":"string","description":"Vertical template to use as the base (default, clinica, ecommerce, imobiliaria, educacao, servicos)."},"transcript":{"type":"array","description":"Optional AI-interview transcript that feeds personalization.","items":{"type":"object","properties":{"role":{"type":"string","enum":["user","assistant"],"description":"Who spoke this turn."},"content":{"type":"string","description":"The turn's text."}}}},"business_profile":{"type":"object","additionalProperties":true,"description":"Versioned business context (REQ-001): business_name, website, industry, sub_segment, company_size, team_size, sales_model, avg_ticket, products_services, tone_of_voice, locale, timezone, working_hours_hint, social{}, main_channels[], goals[]."}}},"example":{"template_key":"clinica","transcript":[{"role":"user","content":"Somos uma clínica odontológica com 8 atendentes."}],"business_profile":{"business_name":"Clínica Sorriso","industry":"clinica","company_size":"2-10","main_channels":["whatsapp","instagram"],"goals":["atender_melhor","agendar"],"tone_of_voice":"informal"}}}}}}},"/api/v1/accounts/{account_id}/setup/apply":{"post":{"tags":["Setup"],"operationId":"auto_post_api_v1_accounts_account_id_setup_apply","summary":"Apply the reviewed blueprint (async)","description":"Freezes the (optionally operator-edited) blueprint on the draft run and enqueues materialization. The blueprint is ALWAYS re-validated server-side — caps, key format, SSRF/secret guards — even when it round-trips unchanged. Poll GET setup for the live ledger. Admin-only.","security":[{"userApiKey":[]}],"responses":{"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"202":{"description":"Blueprint frozen; application enqueued. Body is the run payload (same contract as GET setup).","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":["integer","null"],"description":"Run id."},"status":{"type":"string","enum":["none","pending","running","completed","partial","failed","canceled"],"description":"Run lifecycle."},"source":{"type":"string","enum":["maestro","template","merged","api","clone"],"description":"Where the blueprint came from."},"mode":{"type":"string","enum":["autonomous","interactive","api"],"description":"How the run was driven."},"template_key":{"type":["string","null"],"description":"Vertical template used as the base."},"stats":{"type":"object","additionalProperties":true,"description":"Per-section counters keyed by section name."},"report":{"type":"object","additionalProperties":true,"description":"Run report (warnings, generating, fallback, teardown summary)."},"draft":{"type":"boolean","description":"True while the run is a generated blueprint awaiting review/apply."},"blueprint":{"type":["object","null"],"additionalProperties":true,"description":"The generated SetupBlueprint — present only while draft is true."},"error":{"type":["string","null"],"description":"Engine-level failure message."},"started_at":{"type":["string","null"],"format":"date-time"},"finished_at":{"type":["string","null"],"format":"date-time"},"updated_at":{"type":["string","null"],"format":"date-time"},"items":{"type":"array","description":"The provisioning ledger in application order.","items":{"type":"object","properties":{"id":{"type":"integer"},"section":{"type":"string","description":"Blueprint section the item belongs to."},"key":{"type":"string","description":"The item's stable slug (idempotency key)."},"name":{"type":"string","description":"Human display name."},"status":{"type":"string","enum":["pending","applied","skipped","failed"],"description":"Ledger state of the item."},"error":{"type":["string","null"]},"record_type":{"type":["string","null"],"description":"Class of the materialized record."},"record_id":{"type":["integer","null"]}}}}}},"example":{"id":12,"status":"pending","source":"merged","mode":"interactive","template_key":"clinica","stats":{},"report":{"generating":false},"draft":false,"blueprint":null,"error":null,"started_at":null,"finished_at":null,"updated_at":"2026-07-17T12:01:00.000Z","items":[{"id":301,"section":"labels","key":"vip","name":"vip","status":"pending","error":null,"record_type":null,"record_id":null}]}}}},"409":{"description":"The latest run is not a reviewable draft.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["setup_not_draft"],"description":"Conflict code."}}},"example":{"error":"setup_not_draft"}}}},"422":{"description":"The blueprint failed validation.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["invalid_blueprint"],"description":"Rejection code."},"details":{"type":"array","description":"Per-item validation errors.","items":{"type":"string"}}}},"example":{"error":"invalid_blueprint","details":["labels: 31 items exceeds cap of 30"]}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"description":"The edited blueprint. Omit to apply the draft exactly as generated.","content":{"application/json":{"schema":{"type":"object","properties":{"blueprint":{"type":"object","additionalProperties":true,"description":"SetupBlueprint envelope: {version: 1, meta{}, features{}, limits{}, sections{\u003csection\u003e: [items with stable `key` slugs]}}. Unknown sections are dropped with a warning; invalid items reject the whole apply with per-item errors."}}},"example":{"blueprint":{"version":1,"meta":{"source":"merged","template_key":"clinica","locale":"pt_BR","generated_by":"maestro"},"features":{"crm":true},"limits":{},"sections":{"labels":[{"key":"vip","title":"vip","color":"#8D25AA"}]}}}}}}}},"/api/v1/accounts/{account_id}/setup/retry":{"post":{"tags":["Setup"],"operationId":"auto_post_api_v1_accounts_account_id_setup_retry","summary":"Retry only the failed items (async)","description":"Re-enqueues the applier for a `partial`/`failed` run processing ONLY the items marked failed — applied and skipped items are never touched (idempotency by natural key). Admin-only.","security":[{"userApiKey":[]}],"responses":{"202":{"description":"Retry enqueued. Body is the run payload (same contract as GET setup).","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":["integer","null"],"description":"Run id."},"status":{"type":"string","enum":["none","pending","running","completed","partial","failed","canceled"],"description":"Run lifecycle."},"source":{"type":"string","enum":["maestro","template","merged","api","clone"],"description":"Where the blueprint came from."},"mode":{"type":"string","enum":["autonomous","interactive","api"],"description":"How the run was driven."},"template_key":{"type":["string","null"],"description":"Vertical template used as the base."},"stats":{"type":"object","additionalProperties":true,"description":"Per-section counters keyed by section name."},"report":{"type":"object","additionalProperties":true,"description":"Run report (warnings, generating, fallback, teardown summary)."},"draft":{"type":"boolean","description":"True while the run is a generated blueprint awaiting review/apply."},"blueprint":{"type":["object","null"],"additionalProperties":true,"description":"The generated SetupBlueprint — present only while draft is true."},"error":{"type":["string","null"],"description":"Engine-level failure message."},"started_at":{"type":["string","null"],"format":"date-time"},"finished_at":{"type":["string","null"],"format":"date-time"},"updated_at":{"type":["string","null"],"format":"date-time"},"items":{"type":"array","description":"The provisioning ledger in application order.","items":{"type":"object","properties":{"id":{"type":"integer"},"section":{"type":"string","description":"Blueprint section the item belongs to."},"key":{"type":"string","description":"The item's stable slug (idempotency key)."},"name":{"type":"string","description":"Human display name."},"status":{"type":"string","enum":["pending","applied","skipped","failed"],"description":"Ledger state of the item."},"error":{"type":["string","null"]},"record_type":{"type":["string","null"],"description":"Class of the materialized record."},"record_id":{"type":["integer","null"]}}}}}},"example":{"id":12,"status":"partial","source":"merged","mode":"interactive","template_key":"clinica","stats":{"labels":{"applied":5,"failed":1}},"report":{},"draft":false,"blueprint":null,"error":null,"started_at":"2026-07-17T12:00:00.000Z","finished_at":"2026-07-17T12:00:41.000Z","updated_at":"2026-07-17T12:05:00.000Z","items":[{"id":301,"section":"labels","key":"vip","name":"vip","status":"pending","error":null,"record_type":null,"record_id":null}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"409":{"description":"The latest run is not retryable (not partial/failed).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["setup_not_retryable"],"description":"Conflict code."}}},"example":{"error":"setup_not_retryable"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/setup/teardown":{"post":{"tags":["Setup"],"operationId":"auto_post_api_v1_accounts_account_id_setup_teardown","summary":"Undo the provisioning run (async)","description":"Ledger-reverse undo: destroys ONLY the records this run's applied items point at — records that pre-existed, were skipped, or were created by the user afterwards are never touched. Terminal (the run ends `canceled`). Type-to-confirm: the literal confirmation token is required. Admin-only.","security":[{"userApiKey":[]}],"responses":{"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"202":{"description":"Teardown enqueued. Body is the run payload (same contract as GET setup).","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":["integer","null"],"description":"Run id."},"status":{"type":"string","enum":["none","pending","running","completed","partial","failed","canceled"],"description":"Run lifecycle."},"source":{"type":"string","enum":["maestro","template","merged","api","clone"],"description":"Where the blueprint came from."},"mode":{"type":"string","enum":["autonomous","interactive","api"],"description":"How the run was driven."},"template_key":{"type":["string","null"],"description":"Vertical template used as the base."},"stats":{"type":"object","additionalProperties":true,"description":"Per-section counters keyed by section name."},"report":{"type":"object","additionalProperties":true,"description":"Run report (warnings, generating, fallback, teardown summary)."},"draft":{"type":"boolean","description":"True while the run is a generated blueprint awaiting review/apply."},"blueprint":{"type":["object","null"],"additionalProperties":true,"description":"The generated SetupBlueprint — present only while draft is true."},"error":{"type":["string","null"],"description":"Engine-level failure message."},"started_at":{"type":["string","null"],"format":"date-time"},"finished_at":{"type":["string","null"],"format":"date-time"},"updated_at":{"type":["string","null"],"format":"date-time"},"items":{"type":"array","description":"The provisioning ledger in application order.","items":{"type":"object","properties":{"id":{"type":"integer"},"section":{"type":"string","description":"Blueprint section the item belongs to."},"key":{"type":"string","description":"The item's stable slug (idempotency key)."},"name":{"type":"string","description":"Human display name."},"status":{"type":"string","enum":["pending","applied","skipped","failed"],"description":"Ledger state of the item."},"error":{"type":["string","null"]},"record_type":{"type":["string","null"],"description":"Class of the materialized record."},"record_id":{"type":["integer","null"]}}}}}},"example":{"id":12,"status":"completed","source":"merged","mode":"autonomous","template_key":"clinica","stats":{"labels":{"applied":6}},"report":{},"draft":false,"blueprint":null,"error":null,"started_at":"2026-07-17T12:00:00.000Z","finished_at":"2026-07-17T12:00:41.000Z","updated_at":"2026-07-17T12:10:00.000Z","items":[{"id":301,"section":"labels","key":"vip","name":"vip","status":"pending","error":null,"record_type":null,"record_id":null}]}}}},"409":{"description":"The latest run cannot be torn down (not completed/partial).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["setup_not_torn_down"],"description":"Conflict code."}}},"example":{"error":"setup_not_torn_down"}}}},"422":{"description":"Missing/incorrect confirmation token.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["confirmation_required"],"description":"Rejection code."}}},"example":{"error":"confirmation_required"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"description":"Explicit confirmation of the destructive undo.","content":{"application/json":{"schema":{"type":"object","required":["confirmation"],"properties":{"confirmation":{"type":"string","enum":["undo"],"description":"Must be the literal string `undo` (typed by the admin)."}}},"example":{"confirmation":"undo"}}}}}},"/api/v1/accounts/{account_id}/setup":{"get":{"tags":["Setup"],"operationId":"auto_get_api_v1_accounts_account_id_setup","summary":"Get the provisioning run status","description":"Live status of the account's latest generative-onboarding run: headline status, per-section counters and the per-item ledger the wizard renders. While the run is a reviewable draft the generated blueprint rides along; applied runs expose only the ledger. An account that never started a setup answers a stable cold shape `{\"status\": \"none\"}`. Available when the account has the `ai_onboarding` feature or the installation-wide onboarding mode is on; otherwise 404.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The latest run (or the cold shape when none exists).","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":["integer","null"],"description":"Run id. Absent/null only on the cold shape."},"status":{"type":"string","enum":["none","pending","running","completed","partial","failed","canceled"],"description":"Run lifecycle. `none` = the account never started a setup. `partial` = finished with some failed items (retryable)."},"source":{"type":"string","enum":["maestro","template","merged","api","clone"],"description":"Where the applied blueprint came from. `merged` = vertical template personalized by the AI."},"mode":{"type":"string","enum":["autonomous","interactive","api"],"description":"How the run was driven."},"template_key":{"type":["string","null"],"description":"Vertical template used as the base (default, clinica, ecommerce, imobiliaria, educacao, servicos)."},"stats":{"type":"object","additionalProperties":true,"description":"Per-section counters keyed by section name, each value an object of counts keyed by item status (applied/skipped/failed/pending)."},"report":{"type":"object","additionalProperties":true,"description":"Run report: validation warnings, `generating` (draft still being generated), `fallback` (deterministic template used), teardown summary."},"draft":{"type":"boolean","description":"True while the run is a generated blueprint awaiting review/apply."},"blueprint":{"type":["object","null"],"additionalProperties":true,"description":"The generated SetupBlueprint (envelope version/meta/features/limits/sections) — present ONLY while `draft` is true; re-validated server-side on apply."},"error":{"type":["string","null"],"description":"Engine-level failure message when the run failed before/outside item processing."},"started_at":{"type":["string","null"],"format":"date-time"},"finished_at":{"type":["string","null"],"format":"date-time"},"updated_at":{"type":["string","null"],"format":"date-time"},"items":{"type":"array","description":"The provisioning ledger, one entry per blueprint item, in application order.","items":{"type":"object","properties":{"id":{"type":"integer"},"section":{"type":"string","description":"Blueprint section the item belongs to (labels, teams, crm_pipelines, automation_rules, …)."},"key":{"type":"string","description":"The item's stable slug — the idempotency key."},"name":{"type":"string","description":"Human display name (title/name/display_name of the payload)."},"status":{"type":"string","enum":["pending","applied","skipped","failed"],"description":"applied = created by this run; skipped = already existed (never clobbered) or torn down; failed = isolated error (retryable)."},"error":{"type":["string","null"]},"record_type":{"type":["string","null"],"description":"Class of the materialized record (teardown target)."},"record_id":{"type":["integer","null"]}}}}}},"example":{"id":12,"status":"partial","source":"merged","mode":"interactive","template_key":"clinica","stats":{"labels":{"applied":5,"failed":1},"teams":{"applied":2}},"report":{"warnings":["unknown feature dropped: made_up_flag"],"fallback":false},"draft":false,"blueprint":null,"error":null,"started_at":"2026-07-17T12:00:00.000Z","finished_at":"2026-07-17T12:00:41.000Z","updated_at":"2026-07-17T12:00:41.000Z","items":[{"id":301,"section":"labels","key":"vip","name":"vip","status":"applied","error":null,"record_type":"Label","record_id":88},{"id":302,"section":"labels","key":"urgente","name":"urgente","status":"failed","error":"ActiveRecord::RecordInvalid: Title is invalid","record_type":null,"record_id":null}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/usage":{"get":{"tags":["Usage"],"operationId":"auto_get_api_v1_accounts_account_id_usage","summary":"Get the account's monthly usage","description":"Monthly consumption buckets (messages, conversations, contacts, ai_requests, ai_tokens) plus the configured `\u003cmetric\u003e_monthly` limits, ready for gauges. Metering is dark-shipped — 404 while the `usage_metering` feature is off for the account.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Monthly buckets, newest month first.","content":{"application/json":{"schema":{"type":"object","properties":{"metrics":{"type":"array","description":"The complete metric set.","items":{"type":"string","enum":["messages","conversations","contacts","ai_requests","ai_tokens"]}},"limits":{"type":"object","additionalProperties":true,"description":"Configured monthly ceilings keyed by metric (only metrics with a limit appear)."},"usage":{"type":"object","additionalProperties":true,"description":"Buckets keyed by `YYYY-MM`, each an object of metric → accumulated value."}}},"example":{"metrics":["messages","conversations","contacts","ai_requests","ai_tokens"],"limits":{"messages":10000},"usage":{"2026-07":{"messages":4210,"conversations":380,"contacts":129,"ai_requests":77,"ai_tokens":91240},"2026-06":{"messages":9800,"conversations":745,"contacts":301,"ai_requests":140,"ai_tokens":182002}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"months","in":"query","required":false,"description":"How many months of history to return, clamped to 1-12. Omitted or blank returns 3 months.","schema":{"type":"integer","default":3},"example":6}]}},"/api/v1/accounts/{account_id}/limits":{"get":{"tags":["Limits"],"operationId":"auto_get_api_v1_accounts_account_id_limits","summary":"Get limits","description":"Returns the limit identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"limits":{"type":"string"}}},"example":{"id":1,"limits":"sample limits"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/mcp/profiles/{id}/rotate_token":{"post":{"tags":["Mcp"],"operationId":"auto_post_api_v1_accounts_account_id_mcp_profiles_id_rotate_token","summary":"Rotate an MCP access profile's bearer secret","description":"Mints a fresh bearer secret for the profile — invalidating the one every connected client is using — and returns the new plaintext EXACTLY once. Admin-only. The JSON body requires `form_nonce`, exactly 64 lowercase hexadecimal characters (256-bit); a retry after commit returns `409 idempotency_replay`.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The profile and its NEW bearer secret (shown ONCE).","headers":{"Cache-Control":{"description":"This management response can expose bearer-secret state and must never be retained.","schema":{"type":"string","enum":["no-store, no-cache"],"example":"no-store, no-cache"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"profile":{"type":"object","properties":{"id":{"type":"integer","description":"Profile id.","example":12},"name":{"type":"string","description":"Human-readable label for the connection.","example":"Claude — Support"},"public_id":{"type":"string","description":"The non-secret slug that appears in the connection URL. Unique within the account.","example":"a1b2c3d4e5f6g7h8i9j0"},"acting_user_id":{"type":["integer","null"],"description":"The account member this profile executes as (null if the user was deleted).","example":5},"acting_user":{"type":["object","null"],"description":"The acting user, or null if it was deleted. `available` is false when the user is no longer a member of the account (the profile is then disabled at auth time).","properties":{"id":{"type":"integer","description":"User id.","example":5},"name":{"type":"string","description":"User display name.","example":"Alice Costa"},"available":{"type":"boolean","description":"Whether the user is still a member of the account.","example":true}}},"enabled_toolsets":{"type":"array","description":"The module tags this profile selected (its stored selection; the super-admin ceiling is applied at runtime).","items":{"type":"string","enum":["Access Roles","Account","Account AgentBots","Ads","Agent Bots","Agent Capacity Policies","Agents","Assignable Agents","Assignment Policies","Audit Logs","Automation Rule","Bug Reports","Bulk Actions","CRM","CRM Item Attachments","CRM Item Checklist","CRM Item Line Items","CRM Item Notes","CRM Item Participants","CRM Items","CRM Organizations","CRM Pipelines","CRM Reports","CRM Stages","CRM Templates","CSAT Survey Responses","Calendar","Calendar Availability","Calendar Connections","Calendar Event Types","Calendar Events","Calendar Reports","Calendar Settings","Campaigns","Canned Responses","Captain","Catalog","Catalog Categories","Catalog Products","Catalog Reports","Catalog Sync Runs","Catalog Sync Sources","Catalog Variants","Channels","Commerce","Companies","Contact Inboxes","Contact Labels","Contacts","Contracts","Conversation Assignments","Conversations","Custom Attributes","Custom Filters","Custom Roles","Custom Scripts","Dashboard Apps","Engagement","Flow Builder","Follow-up","Google","Governance","Growth Distribution","Growth Social","Guided Tours","Help Center","Inboxes","Instagram","Integrations","Internal Chat","Labels","Limits","Live Reports","Macros","Maestro","Media Library","Messages","Microsoft","Notification Subscriptions","Notifications","Notion","Onboarding","Organization Memberships","Organizations","Payment Charges","Payment Connections","Payment Demo","Payment Plans","Payment Reports","Payment Subscriptions","Payments","Profile","Relationship Types","Relationships","Reports","Routing Policies","SAML","SLA Policies","Sales","Search","Summary Reports","Task Attachments","Task Checklist","Task Comments","Task Dependencies","Task Links","Task Lists","Task Reminders","Task SLA Policies","Task Templates","Task Watchers","Tasks","Team Management","Teams","TikTok","Twitter","Webhooks","WhatsApp","WhatsApp Calls","WhatsApp Hub","WhatsApp Web","WhatsApp Web Calls","Year In Review"],"example":"Conversations"}},"read_only":{"type":"boolean","description":"When true, every write/destructive tool is hidden from this profile's catalog.","example":false},"enabled":{"type":"boolean","description":"Whether the profile is active. A disabled profile authenticates with 401.","example":true},"tool_cap":{"type":["integer","null"],"description":"Per-profile override of the listing cap (null uses the installation-wide cap).","example":null},"token_last_four":{"type":["string","null"],"description":"The last four characters of the bearer secret, for recognition. The full secret is shown only once, on create/rotate.","example":"ab12"},"last_used_at":{"type":["string","null"],"format":"date-time","description":"When the connection was last used (throttled heartbeat), or null if never.","example":"2026-07-16T12:04:11Z"},"endpoint_url":{"type":"string","description":"Canonical public static bearer MCP URL for this profile. It is omitted when the installation has no safe configured public HTTPS origin; clients must never infer it from a request Host header.","example":"https://app.example.com/api/v1/accounts/1/mcp/c/a1b2c3d4e5f6g7h8i9j0"},"oauth_endpoint_url":{"type":"string","format":"uri","description":"The separate, non-secret OAuth MCP resource URL when native OAuth is enabled with a canonical public issuer. It is omitted otherwise and never accepts the static profile bearer secret.","example":"https://app.example.com/api/v1/accounts/1/mcp/oauth/c/a1b2c3d4e5f6g7h8i9j0"},"tool_count":{"type":"integer","description":"Tools actually exposed right now (ceiling ∩ selection, read-only filter, then cap).","example":42},"selected_tool_count":{"type":"integer","description":"What the selection resolves to BEFORE the cap. When greater than `tool_count`, the cap truncated the list.","example":42},"truncated":{"type":"boolean","description":"Whether the cap truncated the selection (`selected_tool_count` \u003e `tool_count`).","example":false},"chatgpt_compat":{"type":"boolean","description":"Whether this profile also exposes the deep-research aliases `search` and `fetch` that the ChatGPT connector requires by name. They describe only what the profile already exposes and grant no extra access, but they consume two slots of the listing cap.","example":false}}},"token":{"type":"string","description":"The new bearer secret in plaintext — shown ONLY here.","example":"sample-token"}}},"example":{"profile":{"id":12,"name":"Claude — Support","public_id":"a1b2c3d4e5f6g7h8i9j0","acting_user_id":5,"acting_user":{"id":5,"name":"Alice Costa","available":true},"enabled_toolsets":["Conversations","Contacts"],"read_only":false,"enabled":true,"tool_cap":null,"token_last_four":"ab12","last_used_at":"2026-07-16T12:04:11Z","endpoint_url":"https://app.example.com/api/v1/accounts/1/mcp/c/a1b2c3d4e5f6g7h8i9j0","oauth_endpoint_url":"https://app.example.com/api/v1/accounts/1/mcp/oauth/c/a1b2c3d4e5f6g7h8i9j0","tool_count":42,"selected_tool_count":42,"truncated":false,"chatgpt_compat":false},"token":"sample-token"}}}},"401":{"description":"Missing or invalid access token, or the caller is not an account administrator.","headers":{"Cache-Control":{"description":"This management response can expose bearer-secret state and must never be retained.","schema":{"type":"string","enum":["no-store, no-cache"],"example":"no-store, no-cache"}}}},"404":{"description":"MCP is not enabled for this account, or disabled for the whole installation. The feature is dark-shipped, so an unavailable surface is indistinguishable from a missing route.","headers":{"Cache-Control":{"description":"This management response can expose bearer-secret state and must never be retained.","schema":{"type":"string","enum":["no-store, no-cache"],"example":"no-store, no-cache"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Why the MCP surface is unavailable.","example":"MCP is not enabled for this account"}}},"example":{"error":"MCP is not enabled for this account"}}}},"422":{"description":"The required reveal nonce is missing or malformed, or authority validation failed before rotation.","headers":{"Cache-Control":{"description":"This management response can expose bearer-secret state and must never be retained.","schema":{"type":"string","enum":["no-store, no-cache"],"example":"no-store, no-cache"}}},"content":{"application/json":{"schema":{"oneOf":[{"type":"object","required":["error"],"properties":{"error":{"type":"string","enum":["invalid_idempotency_nonce"]}}},{"type":"object","required":["error"],"properties":{"error":{"type":"array","items":{"type":"string"}}}}]},"example":{"error":"invalid_idempotency_nonce"}}}},"409":{"description":"The reveal nonce was already committed. `idempotency_replay` returns no bearer; `idempotency_conflict` indicates a different request tried to reuse it.","headers":{"Cache-Control":{"description":"This management response can expose bearer-secret state and must never be retained.","schema":{"type":"string","enum":["no-store, no-cache"],"example":"no-store, no-cache"}}},"content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","enum":["idempotency_replay","idempotency_conflict"]}}},"example":{"error":"idempotency_replay"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["form_nonce"],"properties":{"form_nonce":{"type":"string","pattern":"^[a-f0-9]{64}$","description":"Opaque 256-bit nonce unique to this actor/account reveal request.","example":"0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"}}},"example":{"form_nonce":"0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"}}}}}},"/api/v1/accounts/{account_id}/mcp/profiles":{"get":{"tags":["Mcp"],"operationId":"auto_get_api_v1_accounts_account_id_mcp_profiles","summary":"List the account MCP access profiles","description":"Returns every MCP access profile for the account (each an independently-scoped connection with its own toolsets, read-only mode, acting user, URL and bearer secret), plus the picker menu the editor needs: the full module list, the areas they group under, the account members that can be an acting user, and the hard per-server tool cap. Admin-only. The secret plaintext is never returned — `token_last_four` is shown for recognition; the full secret appears only once on create/rotate.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The account's access profiles and the picker menu (toolsets, areas, members, cap).","headers":{"Cache-Control":{"description":"This management response can expose bearer-secret state and must never be retained.","schema":{"type":"string","enum":["no-store, no-cache"],"example":"no-store, no-cache"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"profiles":{"type":"array","description":"The account's MCP access profiles.","items":{"type":"object","properties":{"id":{"type":"integer","description":"Profile id.","example":12},"name":{"type":"string","description":"Human-readable label for the connection.","example":"Claude — Support"},"public_id":{"type":"string","description":"The non-secret slug that appears in the connection URL. Unique within the account.","example":"a1b2c3d4e5f6g7h8i9j0"},"acting_user_id":{"type":["integer","null"],"description":"The account member this profile executes as (null if the user was deleted).","example":5},"acting_user":{"type":["object","null"],"description":"The acting user, or null if it was deleted. Ineligible identities block the profile until it is reassigned.","properties":{"id":{"type":"integer","description":"User id.","example":5},"name":{"type":"string","description":"User display name.","example":"Alice Costa"},"available":{"type":"boolean","description":"Legacy alias of eligible.","example":true},"eligible":{"type":"boolean","description":"Whether the user is an active, confirmed member and can act for this profile.","example":true},"blocked_reason":{"type":["string","null"],"description":"Localized explanation when the identity is not eligible.","example":"This user has not confirmed their account."},"blocked_reason_code":{"type":["string","null"],"enum":["membership","inactive","unconfirmed",null],"description":"Stable machine-readable reason for an ineligible identity.","example":"unconfirmed"}}},"enabled_toolsets":{"type":"array","description":"The module tags this profile selected (its stored selection; the super-admin ceiling is applied at runtime).","items":{"type":"string","enum":["Access Roles","Account","Account AgentBots","Ads","Agent Bots","Agent Capacity Policies","Agents","Assignable Agents","Assignment Policies","Audit Logs","Automation Rule","Bug Reports","Bulk Actions","CRM","CRM Item Attachments","CRM Item Checklist","CRM Item Line Items","CRM Item Notes","CRM Item Participants","CRM Items","CRM Organizations","CRM Pipelines","CRM Reports","CRM Stages","CRM Templates","CSAT Survey Responses","Calendar","Calendar Availability","Calendar Connections","Calendar Event Types","Calendar Events","Calendar Reports","Calendar Settings","Campaigns","Canned Responses","Captain","Catalog","Catalog Categories","Catalog Products","Catalog Reports","Catalog Sync Runs","Catalog Sync Sources","Catalog Variants","Channels","Commerce","Companies","Contact Inboxes","Contact Labels","Contacts","Contracts","Conversation Assignments","Conversations","Custom Attributes","Custom Filters","Custom Roles","Custom Scripts","Dashboard Apps","Engagement","Flow Builder","Follow-up","Google","Governance","Growth Distribution","Growth Social","Guided Tours","Help Center","Inboxes","Instagram","Integrations","Internal Chat","Labels","Limits","Live Reports","Macros","Maestro","Media Library","Messages","Microsoft","Notification Subscriptions","Notifications","Notion","Onboarding","Organization Memberships","Organizations","Payment Charges","Payment Connections","Payment Demo","Payment Plans","Payment Reports","Payment Subscriptions","Payments","Profile","Relationship Types","Relationships","Reports","Routing Policies","SAML","SLA Policies","Sales","Search","Summary Reports","Task Attachments","Task Checklist","Task Comments","Task Dependencies","Task Links","Task Lists","Task Reminders","Task SLA Policies","Task Templates","Task Watchers","Tasks","Team Management","Teams","TikTok","Twitter","Webhooks","WhatsApp","WhatsApp Calls","WhatsApp Hub","WhatsApp Web","WhatsApp Web Calls","Year In Review"],"example":"Conversations"}},"read_only":{"type":"boolean","description":"When true, every write/destructive tool is hidden from this profile's catalog.","example":false},"enabled":{"type":"boolean","description":"Whether the profile is active. A disabled profile authenticates with 401.","example":true},"tool_cap":{"type":["integer","null"],"description":"Per-profile override of the listing cap (null uses the installation-wide cap).","example":null},"token_last_four":{"type":["string","null"],"description":"The last four characters of the bearer secret, for recognition. The full secret is shown only once, on create/rotate.","example":"ab12"},"last_used_at":{"type":["string","null"],"format":"date-time","description":"When the connection was last used (throttled heartbeat), or null if never.","example":"2026-07-16T12:04:11Z"},"endpoint_url":{"type":"string","description":"Canonical public static bearer MCP URL for this profile. It is omitted when the installation has no safe configured public HTTPS origin; clients must never infer it from a request Host header.","example":"https://app.example.com/api/v1/accounts/1/mcp/c/a1b2c3d4e5f6g7h8i9j0"},"oauth_endpoint_url":{"type":"string","format":"uri","description":"The separate, non-secret OAuth MCP resource URL for this profile. It is omitted unless native OAuth is enabled and the installation has a canonical public issuer. A client uses this URL for OAuth discovery and consent; it must never send the static profile bearer secret to this resource.","example":"https://app.example.com/api/v1/accounts/1/mcp/oauth/c/a1b2c3d4e5f6g7h8i9j0"},"tool_count":{"type":"integer","description":"Tools actually exposed right now (ceiling ∩ selection, read-only filter, then cap).","example":42},"selected_tool_count":{"type":"integer","description":"What the selection resolves to BEFORE the cap. When greater than `tool_count`, the cap truncated the list.","example":42},"truncated":{"type":"boolean","description":"Whether the cap truncated the selection (`selected_tool_count` \u003e `tool_count`).","example":false},"chatgpt_compat":{"type":"boolean","description":"Whether this profile also exposes the two deep-research aliases `search` and `fetch`, which the ChatGPT connector requires by name. They describe only what the profile already exposes and grant no extra access, but they consume two slots of the listing cap, so they are opt-in. Always false where `chatgpt_compat_supported` is false.","example":false}}}},"available_toolsets":{"type":"array","description":"The complete menu of modules an admin can turn on or off for a profile — each with its area, its out-of-the-box default, whether the super-admin ceiling blocks it, and what it costs in tools.","items":{"type":"object","properties":{"tag":{"type":"string","enum":["Access Roles","Account","Account AgentBots","Ads","Agent Bots","Agent Capacity Policies","Agents","Assignable Agents","Assignment Policies","Audit Logs","Automation Rule","Bug Reports","Bulk Actions","CRM","CRM Item Attachments","CRM Item Checklist","CRM Item Line Items","CRM Item Notes","CRM Item Participants","CRM Items","CRM Organizations","CRM Pipelines","CRM Reports","CRM Stages","CRM Templates","CSAT Survey Responses","Calendar","Calendar Availability","Calendar Connections","Calendar Event Types","Calendar Events","Calendar Reports","Calendar Settings","Campaigns","Canned Responses","Captain","Catalog","Catalog Categories","Catalog Products","Catalog Reports","Catalog Sync Runs","Catalog Sync Sources","Catalog Variants","Channels","Commerce","Companies","Contact Inboxes","Contact Labels","Contacts","Contracts","Conversation Assignments","Conversations","Custom Attributes","Custom Filters","Custom Roles","Custom Scripts","Dashboard Apps","Engagement","Flow Builder","Follow-up","Google","Governance","Growth Distribution","Growth Social","Guided Tours","Help Center","Inboxes","Instagram","Integrations","Internal Chat","Labels","Limits","Live Reports","Macros","Maestro","Media Library","Messages","Microsoft","Notification Subscriptions","Notifications","Notion","Onboarding","Organization Memberships","Organizations","Payment Charges","Payment Connections","Payment Demo","Payment Plans","Payment Reports","Payment Subscriptions","Payments","Profile","Relationship Types","Relationships","Reports","Routing Policies","SAML","SLA Policies","Sales","Search","Summary Reports","Task Attachments","Task Checklist","Task Comments","Task Dependencies","Task Links","Task Lists","Task Reminders","Task SLA Policies","Task Templates","Task Watchers","Tasks","Team Management","Teams","TikTok","Twitter","Webhooks","WhatsApp","WhatsApp Calls","WhatsApp Hub","WhatsApp Web","WhatsApp Web Calls","Year In Review"],"description":"The module tag (matches the API tag its tools come from).","example":"Conversations"},"group":{"type":"string","enum":["conversations","contacts_crm","catalog_commerce","payments","tasks_calendar","whatsapp","channels_integrations","automation_ai","growth_sales","reports","team_admin","content","other"],"description":"The area this module is filed under in the dashboard.","example":"conversations"},"default":{"type":"boolean","description":"Whether the module is on out of the box.","example":true},"blocked_by_ceiling":{"type":"boolean","description":"Whether the super-admin ceiling blocks this module installation-wide.","example":false},"tool_count":{"type":"integer","description":"How many tools this module contributes.","example":24}}}},"toolset_groups":{"type":"array","description":"The AREAS the modules are filed under, in the order the dashboard renders them. Presentation only; labels live in the dashboard i18n. `other` is the catch-all.","items":{"type":"string","enum":["conversations","contacts_crm","catalog_commerce","payments","tasks_calendar","whatsapp","channels_integrations","automation_ai","growth_sales","reports","team_admin","content","other"],"example":"conversations"}},"toolset_presets":{"type":"array","description":"Named STARTING POINTS for the module picker. Applying one only ADDS its tags to the current selection — a preset is never a filter, and no module is hidden because a preset omits it. Unknown tags are dropped server-side, and a preset left with no tags is not returned.","items":{"type":"object","properties":{"key":{"type":"string","description":"Stable preset id. The dashboard i18n supplies the label; an untranslated preset falls back to this key.","example":"essential"},"tags":{"type":"array","description":"The module tags this preset proposes adding.","items":{"type":"string","example":"Conversations"}}}}},"chatgpt_compat_supported":{"type":"boolean","description":"Whether this installation can offer the ChatGPT deep-research aliases at all. False while the additive migration that stores the per-profile flag has not been applied; the editor then hides the option instead of showing a switch that would silently do nothing.","example":true},"available_users":{"type":"array","description":"Account members with their acting-user eligibility. The dashboard must exclude entries whose eligible value is false.","items":{"type":"object","properties":{"id":{"type":"integer","description":"User id.","example":5},"name":{"type":"string","description":"User display name.","example":"Alice Costa"},"eligible":{"type":"boolean","description":"Whether the member is active and confirmed for profile execution.","example":true},"blocked_reason":{"type":["string","null"],"description":"Localized explanation when the member is not eligible.","example":"This user has not confirmed their account."},"blocked_reason_code":{"type":["string","null"],"enum":["membership","inactive","unconfirmed",null],"description":"Stable machine-readable reason for an ineligible member.","example":"unconfirmed"}}}},"cap":{"type":"integer","description":"The installation-wide per-server listing cap (a profile may override it).","example":512},"oauth_enabled":{"type":"boolean","description":"Whether native OAuth is currently usable for account MCP connections. It is false when OAuth is disabled or the installation has no valid canonical public issuer; in either case profiles omit oauth_endpoint_url.","example":true}}},"example":{"profiles":[{"id":12,"name":"Claude — Support","public_id":"a1b2c3d4e5f6g7h8i9j0","acting_user_id":5,"acting_user":{"id":5,"name":"Alice Costa","available":true,"eligible":true,"blocked_reason":null,"blocked_reason_code":null},"enabled_toolsets":["Conversations","Contacts"],"read_only":false,"enabled":true,"tool_cap":null,"token_last_four":"ab12","last_used_at":"2026-07-16T12:04:11Z","endpoint_url":"https://app.example.com/api/v1/accounts/1/mcp/c/a1b2c3d4e5f6g7h8i9j0","oauth_endpoint_url":"https://app.example.com/api/v1/accounts/1/mcp/oauth/c/a1b2c3d4e5f6g7h8i9j0","tool_count":42,"selected_tool_count":42,"truncated":false,"chatgpt_compat":false}],"available_toolsets":[{"tag":"Conversations","group":"conversations","default":true,"blocked_by_ceiling":false,"tool_count":24},{"tag":"Contacts","group":"contacts_crm","default":true,"blocked_by_ceiling":false,"tool_count":18},{"tag":"Reports","group":"reports","default":false,"blocked_by_ceiling":false,"tool_count":12}],"toolset_groups":["conversations","contacts_crm","catalog_commerce","payments","tasks_calendar","whatsapp","channels_integrations","automation_ai","growth_sales","reports","team_admin","content","other"],"available_users":[{"id":5,"name":"Alice Costa","eligible":true,"blocked_reason":null,"blocked_reason_code":null},{"id":8,"name":"Bruno Dias","eligible":false,"blocked_reason":"This user has not confirmed their account.","blocked_reason_code":"unconfirmed"}],"cap":512,"oauth_enabled":true,"toolset_presets":[{"key":"essential","tags":["Conversations"]}],"chatgpt_compat_supported":true}}}},"401":{"description":"Unauthorized"},"404":{"description":"MCP is not enabled for this account, or disabled for the whole installation. The feature is dark-shipped, so an unavailable surface is indistinguishable from a missing route.","headers":{"Cache-Control":{"description":"This management response can expose bearer-secret state and must never be retained.","schema":{"type":"string","enum":["no-store, no-cache"],"example":"no-store, no-cache"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Why the MCP surface is unavailable.","example":"MCP is not enabled for this account"}}},"example":{"error":"MCP is not enabled for this account"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."}]},"post":{"tags":["Mcp"],"operationId":"auto_post_api_v1_accounts_account_id_mcp_profiles","summary":"Create an MCP access profile","description":"Creates an access profile and returns its bearer secret EXACTLY once (`token`) — it is never retrievable again; only the SHA-256 hash + last four are stored. Admin-only. `acting_user_id` must be an account member. Unknown/platform-only toolset tags are dropped on write. A tag outside the current Super Admin ceiling is rejected with `422` and is not saved. `form_nonce` is the canonical opaque 64-lowercase-hex (256-bit) body nonce required for this reveal; an identical committed retry returns `409 idempotency_replay` without a token.","security":[{"userApiKey":[]}],"responses":{"201":{"description":"The created profile and its bearer secret (shown ONCE).","headers":{"Cache-Control":{"description":"This management response can expose bearer-secret state and must never be retained.","schema":{"type":"string","enum":["no-store, no-cache"],"example":"no-store, no-cache"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"profile":{"type":"object","properties":{"id":{"type":"integer","description":"Profile id.","example":12},"name":{"type":"string","description":"Human-readable label for the connection.","example":"Claude — Support"},"public_id":{"type":"string","description":"The non-secret slug that appears in the connection URL. Unique within the account.","example":"a1b2c3d4e5f6g7h8i9j0"},"acting_user_id":{"type":["integer","null"],"description":"The account member this profile executes as (null if the user was deleted).","example":5},"acting_user":{"type":["object","null"],"description":"The acting user, or null if it was deleted. `available` is false when the user is no longer a member of the account (the profile is then disabled at auth time).","properties":{"id":{"type":"integer","description":"User id.","example":5},"name":{"type":"string","description":"User display name.","example":"Alice Costa"},"available":{"type":"boolean","description":"Whether the user is still a member of the account.","example":true}}},"enabled_toolsets":{"type":"array","description":"The module tags this profile selected (its stored selection; the super-admin ceiling is applied at runtime).","items":{"type":"string","enum":["Access Roles","Account","Account AgentBots","Ads","Agent Bots","Agent Capacity Policies","Agents","Assignable Agents","Assignment Policies","Audit Logs","Automation Rule","Bug Reports","Bulk Actions","CRM","CRM Item Attachments","CRM Item Checklist","CRM Item Line Items","CRM Item Notes","CRM Item Participants","CRM Items","CRM Organizations","CRM Pipelines","CRM Reports","CRM Stages","CRM Templates","CSAT Survey Responses","Calendar","Calendar Availability","Calendar Connections","Calendar Event Types","Calendar Events","Calendar Reports","Calendar Settings","Campaigns","Canned Responses","Captain","Catalog","Catalog Categories","Catalog Products","Catalog Reports","Catalog Sync Runs","Catalog Sync Sources","Catalog Variants","Channels","Commerce","Companies","Contact Inboxes","Contact Labels","Contacts","Contracts","Conversation Assignments","Conversations","Custom Attributes","Custom Filters","Custom Roles","Custom Scripts","Dashboard Apps","Engagement","Flow Builder","Follow-up","Google","Governance","Growth Distribution","Growth Social","Guided Tours","Help Center","Inboxes","Instagram","Integrations","Internal Chat","Labels","Limits","Live Reports","Macros","Maestro","Media Library","Messages","Microsoft","Notification Subscriptions","Notifications","Notion","Onboarding","Organization Memberships","Organizations","Payment Charges","Payment Connections","Payment Demo","Payment Plans","Payment Reports","Payment Subscriptions","Payments","Profile","Relationship Types","Relationships","Reports","Routing Policies","SAML","SLA Policies","Sales","Search","Summary Reports","Task Attachments","Task Checklist","Task Comments","Task Dependencies","Task Links","Task Lists","Task Reminders","Task SLA Policies","Task Templates","Task Watchers","Tasks","Team Management","Teams","TikTok","Twitter","Webhooks","WhatsApp","WhatsApp Calls","WhatsApp Hub","WhatsApp Web","WhatsApp Web Calls","Year In Review"],"example":"Conversations"}},"read_only":{"type":"boolean","description":"When true, every write/destructive tool is hidden from this profile's catalog.","example":false},"enabled":{"type":"boolean","description":"Whether the profile is active. A disabled profile authenticates with 401.","example":true},"tool_cap":{"type":["integer","null"],"description":"Per-profile override of the listing cap (null uses the installation-wide cap).","example":null},"token_last_four":{"type":["string","null"],"description":"The last four characters of the bearer secret, for recognition. The full secret is shown only once, on create/rotate.","example":"ab12"},"last_used_at":{"type":["string","null"],"format":"date-time","description":"When the connection was last used (throttled heartbeat), or null if never.","example":"2026-07-16T12:04:11Z"},"endpoint_url":{"type":"string","description":"Canonical public static bearer MCP URL for this profile. It is omitted when the installation has no safe configured public HTTPS origin; clients must never infer it from a request Host header.","example":"https://app.example.com/api/v1/accounts/1/mcp/c/a1b2c3d4e5f6g7h8i9j0"},"oauth_endpoint_url":{"type":"string","format":"uri","description":"The separate, non-secret OAuth MCP resource URL when native OAuth is enabled with a canonical public issuer. It is omitted otherwise and never accepts the static profile bearer secret.","example":"https://app.example.com/api/v1/accounts/1/mcp/oauth/c/a1b2c3d4e5f6g7h8i9j0"},"tool_count":{"type":"integer","description":"Tools actually exposed right now (ceiling ∩ selection, read-only filter, then cap).","example":42},"selected_tool_count":{"type":"integer","description":"What the selection resolves to BEFORE the cap. When greater than `tool_count`, the cap truncated the list.","example":42},"truncated":{"type":"boolean","description":"Whether the cap truncated the selection (`selected_tool_count` \u003e `tool_count`).","example":false},"chatgpt_compat":{"type":"boolean","description":"Whether this profile also exposes the deep-research aliases `search` and `fetch` that the ChatGPT connector requires by name. They describe only what the profile already exposes and grant no extra access, but they consume two slots of the listing cap.","example":false}}},"token":{"type":"string","description":"The bearer secret in plaintext — shown ONLY here. Store it now; it cannot be retrieved again.","example":"sample-token"}}},"example":{"profile":{"id":12,"name":"Claude — Support","public_id":"a1b2c3d4e5f6g7h8i9j0","acting_user_id":5,"acting_user":{"id":5,"name":"Alice Costa","available":true},"enabled_toolsets":["Conversations","Contacts"],"read_only":false,"enabled":true,"tool_cap":null,"token_last_four":"ab12","last_used_at":"2026-07-16T12:04:11Z","endpoint_url":"https://app.example.com/api/v1/accounts/1/mcp/c/a1b2c3d4e5f6g7h8i9j0","oauth_endpoint_url":"https://app.example.com/api/v1/accounts/1/mcp/oauth/c/a1b2c3d4e5f6g7h8i9j0","tool_count":42,"selected_tool_count":42,"truncated":false,"chatgpt_compat":false},"token":"sample-token"}}}},"401":{"description":"Missing or invalid access token, or the caller is not an account administrator.","headers":{"Cache-Control":{"description":"This management response can expose bearer-secret state and must never be retained.","schema":{"type":"string","enum":["no-store, no-cache"],"example":"no-store, no-cache"}}}},"404":{"description":"MCP is not enabled for this account, or disabled for the whole installation. The feature is dark-shipped, so an unavailable surface is indistinguishable from a missing route.","headers":{"Cache-Control":{"description":"This management response can expose bearer-secret state and must never be retained.","schema":{"type":"string","enum":["no-store, no-cache"],"example":"no-store, no-cache"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Why the MCP surface is unavailable.","example":"MCP is not enabled for this account"}}},"example":{"error":"MCP is not enabled for this account"}}}},"422":{"description":"The reveal nonce is missing/malformed, a selected toolset is outside the current Super Admin ceiling, or profile/authority validation failed before a bearer was issued.","headers":{"Cache-Control":{"description":"This management response can expose bearer-secret state and must never be retained.","schema":{"type":"string","enum":["no-store, no-cache"],"example":"no-store, no-cache"}}},"content":{"application/json":{"schema":{"oneOf":[{"type":"object","required":["error"],"properties":{"error":{"type":"string","enum":["invalid_idempotency_nonce"]}}},{"type":"object","required":["error"],"properties":{"error":{"type":"array","items":{"type":"string"}}}}]},"example":{"error":"invalid_idempotency_nonce"}}}},"409":{"description":"The reveal nonce was already committed. `idempotency_replay` means the same request already completed and its bearer cannot be returned again; `idempotency_conflict` means the nonce was reused with a different target or payload.","headers":{"Cache-Control":{"description":"This management response can expose bearer-secret state and must never be retained.","schema":{"type":"string","enum":["no-store, no-cache"],"example":"no-store, no-cache"}}},"content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","enum":["idempotency_replay","idempotency_conflict"]}}},"example":{"error":"idempotency_replay"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["form_nonce","name","acting_user_id"],"properties":{"form_nonce":{"type":"string","pattern":"^[a-f0-9]{64}$","description":"Required opaque 256-bit nonce for this bearer-reveal request.","example":"0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"},"name":{"type":"string","description":"Human-readable label for the connection.","example":"Claude — Support"},"acting_user_id":{"type":"integer","description":"The account member the profile executes as.","example":5},"enabled_toolsets":{"type":"array","description":"Module tags to expose. Unknown/platform-only tags are dropped; a tag outside the current Super Admin ceiling is rejected with `422` and is not saved. An empty array exposes nothing.","items":{"type":"string","enum":["Access Roles","Account","Account AgentBots","Ads","Agent Bots","Agent Capacity Policies","Agents","Assignable Agents","Assignment Policies","Audit Logs","Automation Rule","Bug Reports","Bulk Actions","CRM","CRM Item Attachments","CRM Item Checklist","CRM Item Line Items","CRM Item Notes","CRM Item Participants","CRM Items","CRM Organizations","CRM Pipelines","CRM Reports","CRM Stages","CRM Templates","CSAT Survey Responses","Calendar","Calendar Availability","Calendar Connections","Calendar Event Types","Calendar Events","Calendar Reports","Calendar Settings","Campaigns","Canned Responses","Captain","Catalog","Catalog Categories","Catalog Products","Catalog Reports","Catalog Sync Runs","Catalog Sync Sources","Catalog Variants","Channels","Commerce","Companies","Contact Inboxes","Contact Labels","Contacts","Contracts","Conversation Assignments","Conversations","Custom Attributes","Custom Filters","Custom Roles","Custom Scripts","Dashboard Apps","Engagement","Flow Builder","Follow-up","Google","Governance","Growth Distribution","Growth Social","Guided Tours","Help Center","Inboxes","Instagram","Integrations","Internal Chat","Labels","Limits","Live Reports","Macros","Maestro","Media Library","Messages","Microsoft","Notification Subscriptions","Notifications","Notion","Onboarding","Organization Memberships","Organizations","Payment Charges","Payment Connections","Payment Demo","Payment Plans","Payment Reports","Payment Subscriptions","Payments","Profile","Relationship Types","Relationships","Reports","Routing Policies","SAML","SLA Policies","Sales","Search","Summary Reports","Task Attachments","Task Checklist","Task Comments","Task Dependencies","Task Links","Task Lists","Task Reminders","Task SLA Policies","Task Templates","Task Watchers","Tasks","Team Management","Teams","TikTok","Twitter","Webhooks","WhatsApp","WhatsApp Calls","WhatsApp Hub","WhatsApp Web","WhatsApp Web Calls","Year In Review"],"example":"Conversations"}},"read_only":{"type":"boolean","description":"Hide every write/destructive tool from this profile.","example":false},"chatgpt_compat":{"type":"boolean","description":"Also expose the deep-research aliases `search` and `fetch` that the ChatGPT connector requires by name. They describe only what this profile already exposes and grant no extra access, but they consume two slots of the listing cap. Ignored where the installation does not support it.","example":false},"tool_cap":{"type":["integer","null"],"description":"Optional per-profile override of the listing cap.","example":null}}},"example":{"form_nonce":"0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef","name":"Claude — Support","acting_user_id":5,"enabled_toolsets":["Conversations","Contacts"],"read_only":false,"chatgpt_compat":false,"tool_cap":null}}}}}},"/api/v1/accounts/{account_id}/mcp/profiles/{id}":{"patch":{"tags":["Mcp"],"operationId":"auto_patch_api_v1_accounts_account_id_mcp_profiles_id","summary":"Update an MCP access profile","description":"Updates a profile. Admin-only. Only the fields sent are changed. Changing `acting_user_id` atomically invalidates the old static bearer and reveals a replacement token exactly once; all other updates leave the bearer untouched (use rotate_token for an explicit rotation). Unknown toolset tags are dropped on write; tags outside the current Super Admin ceiling are rejected with `422` and are not saved. `form_nonce` is required only if `acting_user_id` really changes and reveals a replacement bearer.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The updated profile.","headers":{"Cache-Control":{"description":"This management response can expose bearer-secret state and must never be retained.","schema":{"type":"string","enum":["no-store, no-cache"],"example":"no-store, no-cache"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"profile":{"type":"object","properties":{"id":{"type":"integer","description":"Profile id.","example":12},"name":{"type":"string","description":"Human-readable label for the connection.","example":"Claude — Support"},"public_id":{"type":"string","description":"The non-secret slug that appears in the connection URL. Unique within the account.","example":"a1b2c3d4e5f6g7h8i9j0"},"acting_user_id":{"type":["integer","null"],"description":"The account member this profile executes as (null if the user was deleted).","example":5},"acting_user":{"type":["object","null"],"description":"The acting user, or null if it was deleted. `available` is false when the user is no longer a member of the account (the profile is then disabled at auth time).","properties":{"id":{"type":"integer","description":"User id.","example":5},"name":{"type":"string","description":"User display name.","example":"Alice Costa"},"available":{"type":"boolean","description":"Whether the user is still a member of the account.","example":true}}},"enabled_toolsets":{"type":"array","description":"The module tags this profile selected (its stored selection; the super-admin ceiling is applied at runtime).","items":{"type":"string","enum":["Access Roles","Account","Account AgentBots","Ads","Agent Bots","Agent Capacity Policies","Agents","Assignable Agents","Assignment Policies","Audit Logs","Automation Rule","Bug Reports","Bulk Actions","CRM","CRM Item Attachments","CRM Item Checklist","CRM Item Line Items","CRM Item Notes","CRM Item Participants","CRM Items","CRM Organizations","CRM Pipelines","CRM Reports","CRM Stages","CRM Templates","CSAT Survey Responses","Calendar","Calendar Availability","Calendar Connections","Calendar Event Types","Calendar Events","Calendar Reports","Calendar Settings","Campaigns","Canned Responses","Captain","Catalog","Catalog Categories","Catalog Products","Catalog Reports","Catalog Sync Runs","Catalog Sync Sources","Catalog Variants","Channels","Commerce","Companies","Contact Inboxes","Contact Labels","Contacts","Contracts","Conversation Assignments","Conversations","Custom Attributes","Custom Filters","Custom Roles","Custom Scripts","Dashboard Apps","Engagement","Flow Builder","Follow-up","Google","Governance","Growth Distribution","Growth Social","Guided Tours","Help Center","Inboxes","Instagram","Integrations","Internal Chat","Labels","Limits","Live Reports","Macros","Maestro","Media Library","Messages","Microsoft","Notification Subscriptions","Notifications","Notion","Onboarding","Organization Memberships","Organizations","Payment Charges","Payment Connections","Payment Demo","Payment Plans","Payment Reports","Payment Subscriptions","Payments","Profile","Relationship Types","Relationships","Reports","Routing Policies","SAML","SLA Policies","Sales","Search","Summary Reports","Task Attachments","Task Checklist","Task Comments","Task Dependencies","Task Links","Task Lists","Task Reminders","Task SLA Policies","Task Templates","Task Watchers","Tasks","Team Management","Teams","TikTok","Twitter","Webhooks","WhatsApp","WhatsApp Calls","WhatsApp Hub","WhatsApp Web","WhatsApp Web Calls","Year In Review"],"example":"Conversations"}},"read_only":{"type":"boolean","description":"When true, every write/destructive tool is hidden from this profile's catalog.","example":false},"enabled":{"type":"boolean","description":"Whether the profile is active. A disabled profile authenticates with 401.","example":true},"tool_cap":{"type":["integer","null"],"description":"Per-profile override of the listing cap (null uses the installation-wide cap).","example":null},"token_last_four":{"type":["string","null"],"description":"The last four characters of the bearer secret, for recognition. The full secret is shown only once, on create/rotate.","example":"ab12"},"last_used_at":{"type":["string","null"],"format":"date-time","description":"When the connection was last used (throttled heartbeat), or null if never.","example":"2026-07-16T12:04:11Z"},"endpoint_url":{"type":"string","description":"Canonical public static bearer MCP URL for this profile. It is omitted when the installation has no safe configured public HTTPS origin; clients must never infer it from a request Host header.","example":"https://app.example.com/api/v1/accounts/1/mcp/c/a1b2c3d4e5f6g7h8i9j0"},"oauth_endpoint_url":{"type":"string","format":"uri","description":"The separate, non-secret OAuth MCP resource URL when native OAuth is enabled with a canonical public issuer. It is omitted otherwise and never accepts the static profile bearer secret.","example":"https://app.example.com/api/v1/accounts/1/mcp/oauth/c/a1b2c3d4e5f6g7h8i9j0"},"tool_count":{"type":"integer","description":"Tools actually exposed right now (ceiling ∩ selection, read-only filter, then cap).","example":42},"selected_tool_count":{"type":"integer","description":"What the selection resolves to BEFORE the cap. When greater than `tool_count`, the cap truncated the list.","example":42},"truncated":{"type":"boolean","description":"Whether the cap truncated the selection (`selected_tool_count` \u003e `tool_count`).","example":false},"chatgpt_compat":{"type":"boolean","description":"Whether this profile also exposes the deep-research aliases `search` and `fetch` that the ChatGPT connector requires by name. They describe only what the profile already exposes and grant no extra access, but they consume two slots of the listing cap.","example":false}}},"token":{"type":"string","description":"A replacement static bearer secret, present exactly once only when `acting_user_id` changed. Store it securely before closing the response; it is never returned by a later read.","example":"mcp_example_reassignment_secret"}}},"example":{"profile":{"id":12,"name":"Claude — Support","public_id":"a1b2c3d4e5f6g7h8i9j0","acting_user_id":5,"acting_user":{"id":5,"name":"Alice Costa","available":true},"enabled_toolsets":["Conversations","Contacts"],"read_only":false,"enabled":true,"tool_cap":null,"token_last_four":"ab12","last_used_at":"2026-07-16T12:04:11Z","endpoint_url":"https://app.example.com/api/v1/accounts/1/mcp/c/a1b2c3d4e5f6g7h8i9j0","oauth_endpoint_url":"https://app.example.com/api/v1/accounts/1/mcp/oauth/c/a1b2c3d4e5f6g7h8i9j0","tool_count":42,"selected_tool_count":42,"truncated":false,"chatgpt_compat":false},"token":"mcp_example_reassignment_secret"}}}},"401":{"description":"Missing or invalid access token, or the caller is not an account administrator.","headers":{"Cache-Control":{"description":"This management response can expose bearer-secret state and must never be retained.","schema":{"type":"string","enum":["no-store, no-cache"],"example":"no-store, no-cache"}}}},"404":{"description":"MCP is not enabled for this account, or disabled for the whole installation. The feature is dark-shipped, so an unavailable surface is indistinguishable from a missing route.","headers":{"Cache-Control":{"description":"This management response can expose bearer-secret state and must never be retained.","schema":{"type":"string","enum":["no-store, no-cache"],"example":"no-store, no-cache"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Why the MCP surface is unavailable.","example":"MCP is not enabled for this account"}}},"example":{"error":"MCP is not enabled for this account"}}}},"422":{"description":"The reveal nonce is missing/malformed for a real acting-user reassignment, a selected toolset is outside the current Super Admin ceiling, or profile/authority validation failed before a replacement bearer was issued.","headers":{"Cache-Control":{"description":"This management response can expose bearer-secret state and must never be retained.","schema":{"type":"string","enum":["no-store, no-cache"],"example":"no-store, no-cache"}}},"content":{"application/json":{"schema":{"oneOf":[{"type":"object","required":["error"],"properties":{"error":{"type":"string","enum":["invalid_idempotency_nonce"]}}},{"type":"object","required":["error"],"properties":{"error":{"type":"array","items":{"type":"string"}}}}]},"example":{"error":"invalid_idempotency_nonce"}}}},"409":{"description":"A bearer-producing acting-user reassignment reused a committed nonce. `idempotency_replay` is a completed same-payload request with no recoverable bearer; `idempotency_conflict` is a changed request.","headers":{"Cache-Control":{"description":"This management response can expose bearer-secret state and must never be retained.","schema":{"type":"string","enum":["no-store, no-cache"],"example":"no-store, no-cache"}}},"content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","enum":["idempotency_replay","idempotency_conflict"]}}},"example":{"error":"idempotency_conflict"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"form_nonce":{"type":"string","pattern":"^[a-f0-9]{64}$","description":"Required only for a real acting-user reassignment that reveals a bearer.","example":"0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"},"name":{"type":"string","description":"New label.","example":"Claude — Support (read only)"},"acting_user_id":{"type":"integer","description":"New acting user (must be an account member).","example":8},"enabled_toolsets":{"type":"array","description":"New selection. Unknown/platform-only tags are dropped; a tag outside the current Super Admin ceiling is rejected with `422` and is not saved.","items":{"type":"string","enum":["Access Roles","Account","Account AgentBots","Ads","Agent Bots","Agent Capacity Policies","Agents","Assignable Agents","Assignment Policies","Audit Logs","Automation Rule","Bug Reports","Bulk Actions","CRM","CRM Item Attachments","CRM Item Checklist","CRM Item Line Items","CRM Item Notes","CRM Item Participants","CRM Items","CRM Organizations","CRM Pipelines","CRM Reports","CRM Stages","CRM Templates","CSAT Survey Responses","Calendar","Calendar Availability","Calendar Connections","Calendar Event Types","Calendar Events","Calendar Reports","Calendar Settings","Campaigns","Canned Responses","Captain","Catalog","Catalog Categories","Catalog Products","Catalog Reports","Catalog Sync Runs","Catalog Sync Sources","Catalog Variants","Channels","Commerce","Companies","Contact Inboxes","Contact Labels","Contacts","Contracts","Conversation Assignments","Conversations","Custom Attributes","Custom Filters","Custom Roles","Custom Scripts","Dashboard Apps","Engagement","Flow Builder","Follow-up","Google","Governance","Growth Distribution","Growth Social","Guided Tours","Help Center","Inboxes","Instagram","Integrations","Internal Chat","Labels","Limits","Live Reports","Macros","Maestro","Media Library","Messages","Microsoft","Notification Subscriptions","Notifications","Notion","Onboarding","Organization Memberships","Organizations","Payment Charges","Payment Connections","Payment Demo","Payment Plans","Payment Reports","Payment Subscriptions","Payments","Profile","Relationship Types","Relationships","Reports","Routing Policies","SAML","SLA Policies","Sales","Search","Summary Reports","Task Attachments","Task Checklist","Task Comments","Task Dependencies","Task Links","Task Lists","Task Reminders","Task SLA Policies","Task Templates","Task Watchers","Tasks","Team Management","Teams","TikTok","Twitter","Webhooks","WhatsApp","WhatsApp Calls","WhatsApp Hub","WhatsApp Web","WhatsApp Web Calls","Year In Review"],"example":"Conversations"}},"read_only":{"type":"boolean","description":"Hide every write/destructive tool.","example":true},"chatgpt_compat":{"type":"boolean","description":"Also expose the deep-research aliases `search` and `fetch` that the ChatGPT connector requires by name. They describe only what this profile already exposes and grant no extra access, but they consume two slots of the listing cap. Ignored where the installation does not support it.","example":false},"enabled":{"type":"boolean","description":"Enable/disable the profile (a disabled profile authenticates 401).","example":true},"tool_cap":{"type":["integer","null"],"description":"Per-profile listing cap override.","example":null}}},"example":{"name":"Claude — Support (read only)","read_only":true,"form_nonce":"0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef","acting_user_id":8,"enabled_toolsets":["Conversations"],"chatgpt_compat":false,"enabled":true,"tool_cap":null}}}}},"put":{"tags":["Mcp"],"operationId":"auto_put_api_v1_accounts_account_id_mcp_profiles_id","summary":"Update an MCP access profile","description":"Updates a profile. Admin-only. Only the fields sent are changed. Changing `acting_user_id` atomically invalidates the old static bearer and reveals a replacement token exactly once; all other updates leave the bearer untouched (use rotate_token for an explicit rotation). Unknown toolset tags are dropped on write; tags outside the current Super Admin ceiling are rejected with `422` and are not saved. `form_nonce` is required only if `acting_user_id` really changes and reveals a replacement bearer.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The updated profile.","headers":{"Cache-Control":{"description":"This management response can expose bearer-secret state and must never be retained.","schema":{"type":"string","enum":["no-store, no-cache"],"example":"no-store, no-cache"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"profile":{"type":"object","properties":{"id":{"type":"integer","description":"Profile id.","example":12},"name":{"type":"string","description":"Human-readable label for the connection.","example":"Claude — Support"},"public_id":{"type":"string","description":"The non-secret slug that appears in the connection URL. Unique within the account.","example":"a1b2c3d4e5f6g7h8i9j0"},"acting_user_id":{"type":["integer","null"],"description":"The account member this profile executes as (null if the user was deleted).","example":5},"acting_user":{"type":["object","null"],"description":"The acting user, or null if it was deleted. `available` is false when the user is no longer a member of the account (the profile is then disabled at auth time).","properties":{"id":{"type":"integer","description":"User id.","example":5},"name":{"type":"string","description":"User display name.","example":"Alice Costa"},"available":{"type":"boolean","description":"Whether the user is still a member of the account.","example":true}}},"enabled_toolsets":{"type":"array","description":"The module tags this profile selected (its stored selection; the super-admin ceiling is applied at runtime).","items":{"type":"string","enum":["Access Roles","Account","Account AgentBots","Ads","Agent Bots","Agent Capacity Policies","Agents","Assignable Agents","Assignment Policies","Audit Logs","Automation Rule","Bug Reports","Bulk Actions","CRM","CRM Item Attachments","CRM Item Checklist","CRM Item Line Items","CRM Item Notes","CRM Item Participants","CRM Items","CRM Organizations","CRM Pipelines","CRM Reports","CRM Stages","CRM Templates","CSAT Survey Responses","Calendar","Calendar Availability","Calendar Connections","Calendar Event Types","Calendar Events","Calendar Reports","Calendar Settings","Campaigns","Canned Responses","Captain","Catalog","Catalog Categories","Catalog Products","Catalog Reports","Catalog Sync Runs","Catalog Sync Sources","Catalog Variants","Channels","Commerce","Companies","Contact Inboxes","Contact Labels","Contacts","Contracts","Conversation Assignments","Conversations","Custom Attributes","Custom Filters","Custom Roles","Custom Scripts","Dashboard Apps","Engagement","Flow Builder","Follow-up","Google","Governance","Growth Distribution","Growth Social","Guided Tours","Help Center","Inboxes","Instagram","Integrations","Internal Chat","Labels","Limits","Live Reports","Macros","Maestro","Media Library","Messages","Microsoft","Notification Subscriptions","Notifications","Notion","Onboarding","Organization Memberships","Organizations","Payment Charges","Payment Connections","Payment Demo","Payment Plans","Payment Reports","Payment Subscriptions","Payments","Profile","Relationship Types","Relationships","Reports","Routing Policies","SAML","SLA Policies","Sales","Search","Summary Reports","Task Attachments","Task Checklist","Task Comments","Task Dependencies","Task Links","Task Lists","Task Reminders","Task SLA Policies","Task Templates","Task Watchers","Tasks","Team Management","Teams","TikTok","Twitter","Webhooks","WhatsApp","WhatsApp Calls","WhatsApp Hub","WhatsApp Web","WhatsApp Web Calls","Year In Review"],"example":"Conversations"}},"read_only":{"type":"boolean","description":"When true, every write/destructive tool is hidden from this profile's catalog.","example":false},"enabled":{"type":"boolean","description":"Whether the profile is active. A disabled profile authenticates with 401.","example":true},"tool_cap":{"type":["integer","null"],"description":"Per-profile override of the listing cap (null uses the installation-wide cap).","example":null},"token_last_four":{"type":["string","null"],"description":"The last four characters of the bearer secret, for recognition. The full secret is shown only once, on create/rotate.","example":"ab12"},"last_used_at":{"type":["string","null"],"format":"date-time","description":"When the connection was last used (throttled heartbeat), or null if never.","example":"2026-07-16T12:04:11Z"},"endpoint_url":{"type":"string","description":"Canonical public static bearer MCP URL for this profile. It is omitted when the installation has no safe configured public HTTPS origin; clients must never infer it from a request Host header.","example":"https://app.example.com/api/v1/accounts/1/mcp/c/a1b2c3d4e5f6g7h8i9j0"},"oauth_endpoint_url":{"type":"string","format":"uri","description":"The separate, non-secret OAuth MCP resource URL when native OAuth is enabled with a canonical public issuer. It is omitted otherwise and never accepts the static profile bearer secret.","example":"https://app.example.com/api/v1/accounts/1/mcp/oauth/c/a1b2c3d4e5f6g7h8i9j0"},"tool_count":{"type":"integer","description":"Tools actually exposed right now (ceiling ∩ selection, read-only filter, then cap).","example":42},"selected_tool_count":{"type":"integer","description":"What the selection resolves to BEFORE the cap. When greater than `tool_count`, the cap truncated the list.","example":42},"truncated":{"type":"boolean","description":"Whether the cap truncated the selection (`selected_tool_count` \u003e `tool_count`).","example":false},"chatgpt_compat":{"type":"boolean","description":"Whether this profile also exposes the deep-research aliases `search` and `fetch` that the ChatGPT connector requires by name. They describe only what the profile already exposes and grant no extra access, but they consume two slots of the listing cap.","example":false}}},"token":{"type":"string","description":"A replacement static bearer secret, present exactly once only when `acting_user_id` changed. Store it securely before closing the response; it is never returned by a later read.","example":"mcp_example_reassignment_secret"}}},"example":{"profile":{"id":12,"name":"Claude — Support","public_id":"a1b2c3d4e5f6g7h8i9j0","acting_user_id":5,"acting_user":{"id":5,"name":"Alice Costa","available":true},"enabled_toolsets":["Conversations","Contacts"],"read_only":false,"enabled":true,"tool_cap":null,"token_last_four":"ab12","last_used_at":"2026-07-16T12:04:11Z","endpoint_url":"https://app.example.com/api/v1/accounts/1/mcp/c/a1b2c3d4e5f6g7h8i9j0","oauth_endpoint_url":"https://app.example.com/api/v1/accounts/1/mcp/oauth/c/a1b2c3d4e5f6g7h8i9j0","tool_count":42,"selected_tool_count":42,"truncated":false,"chatgpt_compat":false},"token":"mcp_example_reassignment_secret"}}}},"401":{"description":"Missing or invalid access token, or the caller is not an account administrator.","headers":{"Cache-Control":{"description":"This management response can expose bearer-secret state and must never be retained.","schema":{"type":"string","enum":["no-store, no-cache"],"example":"no-store, no-cache"}}}},"404":{"description":"MCP is not enabled for this account, or disabled for the whole installation. The feature is dark-shipped, so an unavailable surface is indistinguishable from a missing route.","headers":{"Cache-Control":{"description":"This management response can expose bearer-secret state and must never be retained.","schema":{"type":"string","enum":["no-store, no-cache"],"example":"no-store, no-cache"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Why the MCP surface is unavailable.","example":"MCP is not enabled for this account"}}},"example":{"error":"MCP is not enabled for this account"}}}},"422":{"description":"The reveal nonce is missing/malformed for a real acting-user reassignment, a selected toolset is outside the current Super Admin ceiling, or profile/authority validation failed before a replacement bearer was issued.","headers":{"Cache-Control":{"description":"This management response can expose bearer-secret state and must never be retained.","schema":{"type":"string","enum":["no-store, no-cache"],"example":"no-store, no-cache"}}},"content":{"application/json":{"schema":{"oneOf":[{"type":"object","required":["error"],"properties":{"error":{"type":"string","enum":["invalid_idempotency_nonce"]}}},{"type":"object","required":["error"],"properties":{"error":{"type":"array","items":{"type":"string"}}}}]},"example":{"error":"invalid_idempotency_nonce"}}}},"409":{"description":"A bearer-producing acting-user reassignment reused a committed nonce. `idempotency_replay` is a completed same-payload request with no recoverable bearer; `idempotency_conflict` is a changed request.","headers":{"Cache-Control":{"description":"This management response can expose bearer-secret state and must never be retained.","schema":{"type":"string","enum":["no-store, no-cache"],"example":"no-store, no-cache"}}},"content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","enum":["idempotency_replay","idempotency_conflict"]}}},"example":{"error":"idempotency_conflict"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"form_nonce":{"type":"string","pattern":"^[a-f0-9]{64}$","description":"Required only for a real acting-user reassignment that reveals a bearer.","example":"0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"},"name":{"type":"string","description":"New label.","example":"Claude — Support (read only)"},"acting_user_id":{"type":"integer","description":"New acting user (must be an account member).","example":8},"enabled_toolsets":{"type":"array","description":"New selection. Unknown/platform-only tags are dropped; a tag outside the current Super Admin ceiling is rejected with `422` and is not saved.","items":{"type":"string","enum":["Access Roles","Account","Account AgentBots","Ads","Agent Bots","Agent Capacity Policies","Agents","Assignable Agents","Assignment Policies","Audit Logs","Automation Rule","Bug Reports","Bulk Actions","CRM","CRM Item Attachments","CRM Item Checklist","CRM Item Line Items","CRM Item Notes","CRM Item Participants","CRM Items","CRM Organizations","CRM Pipelines","CRM Reports","CRM Stages","CRM Templates","CSAT Survey Responses","Calendar","Calendar Availability","Calendar Connections","Calendar Event Types","Calendar Events","Calendar Reports","Calendar Settings","Campaigns","Canned Responses","Captain","Catalog","Catalog Categories","Catalog Products","Catalog Reports","Catalog Sync Runs","Catalog Sync Sources","Catalog Variants","Channels","Commerce","Companies","Contact Inboxes","Contact Labels","Contacts","Contracts","Conversation Assignments","Conversations","Custom Attributes","Custom Filters","Custom Roles","Custom Scripts","Dashboard Apps","Engagement","Flow Builder","Follow-up","Google","Governance","Growth Distribution","Growth Social","Guided Tours","Help Center","Inboxes","Instagram","Integrations","Internal Chat","Labels","Limits","Live Reports","Macros","Maestro","Media Library","Messages","Microsoft","Notification Subscriptions","Notifications","Notion","Onboarding","Organization Memberships","Organizations","Payment Charges","Payment Connections","Payment Demo","Payment Plans","Payment Reports","Payment Subscriptions","Payments","Profile","Relationship Types","Relationships","Reports","Routing Policies","SAML","SLA Policies","Sales","Search","Summary Reports","Task Attachments","Task Checklist","Task Comments","Task Dependencies","Task Links","Task Lists","Task Reminders","Task SLA Policies","Task Templates","Task Watchers","Tasks","Team Management","Teams","TikTok","Twitter","Webhooks","WhatsApp","WhatsApp Calls","WhatsApp Hub","WhatsApp Web","WhatsApp Web Calls","Year In Review"],"example":"Conversations"}},"read_only":{"type":"boolean","description":"Hide every write/destructive tool.","example":true},"chatgpt_compat":{"type":"boolean","description":"Also expose the deep-research aliases `search` and `fetch` that the ChatGPT connector requires by name. They describe only what this profile already exposes and grant no extra access, but they consume two slots of the listing cap. Ignored where the installation does not support it.","example":false},"enabled":{"type":"boolean","description":"Enable/disable the profile (a disabled profile authenticates 401).","example":true},"tool_cap":{"type":["integer","null"],"description":"Per-profile listing cap override.","example":null}}},"example":{"name":"Claude — Support (read only)","read_only":true,"form_nonce":"0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef","acting_user_id":8,"enabled_toolsets":["Conversations"],"chatgpt_compat":false,"enabled":true,"tool_cap":null}}}}},"delete":{"tags":["Mcp"],"operationId":"auto_delete_api_v1_accounts_account_id_mcp_profiles_id","summary":"Delete an MCP access profile","description":"Deletes a profile. Admin-only. Its connection URL immediately stops working (404/401).","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The profile was deleted.","headers":{"Cache-Control":{"description":"This management response can expose bearer-secret state and must never be retained.","schema":{"type":"string","enum":["no-store, no-cache"],"example":"no-store, no-cache"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Always true on success.","example":true}}},"example":{"success":true}}}},"401":{"description":"Missing or invalid access token, or the caller is not an account administrator.","headers":{"Cache-Control":{"description":"This management response can expose bearer-secret state and must never be retained.","schema":{"type":"string","enum":["no-store, no-cache"],"example":"no-store, no-cache"}}}},"404":{"description":"MCP is not enabled for this account, or disabled for the whole installation. The feature is dark-shipped, so an unavailable surface is indistinguishable from a missing route.","headers":{"Cache-Control":{"description":"This management response can expose bearer-secret state and must never be retained.","schema":{"type":"string","enum":["no-store, no-cache"],"example":"no-store, no-cache"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Why the MCP surface is unavailable.","example":"MCP is not enabled for this account"}}},"example":{"error":"MCP is not enabled for this account"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/onboarding/help_center_generation":{"get":{"tags":["Onboarding"],"operationId":"auto_get_api_v1_accounts_account_id_onboarding_help_center_generation","summary":"Help center generation onboardings","description":"Performs the help center generation operation on the targeted onboarding resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"generation_id":{"type":["integer","null"]},"state":{"type":["string","null"]},"articles_count":{"type":"integer","example":0},"categories_count":{"type":"integer","example":0}},"required":["generation_id","state","articles_count","categories_count"],"additionalProperties":false},"example":{"generation_id":1,"state":"active","articles_count":0,"categories_count":0}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/onboarding":{"patch":{"tags":["Onboarding"],"operationId":"auto_patch_api_v1_accounts_account_id_onboarding","summary":"Update onboarding account details","description":"Assigns onboarding account attributes (name/locale) and custom attributes (industry, company size, timezone, referral source, user role, website), clears the onboarding_step when finalizing account details, and returns the account object. Admin-only.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The updated account.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer","example":1},"name":{"type":"string","example":"Acme Support"},"locale":{"type":"string","example":"pt_BR"},"status":{"type":"string","example":"active","enum":["active","suspended"],"description":"Account status."},"support_email":{"type":["string","null"],"example":"support@acme.example.com"},"domain":{"type":["string","null"],"example":"acme.example.com"},"settings":{"type":"object","additionalProperties":true,"example":{"auto_resolve_after":null},"description":"Settings map for this record; the key set depends on the settings scope."},"features":{"type":"object","additionalProperties":{"type":"boolean"},"description":"Enabled feature flags map.","example":{"inbound_emails":true,"channel_website":true}},"custom_attributes":{"type":"object","additionalProperties":true,"example":{"industry":"E-commerce","company_size":"11-50","onboarding_step":"account_details"},"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"session_analytics":{"type":"object","additionalProperties":true,"description":"Effective Session Analytics config (client-safe public tags only).","example":{"enabled":false}},"cache_keys":{"type":"object","additionalProperties":true,"example":{"label":1737023400,"inbox":1737023400},"description":"Per-collection cache-key fingerprints used for client cache invalidation."},"created_at":{"type":"string","format":"date-time","example":"2026-01-15T10:30:00.000Z"}}},"example":{"id":1,"name":"Acme Support","locale":"pt_BR","status":"active","support_email":"support@acme.example.com","domain":"acme.example.com","settings":{"auto_resolve_after":null},"features":{"inbound_emails":true,"channel_website":true},"custom_attributes":{"industry":"E-commerce","company_size":"11-50","onboarding_step":"account_details"},"session_analytics":{"enabled":false},"cache_keys":{"label":1737023400,"inbox":1737023400},"created_at":"2026-01-15T10:30:00.000Z"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","example":"Acme Support"},"locale":{"type":"string","example":"pt_BR"},"industry":{"type":"string","example":"E-commerce"},"company_size":{"type":"string","example":"11-50"},"timezone":{"type":"string","example":"America/Sao_Paulo"},"referral_source":{"type":"string","example":"Google"},"user_role":{"type":"string","example":"Founder"},"website":{"type":"string","example":"https://acme.example.com"}}},"example":{"name":"Acme Support","locale":"pt_BR","industry":"E-commerce","company_size":"11-50","timezone":"America/Sao_Paulo","referral_source":"Google","user_role":"Founder","website":"https://acme.example.com"}}}}},"put":{"tags":["Onboarding"],"operationId":"auto_put_api_v1_accounts_account_id_onboarding","summary":"Update onboarding account details","description":"Assigns onboarding account attributes (name/locale) and custom attributes (industry, company size, timezone, referral source, user role, website), clears the onboarding_step when finalizing account details, and returns the account object. Admin-only.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The updated account.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer","example":1},"name":{"type":"string","example":"Acme Support"},"locale":{"type":"string","example":"pt_BR"},"status":{"type":"string","example":"active","enum":["active","suspended"],"description":"Account status."},"support_email":{"type":["string","null"],"example":"support@acme.example.com"},"domain":{"type":["string","null"],"example":"acme.example.com"},"settings":{"type":"object","additionalProperties":true,"example":{"auto_resolve_after":null},"description":"Settings map for this record; the key set depends on the settings scope."},"features":{"type":"object","additionalProperties":{"type":"boolean"},"description":"Enabled feature flags map.","example":{"inbound_emails":true,"channel_website":true}},"custom_attributes":{"type":"object","additionalProperties":true,"example":{"industry":"E-commerce","company_size":"11-50","onboarding_step":"account_details"},"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"session_analytics":{"type":"object","additionalProperties":true,"description":"Effective Session Analytics config (client-safe public tags only).","example":{"enabled":false}},"cache_keys":{"type":"object","additionalProperties":true,"example":{"label":1737023400,"inbox":1737023400},"description":"Per-collection cache-key fingerprints used for client cache invalidation."},"created_at":{"type":"string","format":"date-time","example":"2026-01-15T10:30:00.000Z"}}},"example":{"id":1,"name":"Acme Support","locale":"pt_BR","status":"active","support_email":"support@acme.example.com","domain":"acme.example.com","settings":{"auto_resolve_after":null},"features":{"inbound_emails":true,"channel_website":true},"custom_attributes":{"industry":"E-commerce","company_size":"11-50","onboarding_step":"account_details"},"session_analytics":{"enabled":false},"cache_keys":{"label":1737023400,"inbox":1737023400},"created_at":"2026-01-15T10:30:00.000Z"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","example":"Acme Support"},"locale":{"type":"string","example":"pt_BR"},"industry":{"type":"string","example":"E-commerce"},"company_size":{"type":"string","example":"11-50"},"timezone":{"type":"string","example":"America/Sao_Paulo"},"referral_source":{"type":"string","example":"Google"},"user_role":{"type":"string","example":"Founder"},"website":{"type":"string","example":"https://acme.example.com"}}},"example":{"name":"Acme Support","locale":"pt_BR","industry":"E-commerce","company_size":"11-50","timezone":"America/Sao_Paulo","referral_source":"Google","user_role":"Founder","website":"https://acme.example.com"}}}}}},"/api/v1/accounts/{account_id}/contextual_help/articles/{article_key}":{"get":{"tags":["Contextual Help"],"operationId":"auto_get_api_v1_accounts_account_id_contextual_help_articles_article_key","summary":"Resolve an account-native contextual Help Center article","description":"Resolves an approved public, published Help Center article key for the authenticated account. The response is bound to the account's Help Center seeder stamp and returns the exact portal and article slug currently available to that account. Unknown keys, unsupported locales, missing or stale portal state, draft articles, and operator-only articles all return the same not-found response.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Account-scoped contextual article URL.","headers":{"Cache-Control":{"description":"Prevents shared or private caches from retaining account publication state.","schema":{"type":"string","enum":["private, no-store"]},"example":"private, no-store"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["account_id","portal_slug","article_key","locale","url"],"properties":{"account_id":{"type":"integer","example":42},"portal_slug":{"type":"string","example":"ajuda-42"},"article_key":{"type":"string","example":"automation-flows-bots-e-captain"},"locale":{"type":"string","enum":["pt_BR","en","es"],"example":"pt_BR"},"url":{"type":"string","example":"/hc/ajuda-42/articles/ajuda-42-automation-flows-bots-e-captain-pt-br"}}},"example":{"account_id":42,"portal_slug":"ajuda-42","article_key":"automation-flows-bots-e-captain","locale":"pt_BR","url":"/hc/ajuda-42/articles/ajuda-42-automation-flows-bots-e-captain-pt-br"}}}},"401":{"description":"Authentication is missing or the caller is not a member of the requested account.","headers":{"Cache-Control":{"description":"Prevents caches from retaining an account authorization result.","schema":{"type":"string","enum":["private, no-store"]},"example":"private, no-store"}}},"404":{"description":"No eligible public article is available for this key and locale in the requested account.","headers":{"Cache-Control":{"description":"Prevents caches from retaining an account, portal, or article existence result.","schema":{"type":"string","enum":["private, no-store"]},"example":"private, no-store"}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"article_key","in":"path","required":true,"schema":{"type":"string"}},{"name":"locale","in":"query","required":true,"description":"Help Center locale to resolve.","schema":{"type":"string","enum":["pt_BR","en","es"]},"example":"pt_BR"}]}},"/api/v1/accounts/{account_id}/product_tour_media":{"get":{"tags":["Guided Tours"],"operationId":"auto_get_api_v1_accounts_account_id_product_tour_media","summary":"List product tour media","description":"Returns the list of product tour media visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Map of enabled product-tour videos keyed by media key, filtered by the authenticated account's enabled modules, the user's effective permissions and step restrictions. Returns an empty map when guided tours are disabled for the account. Video language falls back deterministically when the requested language is unavailable.","content":{"application/json":{"schema":{"type":"object","description":"Keys are tour media keys (e.g. dashboard-overview); values describe the video.","additionalProperties":{"type":"object","required":["provider","video_id","title","locale"],"properties":{"provider":{"type":"string","enum":["youtube"],"description":"Video hosting provider (the dashboard embeds YouTube players).","example":"youtube"},"video_id":{"type":"string","example":"dQw4w9WgXcQ"},"title":{"type":"string","example":"Getting started with the dashboard"},"locale":{"type":"string","enum":["en","pt_BR","es"],"description":"Language of the selected video after applying the safe fallback order.","example":"pt_BR"}}}},"example":{"payments.charges":{"provider":"youtube","video_id":"dQw4w9WgXcQ","title":"Payments — Charges","locale":"pt_BR"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"locale","in":"query","required":false,"description":"Canonical dashboard language requested for the videos. Omit the parameter to use English.","schema":{"type":"string","enum":["en","pt_BR","es"],"default":"en"},"example":"pt_BR"}]}},"/api/v1/accounts/{account_id}/agents/bulk_create":{"post":{"tags":["Agents"],"operationId":"auto_post_api_v1_accounts_account_id_agents_bulk_create","summary":"Invite several agents at once","description":"Creates and invites one agent per address supplied, deriving each name from the local part of the address, and then clears the onboarding step of the account — this is the invite step of onboarding, meant to run once. Addresses that cannot be turned into an agent (already a member, invalid address) are SKIPPED silently so one bad entry never rejects the batch. Because of that the response carries NO body and reports no per-address outcome: list the agents afterwards to confirm who was created.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Batch processed and the onboarding step cleared. Empty body — invalid entries were skipped."},"401":{"description":"Unauthorized"},"404":{"description":"No account matches `account_id`."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["emails"],"properties":{"emails":{"type":"array","description":"Addresses to invite. Each becomes an agent of the account with an invitation e-mail.","items":{"type":"string","format":"email"}}}},"example":{"emails":["alice@example.com","bob@example.com"]}}}}}},"/api/v1/accounts/{account_id}/captain/preferences":{"get":{"tags":["Captain"],"operationId":"auto_get_api_v1_accounts_account_id_captain_preferences","summary":"Get preferences","description":"Returns the preference identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"providers":{"type":"string"},"models":{"type":"string"},"features":{"type":"string"}},"required":["providers","models","features"],"additionalProperties":false},"example":{"providers":"sample providers","models":"sample models","features":"sample features"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]},"patch":{"tags":["Captain"],"operationId":"auto_patch_api_v1_accounts_account_id_captain_preferences","summary":"Update Captain preferences","description":"Merges the supplied captain_models (per-feature model selection) and captain_features (per-feature on/off) into the account and returns the resolved providers/models/features payload. Admin-only.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"providers":{"type":"string"},"models":{"type":"string"},"features":{"type":"string"}},"required":["providers","models","features"],"additionalProperties":false},"example":{"providers":"sample providers","models":"sample models","features":"sample features"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"captain_models":{"type":"object","description":"Selected model id per feature (merged into existing).","properties":{"editor":{"type":"string","example":"openai:gpt-5.5"},"assistant":{"type":"string","example":"openai:gpt-5.5"},"copilot":{"type":"string","example":"openai:gpt-5.5-mini"},"label_suggestion":{"type":"string","example":"openai:gpt-5.5-mini"},"audio_transcription":{"type":"string","example":"openai:whisper-1"},"help_center_search":{"type":"string","example":"openai:gpt-5.5-mini"}}},"captain_features":{"type":"object","description":"Per-feature enablement flags (merged into existing).","properties":{"editor":{"type":"boolean","example":true},"assistant":{"type":"boolean","example":true},"copilot":{"type":"boolean","example":true},"label_suggestion":{"type":"boolean","example":false},"audio_transcription":{"type":"boolean","example":false},"help_center_search":{"type":"boolean","example":true}}}}},"example":{"captain_models":{"editor":"openai:gpt-5.5","assistant":"openai:gpt-5.5","copilot":"openai:gpt-5.5-mini","label_suggestion":"openai:gpt-5.5-mini","audio_transcription":"openai:whisper-1","help_center_search":"openai:gpt-5.5-mini"},"captain_features":{"editor":true,"assistant":true,"copilot":true,"label_suggestion":false,"audio_transcription":false,"help_center_search":true}}}}}},"put":{"tags":["Captain"],"operationId":"auto_put_api_v1_accounts_account_id_captain_preferences","summary":"Update Captain preferences","description":"Merges the supplied captain_models (per-feature model selection) and captain_features (per-feature on/off) into the account and returns the resolved providers/models/features payload. Admin-only.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"providers":{"type":"string"},"models":{"type":"string"},"features":{"type":"string"}},"required":["providers","models","features"],"additionalProperties":false},"example":{"providers":"sample providers","models":"sample models","features":"sample features"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"captain_models":{"type":"object","description":"Selected model id per feature (merged into existing).","properties":{"editor":{"type":"string","example":"openai:gpt-5.5"},"assistant":{"type":"string","example":"openai:gpt-5.5"},"copilot":{"type":"string","example":"openai:gpt-5.5-mini"},"label_suggestion":{"type":"string","example":"openai:gpt-5.5-mini"},"audio_transcription":{"type":"string","example":"openai:whisper-1"},"help_center_search":{"type":"string","example":"openai:gpt-5.5-mini"}}},"captain_features":{"type":"object","description":"Per-feature enablement flags (merged into existing).","properties":{"editor":{"type":"boolean","example":true},"assistant":{"type":"boolean","example":true},"copilot":{"type":"boolean","example":true},"label_suggestion":{"type":"boolean","example":false},"audio_transcription":{"type":"boolean","example":false},"help_center_search":{"type":"boolean","example":true}}}}},"example":{"captain_models":{"editor":"openai:gpt-5.5","assistant":"openai:gpt-5.5","copilot":"openai:gpt-5.5-mini","label_suggestion":"openai:gpt-5.5-mini","audio_transcription":"openai:whisper-1","help_center_search":"openai:gpt-5.5-mini"},"captain_features":{"editor":true,"assistant":true,"copilot":true,"label_suggestion":false,"audio_transcription":false,"help_center_search":true}}}}}}},"/api/v1/accounts/{account_id}/captain/assistants/{id}/playground":{"post":{"tags":["Captain"],"operationId":"auto_post_api_v1_accounts_account_id_captain_assistants_id_playground","summary":"Run the Captain assistant in the playground","description":"Generates one assistant response for the supplied message history (V2 AgentRunnerService when captain_v2 is enabled, else V1 AssistantChatService). The body is the assistant's parsed JSON reply; the exact keys are LLM-shaped, but the V2 runner always sets response/reasoning/ agent_name/handoff_tool_called.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The assistant's generated reply (LLM-shaped JSON object).","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"response":{"type":"string","description":"The assistant's answer (or 'conversation_handoff' when handing off).","example":"Sure — your order ships tomorrow."},"reasoning":{"type":"string","example":"Answered from the order-status tool result."},"agent_name":{"type":["string","null"],"description":"The agent that produced the reply (V2 runner).","example":"Support Assistant"},"handoff_tool_called":{"type":"boolean","description":"True when the run triggered a human-handoff tool.","example":false}}},"example":{"response":"Sure — your order ships tomorrow.","reasoning":"Answered from the order-status tool result.","agent_name":"Support Assistant","handoff_tool_called":false}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"assistant":{"type":"object","properties":{"message_content":{"type":"string"},"message_history":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Free-form object."}}}}},"required":["assistant"]},"example":{"assistant":{"message_content":"sample message content","message_history":[{}]}}}}}}},"/api/v1/accounts/{account_id}/captain/assistants/{id}/metrics":{"get":{"tags":["Captain"],"operationId":"auto_get_api_v1_accounts_account_id_captain_assistants_id_metrics","summary":"Assistant overview metrics for a window and its comparison window","description":"Returns the assistant's headline metrics for the selected window together with the preceding equal-length window and the derived trend, so each card can render a value and a delta. Conversations handled counts the distinct conversations the assistant authored a message in. Auto-resolution and handoff rates are shares of that cohort. Hours saved is an estimate — the number of public assistant replies times an assumed two minutes of agent effort each — not a measured duration. Reopen rate is the share of auto-resolved conversations that reopened afterwards. Conversation depth is public assistant replies per conversation. Requires Captain (Enterprise).","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The six overview metrics, each packed as current, previous and trend.","content":{"application/json":{"schema":{"type":"object","properties":{"conversations_handled":{"type":"object","description":"Distinct conversations the assistant authored a message in. Trend is a percent change.","properties":{"current":{"type":"integer","description":"Value for the selected window.","example":412},"previous":{"type":"integer","description":"Value for the preceding equal-length window.","example":356},"trend":{"type":"number","description":"Percent change against the previous window.","example":15.7}},"additionalProperties":false},"auto_resolution_rate":{"type":"object","description":"Percentage of handled conversations Captain resolved on its own. Trend is a percentage-point change.","properties":{"current":{"type":"number","description":"Percentage for the selected window.","example":42.3},"previous":{"type":"number","description":"Percentage for the previous window.","example":38.1},"trend":{"type":"number","description":"Percentage-point change against the previous window.","example":4.2}},"additionalProperties":false},"handoff_rate":{"type":"object","description":"Percentage of handled conversations transferred to a human. Trend is a percentage-point change.","properties":{"current":{"type":"number","description":"Percentage for the selected window.","example":21.8},"previous":{"type":"number","description":"Percentage for the previous window.","example":25.4},"trend":{"type":"number","description":"Percentage-point change against the previous window.","example":-3.6}},"additionalProperties":false},"hours_saved":{"type":"object","description":"Estimated agent hours displaced, computed as public assistant replies times two assumed minutes each and rounded to whole hours. Trend is a percent change.","properties":{"current":{"type":"integer","description":"Estimated hours for the selected window.","example":31},"previous":{"type":"integer","description":"Estimated hours for the previous window.","example":24},"trend":{"type":"number","description":"Percent change against the previous window.","example":29.2}},"additionalProperties":false},"reopen_rate":{"type":"object","description":"Percentage of auto-resolved conversations that reopened. Trend is a percentage-point change.","properties":{"current":{"type":"number","description":"Percentage for the selected window.","example":6.4},"previous":{"type":"number","description":"Percentage for the previous window.","example":8.9},"trend":{"type":"number","description":"Percentage-point change against the previous window.","example":-2.5}},"additionalProperties":false},"conversation_depth":{"type":"object","description":"Public assistant replies per conversation. Trend is an absolute difference.","properties":{"current":{"type":"number","description":"Average replies per conversation in the selected window.","example":3.4},"previous":{"type":"number","description":"Average replies per conversation in the previous window.","example":3.1},"trend":{"type":"number","description":"Absolute difference against the previous window.","example":0.3}},"additionalProperties":false}},"additionalProperties":false},"example":{"conversations_handled":{"current":412,"previous":356,"trend":15.7},"auto_resolution_rate":{"current":42.3,"previous":38.1,"trend":4.2},"handoff_rate":{"current":21.8,"previous":25.4,"trend":-3.6},"hours_saved":{"current":31,"previous":24,"trend":29.2},"reopen_rate":{"current":6.4,"previous":8.9,"trend":-2.5},"conversation_depth":{"current":3.4,"previous":3.1,"trend":0.3}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"range","in":"query","required":false,"description":"Window to report on: a day count, or a named calendar period. Anything else falls back to 7.","schema":{"type":"string","enum":["7","30","90","this_month","last_month"],"default":"7","example":"30"}},{"name":"timezone_offset","in":"query","required":false,"description":"Viewer UTC offset in hours, so day and month boundaries anchor to the viewer's calendar instead of UTC. Falls back to the account timezone.","schema":{"type":"number","example":-3}}]}},"/api/v1/accounts/{account_id}/captain/assistants/{id}/faq_stats":{"get":{"tags":["Captain"],"operationId":"auto_get_api_v1_accounts_account_id_captain_assistants_id_faq_stats","summary":"Assistant knowledge counters (approved answers, open suggestions, documents)","description":"Returns the assistant's knowledge counters in one round trip: approved answers, still-open answer suggestions visible to the current user, indexed documents, and the coverage percentage — approved answers over approved plus open suggestions, rounded to a whole percent. Not window-scoped: the counters are the current totals. Requires Captain (Enterprise).","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Current knowledge counters for the assistant.","content":{"application/json":{"schema":{"type":"object","properties":{"approved":{"type":"integer","description":"Approved answers attached to this assistant.","example":128},"suggestions":{"type":"integer","description":"Open answer suggestions the current user can act on.","example":17},"documents":{"type":"integer","description":"Documents indexed for this assistant.","example":34},"coverage":{"type":"integer","description":"Approved answers as a whole percentage of approved plus open suggestions; 0 when neither exists.","example":88}},"additionalProperties":false},"example":{"approved":128,"suggestions":17,"documents":34,"coverage":88}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/captain/assistants/{id}/summary":{"get":{"tags":["Captain"],"operationId":"auto_get_api_v1_accounts_account_id_captain_assistants_id_summary","summary":"Summary assistants","description":"Performs the summary operation on the targeted assistant resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"error":{"type":"string"}}},{"type":"object","properties":{"message":{"type":"string"}}}]},"example":{"error":"sample error"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/captain/assistants/{id}/drilldown":{"get":{"tags":["Captain"],"operationId":"auto_get_api_v1_accounts_account_id_captain_assistants_id_drilldown","summary":"List the conversations behind one assistant overview card","description":"Drills from a single overview card into the exact conversations that produced it, over the same window the card used, so the totals reconcile. Rows are ordered newest first and paginated. An unsupported or missing metric is rejected with 422 rather than silently listing a different cohort. Requires Captain (Enterprise).","security":[{"userApiKey":[]}],"responses":{"200":{"description":"One page of the conversations behind the requested card, plus the window it covers.","content":{"application/json":{"schema":{"type":"object","properties":{"meta":{"type":"object","description":"Pagination plus the resolved window, echoed so a caller can label the drawer.","properties":{"metric":{"type":"string","description":"The card that was expanded.","enum":["conversations_handled","auto_resolution_rate","handoff_rate","reopen_rate"],"example":"auto_resolution_rate"},"current_page":{"type":"integer","description":"The page returned.","example":1},"per_page":{"type":"integer","description":"Rows per page actually applied.","example":25},"total_count":{"type":"integer","description":"Total rows across all pages.","example":174},"conversation_count":{"type":"integer","description":"Same total, named for the conversation drawer that renders it.","example":174},"range":{"type":"object","description":"The resolved window, in Unix epoch seconds.","properties":{"since":{"type":"integer","description":"Window start.","example":1776144000},"until":{"type":"integer","description":"Window end.","example":1778736000}},"additionalProperties":false}},"additionalProperties":false},"payload":{"type":"array","description":"The conversations on this page, newest first.","items":{"type":"object","description":"One drilled-down row, serialized by the shared reports drilldown serializer so the existing conversation cards render it unchanged.","properties":{"record_type":{"type":"string","description":"Kind of row. These drilldowns always list conversations; the shared serializer emits `message` only for message-derived report metrics.","enum":["conversation"],"example":"conversation"},"conversation":{"type":"object","description":"The conversation the row points at, with the participants and the latest non-activity message already resolved so a card can render without a second request.","properties":{"id":{"type":"integer","description":"Internal conversation id.","example":90211},"display_id":{"type":"integer","description":"Account-scoped conversation number shown in the dashboard URL.","example":4821},"contact_id":{"type":"integer","description":"Contact that opened the conversation.","example":55210},"contact_name":{"type":["string","null"],"description":"Contact display name; null when the contact has no name yet.","example":"Marina Duarte"},"inbox_id":{"type":"integer","description":"Inbox the conversation belongs to.","example":37},"inbox_name":{"type":["string","null"],"description":"Inbox display name; null when the inbox was deleted.","example":"WhatsApp Support"},"assignee_id":{"type":["integer","null"],"description":"Assigned agent id; null while unassigned.","example":12},"assignee_name":{"type":["string","null"],"description":"Assigned agent name; null while unassigned.","example":"Rafael Lima"},"status":{"type":"string","description":"Current conversation status.","enum":["open","resolved","pending","snoozed"],"example":"resolved"},"created_at":{"type":"integer","description":"Unix epoch seconds the conversation was created.","example":1778730000},"last_activity_at":{"type":"integer","description":"Unix epoch seconds of the last activity.","example":1778735498},"last_message":{"type":["object","null"],"description":"Newest non-activity message of the conversation; null when the conversation has only activity entries.","properties":{"id":{"type":"integer","description":"Message id.","example":771204},"content":{"type":["string","null"],"description":"Message text; null for an attachment-only message.","example":"Perfect, that solved it. Thanks!"},"message_type":{"type":"string","description":"Direction/kind of the message. Never `activity`: the newest non-activity message is the one resolved here.","enum":["incoming","outgoing","template"],"example":"incoming"},"sender_name":{"type":["string","null"],"description":"Display name of the sender; null when the sender was removed.","example":"Marina Duarte"},"created_at":{"type":"integer","description":"Unix epoch seconds the message was created.","example":1778735498}},"additionalProperties":false}},"additionalProperties":false},"message":{"type":["object","null"],"description":"Always null on these drilldowns — the cohort is a conversation list, not a per-message one. Kept in the contract because the shared serializer fills it for message-derived report metrics.","example":null,"properties":{"id":{"type":"integer","description":"Message id.","example":771204},"content":{"type":["string","null"],"description":"Message text.","example":"Perfect, that solved it. Thanks!"},"message_type":{"type":"string","description":"Direction/kind of the message.","enum":["incoming","outgoing","activity","template"],"example":"outgoing"},"sender_name":{"type":["string","null"],"description":"Display name of the sender.","example":"Support Assistant"},"created_at":{"type":"integer","description":"Unix epoch seconds the message was created.","example":1778735498}},"additionalProperties":false},"metric_value":{"type":["number","null"],"description":"Always null on these drilldowns: the row is a membership in a cohort, not a measured duration. Populated only for event-derived report metrics that carry a value.","example":null},"occurred_at":{"type":"integer","description":"Unix epoch seconds used to order the row — the conversation creation time for a conversation row.","example":1778730000}},"additionalProperties":false}}},"additionalProperties":false},"example":{"meta":{"metric":"auto_resolution_rate","current_page":1,"per_page":25,"total_count":174,"conversation_count":174,"range":{"since":1776144000,"until":1778736000}},"payload":[{"record_type":"conversation","conversation":{"id":90211,"display_id":4821,"contact_id":55210,"contact_name":"Marina Duarte","inbox_id":37,"inbox_name":"WhatsApp Support","assignee_id":12,"assignee_name":"Rafael Lima","status":"resolved","created_at":1778730000,"last_activity_at":1778735498,"last_message":{"id":771204,"content":"Perfect, that solved it. Thanks!","message_type":"incoming","sender_name":"Marina Duarte","created_at":1778735498}},"message":null,"metric_value":null,"occurred_at":1778730000}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"metric","in":"query","required":true,"description":"Which overview card to expand. Any other value is rejected with 422.","schema":{"type":"string","enum":["conversations_handled","auto_resolution_rate","handoff_rate","reopen_rate"],"example":"auto_resolution_rate"}},{"name":"range","in":"query","required":false,"description":"Same window the card used. Anything outside the listed set falls back to 7.","schema":{"type":"string","enum":["7","30","90","this_month","last_month"],"default":"7","example":"30"}},{"name":"timezone_offset","in":"query","required":false,"description":"Viewer UTC offset in hours, so window boundaries match the card.","schema":{"type":"number","example":-3}},{"name":"page","in":"query","required":false,"description":"1-based page number.","schema":{"type":"integer","minimum":1,"default":1,"example":1}},{"name":"per_page","in":"query","required":false,"description":"Rows per page. Defaults to 25; values above 100 are capped to 100.","schema":{"type":"integer","minimum":1,"maximum":100,"default":25,"example":25}}]}},"/api/v1/accounts/{account_id}/captain/assistants/{assistant_id}/stats/overview":{"get":{"tags":["Captain"],"operationId":"auto_get_api_v1_accounts_account_id_captain_assistants_assistant_id_stats_overview","summary":"Full assistant outcome metric set for a window and its comparison window","description":"Returns the complete assistant metric set derived from conversation outcome episodes, each packed as the current window value, the preceding equal-length window value, and the derived trend. Funnel and outcome metrics group episodes by when demand started, so a cohort stays stable as later facts arrive; reply-derived metrics (hours saved, conversation depth) remain message-derived because an episode still in progress has no terminal snapshot yet. A trend is null whenever either side of the comparison is null. Requires Captain (Enterprise).","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Thirteen metrics, each packed as current, previous and trend.","content":{"application/json":{"schema":{"type":"object","properties":{"conversations_handled":{"type":"object","description":"Episodes Captain participated in. Trend is a percent change.","properties":{"current":{"type":"integer","description":"Value for the selected window.","example":412},"previous":{"type":"integer","description":"Value for the previous window.","example":356},"trend":{"type":"number","description":"Percent change against the previous window.","example":15.7}},"additionalProperties":false},"auto_resolution_rate":{"type":"object","description":"Autonomous resolutions as a percentage of participated episodes. Trend is a percentage-point change.","properties":{"current":{"type":"number","description":"Percentage for the selected window.","example":42.3},"previous":{"type":"number","description":"Percentage for the previous window.","example":38.1},"trend":{"type":"number","description":"Percentage-point change against the previous window.","example":4.2}},"additionalProperties":false},"autonomous_resolutions":{"type":"object","description":"Episodes resolved with a Captain reply, no handoff and no earlier human reply. Trend is a percent change.","properties":{"current":{"type":"integer","description":"Count for the selected window.","example":174},"previous":{"type":"integer","description":"Count for the previous window.","example":136},"trend":{"type":"number","description":"Percent change against the previous window.","example":27.9}},"additionalProperties":false},"handoff_rate":{"type":"object","description":"Handed-off episodes as a percentage of participated episodes. Trend is a percentage-point change.","properties":{"current":{"type":"number","description":"Percentage for the selected window.","example":21.8},"previous":{"type":"number","description":"Percentage for the previous window.","example":25.4},"trend":{"type":"number","description":"Percentage-point change against the previous window.","example":-3.6}},"additionalProperties":false},"handoff_count":{"type":"object","description":"Episodes transferred to a human. A quota block before Captain ever replied is not counted, because Captain never participated. Trend is a percent change.","properties":{"current":{"type":"integer","description":"Count for the selected window.","example":90},"previous":{"type":"integer","description":"Count for the previous window.","example":91},"trend":{"type":"number","description":"Percent change against the previous window.","example":-1.1}},"additionalProperties":false},"hours_saved":{"type":"object","description":"Estimated agent hours displaced: public assistant replies times two assumed minutes each, rounded to whole hours. Trend is an absolute difference.","properties":{"current":{"type":"integer","description":"Estimated hours for the selected window.","example":31},"previous":{"type":"integer","description":"Estimated hours for the previous window.","example":24},"trend":{"type":"number","description":"Absolute difference against the previous window.","example":7}},"additionalProperties":false},"reopen_rate":{"type":"object","description":"Autonomously resolved episodes that reopened, as a percentage. Trend is a percentage-point change.","properties":{"current":{"type":"number","description":"Percentage for the selected window.","example":6.4},"previous":{"type":"number","description":"Percentage for the previous window.","example":8.9},"trend":{"type":"number","description":"Percentage-point change against the previous window.","example":-2.5}},"additionalProperties":false},"conversation_depth":{"type":"object","description":"Public assistant replies per conversation. Trend is an absolute difference.","properties":{"current":{"type":"number","description":"Average replies per conversation in the selected window.","example":3.4},"previous":{"type":"number","description":"Average replies per conversation in the previous window.","example":3.1},"trend":{"type":"number","description":"Absolute difference against the previous window.","example":0.3}},"additionalProperties":false},"durable_resolution_rate":{"type":"object","description":"Share of assessable autonomous resolutions that stayed closed for seven days. Only resolutions old enough for that verdict are assessable. Trend is a percentage-point change.","properties":{"current":{"type":"number","description":"Percentage for the selected window.","example":93.6},"previous":{"type":"number","description":"Percentage for the previous window.","example":91.1},"trend":{"type":"number","description":"Percentage-point change against the previous window.","example":2.5}},"additionalProperties":false},"autonomous_csat_score":{"type":"object","description":"Average satisfaction rating on autonomously resolved episodes, to two decimals; 0 when no rating exists. Trend is an absolute difference.","properties":{"current":{"type":"number","description":"Average rating for the selected window.","example":4.42},"previous":{"type":"number","description":"Average rating for the previous window.","example":4.31},"trend":{"type":"number","description":"Absolute difference against the previous window.","example":0.11}},"additionalProperties":false},"assisted_csat_score":{"type":"object","description":"Average satisfaction rating on episodes Captain participated in but did not resolve alone, to two decimals; 0 when no rating exists. Trend is an absolute difference.","properties":{"current":{"type":"number","description":"Average rating for the selected window.","example":4.18},"previous":{"type":"number","description":"Average rating for the previous window.","example":4.22},"trend":{"type":"number","description":"Absolute difference against the previous window.","example":-0.04}},"additionalProperties":false},"median_resolution_seconds":{"type":"object","description":"Median seconds from the start of a participated episode to its resolution. Trend is an absolute difference.","properties":{"current":{"type":"integer","description":"Median seconds for the selected window.","example":486},"previous":{"type":"integer","description":"Median seconds for the previous window.","example":602},"trend":{"type":"number","description":"Absolute difference against the previous window.","example":-116}},"additionalProperties":false},"human_only_csat_score":{"type":"object","description":"Account-wide average satisfaction rating from conversations no Captain assistant ever participated in — the human baseline. Every field is null when no such rating exists in the window.","properties":{"current":{"type":["number","null"],"description":"Baseline average for the selected window; null when unrated.","example":4.05},"previous":{"type":["number","null"],"description":"Baseline average for the previous window; null when unrated.","example":4.11},"trend":{"type":["number","null"],"description":"Absolute difference; null when either window is unrated.","example":-0.06}},"additionalProperties":false}},"additionalProperties":false},"example":{"conversations_handled":{"current":412,"previous":356,"trend":15.7},"auto_resolution_rate":{"current":42.3,"previous":38.1,"trend":4.2},"autonomous_resolutions":{"current":174,"previous":136,"trend":27.9},"handoff_rate":{"current":21.8,"previous":25.4,"trend":-3.6},"handoff_count":{"current":90,"previous":91,"trend":-1.1},"hours_saved":{"current":31,"previous":24,"trend":7},"reopen_rate":{"current":6.4,"previous":8.9,"trend":-2.5},"conversation_depth":{"current":3.4,"previous":3.1,"trend":0.3},"durable_resolution_rate":{"current":93.6,"previous":91.1,"trend":2.5},"autonomous_csat_score":{"current":4.42,"previous":4.31,"trend":0.11},"assisted_csat_score":{"current":4.18,"previous":4.22,"trend":-0.04},"median_resolution_seconds":{"current":486,"previous":602,"trend":-116},"human_only_csat_score":{"current":4.05,"previous":4.11,"trend":-0.06}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"assistant_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"range","in":"query","required":false,"description":"Window to report on. Anything outside the listed set falls back to 7.","schema":{"type":"string","enum":["7","30","90","this_month","last_month"],"default":"7","example":"30"}},{"name":"timezone_offset","in":"query","required":false,"description":"Viewer UTC offset in hours, so day and month boundaries follow the viewer's calendar.","schema":{"type":"number","example":-3}}]}},"/api/v1/accounts/{account_id}/captain/assistants/{assistant_id}/stats/overview_summary":{"get":{"tags":["Captain"],"operationId":"auto_get_api_v1_accounts_account_id_captain_assistants_assistant_id_stats_overview_summary","summary":"Overview summary assistant stats","description":"Performs the overview summary operation on the targeted assistant stat resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}},"example":{"error":"sample error"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"assistant_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/captain/assistants/{assistant_id}/stats/resolution_flow":{"get":{"tags":["Captain"],"operationId":"auto_get_api_v1_accounts_account_id_captain_assistants_assistant_id_stats_resolution_flow","summary":"Assistant resolution flow (Sankey) and handoff reason breakdown","description":"Returns the current window's resolution flow as balanced Sankey nodes and links, plus the handoff reason breakdown that feeds the flow's handoff branch. Branches are mutually exclusive, so handled equals resolved plus handed off plus closed with the team, and resolved equals reopened within seven days plus stayed closed. Only the two largest handoff reasons get their own branch; the remainder is folded into a single other-reasons node, which is omitted when it would be empty. Unlike the metric endpoints this one reports the current window only — there is no comparison window. Requires Captain (Enterprise).","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Balanced flow graph plus the ranked handoff reason distribution.","content":{"application/json":{"schema":{"type":"object","properties":{"sankey":{"type":"object","description":"The flow graph, ready to render without further aggregation.","properties":{"nodes":{"type":"array","description":"Flow stages and their counts. The six base stages are always present; reason nodes appear only for the two largest handoff reasons, plus other_reasons when the tail is not empty.","items":{"type":"object","properties":{"id":{"type":"string","description":"Stage identifier.","enum":["conversations_handled","resolved_by_captain","handed_off","closed_with_team","reopened_within_7_days","stayed_closed","handoff_reason_customer_request","handoff_reason_missing_knowledge","handoff_reason_unsupported_request","handoff_reason_policy_restriction","handoff_reason_tool_failure","handoff_reason_pending_clarification","handoff_reason_usage_limit","handoff_reason_unclassified","other_reasons"],"example":"resolved_by_captain"},"count":{"type":"integer","description":"Episodes at this stage.","example":174}},"additionalProperties":false}},"links":{"type":"array","description":"Directed edges between stages; each value is a subset of its source's count.","items":{"type":"object","properties":{"source":{"type":"string","description":"Originating stage.","enum":["conversations_handled","resolved_by_captain","handed_off"],"example":"conversations_handled"},"target":{"type":"string","description":"Receiving stage.","enum":["resolved_by_captain","handed_off","closed_with_team","reopened_within_7_days","stayed_closed","handoff_reason_customer_request","handoff_reason_missing_knowledge","handoff_reason_unsupported_request","handoff_reason_policy_restriction","handoff_reason_tool_failure","handoff_reason_pending_clarification","handoff_reason_usage_limit","handoff_reason_unclassified","other_reasons"],"example":"resolved_by_captain"},"value":{"type":"integer","description":"Episodes flowing along this edge.","example":174}},"additionalProperties":false}}},"additionalProperties":false},"handoff_distribution":{"type":"array","description":"Every handoff reason in the window, largest first, ties broken alphabetically. Complete — not truncated to the two branches drawn in the flow.","items":{"type":"object","properties":{"category":{"type":"string","description":"Classified handoff reason, or unclassified when the episode recorded none.","enum":["customer_request","missing_knowledge","unsupported_request","policy_restriction","tool_failure","pending_clarification","usage_limit","unclassified"],"example":"missing_knowledge"},"count":{"type":"integer","description":"Handoffs with this reason.","example":41},"percentage":{"type":"number","description":"Share of all handoffs in the window, to one decimal; 0 when there were none.","example":45.6}},"additionalProperties":false}}},"additionalProperties":false},"example":{"sankey":{"nodes":[{"id":"resolved_by_captain","count":174}],"links":[{"source":"conversations_handled","target":"resolved_by_captain","value":174}]},"handoff_distribution":[{"category":"missing_knowledge","count":41,"percentage":45.6}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"assistant_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"range","in":"query","required":false,"description":"Window to report on. Anything outside the listed set falls back to 7.","schema":{"type":"string","enum":["7","30","90","this_month","last_month"],"default":"7","example":"30"}},{"name":"timezone_offset","in":"query","required":false,"description":"Viewer UTC offset in hours, so window boundaries follow the viewer's calendar.","schema":{"type":"number","example":-3}}]}},"/api/v1/accounts/{account_id}/captain/assistants/{assistant_id}/stats/resolution_trend":{"get":{"tags":["Captain"],"operationId":"auto_get_api_v1_accounts_account_id_captain_assistants_assistant_id_stats_resolution_trend","summary":"Assistant involvement and autonomous-resolution time series","description":"Returns a bucketed time series of Captain involvement and autonomous resolution for the selected window, with the equivalent bucket of the comparison window aligned by elapsed position so the two lines can be drawn together. Buckets are daily for windows up to fifteen days and weekly beyond that; the last bucket may be shorter than the others because it ends at the window's edge. A resolution rate is null for a bucket with no involvement, so a gap is not drawn as a zero. Requires Captain (Enterprise).","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The chosen bucket size and one entry per bucket, oldest first.","content":{"application/json":{"schema":{"type":"object","properties":{"granularity":{"type":"string","description":"Bucket size chosen for this window — daily up to fifteen days, weekly beyond.","enum":["day","week"],"example":"day"},"buckets":{"type":"array","description":"One entry per bucket, oldest first.","items":{"type":"object","properties":{"starts_on":{"type":"string","format":"date","description":"First calendar day of the bucket, in the viewer's timezone.","example":"2026-08-01"},"ends_on":{"type":"string","format":"date","description":"Last calendar day of the bucket, in the viewer's timezone.","example":"2026-08-01"},"conversations_handled":{"type":"integer","description":"Episodes Captain participated in during the bucket.","example":58},"resolved_by_captain":{"type":"integer","description":"Episodes Captain resolved autonomously during the bucket.","example":24},"current_resolution_rate":{"type":["number","null"],"description":"Autonomous resolutions as a percentage of involvement in this bucket, to one decimal; null when there was no involvement.","example":41.4},"previous_resolution_rate":{"type":["number","null"],"description":"Same percentage for the aligned bucket of the comparison window; null when that bucket had no involvement.","example":37.9}},"additionalProperties":false}}},"additionalProperties":false},"example":{"granularity":"day","buckets":[{"starts_on":"2026-08-01","ends_on":"2026-08-01","conversations_handled":58,"resolved_by_captain":24,"current_resolution_rate":41.4,"previous_resolution_rate":37.9}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"assistant_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"range","in":"query","required":false,"description":"Window to report on. Anything outside the listed set falls back to 7.","schema":{"type":"string","enum":["7","30","90","this_month","last_month"],"default":"7","example":"30"}},{"name":"timezone_offset","in":"query","required":false,"description":"Viewer UTC offset in hours, so bucket boundaries follow the viewer's calendar.","schema":{"type":"number","example":-3}}]}},"/api/v1/accounts/{account_id}/captain/assistants/tools":{"get":{"tags":["Captain"],"operationId":"auto_get_api_v1_accounts_account_id_captain_assistants_tools","summary":"Tools assistants","description":"Performs the tools operation on the targeted assistant resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"title":{"type":"string"},"description":{"type":"string"},"icon":{"type":"string"}}}},"example":[{"id":1,"title":"Sample title","description":"A short description.","icon":"sample icon"}]}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/captain/assistants/{assistant_id}/inboxes":{"get":{"tags":["Captain"],"operationId":"auto_get_api_v1_accounts_account_id_captain_assistants_assistant_id_inboxes","summary":"List inboxes","description":"Returns the list of inboxes visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"avatar_url":{"type":"string"},"channel_id":{"type":"integer"},"name":{"type":"string"},"channel_type":{"type":"string","enum":["Channel::Api","Channel::Email","Channel::FacebookPage","Channel::Instagram","Channel::Line","Channel::Sms","Channel::Telegram","Channel::Tiktok","Channel::TwilioSms","Channel::TwitterProfile","Channel::WebWidget","Channel::Whatsapp"],"description":"The inbox channel class."},"greeting_enabled":{"type":"boolean"},"greeting_message":{"type":"string"},"working_hours_enabled":{"type":"boolean"},"enable_email_collect":{"type":"string"},"csat_survey_enabled":{"type":"boolean"},"csat_config":{"type":"string"},"enable_auto_assignment":{"type":"string"},"auto_assignment_config":{"type":"string"},"out_of_office_message":{"type":"string"},"working_hours":{"type":"string"},"timezone":{"type":"string","description":"IANA timezone identifier (e.g. \"America/Sao_Paulo\", \"UTC\"). Rails timezone names are also accepted on input; an unrecognized value is ignored in favor of the next fallback.","example":"America/Sao_Paulo"},"callback_webhook_url":{"type":"string"},"allow_messages_after_resolved":{"type":"string"},"lock_to_single_conversation":{"type":"string"},"audio_transcription_enabled":{"type":"boolean"},"preserve_deleted_messages":{"type":"string"},"allow_message_deletion":{"type":"string"},"capture_view_once":{"type":"string"},"sender_name_type":{"type":"string","enum":["friendly","professional"]},"auto_resolve_config":{"type":"object","additionalProperties":true,"oneOf":[{"type":"object","maxProperties":0,"additionalProperties":true,"description":"Empty means inherit the account rule."},{"type":"object","additionalProperties":false,"required":["mode"],"properties":{"mode":{"type":"string","enum":["disabled"],"description":"Disable automatic resolution for this inbox."}},"description":"The disabled rule contains only its mode."},{"type":"object","additionalProperties":false,"required":["mode","after","message","label","allow_waiting"],"properties":{"mode":{"type":"string","enum":["custom"],"description":"Use this complete inbox rule."},"after":{"type":"integer","minimum":10,"maximum":1439856,"description":"Inactivity in minutes; required for custom mode."},"message":{"type":["string","null"],"maxLength":10000,"description":"Optional message; blank normalizes to null."},"label":{"type":["string","null"],"description":"An existing account label title, or null."},"allow_waiting":{"type":"boolean","description":"Whether waiting conversations are included."}},"description":"Complete normalized custom rule."}],"description":"Normalized JSON rule from valid model writes: empty, disabled, or complete custom configuration.","example":{"mode":"custom","after":60,"message":null,"label":null,"allow_waiting":false}},"outbound_agent_name_header_policy":{"type":"string"},"agent_bot_working_hours_mode":{"type":"string","enum":["always","inside_business_hours","outside_business_hours"]},"business_name":{"type":"string"},"responder_policy":{"type":"string"},"help_center":{"type":"object","properties":{"name":{"type":"string"},"slug":{"type":"string"}}},"tweets_enabled":{"type":"boolean"},"allowed_domains":{"type":"string"},"widget_color":{"type":"string"},"website_url":{"type":"string"},"hmac_mandatory":{"type":"string"},"welcome_title":{"type":"string"},"welcome_tagline":{"type":"string"},"web_widget_script":{"type":"string"},"website_token":{"type":"string"},"selected_feature_flags":{"type":"string"},"reply_time":{"type":"string","format":"date-time"},"hmac_token":{"type":"string"},"pre_chat_form_enabled":{"type":"boolean"},"pre_chat_form_options":{"type":"string"},"continuity_via_email":{"type":"string","format":"email"},"page_id":{"type":"integer"},"reauthorization_required":{"type":"string"},"instagram_id":{"type":"integer"},"messaging_service_sid":{"type":"string"},"phone_number":{"type":"string"},"medium":{"type":"string"},"bandwidth_callback_state":{"type":"string","enum":["active","reconnect_required","reconciling","reconciliation_required","encryption_required"]},"bandwidth_api_migration_state":{"type":"string","enum":["oauth2_configured","oauth2_required","configuration_required"]},"bandwidth_legacy_basic_deprecated":{"type":"boolean"},"content_templates":{"type":"string"},"auth_token":{"type":"string"},"account_sid":{"type":"string"},"api_key_sid":{"type":"string"},"twilio_credential_state":{"type":"string","enum":["ready","pending","failed","dead_letter","account_auth_token_required","reconciliation_required"],"description":"Durable Twilio credential lifecycle derived from Channel::TwilioSms. A reconciliation-required state is fail-closed until the provider outcome has been verified."},"api_key_configured":{"type":"boolean"},"email":{"type":"string","format":"email"},"auth_method":{"type":"string"},"forwarding_enabled":{"type":"boolean"},"forward_to_email":{"type":"string","format":"email"},"branded_email_layout":{"type":"string"},"imap_login":{"type":"string"},"imap_password":{"type":"string"},"imap_address":{"type":"string"},"imap_port":{"type":"string"},"imap_enabled":{"type":"boolean"},"imap_enable_ssl":{"type":"string"},"imap_authentication":{"type":"string"},"smtp_login":{"type":"string"},"smtp_password":{"type":"string"},"smtp_address":{"type":"string"},"smtp_port":{"type":"string"},"smtp_enabled":{"type":"boolean"},"smtp_domain":{"type":"string"},"smtp_enable_ssl_tls":{"type":"string"},"smtp_enable_starttls_auto":{"type":"string"},"smtp_openssl_verify_mode":{"type":"string","enum":["none","peer","client_once","fail_if_no_peer_cert"],"description":"OpenSSL peer-certificate verification mode for the email channel's SMTP connection."},"smtp_authentication":{"type":"string"},"secret":{"type":"string"},"webhook_url":{"type":"string"},"inbox_identifier":{"type":"string"},"additional_attributes":{"type":"object","additionalProperties":true,"description":"Channel- and source-specific metadata for this record (e.g. browser info, referer, social profile identifiers). The key set depends on the originating channel."},"provider":{"type":"string"},"bot_name":{"type":"string"},"message_templates":{"type":"boolean"},"provider_config":{"type":"string"},"business_management_token_configured":{"type":"boolean"},"hybrid_pair":{"$ref":"#/components/schemas/inbox/properties/hybrid_pair"},"whatsapp_web_session_state":{"$ref":"#/components/schemas/inbox/properties/whatsapp_web_session_state"},"hybrid_hidden":{"type":"string"},"logical_inbox_id":{"type":"integer"},"whatsapp_pending_phone":{"type":"object","nullable":true,"description":"Spec 052 — set only when a WhatsApp phone-number rewrite was REFUSED because a non-sibling channel already holds the number, leaving the inbox on its `pending:` placeholder and inert. `null` in every normal case (including a routine, not-yet-scanned pairing).","additionalProperties":false,"properties":{"awaiting_pair":{"type":"boolean","description":"True while the inbox is still on its `pending:\u003cuuid\u003e` placeholder number."},"phone":{"type":"string","description":"The E.164 number the rewrite tried to claim."},"reason":{"type":"string","enum":["same_account_same_provider","other_account"],"description":"Why the rewrite was refused. `other_account` never carries any identifying detail about the other account."},"sibling_inbox_id":{"type":"integer","nullable":true,"description":"Colliding inbox in the SAME account; absent when the collision is cross-account."},"source":{"type":"string","enum":["pair_success","qr_pump"],"description":"Which path attempted the rewrite."},"at":{"type":"string","format":"date-time","description":"When the refusal was recorded."}}},"whatsapp_sibling_notice":{"type":"string"},"whatsapp_web_contact_request":{"type":"string","enum":["supported","unsupported","unknown"],"description":"WhatsApp Web inboxes only — whether this inbox's WazMeow gateway serves the request that asks a customer to share their phone number. `supported` and `unsupported` come from a no-effect probe of the gateway route, refreshed at most hourly and immediately when a real send finds the route missing; `unknown` means not probed yet or the gateway could not be reached. Only `supported` turns the feature on; with `unknown` the request is refused before any gateway call while the probe runs."},"voice_enabled":{"type":"boolean"},"inbound_calls_enabled":{"type":"boolean"},"voice_configured":{"type":"boolean"},"voice_call_webhook_url":{"type":"string"},"voice_status_webhook_url":{"type":"string"}}}},"meta":{"type":"object","properties":{"total_count":{"type":"integer"},"page":{"type":"string"}}}}},"example":{"payload":[{"id":1,"avatar_url":"https://example.com/resource","channel_id":1,"name":"Sample Name","channel_type":"Channel::Api","greeting_enabled":true,"greeting_message":"sample greeting message","working_hours_enabled":true,"enable_email_collect":"agent@example.com","csat_survey_enabled":true,"csat_config":"sample csat config","enable_auto_assignment":"sample enable auto assignment","auto_assignment_config":"sample auto assignment config","out_of_office_message":"sample out of office message","working_hours":"sample working hours","timezone":"America/Sao_Paulo","callback_webhook_url":"https://example.com/resource","allow_messages_after_resolved":"sample allow messages after resolved","lock_to_single_conversation":"sample lock to single conversation","audio_transcription_enabled":true,"preserve_deleted_messages":"sample preserve deleted messages","allow_message_deletion":"sample allow message deletion","capture_view_once":"sample capture view once","sender_name_type":"friendly","auto_resolve_config":{"mode":"custom","after":60,"message":null,"label":null,"allow_waiting":false},"outbound_agent_name_header_policy":"sample outbound agent name header policy","agent_bot_working_hours_mode":"always","business_name":"sample business name","responder_policy":"sample responder policy","help_center":{"name":"Sample Name","slug":"sample-slug"},"tweets_enabled":true,"allowed_domains":"sample allowed domains","widget_color":"#1F93FF","website_url":"https://example.com/resource","hmac_mandatory":"sample hmac mandatory","welcome_title":"sample welcome title","welcome_tagline":"sample welcome tagline","web_widget_script":"sample web widget script","website_token":"sample-token","selected_feature_flags":"sample selected feature flags","reply_time":"2026-01-15T10:30:00.000Z","hmac_token":"sample-token","pre_chat_form_enabled":true,"pre_chat_form_options":"sample pre chat form options","continuity_via_email":"agent@example.com","page_id":1,"reauthorization_required":"sample reauthorization required","instagram_id":1,"messaging_service_sid":"sample messaging service sid","phone_number":"+5511999998888","medium":"sample medium","bandwidth_callback_state":"active","bandwidth_api_migration_state":"oauth2_configured","bandwidth_legacy_basic_deprecated":true,"content_templates":"sample content templates","auth_token":"sample-token","account_sid":"sample account sid","api_key_sid":"sample api key sid","twilio_credential_state":"ready","api_key_configured":true,"email":"agent@example.com","auth_method":"sample auth method","forwarding_enabled":true,"forward_to_email":"agent@example.com","branded_email_layout":"agent@example.com","imap_login":"sample imap login","imap_password":"sample imap password","imap_address":"sample imap address","imap_port":"sample imap port","imap_enabled":true,"imap_enable_ssl":"sample imap enable ssl","imap_authentication":"sample imap authentication","smtp_login":"sample smtp login","smtp_password":"sample smtp password","smtp_address":"sample smtp address","smtp_port":"sample smtp port","smtp_enabled":true,"smtp_domain":"sample smtp domain","smtp_enable_ssl_tls":"sample smtp enable ssl tls","smtp_enable_starttls_auto":"sample smtp enable starttls auto","smtp_openssl_verify_mode":"none","smtp_authentication":"sample smtp authentication","secret":"sample-token","webhook_url":"https://example.com/resource","inbox_identifier":"sample inbox identifier","additional_attributes":{},"provider":"sample provider","bot_name":"sample bot name","message_templates":true,"provider_config":"sample provider config","business_management_token_configured":true,"hybrid_pair":{"paired":true,"id":4,"role":"cloud","sibling_inbox_id":18,"canonical_phone":"+5521900000000","primary":"cloud","inbound_authority":"cloud","unified_inbox":true,"unified_state":{"state":"complete","scanned":42,"frozen":40,"reconciled_count":2,"completed_at":"2026-10-03T12:00:00.000Z","blocked_conversations":[]},"routing":{"outbound_default":"cloud","out_of_window":"web","fallback":true,"manual_override":true,"weighted":{"mode":"weighted","web_percent":30,"version":2}},"web_channel_id":12,"web_inbox_id":18,"calling_provider":"whatsapp_web","web_voice_enabled":true,"web_inbound_calls_enabled":true,"web_call_config_sync":{"state":"pending","checked_at":"2026-10-03T12:00:00.000Z"},"web_video_calls_enabled":false,"web_group_calls_enabled":false,"web_reauthorization_required":false,"web_session_state":{"state":"connected","fresh":true,"observed_at":"2026-10-03T12:00:00.000Z","disconnected_since":null},"web_allow_message_deletion":true},"whatsapp_web_session_state":{"state":"connected","fresh":true,"observed_at":"2026-01-15T10:30:00.000Z","disconnected_since":null},"hybrid_hidden":"sample hybrid hidden","logical_inbox_id":1,"whatsapp_pending_phone":{"awaiting_pair":true,"phone":"+5511999998888","reason":"same_account_same_provider","sibling_inbox_id":1,"source":"pair_success","at":"2026-01-15T10:30:00.000Z"},"whatsapp_sibling_notice":"sample whatsapp sibling notice","whatsapp_web_contact_request":"supported","voice_enabled":true,"inbound_calls_enabled":true,"voice_configured":true,"voice_call_webhook_url":"https://example.com/resource","voice_status_webhook_url":"https://example.com/resource"}],"meta":{"total_count":5,"page":"sample page"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"assistant_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."}]},"post":{"tags":["Captain"],"operationId":"auto_post_api_v1_accounts_account_id_captain_assistants_assistant_id_inboxes","summary":"Create inboxes","description":"Creates a new inbox from the request payload. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Captain assistant connected to the inbox.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/inbox"},"example":{"navigation_only":true,"id":1,"name":"Sample Name","website_url":"https://example.com/resource","channel_type":"Channel::Api","avatar_url":"https://example.com/resource","widget_color":"#1F93FF","website_token":"sample-token","enable_auto_assignment":true,"web_widget_script":"sample web widget script","welcome_title":"sample welcome title","welcome_tagline":"sample welcome tagline","greeting_enabled":true,"greeting_message":"sample greeting message","channel_id":1,"working_hours_enabled":true,"enable_email_collect":true,"csat_survey_enabled":true,"auto_assignment_config":{},"out_of_office_message":"sample out of office message","working_hours":[{"day_of_week":12.5,"closed_all_day":true,"open_hour":12.5,"open_minutes":12.5,"close_hour":12.5,"close_minutes":12.5,"open_all_day":true}],"timezone":"America/Sao_Paulo","callback_webhook_url":"https://example.com/resource","allow_messages_after_resolved":true,"lock_to_single_conversation":true,"sender_name_type":"friendly","auto_resolve_config":{"mode":"custom","after":30,"message":"We are closing this conversation due to inactivity.","label":"auto-resolved","allow_waiting":false},"outbound_agent_name_header_policy":"inherit","business_name":"sample business name","branded_email_layout":"agent@example.com","responder_policy":{"mode":"agent_bot","conflict":true},"hmac_mandatory":true,"selected_feature_flags":["sample selected feature flag"],"reply_time":"2026-01-15T10:30:00.000Z","messaging_service_sid":"sample messaging service sid","phone_number":"+5511999998888","bandwidth_callback_state":"active","bandwidth_api_migration_state":"oauth2_configured","medium":"sample medium","provider":"default","whatsapp_web_session_state":{"state":"connected","fresh":true,"observed_at":"2026-01-15T10:30:00.000Z","disconnected_since":null},"hybrid_pair":{"paired":true,"id":4,"role":"cloud","sibling_inbox_id":18,"canonical_phone":"+5521900000000","primary":"cloud","inbound_authority":"cloud","unified_inbox":true,"unified_state":{"state":"complete","scanned":42,"frozen":40,"reconciled_count":2,"completed_at":"2026-10-03T12:00:00.000Z","blocked_conversations":[]},"routing":{"outbound_default":"cloud","out_of_window":"web","fallback":true,"manual_override":true,"weighted":{"mode":"weighted","web_percent":30,"version":2}},"web_channel_id":12,"web_inbox_id":18,"calling_provider":"whatsapp_web","web_voice_enabled":true,"web_inbound_calls_enabled":true,"web_call_config_sync":{"state":"pending","checked_at":"2026-10-03T12:00:00.000Z"},"web_video_calls_enabled":false,"web_group_calls_enabled":false,"web_reauthorization_required":false,"web_session_state":{"state":"connected","fresh":true,"observed_at":"2026-10-03T12:00:00.000Z","disconnected_since":null},"web_allow_message_deletion":true}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"422":{"description":"The inbox binding request is incomplete or fails validation.","content":{"application/json":{"schema":{"oneOf":[{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","example":"param is missing or the value is empty: inbox"}}},{"type":"object","additionalProperties":false,"required":["message","attributes"],"properties":{"message":{"type":"string","example":"Name cannot be blank"},"attributes":{"type":"array","items":{"type":"string","example":"name"},"example":["name"]}}},{"type":"object","additionalProperties":false,"required":["error","message"],"properties":{"error":{"type":"string","enum":["explicit_choice_required","invalid_choice"]},"message":{"type":"string","example":"Choose which automated responder is allowed to reply in this inbox."}}}]},"example":{"error":"param is missing or the value is empty: inbox"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"assistant_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["inbox"],"properties":{"inbox":{"type":"object","additionalProperties":false,"required":["inbox_id"],"properties":{"inbox_id":{"type":"integer","minimum":1,"description":"Account-scoped inbox to connect to the Captain assistant."},"responder_mode":{"type":"string","enum":["captain"],"description":"Required when an AgentBot binding already exists; explicitly authorizes Captain to reply."}}}}},"example":{"inbox":{"inbox_id":1,"responder_mode":"captain"}}}}}}},"/api/v1/accounts/{account_id}/captain/assistants/{assistant_id}/inboxes/{inbox_id}":{"delete":{"tags":["Captain"],"operationId":"auto_delete_api_v1_accounts_account_id_captain_assistants_assistant_id_inboxes_inbox_id","summary":"Delete inboxes","description":"Deletes the inbox identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"204":{"description":"Success (no content)"},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"assistant_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"inbox_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/captain/assistants/{assistant_id}/scenarios":{"get":{"tags":["Captain"],"operationId":"auto_get_api_v1_accounts_account_id_captain_assistants_assistant_id_scenarios","summary":"List scenarios","description":"Returns the list of scenarios visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"title":{"type":"string"},"description":{"type":"string"},"instruction":{"type":"string"},"tools":{"type":"string"},"enabled":{"type":"boolean"},"assistant_id":{"type":"integer"},"account_id":{"type":"integer"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"assistant":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"}}}}}},"meta":{"type":"object","properties":{"total_count":{"type":"integer"},"page":{"type":"string"}}}}},"example":{"payload":[{"id":1,"title":"Sample title","description":"A short description.","instruction":"sample instruction","tools":"sample tools","enabled":true,"assistant_id":1,"account_id":1,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","assistant":{"id":1,"name":"Sample Name"}}],"meta":{"total_count":5,"page":"sample page"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"assistant_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."}]},"post":{"tags":["Captain"],"operationId":"auto_post_api_v1_accounts_account_id_captain_assistants_assistant_id_scenarios","summary":"Create scenarios","description":"Creates a new scenario from the request payload. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"title":{"type":"string"},"description":{"type":"string"},"instruction":{"type":"string"},"tools":{"type":"string"},"enabled":{"type":"boolean"},"assistant_id":{"type":"integer"},"account_id":{"type":"integer"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"assistant":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"}}}}},"example":{"id":1,"title":"Sample title","description":"A short description.","instruction":"sample instruction","tools":"sample tools","enabled":true,"assistant_id":1,"account_id":1,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","assistant":{"id":1,"name":"Sample Name"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"assistant_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"scenario":{"type":"object","properties":{"title":{"type":"string"},"description":{"type":"string"},"instruction":{"type":"string"},"enabled":{"type":"boolean"},"tools":{"type":"array","items":{"type":"string"}}},"required":["description","instruction","title"]}},"required":["scenario"]},"example":{"scenario":{"title":"Sample title","description":"A short description.","instruction":"sample instruction","enabled":true,"tools":["sample tool"]}}}}}}},"/api/v1/accounts/{account_id}/captain/assistants/{assistant_id}/scenarios/{id}":{"get":{"tags":["Captain"],"operationId":"auto_get_api_v1_accounts_account_id_captain_assistants_assistant_id_scenarios_id","summary":"Get scenarios","description":"Returns the scenario identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"title":{"type":"string"},"description":{"type":"string"},"instruction":{"type":"string"},"tools":{"type":"string"},"enabled":{"type":"boolean"},"assistant_id":{"type":"integer"},"account_id":{"type":"integer"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"assistant":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"}}}}},"example":{"id":1,"title":"Sample title","description":"A short description.","instruction":"sample instruction","tools":"sample tools","enabled":true,"assistant_id":1,"account_id":1,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","assistant":{"id":1,"name":"Sample Name"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"assistant_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]},"patch":{"tags":["Captain"],"operationId":"auto_patch_api_v1_accounts_account_id_captain_assistants_assistant_id_scenarios_id","summary":"Update scenarios","description":"Updates the scenario identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"title":{"type":"string"},"description":{"type":"string"},"instruction":{"type":"string"},"tools":{"type":"string"},"enabled":{"type":"boolean"},"assistant_id":{"type":"integer"},"account_id":{"type":"integer"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"assistant":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"}}}}},"example":{"id":1,"title":"Sample title","description":"A short description.","instruction":"sample instruction","tools":"sample tools","enabled":true,"assistant_id":1,"account_id":1,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","assistant":{"id":1,"name":"Sample Name"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"assistant_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"scenario":{"type":"object","properties":{"title":{"type":"string"},"description":{"type":"string"},"instruction":{"type":"string"},"enabled":{"type":"boolean"},"tools":{"type":"array","items":{"type":"string"}}}}},"required":["scenario"]},"example":{"scenario":{"title":"Sample title","description":"A short description.","instruction":"sample instruction","enabled":true,"tools":["sample tool"]}}}}}},"put":{"tags":["Captain"],"operationId":"auto_put_api_v1_accounts_account_id_captain_assistants_assistant_id_scenarios_id","summary":"Update scenarios","description":"Updates the scenario identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"title":{"type":"string"},"description":{"type":"string"},"instruction":{"type":"string"},"tools":{"type":"string"},"enabled":{"type":"boolean"},"assistant_id":{"type":"integer"},"account_id":{"type":"integer"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"assistant":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"}}}}},"example":{"id":1,"title":"Sample title","description":"A short description.","instruction":"sample instruction","tools":"sample tools","enabled":true,"assistant_id":1,"account_id":1,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","assistant":{"id":1,"name":"Sample Name"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"assistant_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"scenario":{"type":"object","properties":{"title":{"type":"string"},"description":{"type":"string"},"instruction":{"type":"string"},"enabled":{"type":"boolean"},"tools":{"type":"array","items":{"type":"string"}}}}},"required":["scenario"]},"example":{"scenario":{"title":"Sample title","description":"A short description.","instruction":"sample instruction","enabled":true,"tools":["sample tool"]}}}}}},"delete":{"tags":["Captain"],"operationId":"auto_delete_api_v1_accounts_account_id_captain_assistants_assistant_id_scenarios_id","summary":"Delete scenarios","description":"Deletes the scenario identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"204":{"description":"Success (no content)"},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"assistant_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/captain/assistants":{"get":{"tags":["Captain"],"operationId":"auto_get_api_v1_accounts_account_id_captain_assistants","summary":"List assistants","description":"Returns the list of assistants visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","properties":{"account_id":{"type":"integer"},"config":{"type":"string"},"created_at":{"type":"integer"},"description":{"type":"string"},"guardrails":{"type":"string"},"id":{"type":"integer"},"name":{"type":"string"},"response_guidelines":{"type":"string"},"updated_at":{"type":"integer"}}}},"meta":{"type":"object","properties":{"total_count":{"type":"integer"},"page":{"type":"string"}}}}},"example":{"payload":[{"account_id":1,"config":"sample config","created_at":1,"description":"A short description.","guardrails":"sample guardrails","id":1,"name":"Sample Name","response_guidelines":"sample response guidelines","updated_at":1}],"meta":{"total_count":5,"page":"sample page"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."}]},"post":{"tags":["Captain"],"operationId":"auto_post_api_v1_accounts_account_id_captain_assistants","summary":"Create assistants","description":"Creates a new assistant from the request payload. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"account_id":{"type":"integer"},"config":{"type":"string"},"created_at":{"type":"integer"},"description":{"type":"string"},"guardrails":{"type":"string"},"id":{"type":"integer"},"name":{"type":"string"},"response_guidelines":{"type":"string"},"updated_at":{"type":"integer"}}},"example":{"account_id":1,"config":"sample config","created_at":1,"description":"A short description.","guardrails":"sample guardrails","id":1,"name":"Sample Name","response_guidelines":"sample response guidelines","updated_at":1}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"assistant":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"config":{"type":"object","additionalProperties":true,"description":"Free-form object."}},"required":["description","name"]}},"required":["assistant"]},"example":{"assistant":{"name":"Sample Name","description":"A short description.","config":{}}}}}}}},"/api/v1/accounts/{account_id}/captain/assistants/{id}":{"get":{"tags":["Captain"],"operationId":"auto_get_api_v1_accounts_account_id_captain_assistants_id","summary":"Get assistants","description":"Returns the assistant identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"account_id":{"type":"integer"},"config":{"type":"string"},"created_at":{"type":"integer"},"description":{"type":"string"},"guardrails":{"type":"string"},"id":{"type":"integer"},"name":{"type":"string"},"response_guidelines":{"type":"string"},"updated_at":{"type":"integer"}}},"example":{"account_id":1,"config":"sample config","created_at":1,"description":"A short description.","guardrails":"sample guardrails","id":1,"name":"Sample Name","response_guidelines":"sample response guidelines","updated_at":1}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]},"patch":{"tags":["Captain"],"operationId":"auto_patch_api_v1_accounts_account_id_captain_assistants_id","summary":"Update assistants","description":"Updates the assistant identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"account_id":{"type":"integer"},"config":{"type":"string"},"created_at":{"type":"integer"},"description":{"type":"string"},"guardrails":{"type":"string"},"id":{"type":"integer"},"name":{"type":"string"},"response_guidelines":{"type":"string"},"updated_at":{"type":"integer"}}},"example":{"account_id":1,"config":"sample config","created_at":1,"description":"A short description.","guardrails":"sample guardrails","id":1,"name":"Sample Name","response_guidelines":"sample response guidelines","updated_at":1}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"assistant":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"config":{"type":"object","additionalProperties":true,"description":"Free-form object."}}}},"required":["assistant"]},"example":{"assistant":{"name":"Sample Name","description":"A short description.","config":{}}}}}}},"put":{"tags":["Captain"],"operationId":"auto_put_api_v1_accounts_account_id_captain_assistants_id","summary":"Update assistants","description":"Updates the assistant identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"account_id":{"type":"integer"},"config":{"type":"string"},"created_at":{"type":"integer"},"description":{"type":"string"},"guardrails":{"type":"string"},"id":{"type":"integer"},"name":{"type":"string"},"response_guidelines":{"type":"string"},"updated_at":{"type":"integer"}}},"example":{"account_id":1,"config":"sample config","created_at":1,"description":"A short description.","guardrails":"sample guardrails","id":1,"name":"Sample Name","response_guidelines":"sample response guidelines","updated_at":1}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"assistant":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"config":{"type":"object","additionalProperties":true,"description":"Free-form object."}}}},"required":["assistant"]},"example":{"assistant":{"name":"Sample Name","description":"A short description.","config":{}}}}}}},"delete":{"tags":["Captain"],"operationId":"auto_delete_api_v1_accounts_account_id_captain_assistants_id","summary":"Delete assistants","description":"Deletes the assistant identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"204":{"description":"Success (no content)"},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/captain/agent_sessions/{id}":{"get":{"tags":["Captain"],"operationId":"auto_get_api_v1_accounts_account_id_captain_agent_sessions_id","summary":"Get agent sessions","description":"Returns the agent session identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"message_id":{"type":"integer"},"llm_model":{"type":"string"},"credits_consumed":{"type":"string"},"run_context":{"type":"boolean"},"citations":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"title":{"type":"string"},"link":{"type":["boolean","null"]}}}},"used_faqs":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"title":{"type":"string"}}}},"scenarios":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"title":{"type":"string"}}}}}},"example":{"id":1,"message_id":1,"llm_model":"sample llm model","credits_consumed":"sample credits consumed","run_context":true,"citations":[{"id":1,"title":"Sample title","link":true}],"used_faqs":[{"id":1,"title":"Sample title"}],"scenarios":[{"id":1,"title":"Sample title"}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/captain/assistant_responses/{id}/drilldown":{"get":{"tags":["Captain"],"operationId":"auto_get_api_v1_accounts_account_id_captain_assistant_responses_id_drilldown","summary":"List the conversations where Captain used one approved answer","description":"Lists the conversations in which Captain delivered an answer while using this knowledge record, newest activity first and paginated. Only answers authored by a person can be drilled into — an answer generated from a document has no independent usage trail and returns 404, because the document's own drilldown is the authoritative one. Requires Captain (Enterprise).","security":[{"userApiKey":[]}],"responses":{"200":{"description":"One page of the conversations that used this answer.","content":{"application/json":{"schema":{"type":"object","properties":{"meta":{"type":"object","description":"Pagination over the whole usage set, not the loaded page.","properties":{"current_page":{"type":"integer","description":"The page returned.","example":1},"per_page":{"type":"integer","description":"Rows per page actually applied.","example":25},"total_count":{"type":"integer","description":"Total conversations across all pages.","example":63},"conversation_count":{"type":"integer","description":"Same total, named for the conversation drawer that renders it.","example":63}},"additionalProperties":false},"payload":{"type":"array","description":"The conversations on this page, most recently active first.","items":{"type":"object","description":"One drilled-down row, serialized by the shared reports drilldown serializer so the existing conversation cards render it unchanged.","properties":{"record_type":{"type":"string","description":"Kind of row. These drilldowns always list conversations; the shared serializer emits `message` only for message-derived report metrics.","enum":["conversation"],"example":"conversation"},"conversation":{"type":"object","description":"The conversation the row points at, with the participants and the latest non-activity message already resolved so a card can render without a second request.","properties":{"id":{"type":"integer","description":"Internal conversation id.","example":90211},"display_id":{"type":"integer","description":"Account-scoped conversation number shown in the dashboard URL.","example":4821},"contact_id":{"type":"integer","description":"Contact that opened the conversation.","example":55210},"contact_name":{"type":["string","null"],"description":"Contact display name; null when the contact has no name yet.","example":"Marina Duarte"},"inbox_id":{"type":"integer","description":"Inbox the conversation belongs to.","example":37},"inbox_name":{"type":["string","null"],"description":"Inbox display name; null when the inbox was deleted.","example":"WhatsApp Support"},"assignee_id":{"type":["integer","null"],"description":"Assigned agent id; null while unassigned.","example":12},"assignee_name":{"type":["string","null"],"description":"Assigned agent name; null while unassigned.","example":"Rafael Lima"},"status":{"type":"string","description":"Current conversation status.","enum":["open","resolved","pending","snoozed"],"example":"resolved"},"created_at":{"type":"integer","description":"Unix epoch seconds the conversation was created.","example":1778730000},"last_activity_at":{"type":"integer","description":"Unix epoch seconds of the last activity.","example":1778735498},"last_message":{"type":["object","null"],"description":"Newest non-activity message of the conversation; null when the conversation has only activity entries.","properties":{"id":{"type":"integer","description":"Message id.","example":771204},"content":{"type":["string","null"],"description":"Message text; null for an attachment-only message.","example":"Perfect, that solved it. Thanks!"},"message_type":{"type":"string","description":"Direction/kind of the message. Never `activity`: the newest non-activity message is the one resolved here.","enum":["incoming","outgoing","template"],"example":"incoming"},"sender_name":{"type":["string","null"],"description":"Display name of the sender; null when the sender was removed.","example":"Marina Duarte"},"created_at":{"type":"integer","description":"Unix epoch seconds the message was created.","example":1778735498}},"additionalProperties":false}},"additionalProperties":false},"message":{"type":["object","null"],"description":"Always null on these drilldowns — the cohort is a conversation list, not a per-message one. Kept in the contract because the shared serializer fills it for message-derived report metrics.","example":null,"properties":{"id":{"type":"integer","description":"Message id.","example":771204},"content":{"type":["string","null"],"description":"Message text.","example":"Perfect, that solved it. Thanks!"},"message_type":{"type":"string","description":"Direction/kind of the message.","enum":["incoming","outgoing","activity","template"],"example":"outgoing"},"sender_name":{"type":["string","null"],"description":"Display name of the sender.","example":"Support Assistant"},"created_at":{"type":"integer","description":"Unix epoch seconds the message was created.","example":1778735498}},"additionalProperties":false},"metric_value":{"type":["number","null"],"description":"Always null on these drilldowns: the row is a membership in a cohort, not a measured duration. Populated only for event-derived report metrics that carry a value.","example":null},"occurred_at":{"type":"integer","description":"Unix epoch seconds used to order the row — the conversation creation time for a conversation row.","example":1778730000}},"additionalProperties":false}}},"additionalProperties":false},"example":{"meta":{"current_page":1,"per_page":25,"total_count":63,"conversation_count":63},"payload":[{"record_type":"conversation","conversation":{"id":90211,"display_id":4821,"contact_id":55210,"contact_name":"Marina Duarte","inbox_id":37,"inbox_name":"WhatsApp Support","assignee_id":12,"assignee_name":"Rafael Lima","status":"resolved","created_at":1778730000,"last_activity_at":1778735498,"last_message":{"id":771204,"content":"Perfect, that solved it. Thanks!","message_type":"incoming","sender_name":"Marina Duarte","created_at":1778735498}},"message":null,"metric_value":null,"occurred_at":1778730000}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"1-based page number.","schema":{"type":"integer","minimum":1,"default":1,"example":1}},{"name":"per_page","in":"query","required":false,"description":"Rows per page. Defaults to 25; values above 100 are capped to 100.","schema":{"type":"integer","minimum":1,"maximum":100,"default":25,"example":25}}]}},"/api/v1/accounts/{account_id}/captain/assistant_responses":{"get":{"tags":["Captain"],"operationId":"auto_get_api_v1_accounts_account_id_captain_assistant_responses","summary":"List assistant responses","description":"Returns the list of assistant responses visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","properties":{"account_id":{"type":"integer"},"answer":{"type":"string"},"assistant":{"type":"object","properties":{"account_id":{"type":"integer"},"config":{"type":"string"},"created_at":{"type":"integer"},"description":{"type":"string"},"guardrails":{"type":"string"},"id":{"type":"integer"},"name":{"type":"string"},"response_guidelines":{"type":"string"},"updated_at":{"type":"integer"}}},"created_at":{"type":"integer"},"documentable":{"type":"object","properties":{"type":{"type":"string"},"id":{"type":"integer"},"external_link":{"type":"string"},"name":{"type":"string"},"display_id":{"type":"integer"},"email":{"type":"string","format":"email"},"available_name":{"type":"string"}}},"id":{"type":"integer"},"question":{"type":"string"},"updated_at":{"type":"integer"},"status":{"type":"string","enum":["approved"]},"edited":{"type":"string"}}}},"meta":{"type":"object","properties":{"total_count":{"type":"integer"},"page":{"type":"string"}}}}},"example":{"payload":[{"account_id":1,"answer":"sample answer","assistant":{"account_id":1,"config":"sample config","created_at":1,"description":"A short description.","guardrails":"sample guardrails","id":1,"name":"Sample Name","response_guidelines":"sample response guidelines","updated_at":1},"created_at":1,"documentable":{"type":"sample type","id":1,"external_link":"https://example.com/resource","name":"Sample Name","display_id":1,"email":"agent@example.com","available_name":"sample available name"},"id":1,"question":"sample question","updated_at":1,"status":"approved","edited":"sample edited"}],"meta":{"total_count":5,"page":"sample page"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."},{"name":"id","in":"query","required":false,"schema":{"type":"integer"}},{"name":"assistant_id","in":"query","required":false,"schema":{"type":"integer"}},{"name":"document_id","in":"query","required":false,"schema":{"type":"integer"}},{"name":"search","in":"query","required":false,"schema":{"type":"string"}}]},"post":{"tags":["Captain"],"operationId":"auto_post_api_v1_accounts_account_id_captain_assistant_responses","summary":"Create assistant responses","description":"Creates a new assistant respons from the request payload. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"account_id":{"type":"integer"},"answer":{"type":"string"},"assistant":{"type":"object","properties":{"account_id":{"type":"integer"},"config":{"type":"string"},"created_at":{"type":"integer"},"description":{"type":"string"},"guardrails":{"type":"string"},"id":{"type":"integer"},"name":{"type":"string"},"response_guidelines":{"type":"string"},"updated_at":{"type":"integer"}}},"created_at":{"type":"integer"},"documentable":{"type":"object","properties":{"type":{"type":"string"},"id":{"type":"integer"},"external_link":{"type":"string"},"name":{"type":"string"},"display_id":{"type":"integer"},"email":{"type":"string","format":"email"},"available_name":{"type":"string"}}},"id":{"type":"integer"},"question":{"type":"string"},"updated_at":{"type":"integer"},"status":{"type":"string","enum":["approved"]},"edited":{"type":"string"}}},"example":{"account_id":1,"answer":"sample answer","assistant":{"account_id":1,"config":"sample config","created_at":1,"description":"A short description.","guardrails":"sample guardrails","id":1,"name":"Sample Name","response_guidelines":"sample response guidelines","updated_at":1},"created_at":1,"documentable":{"type":"sample type","id":1,"external_link":"https://example.com/resource","name":"Sample Name","display_id":1,"email":"agent@example.com","available_name":"sample available name"},"id":1,"question":"sample question","updated_at":1,"status":"approved","edited":"sample edited"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"assistant_response":{"type":"object","properties":{"question":{"type":"string"},"answer":{"type":"string"},"assistant_id":{"type":"integer"}},"required":["answer","question"]}},"required":["assistant_response"]},"example":{"assistant_response":{"question":"sample question","answer":"sample answer","assistant_id":1}}}}}}},"/api/v1/accounts/{account_id}/captain/assistant_responses/{id}":{"get":{"tags":["Captain"],"operationId":"auto_get_api_v1_accounts_account_id_captain_assistant_responses_id","summary":"Get assistant responses","description":"Returns the assistant respons identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"account_id":{"type":"integer"},"answer":{"type":"string"},"assistant":{"type":"object","properties":{"account_id":{"type":"integer"},"config":{"type":"string"},"created_at":{"type":"integer"},"description":{"type":"string"},"guardrails":{"type":"string"},"id":{"type":"integer"},"name":{"type":"string"},"response_guidelines":{"type":"string"},"updated_at":{"type":"integer"}}},"created_at":{"type":"integer"},"documentable":{"type":"object","properties":{"type":{"type":"string"},"id":{"type":"integer"},"external_link":{"type":"string"},"name":{"type":"string"},"display_id":{"type":"integer"},"email":{"type":"string","format":"email"},"available_name":{"type":"string"}}},"id":{"type":"integer"},"question":{"type":"string"},"updated_at":{"type":"integer"},"status":{"type":"string","enum":["approved"]},"edited":{"type":"string"}}},"example":{"account_id":1,"answer":"sample answer","assistant":{"account_id":1,"config":"sample config","created_at":1,"description":"A short description.","guardrails":"sample guardrails","id":1,"name":"Sample Name","response_guidelines":"sample response guidelines","updated_at":1},"created_at":1,"documentable":{"type":"sample type","id":1,"external_link":"https://example.com/resource","name":"Sample Name","display_id":1,"email":"agent@example.com","available_name":"sample available name"},"id":1,"question":"sample question","updated_at":1,"status":"approved","edited":"sample edited"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]},"patch":{"tags":["Captain"],"operationId":"auto_patch_api_v1_accounts_account_id_captain_assistant_responses_id","summary":"Update assistant responses","description":"Updates the assistant respons identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"account_id":{"type":"integer"},"answer":{"type":"string"},"assistant":{"type":"object","properties":{"account_id":{"type":"integer"},"config":{"type":"string"},"created_at":{"type":"integer"},"description":{"type":"string"},"guardrails":{"type":"string"},"id":{"type":"integer"},"name":{"type":"string"},"response_guidelines":{"type":"string"},"updated_at":{"type":"integer"}}},"created_at":{"type":"integer"},"documentable":{"type":"object","properties":{"type":{"type":"string"},"id":{"type":"integer"},"external_link":{"type":"string"},"name":{"type":"string"},"display_id":{"type":"integer"},"email":{"type":"string","format":"email"},"available_name":{"type":"string"}}},"id":{"type":"integer"},"question":{"type":"string"},"updated_at":{"type":"integer"},"status":{"type":"string","enum":["approved"]},"edited":{"type":"string"}}},"example":{"account_id":1,"answer":"sample answer","assistant":{"account_id":1,"config":"sample config","created_at":1,"description":"A short description.","guardrails":"sample guardrails","id":1,"name":"Sample Name","response_guidelines":"sample response guidelines","updated_at":1},"created_at":1,"documentable":{"type":"sample type","id":1,"external_link":"https://example.com/resource","name":"Sample Name","display_id":1,"email":"agent@example.com","available_name":"sample available name"},"id":1,"question":"sample question","updated_at":1,"status":"approved","edited":"sample edited"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"assistant_response":{"type":"object","properties":{"question":{"type":"string"},"answer":{"type":"string"},"assistant_id":{"type":"integer"}}}},"required":["assistant_response"]},"example":{"assistant_response":{"question":"sample question","answer":"sample answer","assistant_id":1}}}}}},"put":{"tags":["Captain"],"operationId":"auto_put_api_v1_accounts_account_id_captain_assistant_responses_id","summary":"Update assistant responses","description":"Updates the assistant respons identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"account_id":{"type":"integer"},"answer":{"type":"string"},"assistant":{"type":"object","properties":{"account_id":{"type":"integer"},"config":{"type":"string"},"created_at":{"type":"integer"},"description":{"type":"string"},"guardrails":{"type":"string"},"id":{"type":"integer"},"name":{"type":"string"},"response_guidelines":{"type":"string"},"updated_at":{"type":"integer"}}},"created_at":{"type":"integer"},"documentable":{"type":"object","properties":{"type":{"type":"string"},"id":{"type":"integer"},"external_link":{"type":"string"},"name":{"type":"string"},"display_id":{"type":"integer"},"email":{"type":"string","format":"email"},"available_name":{"type":"string"}}},"id":{"type":"integer"},"question":{"type":"string"},"updated_at":{"type":"integer"},"status":{"type":"string","enum":["approved"]},"edited":{"type":"string"}}},"example":{"account_id":1,"answer":"sample answer","assistant":{"account_id":1,"config":"sample config","created_at":1,"description":"A short description.","guardrails":"sample guardrails","id":1,"name":"Sample Name","response_guidelines":"sample response guidelines","updated_at":1},"created_at":1,"documentable":{"type":"sample type","id":1,"external_link":"https://example.com/resource","name":"Sample Name","display_id":1,"email":"agent@example.com","available_name":"sample available name"},"id":1,"question":"sample question","updated_at":1,"status":"approved","edited":"sample edited"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"assistant_response":{"type":"object","properties":{"question":{"type":"string"},"answer":{"type":"string"},"assistant_id":{"type":"integer"}}}},"required":["assistant_response"]},"example":{"assistant_response":{"question":"sample question","answer":"sample answer","assistant_id":1}}}}}},"delete":{"tags":["Captain"],"operationId":"auto_delete_api_v1_accounts_account_id_captain_assistant_responses_id","summary":"Delete assistant responses","description":"Deletes the assistant respons identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"204":{"description":"Success (no content)"},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/captain/faq_suggestions/{id}/approve":{"post":{"tags":["Captain"],"operationId":"auto_post_api_v1_accounts_account_id_captain_faq_suggestions_id_approve","summary":"Approve faq suggestions","description":"Performs the approve operation on the targeted faq suggestion resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"account_id":{"type":"integer"},"answer":{"type":"string"},"assistant":{"type":"object","properties":{"account_id":{"type":"integer"},"config":{"type":"string"},"created_at":{"type":"integer"},"description":{"type":"string"},"guardrails":{"type":"string"},"id":{"type":"integer"},"name":{"type":"string"},"response_guidelines":{"type":"string"},"updated_at":{"type":"integer"}}},"created_at":{"type":"integer"},"documentable":{"type":"object","properties":{"type":{"type":"string"},"id":{"type":"integer"},"external_link":{"type":"string"},"name":{"type":"string"},"display_id":{"type":"integer"},"email":{"type":"string","format":"email"},"available_name":{"type":"string"}}},"id":{"type":"integer"},"question":{"type":"string"},"updated_at":{"type":"integer"},"status":{"type":"string","enum":["approved"]},"edited":{"type":"string"}}},"example":{"account_id":1,"answer":"sample answer","assistant":{"account_id":1,"config":"sample config","created_at":1,"description":"A short description.","guardrails":"sample guardrails","id":1,"name":"Sample Name","response_guidelines":"sample response guidelines","updated_at":1},"created_at":1,"documentable":{"type":"sample type","id":1,"external_link":"https://example.com/resource","name":"Sample Name","display_id":1,"email":"agent@example.com","available_name":"sample available name"},"id":1,"question":"sample question","updated_at":1,"status":"approved","edited":"sample edited"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"faq_suggestion":{"type":"object","properties":{"question":{"type":"string"},"answer":{"type":"string"}}}},"required":["faq_suggestion"]},"example":{"faq_suggestion":{"question":"sample question","answer":"sample answer"}}}}}}},"/api/v1/accounts/{account_id}/captain/faq_suggestions/{id}/dismiss":{"post":{"tags":["Captain"],"operationId":"auto_post_api_v1_accounts_account_id_captain_faq_suggestions_id_dismiss","summary":"Dismiss faq suggestions","description":"Performs the dismiss operation on the targeted faq suggestion resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"question":{"type":"string"},"answer":{"type":"string"},"language":{"type":"string"},"source_count":{"type":"integer"},"status":{"type":"string","enum":["open","approved","dismissed"]},"created_at":{"type":"integer"},"updated_at":{"type":"integer"},"assistant":{"type":"object","properties":{"account_id":{"type":"integer"},"config":{"type":"string"},"created_at":{"type":"integer"},"description":{"type":"string"},"guardrails":{"type":"string"},"id":{"type":"integer"},"name":{"type":"string"},"response_guidelines":{"type":"string"},"updated_at":{"type":"integer"}}}}},"example":{"id":1,"account_id":1,"question":"sample question","answer":"sample answer","language":"en","source_count":5,"status":"open","created_at":1,"updated_at":1,"assistant":{"account_id":1,"config":"sample config","created_at":1,"description":"A short description.","guardrails":"sample guardrails","id":1,"name":"Sample Name","response_guidelines":"sample response guidelines","updated_at":1}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/captain/faq_suggestions":{"get":{"tags":["Captain"],"operationId":"auto_get_api_v1_accounts_account_id_captain_faq_suggestions","summary":"List faq suggestions","description":"Returns the list of faq suggestions visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"question":{"type":"string"},"answer":{"type":"string"},"language":{"type":"string"},"source_count":{"type":"integer"},"status":{"type":"string","enum":["open","approved","dismissed"]},"created_at":{"type":"integer"},"updated_at":{"type":"integer"},"assistant":{"type":"object","properties":{"account_id":{"type":"integer"},"config":{"type":"string"},"created_at":{"type":"integer"},"description":{"type":"string"},"guardrails":{"type":"string"},"id":{"type":"integer"},"name":{"type":"string"},"response_guidelines":{"type":"string"},"updated_at":{"type":"integer"}}}}}},"meta":{"type":"object","properties":{"total_count":{"type":"integer"},"page":{"type":"string"}}}}},"example":{"payload":[{"id":1,"account_id":1,"question":"sample question","answer":"sample answer","language":"en","source_count":5,"status":"open","created_at":1,"updated_at":1,"assistant":{"account_id":1,"config":"sample config","created_at":1,"description":"A short description.","guardrails":"sample guardrails","id":1,"name":"Sample Name","response_guidelines":"sample response guidelines","updated_at":1}}],"meta":{"total_count":5,"page":"sample page"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."},{"name":"id","in":"query","required":false,"schema":{"type":"integer"}},{"name":"assistant_id","in":"query","required":false,"schema":{"type":"integer"}},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["open","approved","dismissed"]}},{"name":"search","in":"query","required":false,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/captain/faq_suggestions/{id}":{"get":{"tags":["Captain"],"operationId":"auto_get_api_v1_accounts_account_id_captain_faq_suggestions_id","summary":"Get faq suggestions","description":"Returns the faq suggestion identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"question":{"type":"string"},"answer":{"type":"string"},"language":{"type":"string"},"source_count":{"type":"integer"},"status":{"type":"string","enum":["open","approved","dismissed"]},"created_at":{"type":"integer"},"updated_at":{"type":"integer"},"assistant":{"type":"object","properties":{"account_id":{"type":"integer"},"config":{"type":"string"},"created_at":{"type":"integer"},"description":{"type":"string"},"guardrails":{"type":"string"},"id":{"type":"integer"},"name":{"type":"string"},"response_guidelines":{"type":"string"},"updated_at":{"type":"integer"}}},"observations":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"generated_question":{"type":"string"},"generated_answer":{"type":"string"},"language":{"type":"string"},"status":{"type":"string","enum":["attached","discarded"]},"created_at":{"type":"integer"},"conversation":{"type":"object","properties":{"id":{"type":"integer"},"display_id":{"type":"integer"}}}}}}}},"example":{"id":1,"account_id":1,"question":"sample question","answer":"sample answer","language":"en","source_count":5,"status":"open","created_at":1,"updated_at":1,"assistant":{"account_id":1,"config":"sample config","created_at":1,"description":"A short description.","guardrails":"sample guardrails","id":1,"name":"Sample Name","response_guidelines":"sample response guidelines","updated_at":1},"observations":[{"id":1,"generated_question":"sample generated question","generated_answer":"sample generated answer","language":"en","status":"attached","created_at":1,"conversation":{"id":1,"display_id":1}}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]},"patch":{"tags":["Captain"],"operationId":"auto_patch_api_v1_accounts_account_id_captain_faq_suggestions_id","summary":"Update faq suggestions","description":"Updates the faq suggestion identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"question":{"type":"string"},"answer":{"type":"string"},"language":{"type":"string"},"source_count":{"type":"integer"},"status":{"type":"string","enum":["open","approved","dismissed"]},"created_at":{"type":"integer"},"updated_at":{"type":"integer"},"assistant":{"type":"object","properties":{"account_id":{"type":"integer"},"config":{"type":"string"},"created_at":{"type":"integer"},"description":{"type":"string"},"guardrails":{"type":"string"},"id":{"type":"integer"},"name":{"type":"string"},"response_guidelines":{"type":"string"},"updated_at":{"type":"integer"}}}}},"example":{"id":1,"account_id":1,"question":"sample question","answer":"sample answer","language":"en","source_count":5,"status":"open","created_at":1,"updated_at":1,"assistant":{"account_id":1,"config":"sample config","created_at":1,"description":"A short description.","guardrails":"sample guardrails","id":1,"name":"Sample Name","response_guidelines":"sample response guidelines","updated_at":1}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"faq_suggestion":{"type":"object","properties":{"question":{"type":"string"},"answer":{"type":"string"}}}},"required":["faq_suggestion"]},"example":{"faq_suggestion":{"question":"sample question","answer":"sample answer"}}}}}},"put":{"tags":["Captain"],"operationId":"auto_put_api_v1_accounts_account_id_captain_faq_suggestions_id","summary":"Update faq suggestions","description":"Updates the faq suggestion identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"question":{"type":"string"},"answer":{"type":"string"},"language":{"type":"string"},"source_count":{"type":"integer"},"status":{"type":"string","enum":["open","approved","dismissed"]},"created_at":{"type":"integer"},"updated_at":{"type":"integer"},"assistant":{"type":"object","properties":{"account_id":{"type":"integer"},"config":{"type":"string"},"created_at":{"type":"integer"},"description":{"type":"string"},"guardrails":{"type":"string"},"id":{"type":"integer"},"name":{"type":"string"},"response_guidelines":{"type":"string"},"updated_at":{"type":"integer"}}}}},"example":{"id":1,"account_id":1,"question":"sample question","answer":"sample answer","language":"en","source_count":5,"status":"open","created_at":1,"updated_at":1,"assistant":{"account_id":1,"config":"sample config","created_at":1,"description":"A short description.","guardrails":"sample guardrails","id":1,"name":"Sample Name","response_guidelines":"sample response guidelines","updated_at":1}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"faq_suggestion":{"type":"object","properties":{"question":{"type":"string"},"answer":{"type":"string"}}}},"required":["faq_suggestion"]},"example":{"faq_suggestion":{"question":"sample question","answer":"sample answer"}}}}}}},"/api/v1/accounts/{account_id}/captain/message_reports":{"post":{"tags":["Captain"],"operationId":"auto_post_api_v1_accounts_account_id_captain_message_reports","summary":"Create message reports","description":"Creates a new message report from the request payload. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"message_id":{"type":"integer"},"conversation_id":{"type":"integer"},"user_id":{"type":"integer"},"report_reason":{"type":"string","enum":["incorrect_information","inappropriate_response","incomplete_response","outdated_information","other"]},"description":{"type":"string"},"created_at":{"type":"integer"}}},"example":{"id":1,"message_id":1,"conversation_id":1,"user_id":1,"report_reason":"incorrect_information","description":"A short description.","created_at":1}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"message_id":{"type":"integer"},"report_reason":{"type":"string","enum":["incorrect_information","inappropriate_response","incomplete_response","outdated_information","other"]},"description":{"type":"string"}},"required":["report_reason"]},"example":{"message_id":1,"report_reason":"incorrect_information","description":"A short description."}}}}}},"/api/v1/accounts/{account_id}/captain/bulk_actions":{"post":{"tags":["Captain"],"operationId":"auto_post_api_v1_accounts_account_id_captain_bulk_actions","summary":"Create bulk actions","description":"Creates a new bulk action from the request payload. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"account_id":{"type":"integer"},"answer":{"type":"string"},"assistant":{"type":"object","properties":{"account_id":{"type":"integer"},"config":{"type":"string"},"created_at":{"type":"integer"},"description":{"type":"string"},"guardrails":{"type":"string"},"id":{"type":"integer"},"name":{"type":"string"},"response_guidelines":{"type":"string"},"updated_at":{"type":"integer"}}},"created_at":{"type":"integer"},"documentable":{"type":"object","properties":{"type":{"type":"string"},"id":{"type":"integer"},"external_link":{"type":"string"},"name":{"type":"string"},"display_id":{"type":"integer"},"email":{"type":"string","format":"email"},"available_name":{"type":"string"}}},"id":{"type":"integer"},"question":{"type":"string"},"updated_at":{"type":"integer"},"status":{"type":"string","enum":["approved"]},"edited":{"type":"string"}}}},"example":[{"account_id":1,"answer":"sample answer","assistant":{"account_id":1,"config":"sample config","created_at":1,"description":"A short description.","guardrails":"sample guardrails","id":1,"name":"Sample Name","response_guidelines":"sample response guidelines","updated_at":1},"created_at":1,"documentable":{"type":"sample type","id":1,"external_link":"https://example.com/resource","name":"Sample Name","display_id":1,"email":"agent@example.com","available_name":"sample available name"},"id":1,"question":"sample question","updated_at":1,"status":"approved","edited":"sample edited"}]}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"ids":{"type":"array","items":{"type":"string"}},"fields":{"type":"object","properties":{"status":{"type":"string","enum":["open","resolved","pending","snoozed"],"description":"Conversation status to apply in the bulk action."}}}}},"example":{"type":"sample type","ids":["sample id"],"fields":{"status":"open"}}}}}}},"/api/v1/accounts/{account_id}/captain/copilot_threads/{copilot_thread_id}/copilot_messages":{"get":{"tags":["Captain"],"operationId":"auto_get_api_v1_accounts_account_id_captain_copilot_threads_copilot_thread_id_copilot_messages","summary":"List a copilot thread's messages (one bounded page)","description":"Returns one bounded page of a Captain copilot thread's messages, ordered oldest-first within the page. The newest page is returned by default; pass page=2,3,... to walk older messages (the panel's scroll-to-top infinite loader). The per_page query parameter sizes the page (default 25, capped at 100 for safety). meta.count is the authoritative count of the WHOLE thread (not the loaded page) and meta.has_more is true while older pages remain. Requires Captain (Enterprise); the thread must belong to the current user.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"One bounded page of messages plus the authoritative whole-thread meta.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","description":"The messages on this page, ordered oldest-first.","items":{"type":"object","properties":{"id":{"type":"integer","description":"Message id.","example":8891},"message":{"type":"object","description":"The message body. Keys vary by message_type: user/assistant carry content; assistant_thinking may carry reasoning and function_name; an assistant reply may carry reply_suggestion.","properties":{"content":{"type":"string","description":"The user/assistant message text.","example":"How do I reset my password?"},"reasoning":{"type":"string","description":"Assistant thinking step (assistant_thinking only).","example":"Looking up the account's password policy."},"function_name":{"type":"string","description":"Tool invoked during a thinking step.","example":"search_articles"},"reply_suggestion":{"type":"string","description":"A suggested reply the agent can insert into the reply box.","example":"You can reset it from Settings \u003e Security."}},"additionalProperties":false},"message_type":{"type":"string","description":"Author/kind of the message.","enum":["user","assistant","assistant_thinking"],"example":"assistant"},"created_at":{"type":"integer","description":"Unix epoch seconds of creation.","example":1778735498},"account_id":{"type":"integer","description":"Owning account id.","example":1},"copilot_thread":{"type":"object","description":"The parent thread's push payload.","properties":{"id":{"type":"integer","description":"Thread id.","example":42},"title":{"type":"string","description":"Thread title (the first user message).","example":"Password reset help"},"created_at":{"type":"integer","description":"Unix epoch seconds the thread was created.","example":1778730000},"account_id":{"type":"integer","description":"Owning account id.","example":1},"user":{"type":"object","description":"The thread owner's public profile (id, name, avatar_url, availability_status).","additionalProperties":true}},"additionalProperties":true}}}},"meta":{"type":"object","description":"Authoritative whole-thread pagination (never the loaded page size).","properties":{"count":{"type":"integer","description":"Total messages in the WHOLE thread (the entire set, not this page).","example":484},"current_page":{"type":"integer","description":"The page number returned.","example":1},"has_more":{"type":"boolean","description":"True while older pages remain to be loaded.","example":true}}}}},"example":{"payload":[{"id":8891,"message":{"content":"How do I reset my password?","reasoning":"Looking up the account's password policy.","function_name":"search_articles","reply_suggestion":"You can reset it from Settings \u003e Security."},"message_type":"assistant","created_at":1778735498,"account_id":1,"copilot_thread":{"id":42,"title":"Password reset help","created_at":1778730000,"account_id":1,"user":{}}}],"meta":{"count":484,"current_page":1,"has_more":true}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"copilot_thread_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"1-based page number. Page 1 is the newest messages; higher pages are older.","schema":{"type":"integer","minimum":1,"default":1,"example":1}},{"name":"per_page","in":"query","required":false,"description":"Messages per page. Defaults to 25; values above 100 are capped to 100.","schema":{"type":"integer","minimum":1,"maximum":100,"default":25,"example":25}}]},"post":{"tags":["Captain"],"operationId":"auto_post_api_v1_accounts_account_id_captain_copilot_threads_copilot_thread_id_copilot_messages","summary":"Create copilot messages","description":"Creates a new copilot message from the request payload. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"message":{"type":"string"},"message_type":{"type":"string","enum":["user","assistant","assistant_thinking"],"description":"Direction/kind of the message."},"created_at":{"type":"integer"},"copilot_thread":{"type":"string"},"account_id":{"type":"integer"}}},"example":{"id":1,"message":"Sample message text.","message_type":"user","created_at":1,"copilot_thread":"sample copilot thread","account_id":1}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"copilot_thread_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"conversation_id":{"type":"integer"}}},"example":{"message":"Sample message text.","conversation_id":1}}}}}},"/api/v1/accounts/{account_id}/captain/copilot_threads":{"get":{"tags":["Captain"],"operationId":"auto_get_api_v1_accounts_account_id_captain_copilot_threads","summary":"List copilot threads","description":"Returns the list of copilot threads visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"title":{"type":"string"},"created_at":{"type":"integer"},"user":{"type":"string"},"assistant":{"type":"string"},"account_id":{"type":"integer"}}}}}},"example":{"payload":[{"id":1,"title":"Sample title","created_at":1,"user":"sample user","assistant":"sample assistant","account_id":1}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."}]},"post":{"tags":["Captain"],"operationId":"auto_post_api_v1_accounts_account_id_captain_copilot_threads","summary":"Open a copilot thread with its first message","description":"Creates a copilot thread owned by the current user, stores the first user message, and queues the assistant turn. The thread title is that first message. When the account has no copilot responses left in its quota the thread is still created and answered with a limit notice instead of a generated reply. Passing request_type=reply_suggestion routes the turn to the reply-suggestion path, which requires conversation_id to reference a conversation the current user may access — otherwise the request is rejected with 404. Requires Captain (Enterprise).","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"title":{"type":"string"},"created_at":{"type":"integer"},"user":{"type":"string"},"assistant":{"type":"string"},"account_id":{"type":"integer"}}},"example":{"id":1,"title":"Sample title","created_at":1,"user":"sample user","assistant":"sample assistant","account_id":1}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["message","assistant_id"],"properties":{"message":{"type":"string","description":"First user message. Also becomes the thread title. Must not be blank.","example":"Why was this customer charged twice?"},"assistant_id":{"type":"integer","description":"Assistant that will answer the thread. Must belong to this account.","example":7},"conversation_id":{"type":"integer","description":"Account-scoped conversation number (the display id shown in the dashboard URL) the copilot should read as context. Required for request_type=reply_suggestion.","example":4821},"request_type":{"type":"string","description":"Special handling for the first turn. Omit it for an ordinary copilot question; reply_suggestion asks the copilot to draft a reply for the referenced conversation.","enum":["reply_suggestion"],"example":"reply_suggestion"}},"additionalProperties":false},"example":{"message":"Why was this customer charged twice?","assistant_id":7,"conversation_id":4821,"request_type":"reply_suggestion"}}}}}},"/api/v1/accounts/{account_id}/captain/custom_tools/test":{"post":{"tags":["Captain"],"operationId":"auto_post_api_v1_accounts_account_id_captain_custom_tools_test","summary":"Test custom tools","description":"Performs the test operation on the targeted custom tool resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"status":{"type":"integer","example":200},"body":{"type":"string"}}},{"type":"object","properties":{"error":{"type":"string"}}}]},"example":{"status":200,"body":"Sample body text."}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"custom_tool":{"type":"object","properties":{"title":{"type":"string"},"description":{"type":"string"},"endpoint_url":{"type":"string"},"http_method":{"type":"string","enum":["GET","POST"]},"request_template":{"type":"string"},"response_template":{"type":"string"},"auth_type":{"type":"string","enum":["none","bearer","basic","api_key"]},"enabled":{"type":"boolean"},"auth_config":{"type":"object","additionalProperties":true,"description":"Free-form object."},"param_schema":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Free-form object."}}}}},"required":["custom_tool"]},"example":{"custom_tool":{"title":"Sample title","description":"A short description.","endpoint_url":"https://example.com/resource","http_method":"GET","request_template":"sample request template","response_template":"sample response template","auth_type":"none","enabled":true,"auth_config":{},"param_schema":[{}]}}}}}}},"/api/v1/accounts/{account_id}/captain/custom_tools":{"get":{"tags":["Captain"],"operationId":"auto_get_api_v1_accounts_account_id_captain_custom_tools","summary":"List custom tools","description":"Returns the list of custom tools visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"slug":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"endpoint_url":{"type":"string"},"http_method":{"type":"string","enum":["GET","POST"]},"request_template":{"type":"string"},"response_template":{"type":"string"},"auth_type":{"type":"string","enum":["none","bearer","basic","api_key"]},"auth_config":{"type":"string"},"param_schema":{"type":"string"},"enabled":{"type":"boolean"},"account_id":{"type":"integer"},"created_at":{"type":"integer"},"updated_at":{"type":"integer"}}}},"meta":{"type":"object","properties":{"total_count":{"type":"integer"},"page":{"type":"string"}}}}},"example":{"payload":[{"id":1,"slug":"sample-slug","title":"Sample title","description":"A short description.","endpoint_url":"https://example.com/resource","http_method":"GET","request_template":"sample request template","response_template":"sample response template","auth_type":"none","auth_config":"sample auth config","param_schema":"sample param schema","enabled":true,"account_id":1,"created_at":1,"updated_at":1}],"meta":{"total_count":5,"page":"sample page"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."}]},"post":{"tags":["Captain"],"operationId":"auto_post_api_v1_accounts_account_id_captain_custom_tools","summary":"Create custom tools","description":"Creates a new custom tool from the request payload. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"slug":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"endpoint_url":{"type":"string"},"http_method":{"type":"string","enum":["GET","POST"]},"request_template":{"type":"string"},"response_template":{"type":"string"},"auth_type":{"type":"string","enum":["none","bearer","basic","api_key"]},"auth_config":{"type":"string"},"param_schema":{"type":"string"},"enabled":{"type":"boolean"},"account_id":{"type":"integer"},"created_at":{"type":"integer"},"updated_at":{"type":"integer"}}},"example":{"id":1,"slug":"sample-slug","title":"Sample title","description":"A short description.","endpoint_url":"https://example.com/resource","http_method":"GET","request_template":"sample request template","response_template":"sample response template","auth_type":"none","auth_config":"sample auth config","param_schema":"sample param schema","enabled":true,"account_id":1,"created_at":1,"updated_at":1}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"custom_tool":{"type":"object","properties":{"title":{"type":"string"},"description":{"type":"string"},"endpoint_url":{"type":"string"},"http_method":{"type":"string","enum":["GET","POST"]},"request_template":{"type":"string"},"response_template":{"type":"string"},"auth_type":{"type":"string","enum":["none","bearer","basic","api_key"]},"enabled":{"type":"boolean"},"auth_config":{"type":"object","additionalProperties":true,"description":"Free-form object."},"param_schema":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Free-form object."}}},"required":["endpoint_url","title"]}},"required":["custom_tool"]},"example":{"custom_tool":{"title":"Sample title","description":"A short description.","endpoint_url":"https://example.com/resource","http_method":"GET","request_template":"sample request template","response_template":"sample response template","auth_type":"none","enabled":true,"auth_config":{},"param_schema":[{}]}}}}}}},"/api/v1/accounts/{account_id}/captain/custom_tools/{id}":{"get":{"tags":["Captain"],"operationId":"auto_get_api_v1_accounts_account_id_captain_custom_tools_id","summary":"Get custom tools","description":"Returns the custom tool identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"slug":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"endpoint_url":{"type":"string"},"http_method":{"type":"string","enum":["GET","POST"]},"request_template":{"type":"string"},"response_template":{"type":"string"},"auth_type":{"type":"string","enum":["none","bearer","basic","api_key"]},"auth_config":{"type":"string"},"param_schema":{"type":"string"},"enabled":{"type":"boolean"},"account_id":{"type":"integer"},"created_at":{"type":"integer"},"updated_at":{"type":"integer"}}},"example":{"id":1,"slug":"sample-slug","title":"Sample title","description":"A short description.","endpoint_url":"https://example.com/resource","http_method":"GET","request_template":"sample request template","response_template":"sample response template","auth_type":"none","auth_config":"sample auth config","param_schema":"sample param schema","enabled":true,"account_id":1,"created_at":1,"updated_at":1}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]},"patch":{"tags":["Captain"],"operationId":"auto_patch_api_v1_accounts_account_id_captain_custom_tools_id","summary":"Update custom tools","description":"Updates the custom tool identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"slug":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"endpoint_url":{"type":"string"},"http_method":{"type":"string","enum":["GET","POST"]},"request_template":{"type":"string"},"response_template":{"type":"string"},"auth_type":{"type":"string","enum":["none","bearer","basic","api_key"]},"auth_config":{"type":"string"},"param_schema":{"type":"string"},"enabled":{"type":"boolean"},"account_id":{"type":"integer"},"created_at":{"type":"integer"},"updated_at":{"type":"integer"}}},"example":{"id":1,"slug":"sample-slug","title":"Sample title","description":"A short description.","endpoint_url":"https://example.com/resource","http_method":"GET","request_template":"sample request template","response_template":"sample response template","auth_type":"none","auth_config":"sample auth config","param_schema":"sample param schema","enabled":true,"account_id":1,"created_at":1,"updated_at":1}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"custom_tool":{"type":"object","properties":{"title":{"type":"string"},"description":{"type":"string"},"endpoint_url":{"type":"string"},"http_method":{"type":"string","enum":["GET","POST"]},"request_template":{"type":"string"},"response_template":{"type":"string"},"auth_type":{"type":"string","enum":["none","bearer","basic","api_key"]},"enabled":{"type":"boolean"},"auth_config":{"type":"object","additionalProperties":true,"description":"Free-form object."},"param_schema":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Free-form object."}}}}},"required":["custom_tool"]},"example":{"custom_tool":{"title":"Sample title","description":"A short description.","endpoint_url":"https://example.com/resource","http_method":"GET","request_template":"sample request template","response_template":"sample response template","auth_type":"none","enabled":true,"auth_config":{},"param_schema":[{}]}}}}}},"put":{"tags":["Captain"],"operationId":"auto_put_api_v1_accounts_account_id_captain_custom_tools_id","summary":"Update custom tools","description":"Updates the custom tool identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"slug":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"endpoint_url":{"type":"string"},"http_method":{"type":"string","enum":["GET","POST"]},"request_template":{"type":"string"},"response_template":{"type":"string"},"auth_type":{"type":"string","enum":["none","bearer","basic","api_key"]},"auth_config":{"type":"string"},"param_schema":{"type":"string"},"enabled":{"type":"boolean"},"account_id":{"type":"integer"},"created_at":{"type":"integer"},"updated_at":{"type":"integer"}}},"example":{"id":1,"slug":"sample-slug","title":"Sample title","description":"A short description.","endpoint_url":"https://example.com/resource","http_method":"GET","request_template":"sample request template","response_template":"sample response template","auth_type":"none","auth_config":"sample auth config","param_schema":"sample param schema","enabled":true,"account_id":1,"created_at":1,"updated_at":1}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"custom_tool":{"type":"object","properties":{"title":{"type":"string"},"description":{"type":"string"},"endpoint_url":{"type":"string"},"http_method":{"type":"string","enum":["GET","POST"]},"request_template":{"type":"string"},"response_template":{"type":"string"},"auth_type":{"type":"string","enum":["none","bearer","basic","api_key"]},"enabled":{"type":"boolean"},"auth_config":{"type":"object","additionalProperties":true,"description":"Free-form object."},"param_schema":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Free-form object."}}}}},"required":["custom_tool"]},"example":{"custom_tool":{"title":"Sample title","description":"A short description.","endpoint_url":"https://example.com/resource","http_method":"GET","request_template":"sample request template","response_template":"sample response template","auth_type":"none","enabled":true,"auth_config":{},"param_schema":[{}]}}}}}},"delete":{"tags":["Captain"],"operationId":"auto_delete_api_v1_accounts_account_id_captain_custom_tools_id","summary":"Delete custom tools","description":"Deletes the custom tool identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"204":{"description":"Success (no content)"},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/captain/documents/{id}/sync":{"post":{"tags":["Captain"],"operationId":"auto_post_api_v1_accounts_account_id_captain_documents_id_sync","summary":"Re-crawl a knowledge document","description":"Marks the document as syncing, clears the previous failure and queues the crawl that fetches the source again and rebuilds what was derived from it. The work happens in the background, so the call answers `202 Accepted` with an EMPTY body — poll the document to follow its sync status. Only a document that finished processing and has a re-fetchable source can be synced: an uploaded PDF has no source to fetch again.","security":[{"userApiKey":[]}],"responses":{"202":{"description":"Crawl queued. Empty body — the sync status changes asynchronously."},"401":{"description":"Unauthorized"},"404":{"description":"No knowledge document with this id exists in the account."},"422":{"description":"The document cannot be synced: it is a file upload rather than a fetchable source, or it has not finished its initial processing yet.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable reason, localized to the account language."}}},"example":{"error":"Sync is not supported for PDF documents"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/captain/documents/{id}/drilldown":{"get":{"tags":["Captain"],"operationId":"auto_get_api_v1_accounts_account_id_captain_documents_id_drilldown","summary":"List the conversations where Captain used one document","description":"Lists the conversations in which Captain delivered an answer while using this document, newest activity first and paginated. The same count backs the usage badge on the document list, so the drawer and the badge always agree. Requires Captain (Enterprise).","security":[{"userApiKey":[]}],"responses":{"200":{"description":"One page of the conversations that used this document.","content":{"application/json":{"schema":{"type":"object","properties":{"meta":{"type":"object","description":"Pagination over the whole usage set, not the loaded page.","properties":{"current_page":{"type":"integer","description":"The page returned.","example":1},"per_page":{"type":"integer","description":"Rows per page actually applied.","example":25},"total_count":{"type":"integer","description":"Total conversations across all pages.","example":118},"conversation_count":{"type":"integer","description":"Same total, named for the conversation drawer that renders it.","example":118}},"additionalProperties":false},"payload":{"type":"array","description":"The conversations on this page, most recently active first.","items":{"type":"object","description":"One drilled-down row, serialized by the shared reports drilldown serializer so the existing conversation cards render it unchanged.","properties":{"record_type":{"type":"string","description":"Kind of row. These drilldowns always list conversations; the shared serializer emits `message` only for message-derived report metrics.","enum":["conversation"],"example":"conversation"},"conversation":{"type":"object","description":"The conversation the row points at, with the participants and the latest non-activity message already resolved so a card can render without a second request.","properties":{"id":{"type":"integer","description":"Internal conversation id.","example":90211},"display_id":{"type":"integer","description":"Account-scoped conversation number shown in the dashboard URL.","example":4821},"contact_id":{"type":"integer","description":"Contact that opened the conversation.","example":55210},"contact_name":{"type":["string","null"],"description":"Contact display name; null when the contact has no name yet.","example":"Marina Duarte"},"inbox_id":{"type":"integer","description":"Inbox the conversation belongs to.","example":37},"inbox_name":{"type":["string","null"],"description":"Inbox display name; null when the inbox was deleted.","example":"WhatsApp Support"},"assignee_id":{"type":["integer","null"],"description":"Assigned agent id; null while unassigned.","example":12},"assignee_name":{"type":["string","null"],"description":"Assigned agent name; null while unassigned.","example":"Rafael Lima"},"status":{"type":"string","description":"Current conversation status.","enum":["open","resolved","pending","snoozed"],"example":"resolved"},"created_at":{"type":"integer","description":"Unix epoch seconds the conversation was created.","example":1778730000},"last_activity_at":{"type":"integer","description":"Unix epoch seconds of the last activity.","example":1778735498},"last_message":{"type":["object","null"],"description":"Newest non-activity message of the conversation; null when the conversation has only activity entries.","properties":{"id":{"type":"integer","description":"Message id.","example":771204},"content":{"type":["string","null"],"description":"Message text; null for an attachment-only message.","example":"Perfect, that solved it. Thanks!"},"message_type":{"type":"string","description":"Direction/kind of the message. Never `activity`: the newest non-activity message is the one resolved here.","enum":["incoming","outgoing","template"],"example":"incoming"},"sender_name":{"type":["string","null"],"description":"Display name of the sender; null when the sender was removed.","example":"Marina Duarte"},"created_at":{"type":"integer","description":"Unix epoch seconds the message was created.","example":1778735498}},"additionalProperties":false}},"additionalProperties":false},"message":{"type":["object","null"],"description":"Always null on these drilldowns — the cohort is a conversation list, not a per-message one. Kept in the contract because the shared serializer fills it for message-derived report metrics.","example":null,"properties":{"id":{"type":"integer","description":"Message id.","example":771204},"content":{"type":["string","null"],"description":"Message text.","example":"Perfect, that solved it. Thanks!"},"message_type":{"type":"string","description":"Direction/kind of the message.","enum":["incoming","outgoing","activity","template"],"example":"outgoing"},"sender_name":{"type":["string","null"],"description":"Display name of the sender.","example":"Support Assistant"},"created_at":{"type":"integer","description":"Unix epoch seconds the message was created.","example":1778735498}},"additionalProperties":false},"metric_value":{"type":["number","null"],"description":"Always null on these drilldowns: the row is a membership in a cohort, not a measured duration. Populated only for event-derived report metrics that carry a value.","example":null},"occurred_at":{"type":"integer","description":"Unix epoch seconds used to order the row — the conversation creation time for a conversation row.","example":1778730000}},"additionalProperties":false}}},"additionalProperties":false},"example":{"meta":{"current_page":1,"per_page":25,"total_count":118,"conversation_count":118},"payload":[{"record_type":"conversation","conversation":{"id":90211,"display_id":4821,"contact_id":55210,"contact_name":"Marina Duarte","inbox_id":37,"inbox_name":"WhatsApp Support","assignee_id":12,"assignee_name":"Rafael Lima","status":"resolved","created_at":1778730000,"last_activity_at":1778735498,"last_message":{"id":771204,"content":"Perfect, that solved it. Thanks!","message_type":"incoming","sender_name":"Marina Duarte","created_at":1778735498}},"message":null,"metric_value":null,"occurred_at":1778730000}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"1-based page number.","schema":{"type":"integer","minimum":1,"default":1,"example":1}},{"name":"per_page","in":"query","required":false,"description":"Rows per page. Defaults to 25; values above 100 are capped to 100.","schema":{"type":"integer","minimum":1,"maximum":100,"default":25,"example":25}}]}},"/api/v1/accounts/{account_id}/captain/documents":{"get":{"tags":["Captain"],"operationId":"auto_get_api_v1_accounts_account_id_captain_documents","summary":"List documents","description":"Returns the list of documents visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","properties":{"account_id":{"type":"integer"},"assistant":{"type":"object","properties":{"account_id":{"type":"integer"},"config":{"type":"string"},"created_at":{"type":"integer"},"description":{"type":"string"},"guardrails":{"type":"string"},"id":{"type":"integer"},"name":{"type":"string"},"response_guidelines":{"type":"string"},"updated_at":{"type":"integer"}}},"content":{"type":"string"},"content_type":{"type":"string"},"created_at":{"type":"integer"},"external_link":{"type":"string"},"display_url":{"type":"string"},"file_size":{"type":"string"},"pdf_document":{"type":"boolean"},"responses_count":{"type":"integer"},"id":{"type":"integer"},"name":{"type":"string"},"status":{"type":"string","enum":["in_progress","available"]},"sync_status":{"type":"string","enum":["syncing","synced","failed"]},"sync_in_progress":{"type":"boolean"},"last_synced_at":{"type":["integer","null"]},"last_sync_attempted_at":{"type":["integer","null"]},"last_sync_error_code":{"type":"string"},"updated_at":{"type":"integer"}}}},"meta":{"type":"object","properties":{"total_count":{"type":"integer"},"page":{"type":"string"},"sync_interval_hours":{"type":"string"}}}}},"example":{"payload":[{"account_id":1,"assistant":{"account_id":1,"config":"sample config","created_at":1,"description":"A short description.","guardrails":"sample guardrails","id":1,"name":"Sample Name","response_guidelines":"sample response guidelines","updated_at":1},"content":"Sample content text.","content_type":"sample content type","created_at":1,"external_link":"https://example.com/resource","display_url":"https://example.com/resource","file_size":"sample file size","pdf_document":true,"responses_count":5,"id":1,"name":"Sample Name","status":"in_progress","sync_status":"syncing","sync_in_progress":true,"last_synced_at":1,"last_sync_attempted_at":1,"last_sync_error_code":"sample last sync error code","updated_at":1}],"meta":{"total_count":5,"page":"sample page","sync_interval_hours":"sample sync interval hours"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."},{"name":"assistant_id","in":"query","required":false,"schema":{"type":"integer"}},{"name":"id","in":"query","required":false,"schema":{"type":"integer"}},{"name":"filter","in":"query","required":false,"schema":{"type":"string"}},{"name":"source","in":"query","required":false,"schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"schema":{"type":"string"}},{"name":"search_key","in":"query","required":false,"schema":{"type":"string"}}]},"post":{"tags":["Captain"],"operationId":"auto_post_api_v1_accounts_account_id_captain_documents","summary":"Create documents","description":"Creates a new document from the request payload. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"account_id":{"type":"integer"},"assistant":{"type":"object","properties":{"account_id":{"type":"integer"},"config":{"type":"string"},"created_at":{"type":"integer"},"description":{"type":"string"},"guardrails":{"type":"string"},"id":{"type":"integer"},"name":{"type":"string"},"response_guidelines":{"type":"string"},"updated_at":{"type":"integer"}}},"content":{"type":"string"},"content_type":{"type":"string"},"created_at":{"type":"integer"},"external_link":{"type":"string"},"display_url":{"type":"string"},"file_size":{"type":"string"},"pdf_document":{"type":"boolean"},"responses_count":{"type":"integer"},"id":{"type":"integer"},"name":{"type":"string"},"status":{"type":"string","enum":["in_progress","available"]},"sync_status":{"type":"string","enum":["syncing","synced","failed"]},"sync_in_progress":{"type":"boolean"},"last_synced_at":{"type":["integer","null"]},"last_sync_attempted_at":{"type":["integer","null"]},"last_sync_error_code":{"type":"string"},"updated_at":{"type":"integer"}}},"example":{"account_id":1,"assistant":{"account_id":1,"config":"sample config","created_at":1,"description":"A short description.","guardrails":"sample guardrails","id":1,"name":"Sample Name","response_guidelines":"sample response guidelines","updated_at":1},"content":"Sample content text.","content_type":"sample content type","created_at":1,"external_link":"https://example.com/resource","display_url":"https://example.com/resource","file_size":"sample file size","pdf_document":true,"responses_count":5,"id":1,"name":"Sample Name","status":"in_progress","sync_status":"syncing","sync_in_progress":true,"last_synced_at":1,"last_sync_attempted_at":1,"last_sync_error_code":"sample last sync error code","updated_at":1}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"document":{"type":"object","properties":{"name":{"type":"string"},"external_link":{"type":"string"},"assistant_id":{"type":"integer"},"pdf_file":{"type":"string"}}}},"required":["document"]},"example":{"document":{"name":"Sample Name","external_link":"https://example.com/resource","assistant_id":1,"pdf_file":"sample pdf file"}}}}}}},"/api/v1/accounts/{account_id}/captain/documents/{id}":{"get":{"tags":["Captain"],"operationId":"auto_get_api_v1_accounts_account_id_captain_documents_id","summary":"Get documents","description":"Returns the document identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"account_id":{"type":"integer"},"assistant":{"type":"object","properties":{"account_id":{"type":"integer"},"config":{"type":"string"},"created_at":{"type":"integer"},"description":{"type":"string"},"guardrails":{"type":"string"},"id":{"type":"integer"},"name":{"type":"string"},"response_guidelines":{"type":"string"},"updated_at":{"type":"integer"}}},"content":{"type":"string"},"content_type":{"type":"string"},"created_at":{"type":"integer"},"external_link":{"type":"string"},"display_url":{"type":"string"},"file_size":{"type":"string"},"pdf_document":{"type":"boolean"},"responses_count":{"type":"integer"},"id":{"type":"integer"},"name":{"type":"string"},"status":{"type":"string","enum":["in_progress","available"]},"sync_status":{"type":"string","enum":["syncing","synced","failed"]},"sync_in_progress":{"type":"boolean"},"last_synced_at":{"type":["integer","null"]},"last_sync_attempted_at":{"type":["integer","null"]},"last_sync_error_code":{"type":"string"},"updated_at":{"type":"integer"}}},"example":{"account_id":1,"assistant":{"account_id":1,"config":"sample config","created_at":1,"description":"A short description.","guardrails":"sample guardrails","id":1,"name":"Sample Name","response_guidelines":"sample response guidelines","updated_at":1},"content":"Sample content text.","content_type":"sample content type","created_at":1,"external_link":"https://example.com/resource","display_url":"https://example.com/resource","file_size":"sample file size","pdf_document":true,"responses_count":5,"id":1,"name":"Sample Name","status":"in_progress","sync_status":"syncing","sync_in_progress":true,"last_synced_at":1,"last_sync_attempted_at":1,"last_sync_error_code":"sample last sync error code","updated_at":1}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]},"delete":{"tags":["Captain"],"operationId":"auto_delete_api_v1_accounts_account_id_captain_documents_id","summary":"Delete documents","description":"Deletes the document identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"204":{"description":"Success (no content)"},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/captain/tasks/rewrite":{"post":{"tags":["Captain"],"operationId":"auto_post_api_v1_accounts_account_id_captain_tasks_rewrite","summary":"Rewrite tasks","description":"Performs the rewrite operation on the targeted task resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":["string","null"]}}},"example":{"message":"Sample message text."}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"content":{"type":"string"},"operation":{"type":"string"},"conversation_display_id":{"type":"integer"}}},"example":{"content":"Sample content text.","operation":"sample operation","conversation_display_id":1}}}}}},"/api/v1/accounts/{account_id}/captain/tasks/summarize":{"post":{"tags":["Captain"],"operationId":"auto_post_api_v1_accounts_account_id_captain_tasks_summarize","summary":"Summarize tasks","description":"Performs the summarize operation on the targeted task resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":["string","null"]}}},"example":{"message":"Sample message text."}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"conversation_display_id":{"type":"integer"}}},"example":{"conversation_display_id":1}}}}}},"/api/v1/accounts/{account_id}/captain/tasks/reply_suggestion":{"post":{"tags":["Captain"],"operationId":"auto_post_api_v1_accounts_account_id_captain_tasks_reply_suggestion","summary":"Reply suggestion tasks","description":"Performs the reply suggestion operation on the targeted task resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":["string","null"]}}},"example":{"message":"Sample message text."}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"conversation_display_id":{"type":"integer"}}},"example":{"conversation_display_id":1}}}}}},"/api/v1/accounts/{account_id}/captain/tasks/label_suggestion":{"post":{"tags":["Captain"],"operationId":"auto_post_api_v1_accounts_account_id_captain_tasks_label_suggestion","summary":"Label suggestion tasks","description":"Performs the label suggestion operation on the targeted task resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":["string","null"]}}},"example":{"message":"Sample message text."}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"conversation_display_id":{"type":"integer"}}},"example":{"conversation_display_id":1}}}}}},"/api/v1/accounts/{account_id}/captain/tasks/follow_up":{"post":{"tags":["Captain"],"operationId":"auto_post_api_v1_accounts_account_id_captain_tasks_follow_up","summary":"Draft a Captain follow-up reply","description":"Runs the follow-up service for a conversation, threading the running follow_up_context and the operator's message. Returns { message } and an updated follow_up_context when the service produces one.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":["string","null"]}}},"example":{"message":"Sample message text."}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"The operator's instruction / user message for this turn.","example":"Ask if they still need the invoice."},"conversation_display_id":{"type":"integer","description":"Display id of the conversation the follow-up is about.","example":105},"follow_up_context":{"type":"object","additionalProperties":true,"description":"Opaque running context carried between follow-up turns.","example":{}}}},"example":{"message":"Ask if they still need the invoice.","conversation_display_id":105,"follow_up_context":{}}}}}}},"/api/v1/accounts/{account_id}/saml_settings":{"get":{"tags":["SAML"],"operationId":"auto_get_api_v1_accounts_account_id_saml_settings","summary":"Get saml settings","description":"Returns the saml setting identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"sso_url":{"type":"string"},"certificate":{"type":"string"},"fingerprint":{"type":"string"},"idp_entity_id":{"type":"integer"},"sp_entity_id":{"type":"integer"},"role_mappings":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"example":{"id":1,"account_id":1,"sso_url":"https://example.com/resource","certificate":"sample certificate","fingerprint":"sample fingerprint","idp_entity_id":1,"sp_entity_id":1,"role_mappings":"sample role mappings","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]},"patch":{"tags":["SAML"],"operationId":"auto_patch_api_v1_accounts_account_id_saml_settings","summary":"Update saml settings","description":"Updates the saml setting identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"sso_url":{"type":"string"},"certificate":{"type":"string"},"fingerprint":{"type":"string"},"idp_entity_id":{"type":"integer"},"sp_entity_id":{"type":"integer"},"role_mappings":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"example":{"id":1,"account_id":1,"sso_url":"https://example.com/resource","certificate":"sample certificate","fingerprint":"sample fingerprint","idp_entity_id":1,"sp_entity_id":1,"role_mappings":"sample role mappings","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"saml_settings":{"type":"object","properties":{"sso_url":{"type":"string"},"certificate":{"type":"string"},"idp_entity_id":{"type":"integer"},"sp_entity_id":{"type":"integer"},"role_mappings":{"type":"object","additionalProperties":true,"description":"Free-form object."}}}},"required":["saml_settings"]},"example":{"saml_settings":{"sso_url":"https://example.com/resource","certificate":"sample certificate","idp_entity_id":1,"sp_entity_id":1,"role_mappings":{}}}}}}},"put":{"tags":["SAML"],"operationId":"auto_put_api_v1_accounts_account_id_saml_settings","summary":"Update saml settings","description":"Updates the saml setting identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"sso_url":{"type":"string"},"certificate":{"type":"string"},"fingerprint":{"type":"string"},"idp_entity_id":{"type":"integer"},"sp_entity_id":{"type":"integer"},"role_mappings":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"example":{"id":1,"account_id":1,"sso_url":"https://example.com/resource","certificate":"sample certificate","fingerprint":"sample fingerprint","idp_entity_id":1,"sp_entity_id":1,"role_mappings":"sample role mappings","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"saml_settings":{"type":"object","properties":{"sso_url":{"type":"string"},"certificate":{"type":"string"},"idp_entity_id":{"type":"integer"},"sp_entity_id":{"type":"integer"},"role_mappings":{"type":"object","additionalProperties":true,"description":"Free-form object."}}}},"required":["saml_settings"]},"example":{"saml_settings":{"sso_url":"https://example.com/resource","certificate":"sample certificate","idp_entity_id":1,"sp_entity_id":1,"role_mappings":{}}}}}}},"delete":{"tags":["SAML"],"operationId":"auto_delete_api_v1_accounts_account_id_saml_settings","summary":"Delete saml settings","description":"Deletes the saml setting identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"204":{"description":"Success (no content)"},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]},"post":{"tags":["SAML"],"operationId":"auto_post_api_v1_accounts_account_id_saml_settings","summary":"Create saml settings","description":"Creates a new saml setting from the request payload. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"sso_url":{"type":"string"},"certificate":{"type":"string"},"fingerprint":{"type":"string"},"idp_entity_id":{"type":"integer"},"sp_entity_id":{"type":"integer"},"role_mappings":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"example":{"id":1,"account_id":1,"sso_url":"https://example.com/resource","certificate":"sample certificate","fingerprint":"sample fingerprint","idp_entity_id":1,"sp_entity_id":1,"role_mappings":"sample role mappings","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"saml_settings":{"type":"object","properties":{"sso_url":{"type":"string"},"certificate":{"type":"string"},"idp_entity_id":{"type":"integer"},"sp_entity_id":{"type":"integer"},"role_mappings":{"type":"object","additionalProperties":true,"description":"Free-form object."}}}},"required":["saml_settings"]},"example":{"saml_settings":{"sso_url":"https://example.com/resource","certificate":"sample certificate","idp_entity_id":1,"sp_entity_id":1,"role_mappings":{}}}}}}}},"/api/v1/accounts/{account_id}/agent_bots/{id}/avatar":{"delete":{"tags":["Agent Bots"],"operationId":"auto_delete_api_v1_accounts_account_id_agent_bots_id_avatar","summary":"Avatar agent bots","description":"Performs the avatar operation on the targeted agent bot resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"thumbnail":{"type":"string"},"outgoing_url":{"type":"string"},"bot_type":{"type":"string","enum":["webhook"]},"bot_config":{"type":"string"},"receive_incoming_when_assigned":{"type":"boolean"},"receive_incoming_when_assigned_configurable":{"type":"boolean"},"account_id":{"type":"integer"},"access_token":{"type":"string"},"secret":{"type":"string"},"system_bot":{"type":"boolean"}}},"example":{"id":1,"name":"Sample Name","description":"A short description.","thumbnail":"sample thumbnail","outgoing_url":"https://example.com/resource","bot_type":"webhook","bot_config":"sample bot config","receive_incoming_when_assigned":true,"receive_incoming_when_assigned_configurable":true,"account_id":1,"access_token":"sample-token","secret":"sample-token","system_bot":true}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/agent_bots/{id}/reset_access_token":{"post":{"tags":["Agent Bots"],"operationId":"auto_post_api_v1_accounts_account_id_agent_bots_id_reset_access_token","summary":"Reset access token agent bots","description":"Performs the reset access token operation on the targeted agent bot resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"thumbnail":{"type":"string"},"outgoing_url":{"type":"string"},"bot_type":{"type":"string","enum":["webhook"]},"bot_config":{"type":"string"},"receive_incoming_when_assigned":{"type":"boolean"},"receive_incoming_when_assigned_configurable":{"type":"boolean"},"account_id":{"type":"integer"},"access_token":{"type":"string"},"secret":{"type":"string"},"system_bot":{"type":"boolean"}}},"example":{"id":1,"name":"Sample Name","description":"A short description.","thumbnail":"sample thumbnail","outgoing_url":"https://example.com/resource","bot_type":"webhook","bot_config":"sample bot config","receive_incoming_when_assigned":true,"receive_incoming_when_assigned_configurable":true,"account_id":1,"access_token":"sample-token","secret":"sample-token","system_bot":true}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/agent_bots/{id}/reset_secret":{"post":{"tags":["Agent Bots"],"operationId":"auto_post_api_v1_accounts_account_id_agent_bots_id_reset_secret","summary":"Reset secret agent bots","description":"Performs the reset secret operation on the targeted agent bot resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"thumbnail":{"type":"string"},"outgoing_url":{"type":"string"},"bot_type":{"type":"string","enum":["webhook"]},"bot_config":{"type":"string"},"receive_incoming_when_assigned":{"type":"boolean"},"receive_incoming_when_assigned_configurable":{"type":"boolean"},"account_id":{"type":"integer"},"access_token":{"type":"string"},"secret":{"type":"string"},"system_bot":{"type":"boolean"}}},"example":{"id":1,"name":"Sample Name","description":"A short description.","thumbnail":"sample thumbnail","outgoing_url":"https://example.com/resource","bot_type":"webhook","bot_config":"sample bot config","receive_incoming_when_assigned":true,"receive_incoming_when_assigned_configurable":true,"account_id":1,"access_token":"sample-token","secret":"sample-token","system_bot":true}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/maestro/agents":{"get":{"tags":["Maestro"],"operationId":"auto_get_api_v1_accounts_account_id_maestro_agents","summary":"List the account's Maestro agents","description":"Every Robô of this account, each with its full configuration and inbox bindings. Secrets are never echoed — the key fields come back as booleans saying WHETHER a key is set.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Every Robô of the account.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/maestro_agent"}},"example":[{"id":42,"account_id":7,"name":"Atendimento","enabled":true,"config":{"persona":"Você é a atendente virtual da Acme, cordial e objetiva.","instructions":"Sempre confirme o CPF antes de consultar um pedido.","default_model":"openai:gpt-5.4-mini-2026-03-17","fallback_models":["anthropic:claude-haiku-4-5-20251001"],"enabled_tools":["set_labels"],"autonomy_level":"autopilot","interaction_mode":"converse","search_config":{"enabled":true,"search_depth":"basic","max_results":5,"topic":"general","include_domains":["docs.example.com"],"exclude_domains":[]},"locale":"pt_BR","quiet_window_seconds":8,"max_window_seconds":40,"summary_threshold_tokens":3000,"standdown_on_assignment":true,"standdown_auto_resume":true,"standdown_ttl_seconds":86400,"paused_inbound_policy":"discard","paused_inbound_max_messages":10,"paused_inbound_max_age_seconds":3600,"handoff_team_id":3,"working_hours_policy":"ignore","out_of_office_message":"Nosso atendimento volta às 9h. Já registramos sua mensagem.","handoff_policy":{"target_status":"open","target_priority":"none","triggers":["falar com atendente"]},"guardrails":{"banned_topics":["assuntos jurídicos"],"blocked_phrases":["garantimos 100% de aprovação"],"max_output_chars":1200,"pii_policy":"off","require_handoff_conditions":["cliente pede cancelamento"]},"knowledge_base":{"enabled":true,"top_k":5,"use_shared":false},"database":{"enabled":false,"connection_secret":"ERP_DB_URL","read_only":true,"max_rows":200,"statement_timeout_seconds":15,"include_tables":["orders"],"description":"Pedidos e faturas do ERP.","instructions":"Sempre filtre por account_id."},"reactions":{"outbound":false,"understand_inbound":false},"media":{"audio":true,"vision":true,"documents":true},"close_on_complete":"off","verification_policy":"off","model_params":{"reasoning_effort":"low","temperature":0.4,"top_p":0.9,"max_output_tokens":512},"service_flow":{"enabled":false,"on_exit":"handoff","strict_tools":true,"steps":[{"key":"qualificacao","name":"Qualificação","goal":"Descobrir o segmento e o tamanho da empresa.","allowed_tools":["contact_update"],"exit":{"type":"tools_executed","tools":["contact_update"],"attributes":["segmento"],"max_turns":8},"next":"proposta"}]},"max_tool_iterations":8,"history_limit_messages":40,"tail_budget_tokens":1500,"hard_cap_tokens":6000,"chain_same_provider":"","delivery":{"quote_replies":true,"formatting":"auto"},"stt":{"provider":"groq","model":"groq:whisper-large-v3-turbo"},"embedding":{"provider":"openai","model":"text-embedding-3-small"},"voice":{"enabled":false,"mode":"off","with_text":false,"provider":"elevenlabs","model":"eleven_multilingual_v2","call_backend":"auto","call_model":"openai:gpt-realtime","voice_id":"21m00Tcm4TlvDq8ikWAM","openai_voice":"alloy","gemini_voice":"Kore","stability":0.5,"similarity_boost":0.75,"style":0,"use_speaker_boost":true,"speed":1,"instructions":"Fale de forma calma e acolhedora.","style_instructions":"Locução comercial, ritmo animado."},"image_gen":{"enabled":false,"provider":"openai","model":"gpt-image-1"},"video_gen":{"enabled":false,"provider":"openai","model":"sora-2"},"custom_tools":[{"name":"consultar_pedido","description":"Consulta o status de um pedido pelo número.","method":"GET","url":"https://api.acme.com/orders/{{order_id}}","sensitive":false,"extract":"data.status","body_type":"json","body_template":{"source":"maestro","order_id":"{{order_id}}"},"headers":{"X-Api-Version":"2026-01"},"query":{"include":"items"},"auth":{"type":"bearer","name":"X-Api-Key","token_secret":"ACME_API_TOKEN","username_secret":"ACME_USER","password_secret":"ACME_PASS"},"params":[{"name":"order_id","type":"string","description":"Número do pedido.","required":true,"location":"auto"}],"response_map":[{"label":"Status","path":"data.status"}],"pagination":{"type":"none","param":"page","items_path":"data","next_path":"meta.next","start":1,"max_pages":5,"size_param":"per_page","size":50}}],"mcp_servers":[{"name":"acme-erp","url":"https://mcp.acme.com/sse","transport":"streamable_http","timeout":30,"sensitive":false,"enabled_tools":["get_order"],"headers":{"X-Tenant":"acme"},"auth":{"type":"bearer","name":"X-Api-Key","token_secret":"ACME_MCP_TOKEN","username_secret":"ACME_USER","password_secret":"ACME_PASS"}}],"media_assets":[{"name":"catalogo_2026","description":"Catálogo completo em PDF.","url":"https://cdn.acme.com/catalogo.pdf","type":"file"}],"sub_agents":[{"agent_id":7,"name":"Vendas","slug":"vendas","description":"Perguntas sobre planos e preços.","enabled":true,"sensitive":false}],"secrets":{"ACME_API_TOKEN":"sk-live-xxxxxxxx"},"secret_keys":["ACME_API_TOKEN"],"provider_keys":{"openai":"sk-proj-xxxxxxxx"},"chatwoot_native_keys":{"openai":"sk-proj-xxxxxxxx"},"provider_keys_set":["openai"],"native_keys_set":["openai"],"use_global_fallback":true},"bindings":[{"id":9,"inbox_id":3}],"created_at":"2026-07-01T12:00:00Z","updated_at":"2026-07-27T14:03:00Z"}]}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"502":{"description":"The Maestro service could not be reached (connection refused or reset, host unresolvable), or it answered in a way the gateway could not use, or it rejected the server-to-server credential — the last one is a deployment key mismatch, never the caller's own session. Nothing was executed; the call can be retried.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"504":{"description":"The Maestro service did not answer within the proxy timeout. The work may still be running on the service side, so retrying a write can duplicate its effect.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"503":{"description":"The Maestro area is not serving this installation: an operator turned it off, or no admin key was ever provisioned. Nothing was executed, and retrying will not help until the configuration changes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]},"post":{"tags":["Maestro"],"operationId":"auto_post_api_v1_accounts_account_id_maestro_agents","summary":"Create a Maestro agent","description":"Creates a Maestro agent for this account and, when `bindings` is present, links it to the given inbox. The account's native provider keys are mirrored into the agent on create so it can fall back to them. Native AgentBot provisioning is forced off: the caller must use the explicit stable-id link endpoint afterward, which then pushes the linked bot's webhook secret. Only the fields documented here are forwarded to the Maestro sidecar - anything else in the payload is discarded.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The created Robô, with its configuration and bindings.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_agent"},"example":{"id":42,"account_id":7,"name":"Atendimento","enabled":true,"config":{"persona":"Você é a atendente virtual da Acme, cordial e objetiva.","instructions":"Sempre confirme o CPF antes de consultar um pedido.","default_model":"openai:gpt-5.4-mini-2026-03-17","fallback_models":["anthropic:claude-haiku-4-5-20251001"],"enabled_tools":["set_labels"],"autonomy_level":"autopilot","interaction_mode":"converse","search_config":{"enabled":true,"search_depth":"basic","max_results":5,"topic":"general","include_domains":["docs.example.com"],"exclude_domains":[]},"locale":"pt_BR","quiet_window_seconds":8,"max_window_seconds":40,"summary_threshold_tokens":3000,"standdown_on_assignment":true,"standdown_auto_resume":true,"standdown_ttl_seconds":86400,"paused_inbound_policy":"discard","paused_inbound_max_messages":10,"paused_inbound_max_age_seconds":3600,"handoff_team_id":3,"working_hours_policy":"ignore","out_of_office_message":"Nosso atendimento volta às 9h. Já registramos sua mensagem.","handoff_policy":{"target_status":"open","target_priority":"none","triggers":["falar com atendente"]},"guardrails":{"banned_topics":["assuntos jurídicos"],"blocked_phrases":["garantimos 100% de aprovação"],"max_output_chars":1200,"pii_policy":"off","require_handoff_conditions":["cliente pede cancelamento"]},"knowledge_base":{"enabled":true,"top_k":5,"use_shared":false},"database":{"enabled":false,"connection_secret":"ERP_DB_URL","read_only":true,"max_rows":200,"statement_timeout_seconds":15,"include_tables":["orders"],"description":"Pedidos e faturas do ERP.","instructions":"Sempre filtre por account_id."},"reactions":{"outbound":false,"understand_inbound":false},"media":{"audio":true,"vision":true,"documents":true},"close_on_complete":"off","verification_policy":"off","model_params":{"reasoning_effort":"low","temperature":0.4,"top_p":0.9,"max_output_tokens":512},"service_flow":{"enabled":false,"on_exit":"handoff","strict_tools":true,"steps":[{"key":"qualificacao","name":"Qualificação","goal":"Descobrir o segmento e o tamanho da empresa.","allowed_tools":["contact_update"],"exit":{"type":"tools_executed","tools":["contact_update"],"attributes":["segmento"],"max_turns":8},"next":"proposta"}]},"max_tool_iterations":8,"history_limit_messages":40,"tail_budget_tokens":1500,"hard_cap_tokens":6000,"chain_same_provider":"","delivery":{"quote_replies":true,"formatting":"auto"},"stt":{"provider":"groq","model":"groq:whisper-large-v3-turbo"},"embedding":{"provider":"openai","model":"text-embedding-3-small"},"voice":{"enabled":false,"mode":"off","with_text":false,"provider":"elevenlabs","model":"eleven_multilingual_v2","call_backend":"auto","call_model":"openai:gpt-realtime","voice_id":"21m00Tcm4TlvDq8ikWAM","openai_voice":"alloy","gemini_voice":"Kore","stability":0.5,"similarity_boost":0.75,"style":0,"use_speaker_boost":true,"speed":1,"instructions":"Fale de forma calma e acolhedora.","style_instructions":"Locução comercial, ritmo animado."},"image_gen":{"enabled":false,"provider":"openai","model":"gpt-image-1"},"video_gen":{"enabled":false,"provider":"openai","model":"sora-2"},"custom_tools":[{"name":"consultar_pedido","description":"Consulta o status de um pedido pelo número.","method":"GET","url":"https://api.acme.com/orders/{{order_id}}","sensitive":false,"extract":"data.status","body_type":"json","body_template":{"source":"maestro","order_id":"{{order_id}}"},"headers":{"X-Api-Version":"2026-01"},"query":{"include":"items"},"auth":{"type":"bearer","name":"X-Api-Key","token_secret":"ACME_API_TOKEN","username_secret":"ACME_USER","password_secret":"ACME_PASS"},"params":[{"name":"order_id","type":"string","description":"Número do pedido.","required":true,"location":"auto"}],"response_map":[{"label":"Status","path":"data.status"}],"pagination":{"type":"none","param":"page","items_path":"data","next_path":"meta.next","start":1,"max_pages":5,"size_param":"per_page","size":50}}],"mcp_servers":[{"name":"acme-erp","url":"https://mcp.acme.com/sse","transport":"streamable_http","timeout":30,"sensitive":false,"enabled_tools":["get_order"],"headers":{"X-Tenant":"acme"},"auth":{"type":"bearer","name":"X-Api-Key","token_secret":"ACME_MCP_TOKEN","username_secret":"ACME_USER","password_secret":"ACME_PASS"}}],"media_assets":[{"name":"catalogo_2026","description":"Catálogo completo em PDF.","url":"https://cdn.acme.com/catalogo.pdf","type":"file"}],"sub_agents":[{"agent_id":7,"name":"Vendas","slug":"vendas","description":"Perguntas sobre planos e preços.","enabled":true,"sensitive":false}],"secrets":{"ACME_API_TOKEN":"sk-live-xxxxxxxx"},"secret_keys":["ACME_API_TOKEN"],"provider_keys":{"openai":"sk-proj-xxxxxxxx"},"chatwoot_native_keys":{"openai":"sk-proj-xxxxxxxx"},"provider_keys_set":["openai"],"native_keys_set":["openai"],"use_global_fallback":true},"bindings":[{"id":9,"inbox_id":3}],"created_at":"2026-07-01T12:00:00Z","updated_at":"2026-07-27T14:03:00Z"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"502":{"description":"The Maestro service could not be reached (connection refused or reset, host unresolvable), or it answered in a way the gateway could not use, or it rejected the server-to-server credential — the last one is a deployment key mismatch, never the caller's own session. Nothing was executed; the call can be retried.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"504":{"description":"The Maestro service did not answer within the proxy timeout. The work may still be running on the service side, so retrying a write can duplicate its effect.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"503":{"description":"The Maestro area is not serving this installation: an operator turned it off, or no admin key was ever provisioned. Nothing was executed, and retrying will not help until the configuration changes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"201":{"description":"The created Robô, with its configuration and bindings.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_agent"},"example":{"id":42,"account_id":7,"name":"Atendimento","enabled":true,"config":{"persona":"Você é a atendente virtual da Acme, cordial e objetiva.","instructions":"Sempre confirme o CPF antes de consultar um pedido.","default_model":"openai:gpt-5.4-mini-2026-03-17","fallback_models":["anthropic:claude-haiku-4-5-20251001"],"enabled_tools":["set_labels"],"autonomy_level":"autopilot","interaction_mode":"converse","search_config":{"enabled":true,"search_depth":"basic","max_results":5,"topic":"general","include_domains":["docs.example.com"],"exclude_domains":[]},"locale":"pt_BR","quiet_window_seconds":8,"max_window_seconds":40,"summary_threshold_tokens":3000,"standdown_on_assignment":true,"standdown_auto_resume":true,"standdown_ttl_seconds":86400,"paused_inbound_policy":"discard","paused_inbound_max_messages":10,"paused_inbound_max_age_seconds":3600,"handoff_team_id":3,"working_hours_policy":"ignore","out_of_office_message":"Nosso atendimento volta às 9h. Já registramos sua mensagem.","handoff_policy":{"target_status":"open","target_priority":"none","triggers":["falar com atendente"]},"guardrails":{"banned_topics":["assuntos jurídicos"],"blocked_phrases":["garantimos 100% de aprovação"],"max_output_chars":1200,"pii_policy":"off","require_handoff_conditions":["cliente pede cancelamento"]},"knowledge_base":{"enabled":true,"top_k":5,"use_shared":false},"database":{"enabled":false,"connection_secret":"ERP_DB_URL","read_only":true,"max_rows":200,"statement_timeout_seconds":15,"include_tables":["orders"],"description":"Pedidos e faturas do ERP.","instructions":"Sempre filtre por account_id."},"reactions":{"outbound":false,"understand_inbound":false},"media":{"audio":true,"vision":true,"documents":true},"close_on_complete":"off","verification_policy":"off","model_params":{"reasoning_effort":"low","temperature":0.4,"top_p":0.9,"max_output_tokens":512},"service_flow":{"enabled":false,"on_exit":"handoff","strict_tools":true,"steps":[{"key":"qualificacao","name":"Qualificação","goal":"Descobrir o segmento e o tamanho da empresa.","allowed_tools":["contact_update"],"exit":{"type":"tools_executed","tools":["contact_update"],"attributes":["segmento"],"max_turns":8},"next":"proposta"}]},"max_tool_iterations":8,"history_limit_messages":40,"tail_budget_tokens":1500,"hard_cap_tokens":6000,"chain_same_provider":"","delivery":{"quote_replies":true,"formatting":"auto"},"stt":{"provider":"groq","model":"groq:whisper-large-v3-turbo"},"embedding":{"provider":"openai","model":"text-embedding-3-small"},"voice":{"enabled":false,"mode":"off","with_text":false,"provider":"elevenlabs","model":"eleven_multilingual_v2","call_backend":"auto","call_model":"openai:gpt-realtime","voice_id":"21m00Tcm4TlvDq8ikWAM","openai_voice":"alloy","gemini_voice":"Kore","stability":0.5,"similarity_boost":0.75,"style":0,"use_speaker_boost":true,"speed":1,"instructions":"Fale de forma calma e acolhedora.","style_instructions":"Locução comercial, ritmo animado."},"image_gen":{"enabled":false,"provider":"openai","model":"gpt-image-1"},"video_gen":{"enabled":false,"provider":"openai","model":"sora-2"},"custom_tools":[{"name":"consultar_pedido","description":"Consulta o status de um pedido pelo número.","method":"GET","url":"https://api.acme.com/orders/{{order_id}}","sensitive":false,"extract":"data.status","body_type":"json","body_template":{"source":"maestro","order_id":"{{order_id}}"},"headers":{"X-Api-Version":"2026-01"},"query":{"include":"items"},"auth":{"type":"bearer","name":"X-Api-Key","token_secret":"ACME_API_TOKEN","username_secret":"ACME_USER","password_secret":"ACME_PASS"},"params":[{"name":"order_id","type":"string","description":"Número do pedido.","required":true,"location":"auto"}],"response_map":[{"label":"Status","path":"data.status"}],"pagination":{"type":"none","param":"page","items_path":"data","next_path":"meta.next","start":1,"max_pages":5,"size_param":"per_page","size":50}}],"mcp_servers":[{"name":"acme-erp","url":"https://mcp.acme.com/sse","transport":"streamable_http","timeout":30,"sensitive":false,"enabled_tools":["get_order"],"headers":{"X-Tenant":"acme"},"auth":{"type":"bearer","name":"X-Api-Key","token_secret":"ACME_MCP_TOKEN","username_secret":"ACME_USER","password_secret":"ACME_PASS"}}],"media_assets":[{"name":"catalogo_2026","description":"Catálogo completo em PDF.","url":"https://cdn.acme.com/catalogo.pdf","type":"file"}],"sub_agents":[{"agent_id":7,"name":"Vendas","slug":"vendas","description":"Perguntas sobre planos e preços.","enabled":true,"sensitive":false}],"secrets":{"ACME_API_TOKEN":"sk-live-xxxxxxxx"},"secret_keys":["ACME_API_TOKEN"],"provider_keys":{"openai":"sk-proj-xxxxxxxx"},"chatwoot_native_keys":{"openai":"sk-proj-xxxxxxxx"},"provider_keys_set":["openai"],"native_keys_set":["openai"],"use_global_fallback":true},"bindings":[{"id":9,"inbox_id":3}],"created_at":"2026-07-01T12:00:00Z","updated_at":"2026-07-27T14:03:00Z"}}}},"422":{"description":"The configuration was refused before anything was stored — an unbuildable model chain, or an embedding model whose vector width is not this installation's. The body carries a `code` and the facts the UI needs (which providers, which two widths) so the sentence is written in the reader's language, never composed on the server."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","description":"Editable display name. It never selects or links a native AgentBot.","example":"Atendente Acme"},"enabled":{"type":"boolean","description":"Whether the agent answers. Created enabled unless set to false.","example":true},"bindings":{"type":"array","description":"Inboxes to link the agent to on creation.","items":{"type":"object","properties":{"inbox_id":{"type":"integer","description":"Id of the inbox the agent should answer on.","example":12}}}},"config":{"$ref":"#/components/schemas/maestro_agent_config"}}},"example":{"name":"Atendente Acme","enabled":true,"bindings":[{"inbox_id":12}],"config":{"persona":"Você é a atendente virtual da Acme, cordial e objetiva.","instructions":"Sempre confirme o CPF antes de consultar um pedido.","default_model":"openai:gpt-5.4-mini-2026-03-17","fallback_models":["anthropic:claude-haiku-4-5-20251001"],"enabled_tools":["set_labels"],"autonomy_level":"autopilot","interaction_mode":"converse","search_config":{"enabled":true,"search_depth":"basic","max_results":5,"topic":"general","include_domains":["docs.example.com"],"exclude_domains":[]},"locale":"pt_BR","quiet_window_seconds":8,"max_window_seconds":40,"summary_threshold_tokens":3000,"standdown_on_assignment":true,"standdown_auto_resume":true,"standdown_ttl_seconds":86400,"paused_inbound_policy":"discard","paused_inbound_max_messages":10,"paused_inbound_max_age_seconds":3600,"handoff_team_id":3,"working_hours_policy":"ignore","out_of_office_message":"Nosso atendimento volta às 9h. Já registramos sua mensagem.","handoff_policy":{"target_status":"open","target_priority":"none","triggers":["falar com atendente"]},"guardrails":{"banned_topics":["assuntos jurídicos"],"blocked_phrases":["garantimos 100% de aprovação"],"max_output_chars":1200,"pii_policy":"off","require_handoff_conditions":["cliente pede cancelamento"]},"knowledge_base":{"enabled":true,"top_k":5,"use_shared":false},"database":{"enabled":false,"connection_secret":"ERP_DB_URL","read_only":true,"max_rows":200,"statement_timeout_seconds":15,"include_tables":["orders"],"description":"Pedidos e faturas do ERP.","instructions":"Sempre filtre por account_id."},"reactions":{"outbound":false,"understand_inbound":false},"media":{"audio":true,"vision":true,"documents":true},"close_on_complete":"off","verification_policy":"off","model_params":{"reasoning_effort":"low","temperature":0.4,"top_p":0.9,"max_output_tokens":512},"service_flow":{"enabled":false,"on_exit":"handoff","strict_tools":true,"steps":[{"key":"qualificacao","name":"Qualificação","goal":"Descobrir o segmento e o tamanho da empresa.","allowed_tools":["contact_update"],"exit":{"type":"tools_executed","tools":["contact_update"],"attributes":["segmento"],"max_turns":8},"next":"proposta"}]},"max_tool_iterations":8,"history_limit_messages":40,"tail_budget_tokens":1500,"hard_cap_tokens":6000,"chain_same_provider":"","delivery":{"quote_replies":true,"formatting":"auto"},"stt":{"provider":"groq","model":"groq:whisper-large-v3-turbo"},"embedding":{"provider":"openai","model":"text-embedding-3-small"},"voice":{"enabled":false,"mode":"off","with_text":false,"provider":"elevenlabs","model":"eleven_multilingual_v2","call_backend":"auto","call_model":"openai:gpt-realtime","voice_id":"21m00Tcm4TlvDq8ikWAM","openai_voice":"alloy","gemini_voice":"Kore","stability":0.5,"similarity_boost":0.75,"style":0,"use_speaker_boost":true,"speed":1,"instructions":"Fale de forma calma e acolhedora.","style_instructions":"Locução comercial, ritmo animado."},"image_gen":{"enabled":false,"provider":"openai","model":"gpt-image-1"},"video_gen":{"enabled":false,"provider":"openai","model":"sora-2"},"custom_tools":[{"name":"consultar_pedido","description":"Consulta o status de um pedido pelo número.","method":"GET","url":"https://api.acme.com/orders/{{order_id}}","sensitive":false,"extract":"data.status","body_type":"json","body_template":{"source":"maestro","order_id":"{{order_id}}"},"headers":{"X-Api-Version":"2026-01"},"query":{"include":"items"},"auth":{"type":"bearer","name":"X-Api-Key","token_secret":"ACME_API_TOKEN","username_secret":"ACME_USER","password_secret":"ACME_PASS"},"params":[{"name":"order_id","type":"string","description":"Número do pedido.","required":true,"location":"auto"}],"response_map":[{"label":"Status","path":"data.status"}],"pagination":{"type":"none","param":"page","items_path":"data","next_path":"meta.next","start":1,"max_pages":5,"size_param":"per_page","size":50}}],"mcp_servers":[{"name":"acme-erp","url":"https://mcp.acme.com/sse","transport":"streamable_http","timeout":30,"sensitive":false,"enabled_tools":["get_order"],"headers":{"X-Tenant":"acme"},"auth":{"type":"bearer","name":"X-Api-Key","token_secret":"ACME_MCP_TOKEN","username_secret":"ACME_USER","password_secret":"ACME_PASS"}}],"media_assets":[{"name":"catalogo_2026","description":"Catálogo completo em PDF.","url":"https://cdn.acme.com/catalogo.pdf","type":"file"}],"sub_agents":[{"agent_id":7,"name":"Vendas","slug":"vendas","description":"Perguntas sobre planos e preços.","enabled":true,"sensitive":false}],"secrets":{"ACME_API_TOKEN":"sk-live-xxxxxxxx"},"secret_keys":["ACME_API_TOKEN"],"provider_keys":{"openai":"sk-proj-xxxxxxxx"},"chatwoot_native_keys":{"openai":"sk-proj-xxxxxxxx"},"provider_keys_set":["openai"],"native_keys_set":["openai"],"use_global_fallback":true}}}}}}},"/api/v1/accounts/{account_id}/maestro/agents/meta":{"get":{"tags":["Maestro"],"operationId":"auto_get_api_v1_accounts_account_id_maestro_agents_meta","summary":"Get the Maestro capability catalogue (meta)","description":"Returns the sidecar capability catalogue (tools, autonomy levels, locales, model list, prompt variables, manageable providers, media-model options, tool-budget inputs, sub-agent candidates) augmented with the platform-side webhook URL and connection/security flags. A dashboard visit also re-ensures the per-account Maestro service user (throttled). Degrades to 502/503 when the sidecar is unreachable.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Capability catalogue + the platform webhook augmentation.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"tools":{"type":"array","items":{"type":"string"},"example":["send_message","assign_conversation","add_labels"]},"autonomy_levels":{"type":"array","items":{"type":"string"},"example":["suggest","assist","autonomous"]},"locales":{"type":"array","items":{"type":"string"},"example":["pt_BR","en","es"]},"models":{"type":"array","description":"Selectable LLM models grouped for the UI.","items":{"type":"object","properties":{"id":{"type":"string","example":"openai:gpt-5.5"},"provider":{"type":"string","example":"openai"},"provider_label":{"type":"string","example":"OpenAI"},"label":{"type":"string","example":"GPT-5.5"},"tier":{"type":"string","example":"flagship"}}}},"realtime_models":{"type":"array","description":"Speech-to-speech (realtime) models, from the SAME catalogue as `models`, filtered by modality.","items":{"$ref":"#/components/schemas/maestro_modality_model"}},"stt_models":{"type":"array","description":"Transcription (speech-to-text) models, same catalogue, filtered by modality.","items":{"$ref":"#/components/schemas/maestro_modality_model"}},"tts_models":{"type":"array","description":"Voice (text-to-speech) models, same catalogue, filtered by modality.","items":{"$ref":"#/components/schemas/maestro_modality_model"}},"embedding_models":{"type":"array","description":"Embedding models, same catalogue, filtered by modality. The only list whose entries can carry `dimension`, because vector width decides whether the choice DOES anything: the store column is fixed-width and a mis-sized model is skipped in silence at embed time.","items":{"$ref":"#/components/schemas/maestro_modality_model"}},"variables":{"type":"array","description":"Dynamic prompt variables for the UI chips.","items":{"type":"object","properties":{"token":{"type":"string","example":"contato.nome"},"description":{"type":"string","example":"The contact's name"}}}},"providers":{"type":"array","description":"LLM providers whose key the UI can manage.","items":{"type":"object","properties":{"id":{"type":"string","example":"openai"},"label":{"type":"string","example":"OpenAI"},"key_env":{"type":"string","example":"OPENAI_API_KEY"},"manageable":{"type":"boolean","example":true},"native":{"type":"boolean","example":true},"env_configured":{"type":"boolean","example":false}}}},"provider_key_policy":{"type":"object","properties":{"allow_global":{"type":"boolean","example":true},"prefer_chatwoot_native":{"type":"boolean","example":true}}},"media_models":{"type":"object","description":"Generative-media model options per modality -\u003e provider -\u003e model ids.","properties":{"voice":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"example":{"openai":["tts-1","gpt-4o-mini-tts"]},"description":"Voice/TTS model ids available per provider (provider id to a list of model ids)."},"image":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"example":{"openai":["gpt-image-1"]},"description":"Image-generation model ids available per provider (provider id to a list of model ids)."},"video":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"example":{},"description":"Video-generation model ids available per provider (provider id to a list of model ids)."},"voice_names":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"example":{"openai":["alloy","shimmer"]},"description":"Named voices available per provider (provider id to a list of voice names)."}}},"provider_tool_limits":{"type":"object","additionalProperties":{"type":"integer"},"description":"Per-provider hard tool cap (provider absent = no cap).","example":{"openai":128,"google_genai":128}},"always_on_tool_count":{"type":"integer","description":"Built-in CONTACT_CORE tools always bound on top of the selection.","example":4},"media_offer_tools":{"type":"array","items":{"type":"string"},"example":["generate_image","generate_audio"]},"sub_agent_candidates":{"type":"array","description":"This account's OTHER agents, delegation targets.","items":{"type":"object","properties":{"id":{"type":"integer","example":7},"name":{"type":"string","example":"Sales Agent"}}}},"chatwoot_webhook_url":{"type":"string","description":"Public AgentBot webhook URL Rails injects for auto-fill.","example":"https://app.example.com/chatwoot/webhook/maestro"},"connected":{"type":"boolean","description":"True whenever the sidecar responded (Rails-added).","example":true},"webhook_secured":{"type":"boolean","description":"True when a per-bot webhook secret is registered (Rails-added; no secret echoed).","example":true}}},"example":{"tools":["send_message","assign_conversation","add_labels"],"autonomy_levels":["suggest","assist","autonomous"],"locales":["pt_BR","en","es"],"models":[{"id":"openai:gpt-5.5","provider":"openai","provider_label":"OpenAI","label":"GPT-5.5","tier":"flagship"}],"realtime_models":[{"id":"openai:text-embedding-3-small","provider":"openai","provider_label":"OpenAI","label":"Text Embedding 3 Small","description":"Fast and cheap; the default embedding model.","dimension":1536}],"stt_models":[{"id":"openai:text-embedding-3-small","provider":"openai","provider_label":"OpenAI","label":"Text Embedding 3 Small","description":"Fast and cheap; the default embedding model.","dimension":1536}],"tts_models":[{"id":"openai:text-embedding-3-small","provider":"openai","provider_label":"OpenAI","label":"Text Embedding 3 Small","description":"Fast and cheap; the default embedding model.","dimension":1536}],"embedding_models":[{"id":"openai:text-embedding-3-small","provider":"openai","provider_label":"OpenAI","label":"Text Embedding 3 Small","description":"Fast and cheap; the default embedding model.","dimension":1536}],"variables":[{"token":"contato.nome","description":"The contact's name"}],"providers":[{"id":"openai","label":"OpenAI","key_env":"OPENAI_API_KEY","manageable":true,"native":true,"env_configured":false}],"provider_key_policy":{"allow_global":true,"prefer_chatwoot_native":true},"media_models":{"voice":{"openai":["tts-1","gpt-4o-mini-tts"]},"image":{"openai":["gpt-image-1"]},"video":{},"voice_names":{"openai":["alloy","shimmer"]}},"provider_tool_limits":{"openai":128,"google_genai":128},"always_on_tool_count":4,"media_offer_tools":["generate_image","generate_audio"],"sub_agent_candidates":[{"id":7,"name":"Sales Agent"}],"chatwoot_webhook_url":"https://app.example.com/chatwoot/webhook/maestro","connected":true,"webhook_secured":true}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"502":{"description":"The Maestro service could not be reached (connection refused or reset, host unresolvable), or it answered in a way the gateway could not use, or it rejected the server-to-server credential — the last one is a deployment key mismatch, never the caller's own session. Nothing was executed; the call can be retried.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"504":{"description":"The Maestro service did not answer within the proxy timeout. The work may still be running on the service side, so retrying a write can duplicate its effect.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"503":{"description":"The Maestro area is not serving this installation: an operator turned it off, or no admin key was ever provisioned. Nothing was executed, and retrying will not help until the configuration changes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/maestro/agents/templates":{"get":{"tags":["Maestro"],"operationId":"auto_get_api_v1_accounts_account_id_maestro_agents_templates","summary":"List the Maestro quick-start template catalogue","description":"The ready-made catalogue the Robô builder offers: vertical agent presets, pre-mapped HTTP tools, SQL snippets and native capability mappings. The catalogue is account-agnostic — the same four sections are served to every account. The optional `locale` query resolves the human copy (label, description, persona, instructions) to that language; a missing or blank locale is served in English. Structural fields never vary with the locale.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The four catalogue sections, with human copy resolved to the requested locale.","content":{"application/json":{"schema":{"type":"object","properties":{"agents":{"type":"array","description":"Vertical agent presets. Picking one merges its `config` into the Robô form.","items":{"type":"object","properties":{"id":{"type":"string","description":"Stable preset identifier, unchanged across locales.","example":"ecommerce_support"},"label":{"type":"string","description":"Localized preset name shown in the picker.","example":"E-commerce support"},"description":{"type":"string","description":"Localized one-line summary of what the preset does.","example":"Order status, product questions, catalog quotes, and handoff for refunds."},"vertical":{"type":"string","description":"Business vertical the preset was written for.","example":"ecommerce"},"config":{"$ref":"#/components/schemas/maestro_agent_config"}}}},"tools":{"type":"array","description":"Pre-mapped HTTP tool definitions ready to be added to a Robô's custom tools.","items":{"type":"object","properties":{"id":{"type":"string","description":"Stable tool-template identifier.","example":"cep_lookup"},"label":{"type":"string","description":"Localized tool name shown in the picker.","example":"Brazilian address by CEP (ViaCEP)"},"description":{"type":"string","description":"Localized summary of what the tool resolves.","example":"Resolve a Brazilian postal code (CEP) to its address - no auth required."},"tool":{"type":"object","description":"The custom-tool definition itself, in the same shape as one entry of the Robô configuration's `custom_tools`. Merged into the form as-is.","additionalProperties":true,"properties":{"name":{"type":"string","description":"Tool name the model calls.","example":"cep_lookup"},"description":{"type":"string","description":"What the tool does, as the model reads it.","example":"Look up a Brazilian address by CEP (postal code)."},"method":{"type":"string","description":"HTTP verb the tool call issues.","enum":["GET","POST","PUT","PATCH","DELETE"],"example":"GET"},"url":{"type":"string","description":"Endpoint template; `{placeholder}` segments are filled from path params.","example":"https://viacep.com.br/ws/{cep}/json/"},"extract":{"type":"string","description":"Optional JSON path narrowing the response before it reaches the model.","example":""},"params":{"type":"array","description":"Declared arguments the model may fill.","items":{"type":"object","additionalProperties":true,"properties":{"name":{"type":"string","description":"Argument name.","example":"cep"},"type":{"type":"string","description":"Argument primitive type.","example":"string"},"description":{"type":"string","description":"What the argument means, as the model reads it.","example":"CEP (8 digits)"},"required":{"type":"boolean","description":"Whether the model must supply the argument.","example":true},"location":{"type":"string","description":"Where the argument is placed in the request.","example":"path"}}}},"auth":{"type":"object","description":"Authentication block for the call. `type` is `none` for the public templates; credential-bearing variants reference secrets by name. additionalProperties are the credential-reference fields of the chosen type.","additionalProperties":true,"properties":{"type":{"type":"string","description":"Authentication scheme the tool uses.","example":"none"}}}}}}}},"sql":{"type":"array","description":"Read-only SQL snippets for a Robô wired to an external database.","items":{"type":"object","properties":{"id":{"type":"string","description":"Stable snippet identifier.","example":"order_by_phone"},"label":{"type":"string","description":"Localized snippet name.","example":"Latest order by phone"},"description":{"type":"string","description":"Localized summary of what the query answers.","example":"Most recent order for a contact's phone number."},"sql":{"type":"string","description":"The query text, with named bind parameters.","example":"SELECT id, status, total, created_at FROM orders WHERE customer_phone = :phone ORDER BY created_at DESC LIMIT 5"}}}},"mappings":{"type":"array","description":"Native capability mappings - a curated set of enabled tools plus matching instructions, merged into the Robô configuration.","items":{"type":"object","properties":{"id":{"type":"string","description":"Stable mapping identifier.","example":"triage_and_label"},"label":{"type":"string","description":"Localized mapping name.","example":"Triage \u0026 label"},"description":{"type":"string","description":"Localized summary of the behaviour the mapping installs.","example":"Categorize every conversation with labels + custom attributes and set priority."},"config":{"$ref":"#/components/schemas/maestro_agent_config"}}}}}},"example":{"agents":[{"id":"ecommerce_support","label":"E-commerce support","description":"Order status, product questions, catalog quotes, and handoff for refunds.","vertical":"ecommerce","config":{"persona":"Você é a atendente virtual da Acme, cordial e objetiva.","instructions":"Sempre confirme o CPF antes de consultar um pedido.","default_model":"openai:gpt-5.4-mini-2026-03-17","fallback_models":["anthropic:claude-haiku-4-5-20251001"],"enabled_tools":["set_labels"],"autonomy_level":"autopilot","interaction_mode":"converse","search_config":{"enabled":true,"search_depth":"basic","max_results":5,"topic":"general","include_domains":["docs.example.com"],"exclude_domains":[]},"locale":"pt_BR","quiet_window_seconds":8,"max_window_seconds":40,"summary_threshold_tokens":3000,"standdown_on_assignment":true,"standdown_auto_resume":true,"standdown_ttl_seconds":86400,"paused_inbound_policy":"discard","paused_inbound_max_messages":10,"paused_inbound_max_age_seconds":3600,"handoff_team_id":3,"working_hours_policy":"ignore","out_of_office_message":"Nosso atendimento volta às 9h. Já registramos sua mensagem.","handoff_policy":{"target_status":"open","target_priority":"none","triggers":["falar com atendente"]},"guardrails":{"banned_topics":["assuntos jurídicos"],"blocked_phrases":["garantimos 100% de aprovação"],"max_output_chars":1200,"pii_policy":"off","require_handoff_conditions":["cliente pede cancelamento"]},"knowledge_base":{"enabled":true,"top_k":5,"use_shared":false},"database":{"enabled":false,"connection_secret":"ERP_DB_URL","read_only":true,"max_rows":200,"statement_timeout_seconds":15,"include_tables":["orders"],"description":"Pedidos e faturas do ERP.","instructions":"Sempre filtre por account_id."},"reactions":{"outbound":false,"understand_inbound":false},"media":{"audio":true,"vision":true,"documents":true},"close_on_complete":"off","verification_policy":"off","model_params":{"reasoning_effort":"low","temperature":0.4,"top_p":0.9,"max_output_tokens":512},"service_flow":{"enabled":false,"on_exit":"handoff","strict_tools":true,"steps":[{"key":"qualificacao","name":"Qualificação","goal":"Descobrir o segmento e o tamanho da empresa.","allowed_tools":["contact_update"],"exit":{"type":"tools_executed","tools":["contact_update"],"attributes":["segmento"],"max_turns":8},"next":"proposta"}]},"max_tool_iterations":8,"history_limit_messages":40,"tail_budget_tokens":1500,"hard_cap_tokens":6000,"chain_same_provider":"","delivery":{"quote_replies":true,"formatting":"auto"},"stt":{"provider":"groq","model":"groq:whisper-large-v3-turbo"},"embedding":{"provider":"openai","model":"text-embedding-3-small"},"voice":{"enabled":false,"mode":"off","with_text":false,"provider":"elevenlabs","model":"eleven_multilingual_v2","call_backend":"auto","call_model":"openai:gpt-realtime","voice_id":"21m00Tcm4TlvDq8ikWAM","openai_voice":"alloy","gemini_voice":"Kore","stability":0.5,"similarity_boost":0.75,"style":0,"use_speaker_boost":true,"speed":1,"instructions":"Fale de forma calma e acolhedora.","style_instructions":"Locução comercial, ritmo animado."},"image_gen":{"enabled":false,"provider":"openai","model":"gpt-image-1"},"video_gen":{"enabled":false,"provider":"openai","model":"sora-2"},"custom_tools":[{"name":"consultar_pedido","description":"Consulta o status de um pedido pelo número.","method":"GET","url":"https://api.acme.com/orders/{{order_id}}","sensitive":false,"extract":"data.status","body_type":"json","body_template":{"source":"maestro","order_id":"{{order_id}}"},"headers":{"X-Api-Version":"2026-01"},"query":{"include":"items"},"auth":{"type":"bearer","name":"X-Api-Key","token_secret":"ACME_API_TOKEN","username_secret":"ACME_USER","password_secret":"ACME_PASS"},"params":[{"name":"order_id","type":"string","description":"Número do pedido.","required":true,"location":"auto"}],"response_map":[{"label":"Status","path":"data.status"}],"pagination":{"type":"none","param":"page","items_path":"data","next_path":"meta.next","start":1,"max_pages":5,"size_param":"per_page","size":50}}],"mcp_servers":[{"name":"acme-erp","url":"https://mcp.acme.com/sse","transport":"streamable_http","timeout":30,"sensitive":false,"enabled_tools":["get_order"],"headers":{"X-Tenant":"acme"},"auth":{"type":"bearer","name":"X-Api-Key","token_secret":"ACME_MCP_TOKEN","username_secret":"ACME_USER","password_secret":"ACME_PASS"}}],"media_assets":[{"name":"catalogo_2026","description":"Catálogo completo em PDF.","url":"https://cdn.acme.com/catalogo.pdf","type":"file"}],"sub_agents":[{"agent_id":7,"name":"Vendas","slug":"vendas","description":"Perguntas sobre planos e preços.","enabled":true,"sensitive":false}],"secrets":{"ACME_API_TOKEN":"sk-live-xxxxxxxx"},"secret_keys":["ACME_API_TOKEN"],"provider_keys":{"openai":"sk-proj-xxxxxxxx"},"chatwoot_native_keys":{"openai":"sk-proj-xxxxxxxx"},"provider_keys_set":["openai"],"native_keys_set":["openai"],"use_global_fallback":true}}],"tools":[{"id":"cep_lookup","label":"Brazilian address by CEP (ViaCEP)","description":"Resolve a Brazilian postal code (CEP) to its address - no auth required.","tool":{"name":"cep_lookup","description":"Look up a Brazilian address by CEP (postal code).","method":"GET","url":"https://viacep.com.br/ws/{cep}/json/","extract":"","params":[{"name":"cep","type":"string","description":"CEP (8 digits)","required":true,"location":"path"}],"auth":{"type":"none"}}}],"sql":[{"id":"order_by_phone","label":"Latest order by phone","description":"Most recent order for a contact's phone number.","sql":"SELECT id, status, total, created_at FROM orders WHERE customer_phone = :phone ORDER BY created_at DESC LIMIT 5"}],"mappings":[{"id":"triage_and_label","label":"Triage \u0026 label","description":"Categorize every conversation with labels + custom attributes and set priority.","config":{"persona":"Você é a atendente virtual da Acme, cordial e objetiva.","instructions":"Sempre confirme o CPF antes de consultar um pedido.","default_model":"openai:gpt-5.4-mini-2026-03-17","fallback_models":["anthropic:claude-haiku-4-5-20251001"],"enabled_tools":["set_labels"],"autonomy_level":"autopilot","interaction_mode":"converse","search_config":{"enabled":true,"search_depth":"basic","max_results":5,"topic":"general","include_domains":["docs.example.com"],"exclude_domains":[]},"locale":"pt_BR","quiet_window_seconds":8,"max_window_seconds":40,"summary_threshold_tokens":3000,"standdown_on_assignment":true,"standdown_auto_resume":true,"standdown_ttl_seconds":86400,"paused_inbound_policy":"discard","paused_inbound_max_messages":10,"paused_inbound_max_age_seconds":3600,"handoff_team_id":3,"working_hours_policy":"ignore","out_of_office_message":"Nosso atendimento volta às 9h. Já registramos sua mensagem.","handoff_policy":{"target_status":"open","target_priority":"none","triggers":["falar com atendente"]},"guardrails":{"banned_topics":["assuntos jurídicos"],"blocked_phrases":["garantimos 100% de aprovação"],"max_output_chars":1200,"pii_policy":"off","require_handoff_conditions":["cliente pede cancelamento"]},"knowledge_base":{"enabled":true,"top_k":5,"use_shared":false},"database":{"enabled":false,"connection_secret":"ERP_DB_URL","read_only":true,"max_rows":200,"statement_timeout_seconds":15,"include_tables":["orders"],"description":"Pedidos e faturas do ERP.","instructions":"Sempre filtre por account_id."},"reactions":{"outbound":false,"understand_inbound":false},"media":{"audio":true,"vision":true,"documents":true},"close_on_complete":"off","verification_policy":"off","model_params":{"reasoning_effort":"low","temperature":0.4,"top_p":0.9,"max_output_tokens":512},"service_flow":{"enabled":false,"on_exit":"handoff","strict_tools":true,"steps":[{"key":"qualificacao","name":"Qualificação","goal":"Descobrir o segmento e o tamanho da empresa.","allowed_tools":["contact_update"],"exit":{"type":"tools_executed","tools":["contact_update"],"attributes":["segmento"],"max_turns":8},"next":"proposta"}]},"max_tool_iterations":8,"history_limit_messages":40,"tail_budget_tokens":1500,"hard_cap_tokens":6000,"chain_same_provider":"","delivery":{"quote_replies":true,"formatting":"auto"},"stt":{"provider":"groq","model":"groq:whisper-large-v3-turbo"},"embedding":{"provider":"openai","model":"text-embedding-3-small"},"voice":{"enabled":false,"mode":"off","with_text":false,"provider":"elevenlabs","model":"eleven_multilingual_v2","call_backend":"auto","call_model":"openai:gpt-realtime","voice_id":"21m00Tcm4TlvDq8ikWAM","openai_voice":"alloy","gemini_voice":"Kore","stability":0.5,"similarity_boost":0.75,"style":0,"use_speaker_boost":true,"speed":1,"instructions":"Fale de forma calma e acolhedora.","style_instructions":"Locução comercial, ritmo animado."},"image_gen":{"enabled":false,"provider":"openai","model":"gpt-image-1"},"video_gen":{"enabled":false,"provider":"openai","model":"sora-2"},"custom_tools":[{"name":"consultar_pedido","description":"Consulta o status de um pedido pelo número.","method":"GET","url":"https://api.acme.com/orders/{{order_id}}","sensitive":false,"extract":"data.status","body_type":"json","body_template":{"source":"maestro","order_id":"{{order_id}}"},"headers":{"X-Api-Version":"2026-01"},"query":{"include":"items"},"auth":{"type":"bearer","name":"X-Api-Key","token_secret":"ACME_API_TOKEN","username_secret":"ACME_USER","password_secret":"ACME_PASS"},"params":[{"name":"order_id","type":"string","description":"Número do pedido.","required":true,"location":"auto"}],"response_map":[{"label":"Status","path":"data.status"}],"pagination":{"type":"none","param":"page","items_path":"data","next_path":"meta.next","start":1,"max_pages":5,"size_param":"per_page","size":50}}],"mcp_servers":[{"name":"acme-erp","url":"https://mcp.acme.com/sse","transport":"streamable_http","timeout":30,"sensitive":false,"enabled_tools":["get_order"],"headers":{"X-Tenant":"acme"},"auth":{"type":"bearer","name":"X-Api-Key","token_secret":"ACME_MCP_TOKEN","username_secret":"ACME_USER","password_secret":"ACME_PASS"}}],"media_assets":[{"name":"catalogo_2026","description":"Catálogo completo em PDF.","url":"https://cdn.acme.com/catalogo.pdf","type":"file"}],"sub_agents":[{"agent_id":7,"name":"Vendas","slug":"vendas","description":"Perguntas sobre planos e preços.","enabled":true,"sensitive":false}],"secrets":{"ACME_API_TOKEN":"sk-live-xxxxxxxx"},"secret_keys":["ACME_API_TOKEN"],"provider_keys":{"openai":"sk-proj-xxxxxxxx"},"chatwoot_native_keys":{"openai":"sk-proj-xxxxxxxx"},"provider_keys_set":["openai"],"native_keys_set":["openai"],"use_global_fallback":true}}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"502":{"description":"The Maestro service could not be reached (connection refused or reset, host unresolvable), or it answered in a way the gateway could not use, or it rejected the server-to-server credential — the last one is a deployment key mismatch, never the caller's own session. Nothing was executed; the call can be retried.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"504":{"description":"The Maestro service did not answer within the proxy timeout. The work may still be running on the service side, so retrying a write can duplicate its effect.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"503":{"description":"The Maestro area is not serving this installation: an operator turned it off, or no admin key was ever provisioned. Nothing was executed, and retrying will not help until the configuration changes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"locale","in":"query","required":false,"description":"Locale the human copy (label, description, persona, instructions) is resolved to. Missing or blank is served in English; structural fields never vary with the locale.","schema":{"type":"string"},"example":"pt_BR"}]}},"/api/v1/accounts/{account_id}/maestro/agents/templates/generate":{"post":{"tags":["Maestro"],"operationId":"auto_post_api_v1_accounts_account_id_maestro_agents_templates_generate","summary":"Generate a Maestro agent preset on demand","description":"Generates a single ready-to-use agent preset for a niche the static templates catalog does not cover. Proxied to the sidecar, which returns one preset shaped exactly like a `templates.agents[]` entry ({ id, label, config }); the Studio merges the returned `config` into the agent form. The optional `locale` selects the language of the generated labels/instructions — a missing/blank value is treated as English. Admin-only; the sidecar re-validates the body (Pydantic -\u003e 422).","security":[{"userApiKey":[]}],"responses":{"200":{"description":"A single generated preset, shaped like one entry of the templates catalog's agents list.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Stable identifier for the generated preset.","example":"generated-clinica-odontologica"},"label":{"type":"string","description":"Human-readable preset label for the picker.","example":"Clínica odontológica"},"config":{"type":"object","additionalProperties":true,"description":"The agent configuration payload (AgentConfigIn shape — persona, instructions, tools, etc.), free-form here because the sidecar owns and re-validates the schema.","example":{"persona":"Atendente da clínica","instructions":"Responda dúvidas sobre procedimentos e agende avaliações em pt_BR.","default_model":"gpt-5.5"}}}},"example":{"id":"generated-clinica-odontologica","label":"Clínica odontológica","config":{"persona":"Atendente da clínica","instructions":"Responda dúvidas sobre procedimentos e agende avaliações em pt_BR.","default_model":"gpt-5.5"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"502":{"description":"The Maestro service could not be reached (connection refused or reset, host unresolvable), or it answered in a way the gateway could not use, or it rejected the server-to-server credential — the last one is a deployment key mismatch, never the caller's own session. Nothing was executed; the call can be retried.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"504":{"description":"The Maestro service did not answer within the proxy timeout. The work may still be running on the service side, so retrying a write can duplicate its effect.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"503":{"description":"The Maestro area is not serving this installation: an operator turned it off, or no admin key was ever provisioned. Nothing was executed, and retrying will not help until the configuration changes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["niche"],"properties":{"niche":{"type":"string","description":"The vertical / business niche to synthesize the preset for.","example":"Clínica odontológica"},"locale":{"type":"string","description":"UI language for the generated labels/instructions; blank/absent defaults to English.","example":"pt_BR"}}},"example":{"niche":"Clínica odontológica","locale":"pt_BR"}}}}}},"/api/v1/accounts/{account_id}/maestro/templates":{"get":{"tags":["Maestro"],"operationId":"auto_get_api_v1_accounts_account_id_maestro_templates","summary":"List the account's Modelos","description":"Every Modelo this account can see — its own (`scope: account`) plus the shared installation library (`scope: installation`). Read-only entries are still duplicable, which is how a shipped Modelo gets customized without being changed. Use `scope` to narrow the list.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The Modelos visible to this account, account-scoped ones first.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/maestro_template"}},"example":[{"id":12,"scope":"account","account_id":7,"slug":"atendimento_ecommerce","name":"Atendimento e-commerce","description":"Atendimento com rastreio de pedido e política de troca.","vertical":"ecommerce","origin":"custom","schema_version":1,"checksum":"8f14e45fceea167a5a36dedd4bea2543","editable":true,"created_by":"ana@acme.com","created_at":"2026-07-01T12:00:00Z","updated_at":"2026-07-27T14:03:00Z","config":{"persona":"Você é a atendente virtual da Acme, cordial e objetiva.","instructions":"Sempre confirme o CPF antes de consultar um pedido.","default_model":"openai:gpt-5.4-mini-2026-03-17","fallback_models":["anthropic:claude-haiku-4-5-20251001"],"enabled_tools":["set_labels"],"autonomy_level":"autopilot","interaction_mode":"converse","search_config":{"enabled":true,"search_depth":"basic","max_results":5,"topic":"general","include_domains":["docs.example.com"],"exclude_domains":[]},"locale":"pt_BR","quiet_window_seconds":8,"max_window_seconds":40,"summary_threshold_tokens":3000,"standdown_on_assignment":true,"standdown_auto_resume":true,"standdown_ttl_seconds":86400,"paused_inbound_policy":"discard","paused_inbound_max_messages":10,"paused_inbound_max_age_seconds":3600,"handoff_team_id":3,"working_hours_policy":"ignore","out_of_office_message":"Nosso atendimento volta às 9h. Já registramos sua mensagem.","handoff_policy":{"target_status":"open","target_priority":"none","triggers":["falar com atendente"]},"guardrails":{"banned_topics":["assuntos jurídicos"],"blocked_phrases":["garantimos 100% de aprovação"],"max_output_chars":1200,"pii_policy":"off","require_handoff_conditions":["cliente pede cancelamento"]},"knowledge_base":{"enabled":true,"top_k":5,"use_shared":false},"database":{"enabled":false,"connection_secret":"ERP_DB_URL","read_only":true,"max_rows":200,"statement_timeout_seconds":15,"include_tables":["orders"],"description":"Pedidos e faturas do ERP.","instructions":"Sempre filtre por account_id."},"reactions":{"outbound":false,"understand_inbound":false},"media":{"audio":true,"vision":true,"documents":true},"close_on_complete":"off","verification_policy":"off","model_params":{"reasoning_effort":"low","temperature":0.4,"top_p":0.9,"max_output_tokens":512},"service_flow":{"enabled":false,"on_exit":"handoff","strict_tools":true,"steps":[{"key":"qualificacao","name":"Qualificação","goal":"Descobrir o segmento e o tamanho da empresa.","allowed_tools":["contact_update"],"exit":{"type":"tools_executed","tools":["contact_update"],"attributes":["segmento"],"max_turns":8},"next":"proposta"}]},"max_tool_iterations":8,"history_limit_messages":40,"tail_budget_tokens":1500,"hard_cap_tokens":6000,"chain_same_provider":"","delivery":{"quote_replies":true,"formatting":"auto"},"stt":{"provider":"groq","model":"groq:whisper-large-v3-turbo"},"embedding":{"provider":"openai","model":"text-embedding-3-small"},"voice":{"enabled":false,"mode":"off","with_text":false,"provider":"elevenlabs","model":"eleven_multilingual_v2","call_backend":"auto","call_model":"openai:gpt-realtime","voice_id":"21m00Tcm4TlvDq8ikWAM","openai_voice":"alloy","gemini_voice":"Kore","stability":0.5,"similarity_boost":0.75,"style":0,"use_speaker_boost":true,"speed":1,"instructions":"Fale de forma calma e acolhedora.","style_instructions":"Locução comercial, ritmo animado."},"image_gen":{"enabled":false,"provider":"openai","model":"gpt-image-1"},"video_gen":{"enabled":false,"provider":"openai","model":"sora-2"},"custom_tools":[{"name":"consultar_pedido","description":"Consulta o status de um pedido pelo número.","method":"GET","url":"https://api.acme.com/orders/{{order_id}}","sensitive":false,"extract":"data.status","body_type":"json","body_template":{"source":"maestro","order_id":"{{order_id}}"},"headers":{"X-Api-Version":"2026-01"},"query":{"include":"items"},"auth":{"type":"bearer","name":"X-Api-Key","token_secret":"ACME_API_TOKEN","username_secret":"ACME_USER","password_secret":"ACME_PASS"},"params":[{"name":"order_id","type":"string","description":"Número do pedido.","required":true,"location":"auto"}],"response_map":[{"label":"Status","path":"data.status"}],"pagination":{"type":"none","param":"page","items_path":"data","next_path":"meta.next","start":1,"max_pages":5,"size_param":"per_page","size":50}}],"mcp_servers":[{"name":"acme-erp","url":"https://mcp.acme.com/sse","transport":"streamable_http","timeout":30,"sensitive":false,"enabled_tools":["get_order"],"headers":{"X-Tenant":"acme"},"auth":{"type":"bearer","name":"X-Api-Key","token_secret":"ACME_MCP_TOKEN","username_secret":"ACME_USER","password_secret":"ACME_PASS"}}],"media_assets":[{"name":"catalogo_2026","description":"Catálogo completo em PDF.","url":"https://cdn.acme.com/catalogo.pdf","type":"file"}],"sub_agents":[{"agent_id":7,"name":"Vendas","slug":"vendas","description":"Perguntas sobre planos e preços.","enabled":true,"sensitive":false}],"secrets":{"ACME_API_TOKEN":"sk-live-xxxxxxxx"},"secret_keys":["ACME_API_TOKEN"],"provider_keys":{"openai":"sk-proj-xxxxxxxx"},"chatwoot_native_keys":{"openai":"sk-proj-xxxxxxxx"},"provider_keys_set":["openai"],"native_keys_set":["openai"],"use_global_fallback":true}}]}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"502":{"description":"The Maestro service could not be reached (connection refused or reset, host unresolvable), or it answered in a way the gateway could not use, or it rejected the server-to-server credential — the last one is a deployment key mismatch, never the caller's own session. Nothing was executed; the call can be retried.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"504":{"description":"The Maestro service did not answer within the proxy timeout. The work may still be running on the service side, so retrying a write can duplicate its effect.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"503":{"description":"The Maestro area is not serving this installation: an operator turned it off, or no admin key was ever provisioned. Nothing was executed, and retrying will not help until the configuration changes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"scope","in":"query","required":false,"description":"Which library to read. Omitted means both.","schema":{"type":"string","enum":["all","account","installation"],"default":"all"}}]},"post":{"tags":["Maestro"],"operationId":"auto_post_api_v1_accounts_account_id_maestro_templates","summary":"Create a Modelo","description":"Stores a configuration in this account's library. `account_id`, `scope` and `created_by` are taken from the session and ignored if sent — an account-level caller can only ever write into its own library. Credentials are stripped before the row is written, and everything removed comes back in `stripped` so nothing disappears silently.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The stored Modelo plus every credential that had to be removed to store it.","content":{"application/json":{"schema":{"type":"object","properties":{"template":{"$ref":"#/components/schemas/maestro_template"},"stripped":{"type":"array","description":"Credentials removed on the way in. Empty when the configuration carried none.","items":{"$ref":"#/components/schemas/maestro_template_stripped_field"}}}},"example":{"template":{"id":12,"scope":"account","account_id":7,"slug":"atendimento_ecommerce","name":"Atendimento e-commerce","description":"Atendimento com rastreio de pedido e política de troca.","vertical":"ecommerce","origin":"custom","schema_version":1,"checksum":"8f14e45fceea167a5a36dedd4bea2543","editable":true,"created_by":"ana@acme.com","created_at":"2026-07-01T12:00:00Z","updated_at":"2026-07-27T14:03:00Z","config":{"persona":"Você é a atendente virtual da Acme, cordial e objetiva.","instructions":"Sempre confirme o CPF antes de consultar um pedido.","default_model":"openai:gpt-5.4-mini-2026-03-17","fallback_models":["anthropic:claude-haiku-4-5-20251001"],"enabled_tools":["set_labels"],"autonomy_level":"autopilot","interaction_mode":"converse","search_config":{"enabled":true,"search_depth":"basic","max_results":5,"topic":"general","include_domains":["docs.example.com"],"exclude_domains":[]},"locale":"pt_BR","quiet_window_seconds":8,"max_window_seconds":40,"summary_threshold_tokens":3000,"standdown_on_assignment":true,"standdown_auto_resume":true,"standdown_ttl_seconds":86400,"paused_inbound_policy":"discard","paused_inbound_max_messages":10,"paused_inbound_max_age_seconds":3600,"handoff_team_id":3,"working_hours_policy":"ignore","out_of_office_message":"Nosso atendimento volta às 9h. Já registramos sua mensagem.","handoff_policy":{"target_status":"open","target_priority":"none","triggers":["falar com atendente"]},"guardrails":{"banned_topics":["assuntos jurídicos"],"blocked_phrases":["garantimos 100% de aprovação"],"max_output_chars":1200,"pii_policy":"off","require_handoff_conditions":["cliente pede cancelamento"]},"knowledge_base":{"enabled":true,"top_k":5,"use_shared":false},"database":{"enabled":false,"connection_secret":"ERP_DB_URL","read_only":true,"max_rows":200,"statement_timeout_seconds":15,"include_tables":["orders"],"description":"Pedidos e faturas do ERP.","instructions":"Sempre filtre por account_id."},"reactions":{"outbound":false,"understand_inbound":false},"media":{"audio":true,"vision":true,"documents":true},"close_on_complete":"off","verification_policy":"off","model_params":{"reasoning_effort":"low","temperature":0.4,"top_p":0.9,"max_output_tokens":512},"service_flow":{"enabled":false,"on_exit":"handoff","strict_tools":true,"steps":[{"key":"qualificacao","name":"Qualificação","goal":"Descobrir o segmento e o tamanho da empresa.","allowed_tools":["contact_update"],"exit":{"type":"tools_executed","tools":["contact_update"],"attributes":["segmento"],"max_turns":8},"next":"proposta"}]},"max_tool_iterations":8,"history_limit_messages":40,"tail_budget_tokens":1500,"hard_cap_tokens":6000,"chain_same_provider":"","delivery":{"quote_replies":true,"formatting":"auto"},"stt":{"provider":"groq","model":"groq:whisper-large-v3-turbo"},"embedding":{"provider":"openai","model":"text-embedding-3-small"},"voice":{"enabled":false,"mode":"off","with_text":false,"provider":"elevenlabs","model":"eleven_multilingual_v2","call_backend":"auto","call_model":"openai:gpt-realtime","voice_id":"21m00Tcm4TlvDq8ikWAM","openai_voice":"alloy","gemini_voice":"Kore","stability":0.5,"similarity_boost":0.75,"style":0,"use_speaker_boost":true,"speed":1,"instructions":"Fale de forma calma e acolhedora.","style_instructions":"Locução comercial, ritmo animado."},"image_gen":{"enabled":false,"provider":"openai","model":"gpt-image-1"},"video_gen":{"enabled":false,"provider":"openai","model":"sora-2"},"custom_tools":[{"name":"consultar_pedido","description":"Consulta o status de um pedido pelo número.","method":"GET","url":"https://api.acme.com/orders/{{order_id}}","sensitive":false,"extract":"data.status","body_type":"json","body_template":{"source":"maestro","order_id":"{{order_id}}"},"headers":{"X-Api-Version":"2026-01"},"query":{"include":"items"},"auth":{"type":"bearer","name":"X-Api-Key","token_secret":"ACME_API_TOKEN","username_secret":"ACME_USER","password_secret":"ACME_PASS"},"params":[{"name":"order_id","type":"string","description":"Número do pedido.","required":true,"location":"auto"}],"response_map":[{"label":"Status","path":"data.status"}],"pagination":{"type":"none","param":"page","items_path":"data","next_path":"meta.next","start":1,"max_pages":5,"size_param":"per_page","size":50}}],"mcp_servers":[{"name":"acme-erp","url":"https://mcp.acme.com/sse","transport":"streamable_http","timeout":30,"sensitive":false,"enabled_tools":["get_order"],"headers":{"X-Tenant":"acme"},"auth":{"type":"bearer","name":"X-Api-Key","token_secret":"ACME_MCP_TOKEN","username_secret":"ACME_USER","password_secret":"ACME_PASS"}}],"media_assets":[{"name":"catalogo_2026","description":"Catálogo completo em PDF.","url":"https://cdn.acme.com/catalogo.pdf","type":"file"}],"sub_agents":[{"agent_id":7,"name":"Vendas","slug":"vendas","description":"Perguntas sobre planos e preços.","enabled":true,"sensitive":false}],"secrets":{"ACME_API_TOKEN":"sk-live-xxxxxxxx"},"secret_keys":["ACME_API_TOKEN"],"provider_keys":{"openai":"sk-proj-xxxxxxxx"},"chatwoot_native_keys":{"openai":"sk-proj-xxxxxxxx"},"provider_keys_set":["openai"],"native_keys_set":["openai"],"use_global_fallback":true}},"stripped":[{"field":"tools.http.headers.Authorization","kind":"value"}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"502":{"description":"The Maestro service could not be reached (connection refused or reset, host unresolvable), or it answered in a way the gateway could not use, or it rejected the server-to-server credential — the last one is a deployment key mismatch, never the caller's own session. Nothing was executed; the call can be retried.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"504":{"description":"The Maestro service did not answer within the proxy timeout. The work may still be running on the service side, so retrying a write can duplicate its effect.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"503":{"description":"The Maestro area is not serving this installation: an operator turned it off, or no admin key was ever provisioned. Nothing was executed, and retrying will not help until the configuration changes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"201":{"description":"The stored Modelo plus every credential that had to be removed to store it.","content":{"application/json":{"schema":{"type":"object","properties":{"template":{"$ref":"#/components/schemas/maestro_template"},"stripped":{"type":"array","description":"Credentials removed on the way in. Empty when the configuration carried none.","items":{"$ref":"#/components/schemas/maestro_template_stripped_field"}}}},"example":{"template":{"id":12,"scope":"account","account_id":7,"slug":"atendimento_ecommerce","name":"Atendimento e-commerce","description":"Atendimento com rastreio de pedido e política de troca.","vertical":"ecommerce","origin":"custom","schema_version":1,"checksum":"8f14e45fceea167a5a36dedd4bea2543","editable":true,"created_by":"ana@acme.com","created_at":"2026-07-01T12:00:00Z","updated_at":"2026-07-27T14:03:00Z","config":{"persona":"Você é a atendente virtual da Acme, cordial e objetiva.","instructions":"Sempre confirme o CPF antes de consultar um pedido.","default_model":"openai:gpt-5.4-mini-2026-03-17","fallback_models":["anthropic:claude-haiku-4-5-20251001"],"enabled_tools":["set_labels"],"autonomy_level":"autopilot","interaction_mode":"converse","search_config":{"enabled":true,"search_depth":"basic","max_results":5,"topic":"general","include_domains":["docs.example.com"],"exclude_domains":[]},"locale":"pt_BR","quiet_window_seconds":8,"max_window_seconds":40,"summary_threshold_tokens":3000,"standdown_on_assignment":true,"standdown_auto_resume":true,"standdown_ttl_seconds":86400,"paused_inbound_policy":"discard","paused_inbound_max_messages":10,"paused_inbound_max_age_seconds":3600,"handoff_team_id":3,"working_hours_policy":"ignore","out_of_office_message":"Nosso atendimento volta às 9h. Já registramos sua mensagem.","handoff_policy":{"target_status":"open","target_priority":"none","triggers":["falar com atendente"]},"guardrails":{"banned_topics":["assuntos jurídicos"],"blocked_phrases":["garantimos 100% de aprovação"],"max_output_chars":1200,"pii_policy":"off","require_handoff_conditions":["cliente pede cancelamento"]},"knowledge_base":{"enabled":true,"top_k":5,"use_shared":false},"database":{"enabled":false,"connection_secret":"ERP_DB_URL","read_only":true,"max_rows":200,"statement_timeout_seconds":15,"include_tables":["orders"],"description":"Pedidos e faturas do ERP.","instructions":"Sempre filtre por account_id."},"reactions":{"outbound":false,"understand_inbound":false},"media":{"audio":true,"vision":true,"documents":true},"close_on_complete":"off","verification_policy":"off","model_params":{"reasoning_effort":"low","temperature":0.4,"top_p":0.9,"max_output_tokens":512},"service_flow":{"enabled":false,"on_exit":"handoff","strict_tools":true,"steps":[{"key":"qualificacao","name":"Qualificação","goal":"Descobrir o segmento e o tamanho da empresa.","allowed_tools":["contact_update"],"exit":{"type":"tools_executed","tools":["contact_update"],"attributes":["segmento"],"max_turns":8},"next":"proposta"}]},"max_tool_iterations":8,"history_limit_messages":40,"tail_budget_tokens":1500,"hard_cap_tokens":6000,"chain_same_provider":"","delivery":{"quote_replies":true,"formatting":"auto"},"stt":{"provider":"groq","model":"groq:whisper-large-v3-turbo"},"embedding":{"provider":"openai","model":"text-embedding-3-small"},"voice":{"enabled":false,"mode":"off","with_text":false,"provider":"elevenlabs","model":"eleven_multilingual_v2","call_backend":"auto","call_model":"openai:gpt-realtime","voice_id":"21m00Tcm4TlvDq8ikWAM","openai_voice":"alloy","gemini_voice":"Kore","stability":0.5,"similarity_boost":0.75,"style":0,"use_speaker_boost":true,"speed":1,"instructions":"Fale de forma calma e acolhedora.","style_instructions":"Locução comercial, ritmo animado."},"image_gen":{"enabled":false,"provider":"openai","model":"gpt-image-1"},"video_gen":{"enabled":false,"provider":"openai","model":"sora-2"},"custom_tools":[{"name":"consultar_pedido","description":"Consulta o status de um pedido pelo número.","method":"GET","url":"https://api.acme.com/orders/{{order_id}}","sensitive":false,"extract":"data.status","body_type":"json","body_template":{"source":"maestro","order_id":"{{order_id}}"},"headers":{"X-Api-Version":"2026-01"},"query":{"include":"items"},"auth":{"type":"bearer","name":"X-Api-Key","token_secret":"ACME_API_TOKEN","username_secret":"ACME_USER","password_secret":"ACME_PASS"},"params":[{"name":"order_id","type":"string","description":"Número do pedido.","required":true,"location":"auto"}],"response_map":[{"label":"Status","path":"data.status"}],"pagination":{"type":"none","param":"page","items_path":"data","next_path":"meta.next","start":1,"max_pages":5,"size_param":"per_page","size":50}}],"mcp_servers":[{"name":"acme-erp","url":"https://mcp.acme.com/sse","transport":"streamable_http","timeout":30,"sensitive":false,"enabled_tools":["get_order"],"headers":{"X-Tenant":"acme"},"auth":{"type":"bearer","name":"X-Api-Key","token_secret":"ACME_MCP_TOKEN","username_secret":"ACME_USER","password_secret":"ACME_PASS"}}],"media_assets":[{"name":"catalogo_2026","description":"Catálogo completo em PDF.","url":"https://cdn.acme.com/catalogo.pdf","type":"file"}],"sub_agents":[{"agent_id":7,"name":"Vendas","slug":"vendas","description":"Perguntas sobre planos e preços.","enabled":true,"sensitive":false}],"secrets":{"ACME_API_TOKEN":"sk-live-xxxxxxxx"},"secret_keys":["ACME_API_TOKEN"],"provider_keys":{"openai":"sk-proj-xxxxxxxx"},"chatwoot_native_keys":{"openai":"sk-proj-xxxxxxxx"},"provider_keys_set":["openai"],"native_keys_set":["openai"],"use_global_fallback":true}},"stripped":[{"field":"tools.http.headers.Authorization","kind":"value"}]}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","description":"Display name of the Modelo.","example":"Atendimento e-commerce"},"slug":{"type":"string","description":"Stable machine key. Derived from `name` when omitted.","example":"atendimento_ecommerce"},"description":{"type":"string","description":"What this Modelo is for.","example":"Atendimento com rastreio de pedido e política de troca."},"vertical":{"type":"string","description":"Business vertical, used to group the library.","example":"ecommerce"},"origin":{"type":"string","description":"How it was authored. Defaults to `custom`.","enum":["custom","imported","generated"],"example":"custom"},"config":{"$ref":"#/components/schemas/maestro_agent_config"}}},"example":{"name":"Atendimento e-commerce","slug":"atendimento_ecommerce","description":"Atendimento com rastreio de pedido e política de troca.","vertical":"ecommerce","origin":"custom","config":{"persona":"Você é a atendente virtual da Acme, cordial e objetiva.","instructions":"Sempre confirme o CPF antes de consultar um pedido.","default_model":"openai:gpt-5.4-mini-2026-03-17","fallback_models":["anthropic:claude-haiku-4-5-20251001"],"enabled_tools":["set_labels"],"autonomy_level":"autopilot","interaction_mode":"converse","search_config":{"enabled":true,"search_depth":"basic","max_results":5,"topic":"general","include_domains":["docs.example.com"],"exclude_domains":[]},"locale":"pt_BR","quiet_window_seconds":8,"max_window_seconds":40,"summary_threshold_tokens":3000,"standdown_on_assignment":true,"standdown_auto_resume":true,"standdown_ttl_seconds":86400,"paused_inbound_policy":"discard","paused_inbound_max_messages":10,"paused_inbound_max_age_seconds":3600,"handoff_team_id":3,"working_hours_policy":"ignore","out_of_office_message":"Nosso atendimento volta às 9h. Já registramos sua mensagem.","handoff_policy":{"target_status":"open","target_priority":"none","triggers":["falar com atendente"]},"guardrails":{"banned_topics":["assuntos jurídicos"],"blocked_phrases":["garantimos 100% de aprovação"],"max_output_chars":1200,"pii_policy":"off","require_handoff_conditions":["cliente pede cancelamento"]},"knowledge_base":{"enabled":true,"top_k":5,"use_shared":false},"database":{"enabled":false,"connection_secret":"ERP_DB_URL","read_only":true,"max_rows":200,"statement_timeout_seconds":15,"include_tables":["orders"],"description":"Pedidos e faturas do ERP.","instructions":"Sempre filtre por account_id."},"reactions":{"outbound":false,"understand_inbound":false},"media":{"audio":true,"vision":true,"documents":true},"close_on_complete":"off","verification_policy":"off","model_params":{"reasoning_effort":"low","temperature":0.4,"top_p":0.9,"max_output_tokens":512},"service_flow":{"enabled":false,"on_exit":"handoff","strict_tools":true,"steps":[{"key":"qualificacao","name":"Qualificação","goal":"Descobrir o segmento e o tamanho da empresa.","allowed_tools":["contact_update"],"exit":{"type":"tools_executed","tools":["contact_update"],"attributes":["segmento"],"max_turns":8},"next":"proposta"}]},"max_tool_iterations":8,"history_limit_messages":40,"tail_budget_tokens":1500,"hard_cap_tokens":6000,"chain_same_provider":"","delivery":{"quote_replies":true,"formatting":"auto"},"stt":{"provider":"groq","model":"groq:whisper-large-v3-turbo"},"embedding":{"provider":"openai","model":"text-embedding-3-small"},"voice":{"enabled":false,"mode":"off","with_text":false,"provider":"elevenlabs","model":"eleven_multilingual_v2","call_backend":"auto","call_model":"openai:gpt-realtime","voice_id":"21m00Tcm4TlvDq8ikWAM","openai_voice":"alloy","gemini_voice":"Kore","stability":0.5,"similarity_boost":0.75,"style":0,"use_speaker_boost":true,"speed":1,"instructions":"Fale de forma calma e acolhedora.","style_instructions":"Locução comercial, ritmo animado."},"image_gen":{"enabled":false,"provider":"openai","model":"gpt-image-1"},"video_gen":{"enabled":false,"provider":"openai","model":"sora-2"},"custom_tools":[{"name":"consultar_pedido","description":"Consulta o status de um pedido pelo número.","method":"GET","url":"https://api.acme.com/orders/{{order_id}}","sensitive":false,"extract":"data.status","body_type":"json","body_template":{"source":"maestro","order_id":"{{order_id}}"},"headers":{"X-Api-Version":"2026-01"},"query":{"include":"items"},"auth":{"type":"bearer","name":"X-Api-Key","token_secret":"ACME_API_TOKEN","username_secret":"ACME_USER","password_secret":"ACME_PASS"},"params":[{"name":"order_id","type":"string","description":"Número do pedido.","required":true,"location":"auto"}],"response_map":[{"label":"Status","path":"data.status"}],"pagination":{"type":"none","param":"page","items_path":"data","next_path":"meta.next","start":1,"max_pages":5,"size_param":"per_page","size":50}}],"mcp_servers":[{"name":"acme-erp","url":"https://mcp.acme.com/sse","transport":"streamable_http","timeout":30,"sensitive":false,"enabled_tools":["get_order"],"headers":{"X-Tenant":"acme"},"auth":{"type":"bearer","name":"X-Api-Key","token_secret":"ACME_MCP_TOKEN","username_secret":"ACME_USER","password_secret":"ACME_PASS"}}],"media_assets":[{"name":"catalogo_2026","description":"Catálogo completo em PDF.","url":"https://cdn.acme.com/catalogo.pdf","type":"file"}],"sub_agents":[{"agent_id":7,"name":"Vendas","slug":"vendas","description":"Perguntas sobre planos e preços.","enabled":true,"sensitive":false}],"secrets":{"ACME_API_TOKEN":"sk-live-xxxxxxxx"},"secret_keys":["ACME_API_TOKEN"],"provider_keys":{"openai":"sk-proj-xxxxxxxx"},"chatwoot_native_keys":{"openai":"sk-proj-xxxxxxxx"},"provider_keys_set":["openai"],"native_keys_set":["openai"],"use_global_fallback":true}}}}}}},"/api/v1/accounts/{account_id}/maestro/templates/import":{"post":{"tags":["Maestro"],"operationId":"auto_post_api_v1_accounts_account_id_maestro_templates_import","summary":"Import a Modelo document","description":"Reads a `.maestro-template.json` into this account's library. An unreadable or unsupported document is refused whole rather than imported in half — a half-read Modelo is a Robô that LOOKS configured. Per-installation references (teams, contact-attribute keys) are re-matched by NAME, never by id, and anything that found no local match is reported in `references` as cleared instead of being invented.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The stored Modelo plus an honest account of what did and did not survive the trip.","content":{"application/json":{"schema":{"type":"object","properties":{"template":{"$ref":"#/components/schemas/maestro_template"},"stripped":{"type":"array","description":"Credentials removed on the way in.","items":{"$ref":"#/components/schemas/maestro_template_stripped_field"}},"references":{"type":"array","description":"What happened to each per-installation reference.","items":{"$ref":"#/components/schemas/maestro_template_reference_outcome"}}}},"example":{"template":{"id":12,"scope":"account","account_id":7,"slug":"atendimento_ecommerce","name":"Atendimento e-commerce","description":"Atendimento com rastreio de pedido e política de troca.","vertical":"ecommerce","origin":"custom","schema_version":1,"checksum":"8f14e45fceea167a5a36dedd4bea2543","editable":true,"created_by":"ana@acme.com","created_at":"2026-07-01T12:00:00Z","updated_at":"2026-07-27T14:03:00Z","config":{"persona":"Você é a atendente virtual da Acme, cordial e objetiva.","instructions":"Sempre confirme o CPF antes de consultar um pedido.","default_model":"openai:gpt-5.4-mini-2026-03-17","fallback_models":["anthropic:claude-haiku-4-5-20251001"],"enabled_tools":["set_labels"],"autonomy_level":"autopilot","interaction_mode":"converse","search_config":{"enabled":true,"search_depth":"basic","max_results":5,"topic":"general","include_domains":["docs.example.com"],"exclude_domains":[]},"locale":"pt_BR","quiet_window_seconds":8,"max_window_seconds":40,"summary_threshold_tokens":3000,"standdown_on_assignment":true,"standdown_auto_resume":true,"standdown_ttl_seconds":86400,"paused_inbound_policy":"discard","paused_inbound_max_messages":10,"paused_inbound_max_age_seconds":3600,"handoff_team_id":3,"working_hours_policy":"ignore","out_of_office_message":"Nosso atendimento volta às 9h. Já registramos sua mensagem.","handoff_policy":{"target_status":"open","target_priority":"none","triggers":["falar com atendente"]},"guardrails":{"banned_topics":["assuntos jurídicos"],"blocked_phrases":["garantimos 100% de aprovação"],"max_output_chars":1200,"pii_policy":"off","require_handoff_conditions":["cliente pede cancelamento"]},"knowledge_base":{"enabled":true,"top_k":5,"use_shared":false},"database":{"enabled":false,"connection_secret":"ERP_DB_URL","read_only":true,"max_rows":200,"statement_timeout_seconds":15,"include_tables":["orders"],"description":"Pedidos e faturas do ERP.","instructions":"Sempre filtre por account_id."},"reactions":{"outbound":false,"understand_inbound":false},"media":{"audio":true,"vision":true,"documents":true},"close_on_complete":"off","verification_policy":"off","model_params":{"reasoning_effort":"low","temperature":0.4,"top_p":0.9,"max_output_tokens":512},"service_flow":{"enabled":false,"on_exit":"handoff","strict_tools":true,"steps":[{"key":"qualificacao","name":"Qualificação","goal":"Descobrir o segmento e o tamanho da empresa.","allowed_tools":["contact_update"],"exit":{"type":"tools_executed","tools":["contact_update"],"attributes":["segmento"],"max_turns":8},"next":"proposta"}]},"max_tool_iterations":8,"history_limit_messages":40,"tail_budget_tokens":1500,"hard_cap_tokens":6000,"chain_same_provider":"","delivery":{"quote_replies":true,"formatting":"auto"},"stt":{"provider":"groq","model":"groq:whisper-large-v3-turbo"},"embedding":{"provider":"openai","model":"text-embedding-3-small"},"voice":{"enabled":false,"mode":"off","with_text":false,"provider":"elevenlabs","model":"eleven_multilingual_v2","call_backend":"auto","call_model":"openai:gpt-realtime","voice_id":"21m00Tcm4TlvDq8ikWAM","openai_voice":"alloy","gemini_voice":"Kore","stability":0.5,"similarity_boost":0.75,"style":0,"use_speaker_boost":true,"speed":1,"instructions":"Fale de forma calma e acolhedora.","style_instructions":"Locução comercial, ritmo animado."},"image_gen":{"enabled":false,"provider":"openai","model":"gpt-image-1"},"video_gen":{"enabled":false,"provider":"openai","model":"sora-2"},"custom_tools":[{"name":"consultar_pedido","description":"Consulta o status de um pedido pelo número.","method":"GET","url":"https://api.acme.com/orders/{{order_id}}","sensitive":false,"extract":"data.status","body_type":"json","body_template":{"source":"maestro","order_id":"{{order_id}}"},"headers":{"X-Api-Version":"2026-01"},"query":{"include":"items"},"auth":{"type":"bearer","name":"X-Api-Key","token_secret":"ACME_API_TOKEN","username_secret":"ACME_USER","password_secret":"ACME_PASS"},"params":[{"name":"order_id","type":"string","description":"Número do pedido.","required":true,"location":"auto"}],"response_map":[{"label":"Status","path":"data.status"}],"pagination":{"type":"none","param":"page","items_path":"data","next_path":"meta.next","start":1,"max_pages":5,"size_param":"per_page","size":50}}],"mcp_servers":[{"name":"acme-erp","url":"https://mcp.acme.com/sse","transport":"streamable_http","timeout":30,"sensitive":false,"enabled_tools":["get_order"],"headers":{"X-Tenant":"acme"},"auth":{"type":"bearer","name":"X-Api-Key","token_secret":"ACME_MCP_TOKEN","username_secret":"ACME_USER","password_secret":"ACME_PASS"}}],"media_assets":[{"name":"catalogo_2026","description":"Catálogo completo em PDF.","url":"https://cdn.acme.com/catalogo.pdf","type":"file"}],"sub_agents":[{"agent_id":7,"name":"Vendas","slug":"vendas","description":"Perguntas sobre planos e preços.","enabled":true,"sensitive":false}],"secrets":{"ACME_API_TOKEN":"sk-live-xxxxxxxx"},"secret_keys":["ACME_API_TOKEN"],"provider_keys":{"openai":"sk-proj-xxxxxxxx"},"chatwoot_native_keys":{"openai":"sk-proj-xxxxxxxx"},"provider_keys_set":["openai"],"native_keys_set":["openai"],"use_global_fallback":true}},"stripped":[{"field":"tools.http.headers.Authorization","kind":"value"}],"references":[{"field":"handoff_policy.team","action":"remapped","name":"Suporte N2","detail":"matched team by name"}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"502":{"description":"The Maestro service could not be reached (connection refused or reset, host unresolvable), or it answered in a way the gateway could not use, or it rejected the server-to-server credential — the last one is a deployment key mismatch, never the caller's own session. Nothing was executed; the call can be retried.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"504":{"description":"The Maestro service did not answer within the proxy timeout. The work may still be running on the service side, so retrying a write can duplicate its effect.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"503":{"description":"The Maestro area is not serving this installation: an operator turned it off, or no admin key was ever provisioned. Nothing was executed, and retrying will not help until the configuration changes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"201":{"description":"The stored Modelo plus an honest account of what did and did not survive the trip.","content":{"application/json":{"schema":{"type":"object","properties":{"template":{"$ref":"#/components/schemas/maestro_template"},"stripped":{"type":"array","description":"Credentials removed on the way in.","items":{"$ref":"#/components/schemas/maestro_template_stripped_field"}},"references":{"type":"array","description":"What happened to each per-installation reference.","items":{"$ref":"#/components/schemas/maestro_template_reference_outcome"}}}},"example":{"template":{"id":12,"scope":"account","account_id":7,"slug":"atendimento_ecommerce","name":"Atendimento e-commerce","description":"Atendimento com rastreio de pedido e política de troca.","vertical":"ecommerce","origin":"custom","schema_version":1,"checksum":"8f14e45fceea167a5a36dedd4bea2543","editable":true,"created_by":"ana@acme.com","created_at":"2026-07-01T12:00:00Z","updated_at":"2026-07-27T14:03:00Z","config":{"persona":"Você é a atendente virtual da Acme, cordial e objetiva.","instructions":"Sempre confirme o CPF antes de consultar um pedido.","default_model":"openai:gpt-5.4-mini-2026-03-17","fallback_models":["anthropic:claude-haiku-4-5-20251001"],"enabled_tools":["set_labels"],"autonomy_level":"autopilot","interaction_mode":"converse","search_config":{"enabled":true,"search_depth":"basic","max_results":5,"topic":"general","include_domains":["docs.example.com"],"exclude_domains":[]},"locale":"pt_BR","quiet_window_seconds":8,"max_window_seconds":40,"summary_threshold_tokens":3000,"standdown_on_assignment":true,"standdown_auto_resume":true,"standdown_ttl_seconds":86400,"paused_inbound_policy":"discard","paused_inbound_max_messages":10,"paused_inbound_max_age_seconds":3600,"handoff_team_id":3,"working_hours_policy":"ignore","out_of_office_message":"Nosso atendimento volta às 9h. Já registramos sua mensagem.","handoff_policy":{"target_status":"open","target_priority":"none","triggers":["falar com atendente"]},"guardrails":{"banned_topics":["assuntos jurídicos"],"blocked_phrases":["garantimos 100% de aprovação"],"max_output_chars":1200,"pii_policy":"off","require_handoff_conditions":["cliente pede cancelamento"]},"knowledge_base":{"enabled":true,"top_k":5,"use_shared":false},"database":{"enabled":false,"connection_secret":"ERP_DB_URL","read_only":true,"max_rows":200,"statement_timeout_seconds":15,"include_tables":["orders"],"description":"Pedidos e faturas do ERP.","instructions":"Sempre filtre por account_id."},"reactions":{"outbound":false,"understand_inbound":false},"media":{"audio":true,"vision":true,"documents":true},"close_on_complete":"off","verification_policy":"off","model_params":{"reasoning_effort":"low","temperature":0.4,"top_p":0.9,"max_output_tokens":512},"service_flow":{"enabled":false,"on_exit":"handoff","strict_tools":true,"steps":[{"key":"qualificacao","name":"Qualificação","goal":"Descobrir o segmento e o tamanho da empresa.","allowed_tools":["contact_update"],"exit":{"type":"tools_executed","tools":["contact_update"],"attributes":["segmento"],"max_turns":8},"next":"proposta"}]},"max_tool_iterations":8,"history_limit_messages":40,"tail_budget_tokens":1500,"hard_cap_tokens":6000,"chain_same_provider":"","delivery":{"quote_replies":true,"formatting":"auto"},"stt":{"provider":"groq","model":"groq:whisper-large-v3-turbo"},"embedding":{"provider":"openai","model":"text-embedding-3-small"},"voice":{"enabled":false,"mode":"off","with_text":false,"provider":"elevenlabs","model":"eleven_multilingual_v2","call_backend":"auto","call_model":"openai:gpt-realtime","voice_id":"21m00Tcm4TlvDq8ikWAM","openai_voice":"alloy","gemini_voice":"Kore","stability":0.5,"similarity_boost":0.75,"style":0,"use_speaker_boost":true,"speed":1,"instructions":"Fale de forma calma e acolhedora.","style_instructions":"Locução comercial, ritmo animado."},"image_gen":{"enabled":false,"provider":"openai","model":"gpt-image-1"},"video_gen":{"enabled":false,"provider":"openai","model":"sora-2"},"custom_tools":[{"name":"consultar_pedido","description":"Consulta o status de um pedido pelo número.","method":"GET","url":"https://api.acme.com/orders/{{order_id}}","sensitive":false,"extract":"data.status","body_type":"json","body_template":{"source":"maestro","order_id":"{{order_id}}"},"headers":{"X-Api-Version":"2026-01"},"query":{"include":"items"},"auth":{"type":"bearer","name":"X-Api-Key","token_secret":"ACME_API_TOKEN","username_secret":"ACME_USER","password_secret":"ACME_PASS"},"params":[{"name":"order_id","type":"string","description":"Número do pedido.","required":true,"location":"auto"}],"response_map":[{"label":"Status","path":"data.status"}],"pagination":{"type":"none","param":"page","items_path":"data","next_path":"meta.next","start":1,"max_pages":5,"size_param":"per_page","size":50}}],"mcp_servers":[{"name":"acme-erp","url":"https://mcp.acme.com/sse","transport":"streamable_http","timeout":30,"sensitive":false,"enabled_tools":["get_order"],"headers":{"X-Tenant":"acme"},"auth":{"type":"bearer","name":"X-Api-Key","token_secret":"ACME_MCP_TOKEN","username_secret":"ACME_USER","password_secret":"ACME_PASS"}}],"media_assets":[{"name":"catalogo_2026","description":"Catálogo completo em PDF.","url":"https://cdn.acme.com/catalogo.pdf","type":"file"}],"sub_agents":[{"agent_id":7,"name":"Vendas","slug":"vendas","description":"Perguntas sobre planos e preços.","enabled":true,"sensitive":false}],"secrets":{"ACME_API_TOKEN":"sk-live-xxxxxxxx"},"secret_keys":["ACME_API_TOKEN"],"provider_keys":{"openai":"sk-proj-xxxxxxxx"},"chatwoot_native_keys":{"openai":"sk-proj-xxxxxxxx"},"provider_keys_set":["openai"],"native_keys_set":["openai"],"use_global_fallback":true}},"stripped":[{"field":"tools.http.headers.Authorization","kind":"value"}],"references":[{"field":"handoff_policy.team","action":"remapped","name":"Suporte N2","detail":"matched team by name"}]}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["document"],"properties":{"document":{"type":"object","additionalProperties":true,"description":"The `.maestro-template.json` document, verbatim. A free object on purpose — it is a third-party file; the sidecar validates it and reports what did not survive the trip.","example":{"schema_version":1,"name":"Atendimento e-commerce","slug":"atendimento_ecommerce","config":{}}},"name":{"type":"string","description":"Override the document's name. Empty keeps the document's own.","example":"Atendimento e-commerce (importado)"},"slug":{"type":"string","description":"Override the document's slug. Empty keeps the document's own.","example":"atendimento_ecommerce_importado"},"resolve_references":{"type":"boolean","description":"Re-match teams and contact-attribute keys against this installation. Turn it off to import without any platform round-trip — every reference is then reported as cleared, so an import still works when the platform is unreachable.","example":true}}},"example":{"document":{"schema_version":1,"name":"Atendimento e-commerce","slug":"atendimento_ecommerce","config":{}},"name":"Atendimento e-commerce (importado)","slug":"atendimento_ecommerce_importado","resolve_references":true}}}}}},"/api/v1/accounts/{account_id}/maestro/templates/from-agent":{"post":{"tags":["Maestro"],"operationId":"auto_post_api_v1_accounts_account_id_maestro_templates_from_agent","summary":"Save a Robô as a Modelo","description":"Snapshots an existing Robô's configuration into the library. The Robô itself is untouched. Secrets do NOT travel: they are stripped on the way in and listed in `stripped`, which is what makes the result safe to duplicate, export and carry to another installation.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The stored Modelo plus every credential that was stripped out of the snapshot.","content":{"application/json":{"schema":{"type":"object","properties":{"template":{"$ref":"#/components/schemas/maestro_template"},"stripped":{"type":"array","description":"Credentials removed from the Robô's configuration on the way in.","items":{"$ref":"#/components/schemas/maestro_template_stripped_field"}}}},"example":{"template":{"id":12,"scope":"account","account_id":7,"slug":"atendimento_ecommerce","name":"Atendimento e-commerce","description":"Atendimento com rastreio de pedido e política de troca.","vertical":"ecommerce","origin":"custom","schema_version":1,"checksum":"8f14e45fceea167a5a36dedd4bea2543","editable":true,"created_by":"ana@acme.com","created_at":"2026-07-01T12:00:00Z","updated_at":"2026-07-27T14:03:00Z","config":{"persona":"Você é a atendente virtual da Acme, cordial e objetiva.","instructions":"Sempre confirme o CPF antes de consultar um pedido.","default_model":"openai:gpt-5.4-mini-2026-03-17","fallback_models":["anthropic:claude-haiku-4-5-20251001"],"enabled_tools":["set_labels"],"autonomy_level":"autopilot","interaction_mode":"converse","search_config":{"enabled":true,"search_depth":"basic","max_results":5,"topic":"general","include_domains":["docs.example.com"],"exclude_domains":[]},"locale":"pt_BR","quiet_window_seconds":8,"max_window_seconds":40,"summary_threshold_tokens":3000,"standdown_on_assignment":true,"standdown_auto_resume":true,"standdown_ttl_seconds":86400,"paused_inbound_policy":"discard","paused_inbound_max_messages":10,"paused_inbound_max_age_seconds":3600,"handoff_team_id":3,"working_hours_policy":"ignore","out_of_office_message":"Nosso atendimento volta às 9h. Já registramos sua mensagem.","handoff_policy":{"target_status":"open","target_priority":"none","triggers":["falar com atendente"]},"guardrails":{"banned_topics":["assuntos jurídicos"],"blocked_phrases":["garantimos 100% de aprovação"],"max_output_chars":1200,"pii_policy":"off","require_handoff_conditions":["cliente pede cancelamento"]},"knowledge_base":{"enabled":true,"top_k":5,"use_shared":false},"database":{"enabled":false,"connection_secret":"ERP_DB_URL","read_only":true,"max_rows":200,"statement_timeout_seconds":15,"include_tables":["orders"],"description":"Pedidos e faturas do ERP.","instructions":"Sempre filtre por account_id."},"reactions":{"outbound":false,"understand_inbound":false},"media":{"audio":true,"vision":true,"documents":true},"close_on_complete":"off","verification_policy":"off","model_params":{"reasoning_effort":"low","temperature":0.4,"top_p":0.9,"max_output_tokens":512},"service_flow":{"enabled":false,"on_exit":"handoff","strict_tools":true,"steps":[{"key":"qualificacao","name":"Qualificação","goal":"Descobrir o segmento e o tamanho da empresa.","allowed_tools":["contact_update"],"exit":{"type":"tools_executed","tools":["contact_update"],"attributes":["segmento"],"max_turns":8},"next":"proposta"}]},"max_tool_iterations":8,"history_limit_messages":40,"tail_budget_tokens":1500,"hard_cap_tokens":6000,"chain_same_provider":"","delivery":{"quote_replies":true,"formatting":"auto"},"stt":{"provider":"groq","model":"groq:whisper-large-v3-turbo"},"embedding":{"provider":"openai","model":"text-embedding-3-small"},"voice":{"enabled":false,"mode":"off","with_text":false,"provider":"elevenlabs","model":"eleven_multilingual_v2","call_backend":"auto","call_model":"openai:gpt-realtime","voice_id":"21m00Tcm4TlvDq8ikWAM","openai_voice":"alloy","gemini_voice":"Kore","stability":0.5,"similarity_boost":0.75,"style":0,"use_speaker_boost":true,"speed":1,"instructions":"Fale de forma calma e acolhedora.","style_instructions":"Locução comercial, ritmo animado."},"image_gen":{"enabled":false,"provider":"openai","model":"gpt-image-1"},"video_gen":{"enabled":false,"provider":"openai","model":"sora-2"},"custom_tools":[{"name":"consultar_pedido","description":"Consulta o status de um pedido pelo número.","method":"GET","url":"https://api.acme.com/orders/{{order_id}}","sensitive":false,"extract":"data.status","body_type":"json","body_template":{"source":"maestro","order_id":"{{order_id}}"},"headers":{"X-Api-Version":"2026-01"},"query":{"include":"items"},"auth":{"type":"bearer","name":"X-Api-Key","token_secret":"ACME_API_TOKEN","username_secret":"ACME_USER","password_secret":"ACME_PASS"},"params":[{"name":"order_id","type":"string","description":"Número do pedido.","required":true,"location":"auto"}],"response_map":[{"label":"Status","path":"data.status"}],"pagination":{"type":"none","param":"page","items_path":"data","next_path":"meta.next","start":1,"max_pages":5,"size_param":"per_page","size":50}}],"mcp_servers":[{"name":"acme-erp","url":"https://mcp.acme.com/sse","transport":"streamable_http","timeout":30,"sensitive":false,"enabled_tools":["get_order"],"headers":{"X-Tenant":"acme"},"auth":{"type":"bearer","name":"X-Api-Key","token_secret":"ACME_MCP_TOKEN","username_secret":"ACME_USER","password_secret":"ACME_PASS"}}],"media_assets":[{"name":"catalogo_2026","description":"Catálogo completo em PDF.","url":"https://cdn.acme.com/catalogo.pdf","type":"file"}],"sub_agents":[{"agent_id":7,"name":"Vendas","slug":"vendas","description":"Perguntas sobre planos e preços.","enabled":true,"sensitive":false}],"secrets":{"ACME_API_TOKEN":"sk-live-xxxxxxxx"},"secret_keys":["ACME_API_TOKEN"],"provider_keys":{"openai":"sk-proj-xxxxxxxx"},"chatwoot_native_keys":{"openai":"sk-proj-xxxxxxxx"},"provider_keys_set":["openai"],"native_keys_set":["openai"],"use_global_fallback":true}},"stripped":[{"field":"tools.http.headers.Authorization","kind":"value"}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"502":{"description":"The Maestro service could not be reached (connection refused or reset, host unresolvable), or it answered in a way the gateway could not use, or it rejected the server-to-server credential — the last one is a deployment key mismatch, never the caller's own session. Nothing was executed; the call can be retried.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"504":{"description":"The Maestro service did not answer within the proxy timeout. The work may still be running on the service side, so retrying a write can duplicate its effect.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"503":{"description":"The Maestro area is not serving this installation: an operator turned it off, or no admin key was ever provisioned. Nothing was executed, and retrying will not help until the configuration changes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"201":{"description":"The stored Modelo plus every credential that was stripped out of the snapshot.","content":{"application/json":{"schema":{"type":"object","properties":{"template":{"$ref":"#/components/schemas/maestro_template"},"stripped":{"type":"array","description":"Credentials removed from the Robô's configuration on the way in.","items":{"$ref":"#/components/schemas/maestro_template_stripped_field"}}}},"example":{"template":{"id":12,"scope":"account","account_id":7,"slug":"atendimento_ecommerce","name":"Atendimento e-commerce","description":"Atendimento com rastreio de pedido e política de troca.","vertical":"ecommerce","origin":"custom","schema_version":1,"checksum":"8f14e45fceea167a5a36dedd4bea2543","editable":true,"created_by":"ana@acme.com","created_at":"2026-07-01T12:00:00Z","updated_at":"2026-07-27T14:03:00Z","config":{"persona":"Você é a atendente virtual da Acme, cordial e objetiva.","instructions":"Sempre confirme o CPF antes de consultar um pedido.","default_model":"openai:gpt-5.4-mini-2026-03-17","fallback_models":["anthropic:claude-haiku-4-5-20251001"],"enabled_tools":["set_labels"],"autonomy_level":"autopilot","interaction_mode":"converse","search_config":{"enabled":true,"search_depth":"basic","max_results":5,"topic":"general","include_domains":["docs.example.com"],"exclude_domains":[]},"locale":"pt_BR","quiet_window_seconds":8,"max_window_seconds":40,"summary_threshold_tokens":3000,"standdown_on_assignment":true,"standdown_auto_resume":true,"standdown_ttl_seconds":86400,"paused_inbound_policy":"discard","paused_inbound_max_messages":10,"paused_inbound_max_age_seconds":3600,"handoff_team_id":3,"working_hours_policy":"ignore","out_of_office_message":"Nosso atendimento volta às 9h. Já registramos sua mensagem.","handoff_policy":{"target_status":"open","target_priority":"none","triggers":["falar com atendente"]},"guardrails":{"banned_topics":["assuntos jurídicos"],"blocked_phrases":["garantimos 100% de aprovação"],"max_output_chars":1200,"pii_policy":"off","require_handoff_conditions":["cliente pede cancelamento"]},"knowledge_base":{"enabled":true,"top_k":5,"use_shared":false},"database":{"enabled":false,"connection_secret":"ERP_DB_URL","read_only":true,"max_rows":200,"statement_timeout_seconds":15,"include_tables":["orders"],"description":"Pedidos e faturas do ERP.","instructions":"Sempre filtre por account_id."},"reactions":{"outbound":false,"understand_inbound":false},"media":{"audio":true,"vision":true,"documents":true},"close_on_complete":"off","verification_policy":"off","model_params":{"reasoning_effort":"low","temperature":0.4,"top_p":0.9,"max_output_tokens":512},"service_flow":{"enabled":false,"on_exit":"handoff","strict_tools":true,"steps":[{"key":"qualificacao","name":"Qualificação","goal":"Descobrir o segmento e o tamanho da empresa.","allowed_tools":["contact_update"],"exit":{"type":"tools_executed","tools":["contact_update"],"attributes":["segmento"],"max_turns":8},"next":"proposta"}]},"max_tool_iterations":8,"history_limit_messages":40,"tail_budget_tokens":1500,"hard_cap_tokens":6000,"chain_same_provider":"","delivery":{"quote_replies":true,"formatting":"auto"},"stt":{"provider":"groq","model":"groq:whisper-large-v3-turbo"},"embedding":{"provider":"openai","model":"text-embedding-3-small"},"voice":{"enabled":false,"mode":"off","with_text":false,"provider":"elevenlabs","model":"eleven_multilingual_v2","call_backend":"auto","call_model":"openai:gpt-realtime","voice_id":"21m00Tcm4TlvDq8ikWAM","openai_voice":"alloy","gemini_voice":"Kore","stability":0.5,"similarity_boost":0.75,"style":0,"use_speaker_boost":true,"speed":1,"instructions":"Fale de forma calma e acolhedora.","style_instructions":"Locução comercial, ritmo animado."},"image_gen":{"enabled":false,"provider":"openai","model":"gpt-image-1"},"video_gen":{"enabled":false,"provider":"openai","model":"sora-2"},"custom_tools":[{"name":"consultar_pedido","description":"Consulta o status de um pedido pelo número.","method":"GET","url":"https://api.acme.com/orders/{{order_id}}","sensitive":false,"extract":"data.status","body_type":"json","body_template":{"source":"maestro","order_id":"{{order_id}}"},"headers":{"X-Api-Version":"2026-01"},"query":{"include":"items"},"auth":{"type":"bearer","name":"X-Api-Key","token_secret":"ACME_API_TOKEN","username_secret":"ACME_USER","password_secret":"ACME_PASS"},"params":[{"name":"order_id","type":"string","description":"Número do pedido.","required":true,"location":"auto"}],"response_map":[{"label":"Status","path":"data.status"}],"pagination":{"type":"none","param":"page","items_path":"data","next_path":"meta.next","start":1,"max_pages":5,"size_param":"per_page","size":50}}],"mcp_servers":[{"name":"acme-erp","url":"https://mcp.acme.com/sse","transport":"streamable_http","timeout":30,"sensitive":false,"enabled_tools":["get_order"],"headers":{"X-Tenant":"acme"},"auth":{"type":"bearer","name":"X-Api-Key","token_secret":"ACME_MCP_TOKEN","username_secret":"ACME_USER","password_secret":"ACME_PASS"}}],"media_assets":[{"name":"catalogo_2026","description":"Catálogo completo em PDF.","url":"https://cdn.acme.com/catalogo.pdf","type":"file"}],"sub_agents":[{"agent_id":7,"name":"Vendas","slug":"vendas","description":"Perguntas sobre planos e preços.","enabled":true,"sensitive":false}],"secrets":{"ACME_API_TOKEN":"sk-live-xxxxxxxx"},"secret_keys":["ACME_API_TOKEN"],"provider_keys":{"openai":"sk-proj-xxxxxxxx"},"chatwoot_native_keys":{"openai":"sk-proj-xxxxxxxx"},"provider_keys_set":["openai"],"native_keys_set":["openai"],"use_global_fallback":true}},"stripped":[{"field":"tools.http.headers.Authorization","kind":"value"}]}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["agent_id"],"properties":{"agent_id":{"type":"integer","description":"The Robô to snapshot. Must belong to this account.","example":42},"name":{"type":"string","description":"Name for the Modelo. Empty uses the Robô's own name.","example":"Atendimento e-commerce"},"slug":{"type":"string","description":"Stable machine key. Derived from the name when omitted.","example":"atendimento_ecommerce"},"description":{"type":"string","example":"Snapshot do Robô de atendimento em 27/07."},"vertical":{"type":"string","example":"ecommerce"}}},"example":{"agent_id":42,"name":"Atendimento e-commerce","slug":"atendimento_ecommerce","description":"Snapshot do Robô de atendimento em 27/07.","vertical":"ecommerce"}}}}}},"/api/v1/accounts/{account_id}/maestro/templates/{id}":{"get":{"tags":["Maestro"],"operationId":"auto_get_api_v1_accounts_account_id_maestro_templates_id","summary":"Get one Modelo","description":"One stored Modelo with its full configuration. A Modelo belonging to another account is refused (403) — the sidecar filters by id alone, so tenancy is enforced here.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The Modelo.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_template"},"example":{"id":12,"scope":"account","account_id":7,"slug":"atendimento_ecommerce","name":"Atendimento e-commerce","description":"Atendimento com rastreio de pedido e política de troca.","vertical":"ecommerce","origin":"custom","schema_version":1,"checksum":"8f14e45fceea167a5a36dedd4bea2543","editable":true,"created_by":"ana@acme.com","created_at":"2026-07-01T12:00:00Z","updated_at":"2026-07-27T14:03:00Z","config":{"persona":"Você é a atendente virtual da Acme, cordial e objetiva.","instructions":"Sempre confirme o CPF antes de consultar um pedido.","default_model":"openai:gpt-5.4-mini-2026-03-17","fallback_models":["anthropic:claude-haiku-4-5-20251001"],"enabled_tools":["set_labels"],"autonomy_level":"autopilot","interaction_mode":"converse","search_config":{"enabled":true,"search_depth":"basic","max_results":5,"topic":"general","include_domains":["docs.example.com"],"exclude_domains":[]},"locale":"pt_BR","quiet_window_seconds":8,"max_window_seconds":40,"summary_threshold_tokens":3000,"standdown_on_assignment":true,"standdown_auto_resume":true,"standdown_ttl_seconds":86400,"paused_inbound_policy":"discard","paused_inbound_max_messages":10,"paused_inbound_max_age_seconds":3600,"handoff_team_id":3,"working_hours_policy":"ignore","out_of_office_message":"Nosso atendimento volta às 9h. Já registramos sua mensagem.","handoff_policy":{"target_status":"open","target_priority":"none","triggers":["falar com atendente"]},"guardrails":{"banned_topics":["assuntos jurídicos"],"blocked_phrases":["garantimos 100% de aprovação"],"max_output_chars":1200,"pii_policy":"off","require_handoff_conditions":["cliente pede cancelamento"]},"knowledge_base":{"enabled":true,"top_k":5,"use_shared":false},"database":{"enabled":false,"connection_secret":"ERP_DB_URL","read_only":true,"max_rows":200,"statement_timeout_seconds":15,"include_tables":["orders"],"description":"Pedidos e faturas do ERP.","instructions":"Sempre filtre por account_id."},"reactions":{"outbound":false,"understand_inbound":false},"media":{"audio":true,"vision":true,"documents":true},"close_on_complete":"off","verification_policy":"off","model_params":{"reasoning_effort":"low","temperature":0.4,"top_p":0.9,"max_output_tokens":512},"service_flow":{"enabled":false,"on_exit":"handoff","strict_tools":true,"steps":[{"key":"qualificacao","name":"Qualificação","goal":"Descobrir o segmento e o tamanho da empresa.","allowed_tools":["contact_update"],"exit":{"type":"tools_executed","tools":["contact_update"],"attributes":["segmento"],"max_turns":8},"next":"proposta"}]},"max_tool_iterations":8,"history_limit_messages":40,"tail_budget_tokens":1500,"hard_cap_tokens":6000,"chain_same_provider":"","delivery":{"quote_replies":true,"formatting":"auto"},"stt":{"provider":"groq","model":"groq:whisper-large-v3-turbo"},"embedding":{"provider":"openai","model":"text-embedding-3-small"},"voice":{"enabled":false,"mode":"off","with_text":false,"provider":"elevenlabs","model":"eleven_multilingual_v2","call_backend":"auto","call_model":"openai:gpt-realtime","voice_id":"21m00Tcm4TlvDq8ikWAM","openai_voice":"alloy","gemini_voice":"Kore","stability":0.5,"similarity_boost":0.75,"style":0,"use_speaker_boost":true,"speed":1,"instructions":"Fale de forma calma e acolhedora.","style_instructions":"Locução comercial, ritmo animado."},"image_gen":{"enabled":false,"provider":"openai","model":"gpt-image-1"},"video_gen":{"enabled":false,"provider":"openai","model":"sora-2"},"custom_tools":[{"name":"consultar_pedido","description":"Consulta o status de um pedido pelo número.","method":"GET","url":"https://api.acme.com/orders/{{order_id}}","sensitive":false,"extract":"data.status","body_type":"json","body_template":{"source":"maestro","order_id":"{{order_id}}"},"headers":{"X-Api-Version":"2026-01"},"query":{"include":"items"},"auth":{"type":"bearer","name":"X-Api-Key","token_secret":"ACME_API_TOKEN","username_secret":"ACME_USER","password_secret":"ACME_PASS"},"params":[{"name":"order_id","type":"string","description":"Número do pedido.","required":true,"location":"auto"}],"response_map":[{"label":"Status","path":"data.status"}],"pagination":{"type":"none","param":"page","items_path":"data","next_path":"meta.next","start":1,"max_pages":5,"size_param":"per_page","size":50}}],"mcp_servers":[{"name":"acme-erp","url":"https://mcp.acme.com/sse","transport":"streamable_http","timeout":30,"sensitive":false,"enabled_tools":["get_order"],"headers":{"X-Tenant":"acme"},"auth":{"type":"bearer","name":"X-Api-Key","token_secret":"ACME_MCP_TOKEN","username_secret":"ACME_USER","password_secret":"ACME_PASS"}}],"media_assets":[{"name":"catalogo_2026","description":"Catálogo completo em PDF.","url":"https://cdn.acme.com/catalogo.pdf","type":"file"}],"sub_agents":[{"agent_id":7,"name":"Vendas","slug":"vendas","description":"Perguntas sobre planos e preços.","enabled":true,"sensitive":false}],"secrets":{"ACME_API_TOKEN":"sk-live-xxxxxxxx"},"secret_keys":["ACME_API_TOKEN"],"provider_keys":{"openai":"sk-proj-xxxxxxxx"},"chatwoot_native_keys":{"openai":"sk-proj-xxxxxxxx"},"provider_keys_set":["openai"],"native_keys_set":["openai"],"use_global_fallback":true}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"502":{"description":"The Maestro service could not be reached (connection refused or reset, host unresolvable), or it answered in a way the gateway could not use, or it rejected the server-to-server credential — the last one is a deployment key mismatch, never the caller's own session. Nothing was executed; the call can be retried.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"504":{"description":"The Maestro service did not answer within the proxy timeout. The work may still be running on the service side, so retrying a write can duplicate its effect.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"503":{"description":"The Maestro area is not serving this installation: an operator turned it off, or no admin key was ever provisioned. Nothing was executed, and retrying will not help until the configuration changes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]},"patch":{"tags":["Maestro"],"operationId":"auto_patch_api_v1_accounts_account_id_maestro_templates_id","summary":"Update a Modelo","description":"Edits a `custom` or `imported` Modelo (`editable: true`); a read-only entry is refused — duplicate it instead. Every field is optional and an omitted one is left unchanged, but `config` REPLACES the stored configuration, so send the whole object with your changes applied. `account_id`, `scope` and `origin` are not accepted here: changing owner or scope would be promotion without the promotion path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The updated Modelo plus every credential that had to be removed to store it.","content":{"application/json":{"schema":{"type":"object","properties":{"template":{"$ref":"#/components/schemas/maestro_template"},"stripped":{"type":"array","description":"Credentials removed on the way in.","items":{"$ref":"#/components/schemas/maestro_template_stripped_field"}}}},"example":{"template":{"id":12,"scope":"account","account_id":7,"slug":"atendimento_ecommerce","name":"Atendimento e-commerce","description":"Atendimento com rastreio de pedido e política de troca.","vertical":"ecommerce","origin":"custom","schema_version":1,"checksum":"8f14e45fceea167a5a36dedd4bea2543","editable":true,"created_by":"ana@acme.com","created_at":"2026-07-01T12:00:00Z","updated_at":"2026-07-27T14:03:00Z","config":{"persona":"Você é a atendente virtual da Acme, cordial e objetiva.","instructions":"Sempre confirme o CPF antes de consultar um pedido.","default_model":"openai:gpt-5.4-mini-2026-03-17","fallback_models":["anthropic:claude-haiku-4-5-20251001"],"enabled_tools":["set_labels"],"autonomy_level":"autopilot","interaction_mode":"converse","search_config":{"enabled":true,"search_depth":"basic","max_results":5,"topic":"general","include_domains":["docs.example.com"],"exclude_domains":[]},"locale":"pt_BR","quiet_window_seconds":8,"max_window_seconds":40,"summary_threshold_tokens":3000,"standdown_on_assignment":true,"standdown_auto_resume":true,"standdown_ttl_seconds":86400,"paused_inbound_policy":"discard","paused_inbound_max_messages":10,"paused_inbound_max_age_seconds":3600,"handoff_team_id":3,"working_hours_policy":"ignore","out_of_office_message":"Nosso atendimento volta às 9h. Já registramos sua mensagem.","handoff_policy":{"target_status":"open","target_priority":"none","triggers":["falar com atendente"]},"guardrails":{"banned_topics":["assuntos jurídicos"],"blocked_phrases":["garantimos 100% de aprovação"],"max_output_chars":1200,"pii_policy":"off","require_handoff_conditions":["cliente pede cancelamento"]},"knowledge_base":{"enabled":true,"top_k":5,"use_shared":false},"database":{"enabled":false,"connection_secret":"ERP_DB_URL","read_only":true,"max_rows":200,"statement_timeout_seconds":15,"include_tables":["orders"],"description":"Pedidos e faturas do ERP.","instructions":"Sempre filtre por account_id."},"reactions":{"outbound":false,"understand_inbound":false},"media":{"audio":true,"vision":true,"documents":true},"close_on_complete":"off","verification_policy":"off","model_params":{"reasoning_effort":"low","temperature":0.4,"top_p":0.9,"max_output_tokens":512},"service_flow":{"enabled":false,"on_exit":"handoff","strict_tools":true,"steps":[{"key":"qualificacao","name":"Qualificação","goal":"Descobrir o segmento e o tamanho da empresa.","allowed_tools":["contact_update"],"exit":{"type":"tools_executed","tools":["contact_update"],"attributes":["segmento"],"max_turns":8},"next":"proposta"}]},"max_tool_iterations":8,"history_limit_messages":40,"tail_budget_tokens":1500,"hard_cap_tokens":6000,"chain_same_provider":"","delivery":{"quote_replies":true,"formatting":"auto"},"stt":{"provider":"groq","model":"groq:whisper-large-v3-turbo"},"embedding":{"provider":"openai","model":"text-embedding-3-small"},"voice":{"enabled":false,"mode":"off","with_text":false,"provider":"elevenlabs","model":"eleven_multilingual_v2","call_backend":"auto","call_model":"openai:gpt-realtime","voice_id":"21m00Tcm4TlvDq8ikWAM","openai_voice":"alloy","gemini_voice":"Kore","stability":0.5,"similarity_boost":0.75,"style":0,"use_speaker_boost":true,"speed":1,"instructions":"Fale de forma calma e acolhedora.","style_instructions":"Locução comercial, ritmo animado."},"image_gen":{"enabled":false,"provider":"openai","model":"gpt-image-1"},"video_gen":{"enabled":false,"provider":"openai","model":"sora-2"},"custom_tools":[{"name":"consultar_pedido","description":"Consulta o status de um pedido pelo número.","method":"GET","url":"https://api.acme.com/orders/{{order_id}}","sensitive":false,"extract":"data.status","body_type":"json","body_template":{"source":"maestro","order_id":"{{order_id}}"},"headers":{"X-Api-Version":"2026-01"},"query":{"include":"items"},"auth":{"type":"bearer","name":"X-Api-Key","token_secret":"ACME_API_TOKEN","username_secret":"ACME_USER","password_secret":"ACME_PASS"},"params":[{"name":"order_id","type":"string","description":"Número do pedido.","required":true,"location":"auto"}],"response_map":[{"label":"Status","path":"data.status"}],"pagination":{"type":"none","param":"page","items_path":"data","next_path":"meta.next","start":1,"max_pages":5,"size_param":"per_page","size":50}}],"mcp_servers":[{"name":"acme-erp","url":"https://mcp.acme.com/sse","transport":"streamable_http","timeout":30,"sensitive":false,"enabled_tools":["get_order"],"headers":{"X-Tenant":"acme"},"auth":{"type":"bearer","name":"X-Api-Key","token_secret":"ACME_MCP_TOKEN","username_secret":"ACME_USER","password_secret":"ACME_PASS"}}],"media_assets":[{"name":"catalogo_2026","description":"Catálogo completo em PDF.","url":"https://cdn.acme.com/catalogo.pdf","type":"file"}],"sub_agents":[{"agent_id":7,"name":"Vendas","slug":"vendas","description":"Perguntas sobre planos e preços.","enabled":true,"sensitive":false}],"secrets":{"ACME_API_TOKEN":"sk-live-xxxxxxxx"},"secret_keys":["ACME_API_TOKEN"],"provider_keys":{"openai":"sk-proj-xxxxxxxx"},"chatwoot_native_keys":{"openai":"sk-proj-xxxxxxxx"},"provider_keys_set":["openai"],"native_keys_set":["openai"],"use_global_fallback":true}},"stripped":[{"field":"tools.http.headers.Authorization","kind":"value"}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"502":{"description":"The Maestro service could not be reached (connection refused or reset, host unresolvable), or it answered in a way the gateway could not use, or it rejected the server-to-server credential — the last one is a deployment key mismatch, never the caller's own session. Nothing was executed; the call can be retried.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"504":{"description":"The Maestro service did not answer within the proxy timeout. The work may still be running on the service side, so retrying a write can duplicate its effect.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"503":{"description":"The Maestro area is not serving this installation: an operator turned it off, or no admin key was ever provisioned. Nothing was executed, and retrying will not help until the configuration changes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","example":"Atendimento e-commerce"},"description":{"type":"string","example":"Atendimento com rastreio de pedido e política de troca."},"vertical":{"type":"string","example":"ecommerce"},"config":{"$ref":"#/components/schemas/maestro_agent_config"}}},"example":{"name":"Atendimento e-commerce","description":"Atendimento com rastreio de pedido e política de troca.","vertical":"ecommerce","config":{"persona":"Você é a atendente virtual da Acme, cordial e objetiva.","instructions":"Sempre confirme o CPF antes de consultar um pedido.","default_model":"openai:gpt-5.4-mini-2026-03-17","fallback_models":["anthropic:claude-haiku-4-5-20251001"],"enabled_tools":["set_labels"],"autonomy_level":"autopilot","interaction_mode":"converse","search_config":{"enabled":true,"search_depth":"basic","max_results":5,"topic":"general","include_domains":["docs.example.com"],"exclude_domains":[]},"locale":"pt_BR","quiet_window_seconds":8,"max_window_seconds":40,"summary_threshold_tokens":3000,"standdown_on_assignment":true,"standdown_auto_resume":true,"standdown_ttl_seconds":86400,"paused_inbound_policy":"discard","paused_inbound_max_messages":10,"paused_inbound_max_age_seconds":3600,"handoff_team_id":3,"working_hours_policy":"ignore","out_of_office_message":"Nosso atendimento volta às 9h. Já registramos sua mensagem.","handoff_policy":{"target_status":"open","target_priority":"none","triggers":["falar com atendente"]},"guardrails":{"banned_topics":["assuntos jurídicos"],"blocked_phrases":["garantimos 100% de aprovação"],"max_output_chars":1200,"pii_policy":"off","require_handoff_conditions":["cliente pede cancelamento"]},"knowledge_base":{"enabled":true,"top_k":5,"use_shared":false},"database":{"enabled":false,"connection_secret":"ERP_DB_URL","read_only":true,"max_rows":200,"statement_timeout_seconds":15,"include_tables":["orders"],"description":"Pedidos e faturas do ERP.","instructions":"Sempre filtre por account_id."},"reactions":{"outbound":false,"understand_inbound":false},"media":{"audio":true,"vision":true,"documents":true},"close_on_complete":"off","verification_policy":"off","model_params":{"reasoning_effort":"low","temperature":0.4,"top_p":0.9,"max_output_tokens":512},"service_flow":{"enabled":false,"on_exit":"handoff","strict_tools":true,"steps":[{"key":"qualificacao","name":"Qualificação","goal":"Descobrir o segmento e o tamanho da empresa.","allowed_tools":["contact_update"],"exit":{"type":"tools_executed","tools":["contact_update"],"attributes":["segmento"],"max_turns":8},"next":"proposta"}]},"max_tool_iterations":8,"history_limit_messages":40,"tail_budget_tokens":1500,"hard_cap_tokens":6000,"chain_same_provider":"","delivery":{"quote_replies":true,"formatting":"auto"},"stt":{"provider":"groq","model":"groq:whisper-large-v3-turbo"},"embedding":{"provider":"openai","model":"text-embedding-3-small"},"voice":{"enabled":false,"mode":"off","with_text":false,"provider":"elevenlabs","model":"eleven_multilingual_v2","call_backend":"auto","call_model":"openai:gpt-realtime","voice_id":"21m00Tcm4TlvDq8ikWAM","openai_voice":"alloy","gemini_voice":"Kore","stability":0.5,"similarity_boost":0.75,"style":0,"use_speaker_boost":true,"speed":1,"instructions":"Fale de forma calma e acolhedora.","style_instructions":"Locução comercial, ritmo animado."},"image_gen":{"enabled":false,"provider":"openai","model":"gpt-image-1"},"video_gen":{"enabled":false,"provider":"openai","model":"sora-2"},"custom_tools":[{"name":"consultar_pedido","description":"Consulta o status de um pedido pelo número.","method":"GET","url":"https://api.acme.com/orders/{{order_id}}","sensitive":false,"extract":"data.status","body_type":"json","body_template":{"source":"maestro","order_id":"{{order_id}}"},"headers":{"X-Api-Version":"2026-01"},"query":{"include":"items"},"auth":{"type":"bearer","name":"X-Api-Key","token_secret":"ACME_API_TOKEN","username_secret":"ACME_USER","password_secret":"ACME_PASS"},"params":[{"name":"order_id","type":"string","description":"Número do pedido.","required":true,"location":"auto"}],"response_map":[{"label":"Status","path":"data.status"}],"pagination":{"type":"none","param":"page","items_path":"data","next_path":"meta.next","start":1,"max_pages":5,"size_param":"per_page","size":50}}],"mcp_servers":[{"name":"acme-erp","url":"https://mcp.acme.com/sse","transport":"streamable_http","timeout":30,"sensitive":false,"enabled_tools":["get_order"],"headers":{"X-Tenant":"acme"},"auth":{"type":"bearer","name":"X-Api-Key","token_secret":"ACME_MCP_TOKEN","username_secret":"ACME_USER","password_secret":"ACME_PASS"}}],"media_assets":[{"name":"catalogo_2026","description":"Catálogo completo em PDF.","url":"https://cdn.acme.com/catalogo.pdf","type":"file"}],"sub_agents":[{"agent_id":7,"name":"Vendas","slug":"vendas","description":"Perguntas sobre planos e preços.","enabled":true,"sensitive":false}],"secrets":{"ACME_API_TOKEN":"sk-live-xxxxxxxx"},"secret_keys":["ACME_API_TOKEN"],"provider_keys":{"openai":"sk-proj-xxxxxxxx"},"chatwoot_native_keys":{"openai":"sk-proj-xxxxxxxx"},"provider_keys_set":["openai"],"native_keys_set":["openai"],"use_global_fallback":true}}}}}},"delete":{"tags":["Maestro"],"operationId":"auto_delete_api_v1_accounts_account_id_maestro_templates_id","summary":"Delete a Modelo","description":"Removes a `custom` or `imported` Modelo from the library. Read-only entries cannot be deleted. Robôs already created from this Modelo are unaffected — a Modelo is a starting point, not a link.","security":[{"userApiKey":[]}],"responses":{"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"502":{"description":"The Maestro service could not be reached (connection refused or reset, host unresolvable), or it answered in a way the gateway could not use, or it rejected the server-to-server credential — the last one is a deployment key mismatch, never the caller's own session. Nothing was executed; the call can be retried.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"504":{"description":"The Maestro service did not answer within the proxy timeout. The work may still be running on the service side, so retrying a write can duplicate its effect.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"503":{"description":"The Maestro area is not serving this installation: an operator turned it off, or no admin key was ever provisioned. Nothing was executed, and retrying will not help until the configuration changes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"204":{"description":"Deleted. No body."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/maestro/templates/{id}/duplicate":{"post":{"tags":["Maestro"],"operationId":"auto_post_api_v1_accounts_account_id_maestro_templates_id_duplicate","summary":"Duplicate a Modelo","description":"Copies a Modelo into THIS account's library as a private `account`-scoped entry, which is what makes \"duplicate a shipped Modelo to customize it\" possible without publishing to every tenant on the installation. The destination account is injected from the session and is never taken from the payload.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The new Modelo, owned by this account and editable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_template"},"example":{"id":12,"scope":"account","account_id":7,"slug":"atendimento_ecommerce","name":"Atendimento e-commerce","description":"Atendimento com rastreio de pedido e política de troca.","vertical":"ecommerce","origin":"custom","schema_version":1,"checksum":"8f14e45fceea167a5a36dedd4bea2543","editable":true,"created_by":"ana@acme.com","created_at":"2026-07-01T12:00:00Z","updated_at":"2026-07-27T14:03:00Z","config":{"persona":"Você é a atendente virtual da Acme, cordial e objetiva.","instructions":"Sempre confirme o CPF antes de consultar um pedido.","default_model":"openai:gpt-5.4-mini-2026-03-17","fallback_models":["anthropic:claude-haiku-4-5-20251001"],"enabled_tools":["set_labels"],"autonomy_level":"autopilot","interaction_mode":"converse","search_config":{"enabled":true,"search_depth":"basic","max_results":5,"topic":"general","include_domains":["docs.example.com"],"exclude_domains":[]},"locale":"pt_BR","quiet_window_seconds":8,"max_window_seconds":40,"summary_threshold_tokens":3000,"standdown_on_assignment":true,"standdown_auto_resume":true,"standdown_ttl_seconds":86400,"paused_inbound_policy":"discard","paused_inbound_max_messages":10,"paused_inbound_max_age_seconds":3600,"handoff_team_id":3,"working_hours_policy":"ignore","out_of_office_message":"Nosso atendimento volta às 9h. Já registramos sua mensagem.","handoff_policy":{"target_status":"open","target_priority":"none","triggers":["falar com atendente"]},"guardrails":{"banned_topics":["assuntos jurídicos"],"blocked_phrases":["garantimos 100% de aprovação"],"max_output_chars":1200,"pii_policy":"off","require_handoff_conditions":["cliente pede cancelamento"]},"knowledge_base":{"enabled":true,"top_k":5,"use_shared":false},"database":{"enabled":false,"connection_secret":"ERP_DB_URL","read_only":true,"max_rows":200,"statement_timeout_seconds":15,"include_tables":["orders"],"description":"Pedidos e faturas do ERP.","instructions":"Sempre filtre por account_id."},"reactions":{"outbound":false,"understand_inbound":false},"media":{"audio":true,"vision":true,"documents":true},"close_on_complete":"off","verification_policy":"off","model_params":{"reasoning_effort":"low","temperature":0.4,"top_p":0.9,"max_output_tokens":512},"service_flow":{"enabled":false,"on_exit":"handoff","strict_tools":true,"steps":[{"key":"qualificacao","name":"Qualificação","goal":"Descobrir o segmento e o tamanho da empresa.","allowed_tools":["contact_update"],"exit":{"type":"tools_executed","tools":["contact_update"],"attributes":["segmento"],"max_turns":8},"next":"proposta"}]},"max_tool_iterations":8,"history_limit_messages":40,"tail_budget_tokens":1500,"hard_cap_tokens":6000,"chain_same_provider":"","delivery":{"quote_replies":true,"formatting":"auto"},"stt":{"provider":"groq","model":"groq:whisper-large-v3-turbo"},"embedding":{"provider":"openai","model":"text-embedding-3-small"},"voice":{"enabled":false,"mode":"off","with_text":false,"provider":"elevenlabs","model":"eleven_multilingual_v2","call_backend":"auto","call_model":"openai:gpt-realtime","voice_id":"21m00Tcm4TlvDq8ikWAM","openai_voice":"alloy","gemini_voice":"Kore","stability":0.5,"similarity_boost":0.75,"style":0,"use_speaker_boost":true,"speed":1,"instructions":"Fale de forma calma e acolhedora.","style_instructions":"Locução comercial, ritmo animado."},"image_gen":{"enabled":false,"provider":"openai","model":"gpt-image-1"},"video_gen":{"enabled":false,"provider":"openai","model":"sora-2"},"custom_tools":[{"name":"consultar_pedido","description":"Consulta o status de um pedido pelo número.","method":"GET","url":"https://api.acme.com/orders/{{order_id}}","sensitive":false,"extract":"data.status","body_type":"json","body_template":{"source":"maestro","order_id":"{{order_id}}"},"headers":{"X-Api-Version":"2026-01"},"query":{"include":"items"},"auth":{"type":"bearer","name":"X-Api-Key","token_secret":"ACME_API_TOKEN","username_secret":"ACME_USER","password_secret":"ACME_PASS"},"params":[{"name":"order_id","type":"string","description":"Número do pedido.","required":true,"location":"auto"}],"response_map":[{"label":"Status","path":"data.status"}],"pagination":{"type":"none","param":"page","items_path":"data","next_path":"meta.next","start":1,"max_pages":5,"size_param":"per_page","size":50}}],"mcp_servers":[{"name":"acme-erp","url":"https://mcp.acme.com/sse","transport":"streamable_http","timeout":30,"sensitive":false,"enabled_tools":["get_order"],"headers":{"X-Tenant":"acme"},"auth":{"type":"bearer","name":"X-Api-Key","token_secret":"ACME_MCP_TOKEN","username_secret":"ACME_USER","password_secret":"ACME_PASS"}}],"media_assets":[{"name":"catalogo_2026","description":"Catálogo completo em PDF.","url":"https://cdn.acme.com/catalogo.pdf","type":"file"}],"sub_agents":[{"agent_id":7,"name":"Vendas","slug":"vendas","description":"Perguntas sobre planos e preços.","enabled":true,"sensitive":false}],"secrets":{"ACME_API_TOKEN":"sk-live-xxxxxxxx"},"secret_keys":["ACME_API_TOKEN"],"provider_keys":{"openai":"sk-proj-xxxxxxxx"},"chatwoot_native_keys":{"openai":"sk-proj-xxxxxxxx"},"provider_keys_set":["openai"],"native_keys_set":["openai"],"use_global_fallback":true}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"502":{"description":"The Maestro service could not be reached (connection refused or reset, host unresolvable), or it answered in a way the gateway could not use, or it rejected the server-to-server credential — the last one is a deployment key mismatch, never the caller's own session. Nothing was executed; the call can be retried.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"504":{"description":"The Maestro service did not answer within the proxy timeout. The work may still be running on the service side, so retrying a write can duplicate its effect.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"503":{"description":"The Maestro area is not serving this installation: an operator turned it off, or no admin key was ever provisioned. Nothing was executed, and retrying will not help until the configuration changes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"201":{"description":"The new Modelo, owned by this account and editable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_template"},"example":{"id":12,"scope":"account","account_id":7,"slug":"atendimento_ecommerce","name":"Atendimento e-commerce","description":"Atendimento com rastreio de pedido e política de troca.","vertical":"ecommerce","origin":"custom","schema_version":1,"checksum":"8f14e45fceea167a5a36dedd4bea2543","editable":true,"created_by":"ana@acme.com","created_at":"2026-07-01T12:00:00Z","updated_at":"2026-07-27T14:03:00Z","config":{"persona":"Você é a atendente virtual da Acme, cordial e objetiva.","instructions":"Sempre confirme o CPF antes de consultar um pedido.","default_model":"openai:gpt-5.4-mini-2026-03-17","fallback_models":["anthropic:claude-haiku-4-5-20251001"],"enabled_tools":["set_labels"],"autonomy_level":"autopilot","interaction_mode":"converse","search_config":{"enabled":true,"search_depth":"basic","max_results":5,"topic":"general","include_domains":["docs.example.com"],"exclude_domains":[]},"locale":"pt_BR","quiet_window_seconds":8,"max_window_seconds":40,"summary_threshold_tokens":3000,"standdown_on_assignment":true,"standdown_auto_resume":true,"standdown_ttl_seconds":86400,"paused_inbound_policy":"discard","paused_inbound_max_messages":10,"paused_inbound_max_age_seconds":3600,"handoff_team_id":3,"working_hours_policy":"ignore","out_of_office_message":"Nosso atendimento volta às 9h. Já registramos sua mensagem.","handoff_policy":{"target_status":"open","target_priority":"none","triggers":["falar com atendente"]},"guardrails":{"banned_topics":["assuntos jurídicos"],"blocked_phrases":["garantimos 100% de aprovação"],"max_output_chars":1200,"pii_policy":"off","require_handoff_conditions":["cliente pede cancelamento"]},"knowledge_base":{"enabled":true,"top_k":5,"use_shared":false},"database":{"enabled":false,"connection_secret":"ERP_DB_URL","read_only":true,"max_rows":200,"statement_timeout_seconds":15,"include_tables":["orders"],"description":"Pedidos e faturas do ERP.","instructions":"Sempre filtre por account_id."},"reactions":{"outbound":false,"understand_inbound":false},"media":{"audio":true,"vision":true,"documents":true},"close_on_complete":"off","verification_policy":"off","model_params":{"reasoning_effort":"low","temperature":0.4,"top_p":0.9,"max_output_tokens":512},"service_flow":{"enabled":false,"on_exit":"handoff","strict_tools":true,"steps":[{"key":"qualificacao","name":"Qualificação","goal":"Descobrir o segmento e o tamanho da empresa.","allowed_tools":["contact_update"],"exit":{"type":"tools_executed","tools":["contact_update"],"attributes":["segmento"],"max_turns":8},"next":"proposta"}]},"max_tool_iterations":8,"history_limit_messages":40,"tail_budget_tokens":1500,"hard_cap_tokens":6000,"chain_same_provider":"","delivery":{"quote_replies":true,"formatting":"auto"},"stt":{"provider":"groq","model":"groq:whisper-large-v3-turbo"},"embedding":{"provider":"openai","model":"text-embedding-3-small"},"voice":{"enabled":false,"mode":"off","with_text":false,"provider":"elevenlabs","model":"eleven_multilingual_v2","call_backend":"auto","call_model":"openai:gpt-realtime","voice_id":"21m00Tcm4TlvDq8ikWAM","openai_voice":"alloy","gemini_voice":"Kore","stability":0.5,"similarity_boost":0.75,"style":0,"use_speaker_boost":true,"speed":1,"instructions":"Fale de forma calma e acolhedora.","style_instructions":"Locução comercial, ritmo animado."},"image_gen":{"enabled":false,"provider":"openai","model":"gpt-image-1"},"video_gen":{"enabled":false,"provider":"openai","model":"sora-2"},"custom_tools":[{"name":"consultar_pedido","description":"Consulta o status de um pedido pelo número.","method":"GET","url":"https://api.acme.com/orders/{{order_id}}","sensitive":false,"extract":"data.status","body_type":"json","body_template":{"source":"maestro","order_id":"{{order_id}}"},"headers":{"X-Api-Version":"2026-01"},"query":{"include":"items"},"auth":{"type":"bearer","name":"X-Api-Key","token_secret":"ACME_API_TOKEN","username_secret":"ACME_USER","password_secret":"ACME_PASS"},"params":[{"name":"order_id","type":"string","description":"Número do pedido.","required":true,"location":"auto"}],"response_map":[{"label":"Status","path":"data.status"}],"pagination":{"type":"none","param":"page","items_path":"data","next_path":"meta.next","start":1,"max_pages":5,"size_param":"per_page","size":50}}],"mcp_servers":[{"name":"acme-erp","url":"https://mcp.acme.com/sse","transport":"streamable_http","timeout":30,"sensitive":false,"enabled_tools":["get_order"],"headers":{"X-Tenant":"acme"},"auth":{"type":"bearer","name":"X-Api-Key","token_secret":"ACME_MCP_TOKEN","username_secret":"ACME_USER","password_secret":"ACME_PASS"}}],"media_assets":[{"name":"catalogo_2026","description":"Catálogo completo em PDF.","url":"https://cdn.acme.com/catalogo.pdf","type":"file"}],"sub_agents":[{"agent_id":7,"name":"Vendas","slug":"vendas","description":"Perguntas sobre planos e preços.","enabled":true,"sensitive":false}],"secrets":{"ACME_API_TOKEN":"sk-live-xxxxxxxx"},"secret_keys":["ACME_API_TOKEN"],"provider_keys":{"openai":"sk-proj-xxxxxxxx"},"chatwoot_native_keys":{"openai":"sk-proj-xxxxxxxx"},"provider_keys_set":["openai"],"native_keys_set":["openai"],"use_global_fallback":true}}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Name for the copy. Empty produces \"\u003cname\u003e (2)\" — a NUMBER, so the UI owns language.","example":"Atendimento e-commerce (2)"},"slug":{"type":"string","description":"Stable machine key for the copy. Derived from the name when omitted.","example":"atendimento_ecommerce_2"}}},"example":{"name":"Atendimento e-commerce (2)","slug":"atendimento_ecommerce_2"}}}}}},"/api/v1/accounts/{account_id}/maestro/templates/{id}/instantiate":{"post":{"tags":["Maestro"],"operationId":"auto_post_api_v1_accounts_account_id_maestro_templates_id_instantiate","summary":"Instantiate a Modelo as a Robô","description":"Creates a real Maestro agent from a stored Modelo visible to this account. The template configuration is read server-side, so clients never have to copy its complete AgentConfig or handle credentials. The new Robô starts disabled unless `enabled` is explicitly true. The response is intentionally a safe identity summary: it does not echo configuration, provider keys, secrets, or custom-tool URLs.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Safe identity of the new Robô and the inboxes linked during creation.","content":{"application/json":{"schema":{"type":"object","required":["id","account_id","name","enabled","template_id","inbox_ids"],"properties":{"id":{"type":"integer","description":"Id of the new Robô.","example":91},"account_id":{"type":"integer","description":"Account that owns the new Robô.","example":7},"name":{"type":"string","example":"Bia"},"enabled":{"type":"boolean","example":false},"template_id":{"type":"integer","description":"Modelo used as the source.","example":14},"inbox_ids":{"type":"array","description":"Inboxes linked during creation.","items":{"type":"integer"},"example":[12]}}},"example":{"id":91,"account_id":7,"name":"Bia","enabled":false,"template_id":14,"inbox_ids":[12]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"502":{"description":"The Maestro service could not be reached (connection refused or reset, host unresolvable), or it answered in a way the gateway could not use, or it rejected the server-to-server credential — the last one is a deployment key mismatch, never the caller's own session. Nothing was executed; the call can be retried.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"504":{"description":"The Maestro service did not answer within the proxy timeout. The work may still be running on the service side, so retrying a write can duplicate its effect.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"503":{"description":"The Maestro area is not serving this installation: an operator turned it off, or no admin key was ever provisioned. Nothing was executed, and retrying will not help until the configuration changes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"201":{"description":"Safe identity of the new Robô and the inboxes linked during creation.","content":{"application/json":{"schema":{"type":"object","required":["id","account_id","name","enabled","template_id","inbox_ids"],"properties":{"id":{"type":"integer","description":"Id of the new Robô.","example":91},"account_id":{"type":"integer","description":"Account that owns the new Robô.","example":7},"name":{"type":"string","example":"Bia"},"enabled":{"type":"boolean","example":false},"template_id":{"type":"integer","description":"Modelo used as the source.","example":14},"inbox_ids":{"type":"array","description":"Inboxes linked during creation.","items":{"type":"integer"},"example":[12]}}},"example":{"id":91,"account_id":7,"name":"Bia","enabled":false,"template_id":14,"inbox_ids":[12]}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Name for the Robô. Empty uses the Modelo's name.","example":"Bia"},"enabled":{"type":"boolean","description":"Whether the Robô may answer immediately. Defaults to false.","default":false,"example":false},"bindings":{"type":"array","description":"Inboxes to link to the new Robô. Omit for an unbound Robô.","items":{"type":"object","required":["inbox_id"],"properties":{"inbox_id":{"type":"integer","description":"Inbox owned by this account.","example":12}}}}}},"example":{"name":"Bia","enabled":false,"bindings":[{"inbox_id":12}]}}}}}},"/api/v1/accounts/{account_id}/maestro/templates/{id}/export":{"get":{"tags":["Maestro"],"operationId":"auto_get_api_v1_accounts_account_id_maestro_templates_id_export","summary":"Export a Modelo document","description":"Produces the `.maestro-template.json` for this Modelo, ready to be saved to disk and imported elsewhere. Credentials never travel (`stripped`) and per-installation references are emptied rather than carried to an installation where their ids mean something else (`cleared`) — together they are the checklist of what the receiving side has to wire by hand.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The portable document plus the reconfiguration checklist.","content":{"application/json":{"schema":{"type":"object","properties":{"filename":{"type":"string","description":"Suggested file name for the download.","example":"atendimento_ecommerce.maestro-template.json"},"document":{"type":"object","additionalProperties":true,"description":"The document itself — the exact payload the import endpoint accepts. A free object because its inner shape is versioned by `schema_version`, not by this reference.","example":{"schema_version":1,"name":"Atendimento e-commerce","slug":"atendimento_ecommerce","config":{}}},"stripped":{"type":"array","description":"Credentials that did not travel with the document.","items":{"$ref":"#/components/schemas/maestro_template_stripped_field"}},"cleared":{"type":"array","description":"Per-installation references emptied on the way out.","items":{"$ref":"#/components/schemas/maestro_template_reference_outcome"}}}},"example":{"filename":"atendimento_ecommerce.maestro-template.json","document":{"schema_version":1,"name":"Atendimento e-commerce","slug":"atendimento_ecommerce","config":{}},"stripped":[{"field":"tools.http.headers.Authorization","kind":"value"}],"cleared":[{"field":"handoff_policy.team","action":"remapped","name":"Suporte N2","detail":"matched team by name"}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"502":{"description":"The Maestro service could not be reached (connection refused or reset, host unresolvable), or it answered in a way the gateway could not use, or it rejected the server-to-server credential — the last one is a deployment key mismatch, never the caller's own session. Nothing was executed; the call can be retried.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"504":{"description":"The Maestro service did not answer within the proxy timeout. The work may still be running on the service side, so retrying a write can duplicate its effect.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"503":{"description":"The Maestro area is not serving this installation: an operator turned it off, or no admin key was ever provisioned. Nothing was executed, and retrying will not help until the configuration changes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/maestro/agents/{id}/export-template":{"get":{"tags":["Maestro"],"operationId":"auto_get_api_v1_accounts_account_id_maestro_agents_id_export_template","summary":"Export a Robô as a Modelo document","description":"The same `.maestro-template.json` as the Modelo export, produced directly from a Robô without storing it in the library first — for carrying a tuned Robô to another installation. Secrets are stripped and per-installation references cleared, both reported so nothing vanishes silently.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The portable document plus the reconfiguration checklist.","content":{"application/json":{"schema":{"type":"object","properties":{"filename":{"type":"string","description":"Suggested file name for the download.","example":"atendimento_ecommerce.maestro-template.json"},"document":{"type":"object","additionalProperties":true,"description":"The document itself — the exact payload the import endpoint accepts.","example":{"schema_version":1,"name":"Atendimento e-commerce","slug":"atendimento_ecommerce","config":{}}},"stripped":{"type":"array","description":"Credentials that did not travel with the document.","items":{"$ref":"#/components/schemas/maestro_template_stripped_field"}},"cleared":{"type":"array","description":"Per-installation references emptied on the way out.","items":{"$ref":"#/components/schemas/maestro_template_reference_outcome"}}}},"example":{"filename":"atendimento_ecommerce.maestro-template.json","document":{"schema_version":1,"name":"Atendimento e-commerce","slug":"atendimento_ecommerce","config":{}},"stripped":[{"field":"tools.http.headers.Authorization","kind":"value"}],"cleared":[{"field":"handoff_policy.team","action":"remapped","name":"Suporte N2","detail":"matched team by name"}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"502":{"description":"The Maestro service could not be reached (connection refused or reset, host unresolvable), or it answered in a way the gateway could not use, or it rejected the server-to-server credential — the last one is a deployment key mismatch, never the caller's own session. Nothing was executed; the call can be retried.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"504":{"description":"The Maestro service did not answer within the proxy timeout. The work may still be running on the service side, so retrying a write can duplicate its effect.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"503":{"description":"The Maestro area is not serving this installation: an operator turned it off, or no admin key was ever provisioned. Nothing was executed, and retrying will not help until the configuration changes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/maestro/agents/{id}/duplicate":{"post":{"tags":["Maestro"],"operationId":"auto_post_api_v1_accounts_account_id_maestro_agents_id_duplicate","summary":"Duplicate a Robô","description":"Copies a whole Robô inside its own account — configuration, keys and secrets included. Within one account the copy SHOULD carry the credentials: same tenant, and a duplicate that cannot answer is not a duplicate. (Crossing accounts or installations is what Modelos are for, and those strip everything.) The copy starts DISABLED and unbound — two identical Robôs answering the same inbox is not what anyone means by \"duplicate\". Returns the new Robô's identity; re-read it from the agent endpoint, which stays the single serializer for a Robô.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Identity of the new Robô.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer","description":"Id of the new Robô.","example":43},"account_id":{"type":"integer","example":7},"name":{"type":"string","example":"Atendimento (2)"},"enabled":{"type":"boolean","description":"False unless the request asked otherwise.","example":false},"source_agent_id":{"type":"integer","description":"The Robô this copy was made from.","example":42}}},"example":{"id":43,"account_id":7,"name":"Atendimento (2)","enabled":false,"source_agent_id":42}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"502":{"description":"The Maestro service could not be reached (connection refused or reset, host unresolvable), or it answered in a way the gateway could not use, or it rejected the server-to-server credential — the last one is a deployment key mismatch, never the caller's own session. Nothing was executed; the call can be retried.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"504":{"description":"The Maestro service did not answer within the proxy timeout. The work may still be running on the service side, so retrying a write can duplicate its effect.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"503":{"description":"The Maestro area is not serving this installation: an operator turned it off, or no admin key was ever provisioned. Nothing was executed, and retrying will not help until the configuration changes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"201":{"description":"Identity of the new Robô.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer","description":"Id of the new Robô.","example":43},"account_id":{"type":"integer","example":7},"name":{"type":"string","example":"Atendimento (2)"},"enabled":{"type":"boolean","description":"False unless the request asked otherwise.","example":false},"source_agent_id":{"type":"integer","description":"The Robô this copy was made from.","example":42}}},"example":{"id":43,"account_id":7,"name":"Atendimento (2)","enabled":false,"source_agent_id":42}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Name for the copy. Empty produces \"\u003cname\u003e (2)\".","example":"Atendimento (2)"},"enabled":{"type":"boolean","description":"Whether the copy answers immediately. Defaults to false.","example":false},"provision_bot":{"type":"boolean","description":"Also create the linked AgentBot for the copy. Defaults to true.","example":true}}},"example":{"name":"Atendimento (2)","enabled":false,"provision_bot":true}}}}}},"/api/v1/accounts/{account_id}/maestro/provider-status":{"get":{"tags":["Maestro"],"operationId":"auto_get_api_v1_accounts_account_id_maestro_provider_status","summary":"Provider status maestro","description":"Performs the provider status operation on the targeted maestro resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"native":{"type":"array","items":{"type":"string"}}}},"example":{"native":["sample native"]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"503":{"description":"The Maestro area is not serving this installation: an operator turned it off, or no admin key was ever provisioned. Nothing was executed, and retrying will not help until the configuration changes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/maestro/platform-readiness":{"get":{"tags":["Maestro"],"operationId":"auto_get_api_v1_accounts_account_id_maestro_platform_readiness","summary":"Platform readiness maestro","description":"Performs the platform readiness operation on the targeted maestro resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"ready":{"type":"boolean"}}},"example":{"ready":true}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"503":{"description":"The Maestro area is not serving this installation: an operator turned it off, or no admin key was ever provisioned. Nothing was executed, and retrying will not help until the configuration changes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/maestro/mcp-token":{"get":{"tags":["Maestro"],"operationId":"auto_get_api_v1_accounts_account_id_maestro_mcp_token","summary":"Get the Maestro MCP server token status","description":"Reports whether this account already has a bearer token registered on the Maestro sidecar (which exposes the account's departments as MCP tools to an external client such as an IDE or a desktop assistant) and the public endpoint that client should point at. The token VALUE is never returned — the sidecar stores only its hash, and the plaintext is revealed once, on rotation. Admin-only.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Whether a Maestro MCP-server token is registered, plus the public MCP endpoint.","content":{"application/json":{"schema":{"type":"object","properties":{"configured":{"type":"boolean","description":"Whether the sidecar currently holds a token for this account. False also when Maestro is not deployed or is unreachable.","example":true},"endpoint_url":{"type":["string","null"],"description":"The MCP endpoint to configure in the external client. Resolves to the installation's internet-facing Maestro address (MAESTRO_PUBLIC_BASE_URL) and falls back to the internal one, which a client on the same host can still reach; null only when none is declared. One endpoint per deployment — the per-account token selects the account.","example":"https://maestro.example.com/mcp"},"endpoint_public":{"type":"boolean","description":"Whether that endpoint is one an EXTERNAL client can reach (a public Maestro address is declared). When false the URL is Maestro's internal address: usable from the same host, never from an IDE outside the network.","example":true}}},"example":{"configured":true,"endpoint_url":"https://maestro.example.com/mcp","endpoint_public":true}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/maestro/mcp-token/rotate":{"post":{"tags":["Maestro"],"operationId":"auto_post_api_v1_accounts_account_id_maestro_mcp_token_rotate","summary":"Rotate the Maestro MCP server token","description":"Generates a fresh bearer token for this account's Maestro MCP server, pushes it to the sidecar (which stores only its SHA-256 hash) and returns the plaintext ONCE. Any previously issued token is invalidated immediately. The platform never persists the plaintext, so it cannot be recovered later — copy it into the external MCP client now. Takes no request body. Admin-only. The Maestro sidecar does not accept an idempotency key for this operation: after a timeout, do not retry blindly because the first request may already have replaced the bearer. Check the sidecar status and rotate again only when a new replacement token is intended.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The freshly generated token — revealed ONCE. Store it now; a later request can only rotate it again, never read it back.","headers":{"Cache-Control":{"description":"This reveal-once response must never be retained by a browser or intermediary.","schema":{"type":"string","enum":["no-store, no-cache"],"example":"no-store, no-cache"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"token":{"type":"string","description":"The plaintext bearer token. Shown only in this response, never again.","example":"sample-token"},"endpoint_url":{"type":["string","null"],"description":"The MCP endpoint to configure in the external client, alongside the token. Same resolution as the status probe (public Maestro address, falling back to the API address); null only when neither is declared.","example":"https://maestro.example.com/mcp"},"endpoint_public":{"type":"boolean","description":"Whether that endpoint is reachable by an external client (see the status probe).","example":true}}},"example":{"token":"sample-token","endpoint_url":"https://maestro.example.com/mcp","endpoint_public":true}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"503":{"description":"Maestro is not configured for this installation, or the sidecar is unreachable. When the request could not reach a configured sidecar, the outcome is unknown: the sidecar may already have replaced the bearer even though the platform did not receive the response, so the previous token may already be invalid. Do not retry blindly; check status and rotate again only when a new replacement token is intended.","headers":{"Cache-Control":{"description":"This management error must never be retained by a browser or intermediary.","schema":{"type":"string","enum":["no-store, no-cache"],"example":"no-store, no-cache"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["maestro_unavailable"],"description":"The only failure code for this operation.","example":"maestro_unavailable"}}},"example":{"error":"maestro_unavailable"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/maestro/agents/providers/{provider}/models":{"get":{"tags":["Maestro"],"operationId":"auto_get_api_v1_accounts_account_id_maestro_agents_providers_provider_models","summary":"Browse a provider's live LLM model catalogue","description":"Proxies the sidecar's normalized model catalogue for a whitelisted provider (openai, anthropic, google_genai, groq, xai, cohere, deepseek, ollama, openrouter, elevenlabs). The first nine list LIVE from the provider's own models API; `elevenlabs` answers from the curated catalogue instead, because it publishes no models endpoint on the key we hold — and it is a real, selectable voice provider, so refusing it would claim it has no voices. An unknown provider or an unreachable sidecar returns an empty array. Only model metadata is returned, never any key — the sidecar lists with the credential it already holds for that provider (the agent's own key when `agent_id` is given, then the account's, then the installation panel, then `.env`).","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Normalized model list for the provider (empty for an unknown provider).","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ready-to-store provider:model spec","example":"openai:gpt-5.5"},"model":{"type":"string","description":"bare model id","example":"gpt-5.5"},"provider":{"type":"string","example":"openai","enum":["openai","anthropic","google_genai","groq","xai","cohere","deepseek","ollama","openrouter","elevenlabs"],"description":"Provider whose model catalogue is browsed. The set is the model browser's own whitelist: the nine providers that list models LIVE, plus `elevenlabs`, which answers from the curated catalogue because it publishes no models endpoint on the key we hold — barring it would claim ElevenLabs has no voices, which is false. `tavily` is absent on purpose and is not an omission: it serves the web search/fetch tools and hosts no model, so it can never be an answer here. An id outside the set returns an empty array rather than an error."},"provider_label":{"type":"string","example":"OpenAI"},"label":{"type":"string","example":"GPT-5.5"},"context_length":{"type":["integer","null"],"description":"input context window (tokens)","example":1000000},"max_output_tokens":{"type":["integer","null"],"example":128000},"prompt_price":{"type":["number","null"],"description":"USD per 1M input tokens","example":5.0},"completion_price":{"type":["number","null"],"description":"USD per 1M output tokens","example":30.0},"supports_tools":{"type":"boolean","example":true},"input_modalities":{"type":"array","items":{"type":"string"},"example":["text","image"]},"output_modalities":{"type":"array","items":{"type":"string"},"example":["text"]},"description":{"type":"string","example":""},"source":{"type":"string","enum":["live","catalogue"],"example":"live"},"dimension":{"type":["integer","null"],"description":"Vector width, on EMBEDDING rows only, and only when it is known as DATA. No provider publishes it in its models API (Google's `outputDimensionality` is a request parameter of `embedContent`, not model metadata; Cohere publishes none), so it comes from the curated catalogue and is null for a model reached only through the live list. It rides on the row because it decides whether the choice DOES anything: the store column is fixed-width, and a mis-sized model saves cleanly, shows success and is then skipped in silence at embed time. null means unknown — never a guessed number, and never a verdict on whether it fits.","example":1536}}}},"example":[{"id":"openai:gpt-5.5","model":"gpt-5.5","provider":"openai","provider_label":"OpenAI","label":"GPT-5.5","context_length":1000000,"max_output_tokens":128000,"prompt_price":5.0,"completion_price":30.0,"supports_tools":true,"input_modalities":["text","image"],"output_modalities":["text"],"description":"","source":"live","dimension":1536}]}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"502":{"description":"The Maestro service could not be reached (connection refused or reset, host unresolvable), or it answered in a way the gateway could not use, or it rejected the server-to-server credential — the last one is a deployment key mismatch, never the caller's own session. Nothing was executed; the call can be retried.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"504":{"description":"The Maestro service did not answer within the proxy timeout. The work may still be running on the service side, so retrying a write can duplicate its effect.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"503":{"description":"The Maestro area is not serving this installation: an operator turned it off, or no admin key was ever provisioned. Nothing was executed, and retrying will not help until the configuration changes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"provider","in":"path","required":true,"schema":{"type":"string"}},{"name":"modality","in":"query","required":false,"description":"Which modality to list. `chat` (the default) lists conversational models; the others list the models of that modality only. A provider is offered for a modality only when something can actually RUN it: Groq lists `playai-tts` beside its Whisper ids, so listing it for `tts` would hand back a model the voice layer discards in silence.","schema":{"type":"string","enum":["chat","realtime","stt","tts","embedding"],"default":"chat"},"example":"embedding"},{"name":"tools","in":"query","required":false,"description":"Keep only models that support function calling. Applied on the CHAT branch alone — no transcription, voice or embedding model does function calling, so outside chat it is a filter with nothing to filter.","schema":{"type":"boolean","default":false},"example":true},{"name":"q","in":"query","required":false,"description":"Case-insensitive substring match on the model id and label.","schema":{"type":"string"},"example":"embedding"},{"name":"agent_id","in":"query","required":false,"description":"List with THIS agent's credentials instead of the account's. What the browser offers then reflects what that agent can actually reach: an agent whose global fallback is disabled and that holds no key of its own gets the curated entries rather than the installation's catalogue.","schema":{"type":"integer"},"example":42}]}},"/api/v1/accounts/{account_id}/maestro/agents/provider-keys/test":{"post":{"tags":["Maestro"],"operationId":"auto_post_api_v1_accounts_account_id_maestro_agents_provider_keys_test","summary":"Test an AI provider key","description":"Validates a provider API key with one tiny live call before it is saved, so the form can show a result inline. The key is never echoed back. An authentication or transport failure is reported as `ok: false` with a short message rather than an error status. The honest limit: this proves the key exists and authenticates, not that there is quota behind it - a valid key with an exhausted balance passes here and still fails on the next real call.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The probe verdict. Reported inline whether the key worked or not.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","description":"True when the key authenticated against the provider.","example":true},"model":{"type":"string","description":"The model the ping was made with. Empty when no model was exercised - either because the provider has no chat model to ping (its own authenticated read is used instead) or because no model could be resolved.","example":"openai:gpt-5.5"},"error":{"type":["string","null"],"description":"Short failure reason, truncated. Null when the probe succeeded.","example":null}}},"example":{"ok":true,"model":"openai:gpt-5.5","error":null}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"502":{"description":"The Maestro service could not be reached (connection refused or reset, host unresolvable), or it answered in a way the gateway could not use, or it rejected the server-to-server credential — the last one is a deployment key mismatch, never the caller's own session. Nothing was executed; the call can be retried.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"504":{"description":"The Maestro service did not answer within the proxy timeout. The work may still be running on the service side, so retrying a write can duplicate its effect.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"503":{"description":"The Maestro area is not serving this installation: an operator turned it off, or no admin key was ever provisioned. Nothing was executed, and retrying will not help until the configuration changes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"description":"Whose key it is and the key itself. Exactly three fields are forwarded to the probe - `provider`, `api_key` and `model`; anything else in the body is dropped before the request leaves the platform. `api_key` is write-only: it travels here and is never read back, neither in this response nor by any later call.","content":{"application/json":{"schema":{"type":"object","required":["provider","api_key"],"properties":{"provider":{"type":"string","description":"Which provider the key belongs to. The set is every id the probe knows how to test, which is the same set the installation vault holds a key for. `google_genai` (not `google`) is the real id - a wrong id is answered as a failed probe, which reads as \"your key is bad\" when the mistake was in the id. Two entries are not chat providers and are still testable, each against its own API: `elevenlabs` (voice) and `tavily` (the web search/fetch tools). `ollama` is the one browsable provider absent here, and its absence is correct: it is keyless by nature, so there is nothing to probe.","enum":["openai","anthropic","google_genai","groq","xai","cohere","deepseek","openrouter","elevenlabs","tavily"],"example":"openai"},"api_key":{"type":"string","format":"password","description":"The raw key to probe, exactly as the operator pasted it. Sent on every attempt: this route validates a key BEFORE it is saved, so there is no stored value to fall back on. Never echoed back.","example":"sample-api-key"},"model":{"type":["string","null"],"description":"Optional `provider:model` spec to ping with. Omit it and the probe resolves a model for the provider itself - which is what the Robô form does, since the operator is testing a key, not a model. A provider with no chat model to ping ignores it and uses its own authenticated read instead.","example":"openai:gpt-5.5"}}},"example":{"provider":"openai","api_key":"sample-api-key","model":"openai:gpt-5.5"}}}}}},"/api/v1/accounts/{account_id}/maestro/agents/tools/test":{"post":{"tags":["Maestro"],"operationId":"auto_post_api_v1_accounts_account_id_maestro_agents_tools_test","summary":"Test a Maestro custom HTTP tool","description":"Executes a custom HTTP tool definition live (headers/query/body/auth actually run through the sidecar's turn-time engine + SSRF guard) with sample args, so the operator sees the real result. `agent_id` lets the sidecar resolve saved {{secret.X}} / auth from that agent's secrets.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The full captured result of the single live call — outcome flag, upstream status, every response header, the raw body and the value the model would actually receive after mapping/extract. This status is returned even when the tool itself failed: an upstream error or a transport/SSRF failure is reported inside the body (`ok: false` plus `error`) so the Studio can show it inline instead of surfacing a proxy error.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","description":"Whether the call completed successfully (false on upstream error or transport failure).","example":true},"result":{"type":"string","description":"Raw upstream response body, truncated to 4000 characters, so the operator can inspect every field before mapping it. Falls back to the rendered value when the upstream body is empty, and is an empty string when no response was received.","example":"{\"cep\":\"01310-100\",\"logradouro\":\"Avenida Paulista\",\"localidade\":\"Sao Paulo\",\"uf\":\"SP\"}"},"status":{"type":["integer","null"],"description":"Upstream HTTP status code; null when no HTTP response came back (transport or SSRF failure).","example":200},"headers":{"type":"object","additionalProperties":{"type":"string"},"description":"Every response header captured from the upstream call, name to value. Empty when no response was received.","example":{"content-type":"application/json; charset=utf-8"}},"rendered":{"type":"string","description":"What the agent would actually receive for this call after the tool's mapping and `extract` are applied, truncated to 2000 characters. Empty when nothing was rendered.","example":"Avenida Paulista"},"error":{"type":["string","null"],"description":"Transport, SSRF-guard or rendering failure message, truncated to 500 characters. Null when the call reached the upstream service.","example":null}}},"example":{"ok":true,"result":"{\"cep\":\"01310-100\",\"logradouro\":\"Avenida Paulista\",\"localidade\":\"Sao Paulo\",\"uf\":\"SP\"}","status":200,"headers":{"content-type":"application/json; charset=utf-8"},"rendered":"Avenida Paulista","error":null}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"502":{"description":"The sidecar could not be reached, answered with an unusable response, or rejected the server-to-server admin credential. Never a pass-through of the sidecar's own auth status — the requester's session is already valid at this point.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Localized human-readable message for the failure class.","example":"Maestro is unreachable."},"code":{"type":"string","description":"Stable machine code identifying the transport failure class.","enum":["maestro_unreachable","maestro_error","maestro_auth_failed"],"example":"maestro_unreachable"}}},"example":{"error":"Maestro is unreachable.","code":"maestro_unreachable"}}}},"504":{"description":"The sidecar did not answer within the proxy timeout window for this call.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Localized human-readable timeout message.","example":"Maestro timed out."},"code":{"type":"string","description":"Stable machine code for the timeout failure class.","enum":["maestro_timeout"],"example":"maestro_timeout"}}},"example":{"error":"Maestro timed out.","code":"maestro_timeout"}}}},"503":{"description":"Maestro is not usable for this installation — either the operator turned it off or no admin key was ever provisioned. The two cases are distinguished by the machine code.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Localized human-readable message for the unavailable state.","example":"Maestro is not configured."},"code":{"type":"string","description":"Stable machine code telling \"turned off\" apart from \"never provisioned\".","enum":["maestro_disabled","maestro_not_configured"],"example":"maestro_not_configured"}}},"example":{"error":"Maestro is not configured.","code":"maestro_not_configured"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"agent_id":{"type":"integer","description":"Agent whose saved secrets back the tool's auth/{{secret.X}}.","example":12},"args":{"type":"object","additionalProperties":true,"description":"Sample argument values for the tool's parameters.","example":{"cep":"01310-100"}},"tool":{"type":"object","description":"The custom-tool definition (same shape as a config custom_tools item).","properties":{"name":{"type":"string","example":"lookup_cep"},"description":{"type":"string","example":"Resolve a Brazilian postal code"},"method":{"type":"string","example":"GET"},"url":{"type":"string","example":"https://viacep.com.br/ws/{{args.cep}}/json/"},"sensitive":{"type":"boolean","example":false},"extract":{"type":"string","example":"logradouro"},"body_type":{"type":"string","example":"json"},"auth":{"type":"object","properties":{"type":{"type":"string","example":"bearer"},"name":{"type":"string","example":"Authorization"},"token_secret":{"type":"string","example":"API_TOKEN"},"username_secret":{"type":"string","example":"BASIC_USER"},"password_secret":{"type":"string","example":"BASIC_PASS"}}},"params":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","example":"cep"},"type":{"type":"string","example":"string"},"description":{"type":"string","example":"Postal code"},"required":{"type":"boolean","example":true},"location":{"type":"string","example":"path"}}}},"headers":{"type":"object","additionalProperties":{"type":"string"},"description":"Static HTTP headers sent with the custom tool request (name to value)."},"query":{"type":"object","additionalProperties":{"type":"string"},"description":"Static query-string parameters sent with the custom tool request (name to value)."}}}}},"example":{"agent_id":12,"args":{"cep":"01310-100"},"tool":{"name":"lookup_cep","description":"Resolve a Brazilian postal code","method":"GET","url":"https://viacep.com.br/ws/{{args.cep}}/json/","sensitive":false,"extract":"logradouro","body_type":"json","auth":{"type":"bearer","name":"Authorization","token_secret":"API_TOKEN","username_secret":"BASIC_USER","password_secret":"BASIC_PASS"},"params":[{"name":"cep","type":"string","description":"Postal code","required":true,"location":"path"}],"headers":{},"query":{}}}}}}}},"/api/v1/accounts/{account_id}/maestro/agents/mcp/discover":{"post":{"tags":["Maestro"],"operationId":"auto_post_api_v1_accounts_account_id_maestro_agents_mcp_discover","summary":"Discover an external MCP server's tools","description":"Previews the tools an external MCP server exposes, before the server is saved on an AI agent. The Maestro sidecar performs the discovery behind its SSRF guard (a blocked or unreachable host comes back as `ok: false` with an `error` message — never a 5xx), so the operator sees the real tool list and can build the allowlist. Secrets are referenced BY KEY: `auth` names the secret keys, and their values are resolved on the sidecar from the saved agent's secrets (`agent_id`) and/or from `secrets` typed in the form but not yet persisted. No secret value is ever echoed back. The authoritative discovery runs again on the sidecar when the agent is saved; the tools are stored there, not round-tripped through this API. Admin-only.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The discovery result. A refused host, an unreachable server or a failed handshake comes back here with `ok: false` and a human-readable `error` — this operation does not 5xx.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","description":"Whether the remote server responded and its tools could be listed.","example":true},"tools":{"type":"array","description":"The discovered tools, already filtered by the `enabled_tools` allowlist. Empty when the discovery failed or the server exposes no tools.","items":{"type":"object","properties":{"name":{"type":"string","description":"Remote tool name (the value to put in `enabled_tools`).","example":"echo"},"description":{"type":"string","description":"Remote tool description, as advertised by the server.","example":"Echo back the input"},"input_schema":{"type":"object","additionalProperties":true,"description":"JSON Schema of the remote tool's arguments, as advertised by the server.","example":{}}}}},"error":{"type":["string","null"],"description":"Why the discovery failed (blocked host, connection refused, handshake error). Null when `ok` is true.","example":null}}},"example":{"ok":true,"tools":[{"name":"echo","description":"Echo back the input","input_schema":{"type":"object","properties":{"text":{"type":"string"}},"required":["text"]}}],"error":null}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["server"],"properties":{"server":{"type":"object","description":"The external MCP server definition — only the operator-editable fields. The remote tools are discovered, never declared here.","properties":{"name":{"type":"string","description":"Local name for the server; it namespaces the discovered tools on the agent.","example":"acme"},"url":{"type":"string","description":"The remote MCP endpoint. Private/loopback hosts are refused by the sidecar's SSRF guard.","example":"https://mcp.acme.com/mcp"},"transport":{"type":"string","enum":["streamable_http","sse"],"description":"MCP transport the remote server speaks.","example":"streamable_http"},"timeout":{"type":"number","description":"Per-call timeout in seconds.","example":30},"sensitive":{"type":"boolean","description":"When true, every tool from this server requires human approval (HITL) before it runs in a conversation.","example":false},"enabled_tools":{"type":"array","description":"Allowlist of remote tool names to bind to the agent. Empty means every discovered tool. The discovery response is filtered by this list.","items":{"type":"string","example":"echo"}},"headers":{"type":"object","additionalProperties":{"type":"string"},"description":"Static headers sent to the remote server. Values may reference a secret key instead of carrying a literal credential.","example":{}},"auth":{"type":"object","description":"Authentication for the remote server, expressed as secret-key REFERENCES. The values are resolved on the sidecar and never echoed. With `oauth` no secret key is used at all — the credential is the OAuth grant obtained through the browser consent flow and held in the sidecar's encrypted token store, keyed by (agent, server name).","properties":{"type":{"type":"string","enum":["none","bearer","basic","header","query","oauth"],"description":"How the credential is presented to the remote server. Most public MCP servers (Linear, Stripe, GitHub, Atlassian) answer 401 with an OAuth challenge yet ALSO accept a plain API key in `Authorization: Bearer`, so `bearer` + a secret holding the key is enough for them; Sentry needs `header` with the value `Sentry-Bearer \u003ctoken\u003e`; an OAuth-only server (Notion) needs `oauth`, which ignores every `*_secret` field.","example":"bearer"},"name":{"type":["string","null"],"description":"Header or query-parameter name — only for the `header` and `query` types.","example":null},"token_secret":{"type":["string","null"],"description":"Secret KEY holding the token — for the `bearer`, `header` and `query` types.","example":"ACME_TOKEN"},"username_secret":{"type":["string","null"],"description":"Secret KEY holding the username — for the `basic` type.","example":null},"password_secret":{"type":["string","null"],"description":"Secret KEY holding the password — for the `basic` type.","example":null}}}}},"agent_id":{"type":["integer","null"],"description":"Resolve the secret-key references from this saved agent's secrets. Omit when the agent does not exist yet and send the values in `secrets` instead.","example":12},"secrets":{"type":"object","additionalProperties":{"type":"string"},"description":"Freshly typed secret values, keyed by secret name, for keys not yet persisted on the agent. Write-only — never echoed back.","example":{}}}},"example":{"server":{"name":"acme","url":"https://mcp.acme.com/mcp","transport":"streamable_http","timeout":30,"sensitive":false,"enabled_tools":["echo"],"headers":{},"auth":{"type":"bearer","name":null,"token_secret":"ACME_TOKEN","username_secret":null,"password_secret":null}},"agent_id":12,"secrets":{}}}}}}},"/api/v1/accounts/{account_id}/maestro/agents/mcp/oauth/start":{"post":{"tags":["Maestro"],"operationId":"auto_post_api_v1_accounts_account_id_maestro_agents_mcp_oauth_start","summary":"Start the OAuth consent flow for an external MCP server","description":"Begins the browser consent flow that authorizes an AI agent to call an external MCP server whose auth type is `oauth` (an OAuth-only provider such as Notion). The Maestro sidecar registers itself with the remote provider and returns the provider's `authorization_url`; the dashboard opens it in a popup, the operator approves there, and the provider redirects to the sidecar's public callback — NOT to this API — which exchanges the code and stores the tokens encrypted, keyed by (agent, server name). No token, code or client secret ever reaches the platform. Poll the status operation to learn when the connection is live. A provider that cannot be reached, refuses registration, or is blocked by the sidecar's SSRF guard comes back here with `ok: false` and a human-readable `error` — not a 5xx. Admin-only.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Where to send the operator's browser, or why the flow could not be started. A refused host, an unreachable provider or a failed registration comes back here with `ok: false` — this operation does not 5xx on a remote failure.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","description":"Whether the consent flow could be started.","example":true},"authorization_url":{"type":["string","null"],"description":"The remote provider's consent screen. Open it in a popup; the provider redirects back to the sidecar's public callback, which stores the tokens and closes the window. Null when `ok` is false.","example":"https://provider.example.com/oauth/authorize?client_id=abc\u0026state=xyz"},"error":{"type":["string","null"],"description":"Why the flow could not be started (blocked host, unreachable provider, registration refused). Null when `ok` is true.","example":null}}},"example":{"ok":true,"authorization_url":"https://provider.example.com/oauth/authorize?client_id=abc\u0026state=xyz","error":null}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"502":{"description":"The Maestro sidecar is unreachable or answered with a transport-level failure. Nothing was started.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable message, localized for the caller.","example":"Maestro is unavailable"},"code":{"type":"string","enum":["maestro_unreachable","maestro_error"],"description":"Stable machine code for the failure class.","example":"maestro_unreachable"}}},"example":{"error":"Maestro is unavailable","code":"maestro_unreachable"}}}},"503":{"description":"Maestro is not configured for this installation — the sidecar was never called.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable message, localized for the caller.","example":"Maestro is not configured"},"code":{"type":"string","enum":["maestro_not_configured"],"description":"The only failure code for a missing Maestro configuration.","example":"maestro_not_configured"}}},"example":{"error":"Maestro is not configured","code":"maestro_not_configured"}}}},"504":{"description":"The sidecar did not answer within the proxy timeout. The flow may or may not have been registered — retry.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable message, localized for the caller.","example":"Maestro timed out"},"code":{"type":"string","enum":["maestro_timeout"],"description":"The only failure code for a proxy timeout.","example":"maestro_timeout"}}},"example":{"error":"Maestro timed out","code":"maestro_timeout"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"},"description":"The account that owns the AI agent."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["agent_id","server"],"properties":{"agent_id":{"type":"integer","description":"The saved AI agent the connection is bound to. Required — the sidecar keys the token store by (agent, server name), so the agent must exist before consent is started.","example":12},"server":{"type":"object","description":"The external MCP server to authorize. Only the connection fields are read; the OAuth auth type carries no secret keys, so none are sent.","properties":{"name":{"type":"string","description":"Local name of the server on the agent. Together with `agent_id` it is the key of the stored grant, so it must match the name saved on the agent.","example":"acme"},"url":{"type":"string","description":"The remote MCP endpoint. Private/loopback hosts are refused by the sidecar's SSRF guard.","example":"https://mcp.acme.com/mcp"},"transport":{"type":"string","enum":["streamable_http","sse"],"description":"MCP transport the remote server speaks.","example":"streamable_http"},"timeout":{"type":"number","description":"Per-call timeout in seconds.","example":30}}}}},"example":{"agent_id":12,"server":{"name":"acme","url":"https://mcp.acme.com/mcp","transport":"streamable_http","timeout":30}}}}}}},"/api/v1/accounts/{account_id}/maestro/agents/mcp/oauth/status":{"get":{"tags":["Maestro"],"operationId":"auto_get_api_v1_accounts_account_id_maestro_agents_mcp_oauth_status","summary":"Check the OAuth connection of an external MCP server","description":"Reports whether the sidecar currently holds a valid OAuth grant for this (agent, server name) pair — what the dashboard polls while the consent popup is open, and what paints the Connected/Disconnected state afterwards. The token VALUE is never returned: only whether it exists, when it expires and which scope the provider granted. Admin-only.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The state of the stored grant. An agent/server pair that was never connected simply comes back with `connected` false — it is not an error.","content":{"application/json":{"schema":{"type":"object","properties":{"connected":{"type":"boolean","description":"Whether the sidecar holds a usable OAuth grant for this (agent, server) pair.","example":true},"expires_at":{"type":["string","null"],"format":"date-time","description":"When the access token expires, as reported by the provider. Null when it is not connected or the provider issues tokens that do not expire.","example":"2026-07-13T18:42:00Z"},"scope":{"type":["string","null"],"description":"The scope string the provider granted. Null when it is not connected or the provider returned none.","example":"read write"}}},"example":{"connected":true,"expires_at":"2026-07-13T18:42:00Z","scope":"read write"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"502":{"description":"The Maestro sidecar is unreachable or answered with a transport-level failure.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable message, localized for the caller.","example":"Maestro is unavailable"},"code":{"type":"string","enum":["maestro_unreachable","maestro_error"],"description":"Stable machine code for the failure class.","example":"maestro_unreachable"}}},"example":{"error":"Maestro is unavailable","code":"maestro_unreachable"}}}},"503":{"description":"Maestro is not configured for this installation — the sidecar was never called.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable message, localized for the caller.","example":"Maestro is not configured"},"code":{"type":"string","enum":["maestro_not_configured"],"description":"The only failure code for a missing Maestro configuration.","example":"maestro_not_configured"}}},"example":{"error":"Maestro is not configured","code":"maestro_not_configured"}}}},"504":{"description":"The sidecar did not answer within the proxy timeout.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable message, localized for the caller.","example":"Maestro timed out"},"code":{"type":"string","enum":["maestro_timeout"],"description":"The only failure code for a proxy timeout.","example":"maestro_timeout"}}},"example":{"error":"Maestro timed out","code":"maestro_timeout"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"},"description":"The account that owns the AI agent."},{"name":"agent_id","in":"query","required":true,"schema":{"type":"integer"},"description":"The AI agent the grant is bound to."},{"name":"server","in":"query","required":true,"schema":{"type":"string"},"description":"Local name of the external MCP server on that agent (the other half of the grant's key)."}]}},"/api/v1/accounts/{account_id}/maestro/agents/mcp/oauth":{"delete":{"tags":["Maestro"],"operationId":"auto_delete_api_v1_accounts_account_id_maestro_agents_mcp_oauth","summary":"Forget the OAuth connection of an external MCP server","description":"Makes the sidecar discard the OAuth grant it holds for this (agent, server name) pair. The agent stops being able to call that server until the consent flow is run again — use it to revoke access or to switch the provider account. The grant lives only on the sidecar, so nothing is deleted on the platform side. Idempotent: forgetting a pair that was never connected still answers `ok: true`. The keys travel as query parameters, so the request carries no body. Admin-only.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The grant was discarded (or there was none to discard).","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","description":"Always true — the operation is idempotent.","example":true}}},"example":{"ok":true}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"502":{"description":"The Maestro sidecar is unreachable or answered with a transport-level failure. The grant was NOT discarded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable message, localized for the caller.","example":"Maestro is unavailable"},"code":{"type":"string","enum":["maestro_unreachable","maestro_error"],"description":"Stable machine code for the failure class.","example":"maestro_unreachable"}}},"example":{"error":"Maestro is unavailable","code":"maestro_unreachable"}}}},"503":{"description":"Maestro is not configured for this installation — the sidecar was never called.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable message, localized for the caller.","example":"Maestro is not configured"},"code":{"type":"string","enum":["maestro_not_configured"],"description":"The only failure code for a missing Maestro configuration.","example":"maestro_not_configured"}}},"example":{"error":"Maestro is not configured","code":"maestro_not_configured"}}}},"504":{"description":"The sidecar did not answer within the proxy timeout. The grant may or may not have been discarded — retry.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable message, localized for the caller.","example":"Maestro timed out"},"code":{"type":"string","enum":["maestro_timeout"],"description":"The only failure code for a proxy timeout.","example":"maestro_timeout"}}},"example":{"error":"Maestro timed out","code":"maestro_timeout"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"},"description":"The account that owns the AI agent."},{"name":"agent_id","in":"query","required":true,"schema":{"type":"integer"},"description":"The AI agent the grant is bound to."},{"name":"server","in":"query","required":true,"schema":{"type":"string"},"description":"Local name of the external MCP server on that agent (the other half of the grant's key)."}]}},"/api/v1/accounts/{account_id}/maestro/agents/database/test":{"post":{"tags":["Maestro"],"operationId":"auto_post_api_v1_accounts_account_id_maestro_agents_database_test","summary":"Test a Robô database connection","description":"Validates a database connection by opening it and listing the tables it can read, so the form can show a result and the discovered table names inline. Accepts either a connection URL typed into the form or a Robô id plus the name of one of its stored connection secrets. The connection string is never echoed back, and a connection or authentication failure is reported as `ok: false` with a short message rather than an error status.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The probe verdict and, on success, the tables the connection can read.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","description":"True when the connection opened and reflection succeeded.","example":true},"tables":{"type":"array","description":"Table names the connection can read. Empty when the probe failed.","items":{"type":"string"},"example":["orders","customers","shipments"]},"error":{"type":["string","null"],"description":"Short failure reason, truncated. Null when the probe succeeded.","example":null}}},"example":{"ok":true,"tables":["orders","customers","shipments"],"error":null}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"502":{"description":"The Maestro service could not be reached (connection refused or reset, host unresolvable), or it answered in a way the gateway could not use, or it rejected the server-to-server credential — the last one is a deployment key mismatch, never the caller's own session. Nothing was executed; the call can be retried.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"504":{"description":"The Maestro service did not answer within the proxy timeout. The work may still be running on the service side, so retrying a write can duplicate its effect.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"503":{"description":"The Maestro area is not serving this installation: an operator turned it off, or no admin key was ever provisioned. Nothing was executed, and retrying will not help until the configuration changes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"connection_url":{"type":"string"},"agent_id":{"type":"integer"},"connection_secret":{"type":"string"}}},"example":{"connection_url":"https://example.com/resource","agent_id":1,"connection_secret":"sample-token"}}}}}},"/api/v1/accounts/{account_id}/maestro/agents/{id}/sync-native-keys":{"post":{"tags":["Maestro"],"operationId":"auto_post_api_v1_accounts_account_id_maestro_agents_id_sync_native_keys","summary":"Re-mirror the account provider keys into a Robô","description":"Pushes the account's currently configured native AI provider keys into the Robô without touching any other setting, so a key rotated in the integration settings reaches the Robô immediately instead of waiting for the next configuration save. Returns the Robô as stored; the key fields come back as booleans saying WHICH providers are configured, never the values.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The Robô, with its key-presence flags refreshed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_agent"},"example":{"id":42,"account_id":7,"name":"Atendimento","enabled":true,"config":{"persona":"Você é a atendente virtual da Acme, cordial e objetiva.","instructions":"Sempre confirme o CPF antes de consultar um pedido.","default_model":"openai:gpt-5.4-mini-2026-03-17","fallback_models":["anthropic:claude-haiku-4-5-20251001"],"enabled_tools":["set_labels"],"autonomy_level":"autopilot","interaction_mode":"converse","search_config":{"enabled":true,"search_depth":"basic","max_results":5,"topic":"general","include_domains":["docs.example.com"],"exclude_domains":[]},"locale":"pt_BR","quiet_window_seconds":8,"max_window_seconds":40,"summary_threshold_tokens":3000,"standdown_on_assignment":true,"standdown_auto_resume":true,"standdown_ttl_seconds":86400,"paused_inbound_policy":"discard","paused_inbound_max_messages":10,"paused_inbound_max_age_seconds":3600,"handoff_team_id":3,"working_hours_policy":"ignore","out_of_office_message":"Nosso atendimento volta às 9h. Já registramos sua mensagem.","handoff_policy":{"target_status":"open","target_priority":"none","triggers":["falar com atendente"]},"guardrails":{"banned_topics":["assuntos jurídicos"],"blocked_phrases":["garantimos 100% de aprovação"],"max_output_chars":1200,"pii_policy":"off","require_handoff_conditions":["cliente pede cancelamento"]},"knowledge_base":{"enabled":true,"top_k":5,"use_shared":false},"database":{"enabled":false,"connection_secret":"ERP_DB_URL","read_only":true,"max_rows":200,"statement_timeout_seconds":15,"include_tables":["orders"],"description":"Pedidos e faturas do ERP.","instructions":"Sempre filtre por account_id."},"reactions":{"outbound":false,"understand_inbound":false},"media":{"audio":true,"vision":true,"documents":true},"close_on_complete":"off","verification_policy":"off","model_params":{"reasoning_effort":"low","temperature":0.4,"top_p":0.9,"max_output_tokens":512},"service_flow":{"enabled":false,"on_exit":"handoff","strict_tools":true,"steps":[{"key":"qualificacao","name":"Qualificação","goal":"Descobrir o segmento e o tamanho da empresa.","allowed_tools":["contact_update"],"exit":{"type":"tools_executed","tools":["contact_update"],"attributes":["segmento"],"max_turns":8},"next":"proposta"}]},"max_tool_iterations":8,"history_limit_messages":40,"tail_budget_tokens":1500,"hard_cap_tokens":6000,"chain_same_provider":"","delivery":{"quote_replies":true,"formatting":"auto"},"stt":{"provider":"groq","model":"groq:whisper-large-v3-turbo"},"embedding":{"provider":"openai","model":"text-embedding-3-small"},"voice":{"enabled":false,"mode":"off","with_text":false,"provider":"elevenlabs","model":"eleven_multilingual_v2","call_backend":"auto","call_model":"openai:gpt-realtime","voice_id":"21m00Tcm4TlvDq8ikWAM","openai_voice":"alloy","gemini_voice":"Kore","stability":0.5,"similarity_boost":0.75,"style":0,"use_speaker_boost":true,"speed":1,"instructions":"Fale de forma calma e acolhedora.","style_instructions":"Locução comercial, ritmo animado."},"image_gen":{"enabled":false,"provider":"openai","model":"gpt-image-1"},"video_gen":{"enabled":false,"provider":"openai","model":"sora-2"},"custom_tools":[{"name":"consultar_pedido","description":"Consulta o status de um pedido pelo número.","method":"GET","url":"https://api.acme.com/orders/{{order_id}}","sensitive":false,"extract":"data.status","body_type":"json","body_template":{"source":"maestro","order_id":"{{order_id}}"},"headers":{"X-Api-Version":"2026-01"},"query":{"include":"items"},"auth":{"type":"bearer","name":"X-Api-Key","token_secret":"ACME_API_TOKEN","username_secret":"ACME_USER","password_secret":"ACME_PASS"},"params":[{"name":"order_id","type":"string","description":"Número do pedido.","required":true,"location":"auto"}],"response_map":[{"label":"Status","path":"data.status"}],"pagination":{"type":"none","param":"page","items_path":"data","next_path":"meta.next","start":1,"max_pages":5,"size_param":"per_page","size":50}}],"mcp_servers":[{"name":"acme-erp","url":"https://mcp.acme.com/sse","transport":"streamable_http","timeout":30,"sensitive":false,"enabled_tools":["get_order"],"headers":{"X-Tenant":"acme"},"auth":{"type":"bearer","name":"X-Api-Key","token_secret":"ACME_MCP_TOKEN","username_secret":"ACME_USER","password_secret":"ACME_PASS"}}],"media_assets":[{"name":"catalogo_2026","description":"Catálogo completo em PDF.","url":"https://cdn.acme.com/catalogo.pdf","type":"file"}],"sub_agents":[{"agent_id":7,"name":"Vendas","slug":"vendas","description":"Perguntas sobre planos e preços.","enabled":true,"sensitive":false}],"secrets":{"ACME_API_TOKEN":"sk-live-xxxxxxxx"},"secret_keys":["ACME_API_TOKEN"],"provider_keys":{"openai":"sk-proj-xxxxxxxx"},"chatwoot_native_keys":{"openai":"sk-proj-xxxxxxxx"},"provider_keys_set":["openai"],"native_keys_set":["openai"],"use_global_fallback":true},"bindings":[{"id":9,"inbox_id":3}],"created_at":"2026-07-01T12:00:00Z","updated_at":"2026-07-27T14:03:00Z"}}}},"401":{"description":"Unauthorized"},"404":{"description":"No Robô with this id belongs to the account."},"502":{"description":"The Maestro service could not be reached (connection refused or reset, host unresolvable), or it answered in a way the gateway could not use, or it rejected the server-to-server credential — the last one is a deployment key mismatch, never the caller's own session. Nothing was executed; the call can be retried.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"504":{"description":"The Maestro service did not answer within the proxy timeout. The work may still be running on the service side, so retrying a write can duplicate its effect.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"503":{"description":"The Maestro area is not serving this installation: an operator turned it off, or no admin key was ever provisioned. Nothing was executed, and retrying will not help until the configuration changes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/maestro/agents/{id}/voice-clone":{"post":{"tags":["Maestro"],"operationId":"auto_post_api_v1_accounts_account_id_maestro_agents_id_voice_clone","summary":"Clone a voice for a Robô","description":"Creates an instant voice clone from the uploaded audio samples and stores the resulting voice on the Robô, switching its voice provider to the cloning provider. Samples ride as base64 because this proxy forwards every call as JSON. The provider key is resolved server-side, per Robô then account then installation, and is never returned. Answers with the updated Robô - the new voice identifier is in its voice configuration.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The Robô, with the cloned voice stored on its voice configuration.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_agent"},"example":{"id":42,"account_id":7,"name":"Atendimento","enabled":true,"config":{"persona":"Você é a atendente virtual da Acme, cordial e objetiva.","instructions":"Sempre confirme o CPF antes de consultar um pedido.","default_model":"openai:gpt-5.4-mini-2026-03-17","fallback_models":["anthropic:claude-haiku-4-5-20251001"],"enabled_tools":["set_labels"],"autonomy_level":"autopilot","interaction_mode":"converse","search_config":{"enabled":true,"search_depth":"basic","max_results":5,"topic":"general","include_domains":["docs.example.com"],"exclude_domains":[]},"locale":"pt_BR","quiet_window_seconds":8,"max_window_seconds":40,"summary_threshold_tokens":3000,"standdown_on_assignment":true,"standdown_auto_resume":true,"standdown_ttl_seconds":86400,"paused_inbound_policy":"discard","paused_inbound_max_messages":10,"paused_inbound_max_age_seconds":3600,"handoff_team_id":3,"working_hours_policy":"ignore","out_of_office_message":"Nosso atendimento volta às 9h. Já registramos sua mensagem.","handoff_policy":{"target_status":"open","target_priority":"none","triggers":["falar com atendente"]},"guardrails":{"banned_topics":["assuntos jurídicos"],"blocked_phrases":["garantimos 100% de aprovação"],"max_output_chars":1200,"pii_policy":"off","require_handoff_conditions":["cliente pede cancelamento"]},"knowledge_base":{"enabled":true,"top_k":5,"use_shared":false},"database":{"enabled":false,"connection_secret":"ERP_DB_URL","read_only":true,"max_rows":200,"statement_timeout_seconds":15,"include_tables":["orders"],"description":"Pedidos e faturas do ERP.","instructions":"Sempre filtre por account_id."},"reactions":{"outbound":false,"understand_inbound":false},"media":{"audio":true,"vision":true,"documents":true},"close_on_complete":"off","verification_policy":"off","model_params":{"reasoning_effort":"low","temperature":0.4,"top_p":0.9,"max_output_tokens":512},"service_flow":{"enabled":false,"on_exit":"handoff","strict_tools":true,"steps":[{"key":"qualificacao","name":"Qualificação","goal":"Descobrir o segmento e o tamanho da empresa.","allowed_tools":["contact_update"],"exit":{"type":"tools_executed","tools":["contact_update"],"attributes":["segmento"],"max_turns":8},"next":"proposta"}]},"max_tool_iterations":8,"history_limit_messages":40,"tail_budget_tokens":1500,"hard_cap_tokens":6000,"chain_same_provider":"","delivery":{"quote_replies":true,"formatting":"auto"},"stt":{"provider":"groq","model":"groq:whisper-large-v3-turbo"},"embedding":{"provider":"openai","model":"text-embedding-3-small"},"voice":{"enabled":false,"mode":"off","with_text":false,"provider":"elevenlabs","model":"eleven_multilingual_v2","call_backend":"auto","call_model":"openai:gpt-realtime","voice_id":"21m00Tcm4TlvDq8ikWAM","openai_voice":"alloy","gemini_voice":"Kore","stability":0.5,"similarity_boost":0.75,"style":0,"use_speaker_boost":true,"speed":1,"instructions":"Fale de forma calma e acolhedora.","style_instructions":"Locução comercial, ritmo animado."},"image_gen":{"enabled":false,"provider":"openai","model":"gpt-image-1"},"video_gen":{"enabled":false,"provider":"openai","model":"sora-2"},"custom_tools":[{"name":"consultar_pedido","description":"Consulta o status de um pedido pelo número.","method":"GET","url":"https://api.acme.com/orders/{{order_id}}","sensitive":false,"extract":"data.status","body_type":"json","body_template":{"source":"maestro","order_id":"{{order_id}}"},"headers":{"X-Api-Version":"2026-01"},"query":{"include":"items"},"auth":{"type":"bearer","name":"X-Api-Key","token_secret":"ACME_API_TOKEN","username_secret":"ACME_USER","password_secret":"ACME_PASS"},"params":[{"name":"order_id","type":"string","description":"Número do pedido.","required":true,"location":"auto"}],"response_map":[{"label":"Status","path":"data.status"}],"pagination":{"type":"none","param":"page","items_path":"data","next_path":"meta.next","start":1,"max_pages":5,"size_param":"per_page","size":50}}],"mcp_servers":[{"name":"acme-erp","url":"https://mcp.acme.com/sse","transport":"streamable_http","timeout":30,"sensitive":false,"enabled_tools":["get_order"],"headers":{"X-Tenant":"acme"},"auth":{"type":"bearer","name":"X-Api-Key","token_secret":"ACME_MCP_TOKEN","username_secret":"ACME_USER","password_secret":"ACME_PASS"}}],"media_assets":[{"name":"catalogo_2026","description":"Catálogo completo em PDF.","url":"https://cdn.acme.com/catalogo.pdf","type":"file"}],"sub_agents":[{"agent_id":7,"name":"Vendas","slug":"vendas","description":"Perguntas sobre planos e preços.","enabled":true,"sensitive":false}],"secrets":{"ACME_API_TOKEN":"sk-live-xxxxxxxx"},"secret_keys":["ACME_API_TOKEN"],"provider_keys":{"openai":"sk-proj-xxxxxxxx"},"chatwoot_native_keys":{"openai":"sk-proj-xxxxxxxx"},"provider_keys_set":["openai"],"native_keys_set":["openai"],"use_global_fallback":true},"bindings":[{"id":9,"inbox_id":3}],"created_at":"2026-07-01T12:00:00Z","updated_at":"2026-07-27T14:03:00Z"}}}},"401":{"description":"Unauthorized"},"404":{"description":"No Robô with this id belongs to the account."},"502":{"description":"The voice provider refused or failed the clone. Nothing was stored on the Robô."},"504":{"description":"The Maestro service did not answer within the proxy timeout. The work may still be running on the service side, so retrying a write can duplicate its effect.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"503":{"description":"The Maestro area is not serving this installation: an operator turned it off, or no admin key was ever provisioned. Nothing was executed, and retrying will not help until the configuration changes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"400":{"description":"No voice provider key is configured for this Robô, or the samples were unusable - a sample that is not valid base64, or a request carrying no sample at all."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"samples":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Free-form object."}}}},"example":{"name":"Sample Name","samples":[{}]}}}}}},"/api/v1/accounts/{account_id}/maestro/agents/{id}/voice-test":{"post":{"tags":["Maestro"],"operationId":"auto_post_api_v1_accounts_account_id_maestro_agents_id_voice_test","summary":"Preview a Robô voice","description":"Synthesizes a short clip so a voice can be heard before it is saved. Uses the voice settings sent in the body when present, otherwise the Robô's stored ones. The clip is returned inline as base64 for the browser to play; nothing is sent to any contact. A synthesis failure is reported as `ok: false` with a short message rather than an error status.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The synthesized preview, or the reason no audio could be produced.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","description":"True when a clip was produced.","example":true},"audio_base64":{"type":"string","description":"The clip, base64-encoded. Empty when synthesis failed.","example":"T2dnUwACAAAAAAAAAAA="},"mime":{"type":"string","description":"Media type of the returned clip. Empty when synthesis failed.","example":"audio/ogg"},"provider":{"type":"string","description":"The provider that actually produced the clip - the chain is walked in order and the first one with a usable key answers. Empty when synthesis failed.","enum":["","elevenlabs","openai","google_genai"],"example":"elevenlabs"},"error":{"type":["string","null"],"description":"Short failure reason, truncated. Null when a clip was produced.","example":null}}},"example":{"ok":true,"audio_base64":"T2dnUwACAAAAAAAAAAA=","mime":"audio/ogg","provider":"elevenlabs","error":null}}}},"401":{"description":"Unauthorized"},"404":{"description":"No Robô with this id belongs to the account."},"502":{"description":"The Maestro service could not be reached (connection refused or reset, host unresolvable), or it answered in a way the gateway could not use, or it rejected the server-to-server credential — the last one is a deployment key mismatch, never the caller's own session. Nothing was executed; the call can be retried.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"504":{"description":"The Maestro service did not answer within the proxy timeout. The work may still be running on the service side, so retrying a write can duplicate its effect.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"503":{"description":"The Maestro area is not serving this installation: an operator turned it off, or no admin key was ever provisioned. Nothing was executed, and retrying will not help until the configuration changes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string"},"voice":{"type":"object","additionalProperties":true,"description":"Free-form object."}}},"example":{"text":"sample text","voice":{}}}}}}},"/api/v1/accounts/{account_id}/maestro/agents/{id}/voices":{"get":{"tags":["Maestro"],"operationId":"auto_get_api_v1_accounts_account_id_maestro_agents_id_voices","summary":"List the voices available to a Robô","description":"The voices the Robô's voice provider key can reach - the provider's stock catalogue plus the voices this operator cloned - so the form offers a picker instead of a pasted identifier. The key is resolved server-side and never returned. A missing key or a provider error answers `ok: false` with a hint rather than an error status, and the form falls back to manual entry.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The reachable voices, or the reason the catalogue could not be listed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","description":"True when the catalogue was listed.","example":true},"voices":{"type":"array","description":"Available voices. Empty when the catalogue could not be listed.","items":{"type":"object","properties":{"voice_id":{"type":"string","description":"Provider identifier to store on the Robô's voice configuration.","example":"21m00Tcm4TlvDq8ikWAM"},"name":{"type":"string","description":"Human name of the voice.","example":"Rachel"},"category":{"type":"string","description":"Provider-assigned grouping for the voice, as reported by the provider - stock catalogue entries and voices this operator created are distinguished here.","example":"premade"},"labels":{"type":"object","description":"Free-form provider tags describing the voice (accent, age, use case). Keys and values are whatever the provider assigns.","additionalProperties":{"type":"string"},"example":{"accent":"american","gender":"female"}},"preview_url":{"type":"string","description":"Provider-hosted sample the picker can play. Empty when none is offered.","example":"https://storage.googleapis.com/eleven-public-prod/premade/voices/preview.mp3"}}}},"error":{"type":["string","null"],"description":"Short failure reason. Null when the catalogue was listed.","example":null}}},"example":{"ok":true,"voices":[{"voice_id":"21m00Tcm4TlvDq8ikWAM","name":"Rachel","category":"premade","labels":{"accent":"american","gender":"female"},"preview_url":"https://storage.googleapis.com/eleven-public-prod/premade/voices/preview.mp3"}],"error":null}}}},"401":{"description":"Unauthorized"},"404":{"description":"No Robô with this id belongs to the account."},"502":{"description":"The Maestro service could not be reached (connection refused or reset, host unresolvable), or it answered in a way the gateway could not use, or it rejected the server-to-server credential — the last one is a deployment key mismatch, never the caller's own session. Nothing was executed; the call can be retried.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"504":{"description":"The Maestro service did not answer within the proxy timeout. The work may still be running on the service side, so retrying a write can duplicate its effect.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"503":{"description":"The Maestro area is not serving this installation: an operator turned it off, or no admin key was ever provisioned. Nothing was executed, and retrying will not help until the configuration changes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/maestro/agents/{id}/agent-bot-link":{"put":{"tags":["Maestro"],"operationId":"auto_put_api_v1_accounts_account_id_maestro_agents_id_agent_bot_link","summary":"Link a native AgentBot to a Maestro agent","description":"Creates the immutable one-to-one identity edge after both account-scoped records exist. The Maestro agent is validated before the short local lock is acquired. Repeating the same pair is idempotent; changing either side is never inferred from names and returns a conflict instead.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The pair already existed or was linked now. The credential-free native-bot projection includes `bot_config.maestro_agent_id` so the client can update its cache before showing success. Access tokens and webhook secrets are never returned by this identity endpoint.","content":{"application/json":{"schema":{"type":"object","required":["id","name","bot_type","bot_config","account_id","system_bot"],"additionalProperties":false,"properties":{"id":{"type":"integer","minimum":1},"name":{"type":"string"},"description":{"type":["string","null"]},"thumbnail":{"type":["string","null"]},"outgoing_url":{"type":["string","null"]},"bot_type":{"type":"string","enum":["webhook"]},"bot_config":{"type":"object","required":["maestro_agent_id"],"additionalProperties":true,"properties":{"maestro_agent_id":{"type":"integer","minimum":1}}},"receive_incoming_when_assigned":{"type":"boolean"},"receive_incoming_when_assigned_configurable":{"type":"boolean"},"account_id":{"type":"integer","minimum":1},"system_bot":{"type":"boolean"}}},"example":{"id":42,"name":"Atendente Acme","bot_type":"webhook","bot_config":{"maestro_agent_id":77},"account_id":1,"system_bot":false,"description":"A short description.","thumbnail":"sample thumbnail","outgoing_url":"https://example.com/resource","receive_incoming_when_assigned":true,"receive_incoming_when_assigned_configurable":true}}}},"401":{"description":"Unauthorized"},"404":{"description":"The native AgentBot or Maestro agent does not exist in the authenticated account. Records owned by another account produce the same response.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}},"example":{"error":"agent not found"}}}},"502":{"description":"The Maestro service could not be reached (connection refused or reset, host unresolvable), or it answered in a way the gateway could not use, or it rejected the server-to-server credential — the last one is a deployment key mismatch, never the caller's own session. Nothing was executed; the call can be retried.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"504":{"description":"The Maestro service did not answer within the proxy timeout. The work may still be running on the service side, so retrying a write can duplicate its effect.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"503":{"description":"The Maestro area is not serving this installation: an operator turned it off, or no admin key was ever provisioned. Nothing was executed, and retrying will not help until the configuration changes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"409":{"description":"The native bot or the Maestro agent is already linked to a different id.","content":{"application/json":{"schema":{"type":"object","required":["error","code","agent_bot_id","maestro_agent_id"],"properties":{"error":{"type":"string"},"code":{"type":"string","enum":["maestro_agent_bot_link_conflict"]},"agent_bot_id":{"type":"integer","minimum":1},"maestro_agent_id":{"type":"integer","minimum":1}}},"example":{"error":"maestro_agent_bot_link_conflict","code":"maestro_agent_bot_link_conflict","agent_bot_id":42,"maestro_agent_id":77}}}},"422":{"description":"The native AgentBot id or Maestro agent id is missing or is not a positive integer.","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"type":"string"},"code":{"type":"string","enum":["maestro_agent_bot_link_invalid"]},"agent_bot_id":{"type":["integer","null"]},"maestro_agent_id":{"type":["integer","null"]}}},"example":{"error":"maestro_agent_bot_link_invalid","code":"maestro_agent_bot_link_invalid","agent_bot_id":null,"maestro_agent_id":77}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["agent_bot_id"],"additionalProperties":false,"properties":{"agent_bot_id":{"type":"integer","minimum":1,"description":"Native AgentBot id from the authenticated account.","example":42}}},"example":{"agent_bot_id":42}}}}}},"/api/v1/accounts/{account_id}/maestro/agents/{id}/agent-bot-credential":{"put":{"tags":["Maestro"],"operationId":"auto_put_api_v1_accounts_account_id_maestro_agents_id_agent_bot_credential","summary":"Synchronize the linked AgentBot credential","description":"Re-pushes the linked native AgentBot secret and access token to the Maestro sidecar by immutable sidecar id. The identity pair must already exist. A sidecar outage returns a stable retryable error and never removes, replaces, or infers either side of the link.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"maestro_agent_bot_credential_sync_failed"},"code":{"type":"string","example":"maestro_agent_bot_credential_sync_failed"},"agent_bot_id":{"type":"integer"},"maestro_agent_id":{"type":"integer"}}},"example":{"error":"maestro_agent_bot_credential_sync_failed","code":"maestro_agent_bot_credential_sync_failed","agent_bot_id":1,"maestro_agent_id":1}}}},"401":{"description":"Unauthorized"},"404":{"description":"The Maestro agent does not belong to the authenticated account, or no native AgentBot is linked to this sidecar id.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}},"example":{"error":"Record not found"}}}},"502":{"description":"The durable pair remains linked, but the sidecar did not accept the credential projection. The same action can be retried safely.","content":{"application/json":{"schema":{"type":"object","required":["error","code","agent_bot_id","maestro_agent_id"],"properties":{"error":{"type":"string"},"code":{"type":"string","enum":["maestro_agent_bot_credential_sync_failed"]},"agent_bot_id":{"type":"integer","minimum":1},"maestro_agent_id":{"type":"integer","minimum":1}}},"example":{"error":"maestro_agent_bot_credential_sync_failed","code":"maestro_agent_bot_credential_sync_failed","agent_bot_id":42,"maestro_agent_id":77}}}},"504":{"description":"The Maestro service did not answer within the proxy timeout. The work may still be running on the service side, so retrying a write can duplicate its effect.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"503":{"description":"The Maestro area is not serving this installation: an operator turned it off, or no admin key was ever provisioned. Nothing was executed, and retrying will not help until the configuration changes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"204":{"description":"Credential projection synchronized; no secret or token is returned."},"422":{"description":"The Maestro agent id is not a positive integer.","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"type":"string"},"code":{"type":"string","enum":["maestro_agent_bot_link_invalid"]},"maestro_agent_id":{"type":["integer","null"]}}},"example":{"error":"maestro_agent_bot_link_invalid","code":"maestro_agent_bot_link_invalid","maestro_agent_id":null}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/maestro/agents/{id}":{"get":{"tags":["Maestro"],"operationId":"auto_get_api_v1_accounts_account_id_maestro_agents_id","summary":"Get one Maestro agent","description":"The Robô with its full configuration and inbox bindings. Secrets are never echoed: the key fields come back as booleans saying WHETHER a key is set, not what it is.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The Robô, with its configuration and bindings.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_agent"},"example":{"id":42,"account_id":7,"name":"Atendimento","enabled":true,"config":{"persona":"Você é a atendente virtual da Acme, cordial e objetiva.","instructions":"Sempre confirme o CPF antes de consultar um pedido.","default_model":"openai:gpt-5.4-mini-2026-03-17","fallback_models":["anthropic:claude-haiku-4-5-20251001"],"enabled_tools":["set_labels"],"autonomy_level":"autopilot","interaction_mode":"converse","search_config":{"enabled":true,"search_depth":"basic","max_results":5,"topic":"general","include_domains":["docs.example.com"],"exclude_domains":[]},"locale":"pt_BR","quiet_window_seconds":8,"max_window_seconds":40,"summary_threshold_tokens":3000,"standdown_on_assignment":true,"standdown_auto_resume":true,"standdown_ttl_seconds":86400,"paused_inbound_policy":"discard","paused_inbound_max_messages":10,"paused_inbound_max_age_seconds":3600,"handoff_team_id":3,"working_hours_policy":"ignore","out_of_office_message":"Nosso atendimento volta às 9h. Já registramos sua mensagem.","handoff_policy":{"target_status":"open","target_priority":"none","triggers":["falar com atendente"]},"guardrails":{"banned_topics":["assuntos jurídicos"],"blocked_phrases":["garantimos 100% de aprovação"],"max_output_chars":1200,"pii_policy":"off","require_handoff_conditions":["cliente pede cancelamento"]},"knowledge_base":{"enabled":true,"top_k":5,"use_shared":false},"database":{"enabled":false,"connection_secret":"ERP_DB_URL","read_only":true,"max_rows":200,"statement_timeout_seconds":15,"include_tables":["orders"],"description":"Pedidos e faturas do ERP.","instructions":"Sempre filtre por account_id."},"reactions":{"outbound":false,"understand_inbound":false},"media":{"audio":true,"vision":true,"documents":true},"close_on_complete":"off","verification_policy":"off","model_params":{"reasoning_effort":"low","temperature":0.4,"top_p":0.9,"max_output_tokens":512},"service_flow":{"enabled":false,"on_exit":"handoff","strict_tools":true,"steps":[{"key":"qualificacao","name":"Qualificação","goal":"Descobrir o segmento e o tamanho da empresa.","allowed_tools":["contact_update"],"exit":{"type":"tools_executed","tools":["contact_update"],"attributes":["segmento"],"max_turns":8},"next":"proposta"}]},"max_tool_iterations":8,"history_limit_messages":40,"tail_budget_tokens":1500,"hard_cap_tokens":6000,"chain_same_provider":"","delivery":{"quote_replies":true,"formatting":"auto"},"stt":{"provider":"groq","model":"groq:whisper-large-v3-turbo"},"embedding":{"provider":"openai","model":"text-embedding-3-small"},"voice":{"enabled":false,"mode":"off","with_text":false,"provider":"elevenlabs","model":"eleven_multilingual_v2","call_backend":"auto","call_model":"openai:gpt-realtime","voice_id":"21m00Tcm4TlvDq8ikWAM","openai_voice":"alloy","gemini_voice":"Kore","stability":0.5,"similarity_boost":0.75,"style":0,"use_speaker_boost":true,"speed":1,"instructions":"Fale de forma calma e acolhedora.","style_instructions":"Locução comercial, ritmo animado."},"image_gen":{"enabled":false,"provider":"openai","model":"gpt-image-1"},"video_gen":{"enabled":false,"provider":"openai","model":"sora-2"},"custom_tools":[{"name":"consultar_pedido","description":"Consulta o status de um pedido pelo número.","method":"GET","url":"https://api.acme.com/orders/{{order_id}}","sensitive":false,"extract":"data.status","body_type":"json","body_template":{"source":"maestro","order_id":"{{order_id}}"},"headers":{"X-Api-Version":"2026-01"},"query":{"include":"items"},"auth":{"type":"bearer","name":"X-Api-Key","token_secret":"ACME_API_TOKEN","username_secret":"ACME_USER","password_secret":"ACME_PASS"},"params":[{"name":"order_id","type":"string","description":"Número do pedido.","required":true,"location":"auto"}],"response_map":[{"label":"Status","path":"data.status"}],"pagination":{"type":"none","param":"page","items_path":"data","next_path":"meta.next","start":1,"max_pages":5,"size_param":"per_page","size":50}}],"mcp_servers":[{"name":"acme-erp","url":"https://mcp.acme.com/sse","transport":"streamable_http","timeout":30,"sensitive":false,"enabled_tools":["get_order"],"headers":{"X-Tenant":"acme"},"auth":{"type":"bearer","name":"X-Api-Key","token_secret":"ACME_MCP_TOKEN","username_secret":"ACME_USER","password_secret":"ACME_PASS"}}],"media_assets":[{"name":"catalogo_2026","description":"Catálogo completo em PDF.","url":"https://cdn.acme.com/catalogo.pdf","type":"file"}],"sub_agents":[{"agent_id":7,"name":"Vendas","slug":"vendas","description":"Perguntas sobre planos e preços.","enabled":true,"sensitive":false}],"secrets":{"ACME_API_TOKEN":"sk-live-xxxxxxxx"},"secret_keys":["ACME_API_TOKEN"],"provider_keys":{"openai":"sk-proj-xxxxxxxx"},"chatwoot_native_keys":{"openai":"sk-proj-xxxxxxxx"},"provider_keys_set":["openai"],"native_keys_set":["openai"],"use_global_fallback":true},"bindings":[{"id":9,"inbox_id":3}],"created_at":"2026-07-01T12:00:00Z","updated_at":"2026-07-27T14:03:00Z"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"502":{"description":"The Maestro service could not be reached (connection refused or reset, host unresolvable), or it answered in a way the gateway could not use, or it rejected the server-to-server credential — the last one is a deployment key mismatch, never the caller's own session. Nothing was executed; the call can be retried.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"504":{"description":"The Maestro service did not answer within the proxy timeout. The work may still be running on the service side, so retrying a write can duplicate its effect.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"503":{"description":"The Maestro area is not serving this installation: an operator turned it off, or no admin key was ever provisioned. Nothing was executed, and retrying will not help until the configuration changes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]},"patch":{"tags":["Maestro"],"operationId":"auto_patch_api_v1_accounts_account_id_maestro_agents_id","summary":"Update a Maestro agent","description":"Updates an existing Maestro agent. Accepts the same payload as create; omitted top-level fields are left untouched. A nested `config` patch preserves omitted stored fields. For the human-takeover policy specifically, the platform also carries the stored `standdown_on_assignment`, `standdown_auto_resume` and `standdown_ttl_seconds` through a partial payload; a legacy null/missing value resolves to the shipped policy (true, true, 86400 seconds). Only the documented fields reach the sidecar.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The updated Robô.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_agent"},"example":{"id":42,"account_id":7,"name":"Atendimento","enabled":true,"config":{"persona":"Você é a atendente virtual da Acme, cordial e objetiva.","instructions":"Sempre confirme o CPF antes de consultar um pedido.","default_model":"openai:gpt-5.4-mini-2026-03-17","fallback_models":["anthropic:claude-haiku-4-5-20251001"],"enabled_tools":["set_labels"],"autonomy_level":"autopilot","interaction_mode":"converse","search_config":{"enabled":true,"search_depth":"basic","max_results":5,"topic":"general","include_domains":["docs.example.com"],"exclude_domains":[]},"locale":"pt_BR","quiet_window_seconds":8,"max_window_seconds":40,"summary_threshold_tokens":3000,"standdown_on_assignment":true,"standdown_auto_resume":true,"standdown_ttl_seconds":86400,"paused_inbound_policy":"discard","paused_inbound_max_messages":10,"paused_inbound_max_age_seconds":3600,"handoff_team_id":3,"working_hours_policy":"ignore","out_of_office_message":"Nosso atendimento volta às 9h. Já registramos sua mensagem.","handoff_policy":{"target_status":"open","target_priority":"none","triggers":["falar com atendente"]},"guardrails":{"banned_topics":["assuntos jurídicos"],"blocked_phrases":["garantimos 100% de aprovação"],"max_output_chars":1200,"pii_policy":"off","require_handoff_conditions":["cliente pede cancelamento"]},"knowledge_base":{"enabled":true,"top_k":5,"use_shared":false},"database":{"enabled":false,"connection_secret":"ERP_DB_URL","read_only":true,"max_rows":200,"statement_timeout_seconds":15,"include_tables":["orders"],"description":"Pedidos e faturas do ERP.","instructions":"Sempre filtre por account_id."},"reactions":{"outbound":false,"understand_inbound":false},"media":{"audio":true,"vision":true,"documents":true},"close_on_complete":"off","verification_policy":"off","model_params":{"reasoning_effort":"low","temperature":0.4,"top_p":0.9,"max_output_tokens":512},"service_flow":{"enabled":false,"on_exit":"handoff","strict_tools":true,"steps":[{"key":"qualificacao","name":"Qualificação","goal":"Descobrir o segmento e o tamanho da empresa.","allowed_tools":["contact_update"],"exit":{"type":"tools_executed","tools":["contact_update"],"attributes":["segmento"],"max_turns":8},"next":"proposta"}]},"max_tool_iterations":8,"history_limit_messages":40,"tail_budget_tokens":1500,"hard_cap_tokens":6000,"chain_same_provider":"","delivery":{"quote_replies":true,"formatting":"auto"},"stt":{"provider":"groq","model":"groq:whisper-large-v3-turbo"},"embedding":{"provider":"openai","model":"text-embedding-3-small"},"voice":{"enabled":false,"mode":"off","with_text":false,"provider":"elevenlabs","model":"eleven_multilingual_v2","call_backend":"auto","call_model":"openai:gpt-realtime","voice_id":"21m00Tcm4TlvDq8ikWAM","openai_voice":"alloy","gemini_voice":"Kore","stability":0.5,"similarity_boost":0.75,"style":0,"use_speaker_boost":true,"speed":1,"instructions":"Fale de forma calma e acolhedora.","style_instructions":"Locução comercial, ritmo animado."},"image_gen":{"enabled":false,"provider":"openai","model":"gpt-image-1"},"video_gen":{"enabled":false,"provider":"openai","model":"sora-2"},"custom_tools":[{"name":"consultar_pedido","description":"Consulta o status de um pedido pelo número.","method":"GET","url":"https://api.acme.com/orders/{{order_id}}","sensitive":false,"extract":"data.status","body_type":"json","body_template":{"source":"maestro","order_id":"{{order_id}}"},"headers":{"X-Api-Version":"2026-01"},"query":{"include":"items"},"auth":{"type":"bearer","name":"X-Api-Key","token_secret":"ACME_API_TOKEN","username_secret":"ACME_USER","password_secret":"ACME_PASS"},"params":[{"name":"order_id","type":"string","description":"Número do pedido.","required":true,"location":"auto"}],"response_map":[{"label":"Status","path":"data.status"}],"pagination":{"type":"none","param":"page","items_path":"data","next_path":"meta.next","start":1,"max_pages":5,"size_param":"per_page","size":50}}],"mcp_servers":[{"name":"acme-erp","url":"https://mcp.acme.com/sse","transport":"streamable_http","timeout":30,"sensitive":false,"enabled_tools":["get_order"],"headers":{"X-Tenant":"acme"},"auth":{"type":"bearer","name":"X-Api-Key","token_secret":"ACME_MCP_TOKEN","username_secret":"ACME_USER","password_secret":"ACME_PASS"}}],"media_assets":[{"name":"catalogo_2026","description":"Catálogo completo em PDF.","url":"https://cdn.acme.com/catalogo.pdf","type":"file"}],"sub_agents":[{"agent_id":7,"name":"Vendas","slug":"vendas","description":"Perguntas sobre planos e preços.","enabled":true,"sensitive":false}],"secrets":{"ACME_API_TOKEN":"sk-live-xxxxxxxx"},"secret_keys":["ACME_API_TOKEN"],"provider_keys":{"openai":"sk-proj-xxxxxxxx"},"chatwoot_native_keys":{"openai":"sk-proj-xxxxxxxx"},"provider_keys_set":["openai"],"native_keys_set":["openai"],"use_global_fallback":true},"bindings":[{"id":9,"inbox_id":3}],"created_at":"2026-07-01T12:00:00Z","updated_at":"2026-07-27T14:03:00Z"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"502":{"description":"The Maestro service could not be reached (connection refused or reset, host unresolvable), or it answered in a way the gateway could not use, or it rejected the server-to-server credential — the last one is a deployment key mismatch, never the caller's own session. Nothing was executed; the call can be retried.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"504":{"description":"The Maestro service did not answer within the proxy timeout. The work may still be running on the service side, so retrying a write can duplicate its effect.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"503":{"description":"The Maestro area is not serving this installation: an operator turned it off, or no admin key was ever provisioned. Nothing was executed, and retrying will not help until the configuration changes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"409":{"description":"An inbox in the submitted replacement set already belongs to another agent in this account. Metadata, configuration and bindings were all rolled back.","content":{"application/json":{"schema":{"type":"object","required":["detail"],"properties":{"detail":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["maestro_binding_conflict"]}}}}},"example":{"detail":{"code":"maestro_binding_conflict"}}}}},"422":{"description":"The configuration was refused before anything was stored — an unbuildable model chain, or an embedding model whose vector width is not this installation's. The body carries a `code` and the facts the UI needs (which providers, which two widths) so the sentence is written in the reader's language, never composed on the server."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"New agent name.","example":"Atendente Acme"},"enabled":{"type":"boolean","description":"Turn the agent on or off without deleting it.","example":true},"bindings":{"type":"array","description":"Complete replacement set for inbox bindings. Metadata, config and this set are committed atomically; omit the field to preserve the existing bindings.","items":{"type":"object","properties":{"inbox_id":{"type":"integer","description":"Id of the inbox the agent should answer on.","example":12}}}},"config":{"$ref":"#/components/schemas/maestro_agent_config"}}},"example":{"name":"Atendente Acme","enabled":true,"bindings":[{"inbox_id":12}],"config":{"persona":"Você é a atendente virtual da Acme, cordial e objetiva.","instructions":"Sempre confirme o CPF antes de consultar um pedido.","default_model":"openai:gpt-5.4-mini-2026-03-17","fallback_models":["anthropic:claude-haiku-4-5-20251001"],"enabled_tools":["set_labels"],"autonomy_level":"autopilot","interaction_mode":"converse","search_config":{"enabled":true,"search_depth":"basic","max_results":5,"topic":"general","include_domains":["docs.example.com"],"exclude_domains":[]},"locale":"pt_BR","quiet_window_seconds":8,"max_window_seconds":40,"summary_threshold_tokens":3000,"standdown_on_assignment":true,"standdown_auto_resume":true,"standdown_ttl_seconds":86400,"paused_inbound_policy":"discard","paused_inbound_max_messages":10,"paused_inbound_max_age_seconds":3600,"handoff_team_id":3,"working_hours_policy":"ignore","out_of_office_message":"Nosso atendimento volta às 9h. Já registramos sua mensagem.","handoff_policy":{"target_status":"open","target_priority":"none","triggers":["falar com atendente"]},"guardrails":{"banned_topics":["assuntos jurídicos"],"blocked_phrases":["garantimos 100% de aprovação"],"max_output_chars":1200,"pii_policy":"off","require_handoff_conditions":["cliente pede cancelamento"]},"knowledge_base":{"enabled":true,"top_k":5,"use_shared":false},"database":{"enabled":false,"connection_secret":"ERP_DB_URL","read_only":true,"max_rows":200,"statement_timeout_seconds":15,"include_tables":["orders"],"description":"Pedidos e faturas do ERP.","instructions":"Sempre filtre por account_id."},"reactions":{"outbound":false,"understand_inbound":false},"media":{"audio":true,"vision":true,"documents":true},"close_on_complete":"off","verification_policy":"off","model_params":{"reasoning_effort":"low","temperature":0.4,"top_p":0.9,"max_output_tokens":512},"service_flow":{"enabled":false,"on_exit":"handoff","strict_tools":true,"steps":[{"key":"qualificacao","name":"Qualificação","goal":"Descobrir o segmento e o tamanho da empresa.","allowed_tools":["contact_update"],"exit":{"type":"tools_executed","tools":["contact_update"],"attributes":["segmento"],"max_turns":8},"next":"proposta"}]},"max_tool_iterations":8,"history_limit_messages":40,"tail_budget_tokens":1500,"hard_cap_tokens":6000,"chain_same_provider":"","delivery":{"quote_replies":true,"formatting":"auto"},"stt":{"provider":"groq","model":"groq:whisper-large-v3-turbo"},"embedding":{"provider":"openai","model":"text-embedding-3-small"},"voice":{"enabled":false,"mode":"off","with_text":false,"provider":"elevenlabs","model":"eleven_multilingual_v2","call_backend":"auto","call_model":"openai:gpt-realtime","voice_id":"21m00Tcm4TlvDq8ikWAM","openai_voice":"alloy","gemini_voice":"Kore","stability":0.5,"similarity_boost":0.75,"style":0,"use_speaker_boost":true,"speed":1,"instructions":"Fale de forma calma e acolhedora.","style_instructions":"Locução comercial, ritmo animado."},"image_gen":{"enabled":false,"provider":"openai","model":"gpt-image-1"},"video_gen":{"enabled":false,"provider":"openai","model":"sora-2"},"custom_tools":[{"name":"consultar_pedido","description":"Consulta o status de um pedido pelo número.","method":"GET","url":"https://api.acme.com/orders/{{order_id}}","sensitive":false,"extract":"data.status","body_type":"json","body_template":{"source":"maestro","order_id":"{{order_id}}"},"headers":{"X-Api-Version":"2026-01"},"query":{"include":"items"},"auth":{"type":"bearer","name":"X-Api-Key","token_secret":"ACME_API_TOKEN","username_secret":"ACME_USER","password_secret":"ACME_PASS"},"params":[{"name":"order_id","type":"string","description":"Número do pedido.","required":true,"location":"auto"}],"response_map":[{"label":"Status","path":"data.status"}],"pagination":{"type":"none","param":"page","items_path":"data","next_path":"meta.next","start":1,"max_pages":5,"size_param":"per_page","size":50}}],"mcp_servers":[{"name":"acme-erp","url":"https://mcp.acme.com/sse","transport":"streamable_http","timeout":30,"sensitive":false,"enabled_tools":["get_order"],"headers":{"X-Tenant":"acme"},"auth":{"type":"bearer","name":"X-Api-Key","token_secret":"ACME_MCP_TOKEN","username_secret":"ACME_USER","password_secret":"ACME_PASS"}}],"media_assets":[{"name":"catalogo_2026","description":"Catálogo completo em PDF.","url":"https://cdn.acme.com/catalogo.pdf","type":"file"}],"sub_agents":[{"agent_id":7,"name":"Vendas","slug":"vendas","description":"Perguntas sobre planos e preços.","enabled":true,"sensitive":false}],"secrets":{"ACME_API_TOKEN":"sk-live-xxxxxxxx"},"secret_keys":["ACME_API_TOKEN"],"provider_keys":{"openai":"sk-proj-xxxxxxxx"},"chatwoot_native_keys":{"openai":"sk-proj-xxxxxxxx"},"provider_keys_set":["openai"],"native_keys_set":["openai"],"use_global_fallback":true}}}}}},"delete":{"tags":["Maestro"],"operationId":"auto_delete_api_v1_accounts_account_id_maestro_agents_id","summary":"Destroy agent maestro","description":"Performs the destroy agent operation on the targeted maestro resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"502":{"description":"The Maestro service could not be reached (connection refused or reset, host unresolvable), or it answered in a way the gateway could not use, or it rejected the server-to-server credential — the last one is a deployment key mismatch, never the caller's own session. Nothing was executed; the call can be retried.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"504":{"description":"The Maestro service did not answer within the proxy timeout. The work may still be running on the service side, so retrying a write can duplicate its effect.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"503":{"description":"The Maestro area is not serving this installation: an operator turned it off, or no admin key was ever provisioned. Nothing was executed, and retrying will not help until the configuration changes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"204":{"description":"The Robô was deleted, together with its bindings and configuration. No body."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/maestro/agents/{id}/config":{"put":{"tags":["Maestro"],"operationId":"auto_put_api_v1_accounts_account_id_maestro_agents_id_config","summary":"Replace a Maestro agent configuration","description":"Replaces the agent's configuration. Unlike agent create/update, the configuration is sent at the TOP level of the body rather than nested under `config`. Send the full object as returned by the agent read endpoint with your changes applied - the sidecar stores what it receives, so an omitted field normally falls back to its default rather than keeping the previously stored value. The three human-takeover fields are protected from that replacement hazard: when omitted/null, the platform preserves the stored `standdown_on_assignment`, `standdown_auto_resume` and `standdown_ttl_seconds`; a legacy null/missing stored value resolves to true, true and 86400 seconds. WRITE-ONLY credential fields (secrets, provider_keys, chatwoot_native_keys) are never returned by a read, so include them only when you are changing them.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The Robô, with the configuration as stored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_agent"},"example":{"id":42,"account_id":7,"name":"Atendimento","enabled":true,"config":{"persona":"Você é a atendente virtual da Acme, cordial e objetiva.","instructions":"Sempre confirme o CPF antes de consultar um pedido.","default_model":"openai:gpt-5.4-mini-2026-03-17","fallback_models":["anthropic:claude-haiku-4-5-20251001"],"enabled_tools":["set_labels"],"autonomy_level":"autopilot","interaction_mode":"converse","search_config":{"enabled":true,"search_depth":"basic","max_results":5,"topic":"general","include_domains":["docs.example.com"],"exclude_domains":[]},"locale":"pt_BR","quiet_window_seconds":8,"max_window_seconds":40,"summary_threshold_tokens":3000,"standdown_on_assignment":true,"standdown_auto_resume":true,"standdown_ttl_seconds":86400,"paused_inbound_policy":"discard","paused_inbound_max_messages":10,"paused_inbound_max_age_seconds":3600,"handoff_team_id":3,"working_hours_policy":"ignore","out_of_office_message":"Nosso atendimento volta às 9h. Já registramos sua mensagem.","handoff_policy":{"target_status":"open","target_priority":"none","triggers":["falar com atendente"]},"guardrails":{"banned_topics":["assuntos jurídicos"],"blocked_phrases":["garantimos 100% de aprovação"],"max_output_chars":1200,"pii_policy":"off","require_handoff_conditions":["cliente pede cancelamento"]},"knowledge_base":{"enabled":true,"top_k":5,"use_shared":false},"database":{"enabled":false,"connection_secret":"ERP_DB_URL","read_only":true,"max_rows":200,"statement_timeout_seconds":15,"include_tables":["orders"],"description":"Pedidos e faturas do ERP.","instructions":"Sempre filtre por account_id."},"reactions":{"outbound":false,"understand_inbound":false},"media":{"audio":true,"vision":true,"documents":true},"close_on_complete":"off","verification_policy":"off","model_params":{"reasoning_effort":"low","temperature":0.4,"top_p":0.9,"max_output_tokens":512},"service_flow":{"enabled":false,"on_exit":"handoff","strict_tools":true,"steps":[{"key":"qualificacao","name":"Qualificação","goal":"Descobrir o segmento e o tamanho da empresa.","allowed_tools":["contact_update"],"exit":{"type":"tools_executed","tools":["contact_update"],"attributes":["segmento"],"max_turns":8},"next":"proposta"}]},"max_tool_iterations":8,"history_limit_messages":40,"tail_budget_tokens":1500,"hard_cap_tokens":6000,"chain_same_provider":"","delivery":{"quote_replies":true,"formatting":"auto"},"stt":{"provider":"groq","model":"groq:whisper-large-v3-turbo"},"embedding":{"provider":"openai","model":"text-embedding-3-small"},"voice":{"enabled":false,"mode":"off","with_text":false,"provider":"elevenlabs","model":"eleven_multilingual_v2","call_backend":"auto","call_model":"openai:gpt-realtime","voice_id":"21m00Tcm4TlvDq8ikWAM","openai_voice":"alloy","gemini_voice":"Kore","stability":0.5,"similarity_boost":0.75,"style":0,"use_speaker_boost":true,"speed":1,"instructions":"Fale de forma calma e acolhedora.","style_instructions":"Locução comercial, ritmo animado."},"image_gen":{"enabled":false,"provider":"openai","model":"gpt-image-1"},"video_gen":{"enabled":false,"provider":"openai","model":"sora-2"},"custom_tools":[{"name":"consultar_pedido","description":"Consulta o status de um pedido pelo número.","method":"GET","url":"https://api.acme.com/orders/{{order_id}}","sensitive":false,"extract":"data.status","body_type":"json","body_template":{"source":"maestro","order_id":"{{order_id}}"},"headers":{"X-Api-Version":"2026-01"},"query":{"include":"items"},"auth":{"type":"bearer","name":"X-Api-Key","token_secret":"ACME_API_TOKEN","username_secret":"ACME_USER","password_secret":"ACME_PASS"},"params":[{"name":"order_id","type":"string","description":"Número do pedido.","required":true,"location":"auto"}],"response_map":[{"label":"Status","path":"data.status"}],"pagination":{"type":"none","param":"page","items_path":"data","next_path":"meta.next","start":1,"max_pages":5,"size_param":"per_page","size":50}}],"mcp_servers":[{"name":"acme-erp","url":"https://mcp.acme.com/sse","transport":"streamable_http","timeout":30,"sensitive":false,"enabled_tools":["get_order"],"headers":{"X-Tenant":"acme"},"auth":{"type":"bearer","name":"X-Api-Key","token_secret":"ACME_MCP_TOKEN","username_secret":"ACME_USER","password_secret":"ACME_PASS"}}],"media_assets":[{"name":"catalogo_2026","description":"Catálogo completo em PDF.","url":"https://cdn.acme.com/catalogo.pdf","type":"file"}],"sub_agents":[{"agent_id":7,"name":"Vendas","slug":"vendas","description":"Perguntas sobre planos e preços.","enabled":true,"sensitive":false}],"secrets":{"ACME_API_TOKEN":"sk-live-xxxxxxxx"},"secret_keys":["ACME_API_TOKEN"],"provider_keys":{"openai":"sk-proj-xxxxxxxx"},"chatwoot_native_keys":{"openai":"sk-proj-xxxxxxxx"},"provider_keys_set":["openai"],"native_keys_set":["openai"],"use_global_fallback":true},"bindings":[{"id":9,"inbox_id":3}],"created_at":"2026-07-01T12:00:00Z","updated_at":"2026-07-27T14:03:00Z"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"502":{"description":"The Maestro service could not be reached (connection refused or reset, host unresolvable), or it answered in a way the gateway could not use, or it rejected the server-to-server credential — the last one is a deployment key mismatch, never the caller's own session. Nothing was executed; the call can be retried.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"504":{"description":"The Maestro service did not answer within the proxy timeout. The work may still be running on the service side, so retrying a write can duplicate its effect.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"503":{"description":"The Maestro area is not serving this installation: an operator turned it off, or no admin key was ever provisioned. Nothing was executed, and retrying will not help until the configuration changes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"422":{"description":"The configuration was refused before anything was stored — an unbuildable model chain, or an embedding model whose vector width is not this installation's. The body carries a `code` and the facts the UI needs (which providers, which two widths) so the sentence is written in the reader's language, never composed on the server."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_agent_config"},"example":{"persona":"Você é a atendente virtual da Acme, cordial e objetiva.","instructions":"Sempre confirme o CPF antes de consultar um pedido.","default_model":"openai:gpt-5.4-mini-2026-03-17","fallback_models":["anthropic:claude-haiku-4-5-20251001"],"enabled_tools":["set_labels"],"autonomy_level":"autopilot","interaction_mode":"converse","search_config":{"enabled":true,"search_depth":"basic","max_results":5,"topic":"general","include_domains":["docs.example.com"],"exclude_domains":[]},"locale":"pt_BR","quiet_window_seconds":8,"max_window_seconds":40,"summary_threshold_tokens":3000,"standdown_on_assignment":true,"standdown_auto_resume":true,"standdown_ttl_seconds":86400,"paused_inbound_policy":"discard","paused_inbound_max_messages":10,"paused_inbound_max_age_seconds":3600,"handoff_team_id":3,"working_hours_policy":"ignore","out_of_office_message":"Nosso atendimento volta às 9h. Já registramos sua mensagem.","handoff_policy":{"target_status":"open","target_priority":"none","triggers":["falar com atendente"]},"guardrails":{"banned_topics":["assuntos jurídicos"],"blocked_phrases":["garantimos 100% de aprovação"],"max_output_chars":1200,"pii_policy":"off","require_handoff_conditions":["cliente pede cancelamento"]},"knowledge_base":{"enabled":true,"top_k":5,"use_shared":false},"database":{"enabled":false,"connection_secret":"ERP_DB_URL","read_only":true,"max_rows":200,"statement_timeout_seconds":15,"include_tables":["orders"],"description":"Pedidos e faturas do ERP.","instructions":"Sempre filtre por account_id."},"reactions":{"outbound":false,"understand_inbound":false},"media":{"audio":true,"vision":true,"documents":true},"close_on_complete":"off","verification_policy":"off","model_params":{"reasoning_effort":"low","temperature":0.4,"top_p":0.9,"max_output_tokens":512},"service_flow":{"enabled":false,"on_exit":"handoff","strict_tools":true,"steps":[{"key":"qualificacao","name":"Qualificação","goal":"Descobrir o segmento e o tamanho da empresa.","allowed_tools":["contact_update"],"exit":{"type":"tools_executed","tools":["contact_update"],"attributes":["segmento"],"max_turns":8},"next":"proposta"}]},"max_tool_iterations":8,"history_limit_messages":40,"tail_budget_tokens":1500,"hard_cap_tokens":6000,"chain_same_provider":"","delivery":{"quote_replies":true,"formatting":"auto"},"stt":{"provider":"groq","model":"groq:whisper-large-v3-turbo"},"embedding":{"provider":"openai","model":"text-embedding-3-small"},"voice":{"enabled":false,"mode":"off","with_text":false,"provider":"elevenlabs","model":"eleven_multilingual_v2","call_backend":"auto","call_model":"openai:gpt-realtime","voice_id":"21m00Tcm4TlvDq8ikWAM","openai_voice":"alloy","gemini_voice":"Kore","stability":0.5,"similarity_boost":0.75,"style":0,"use_speaker_boost":true,"speed":1,"instructions":"Fale de forma calma e acolhedora.","style_instructions":"Locução comercial, ritmo animado."},"image_gen":{"enabled":false,"provider":"openai","model":"gpt-image-1"},"video_gen":{"enabled":false,"provider":"openai","model":"sora-2"},"custom_tools":[{"name":"consultar_pedido","description":"Consulta o status de um pedido pelo número.","method":"GET","url":"https://api.acme.com/orders/{{order_id}}","sensitive":false,"extract":"data.status","body_type":"json","body_template":{"source":"maestro","order_id":"{{order_id}}"},"headers":{"X-Api-Version":"2026-01"},"query":{"include":"items"},"auth":{"type":"bearer","name":"X-Api-Key","token_secret":"ACME_API_TOKEN","username_secret":"ACME_USER","password_secret":"ACME_PASS"},"params":[{"name":"order_id","type":"string","description":"Número do pedido.","required":true,"location":"auto"}],"response_map":[{"label":"Status","path":"data.status"}],"pagination":{"type":"none","param":"page","items_path":"data","next_path":"meta.next","start":1,"max_pages":5,"size_param":"per_page","size":50}}],"mcp_servers":[{"name":"acme-erp","url":"https://mcp.acme.com/sse","transport":"streamable_http","timeout":30,"sensitive":false,"enabled_tools":["get_order"],"headers":{"X-Tenant":"acme"},"auth":{"type":"bearer","name":"X-Api-Key","token_secret":"ACME_MCP_TOKEN","username_secret":"ACME_USER","password_secret":"ACME_PASS"}}],"media_assets":[{"name":"catalogo_2026","description":"Catálogo completo em PDF.","url":"https://cdn.acme.com/catalogo.pdf","type":"file"}],"sub_agents":[{"agent_id":7,"name":"Vendas","slug":"vendas","description":"Perguntas sobre planos e preços.","enabled":true,"sensitive":false}],"secrets":{"ACME_API_TOKEN":"sk-live-xxxxxxxx"},"secret_keys":["ACME_API_TOKEN"],"provider_keys":{"openai":"sk-proj-xxxxxxxx"},"chatwoot_native_keys":{"openai":"sk-proj-xxxxxxxx"},"provider_keys_set":["openai"],"native_keys_set":["openai"],"use_global_fallback":true}}}}}},"/api/v1/accounts/{account_id}/maestro/agents/{id}/bindings":{"post":{"tags":["Maestro"],"operationId":"auto_post_api_v1_accounts_account_id_maestro_agents_id_bindings","summary":"Bind a Robô to an inbox","description":"Links the Robô to an inbox so it answers there. Sending no inbox creates a collective binding - the Robô answers on every inbox of the account that no other Robô claims. An inbox belongs to at most one Robô per account. Answers with the Robô, its `bindings` including the new link.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The Robô, with the new binding included.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_agent"},"example":{"id":42,"account_id":7,"name":"Atendimento","enabled":true,"config":{"persona":"Você é a atendente virtual da Acme, cordial e objetiva.","instructions":"Sempre confirme o CPF antes de consultar um pedido.","default_model":"openai:gpt-5.4-mini-2026-03-17","fallback_models":["anthropic:claude-haiku-4-5-20251001"],"enabled_tools":["set_labels"],"autonomy_level":"autopilot","interaction_mode":"converse","search_config":{"enabled":true,"search_depth":"basic","max_results":5,"topic":"general","include_domains":["docs.example.com"],"exclude_domains":[]},"locale":"pt_BR","quiet_window_seconds":8,"max_window_seconds":40,"summary_threshold_tokens":3000,"standdown_on_assignment":true,"standdown_auto_resume":true,"standdown_ttl_seconds":86400,"paused_inbound_policy":"discard","paused_inbound_max_messages":10,"paused_inbound_max_age_seconds":3600,"handoff_team_id":3,"working_hours_policy":"ignore","out_of_office_message":"Nosso atendimento volta às 9h. Já registramos sua mensagem.","handoff_policy":{"target_status":"open","target_priority":"none","triggers":["falar com atendente"]},"guardrails":{"banned_topics":["assuntos jurídicos"],"blocked_phrases":["garantimos 100% de aprovação"],"max_output_chars":1200,"pii_policy":"off","require_handoff_conditions":["cliente pede cancelamento"]},"knowledge_base":{"enabled":true,"top_k":5,"use_shared":false},"database":{"enabled":false,"connection_secret":"ERP_DB_URL","read_only":true,"max_rows":200,"statement_timeout_seconds":15,"include_tables":["orders"],"description":"Pedidos e faturas do ERP.","instructions":"Sempre filtre por account_id."},"reactions":{"outbound":false,"understand_inbound":false},"media":{"audio":true,"vision":true,"documents":true},"close_on_complete":"off","verification_policy":"off","model_params":{"reasoning_effort":"low","temperature":0.4,"top_p":0.9,"max_output_tokens":512},"service_flow":{"enabled":false,"on_exit":"handoff","strict_tools":true,"steps":[{"key":"qualificacao","name":"Qualificação","goal":"Descobrir o segmento e o tamanho da empresa.","allowed_tools":["contact_update"],"exit":{"type":"tools_executed","tools":["contact_update"],"attributes":["segmento"],"max_turns":8},"next":"proposta"}]},"max_tool_iterations":8,"history_limit_messages":40,"tail_budget_tokens":1500,"hard_cap_tokens":6000,"chain_same_provider":"","delivery":{"quote_replies":true,"formatting":"auto"},"stt":{"provider":"groq","model":"groq:whisper-large-v3-turbo"},"embedding":{"provider":"openai","model":"text-embedding-3-small"},"voice":{"enabled":false,"mode":"off","with_text":false,"provider":"elevenlabs","model":"eleven_multilingual_v2","call_backend":"auto","call_model":"openai:gpt-realtime","voice_id":"21m00Tcm4TlvDq8ikWAM","openai_voice":"alloy","gemini_voice":"Kore","stability":0.5,"similarity_boost":0.75,"style":0,"use_speaker_boost":true,"speed":1,"instructions":"Fale de forma calma e acolhedora.","style_instructions":"Locução comercial, ritmo animado."},"image_gen":{"enabled":false,"provider":"openai","model":"gpt-image-1"},"video_gen":{"enabled":false,"provider":"openai","model":"sora-2"},"custom_tools":[{"name":"consultar_pedido","description":"Consulta o status de um pedido pelo número.","method":"GET","url":"https://api.acme.com/orders/{{order_id}}","sensitive":false,"extract":"data.status","body_type":"json","body_template":{"source":"maestro","order_id":"{{order_id}}"},"headers":{"X-Api-Version":"2026-01"},"query":{"include":"items"},"auth":{"type":"bearer","name":"X-Api-Key","token_secret":"ACME_API_TOKEN","username_secret":"ACME_USER","password_secret":"ACME_PASS"},"params":[{"name":"order_id","type":"string","description":"Número do pedido.","required":true,"location":"auto"}],"response_map":[{"label":"Status","path":"data.status"}],"pagination":{"type":"none","param":"page","items_path":"data","next_path":"meta.next","start":1,"max_pages":5,"size_param":"per_page","size":50}}],"mcp_servers":[{"name":"acme-erp","url":"https://mcp.acme.com/sse","transport":"streamable_http","timeout":30,"sensitive":false,"enabled_tools":["get_order"],"headers":{"X-Tenant":"acme"},"auth":{"type":"bearer","name":"X-Api-Key","token_secret":"ACME_MCP_TOKEN","username_secret":"ACME_USER","password_secret":"ACME_PASS"}}],"media_assets":[{"name":"catalogo_2026","description":"Catálogo completo em PDF.","url":"https://cdn.acme.com/catalogo.pdf","type":"file"}],"sub_agents":[{"agent_id":7,"name":"Vendas","slug":"vendas","description":"Perguntas sobre planos e preços.","enabled":true,"sensitive":false}],"secrets":{"ACME_API_TOKEN":"sk-live-xxxxxxxx"},"secret_keys":["ACME_API_TOKEN"],"provider_keys":{"openai":"sk-proj-xxxxxxxx"},"chatwoot_native_keys":{"openai":"sk-proj-xxxxxxxx"},"provider_keys_set":["openai"],"native_keys_set":["openai"],"use_global_fallback":true},"bindings":[{"id":9,"inbox_id":3}],"created_at":"2026-07-01T12:00:00Z","updated_at":"2026-07-27T14:03:00Z"}}}},"401":{"description":"Unauthorized"},"404":{"description":"No Robô with this id belongs to the account."},"502":{"description":"The Maestro service could not be reached (connection refused or reset, host unresolvable), or it answered in a way the gateway could not use, or it rejected the server-to-server credential — the last one is a deployment key mismatch, never the caller's own session. Nothing was executed; the call can be retried.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"504":{"description":"The Maestro service did not answer within the proxy timeout. The work may still be running on the service side, so retrying a write can duplicate its effect.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"503":{"description":"The Maestro area is not serving this installation: an operator turned it off, or no admin key was ever provisioned. Nothing was executed, and retrying will not help until the configuration changes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"201":{"description":"The Robô, with the new binding included.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_agent"},"example":{"id":42,"account_id":7,"name":"Atendimento","enabled":true,"config":{"persona":"Você é a atendente virtual da Acme, cordial e objetiva.","instructions":"Sempre confirme o CPF antes de consultar um pedido.","default_model":"openai:gpt-5.4-mini-2026-03-17","fallback_models":["anthropic:claude-haiku-4-5-20251001"],"enabled_tools":["set_labels"],"autonomy_level":"autopilot","interaction_mode":"converse","search_config":{"enabled":true,"search_depth":"basic","max_results":5,"topic":"general","include_domains":["docs.example.com"],"exclude_domains":[]},"locale":"pt_BR","quiet_window_seconds":8,"max_window_seconds":40,"summary_threshold_tokens":3000,"standdown_on_assignment":true,"standdown_auto_resume":true,"standdown_ttl_seconds":86400,"paused_inbound_policy":"discard","paused_inbound_max_messages":10,"paused_inbound_max_age_seconds":3600,"handoff_team_id":3,"working_hours_policy":"ignore","out_of_office_message":"Nosso atendimento volta às 9h. Já registramos sua mensagem.","handoff_policy":{"target_status":"open","target_priority":"none","triggers":["falar com atendente"]},"guardrails":{"banned_topics":["assuntos jurídicos"],"blocked_phrases":["garantimos 100% de aprovação"],"max_output_chars":1200,"pii_policy":"off","require_handoff_conditions":["cliente pede cancelamento"]},"knowledge_base":{"enabled":true,"top_k":5,"use_shared":false},"database":{"enabled":false,"connection_secret":"ERP_DB_URL","read_only":true,"max_rows":200,"statement_timeout_seconds":15,"include_tables":["orders"],"description":"Pedidos e faturas do ERP.","instructions":"Sempre filtre por account_id."},"reactions":{"outbound":false,"understand_inbound":false},"media":{"audio":true,"vision":true,"documents":true},"close_on_complete":"off","verification_policy":"off","model_params":{"reasoning_effort":"low","temperature":0.4,"top_p":0.9,"max_output_tokens":512},"service_flow":{"enabled":false,"on_exit":"handoff","strict_tools":true,"steps":[{"key":"qualificacao","name":"Qualificação","goal":"Descobrir o segmento e o tamanho da empresa.","allowed_tools":["contact_update"],"exit":{"type":"tools_executed","tools":["contact_update"],"attributes":["segmento"],"max_turns":8},"next":"proposta"}]},"max_tool_iterations":8,"history_limit_messages":40,"tail_budget_tokens":1500,"hard_cap_tokens":6000,"chain_same_provider":"","delivery":{"quote_replies":true,"formatting":"auto"},"stt":{"provider":"groq","model":"groq:whisper-large-v3-turbo"},"embedding":{"provider":"openai","model":"text-embedding-3-small"},"voice":{"enabled":false,"mode":"off","with_text":false,"provider":"elevenlabs","model":"eleven_multilingual_v2","call_backend":"auto","call_model":"openai:gpt-realtime","voice_id":"21m00Tcm4TlvDq8ikWAM","openai_voice":"alloy","gemini_voice":"Kore","stability":0.5,"similarity_boost":0.75,"style":0,"use_speaker_boost":true,"speed":1,"instructions":"Fale de forma calma e acolhedora.","style_instructions":"Locução comercial, ritmo animado."},"image_gen":{"enabled":false,"provider":"openai","model":"gpt-image-1"},"video_gen":{"enabled":false,"provider":"openai","model":"sora-2"},"custom_tools":[{"name":"consultar_pedido","description":"Consulta o status de um pedido pelo número.","method":"GET","url":"https://api.acme.com/orders/{{order_id}}","sensitive":false,"extract":"data.status","body_type":"json","body_template":{"source":"maestro","order_id":"{{order_id}}"},"headers":{"X-Api-Version":"2026-01"},"query":{"include":"items"},"auth":{"type":"bearer","name":"X-Api-Key","token_secret":"ACME_API_TOKEN","username_secret":"ACME_USER","password_secret":"ACME_PASS"},"params":[{"name":"order_id","type":"string","description":"Número do pedido.","required":true,"location":"auto"}],"response_map":[{"label":"Status","path":"data.status"}],"pagination":{"type":"none","param":"page","items_path":"data","next_path":"meta.next","start":1,"max_pages":5,"size_param":"per_page","size":50}}],"mcp_servers":[{"name":"acme-erp","url":"https://mcp.acme.com/sse","transport":"streamable_http","timeout":30,"sensitive":false,"enabled_tools":["get_order"],"headers":{"X-Tenant":"acme"},"auth":{"type":"bearer","name":"X-Api-Key","token_secret":"ACME_MCP_TOKEN","username_secret":"ACME_USER","password_secret":"ACME_PASS"}}],"media_assets":[{"name":"catalogo_2026","description":"Catálogo completo em PDF.","url":"https://cdn.acme.com/catalogo.pdf","type":"file"}],"sub_agents":[{"agent_id":7,"name":"Vendas","slug":"vendas","description":"Perguntas sobre planos e preços.","enabled":true,"sensitive":false}],"secrets":{"ACME_API_TOKEN":"sk-live-xxxxxxxx"},"secret_keys":["ACME_API_TOKEN"],"provider_keys":{"openai":"sk-proj-xxxxxxxx"},"chatwoot_native_keys":{"openai":"sk-proj-xxxxxxxx"},"provider_keys_set":["openai"],"native_keys_set":["openai"],"use_global_fallback":true},"bindings":[{"id":9,"inbox_id":3}],"created_at":"2026-07-01T12:00:00Z","updated_at":"2026-07-27T14:03:00Z"}}}},"409":{"description":"The inbox is already bound to another Robô in this account."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"inbox_id":{"type":"integer"}}},"example":{"inbox_id":1}}}}}},"/api/v1/accounts/{account_id}/maestro/agents/{id}/bindings/{binding_id}":{"delete":{"tags":["Maestro"],"operationId":"auto_delete_api_v1_accounts_account_id_maestro_agents_id_bindings_binding_id","summary":"Destroy binding maestro","description":"Performs the destroy binding operation on the targeted maestro resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"502":{"description":"The Maestro service could not be reached (connection refused or reset, host unresolvable), or it answered in a way the gateway could not use, or it rejected the server-to-server credential — the last one is a deployment key mismatch, never the caller's own session. Nothing was executed; the call can be retried.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"504":{"description":"The Maestro service did not answer within the proxy timeout. The work may still be running on the service side, so retrying a write can duplicate its effect.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"503":{"description":"The Maestro area is not serving this installation: an operator turned it off, or no admin key was ever provisioned. Nothing was executed, and retrying will not help until the configuration changes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"204":{"description":"The inbox binding was removed. The Robô itself is untouched. No body."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"binding_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/maestro/agents/{id}/kb/sources":{"get":{"tags":["Maestro"],"operationId":"auto_get_api_v1_accounts_account_id_maestro_agents_id_kb_sources","summary":"List a Robô's knowledge base sources","description":"The sources ingested into this Robô's own knowledge base, each with the number of chunks stored for it. A source is the label the chunks were filed under - the URL that was fetched, the uploaded file name, or the label given to a block of pasted text.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Every source in the Robô's knowledge base, with its chunk count.","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"source":{"type":"string","description":"Label the chunks are filed under. Deleting a source removes all of them.","example":"https://acme.com/policies/returns"},"chunks":{"type":"integer","description":"Number of embedded chunks stored for this source.","example":42}}}},"example":[{"source":"https://acme.com/policies/returns","chunks":42},{"source":"manual-de-atendimento.pdf","chunks":118}]}}},"401":{"description":"Unauthorized"},"404":{"description":"No Robô with this id belongs to the account."},"502":{"description":"The Maestro service could not be reached (connection refused or reset, host unresolvable), or it answered in a way the gateway could not use, or it rejected the server-to-server credential — the last one is a deployment key mismatch, never the caller's own session. Nothing was executed; the call can be retried.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"504":{"description":"The Maestro service did not answer within the proxy timeout. The work may still be running on the service side, so retrying a write can duplicate its effect.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"503":{"description":"The Maestro area is not serving this installation: an operator turned it off, or no admin key was ever provisioned. Nothing was executed, and retrying will not help until the configuration changes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]},"post":{"tags":["Maestro"],"operationId":"auto_post_api_v1_accounts_account_id_maestro_agents_id_kb_sources","summary":"Add a source to a Robô's knowledge base","description":"Ingests one source into this Robô's own knowledge base: a URL (fetched and text-extracted, which also covers a document upload handed over as a link) or a block of raw text. The content is chunked, embedded and stored for retrieval. Re-adding an existing label appends to it - replacing a source means deleting it first, then adding it again. Answers with the stored label and how many chunks it produced.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The stored source label and the number of chunks it produced.","content":{"application/json":{"schema":{"type":"object","properties":{"source":{"type":"string","description":"Label the chunks are filed under. Deleting a source removes all of them.","example":"https://acme.com/policies/returns"},"chunks":{"type":"integer","description":"Number of embedded chunks stored for this source.","example":42}}},"example":{"source":"https://acme.com/policies/returns","chunks":42}}}},"401":{"description":"Unauthorized"},"404":{"description":"No Robô with this id belongs to the account."},"502":{"description":"The Maestro service could not be reached (connection refused or reset, host unresolvable), or it answered in a way the gateway could not use, or it rejected the server-to-server credential — the last one is a deployment key mismatch, never the caller's own session. Nothing was executed; the call can be retried.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"504":{"description":"The Maestro service did not answer within the proxy timeout. The work may still be running on the service side, so retrying a write can duplicate its effect.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"503":{"description":"The content could not be embedded - the embedding provider is unreachable, or its key has no credit left. Nothing was stored, so the same request can simply be retried."},"201":{"description":"The stored source label and the number of chunks it produced.","content":{"application/json":{"schema":{"type":"object","properties":{"source":{"type":"string","description":"Label the chunks are filed under. Deleting a source removes all of them.","example":"https://acme.com/policies/returns"},"chunks":{"type":"integer","description":"Number of embedded chunks stored for this source.","example":42}}},"example":{"source":"https://acme.com/policies/returns","chunks":42}}}},"400":{"description":"Neither a URL nor text was supplied, so there was nothing to ingest."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string"},"text":{"type":"string"},"source":{"type":"string"}}},"example":{"url":"https://example.com/resource","text":"sample text","source":"sample source"}}}}},"delete":{"tags":["Maestro"],"operationId":"auto_delete_api_v1_accounts_account_id_maestro_agents_id_kb_sources","summary":"Destroy kb source maestro","description":"Performs the destroy kb source operation on the targeted maestro resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"502":{"description":"The Maestro service could not be reached (connection refused or reset, host unresolvable), or it answered in a way the gateway could not use, or it rejected the server-to-server credential — the last one is a deployment key mismatch, never the caller's own session. Nothing was executed; the call can be retried.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"504":{"description":"The Maestro service did not answer within the proxy timeout. The work may still be running on the service side, so retrying a write can duplicate its effect.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"503":{"description":"The Maestro area is not serving this installation: an operator turned it off, or no admin key was ever provisioned. Nothing was executed, and retrying will not help until the configuration changes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"204":{"description":"Every chunk of that source was removed from this Robô's knowledge base. No body."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/maestro/account-kb/sources":{"get":{"tags":["Maestro"],"operationId":"auto_get_api_v1_accounts_account_id_maestro_account_kb_sources","summary":"List the account's shared knowledge base sources","description":"The sources ingested into the knowledge base shared by every Robô of the account that opts into it, each with the number of chunks stored for it. Separate from a Robô's own base: this one is queried by all the Robôs configured to use it.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Every source in the shared knowledge base, with its chunk count.","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"source":{"type":"string","description":"Label the chunks are filed under. Deleting a source removes all of them.","example":"https://acme.com/policies/returns"},"chunks":{"type":"integer","description":"Number of embedded chunks stored for this source.","example":42}}}},"example":[{"source":"politica-de-trocas.pdf","chunks":87}]}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"502":{"description":"The Maestro service could not be reached (connection refused or reset, host unresolvable), or it answered in a way the gateway could not use, or it rejected the server-to-server credential — the last one is a deployment key mismatch, never the caller's own session. Nothing was executed; the call can be retried.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"504":{"description":"The Maestro service did not answer within the proxy timeout. The work may still be running on the service side, so retrying a write can duplicate its effect.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"503":{"description":"The Maestro area is not serving this installation: an operator turned it off, or no admin key was ever provisioned. Nothing was executed, and retrying will not help until the configuration changes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]},"post":{"tags":["Maestro"],"operationId":"auto_post_api_v1_accounts_account_id_maestro_account_kb_sources","summary":"Add a source to the account's shared knowledge base","description":"Ingests one source into the knowledge base shared by the account's Robôs: a URL (fetched and text-extracted) or a block of raw text. The content is chunked, embedded and stored for retrieval. Answers with the stored label and how many chunks it produced.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The stored source label and the number of chunks it produced.","content":{"application/json":{"schema":{"type":"object","properties":{"source":{"type":"string","description":"Label the chunks are filed under. Deleting a source removes all of them.","example":"https://acme.com/policies/returns"},"chunks":{"type":"integer","description":"Number of embedded chunks stored for this source.","example":42}}},"example":{"source":"politica-de-trocas.pdf","chunks":87}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"502":{"description":"The Maestro service could not be reached (connection refused or reset, host unresolvable), or it answered in a way the gateway could not use, or it rejected the server-to-server credential — the last one is a deployment key mismatch, never the caller's own session. Nothing was executed; the call can be retried.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"504":{"description":"The Maestro service did not answer within the proxy timeout. The work may still be running on the service side, so retrying a write can duplicate its effect.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"503":{"description":"The content could not be embedded - the embedding provider is unreachable, or its key has no credit left. Nothing was stored, so the same request can simply be retried."},"201":{"description":"The stored source label and the number of chunks it produced.","content":{"application/json":{"schema":{"type":"object","properties":{"source":{"type":"string","description":"Label the chunks are filed under. Deleting a source removes all of them.","example":"https://acme.com/policies/returns"},"chunks":{"type":"integer","description":"Number of embedded chunks stored for this source.","example":42}}},"example":{"source":"politica-de-trocas.pdf","chunks":87}}}},"400":{"description":"Neither a URL nor text was supplied, so there was nothing to ingest."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string"},"text":{"type":"string"},"source":{"type":"string"}}},"example":{"url":"https://example.com/resource","text":"sample text","source":"sample source"}}}}},"delete":{"tags":["Maestro"],"operationId":"auto_delete_api_v1_accounts_account_id_maestro_account_kb_sources","summary":"Destroy account kb source maestro","description":"Performs the destroy account kb source operation on the targeted maestro resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"502":{"description":"The Maestro service could not be reached (connection refused or reset, host unresolvable), or it answered in a way the gateway could not use, or it rejected the server-to-server credential — the last one is a deployment key mismatch, never the caller's own session. Nothing was executed; the call can be retried.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"504":{"description":"The Maestro service did not answer within the proxy timeout. The work may still be running on the service side, so retrying a write can duplicate its effect.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"503":{"description":"The Maestro area is not serving this installation: an operator turned it off, or no admin key was ever provisioned. Nothing was executed, and retrying will not help until the configuration changes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"204":{"description":"Every chunk of that source was removed from the account's shared knowledge base. No body."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/maestro/help-center-articles":{"get":{"tags":["Maestro"],"operationId":"auto_get_api_v1_accounts_account_id_maestro_help_center_articles","summary":"Articles help center kb","description":"Performs the articles operation on the targeted help center kb resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"portals":{"type":"array","items":{"type":"string"}},"categories":{"type":"array","items":{"type":"string"}},"articles":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"title":{"type":"string"},"status":{"type":"string","enum":["draft","published","archived"],"description":"Publication state of the Help Center article."},"locale":{"type":"string"},"portal_id":{"type":"integer"},"category_id":{"type":"integer"},"description":{"type":["string","null"]},"tags":{"type":"string"}},"required":["id","title","status","locale","portal_id","category_id","description","tags"],"additionalProperties":false}}}},"example":{"portals":["sample portal"],"categories":["sample categorie"],"articles":[{"id":1,"title":"Sample title","status":"draft","locale":"en","portal_id":1,"category_id":1,"description":"A short description.","tags":"sample tags"}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/maestro/agents/{id}/help-center-kb":{"get":{"tags":["Maestro"],"operationId":"auto_get_api_v1_accounts_account_id_maestro_agents_id_help_center_kb","summary":"List help center kb","description":"Returns the list of help center kb visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"article_ids":{"type":"array","items":{"type":"integer"}}}},"example":{"article_ids":[1]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."}]},"put":{"tags":["Maestro"],"operationId":"auto_put_api_v1_accounts_account_id_maestro_agents_id_help_center_kb","summary":"Update help center kb","description":"Updates the help center kb identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"article_ids":{"type":"array","items":{"type":"integer"}}}},"example":{"article_ids":[1]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"article_ids":{"type":"array","items":{"type":"integer"}}}},"example":{"article_ids":[1]}}}}}},"/api/v1/accounts/{account_id}/maestro/control/status":{"get":{"tags":["Maestro"],"operationId":"auto_get_api_v1_accounts_account_id_maestro_control_status","summary":"Get the Robô state for one conversation","description":"Everything the conversation panel needs to describe what the Robô is doing here: whether it has stood down for a human, which Robô is bound to this inbox and whether it is switched on, the autonomy tier it runs at, and how many of its actions are parked waiting for approval. The conversation's own status, priority, assignee and team are echoed alongside so the panel renders from one call. Parked approvals are known even when the conversation itself cannot be read - an action waiting on a human must surface no matter what else is degraded, which is what `chatwoot_reachable` reports.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The Robô and conversation state powering the panel.","content":{"application/json":{"schema":{"type":"object","properties":{"contract_version":{"type":"string","enum":["2"],"description":"Version of the durable stand-down contract returned by Maestro.","example":"2"},"standdown_known":{"type":"boolean","description":"True when the pause state is backed by a durable Maestro transition.","example":true},"standdown_active":{"type":"boolean","description":"True while the Robô has receded because a human took over. It stays paused until resumed, or until the configured idle window elapses when auto-resume is on.","example":false},"standdown_version":{"type":"integer","description":"Monotonic generation of the durable stand-down state.","example":12},"standdown_source":{"type":["string","null"],"description":"System or operator action that last changed the stand-down state.","example":"human_assignment"},"standdown_reason":{"type":["string","null"],"description":"Machine-readable reason for the current stand-down state.","example":"human_assignee"},"standdown_expires_at":{"type":["string","null"],"format":"date-time","description":"Optional automatic-resume instant. Null means explicit resume is required.","example":"2026-08-21T20:00:00Z"},"standdown_event_cursor":{"type":["integer","null"],"description":"Monotonic platform event cursor last applied by Maestro.","example":1787284800123456},"standdown_request_id":{"type":["string","null"],"format":"uuid","description":"Idempotency identifier of the last durable run-state transition.","example":"1d5b85ba-f6be-47d8-82c8-f03af19f6288"},"automation_control_state":{"type":"string","enum":["active","paused","unknown"],"description":"the platform’s authoritative local projection. `unknown` is held fail-closed and must never be interpreted as active.","example":"paused"},"automation_control_recovery_available":{"type":"boolean","description":"True when an operator may explicitly recover a bootstrap-unknown state.","example":false},"maestro_control_admin":{"type":"boolean","description":"True when the authenticated dashboard actor may use administrator-only controls.","example":true},"maestro_capabilities":{"type":"object","description":"Effective native action grants for this conversation, intersected with visibility and operational scope. No field grants account administration.","required":["pause","resume","assume","handoff","conversation_status","priority","labels","attributes","assign","macro","agent","autonomy","context_reset","replay","suggest","summarize","ask","execute","pending_view","pending_approve","pending_reject","generate","send_prepared","action_label","action_resolve","preview_read"],"properties":{"pause":{"type":"boolean","description":"Whether this action is authorized for the current human in this conversation.","example":true},"resume":{"type":"boolean","description":"Whether this action is authorized for the current human in this conversation.","example":true},"assume":{"type":"boolean","description":"Whether this action is authorized for the current human in this conversation.","example":true},"handoff":{"type":"boolean","description":"Whether this action is authorized for the current human in this conversation.","example":true},"conversation_status":{"type":"boolean","description":"Whether this action is authorized for the current human in this conversation.","example":true},"priority":{"type":"boolean","description":"Whether this action is authorized for the current human in this conversation.","example":true},"labels":{"type":"boolean","description":"Whether this action is authorized for the current human in this conversation.","example":true},"attributes":{"type":"boolean","description":"Whether this action is authorized for the current human in this conversation.","example":true},"assign":{"type":"boolean","description":"Whether this action is authorized for the current human in this conversation.","example":true},"macro":{"type":"boolean","description":"Whether this action is authorized for the current human in this conversation.","example":true},"agent":{"type":"boolean","description":"Whether this action is authorized for the current human in this conversation.","example":true},"autonomy":{"type":"boolean","description":"Whether this action is authorized for the current human in this conversation.","example":true},"context_reset":{"type":"boolean","description":"Whether this action is authorized for the current human in this conversation.","example":true},"replay":{"type":"boolean","description":"Whether this action is authorized for the current human in this conversation.","example":true},"suggest":{"type":"boolean","description":"Whether this action is authorized for the current human in this conversation.","example":true},"summarize":{"type":"boolean","description":"Whether this action is authorized for the current human in this conversation.","example":true},"ask":{"type":"boolean","description":"Whether this action is authorized for the current human in this conversation.","example":true},"execute":{"type":"boolean","description":"Whether this action is authorized for the current human in this conversation.","example":true},"pending_view":{"type":"boolean","description":"Whether this action is authorized for the current human in this conversation.","example":true},"pending_approve":{"type":"boolean","description":"Whether this action is authorized for the current human in this conversation.","example":true},"pending_reject":{"type":"boolean","description":"Whether this action is authorized for the current human in this conversation.","example":true},"generate":{"type":"boolean","description":"Whether this action is authorized for the current human in this conversation.","example":true},"send_prepared":{"type":"boolean","description":"Whether this action is authorized for the current human in this conversation.","example":true},"action_label":{"type":"boolean","description":"Execute grant intersected with labels grant and native conversation policy.","example":true},"action_resolve":{"type":"boolean","description":"Execute grant intersected with conversation_status grant and native conversation policy.","example":true},"preview_read":{"type":"boolean","description":"Generate OR send_prepared grant intersected with conversation visibility. Never grants generation.","example":true}}},"maestro_generation_scope":{"type":"string","enum":["none","text_only","full"],"description":"Text-only generation permits no references or resource selection. Full retains administrator behavior.","example":"text_only"},"maestro_ask_scope":{"type":"string","enum":["none","conversation","full"],"description":"Conversation answers only from this conversation transcript without tools, KB, contact profile or other resources.","example":"conversation"},"maestro_execution_scope":{"type":"string","enum":["none","qualified","full"],"description":"Full preserves real administrator behavior. Qualified is limited to the explicitly listed existing human Sales consumers, with per-target authorization on every request.","example":"qualified"},"maestro_executable_tools":{"type":"array","description":"Enumerates the bounded non-administrator subset only. An administrator with full scope uses the existing catalogue and receives an empty subset list. No entry authorizes arbitrary arguments.","items":{"type":"string","enum":["sales_get_leaderboard","sales_recognize","sales_list_deal_approvals","sales_decide_deal_approval"]},"example":["sales_list_deal_approvals","sales_decide_deal_approval"]},"maestro_pending_approve_tools":{"type":"array","description":"Bounded approval tools; an administrator retains existing full behavior. Every pending entry also carries authoritative maestro_can_approve.","items":{"type":"string","enum":["execute_macro"]},"example":["execute_macro"]},"human_assigned":{"type":"boolean","description":"the platform’s tenant-scoped human assignment. An administrator may explicitly return ownership to an active native bot when resume_to_bot_available is true; background reconciliation never clears a human hold from a stale remote flag.","example":true},"resume_to_bot_available":{"type":"boolean","description":"The effective inbox has an active native Maestro binding eligible for explicit handback.","example":true},"pending_resume":{"type":["object","null"],"description":"Pending operation visible only to a human authorized to resume this conversation. Only request_id/context_action are exposed; retry that exact operation after an ambiguous response.","properties":{"request_id":{"type":"string","format":"uuid"},"context_action":{"type":"string","enum":["preserve","reset"]}},"example":null},"maestro_binding_mismatch":{"type":"boolean","description":"True when the platform still dispatches to this conversation's inbox (an active Maestro AgentBot binding) while Maestro reports no Robo for the conversation (`effective_agent` null). Each side is individually correct, so the contradiction is invisible in either one alone; surfaced here it names the inbox that is delivering without a binding. False whenever either half does not hold, and never an error.","example":false},"paused_inbound_retained_count":{"type":"integer","minimum":0,"description":"Number of paused inbound messages still retained and eligible for an explicit replay.","example":3},"paused_inbound_replay_available":{"type":"boolean","description":"True only when retained messages exist, the local automation state is active, and no human is assigned. Safety-retained messages can be replayable even when the configured steady-state policy is discard. Replay still requires explicit confirmation.","example":true},"paused_inbound_policy":{"type":["string","null"],"enum":["discard","latest","bounded_all",null],"description":"Per-Robot retention policy for contact messages received while paused.","example":"bounded_all"},"effective_agent":{"type":["string","null"],"description":"Name of the Robô bound to this conversation's inbox. Null when none is bound.","example":"Atendente Acme"},"agent_enabled":{"type":["boolean","null"],"description":"Whether that Robô is switched on. False means it is bound but deactivated, which the panel shows as inactive. Null when no Robô is bound.","example":true},"agent_id":{"type":["integer","null"],"description":"Maestro id of the Robot effectively serving the conversation.","example":17},"agent_origin":{"type":["string","null"],"enum":["conversation","inbox",null],"description":"Whether the Robot was selected for this conversation or inherited from the inbox.","example":"inbox"},"agent_source":{"type":["string","null"],"description":"Display-only provenance of a conversation Robot override.","example":"operator"},"autonomy_level":{"type":["string","null"],"description":"The bound Robô's autonomy tier. In `copilot` it never replies on its own, in `hybrid` sensitive actions are parked for approval, in `autopilot` it acts. Null when no Robô is bound.","enum":["autopilot","copilot","hybrid",null],"example":"hybrid"},"autonomy_origin":{"type":["string","null"],"enum":["conversation","agent",null],"description":"Whether the effective mode is a conversation override or inherited from the Robot.","example":"conversation"},"agent_autonomy_level":{"type":["string","null"],"enum":["autopilot","copilot","hybrid",null],"description":"The Robot's configured mode even while a conversation override is active.","example":"autopilot"},"pending_count":{"type":"integer","description":"Sensitive actions parked on this conversation waiting for a human decision.","example":1},"conversation_status":{"type":["string","null"],"description":"The conversation's current status. Null when it could not be read.","enum":["open","resolved","pending","snoozed",null],"example":"open"},"priority":{"type":["string","null"],"description":"The conversation's current priority. Null when unset or unreadable.","enum":["low","medium","high","urgent",null],"example":"high"},"assignee":{"type":["object","null"],"description":"The agent the conversation is assigned to. Null when unassigned.","properties":{"id":{"type":"integer","description":"Identifier of the assigned agent.","example":7},"name":{"type":"string","description":"Display name of the assigned agent.","example":"Ana Souza"}}},"team":{"type":["object","null"],"description":"The team the conversation belongs to. Null when none.","properties":{"id":{"type":"integer","description":"Identifier of the team.","example":3},"name":{"type":"string","description":"Name of the team.","example":"Suporte"}}},"chatwoot_reachable":{"type":"boolean","description":"False when the conversation itself could not be read, in which case only the stand-down flag and the pending count above are meaningful.","example":true},"resume_context_permission_supported":{"type":"boolean","enum":[true],"description":"Positive support for server-asserted reset permission on delegated resume. Missing/false/failed fresh status prevents any new delegated resume/reservation; never fallback to an older producer.","example":true},"context_reset_supported":{"type":"boolean","description":"True when this Maestro version supports conversation context boundaries.","example":true},"resume_context_policy":{"type":["string","null"],"enum":["preserve","reset","ask",null],"description":"Context action snapshotted when this conversation was paused, or the live Robot policy while active.","example":"ask"},"ask_auto_resume_fallback":{"type":["string","null"],"enum":["stay_paused","preserve","reset",null],"description":"Timer action used when the snapshotted resume policy requires a human decision.","example":"stay_paused"},"context_decision_required":{"type":"boolean","description":"True when Resume must explicitly choose whether to preserve or reset context.","example":true},"allow_human_context_reset":{"type":"boolean","description":"Whether this Robot grants the narrow reset operation to ordinary agents.","example":false},"context_reset_allowed":{"type":"boolean","description":"Whether the authenticated actor may reset this conversation now. Administrators are always eligible; ordinary agents additionally require the per-Robot grant.","example":true},"context_generation":{"type":"integer","minimum":0,"description":"Monotonic working-memory generation. Zero means no reset has occurred.","example":2},"context_cutoff_message_id":{"type":"integer","minimum":0,"description":"Highest platform message id excluded from future Robot context.","example":9182},"context_last_reset_at":{"type":["string","null"],"format":"date-time","description":"Time of the latest completed context-boundary creation.","example":"2026-09-02T18:00:00Z"},"context_last_reset_actor_name":{"type":["string","null"],"description":"Display name recorded for the latest context reset.","example":"Ana Souza"},"context_last_reset_source":{"type":["string","null"],"enum":["manual","resume","auto_resume","webhook_resume",null],"description":"Flow that created the latest context boundary.","example":"manual"}}},"example":{"contract_version":"2","standdown_known":true,"standdown_active":true,"standdown_version":12,"standdown_source":"human_assignment","standdown_reason":"human_assignee","standdown_expires_at":null,"standdown_event_cursor":1787284800123456,"standdown_request_id":"1d5b85ba-f6be-47d8-82c8-f03af19f6288","automation_control_state":"paused","automation_control_recovery_available":false,"maestro_control_admin":true,"maestro_capabilities":{"pause":true,"resume":true,"assume":true,"handoff":true,"conversation_status":true,"priority":true,"labels":true,"attributes":true,"assign":true,"macro":true,"agent":true,"autonomy":true,"context_reset":true,"replay":true,"suggest":true,"summarize":true,"ask":true,"execute":true,"pending_view":true,"pending_approve":true,"pending_reject":true,"generate":true,"send_prepared":true,"action_label":true,"action_resolve":true,"preview_read":true},"maestro_generation_scope":"full","maestro_ask_scope":"full","resume_context_permission_supported":true,"maestro_execution_scope":"full","maestro_executable_tools":[],"maestro_pending_approve_tools":[],"human_assigned":true,"maestro_binding_mismatch":false,"paused_inbound_retained_count":3,"paused_inbound_replay_available":false,"paused_inbound_policy":"bounded_all","effective_agent":"Atendente Acme","agent_enabled":true,"agent_id":17,"agent_origin":"inbox","agent_source":"operator","autonomy_level":"hybrid","autonomy_origin":"conversation","agent_autonomy_level":"autopilot","pending_count":1,"conversation_status":"open","priority":"high","assignee":{"id":7,"name":"Ana Souza"},"team":{"id":3,"name":"Suporte"},"chatwoot_reachable":true,"context_reset_supported":true,"resume_context_policy":"ask","ask_auto_resume_fallback":"stay_paused","context_decision_required":true,"allow_human_context_reset":false,"context_reset_allowed":true,"context_generation":2,"context_cutoff_message_id":9182,"context_last_reset_at":"2026-09-02T18:00:00Z","context_last_reset_actor_name":"Ana Souza","context_last_reset_source":"manual","resume_to_bot_available":true,"pending_resume":null}}}},"401":{"description":"Not signed in, not a member of this account, or the membership was revoked. The account check runs before any Maestro authorization, so nothing is sent to Maestro."},"404":{"description":"Account or resource not found"},"502":{"description":"The Maestro service could not be reached (connection refused or reset, host unresolvable), or it answered in a way the gateway could not use, or it rejected the server-to-server credential — the last one is a deployment key mismatch, never the caller's own session. Nothing was executed; the call can be retried.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"504":{"description":"The Maestro service did not answer within the proxy timeout. The work may still be running on the service side, so retrying a write can duplicate its effect.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"503":{"description":"The Maestro area is not serving this installation: an operator turned it off, or no admin key was ever provisioned. Nothing was executed, and retrying will not help until the configuration changes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"422":{"description":"The required account-scoped conversation id is missing.","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"type":"string"},"code":{"type":"string","enum":["maestro_conversation_required"]}}},"example":{"error":"sample error","code":"maestro_conversation_required"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"conversation_id","in":"query","required":true,"description":"Account-scoped conversation display id whose authoritative control state is reported.","schema":{"type":"integer"},"example":4821}]}},"/api/v1/accounts/{account_id}/maestro/control/pickers/{kind}":{"get":{"tags":["Maestro"],"operationId":"auto_get_api_v1_accounts_account_id_maestro_control_pickers_kind","summary":"Get a Maestro control-surface picker (teams or macros)","description":"Returns the account's teams or macros as {id, name} refs for the copilot control surface. `kind` must be `teams` or `macros`; any other value returns 400 with an error body.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"List of {id, name} refs for the requested picker.","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","example":3},"name":{"type":"string","example":"Support Team"}}}},"example":[{"id":3,"name":"Support Team"}]}}},"401":{"description":"Not signed in, not a member of this account, or the membership was revoked. The account check runs before any Maestro authorization, so nothing is sent to Maestro."},"404":{"description":"Account or resource not found"},"502":{"description":"The Maestro service could not be reached (connection refused or reset, host unresolvable), or it answered in a way the gateway could not use, or it rejected the server-to-server credential — the last one is a deployment key mismatch, never the caller's own session. Nothing was executed; the call can be retried.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"504":{"description":"The Maestro service did not answer within the proxy timeout. The work may still be running on the service side, so retrying a write can duplicate its effect.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"503":{"description":"The Maestro area is not serving this installation: an operator turned it off, or no admin key was ever provisioned. Nothing was executed, and retrying will not help until the configuration changes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"400":{"description":"Unknown picker kind.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"unknown picker"}}},"example":{"error":"unknown picker"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"kind","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/maestro/control/pending/summary":{"get":{"tags":["Maestro"],"operationId":"auto_get_api_v1_accounts_account_id_maestro_control_pending_summary","summary":"List conversations with Maestro actions awaiting approval","description":"Returns one entry per conversation of this account that currently has hybrid-mode sensitive tool calls parked for human approval, with the number of parked actions and the conversation display id (for deep-linking). An empty array means nothing is awaiting approval. Admin-only.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"One entry per conversation with parked approvals (empty when all clear).","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"conversation_id":{"type":"integer","description":"Global conversation id (the sidecar's key).","example":1024},"display_id":{"type":["integer","null"],"description":"Per-account display id for deep-linking (null if unresolved).","example":42},"count":{"type":"integer","description":"Number of sensitive actions parked for approval on this conversation.","example":2}}}},"example":[{"conversation_id":1024,"display_id":42,"count":2}]}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"502":{"description":"The Maestro service could not be reached (connection refused or reset, host unresolvable), or it answered in a way the gateway could not use, or it rejected the server-to-server credential — the last one is a deployment key mismatch, never the caller's own session. Nothing was executed; the call can be retried.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"504":{"description":"The Maestro service did not answer within the proxy timeout. The work may still be running on the service side, so retrying a write can duplicate its effect.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"503":{"description":"Either the Maestro area is not serving this installation (an operator turned it off, or no admin key was ever provisioned; retrying will not help until the configuration changes), or the Maestro service could not read its approvals queue (`maestro_pending_summary_unavailable`). In the second case nothing was changed and the answer is unknown, not empty: approvals may still be waiting, and the call can be retried.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Localized, human-readable explanation of the failure.","example":"The approvals queue could not be read right now. Nothing was changed; try again in a moment."},"code":{"type":"string","description":"Stable machine code. `maestro_disabled` — the operator turned the Maestro area off. `maestro_not_configured` — no admin key was ever provisioned. `maestro_pending_summary_unavailable` — the approvals queue could not be read.","enum":["maestro_disabled","maestro_not_configured","maestro_pending_summary_unavailable"],"example":"maestro_pending_summary_unavailable"}}},"example":{"error":"The approvals queue could not be read right now. Nothing was changed; try again in a moment.","code":"maestro_pending_summary_unavailable"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/maestro/control/pending":{"get":{"tags":["Maestro"],"operationId":"auto_get_api_v1_accounts_account_id_maestro_control_pending","summary":"List actions awaiting approval on a conversation","description":"The sensitive actions this conversation's Robô proposed and parked for a human decision. Each entry carries the tool it would run, why the Robô proposed it and the arguments it resolved, so the approver decides on the full proposal rather than on a name. Sensitive argument values are redacted before they reach this response.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Every parked action on this conversation, oldest identifier first.","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Identifier of the parked action, used to approve or reject it.","example":"pa_7f3c1b90"},"tool":{"type":"string","description":"The write tool that runs verbatim if the action is approved.","example":"crm_create_deal"},"rationale":{"type":"string","description":"Why the Robô proposed the action, in its own words.","example":"O contato confirmou interesse no plano anual e pediu proposta."},"created_at":{"type":"integer","description":"Unix timestamp, in seconds, of when the action was parked.","example":1782000000},"args":{"type":"object","description":"The arguments the action would run with, as the Robô resolved them. Keys and value types are the tool's own; values flagged sensitive are redacted.","additionalProperties":true,"example":{"title":"Plano anual - Acme","value_amount":4800}},"maestro_can_approve":{"type":"boolean","description":"Server-authorized eligibility for this actual pending entry. Non-administrators may approve only an eligible native macro, never another tool.","example":false},"state":{"type":"string","enum":["pending","processing","needs_attention"],"example":"pending"},"attention_reason":{"type":["string","null"],"enum":["conflicting_assignment","legacy_unsigned","paused",null],"description":"Why an undecided action cannot be approved as it stands; null otherwise. It comes with state needs_attention and every reason still allows rejection. conflicting_assignment: another transfer proposal of the same request names a different team, so one alternative must be rejected first. legacy_unsigned: an older proposal without a confirmed origin, which can only be rejected. paused: the Robô is paused in this conversation, so approval is refused until it is resumed there.","example":"paused"},"conflicting_ids":{"type":"array","description":"Identifiers of the competing transfer proposals. Filled whenever such proposals exist, even when an invalid signature or a claim prevails and attention_reason is not conflicting_assignment.","items":{"type":"string"},"example":[]},"presentation":{"type":"object","properties":{"title":{"type":"string","example":"Transferir para o time suporte"},"tool_label":{"type":"string","example":"Transferir para um time"},"locale":{"type":"string","example":"pt_BR"},"title_key":{"type":"string","example":"handoff_to_team"},"title_params":{"type":"object","properties":{"team_name":{"type":"string","example":"suporte"}}},"arguments":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string","example":"team_id"},"label":{"type":"string","example":"Time"},"value":{"type":"string","example":"suporte"},"available":{"type":"boolean","example":true},"reference":{"type":"string","example":"2"}}}}}}}}},"example":[{"id":"pa_7f3c1b90","tool":"crm_create_deal","rationale":"O contato confirmou interesse no plano anual e pediu proposta.","created_at":1782000000,"args":{"title":"Plano anual - Acme","value_amount":4800},"maestro_can_approve":false,"state":"pending","attention_reason":"paused","conflicting_ids":[],"presentation":{"title":"Transferir para o time suporte","tool_label":"Transferir para um time","locale":"pt_BR","title_key":"handoff_to_team","title_params":{"team_name":"suporte"},"arguments":[{"key":"team_id","label":"Time","value":"suporte","available":true,"reference":"2"}]}}]}}},"401":{"description":"Not signed in, not a member of this account, or the membership was revoked. The account check runs before any Maestro authorization, so nothing is sent to Maestro."},"404":{"description":"Account or resource not found"},"502":{"description":"The Maestro service could not be reached (connection refused or reset, host unresolvable), or it answered in a way the gateway could not use, or it rejected the server-to-server credential — the last one is a deployment key mismatch, never the caller's own session. Nothing was executed; the call can be retried.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"504":{"description":"The Maestro service did not answer within the proxy timeout. The work may still be running on the service side, so retrying a write can duplicate its effect.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"503":{"description":"The Maestro area is not serving this installation: an operator turned it off, or no admin key was ever provisioned. Nothing was executed, and retrying will not help until the configuration changes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"conversation_id","in":"query","required":true,"description":"Authorized positive conversation display id. This route never lists another conversation or an account-wide queue.","schema":{"type":"integer"},"example":4821}]}},"/api/v1/accounts/{account_id}/maestro/control/context/reset":{"post":{"tags":["Maestro"],"operationId":"auto_post_api_v1_accounts_account_id_maestro_control_context_reset","summary":"Reset the Maestro context for one conversation","description":"Creates a durable generation boundary so the Robot starts fresh on the next contact message, without deleting any platform message, contact, CRM record, knowledge-base source or cross-contact long-term memory. The operation preserves the current active or paused state, cancels parked approvals and retained paused inbound for this conversation, clears the rolling summary, and writes a private audit note that is excluded from future model context. Administrators may always reset; an ordinary agent must be able to open the conversation and the effective Robot must grant the per-Robot reset permission. Confirmation and a reusable UUID are mandatory.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Durable reset receipt returned for the first execution and identical UUID retries.","content":{"application/json":{"schema":{"type":"object","required":["ok","detail","generation","cutoff_message_id","reset_at","standdown_active","cancelled_pending_count","cancelled_paused_count","note_status"],"properties":{"ok":{"type":"boolean","enum":[true],"description":"True when the durable context boundary exists.","example":true},"detail":{"type":"string","enum":["context_reset_completed"],"description":"Stable machine-readable reset outcome.","example":"context_reset_completed"},"generation":{"type":"integer","minimum":1,"description":"New monotonic conversation context generation.","example":2},"cutoff_message_id":{"type":"integer","minimum":0,"description":"Highest existing platform message id excluded from the new context.","example":9182},"reset_at":{"type":"string","format":"date-time","description":"Time the durable boundary was created.","example":"2026-09-02T18:00:00Z"},"standdown_active":{"type":"boolean","description":"Pause state preserved by the reset operation.","example":true},"cancelled_pending_count":{"type":"integer","minimum":0,"description":"Parked approvals canceled for this conversation.","example":1},"cancelled_paused_count":{"type":"integer","minimum":0,"description":"Retained paused inbound messages canceled for this conversation.","example":3},"note_status":{"type":"string","enum":["note_pending","note_sent"],"description":"Delivery state of the private platform audit note.","example":"note_sent"}}},"example":{"ok":true,"detail":"context_reset_completed","generation":2,"cutoff_message_id":9182,"reset_at":"2026-09-02T18:00:00Z","standdown_active":true,"cancelled_pending_count":1,"cancelled_paused_count":3,"note_status":"note_sent"}}}},"401":{"description":"Not signed in, not a member of this account, or the membership was revoked. The account check runs before any Maestro authorization, so nothing is sent to Maestro."},"404":{"description":"Account or resource not found"},"502":{"description":"The Maestro service could not be reached (connection refused or reset, host unresolvable), or it answered in a way the gateway could not use, or it rejected the server-to-server credential — the last one is a deployment key mismatch, never the caller's own session. Nothing was executed; the call can be retried.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"504":{"description":"The Maestro service did not answer within the proxy timeout. The work may still be running on the service side, so retrying a write can duplicate its effect.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"503":{"description":"The Maestro area is not serving this installation: an operator turned it off, or no admin key was ever provisioned. Nothing was executed, and retrying will not help until the configuration changes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"403":{"description":"The ordinary agent lacks the effective Robot's context-reset permission."},"409":{"description":"A turn/reset is busy, or the UUID conflicts with another request."},"422":{"description":"Confirmation, conversation id or the UUID idempotency identifier is missing or invalid."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["conversation_id","request_id","confirm"],"properties":{"conversation_id":{"type":"integer","description":"Account-scoped conversation display id whose Robot context is reset.","example":4821},"request_id":{"type":"string","format":"uuid","description":"Idempotency identifier reused when retrying the same reset attempt.","example":"1969f63d-2225-488a-91db-8a8e9f405289"},"confirm":{"type":"boolean","enum":[true],"description":"Explicit acknowledgement that Robot working memory will be cleared.","example":true}}},"example":{"conversation_id":4821,"request_id":"1969f63d-2225-488a-91db-8a8e9f405289","confirm":true}}}}}},"/api/v1/accounts/{account_id}/maestro/control/pending/approve":{"post":{"tags":["Maestro"],"operationId":"auto_post_api_v1_accounts_account_id_maestro_control_pending_approve","summary":"Approve a parked Robô action","description":"Approves one action the Robô parked for review and runs it, verbatim, with the arguments that were proposed - nothing is re-decided at approval time. The approver's name is recorded with the decision. A proven pre-execution failure may remain pending; an uncertain external effect requires attention and must not be blindly retried. Inspect `ok` and `code`: HTTP 200 does not itself confirm execution, and `detail` is prose, not guidance. An identifier that is not pending - unknown, already approved, rejected, expired or closed by a handoff - never runs: the answer is `ok: false` with `pending_superseded` (disposition needs_new_request) when a handoff closed it, otherwise `pending_expired`, whose disposition is not_pending (check the conversation history before asking for a new action). A parked macro runs with the approver's own permissions, never the service user's: Chatwoot reads the parked action and checks that this person can run that macro on this conversation before asking Maestro to approve it. A refusal answers `ok: false`, `state: pending` and a `code`, and the action stays pending for someone who is allowed.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Whether the action took effect, and a short human-readable outcome. Not an error status - a refusal is part of the normal answer.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","description":"True when the action took effect.","example":true},"state":{"type":"string","enum":["approved","rejected","pending","processing","needs_attention"],"description":"Durable decision result; HTTP 200 with ok false is not a successful execution.","example":"approved"},"detail":{"type":"string","description":"Localized outcome description. Clients must use ok and state to distinguish successful execution from uncertain delivery.","example":"Negócio criado no CRM."},"code":{"type":"string","enum":["maestro_macro_access_denied","maestro_conversation_access_denied","maestro_human_actor_required","maestro_macro_not_found","maestro_conversation_not_found","maestro_human_macro_request_invalid","maestro_human_capability_unavailable","pending_agent_changed","pending_already_processed","pending_approved","pending_authority","pending_channel_changed","pending_conflicting_assignment","pending_consumed_no_effect","pending_credential","pending_delivery_unconfirmed","pending_destination_changed","pending_execution_failed","pending_execution_refused","pending_expired","pending_human_actor","pending_partial","pending_paused","pending_rejected","pending_request_changed","pending_superseded","pending_tenant_mismatch","pending_ui_only","pending_unauthenticated","pending_unavailable","pending_uncertain","pending_unsupported"],"description":"What happened to this attempt, from a closed vocabulary; clients localize it and must not read detail as guidance. maestro_* codes are Chatwoot refusals of a parked macro for this approver before Maestro was asked: nothing ran and the action stays pending. pending_* codes come from Maestro's versioned decision contract, where each one has a disposition: executed or rejected (ok true); not_consumed (refused before the claim, nothing ran, the proposal is unchanged); needs_new_request (nothing ran and this proposal can never run as it stands); not_pending (the proposal is gone and nothing on record says why, so it may have already run: check the conversation history before any new action); consumed_no_effect (the attempt was spent with no effect); uncertain (an effect may have happened, check before any new action and never approve again).","example":"maestro_macro_access_denied"}}},"example":{"ok":true,"detail":"Negócio criado no CRM.","state":"approved","code":"maestro_macro_access_denied"}}}},"401":{"description":"Not signed in, not a member of this account, or the membership was revoked. The account check runs before any Maestro authorization, so nothing is sent to Maestro."},"404":{"description":"Account or resource not found"},"502":{"description":"The Maestro service could not be reached (connection refused or reset, host unresolvable), or it answered in a way the gateway could not use, or it rejected the server-to-server credential — the last one is a deployment key mismatch, never the caller's own session. Nothing was executed; the call can be retried.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"504":{"description":"The Maestro service did not answer within the proxy timeout. The work may still be running on the service side, so retrying a write can duplicate its effect.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"503":{"description":"The Maestro area is not serving this installation: an operator turned it off, or no admin key was ever provisioned. Nothing was executed, and retrying will not help until the configuration changes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"403":{"description":"A delegated human requires maestro_pending_approve AND maestro_macro plus effective native conversation and MacroPolicy authorization. Only an existing execute_macro entry is eligible; Rails uses the existing U23 parked-action lookup, not caller-provided tool/args, and signs the exact macro/request/conversation. The sidecar verifies the original binding before claim and the native human macro job reauthorizes. HOLD or unavailable delegation never falls back to service. Other tools remain administrator-only. Missing grants/policy/scope are 403 before sidecar I/O; a denied resolved entry is 403 before mint/approval POST/claim. Administrators preserve the existing flow."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"conversation_id":{"type":"integer"},"id":{"type":"integer"},"cmd":{"type":"string"},"macro_id":{"type":"integer"},"request_id":{"type":"integer"}}},"example":{"conversation_id":1,"id":1,"cmd":"sample cmd","macro_id":1,"request_id":1}}}}}},"/api/v1/accounts/{account_id}/maestro/control/pending/reject":{"post":{"tags":["Maestro"],"operationId":"auto_post_api_v1_accounts_account_id_maestro_control_pending_reject","summary":"Reject a parked Robô action","description":"Discards one action the Robô parked for review. The action is never executed. The decision, its rationale and the approver's name are recorded before the parked entry is removed, because a rejection erases the proposal and that record becomes the only evidence it was ever made. An identifier that no longer exists answers `ok: false` rather than an error status.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Whether the action took effect, and a short human-readable outcome. Not an error status - a refusal is part of the normal answer.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","description":"True when the action took effect.","example":true},"state":{"type":"string","enum":["approved","rejected","pending","processing","needs_attention"],"description":"Durable decision result; HTTP 200 with ok false is not a successful execution.","example":"approved"},"detail":{"type":"string","description":"Localized outcome description. Clients must use ok and state to distinguish successful execution from uncertain delivery.","example":"Negócio criado no CRM."},"code":{"type":"string","enum":["maestro_macro_access_denied","maestro_conversation_access_denied","maestro_human_actor_required","maestro_macro_not_found","maestro_conversation_not_found","maestro_human_macro_request_invalid","maestro_human_capability_unavailable","pending_agent_changed","pending_already_processed","pending_approved","pending_authority","pending_channel_changed","pending_conflicting_assignment","pending_consumed_no_effect","pending_credential","pending_delivery_unconfirmed","pending_destination_changed","pending_execution_failed","pending_execution_refused","pending_expired","pending_human_actor","pending_partial","pending_paused","pending_rejected","pending_request_changed","pending_superseded","pending_tenant_mismatch","pending_ui_only","pending_unauthenticated","pending_unavailable","pending_uncertain","pending_unsupported"],"description":"What happened to this attempt, from a closed vocabulary; clients localize it and must not read detail as guidance. maestro_* codes are Chatwoot refusals of a parked macro for this approver before Maestro was asked: nothing ran and the action stays pending. pending_* codes come from Maestro's versioned decision contract, where each one has a disposition: executed or rejected (ok true); not_consumed (refused before the claim, nothing ran, the proposal is unchanged); needs_new_request (nothing ran and this proposal can never run as it stands); not_pending (the proposal is gone and nothing on record says why, so it may have already run: check the conversation history before any new action); consumed_no_effect (the attempt was spent with no effect); uncertain (an effect may have happened, check before any new action and never approve again).","example":"maestro_macro_access_denied"}}},"example":{"ok":true,"detail":"Negócio criado no CRM.","state":"approved","code":"maestro_macro_access_denied"}}}},"401":{"description":"Not signed in, not a member of this account, or the membership was revoked. The account check runs before any Maestro authorization, so nothing is sent to Maestro."},"404":{"description":"Account or resource not found"},"502":{"description":"The Maestro service could not be reached (connection refused or reset, host unresolvable), or it answered in a way the gateway could not use, or it rejected the server-to-server credential — the last one is a deployment key mismatch, never the caller's own session. Nothing was executed; the call can be retried.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"504":{"description":"The Maestro service did not answer within the proxy timeout. The work may still be running on the service side, so retrying a write can duplicate its effect.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"503":{"description":"The Maestro area is not serving this installation: an operator turned it off, or no admin key was ever provisioned. Nothing was executed, and retrying will not help until the configuration changes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"conversation_id":{"type":"integer"},"id":{"type":"integer"},"cmd":{"type":"string"},"macro_id":{"type":"integer"},"request_id":{"type":"integer"}}},"example":{"conversation_id":1,"id":1,"cmd":"sample cmd","macro_id":1,"request_id":1}}}}}},"/api/v1/accounts/{account_id}/maestro/control/paused-inbound":{"get":{"tags":["Maestro"],"operationId":"auto_get_api_v1_accounts_account_id_maestro_control_paused_inbound","summary":"Review input retained during a Maestro pause","description":"Read-only preview of unexpired retained input for an authorized conversation. Requires the same native replay capability as processing: administrators or human agents with a replay grant and access to the writable conversation. No additional role or permission is implied by this read. Returns current native public incoming content in retained order, including eligible expired claim leases and claims belonging to the optional request_id for a retry. The sidecar supplies identities, never authorization: missing, private, outgoing and other-conversation messages are omitted and counted as unavailable. Legacy retention without message identities is also reported unavailable. Reading does not claim, consume, enqueue or replay retained input and does not resume the bot. Processing remains a separate explicitly confirmed action. The dashboard passes preview_token to the separate replay action; a changed cohort is refused with 409 and requires a fresh review. A partial or unavailable preview must not be treated as a complete review. Native media readiness and view-once restrictions apply.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Retained message preview; an empty list is not a processing receipt.","content":{"application/json":{"schema":{"type":"object","required":["messages","unavailable_count","truncated","preview_token"],"additionalProperties":false,"properties":{"messages":{"type":"array","maxItems":100,"items":{"type":"object","additionalProperties":false,"required":["id","content","created_at","content_type"],"properties":{"id":{"type":"integer","minimum":1,"description":"Native message id."},"content":{"type":["string","null"],"description":"Current native display content, including native redaction."},"created_at":{"type":"integer","description":"Unix creation timestamp in seconds."},"content_type":{"type":"string","enum":["text","input_text","input_textarea","input_email","input_select","cards","form","article","incoming_email","input_csat","integrations","sticker","voice_call","poll"],"description":"Structured content type of the message (drives how content_attributes is interpreted)."},"attachments":{"type":"array","description":"Native displayed attachments, omitted when there are none; restricted media may produce an empty list.","items":{"$ref":"#/components/schemas/public_message_attachment"}}}}},"preview_token":{"type":"string","pattern":"^[a-f0-9]{64}$","description":"Scope-bound retained-cohort digest, checked atomically before claiming when supplied to replay."},"unavailable_count":{"type":"integer","minimum":0,"description":"Retention records without usable identities plus referenced messages unavailable under local visibility."},"truncated":{"type":"boolean","description":"True when the bounded preview cannot represent all retained records or identities."}}},"example":{"messages":[{"id":7001,"content":"Please continue our conversation.","created_at":1792930000,"content_type":"text","attachments":[{"id":1,"message_id":1,"file_type":"image","account_id":1,"extension":"sample extension","data_url":"https://example.com/resource","media_readiness_revision":"sample media readiness revision","playable_audio_url":"https://example.com/resource","playable_video_url":"https://example.com/resource","video_processing":true,"video_unavailable":true,"thumb_url":"https://example.com/resource","file_size":1,"width":1,"height":1,"coordinates_lat":12.5,"coordinates_long":12.5,"fallback_title":"sample fallback title","meta":{},"transcribed_text":"sample transcribed text","transcript_translations":{"pt-BR":"Você pode me ajudar?","es":"¿Puedes ayudarme?"},"transcript_translation_states":{}}]}],"preview_token":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","unavailable_count":0,"truncated":false}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"conversation_id","in":"query","required":true,"description":"Account-scoped conversation display id.","schema":{"type":"integer","minimum":1},"example":4821},{"name":"request_id","in":"query","required":false,"description":"Existing replay UUID from an ambiguous attempt; reads its claimed input without renewing or consuming the claim.","schema":{"type":"string","format":"uuid"},"example":"76d70ec8-fe05-43b1-8a1f-d2bb4cc7ad49"}]}},"/api/v1/accounts/{account_id}/maestro/control/paused-inbound/replay":{"post":{"tags":["Maestro"],"operationId":"auto_post_api_v1_accounts_account_id_maestro_control_paused_inbound_replay","summary":"Process retained messages after a confirmed Resume","description":"Processes inbound messages that the Robot retained while a human owned this conversation. This is deliberately separate from Resume: Resume releases only future messages and never invokes this operation implicitly. The platform verifies the conversation belongs to the authenticated account and remains locally active without a human assignee. The caller must explicitly send `confirm: true` and reuse the same UUID when retrying an ambiguous attempt. The dashboard also supplies the optional preview_token from its current review. A changed locked claim cohort is refused with 409 before claiming or scheduling input and requires a fresh review. Existing callers may omit this digest; it never replaces authorization or fences.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The retained queue was scheduled, or no eligible retained message remained.","content":{"application/json":{"schema":{"type":"object","required":["ok","detail"],"properties":{"ok":{"type":"boolean","enum":[true],"description":"True when the explicit replay decision was handled idempotently.","example":true},"detail":{"type":"string","description":"Human-readable outcome from the retained-queue processor.","example":"2 mensagem(ns) pausada(s) agendada(s)"}}},"example":{"ok":true,"detail":"2 mensagem(ns) pausada(s) agendada(s)"}}}},"401":{"description":"Not signed in, not a member of this account, or the membership was revoked. The account check runs before any Maestro authorization, so nothing is sent to Maestro."},"404":{"description":"Account or resource not found"},"502":{"description":"The Maestro service could not be reached (connection refused or reset, host unresolvable), or it answered in a way the gateway could not use, or it rejected the server-to-server credential — the last one is a deployment key mismatch, never the caller's own session. Nothing was executed; the call can be retried.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"504":{"description":"The Maestro service did not answer within the proxy timeout. The work may still be running on the service side, so retrying a write can duplicate its effect.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"503":{"description":"The Maestro area is not serving this installation: an operator turned it off, or no admin key was ever provisioned. Nothing was executed, and retrying will not help until the configuration changes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"409":{"description":"The conversation is still paused, unknown or assigned to a human; nothing was released."},"422":{"description":"Confirmation, conversation id or the UUID idempotency identifier is missing or invalid."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["conversation_id","request_id","confirm"],"properties":{"conversation_id":{"type":"integer","description":"Account-scoped conversation display id resumed immediately before this action.","example":4821},"request_id":{"type":"string","format":"uuid","description":"Idempotency identifier for this replay attempt. Reuse it when retrying after an ambiguous timeout; generate a new UUID only for a new operator decision.","example":"76d70ec8-fe05-43b1-8a1f-d2bb4cc7ad49"},"confirm":{"type":"boolean","enum":[true],"description":"Must be true; Resume never supplies this confirmation automatically.","example":true},"preview_token":{"type":"string","pattern":"^[a-f0-9]{64}$","description":"Optional scope-bound retained-cohort digest returned by the current preview.","example":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"}}},"example":{"conversation_id":4821,"request_id":"76d70ec8-fe05-43b1-8a1f-d2bb4cc7ad49","confirm":true,"preview_token":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"}}}}}},"/api/v1/accounts/{account_id}/maestro/control/{cmd}":{"post":{"tags":["Maestro"],"operationId":"auto_post_api_v1_accounts_account_id_maestro_control_cmd","summary":"Maestro control command","description":"Each human command requires its own maestro_* grant intersected with native conversation, target and operational-scope policy. The role never becomes administrator. Macro uses the existing signed human delegation/native job rather than service impersonation. Delegated resume does not grant context reset. Any effective reset requires both grants and the Robot's reset permission, including fixed policy reset. Before a new delegated reservation, Rails reads current server status with actor_role=agent and requires positive resume_context_permission_supported. Missing/false/failed support returns503 without POST or reservation, never a fallback to an older producer. The server-only context_reset_permitted and actor fields cannot be chosen by browser input. Completed/transitioned same-request recovery preserves the existing receipt/context and never performs an unauthorized new reset. Proxies a validated conversation command to the Maestro sidecar. The path command is one of pause, resume, assume, handoff, conversation-status, priority, labels, attributes, assign, macro, agent or autonomy. The platform injects the authenticated account id; the browser cannot select another tenant. `request_id` is a UUID generated once per semantic attempt and MUST be reused when retrying after an ambiguous timeout, preventing a duplicate state transition. A completed `resume` stores its successful response durably: a retry of that same command and UUID returns the recorded 2xx without calling Maestro again only while the conversation remains unassigned and its local state and revision still match the completion. A different UUID after completion, or the old UUID after a newer takeover, is rejected with 409. For `autonomy`, send one of `autopilot`, `copilot` or `hybrid`; send null to remove the conversation override and inherit the effective Robot's configured mode.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Command accepted by the sidecar, or the exact recorded 2xx for a compatible same-UUID `resume` retry. A recorded retry does not call the sidecar or advance the local revision.","content":{"application/json":{"schema":{"type":"object","required":["ok","detail"],"properties":{"ok":{"type":"boolean","example":true},"detail":{"type":"string","example":"copilot"},"standdown_active":{"type":"boolean","description":"Durable run-state returned for pause, resume, assume and handoff."},"standdown_version":{"type":"integer","description":"Monotonic Maestro generation for the durable run-state."},"standdown_source":{"type":["string","null"]},"standdown_reason":{"type":["string","null"]},"standdown_expires_at":{"type":["string","null"],"format":"date-time"},"standdown_event_cursor":{"type":["integer","null"],"description":"Monotonic platform event cursor observed by Maestro."},"standdown_request_id":{"type":["string","null"],"format":"uuid","description":"Idempotency identifier applied to this run-state transition."}}},"example":{"ok":true,"detail":"copilot","standdown_active":true,"standdown_version":1,"standdown_source":"sample standdown source","standdown_reason":"sample standdown reason","standdown_expires_at":"2026-01-15T10:30:00.000Z","standdown_event_cursor":1,"standdown_request_id":"550e8400-e29b-41d4-a716-446655440000"}}}},"401":{"description":"Not signed in, not a member of this account, or the membership was revoked. The account check runs before any Maestro authorization, so nothing is sent to Maestro."},"404":{"description":"The conversation, or for `macro` the macro id, does not exist in this account. A `team_id` (handoff) or `assignee_id` (assign) that does not exist also answers `maestro_conversation_not_found` today, because the contract has no code for those targets.","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"type":"string"},"code":{"type":"string","enum":["maestro_conversation_not_found","maestro_macro_not_found"]}}},"example":{"error":"This macro does not exist in the current account.","code":"maestro_macro_not_found"}}}},"502":{"description":"The Maestro service could not be reached (connection refused or reset, host unresolvable), or it answered in a way the gateway could not use, or it rejected the server-to-server credential — the last one is a deployment key mismatch, never the caller's own session. Nothing was executed; the call can be retried.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"504":{"description":"The Maestro service did not answer within the proxy timeout. The work may still be running on the service side, so retrying a write can duplicate its effect.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"503":{"description":"The Maestro feature is disabled or not configured, or the platform could not yet confirm a compensating safety pause / authoritative recovery after a concurrent control transition. The local projection remains held fail-closed; retry the same semantic attempt with the same request_id after the dependency recovers. For `macro`, the person's permission could not be checked right now and nothing was sent to Maestro.","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"type":"string"},"code":{"type":"string","enum":["maestro_disabled","maestro_not_configured","maestro_compensation_pending","maestro_state_recovery_pending","maestro_human_capability_unavailable","maestro_resume_permission_unsupported"]}}},"example":{"error":"sample error","code":"maestro_disabled"}}}},"400":{"description":"The path command is outside the supported closed set; nothing was executed.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","enum":["unknown control action"]}}},"example":{"error":"unknown control action"}}}},"409":{"description":"Resume was refused because a human remains assigned or the local state was not a confirmed pause; alternatively, a newer takeover superseded an in-flight Resume and the platform restored the sidecar pause. The local state remains held fail-closed.","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"type":"string"},"code":{"type":"string","enum":["maestro_resume_requires_unassigned","maestro_resume_requires_paused","maestro_request_superseded"]}}},"example":{"error":"sample error","code":"maestro_resume_requires_unassigned"}}}},"403":{"description":"The human lacks the command/reset grant, native target policy or operational scope; no new effect or reservation is authorized. For `macro`, the command runs as the person who sent it, never the service user Maestro calls back with. That person must be a confirmed human account member allowed to see the conversation and run this macro. Native human-delegation refusal codes are preserved alongside the per-action denial; nothing was sent to Maestro.","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"type":"string"},"code":{"type":"string","enum":["maestro_macro_access_denied","maestro_conversation_access_denied","maestro_human_actor_required","maestro_action_forbidden"]}}},"example":{"error":"You are not allowed to run this macro, so nothing was run.","code":"maestro_macro_access_denied"}}}},"422":{"description":"The conversation is missing, the request_id is not a UUID, the human macro request is invalid, or a granular command/argument is invalid. Unknown commands and invalid context_action are rejected before sidecar I/O or reservation; preserved U6 refusal codes remain valid.","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"type":"string"},"code":{"type":"string","enum":["maestro_conversation_required","maestro_request_id_invalid","maestro_human_macro_request_invalid","human_tool_invalid","maestro_action_invalid"]}}},"example":{"error":"Choose a conversation before using Maestro controls.","code":"maestro_conversation_required"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"cmd","in":"path","required":true,"description":"Closed set of supported per-conversation control commands.","schema":{"type":"string","enum":["pause","resume","assume","handoff","conversation-status","priority","labels","attributes","assign","macro","agent","autonomy"]}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["conversation_id"],"properties":{"conversation_id":{"type":"integer","description":"Account-scoped conversation display id.","example":4821},"request_id":{"type":"string","format":"uuid","description":"Idempotency identifier for this semantic attempt. Reuse it when retrying the same command after an ambiguous network failure; generate a new UUID for a new attempt. Required for `pause`, `resume`, `assume` and `handoff`; optional for legacy non-run-state commands.","example":"1d5b85ba-f6be-47d8-82c8-f03af19f6288"},"autonomy_level":{"type":["string","null"],"enum":["autopilot","copilot","hybrid",null],"description":"Effective mode override for `autonomy`; null restores inheritance.","example":"copilot"},"agent_id":{"type":["integer","null"],"description":"Maestro Robot id for `agent`; null clears the Robot override."},"source":{"type":"string","description":"Display-only provenance such as `operator`, never used for authorization.","example":"operator"},"assignee_id":{"type":"integer"},"team_id":{"type":"integer"},"macro_id":{"type":"integer"},"status":{"type":"string","enum":["open","pending","snoozed","resolved"]},"priority":{"type":"string","enum":["urgent","high","medium","low","none"]},"note":{"type":"string"},"labels":{"type":"array","items":{"type":"string"}},"attributes":{"type":"object","description":"Conversation custom-attribute values keyed by attribute name.","additionalProperties":{"oneOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"array","items":{"type":"string"}}]}}}},"example":{"conversation_id":4821,"request_id":"1d5b85ba-f6be-47d8-82c8-f03af19f6288","autonomy_level":"copilot","agent_id":1,"source":"operator","assignee_id":1,"team_id":1,"macro_id":1,"status":"open","priority":"urgent","note":"Sample note.","labels":["sample label"],"attributes":{}}}}}}},"/api/v1/accounts/{account_id}/maestro/copilot/suggest":{"post":{"tags":["Maestro"],"operationId":"auto_post_api_v1_accounts_account_id_maestro_copilot_suggest","summary":"Suggest a reply for a conversation","description":"Delegated humans require their own maestro_suggest grant and native conversation scope, without requiring Ask. A fixed server prompt uses only the current transcript via the bounded analyst; no service contact profile or external sources. The existing suggestion string is preserved, with channel:null. Administrators keep the existing producer. Drafts one reply for the human agent to review. Nothing is sent to the contact. The draft is written in the account's configured language and formatted for the conversation's channel, which is named back so the panel can say what the draft was shaped for.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The drafted reply.","content":{"application/json":{"schema":{"type":"object","properties":{"suggestion":{"type":"string","description":"The drafted reply text, ready to be copied into the composer.","example":"Oi, Marina! Seu pedido"},"channel":{"type":["string","null"],"description":"Friendly name of the channel the draft was formatted for. Null when the channel could not be resolved.","example":"WhatsApp"}}},"example":{"suggestion":"Oi, Marina! Seu pedido","channel":"WhatsApp"}}}},"401":{"description":"Not signed in, not a member of this account, or the membership was revoked. The account check runs before any Maestro authorization, so nothing is sent to Maestro."},"404":{"description":"Account or resource not found"},"502":{"description":"The Maestro service could not be reached (connection refused or reset, host unresolvable), or it answered in a way the gateway could not use, or it rejected the server-to-server credential — the last one is a deployment key mismatch, never the caller's own session. Nothing was executed; the call can be retried.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"504":{"description":"The Maestro service did not answer within the proxy timeout. The work may still be running on the service side, so retrying a write can duplicate its effect.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"503":{"description":"The Maestro area is not serving this installation: an operator turned it off, or no admin key was ever provisioned. Nothing was executed, and retrying will not help until the configuration changes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"conversation_id":{"type":"integer"},"locale":{"type":"string","enum":["en","pt_BR","es"]}}},"example":{"conversation_id":1,"locale":"en"}}}}}},"/api/v1/accounts/{account_id}/maestro/copilot/action":{"post":{"tags":["Maestro"],"operationId":"auto_post_api_v1_accounts_account_id_maestro_copilot_action","summary":"Run a quick copilot action on a conversation","description":"Applies one of the two quick actions the copilot offers on a conversation: labelling it with the supplied value, or resolving it. Answers whether the action took effect with a short outcome text; a refusal is reported in the body rather than as an error status.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Whether the action took effect, and a short human-readable outcome. Not an error status - a refusal is part of the normal answer.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","description":"True when the action took effect.","example":true},"detail":{"type":"string","description":"Short outcome text, shown to the operator as-is.","example":"Negócio criado no CRM."}}},"example":{"ok":true,"detail":"Negócio criado no CRM."}}}},"401":{"description":"Not signed in, not a member of this account, or the membership was revoked. The account check runs before any Maestro authorization, so nothing is sent to Maestro."},"404":{"description":"Account or resource not found"},"502":{"description":"The Maestro service could not be reached (connection refused or reset, host unresolvable), or it answered in a way the gateway could not use, or it rejected the server-to-server credential — the last one is a deployment key mismatch, never the caller's own session. Nothing was executed; the call can be retried.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"504":{"description":"The Maestro service did not answer within the proxy timeout. The work may still be running on the service side, so retrying a write can duplicate its effect.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"503":{"description":"The Maestro area is not serving this installation: an operator turned it off, or no admin key was ever provisioned. Nothing was executed, and retrying will not help until the configuration changes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["conversation_id","action"],"properties":{"conversation_id":{"type":"integer","description":"Conversation the quick action applies to.","example":4821},"action":{"type":"string","description":"Which quick action to run.","enum":["label","resolve"],"example":"label"},"value":{"type":"string","description":"The label to apply. Ignored when resolving.","example":"interessado"}}},"example":{"conversation_id":4821,"action":"label","value":"interessado"}}}}}},"/api/v1/accounts/{account_id}/maestro/copilot/summarize":{"post":{"tags":["Maestro"],"operationId":"auto_post_api_v1_accounts_account_id_maestro_copilot_summarize","summary":"Summarize a conversation","description":"Delegated humans require their own maestro_summarize grant and native conversation scope, without requiring Ask. A fixed server prompt uses only the current transcript via the bounded analyst; no service contact profile or external sources. The existing summary string is preserved, with model:null. Administrators keep the existing producer. Produces a structured digest of the whole conversation for the human agent - what the contact asked, what was decided, what is still open. Nothing is sent to the contact. Written in the account's configured language.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The digest, and which model produced it.","content":{"application/json":{"schema":{"type":"object","properties":{"summary":{"type":"string","description":"The structured digest text.","example":"Contato: Marina Alves. Pedido #1042 atrasado.\nDecidido: reenvio sem custo, prazo de 2 dias.\nEm aberto: confirmar endereço de entrega."},"model":{"type":["string","null"],"description":"The model that produced the digest, informational. Null when it could not be determined.","example":"openai:gpt-5.5"}}},"example":{"summary":"Contato: Marina Alves. Pedido #1042 atrasado.\nDecidido: reenvio sem custo, prazo de 2 dias.\nEm aberto: confirmar endereço de entrega.","model":"openai:gpt-5.5"}}}},"401":{"description":"Not signed in, not a member of this account, or the membership was revoked. The account check runs before any Maestro authorization, so nothing is sent to Maestro."},"404":{"description":"Account or resource not found"},"502":{"description":"The Maestro service could not be reached (connection refused or reset, host unresolvable), or it answered in a way the gateway could not use, or it rejected the server-to-server credential — the last one is a deployment key mismatch, never the caller's own session. Nothing was executed; the call can be retried.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"504":{"description":"The Maestro service did not answer within the proxy timeout. The work may still be running on the service side, so retrying a write can duplicate its effect.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"503":{"description":"The Maestro area is not serving this installation: an operator turned it off, or no admin key was ever provisioned. Nothing was executed, and retrying will not help until the configuration changes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"conversation_id":{"type":"integer"},"locale":{"type":"string","enum":["en","pt_BR","es"]}}},"example":{"conversation_id":1,"locale":"en"}}}}}},"/api/v1/accounts/{account_id}/maestro/copilot/ask":{"post":{"tags":["Maestro"],"operationId":"auto_post_api_v1_accounts_account_id_maestro_copilot_ask","summary":"Ask the Maestro analyst about a conversation","description":"Native maestro_ask grant and effective conversation visibility/scope are required for a human non-administrator. This caller receives transcript-only answers via a server-selected bounded upstream, with used_tools, ui_blocks and citations always empty. Account/conversation/inbox come from the server. Nonempty forced_tools/mentions or plain mode fail with 422 before stream/worker or sidecar I/O. An older sidecar never causes fallback to the broad analyst. Administrators retain the existing free-form analyst using read-only tools over account data and its knowledge base. Nothing is mutated and nothing is sent to the contact. Alongside the prose answer the response can carry action cards the panel renders - a drafted message, or a proposal whose Confirm button runs the named write tool through the execute endpoint. When the answer was grounded in the knowledge base, the sources behind it are listed so the reader can check them. With Accept: text/event-stream, the response commits HTTP 200 before the analyst finishes. Comment-only keep-alives maintain the connection. A result event carries the same JSON answer; an error event carries status, code and error instead of changing the committed HTTP status. Before commit, authentication and configuration failures remain ordinary HTTP errors. The application/json mode remains available to existing clients.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The analyst's answer, the tools it used, any cards to render, and its sources.","content":{"application/json":{"schema":{"type":"object","properties":{"answer":{"type":"string","description":"The prose answer, in the requested language.","example":"O pedido"},"used_tools":{"type":"array","description":"Names of the read-only tools the analyst called to compose the answer.","items":{"type":"string"},"example":["commerce_find_order","kb_search"]},"ui_blocks":{"type":"array","description":"Cards for the panel to render. Empty on a plain prose answer. Each card is discriminated by `type`; the fields beyond `type` and `action` differ per card, and a client that does not know a type ignores that card.","items":{"type":"object","description":"One card. Its remaining fields depend on `type` - a drafted message carries the text, a deal proposal carries the deal fields, and so on.","additionalProperties":true,"properties":{"type":{"type":"string","description":"Which card this is, and therefore which other fields it carries.","enum":["message_suggestion","crm_deal","calendar_booking","catalog_product","generate_image","generate_video","voice_reply","task","tools_catalog"],"example":"crm_deal"},"action":{"type":"object","description":"What the card's Confirm button runs. Absent on purely informative cards such as a drafted message or the tools catalogue.","properties":{"tool":{"type":"string","description":"The write tool the confirmation executes.","example":"crm_create_deal"},"args":{"type":"object","description":"Arguments the analyst resolved for that tool. Keys and value types are the tool's own; the conversation is linked server-side and is never listed here.","additionalProperties":true,"example":{"title":"Plano anual - Acme","value_amount":4800}},"label":{"type":"string","description":"Suggested button label. Empty when the panel should pick its own.","example":"Criar negócio"}}}}}},"citations":{"type":"array","description":"Knowledge base sources that grounded the answer. Empty when it was not grounded in the knowledge base. Only source labels are returned, never chunk text.","items":{"type":"object","properties":{"source":{"type":"string","description":"Label of the knowledge base source behind the answer.","example":"politica-de-trocas.pdf"}}}}}},"example":{"answer":"O pedido","used_tools":["commerce_find_order","kb_search"],"ui_blocks":[{"type":"crm_deal","action":{"tool":"crm_create_deal","args":{"title":"Plano anual - Acme","value_amount":4800},"label":"Criar negócio"}}],"citations":[{"source":"politica-de-trocas.pdf"}]}},"text/event-stream":{"schema":{"type":"string","description":"SSE frames. Comments carry no data. Event result has the JSON answer shown above. Event error has integer status and a stable code: maestro_timeout (504), maestro_unreachable, maestro_error or maestro_auth_failed (502). Other non-success sidecar validation statuses can be reported with maestro_error. A committed stream stays HTTP 200, including an error event; the client must inspect its terminal event."},"example":": connected\n\n: keep-alive\n\nevent: result\ndata: {\"answer\":\"The appointment is tomorrow.\",\"used_tools\":[],\"ui_blocks\":[],\"citations\":[]}"}}},"401":{"description":"Not signed in, not a member of this account, or the membership was revoked. The account check runs before any Maestro authorization, so nothing is sent to Maestro."},"404":{"description":"Account or resource not found"},"502":{"description":"The Maestro service could not be reached (connection refused or reset, host unresolvable), or it answered in a way the gateway could not use, or it rejected the server-to-server credential — the last one is a deployment key mismatch, never the caller's own session. Nothing was executed; the call can be retried.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"504":{"description":"The Maestro service did not answer within the proxy timeout. The work may still be running on the service side, so retrying a write can duplicate its effect.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"503":{"description":"The Maestro area is not serving this installation: an operator turned it off, or no admin key was ever provisioned. Nothing was executed, and retrying will not help until the configuration changes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"403":{"description":"The action grant, conversation policy or operational scope denies this question, or the account member is not a human user. No stream/worker or sidecar I/O.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["maestro_action_forbidden"]}}},"example":{"error":"sample error","code":"maestro_action_forbidden"}}}},"422":{"description":"A bounded question requested tools/entities or plain mode (maestro_ask_scope_invalid), or omitted a positive conversation. Refused before streaming."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"in":"header","name":"Accept","required":false,"description":"Select text/event-stream with positive valid qvalue for Live. Tokens are case-insensitive; q=0, malformed quality and other media types keep JSON. Any Accept containing double quotes also keeps JSON.","schema":{"type":"string"},"example":"text/event-stream"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"conversation_id":{"type":"integer","description":"Positive authorized conversation display id. Unlinked questions remain administrator-only.","example":42},"inbox_id":{"type":"integer","description":"Inbox context when the question is not linked to a conversation.","example":12},"question":{"type":"string","description":"The human's read-only question.","example":"What was agreed in this conversation?"},"locale":{"type":"string","description":"Language for the answer.","example":"en"},"history":{"type":"array","description":"Prior question and answer turns in this panel.","items":{"type":"object","properties":{"role":{"type":"string","enum":["user","assistant"],"example":"user"},"content":{"type":"string","example":"What does the customer need?"}}}},"forced_tools":{"type":"array","description":"Administrator-only tool/skill handles. Non-administrators must omit this field or send an empty array.","items":{"type":"string"},"example":["@kb_search"]},"mentions":{"type":"array","description":"Administrator-only entity references. Non-administrators must omit this field or send an empty array.","items":{"type":"object","properties":{"type":{"type":"string","description":"Entity namespace.","example":"contact"},"id":{"type":"integer","description":"Entity reference when available.","example":9},"label":{"type":"string","example":"Contact"}}}}}},"example":{"conversation_id":42,"inbox_id":12,"question":"What was agreed in this conversation?","locale":"en","history":[{"role":"user","content":"What does the customer need?"}],"forced_tools":["@kb_search"],"mentions":[{"type":"contact","id":9,"label":"Contact"}]}}}}}},"/api/v1/accounts/{account_id}/maestro/copilot/suggestions":{"post":{"tags":["Maestro"],"operationId":"auto_post_api_v1_accounts_account_id_maestro_copilot_suggestions","summary":"List the copilot quick actions for a conversation","description":"The quick actions this conversation's Robô can actually perform, as ordered capability keys the panel renders as starter chips. Gated by that Robô's configuration: a generative key appears only when its section is enabled and the installation-wide switch is on, and a write key only when its tool is enabled - so a chip never offers something that would then be refused. Drafting, summarizing and the capabilities catalogue are always offered because they have no side effect, and the response degrades to those three if the Robô cannot be resolved. The panel supplies the label and the prompt for each key.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The capability keys to offer, in display order.","content":{"application/json":{"schema":{"type":"object","properties":{"suggestions":{"type":"array","description":"Ordered capability keys. `suggest_reply`, `summarize` and `capabilities` are always present; the rest appear only when the Robô is configured for them.","items":{"type":"string","enum":["suggest_reply","generate_image","send_voice","generate_video","create_deal","schedule","send_product","create_task","summarize","capabilities"]},"example":["suggest_reply","create_deal","summarize","capabilities"]}}},"example":{"suggestions":["suggest_reply","create_deal","summarize","capabilities"]}}}},"401":{"description":"Not signed in, not a member of this account, or the membership was revoked. The account check runs before any Maestro authorization, so nothing is sent to Maestro."},"404":{"description":"Account or resource not found"},"502":{"description":"The Maestro service could not be reached (connection refused or reset, host unresolvable), or it answered in a way the gateway could not use, or it rejected the server-to-server credential — the last one is a deployment key mismatch, never the caller's own session. Nothing was executed; the call can be retried.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"504":{"description":"The Maestro service did not answer within the proxy timeout. The work may still be running on the service side, so retrying a write can duplicate its effect.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"503":{"description":"The Maestro area is not serving this installation: an operator turned it off, or no admin key was ever provisioned. Nothing was executed, and retrying will not help until the configuration changes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"conversation_id":{"type":"integer"},"locale":{"type":"string","enum":["en","pt_BR","es"]}}},"example":{"conversation_id":1,"locale":"en"}}}}}},"/api/v1/accounts/{account_id}/maestro/copilot/execute":{"post":{"tags":["Maestro"],"operationId":"auto_post_api_v1_accounts_account_id_maestro_copilot_execute","summary":"Run a confirmed copilot action card","description":"Non-administrators with maestro_execute are limited to sales_get_leaderboard, sales_recognize, sales_list_deal_approvals and sales_decide_deal_approval. Canonical Sales target arguments, feature, native manager/owner scope or DealApprovalPolicy are checked BEFORE mint/sidecar I/O; the existing signed human consumer checks again at execution. Unknown tools/targets do not fall back to service. action_id follows the native HumanToolCapability pattern; proposed_at must be a positive integer no older than 3600 seconds or more than 60 seconds in the future. Administrators retain existing behavior. Runs the single tool after human confirmation. This is never an arbitrary tool runner: the tool must be one the proposal cards can offer AND enabled for this conversation's Robô, the arguments are validated against that tool's own schema, and the qualified Sales call runs under signed human authority so native permissions still apply. Protected Sales actions additionally receive a short-lived, exact-action capability minted server-side; the browser never supplies or receives that proof, and retries reuse `action_id` so the effect can be deduplicated. The response echoes who ran it, for the audit trail. A downstream tool failure is reported as `ok: false` with the reason rather than as an error status.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Whether the action took effect, with a short outcome and the acting user.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","description":"True when the tool ran successfully.","example":true},"detail":{"type":"string","description":"Short outcome text, shown to the operator as-is.","example":"Negócio criado no CRM."},"executed_by":{"type":["string","null"],"description":"Name of the human who confirmed and ran the card, echoed for the audit trail. Null when the caller supplied none.","example":"Ana Souza"}}},"example":{"ok":true,"detail":"Negócio criado no CRM.","executed_by":"Ana Souza"}}}},"401":{"description":"Not signed in, not a member of this account, or the membership was revoked. The account check runs before any Maestro authorization, so nothing is sent to Maestro."},"404":{"description":"Account or resource not found"},"502":{"description":"The Maestro service could not be reached (connection refused or reset, host unresolvable), or it answered in a way the gateway could not use, or it rejected the server-to-server credential — the last one is a deployment key mismatch, never the caller's own session. Nothing was executed; the call can be retried.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"504":{"description":"The Maestro service did not answer within the proxy timeout. The work may still be running on the service side, so retrying a write can duplicate its effect.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"503":{"description":"The Maestro area is not serving this installation: an operator turned it off, or no admin key was ever provisioned. Nothing was executed, and retrying will not help until the configuration changes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"410":{"description":"The proposal card is too old to run. A card left open while the conversation moved on is refused rather than fired out of context; ask the Robô again to get a fresh one."},"403":{"description":"The account member is not a human user, or the same action id was rebound to different effect arguments. No capability was issued and no Sales effect ran."},"422":{"description":"A protected Sales action has an invalid action id or arguments and was refused before the request reached the Maestro service."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["conversation_id","tool"],"properties":{"conversation_id":{"type":"integer","description":"Conversation the confirmed card belongs to.","example":4821},"tool":{"type":"string","description":"The write tool the card proposes. Only tools a proposal card can offer AND that are enabled for this conversation's Robô are accepted.","example":"generate_image"},"args":{"type":"object","additionalProperties":true,"description":"Arguments for that tool, exactly as the card resolved them. They are validated against the tool's own schema before anything runs; the conversation is linked server-side, so it is never passed here.","example":{"prompt":"Promotional image of the winter combo, warm lighting","caption":"Nosso combo de inverno"}},"action_id":{"type":"string","format":"uuid","description":"Stable identity of this confirmed card. A transport retry of the same card must reuse it; a newly proposed action receives another value. Required for protected Sales actions.","example":"11111111-1111-4111-8111-111111111111"},"proposed_at":{"type":"integer","format":"int64","description":"Unix timestamp created with the card and reused on retries.","example":1788746400}}},"example":{"conversation_id":4821,"tool":"generate_image","args":{"prompt":"Promotional image of the winter combo, warm lighting","caption":"Nosso combo de inverno"},"action_id":"11111111-1111-4111-8111-111111111111","proposed_at":1788746400}}}}}},"/api/v1/accounts/{account_id}/maestro/copilot/generate-preview":{"post":{"tags":["Maestro"],"operationId":"auto_post_api_v1_accounts_account_id_maestro_copilot_generate_preview","summary":"Generate a media preview before sending it","description":"Requires maestro_generate and native conversation visibility. Non-administrators are limited to text-only input. send_voice accepts only nonblank text; generate_image accepts prompt, caption, aspect_ratio, image_quality and image_resolution; generate_video accepts prompt, caption, aspect_ratio, integer duration_seconds and video_resolution. Unknown keys/types and active references fail 422 maestro_preview_arguments_invalid BEFORE sidecar I/O/reservations. Non-administrator tool/args must come from the JSON body: either key in the URL query is invalid with the same422 before references, downloads, reservation or cost. Dispatch uses exactly the validated JSON tool/args, with account/conversation identity injected by the server; a merged query/body representation cannot replace the validated generation data. Administrative generation retains its existing broad contract. For image, optional reference fields must be references:[], conversation_image_ids:[], use_inbound_image:false and use_contact_avatar:false. For video they must be reference:\"\", conversation_image_id:null, use_inbound_image:false and use_contact_avatar:false. Image aspect ratios: 1:1,1:4,1:8,2:3,3:2,3:4,4:1,4:3,4:5,5:4,8:1,9:16,16:9,21:9; quality: auto,low,medium,high; resolution: 0.5K,1K,2K,4K. Video aspect ratios: 16:9,9:16; duration: 4,6,8,12; resolution: 720p,1024p,1080p,4k. Options also remain subject to the configured provider. Administrators retain the full reference schema below. Renders the image, voice note or video, so a human sees exactly what the contact would receive. Image and voice come back inline as a data URI. Video and heavier image renders run in the background and answer immediately with `pending: true` and a handle - poll the preview status route, then stream the asset - so a long render can never time the request out. What was previewed is what the send-prepared route delivers, byte for byte; nothing is regenerated at send time.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The rendered preview, or the handle of one still rendering, or the failure reason.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","description":"True when the preview was produced or accepted for background rendering.","example":true},"kind":{"type":"string","description":"What was generated. Empty when nothing was.","enum":["","image","audio","video"],"example":"image"},"data_uri":{"type":"string","description":"The rendered asset inline, as a data URI. Empty for a background render - use the handle instead.","example":"data:image/png;base64,iVBORw0KGgoAAAANSUhEUg=="},"mime":{"type":"string","description":"Media type of the rendered asset. Empty when nothing was produced inline.","example":"image/png"},"caption":{"type":"string","description":"Caption proposed alongside the asset. Empty when none.","example":"Nosso combo de inverno"},"text":{"type":"string","description":"For a voice preview, the spoken text, echoed so the card can adjust and re-render it. Empty otherwise.","example":""},"preview_id":{"type":"string","description":"Handle for a background render - poll the preview status route with it, then stream the asset. Empty for an inline preview.","example":""},"pending":{"type":"boolean","description":"True when the asset is still rendering and must be polled.","example":false},"error":{"type":"string","description":"Short failure reason. Empty when the preview succeeded.","example":""}}},"example":{"ok":true,"kind":"image","data_uri":"data:image/png;base64,iVBORw0KGgoAAAANSUhEUg==","mime":"image/png","caption":"Nosso combo de inverno","text":"","preview_id":"","pending":false,"error":""}}}},"401":{"description":"Not signed in, not a member of this account, or the membership was revoked. The account check runs before any Maestro authorization, so nothing is sent to Maestro."},"404":{"description":"Account or resource not found"},"502":{"description":"The Maestro service could not be reached (connection refused or reset, host unresolvable), or it answered in a way the gateway could not use, or it rejected the server-to-server credential — the last one is a deployment key mismatch, never the caller's own session. Nothing was executed; the call can be retried.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"504":{"description":"The Maestro service did not answer within the proxy timeout. The work may still be running on the service side, so retrying a write can duplicate its effect.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"503":{"description":"The Maestro area is not serving this installation: an operator turned it off, or no admin key was ever provisioned. Nothing was executed, and retrying will not help until the configuration changes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"403":{"description":"Missing generation grant or native conversation scope; zero sidecar I/O."},"422":{"description":"Invalid text-only args, references, unknown fields, types or options; code maestro_preview_arguments_invalid, zero sidecar I/O."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["conversation_id","tool"],"properties":{"conversation_id":{"type":"integer","description":"Conversation the preview belongs to. The asset is never sent to it here.","example":4821},"tool":{"type":"string","description":"Which generative tool to preview.","enum":["generate_image","generate_video","send_voice"],"example":"generate_image"},"args":{"type":"object","additionalProperties":true,"description":"Arguments for the chosen tool. `generate_image` takes `prompt`, `caption`, `aspect_ratio`, `image_quality` (OpenAI models only), `image_resolution` (Google models only), `references` (Media Library asset names or image URLs), `conversation_image_ids`, `use_inbound_image` and `use_contact_avatar`. `generate_video` takes `prompt`, `caption`, `aspect_ratio`, `duration_seconds`, `video_resolution` and ONE reference source (`reference`, `conversation_image_id`, `use_inbound_image` or `use_contact_avatar`). `send_voice` takes `text`. Every render option is checked against the robot's configured provider/model — one it does not support is refused with `unsupported_render_options` rather than silently ignored.","example":{"prompt":"Promotional image of the winter combo, warm lighting","caption":"Nosso combo de inverno","aspect_ratio":"16:9","image_resolution":"1K","references":["https://app.example.com/rails/active_storage/blobs/redirect/abc/brand.png"]}}}},"example":{"conversation_id":4821,"tool":"generate_image","args":{"prompt":"Promotional image of the winter combo, warm lighting","caption":"Nosso combo de inverno","aspect_ratio":"16:9","image_resolution":"1K"}}}}}}},"/api/v1/accounts/{account_id}/maestro/copilot/preview-status":{"get":{"tags":["Maestro"],"operationId":"auto_get_api_v1_accounts_account_id_maestro_copilot_preview_status","summary":"Poll a background media preview","description":"Requires preview_read, derived from generate OR send_prepared and native conversation scope. A handle from another conversation is opaque (ready:false); no generation grant is implied. Reports whether the asset behind a preview handle has finished rendering. Both flags false means it is still running and the caller should poll again. Once ready, stream the bytes from the preview asset route and deliver them with send-prepared.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Whether the render has finished, and whether it failed.","content":{"application/json":{"schema":{"type":"object","properties":{"ready":{"type":"boolean","description":"True once the rendered asset can be streamed.","example":true},"error":{"type":"boolean","description":"True when the render failed. Both flags false means it is still running.","example":false}}},"example":{"ready":true,"error":false}}}},"401":{"description":"Not signed in, not a member of this account, or the membership was revoked. The account check runs before any Maestro authorization, so nothing is sent to Maestro."},"404":{"description":"Account or resource not found"},"502":{"description":"The Maestro service could not be reached (connection refused or reset, host unresolvable), or it answered in a way the gateway could not use, or it rejected the server-to-server credential — the last one is a deployment key mismatch, never the caller's own session. Nothing was executed; the call can be retried.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"504":{"description":"The Maestro service did not answer within the proxy timeout. The work may still be running on the service side, so retrying a write can duplicate its effect.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"503":{"description":"The Maestro area is not serving this installation: an operator turned it off, or no admin key was ever provisioned. Nothing was executed, and retrying will not help until the configuration changes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"preview_id","in":"query","required":true,"description":"Identifier returned when the preview was requested — it is what is polled.","schema":{"type":"string"},"example":"prev_7c1a"},{"name":"conversation_id","in":"query","required":false,"description":"Conversation the preview was generated for.","schema":{"type":"integer"},"example":4821}]}},"/api/v1/accounts/{account_id}/maestro/copilot/preview-asset/{preview_id}":{"get":{"tags":["Maestro"],"operationId":"auto_get_api_v1_accounts_account_id_maestro_copilot_preview_asset_preview_id","summary":"Copilot preview asset maestro","description":"Performs the copilot preview asset operation on the targeted maestro resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"File download","content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"401":{"description":"Not signed in, not a member of this account, or the membership was revoked. The account check runs before any Maestro authorization, so nothing is sent to Maestro."},"404":{"description":"Account or resource not found"},"502":{"description":"The Maestro service could not be reached (connection refused or reset, host unresolvable), or it answered in a way the gateway could not use, or it rejected the server-to-server credential — the last one is a deployment key mismatch, never the caller's own session. Nothing was executed; the call can be retried.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"504":{"description":"The Maestro service did not answer within the proxy timeout. The work may still be running on the service side, so retrying a write can duplicate its effect.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"503":{"description":"The Maestro area is not serving this installation: an operator turned it off, or no admin key was ever provisioned. Nothing was executed, and retrying will not help until the configuration changes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"preview_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"conversation_id","in":"query","required":true,"description":"Authorized account-scoped conversation display id; the preview must belong to this exact conversation.","schema":{"type":"integer","minimum":1},"example":4821}]}},"/api/v1/accounts/{account_id}/maestro/copilot/send-prepared":{"post":{"tags":["Maestro"],"operationId":"auto_post_api_v1_accounts_account_id_maestro_copilot_send_prepared","summary":"Send a previewed asset to the contact","description":"Requires the separate maestro_send_prepared grant and native Messages/show/writable target policy. The server binds the handle to the authorized account/conversation; cross-conversation, missing or expired handles remain opaque. No generation permission or human impersonation is implied. Delivers the exact asset a human already previewed - the image or audio bytes supplied inline, or the rendered video behind a preview handle. Nothing is regenerated, so what was approved is what the contact receives. Answers whether the message went out with a short outcome; a refusal is reported in the body rather than as an error status.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Whether the action took effect, and a short human-readable outcome. Not an error status - a refusal is part of the normal answer.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","description":"True when the action took effect.","example":true},"detail":{"type":"string","description":"Short outcome text, shown to the operator as-is.","example":"Negócio criado no CRM."}}},"example":{"ok":true,"detail":"Negócio criado no CRM."}}}},"401":{"description":"Not signed in, not a member of this account, or the membership was revoked. The account check runs before any Maestro authorization, so nothing is sent to Maestro."},"404":{"description":"Account or resource not found"},"502":{"description":"The Maestro service could not be reached (connection refused or reset, host unresolvable), or it answered in a way the gateway could not use, or it rejected the server-to-server credential — the last one is a deployment key mismatch, never the caller's own session. Nothing was executed; the call can be retried.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"504":{"description":"The Maestro service did not answer within the proxy timeout. The work may still be running on the service side, so retrying a write can duplicate its effect.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"503":{"description":"The Maestro area is not serving this installation: an operator turned it off, or no admin key was ever provisioned. Nothing was executed, and retrying will not help until the configuration changes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["conversation_id","kind"],"properties":{"conversation_id":{"type":"integer","description":"Conversation that receives the asset.","example":4821},"kind":{"type":"string","description":"Which previewed asset is being delivered.","enum":["image","audio","video"],"example":"image"},"data_uri":{"type":"string","description":"The previewed bytes inline, for an asset that was returned inline. Empty when the render used a handle.","example":""},"preview_id":{"type":"string","description":"Handle of a background render, whose stored bytes are delivered verbatim. Empty when the bytes ride inline.","example":"prev_7c1a"},"caption":{"type":"string","description":"Caption to send alongside the asset.","example":"Nosso combo de inverno"},"text":{"type":"string","description":"For a voice note, the spoken text — informational, already synthesized.","example":""},"is_voice":{"type":"boolean","description":"True to deliver an audio asset as a native voice note rather than a file.","example":false}}},"example":{"conversation_id":4821,"kind":"image","preview_id":"prev_7c1a","caption":"Nosso combo de inverno","data_uri":"","text":"","is_voice":false}}}}}},"/api/v1/accounts/{account_id}/maestro/copilot/transcribe":{"post":{"tags":["Maestro"],"operationId":"auto_post_api_v1_accounts_account_id_maestro_copilot_transcribe","summary":"Transcribe a dictated audio clip","description":"Turns a recorded clip into text for the human agent to review - the microphone button in the reply composer and in the Maestro panel. Nothing is sent to the contact. The clip rides as base64 because this proxy forwards every call as JSON. The account's configured language is applied server-side as the transcription hint, so the result follows the account setting regardless of the dashboard language of whoever is dictating.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The transcribed text.","content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string","description":"The transcript, for the human to review and edit before using it.","example":"Bom dia, poderia confirmar o endereço de entrega, por favor?"}}},"example":{"text":"Bom dia, poderia confirmar o endereço de entrega, por favor?"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"502":{"description":"The Maestro service could not be reached (connection refused or reset, host unresolvable), or it answered in a way the gateway could not use, or it rejected the server-to-server credential — the last one is a deployment key mismatch, never the caller's own session. Nothing was executed; the call can be retried.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"504":{"description":"The Maestro service did not answer within the proxy timeout. The work may still be running on the service side, so retrying a write can duplicate its effect.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"503":{"description":"The Maestro area is not serving this installation: an operator turned it off, or no admin key was ever provisioned. Nothing was executed, and retrying will not help until the configuration changes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"400":{"description":"The audio was missing or was not valid base64."},"413":{"description":"The decoded clip is larger than the per-dictation limit of 25 MB."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"conversation_id":{"type":"integer"},"audio_base64":{"type":"string"},"filename":{"type":"string"},"locale":{"type":"string"}}},"example":{"conversation_id":1,"audio_base64":"sample audio base64","filename":"sample filename","locale":"en"}}}}}},"/api/v1/accounts/{account_id}/maestro/surfaces":{"get":{"tags":["Maestro"],"operationId":"auto_get_api_v1_accounts_account_id_maestro_surfaces","summary":"List the account's per-surface Robô assignments","description":"Every account-scoped surface that calls a model OUTSIDE a conversation turn — the Brain interview, the agent copilot, the rolling summary, the improvement judge, the generative dashboards, the realtime call and the knowledge-base embeddings — with the Robô assigned to it, or none. Always the FULL list, including surfaces with no assignment: \"nothing is pointed here\" and \"that surface does not exist\" are different answers, and a screen that renders only what was configured can only show the first as the second.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Every surface of the account, assigned or not.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_surfaces"},"example":{"account_id":7,"surfaces":[{"surface":"brain","agent_id":42,"agent_name":"Atendimento","enabled":true,"assigned":true,"cost_sensitive":false,"requires_independence":false,"updated_at":"2026-07-27T14:03:00Z"}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"502":{"description":"The Maestro service could not be reached (connection refused or reset, host unresolvable), or it answered in a way the gateway could not use, or it rejected the server-to-server credential — the last one is a deployment key mismatch, never the caller's own session. Nothing was executed; the call can be retried.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"504":{"description":"The Maestro service did not answer within the proxy timeout. The work may still be running on the service side, so retrying a write can duplicate its effect.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"503":{"description":"The Maestro area is not serving this installation: an operator turned it off, or no admin key was ever provisioned. Nothing was executed, and retrying will not help until the configuration changes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]},"put":{"tags":["Maestro"],"operationId":"auto_put_api_v1_accounts_account_id_maestro_surfaces","summary":"Replace the account's per-surface Robô assignments","description":"Full-set replacement: what is not sent is removed. Every referenced Robô must belong to this account — a cross-account assignment would run one account's surface on another's key and quota, and is refused with 422. Returns the resulting full list, so the screen renders the truth the server stored rather than what it hoped it stored.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The resulting assignments (full list).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_surfaces"},"example":{"account_id":7,"surfaces":[{"surface":"brain","agent_id":42,"agent_name":"Atendimento","enabled":true,"assigned":true,"cost_sensitive":false,"requires_independence":false,"updated_at":"2026-07-27T14:03:00Z"}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"502":{"description":"The Maestro service could not be reached (connection refused or reset, host unresolvable), or it answered in a way the gateway could not use, or it rejected the server-to-server credential — the last one is a deployment key mismatch, never the caller's own session. Nothing was executed; the call can be retried.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"504":{"description":"The Maestro service did not answer within the proxy timeout. The work may still be running on the service side, so retrying a write can duplicate its effect.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"503":{"description":"The Maestro area is not serving this installation: an operator turned it off, or no admin key was ever provisioned. Nothing was executed, and retrying will not help until the configuration changes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"422":{"description":"An assignment names an unknown surface, or a Robô from another account."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"assignments":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Free-form object."}}}},"example":{"assignments":[{}]}}}}}},"/api/v1/accounts/{account_id}/maestro/agents/{id}/surfaces":{"get":{"tags":["Maestro"],"operationId":"auto_get_api_v1_accounts_account_id_maestro_agents_id_surfaces","summary":"List the surfaces THIS Robô serves","description":"The \"where is this Robô used\" list the agent screen renders next to its configuration, so changing a model or a key shows what else it affects before the change is saved.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The surfaces this Robô is assigned to (empty when it serves none).","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/maestro_surface_assignment"}},"example":[{"surface":"brain","agent_id":42,"agent_name":"Atendimento","enabled":true,"assigned":true,"cost_sensitive":false,"requires_independence":false,"updated_at":"2026-07-27T14:03:00Z"}]}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"502":{"description":"The Maestro service could not be reached (connection refused or reset, host unresolvable), or it answered in a way the gateway could not use, or it rejected the server-to-server credential — the last one is a deployment key mismatch, never the caller's own session. Nothing was executed; the call can be retried.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"504":{"description":"The Maestro service did not answer within the proxy timeout. The work may still be running on the service side, so retrying a write can duplicate its effect.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"503":{"description":"The Maestro area is not serving this installation: an operator turned it off, or no admin key was ever provisioned. Nothing was executed, and retrying will not help until the configuration changes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/maestro/verification/turns":{"get":{"tags":["Maestro"],"operationId":"auto_get_api_v1_accounts_account_id_maestro_verification_turns","summary":"List Robô turns for verification","description":"The account's Robô turns, newest first, as timeline rows - enough to spot the interesting one, with the full record one call away. Optionally narrowed to one conversation or one outcome status. Counts rather than contents: a row says how many tools ran, how many failed and how many claims the reconciliation could not back, and the detail route answers which. No customer data is returned - the record deliberately stores tool names, statuses and a reply hash, never the text. The page cap is echoed back so a caller can see the ceiling that produced its page.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"A page of turns, newest first, with the cap that produced it.","content":{"application/json":{"schema":{"type":"object","properties":{"account_id":{"type":"integer","description":"The account the turns belong to.","example":1},"limit":{"type":"integer","description":"Maximum rows this page could contain. Capped at 200.","example":50},"turns":{"type":"array","description":"The turns, newest first.","items":{"type":"object","properties":{"turn_id":{"type":"string","description":"Identifier of the turn, used to fetch its full record.","example":"t_9f21ac4e7b"},"conversation_id":{"type":"integer","description":"Conversation the turn happened on, by its per-account display number.","example":1042},"agent_id":{"type":["integer","null"],"description":"The Robô that ran the turn. Null when it could not be attributed.","example":12},"inbox_id":{"type":["integer","null"],"description":"Inbox the conversation belongs to. Null when unknown.","example":3},"channel":{"type":["string","null"],"description":"Channel the turn was delivered on. Null when unknown.","example":"whatsapp"},"status":{"type":"string","description":"What the verification layer did with the reply. `passed` delivered it as written; `softened` and `stripped` edited it; `regenerated` replaced it; `held` parked it for human approval instead of delivering it; `blocked` stopped it; `judge_flagged` delivered it but the asynchronous review objected afterwards. `failed` is the one value that is not a verdict: the turn produced no reply - it raised, or it ended with nothing to deliver.","enum":["passed","softened","stripped","regenerated","held","blocked","judge_flagged","failed"],"example":"passed"},"failure_reason":{"type":["string","null"],"maxLength":64,"pattern":"^[a-z_]+(:[A-Za-z0-9_.]+)?$","description":"Why the turn did not end normally, as recorded: a kind, optionally followed by a colon and a detail - never customer data. Null on a turn that ended normally. The set is open: a consumer must treat a value it does not know as opaque. Known values on `failed` rows: `stt_failed`, `tool_call_leak`, `delivery_exhausted`, `empty_reply`, `missing_key:\u003cprovider\u003e`, `permanent:\u003cExceptionClass\u003e`, `transient:\u003cExceptionClass\u003e`, `retry_scheduled:tool_call_leak` and `retry_scheduled:delivery_incomplete`. Known values on `blocked` rows: `standdown_at_send`, `standdown_before_transport`, `standdown_between_transports`, `superseded`, `verification_failed`, `unverified_reply_removed` and `unfulfilled_deferral`.","example":null},"retried":{"type":"boolean","description":"True exactly when `failure_reason` starts with `retry_scheduled:` - the row is an attempt that scheduled its own retry. Its `status` still says `failed`, but it is not how the turn ended: the retry ran under another `turn_id`, and that row is the outcome. False does not prove the opposite: a `transient:\u003cExceptionClass\u003e` attempt may also have been re-buffered and run again under another `turn_id`. Never null.","example":false},"created_at":{"type":"string","format":"date-time","description":"When the turn was recorded.","example":"2026-07-27T14:03:11Z"},"calls":{"type":"integer","description":"Model calls the turn consumed.","example":2},"input_tokens":{"type":"integer","description":"Prompt tokens billed for the turn.","example":3184},"output_tokens":{"type":"integer","description":"Completion tokens billed for the turn.","example":212},"cache_read_tokens":{"type":"integer","description":"Prompt tokens served from cache rather than billed at full rate.","example":2560},"cost_usd":{"type":"number","description":"Cost of the turn in US dollars.","example":0.0143},"latency_ms":{"type":"integer","description":"Wall-clock duration of the turn in milliseconds.","example":2840},"tools_run":{"type":"integer","description":"Tools the turn called.","example":2},"tools_failed":{"type":"integer","description":"Tool calls that failed, were refused or were not executed in the turn. Counted on their own, not as a share of `tools_run`.","example":1},"claims_flagged":{"type":"integer","description":"Statements in the reply the reconciliation could not back with evidence.","example":0},"judge_score":{"type":["number","null"],"description":"Score from the asynchronous review, when this turn was sampled for one. Null when it was not reviewed.","example":0.94},"resolved_at":{"type":["string","null"],"format":"date-time","description":"When a human resolved a held reply. Null when the turn never waited on one.","example":null},"resolved_by":{"type":["string","null"],"description":"Name of the human who resolved it. Null when nobody had to.","example":null}}}}}},"example":{"account_id":1,"limit":50,"turns":[{"turn_id":"t_9f21ac4e7b","conversation_id":1042,"agent_id":12,"inbox_id":3,"channel":"whatsapp","status":"passed","failure_reason":null,"retried":false,"created_at":"2026-07-27T14:03:11Z","calls":2,"input_tokens":3184,"output_tokens":212,"cache_read_tokens":2560,"cost_usd":0.0143,"latency_ms":2840,"tools_run":2,"tools_failed":1,"claims_flagged":0,"judge_score":0.94,"resolved_at":null,"resolved_by":null}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"502":{"description":"The Maestro service could not be reached (connection refused or reset, host unresolvable), or it answered in a way the gateway could not use, or it rejected the server-to-server credential — the last one is a deployment key mismatch, never the caller's own session. Nothing was executed; the call can be retried.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"504":{"description":"The Maestro service did not answer within the proxy timeout. The work may still be running on the service side, so retrying a write can duplicate its effect.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"503":{"description":"The Maestro area is not serving this installation: an operator turned it off, or no admin key was ever provisioned. Nothing was executed, and retrying will not help until the configuration changes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"conversation_id","in":"query","required":false,"description":"Restrict the page to one conversation, named by its account-scoped display id. Omitted, turns of every conversation of the account are listed.","schema":{"type":"integer"},"example":4821},{"name":"status","in":"query","required":false,"description":"Restrict the page by outcome. A free string, matched exactly against the stored `status` of each turn - `passed`, `softened`, `stripped`, `regenerated`, `held`, `blocked`, `judge_flagged` or `failed`; a value no turn carries returns an empty page. Two values do more than match: `retried` is not a row status - it selects the attempts that recorded their own scheduled retry (rows with `retried: true`, whose `status` is `failed`) - and `failed` leaves exactly those rows out. `failed` is therefore not a list of turns that ended in failure: a `transient:\u003cExceptionClass\u003e` row is written before the retry is decided, so an attempt that was re-buffered and run again under another `turn_id` stays under `failed` with `retried: false`. Omitted or blank, every row is listed, retried attempts included.","schema":{"type":"string"},"example":"held"},{"name":"limit","in":"query","required":false,"description":"Maximum number of turns in the page, between 1 and 200; 50 when omitted. The value applied is echoed back in the `limit` field of the response.","schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"example":50}]}},"/api/v1/accounts/{account_id}/maestro/verification/turns/{turn_id}":{"get":{"tags":["Maestro"],"operationId":"auto_get_api_v1_accounts_account_id_maestro_verification_turns_turn_id","summary":"Get one Robô turn in full","description":"One turn with everything the timeline row summarized: the guardrail verdict, the reconciliation of what the reply claimed against what the tools actually returned, the digest of which tools ran and how they ended, and the human decisions recorded on the same conversation - so a held reply and the person who released it are read on one screen. Hashes stand in for the prompt and the reply on purpose: enough to prove which text was delivered, never enough to reconstruct the customer's data.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The full turn record, with the human decisions on its conversation.","content":{"application/json":{"schema":{"allOf":[{"type":"object","properties":{"turn_id":{"type":"string","description":"Identifier of the turn, used to fetch its full record.","example":"t_9f21ac4e7b"},"conversation_id":{"type":"integer","description":"Conversation the turn happened on, by its per-account display number.","example":1042},"agent_id":{"type":["integer","null"],"description":"The Robô that ran the turn. Null when it could not be attributed.","example":12},"inbox_id":{"type":["integer","null"],"description":"Inbox the conversation belongs to. Null when unknown.","example":3},"channel":{"type":["string","null"],"description":"Channel the turn was delivered on. Null when unknown.","example":"whatsapp"},"status":{"type":"string","description":"What the verification layer did with the reply. `passed` delivered it as written; `softened` and `stripped` edited it; `regenerated` replaced it; `held` parked it for human approval instead of delivering it; `blocked` stopped it; `judge_flagged` delivered it but the asynchronous review objected afterwards. `failed` is the one value that is not a verdict: the turn produced no reply - it raised, or it ended with nothing to deliver.","enum":["passed","softened","stripped","regenerated","held","blocked","judge_flagged","failed"],"example":"passed"},"failure_reason":{"type":["string","null"],"maxLength":64,"pattern":"^[a-z_]+(:[A-Za-z0-9_.]+)?$","description":"Why the turn did not end normally, as recorded: a kind, optionally followed by a colon and a detail - never customer data. Null on a turn that ended normally. The set is open: a consumer must treat a value it does not know as opaque. Known values on `failed` rows: `stt_failed`, `tool_call_leak`, `delivery_exhausted`, `empty_reply`, `missing_key:\u003cprovider\u003e`, `permanent:\u003cExceptionClass\u003e`, `transient:\u003cExceptionClass\u003e`, `retry_scheduled:tool_call_leak` and `retry_scheduled:delivery_incomplete`. Known values on `blocked` rows: `standdown_at_send`, `standdown_before_transport`, `standdown_between_transports`, `superseded`, `verification_failed`, `unverified_reply_removed` and `unfulfilled_deferral`.","example":null},"retried":{"type":"boolean","description":"True exactly when `failure_reason` starts with `retry_scheduled:` - the row is an attempt that scheduled its own retry. Its `status` still says `failed`, but it is not how the turn ended: the retry ran under another `turn_id`, and that row is the outcome. False does not prove the opposite: a `transient:\u003cExceptionClass\u003e` attempt may also have been re-buffered and run again under another `turn_id`. Never null.","example":false},"created_at":{"type":"string","format":"date-time","description":"When the turn was recorded.","example":"2026-07-27T14:03:11Z"},"calls":{"type":"integer","description":"Model calls the turn consumed.","example":2},"input_tokens":{"type":"integer","description":"Prompt tokens billed for the turn.","example":3184},"output_tokens":{"type":"integer","description":"Completion tokens billed for the turn.","example":212},"cache_read_tokens":{"type":"integer","description":"Prompt tokens served from cache rather than billed at full rate.","example":2560},"cost_usd":{"type":"number","description":"Cost of the turn in US dollars.","example":0.0143},"latency_ms":{"type":"integer","description":"Wall-clock duration of the turn in milliseconds.","example":2840},"tools_run":{"type":"integer","description":"Tools the turn called.","example":2},"tools_failed":{"type":"integer","description":"Tool calls that failed, were refused or were not executed in the turn. Counted on their own, not as a share of `tools_run`.","example":1},"claims_flagged":{"type":"integer","description":"Statements in the reply the reconciliation could not back with evidence.","example":0},"judge_score":{"type":["number","null"],"description":"Score from the asynchronous review, when this turn was sampled for one. Null when it was not reviewed.","example":0.94},"resolved_at":{"type":["string","null"],"format":"date-time","description":"When a human resolved a held reply. Null when the turn never waited on one.","example":null},"resolved_by":{"type":["string","null"],"description":"Name of the human who resolved it. Null when nobody had to.","example":null}}},{"type":"object","properties":{"locale":{"type":["string","null"],"description":"Language the turn was answered in. Null when not recorded.","example":"pt_BR"},"classes":{"type":"object","description":"The guardrail verdict: which output guardrails changed the reply before it could go out. Returned as stored; an empty object means no verdict was recorded.","additionalProperties":true,"properties":{"guardrail":{"type":"array","description":"Guardrails that altered the reply, each listed once, in the order they ran. Empty when none did.","items":{"type":"string","enum":["context_tag","html_sanitized","blocked_phrase","pii_masked","truncated"],"description":"`context_tag` removed a leaked internal tag; `html_sanitized` flattened HTML; `blocked_phrase` redacted a configured phrase; `pii_masked` masked personal data; `truncated` cut the reply at the length cap."}}},"example":{"guardrail":[]}},"claims":{"type":"object","description":"The reconciliation outcome: each statement of a completed action found in the reply and whether the turn's tools backed it. An empty object means the reconciliation did not run for this turn. Returned as stored - a turn recorded by an earlier version may carry a different key set.","additionalProperties":true,"properties":{"claims":{"type":"array","description":"One entry per claim found, in the order they appear in the reply. Empty when the reply made no checkable claim. `claims_flagged` counts the entries whose verdict is `unsupported` or `contradicted`.","items":{"type":"object","required":["kind","verdict","satisfied_by"],"properties":{"kind":{"type":"string","enum":["scheduled","created_record","sent_document","payment_link","transferred_to_human","price_quoted","promised_followup"],"description":"Family of the claim."},"verdict":{"type":"string","enum":["consistent","contradicted","unsupported"],"description":"`consistent` when the turn backs the claim; `contradicted` when a matching tool ran and failed; `unsupported` when nothing in the turn backs it."},"satisfied_by":{"type":["string","null"],"description":"Name of the tool that backs the claim, or `handoff` when the conversation's handoff backs a transfer claim. Null when nothing backs it, and always null for a quoted price, which is checked against the tool results rather than against a tool having run."}}}}},"example":{"claims":[{"kind":"price_quoted","verdict":"consistent","satisfied_by":null}]}},"evidence_digest":{"type":"object","description":"Which tools the turn ran and how each ended. Tool names, outcomes and counters only - never their arguments or results, so the audit trail is not a second copy of customer data. The stored digest is returned as it was written: a turn recorded by an earlier version may lack `tool_execution` and `delivery_receipts` or carry a different key set, and an empty object means no digest was recorded.","additionalProperties":true,"properties":{"executed":{"type":"array","description":"Names of the tools that returned successfully in this turn, deduplicated and sorted. `tools_run` is the size of this list. A turn recorded by an earlier version lists every tool available to the Robô here instead of the ones that ran.","items":{"type":"string"}},"failed":{"type":"array","description":"One entry per tool call that failed, was refused or was not executed. `tools_failed` is the size of this list.","items":{"type":"object","required":["tool","error_code"],"properties":{"tool":{"type":"string","description":"Name of the tool that failed."},"error_code":{"type":"string","description":"Machine-readable failure code reported for the call, such as `http_error`. `not_executed_iteration_cap` marks a call dropped because the turn ran out of tool calls; `unknown` when none was reported."},"http_status":{"type":"integer","minimum":100,"maximum":599,"description":"HTTP status of the upstream response. Present only when the tool reported one."},"reason":{"type":"string","maxLength":200,"description":"Short upstream error text. E-mails, URLs, credentials, opaque tokens and long numbers are replaced by markers before it is stored. Present only when the tool reported a text reason."}}}},"discarded":{"type":"array","description":"Names of the mutating tool calls dropped without running because the turn reached its tool-call limit. Each one is also listed in `failed`.","items":{"type":"string"}},"tool_execution":{"type":"object","description":"Lifecycle of every tool call the model requested in this turn. A returned success is evidence that the tool ran, not proof that anything reached the recipient.","required":["state","requested_count","returned_success_count","returned_error_count","returned_unclassified_count","result_missing_count","calls"],"properties":{"state":{"type":"string","enum":["not_requested","recorded"],"description":"`not_requested` when the model asked for no tool in this turn - a promise made only in prose stays here; `recorded` otherwise."},"requested_count":{"type":"integer","description":"Tool calls the model requested."},"returned_success_count":{"type":"integer","description":"Requested calls whose result came back as a success."},"returned_error_count":{"type":"integer","description":"Requested calls whose result came back as an error."},"returned_unclassified_count":{"type":"integer","description":"Requested calls whose result carried neither a success nor an error status."},"result_missing_count":{"type":"integer","description":"Requested calls for which no result was recorded."},"calls":{"type":"array","description":"The requested calls in request order, capped at 200.","items":{"type":"object","required":["tool","outcome"],"properties":{"tool":{"type":"string","description":"Name of the requested tool. `invalid_tool_name` when the model produced a malformed name."},"outcome":{"type":"string","enum":["returned_success","returned_error","returned_unclassified","result_missing"],"description":"How the call ended."}}}}}},"delivery_receipts":{"type":"array","description":"Structured receipts for the product cards this turn created in the conversation, capped at 200: the ones this run obtained first, then the ones an earlier run of the same turn obtained. A created message is not confirmation that the recipient received it.","items":{"type":"object","required":["tool","message_id","acceptance"],"properties":{"tool":{"type":"string","enum":["catalog_send_product"],"description":"Tool that produced the receipt."},"message_id":{"type":"integer","minimum":1,"description":"Identifier of the message created in the conversation."},"acceptance":{"type":"string","enum":["chatwoot_message_created"],"description":"What the receipt attests - the message was created, nothing further."},"source":{"type":"string","enum":["earlier_attempt"],"description":"Present only on a receipt obtained by an earlier run of the same turn: a corrective re-run or a retried attempt repeats the send, which answers that the card was already delivered and returns no new receipt. Absent on a receipt this run obtained itself."},"commercial_validation":{"type":"object","description":"The commercial check the send recorded for the card, reduced to these two fields. Present only when the send reported one.","required":["validated","source"],"properties":{"validated":{"type":"boolean","description":"True only when the send reported the card as validated."},"source":{"type":"string","enum":["catalog","unknown"],"description":"`catalog` when the send named the catalog as the source of the check, `unknown` otherwise."}}}}}}},"example":{"executed":["catalog_search_products","catalog_send_product"],"failed":[{"tool":"calendar_create_event","error_code":"http_error","http_status":422,"reason":"Response status is not included in the list"}],"discarded":[],"tool_execution":{"state":"recorded","requested_count":3,"returned_success_count":2,"returned_error_count":1,"returned_unclassified_count":0,"result_missing_count":0,"calls":[{"tool":"catalog_search_products","outcome":"returned_success"},{"tool":"catalog_send_product","outcome":"returned_success"},{"tool":"calendar_create_event","outcome":"returned_error"}]},"delivery_receipts":[{"tool":"catalog_send_product","message_id":48211,"acceptance":"chatwoot_message_created","source":"earlier_attempt","commercial_validation":{"validated":true,"source":"catalog"}}]}},"reply_hash":{"type":["string","null"],"description":"Hash of the delivered reply. Proves which text went out without storing it. Null when nothing was delivered.","example":"9f2b7c1d4e8a05f3b6c9d2e5a8f1b4c7d0e3a6f9b2c5d8e1a4f7b0c3d6e9a2f5"},"prompt_hash":{"type":["string","null"],"description":"Hash of the prompt the turn ran with, so two turns can be compared without storing either prompt. Null when not recorded.","example":"4e8a05f3b6c9d2e5a8f1b4c7"},"judge":{"type":["object","null"],"description":"The asynchronous review of this turn, filled in after the fact when the turn was sampled for one. Null when it was not reviewed.","additionalProperties":true,"example":{"score":0.94,"verdict":"grounded"}},"approvals":{"type":"array","description":"Human decisions recorded on this turn's conversation, newest first. Empty when nothing on the conversation ever needed one.","items":{"type":"object","properties":{"id":{"type":"integer","description":"Identifier of the recorded decision.","example":512},"conversation_id":{"type":"integer","description":"Conversation the decision was made on.","example":1042},"pending_id":{"type":"string","description":"The parked action the decision applied to.","example":"pa_7f3c1b90"},"decision":{"type":"string","description":"What was decided, and how it ended. `failed` is an approval attempt whose success was not confirmed: the run errored or was refused, possibly after some or all of its effects already went out. Read `detail` and the conversation history to see what landed; the attempt is consumed and is never run again. It is recorded precisely because it is the event someone later asks about. `discarded` is an approval whose arguments can never run as parked, so the action was dropped. `superseded` is a routing proposal closed by a completed handoff, with no human decision behind it.","enum":["approved","rejected","failed","discarded","superseded"],"example":"approved"},"kind":{"type":"string","description":"What was being decided: a parked tool call, or a reply held back for approval before delivery.","enum":["tool","held_reply"],"example":"tool"},"tool":{"type":"string","description":"The tool the decision applied to. Empty for a held reply.","example":"crm_create_deal"},"rationale":{"type":"string","description":"Why the Robô had proposed the action, as recorded when it was parked.","example":"O contato confirmou interesse no plano anual."},"args_digest":{"type":["string","null"],"description":"Hash of the exact arguments that were approved. Proves WHAT was approved without copying a payload that may carry personal data - two decisions with the same digest approved the same thing. Null when none was recorded.","example":"b4c7d0e3a6f9b2c5d8e1a4f7b0c3d6e9"},"decided_by":{"type":["string","null"],"description":"Name of the human who decided. Null when it was not captured.","example":"Ana Souza"},"approved_by_id":{"type":["integer","null"],"description":"Identifier of the user who decided, taken from that user's own authenticated session when the decision was proxied. Unlike the name, it does not change or repeat. Null when it was not captured: decisions recorded before it existed, a superseded proposal, or a decision made by an automated flow.","example":37},"detail":{"type":"string","description":"Short outcome text, the same one shown to the operator at the time.","example":"Negócio criado no CRM."},"created_at":{"type":"string","format":"date-time","description":"When the decision was recorded.","example":"2026-07-27T14:05:02Z"}}}}}}]},"example":{"turn_id":"t_9f21ac4e7b","conversation_id":1042,"agent_id":12,"inbox_id":3,"channel":"whatsapp","status":"passed","failure_reason":null,"retried":false,"created_at":"2026-07-27T14:03:11Z","calls":2,"input_tokens":3184,"output_tokens":212,"cache_read_tokens":2560,"cost_usd":0.0143,"latency_ms":2840,"tools_run":2,"tools_failed":1,"claims_flagged":0,"judge_score":0.94,"resolved_at":null,"resolved_by":null,"locale":"pt_BR","classes":{"guardrail":[]},"claims":{"claims":[{"kind":"price_quoted","verdict":"consistent","satisfied_by":null}]},"evidence_digest":{"executed":["catalog_search_products","catalog_send_product"],"failed":[{"tool":"calendar_create_event","error_code":"http_error","http_status":422,"reason":"Response status is not included in the list"}],"discarded":[],"tool_execution":{"state":"recorded","requested_count":3,"returned_success_count":2,"returned_error_count":1,"returned_unclassified_count":0,"result_missing_count":0,"calls":[{"tool":"catalog_search_products","outcome":"returned_success"},{"tool":"catalog_send_product","outcome":"returned_success"},{"tool":"calendar_create_event","outcome":"returned_error"}]},"delivery_receipts":[{"tool":"catalog_send_product","message_id":48211,"acceptance":"chatwoot_message_created","source":"earlier_attempt","commercial_validation":{"validated":true,"source":"catalog"}}]},"reply_hash":"9f2b7c1d4e8a05f3b6c9d2e5a8f1b4c7d0e3a6f9b2c5d8e1a4f7b0c3d6e9a2f5","prompt_hash":"4e8a05f3b6c9d2e5a8f1b4c7","judge":{"score":0.94,"verdict":"grounded"},"approvals":[{"id":512,"conversation_id":1042,"pending_id":"pa_7f3c1b90","decision":"approved","kind":"tool","tool":"crm_create_deal","rationale":"O contato confirmou interesse no plano anual.","args_digest":"b4c7d0e3a6f9b2c5d8e1a4f7b0c3d6e9","decided_by":"Ana Souza","approved_by_id":37,"detail":"Negócio criado no CRM.","created_at":"2026-07-27T14:05:02Z"}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"No turn with this identifier belongs to the account."},"502":{"description":"The Maestro service could not be reached (connection refused or reset, host unresolvable), or it answered in a way the gateway could not use, or it rejected the server-to-server credential — the last one is a deployment key mismatch, never the caller's own session. Nothing was executed; the call can be retried.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"504":{"description":"The Maestro service did not answer within the proxy timeout. The work may still be running on the service side, so retrying a write can duplicate its effect.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"503":{"description":"The Maestro area is not serving this installation: an operator turned it off, or no admin key was ever provisioned. Nothing was executed, and retrying will not help until the configuration changes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"turn_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/maestro/verification/approvals":{"get":{"tags":["Maestro"],"operationId":"auto_get_api_v1_accounts_account_id_maestro_verification_approvals","summary":"List recorded human decisions","description":"Every approval and rejection recorded for the account, newest first, optionally narrowed to one conversation. This is the durable history the live approval queue cannot keep: resolving a parked action deletes it from the queue, so without these rows the question of who approved what, and when, would have no answer. Arguments are stored as a hash rather than a payload.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The recorded decisions, newest first.","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Identifier of the recorded decision.","example":512},"conversation_id":{"type":"integer","description":"Conversation the decision was made on.","example":1042},"pending_id":{"type":"string","description":"The parked action the decision applied to.","example":"pa_7f3c1b90"},"decision":{"type":"string","description":"What was decided, and how it ended. `failed` is an approval attempt whose success was not confirmed: the run errored or was refused, possibly after some or all of its effects already went out. Read `detail` and the conversation history to see what landed; the attempt is consumed and is never run again. It is recorded precisely because it is the event someone later asks about. `discarded` is an approval whose arguments can never run as parked, so the action was dropped. `superseded` is a routing proposal closed by a completed handoff, with no human decision behind it.","enum":["approved","rejected","failed","discarded","superseded"],"example":"approved"},"kind":{"type":"string","description":"What was being decided: a parked tool call, or a reply held back for approval before delivery.","enum":["tool","held_reply"],"example":"tool"},"tool":{"type":"string","description":"The tool the decision applied to. Empty for a held reply.","example":"crm_create_deal"},"rationale":{"type":"string","description":"Why the Robô had proposed the action, as recorded when it was parked.","example":"O contato confirmou interesse no plano anual."},"args_digest":{"type":["string","null"],"description":"Hash of the exact arguments that were approved. Proves WHAT was approved without copying a payload that may carry personal data - two decisions with the same digest approved the same thing. Null when none was recorded.","example":"b4c7d0e3a6f9b2c5d8e1a4f7b0c3d6e9"},"decided_by":{"type":["string","null"],"description":"Name of the human who decided. Null when it was not captured.","example":"Ana Souza"},"approved_by_id":{"type":["integer","null"],"description":"Identifier of the user who decided, taken from that user's own authenticated session when the decision was proxied. Unlike the name, it does not change or repeat. Null when it was not captured: decisions recorded before it existed, a superseded proposal, or a decision made by an automated flow.","example":37},"detail":{"type":"string","description":"Short outcome text, the same one shown to the operator at the time.","example":"Negócio criado no CRM."},"created_at":{"type":"string","format":"date-time","description":"When the decision was recorded.","example":"2026-07-27T14:05:02Z"}}}},"example":[{"id":512,"conversation_id":1042,"pending_id":"pa_7f3c1b90","decision":"approved","kind":"tool","tool":"crm_create_deal","rationale":"O contato confirmou interesse no plano anual.","args_digest":"b4c7d0e3a6f9b2c5d8e1a4f7b0c3d6e9","decided_by":"Ana Souza","approved_by_id":37,"detail":"Negócio criado no CRM.","created_at":"2026-07-27T14:05:02Z"}]}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"502":{"description":"The Maestro service could not be reached (connection refused or reset, host unresolvable), or it answered in a way the gateway could not use, or it rejected the server-to-server credential — the last one is a deployment key mismatch, never the caller's own session. Nothing was executed; the call can be retried.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"504":{"description":"The Maestro service did not answer within the proxy timeout. The work may still be running on the service side, so retrying a write can duplicate its effect.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"503":{"description":"The Maestro area is not serving this installation: an operator turned it off, or no admin key was ever provisioned. Nothing was executed, and retrying will not help until the configuration changes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/maestro/verification/policy":{"get":{"tags":["Maestro"],"operationId":"auto_get_api_v1_accounts_account_id_maestro_verification_policy","summary":"Get the reply approval policy","description":"The approval policy in force for the account, and which Robô it was read from - the policy is stored on the Robô that answers, so naming it tells the operator what they are about to change. An account with no bound Robô reports the default policy with no Robô attached.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The policy in force, and the Robô it comes from.","content":{"application/json":{"schema":{"type":"object","properties":{"account_id":{"type":"integer","description":"The account the policy applies to.","example":1},"agent_id":{"type":["integer","null"],"description":"The Robô holding the policy. Null when no Robô is bound to the account.","example":12},"agent_name":{"type":"string","description":"Name of that Robô. Empty when none is bound.","example":"Atendente Acme"},"verification_policy":{"type":"string","description":"When a reply is held for human approval instead of being delivered. `off` always delivers; `unverified` holds only replies the reconciliation could not back; `always` holds every reply. Holding makes the contact wait for a human, which is why `off` is the default.","enum":["off","unverified","always"],"example":"off"}}},"example":{"account_id":1,"agent_id":12,"agent_name":"Atendente Acme","verification_policy":"off"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"502":{"description":"The Maestro service could not be reached (connection refused or reset, host unresolvable), or it answered in a way the gateway could not use, or it rejected the server-to-server credential — the last one is a deployment key mismatch, never the caller's own session. Nothing was executed; the call can be retried.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"504":{"description":"The Maestro service did not answer within the proxy timeout. The work may still be running on the service side, so retrying a write can duplicate its effect.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"503":{"description":"The Maestro area is not serving this installation: an operator turned it off, or no admin key was ever provisioned. Nothing was executed, and retrying will not help until the configuration changes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]},"put":{"tags":["Maestro"],"operationId":"auto_put_api_v1_accounts_account_id_maestro_verification_policy","summary":"Set the reply approval policy","description":"Sets when the account's Robô holds a reply for human approval instead of delivering it. Answers with the policy as stored, and the Robô it was written to. Refused rather than silently accepted when the account has no bound Robô: the policy lives on a Robô, so storing it nowhere would show a setting that reverts the next time anyone looks.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The policy in force, and the Robô it comes from.","content":{"application/json":{"schema":{"type":"object","properties":{"account_id":{"type":"integer","description":"The account the policy applies to.","example":1},"agent_id":{"type":["integer","null"],"description":"The Robô holding the policy. Null when no Robô is bound to the account.","example":12},"agent_name":{"type":"string","description":"Name of that Robô. Empty when none is bound.","example":"Atendente Acme"},"verification_policy":{"type":"string","description":"When a reply is held for human approval instead of being delivered. `off` always delivers; `unverified` holds only replies the reconciliation could not back; `always` holds every reply. Holding makes the contact wait for a human, which is why `off` is the default.","enum":["off","unverified","always"],"example":"off"}}},"example":{"account_id":1,"agent_id":12,"agent_name":"Atendente Acme","verification_policy":"off"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"502":{"description":"The Maestro service could not be reached (connection refused or reset, host unresolvable), or it answered in a way the gateway could not use, or it rejected the server-to-server credential — the last one is a deployment key mismatch, never the caller's own session. Nothing was executed; the call can be retried.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"504":{"description":"The Maestro service did not answer within the proxy timeout. The work may still be running on the service side, so retrying a write can duplicate its effect.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"503":{"description":"The Maestro area is not serving this installation: an operator turned it off, or no admin key was ever provisioned. Nothing was executed, and retrying will not help until the configuration changes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"422":{"description":"No Robô is bound to this account, so there is nothing to apply the policy to. Nothing was stored."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"verification_policy":{"type":"string"}}},"example":{"verification_policy":"sample verification policy"}}}}}},"/api/v1/accounts/{account_id}/maestro/brain/profile":{"get":{"tags":["Maestro"],"operationId":"auto_get_api_v1_accounts_account_id_maestro_brain_profile","summary":"Profile brain","description":"Performs the profile operation on the targeted brain resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"entities":{"type":"string"},"relations":{"type":"string"},"generated_at":{"type":"string","format":"date-time"},"cached":{"type":"boolean","example":false}}},"example":{"entities":"sample entities","relations":"sample relations","generated_at":"2026-01-15T10:30:00.000Z","cached":false}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"502":{"description":"The Maestro service could not be reached (connection refused or reset, host unresolvable), or it answered in a way the gateway could not use, or it rejected the server-to-server credential — the last one is a deployment key mismatch, never the caller's own session. Nothing was executed; the call can be retried.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"504":{"description":"The Maestro service did not answer within the proxy timeout. The work may still be running on the service side, so retrying a write can duplicate its effect.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"503":{"description":"The Maestro area is not serving this installation: an operator turned it off, or no admin key was ever provisioned. Nothing was executed, and retrying will not help until the configuration changes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/maestro/brain/refresh":{"post":{"tags":["Maestro"],"operationId":"auto_post_api_v1_accounts_account_id_maestro_brain_refresh","summary":"Map the account structure now","description":"Runs the Cérebro's structure mapping on demand instead of waiting for the nightly sweep, and invalidates the cached snapshot on success — serving the pre-map cache right after the operator pressed \"map now\" is exactly the \"nothing happened\" this endpoint exists to fix. Synchronous on purpose: the work is a handful of reads plus one embedding call, and the caller is a human looking at an empty screen, who cannot tell a queued job from a broken one.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The outcome of the mapping run, in the terms the screen has to explain to a human.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","description":"Whether the structure was mapped and persisted.","example":true},"status":{"type":"string","description":"`mapped` — read and persisted. `unreachable` — every structure read was refused, almost always the account's service-user token: an operator fix, not a retry. `failed` — anything else on the sidecar. `unavailable` — the sidecar itself could not be reached or its answer could not be read (returned with HTTP 503).","enum":["mapped","unreachable","failed","unavailable"],"example":"mapped"},"detail":{"type":"string","description":"Short explanation, present on the failure paths so the screen can say what to fix.","example":""},"entities":{"type":"object","additionalProperties":{"type":"integer"},"description":"How many of each mapped entity kind were found (inboxes, teams, labels, bots...).","example":{"inboxes":15,"teams":3}},"relations":{"type":"integer","description":"How many relations between those entities were mapped.","example":21},"chunks_ingested":{"type":"integer","description":"How many knowledge chunks the mapping wrote into the account's base.","example":8},"version":{"type":"integer","description":"Version of the persisted profile after this run.","example":4},"generated_at":{"type":["string","null"],"format":"date-time","description":"When the persisted profile was generated.","example":"2026-08-01T22:10:00Z"},"kb_degraded":{"type":"boolean","description":"True when the structure mapped but the knowledge-base write failed.","example":false},"pushed":{"type":"boolean","description":"True when the resulting profile was pushed downstream.","example":true}}},"example":{"ok":true,"status":"mapped","detail":"","entities":{"inboxes":15,"teams":3},"relations":21,"chunks_ingested":8,"version":4,"generated_at":"2026-08-01T22:10:00Z","kb_degraded":false,"pushed":true}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"502":{"description":"The Maestro service could not be reached (connection refused or reset, host unresolvable), or it answered in a way the gateway could not use, or it rejected the server-to-server credential — the last one is a deployment key mismatch, never the caller's own session. Nothing was executed; the call can be retried.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"504":{"description":"The Maestro service did not answer within the proxy timeout. The work may still be running on the service side, so retrying a write can duplicate its effect.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"503":{"description":"The Maestro sidecar could not be reached, or answered something unreadable. The body carries `status: unavailable` and an actionable `detail` rather than a stack trace."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/maestro/brain/insights":{"get":{"tags":["Maestro"],"operationId":"auto_get_api_v1_accounts_account_id_maestro_brain_insights","summary":"List the account's Maestro insights","description":"The insight feed: what the Maestro departments noticed, most recently written first. A finding the producer measures again is updated in place and moves back to the top instead of becoming a second insight. Insights flagged sensitive are returned only to administrators and to roles that manage the Cérebro.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"One page of the feed.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","description":"The insights on this page.","items":{"type":"object","properties":{"id":{"type":"integer","description":"Insight id.","example":812},"department":{"type":["string","null"],"description":"Key of the Maestro department that produced the insight. Departments are configurable, so the set is open. Null on a redacted insight whose department is not one of the known keys.","example":"atendimento"},"insight_type":{"type":"string","description":"What kind of finding this is (for example `risk_band`, `slow_first_response`, `low_csat`, `no_nurture`, `faq_gap`, `turn_failures`). Defined by the producer; an unknown type must be rendered from `title`/`body`.","example":"slow_first_response"},"severity":{"type":"string","enum":["info","low","warning","medium","high","critical"],"description":"How urgent the finding is. Only `high` and `critical` raise a notification.","example":"critical"},"subject_type":{"type":["string","null"],"description":"Kind of record the insight is about, when it is about one record (for example `Conversation` or `MaestroAgent`). Null for an account-level finding.","example":null},"subject_id":{"type":["integer","null"],"description":"Id of that record. For a `Conversation` subject this is the conversation display id, and it is returned only when the caller can open that conversation — null otherwise.","example":null},"title":{"type":"string","description":"Stored title, in the language the producer wrote it. Fallback when `facts` cannot be rendered. When `redacted` is true this is a neutral title instead.","example":"Tempo de primeira resposta crítico"},"body":{"type":["string","null"],"description":"Stored explanation, in the language the producer wrote it. Fallback when `facts` cannot be rendered. When `redacted` is true this is a neutral sentence that states how many conversations are involved and never repeats what a customer wrote.","example":"A média de primeira resposta está em 4h12m — muito acima do alvo."},"redacted":{"type":"boolean","description":"True when the insight quotes what a customer wrote (a recurring question, the article suggested for it) and the caller may not read that text. The quote is returned to administrators and to a caller who can open at least one of the conversations the insight names; an insight that names no conversation is therefore read in full by administrators only. A redacted insight is rebuilt from a closed list: `title` and `body` are neutral sentences, `facts` keeps only the count facts known for the type (numbers), `evidence` only the metrics known for the type (numbers, `comparator`, `scope`) and a window of numbers and a timestamp, `suggested_action` only its `kind`, and `department` / `subject_type` only known keys.","example":false},"redacted_reason":{"type":["string","null"],"enum":["no_access","restricted",null],"description":"Why the quote was withheld, null when `redacted` is false. `no_access` — the insight names conversations and the caller can open none of them. `restricted` — the insight names no conversation, so its quote is returned only to administrators.","example":null},"redacted_count":{"type":["integer","null"],"description":"In how many conversations the withheld text appeared, when the insight says so; null when it does not, and always null when `redacted` is false.","example":null},"suggested_action":{"description":"The suggestion as stored for an authorized reader. JSON arrays and truthy scalar values are preserved as well as objects; null or false reads as an empty object. Nonblank stored JSON is limited to 64000 bytes. A redacted insight returns only its reviewed action fields.","oneOf":[{"type":"object","additionalProperties":true,"description":"What the insight suggests doing. `kind` names the next step a person can take; `tool`/`args` (and, on older rows, `label`) are the producer's own vocabulary and may be absent. An empty object means no suggestion. When `redacted` is true only `kind`, `tool` and a numeric `args.occurrences` are returned.","properties":{"kind":{"type":"string","description":"The next step this insight calls for. Absent on rows written before the kind existed.","example":"review_conversations"},"tool":{"type":"string","description":"Department action the producer proposed.","example":"notify_team"},"args":{"type":"object","additionalProperties":true,"description":"Arguments of that action, as the producer sent them.","example":{"reason":"first_response_critical"}}}},{"type":"array","description":"A stored JSON array preserved by the reader.","items":{"$ref":"#/components/schemas/json_value"}},{"type":"string"},{"type":"number"},{"type":"boolean","enum":[true]}]},"sensitive":{"type":"boolean","description":"True when the text may quote confidential material. Such an insight is returned only to administrators and to roles that manage the Cérebro.","example":false},"schema_version":{"type":"integer","description":"2 when the insight came with `facts`/`evidence`; 1 for a row that only carries its stored text.","example":2},"facts":{"type":"object","additionalProperties":true,"description":"The typed values the sentence was built from — flat, only strings, numbers and booleans, with the unit in the key name (`value_seconds`, `target_percent`). Which keys exist depends on `insight_type`. Empty for a row without facts.","example":{"value_seconds":15120.0,"threshold_seconds":14400.0,"level":"critical"}},"evidence":{"type":"object","description":"What was measured against which limit. Empty for a row without evidence.","properties":{"window":{"type":"object","description":"When the reading was taken and, only when a metric covers a period, how long that period is.","properties":{"days":{"type":"integer","description":"Length of the measured period in days, when a metric is scoped to it.","example":14},"hours":{"type":"integer","description":"Length of the measured period in hours, when a metric is scoped to it.","example":24},"generated_at":{"type":"string","format":"date-time","description":"When the reading was taken.","example":"2026-10-06T12:00:00Z"}}},"metrics":{"type":"array","description":"Each value that was measured and the limit that fired the rule.","items":{"type":"object","properties":{"key":{"type":"string","description":"Name of the metric, with its unit.","example":"avg_first_response_time_seconds"},"value":{"type":"number","description":"Measured value.","example":15120.0},"threshold":{"type":"number","description":"Limit the value was compared with.","example":14400.0},"comparator":{"type":"string","enum":["gte","gt","lte","lt"],"description":"How the value was compared with the limit.","example":"gte"},"scope":{"type":"string","enum":["window","current","all_time"],"description":"Period the value covers — the measured window, the state right now, or everything on record. Absent when the producer did not state it.","example":"window"}}}}}},"refreshed":{"type":"boolean","description":"True when the producer re-measured this finding and updated the same insight in place.","example":false},"updated_at":{"type":"string","format":"date-time","description":"When the insight was last written. A finding the producer measures again moves up the feed by this time.","example":"2026-10-06T12:00:05.000Z"},"created_at":{"type":"string","format":"date-time","description":"When the finding was first seen.","example":"2026-10-06T12:00:05.000Z"},"conversation_refs_count":{"type":"integer","description":"How many of the conversations the producer named for this insight the caller can open.","example":0},"primary_conversation_id":{"type":["integer","null"],"description":"Display id of the conversation to open, set only when the producer named exactly one conversation and the caller can open it.","example":null}}}},"meta":{"type":"object","description":"Pagination of the feed.","properties":{"current_page":{"type":"integer","description":"Page returned.","example":1},"total_pages":{"type":"integer","description":"Number of pages.","example":3},"total_count":{"type":"integer","description":"Number of insights the caller can read with these filters.","example":61},"per_page":{"type":"integer","description":"Insights per page.","example":25}}}}},"example":{"payload":[{"id":812,"department":"atendimento","insight_type":"slow_first_response","severity":"critical","subject_type":null,"subject_id":null,"title":"Tempo de primeira resposta crítico","body":"A média de primeira resposta está em 4h12m — muito acima do alvo.","redacted":false,"redacted_reason":null,"redacted_count":null,"suggested_action":{"kind":"review_conversations","tool":"notify_team","args":{"reason":"first_response_critical"}},"sensitive":false,"schema_version":2,"facts":{"value_seconds":15120.0,"threshold_seconds":14400.0,"level":"critical"},"evidence":{"window":{"days":14,"hours":24,"generated_at":"2026-10-06T12:00:00Z"},"metrics":[{"key":"avg_first_response_time_seconds","value":15120.0,"threshold":14400.0,"comparator":"gte","scope":"window"}]},"refreshed":false,"updated_at":"2026-10-06T12:00:05.000Z","created_at":"2026-10-06T12:00:05.000Z","conversation_refs_count":0,"primary_conversation_id":null}],"meta":{"current_page":1,"total_pages":3,"total_count":61,"per_page":25}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"503":{"description":"The Maestro area is not serving this installation: an operator turned it off, or no admin key was ever provisioned. Nothing was executed, and retrying will not help until the configuration changes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"department","in":"query","required":false,"description":"Only insights of this department key.","schema":{"type":"string"},"example":"atendimento"},{"name":"severity","in":"query","required":false,"description":"Only insights of this severity.","schema":{"type":"string","enum":["info","low","warning","medium","high","critical"]},"example":"critical"},{"name":"page","in":"query","required":false,"description":"Page of the feed, 25 insights per page.","schema":{"type":"integer","minimum":1},"example":1}]}},"/api/v1/accounts/{account_id}/maestro/brain/insights/{id}":{"get":{"tags":["Maestro"],"operationId":"auto_get_api_v1_accounts_account_id_maestro_brain_insights_id","summary":"Get one Maestro insight","description":"One insight in the same shape as the feed. This is what a notification about an insight links to, so that it can be opened even when it is no longer on the first page of the feed.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The insight.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer","description":"Insight id.","example":812},"department":{"type":["string","null"],"description":"Key of the Maestro department that produced the insight. Departments are configurable, so the set is open. Null on a redacted insight whose department is not one of the known keys.","example":"atendimento"},"insight_type":{"type":"string","description":"What kind of finding this is (for example `risk_band`, `slow_first_response`, `low_csat`, `no_nurture`, `faq_gap`, `turn_failures`). Defined by the producer; an unknown type must be rendered from `title`/`body`.","example":"slow_first_response"},"severity":{"type":"string","enum":["info","low","warning","medium","high","critical"],"description":"How urgent the finding is. Only `high` and `critical` raise a notification.","example":"critical"},"subject_type":{"type":["string","null"],"description":"Kind of record the insight is about, when it is about one record (for example `Conversation` or `MaestroAgent`). Null for an account-level finding.","example":null},"subject_id":{"type":["integer","null"],"description":"Id of that record. For a `Conversation` subject this is the conversation display id, and it is returned only when the caller can open that conversation — null otherwise.","example":null},"title":{"type":"string","description":"Stored title, in the language the producer wrote it. Fallback when `facts` cannot be rendered. When `redacted` is true this is a neutral title instead.","example":"Tempo de primeira resposta crítico"},"body":{"type":["string","null"],"description":"Stored explanation, in the language the producer wrote it. Fallback when `facts` cannot be rendered. When `redacted` is true this is a neutral sentence that states how many conversations are involved and never repeats what a customer wrote.","example":"A média de primeira resposta está em 4h12m — muito acima do alvo."},"redacted":{"type":"boolean","description":"True when the insight quotes what a customer wrote (a recurring question, the article suggested for it) and the caller may not read that text. The quote is returned to administrators and to a caller who can open at least one of the conversations the insight names; an insight that names no conversation is therefore read in full by administrators only. A redacted insight is rebuilt from a closed list: `title` and `body` are neutral sentences, `facts` keeps only the count facts known for the type (numbers), `evidence` only the metrics known for the type (numbers, `comparator`, `scope`) and a window of numbers and a timestamp, `suggested_action` only its `kind`, and `department` / `subject_type` only known keys.","example":false},"redacted_reason":{"type":["string","null"],"enum":["no_access","restricted",null],"description":"Why the quote was withheld, null when `redacted` is false. `no_access` — the insight names conversations and the caller can open none of them. `restricted` — the insight names no conversation, so its quote is returned only to administrators.","example":null},"redacted_count":{"type":["integer","null"],"description":"In how many conversations the withheld text appeared, when the insight says so; null when it does not, and always null when `redacted` is false.","example":null},"suggested_action":{"description":"The suggestion as stored for an authorized reader. JSON arrays and truthy scalar values are preserved as well as objects; null or false reads as an empty object. Nonblank stored JSON is limited to 64000 bytes. A redacted insight returns only its reviewed action fields.","oneOf":[{"type":"object","additionalProperties":true,"description":"What the insight suggests doing. `kind` names the next step a person can take; `tool`/`args` (and, on older rows, `label`) are the producer's own vocabulary and may be absent. An empty object means no suggestion. When `redacted` is true only `kind`, `tool` and a numeric `args.occurrences` are returned.","properties":{"kind":{"type":"string","description":"The next step this insight calls for. Absent on rows written before the kind existed.","example":"review_conversations"},"tool":{"type":"string","description":"Department action the producer proposed.","example":"notify_team"},"args":{"type":"object","additionalProperties":true,"description":"Arguments of that action, as the producer sent them.","example":{"reason":"first_response_critical"}}}},{"type":"array","description":"A stored JSON array preserved by the reader.","items":{"$ref":"#/components/schemas/json_value"}},{"type":"string"},{"type":"number"},{"type":"boolean","enum":[true]}]},"sensitive":{"type":"boolean","description":"True when the text may quote confidential material. Such an insight is returned only to administrators and to roles that manage the Cérebro.","example":false},"schema_version":{"type":"integer","description":"2 when the insight came with `facts`/`evidence`; 1 for a row that only carries its stored text.","example":2},"facts":{"type":"object","additionalProperties":true,"description":"The typed values the sentence was built from — flat, only strings, numbers and booleans, with the unit in the key name (`value_seconds`, `target_percent`). Which keys exist depends on `insight_type`. Empty for a row without facts.","example":{"value_seconds":15120.0,"threshold_seconds":14400.0,"level":"critical"}},"evidence":{"type":"object","description":"What was measured against which limit. Empty for a row without evidence.","properties":{"window":{"type":"object","description":"When the reading was taken and, only when a metric covers a period, how long that period is.","properties":{"days":{"type":"integer","description":"Length of the measured period in days, when a metric is scoped to it.","example":14},"hours":{"type":"integer","description":"Length of the measured period in hours, when a metric is scoped to it.","example":24},"generated_at":{"type":"string","format":"date-time","description":"When the reading was taken.","example":"2026-10-06T12:00:00Z"}}},"metrics":{"type":"array","description":"Each value that was measured and the limit that fired the rule.","items":{"type":"object","properties":{"key":{"type":"string","description":"Name of the metric, with its unit.","example":"avg_first_response_time_seconds"},"value":{"type":"number","description":"Measured value.","example":15120.0},"threshold":{"type":"number","description":"Limit the value was compared with.","example":14400.0},"comparator":{"type":"string","enum":["gte","gt","lte","lt"],"description":"How the value was compared with the limit.","example":"gte"},"scope":{"type":"string","enum":["window","current","all_time"],"description":"Period the value covers — the measured window, the state right now, or everything on record. Absent when the producer did not state it.","example":"window"}}}}}},"refreshed":{"type":"boolean","description":"True when the producer re-measured this finding and updated the same insight in place.","example":false},"updated_at":{"type":"string","format":"date-time","description":"When the insight was last written. A finding the producer measures again moves up the feed by this time.","example":"2026-10-06T12:00:05.000Z"},"created_at":{"type":"string","format":"date-time","description":"When the finding was first seen.","example":"2026-10-06T12:00:05.000Z"},"conversation_refs_count":{"type":"integer","description":"How many of the conversations the producer named for this insight the caller can open.","example":0},"primary_conversation_id":{"type":["integer","null"],"description":"Display id of the conversation to open, set only when the producer named exactly one conversation and the caller can open it.","example":null}}}}},"example":{"payload":{"id":812,"department":"atendimento","insight_type":"slow_first_response","severity":"critical","subject_type":null,"subject_id":null,"title":"Tempo de primeira resposta crítico","body":"A média de primeira resposta está em 4h12m — muito acima do alvo.","redacted":false,"redacted_reason":null,"redacted_count":null,"suggested_action":{"kind":"review_conversations","tool":"notify_team","args":{"reason":"first_response_critical"}},"sensitive":false,"schema_version":2,"facts":{"value_seconds":15120.0,"threshold_seconds":14400.0,"level":"critical"},"evidence":{"window":{"days":14,"hours":24,"generated_at":"2026-10-06T12:00:00Z"},"metrics":[{"key":"avg_first_response_time_seconds","value":15120.0,"threshold":14400.0,"comparator":"gte","scope":"window"}]},"refreshed":false,"updated_at":"2026-10-06T12:00:05.000Z","created_at":"2026-10-06T12:00:05.000Z","conversation_refs_count":0,"primary_conversation_id":null}}}}},"401":{"description":"Unauthorized"},"404":{"description":"No such insight for this caller: the id belongs to another account, the insight was discarded, or it is flagged sensitive and the caller may not read sensitive insights. The three cases answer the same way on purpose.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["not_found"],"description":"Machine-readable reason.","example":"not_found"}}},"example":{"error":"not_found"}}}},"503":{"description":"The Maestro area is not serving this installation: an operator turned it off, or no admin key was ever provisioned. Nothing was executed, and retrying will not help until the configuration changes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Insight id.","schema":{"type":"integer"},"example":812}]}},"/api/v1/accounts/{account_id}/maestro/brain/insights/{id}/conversations":{"get":{"tags":["Maestro"],"operationId":"auto_get_api_v1_accounts_account_id_maestro_brain_insights_id_conversations","summary":"List the conversations behind a Maestro insight","description":"The conversations that contribute to one insight, resolved from the account's current data at the moment of the call and restricted to the conversations the caller can open — the same decision that governs opening the conversation itself, applied to every row before it is listed or counted towards `has_more`. Each one carries the reason it is listed, as a key plus typed values, so the caller can phrase it in its own language. A finding that is not about conversations answers with an empty list and says why in `meta.state`; nothing is ever listed that the account's data does not support. One call examines at most `meta.candidate_limit` candidate conversations; `meta.truncated` says when that limit was reached before the page was filled.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"One page of contributing conversations, or an empty page with the reason in `meta.state`.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","description":"Contributing conversations the caller can open.","items":{"type":"object","properties":{"id":{"type":"integer","description":"Conversation display id — the id used in conversation URLs and by the conversations API.","example":4821},"status":{"type":"string","enum":["open","resolved","pending","snoozed"],"description":"Current conversation status.","example":"open"},"contact":{"type":["object","null"],"description":"Contact of the conversation.","properties":{"id":{"type":"integer","description":"Contact id.","example":77},"name":{"type":["string","null"],"description":"Contact name.","example":"Ana Souza"}}},"inbox":{"type":["object","null"],"description":"Inbox the conversation lives in.","properties":{"id":{"type":"integer","description":"Inbox id.","example":3},"name":{"type":"string","description":"Inbox name.","example":"WhatsApp Vendas"}}},"assignee":{"type":["object","null"],"description":"Agent the conversation is assigned to, or null when unassigned.","properties":{"id":{"type":"integer","description":"User id.","example":12},"name":{"type":"string","description":"Agent name.","example":"Bruno Lima"}}},"created_at":{"type":"string","format":"date-time","description":"When the conversation was opened.","example":"2026-10-06T07:00:00.000Z"},"last_activity_at":{"type":"string","format":"date-time","description":"Last activity on the conversation.","example":"2026-10-06T07:00:00.000Z"},"reason":{"type":"object","description":"Why this conversation is on the list.","properties":{"key":{"type":"string","enum":["risk","awaiting_first_reply","open_since","csat_rating","no_active_follow_up","ref","contributing"],"description":"`risk` — its latest risk score is medium or high. `awaiting_first_reply` — open and nobody has replied yet. `open_since` — among the longest open. `csat_rating` — its customer answered the survey with 3 or less. `no_active_follow_up` — its contact is in no running follow-up. `ref` — the producer named it. `contributing` — listed without a more specific reason.","example":"awaiting_first_reply"},"params":{"type":"object","additionalProperties":true,"description":"Values for that reason: `since` (date-time) for the waiting and open reasons; `band`, `score` and `signals` for `risk`; `rating` and `responded_at` for `csat_rating`; `last_activity_at` for `no_active_follow_up`; `reason` (the producer's own label, for example `faq_cluster`) for `ref`.","example":{"since":"2026-10-06T07:00:00.000Z"}}}}}}},"meta":{"type":"object","description":"Pagination and what kind of answer this is.","properties":{"current_page":{"type":"integer","description":"Page returned.","example":1},"per_page":{"type":"integer","description":"Conversations per page.","example":10},"has_more":{"type":"boolean","description":"Whether a next page exists.","example":false},"truncated":{"type":"boolean","description":"True when the candidate limit was reached before the page was filled and conversations were left unexamined: the list may be incomplete for this caller.","example":false},"candidate_limit":{"type":"integer","description":"How many candidate conversations one call examines at most.","example":200},"can_prepare_reply":{"type":"boolean","description":"Whether the caller may ask Maestro for a suggested reply to these conversations. It follows the authorization of the copilot suggestion endpoint: administrators only.","example":true},"state":{"type":"string","enum":["ok","empty","pipeline","feature_disabled","unsupported"],"description":"`ok` — conversations are listed. `empty` — nothing matches right now for this caller. `pipeline` — the finding is about deals; see `target`. `feature_disabled` — the list depends on a module the account has not enabled. `unsupported` — this kind of finding cannot be traced to conversations.","example":"ok"},"source":{"type":"string","enum":["live","refs"],"description":"`live` — resolved from the account data now. `refs` — the conversations the producer named.","example":"live"},"target":{"type":["object","null"],"description":"Where to send the reader when the answer is not a list of conversations.","properties":{"type":{"type":"string","enum":["crm_pipeline"],"description":"Destination kind.","example":"crm_pipeline"}}}}}}},"example":{"payload":[{"id":4821,"status":"open","contact":{"id":77,"name":"Ana Souza"},"inbox":{"id":3,"name":"WhatsApp Vendas"},"assignee":{"id":12,"name":"Bruno Lima"},"created_at":"2026-10-06T07:00:00.000Z","last_activity_at":"2026-10-06T07:00:00.000Z","reason":{"key":"awaiting_first_reply","params":{"since":"2026-10-06T07:00:00.000Z"}}}],"meta":{"current_page":1,"per_page":10,"has_more":false,"truncated":false,"candidate_limit":200,"can_prepare_reply":true,"state":"ok","source":"live","target":{"type":"crm_pipeline"}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"No such insight for this caller: the id belongs to another account, the insight was discarded, or it is flagged sensitive and the caller may not read sensitive insights. The three cases answer the same way on purpose.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["not_found"],"description":"Machine-readable reason.","example":"not_found"}}},"example":{"error":"not_found"}}}},"503":{"description":"The Maestro area is not serving this installation: an operator turned it off, or no admin key was ever provisioned. Nothing was executed, and retrying will not help until the configuration changes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Insight id.","schema":{"type":"integer"},"example":812},{"name":"page","in":"query","required":false,"description":"Page of the list, 10 conversations per page, at most 20 pages.","schema":{"type":"integer","minimum":1,"maximum":20},"example":1}]}},"/api/v1/accounts/{account_id}/maestro/brain/risk":{"get":{"tags":["Maestro"],"operationId":"auto_get_api_v1_accounts_account_id_maestro_brain_risk","summary":"List the account's risk scores","description":"The most recent risk scores of the account, newest first, at most 100. A score about a conversation (its display id, how it scored and the signals that explain it) is returned only when the caller can open that conversation — the same decision that governs opening the conversation itself, taken before the list is cut to its limit; a filter that names a conversation the caller cannot open answers with an empty list. Scores about other subjects are returned to any member who can read the Cérebro. One call examines at most `meta.candidate_limit` of the most recent scores; `meta.truncated` says when that limit was reached before the list was full.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The risk scores the caller may read.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","description":"Risk scores, most recently computed first.","items":{"type":"object","properties":{"id":{"type":"integer","description":"Risk score id.","example":9301},"subject_type":{"type":"string","description":"Kind of record the score is about (for example `Conversation`, `Contact`, `Account`).","example":"Conversation"},"subject_id":{"type":"integer","description":"Id of that record. For a conversation this is its display id.","example":4821},"score":{"type":"integer","description":"Risk score, 0 to 100.","example":82},"band":{"type":"string","enum":["low","medium","high"],"description":"Risk band of the score.","example":"high"},"signals":{"description":"Measured signals as stored; nonblank values are limited to 64000 bytes. The reader preserves JSON arrays and truthy scalar values as well as maps; null or false reads as an empty object.","oneOf":[{"type":"object","additionalProperties":true,"description":"The measured signals keyed by signal name.","example":{"no_response":7233.8,"sla_breached":true}},{"type":"array","description":"A stored JSON array preserved by the reader.","items":{"$ref":"#/components/schemas/json_value"}},{"type":"string"},{"type":"number"},{"type":"boolean","enum":[true]}]},"computed_at":{"type":["string","null"],"format":"date-time","description":"When the score was computed.","example":"2026-10-06T12:00:00.000Z"}}}},"meta":{"type":"object","description":"Whether the list is complete for this caller.","properties":{"truncated":{"type":"boolean","description":"True when the candidate limit was reached before the list was full and scores were left unexamined: the list may be incomplete for this caller.","example":false},"candidate_limit":{"type":"integer","description":"How many of the most recent scores one call examines at most.","example":300}}}}},"example":{"payload":[{"id":9301,"subject_type":"Conversation","subject_id":4821,"score":82,"band":"high","signals":{"no_response":7233.8,"sla_breached":true},"computed_at":"2026-10-06T12:00:00.000Z"}],"meta":{"truncated":false,"candidate_limit":300}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"503":{"description":"The Maestro area is not serving this installation: an operator turned it off, or no admin key was ever provisioned. Nothing was executed, and retrying will not help until the configuration changes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"band","in":"query","required":false,"description":"Only scores in this band.","schema":{"type":"string","enum":["low","medium","high"]},"example":"high"},{"name":"subject_type","in":"query","required":false,"description":"Only scores about this kind of subject.","schema":{"type":"string"},"example":"Conversation"},{"name":"subject_id","in":"query","required":false,"description":"Only scores about this subject. For a conversation this is its display id.","schema":{"type":"integer"},"example":4821}]}},"/api/v1/accounts/{account_id}/maestro/brain/runs":{"get":{"tags":["Maestro"],"operationId":"auto_get_api_v1_accounts_account_id_maestro_brain_runs","summary":"Runs brain","description":"Performs the runs operation on the targeted brain resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"department":{"type":"string"},"autonomy_level":{"type":"string","enum":["read_only","hitl","autonomous"],"description":"How autonomously the department run was allowed to act."},"status":{"type":"string"},"hitl_state":{"type":"string"},"started_at":{"type":"string","format":"date-time"},"finished_at":{"type":"string","format":"date-time"},"actions":{"type":"string"},"outcome":{"type":"string"},"created_at":{"type":"string","format":"date-time"}},"required":["id","department","autonomy_level","status","hitl_state","started_at","finished_at","actions","outcome","created_at"],"additionalProperties":false}},"meta":{"type":"string"}}},"example":{"payload":[{"id":1,"department":"sample department","autonomy_level":"read_only","status":"active","hitl_state":"sample hitl state","started_at":"2026-01-15T10:30:00.000Z","finished_at":"2026-01-15T10:30:00.000Z","actions":"sample actions","outcome":"sample outcome","created_at":"2026-01-15T10:30:00.000Z"}],"meta":"sample meta"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"503":{"description":"The Maestro area is not serving this installation: an operator turned it off, or no admin key was ever provisioned. Nothing was executed, and retrying will not help until the configuration changes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/maestro/brain/analytics":{"get":{"tags":["Maestro"],"operationId":"auto_get_api_v1_accounts_account_id_maestro_brain_analytics","summary":"Get the account brain analytics matrix","description":"Returns the consultative analytics matrix (KPI + chart configs). Proxy-pulls the live matrix from the sidecar and falls back to a NATIVE computed matrix (AccountBrain::AnalyticsMatrixQuery) when the sidecar is down or returns a non-matrix body, so a stable shape is always returned (a cold account renders zeroed KPIs + empty series, never a 502). `cached` is true when the native fallback served it.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The analytics matrix (KPIs + series).","content":{"application/json":{"schema":{"type":"object","properties":{"generated_at":{"type":"string","format":"date-time","example":"2026-01-15T10:30:00.000Z"},"cached":{"type":"boolean","description":"True when served from the native fallback.","example":false},"kpis":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string","example":"open_conversations"},"label":{"type":"string","example":"open_conversations"},"value":{"type":"number","example":42},"unit":{"type":["string","null"],"description":"null | seconds | percent | currency","example":null},"delta":{"type":["number","null"],"example":null},"trend":{"type":["string","null"],"example":null}}}},"series":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string","example":"conversations_volume"},"label":{"type":"string","example":"conversations_volume"},"chart":{"type":"string","description":"line | doughnut","example":"line"},"points":{"type":"array","items":{"type":"object","properties":{"x":{"type":"string","example":"2026-01-15"},"y":{"type":"number","example":8}}}}}}}}},"example":{"generated_at":"2026-01-15T10:30:00.000Z","cached":false,"kpis":[{"key":"open_conversations","label":"open_conversations","value":42,"unit":null,"delta":null,"trend":null}],"series":[{"key":"conversations_volume","label":"conversations_volume","chart":"line","points":[{"x":"2026-01-15","y":8}]}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"502":{"description":"The Maestro service could not be reached (connection refused or reset, host unresolvable), or it answered in a way the gateway could not use, or it rejected the server-to-server credential — the last one is a deployment key mismatch, never the caller's own session. Nothing was executed; the call can be retried.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"504":{"description":"The Maestro service did not answer within the proxy timeout. The work may still be running on the service side, so retrying a write can duplicate its effect.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"503":{"description":"The Maestro area is not serving this installation: an operator turned it off, or no admin key was ever provisioned. Nothing was executed, and retrying will not help until the configuration changes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"range","in":"query","required":false,"description":"Window the analytics are computed over, forwarded verbatim to the Maestro service. Omitted, the service's own default window applies.","schema":{"type":"string"},"example":"30d"}]}},"/api/v1/accounts/{account_id}/maestro/brain/recommendations":{"get":{"tags":["Maestro"],"operationId":"auto_get_api_v1_accounts_account_id_maestro_brain_recommendations","summary":"Recommendations brain","description":"Performs the recommendations operation on the targeted brain resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"department":{"type":"string"},"severity":{"type":"string","enum":["info","low","warning","medium","high","critical"],"description":"Severity of the improvement recommendation."},"title":{"type":"string"},"body":{"type":"string"},"suggested_action":{"type":"string"},"review":{"type":"string"},"created_at":{"type":"string","format":"date-time"}},"required":["id","department","severity","title","body","suggested_action","review","created_at"],"additionalProperties":false}},"meta":{"type":"string"}}},"example":{"payload":[{"id":1,"department":"sample department","severity":"info","title":"Sample title","body":"Sample body text.","suggested_action":"sample suggested action","review":"sample review","created_at":"2026-01-15T10:30:00.000Z"}],"meta":"sample meta"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"503":{"description":"The Maestro area is not serving this installation: an operator turned it off, or no admin key was ever provisioned. Nothing was executed, and retrying will not help until the configuration changes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/maestro/brain/recommendations/{id}/accept":{"post":{"tags":["Maestro"],"operationId":"auto_post_api_v1_accounts_account_id_maestro_brain_recommendations_id_accept","summary":"Accept an improvement recommendation","description":"Records that an administrator accepted the recommendation, with who, when and an optional note, and returns it. The recommendation stays in the feed. Nothing in the account configuration or the knowledge base is changed by this call, and accepting it again only refreshes the recorded decision. Answers 404 when the account has no improvement recommendation with this id.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The recommendation with the recorded decision.","content":{"application/json":{"schema":{"type":"object","required":["payload"],"properties":{"payload":{"type":"object","additionalProperties":false,"required":["id","department","severity","title","body","suggested_action","review","created_at"],"properties":{"id":{"type":"integer","description":"Recommendation id.","example":1203},"department":{"type":"string","description":"Key of the Maestro department that proposed it. Departments are configurable, so the set is open; a push that names no department is stored as `conhecimento`.","example":"conhecimento"},"severity":{"type":"string","enum":["info","low","warning","medium","high","critical"],"description":"How urgent the recommendation is.","example":"info"},"title":{"type":"string","description":"Stored title, in the language the producer wrote it.","example":"Recomendação de melhoria do atendimento"},"body":{"type":["string","null"],"description":"Stored explanation, in the language the producer wrote it. Null when the producer sent none.","example":"Score médio recente 0.42. Padrões a corrigir: handoff_has_summary, resolution_has_reply."},"suggested_action":{"type":"object","additionalProperties":true,"description":"The stored suggestion in the producer's own vocabulary (for example `type`, `scope`, `agent_id` and `source`), plus the `review` entry this call recorded.","example":{"type":"refine_kb","scope":"account","agent_id":null,"source":"improve:refinement","review":{"state":"accepted","by_user_id":7,"at":"2026-06-17T14:22:05Z","note":"Artigo revisado."}}},"review":{"type":"object","additionalProperties":false,"required":["state","at"],"description":"The decision this call recorded. Calling again replaces it.","properties":{"state":{"type":"string","enum":["accepted","rejected"],"description":"Whether the recommendation was accepted or rejected.","example":"accepted"},"by_user_id":{"type":"integer","description":"Id of the user who reviewed it. Absent when the call carried no user.","example":7},"at":{"type":"string","format":"date-time","description":"When it was reviewed.","example":"2026-06-17T14:22:05Z"},"note":{"type":"string","description":"Note sent with the call. Absent when none was sent.","example":"Artigo revisado."}}},"created_at":{"type":"string","format":"date-time","description":"When the recommendation was stored.","example":"2026-06-17T03:00:01.482Z"}}}}},"example":{"payload":{"id":1203,"department":"conhecimento","severity":"info","title":"Recomendação de melhoria do atendimento","body":"Score médio recente 0.42. Padrões a corrigir: handoff_has_summary, resolution_has_reply.","created_at":"2026-06-17T03:00:01.482Z","suggested_action":{"type":"refine_kb","scope":"account","agent_id":null,"source":"improve:refinement","review":{"state":"accepted","by_user_id":7,"at":"2026-06-17T14:22:05Z","note":"Artigo revisado."}},"review":{"state":"accepted","by_user_id":7,"at":"2026-06-17T14:22:05Z","note":"Artigo revisado."}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"503":{"description":"The Maestro area is not serving this installation: an operator turned it off, or no admin key was ever provisioned. Nothing was executed, and retrying will not help until the configuration changes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Recommendation id.","schema":{"type":"integer"},"example":1203}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"note":{"type":"string","description":"Optional note kept with the decision. A blank note is not stored.","example":"Artigo revisado."}}},"example":{"note":"Artigo revisado."}}}}}},"/api/v1/accounts/{account_id}/maestro/brain/recommendations/{id}/reject":{"post":{"tags":["Maestro"],"operationId":"auto_post_api_v1_accounts_account_id_maestro_brain_recommendations_id_reject","summary":"Reject an improvement recommendation","description":"Records that an administrator rejected the recommendation, with who, when and an optional note, removes it from the recommendation feed and returns it. Nothing in the account configuration or the knowledge base is changed. Answers 404 when the account has no improvement recommendation with this id.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The rejected recommendation with the recorded decision.","content":{"application/json":{"schema":{"type":"object","required":["payload"],"properties":{"payload":{"type":"object","additionalProperties":false,"required":["id","department","severity","title","body","suggested_action","review","created_at"],"properties":{"id":{"type":"integer","description":"Recommendation id.","example":1203},"department":{"type":"string","description":"Key of the Maestro department that proposed it. Departments are configurable, so the set is open; a push that names no department is stored as `conhecimento`.","example":"conhecimento"},"severity":{"type":"string","enum":["info","low","warning","medium","high","critical"],"description":"How urgent the recommendation is.","example":"info"},"title":{"type":"string","description":"Stored title, in the language the producer wrote it.","example":"Recomendação de melhoria do atendimento"},"body":{"type":["string","null"],"description":"Stored explanation, in the language the producer wrote it. Null when the producer sent none.","example":"Score médio recente 0.42. Padrões a corrigir: handoff_has_summary, resolution_has_reply."},"suggested_action":{"type":"object","additionalProperties":true,"description":"The stored suggestion in the producer's own vocabulary (for example `type`, `scope`, `agent_id` and `source`), plus the `review` entry this call recorded.","example":{"type":"refine_kb","scope":"account","agent_id":null,"source":"improve:refinement","review":{"state":"accepted","by_user_id":7,"at":"2026-06-17T14:22:05Z","note":"Artigo revisado."}}},"review":{"type":"object","additionalProperties":false,"required":["state","at"],"description":"The decision this call recorded. Calling again replaces it.","properties":{"state":{"type":"string","enum":["accepted","rejected"],"description":"Whether the recommendation was accepted or rejected.","example":"accepted"},"by_user_id":{"type":"integer","description":"Id of the user who reviewed it. Absent when the call carried no user.","example":7},"at":{"type":"string","format":"date-time","description":"When it was reviewed.","example":"2026-06-17T14:22:05Z"},"note":{"type":"string","description":"Note sent with the call. Absent when none was sent.","example":"Artigo revisado."}}},"created_at":{"type":"string","format":"date-time","description":"When the recommendation was stored.","example":"2026-06-17T03:00:01.482Z"}}}}},"example":{"payload":{"id":1203,"department":"conhecimento","severity":"info","title":"Recomendação de melhoria do atendimento","body":"Score médio recente 0.42. Padrões a corrigir: handoff_has_summary, resolution_has_reply.","created_at":"2026-06-17T03:00:01.482Z","suggested_action":{"type":"refine_kb","scope":"account","agent_id":null,"source":"improve:refinement","review":{"state":"rejected","by_user_id":7,"at":"2026-06-17T14:22:05Z","note":"Já coberto pela base atual."}},"review":{"state":"rejected","by_user_id":7,"at":"2026-06-17T14:22:05Z","note":"Já coberto pela base atual."}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"503":{"description":"The Maestro area is not serving this installation: an operator turned it off, or no admin key was ever provisioned. Nothing was executed, and retrying will not help until the configuration changes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Recommendation id.","schema":{"type":"integer"},"example":1203}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"note":{"type":"string","description":"Optional note kept with the decision. A blank note is not stored.","example":"Artigo revisado."}}},"example":{"note":"Artigo revisado."}}}}}},"/api/v1/accounts/{account_id}/maestro/usage/summary":{"get":{"tags":["Maestro"],"operationId":"auto_get_api_v1_accounts_account_id_maestro_usage_summary","summary":"What this account spent on AI","description":"Aggregates one account's model spend over a trailing window: the grand total, then the same measures broken down per surface, per model and per Robô, plus a zero-filled daily trend. Administrator-only — it is billing-shaped information about the account, unlike the Cérebro's other reads. `days` defaults to 30 and is clamped to 1..365 rather than refused, because the only real caller is a period selector and a 422 there would be a dead end.\n\nModel attribution is PARTIAL by construction: conversation turns are measured without a model id, so their cost lands in `totals`, `by_surface` and `daily` but cannot land in `by_model`. The response therefore reports `model_attributed_cost_usd` and `model_attributed_measured_subtotal_usd` separately instead of letting a by-model chart quietly stand for the whole invoice. They carry model-labelled portions, never a replacement for a null complete total.\n\nCost is likewise partial, and says so. Every spend record carries a per-row `cost_priced` flag stating whether its `cost_usd` is a MEASUREMENT or merely the absence of one. That flag is never returned per row here — this endpoint is an aggregate — it arrives counted: as `unpriced_calls` inside every bucket and every conversation, and as the `unpriced` block for the window. Wherever `unpriced_calls` is above zero the complete `cost_usd` beside it is null and `cost_is_floor` is true. `measured_subtotal_usd` sums only measured, priced portions, including known components of incomplete rows; it is null when no such portion exists and may be 0 when zero was measured. It is never the unknown total or an amount to add to it. A complete, genuinely measured zero remains numeric 0. Calls and unpriced counts remain visible in all of these cases.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The account's consumption over the window, aggregated every way the screen needs.","content":{"application/json":{"schema":{"type":"object","properties":{"account_id":{"type":"integer","description":"The account this summary belongs to (injected server-side, never from the caller).","example":31},"since":{"type":"string","format":"date-time","description":"Start of the window (UTC).","example":"2026-07-03T00:00:00Z"},"until":{"type":"string","format":"date-time","description":"End of the window (UTC).","example":"2026-08-02T00:00:00Z"},"days":{"type":"integer","description":"Window length in days, as applied after clamping.","example":30},"filters":{"type":"object","description":"What the server ACTUALLY applied, echoed back. A screen that sends four filters and renders one total has to be able to prove which of them were honoured — `excludes_turn_rows` is the difference between \"this account spent less\" and \"this view cannot see part of the spend\".","properties":{"surface":{"type":["string","null"],"description":"Surface filter applied. Null when none was.","example":null},"model":{"type":["string","null"],"description":"Model filter applied. Null when none was.","example":null},"agent_id":{"type":["integer","null"],"description":"Robô filter applied. Null when none was.","example":null},"conversation_id":{"type":["integer","null"],"description":"Conversation filter applied. Null when none was.","example":null},"order":{"type":"string","enum":["cost","calls","tokens"],"description":"Ranking applied to every bucket list and to `by_conversation`.","example":"cost"},"excludes_turn_rows":{"type":"boolean","description":"True when conversation turns could NOT participate under these filters, so every figure in this response covers off-turn spend only. See `exclusion_reason`.","example":false},"exclusion_reason":{"type":["string","null"],"enum":["model_not_recorded_on_turns","surface_is_not_turn",null],"description":"Why the turn leg is out — machine-readable so the screen renders its own localized sentence instead of echoing a server string it cannot translate. `model_not_recorded_on_turns`: conversation turns are stored without a model id, so a model filter cannot select them and the totals are genuinely partial — that is a caveat, not a smaller bill. `surface_is_not_turn`: the caller asked for one non-turn surface, so the absence of turns IS the requested answer. Null when turns took part.","example":null}}},"totals":{"$ref":"#/components/schemas/maestro_usage_bucket"},"by_surface":{"type":"array","description":"Spend per surface (customer replies, dashboards, briefing, judge...), costliest first.","items":{"$ref":"#/components/schemas/maestro_usage_bucket"}},"by_model":{"type":"array","description":"Spend per model, costliest first. PARTIAL — see `model_attributed_cost_usd`.","items":{"$ref":"#/components/schemas/maestro_usage_bucket"}},"by_agent":{"type":"array","description":"Spend per Robô, costliest first. Work with no Robô attached is omitted entirely rather than bucketed as zero.","items":{"$ref":"#/components/schemas/maestro_usage_bucket"}},"by_conversation":{"type":"array","description":"Costliest conversations first, bounded by `conversation_limit` and ranked in the database rather than in memory. Both sides summed: the reply turns AND what the same conversation spent off the turn path — a voice note transcribed, an answer spoken, a live call taken.","items":{"type":"object","example":{"conversation_id":800,"calls":5,"turns":2,"input_tokens":2400,"output_tokens":600,"cache_read_tokens":0,"cost_usd":null,"measured_subtotal_usd":0.05,"unpriced_calls":2,"cost_is_floor":true,"model":null,"model_attributed_cost_usd":0.0,"model_attributed_measured_subtotal_usd":null,"nested_calls":0,"nested_cost_usd":0.0,"nested_measured_subtotal_usd":null,"nested_cost_is_floor":false,"nested_truncated":false},"examples":[{"conversation_id":500,"calls":1,"turns":0,"input_tokens":0,"output_tokens":0,"cache_read_tokens":0,"cost_usd":null,"measured_subtotal_usd":null,"unpriced_calls":1,"cost_is_floor":true,"model":"gpt-5.5","model_attributed_cost_usd":0.0,"model_attributed_measured_subtotal_usd":null,"nested_calls":0,"nested_cost_usd":0.0,"nested_measured_subtotal_usd":null,"nested_cost_is_floor":false,"nested_truncated":false},{"conversation_id":500,"calls":1,"turns":0,"input_tokens":0,"output_tokens":0,"cache_read_tokens":0,"cost_usd":0.0,"measured_subtotal_usd":0.0,"unpriced_calls":0,"cost_is_floor":false,"model":"gpt-5.5","model_attributed_cost_usd":0.0,"model_attributed_measured_subtotal_usd":0.0,"nested_calls":0,"nested_cost_usd":0.0,"nested_measured_subtotal_usd":null,"nested_cost_is_floor":false,"nested_truncated":false},{"conversation_id":800,"calls":5,"turns":2,"input_tokens":2400,"output_tokens":600,"cache_read_tokens":0,"cost_usd":null,"measured_subtotal_usd":0.05,"unpriced_calls":2,"cost_is_floor":true,"model":null,"model_attributed_cost_usd":0.0,"model_attributed_measured_subtotal_usd":null,"nested_calls":0,"nested_cost_usd":0.0,"nested_measured_subtotal_usd":null,"nested_cost_is_floor":false,"nested_truncated":false}],"properties":{"conversation_id":{"type":"integer","description":"The platform conversation id — the screen links straight to it.","example":1042},"calls":{"type":"integer","description":"Model calls attributed to this conversation.","example":14},"turns":{"type":"integer","description":"Agent turns recorded for it. Zero means the cost is entirely off-turn work, which is a different problem from a chatty bot and takes a different fix.","example":9},"input_tokens":{"type":"integer","description":"Prompt tokens billed.","example":6200},"output_tokens":{"type":"integer","description":"Completion tokens billed.","example":940},"cache_read_tokens":{"type":"integer","description":"Subset of `input_tokens` served from the provider's prompt cache.","example":2100},"cost_usd":{"type":["number","null"],"format":"float","description":"Complete cost in USD for this conversation, both sides summed. Null when any work is unpriced or incomplete; a genuinely measured zero remains 0. The separate `measured_subtotal_usd` never replaces a null complete total.","example":null},"measured_subtotal_usd":{"type":["number","null"],"format":"float","description":"Only measured, priced portions of this conversation's work, including known components of incomplete rows. Null when none resolved to a rate; a measured zero remains 0. A lower bound when `cost_is_floor` is true, never an extra charge.","example":0.05},"unpriced_calls":{"type":"integer","description":"Calls on rows whose cost is not a complete priced measurement. Above zero means `cost_usd` is null and any `measured_subtotal_usd` is only a known lower bound. Calls remain counted even when neither monetary amount is known.","example":2},"cost_is_floor":{"type":"boolean","description":"True when `unpriced_calls` is above zero. The complete cost is then null; this flag does not turn an absent measured subtotal into 0.","example":true},"model":{"type":["string","null"],"description":"The costliest model that served this conversation. Null when only conversation turns contributed — they record no model id, and \"unknown\" would read as a model actually named unknown.","example":"gpt-5.4-mini-2026-03-17"},"model_attributed_cost_usd":{"type":"number","format":"float","description":"Complete priced cost on model-labelled rows, excluding partial unpriced components. Conversation turns carry no model id and are omitted. This numeric portion can be 0 while the conversation's complete cost is null; it never supplies that unknown total.","example":0.0},"model_attributed_measured_subtotal_usd":{"type":["number","null"],"format":"float","description":"Measured, priced portions carrying a model label, including known components of incomplete rows. Null when none exists; measured zero remains 0. Omits conversation-turn costs without model attribution and is never added to the conversation's total or measured subtotal.","example":null},"nested_calls":{"type":["integer","null"],"description":"Model calls this conversation delegated to a sub-agent or a rolling summary, ALREADY inside `calls`. NULL means NOT MEASURED for this row (the nested scan hit its cap — see `nested_truncated`), never \"none happened\".","example":3},"nested_cost_usd":{"type":["number","null"],"format":"float","description":"Complete cost of delegated or summary work, already included in the conversation's spend, never an addition. Null when new nested records have incomplete measurement or pricing, or the scan was capped. Legacy records without the completeness marker retain their recorded amounts. Numeric zero is distinct from an unknown amount.","example":0.0052},"nested_measured_subtotal_usd":{"type":["number","null"],"format":"float","description":"Known measured, priced portion of this conversation's nested work. Null when no portion is known or the conversation scan was capped; measured zero stays numeric 0. A subset of the conversation's spend, never added again.","example":0.0052},"nested_cost_is_floor":{"type":"boolean","description":"True when the nested complete cost is unconfirmed, including incomplete new rows or a capped scan. Qualifies any known subtotal; does not imply the scan was capped.","example":false},"nested_truncated":{"type":"boolean","description":"True only when the nested scan hit its row cap. This conversation's nested calls, complete cost and subtotal are then null. False does not certify measurement or pricing completeness. The top-level `nested` block retains the scanned subtotal.","example":false}}}},"daily":{"type":"array","description":"Daily trend, oldest first, zero-filled — a day with no spend is a fact, not a gap.","items":{"type":"object","example":{"date":"2026-08-01","calls":5,"cost_usd":null,"measured_subtotal_usd":0.05,"unpriced_calls":2,"cost_is_floor":true},"examples":[{"date":"2026-08-01","calls":1,"cost_usd":null,"measured_subtotal_usd":null,"unpriced_calls":1,"cost_is_floor":true},{"date":"2026-08-01","calls":1,"cost_usd":0.0,"measured_subtotal_usd":0.0,"unpriced_calls":0,"cost_is_floor":false},{"date":"2026-08-01","calls":5,"cost_usd":null,"measured_subtotal_usd":0.05,"unpriced_calls":2,"cost_is_floor":true}],"properties":{"date":{"type":"string","description":"Calendar day (UTC), ISO-8601.","example":"2026-08-01"},"calls":{"type":"integer","description":"Model calls that day.","example":12},"cost_usd":{"type":["number","null"],"format":"float","description":"Complete cost in USD that day. Null when any work is unpriced or incomplete; genuinely measured zero remains 0. A zero-filled day with no work has cost 0 and no measured subtotal, rather than an invented measurement.","example":null},"measured_subtotal_usd":{"type":["number","null"],"format":"float","description":"Only measured, priced portions that day, including known components of incomplete rows. Null when none exists; measured zero remains 0. When `cost_is_floor` is true, this is a lower bound, never the complete daily cost.","example":0.05},"unpriced_calls":{"type":"integer","description":"Calls on rows that prevent the daily cost being a complete priced total.","example":2},"cost_is_floor":{"type":"boolean","description":"True when `unpriced_calls` is above zero, with complete daily cost null and any measured subtotal remaining only a known lower bound.","example":true}}}},"model_attributed_cost_usd":{"type":"number","format":"float","description":"Complete priced cost on model-labelled rows, excluding partial unpriced components. Omits conversation turns without model attribution. This numeric portion can be 0 while `totals.cost_usd` is null; it never supplies an unknown complete total.","example":0.0},"model_attributed_measured_subtotal_usd":{"type":["number","null"],"format":"float","description":"Measured, priced portions carrying a model label, including known components of incomplete rows. Null when none exists; measured zero remains 0. Omits unlabelled conversation-turn costs and is never added to `totals.cost_usd` or its measured subtotal.","example":null},"unpriced":{"type":"object","description":"Work that was MEASURED but never PRICED. Transcription, speech, rendered images and live audio bill per second, per character or per output, and this system holds no rate table for any of them — so their cost figure is the ABSENCE of a measurement, not a measurement of zero. Conversation turns land here too, whenever the model that served them has no entry in the price table. This block therefore has NO cost field anywhere in its schema: a reader must not be able to see \"US$ 0.00\" beside \"transcription\" and conclude that transcription is free.\n\nEvery figure here is the roll-up of one per-row flag, `cost_priced`. It is a FLOOR before a boundary in the account's own history: the flag reached the conversation-turn side later than the rest, and the turns already recorded were grandfathered as priced rather than rewritten — they carry no model id, so nothing in them says which model served the turn, and marking them all unpriced would have declared the account's whole history unmeasured, a larger error than the one being corrected. A turn served before that boundary by a model with no published rate therefore still reads as a measured US$ 0.00 and is NOT counted here. The boundary is reported: see `priced_boundary`, and do not infer one from the data instead.","properties":{"calls":{"type":"integer","description":"Total unpriced calls in the window, after filters. Aggregated in SQL, so it is never a truncated read — but it counts only the rows that carry `cost_priced` honestly, which is what the boundary note above is about.","example":12},"rows":{"type":"integer","description":"Total unpriced spend records behind those calls. Exact.","example":12},"units_truncated":{"type":"boolean","description":"True when there were more unpriced records than the unit roll-up reads, so the per-unit quantities below are a floor. `calls` and `rows` stay exact either way.","example":false},"surfaces":{"type":"array","description":"Which surfaces the unpriced work came from, most calls first.","items":{"type":"object","properties":{"key":{"type":"string","description":"Surface name — `stt`, `tts`, `realtime`, `image`, `video`, `voice_clone`, `embeddings`, `search`, and `turn` when a conversation ran on a model with no published rate.","example":"tts"},"calls":{"type":"integer","description":"Calls on this surface whose cost was never priced.","example":7},"rows":{"type":"integer","description":"Recorded units of work behind those calls.","example":7},"units":{"type":"array","description":"What it actually consumed, in its own unit. Normally one entry — a surface bills in one unit. A LIST rather than a scalar because two different units are never summed into one number. Empty for `turn`, which bills in tokens the response already reports as tokens.","items":{"type":"object","properties":{"unit":{"type":"string","enum":["audio_bytes","characters","documents","images","pages","responses","searches","videos","voices"],"description":"The unit's own name — the measurement that exists where a price does not. `audio_bytes` (transcription), `characters` (speech), `documents` (embeddings), `images`, `videos`, `voices` (cloning), `responses` (live audio), `searches` and `pages` (web research).","example":"characters"},"quantity":{"type":"number","format":"float","description":"How much of it was consumed in the window, after filters.","example":3412.0}}}}}}}}},"priced_boundary":{"type":"object","description":"From when `unpriced_calls` is a MEASUREMENT on the conversation-turn side rather than a migration default. The flag reached that side after the rows already existed, and the existing turns were grandfathered as priced rather than rewritten — they carry no model id, so nothing in them says which model served the turn, and marking the whole history unpriced would have declared every account's past unmeasured, a larger error than the one being corrected. The cost of that decision is paid here: a window spanning the change holds TWO meanings of one column, so `unpriced_calls: 0` across it is not evidence that everything was priced. Off-turn spend is unaffected — it was created with the flag, so every one of its rows computes it.","properties":{"measured_since":{"type":["string","null"],"format":"date-time","description":"Instant (UTC) from which the turn-side price flag is known to be computed rather than defaulted. A LOWER BOUND read from this account's own rows — the earliest turn that only post-change code could have written — never a deploy timestamp, which the sidecar does not have. The true boundary is at or before it, so treating the window as suspect up to this instant errs in the safe direction. Null means UNKNOWN (this account has no such row), never \"always measured\".","example":"2026-07-28T14:02:11Z"},"window_starts_before_measurement":{"type":"boolean","description":"True when this window reaches back past `measured_since`, or `measured_since` is unknown. The earlier part of the series then cannot tell a measured price from a migration default, so `unpriced` under-reports there and a client must say so. False only when the whole window sits on the measured side — the only case in which the unpriced figures may be presented without that caveat.","example":true},"basis":{"type":"string","enum":["observed_post_migration_row","unknown"],"description":"How `measured_since` was established. `observed_post_migration_row`: it is the earliest turn row that only post-change code could have written — one carrying an unpriced cost or a recorded failure reason, both of which arrived with the same change. `unknown`: this account has no such row, so the boundary is undetermined and `window_starts_before_measurement` stays true.","example":"observed_post_migration_row"}}},"nested":{"type":"object","description":"Delegated and rolling-summary work, already booked on the parent row. A breakdown, never an addition to `totals`. New rows distinguish complete cost from a known measured subtotal; incomplete measurement or pricing makes complete cost null and sets the floor flag. Legacy rows without the completeness marker retain their recorded amounts.","example":{"calls":2,"cost_usd":null,"measured_subtotal_usd":0.0052,"cost_is_floor":true,"rows":1,"truncated":false,"surfaces":[{"key":"delegation","calls":2,"cost_usd":null,"measured_subtotal_usd":0.0052,"cost_is_floor":true,"rows":1}]},"properties":{"calls":{"type":"integer","description":"Nested model calls in the window, after filters.","example":18},"cost_usd":{"type":["number","null"],"format":"float","description":"Complete nested cost or null when measurement, pricing or scan coverage is incomplete. Already included in the account spend; never add it on top. Measured zero is numeric 0.","example":0.0219},"measured_subtotal_usd":{"type":["number","null"],"format":"float","description":"Known measured, priced portions of scanned nested rows. Null when no portion is known; explicit measured zero remains numeric 0. Never added again to the total.","example":0.0219},"cost_is_floor":{"type":"boolean","description":"True when complete nested cost is unconfirmed. Any known subtotal is only a floor. This includes incomplete new rows and scan limits; legacy rows keep their old meaning.","example":false},"rows":{"type":"integer","description":"Nested spend records behind those calls. Exact — counted in SQL.","example":18},"truncated":{"type":"boolean","description":"True only when there were more nested records than this roll-up reads. Calls and any known subtotal then describe the scanned floor, complete cost is null, and rows stay exact. Incomplete measurement alone never sets this flag.","example":false},"surfaces":{"type":"array","description":"Which surfaces the nested work came from, costliest first.","items":{"type":"object","properties":{"key":{"type":"string","description":"Surface name — `delegation`, `summary`, `research`.","example":"delegation"},"calls":{"type":"integer","description":"Model calls this surface really made.","example":12},"cost_usd":{"type":["number","null"],"format":"float","description":"Complete cost or null; already included in spend via the parent row.","example":0.0161},"measured_subtotal_usd":{"type":["number","null"],"format":"float","description":"Known priced portion or null; measured zero remains numeric 0.","example":0.0161},"cost_is_floor":{"type":"boolean","description":"True when this surface's complete nested cost is unconfirmed.","example":false},"rows":{"type":"integer","description":"Nested units of work behind those calls. Exact.","example":12}}}}}}}},"example":{"account_id":31,"since":"2026-07-03T00:00:00Z","until":"2026-08-02T00:00:00Z","days":30,"filters":{"surface":null,"model":null,"agent_id":null,"conversation_id":null,"order":"cost","excludes_turn_rows":false,"exclusion_reason":null},"totals":{"key":"turn","label":null,"calls":5,"input_tokens":2400,"output_tokens":600,"cache_read_tokens":0,"cost_usd":null,"measured_subtotal_usd":0.05,"unpriced_calls":2,"cost_is_floor":true},"by_surface":[{"key":"turn","label":null,"calls":5,"input_tokens":2400,"output_tokens":600,"cache_read_tokens":0,"cost_usd":null,"measured_subtotal_usd":0.05,"unpriced_calls":2,"cost_is_floor":true}],"by_model":[{"key":"turn","label":null,"calls":5,"input_tokens":2400,"output_tokens":600,"cache_read_tokens":0,"cost_usd":null,"measured_subtotal_usd":0.05,"unpriced_calls":2,"cost_is_floor":true}],"by_agent":[{"key":"turn","label":null,"calls":5,"input_tokens":2400,"output_tokens":600,"cache_read_tokens":0,"cost_usd":null,"measured_subtotal_usd":0.05,"unpriced_calls":2,"cost_is_floor":true}],"by_conversation":[{"conversation_id":800,"calls":5,"turns":2,"input_tokens":2400,"output_tokens":600,"cache_read_tokens":0,"cost_usd":null,"measured_subtotal_usd":0.05,"unpriced_calls":2,"cost_is_floor":true,"model":null,"model_attributed_cost_usd":0.0,"model_attributed_measured_subtotal_usd":null,"nested_calls":0,"nested_cost_usd":0.0,"nested_measured_subtotal_usd":null,"nested_cost_is_floor":false,"nested_truncated":false}],"daily":[{"date":"2026-08-01","calls":5,"cost_usd":null,"measured_subtotal_usd":0.05,"unpriced_calls":2,"cost_is_floor":true}],"model_attributed_cost_usd":0.0,"model_attributed_measured_subtotal_usd":null,"unpriced":{"calls":12,"rows":12,"units_truncated":false,"surfaces":[{"key":"tts","calls":7,"rows":7,"units":[{"unit":"characters","quantity":3412.0}]}]},"priced_boundary":{"measured_since":"2026-07-28T14:02:11Z","window_starts_before_measurement":true,"basis":"observed_post_migration_row"},"nested":{"calls":2,"cost_usd":null,"measured_subtotal_usd":0.0052,"cost_is_floor":true,"rows":1,"truncated":false,"surfaces":[{"key":"delegation","calls":2,"cost_usd":null,"measured_subtotal_usd":0.0052,"cost_is_floor":true,"rows":1}]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"502":{"description":"The Maestro service could not be reached (connection refused or reset, host unresolvable), or it answered in a way the gateway could not use, or it rejected the server-to-server credential — the last one is a deployment key mismatch, never the caller's own session. Nothing was executed; the call can be retried.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"504":{"description":"The Maestro service did not answer within the proxy timeout. The work may still be running on the service side, so retrying a write can duplicate its effect.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"503":{"description":"The Maestro area is not serving this installation: an operator turned it off, or no admin key was ever provisioned. Nothing was executed, and retrying will not help until the configuration changes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"days","in":"query","required":false,"description":"Trailing window in days. Defaults to 30 and is CLAMPED to 1..365 rather than refused — the only real caller is a period selector, where a 422 would be a dead end.","schema":{"type":"integer","minimum":1,"maximum":365,"default":30,"example":30}},{"name":"surface","in":"query","required":false,"description":"Keep only this surface (`turn`, `dashboards`, `onboarding`, `judge`, `improve`, `copilot`, `call`, `stt`, `tts`, `realtime`, `embeddings`, `image`, `video`, `voice_clone`, `summary`, `delegation`, `research`). Anything but `turn` drops the conversation-turn leg entirely, and the response says so in `filters.exclusion_reason` — that is the requested answer, not a caveat.","schema":{"type":"string","maxLength":32,"example":"tts"}},{"name":"model","in":"query","required":false,"description":"Keep only this model id. Conversation turns are stored WITHOUT a model id, so this filter cannot select them and the turn leg is dropped from every aggregation consistently — reported as `filters.exclusion_reason: model_not_recorded_on_turns`. Dropping it consistently is deliberate: a partially-applied filter would let two numbers on the same screen disagree.","schema":{"type":"string","maxLength":128,"example":"gpt-5.4-mini-2026-03-17"}},{"name":"agent_id","in":"query","required":false,"description":"Keep only the spend of one Robô. Applies to BOTH tables, so the totals stay consistent.","schema":{"type":"integer","minimum":1,"example":77}},{"name":"conversation_id","in":"query","required":false,"description":"Keep only one conversation's spend, including what it spent off the reply turn (a transcription, a synthesized answer, a voice call).","schema":{"type":"integer","minimum":1,"example":1042}},{"name":"order","in":"query","required":false,"description":"How the buckets and the per-conversation list are ranked. An unrecognized value is DROPPED here rather than forwarded, so a typo falls back to the default instead of reaching the sidecar as a 422 the operator never typed.","schema":{"type":"string","enum":["cost","calls","tokens"],"default":"cost","example":"cost"}},{"name":"conversation_limit","in":"query","required":false,"description":"How many conversations `by_conversation` returns, costliest first. Bounded in SQL, never in memory.","schema":{"type":"integer","minimum":1,"maximum":100,"default":20,"example":20}}]}},"/api/v1/accounts/{account_id}/maestro/usage/call":{"get":{"tags":["Maestro"],"operationId":"auto_get_api_v1_accounts_account_id_maestro_usage_call","summary":"Get the AI cost of a voice call","description":"What the AI voice pipeline of one call cost, as Maestro measured it: always in USD, one line per role, provider and model, and a priced subtotal when present. It is NEVER added to Meta's cost of the same call, which is reported by the WhatsApp Cost Center in the WABA billing currency — different currencies, different owners. `total_usd` is the complete cost or null; `measured_subtotal_usd` is a nullable floor of only measured and priced units, never added again to `total_usd`. `cost_usd` belongs to each individual line, never to the top-level call payload. `state: in_progress` means the call still has an open AI session and the lines are partial; a client should also treat a call that has not ended, or ended less than 120 seconds ago, as in progress. A successful read of transient Redis liveness is not durable completion proof: without a durable flush/finalization proof the producer answers `state: unknown`, never `final` or `no_usage`. `no_usage` is reserved for a positive producer proof of zero operations. Administrator-only, like the account usage summary, and gated by the `account_brain` feature.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The AI cost of the call.","content":{"application/json":{"schema":{"type":"object","properties":{"contract":{"type":"string","enum":["maestro.usage.call_cost.v1"]},"account_id":{"type":"integer"},"call_id":{"type":"string"},"ref":{"type":"string","description":"The spend reference the call's usage is recorded under (`call:\u003ccall_id\u003e`)."},"conversation_id":{"type":["integer","null"],"description":"Display id of the call's conversation."},"currency":{"type":"string","enum":["USD"]},"state":{"type":"string","enum":["no_usage","in_progress","final","unknown"],"description":"`in_progress` (an AI session of the call is still open; the lines are partial), `final` (the producer has durable completion proof), `no_usage` (positive proof of zero AI operations; `lines` is empty), or `unknown` (no durable completion proof; any lines and amount are only partial measurements)."},"liveness_known":{"type":"boolean","description":"Whether the transient Redis open-session marker was readable. `true` can mean a known marker absence; it is liveness only and does not prove finalization. `false` means the liveness read failed. Either case is `state: unknown` unless a durable producer finalization proof exists."},"measurement_complete":{"type":["boolean","null"],"description":"`true` only after the producer positively confirmed all call operations were measured; `false` when a partial measurement is known; null when measurement coverage cannot be established. It is independent from lifecycle finalization: a durably `final` call can still be partial in ASR or pricing. A client must not infer `no_usage`, finality, or a zero amount from any value of this field."},"persistence_complete":{"type":["boolean","null"],"description":"Durable persistence/finalization proof only. It is independent from price and measurement coverage, and must not make a UI total or a `no_usage` state by itself."},"usage_complete":{"type":["boolean","null"],"description":"Legacy compatibility coverage signal. It follows `measurement_complete` when present; neither field authorizes a lifecycle inference."},"measured_subtotal_usd":{"type":["number","null"],"description":"Floor in USD of only measured and priced units. It is null when no such subset is known and never a complete cost."},"total_usd":{"type":["number","null"],"description":"Complete AI cost in USD (6 decimals), or null when measurement or pricing is incomplete. It is never a zero inferred from missing data and never includes `measured_subtotal_usd` a second time."},"total_is_floor":{"type":"boolean","description":"True when `measured_subtotal_usd` is only a minimum priced measurement because some line is unmeasured or unpriced. It never turns null `total_usd` into a complete total."},"unpriced_lines":{"type":"integer"},"settlement":{"type":"string","enum":["reconciled","estimated","unpriced"],"description":"`reconciled` (the provider reported the cost, or the daily reconciliation matched), `estimated` (price book × measured usage) or `unpriced` (no price). At the top, the worst seal among the lines."},"price_version":{"type":["string","null"],"description":"Version of the price book used."},"first_recorded_at":{"type":["string","null"],"format":"date-time"},"last_recorded_at":{"type":["string","null"],"format":"date-time"},"lines":{"type":"array","description":"One line per role, purpose, provider and model — s2s, stt, llm, tts, then by cost.","items":{"type":"object","properties":{"role":{"type":"string","enum":["s2s","stt","llm","tts"],"description":"Speech-to-speech, transcription, language model or speech synthesis."},"purpose":{"type":["string","null"],"enum":["conversation","summary",null],"description":"For an `llm` line, whether it served the conversation or the post-call summary."},"surface":{"type":"string","enum":["realtime","stt","tts","call"]},"provider":{"type":["string","null"],"description":"Provider-defined string from the Maestro sidecar.","example":"openai"},"model":{"type":"string"},"rows":{"type":"integer","description":"Spend records behind the line."},"calls":{"type":"integer","description":"Provider requests behind the line."},"failures":{"type":"integer"},"input_tokens":{"type":"integer"},"output_tokens":{"type":"integer"},"cache_read_tokens":{"type":"integer"},"quantities":{"type":"array","description":"What the provider measured, in the unit it charges; two units are never merged.","items":{"type":"object","properties":{"unit":{"type":"string","description":"Provider-defined usage unit, e.g. audio_seconds, characters, audio_input_tokens.","example":"audio_seconds"},"quantity":{"type":"number"}}}},"usage_complete":{"type":["boolean","null"],"description":"Whether this measured line is complete. False or null keeps its quantities and price partial; it never authorizes a zero quantity or a `no_usage` call state."},"cost_usd":{"type":["number","null"],"description":"Null when `cost_priced` is false."},"cost_priced":{"type":"boolean"},"unpriced_reason":{"type":["string","null"],"enum":["model_not_in_price_table","no_official_rate","price_expired","provider_reported_no_usage","unit_not_priced","ambiguous_call",null],"description":"Reason this measured line cannot contribute a priced amount; it does not mean the line or call had no usage."},"cost_source":{"type":"string","enum":["estimated","provider_reported","mixed"]},"settlement":{"type":"string","enum":["reconciled","estimated","unpriced"],"description":"`reconciled` (the provider reported the cost, or the daily reconciliation matched), `estimated` (price book × measured usage) or `unpriced` (no price). At the top, the worst seal among the lines."},"key_origin":{"type":["string","null"],"enum":["agent","account","installation","env","mixed",null],"description":"Whose provider key paid for the line."},"price_version":{"type":["string","null"]}}}}}},"example":{"contract":"maestro.usage.call_cost.v1","account_id":1,"call_id":"8812","ref":"call:8812","conversation_id":4512,"currency":"USD","state":"final","liveness_known":true,"measurement_complete":true,"persistence_complete":true,"usage_complete":true,"measured_subtotal_usd":null,"total_usd":0.7152,"total_is_floor":false,"unpriced_lines":0,"settlement":"estimated","price_version":"2026-10-01","first_recorded_at":"2026-10-02T13:00:01+00:00","last_recorded_at":"2026-10-02T13:04:12+00:00","lines":[{"role":"s2s","purpose":"conversation","surface":"realtime","provider":"openai","model":"gpt-realtime","rows":1,"calls":1,"failures":0,"input_tokens":6120,"output_tokens":9010,"cache_read_tokens":0,"quantities":[{"unit":"audio_input_tokens","quantity":5120},{"unit":"text_input_tokens","quantity":1000},{"unit":"audio_output_tokens","quantity":8400},{"unit":"text_output_tokens","quantity":610}],"cost_usd":0.7152,"cost_priced":true,"unpriced_reason":null,"cost_source":"estimated","settlement":"estimated","key_origin":"installation","price_version":"2026-10-01","usage_complete":true}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"The `account_brain` feature is off for the account, or the call is not a call of this account.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}},"example":{"error":"Resource could not be found"}}}},"502":{"description":"The Maestro service could not be reached (connection refused or reset, host unresolvable), or it answered in a way the gateway could not use, or it rejected the server-to-server credential — the last one is a deployment key mismatch, never the caller's own session. Nothing was executed; the call can be retried.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"504":{"description":"The Maestro service did not answer within the proxy timeout. The work may still be running on the service side, so retrying a write can duplicate its effect.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"503":{"description":"Either the Maestro area is not serving this installation (turned off, or no admin key — `code` says which), or Maestro's spend tables are unavailable (`error: usage_unavailable`). Never answered with a zero cost.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["maestro_disabled","maestro_not_configured"]}}},"example":{"error":"usage_unavailable","code":"maestro_disabled"}}}},"422":{"description":"`call_id` is missing or is not a call id.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["invalid_call_id"]}}},"example":{"error":"invalid_call_id"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"call_id","in":"query","required":true,"description":"Id of the call in this account (not the provider's call id). A call of another account answers 404.","schema":{"type":"string","pattern":"^[0-9]{1,18}$","example":"8812"}}]}},"/api/v1/accounts/{account_id}/maestro/onboarding/briefing":{"get":{"tags":["Maestro"],"operationId":"auto_get_api_v1_accounts_account_id_maestro_onboarding_briefing","summary":"Briefing onboarding","description":"Performs the briefing operation on the targeted onboarding resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"status":{"type":"string"},"transcript":{"type":"string"},"proposal":{"type":"string"},"applied_agent_bot_id":{"type":"integer"},"updated_at":{"type":"string","format":"date-time"}}},"example":{"id":1,"status":"active","transcript":"sample transcript","proposal":"sample proposal","applied_agent_bot_id":1,"updated_at":"2026-01-15T10:30:00.000Z"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"503":{"description":"The Maestro area is not serving this installation: an operator turned it off, or no admin key was ever provisioned. Nothing was executed, and retrying will not help until the configuration changes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/maestro/onboarding/briefing_turn":{"post":{"tags":["Maestro"],"operationId":"auto_post_api_v1_accounts_account_id_maestro_onboarding_briefing_turn","summary":"Briefing turn onboarding","description":"Performs the briefing turn operation on the targeted onboarding resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Maestro indisponível"}}},"example":{"error":"Maestro indisponível"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"502":{"description":"The Maestro service could not be reached (connection refused or reset, host unresolvable), or it answered in a way the gateway could not use, or it rejected the server-to-server credential — the last one is a deployment key mismatch, never the caller's own session. Nothing was executed; the call can be retried.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"504":{"description":"The Maestro service did not answer within the proxy timeout. The work may still be running on the service side, so retrying a write can duplicate its effect.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"503":{"description":"The Maestro area is not serving this installation: an operator turned it off, or no admin key was ever provisioned. Nothing was executed, and retrying will not help until the configuration changes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"locale":{"type":"string"},"transcript":{"type":"array","items":{"type":"object","properties":{"role":{"type":"string","enum":["user","assistant"],"description":"Speaker of an onboarding interview transcript turn."},"content":{"type":"string"}}}}}},"example":{"message":"Sample message text.","locale":"en","transcript":[{"role":"user","content":"Sample content text."}]}}}}}},"/api/v1/accounts/{account_id}/maestro/onboarding/proposal":{"post":{"tags":["Maestro"],"operationId":"auto_post_api_v1_accounts_account_id_maestro_onboarding_proposal","summary":"Proposal onboarding","description":"Performs the proposal operation on the targeted onboarding resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Maestro indisponível"}}},"example":{"error":"Maestro indisponível"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"locale":{"type":"string"},"transcript":{"type":"array","items":{"type":"object","properties":{"role":{"type":"string","enum":["user","assistant"],"description":"Speaker of an onboarding interview transcript turn."},"content":{"type":"string"}}}}}},"example":{"locale":"en","transcript":[{"role":"user","content":"Sample content text."}]}}}}}},"/api/v1/accounts/{account_id}/maestro/onboarding/apply":{"post":{"tags":["Maestro"],"operationId":"auto_post_api_v1_accounts_account_id_maestro_onboarding_apply","summary":"Preview or apply reviewed Maestro onboarding agents","description":"Admin-only, native human-reviewed onboarding. A legacy request containing only `proposal` creates or reuses one principal agent. A request containing `topology` is always two-step: omit `expected_topology_fingerprint` to obtain and persist a no-write preview, then echo that exact account-bound fingerprint to apply. The platform verifies account-scoped inbox, team and AgentBot references, attaches the principal AgentBot to the selected inboxes, reconciles the sidecar bindings and records the sanitized result in the native briefing audit trail. Specialists remain internal Maestro agents and never receive direct inbox bindings. This operation is excluded from MCP because it can activate autonomous agents and external conversation delivery.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"No-write topology preview, completed topology apply, or legacy single-agent apply.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["ok"],"properties":{"ok":{"type":"boolean","example":true},"agent_id":{"type":["integer","null"],"example":31},"agent_bot_id":{"type":["integer","null"],"example":42},"created_agent":{"type":"boolean","example":true},"departments_provisioned":{"type":"array","items":{"type":"string"},"example":["atendimento","vendas","financeiro"]},"topology_preview":{"type":"boolean","example":true},"topology_fingerprint":{"type":["string","null"],"pattern":"^[0-9a-f]{64}$","example":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"},"agents":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["key","name","action","inbox_ids","delegate_keys"],"properties":{"key":{"type":"string","example":"principal"},"name":{"type":"string","example":"Principal"},"agent_id":{"type":["integer","null"],"example":31},"action":{"type":"string","enum":["create","replace","preserve"],"example":"create"},"inbox_ids":{"type":"array","items":{"type":["integer","null"]},"example":[15]},"delegate_keys":{"type":"array","items":{"type":"string"},"example":["suporte"]}}}},"warnings":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["code","data"],"properties":{"code":{"type":"string","example":"primary_agent_has_no_inbox_binding"},"data":{"type":"object","additionalProperties":true,"description":"Non-secret identifiers describing the warning context.","example":{"primary_agent_key":"principal"}}}}},"chatwoot_attachments":{"type":["object","null"],"additionalProperties":false,"properties":{"agent_bot_id":{"type":"integer","example":42},"requested_inbox_ids":{"type":"array","description":"Reviewed logical inbox ids; a single null means account-wide.","items":{"type":["integer","null"]},"example":[15]},"physical_inbox_ids":{"type":"array","items":{"type":"integer"},"example":[8,15]},"reconciled":{"type":"boolean","example":true}}}}},"example":{"ok":true,"agent_id":null,"agent_bot_id":null,"created_agent":false,"departments_provisioned":[],"topology_preview":true,"topology_fingerprint":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","agents":[{"key":"principal","name":"Principal","agent_id":null,"action":"create","inbox_ids":[15],"delegate_keys":["suporte"]}],"warnings":[{"code":"chatwoot_inbox_attachment_requires_reconciliation","data":{"primary_agent_key":"principal"}}],"chatwoot_attachments":null}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"502":{"description":"The Maestro service could not be reached (connection refused or reset, host unresolvable), or it answered in a way the gateway could not use, or it rejected the server-to-server credential — the last one is a deployment key mismatch, never the caller's own session. Nothing was executed; the call can be retried.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"504":{"description":"The Maestro service did not answer within the proxy timeout. The work may still be running on the service side, so retrying a write can duplicate its effect.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"503":{"description":"The Maestro area is not serving this installation: an operator turned it off, or no admin key was ever provisioned. Nothing was executed, and retrying will not help until the configuration changes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"proposal":{"type":"object","additionalProperties":true,"description":"The reviewed RobotProposal (free-form; the sidecar re-validates via Pydantic). When omitted, the persisted draft proposal for the account is used.","example":{"persona":"Friendly support assistant","instructions":"Answer product questions in pt_BR."}},"agent_bot_id":{"type":["integer","null"],"description":"Existing AgentBot to update instead of creating a new one.","example":42},"agent_name":{"type":"string","description":"Optional name for the legacy single-agent creation path.","example":"Principal"},"expected_topology_fingerprint":{"type":"string","pattern":"^[0-9a-f]{64}$","description":"Exact fingerprint returned by the preceding preview. Omit for preview.","example":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"},"topology":{"type":"object","additionalProperties":false,"required":["version","primary_agent_key","agents"],"properties":{"version":{"type":"integer","enum":[1],"example":1},"primary_agent_key":{"type":"string","pattern":"^[a-z0-9][a-z0-9_-]{0,59}$","example":"principal"},"agents":{"type":"array","minItems":1,"maxItems":20,"items":{"type":"object","additionalProperties":false,"required":["key","name"],"properties":{"key":{"type":"string","pattern":"^[a-z0-9][a-z0-9_-]{0,59}$","example":"principal"},"name":{"type":"string","example":"Principal"},"agent_id":{"type":["integer","null"],"description":"Existing same-account Maestro agent to adopt.","example":31},"enabled":{"type":"boolean","default":true,"example":true},"on_existing":{"type":"string","enum":["preserve","replace"],"default":"replace","example":"replace"},"config":{"type":"object","additionalProperties":true,"description":"Reviewed Maestro AgentConfig fields. The sidecar rejects secrets, unknown fields and commercial or financial write capabilities.","example":{"locale":"pt_BR","autonomy_level":"copilot","handoff_team_id":2}},"inbox_ids":{"type":"array","maxItems":20,"description":"Account inbox ids for the principal. A single null means account-wide. Specialists must use an empty list.","items":{"type":["integer","null"]},"example":[15]},"delegates":{"type":"array","maxItems":20,"items":{"type":"object","additionalProperties":false,"required":["target_key"],"properties":{"target_key":{"type":"string","example":"suporte"},"slug":{"type":"string","example":"suporte"},"name":{"type":"string","example":"Suporte"},"description":{"type":"string","example":"Especialista em suporte e produto."},"enabled":{"type":"boolean","default":true,"example":true},"sensitive":{"type":"boolean","default":false,"example":false}}}}}}}}}},"example":{"proposal":{"persona":"Coordenador de triagem","instructions":"Classifique e delegue cada atendimento."},"topology":{"version":1,"primary_agent_key":"principal","agents":[{"key":"principal","name":"Principal","inbox_ids":[15],"config":{"locale":"pt_BR","autonomy_level":"hybrid"},"delegates":[{"target_key":"suporte","slug":"suporte"}]},{"key":"suporte","name":"Suporte","inbox_ids":[],"config":{"locale":"pt_BR","autonomy_level":"copilot","handoff_team_id":2},"delegates":[]}]}}},"example":{"proposal":{"persona":"Coordenador de triagem","instructions":"Classifique e delegue cada atendimento."},"topology":{"version":1,"primary_agent_key":"principal","agents":[{"key":"principal","name":"Principal","inbox_ids":[15],"config":{"locale":"pt_BR","autonomy_level":"hybrid"},"delegates":[{"target_key":"suporte","slug":"suporte","name":"Suporte","description":"Especialista em suporte e produto.","enabled":true,"sensitive":false}],"agent_id":31,"enabled":true,"on_existing":"replace"},{"key":"suporte","name":"Suporte","inbox_ids":[],"config":{"locale":"pt_BR","autonomy_level":"copilot","handoff_team_id":2},"delegates":[{"target_key":"suporte","slug":"suporte","name":"Suporte","description":"Especialista em suporte e produto.","enabled":true,"sensitive":false}],"agent_id":31,"enabled":true,"on_existing":"replace"}]},"agent_bot_id":42,"agent_name":"Principal","expected_topology_fingerprint":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"}}}}}},"/api/v1/accounts/{account_id}/maestro/onboarding/realtime":{"post":{"tags":["Maestro"],"operationId":"auto_post_api_v1_accounts_account_id_maestro_onboarding_realtime","summary":"Realtime onboarding","description":"Performs the realtime operation on the targeted onboarding resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"fallback":{"type":"string","example":"dictation+chat"},"reason":{"type":"string","example":"realtime_unavailable"}}},"example":{"fallback":"dictation+chat","reason":"realtime_unavailable"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"502":{"description":"The Maestro service could not be reached (connection refused or reset, host unresolvable), or it answered in a way the gateway could not use, or it rejected the server-to-server credential — the last one is a deployment key mismatch, never the caller's own session. Nothing was executed; the call can be retried.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"504":{"description":"The Maestro service did not answer within the proxy timeout. The work may still be running on the service side, so retrying a write can duplicate its effect.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"503":{"description":"The Maestro area is not serving this installation: an operator turned it off, or no admin key was ever provisioned. Nothing was executed, and retrying will not help until the configuration changes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"locale":{"type":"string"}}},"example":{"locale":"en"}}}}}},"/api/v1/accounts/{account_id}/maestro/departments":{"get":{"tags":["Maestro"],"operationId":"auto_get_api_v1_accounts_account_id_maestro_departments","summary":"List the account brain department settings","description":"How each autonomous department of the account brain is configured: the autonomy tier it acts at, how often it sweeps, and whether it runs at all. A department with no stored configuration is simply absent from the list - it takes its shipped defaults until someone changes it.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The stored department configurations, ordered by department key.","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"account_id":{"type":"integer","description":"The account the configuration belongs to.","example":1},"department":{"type":"string","description":"Which department this configures. The shipped departments are `atendimento`, `vendas`, `risco`, `financeiro` and `conhecimento`; an unrecognized key is accepted and runs the no-op default until a department claims it.","example":"atendimento"},"autonomy_level":{"type":"string","description":"How far the department may act on its own. `read_only` only observes; `hitl` parks its proposals for a human to approve; `autonomous` executes them within its guardrails.","enum":["read_only","hitl","autonomous"],"example":"hitl"},"cadence_seconds":{"type":"integer","description":"Seconds between sweeps. Never faster than once a minute.","example":3600},"enabled":{"type":"boolean","description":"Whether the department sweeps at all.","example":true}}}},"example":[{"account_id":1,"department":"atendimento","autonomy_level":"hitl","cadence_seconds":3600,"enabled":true}]}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"502":{"description":"The Maestro service could not be reached (connection refused or reset, host unresolvable), or it answered in a way the gateway could not use, or it rejected the server-to-server credential — the last one is a deployment key mismatch, never the caller's own session. Nothing was executed; the call can be retried.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"504":{"description":"The Maestro service did not answer within the proxy timeout. The work may still be running on the service side, so retrying a write can duplicate its effect.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"503":{"description":"The Maestro area is not serving this installation: an operator turned it off, or no admin key was ever provisioned. Nothing was executed, and retrying will not help until the configuration changes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."}]}},"/api/v1/accounts/{account_id}/maestro/departments/runs":{"get":{"tags":["Maestro"],"operationId":"auto_get_api_v1_accounts_account_id_maestro_departments_runs","summary":"List account brain department runs","description":"The audit of department sweeps for the account, most recent first, optionally narrowed to one department or one status. Each run records what it did and how it ended - including the runs parked awaiting approval, which is where the brain's human-in-the-loop queue is read from.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The recorded runs, most recent first.","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Identifier of the run, used to approve or reject a parked one.","example":3187},"account_id":{"type":"integer","description":"The account the run belongs to.","example":1},"department":{"type":"string","description":"Which department swept.","example":"vendas"},"autonomy_level":{"type":"string","description":"The autonomy tier the run executed at.","enum":["read_only","hitl","autonomous"],"example":"hitl"},"status":{"type":"string","description":"How the run ended. `completed` finished; `pending` is still running; `failed` errored; `awaiting_approval` parked its proposals for a human, and is the only status a resume can act on.","enum":["completed","pending","failed","awaiting_approval"],"example":"awaiting_approval"},"started_at":{"type":["string","null"],"format":"date-time","description":"When the run began. Null when not recorded.","example":"2026-07-27T13:00:00+00:00"},"finished_at":{"type":["string","null"],"format":"date-time","description":"When the run ended. Null while it is still running or waiting on a human.","example":null},"actions":{"type":"array","description":"What the run did, or proposed to do while it waits for approval. Each entry names a tool with the arguments it ran or would run and how it ended.","items":{"type":"object","additionalProperties":true,"description":"One executed or proposed action, in the department's own shape.","example":{"tool":"crm_create_deal","status":"proposed"}}},"outcome":{"type":"object","description":"The run's own summary of what it concluded, in the shape its department writes. Also carries who resolved a parked run, once someone has.","additionalProperties":true,"example":{"summary":"2 oportunidades identificadas","resolved_by":"Ana Souza"}},"hitl_state":{"type":["object","null"],"description":"What a parked run is holding while it waits for a decision. Null on any run that never waited on a human.","additionalProperties":true,"example":{"proposals":2}}}}},"example":[{"id":3187,"account_id":1,"department":"vendas","autonomy_level":"hitl","status":"awaiting_approval","started_at":"2026-07-27T13:00:00+00:00","finished_at":null,"actions":[{"tool":"crm_create_deal","status":"proposed"}],"outcome":{"summary":"2 oportunidades identificadas","resolved_by":"Ana Souza"},"hitl_state":{"proposals":2}}]}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"502":{"description":"The Maestro service could not be reached (connection refused or reset, host unresolvable), or it answered in a way the gateway could not use, or it rejected the server-to-server credential — the last one is a deployment key mismatch, never the caller's own session. Nothing was executed; the call can be retried.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"504":{"description":"The Maestro service did not answer within the proxy timeout. The work may still be running on the service side, so retrying a write can duplicate its effect.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"503":{"description":"The Maestro area is not serving this installation: an operator turned it off, or no admin key was ever provisioned. Nothing was executed, and retrying will not help until the configuration changes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"department","in":"query","required":false,"description":"Restrict to runs of one department.","schema":{"type":"string"},"example":"support"},{"name":"status","in":"query","required":false,"description":"Restrict to runs in one state, forwarded verbatim to the Maestro service.","schema":{"type":"string"},"example":"completed"}]}},"/api/v1/accounts/{account_id}/maestro/departments/runs/{run_id}/resume":{"post":{"tags":["Maestro"],"operationId":"auto_post_api_v1_accounts_account_id_maestro_departments_runs_run_id_resume","summary":"Approve or reject a parked department run","description":"Resolves a run that parked its proposals for a human. Approving executes them through the real department executor, within that department's guardrails; rejecting completes the run having done nothing. Either way the run is closed, the deciding human is recorded on its outcome, and the updated run is answered. Administrators only. Runs are looked up within the account, so a run belonging to another account is simply not found.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The run as resolved, with its final status, actions and outcome.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer","description":"Identifier of the run, used to approve or reject a parked one.","example":3187},"account_id":{"type":"integer","description":"The account the run belongs to.","example":1},"department":{"type":"string","description":"Which department swept.","example":"vendas"},"autonomy_level":{"type":"string","description":"The autonomy tier the run executed at.","enum":["read_only","hitl","autonomous"],"example":"hitl"},"status":{"type":"string","description":"How the run ended. `completed` finished; `pending` is still running; `failed` errored; `awaiting_approval` parked its proposals for a human, and is the only status a resume can act on.","enum":["completed","pending","failed","awaiting_approval"],"example":"awaiting_approval"},"started_at":{"type":["string","null"],"format":"date-time","description":"When the run began. Null when not recorded.","example":"2026-07-27T13:00:00+00:00"},"finished_at":{"type":["string","null"],"format":"date-time","description":"When the run ended. Null while it is still running or waiting on a human.","example":null},"actions":{"type":"array","description":"What the run did, or proposed to do while it waits for approval. Each entry names a tool with the arguments it ran or would run and how it ended.","items":{"type":"object","additionalProperties":true,"description":"One executed or proposed action, in the department's own shape.","example":{"tool":"crm_create_deal","status":"proposed"}}},"outcome":{"type":"object","description":"The run's own summary of what it concluded, in the shape its department writes. Also carries who resolved a parked run, once someone has.","additionalProperties":true,"example":{"summary":"2 oportunidades identificadas","resolved_by":"Ana Souza"}},"hitl_state":{"type":["object","null"],"description":"What a parked run is holding while it waits for a decision. Null on any run that never waited on a human.","additionalProperties":true,"example":{"proposals":2}}}},"example":{"id":3187,"account_id":1,"department":"vendas","autonomy_level":"hitl","status":"awaiting_approval","started_at":"2026-07-27T13:00:00+00:00","finished_at":null,"actions":[{"tool":"crm_create_deal","status":"proposed"}],"outcome":{"summary":"2 oportunidades identificadas","resolved_by":"Ana Souza"},"hitl_state":{"proposals":2}}}}},"401":{"description":"Unauthorized"},"404":{"description":"No run with this identifier belongs to the account."},"502":{"description":"The Maestro service could not be reached (connection refused or reset, host unresolvable), or it answered in a way the gateway could not use, or it rejected the server-to-server credential — the last one is a deployment key mismatch, never the caller's own session. Nothing was executed; the call can be retried.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"504":{"description":"The Maestro service did not answer within the proxy timeout. The work may still be running on the service side, so retrying a write can duplicate its effect.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"503":{"description":"The Maestro area is not serving this installation: an operator turned it off, or no admin key was ever provisioned. Nothing was executed, and retrying will not help until the configuration changes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"403":{"description":"Only administrators can resolve a parked run."},"409":{"description":"The run is not awaiting approval - it already completed, failed, or is still running. Nothing was changed."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"run_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"department":{"type":"string"},"status":{"type":"string"},"approve":{"type":"string"}}},"example":{"department":"sample department","status":"active","approve":"sample approve"}}}}}},"/api/v1/accounts/{account_id}/maestro/departments/{id}":{"patch":{"tags":["Maestro"],"operationId":"auto_patch_api_v1_accounts_account_id_maestro_departments_id","summary":"Update one account brain department setting","description":"Changes a department's autonomy tier, cadence or on/off switch. Only the supplied fields are applied; a department with no stored configuration is created first, seeded conservatively at read-only with that department's shipped cadence. The cadence is floored at one minute, so a smaller value is stored as the floor rather than rejected. Administrators only. Answers with the configuration as stored.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The department configuration as stored.","content":{"application/json":{"schema":{"type":"object","properties":{"account_id":{"type":"integer","description":"The account the configuration belongs to.","example":1},"department":{"type":"string","description":"Which department this configures. The shipped departments are `atendimento`, `vendas`, `risco`, `financeiro` and `conhecimento`; an unrecognized key is accepted and runs the no-op default until a department claims it.","example":"atendimento"},"autonomy_level":{"type":"string","description":"How far the department may act on its own. `read_only` only observes; `hitl` parks its proposals for a human to approve; `autonomous` executes them within its guardrails.","enum":["read_only","hitl","autonomous"],"example":"hitl"},"cadence_seconds":{"type":"integer","description":"Seconds between sweeps. Never faster than once a minute.","example":3600},"enabled":{"type":"boolean","description":"Whether the department sweeps at all.","example":true}}},"example":{"account_id":1,"department":"vendas","autonomy_level":"autonomous","cadence_seconds":1800,"enabled":true}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"502":{"description":"The Maestro service could not be reached (connection refused or reset, host unresolvable), or it answered in a way the gateway could not use, or it rejected the server-to-server credential — the last one is a deployment key mismatch, never the caller's own session. Nothing was executed; the call can be retried.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"504":{"description":"The Maestro service did not answer within the proxy timeout. The work may still be running on the service side, so retrying a write can duplicate its effect.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"503":{"description":"The Maestro area is not serving this installation: an operator turned it off, or no admin key was ever provisioned. Nothing was executed, and retrying will not help until the configuration changes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"403":{"description":"Only administrators can change department settings."},"422":{"description":"The autonomy tier is not one of the three accepted values. Nothing was stored."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"autonomy_level":{"type":"string","enum":["read_only","hitl","autonomous"]},"cadence_seconds":{"type":"integer"},"enabled":{"type":"boolean"}}},"example":{"autonomy_level":"read_only","cadence_seconds":60,"enabled":true}}}}}},"/api/v1/accounts/{account_id}/maestro/dashboards":{"get":{"tags":["Maestro"],"operationId":"auto_get_api_v1_accounts_account_id_maestro_dashboards","summary":"Dashboards dashboards","description":"Performs the dashboards operation on the targeted dashboard resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The account's saved generative dashboards, newest first.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"spec":{"type":"object","additionalProperties":true,"description":"Declarative dashboard specification (KPIs, charts, filters) produced by the Maestro sidecar."},"layout":{"type":"object","additionalProperties":true,"description":"Per-account grid layout for the dashboard widgets."},"created_by_id":{"type":["integer","null"]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}}},"example":{"payload":[{"id":1,"name":"Sample Name","spec":{},"layout":{},"created_by_id":1,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"503":{"description":"The Maestro area is not serving this installation: an operator turned it off, or no admin key was ever provisioned. Nothing was executed, and retrying will not help until the configuration changes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/maestro/dashboards/generate":{"post":{"tags":["Maestro"],"operationId":"auto_post_api_v1_accounts_account_id_maestro_dashboards_generate","summary":"Generate dashboards","description":"Performs the generate operation on the targeted dashboard resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Maestro indisponível"}}},"example":{"error":"Maestro indisponível"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"502":{"description":"The Maestro service could not be reached (connection refused or reset, host unresolvable), or it answered in a way the gateway could not use, or it rejected the server-to-server credential — the last one is a deployment key mismatch, never the caller's own session. Nothing was executed; the call can be retried.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"504":{"description":"The Maestro service did not answer within the proxy timeout. The work may still be running on the service side, so retrying a write can duplicate its effect.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"503":{"description":"The Maestro area is not serving this installation: an operator turned it off, or no admin key was ever provisioned. Nothing was executed, and retrying will not help until the configuration changes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"request":{"type":"string"},"locale":{"type":"string","enum":["en","pt_BR","es"]},"filters":{"type":"object","additionalProperties":true,"description":"Free-form object."}}},"example":{"request":"sample request","locale":"en","filters":{}}}}}}},"/api/v1/accounts/{account_id}/maestro/dashboards/save":{"post":{"tags":["Maestro"],"operationId":"auto_post_api_v1_accounts_account_id_maestro_dashboards_save","summary":"Save dashboards","description":"Performs the save operation on the targeted dashboard resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"spec":{"type":"string"},"layout":{"type":"string"},"created_by_id":{"type":"integer"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"example":{"id":1,"name":"Sample Name","spec":"sample spec","layout":"sample layout","created_by_id":1,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"503":{"description":"The Maestro area is not serving this installation: an operator turned it off, or no admin key was ever provisioned. Nothing was executed, and retrying will not help until the configuration changes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"spec":{"type":"object","additionalProperties":true,"description":"Free-form object."},"layout":{"type":"object","additionalProperties":true,"description":"Free-form object."}}},"example":{"id":1,"name":"Sample Name","spec":{},"layout":{}}}}}}},"/api/v1/accounts/{account_id}/maestro/dashboards/{id}":{"delete":{"tags":["Maestro"],"operationId":"auto_delete_api_v1_accounts_account_id_maestro_dashboards_id","summary":"Delete dashboards","description":"Deletes the dashboard identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"204":{"description":"Success (no content)"},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"503":{"description":"The Maestro area is not serving this installation: an operator turned it off, or no admin key was ever provisioned. Nothing was executed, and retrying will not help until the configuration changes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/maestro/knowledge/sources":{"get":{"tags":["Maestro"],"operationId":"auto_get_api_v1_accounts_account_id_maestro_knowledge_sources","summary":"List the account brain knowledge sources","description":"The knowledge corpus feeding the account brain - the same shared base the account's Robôs query, read through the brain surface. Each entry is a source label with the number of chunks stored for it. Readable by any member of the account.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Every source in the account's knowledge corpus, with its chunk count.","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"source":{"type":"string","description":"Label the chunks are filed under. Deleting a source removes all of them.","example":"https://acme.com/policies/returns"},"chunks":{"type":"integer","description":"Number of embedded chunks stored for this source.","example":42}}}},"example":[{"source":"account:1:objectives","chunks":3},{"source":"politica-de-trocas.pdf","chunks":87}]}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"502":{"description":"The Maestro service could not be reached (connection refused or reset, host unresolvable), or it answered in a way the gateway could not use, or it rejected the server-to-server credential — the last one is a deployment key mismatch, never the caller's own session. Nothing was executed; the call can be retried.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"504":{"description":"The Maestro service did not answer within the proxy timeout. The work may still be running on the service side, so retrying a write can duplicate its effect.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"503":{"description":"The Maestro area is not serving this installation: an operator turned it off, or no admin key was ever provisioned. Nothing was executed, and retrying will not help until the configuration changes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]},"post":{"tags":["Maestro"],"operationId":"auto_post_api_v1_accounts_account_id_maestro_knowledge_sources","summary":"Add a source to the account brain knowledge corpus","description":"Feeds the account brain one source. A multipart file upload is stored first and handed to the ingester as a link, so the bytes are fetched and text-extracted server-side; a URL is fetched the same way; plain text is filed under a stable per-account label so re-saving the account objective replaces it instead of piling up duplicates. Administrators only. Answers with the stored label and how many chunks it produced.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The stored source label and the number of chunks it produced.","content":{"application/json":{"schema":{"type":"object","properties":{"source":{"type":"string","description":"Label the chunks are filed under. Deleting a source removes all of them.","example":"https://acme.com/policies/returns"},"chunks":{"type":"integer","description":"Number of embedded chunks stored for this source.","example":42}}},"example":{"source":"account:1:objectives","chunks":3}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"502":{"description":"The Maestro service could not be reached (connection refused or reset, host unresolvable), or it answered in a way the gateway could not use, or it rejected the server-to-server credential — the last one is a deployment key mismatch, never the caller's own session. Nothing was executed; the call can be retried.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"504":{"description":"The Maestro service did not answer within the proxy timeout. The work may still be running on the service side, so retrying a write can duplicate its effect.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"503":{"description":"The content could not be embedded - the embedding provider is unreachable, or its key has no credit left. Nothing was stored, so the same request can simply be retried."},"201":{"description":"The stored source label and the number of chunks it produced.","content":{"application/json":{"schema":{"type":"object","properties":{"source":{"type":"string","description":"Label the chunks are filed under. Deleting a source removes all of them.","example":"https://acme.com/policies/returns"},"chunks":{"type":"integer","description":"Number of embedded chunks stored for this source.","example":42}}},"example":{"source":"account:1:objectives","chunks":3}}}},"400":{"description":"Neither a file, a URL nor text was supplied, so there was nothing to ingest."},"403":{"description":"Only administrators can feed the account brain."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"file":{"type":"string"},"url":{"type":"string"},"source":{"type":"string"},"text":{"type":"string"}}},"example":{"file":"sample file","url":"https://example.com/resource","source":"sample source","text":"sample text"}}}}},"delete":{"tags":["Maestro"],"operationId":"auto_delete_api_v1_accounts_account_id_maestro_knowledge_sources","summary":"Destroy source knowledge","description":"Performs the destroy source operation on the targeted knowledge resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"502":{"description":"The Maestro service could not be reached (connection refused or reset, host unresolvable), or it answered in a way the gateway could not use, or it rejected the server-to-server credential — the last one is a deployment key mismatch, never the caller's own session. Nothing was executed; the call can be retried.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"504":{"description":"The Maestro service did not answer within the proxy timeout. The work may still be running on the service side, so retrying a write can duplicate its effect.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"503":{"description":"The Maestro area is not serving this installation: an operator turned it off, or no admin key was ever provisioned. Nothing was executed, and retrying will not help until the configuration changes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"204":{"description":"Every chunk of that source was removed from the account's shared knowledge base. No body."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/maestro/knowledge/embedding":{"get":{"tags":["Maestro"],"operationId":"auto_get_api_v1_accounts_account_id_maestro_knowledge_embedding","summary":"Get the account's knowledge-base embedding provider","description":"Returns the account's knowledge-base embedding provider choice (null means the installation default applies), the curated same-dimension provider registry the dashboard renders as a select, and the account's stored chunk count. Readable by any account member.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The current choice plus the selectable registry.","content":{"application/json":{"schema":{"type":"object","properties":{"provider":{"type":["string","null"],"enum":["openai","cohere",null],"description":"The account override; null = installation default.","example":"cohere"},"default_provider":{"type":"string","enum":["openai","cohere"],"description":"The installation-default provider applied when no override is set.","example":"openai"},"options":{"type":"array","description":"The curated same-dimension registry (safe to select — every entry matches the vector column width).","items":{"type":"object","properties":{"id":{"type":"string","enum":["openai","cohere"],"example":"cohere"},"model":{"type":"string","description":"The provider:model spec used for this choice.","example":"cohere:embed-v4.0"}},"additionalProperties":false}},"chunks":{"type":"integer","description":"The account's stored chunk count (agent KBs + shared base).","example":128}},"additionalProperties":false},"example":{"provider":"cohere","default_provider":"openai","options":[{"id":"openai","model":"openai:text-embedding-3-small"},{"id":"cohere","model":"cohere:embed-v4.0"}],"chunks":128}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"502":{"description":"The Maestro service could not be reached (connection refused or reset, host unresolvable), or it answered in a way the gateway could not use, or it rejected the server-to-server credential — the last one is a deployment key mismatch, never the caller's own session. Nothing was executed; the call can be retried.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"504":{"description":"The Maestro service did not answer within the proxy timeout. The work may still be running on the service side, so retrying a write can duplicate its effect.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"503":{"description":"The Maestro area is not serving this installation: an operator turned it off, or no admin key was ever provisioned. Nothing was executed, and retrying will not help until the configuration changes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]},"put":{"tags":["Maestro"],"operationId":"auto_put_api_v1_accounts_account_id_maestro_knowledge_embedding","summary":"Switch the account's knowledge-base embedding provider","description":"Sets (or clears, with a null provider) the account's knowledge-base embedding provider and enqueues an automatic re-index of every stored chunk, so retrieval keeps working after the switch. Administrator-only.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The stored choice (same shape as the read), with the re-index already enqueued.","content":{"application/json":{"schema":{"type":"object","properties":{"provider":{"type":["string","null"],"enum":["openai","cohere",null],"description":"The account override; null = installation default.","example":"cohere"},"default_provider":{"type":"string","enum":["openai","cohere"],"description":"The installation-default provider applied when no override is set.","example":"openai"},"options":{"type":"array","description":"The curated same-dimension registry (safe to select — every entry matches the vector column width).","items":{"type":"object","properties":{"id":{"type":"string","enum":["openai","cohere"],"example":"cohere"},"model":{"type":"string","description":"The provider:model spec used for this choice.","example":"cohere:embed-v4.0"}},"additionalProperties":false}},"chunks":{"type":"integer","description":"The account's stored chunk count (agent KBs + shared base).","example":128}},"additionalProperties":false},"example":{"provider":"cohere","default_provider":"openai","options":[{"id":"openai","model":"openai:text-embedding-3-small"},{"id":"cohere","model":"cohere:embed-v4.0"}],"chunks":128}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"502":{"description":"The Maestro service could not be reached (connection refused or reset, host unresolvable), or it answered in a way the gateway could not use, or it rejected the server-to-server credential — the last one is a deployment key mismatch, never the caller's own session. Nothing was executed; the call can be retried.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"504":{"description":"The Maestro service did not answer within the proxy timeout. The work may still be running on the service side, so retrying a write can duplicate its effect.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}},"503":{"description":"The Maestro area is not serving this installation: an operator turned it off, or no admin key was ever provisioned. Nothing was executed, and retrying will not help until the configuration changes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/maestro_transport_error"},"example":{"error":"Maestro indisponível","code":"maestro_unreachable"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"provider":{"type":["string","null"],"enum":["openai","cohere",null],"description":"A provider id from the registry, or null to return to the installation default.","example":"cohere"}},"additionalProperties":false},"example":{"provider":"cohere"}}}}}},"/api/v1/accounts/{account_id}/contact_inboxes/filter":{"post":{"tags":["Contact Inboxes"],"operationId":"auto_post_api_v1_accounts_account_id_contact_inboxes_filter","summary":"Filter contact inboxes","description":"Performs the filter operation on the targeted contact inbox resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"additional_attributes":{"type":"object","additionalProperties":true,"description":"Channel- and source-specific metadata for this record (e.g. browser info, referer, social profile identifiers). The key set depends on the originating channel."},"availability_status":{"type":"string","enum":["online","offline","busy"],"description":"Realtime availability. Contacts report online/offline (presence-based); agents/users additionally report busy (their configured availability)."},"email":{"type":"string","format":"email"},"id":{"type":"integer"},"name":{"type":"string"},"phone_number":{"type":"string"},"blocked":{"type":"string"},"contact_type":{"type":"string","enum":["visitor","lead","customer"]},"identifier":{"type":"string"},"company_id":{"type":"integer"},"organization_id":{"type":"integer"},"referred_by_affiliate_id":{"type":"integer"},"referred_by_affiliate_name":{"type":["string","null"]},"owner_id":{"type":"integer"},"legal_type":{"type":"string","enum":["individual","business"]},"tax_id":{"type":"string","description":"The fiscal identifier (CPF/CNPJ/EIN/VAT); validated and stored encrypted on write. Read payloads return the real value to an authenticated human agent, and a type-aware mask (e.g. \"***.***.***-09\") when a role field rule masks it or the caller is a bot; a hidden rule omits the key. Webhooks, exports and message variables always carry the masked form."},"tax_id_type":{"type":"string","enum":["br_cpf","br_cnpj","us_ein","eu_vat","uk_vat","generic"],"description":"The fiscal identifier scheme used to validate and mask the tax_id (CPF/CNPJ check digits, EIN, EU/UK VAT or a generic fallback)."},"country":{"type":"integer"},"address":{"type":"object","description":"Native postal address of the contact. Blank components are omitted.","properties":{"zip":{"type":"string","description":"Postal/ZIP code (CEP in Brazil)"},"street":{"type":"string","description":"Street name"},"number":{"type":"string","description":"Street number"},"complement":{"type":"string","description":"Address complement (apartment, suite, block)"},"neighborhood":{"type":"string","description":"Neighborhood/district"},"city":{"type":"string","description":"City name"},"state":{"type":"string","description":"State/province (UF in Brazil)"},"country":{"type":"string","description":"Country of the postal address"}}},"billing_address":{"type":"object","description":"Optional billing address override of the contact. An empty object means billing uses the principal address.","properties":{"zip":{"type":"string","description":"Postal/ZIP code (CEP in Brazil)"},"street":{"type":"string","description":"Street name"},"number":{"type":"string","description":"Street number"},"complement":{"type":"string","description":"Address complement (apartment, suite, block)"},"neighborhood":{"type":"string","description":"Neighborhood/district"},"city":{"type":"string","description":"City name"},"state":{"type":"string","description":"State/province (UF in Brazil)"},"country":{"type":"string","description":"Country of the postal address"}}},"thumbnail":{"type":"string"},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"last_activity_at":{"type":"integer"},"created_at":{"type":"integer"},"field_visibility":{"type":"string","enum":["visible","masked","hidden"],"description":"Per-field visibility resolved from the current access role's field_permissions (FieldVisibilityHelper). `visible` renders the real value, `masked` an obfuscated one, `hidden` omits the key entirely."},"contact_inboxes":{"type":"array","items":{"type":"object","properties":{"source_id":{"type":"integer"},"logical_inbox_id":{"type":"integer"},"inbox":{"type":"object","properties":{"id":{"type":"integer"},"avatar_url":{"type":"string"},"channel_id":{"type":"integer"},"name":{"type":"string"},"channel_type":{"type":"string","enum":["Channel::Api","Channel::Email","Channel::FacebookPage","Channel::Instagram","Channel::Line","Channel::Sms","Channel::Telegram","Channel::Tiktok","Channel::TwilioSms","Channel::TwitterProfile","Channel::WebWidget","Channel::Whatsapp"],"description":"The inbox channel class — identifies which messaging channel backs the inbox."},"provider":{"type":"string","enum":["default","whatsapp_cloud","whatsapp_web","google","microsoft"],"description":"Messaging provider backing the inbox channel (whatsapp_web is the WazMeow gateway; email uses google/microsoft; default otherwise)."}}}}}},"consent_state":{"type":"object","additionalProperties":{"type":"string","enum":["granted","denied","pending"],"description":"Consent state in force for this delivery channel."},"description":"LGPD consent state keyed by delivery channel (\"all\" is the account-wide scope that shadows the per-channel ones). A channel the contact never declared on is absent rather than pending, since the set of channels an account may use is open. Present only on single-contact payloads. Signals only — it never blocks a send."}}},"example":{"additional_attributes":{},"availability_status":"online","email":"agent@example.com","id":1,"name":"Sample Name","phone_number":"+5511999998888","blocked":"sample blocked","contact_type":"visitor","identifier":"sample-identifier","company_id":1,"organization_id":1,"referred_by_affiliate_id":1,"referred_by_affiliate_name":"sample referred by affiliate name","owner_id":1,"legal_type":"individual","tax_id":"sample tax id","tax_id_type":"br_cpf","country":1,"address":{"zip":"sample zip","street":"sample street","number":"sample number","complement":"sample complement","neighborhood":"sample neighborhood","city":"São Paulo","state":"active","country":"BR"},"billing_address":{"zip":"sample zip","street":"sample street","number":"sample number","complement":"sample complement","neighborhood":"sample neighborhood","city":"São Paulo","state":"active","country":"BR"},"thumbnail":"sample thumbnail","custom_attributes":{},"last_activity_at":1,"created_at":1,"field_visibility":"visible","contact_inboxes":[{"source_id":1,"logical_inbox_id":1,"inbox":{"id":1,"avatar_url":"https://example.com/resource","channel_id":1,"name":"Sample Name","channel_type":"Channel::Api","provider":"default"}}],"consent_state":{}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/assignable_agents":{"get":{"tags":["Assignable Agents"],"operationId":"auto_get_api_v1_accounts_account_id_assignable_agents","summary":"List assignable agents","description":"Lists agents eligible for every requested inbox, including administrators. Requires at least one positive inbox_ids array entry. Team-scoped navigation does not expand conversation permissions. Missing or malformed IDs return 422; nonexistent or inaccessible inboxes remain 404/401.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":["integer","null"]},"account_user_id":{"type":["integer","null"]},"availability_status":{"type":"string","enum":["online","offline","busy"],"description":"Realtime availability. Contacts report online/offline (presence-based); agents/users additionally report busy (their configured availability)."},"auto_offline":{"type":"boolean"},"confirmed":{"type":"boolean"},"email":{"type":"string","format":"email"},"provider":{"type":"string","enum":["email","google_oauth2","saml"],"description":"Authentication provider the user signed up through."},"available_name":{"type":"string"},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"name":{"type":"string"},"role":{"type":"string","enum":["agent","administrator"]},"outbound_agent_name_header_policy":{"type":["string","null"]},"thumbnail":{"type":"string"},"custom_role_id":{"type":["integer","null"]},"access_role_id":{"type":["integer","null"]}}}}}},"example":{"payload":[{"id":1,"account_id":1,"account_user_id":1,"availability_status":"online","auto_offline":true,"confirmed":true,"email":"agent@example.com","provider":"email","available_name":"sample available name","custom_attributes":{},"name":"Sample Name","role":"agent","outbound_agent_name_header_policy":"sample outbound agent name header policy","thumbnail":"sample thumbnail","custom_role_id":1,"access_role_id":1}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"422":{"description":"inbox_ids is absent, empty or malformed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["invalid_inbox_ids"]},"message":{"type":"string","description":"Localized explanation that inbox IDs are required."}}},"example":{"error":"invalid_inbox_ids","message":"Sample message text."}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."}]}},"/api/v1/accounts/{account_id}/callbacks/register_facebook_page":{"post":{"tags":["Callbacks"],"operationId":"auto_post_api_v1_accounts_account_id_callbacks_register_facebook_page","summary":"Register facebook page callbacks","description":"Performs the register facebook page operation on the targeted callback resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"channel_id":{"type":"integer"},"name":{"type":"string"},"channel_type":{"type":"string","enum":["Channel::Api","Channel::Email","Channel::FacebookPage","Channel::Instagram","Channel::Line","Channel::Sms","Channel::Telegram","Channel::Tiktok","Channel::TwilioSms","Channel::TwitterProfile","Channel::WebWidget","Channel::Whatsapp"],"description":"The inbox channel class — identifies which messaging channel backs the inbox."},"avatar_url":{"type":"string"},"page_id":{"type":"integer"},"enable_auto_assignment":{"type":"string"}}},"example":{"id":1,"channel_id":1,"name":"Sample Name","channel_type":"Channel::Api","avatar_url":"https://example.com/resource","page_id":1,"enable_auto_assignment":"sample enable auto assignment"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"user_access_token","in":"query","required":true,"description":"Long-lived Facebook USER access token obtained in the OAuth dance.","schema":{"type":"string"},"example":"EAAG..."},{"name":"page_access_token","in":"query","required":true,"description":"Page access token for the page being connected — this is what the channel sends with.","schema":{"type":"string"},"example":"EAAP..."},{"name":"page_id","in":"query","required":true,"description":"Numeric Facebook Page id to connect.","schema":{"type":"string"},"example":"102938475610293"},{"name":"inbox_name","in":"query","required":true,"description":"Name for the inbox created around the page.","schema":{"type":"string"},"example":"Support Page"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"user_access_token":{"type":"string"},"page_access_token":{"type":"string"},"page_id":{"type":"integer"},"inbox_name":{"type":"string"},"omniauth_token":{"type":"string"}}},"example":{"user_access_token":"sample-token","page_access_token":"sample-token","page_id":1,"inbox_name":"sample inbox name","omniauth_token":"sample-token"}}}}},"get":{"tags":["Callbacks"],"operationId":"auto_get_api_v1_accounts_account_id_callbacks_register_facebook_page","summary":"Register facebook page callbacks","description":"Performs the register facebook page operation on the targeted callback resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"channel_id":{"type":"integer"},"name":{"type":"string"},"channel_type":{"type":"string","enum":["Channel::Api","Channel::Email","Channel::FacebookPage","Channel::Instagram","Channel::Line","Channel::Sms","Channel::Telegram","Channel::Tiktok","Channel::TwilioSms","Channel::TwitterProfile","Channel::WebWidget","Channel::Whatsapp"],"description":"The inbox channel class — identifies which messaging channel backs the inbox."},"avatar_url":{"type":"string"},"page_id":{"type":"integer"},"enable_auto_assignment":{"type":"string"}}},"example":{"id":1,"channel_id":1,"name":"Sample Name","channel_type":"Channel::Api","avatar_url":"https://example.com/resource","page_id":1,"enable_auto_assignment":"sample enable auto assignment"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"user_access_token","in":"query","required":true,"description":"Long-lived Facebook USER access token obtained in the OAuth dance.","schema":{"type":"string"},"example":"EAAG..."},{"name":"page_access_token","in":"query","required":true,"description":"Page access token for the page being connected — this is what the channel sends with.","schema":{"type":"string"},"example":"EAAP..."},{"name":"page_id","in":"query","required":true,"description":"Numeric Facebook Page id to connect.","schema":{"type":"string"},"example":"102938475610293"},{"name":"inbox_name","in":"query","required":true,"description":"Name for the inbox created around the page.","schema":{"type":"string"},"example":"Support Page"}]}},"/api/v1/accounts/{account_id}/callbacks/facebook_pages":{"post":{"tags":["Callbacks"],"operationId":"auto_post_api_v1_accounts_account_id_callbacks_facebook_pages","summary":"Facebook pages callbacks","description":"Performs the facebook pages operation on the targeted callback resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"page_details":{"type":"string"},"user_access_token":{"type":"string"}}}}},"example":{"data":{"page_details":"sample page details","user_access_token":"sample-token"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"omniauth_token":{"type":"string"}}},"example":{"omniauth_token":"sample-token"}}}}}},"/api/v1/accounts/{account_id}/callbacks/reauthorize_page":{"post":{"tags":["Callbacks"],"operationId":"auto_post_api_v1_accounts_account_id_callbacks_reauthorize_page","summary":"Reauthorize page callbacks","description":"Performs the reauthorize page operation on the targeted callback resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"integer"},"avatar_url":{"type":"string"},"channel_id":{"type":"integer"},"name":{"type":"string"},"channel_type":{"type":"string","enum":["Channel::Api","Channel::Email","Channel::FacebookPage","Channel::Instagram","Channel::Line","Channel::Sms","Channel::Telegram","Channel::Tiktok","Channel::TwilioSms","Channel::TwitterProfile","Channel::WebWidget","Channel::Whatsapp"],"description":"The inbox channel class — identifies which messaging channel backs the inbox."},"greeting_enabled":{"type":"boolean"},"greeting_message":{"type":"string"},"working_hours_enabled":{"type":"boolean"},"enable_email_collect":{"type":"string"},"csat_survey_enabled":{"type":"boolean"},"csat_config":{"type":"string"},"enable_auto_assignment":{"type":"string"},"auto_assignment_config":{"type":"string"},"out_of_office_message":{"type":"string"},"working_hours":{"type":"string"},"timezone":{"type":"string","description":"IANA timezone identifier (e.g. \"America/Sao_Paulo\", \"UTC\"). Rails timezone names are also accepted on input; an unrecognized value is ignored in favor of the next fallback.","example":"America/Sao_Paulo"},"callback_webhook_url":{"type":"string"},"allow_messages_after_resolved":{"type":"string"},"lock_to_single_conversation":{"type":"string"},"audio_transcription_enabled":{"type":"boolean"},"preserve_deleted_messages":{"type":"string"},"allow_message_deletion":{"type":"string"},"capture_view_once":{"type":"string"},"sender_name_type":{"type":"string","enum":["friendly","professional"]},"auto_resolve_config":{"type":"object","additionalProperties":true,"oneOf":[{"type":"object","maxProperties":0,"additionalProperties":true,"description":"Empty means inherit the account rule."},{"type":"object","additionalProperties":false,"required":["mode"],"properties":{"mode":{"type":"string","enum":["disabled"],"description":"Disable automatic resolution for this inbox."}},"description":"The disabled rule contains only its mode."},{"type":"object","additionalProperties":false,"required":["mode","after","message","label","allow_waiting"],"properties":{"mode":{"type":"string","enum":["custom"],"description":"Use this complete inbox rule."},"after":{"type":"integer","minimum":10,"maximum":1439856,"description":"Inactivity in minutes; required for custom mode."},"message":{"type":["string","null"],"maxLength":10000,"description":"Optional message; blank normalizes to null."},"label":{"type":["string","null"],"description":"An existing account label title, or null."},"allow_waiting":{"type":"boolean","description":"Whether waiting conversations are included."}},"description":"Complete normalized custom rule."}],"description":"Normalized JSON rule from valid model writes: empty, disabled, or complete custom configuration.","example":{"mode":"custom","after":60,"message":null,"label":null,"allow_waiting":false}},"outbound_agent_name_header_policy":{"type":"string"},"agent_bot_working_hours_mode":{"type":"string","enum":["always","inside_business_hours","outside_business_hours"]},"business_name":{"type":"string"},"responder_policy":{"type":"string"},"help_center":{"type":"object","properties":{"name":{"type":"string"},"slug":{"type":"string"}}},"tweets_enabled":{"type":"boolean"},"allowed_domains":{"type":"string"},"widget_color":{"type":"string"},"website_url":{"type":"string"},"hmac_mandatory":{"type":"string"},"welcome_title":{"type":"string"},"welcome_tagline":{"type":"string"},"web_widget_script":{"type":"string"},"website_token":{"type":"string"},"selected_feature_flags":{"type":"string"},"reply_time":{"type":"string","format":"date-time"},"hmac_token":{"type":"string"},"pre_chat_form_enabled":{"type":"boolean"},"pre_chat_form_options":{"type":"string"},"continuity_via_email":{"type":"string","format":"email"},"page_id":{"type":"integer"},"reauthorization_required":{"type":"string"},"instagram_id":{"type":"integer"},"messaging_service_sid":{"type":"string"},"phone_number":{"type":"string"},"medium":{"type":"string"},"bandwidth_callback_state":{"type":"string","enum":["active","reconnect_required","reconciling","reconciliation_required","encryption_required"]},"bandwidth_api_migration_state":{"type":"string","enum":["oauth2_configured","oauth2_required","configuration_required"]},"bandwidth_legacy_basic_deprecated":{"type":"boolean"},"content_templates":{"type":"string"},"auth_token":{"type":"string"},"account_sid":{"type":"string"},"api_key_sid":{"type":"string"},"twilio_credential_state":{"type":"string","enum":["ready","pending","failed","dead_letter","account_auth_token_required","reconciliation_required"],"description":"Durable Twilio credential lifecycle derived from Channel::TwilioSms. A reconciliation-required state is fail-closed until the provider outcome has been verified."},"api_key_configured":{"type":"boolean"},"email":{"type":"string","format":"email"},"auth_method":{"type":"string"},"forwarding_enabled":{"type":"boolean"},"forward_to_email":{"type":"string","format":"email"},"branded_email_layout":{"type":"string"},"imap_login":{"type":"string"},"imap_password":{"type":"string"},"imap_address":{"type":"string"},"imap_port":{"type":"string"},"imap_enabled":{"type":"boolean"},"imap_enable_ssl":{"type":"string"},"imap_authentication":{"type":"string"},"smtp_login":{"type":"string"},"smtp_password":{"type":"string"},"smtp_address":{"type":"string"},"smtp_port":{"type":"string"},"smtp_enabled":{"type":"boolean"},"smtp_domain":{"type":"string"},"smtp_enable_ssl_tls":{"type":"string"},"smtp_enable_starttls_auto":{"type":"string"},"smtp_openssl_verify_mode":{"type":"string","enum":["none","peer","client_once","fail_if_no_peer_cert"],"description":"OpenSSL peer-certificate verification mode for the email channel's SMTP connection."},"smtp_authentication":{"type":"string"},"secret":{"type":"string"},"webhook_url":{"type":"string"},"inbox_identifier":{"type":"string"},"additional_attributes":{"type":"object","additionalProperties":true,"description":"Channel- and source-specific metadata for this record (e.g. browser info, referer, social profile identifiers). The key set depends on the originating channel."},"provider":{"type":"string","enum":["default","whatsapp_cloud","whatsapp_web","google","microsoft"],"description":"Messaging provider backing the inbox channel (whatsapp_web is the WazMeow gateway; email uses google/microsoft; default otherwise)."},"bot_name":{"type":"string"},"message_templates":{"type":"boolean"},"provider_config":{"type":"string"},"business_management_token_configured":{"type":"boolean"},"hybrid_pair":{"$ref":"#/components/schemas/inbox/properties/hybrid_pair"},"whatsapp_web_session_state":{"$ref":"#/components/schemas/inbox/properties/whatsapp_web_session_state"},"hybrid_hidden":{"type":"string"},"logical_inbox_id":{"type":"integer"},"whatsapp_pending_phone":{"type":"object","nullable":true,"description":"Spec 052 — set only when a WhatsApp phone-number rewrite was REFUSED because a non-sibling channel already holds the number, leaving the inbox on its `pending:` placeholder and inert. `null` in every normal case (including a routine, not-yet-scanned pairing).","additionalProperties":false,"properties":{"awaiting_pair":{"type":"boolean","description":"True while the inbox is still on its `pending:\u003cuuid\u003e` placeholder number."},"phone":{"type":"string","description":"The E.164 number the rewrite tried to claim."},"reason":{"type":"string","enum":["same_account_same_provider","other_account"],"description":"Why the rewrite was refused. `other_account` never carries any identifying detail about the other account."},"sibling_inbox_id":{"type":"integer","nullable":true,"description":"Colliding inbox in the SAME account; absent when the collision is cross-account."},"source":{"type":"string","enum":["pair_success","qr_pump"],"description":"Which path attempted the rewrite."},"at":{"type":"string","format":"date-time","description":"When the refusal was recorded."}}},"whatsapp_sibling_notice":{"type":"string"},"whatsapp_web_contact_request":{"type":"string","enum":["supported","unsupported","unknown"],"description":"WhatsApp Web inboxes only — whether this inbox's WazMeow gateway serves the request that asks a customer to share their phone number. `supported` and `unsupported` come from a no-effect probe of the gateway route, refreshed at most hourly and immediately when a real send finds the route missing; `unknown` means not probed yet or the gateway could not be reached. Only `supported` turns the feature on; with `unknown` the request is refused before any gateway call while the probe runs."},"voice_enabled":{"type":"boolean"},"inbound_calls_enabled":{"type":"boolean"},"voice_configured":{"type":"boolean"},"voice_call_webhook_url":{"type":"string"},"voice_status_webhook_url":{"type":"string"}}}}},"example":{"data":{"id":1,"avatar_url":"https://example.com/resource","channel_id":1,"name":"Sample Name","channel_type":"Channel::Api","greeting_enabled":true,"greeting_message":"sample greeting message","working_hours_enabled":true,"enable_email_collect":"agent@example.com","csat_survey_enabled":true,"csat_config":"sample csat config","enable_auto_assignment":"sample enable auto assignment","auto_assignment_config":"sample auto assignment config","out_of_office_message":"sample out of office message","working_hours":"sample working hours","timezone":"America/Sao_Paulo","callback_webhook_url":"https://example.com/resource","allow_messages_after_resolved":"sample allow messages after resolved","lock_to_single_conversation":"sample lock to single conversation","audio_transcription_enabled":true,"preserve_deleted_messages":"sample preserve deleted messages","allow_message_deletion":"sample allow message deletion","capture_view_once":"sample capture view once","sender_name_type":"friendly","auto_resolve_config":{"mode":"custom","after":60,"message":null,"label":null,"allow_waiting":false},"outbound_agent_name_header_policy":"sample outbound agent name header policy","agent_bot_working_hours_mode":"always","business_name":"sample business name","responder_policy":"sample responder policy","help_center":{"name":"Sample Name","slug":"sample-slug"},"tweets_enabled":true,"allowed_domains":"sample allowed domains","widget_color":"#1F93FF","website_url":"https://example.com/resource","hmac_mandatory":"sample hmac mandatory","welcome_title":"sample welcome title","welcome_tagline":"sample welcome tagline","web_widget_script":"sample web widget script","website_token":"sample-token","selected_feature_flags":"sample selected feature flags","reply_time":"2026-01-15T10:30:00.000Z","hmac_token":"sample-token","pre_chat_form_enabled":true,"pre_chat_form_options":"sample pre chat form options","continuity_via_email":"agent@example.com","page_id":1,"reauthorization_required":"sample reauthorization required","instagram_id":1,"messaging_service_sid":"sample messaging service sid","phone_number":"+5511999998888","medium":"sample medium","bandwidth_callback_state":"active","bandwidth_api_migration_state":"oauth2_configured","bandwidth_legacy_basic_deprecated":true,"content_templates":"sample content templates","auth_token":"sample-token","account_sid":"sample account sid","api_key_sid":"sample api key sid","twilio_credential_state":"ready","api_key_configured":true,"email":"agent@example.com","auth_method":"sample auth method","forwarding_enabled":true,"forward_to_email":"agent@example.com","branded_email_layout":"agent@example.com","imap_login":"sample imap login","imap_password":"sample imap password","imap_address":"sample imap address","imap_port":"sample imap port","imap_enabled":true,"imap_enable_ssl":"sample imap enable ssl","imap_authentication":"sample imap authentication","smtp_login":"sample smtp login","smtp_password":"sample smtp password","smtp_address":"sample smtp address","smtp_port":"sample smtp port","smtp_enabled":true,"smtp_domain":"sample smtp domain","smtp_enable_ssl_tls":"sample smtp enable ssl tls","smtp_enable_starttls_auto":"sample smtp enable starttls auto","smtp_openssl_verify_mode":"none","smtp_authentication":"sample smtp authentication","secret":"sample-token","webhook_url":"https://example.com/resource","inbox_identifier":"sample inbox identifier","additional_attributes":{},"provider":"default","bot_name":"sample bot name","message_templates":true,"provider_config":"sample provider config","business_management_token_configured":true,"hybrid_pair":{"paired":true,"id":4,"role":"cloud","sibling_inbox_id":18,"canonical_phone":"+5521900000000","primary":"cloud","inbound_authority":"cloud","unified_inbox":true,"unified_state":{"state":"complete","scanned":42,"frozen":40,"reconciled_count":2,"completed_at":"2026-10-03T12:00:00.000Z","blocked_conversations":[]},"routing":{"outbound_default":"cloud","out_of_window":"web","fallback":true,"manual_override":true,"weighted":{"mode":"weighted","web_percent":30,"version":2}},"web_channel_id":12,"web_inbox_id":18,"calling_provider":"whatsapp_web","web_voice_enabled":true,"web_inbound_calls_enabled":true,"web_call_config_sync":{"state":"pending","checked_at":"2026-10-03T12:00:00.000Z"},"web_video_calls_enabled":false,"web_group_calls_enabled":false,"web_reauthorization_required":false,"web_session_state":{"state":"connected","fresh":true,"observed_at":"2026-10-03T12:00:00.000Z","disconnected_since":null},"web_allow_message_deletion":true},"whatsapp_web_session_state":{"state":"connected","fresh":true,"observed_at":"2026-01-15T10:30:00.000Z","disconnected_since":null},"hybrid_hidden":"sample hybrid hidden","logical_inbox_id":1,"whatsapp_pending_phone":{"awaiting_pair":true,"phone":"+5511999998888","reason":"same_account_same_provider","sibling_inbox_id":1,"source":"pair_success","at":"2026-01-15T10:30:00.000Z"},"whatsapp_sibling_notice":"sample whatsapp sibling notice","whatsapp_web_contact_request":"supported","voice_enabled":true,"inbound_calls_enabled":true,"voice_configured":true,"voice_call_webhook_url":"https://example.com/resource","voice_status_webhook_url":"https://example.com/resource"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"422":{"description":"The selected inbox is not a Facebook inbox, its page is no longer available to the user, or reauthorization cannot be completed. The response has no body."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"inbox_id":{"type":"integer"},"omniauth_token":{"type":"string"}}},"example":{"inbox_id":1,"omniauth_token":"sample-token"}}}}}},"/api/v1/accounts/{account_id}/messaging/variables":{"get":{"tags":["Messaging"],"operationId":"auto_get_api_v1_accounts_account_id_messaging_variables","summary":"List the dynamic message variables, and what they currently render","description":"The canonical `{{ }}` vocabulary of the account, derived from the message Drops themselves — the single source a variable can be declared in, so a token can only be offered if it actually resolves. Grouped by namespace (contact, conversation, crm, payment, booking, brand, now, ...), each token carrying the i18n key of its label.\n\nPass `scope` to narrow the catalog to what a given surface can resolve: a campaign has no conversation, and a blank render in the HSM processor SKIPS the recipient, so withholding a prefix there is not cosmetic.\n\nPass `conversation_id` (the conversation's display id) to additionally receive `values` — what each token renders RIGHT NOW for that conversation, resolved by the same renderer the send path uses. The conversation is authorized like any other read, and field-level (Layer 3) masking is applied, so a masked contact field previews masked. A token that renders blank is omitted rather than returned empty. Without `conversation_id` the response is a pure vocabulary read and `values` is an empty object.\n\nThe Brain variables (`brain.*`) are the reading of the conversation asked about: its own risk score and band, else its contact's, never another conversation's. The insight variables name only a type, a severity and a department — of the insight about that conversation or its contact, else of the latest insight about the account as a whole — and never of an insight flagged `sensitive`. They are previewed exactly as a message sent in that conversation renders them, for every caller the conversation is authorized for; a value there is none of is omitted.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The variable catalog for the requested scope, plus resolved values when asked.","content":{"application/json":{"schema":{"type":"object","properties":{"scope":{"type":"string","description":"The scope that was applied; `all` when none was requested.","example":"conversation"},"attribute_model_prefixes":{"type":"object","description":"Custom-attribute model → token prefix, for all 11 attribute models. The client namespaces the account's own custom attributes with this, so an attribute on any model produces a token that resolves.","additionalProperties":{"type":"string"},"example":{"contact_attribute":"contact","conversation_attribute":"conversation","crm_item_attribute":"crm","payment_charge_attribute":"payment"}},"values":{"type":"object","description":"Token → what it renders for the requested conversation. Empty when no `conversation_id` was given; a token that renders blank is absent rather than empty.","additionalProperties":{"type":"string"},"example":{"contact.name":"Ana Souza","contact.email":"ana@example.com","conversation.display_id":"42"}},"groups":{"type":"array","description":"One entry per namespace, in presentation order.","items":{"type":"object","properties":{"group":{"type":"string","description":"The namespace prefix — the part before the dot in every token.","example":"contact"},"i18n_key":{"type":"string","description":"Translation key of the group heading.","example":"VARIABLE_PICKER.GROUPS.CONTACT"},"attribute_model":{"type":["string","null"],"description":"The custom-attribute model whose attributes extend this namespace, or null when the namespace has none.","example":"contact_attribute"},"tokens":{"type":"array","items":{"type":"object","properties":{"token":{"type":"string","description":"The token to write between `{{ }}`.","example":"contact.name"},"i18n_key":{"type":"string","description":"Translation key of the token label.","example":"MESSAGE_VARIABLES.CONTACT.NAME"}}}}}}}}},"example":{"scope":"conversation","attribute_model_prefixes":{"contact_attribute":"contact","conversation_attribute":"conversation","crm_item_attribute":"crm","payment_charge_attribute":"payment"},"values":{"contact.name":"Ana Souza","contact.email":"ana@example.com","conversation.display_id":"42"},"groups":[{"group":"contact","i18n_key":"VARIABLE_PICKER.GROUPS.CONTACT","attribute_model":"contact_attribute","tokens":[{"token":"contact.name","i18n_key":"MESSAGE_VARIABLES.CONTACT.NAME"},{"token":"contact.email","i18n_key":"MESSAGE_VARIABLES.CONTACT.EMAIL"}]},{"group":"conversation","i18n_key":"VARIABLE_PICKER.GROUPS.CONVERSATION","attribute_model":"conversation_attribute","tokens":[{"token":"conversation.display_id","i18n_key":"MESSAGE_VARIABLES.CONVERSATION.DISPLAY_ID"}]}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"scope","in":"query","required":false,"description":"The surface asking. Narrows the catalog to the namespaces that resolve there. Omit for the full vocabulary. Automation and macro action fields ask for `automation` (a macro) or `automation:\u003cevent_name\u003e` (a rule, e.g. `automation:contact_created`): those scopes never offer the flow runtime roots nor the override-only roots (product, campaign, group, article), and a contact or company event also withholds the conversation-derived roots (conversation, inbox, agent, team, sla), because the action renderer has no conversation there.","schema":{"type":"string","example":"automation:conversation_created"}},{"name":"conversation_id","in":"query","required":false,"description":"Conversation display id. When given, `values` carries what each token renders for it. Ignored (values stay empty) when the conversation does not exist in this account or the user cannot open it.","schema":{"type":"integer","example":42}}]}},"/api/v1/accounts/{account_id}/automation_rules/{automation_rule_id}/clone":{"post":{"tags":["Automation Rule"],"operationId":"auto_post_api_v1_accounts_account_id_automation_rules_automation_rule_id_clone","summary":"Clone automation rules","description":"Performs the clone operation on the targeted automation rule resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}},"example":{"error":"sample error"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_rule_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/macros/{id}/execute":{"post":{"tags":["Macros"],"operationId":"auto_post_api_v1_accounts_account_id_macros_id_execute","summary":"Run a macro over conversations","description":"Runs every action of the macro against the listed conversations, on behalf of the calling agent. The work is queued and carried out in the background, so the call returns as soon as it is accepted and not when the actions have finished; conversations that do not belong to the account are skipped. The response carries no body, so it reports neither the queued count nor the per-conversation outcome.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Macro execution queued for the listed conversations. Empty body."},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"503":{"description":"The operator is holding Maestro macros for an update or rollback and the caller is the Maestro service identity. Nothing was queued. People, and accounts the operator released from the hold, are not affected.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","enum":["human_capability_unavailable"],"description":"Refusal code from the versioned human macro delegation contract."}}},"example":{"error":"human_capability_unavailable"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"conversation_ids":{"type":"array","description":"Display IDs of the conversations to run the macro on — the per-account number shown in the dashboard, not the global conversation ID. NOT enforced: the job coerces a missing list to empty and returns early, so omitting it still answers 2xx and simply runs nothing. Declared optional here because declaring it required would describe a rejection the server does not perform.","items":{"type":"integer"}}}},"example":{"conversation_ids":[7,12]}}}}}},"/api/v1/accounts/{account_id}/macros/{id}/delegated_execute":{"post":{"tags":["Macros"],"operationId":"auto_post_api_v1_accounts_account_id_macros_id_delegated_execute","summary":"Run a macro on behalf of a signed human","description":"Enqueues one macro on one conversation as the person who asked for it, using a short-lived capability that Chatwoot signed for that authenticated account member, this macro and this conversation. The authenticated caller is never the actor, and Application API authentication alone never authorizes the run. The person's membership, macro access and conversation access are checked again here and once more when the execution job runs. Repeating the same request returns the first receipt without enqueuing again.","security":[{"userApiKey":[]}],"responses":{"202":{"description":"The macro was enqueued to run as the signed person.","content":{"application/json":{"schema":{"type":"object","required":["status","macro_id","conversation_id"],"properties":{"status":{"type":"string","enum":["enqueued"],"description":"The execution was queued; the job re-checks the person's access before any effect."},"macro_id":{"type":"integer","description":"Macro that was enqueued."},"conversation_id":{"type":"integer","description":"Conversation display id the macro runs on."}}},"example":{"status":"enqueued","macro_id":12,"conversation_id":4821}}}},"401":{"description":"Unauthorized"},"404":{"description":"The macro or the signed conversation does not exist in this account.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","enum":["conversation_access_denied","conversation_not_found","human_action_in_progress","human_action_outcome_unknown","human_actor_required","human_capability_unavailable","human_macro_request_invalid","macro_access_denied","macro_not_found"],"description":"Refusal code from the versioned human macro delegation contract."}}},"example":{"error":"macro_not_found"}}}},"403":{"description":"Missing or invalid human capability, or the person can no longer run this macro or see this conversation.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","enum":["conversation_access_denied","conversation_not_found","human_action_in_progress","human_action_outcome_unknown","human_actor_required","human_capability_unavailable","human_macro_request_invalid","macro_access_denied","macro_not_found"],"description":"Refusal code from the versioned human macro delegation contract."}}},"example":{"error":"macro_access_denied"}}}},"409":{"description":"The same request is still running or its first outcome is unknown; do not retry the effect.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","enum":["conversation_access_denied","conversation_not_found","human_action_in_progress","human_action_outcome_unknown","human_actor_required","human_capability_unavailable","human_macro_request_invalid","macro_access_denied","macro_not_found"],"description":"Refusal code from the versioned human macro delegation contract."}}},"example":{"error":"human_action_outcome_unknown"}}}},"422":{"description":"The body is not exactly one integer conversation id matching the signed conversation.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","enum":["conversation_access_denied","conversation_not_found","human_action_in_progress","human_action_outcome_unknown","human_actor_required","human_capability_unavailable","human_macro_request_invalid","macro_access_denied","macro_not_found"],"description":"Refusal code from the versioned human macro delegation contract."}}},"example":{"error":"human_macro_request_invalid"}}}},"503":{"description":"The capability or its execution receipt could not be checked; nothing was enqueued.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","enum":["conversation_access_denied","conversation_not_found","human_action_in_progress","human_action_outcome_unknown","human_actor_required","human_capability_unavailable","human_macro_request_invalid","macro_access_denied","macro_not_found"],"description":"Refusal code from the versioned human macro delegation contract."}}},"example":{"error":"human_capability_unavailable"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"in":"path","name":"id","required":true,"description":"Macro id in this account.","schema":{"type":"integer"},"example":12},{"in":"header","name":"X-Maestro-Human-Capability","required":true,"schema":{"type":"string","writeOnly":true},"description":"Runtime-only signed capability; never supplied by a model or logged."},{"in":"header","name":"X-Maestro-Human-Request-Id","required":true,"schema":{"type":"string"},"description":"Request identifier the capability was signed for; `pending:\u003cid\u003e` for an approval.","example":"pending:7f3c1b90a1b24c55b6e0d2a9c4f81e63"},{"in":"header","name":"X-Maestro-Human-Conversation-Id","required":true,"schema":{"type":"string"},"description":"Account-scoped conversation display id the capability was signed for.","example":"4821"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["conversation_id"],"additionalProperties":false,"properties":{"conversation_id":{"type":"integer","description":"Account-scoped conversation display id; must match the signed conversation.","example":4821}}},"example":{"conversation_id":4821}}}}}},"/api/v1/accounts/{account_id}/macros":{"get":{"tags":["Macros"],"operationId":"auto_get_api_v1_accounts_account_id_macros","summary":"List macros","description":"Returns the list of macros visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"visibility":{"type":"string","enum":["personal","global","selective"]},"visibility_config":{"type":"string"},"created_by":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":["integer","null"]},"account_user_id":{"type":["integer","null"]},"availability_status":{"type":"string","enum":["online","offline","busy"],"description":"Realtime availability. Contacts report online/offline (presence-based); agents/users additionally report busy (their configured availability)."},"auto_offline":{"type":"boolean"},"confirmed":{"type":"boolean"},"email":{"type":"string","format":"email"},"provider":{"type":"string","enum":["email","google_oauth2","saml"],"description":"Authentication provider the user signed up through."},"available_name":{"type":"string"},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"name":{"type":"string"},"role":{"type":"string","enum":["agent","administrator"]},"outbound_agent_name_header_policy":{"type":["string","null"]},"thumbnail":{"type":"string"},"custom_role_id":{"type":["integer","null"]},"access_role_id":{"type":["integer","null"]}}},"updated_by":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":["integer","null"]},"account_user_id":{"type":["integer","null"]},"availability_status":{"type":"string","enum":["online","offline","busy"],"description":"Realtime availability. Contacts report online/offline (presence-based); agents/users additionally report busy (their configured availability)."},"auto_offline":{"type":"boolean"},"confirmed":{"type":"boolean"},"email":{"type":"string","format":"email"},"provider":{"type":"string","enum":["email","google_oauth2","saml"],"description":"Authentication provider the user signed up through."},"available_name":{"type":"string"},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"name":{"type":"string"},"role":{"type":"string","enum":["agent","administrator"]},"outbound_agent_name_header_policy":{"type":["string","null"]},"thumbnail":{"type":"string"},"custom_role_id":{"type":["integer","null"]},"access_role_id":{"type":["integer","null"]}}},"account_id":{"type":"integer"},"actions":{"type":"string"},"files":{"type":"string"}}}}}},"example":{"payload":[{"id":1,"name":"Sample Name","visibility":"personal","visibility_config":"sample visibility config","created_by":{"id":1,"account_id":1,"account_user_id":1,"availability_status":"online","auto_offline":true,"confirmed":true,"email":"agent@example.com","provider":"email","available_name":"sample available name","custom_attributes":{},"name":"Sample Name","role":"agent","outbound_agent_name_header_policy":"sample outbound agent name header policy","thumbnail":"sample thumbnail","custom_role_id":1,"access_role_id":1},"updated_by":{"id":1,"account_id":1,"account_user_id":1,"availability_status":"online","auto_offline":true,"confirmed":true,"email":"agent@example.com","provider":"email","available_name":"sample available name","custom_attributes":{},"name":"Sample Name","role":"agent","outbound_agent_name_header_policy":"sample outbound agent name header policy","thumbnail":"sample thumbnail","custom_role_id":1,"access_role_id":1},"account_id":1,"actions":"sample actions","files":"sample files"}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."}]},"post":{"tags":["Macros"],"operationId":"auto_post_api_v1_accounts_account_id_macros","summary":"Create macros","description":"Creates a new macro from the request payload. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"visibility":{"type":"string","enum":["personal","global","selective"]},"visibility_config":{"type":"string"},"created_by":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":["integer","null"]},"account_user_id":{"type":["integer","null"]},"availability_status":{"type":"string","enum":["online","offline","busy"],"description":"Realtime availability. Contacts report online/offline (presence-based); agents/users additionally report busy (their configured availability)."},"auto_offline":{"type":"boolean"},"confirmed":{"type":"boolean"},"email":{"type":"string","format":"email"},"provider":{"type":"string","enum":["email","google_oauth2","saml"],"description":"Authentication provider the user signed up through."},"available_name":{"type":"string"},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"name":{"type":"string"},"role":{"type":"string","enum":["agent","administrator"]},"outbound_agent_name_header_policy":{"type":["string","null"]},"thumbnail":{"type":"string"},"custom_role_id":{"type":["integer","null"]},"access_role_id":{"type":["integer","null"]}}},"updated_by":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":["integer","null"]},"account_user_id":{"type":["integer","null"]},"availability_status":{"type":"string","enum":["online","offline","busy"],"description":"Realtime availability. Contacts report online/offline (presence-based); agents/users additionally report busy (their configured availability)."},"auto_offline":{"type":"boolean"},"confirmed":{"type":"boolean"},"email":{"type":"string","format":"email"},"provider":{"type":"string","enum":["email","google_oauth2","saml"],"description":"Authentication provider the user signed up through."},"available_name":{"type":"string"},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"name":{"type":"string"},"role":{"type":"string","enum":["agent","administrator"]},"outbound_agent_name_header_policy":{"type":["string","null"]},"thumbnail":{"type":"string"},"custom_role_id":{"type":["integer","null"]},"access_role_id":{"type":["integer","null"]}}},"account_id":{"type":"integer"},"actions":{"type":"string"},"files":{"type":"string"}}}}},"example":{"payload":{"id":1,"name":"Sample Name","visibility":"personal","visibility_config":"sample visibility config","created_by":{"id":1,"account_id":1,"account_user_id":1,"availability_status":"online","auto_offline":true,"confirmed":true,"email":"agent@example.com","provider":"email","available_name":"sample available name","custom_attributes":{},"name":"Sample Name","role":"agent","outbound_agent_name_header_policy":"sample outbound agent name header policy","thumbnail":"sample thumbnail","custom_role_id":1,"access_role_id":1},"updated_by":{"id":1,"account_id":1,"account_user_id":1,"availability_status":"online","auto_offline":true,"confirmed":true,"email":"agent@example.com","provider":"email","available_name":"sample available name","custom_attributes":{},"name":"Sample Name","role":"agent","outbound_agent_name_header_policy":"sample outbound agent name header policy","thumbnail":"sample thumbnail","custom_role_id":1,"access_role_id":1},"account_id":1,"actions":"sample actions","files":"sample files"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"422":{"description":"Attachment preparation or macro attribute validation failed. Returns the `error` shape, or the global RecordInvalid shape when the record stops being valid between the check and the write.","content":{"application/json":{"schema":{"oneOf":[{"type":"object","description":"Attachment or macro attribute validation, as rendered by the controller.","required":["error"],"properties":{"error":{"oneOf":[{"type":"string","description":"The localized attachment validation message.","example":"Invalid attachment"},{"type":"object","description":"Validation messages grouped by attribute name, or base for the whole macro.","additionalProperties":{"type":"array","items":{"type":"string"}},"example":{"base":["Remove these actions or ask an administrator to publish the macro (create_charge)."]}}]}}},{"type":"object","description":"The global ActiveRecord::RecordInvalid shape. On create this is a race only: the record passed validation and then stopped being valid before the write, for example when the editor's administrator role is revoked in between.","required":["message","attributes"],"properties":{"message":{"type":"string","description":"Every validation message joined by ', '.","example":"Remove these actions or ask an administrator to publish the macro (create_charge)."},"attributes":{"type":"array","description":"The attribute names that carried a validation error, with base for the whole macro.","items":{"type":"string"},"example":["base"]}}}]},"example":{"error":"Invalid attachment"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"visibility":{"type":"string","enum":["personal","global","selective"]},"visibility_config":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Free-form object."}},"actions":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Free-form object."}}}},"example":{"name":"Sample Name","visibility":"personal","visibility_config":[{}],"actions":[{}]}}}}}},"/api/v1/accounts/{account_id}/macros/{id}":{"get":{"tags":["Macros"],"operationId":"auto_get_api_v1_accounts_account_id_macros_id","summary":"Get macros","description":"Returns the macro identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"visibility":{"type":"string","enum":["personal","global","selective"]},"visibility_config":{"type":"string"},"created_by":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":["integer","null"]},"account_user_id":{"type":["integer","null"]},"availability_status":{"type":"string","enum":["online","offline","busy"],"description":"Realtime availability. Contacts report online/offline (presence-based); agents/users additionally report busy (their configured availability)."},"auto_offline":{"type":"boolean"},"confirmed":{"type":"boolean"},"email":{"type":"string","format":"email"},"provider":{"type":"string","enum":["email","google_oauth2","saml"],"description":"Authentication provider the user signed up through."},"available_name":{"type":"string"},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"name":{"type":"string"},"role":{"type":"string","enum":["agent","administrator"]},"outbound_agent_name_header_policy":{"type":["string","null"]},"thumbnail":{"type":"string"},"custom_role_id":{"type":["integer","null"]},"access_role_id":{"type":["integer","null"]}}},"updated_by":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":["integer","null"]},"account_user_id":{"type":["integer","null"]},"availability_status":{"type":"string","enum":["online","offline","busy"],"description":"Realtime availability. Contacts report online/offline (presence-based); agents/users additionally report busy (their configured availability)."},"auto_offline":{"type":"boolean"},"confirmed":{"type":"boolean"},"email":{"type":"string","format":"email"},"provider":{"type":"string","enum":["email","google_oauth2","saml"],"description":"Authentication provider the user signed up through."},"available_name":{"type":"string"},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"name":{"type":"string"},"role":{"type":"string","enum":["agent","administrator"]},"outbound_agent_name_header_policy":{"type":["string","null"]},"thumbnail":{"type":"string"},"custom_role_id":{"type":["integer","null"]},"access_role_id":{"type":["integer","null"]}}},"account_id":{"type":"integer"},"actions":{"type":"string"},"files":{"type":"string"}}}}},"example":{"payload":{"id":1,"name":"Sample Name","visibility":"personal","visibility_config":"sample visibility config","created_by":{"id":1,"account_id":1,"account_user_id":1,"availability_status":"online","auto_offline":true,"confirmed":true,"email":"agent@example.com","provider":"email","available_name":"sample available name","custom_attributes":{},"name":"Sample Name","role":"agent","outbound_agent_name_header_policy":"sample outbound agent name header policy","thumbnail":"sample thumbnail","custom_role_id":1,"access_role_id":1},"updated_by":{"id":1,"account_id":1,"account_user_id":1,"availability_status":"online","auto_offline":true,"confirmed":true,"email":"agent@example.com","provider":"email","available_name":"sample available name","custom_attributes":{},"name":"Sample Name","role":"agent","outbound_agent_name_header_policy":"sample outbound agent name header policy","thumbnail":"sample thumbnail","custom_role_id":1,"access_role_id":1},"account_id":1,"actions":"sample actions","files":"sample files"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]},"patch":{"tags":["Macros"],"operationId":"auto_patch_api_v1_accounts_account_id_macros_id","summary":"Update macros","description":"Updates the macro identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"visibility":{"type":"string","enum":["personal","global","selective"]},"visibility_config":{"type":"string"},"created_by":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":["integer","null"]},"account_user_id":{"type":["integer","null"]},"availability_status":{"type":"string","enum":["online","offline","busy"],"description":"Realtime availability. Contacts report online/offline (presence-based); agents/users additionally report busy (their configured availability)."},"auto_offline":{"type":"boolean"},"confirmed":{"type":"boolean"},"email":{"type":"string","format":"email"},"provider":{"type":"string","enum":["email","google_oauth2","saml"],"description":"Authentication provider the user signed up through."},"available_name":{"type":"string"},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"name":{"type":"string"},"role":{"type":"string","enum":["agent","administrator"]},"outbound_agent_name_header_policy":{"type":["string","null"]},"thumbnail":{"type":"string"},"custom_role_id":{"type":["integer","null"]},"access_role_id":{"type":["integer","null"]}}},"updated_by":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":["integer","null"]},"account_user_id":{"type":["integer","null"]},"availability_status":{"type":"string","enum":["online","offline","busy"],"description":"Realtime availability. Contacts report online/offline (presence-based); agents/users additionally report busy (their configured availability)."},"auto_offline":{"type":"boolean"},"confirmed":{"type":"boolean"},"email":{"type":"string","format":"email"},"provider":{"type":"string","enum":["email","google_oauth2","saml"],"description":"Authentication provider the user signed up through."},"available_name":{"type":"string"},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"name":{"type":"string"},"role":{"type":"string","enum":["agent","administrator"]},"outbound_agent_name_header_policy":{"type":["string","null"]},"thumbnail":{"type":"string"},"custom_role_id":{"type":["integer","null"]},"access_role_id":{"type":["integer","null"]}}},"account_id":{"type":"integer"},"actions":{"type":"string"},"files":{"type":"string"}}}}},"example":{"payload":{"id":1,"name":"Sample Name","visibility":"personal","visibility_config":"sample visibility config","created_by":{"id":1,"account_id":1,"account_user_id":1,"availability_status":"online","auto_offline":true,"confirmed":true,"email":"agent@example.com","provider":"email","available_name":"sample available name","custom_attributes":{},"name":"Sample Name","role":"agent","outbound_agent_name_header_policy":"sample outbound agent name header policy","thumbnail":"sample thumbnail","custom_role_id":1,"access_role_id":1},"updated_by":{"id":1,"account_id":1,"account_user_id":1,"availability_status":"online","auto_offline":true,"confirmed":true,"email":"agent@example.com","provider":"email","available_name":"sample available name","custom_attributes":{},"name":"Sample Name","role":"agent","outbound_agent_name_header_policy":"sample outbound agent name header policy","thumbnail":"sample thumbnail","custom_role_id":1,"access_role_id":1},"account_id":1,"actions":"sample actions","files":"sample files"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"422":{"description":"Attachment preparation or macro attribute validation failed.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"oneOf":[{"type":"string","description":"The localized attachment validation message.","example":"Invalid attachment"},{"type":"object","description":"Validation messages grouped by attribute name, or base for the whole macro.","additionalProperties":{"type":"array","items":{"type":"string"}},"example":{"base":["Remove these actions or ask an administrator to publish the macro (create_charge)."]}}]}}},"example":{"error":"Invalid attachment"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"visibility":{"type":"string","enum":["personal","global","selective"]},"visibility_config":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Free-form object."}},"actions":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Free-form object."}}}},"example":{"name":"Sample Name","visibility":"personal","visibility_config":[{}],"actions":[{}]}}}}},"put":{"tags":["Macros"],"operationId":"auto_put_api_v1_accounts_account_id_macros_id","summary":"Update macros","description":"Updates the macro identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"visibility":{"type":"string","enum":["personal","global","selective"]},"visibility_config":{"type":"string"},"created_by":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":["integer","null"]},"account_user_id":{"type":["integer","null"]},"availability_status":{"type":"string","enum":["online","offline","busy"],"description":"Realtime availability. Contacts report online/offline (presence-based); agents/users additionally report busy (their configured availability)."},"auto_offline":{"type":"boolean"},"confirmed":{"type":"boolean"},"email":{"type":"string","format":"email"},"provider":{"type":"string","enum":["email","google_oauth2","saml"],"description":"Authentication provider the user signed up through."},"available_name":{"type":"string"},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"name":{"type":"string"},"role":{"type":"string","enum":["agent","administrator"]},"outbound_agent_name_header_policy":{"type":["string","null"]},"thumbnail":{"type":"string"},"custom_role_id":{"type":["integer","null"]},"access_role_id":{"type":["integer","null"]}}},"updated_by":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":["integer","null"]},"account_user_id":{"type":["integer","null"]},"availability_status":{"type":"string","enum":["online","offline","busy"],"description":"Realtime availability. Contacts report online/offline (presence-based); agents/users additionally report busy (their configured availability)."},"auto_offline":{"type":"boolean"},"confirmed":{"type":"boolean"},"email":{"type":"string","format":"email"},"provider":{"type":"string","enum":["email","google_oauth2","saml"],"description":"Authentication provider the user signed up through."},"available_name":{"type":"string"},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"name":{"type":"string"},"role":{"type":"string","enum":["agent","administrator"]},"outbound_agent_name_header_policy":{"type":["string","null"]},"thumbnail":{"type":"string"},"custom_role_id":{"type":["integer","null"]},"access_role_id":{"type":["integer","null"]}}},"account_id":{"type":"integer"},"actions":{"type":"string"},"files":{"type":"string"}}}}},"example":{"payload":{"id":1,"name":"Sample Name","visibility":"personal","visibility_config":"sample visibility config","created_by":{"id":1,"account_id":1,"account_user_id":1,"availability_status":"online","auto_offline":true,"confirmed":true,"email":"agent@example.com","provider":"email","available_name":"sample available name","custom_attributes":{},"name":"Sample Name","role":"agent","outbound_agent_name_header_policy":"sample outbound agent name header policy","thumbnail":"sample thumbnail","custom_role_id":1,"access_role_id":1},"updated_by":{"id":1,"account_id":1,"account_user_id":1,"availability_status":"online","auto_offline":true,"confirmed":true,"email":"agent@example.com","provider":"email","available_name":"sample available name","custom_attributes":{},"name":"Sample Name","role":"agent","outbound_agent_name_header_policy":"sample outbound agent name header policy","thumbnail":"sample thumbnail","custom_role_id":1,"access_role_id":1},"account_id":1,"actions":"sample actions","files":"sample files"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"422":{"description":"Attachment preparation or macro attribute validation failed.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"oneOf":[{"type":"string","description":"The localized attachment validation message.","example":"Invalid attachment"},{"type":"object","description":"Validation messages grouped by attribute name, or base for the whole macro.","additionalProperties":{"type":"array","items":{"type":"string"}},"example":{"base":["Remove these actions or ask an administrator to publish the macro (create_charge)."]}}]}}},"example":{"error":"Invalid attachment"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"visibility":{"type":"string","enum":["personal","global","selective"]},"visibility_config":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Free-form object."}},"actions":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Free-form object."}}}},"example":{"name":"Sample Name","visibility":"personal","visibility_config":[{}],"actions":[{}]}}}}},"delete":{"tags":["Macros"],"operationId":"auto_delete_api_v1_accounts_account_id_macros_id","summary":"Delete macros","description":"Deletes the macro identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Success (no content)"},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/sla_policies":{"get":{"tags":["SLA Policies"],"operationId":"auto_get_api_v1_accounts_account_id_sla_policies","summary":"List sla policies","description":"Returns the list of sla policies visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"first_response_time_threshold":{"type":"string"},"next_response_time_threshold":{"type":"string"},"resolution_time_threshold":{"type":"string"},"only_during_business_hours":{"type":"string"}}}}}},"example":{"payload":[{"id":1,"name":"Sample Name","description":"A short description.","first_response_time_threshold":"sample first response time threshold","next_response_time_threshold":"sample next response time threshold","resolution_time_threshold":"sample resolution time threshold","only_during_business_hours":"sample only during business hours"}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."}]},"post":{"tags":["SLA Policies"],"operationId":"auto_post_api_v1_accounts_account_id_sla_policies","summary":"Create sla policies","description":"Creates a new sla policy from the request payload. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"first_response_time_threshold":{"type":"string"},"next_response_time_threshold":{"type":"string"},"resolution_time_threshold":{"type":"string"},"only_during_business_hours":{"type":"string"}}}}},"example":{"payload":{"id":1,"name":"Sample Name","description":"A short description.","first_response_time_threshold":"sample first response time threshold","next_response_time_threshold":"sample next response time threshold","resolution_time_threshold":"sample resolution time threshold","only_during_business_hours":"sample only during business hours"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"sla_policy":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"first_response_time_threshold":{"type":"string"},"next_response_time_threshold":{"type":"string"},"resolution_time_threshold":{"type":"string"},"only_during_business_hours":{"type":"string"}},"required":["name"]}},"required":["sla_policy"]},"example":{"sla_policy":{"name":"Sample Name","description":"A short description.","first_response_time_threshold":"sample first response time threshold","next_response_time_threshold":"sample next response time threshold","resolution_time_threshold":"sample resolution time threshold","only_during_business_hours":"sample only during business hours"}}}}}}},"/api/v1/accounts/{account_id}/sla_policies/{id}":{"get":{"tags":["SLA Policies"],"operationId":"auto_get_api_v1_accounts_account_id_sla_policies_id","summary":"Get sla policies","description":"Returns the sla policy identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"first_response_time_threshold":{"type":"string"},"next_response_time_threshold":{"type":"string"},"resolution_time_threshold":{"type":"string"},"only_during_business_hours":{"type":"string"}}}}},"example":{"payload":{"id":1,"name":"Sample Name","description":"A short description.","first_response_time_threshold":"sample first response time threshold","next_response_time_threshold":"sample next response time threshold","resolution_time_threshold":"sample resolution time threshold","only_during_business_hours":"sample only during business hours"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]},"patch":{"tags":["SLA Policies"],"operationId":"auto_patch_api_v1_accounts_account_id_sla_policies_id","summary":"Update sla policies","description":"Updates the sla policy identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"first_response_time_threshold":{"type":"string"},"next_response_time_threshold":{"type":"string"},"resolution_time_threshold":{"type":"string"},"only_during_business_hours":{"type":"string"}}}}},"example":{"payload":{"id":1,"name":"Sample Name","description":"A short description.","first_response_time_threshold":"sample first response time threshold","next_response_time_threshold":"sample next response time threshold","resolution_time_threshold":"sample resolution time threshold","only_during_business_hours":"sample only during business hours"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"sla_policy":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"first_response_time_threshold":{"type":"string"},"next_response_time_threshold":{"type":"string"},"resolution_time_threshold":{"type":"string"},"only_during_business_hours":{"type":"string"}}}},"required":["sla_policy"]},"example":{"sla_policy":{"name":"Sample Name","description":"A short description.","first_response_time_threshold":"sample first response time threshold","next_response_time_threshold":"sample next response time threshold","resolution_time_threshold":"sample resolution time threshold","only_during_business_hours":"sample only during business hours"}}}}}},"put":{"tags":["SLA Policies"],"operationId":"auto_put_api_v1_accounts_account_id_sla_policies_id","summary":"Update sla policies","description":"Updates the sla policy identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"first_response_time_threshold":{"type":"string"},"next_response_time_threshold":{"type":"string"},"resolution_time_threshold":{"type":"string"},"only_during_business_hours":{"type":"string"}}}}},"example":{"payload":{"id":1,"name":"Sample Name","description":"A short description.","first_response_time_threshold":"sample first response time threshold","next_response_time_threshold":"sample next response time threshold","resolution_time_threshold":"sample resolution time threshold","only_during_business_hours":"sample only during business hours"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"sla_policy":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"first_response_time_threshold":{"type":"string"},"next_response_time_threshold":{"type":"string"},"resolution_time_threshold":{"type":"string"},"only_during_business_hours":{"type":"string"}}}},"required":["sla_policy"]},"example":{"sla_policy":{"name":"Sample Name","description":"A short description.","first_response_time_threshold":"sample first response time threshold","next_response_time_threshold":"sample next response time threshold","resolution_time_threshold":"sample resolution time threshold","only_during_business_hours":"sample only during business hours"}}}}}},"delete":{"tags":["SLA Policies"],"operationId":"auto_delete_api_v1_accounts_account_id_sla_policies_id","summary":"Delete sla policies","description":"Deletes the sla policy identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Success (no content)"},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/custom_roles":{"get":{"tags":["Custom Roles"],"operationId":"auto_get_api_v1_accounts_account_id_custom_roles","summary":"List custom roles","description":"Returns the list of custom roles visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"permissions":{"type":"string","enum":["","conversation_manage","conversation_unassigned_manage","conversation_participating_manage","contact_manage","report_manage","knowledge_base_manage"]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}},"example":[{"id":1,"name":"Sample Name","description":"A short description.","permissions":"","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}]}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."}]},"post":{"tags":["Custom Roles"],"operationId":"auto_post_api_v1_accounts_account_id_custom_roles","summary":"Create custom roles","description":"Creates a new custom role from the request payload. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"permissions":{"type":"string","enum":["","conversation_manage","conversation_unassigned_manage","conversation_participating_manage","contact_manage","report_manage","knowledge_base_manage"]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"example":{"id":1,"name":"Sample Name","description":"A short description.","permissions":"","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"custom_role":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"permissions":{"type":"array","items":{"type":"string"}}},"required":["name"]}},"required":["custom_role"]},"example":{"custom_role":{"name":"Sample Name","description":"A short description.","permissions":["sample permission"]}}}}}}},"/api/v1/accounts/{account_id}/custom_roles/{id}":{"get":{"tags":["Custom Roles"],"operationId":"auto_get_api_v1_accounts_account_id_custom_roles_id","summary":"Get custom roles","description":"Returns the custom role identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"permissions":{"type":"string","enum":["","conversation_manage","conversation_unassigned_manage","conversation_participating_manage","contact_manage","report_manage","knowledge_base_manage"]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"example":{"id":1,"name":"Sample Name","description":"A short description.","permissions":"","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]},"patch":{"tags":["Custom Roles"],"operationId":"auto_patch_api_v1_accounts_account_id_custom_roles_id","summary":"Update custom roles","description":"Updates the custom role identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"permissions":{"type":"string","enum":["","conversation_manage","conversation_unassigned_manage","conversation_participating_manage","contact_manage","report_manage","knowledge_base_manage"]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"example":{"id":1,"name":"Sample Name","description":"A short description.","permissions":"","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"custom_role":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"permissions":{"type":"array","items":{"type":"string"}}}}},"required":["custom_role"]},"example":{"custom_role":{"name":"Sample Name","description":"A short description.","permissions":["sample permission"]}}}}}},"put":{"tags":["Custom Roles"],"operationId":"auto_put_api_v1_accounts_account_id_custom_roles_id","summary":"Update custom roles","description":"Updates the custom role identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"permissions":{"type":"string","enum":["","conversation_manage","conversation_unassigned_manage","conversation_participating_manage","contact_manage","report_manage","knowledge_base_manage"]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"example":{"id":1,"name":"Sample Name","description":"A short description.","permissions":"","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"custom_role":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"permissions":{"type":"array","items":{"type":"string"}}}}},"required":["custom_role"]},"example":{"custom_role":{"name":"Sample Name","description":"A short description.","permissions":["sample permission"]}}}}}},"delete":{"tags":["Custom Roles"],"operationId":"auto_delete_api_v1_accounts_account_id_custom_roles_id","summary":"Delete custom roles","description":"Deletes the custom role identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Success (no content)"},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/access_roles/templates":{"get":{"tags":["Access Roles"],"operationId":"auto_get_api_v1_accounts_account_id_access_roles_templates","summary":"Templates access roles","description":"Performs the templates operation on the targeted access role resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"permissions":{"type":"string"},"field_permissions":{"type":"string"},"source":{"type":"string"},"role_template_id":{"type":"integer"}}}},"example":[{"key":"sample key","name":"Sample Name","description":"A short description.","permissions":"sample permissions","field_permissions":"sample field permissions","source":"sample source","role_template_id":1}]}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/access_roles/apply_template":{"post":{"tags":["Access Roles"],"operationId":"auto_post_api_v1_accounts_account_id_access_roles_apply_template","summary":"Apply template access roles","description":"Performs the apply template operation on the targeted access role resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"permissions":{"type":"string","enum":["","conversation_manage","conversation_unassigned_manage","conversation_participating_manage","contact_manage","report_manage","knowledge_base_manage","contact_export","contact_delete","report_view","report_export","agent_manage","team_manage","inbox_manage","canned_response_manage","label_manage","custom_attribute_manage","automation_manage","macro_manage","campaign_manage","integration_manage","agent_bot_manage","sla_manage","account_settings_manage","audit_log_view","billing_manage","data_export","data_erase","data_governance_manage","crm_manage","payments_manage","whatsapp_hub_manage","catalog_manage","follow_up_manage","calendar_manage","routing_manage","distribution_manage","growth_social_manage","ads_manage","sales_manage","contracts_manage","contracts_admin","media_library_manage","tasks_manage","internal_chat_manage","flow_builder_manage","account_brain_manage","engagement_manage","lead_score_view","wfm_manage","wfm_view","social_collaboration_manage","organizations_manage","commerce_manage","message_scheduling_manage","maestro_pause","maestro_resume","maestro_assume","maestro_handoff","maestro_conversation_status","maestro_priority","maestro_labels","maestro_attributes","maestro_assign","maestro_macro","maestro_agent","maestro_autonomy","maestro_context_reset","maestro_replay","maestro_suggest","maestro_summarize","maestro_ask","maestro_execute","maestro_pending_view","maestro_pending_approve","maestro_pending_reject","maestro_generate","maestro_send_prepared"]},"scope_type":{"type":"string","enum":["account","teams","inboxes"]},"scoped_team_ids":{"type":"array","items":{"type":"integer"}},"scoped_inbox_ids":{"type":"array","items":{"type":"integer"}},"physical_scoped_inbox_ids":{"type":"array","items":{"type":"integer"}},"field_permissions":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"example":{"id":1,"name":"Sample Name","description":"A short description.","permissions":"","scope_type":"account","scoped_team_ids":[1],"scoped_inbox_ids":[1],"physical_scoped_inbox_ids":[1],"field_permissions":"sample field permissions","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"role_template_id":{"type":"integer"},"key":{"type":"string"}}},"example":{"role_template_id":1,"key":"sample key"}}}}}},"/api/v1/accounts/{account_id}/access_roles":{"get":{"tags":["Access Roles"],"operationId":"auto_get_api_v1_accounts_account_id_access_roles","summary":"List access roles","description":"Returns the list of access roles visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"permissions":{"type":"string","enum":["","conversation_manage","conversation_unassigned_manage","conversation_participating_manage","contact_manage","report_manage","knowledge_base_manage","contact_export","contact_delete","report_view","report_export","agent_manage","team_manage","inbox_manage","canned_response_manage","label_manage","custom_attribute_manage","automation_manage","macro_manage","campaign_manage","integration_manage","agent_bot_manage","sla_manage","account_settings_manage","audit_log_view","billing_manage","data_export","data_erase","data_governance_manage","crm_manage","payments_manage","whatsapp_hub_manage","catalog_manage","follow_up_manage","calendar_manage","routing_manage","distribution_manage","growth_social_manage","ads_manage","sales_manage","contracts_manage","contracts_admin","media_library_manage","tasks_manage","internal_chat_manage","flow_builder_manage","account_brain_manage","engagement_manage","lead_score_view","wfm_manage","wfm_view","social_collaboration_manage","organizations_manage","commerce_manage","message_scheduling_manage","maestro_pause","maestro_resume","maestro_assume","maestro_handoff","maestro_conversation_status","maestro_priority","maestro_labels","maestro_attributes","maestro_assign","maestro_macro","maestro_agent","maestro_autonomy","maestro_context_reset","maestro_replay","maestro_suggest","maestro_summarize","maestro_ask","maestro_execute","maestro_pending_view","maestro_pending_approve","maestro_pending_reject","maestro_generate","maestro_send_prepared"]},"scope_type":{"type":"string","enum":["account","teams","inboxes"]},"scoped_team_ids":{"type":"array","items":{"type":"integer"}},"scoped_inbox_ids":{"type":"array","items":{"type":"integer"}},"physical_scoped_inbox_ids":{"type":"array","items":{"type":"integer"}},"field_permissions":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}},"example":[{"id":1,"name":"Sample Name","description":"A short description.","permissions":"","scope_type":"account","scoped_team_ids":[1],"scoped_inbox_ids":[1],"physical_scoped_inbox_ids":[1],"field_permissions":"sample field permissions","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}]}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."}]},"post":{"tags":["Access Roles"],"operationId":"auto_post_api_v1_accounts_account_id_access_roles","summary":"Create access roles","description":"Creates a new access role from the request payload. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"permissions":{"type":"string","enum":["","conversation_manage","conversation_unassigned_manage","conversation_participating_manage","contact_manage","report_manage","knowledge_base_manage","contact_export","contact_delete","report_view","report_export","agent_manage","team_manage","inbox_manage","canned_response_manage","label_manage","custom_attribute_manage","automation_manage","macro_manage","campaign_manage","integration_manage","agent_bot_manage","sla_manage","account_settings_manage","audit_log_view","billing_manage","data_export","data_erase","data_governance_manage","crm_manage","payments_manage","whatsapp_hub_manage","catalog_manage","follow_up_manage","calendar_manage","routing_manage","distribution_manage","growth_social_manage","ads_manage","sales_manage","contracts_manage","contracts_admin","media_library_manage","tasks_manage","internal_chat_manage","flow_builder_manage","account_brain_manage","engagement_manage","lead_score_view","wfm_manage","wfm_view","social_collaboration_manage","organizations_manage","commerce_manage","message_scheduling_manage","maestro_pause","maestro_resume","maestro_assume","maestro_handoff","maestro_conversation_status","maestro_priority","maestro_labels","maestro_attributes","maestro_assign","maestro_macro","maestro_agent","maestro_autonomy","maestro_context_reset","maestro_replay","maestro_suggest","maestro_summarize","maestro_ask","maestro_execute","maestro_pending_view","maestro_pending_approve","maestro_pending_reject","maestro_generate","maestro_send_prepared"]},"scope_type":{"type":"string","enum":["account","teams","inboxes"]},"scoped_team_ids":{"type":"array","items":{"type":"integer"}},"scoped_inbox_ids":{"type":"array","items":{"type":"integer"}},"physical_scoped_inbox_ids":{"type":"array","items":{"type":"integer"}},"field_permissions":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"example":{"id":1,"name":"Sample Name","description":"A short description.","permissions":"","scope_type":"account","scoped_team_ids":[1],"scoped_inbox_ids":[1],"physical_scoped_inbox_ids":[1],"field_permissions":"sample field permissions","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"access_role":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"scope_type":{"type":"string","enum":["account","teams","inboxes"]},"permissions":{"type":"array","items":{"type":"string"}},"scoped_team_ids":{"type":"array","items":{"type":"integer"}},"scoped_inbox_ids":{"type":"array","items":{"type":"integer"}},"field_permissions":{"type":"object","additionalProperties":true,"description":"Free-form object."}},"required":["name"]}},"required":["access_role"]},"example":{"access_role":{"name":"Sample Name","description":"A short description.","scope_type":"account","permissions":["sample permission"],"scoped_team_ids":[1],"scoped_inbox_ids":[1],"field_permissions":{}}}}}}}},"/api/v1/accounts/{account_id}/access_roles/{id}":{"get":{"tags":["Access Roles"],"operationId":"auto_get_api_v1_accounts_account_id_access_roles_id","summary":"Get access roles","description":"Returns the access role identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"permissions":{"type":"string","enum":["","conversation_manage","conversation_unassigned_manage","conversation_participating_manage","contact_manage","report_manage","knowledge_base_manage","contact_export","contact_delete","report_view","report_export","agent_manage","team_manage","inbox_manage","canned_response_manage","label_manage","custom_attribute_manage","automation_manage","macro_manage","campaign_manage","integration_manage","agent_bot_manage","sla_manage","account_settings_manage","audit_log_view","billing_manage","data_export","data_erase","data_governance_manage","crm_manage","payments_manage","whatsapp_hub_manage","catalog_manage","follow_up_manage","calendar_manage","routing_manage","distribution_manage","growth_social_manage","ads_manage","sales_manage","contracts_manage","contracts_admin","media_library_manage","tasks_manage","internal_chat_manage","flow_builder_manage","account_brain_manage","engagement_manage","lead_score_view","wfm_manage","wfm_view","social_collaboration_manage","organizations_manage","commerce_manage","message_scheduling_manage","maestro_pause","maestro_resume","maestro_assume","maestro_handoff","maestro_conversation_status","maestro_priority","maestro_labels","maestro_attributes","maestro_assign","maestro_macro","maestro_agent","maestro_autonomy","maestro_context_reset","maestro_replay","maestro_suggest","maestro_summarize","maestro_ask","maestro_execute","maestro_pending_view","maestro_pending_approve","maestro_pending_reject","maestro_generate","maestro_send_prepared"]},"scope_type":{"type":"string","enum":["account","teams","inboxes"]},"scoped_team_ids":{"type":"array","items":{"type":"integer"}},"scoped_inbox_ids":{"type":"array","items":{"type":"integer"}},"physical_scoped_inbox_ids":{"type":"array","items":{"type":"integer"}},"field_permissions":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"example":{"id":1,"name":"Sample Name","description":"A short description.","permissions":"","scope_type":"account","scoped_team_ids":[1],"scoped_inbox_ids":[1],"physical_scoped_inbox_ids":[1],"field_permissions":"sample field permissions","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]},"patch":{"tags":["Access Roles"],"operationId":"auto_patch_api_v1_accounts_account_id_access_roles_id","summary":"Update access roles","description":"Updates the access role identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"permissions":{"type":"string","enum":["","conversation_manage","conversation_unassigned_manage","conversation_participating_manage","contact_manage","report_manage","knowledge_base_manage","contact_export","contact_delete","report_view","report_export","agent_manage","team_manage","inbox_manage","canned_response_manage","label_manage","custom_attribute_manage","automation_manage","macro_manage","campaign_manage","integration_manage","agent_bot_manage","sla_manage","account_settings_manage","audit_log_view","billing_manage","data_export","data_erase","data_governance_manage","crm_manage","payments_manage","whatsapp_hub_manage","catalog_manage","follow_up_manage","calendar_manage","routing_manage","distribution_manage","growth_social_manage","ads_manage","sales_manage","contracts_manage","contracts_admin","media_library_manage","tasks_manage","internal_chat_manage","flow_builder_manage","account_brain_manage","engagement_manage","lead_score_view","wfm_manage","wfm_view","social_collaboration_manage","organizations_manage","commerce_manage","message_scheduling_manage","maestro_pause","maestro_resume","maestro_assume","maestro_handoff","maestro_conversation_status","maestro_priority","maestro_labels","maestro_attributes","maestro_assign","maestro_macro","maestro_agent","maestro_autonomy","maestro_context_reset","maestro_replay","maestro_suggest","maestro_summarize","maestro_ask","maestro_execute","maestro_pending_view","maestro_pending_approve","maestro_pending_reject","maestro_generate","maestro_send_prepared"]},"scope_type":{"type":"string","enum":["account","teams","inboxes"]},"scoped_team_ids":{"type":"array","items":{"type":"integer"}},"scoped_inbox_ids":{"type":"array","items":{"type":"integer"}},"physical_scoped_inbox_ids":{"type":"array","items":{"type":"integer"}},"field_permissions":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"example":{"id":1,"name":"Sample Name","description":"A short description.","permissions":"","scope_type":"account","scoped_team_ids":[1],"scoped_inbox_ids":[1],"physical_scoped_inbox_ids":[1],"field_permissions":"sample field permissions","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"access_role":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"scope_type":{"type":"string","enum":["account","teams","inboxes"]},"permissions":{"type":"array","items":{"type":"string"}},"scoped_team_ids":{"type":"array","items":{"type":"integer"}},"scoped_inbox_ids":{"type":"array","items":{"type":"integer"}},"field_permissions":{"type":"object","additionalProperties":true,"description":"Free-form object."}}}},"required":["access_role"]},"example":{"access_role":{"name":"Sample Name","description":"A short description.","scope_type":"account","permissions":["sample permission"],"scoped_team_ids":[1],"scoped_inbox_ids":[1],"field_permissions":{}}}}}}},"put":{"tags":["Access Roles"],"operationId":"auto_put_api_v1_accounts_account_id_access_roles_id","summary":"Update access roles","description":"Updates the access role identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"permissions":{"type":"string","enum":["","conversation_manage","conversation_unassigned_manage","conversation_participating_manage","contact_manage","report_manage","knowledge_base_manage","contact_export","contact_delete","report_view","report_export","agent_manage","team_manage","inbox_manage","canned_response_manage","label_manage","custom_attribute_manage","automation_manage","macro_manage","campaign_manage","integration_manage","agent_bot_manage","sla_manage","account_settings_manage","audit_log_view","billing_manage","data_export","data_erase","data_governance_manage","crm_manage","payments_manage","whatsapp_hub_manage","catalog_manage","follow_up_manage","calendar_manage","routing_manage","distribution_manage","growth_social_manage","ads_manage","sales_manage","contracts_manage","contracts_admin","media_library_manage","tasks_manage","internal_chat_manage","flow_builder_manage","account_brain_manage","engagement_manage","lead_score_view","wfm_manage","wfm_view","social_collaboration_manage","organizations_manage","commerce_manage","message_scheduling_manage","maestro_pause","maestro_resume","maestro_assume","maestro_handoff","maestro_conversation_status","maestro_priority","maestro_labels","maestro_attributes","maestro_assign","maestro_macro","maestro_agent","maestro_autonomy","maestro_context_reset","maestro_replay","maestro_suggest","maestro_summarize","maestro_ask","maestro_execute","maestro_pending_view","maestro_pending_approve","maestro_pending_reject","maestro_generate","maestro_send_prepared"]},"scope_type":{"type":"string","enum":["account","teams","inboxes"]},"scoped_team_ids":{"type":"array","items":{"type":"integer"}},"scoped_inbox_ids":{"type":"array","items":{"type":"integer"}},"physical_scoped_inbox_ids":{"type":"array","items":{"type":"integer"}},"field_permissions":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"example":{"id":1,"name":"Sample Name","description":"A short description.","permissions":"","scope_type":"account","scoped_team_ids":[1],"scoped_inbox_ids":[1],"physical_scoped_inbox_ids":[1],"field_permissions":"sample field permissions","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"access_role":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"scope_type":{"type":"string","enum":["account","teams","inboxes"]},"permissions":{"type":"array","items":{"type":"string"}},"scoped_team_ids":{"type":"array","items":{"type":"integer"}},"scoped_inbox_ids":{"type":"array","items":{"type":"integer"}},"field_permissions":{"type":"object","additionalProperties":true,"description":"Free-form object."}}}},"required":["access_role"]},"example":{"access_role":{"name":"Sample Name","description":"A short description.","scope_type":"account","permissions":["sample permission"],"scoped_team_ids":[1],"scoped_inbox_ids":[1],"field_permissions":{}}}}}}},"delete":{"tags":["Access Roles"],"operationId":"auto_delete_api_v1_accounts_account_id_access_roles_id","summary":"Delete access roles","description":"Deletes the access role identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Success (no content)"},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/governance/settings/preview":{"post":{"tags":["Governance"],"operationId":"auto_post_api_v1_accounts_account_id_governance_settings_preview","summary":"Preview settings","description":"Performs the preview operation on the targeted setting resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The prompt rendered per channel, with a real contact's name and the tokens the matcher accepts. Nothing is persisted.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"locale":{"type":"string","description":"The locale the preview rendered in.","example":"pt_BR"},"sample_present":{"type":"boolean","description":"False when the account has no contact yet — the variables then render blank.","example":true},"variables":{"type":"object","description":"The five supported placeholders, resolved.","additionalProperties":{"type":"string"},"example":{"affirmative_token":"sim","contact_name":"Ana","dpo_email":"dpo@example.com","negative_token":"nao","privacy_policy_url":"https://example.com/privacidade"}},"rendered":{"type":"string","description":"The prompt with its placeholders resolved (before per-channel rendering).","example":"Olá Ana, responda sim para consentir."},"rendered_by_channel":{"type":"object","description":"One entry per channel type the ACCOUNT has an inbox of, rendered by Messages::MarkdownRendererService.","additionalProperties":{"type":"string"},"example":{"Channel::WebWidget":"Olá Ana, responda sim para consentir."}},"hsm":{"type":["object","null"],"description":"Always null — the consent prompt has no approved-template surface.","additionalProperties":true,"example":null},"buttons":{"type":"array","description":"Always empty — the consent prompt ships no native button; it is a question the contact answers by replying.","items":{"type":"object","additionalProperties":true,"description":"Never populated for this operation."},"example":[]},"defaults":{"type":"object","description":"The SHIPPED prompt behind each key named in `types` — what an empty box actually sends.","properties":{"bodies":{"type":"object","description":"key -\u003e the shipped prompt, in the previewed locale.","additionalProperties":{"type":"string"},"example":{"consent_prompt":"Antes de continuarmos, precisamos do seu consentimento para tratar seus dados. Responda \"sim\" para consentir ou \"nao\" para recusar."}},"labels":{"type":"object","description":"Always empty — the consent prompt exposes no auxiliary labels.","additionalProperties":{"type":"string"},"example":{}}}}}}}},"example":{"payload":{"locale":"pt_BR","sample_present":true,"variables":{"affirmative_token":"sim","contact_name":"Ana","dpo_email":"dpo@example.com","negative_token":"nao","privacy_policy_url":"https://example.com/privacidade"},"rendered":"Olá Ana, responda sim para consentir.","rendered_by_channel":{"Channel::WebWidget":"Olá Ana, responda sim para consentir."},"hsm":null,"buttons":[],"defaults":{"bodies":{"consent_prompt":"Antes de continuarmos, precisamos do seu consentimento para tratar seus dados. Responda \"sim\" para consentir ou \"nao\" para recusar."},"labels":{}}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"The unsaved prompt the operator is looking at — nothing is persisted, nothing is sent.","properties":{"body":{"type":"string","description":"The prompt exactly as authored. Only the five supported placeholders resolve (`contact_name`, `privacy_policy_url`, `dpo_email`, `affirmative_token`, `negative_token`); every other `{{ … }}` or `{% … %}` is STRIPPED, here and on the send.","example":"Olá {{ contact_name }}, responda {{ affirmative_token }} para consentir."},"locale":{"type":"string","description":"Locale to render in; omitted falls back to the contact -\u003e account cascade.","example":"pt_BR"},"type":{"type":"string","description":"The channel the prompt is being authored for (informational — the prompt has no per-type template).","example":"whatsapp"},"types":{"type":"array","description":"Keys whose SHIPPED prompt should come back in `defaults.bodies` (any key resolves to the same shipped prompt).","items":{"type":"string"},"example":["consent_prompt"]}}},"example":{"body":"Olá {{ contact_name }}, responda {{ affirmative_token }} para consentir.","locale":"pt_BR","type":"whatsapp","types":["consent_prompt"]}}}}}},"/api/v1/accounts/{account_id}/governance/settings/test_send":{"post":{"tags":["Governance"],"operationId":"auto_post_api_v1_accounts_account_id_governance_settings_test_send","summary":"Test send settings","description":"Performs the test send operation on the targeted setting resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The outcome of the send, which honours the WhatsApp 24h window exactly as the real prompt does.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"status":{"type":"string","enum":["sent","skipped","failed"],"description":"sent = a message was created; skipped = nothing was sent (see reason); failed = the send raised.","example":"sent"},"reason":{"type":["string","null"],"description":"Canonical skip/failure reason: `whatsapp_window_closed` or `empty_body`. Null when sent.","example":"whatsapp_window_closed"},"content":{"type":"string","description":"The rendered prompt that was sent (or would have been).","example":"Olá Ana, responda sim para consentir."},"message_id":{"type":["integer","null"],"description":"The created message id; null on skip/failure.","example":9001}}}}},"example":{"payload":{"status":"sent","reason":"whatsapp_window_closed","content":"Olá Ana, responda sim para consentir.","message_id":9001}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"422":{"description":"No conversation was given (`conversation_required`), so there is nothing to send into.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"conversation_required"}}},"example":{"error":"conversation_required"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["conversation_id"],"description":"Sends ONE real prompt into an EXISTING conversation. Never creates a conversation and never records consent — it is a wording check.","properties":{"conversation_id":{"type":"string","description":"Conversation display_id (an internal id is accepted as a fallback).","example":"42"},"body":{"type":"string","description":"The prompt exactly as authored.","example":"Olá {{ contact_name }}, responda {{ affirmative_token }} para consentir."},"locale":{"type":"string","example":"pt_BR"},"type":{"type":"string","description":"The channel the prompt is being authored for.","example":"whatsapp"}}},"example":{"conversation_id":"42","body":"Olá {{ contact_name }}, responda {{ affirmative_token }} para consentir.","locale":"pt_BR","type":"whatsapp"}}}}}},"/api/v1/accounts/{account_id}/governance/settings":{"get":{"tags":["Governance"],"operationId":"auto_get_api_v1_accounts_account_id_governance_settings","summary":"Get settings","description":"Returns the setting identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The resolved governance settings for administrators and governance managers. DSR/audit-only roles receive the same shape with empty sections so page bootstrap never exposes DPO, consent, or retention configuration.","content":{"application/json":{"schema":{"type":"object","properties":{"presentation_mode":{"type":"object","description":"Account-wide blur categories for Presentation Mode (the per-user on/off switch lives in ui_settings).","properties":{"enabled":{"type":"boolean","example":false},"blur_avatars":{"type":"boolean","example":true},"blur_contact_names":{"type":"boolean","example":true},"blur_phones_emails":{"type":"boolean","example":true},"blur_message_content":{"type":"boolean","example":false},"blur_media_previews":{"type":"boolean","example":false},"blur_deal_values":{"type":"boolean","example":false},"blur_agent_names":{"type":"boolean","example":false}}},"lgpd":{"type":"object","description":"LGPD structure — DPO data, consent default and central retention.","properties":{"dpo_name":{"type":"string","example":"Maria Andrade"},"dpo_email":{"type":"string","example":"dpo@example.com"},"consent_required":{"type":"boolean","description":"When enabled, the first inbound interaction without a recorded state receives a consent prompt before message events are dispatched. It does not block inbound processing or outbound replies.","example":false},"consent_prompt_text":{"type":"string","description":"Optional global prompt template. Blank values use the account-locale default. Only the documented consent placeholders are accepted; Liquid expressions are rejected.","example":"Please reply {{affirmative_token}} to consent or {{negative_token}} to decline."},"consent_prompt_texts":{"type":"object","description":"Optional prompt overrides keyed by normalized channel. Missing or blank values fall back to the global template. Only the documented consent placeholders are accepted.","additionalProperties":{"type":"string"},"example":{"whatsapp":"Reply SIM to consent or NAO to decline."}},"consent_affirmative_tokens":{"type":"array","description":"Accepted affirmative replies after case, accent and edge-punctuation normalization. Values must not overlap negative tokens.","items":{"type":"string"},"example":["yes","agreed"]},"consent_negative_tokens":{"type":"array","description":"Accepted negative replies after case, accent and edge-punctuation normalization. Values must not overlap affirmative tokens.","items":{"type":"string"},"example":["no","decline"]},"privacy_policy_url":{"type":"string","example":"https://example.com/privacy"},"retention_message_days":{"type":"integer","description":"0 disables it. Messages of RESOLVED conversations older than this are redacted daily.","example":0},"retention_conversation_days":{"type":"integer","description":"0 disables it. Old resolved conversations are deleted unless covered by a legal or contract hold.","example":0},"retention_commerce_days":{"type":"integer","description":"0 disables it. Buyer-identifying commerce payload is scrubbed while aggregate revenue remains.","example":0}}},"audit":{"type":"object","description":"Native audit-trail tunables.","properties":{"retention_days":{"type":"integer","example":365}}}}},"example":{"presentation_mode":{"enabled":false,"blur_avatars":true,"blur_contact_names":true,"blur_phones_emails":true,"blur_message_content":false,"blur_media_previews":false,"blur_deal_values":false,"blur_agent_names":false},"lgpd":{"dpo_name":"Maria Andrade","dpo_email":"dpo@example.com","consent_required":false,"consent_prompt_text":"Please reply {{affirmative_token}} to consent or {{negative_token}} to decline.","consent_prompt_texts":{"whatsapp":"Reply SIM to consent or NAO to decline."},"consent_affirmative_tokens":["yes","agreed"],"consent_negative_tokens":["no","decline"],"privacy_policy_url":"https://example.com/privacy","retention_message_days":0,"retention_conversation_days":0,"retention_commerce_days":0},"audit":{"retention_days":365}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]},"patch":{"tags":["Governance"],"operationId":"auto_patch_api_v1_accounts_account_id_governance_settings","summary":"Update settings","description":"Updates the setting identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The resolved governance settings after the merge.","content":{"application/json":{"schema":{"type":"object","properties":{"presentation_mode":{"type":"object","description":"Account-wide blur categories for Presentation Mode (the per-user on/off switch lives in ui_settings).","properties":{"enabled":{"type":"boolean","example":false},"blur_avatars":{"type":"boolean","example":true},"blur_contact_names":{"type":"boolean","example":true},"blur_phones_emails":{"type":"boolean","example":true},"blur_message_content":{"type":"boolean","example":false},"blur_media_previews":{"type":"boolean","example":false},"blur_deal_values":{"type":"boolean","example":false},"blur_agent_names":{"type":"boolean","example":false}}},"lgpd":{"type":"object","description":"LGPD structure — DPO data, consent default and central retention.","properties":{"dpo_name":{"type":"string","example":"Maria Andrade"},"dpo_email":{"type":"string","example":"dpo@example.com"},"consent_required":{"type":"boolean","description":"When enabled, the first inbound interaction without a recorded state receives a consent prompt before message events are dispatched. It does not block inbound processing or outbound replies.","example":false},"consent_prompt_text":{"type":"string","description":"Optional global prompt template. Blank values use the account-locale default.","example":"Please reply {{affirmative_token}} to consent or {{negative_token}} to decline."},"consent_prompt_texts":{"type":"object","description":"Optional prompt overrides keyed by normalized channel.","additionalProperties":{"type":"string"},"example":{"whatsapp":"Reply SIM to consent or NAO to decline."}},"consent_affirmative_tokens":{"type":"array","items":{"type":"string"},"example":["yes","agreed"]},"consent_negative_tokens":{"type":"array","items":{"type":"string"},"example":["no","decline"]},"privacy_policy_url":{"type":"string","example":"https://example.com/privacy"},"retention_message_days":{"type":"integer","description":"0 disables it. Messages of RESOLVED conversations older than this are redacted daily.","example":0},"retention_conversation_days":{"type":"integer","description":"0 disables it. Old resolved conversations are deleted unless covered by a legal or contract hold.","example":0},"retention_commerce_days":{"type":"integer","description":"0 disables it. Buyer-identifying commerce payload is scrubbed while aggregate revenue remains.","example":0}}},"audit":{"type":"object","description":"Native audit-trail tunables.","properties":{"retention_days":{"type":"integer","example":365}}}}},"example":{"presentation_mode":{"enabled":false,"blur_avatars":true,"blur_contact_names":true,"blur_phones_emails":true,"blur_message_content":false,"blur_media_previews":false,"blur_deal_values":false,"blur_agent_names":false},"lgpd":{"dpo_name":"Maria Andrade","dpo_email":"dpo@example.com","consent_required":false,"consent_prompt_text":"Please reply {{affirmative_token}} to consent or {{negative_token}} to decline.","consent_prompt_texts":{"whatsapp":"Reply SIM to consent or NAO to decline."},"consent_affirmative_tokens":["yes","agreed"],"consent_negative_tokens":["no","decline"],"privacy_policy_url":"https://example.com/privacy","retention_message_days":0,"retention_conversation_days":0,"retention_commerce_days":0},"audit":{"retention_days":365}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"422":{"description":"The configuration is invalid, including affirmative and negative consent token lists that overlap after normalization.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"Data Consent response tokens cannot be both affirmative and negative: si"},"attributes":{"type":"array","items":{"type":"string"},"example":["data"]}}},"example":{"message":"Data Consent response tokens cannot be both affirmative and negative: si","attributes":["data"]}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["settings"],"properties":{"clear":{"type":"array","description":"Dot-paths the operator RESTORED to the shipped default, e.g. `lgpd.consent_prompt_text.es`. A deep merge can only ADD or REPLACE a key, never remove one, so without these a restored wording would live on in jsonb forever. Only paths rooted at one of the three sections are honoured; the row itself is never destroyed.","items":{"type":"string"},"example":["lgpd.consent_prompt_text.es"]},"settings":{"type":"object","description":"Whitelisted slice(s) to deep-merge — any subset of the three sections.","properties":{"presentation_mode":{"type":"object","properties":{"enabled":{"type":"boolean","example":false},"blur_avatars":{"type":"boolean","example":true},"blur_contact_names":{"type":"boolean","example":true},"blur_phones_emails":{"type":"boolean","example":true},"blur_message_content":{"type":"boolean","example":false},"blur_media_previews":{"type":"boolean","example":false},"blur_deal_values":{"type":"boolean","example":false},"blur_agent_names":{"type":"boolean","example":false}}},"lgpd":{"type":"object","properties":{"dpo_name":{"type":"string","example":"Maria Andrade"},"dpo_email":{"type":"string","example":"dpo@example.com"},"consent_required":{"type":"boolean","description":"Requests consent on the first inbound interaction without a recorded state; it does not block inbound processing or outbound replies.","example":false},"consent_prompt_text":{"description":"DUAL-SHAPED. Either a plain string (one wording for every language — how every account was configured before the prompt became per-language, and still accepted verbatim) or a `{ locale =\u003e text }` map. On send it is resolved for the CONTACT's language, falling back to the same base language, then the account language, then the `default` slot. Only contact_name, privacy_policy_url, dpo_email, affirmative_token and negative_token are accepted, in EVERY language — an unsupported placeholder in any one of them rejects the whole save; arbitrary Liquid is rejected too.","oneOf":[{"type":"string","description":"Legacy single wording, applied to every language.","example":"Please reply {{affirmative_token}} to consent or {{negative_token}} to decline."},{"type":"object","description":"Per-language wording. `default` is where the first per-language edit lifts the legacy text.","additionalProperties":{"type":"string"},"example":{"pt_BR":"Responda {{affirmative_token}} para consentir.","en":"Please reply {{affirmative_token}} to consent."}}],"example":"Please reply {{affirmative_token}} to consent or {{negative_token}} to decline."},"consent_prompt_texts":{"type":"object","description":"Prompt overrides keyed by normalized channel, each one DUAL-SHAPED exactly like `consent_prompt_text` (a plain string or a `{ locale =\u003e text }` map) and winning over it for that channel. Same placeholder rules, enforced per language.","additionalProperties":true,"example":{"whatsapp":"Reply SIM to consent or NAO to decline.","email":{"pt_BR":"Responda SIM para consentir.","en":"Reply YES to consent."}}},"consent_affirmative_tokens":{"type":"array","description":"Values must not overlap normalized negative tokens; ambiguous configurations are rejected.","items":{"type":"string"},"example":["yes","agreed"]},"consent_negative_tokens":{"type":"array","description":"Values must not overlap normalized affirmative tokens; ambiguous configurations are rejected.","items":{"type":"string"},"example":["no","decline"]},"privacy_policy_url":{"type":"string","example":"https://example.com/privacy"},"retention_message_days":{"type":"integer","example":90},"retention_conversation_days":{"type":"integer","example":0},"retention_commerce_days":{"type":"integer","example":0}}},"audit":{"type":"object","properties":{"retention_days":{"type":"integer","example":365}}}}}}},"example":{"clear":["lgpd.consent_prompt_text.es"],"settings":{"presentation_mode":{"enabled":false,"blur_avatars":true,"blur_contact_names":true,"blur_phones_emails":true,"blur_message_content":false,"blur_media_previews":false,"blur_deal_values":false,"blur_agent_names":false},"lgpd":{"dpo_name":"Maria Andrade","dpo_email":"dpo@example.com","consent_required":false,"consent_prompt_text":"Please reply {{affirmative_token}} to consent or {{negative_token}} to decline.","consent_prompt_texts":{"whatsapp":"Reply SIM to consent or NAO to decline.","email":{"pt_BR":"Responda SIM para consentir.","en":"Reply YES to consent."}},"consent_affirmative_tokens":["yes","agreed"],"consent_negative_tokens":["no","decline"],"privacy_policy_url":"https://example.com/privacy","retention_message_days":90,"retention_conversation_days":0,"retention_commerce_days":0},"audit":{"retention_days":365}}}}}}},"put":{"tags":["Governance"],"operationId":"auto_put_api_v1_accounts_account_id_governance_settings","summary":"Update settings","description":"Updates the setting identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The resolved governance settings after the merge.","content":{"application/json":{"schema":{"type":"object","properties":{"presentation_mode":{"type":"object","description":"Account-wide blur categories for Presentation Mode (the per-user on/off switch lives in ui_settings).","properties":{"enabled":{"type":"boolean","example":false},"blur_avatars":{"type":"boolean","example":true},"blur_contact_names":{"type":"boolean","example":true},"blur_phones_emails":{"type":"boolean","example":true},"blur_message_content":{"type":"boolean","example":false},"blur_media_previews":{"type":"boolean","example":false},"blur_deal_values":{"type":"boolean","example":false},"blur_agent_names":{"type":"boolean","example":false}}},"lgpd":{"type":"object","description":"LGPD structure — DPO data, consent default and central retention.","properties":{"dpo_name":{"type":"string","example":"Maria Andrade"},"dpo_email":{"type":"string","example":"dpo@example.com"},"consent_required":{"type":"boolean","description":"When enabled, the first inbound interaction without a recorded state receives a consent prompt before message events are dispatched. It does not block inbound processing or outbound replies.","example":false},"consent_prompt_text":{"type":"string","description":"Optional global prompt template. Blank values use the account-locale default.","example":"Please reply {{affirmative_token}} to consent or {{negative_token}} to decline."},"consent_prompt_texts":{"type":"object","description":"Optional prompt overrides keyed by normalized channel.","additionalProperties":{"type":"string"},"example":{"whatsapp":"Reply SIM to consent or NAO to decline."}},"consent_affirmative_tokens":{"type":"array","items":{"type":"string"},"example":["yes","agreed"]},"consent_negative_tokens":{"type":"array","items":{"type":"string"},"example":["no","decline"]},"privacy_policy_url":{"type":"string","example":"https://example.com/privacy"},"retention_message_days":{"type":"integer","description":"0 disables it. Messages of RESOLVED conversations older than this are redacted daily.","example":0},"retention_conversation_days":{"type":"integer","description":"0 disables it. Old resolved conversations are deleted unless covered by a legal or contract hold.","example":0},"retention_commerce_days":{"type":"integer","description":"0 disables it. Buyer-identifying commerce payload is scrubbed while aggregate revenue remains.","example":0}}},"audit":{"type":"object","description":"Native audit-trail tunables.","properties":{"retention_days":{"type":"integer","example":365}}}}},"example":{"presentation_mode":{"enabled":false,"blur_avatars":true,"blur_contact_names":true,"blur_phones_emails":true,"blur_message_content":false,"blur_media_previews":false,"blur_deal_values":false,"blur_agent_names":false},"lgpd":{"dpo_name":"Maria Andrade","dpo_email":"dpo@example.com","consent_required":false,"consent_prompt_text":"Please reply {{affirmative_token}} to consent or {{negative_token}} to decline.","consent_prompt_texts":{"whatsapp":"Reply SIM to consent or NAO to decline."},"consent_affirmative_tokens":["yes","agreed"],"consent_negative_tokens":["no","decline"],"privacy_policy_url":"https://example.com/privacy","retention_message_days":0,"retention_conversation_days":0,"retention_commerce_days":0},"audit":{"retention_days":365}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"422":{"description":"The configuration is invalid, including affirmative and negative consent token lists that overlap after normalization.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"Data Consent response tokens cannot be both affirmative and negative: si"},"attributes":{"type":"array","items":{"type":"string"},"example":["data"]}}},"example":{"message":"Data Consent response tokens cannot be both affirmative and negative: si","attributes":["data"]}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["settings"],"properties":{"clear":{"type":"array","description":"Dot-paths the operator RESTORED to the shipped default, e.g. `lgpd.consent_prompt_text.es`. A deep merge can only ADD or REPLACE a key, never remove one, so without these a restored wording would live on in jsonb forever. Only paths rooted at one of the three sections are honoured; the row itself is never destroyed.","items":{"type":"string"},"example":["lgpd.consent_prompt_text.es"]},"settings":{"type":"object","description":"Whitelisted slice(s) to deep-merge — any subset of the three sections.","properties":{"presentation_mode":{"type":"object","properties":{"enabled":{"type":"boolean","example":false},"blur_avatars":{"type":"boolean","example":true},"blur_contact_names":{"type":"boolean","example":true},"blur_phones_emails":{"type":"boolean","example":true},"blur_message_content":{"type":"boolean","example":false},"blur_media_previews":{"type":"boolean","example":false},"blur_deal_values":{"type":"boolean","example":false},"blur_agent_names":{"type":"boolean","example":false}}},"lgpd":{"type":"object","properties":{"dpo_name":{"type":"string","example":"Maria Andrade"},"dpo_email":{"type":"string","example":"dpo@example.com"},"consent_required":{"type":"boolean","description":"Requests consent on the first inbound interaction without a recorded state; it does not block inbound processing or outbound replies.","example":false},"consent_prompt_text":{"description":"DUAL-SHAPED. Either a plain string (one wording for every language — how every account was configured before the prompt became per-language, and still accepted verbatim) or a `{ locale =\u003e text }` map. On send it is resolved for the CONTACT's language, falling back to the same base language, then the account language, then the `default` slot. Only contact_name, privacy_policy_url, dpo_email, affirmative_token and negative_token are accepted, in EVERY language — an unsupported placeholder in any one of them rejects the whole save; arbitrary Liquid is rejected too.","oneOf":[{"type":"string","description":"Legacy single wording, applied to every language.","example":"Please reply {{affirmative_token}} to consent or {{negative_token}} to decline."},{"type":"object","description":"Per-language wording. `default` is where the first per-language edit lifts the legacy text.","additionalProperties":{"type":"string"},"example":{"pt_BR":"Responda {{affirmative_token}} para consentir.","en":"Please reply {{affirmative_token}} to consent."}}],"example":"Please reply {{affirmative_token}} to consent or {{negative_token}} to decline."},"consent_prompt_texts":{"type":"object","description":"Prompt overrides keyed by normalized channel, each one DUAL-SHAPED exactly like `consent_prompt_text` (a plain string or a `{ locale =\u003e text }` map) and winning over it for that channel. Same placeholder rules, enforced per language.","additionalProperties":true,"example":{"whatsapp":"Reply SIM to consent or NAO to decline.","email":{"pt_BR":"Responda SIM para consentir.","en":"Reply YES to consent."}}},"consent_affirmative_tokens":{"type":"array","description":"Values must not overlap normalized negative tokens; ambiguous configurations are rejected.","items":{"type":"string"},"example":["yes","agreed"]},"consent_negative_tokens":{"type":"array","description":"Values must not overlap normalized affirmative tokens; ambiguous configurations are rejected.","items":{"type":"string"},"example":["no","decline"]},"privacy_policy_url":{"type":"string","example":"https://example.com/privacy"},"retention_message_days":{"type":"integer","example":90},"retention_conversation_days":{"type":"integer","example":0},"retention_commerce_days":{"type":"integer","example":0}}},"audit":{"type":"object","properties":{"retention_days":{"type":"integer","example":365}}}}}}},"example":{"clear":["lgpd.consent_prompt_text.es"],"settings":{"presentation_mode":{"enabled":false,"blur_avatars":true,"blur_contact_names":true,"blur_phones_emails":true,"blur_message_content":false,"blur_media_previews":false,"blur_deal_values":false,"blur_agent_names":false},"lgpd":{"dpo_name":"Maria Andrade","dpo_email":"dpo@example.com","consent_required":false,"consent_prompt_text":"Please reply {{affirmative_token}} to consent or {{negative_token}} to decline.","consent_prompt_texts":{"whatsapp":"Reply SIM to consent or NAO to decline.","email":{"pt_BR":"Responda SIM para consentir.","en":"Reply YES to consent."}},"consent_affirmative_tokens":["yes","agreed"],"consent_negative_tokens":["no","decline"],"privacy_policy_url":"https://example.com/privacy","retention_message_days":90,"retention_conversation_days":0,"retention_commerce_days":0},"audit":{"retention_days":365}}}}}}}},"/api/v1/accounts/{account_id}/governance/audit_events":{"get":{"tags":["Governance"],"operationId":"auto_get_api_v1_accounts_account_id_governance_audit_events","summary":"List audit events","description":"Returns the list of audit events visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Native audit events (newest first) with pagination meta.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","example":91},"action":{"type":"string","enum":["sign_in","settings_updated","privacy_mode_updated","access_role_created","access_role_updated","access_role_deleted","role_template_applied","routing_template_applied","agent_added","agent_removed","inbox_created","inbox_updated","contact_deleted","contacts_exported","consent_recorded","consent_prompted","consent_granted","consent_denied","dsr_export_requested","dsr_export_downloaded","dsr_erasure_requested","dsr_completed","dsr_failed","setup.blueprint_applied","setup.teardown","organization_created","organization_updated","organization_archived","organization_membership_created","organization_membership_updated","organization_membership_removed","relationship_preset_applied","relationship_deleted","catalog_sync_credential_rotated","domain_event_recorded"],"example":"sign_in"},"user":{"type":["object","null"],"description":"The acting user — null for system-generated events (listener captures, sweeps).","properties":{"id":{"type":"integer","example":7},"name":{"type":"string","example":"Ana Souza"},"email":{"type":"string","example":"ana@example.com"}}},"auditable_type":{"type":["string","null"],"description":"Polymorphic target type — null for events without a target record.","enum":["Inbox","AccessRole","RoutingPolicy","RoutingCapacityPolicy","Governance::ConsentRecord","Governance::DsrRequest","Organization","OrganizationMembership","Relationship","AccountSetupRun",null],"example":"Inbox"},"auditable_id":{"type":["integer","null"],"description":"The audited record's primary key.","example":14},"auditable_display_id":{"type":"integer","description":"Present ONLY when auditable_type is Conversation: a conversation's primary key is not the number shown across the product, so the display_id is resolved and sent alongside it. Absent for every other target type.","example":1042},"metadata":{"type":"object","additionalProperties":true,"description":"Free-form context bag — the key set depends on the action (e.g. template_key, contact_id, sections).","example":{"name":"Support inbox","channel_type":"Channel::WebWidget"}},"ip":{"type":["string","null"],"example":"203.0.113.7"},"created_at":{"type":"integer","description":"Unix timestamp.","example":1789300000}}}},"meta":{"type":"object","properties":{"current_page":{"type":"integer","example":1},"total_pages":{"type":"integer","example":3},"total_entries":{"type":"integer","example":64},"per_page":{"type":"integer","example":25}}}}},"example":{"payload":[{"id":91,"action":"sign_in","user":{"id":7,"name":"Ana Souza","email":"ana@example.com"},"auditable_type":"Inbox","auditable_id":14,"auditable_display_id":1042,"metadata":{"name":"Support inbox","channel_type":"Channel::WebWidget"},"ip":"203.0.113.7","created_at":1789300000}],"meta":{"current_page":1,"total_pages":3,"total_entries":64,"per_page":25}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."}]}},"/api/v1/accounts/{account_id}/governance/consent_records":{"get":{"tags":["Governance"],"operationId":"auto_get_api_v1_accounts_account_id_governance_consent_records","summary":"List consent records","description":"Returns the list of consent records visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The consent history (append-only, newest first; filter with contact_id).","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","example":11},"contact_id":{"type":"integer","example":42},"consent_type":{"type":"string","enum":["data_processing","marketing","cookies","custom","campaigns"],"example":"marketing"},"channel":{"type":"string","maxLength":64,"pattern":"^[a-z0-9_]+$","default":"all","description":"Normalized delivery channel, or all for an account-wide declaration.","example":"whatsapp"},"granted":{"type":"boolean","example":true},"status":{"type":"string","enum":["granted","denied"],"example":"granted","description":"Consent verdict, derived from the record's granted flag (Governance::ConsentRecord#status)."},"current":{"type":"boolean","description":"Whether this event is effective after applying newest global-versus-channel precedence.","example":true},"source":{"type":"string","enum":["agent","api","import","widget","message","keyword"],"example":"agent"},"occurred_at":{"type":"integer","description":"Unix timestamp.","example":1789300000},"note":{"type":["string","null"],"example":"Opt-in confirmed on a call"},"message_id":{"type":["integer","null"],"description":"Inbound response message that proved an automatic consent decision.","example":null},"evidence":{"type":"object","additionalProperties":true,"description":"Structured evidence for the append-only declaration. Automatic capture stores identifiers, the normalized matched token, and a SHA-256 digest, never the raw reply text.","example":{"matched_token":"yes","response_sha256":"8a798890fe93817163b10b5f8f0c48ee4dd4d3db0d98c35e59a27c2603c4d8a2"}},"recorded_by":{"type":["object","null"],"properties":{"id":{"type":"integer","example":7},"name":{"type":"string","example":"Ana Souza"}}},"created_at":{"type":"integer","description":"Unix timestamp.","example":1789300000}}}},"example":[{"id":11,"contact_id":42,"consent_type":"marketing","channel":"whatsapp","granted":true,"status":"granted","current":true,"source":"agent","occurred_at":1789300000,"note":"Opt-in confirmed on a call","message_id":null,"evidence":{"matched_token":"yes","response_sha256":"8a798890fe93817163b10b5f8f0c48ee4dd4d3db0d98c35e59a27c2603c4d8a2"},"recorded_by":{"id":7,"name":"Ana Souza"},"created_at":1789300000}]}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"contact_id","in":"query","required":false,"schema":{"type":"integer"},"example":42},{"name":"consent_type","in":"query","required":false,"schema":{"type":"string","enum":["data_processing","marketing","cookies","custom","campaigns"]},"example":"data_processing"},{"name":"channel","in":"query","required":false,"schema":{"type":"string","pattern":"^[a-z0-9_]+$"},"example":"whatsapp"}]},"post":{"tags":["Governance"],"operationId":"auto_post_api_v1_accounts_account_id_governance_consent_records","summary":"Create consent records","description":"Creates a new consent record from the request payload. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The appended consent event (the newest applicable event per purpose and channel is the current state).","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer","example":11},"contact_id":{"type":"integer","example":42},"consent_type":{"type":"string","enum":["data_processing","marketing","cookies","custom","campaigns"],"example":"marketing"},"channel":{"type":"string","maxLength":64,"pattern":"^[a-z0-9_]+$","default":"all","description":"Normalized delivery channel, or all for an account-wide declaration.","example":"whatsapp"},"granted":{"type":"boolean","example":true},"status":{"type":"string","enum":["granted","denied"],"example":"granted","description":"Consent verdict, derived from the record's granted flag (Governance::ConsentRecord#status)."},"current":{"type":"boolean","description":"Whether this event is effective after applying newest global-versus-channel precedence.","example":true},"source":{"type":"string","enum":["agent","api","import","widget","message","keyword"],"example":"agent"},"occurred_at":{"type":"integer","description":"Unix timestamp.","example":1789300000},"note":{"type":["string","null"],"example":"Opt-in confirmed on a call"},"message_id":{"type":["integer","null"],"description":"Inbound response message that proved an automatic consent decision.","example":null},"evidence":{"type":"object","additionalProperties":true,"description":"Structured evidence for the append-only declaration. Automatic capture stores identifiers, the normalized matched token, and a SHA-256 digest, never the raw reply text.","example":{"ticket_id":"PRIV-1042"}},"recorded_by":{"type":["object","null"],"properties":{"id":{"type":"integer","example":7},"name":{"type":"string","example":"Ana Souza"}}},"created_at":{"type":"integer","description":"Unix timestamp.","example":1789300000}}},"example":{"id":11,"contact_id":42,"consent_type":"marketing","channel":"whatsapp","granted":true,"status":"granted","current":true,"source":"agent","occurred_at":1789300000,"note":"Opt-in confirmed on a call","message_id":null,"evidence":{"ticket_id":"PRIV-1042"},"recorded_by":{"id":7,"name":"Ana Souza"},"created_at":1789300000}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["consent_record"],"properties":{"consent_record":{"type":"object","required":["contact_id","consent_type","granted"],"properties":{"contact_id":{"type":"integer","description":"Account-scoped contact receiving the consent declaration.","example":42},"consent_type":{"type":"string","enum":["data_processing","marketing","cookies","custom","campaigns"],"example":"marketing"},"channel":{"type":"string","maxLength":64,"pattern":"^[a-z0-9_]+$","default":"all","description":"Normalized delivery channel; omit or use all for an account-wide declaration.","example":"whatsapp"},"granted":{"type":"boolean","example":true},"source":{"type":["string","null"],"enum":["agent","api","import","widget",null],"description":"Capture origin; omitted values are recorded as agent.","example":"agent"},"occurred_at":{"type":["string","null"],"format":"date-time","description":"Declaration time; omitted values use the server time.","example":"2026-09-13T12:26:40Z"},"note":{"type":["string","null"],"description":"Optional human-readable evidence note.","example":"Opt-in confirmed on a call"},"evidence":{"type":"object","additionalProperties":true,"description":"Optional structured evidence supplied by an authenticated manual/API capture.","example":{"ticket_id":"PRIV-1042"}}}}}},"example":{"consent_record":{"contact_id":42,"consent_type":"marketing","channel":"whatsapp","granted":true,"source":"agent","occurred_at":"2026-09-13T12:26:40Z","note":"Opt-in confirmed on a call","evidence":{"ticket_id":"PRIV-1042"}}}}}}}},"/api/v1/accounts/{account_id}/governance/legal_holds":{"get":{"tags":["Governance"],"operationId":"auto_get_api_v1_accounts_account_id_governance_legal_holds","summary":"List legal holds","description":"Returns the list of legal holds visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"reason":{"type":"string"},"active":{"type":"boolean"},"created_at":{"type":"integer"},"released_at":{"type":["integer","null"]},"conversation":{"type":"object","properties":{"id":{"type":"integer"},"display_id":{"type":["integer","null"]}}},"created_by":{"type":"string"},"released_by":{"type":"string"}}}},"example":[{"id":1,"reason":"Sample reason.","active":true,"created_at":1,"released_at":1,"conversation":{"id":1,"display_id":1},"created_by":"sample created by","released_by":"sample released by"}]}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."}]},"post":{"tags":["Governance"],"operationId":"auto_post_api_v1_accounts_account_id_governance_legal_holds","summary":"Create legal holds","description":"Creates a new legal hold from the request payload. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}},"example":{"error":"sample error"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"legal_hold":{"type":"object","properties":{"conversation_display_id":{"type":"integer"},"reason":{"type":"string","enum":["","client_revocation","refresh_token_reuse","subject_revoked","account_admin_security_review","account_admin_access_removed","account_admin_client_decommissioned","account_admin_incident_response","operator_security_review","operator_access_removed","operator_client_decommissioned","operator_incident_response","operator_credential_provisioning","operator_credential_rotation","operator_approval_required","operator_approval_approved","operator_approval_rejected","operator_approval_execution_failed","operator_approval_response_delivery_failed","operator_approval_execution_unknown","operator_approval_execution_started","operator_approval_execution_succeeded","operator_approval_execution_rejected","operator_approval_confirmed_succeeded","operator_approval_confirmed_not_applied","operator_delegation_profile_changed","operator_delegation_profile_revoked","mfa_disabled"]}},"required":["reason"]}},"required":["legal_hold"]},"example":{"legal_hold":{"conversation_display_id":1,"reason":""}}}}}}},"/api/v1/accounts/{account_id}/governance/legal_holds/{id}":{"delete":{"tags":["Governance"],"operationId":"auto_delete_api_v1_accounts_account_id_governance_legal_holds_id","summary":"Delete legal holds","description":"Deletes the legal hold identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The released legal hold (the row is kept as evidence that deletion was suspended)","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer","example":91},"reason":{"type":"string","description":"Why deletion was suspended","example":"Court order 1234"},"active":{"type":"boolean","description":"False once released","example":false},"created_at":{"type":"integer","description":"Unix timestamp when the hold was placed","example":1782000000},"released_at":{"type":["integer","null"],"description":"Unix timestamp when the hold was released; null while active","example":1782600000},"conversation":{"type":"object","properties":{"id":{"type":"integer","example":4821},"display_id":{"type":"integer","description":"The number agents see on the conversation","example":1042}}},"created_by":{"type":["object","null"],"description":"The user who placed the hold; null when the user was since deleted","properties":{"id":{"type":"integer","example":7},"name":{"type":"string","example":"Ana Ribeiro"}}},"released_by":{"type":["object","null"],"description":"The user who released the hold; null while the hold is active","properties":{"id":{"type":"integer","example":7},"name":{"type":"string","example":"Ana Ribeiro"}}}}},"example":{"id":91,"reason":"Court order 1234","active":false,"created_at":1782000000,"released_at":1782600000,"conversation":{"id":4821,"display_id":1042},"created_by":{"id":7,"name":"Ana Ribeiro"},"released_by":{"id":7,"name":"Ana Ribeiro"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/governance/dsr_requests/{id}/download":{"get":{"tags":["Governance"],"operationId":"auto_get_api_v1_accounts_account_id_governance_dsr_requests_id_download","summary":"Download dsr requests","description":"Performs the download operation on the targeted dsr request resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"A short-lived service URL for the authorized export bundle download.","content":{"application/json":{"schema":{"type":"object","properties":{"download_url":{"type":"string","description":"Storage-service URL that expires after the indicated number of seconds.","example":"https://storage.example.com/exports/contact-42.zip?signature=short-lived"},"expires_in":{"type":"integer","description":"Lifetime of the URL in seconds.","example":300}}},"example":{"download_url":"https://storage.example.com/exports/contact-42.zip?signature=short-lived","expires_in":300}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/governance/dsr_requests/scope":{"get":{"tags":["Governance"],"operationId":"auto_get_api_v1_accounts_account_id_governance_dsr_requests_scope","summary":"Scope dsr requests","description":"Performs the scope operation on the targeted dsr request resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"contact_id":{"type":"integer"},"total_rows":{"type":"string"},"modules":{"type":"array","items":{"type":"object","properties":{"module":{"type":"string"},"model":{"type":"string"},"count":{"type":"integer"},"disposition":{"type":"string"},"holds":{"type":"string"}}}}}},"example":{"contact_id":1,"total_rows":"sample total rows","modules":[{"module":"sample module","model":"sample model","count":5,"disposition":"sample disposition","holds":"sample holds"}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/governance/dsr_requests":{"get":{"tags":["Governance"],"operationId":"auto_get_api_v1_accounts_account_id_governance_dsr_requests","summary":"List dsr requests","description":"Returns the list of dsr requests visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The account's data-subject requests, newest first.","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","example":5},"contact_id":{"type":"integer","example":42},"kind":{"type":"string","enum":["export","erase","anonymize"],"example":"export"},"status":{"type":"string","enum":["pending","processing","completed","failed"],"example":"pending"},"options":{"type":"object","additionalProperties":true,"description":"Kind-specific options as requested (e.g. scrub_messages for anonymize).","example":{"scrub_messages":false}},"error":{"type":["string","null"],"example":null},"requested_by":{"type":["object","null"],"properties":{"id":{"type":"integer","example":7},"name":{"type":"string","example":"Ana Souza"}}},"export_file_available":{"type":"boolean","description":"Whether this export receipt has a bundle available through the separately authorized download endpoint.","example":false},"completed_at":{"type":["integer","null"],"description":"Unix timestamp.","example":null},"created_at":{"type":"integer","description":"Unix timestamp.","example":1789300000}}}},"example":[{"id":5,"contact_id":42,"kind":"export","status":"pending","options":{"scrub_messages":false},"error":null,"requested_by":{"id":7,"name":"Ana Souza"},"export_file_available":false,"completed_at":null,"created_at":1789300000}]}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."}]},"post":{"tags":["Governance"],"operationId":"auto_post_api_v1_accounts_account_id_governance_dsr_requests","summary":"Create dsr requests","description":"Creates a new dsr request from the request payload. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The created request — the compliance receipt; jobs run async.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer","example":5},"contact_id":{"type":"integer","example":42},"kind":{"type":"string","enum":["export","erase","anonymize"],"example":"export"},"status":{"type":"string","enum":["pending","processing","completed","failed"],"example":"pending"},"options":{"type":"object","additionalProperties":true,"description":"Kind-specific options as requested (e.g. scrub_messages for anonymize).","example":{"scrub_messages":false}},"error":{"type":["string","null"],"example":null},"requested_by":{"type":["object","null"],"properties":{"id":{"type":"integer","example":7},"name":{"type":"string","example":"Ana Souza"}}},"export_file_available":{"type":"boolean","description":"Whether this export receipt has a bundle available through the separately authorized download endpoint.","example":false},"completed_at":{"type":["integer","null"],"description":"Unix timestamp.","example":null},"created_at":{"type":"integer","description":"Unix timestamp.","example":1789300000}}},"example":{"id":5,"contact_id":42,"kind":"export","status":"pending","options":{"scrub_messages":false},"error":null,"requested_by":{"id":7,"name":"Ana Souza"},"export_file_available":false,"completed_at":null,"created_at":1789300000}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["kind","contact_id"],"properties":{"kind":{"type":"string","enum":["export","erase","anonymize"],"example":"export"},"contact_id":{"type":"integer","example":42},"confirmation":{"type":"string","description":"Required for erase/anonymize — must echo the contact id (type-to-confirm guard).","example":"42"},"options":{"type":"object","description":"Kind-specific options.","properties":{"scrub_messages":{"type":"boolean","description":"anonymize only — also redact the contact's inbound messages and purge attachments.","example":false}}}}},"example":{"kind":"export","contact_id":42,"confirmation":"42","options":{"scrub_messages":false}}}}}}},"/api/v1/accounts/{account_id}/governance/dsr_requests/{id}":{"get":{"tags":["Governance"],"operationId":"auto_get_api_v1_accounts_account_id_governance_dsr_requests_id","summary":"Get dsr requests","description":"Returns the dsr request identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"One data-subject request (the compliance receipt).","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer","example":5},"contact_id":{"type":"integer","example":42},"kind":{"type":"string","enum":["export","erase","anonymize"],"example":"export"},"status":{"type":"string","enum":["pending","processing","completed","failed"],"example":"pending"},"options":{"type":"object","additionalProperties":true,"description":"Kind-specific options as requested (e.g. scrub_messages for anonymize).","example":{"scrub_messages":false}},"error":{"type":["string","null"],"example":null},"requested_by":{"type":["object","null"],"properties":{"id":{"type":"integer","example":7},"name":{"type":"string","example":"Ana Souza"}}},"export_file_available":{"type":"boolean","description":"Whether this export receipt has a bundle available through the separately authorized download endpoint.","example":false},"completed_at":{"type":["integer","null"],"description":"Unix timestamp.","example":null},"created_at":{"type":"integer","description":"Unix timestamp.","example":1789300000}}},"example":{"id":5,"contact_id":42,"kind":"export","status":"pending","options":{"scrub_messages":false},"error":null,"requested_by":{"id":7,"name":"Ana Souza"},"export_file_available":false,"completed_at":null,"created_at":1789300000}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/agent_capacity_policies/{agent_capacity_policy_id}/users":{"get":{"tags":["Agent Capacity Policies"],"operationId":"auto_get_api_v1_accounts_account_id_agent_capacity_policies_agent_capacity_policy_id_users","summary":"List users","description":"Returns the list of users visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/user"}},"example":[{"id":1,"access_token":"sample-token","account_id":1,"available_name":"sample available name","avatar_url":"https://example.com/resource","confirmed":true,"display_name":"sample display name","message_signature":"sample message signature","email":"agent@example.com","hmac_identifier":"sample hmac identifier","inviter_id":1,"name":"Sample Name","provider":"email","pubsub_token":"sample-token","role":"agent","ui_settings":{"translation_language_by_account":{"1":"pt-BR"}},"uid":"sample uid","type":"sample type","custom_attributes":{},"accounts":[{"id":1,"name":"Sample Name","status":"active","active_at":"2026-01-15T10:30:00.000Z","role":"administrator","outbound_agent_name_header_policy":"inherit","permissions":["sample permission"],"availability":"online","availability_status":"online","auto_offline":true,"custom_role_id":1,"custom_role":{"id":1,"name":"Sample Name","description":"A short description.","permissions":["conversation_manage"]},"onboarding_step":"sample onboarding step","access_role_id":1,"access_role":{"id":1,"name":"Sample Name","field_permissions":{"contact":{},"organization":{}}},"api_and_webhooks":true}]}]}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"agent_capacity_policy_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."}]},"post":{"tags":["Agent Capacity Policies"],"operationId":"auto_post_api_v1_accounts_account_id_agent_capacity_policies_agent_capacity_policy_id_users","summary":"Create users","description":"Creates a new user from the request payload. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/user"},"example":{"id":1,"access_token":"sample-token","account_id":1,"available_name":"sample available name","avatar_url":"https://example.com/resource","confirmed":true,"display_name":"sample display name","message_signature":"sample message signature","email":"agent@example.com","hmac_identifier":"sample hmac identifier","inviter_id":1,"name":"Sample Name","provider":"email","pubsub_token":"sample-token","role":"agent","ui_settings":{"translation_language_by_account":{"1":"pt-BR"}},"uid":"sample uid","type":"sample type","custom_attributes":{},"accounts":[{"id":1,"name":"Sample Name","status":"active","active_at":"2026-01-15T10:30:00.000Z","role":"administrator","outbound_agent_name_header_policy":"inherit","permissions":["sample permission"],"availability":"online","availability_status":"online","auto_offline":true,"custom_role_id":1,"custom_role":{"id":1,"name":"Sample Name","description":"A short description.","permissions":["conversation_manage"]},"onboarding_step":"sample onboarding step","access_role_id":1,"access_role":{"id":1,"name":"Sample Name","field_permissions":{"contact":{},"organization":{}}},"api_and_webhooks":true}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"agent_capacity_policy_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"user_id":{"type":"integer"}}},"example":{"user_id":1}}}}}},"/api/v1/accounts/{account_id}/agent_capacity_policies/{agent_capacity_policy_id}/users/{id}":{"delete":{"tags":["Agent Capacity Policies"],"operationId":"auto_delete_api_v1_accounts_account_id_agent_capacity_policies_agent_capacity_policy_id_users_id","summary":"Delete users","description":"Deletes the user identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Success (no content)"},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"agent_capacity_policy_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/agent_capacity_policies/{agent_capacity_policy_id}/inbox_limits":{"post":{"tags":["Agent Capacity Policies"],"operationId":"auto_post_api_v1_accounts_account_id_agent_capacity_policies_agent_capacity_policy_id_inbox_limits","summary":"Create inbox limits","description":"Creates a new inbox limit from the request payload. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"inbox_id":{"type":"integer"},"agent_capacity_policy_id":{"type":"integer"},"conversation_limit":{"type":"string"},"created_at":{"type":"integer"},"updated_at":{"type":"integer"}}},"example":{"id":1,"inbox_id":1,"agent_capacity_policy_id":1,"conversation_limit":"sample conversation limit","created_at":1,"updated_at":1}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"agent_capacity_policy_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"inbox_id":{"type":"integer"},"conversation_limit":{"type":"string"}}},"example":{"inbox_id":1,"conversation_limit":"sample conversation limit"}}}}}},"/api/v1/accounts/{account_id}/agent_capacity_policies/{agent_capacity_policy_id}/inbox_limits/{id}":{"patch":{"tags":["Agent Capacity Policies"],"operationId":"auto_patch_api_v1_accounts_account_id_agent_capacity_policies_agent_capacity_policy_id_inbox_limits_id","summary":"Update inbox limits","description":"Updates the inbox limit identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"inbox_id":{"type":"integer"},"inbox_name":{"type":"string"},"agent_capacity_policy_id":{"type":"integer"},"conversation_limit":{"type":"string"},"created_at":{"type":"integer"},"updated_at":{"type":"integer"}}},"example":{"id":1,"inbox_id":1,"inbox_name":"sample inbox name","agent_capacity_policy_id":1,"conversation_limit":"sample conversation limit","created_at":1,"updated_at":1}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"agent_capacity_policy_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"inbox_id":{"type":"integer"},"conversation_limit":{"type":"string"}}},"example":{"inbox_id":1,"conversation_limit":"sample conversation limit"}}}}},"put":{"tags":["Agent Capacity Policies"],"operationId":"auto_put_api_v1_accounts_account_id_agent_capacity_policies_agent_capacity_policy_id_inbox_limits_id","summary":"Update inbox limits","description":"Updates the inbox limit identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"inbox_id":{"type":"integer"},"inbox_name":{"type":"string"},"agent_capacity_policy_id":{"type":"integer"},"conversation_limit":{"type":"string"},"created_at":{"type":"integer"},"updated_at":{"type":"integer"}}},"example":{"id":1,"inbox_id":1,"inbox_name":"sample inbox name","agent_capacity_policy_id":1,"conversation_limit":"sample conversation limit","created_at":1,"updated_at":1}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"agent_capacity_policy_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"inbox_id":{"type":"integer"},"conversation_limit":{"type":"string"}}},"example":{"inbox_id":1,"conversation_limit":"sample conversation limit"}}}}},"delete":{"tags":["Agent Capacity Policies"],"operationId":"auto_delete_api_v1_accounts_account_id_agent_capacity_policies_agent_capacity_policy_id_inbox_limits_id","summary":"Delete inbox limits","description":"Deletes the inbox limit identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"204":{"description":"Success (no content)"},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"agent_capacity_policy_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/agent_capacity_policies":{"get":{"tags":["Agent Capacity Policies"],"operationId":"auto_get_api_v1_accounts_account_id_agent_capacity_policies","summary":"List agent capacity policies","description":"Returns the list of agent capacity policies visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"exclusion_rules":{"type":"string"},"created_at":{"type":"integer"},"updated_at":{"type":"integer"},"account_id":{"type":"integer"},"assigned_agent_count":{"type":"integer"},"inbox_capacity_limits":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"inbox_id":{"type":"integer"},"conversation_limit":{"type":"string"}}}}}}},"example":[{"id":1,"name":"Sample Name","description":"A short description.","exclusion_rules":"sample exclusion rules","created_at":1,"updated_at":1,"account_id":1,"assigned_agent_count":5,"inbox_capacity_limits":[{"id":1,"inbox_id":1,"conversation_limit":"sample conversation limit"}]}]}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."}]},"post":{"tags":["Agent Capacity Policies"],"operationId":"auto_post_api_v1_accounts_account_id_agent_capacity_policies","summary":"Create agent capacity policies","description":"Creates a new agent capacity policy from the request payload. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"exclusion_rules":{"type":"string"},"created_at":{"type":"integer"},"updated_at":{"type":"integer"},"account_id":{"type":"integer"},"assigned_agent_count":{"type":"integer"},"inbox_capacity_limits":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"inbox_id":{"type":"integer"},"conversation_limit":{"type":"string"}}}}}},"example":{"id":1,"name":"Sample Name","description":"A short description.","exclusion_rules":"sample exclusion rules","created_at":1,"updated_at":1,"account_id":1,"assigned_agent_count":5,"inbox_capacity_limits":[{"id":1,"inbox_id":1,"conversation_limit":"sample conversation limit"}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"agent_capacity_policy":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"exclusion_rules":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Free-form object."}}},"required":["name"]}},"required":["agent_capacity_policy"]},"example":{"agent_capacity_policy":{"name":"Sample Name","description":"A short description.","exclusion_rules":[{}]}}}}}}},"/api/v1/accounts/{account_id}/agent_capacity_policies/{id}":{"get":{"tags":["Agent Capacity Policies"],"operationId":"auto_get_api_v1_accounts_account_id_agent_capacity_policies_id","summary":"Get agent capacity policies","description":"Returns the agent capacity policy identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"exclusion_rules":{"type":"string"},"created_at":{"type":"integer"},"updated_at":{"type":"integer"},"account_id":{"type":"integer"},"assigned_agent_count":{"type":"integer"},"inbox_capacity_limits":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"inbox_id":{"type":"integer"},"conversation_limit":{"type":"string"}}}}}},"example":{"id":1,"name":"Sample Name","description":"A short description.","exclusion_rules":"sample exclusion rules","created_at":1,"updated_at":1,"account_id":1,"assigned_agent_count":5,"inbox_capacity_limits":[{"id":1,"inbox_id":1,"conversation_limit":"sample conversation limit"}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]},"patch":{"tags":["Agent Capacity Policies"],"operationId":"auto_patch_api_v1_accounts_account_id_agent_capacity_policies_id","summary":"Update agent capacity policies","description":"Updates the agent capacity policy identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"exclusion_rules":{"type":"string"},"created_at":{"type":"integer"},"updated_at":{"type":"integer"},"account_id":{"type":"integer"},"assigned_agent_count":{"type":"integer"},"inbox_capacity_limits":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"inbox_id":{"type":"integer"},"conversation_limit":{"type":"string"}}}}}},"example":{"id":1,"name":"Sample Name","description":"A short description.","exclusion_rules":"sample exclusion rules","created_at":1,"updated_at":1,"account_id":1,"assigned_agent_count":5,"inbox_capacity_limits":[{"id":1,"inbox_id":1,"conversation_limit":"sample conversation limit"}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"agent_capacity_policy":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"exclusion_rules":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Free-form object."}}}}},"required":["agent_capacity_policy"]},"example":{"agent_capacity_policy":{"name":"Sample Name","description":"A short description.","exclusion_rules":[{}]}}}}}},"put":{"tags":["Agent Capacity Policies"],"operationId":"auto_put_api_v1_accounts_account_id_agent_capacity_policies_id","summary":"Update agent capacity policies","description":"Updates the agent capacity policy identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"exclusion_rules":{"type":"string"},"created_at":{"type":"integer"},"updated_at":{"type":"integer"},"account_id":{"type":"integer"},"assigned_agent_count":{"type":"integer"},"inbox_capacity_limits":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"inbox_id":{"type":"integer"},"conversation_limit":{"type":"string"}}}}}},"example":{"id":1,"name":"Sample Name","description":"A short description.","exclusion_rules":"sample exclusion rules","created_at":1,"updated_at":1,"account_id":1,"assigned_agent_count":5,"inbox_capacity_limits":[{"id":1,"inbox_id":1,"conversation_limit":"sample conversation limit"}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"agent_capacity_policy":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"exclusion_rules":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Free-form object."}}}}},"required":["agent_capacity_policy"]},"example":{"agent_capacity_policy":{"name":"Sample Name","description":"A short description.","exclusion_rules":[{}]}}}}}},"delete":{"tags":["Agent Capacity Policies"],"operationId":"auto_delete_api_v1_accounts_account_id_agent_capacity_policies_id","summary":"Delete agent capacity policies","description":"Deletes the agent capacity policy identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Success (no content)"},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/campaigns/{id}/pause":{"post":{"tags":["Campaigns"],"operationId":"auto_post_api_v1_accounts_account_id_campaigns_id_pause","summary":"Pause a running campaign","description":"Moves a campaign that is currently sending into the paused state, which stops further recipient dispatches. A native WhatsApp Web campaign pauses from `sending`; a WhatsApp Cloud one-off pauses from `processing`: its dispatch loop stops at its next checkpoint, contacts it had not reached get no recipient row, and a campaign message already queued is held back before it reaches Meta (never charged) with its recipient returned to `pending`. The pause reason is recorded under `send_settings.dispatch_control.pause` (`reason` = `manual`). A Cloud campaign is also paused automatically, without this call, when Meta refuses its template (Graph error codes 132015, 132016 or 132001; 132005 only when the template carries no parameters, otherwise it fails just that recipient; or a PAUSED/DISABLED/ARCHIVED template status webhook); the reason is then `meta_template_rejected` or `meta_template_status` and every administrator receives a `campaign_auto_paused` notification. It is likewise paused, with the reason `meta_account_restricted`, when Meta refuses a send for the whole account or business portfolio (Graph error codes 131063, 131064, 135000, 131042, 131031 or 368) or answers a template send with `message_status: held_for_quality_assessment` (the pause `error_code` is then that string). A Cloud campaign whose dispatch stopped making progress is first recovered automatically (a `stalled_recovered` entry in `send_settings.dispatch_control.history`) and, when it still does not move, paused with the reason `stalled` (resumable, same notification). Answers `200 OK` with the updated campaign; a campaign in any other state is refused with `422`, and the body names the `campaign_status` that blocked it.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Campaign paused. Body is the updated campaign."},"401":{"description":"Unauthorized"},"404":{"description":"No campaign with this display id in the account."},"422":{"description":"The campaign was not sending, so it cannot be paused. Body is `{ \"error\": \"not_pausable\", \"campaign_status\": \"\u003ccurrent status\u003e\" }`."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/campaigns/{id}/resume":{"post":{"tags":["Campaigns"],"operationId":"auto_post_api_v1_accounts_account_id_campaigns_id_resume","summary":"Resume a paused campaign","description":"Resumes a paused campaign. A native WhatsApp Web campaign flips back to sending and re-schedules every recipient still pending, honouring the configured anti-block delays. A WhatsApp Cloud one-off flips back to `processing` under a new run and continues in the background with ONLY the contacts that have no recipient row yet or whose row is still `pending`; nobody who already received, or was refused, is sent to again, and `started_at` is kept. When the Cloud campaign was paused because Meta refused its template, the resume is refused until an approved template is in place: `template_not_approved` while the campaign template is not APPROVED in the inbox template cache, `template_status_pending` while it is the refused template and the cache has not been refreshed since the pause. A pause for the whole account or portfolio (`meta_account_restricted`) does not depend on the template cache: this call is the operator's explicit resume once the cause is fixed. The optional `template_params` switches the Cloud campaign to another approved template in the same call. The detail read (`GET .../campaigns/{id}`) exposes the same answer as `resume_block_reason`. Only a PAUSED campaign can be resumed; any other state is refused with `422`.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Resume processed. Body is the campaign after the transition."},"401":{"description":"Unauthorized"},"404":{"description":"No campaign with this display id in the account."},"422":{"description":"The campaign cannot resume. Body is `{ \"error\": \"\u003ccode\u003e\", \"campaign_status\": \"\u003ccurrent status\u003e\" }` where `error` is `not_resumable` (not paused), `template_not_approved` or `template_status_pending` (WhatsApp Cloud campaign paused because Meta refused its template)."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"template_params":{"type":"object","additionalProperties":true,"description":"WhatsApp Cloud only. Replacement template for the rest of the dispatch, in the same shape `campaign.template_params` takes on create (`name`, `language`, `category`, `namespace`, `processed_params`). Must name a template APPROVED on the campaign inbox.","example":{"name":"promo_v4","language":"pt_BR","category":"MARKETING","processed_params":{"body":{"1":"Maria"}}}}}},"example":{"template_params":{"name":"promo_v4","language":"pt_BR","category":"MARKETING","processed_params":{"body":{"1":"Maria"}}}}}}}}},"/api/v1/accounts/{account_id}/campaigns/{id}/cancel":{"post":{"tags":["Campaigns"],"operationId":"auto_post_api_v1_accounts_account_id_campaigns_id_cancel","summary":"Cancel a campaign","description":"Stops the campaign for good, dropping the recipients that had not been dispatched yet. A native WhatsApp Web campaign is cancellable in `draft`, `scheduled`, `sending` or `paused`. A WhatsApp Cloud one-off is cancellable while waiting for its scheduled time (`active`, never started), while dispatching (`processing`) and while `paused`: it becomes `completed` with `enabled: false`, rows still `pending`/`processing` become `skipped` (`campaign_cancelled`, never charged), the dispatch loop stops at its next checkpoint, and a message already queued is held back before reaching Meta. Messages already sent keep their delivery status. Answers `200 OK` with the campaign after the cancellation; anything else is refused with `422`.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Cancellation processed. Body is the campaign after the pending recipients were skipped."},"401":{"description":"Unauthorized"},"404":{"description":"No campaign with this display id in the account."},"422":{"description":"The campaign is in a state that cannot be cancelled. Body is `{ \"error\": \"not_cancellable\", \"campaign_status\": \"\u003ccurrent status\u003e\" }`."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/campaigns/{id}/recipients":{"get":{"tags":["Campaigns"],"operationId":"auto_get_api_v1_accounts_account_id_campaigns_id_recipients","summary":"Recipients campaigns","description":"Performs the recipients operation on the targeted campaign resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"One page of campaign recipients with their dispatch funnel, the price frozen at dispatch and — with the `whatsapp_cost_center` feature — the WhatsApp cost-ledger state of the recipient's current message (else its most recent one). The ledger fields are null when nothing was recorded.","content":{"application/json":{"schema":{"type":"object","properties":{"meta":{"type":"object","properties":{"count":{"type":"integer"},"current_page":{"type":"integer"},"total_pages":{"type":"integer"}}},"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"status":{"type":"string","enum":["pending","processing","sent","delivered","read","replied","failed","skipped"],"description":"Per-recipient delivery funnel status for the campaign."},"error":{"type":["string","null"],"description":"Reason recorded for a failed send."},"conversation_id":{"type":["integer","null"]},"conversation_display_id":{"type":["integer","null"],"description":"Per-account conversation display id used by dashboard routes."},"message_id":{"type":["integer","null"]},"sent_at":{"type":["string","null"],"format":"date-time"},"delivered_at":{"type":["string","null"],"format":"date-time"},"read_at":{"type":["string","null"],"format":"date-time"},"replied_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"},"cost":{"type":["string","null"],"description":"Price frozen at dispatch, as a decimal string in MAJOR units (present once the pricing audit is available)."},"cost_basis":{"type":["string","null"],"enum":["frozen",null],"description":"`frozen` when the recipient was priced at dispatch."},"priced_at":{"type":["string","null"],"format":"date-time"},"billing_state":{"type":["string","null"],"enum":["pending_delivery","billable","free","not_billed","not_billed_expired","unverified",null],"description":"WhatsApp cost-ledger state of the recipient's message; only `billable` counts as cost."},"free_reason":{"type":["string","null"],"enum":["free_tier","free_customer_service","free_entry_point","business_app","web_transport",null],"description":"Why a `free` message costs nothing (`free_tier` = inside the number's monthly free tier of service messages)."},"amount_source":{"type":["string","null"],"enum":["list_rate","tier_estimated","override","meta_reported",null],"description":"How the ledger amount was priced — official rate card, estimated volume tier, the account's own tariff or the cost Meta reported (max-price marketing)."},"partner_billed":{"type":["boolean","null"],"description":"True when the number is billed by a Solution Partner."},"billed_amount":{"type":["number","null"],"description":"What this recipient actually cost — the sum of its delivered billable ledger entries (a retry adds up), in `billed_currency`. Null until something is billable."},"billed_currency":{"type":["string","null"],"description":"ISO currency of `billed_amount` (the WABA billing currency); null when nothing is billable."},"contact":{"type":"object","description":"The recipient contact; `name` and `phone_number` follow the caller's field visibility (masked or omitted).","properties":{"id":{"type":"integer"},"name":{"type":["string","null"]},"phone_number":{"type":["string","null"]}}}}}}}},"example":{"meta":{"count":2,"current_page":1,"total_pages":1},"payload":[{"id":1101,"status":"delivered","error":null,"conversation_id":5520,"conversation_display_id":1234,"message_id":88431,"sent_at":"2026-10-02T12:00:00.000Z","delivered_at":"2026-10-02T12:00:05.000Z","read_at":null,"replied_at":null,"created_at":"2026-10-02T11:59:58.000Z","cost":"0.0068","cost_basis":"frozen","priced_at":"2026-10-02T11:59:58.000Z","billing_state":"billable","free_reason":null,"amount_source":"list_rate","partner_billed":false,"billed_amount":0.0068,"billed_currency":"USD","contact":{"id":1341,"name":"Maria Souza","phone_number":"+5511999990000"}},{"id":1102,"status":"delivered","error":null,"conversation_id":5521,"conversation_display_id":1235,"message_id":88432,"sent_at":"2026-10-02T12:00:01.000Z","delivered_at":"2026-10-02T12:00:06.000Z","read_at":"2026-10-02T12:10:00.000Z","replied_at":null,"created_at":"2026-10-02T11:59:58.000Z","cost":null,"cost_basis":null,"priced_at":null,"billing_state":"free","free_reason":"free_customer_service","amount_source":null,"partner_billed":false,"billed_amount":null,"billed_currency":null,"contact":{"id":1342,"name":"João Pereira","phone_number":"+5521988880000"}}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"status","in":"query","required":false,"description":"Restrict to recipients in one dispatch state. An unknown value is ignored.","schema":{"type":"string","enum":["pending","processing","sent","delivered","read","replied","failed","skipped"]},"example":"failed"},{"name":"page","in":"query","required":false,"description":"Page of recipients.","schema":{"type":"integer","default":1},"example":1},{"name":"per_page","in":"query","required":false,"description":"Recipients per page (default 50).","schema":{"type":"integer","default":50},"example":50}]}},"/api/v1/accounts/{account_id}/campaigns/{id}/retry":{"post":{"tags":["Campaigns"],"operationId":"auto_post_api_v1_accounts_account_id_campaigns_id_retry","summary":"Retry the failed recipients of a campaign","description":"Schedules the campaign's FAILED recipients (all of them, or the `recipient_ids` subset) to be re-materialized and re-sent in the background, and answers `202 Accepted` right away with how many rows were queued. The same classification the campaign detail shows decides what is resent. Errors that fail again until the cause is fixed (a paused or rejected template, an invalid number, an invalid template parameter) are skipped by a retry of every failed recipient and counted in `skipped_fixable`; naming such a row in `recipient_ids` resends it, because the operator fixed the cause. Errors that no resend can fix (a cancelled dispatch, a contact without a phone, a refused consent, a deleted contact) and a send whose outcome is unknown (resending could reach the contact twice) are never resent and are counted in `skipped_permanent`. A row whose contact has since lost its phone, refused consent or was deleted is marked `skipped` when the retry reaches it. Each row is claimed atomically before it is re-sent, so a concurrent retry never sends twice, and the same request cannot be queued twice within a minute (`422` `retry_in_progress`); poll the campaign recipients to watch the queued rows leave `failed`. A WhatsApp Cloud campaign that is still dispatching (`processing`) or `paused` refuses the retry with `422` (`campaign_dispatching`): its dispatch owns the rows until it finishes. A cancelled WhatsApp Cloud campaign refuses it with `422` (`campaign_cancelled`), because cancelling is final; a retry already running stops at its next checkpoint when the campaign is cancelled or starts dispatching again.","security":[{"userApiKey":[]}],"responses":{"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"202":{"description":"Retry accepted. The queued rows are re-sent in the background.","content":{"application/json":{"schema":{"type":"object","required":["queued","skipped_permanent","skipped_fixable","skipped_waiting","skipped_opted_out","campaign_status","recipient_stats"],"properties":{"queued":{"type":"integer","description":"Failed recipients scheduled to be re-sent."},"skipped_permanent":{"type":"integer","description":"Failed recipients never resent: no resend can fix their error, or the send outcome is unknown and a resend could deliver twice."},"skipped_fixable":{"type":"integer","description":"Failed recipients a retry of every failed recipient leaves alone because their error (template, number, template parameter) fails again until its cause is fixed. Always 0 for a request that names `recipient_ids`, which resends them."},"skipped_waiting":{"type":"integer","description":"Failed recipients held back because their error asks for a waiting period that has not passed yet: Meta's per-user marketing limit (131049) asks for at least 24 hours after the failure, and resending earlier can block delivery to that user. Applies to an explicit `recipient_ids` selection too; the rows can be resent once the period ends."},"skipped_opted_out":{"type":"integer","description":"Failed recipients of a MARKETING template whose contact stopped marketing messages from this number after the failure. They are not resent: each row moves from `failed` to `skipped` with `marketing_opted_out`, the reason the dispatch uses, and stays that way. Applies to an explicit `recipient_ids` selection too."},"campaign_status":{"type":"string","enum":["active","completed","draft","scheduled","sending","paused","failed","processing"],"description":"Campaign status when the retry was accepted."},"recipient_stats":{"type":"object","description":"Recipient count per delivery status when the retry was accepted. The queued rows are still `failed` here; they move as the background retry reaches them.","properties":{"pending":{"type":"integer","description":"Recipients waiting to be dispatched."},"processing":{"type":"integer","description":"Recipients claimed by a dispatch or retry and being built."},"sent":{"type":"integer","description":"Recipients whose message was handed to the provider."},"delivered":{"type":"integer","description":"Recipients whose message was delivered."},"read":{"type":"integer","description":"Recipients who read the message."},"replied":{"type":"integer","description":"Recipients who replied."},"failed":{"type":"integer","description":"Recipients whose send failed."},"skipped":{"type":"integer","description":"Recipients that were never sent (no phone, cancelled dispatch)."}}}}},"example":{"queued":412,"skipped_permanent":12,"skipped_fixable":25,"skipped_waiting":3,"skipped_opted_out":2,"campaign_status":"completed","recipient_stats":{"pending":0,"processing":0,"sent":1180,"delivered":3021,"read":1874,"replied":96,"failed":449,"skipped":12}}}}},"422":{"description":"The WhatsApp Cloud campaign is dispatching or paused (`campaign_dispatching`), it was cancelled (`campaign_cancelled`), or the same retry was requested less than a minute ago and is still being scheduled (`retry_in_progress`). Body is `{ \"error\": \"\u003ccode\u003e\", \"campaign_status\": \"\u003ccurrent status\u003e\" }`."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"recipient_ids":{"type":"array","items":{"type":"integer"},"description":"Recipient ids (from the campaign recipients list) to retry. Omit it, or send null, to retry every failed recipient; a list retries only those ids (including the ones whose error is fixable), even when none of them is a failed recipient of this campaign."}}},"example":{"recipient_ids":[18342,18351]}}}}}},"/api/v1/accounts/{account_id}/campaigns/{id}/metrics_history":{"get":{"tags":["Campaigns"],"operationId":"auto_get_api_v1_accounts_account_id_campaigns_id_metrics_history","summary":"Metrics history campaigns","description":"Performs the metrics history operation on the targeted campaign resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"string"}}}},"example":{"payload":["sample payload"]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/campaigns/{id}/cost_reconciliation":{"get":{"tags":["Campaigns"],"operationId":"auto_get_api_v1_accounts_account_id_campaigns_id_cost_reconciliation","summary":"Cost reconciliation campaigns","description":"Performs the cost reconciliation operation on the targeted campaign resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Reconciliation report. `available` is false when there is nothing to compare — the campaign has no frozen prices, the cost-snapshot table is absent, or the report could not be built.","content":{"application/json":{"schema":{"type":"object","properties":{"available":{"type":"boolean","description":"Whether a comparison could be produced. All other fields are present only when true."},"reason":{"type":"string","description":"Why no comparison was produced. Present only when `available` is false.","enum":["pricing_audit_unavailable","snapshots_unavailable","no_priced_recipients","error"]},"currency":{"type":"string","description":"Settlement currency of the frozen prices.","example":"BRL"},"window":{"type":"object","description":"Dispatch window compared, padded by one hour on each side so a straddling send is not clipped.","properties":{"from":{"type":"string","format":"date-time","description":"Start of the compared window."},"to":{"type":"string","format":"date-time","description":"End of the compared window."}}},"frozen":{"type":"object","description":"Our side — the sum of the prices frozen on each billed recipient at dispatch.","properties":{"amount":{"type":"number","format":"float","description":"Sum of the frozen per-recipient prices, in `currency`."},"recipients":{"type":"integer","description":"Number of billed recipients carrying a frozen price."}}},"channel":{"type":"object","description":"Channel side — WhatsApp cost buckets for the same window, narrowed to the categories and countries this campaign priced. `amount` is null when no bucket matched.","properties":{"amount":{"type":["number","null"],"format":"float","description":"Bucket cost converted to `currency`, or null when no bucket matched."},"amount_usd":{"type":"number","format":"float","description":"Bucket cost as reported by the channel, in USD."},"volume":{"type":"integer","description":"Conversations counted across the matched buckets."},"buckets":{"type":"integer","description":"Number of matched buckets."},"fx_rate":{"type":"number","format":"float","description":"USD to `currency` rate used for the comparison."},"fx_source":{"type":"string","description":"Whether the rate was a live quote or the flagged contingency constant.","enum":["live","fallback"]},"reason":{"type":"string","description":"Why the channel side could not be measured. Present only when `amount` is null.","enum":["no_buckets"]}}},"difference":{"type":["object","null"],"description":"Frozen minus channel. Null when the channel side could not be measured — a missing comparison is reported as missing, never as a zero difference.","properties":{"amount":{"type":"number","format":"float","description":"Absolute difference in `currency`. Positive means we froze more than the channel reports."},"percent":{"type":["number","null"],"format":"float","description":"Difference as a percentage of the frozen total, or null when that total is zero."}}}}},"example":{"available":true,"reason":"no_priced_recipients","currency":"BRL","window":{"from":"2026-08-16T10:00:00Z","to":"2026-08-16T14:00:00Z"},"frozen":{"amount":0.6,"recipients":2},"channel":{"amount":0.5,"amount_usd":0.05,"volume":2,"buckets":1,"fx_rate":10.0,"fx_source":"live","reason":"no_buckets"},"difference":{"amount":0.1,"percent":16.67}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/campaigns/dispatch_calculator":{"get":{"tags":["Campaigns"],"operationId":"auto_get_api_v1_accounts_account_id_campaigns_dispatch_calculator","summary":"Dispatch calculator campaigns","description":"Performs the dispatch calculator operation on the targeted campaign resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"WhatsApp dispatch cost calculator data (per-category USD tariffs + live USD→BRL rate)","content":{"application/json":{"schema":{"type":"object","properties":{"exchange_rate":{"type":"object","properties":{"rate":{"type":"number","format":"float","example":5.42},"source":{"type":"string","enum":["live","fallback"],"example":"live"},"base":{"type":"string","example":"USD"},"quote":{"type":"string","example":"BRL"}}},"country":{"type":"string","description":"Resolved ISO country code","example":"BR"},"countries":{"type":"array","items":{"type":"string"},"example":["BR","US","CA","MX","AR","GB","DE","FR","IN","ID","SG","AE","ZA","NG"]},"categories":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string","enum":["marketing","utility","authentication"],"example":"marketing"},"rate_usd":{"type":"number","format":"float","example":0.0625},"base_rate_usd":{"type":"number","format":"float","example":0.0625},"overridden":{"type":"boolean","example":false},"source":{"type":"string","enum":["override","synced","base"],"example":"base"},"billable":{"type":"boolean","example":true}}}},"official_pricing_url":{"type":"string","example":"https://business.whatsapp.com/products/platform-pricing"},"rates_updated_at":{"type":["string","null"],"format":"date","description":"Effective date of the official USD rate card in force; null when no official card is loaded (see rates_source)","example":"2026-10-01"},"rates_source":{"type":"string","enum":["official","legacy"],"description":"official: the official rate card in force (or the account's override of it) answers; legacy: no official card or market map is loaded and the internal reference table answers","example":"official"},"synced_at":{"type":["string","null"],"description":"ISO8601 timestamp of last rate-card sync (nil if never)","example":null}}},"example":{"exchange_rate":{"rate":5.42,"source":"live","base":"USD","quote":"BRL"},"country":"BR","countries":["BR","US","CA","MX","AR","GB","DE","FR","IN","ID","SG","AE","ZA","NG"],"categories":[{"key":"marketing","rate_usd":0.0625,"base_rate_usd":0.0625,"overridden":false,"source":"base","billable":true}],"official_pricing_url":"https://business.whatsapp.com/products/platform-pricing","rates_updated_at":"2026-10-01","rates_source":"official","synced_at":null}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"country","in":"query","required":false,"description":"ISO country code the per-country dispatch pacing is calculated for.","schema":{"type":"string"},"example":"BR"},{"name":"refresh","in":"query","required":false,"description":"Any non-empty value recomputes the projection instead of serving the cached one.","schema":{"type":"string"},"example":"1"}]},"patch":{"tags":["Campaigns"],"operationId":"auto_patch_api_v1_accounts_account_id_campaigns_dispatch_calculator","summary":"Update dispatch calculator campaigns","description":"Performs the update dispatch calculator operation on the targeted campaign resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Override applied — returns the full recalculated calculator payload (same shape as dispatch_calculator)","content":{"application/json":{"schema":{"type":"object","properties":{"exchange_rate":{"type":"object","additionalProperties":true,"description":"FX rate used for dispatch pricing: rate (number), source (live or fallback), base (USD) and quote (BRL)."},"country":{"type":"string","example":"BR"},"countries":{"type":"array","items":{"type":"string"}},"categories":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string","example":"marketing"},"rate_usd":{"type":"number","format":"float","example":0.07},"base_rate_usd":{"type":"number","format":"float","example":0.0625},"overridden":{"type":"boolean","example":true},"source":{"type":"string","example":"override"},"billable":{"type":"boolean","example":true}}}},"official_pricing_url":{"type":"string","example":"https://business.whatsapp.com/products/platform-pricing"},"rates_updated_at":{"type":"string","example":"2026-06-01"},"synced_at":{"type":["string","null"],"example":null}}},"example":{"exchange_rate":{},"country":"BR","countries":["sample countrie"],"categories":[{"key":"marketing","rate_usd":0.07,"base_rate_usd":0.0625,"overridden":true,"source":"override","billable":true}],"official_pricing_url":"https://business.whatsapp.com/products/platform-pricing","rates_updated_at":"2026-06-01","synced_at":null}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"422":{"description":"Invalid category or rate","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["invalid_category","invalid_rate"],"example":"invalid_rate"}}},"example":{"error":"invalid_rate"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["category"],"properties":{"category":{"type":"string","enum":["marketing","utility","authentication"],"example":"marketing"},"rate_usd":{"type":"string","description":"New USD per-message tariff; blank clears the override (restores official/synced rate)","example":"0.07"},"country":{"type":"string","example":"BR"}}},"example":{"category":"marketing","rate_usd":"0.07","country":"BR"}}}}}},"/api/v1/accounts/{account_id}/campaigns/sync_dispatch_pricing":{"post":{"tags":["Campaigns"],"operationId":"auto_post_api_v1_accounts_account_id_campaigns_sync_dispatch_pricing","summary":"Sync dispatch pricing campaigns","description":"Performs the sync dispatch pricing operation on the targeted campaign resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Calculator payload (as in dispatch_calculator) plus the legacy calculator tariff update outcome of this execution under `sync`","content":{"application/json":{"schema":{"type":"object","properties":{"exchange_rate":{"type":"object","additionalProperties":true,"description":"FX rate used for dispatch pricing: rate (number), source (live or fallback), base (USD) and quote (BRL)."},"country":{"type":"string","example":"BR"},"countries":{"type":"array","items":{"type":"string"}},"categories":{"type":"array","description":"Per-category dispatch tariffs (marketing, utility, authentication).","items":{"type":"object","additionalProperties":true,"description":"One category with its effective rate details."}},"official_pricing_url":{"type":"string","example":"https://business.whatsapp.com/products/platform-pricing"},"rates_updated_at":{"type":"string","example":"2026-06-01"},"synced_at":{"type":["string","null"],"example":"2026-01-15T10:30:00.000Z"},"sync":{"type":"object","description":"Calculator sync result: ok is true only when this execution read the page and wrote a current legacy tariff, with its own synced_at and no legacy_rates error. Reading the page or importing future cards alone is not a calculator update. The top-level synced_at may describe a prior cached tariff and cannot prove this execution updated it. rate_card_import retains the separate cost-center import outcome; a partial bulk import does not negate an actual legacy update.","properties":{"ok":{"type":"boolean","example":false,"description":"True only when this execution effectively updated the legacy calculator tariff."},"countries":{"type":["integer","null"],"example":0},"source":{"type":["string","null"],"example":"https://business.whatsapp.com/products/platform-pricing"},"synced_at":{"type":["string","null"],"example":null},"reason":{"type":["string","null"],"enum":["http_error","no_rates_parsed","request_failed",null],"example":"no_rates_parsed","description":"Why no legacy calculator update occurred: non-2xx page response, no usable current legacy tariff (including future-only imports), or a failed request. Document/import diagnostics remain in the separate import outcome."},"status":{"type":["integer","null"],"example":200,"description":"HTTP status the source answered with, when it answered."},"detail":{"type":["string","null"],"example":"execution expired","description":"Diagnostic message of a request that failed before an answer."},"legacy_rates":{"type":"string","enum":["no_rates_parsed"],"description":"Optional legacy-layer diagnostic when no usable legacy tariff was parsed; omitted when absent. Independent of the bulk import outcome.","example":"no_rates_parsed"},"rate_card_import":{"type":["object","null"],"description":"Optional raw bulk-import summary, separate from the legacy calculator update. Imported and failed lists may be empty. A real selected card id can remain present while ok is false, including a partial import or a future-only import; it is null when no card was imported. This raw summary is not the publicly normalized Cost Center sync envelope.","required":["ok","imported","failed","rate_card_id"],"properties":{"ok":{"type":"boolean","example":false,"description":"True only when at least one card was imported and the failed list is empty; this does not define the legacy calculator sync.ok."},"rate_card_id":{"type":["integer","null"],"example":695,"description":"Selected imported card id, including partial or future-only outcomes; null when imported is empty."},"imported":{"type":"array","description":"Cards stored during this execution; may be empty.","items":{"type":"object","required":["currency","effective_from","rate_card_id"],"properties":{"currency":{"type":"string","example":"USD"},"effective_from":{"type":"string","format":"date","example":"2026-10-01"},"rate_card_id":{"type":"integer","example":695}}},"example":[{"currency":"USD","effective_from":"2026-10-01","rate_card_id":695}]},"failed":{"type":"array","description":"Failed eligible document groups or imports, and a missing current USD tariff; may be empty.","items":{"type":"object","required":["currency","effective_from","error"],"properties":{"currency":{"type":"string","example":"USD"},"effective_from":{"type":["string","null"],"format":"date","example":null,"description":"Declared effective date when known; null when the date or a current tariff is unavailable."},"error":{"type":"string","description":"Raw service token or demodulized exception class name only, without an exception message, requested URL, host or secret. Known tokens include DownloadFailed, UnrecognizedDocument, InvalidDocument, IncompleteDocument, DocumentTooLarge, NoCurrentRate and rates_document_missing. Import failures can also report other sanitized exception class names; this is an open string, not a closed enum. Public error normalization applies only to the separate Cost Center sync envelope.","example":"NoCurrentRate"}}},"example":[{"currency":"USD","effective_from":null,"error":"NoCurrentRate"}]}}}},"examples":[{"ok":true,"synced_at":"2026-10-01T00:00:00Z","rate_card_import":{"ok":true,"imported":[{"currency":"USD","effective_from":"2026-10-01","rate_card_id":695}],"failed":[],"rate_card_id":695}},{"ok":false,"countries":0,"reason":"no_rates_parsed","legacy_rates":"no_rates_parsed","rate_card_import":{"ok":false,"imported":[{"currency":"USD","effective_from":"2026-10-01","rate_card_id":695}],"failed":[{"currency":"USD","effective_from":null,"error":"NoCurrentRate"}],"rate_card_id":695}},{"ok":true,"synced_at":"2026-10-02T12:00:00Z","rate_card_import":{"ok":false,"imported":[{"currency":"USD","effective_from":"2026-10-01","rate_card_id":695}],"failed":[{"currency":"BRL","effective_from":"2026-10-01","error":"DownloadFailed"}],"rate_card_id":695}},{"ok":false,"countries":0,"reason":"no_rates_parsed","legacy_rates":"no_rates_parsed","rate_card_import":{"ok":false,"imported":[],"failed":[{"currency":"USD","effective_from":"2026-10-01","error":"DownloadFailed"}],"rate_card_id":null}}]}}},"example":{"exchange_rate":{},"country":"BR","countries":["sample countrie"],"categories":[{}],"official_pricing_url":"https://business.whatsapp.com/products/platform-pricing","rates_updated_at":"2026-06-01","synced_at":"2026-01-15T10:30:00.000Z","sync":{"ok":false,"countries":0,"source":"https://business.whatsapp.com/products/platform-pricing","synced_at":null,"reason":"no_rates_parsed","status":200,"detail":"execution expired","legacy_rates":"no_rates_parsed","rate_card_import":{"ok":false,"rate_card_id":695,"imported":[{"currency":"USD","effective_from":"2026-10-01","rate_card_id":695}],"failed":[{"currency":"USD","effective_from":null,"error":"NoCurrentRate"}]}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"country":{"type":"string","example":"BR"}}},"example":{"country":"BR"}}}}}},"/api/v1/accounts/{account_id}/campaigns/audience_preview":{"post":{"tags":["Campaigns"],"operationId":"auto_post_api_v1_accounts_account_id_campaigns_audience_preview","summary":"Audience preview campaigns","description":"Performs the audience preview operation on the targeted campaign resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Resolved audience size (+ cost estimate when a category is supplied)","content":{"application/json":{"schema":{"type":"object","properties":{"count":{"type":"integer","description":"Contacts the campaign would send to: the campaign opt-out list (suppressed_count) and consent applied, recent 131026 contacts (undeliverable_count) and marketing opt-outs (marketing_opted_out_count) left out, contacts with only a business-scoped WhatsApp user ID included only when bsuid_only_enabled is true and never for an authentication category. The cost estimate prices this same set.","example":1280},"marketing_opted_out_count":{"type":"integer","description":"Contacts of the audience who stopped marketing messages from the inbox number. Always 0 unless inbox_id is given and category is marketing.","example":7},"bsuid_only_count":{"type":"integer","description":"Contacts without a phone number that have a current business-scoped WhatsApp user ID. Same filters as count (consent, marketing opt-out); always 0 for an authentication category, which Meta refuses for them. Counted in count and reached only when bsuid_only_enabled is true; otherwise informative, left out until the batch send is validated. Always 0 unless inbox_id is a WhatsApp Cloud inbox.","example":3},"bsuid_only_enabled":{"type":"boolean","description":"Whether campaigns from this inbox currently reach contacts that have only a business-scoped WhatsApp user ID (the release gate for the batch send to them). False while that send is held for validation, and for any inbox that is not WhatsApp Cloud.","example":false},"consent_excluded_count":{"type":"integer","description":"How many contacts this audience lost to an explicit LGPD refusal. Always 0 unless the account has governance_lgpd enabled with consent_required on; a contact who was never asked is never excluded.","example":12},"suppressed_count":{"type":"integer","description":"Contacts of the audience on the account campaign opt-out list (an opt-out keyword or quick-reply button, or an administrator). Never sendable, for any category and channel; counted before the LGPD consent gate, so a contact is reported here or in consent_excluded_count, never both.","example":4},"undeliverable_count":{"type":"integer","description":"Contacts of the audience whose last WhatsApp Cloud campaign send failed with 131026 (no WhatsApp, terms not accepted or outdated app) on their current phone, less than 90 days ago, with no activity since. Left out of count unless undeliverable_included is true. Always 0 unless inbox_id is a WhatsApp Cloud inbox.","example":9},"undeliverable_included":{"type":"boolean","description":"Whether the 131026 contacts in undeliverable_count are part of count (the campaign chose to include them).","example":false},"category":{"type":["string","null"],"enum":["marketing","utility","authentication",null],"description":"The template category that filtered and priced this preview, or null when none applies.","example":"marketing"},"category_source":{"type":"string","enum":["template","param","none"],"description":"`template` when the category was read from the chosen template synced on the inbox (how the dispatch decides it), `param` when the template is not synced there and the request category was used instead, `none` when no category applies.","example":"template"},"estimated_cost":{"type":["number","null"],"format":"float","description":"Present only when `category` given","example":80.0},"currency":{"type":["string","null"],"example":"BRL"},"billable":{"type":"boolean","description":"Present only when `category` given","example":true}}},"example":{"count":1280,"marketing_opted_out_count":7,"bsuid_only_count":3,"bsuid_only_enabled":false,"consent_excluded_count":12,"suppressed_count":4,"undeliverable_count":9,"undeliverable_included":false,"category":"marketing","category_source":"template","estimated_cost":80.0,"currency":"BRL","billable":true}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"audience":{"type":"array","description":"Audience sources, unioned (a contact matched by more than one entry is counted once). A single `All` entry dominates the rest. This is the SAME array the campaign body persists, so the previewed number is the number the saved campaign resolves to.","items":{"type":"object","description":"One audience source. `type` picks it; the remaining fields qualify it and are ignored where they do not apply. An unknown value for any qualifier falls back to its safe default rather than failing the request.","properties":{"type":{"type":"string","enum":["Label","Contact","Segment","Crm","Organization","All"],"example":"Label","description":"`Label` contacts carrying a label · `Contact` one hand-picked contact · `Segment` a saved segment · `Crm` the open deals of a pipeline · `Organization` everyone linked to one company · `All` the whole account."},"id":{"type":"integer","example":15,"description":"The record this entry points at: a label id, a contact id, a saved-segment (custom filter) id, a CRM pipeline id, or a company id. Omitted for `All`."},"source":{"type":"string","enum":["contact","conversation","both","organization"],"example":"conversation","description":"For `Label`, WHERE the label was applied — `contact` (the default, and what an entry with no `source` has always meant), `conversation` (the contacts behind the labeled conversations) or `both`. For `Segment`, WHICH saved-filter family the id belongs to — `contact`, `conversation` (a conversation folder) or `organization` (a company segment, resolved to its companies' people). Ignored for other types."},"conversation_status":{"type":"string","enum":["all","open","pending","snoozed","resolved"],"example":"open","description":"Narrows a conversation-sourced `Label` to conversations in one status. Defaults to `all`. Ignored when the label is read on contacts."},"stage_id":{"type":"integer","example":21,"description":"Narrows a `Crm` entry to a single stage of the pipeline. Omitted means every stage. Only OPEN deals ever enter the audience."}}}},"category":{"type":"string","enum":["marketing","utility","authentication"],"description":"Fallback template category, used only when template_name and template_language do not match a template synced on the inbox. A category (synced or this one) also returns the estimated BRL cost.","example":"marketing"},"template_name":{"type":"string","description":"Name of the chosen template. With template_language and inbox_id, the category is read from the template synced on that inbox, exactly as the dispatch decides it.","example":"black_friday_offer"},"template_language":{"type":"string","description":"Language code of the chosen template, as synced from Meta.","example":"pt_BR"},"provider":{"type":"string","description":"whatsapp_cloud enables Cloud pricing; otherwise Web","example":"whatsapp_cloud","enum":["whatsapp_web","whatsapp_cloud"]},"require_phone":{"type":"boolean","description":"Count only phone-bearing contacts (default true)","example":true},"inbox_id":{"type":"integer","example":42,"description":"The inbox the campaign sends from. With a `marketing` category, contacts who stopped marketing messages from this WhatsApp number are left out of `count` and of the cost estimate, exactly as the dispatch skips them, and reported in `marketing_opted_out_count`. Without it nothing is excluded here; the dispatch still skips those contacts."}}},"example":{"audience":[{"type":"Label","id":15,"source":"conversation","conversation_status":"open","stage_id":21}],"category":"marketing","template_name":"black_friday_offer","template_language":"pt_BR","provider":"whatsapp_cloud","require_phone":true,"inbox_id":42}}}}}},"/api/v1/accounts/{account_id}/campaigns/direct_uploads":{"post":{"tags":["Campaigns"],"operationId":"auto_post_api_v1_accounts_account_id_campaigns_direct_uploads","summary":"Reserve a storage blob for campaign media","description":"Creates the storage record for a file that the client will upload DIRECTLY to the storage service, before any campaign exists. The response carries the persisted blob plus the pre-signed `direct_upload` instructions: PUT the bytes to `direct_upload.url` echoing every header in `direct_upload.headers`, then submit `signed_id` as the campaign's media reference. Returns `200 OK` with a JSON body (the contract previously advertised an empty 204, which the action never produces).","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Blob reserved. Upload the bytes to the returned pre-signed URL.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer","description":"Storage blob identifier."},"key":{"type":"string","description":"Opaque storage key the bytes are written under."},"filename":{"type":"string","description":"Original file name supplied by the client."},"content_type":{"type":"string","description":"IANA media type declared by the client for the file."},"metadata":{"type":"object","additionalProperties":true,"description":"Free-form analysis metadata kept alongside the blob (analysis and identification flags, plus anything the client submitted). Keys vary by file type."},"service_name":{"type":"string","description":"Storage service the blob lives on, as configured for this installation."},"byte_size":{"type":"integer","description":"Declared size of the file in bytes."},"checksum":{"type":"string","description":"Base64-encoded MD5 the storage service validates the upload against."},"created_at":{"type":"string","format":"date-time","description":"When the blob record was reserved."},"signed_id":{"type":"string","description":"Signed reference to submit as the campaign's media identifier once the bytes are uploaded."},"direct_upload":{"type":"object","description":"Pre-signed instructions for the client-side upload.","properties":{"url":{"type":"string","description":"Pre-signed URL the client PUTs the file bytes to."},"headers":{"type":"object","additionalProperties":{"type":"string"},"description":"Headers that must be replayed verbatim on the upload request. The set depends on the storage service."}}}}},"example":{"id":4821,"key":"0f9c2d1a7b3e4f5a6c8d","filename":"promo-video.mp4","content_type":"video/mp4","metadata":{"identified":true},"service_name":"amazon","byte_size":8734512,"checksum":"kMHKk1KMxKrTGiUxRxJHVA==","created_at":"2026-07-27T12:04:31.000Z","signed_id":"eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBBcThDIn19","direct_upload":{"url":"https://storage.example.com/uploads/0f9c2d1a7b3e4f5a6c8d","headers":{"Content-Type":"video/mp4","Content-MD5":"kMHKk1KMxKrTGiUxRxJHVA=="}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"blob":{"type":"object","properties":{"filename":{"type":"string"},"byte_size":{"type":"string"},"checksum":{"type":"string"},"content_type":{"type":"string"},"metadata":{"type":"object","additionalProperties":true,"description":"Free-form metadata bag; the key set depends on the record and context."}}}},"required":["blob"]},"example":{"blob":{"filename":"sample filename","byte_size":"sample byte size","checksum":"sample checksum","content_type":"sample content type","metadata":{}}}}}}}},"/api/v1/accounts/{account_id}/campaigns":{"get":{"tags":["Campaigns"],"operationId":"auto_get_api_v1_accounts_account_id_campaigns","summary":"List campaigns","description":"Returns the list of campaigns visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"title":{"type":"string"},"description":{"type":"string"},"account_id":{"type":"integer"},"inbox":{"type":"object","properties":{"id":{"type":"integer"},"avatar_url":{"type":"string"},"channel_id":{"type":"integer"},"name":{"type":"string"},"channel_type":{"type":"string","enum":["Channel::Api","Channel::Email","Channel::FacebookPage","Channel::Instagram","Channel::Line","Channel::Sms","Channel::Telegram","Channel::Tiktok","Channel::TwilioSms","Channel::TwitterProfile","Channel::WebWidget","Channel::Whatsapp"],"description":"Inbox channel model class (STI type)."},"greeting_enabled":{"type":"boolean"},"greeting_message":{"type":"string"},"working_hours_enabled":{"type":"boolean"},"enable_email_collect":{"type":"string"},"csat_survey_enabled":{"type":"boolean"},"csat_config":{"type":"string"},"enable_auto_assignment":{"type":"string"},"auto_assignment_config":{"type":"string"},"out_of_office_message":{"type":"string"},"working_hours":{"type":"string"},"timezone":{"type":"string","description":"IANA timezone identifier (e.g. \"America/Sao_Paulo\", \"UTC\"). Rails timezone names are also accepted on input; an unrecognized value is ignored in favor of the next fallback.","example":"America/Sao_Paulo"},"callback_webhook_url":{"type":"string"},"allow_messages_after_resolved":{"type":"string"},"lock_to_single_conversation":{"type":"string"},"audio_transcription_enabled":{"type":"boolean"},"preserve_deleted_messages":{"type":"string"},"allow_message_deletion":{"type":"string"},"capture_view_once":{"type":"string"},"sender_name_type":{"type":"string","enum":["friendly","professional"]},"auto_resolve_config":{"type":"object","additionalProperties":true,"oneOf":[{"type":"object","maxProperties":0,"additionalProperties":true,"description":"Empty means inherit the account rule."},{"type":"object","additionalProperties":false,"required":["mode"],"properties":{"mode":{"type":"string","enum":["disabled"],"description":"Disable automatic resolution for this inbox."}},"description":"The disabled rule contains only its mode."},{"type":"object","additionalProperties":false,"required":["mode","after","message","label","allow_waiting"],"properties":{"mode":{"type":"string","enum":["custom"],"description":"Use this complete inbox rule."},"after":{"type":"integer","minimum":10,"maximum":1439856,"description":"Inactivity in minutes; required for custom mode."},"message":{"type":["string","null"],"maxLength":10000,"description":"Optional message; blank normalizes to null."},"label":{"type":["string","null"],"description":"An existing account label title, or null."},"allow_waiting":{"type":"boolean","description":"Whether waiting conversations are included."}},"description":"Complete normalized custom rule."}],"description":"Normalized JSON rule from valid model writes: empty, disabled, or complete custom configuration.","example":{"mode":"custom","after":60,"message":null,"label":null,"allow_waiting":false}},"outbound_agent_name_header_policy":{"type":"string"},"agent_bot_working_hours_mode":{"type":"string","enum":["always","inside_business_hours","outside_business_hours"]},"business_name":{"type":"string"},"responder_policy":{"type":"string"},"help_center":{"type":"object","properties":{"name":{"type":"string"},"slug":{"type":"string"}}},"tweets_enabled":{"type":"boolean"},"allowed_domains":{"type":"string"},"widget_color":{"type":"string"},"website_url":{"type":"string"},"hmac_mandatory":{"type":"string"},"welcome_title":{"type":"string"},"welcome_tagline":{"type":"string"},"web_widget_script":{"type":"string"},"website_token":{"type":"string"},"selected_feature_flags":{"type":"string"},"reply_time":{"type":"string","format":"date-time"},"hmac_token":{"type":"string"},"pre_chat_form_enabled":{"type":"boolean"},"pre_chat_form_options":{"type":"string"},"continuity_via_email":{"type":"string","format":"email"},"page_id":{"type":"integer"},"reauthorization_required":{"type":"string"},"instagram_id":{"type":"integer"},"messaging_service_sid":{"type":"string"},"phone_number":{"type":"string"},"medium":{"type":"string"},"bandwidth_callback_state":{"type":"string","enum":["active","reconnect_required","reconciling","reconciliation_required","encryption_required"]},"bandwidth_api_migration_state":{"type":"string","enum":["oauth2_configured","oauth2_required","configuration_required"]},"bandwidth_legacy_basic_deprecated":{"type":"boolean"},"content_templates":{"type":"string"},"auth_token":{"type":"string"},"account_sid":{"type":"string"},"api_key_sid":{"type":"string"},"twilio_credential_state":{"type":"string","enum":["ready","pending","failed","dead_letter","account_auth_token_required","reconciliation_required"],"description":"Durable Twilio credential lifecycle derived from Channel::TwilioSms. A reconciliation-required state is fail-closed until the provider outcome has been verified."},"api_key_configured":{"type":"boolean"},"email":{"type":"string","format":"email"},"auth_method":{"type":"string"},"forwarding_enabled":{"type":"boolean"},"forward_to_email":{"type":"string","format":"email"},"branded_email_layout":{"type":"string"},"imap_login":{"type":"string"},"imap_password":{"type":"string"},"imap_address":{"type":"string"},"imap_port":{"type":"string"},"imap_enabled":{"type":"boolean"},"imap_enable_ssl":{"type":"string"},"imap_authentication":{"type":"string"},"smtp_login":{"type":"string"},"smtp_password":{"type":"string"},"smtp_address":{"type":"string"},"smtp_port":{"type":"string"},"smtp_enabled":{"type":"boolean"},"smtp_domain":{"type":"string"},"smtp_enable_ssl_tls":{"type":"string"},"smtp_enable_starttls_auto":{"type":"string"},"smtp_openssl_verify_mode":{"type":"string","enum":["none","peer","client_once","fail_if_no_peer_cert"],"description":"OpenSSL peer-verification mode for the SMTP connection."},"smtp_authentication":{"type":"string"},"secret":{"type":"string"},"webhook_url":{"type":"string"},"inbox_identifier":{"type":"string"},"additional_attributes":{"type":"object","additionalProperties":true,"description":"Channel- and source-specific metadata for this record (e.g. browser info, referer, social profile identifiers). The key set depends on the originating channel."},"provider":{"type":"string","enum":["default","whatsapp_cloud","whatsapp_web","google","microsoft"],"description":"Messaging provider backing the inbox channel (whatsapp_web is the WazMeow gateway; email uses google/microsoft; default otherwise)."},"bot_name":{"type":"string"},"message_templates":{"type":"boolean"},"provider_config":{"type":"string"},"business_management_token_configured":{"type":"boolean"},"hybrid_pair":{"$ref":"#/components/schemas/inbox/properties/hybrid_pair"},"whatsapp_web_session_state":{"$ref":"#/components/schemas/inbox/properties/whatsapp_web_session_state"},"hybrid_hidden":{"type":"string"},"logical_inbox_id":{"type":"integer"},"whatsapp_pending_phone":{"type":"object","nullable":true,"description":"Spec 052 — set only when a WhatsApp phone-number rewrite was REFUSED because a non-sibling channel already holds the number, leaving the inbox on its `pending:` placeholder and inert. `null` in every normal case (including a routine, not-yet-scanned pairing).","additionalProperties":false,"properties":{"awaiting_pair":{"type":"boolean","description":"True while the inbox is still on its `pending:\u003cuuid\u003e` placeholder number."},"phone":{"type":"string","description":"The E.164 number the rewrite tried to claim."},"reason":{"type":"string","enum":["same_account_same_provider","other_account"],"description":"Why the rewrite was refused. `other_account` never carries any identifying detail about the other account."},"sibling_inbox_id":{"type":"integer","nullable":true,"description":"Colliding inbox in the SAME account; absent when the collision is cross-account."},"source":{"type":"string","enum":["pair_success","qr_pump"],"description":"Which path attempted the rewrite."},"at":{"type":"string","format":"date-time","description":"When the refusal was recorded."}}},"whatsapp_sibling_notice":{"type":"string"},"whatsapp_web_contact_request":{"type":"string","enum":["supported","unsupported","unknown"],"description":"WhatsApp Web inboxes only — whether this inbox's WazMeow gateway serves the request that asks a customer to share their phone number. `supported` and `unsupported` come from a no-effect probe of the gateway route, refreshed at most hourly and immediately when a real send finds the route missing; `unknown` means not probed yet or the gateway could not be reached. Only `supported` turns the feature on; with `unknown` the request is refused before any gateway call while the probe runs."},"voice_enabled":{"type":"boolean"},"inbound_calls_enabled":{"type":"boolean"},"voice_configured":{"type":"boolean"},"voice_call_webhook_url":{"type":"string"},"voice_status_webhook_url":{"type":"string"}}},"logical_inbox_id":{"type":"integer"},"whatsapp_transport":{"type":"string"},"sender":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":["integer","null"]},"account_user_id":{"type":["integer","null"]},"availability_status":{"type":"string","enum":["online","offline","busy"],"description":"Realtime availability. Contacts report online/offline (presence-based); agents/users additionally report busy (their configured availability)."},"auto_offline":{"type":"boolean"},"confirmed":{"type":"boolean"},"email":{"type":"string","format":"email"},"provider":{"type":"string","enum":["email","google_oauth2","saml"],"description":"Authentication provider the user signed up through."},"available_name":{"type":"string"},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"name":{"type":"string"},"role":{"type":"string","enum":["agent","administrator"]},"outbound_agent_name_header_policy":{"type":["string","null"]},"thumbnail":{"type":"string"},"custom_role_id":{"type":["integer","null"]},"access_role_id":{"type":["integer","null"]}}},"message":{"type":"string"},"template_params":{"type":"string"},"campaign_status":{"type":"string","enum":["active","completed","draft","scheduled","sending","paused","failed","processing"]},"enabled":{"type":"boolean"},"campaign_type":{"type":"string","enum":["ongoing","one_off"]},"scheduled_at":{"type":"integer"},"started_at":{"type":["integer","null"]},"completed_at":{"type":["integer","null"]},"audience":{"type":"array","description":"Audience sources for this campaign, unioned (a contact matched by more than one entry is targeted once). A single `All` entry dominates the rest. Contacts without a phone number are dropped on phone-dispatch channels, and a contact who refused data processing is dropped when the account requires consent.","items":{"type":"object","description":"One audience source. `type` picks it; the remaining fields qualify it and are ignored where they do not apply. An unknown value for any qualifier falls back to its safe default rather than failing the request.","properties":{"type":{"type":"string","enum":["Label","Contact","Segment","Crm","Organization","All"],"example":"Label","description":"`Label` contacts carrying a label · `Contact` one hand-picked contact · `Segment` a saved segment · `Crm` the open deals of a pipeline · `Organization` everyone linked to one company · `All` the whole account."},"id":{"type":"integer","example":15,"description":"The record this entry points at: a label id, a contact id, a saved-segment (custom filter) id, a CRM pipeline id, or a company id. Omitted for `All`."},"source":{"type":"string","enum":["contact","conversation","both","organization"],"example":"conversation","description":"For `Label`, WHERE the label was applied — `contact` (the default, and what an entry with no `source` has always meant), `conversation` (the contacts behind the labeled conversations) or `both`. For `Segment`, WHICH saved-filter family the id belongs to — `contact`, `conversation` (a conversation folder) or `organization` (a company segment, resolved to its companies' people). Ignored for other types."},"conversation_status":{"type":"string","enum":["all","open","pending","snoozed","resolved"],"example":"open","description":"Narrows a conversation-sourced `Label` to conversations in one status. Defaults to `all`. Ignored when the label is read on contacts."},"stage_id":{"type":"integer","example":21,"description":"Narrows a `Crm` entry to a single stage of the pipeline. Omitted means every stage. Only OPEN deals ever enter the audience."}}}},"trigger_rules":{"type":"string"},"trigger_only_during_business_hours":{"type":"string"},"message_variants":{"type":"string"},"send_settings":{"type":"object","additionalProperties":true,"description":"WhatsApp delivery settings: WhatsApp Web pacing, batching, variant randomization and spintax, plus `conversation`, the policy for the conversation the campaign creates. `dispatch_control` is written by the server only.","properties":{"conversation":{"$ref":"#/components/schemas/campaign_conversation_policy"}},"example":{"conversation":{"initial_status":"pending","on_reply":"open","assignment":"inbox_rules","labels":["black-friday"],"existing":"keep"}}},"recipient_stats":{"type":"string"},"estimated_cost":{"type":"string"},"actual_cost":{"type":"string"},"currency":{"type":"string"},"cost_basis":{"type":"string"},"media_attachments":{"type":"array","description":"Media attached to the campaign message.","items":{"type":"object","additionalProperties":true,"description":"An attachment: id, signed_id, filename, content_type (MIME) and byte_size."}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}},"example":[{"id":1,"title":"Sample title","description":"A short description.","account_id":1,"inbox":{"id":1,"avatar_url":"https://example.com/resource","channel_id":1,"name":"Sample Name","channel_type":"Channel::Api","greeting_enabled":true,"greeting_message":"sample greeting message","working_hours_enabled":true,"enable_email_collect":"agent@example.com","csat_survey_enabled":true,"csat_config":"sample csat config","enable_auto_assignment":"sample enable auto assignment","auto_assignment_config":"sample auto assignment config","out_of_office_message":"sample out of office message","working_hours":"sample working hours","timezone":"America/Sao_Paulo","callback_webhook_url":"https://example.com/resource","allow_messages_after_resolved":"sample allow messages after resolved","lock_to_single_conversation":"sample lock to single conversation","audio_transcription_enabled":true,"preserve_deleted_messages":"sample preserve deleted messages","allow_message_deletion":"sample allow message deletion","capture_view_once":"sample capture view once","sender_name_type":"friendly","auto_resolve_config":{"mode":"custom","after":60,"message":null,"label":null,"allow_waiting":false},"outbound_agent_name_header_policy":"sample outbound agent name header policy","agent_bot_working_hours_mode":"always","business_name":"sample business name","responder_policy":"sample responder policy","help_center":{"name":"Sample Name","slug":"sample-slug"},"tweets_enabled":true,"allowed_domains":"sample allowed domains","widget_color":"#1F93FF","website_url":"https://example.com/resource","hmac_mandatory":"sample hmac mandatory","welcome_title":"sample welcome title","welcome_tagline":"sample welcome tagline","web_widget_script":"sample web widget script","website_token":"sample-token","selected_feature_flags":"sample selected feature flags","reply_time":"2026-01-15T10:30:00.000Z","hmac_token":"sample-token","pre_chat_form_enabled":true,"pre_chat_form_options":"sample pre chat form options","continuity_via_email":"agent@example.com","page_id":1,"reauthorization_required":"sample reauthorization required","instagram_id":1,"messaging_service_sid":"sample messaging service sid","phone_number":"+5511999998888","medium":"sample medium","bandwidth_callback_state":"active","bandwidth_api_migration_state":"oauth2_configured","bandwidth_legacy_basic_deprecated":true,"content_templates":"sample content templates","auth_token":"sample-token","account_sid":"sample account sid","api_key_sid":"sample api key sid","twilio_credential_state":"ready","api_key_configured":true,"email":"agent@example.com","auth_method":"sample auth method","forwarding_enabled":true,"forward_to_email":"agent@example.com","branded_email_layout":"agent@example.com","imap_login":"sample imap login","imap_password":"sample imap password","imap_address":"sample imap address","imap_port":"sample imap port","imap_enabled":true,"imap_enable_ssl":"sample imap enable ssl","imap_authentication":"sample imap authentication","smtp_login":"sample smtp login","smtp_password":"sample smtp password","smtp_address":"sample smtp address","smtp_port":"sample smtp port","smtp_enabled":true,"smtp_domain":"sample smtp domain","smtp_enable_ssl_tls":"sample smtp enable ssl tls","smtp_enable_starttls_auto":"sample smtp enable starttls auto","smtp_openssl_verify_mode":"none","smtp_authentication":"sample smtp authentication","secret":"sample-token","webhook_url":"https://example.com/resource","inbox_identifier":"sample inbox identifier","additional_attributes":{},"provider":"default","bot_name":"sample bot name","message_templates":true,"provider_config":"sample provider config","business_management_token_configured":true,"hybrid_pair":{"paired":true,"id":4,"role":"cloud","sibling_inbox_id":18,"canonical_phone":"+5521900000000","primary":"cloud","inbound_authority":"cloud","unified_inbox":true,"unified_state":{"state":"complete","scanned":42,"frozen":40,"reconciled_count":2,"completed_at":"2026-10-03T12:00:00.000Z","blocked_conversations":[]},"routing":{"outbound_default":"cloud","out_of_window":"web","fallback":true,"manual_override":true,"weighted":{"mode":"weighted","web_percent":30,"version":2}},"web_channel_id":12,"web_inbox_id":18,"calling_provider":"whatsapp_web","web_voice_enabled":true,"web_inbound_calls_enabled":true,"web_call_config_sync":{"state":"pending","checked_at":"2026-10-03T12:00:00.000Z"},"web_video_calls_enabled":false,"web_group_calls_enabled":false,"web_reauthorization_required":false,"web_session_state":{"state":"connected","fresh":true,"observed_at":"2026-10-03T12:00:00.000Z","disconnected_since":null},"web_allow_message_deletion":true},"whatsapp_web_session_state":{"state":"connected","fresh":true,"observed_at":"2026-01-15T10:30:00.000Z","disconnected_since":null},"hybrid_hidden":"sample hybrid hidden","logical_inbox_id":1,"whatsapp_pending_phone":{"awaiting_pair":true,"phone":"+5511999998888","reason":"same_account_same_provider","sibling_inbox_id":1,"source":"pair_success","at":"2026-01-15T10:30:00.000Z"},"whatsapp_sibling_notice":"sample whatsapp sibling notice","whatsapp_web_contact_request":"supported","voice_enabled":true,"inbound_calls_enabled":true,"voice_configured":true,"voice_call_webhook_url":"https://example.com/resource","voice_status_webhook_url":"https://example.com/resource"},"logical_inbox_id":1,"whatsapp_transport":"sample whatsapp transport","sender":{"id":1,"account_id":1,"account_user_id":1,"availability_status":"online","auto_offline":true,"confirmed":true,"email":"agent@example.com","provider":"email","available_name":"sample available name","custom_attributes":{},"name":"Sample Name","role":"agent","outbound_agent_name_header_policy":"sample outbound agent name header policy","thumbnail":"sample thumbnail","custom_role_id":1,"access_role_id":1},"message":"Sample message text.","template_params":"sample template params","campaign_status":"active","enabled":true,"campaign_type":"ongoing","scheduled_at":1,"started_at":1,"completed_at":1,"audience":[{"type":"Label","id":15,"source":"conversation","conversation_status":"open","stage_id":21}],"trigger_rules":"sample trigger rules","trigger_only_during_business_hours":"sample trigger only during business hours","message_variants":"sample message variants","send_settings":{"conversation":{"initial_status":"pending","on_reply":"open","assignment":"inbox_rules","labels":["black-friday"],"existing":"keep"}},"recipient_stats":"sample recipient stats","estimated_cost":"sample estimated cost","actual_cost":"sample actual cost","currency":"BRL","cost_basis":"sample cost basis","media_attachments":[{}],"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}]}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."}]},"post":{"tags":["Campaigns"],"operationId":"auto_post_api_v1_accounts_account_id_campaigns","summary":"Create a campaign","description":"Creates an account campaign. Optional media and per-variant attachments are Active Storage signed identifiers minted for this same account; a foreign, malformed, or legacy unattached blob is rejected atomically before the campaign is saved.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Campaign created successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/campaign"},"example":{"id":31,"title":"Renewal reminder","description":"Reminds customers whose renewal is due this week.","account_id":1,"inbox":{"navigation_only":true,"id":1,"name":"Sample Name","website_url":"https://example.com/resource","channel_type":"Channel::Api","avatar_url":"https://example.com/resource","widget_color":"#1F93FF","website_token":"sample-token","enable_auto_assignment":true,"web_widget_script":"sample web widget script","welcome_title":"sample welcome title","welcome_tagline":"sample welcome tagline","greeting_enabled":true,"greeting_message":"sample greeting message","channel_id":1,"working_hours_enabled":true,"enable_email_collect":true,"csat_survey_enabled":true,"auto_assignment_config":{},"out_of_office_message":"sample out of office message","working_hours":[{"day_of_week":12.5,"closed_all_day":true,"open_hour":12.5,"open_minutes":12.5,"close_hour":12.5,"close_minutes":12.5,"open_all_day":true}],"timezone":"America/Sao_Paulo","callback_webhook_url":"https://example.com/resource","allow_messages_after_resolved":true,"lock_to_single_conversation":true,"sender_name_type":"friendly","auto_resolve_config":{"mode":"custom","after":30,"message":"We are closing this conversation due to inactivity.","label":"auto-resolved","allow_waiting":false},"outbound_agent_name_header_policy":"inherit","business_name":"sample business name","branded_email_layout":"agent@example.com","responder_policy":{"mode":"agent_bot","conflict":true},"hmac_mandatory":true,"selected_feature_flags":["sample selected feature flag"],"reply_time":"2026-01-15T10:30:00.000Z","messaging_service_sid":"sample messaging service sid","phone_number":"+5511999998888","bandwidth_callback_state":"active","bandwidth_api_migration_state":"oauth2_configured","medium":"sample medium","provider":"default","whatsapp_web_session_state":{"state":"connected","fresh":true,"observed_at":"2026-01-15T10:30:00.000Z","disconnected_since":null},"hybrid_pair":{"paired":true,"id":4,"role":"cloud","sibling_inbox_id":18,"canonical_phone":"+5521900000000","primary":"cloud","inbound_authority":"cloud","unified_inbox":true,"unified_state":{"state":"complete","scanned":42,"frozen":40,"reconciled_count":2,"completed_at":"2026-10-03T12:00:00.000Z","blocked_conversations":[]},"routing":{"outbound_default":"cloud","out_of_window":"web","fallback":true,"manual_override":true,"weighted":{"mode":"weighted","web_percent":30,"version":2}},"web_channel_id":12,"web_inbox_id":18,"calling_provider":"whatsapp_web","web_voice_enabled":true,"web_inbound_calls_enabled":true,"web_call_config_sync":{"state":"pending","checked_at":"2026-10-03T12:00:00.000Z"},"web_video_calls_enabled":false,"web_group_calls_enabled":false,"web_reauthorization_required":false,"web_session_state":{"state":"connected","fresh":true,"observed_at":"2026-10-03T12:00:00.000Z","disconnected_since":null},"web_allow_message_deletion":true}},"logical_inbox_id":15,"whatsapp_transport":"web","sender":{"id":1,"account_id":1,"account_user_id":1,"availability_status":"online","auto_offline":true,"confirmed":true,"email":"agent@example.com","available_name":"sample available name","name":"Sample Name","role":"agent","outbound_agent_name_header_policy":"inherit","thumbnail":"sample thumbnail","custom_role_id":1},"message":"Hello {{contact.name}}, your renewal is due soon.","template_params":{},"campaign_status":"scheduled","enabled":true,"campaign_type":"one_off","scheduled_at":1786791600,"audience":[{"type":"Label","id":15,"source":"conversation","conversation_status":"open","stage_id":21}],"trigger_rules":{},"trigger_only_during_business_hours":false,"message_variants":[{"body":"Hello {{contact.name}}.","content_type":"text","content_attributes":{},"attachment_blob_ids":[]}],"send_settings":{"conversation":{"initial_status":"pending","on_reply":"open","assignment":"inbox_rules","labels":["black-friday"],"existing":"keep"}},"recipient_stats":{"pending":20,"processing":2,"sent":10,"delivered":8,"read":5,"replied":1,"failed":0,"skipped":0},"estimated_cost":"12.50","actual_cost":"10.75","currency":"BRL","media_attachments":[{"id":91,"signed_id":"eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBBQT09In19","filename":"renewal.pdf","content_type":"application/pdf","byte_size":48192}],"created_at":"2026-08-15T10:00:00.000Z","updated_at":"2026-08-15T10:05:00.000Z"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"422":{"description":"One of the submitted media signed IDs is invalid for this account (`error`), or the campaign failed validation (`message` + `attributes`) — including an invalid `send_settings.conversation` policy: a value outside its closed sets, an agent who cannot receive the inbox's conversations, a team or label that does not exist in the account, more than 10 labels, or `existing: apply` with `initial_status: resolved`.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["invalid_campaign_media"],"description":"Present when a media signed ID is invalid.","example":"invalid_campaign_media"},"message":{"type":"string","description":"Present on a validation failure — the readable reasons, in the account locale.","example":"These labels do not exist in this account: vip."},"attributes":{"type":"array","description":"Present on a validation failure — the attributes that failed (`base` for the conversation policy).","items":{"type":"string"},"example":["base"]}}},"example":{"error":"invalid_campaign_media","message":"These labels do not exist in this account: vip.","attributes":["base"]}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/campaign_create_update_payload"},"example":{"whatsapp_transport":"web","campaign":{"title":"Renewal reminder","message":"Hello {{contact.name}}, your renewal is due this week.","inbox_id":15,"whatsapp_transport":"web","campaign_status":"scheduled","audience":[{"type":"Label","id":15,"source":"conversation","conversation_status":"open","stage_id":21}],"media_blob_ids":[],"message_variants":[{"body":"Hello {{contact.name}}.","content_type":"text","content_attributes":{},"attachment_blob_ids":[]}],"description":"Reminds customers whose renewal is due this week.","enabled":true,"trigger_only_during_business_hours":false,"sender_id":7,"scheduled_at":1786791600,"trigger_rules":{},"template_params":{},"send_settings":{"conversation":{"initial_status":"pending","on_reply":"open","assignment":"inbox_rules","labels":["black-friday"],"existing":"keep"}}}}}}}}},"/api/v1/accounts/{account_id}/campaigns/{id}":{"get":{"tags":["Campaigns"],"operationId":"auto_get_api_v1_accounts_account_id_campaigns_id","summary":"Get campaigns","description":"Returns the campaign identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"title":{"type":"string"},"description":{"type":"string"},"account_id":{"type":"integer"},"inbox":{"type":"object","properties":{"id":{"type":"integer"},"avatar_url":{"type":"string"},"channel_id":{"type":"integer"},"name":{"type":"string"},"channel_type":{"type":"string","enum":["Channel::Api","Channel::Email","Channel::FacebookPage","Channel::Instagram","Channel::Line","Channel::Sms","Channel::Telegram","Channel::Tiktok","Channel::TwilioSms","Channel::TwitterProfile","Channel::WebWidget","Channel::Whatsapp"],"description":"Inbox channel model class (STI type)."},"greeting_enabled":{"type":"boolean"},"greeting_message":{"type":"string"},"working_hours_enabled":{"type":"boolean"},"enable_email_collect":{"type":"string"},"csat_survey_enabled":{"type":"boolean"},"csat_config":{"type":"string"},"enable_auto_assignment":{"type":"string"},"auto_assignment_config":{"type":"string"},"out_of_office_message":{"type":"string"},"working_hours":{"type":"string"},"timezone":{"type":"string","description":"IANA timezone identifier (e.g. \"America/Sao_Paulo\", \"UTC\"). Rails timezone names are also accepted on input; an unrecognized value is ignored in favor of the next fallback.","example":"America/Sao_Paulo"},"callback_webhook_url":{"type":"string"},"allow_messages_after_resolved":{"type":"string"},"lock_to_single_conversation":{"type":"string"},"audio_transcription_enabled":{"type":"boolean"},"preserve_deleted_messages":{"type":"string"},"allow_message_deletion":{"type":"string"},"capture_view_once":{"type":"string"},"sender_name_type":{"type":"string","enum":["friendly","professional"]},"auto_resolve_config":{"type":"object","additionalProperties":true,"oneOf":[{"type":"object","maxProperties":0,"additionalProperties":true,"description":"Empty means inherit the account rule."},{"type":"object","additionalProperties":false,"required":["mode"],"properties":{"mode":{"type":"string","enum":["disabled"],"description":"Disable automatic resolution for this inbox."}},"description":"The disabled rule contains only its mode."},{"type":"object","additionalProperties":false,"required":["mode","after","message","label","allow_waiting"],"properties":{"mode":{"type":"string","enum":["custom"],"description":"Use this complete inbox rule."},"after":{"type":"integer","minimum":10,"maximum":1439856,"description":"Inactivity in minutes; required for custom mode."},"message":{"type":["string","null"],"maxLength":10000,"description":"Optional message; blank normalizes to null."},"label":{"type":["string","null"],"description":"An existing account label title, or null."},"allow_waiting":{"type":"boolean","description":"Whether waiting conversations are included."}},"description":"Complete normalized custom rule."}],"description":"Normalized JSON rule from valid model writes: empty, disabled, or complete custom configuration.","example":{"mode":"custom","after":60,"message":null,"label":null,"allow_waiting":false}},"outbound_agent_name_header_policy":{"type":"string"},"agent_bot_working_hours_mode":{"type":"string","enum":["always","inside_business_hours","outside_business_hours"]},"business_name":{"type":"string"},"responder_policy":{"type":"string"},"help_center":{"type":"object","properties":{"name":{"type":"string"},"slug":{"type":"string"}}},"tweets_enabled":{"type":"boolean"},"allowed_domains":{"type":"string"},"widget_color":{"type":"string"},"website_url":{"type":"string"},"hmac_mandatory":{"type":"string"},"welcome_title":{"type":"string"},"welcome_tagline":{"type":"string"},"web_widget_script":{"type":"string"},"website_token":{"type":"string"},"selected_feature_flags":{"type":"string"},"reply_time":{"type":"string","format":"date-time"},"hmac_token":{"type":"string"},"pre_chat_form_enabled":{"type":"boolean"},"pre_chat_form_options":{"type":"string"},"continuity_via_email":{"type":"string","format":"email"},"page_id":{"type":"integer"},"reauthorization_required":{"type":"string"},"instagram_id":{"type":"integer"},"messaging_service_sid":{"type":"string"},"phone_number":{"type":"string"},"medium":{"type":"string"},"bandwidth_callback_state":{"type":"string","enum":["active","reconnect_required","reconciling","reconciliation_required","encryption_required"]},"bandwidth_api_migration_state":{"type":"string","enum":["oauth2_configured","oauth2_required","configuration_required"]},"bandwidth_legacy_basic_deprecated":{"type":"boolean"},"content_templates":{"type":"string"},"auth_token":{"type":"string"},"account_sid":{"type":"string"},"api_key_sid":{"type":"string"},"twilio_credential_state":{"type":"string","enum":["ready","pending","failed","dead_letter","account_auth_token_required","reconciliation_required"],"description":"Durable Twilio credential lifecycle derived from Channel::TwilioSms. A reconciliation-required state is fail-closed until the provider outcome has been verified."},"api_key_configured":{"type":"boolean"},"email":{"type":"string","format":"email"},"auth_method":{"type":"string"},"forwarding_enabled":{"type":"boolean"},"forward_to_email":{"type":"string","format":"email"},"branded_email_layout":{"type":"string"},"imap_login":{"type":"string"},"imap_password":{"type":"string"},"imap_address":{"type":"string"},"imap_port":{"type":"string"},"imap_enabled":{"type":"boolean"},"imap_enable_ssl":{"type":"string"},"imap_authentication":{"type":"string"},"smtp_login":{"type":"string"},"smtp_password":{"type":"string"},"smtp_address":{"type":"string"},"smtp_port":{"type":"string"},"smtp_enabled":{"type":"boolean"},"smtp_domain":{"type":"string"},"smtp_enable_ssl_tls":{"type":"string"},"smtp_enable_starttls_auto":{"type":"string"},"smtp_openssl_verify_mode":{"type":"string","enum":["none","peer","client_once","fail_if_no_peer_cert"],"description":"OpenSSL peer-verification mode for the SMTP connection."},"smtp_authentication":{"type":"string"},"secret":{"type":"string"},"webhook_url":{"type":"string"},"inbox_identifier":{"type":"string"},"additional_attributes":{"type":"object","additionalProperties":true,"description":"Channel- and source-specific metadata for this record (e.g. browser info, referer, social profile identifiers). The key set depends on the originating channel."},"provider":{"type":"string","enum":["default","whatsapp_cloud","whatsapp_web","google","microsoft"],"description":"Messaging provider backing the inbox channel (whatsapp_web is the WazMeow gateway; email uses google/microsoft; default otherwise)."},"bot_name":{"type":"string"},"message_templates":{"type":"boolean"},"provider_config":{"type":"string"},"business_management_token_configured":{"type":"boolean"},"hybrid_pair":{"$ref":"#/components/schemas/inbox/properties/hybrid_pair"},"whatsapp_web_session_state":{"$ref":"#/components/schemas/inbox/properties/whatsapp_web_session_state"},"hybrid_hidden":{"type":"string"},"logical_inbox_id":{"type":"integer"},"whatsapp_pending_phone":{"type":"object","nullable":true,"description":"Spec 052 — set only when a WhatsApp phone-number rewrite was REFUSED because a non-sibling channel already holds the number, leaving the inbox on its `pending:` placeholder and inert. `null` in every normal case (including a routine, not-yet-scanned pairing).","additionalProperties":false,"properties":{"awaiting_pair":{"type":"boolean","description":"True while the inbox is still on its `pending:\u003cuuid\u003e` placeholder number."},"phone":{"type":"string","description":"The E.164 number the rewrite tried to claim."},"reason":{"type":"string","enum":["same_account_same_provider","other_account"],"description":"Why the rewrite was refused. `other_account` never carries any identifying detail about the other account."},"sibling_inbox_id":{"type":"integer","nullable":true,"description":"Colliding inbox in the SAME account; absent when the collision is cross-account."},"source":{"type":"string","enum":["pair_success","qr_pump"],"description":"Which path attempted the rewrite."},"at":{"type":"string","format":"date-time","description":"When the refusal was recorded."}}},"whatsapp_sibling_notice":{"type":"string"},"whatsapp_web_contact_request":{"type":"string","enum":["supported","unsupported","unknown"],"description":"WhatsApp Web inboxes only — whether this inbox's WazMeow gateway serves the request that asks a customer to share their phone number. `supported` and `unsupported` come from a no-effect probe of the gateway route, refreshed at most hourly and immediately when a real send finds the route missing; `unknown` means not probed yet or the gateway could not be reached. Only `supported` turns the feature on; with `unknown` the request is refused before any gateway call while the probe runs."},"voice_enabled":{"type":"boolean"},"inbound_calls_enabled":{"type":"boolean"},"voice_configured":{"type":"boolean"},"voice_call_webhook_url":{"type":"string"},"voice_status_webhook_url":{"type":"string"}}},"logical_inbox_id":{"type":"integer"},"whatsapp_transport":{"type":"string"},"sender":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":["integer","null"]},"account_user_id":{"type":["integer","null"]},"availability_status":{"type":"string","enum":["online","offline","busy"],"description":"Realtime availability. Contacts report online/offline (presence-based); agents/users additionally report busy (their configured availability)."},"auto_offline":{"type":"boolean"},"confirmed":{"type":"boolean"},"email":{"type":"string","format":"email"},"provider":{"type":"string","enum":["email","google_oauth2","saml"],"description":"Authentication provider the user signed up through."},"available_name":{"type":"string"},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"name":{"type":"string"},"role":{"type":"string","enum":["agent","administrator"]},"outbound_agent_name_header_policy":{"type":["string","null"]},"thumbnail":{"type":"string"},"custom_role_id":{"type":["integer","null"]},"access_role_id":{"type":["integer","null"]}}},"message":{"type":"string"},"template_params":{"type":"string"},"campaign_status":{"type":"string","enum":["active","completed","draft","scheduled","sending","paused","failed","processing"]},"enabled":{"type":"boolean"},"campaign_type":{"type":"string","enum":["ongoing","one_off"]},"scheduled_at":{"type":"integer"},"started_at":{"type":["integer","null"]},"completed_at":{"type":["integer","null"]},"audience":{"type":"array","description":"Audience sources for this campaign, unioned (a contact matched by more than one entry is targeted once). A single `All` entry dominates the rest. Contacts without a phone number are dropped on phone-dispatch channels, and a contact who refused data processing is dropped when the account requires consent.","items":{"type":"object","description":"One audience source. `type` picks it; the remaining fields qualify it and are ignored where they do not apply. An unknown value for any qualifier falls back to its safe default rather than failing the request.","properties":{"type":{"type":"string","enum":["Label","Contact","Segment","Crm","Organization","All"],"example":"Label","description":"`Label` contacts carrying a label · `Contact` one hand-picked contact · `Segment` a saved segment · `Crm` the open deals of a pipeline · `Organization` everyone linked to one company · `All` the whole account."},"id":{"type":"integer","example":15,"description":"The record this entry points at: a label id, a contact id, a saved-segment (custom filter) id, a CRM pipeline id, or a company id. Omitted for `All`."},"source":{"type":"string","enum":["contact","conversation","both","organization"],"example":"conversation","description":"For `Label`, WHERE the label was applied — `contact` (the default, and what an entry with no `source` has always meant), `conversation` (the contacts behind the labeled conversations) or `both`. For `Segment`, WHICH saved-filter family the id belongs to — `contact`, `conversation` (a conversation folder) or `organization` (a company segment, resolved to its companies' people). Ignored for other types."},"conversation_status":{"type":"string","enum":["all","open","pending","snoozed","resolved"],"example":"open","description":"Narrows a conversation-sourced `Label` to conversations in one status. Defaults to `all`. Ignored when the label is read on contacts."},"stage_id":{"type":"integer","example":21,"description":"Narrows a `Crm` entry to a single stage of the pipeline. Omitted means every stage. Only OPEN deals ever enter the audience."}}}},"trigger_rules":{"type":"string"},"trigger_only_during_business_hours":{"type":"string"},"message_variants":{"type":"string"},"send_settings":{"type":"object","additionalProperties":true,"description":"WhatsApp delivery settings: WhatsApp Web pacing, batching, variant randomization and spintax, plus `conversation`, the policy for the conversation the campaign creates. `dispatch_control` is written by the server only.","properties":{"conversation":{"$ref":"#/components/schemas/campaign_conversation_policy"}},"example":{"conversation":{"initial_status":"pending","on_reply":"open","assignment":"inbox_rules","labels":["black-friday"],"existing":"keep"}}},"recipient_stats":{"type":"string"},"estimated_cost":{"type":"string"},"actual_cost":{"type":"string"},"currency":{"type":"string"},"cost_basis":{"type":"string"},"media_attachments":{"type":"array","description":"Media attached to the campaign message.","items":{"type":"object","additionalProperties":true,"description":"An attachment: id, signed_id, filename, content_type (MIME) and byte_size."}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"recipient_timing":{"type":"string"},"conversations_opened_by_reply":{"type":["integer","null"],"minimum":0,"description":"Conversations this campaign created pending (`send_settings.conversation`) that the customer's first reply opened. Counted among recipients in `replied`. Null when the campaign has no conversation policy that waits for the reply (feature off, non-WhatsApp inbox, or a policy that does not start pending and open on reply).","example":42},"cost_breakdown":{"type":["object","null"],"description":"Billable, awaiting delivery, free and not-billed messages of the campaign plus the price frozen at dispatch, read from the WhatsApp cost ledger. Null without the `whatsapp_cost_center` feature or for a campaign whose inbox is not WhatsApp.","properties":{"currency":{"type":["string","null"],"description":"Currency of the amounts — the single native billing currency, or the display currency when the campaign mixes currencies."},"display_currency":{"type":["string","null"],"description":"The campaign currency the cards render in."},"fx":{"type":["object","null"],"description":"Rate from `currency` to `display_currency`, when they differ and a rate is available.","properties":{"rate":{"type":"number"},"source":{"type":"string","enum":["live"]},"as_of":{"type":["string","null"],"format":"date-time"}}},"partner_billed":{"type":"boolean","description":"True when any message was sent from a partner-billed number (Meta reports no cost for it)."},"amount_source":{"type":["string","null"],"enum":["list_rate","tier_estimated","override","meta_reported","mixed",null],"description":"How the billable messages were priced; `meta_reported` is the cost Meta reported with a max-price marketing delivery, `mixed` when more than one source was used."},"billable":{"type":"object","properties":{"count":{"type":"integer"},"amount":{"type":["number","null"]}}},"pending_delivery":{"type":"object","description":"Sent messages still awaiting their final status; the provisional amount never counts as cost.","properties":{"count":{"type":"integer"},"amount":{"type":["number","null"]}}},"free":{"type":"object","properties":{"count":{"type":"integer"}}},"not_billed":{"type":"object","description":"Recipients whose send failed or was skipped, and messages without a final status after 30 days.","properties":{"failed":{"type":"integer"},"skipped":{"type":"integer"},"expired":{"type":"integer"}}},"frozen_estimate":{"type":"object","description":"The price frozen at dispatch over the recipients that were actually sent.","properties":{"amount":{"type":["number","null"]},"currency":{"type":["string","null"]},"basis":{"type":["string","null"],"enum":["frozen",null]}}}}},"dispatch_progress":{"type":["object","null"],"description":"WhatsApp Cloud campaigns only. Audience progress of the current dispatch run. Null until the first run records the size of the audience it resolved.","properties":{"audience_total":{"type":"integer","description":"Contacts the current run resolved when it started."},"processed":{"type":"integer","description":"Recipients that already left `pending` (sent, failed, skipped or being processed)."},"remaining":{"type":"integer","description":"Contacts still waiting — rows in `pending`, rows claimed by a worker that never built the message, and contacts the run has not reached yet (which have no recipient row). A resume continues with them. A cancellation guarantees none of them receives the campaign: existing rows become `skipped`, contacts without a row are simply never sent to and get no row."}},"example":{"audience_total":15570,"processed":3601,"remaining":11969}},"resume_block_reason":{"type":"string","enum":["template_not_approved","template_status_pending"]},"bsuid_only_recipients_count":{"type":"integer","minimum":0,"description":"WhatsApp Cloud campaigns only. Recipients whose contact has no phone number and that were not skipped: the dispatch addresses them through the contact's business-scoped WhatsApp user ID. A phoneless contact without a current ID is skipped (`blank_phone`) and therefore not counted.","example":12},"dispatch_messages_per_second":{"type":"integer","minimum":1,"description":"WhatsApp Cloud campaigns only. Messages per second the campaign sends at: the number's throughput limit at Meta minus 5 — 75 on a standard number (limit 80), 995 on a number Meta upgraded to 1,000, and 15 on a number shared with the WhatsApp Business app (Meta fixes it at 20). A level Meta has not confirmed in the last 24 hours, or an unknown one, uses the standard pace. An operator override can only lower it.","example":75}}},"example":{"id":1,"title":"Sample title","description":"A short description.","account_id":1,"inbox":{"id":1,"avatar_url":"https://example.com/resource","channel_id":1,"name":"Sample Name","channel_type":"Channel::Api","greeting_enabled":true,"greeting_message":"sample greeting message","working_hours_enabled":true,"enable_email_collect":"agent@example.com","csat_survey_enabled":true,"csat_config":"sample csat config","enable_auto_assignment":"sample enable auto assignment","auto_assignment_config":"sample auto assignment config","out_of_office_message":"sample out of office message","working_hours":"sample working hours","timezone":"America/Sao_Paulo","callback_webhook_url":"https://example.com/resource","allow_messages_after_resolved":"sample allow messages after resolved","lock_to_single_conversation":"sample lock to single conversation","audio_transcription_enabled":true,"preserve_deleted_messages":"sample preserve deleted messages","allow_message_deletion":"sample allow message deletion","capture_view_once":"sample capture view once","sender_name_type":"friendly","auto_resolve_config":{"mode":"custom","after":60,"message":null,"label":null,"allow_waiting":false},"outbound_agent_name_header_policy":"sample outbound agent name header policy","agent_bot_working_hours_mode":"always","business_name":"sample business name","responder_policy":"sample responder policy","help_center":{"name":"Sample Name","slug":"sample-slug"},"tweets_enabled":true,"allowed_domains":"sample allowed domains","widget_color":"#1F93FF","website_url":"https://example.com/resource","hmac_mandatory":"sample hmac mandatory","welcome_title":"sample welcome title","welcome_tagline":"sample welcome tagline","web_widget_script":"sample web widget script","website_token":"sample-token","selected_feature_flags":"sample selected feature flags","reply_time":"2026-01-15T10:30:00.000Z","hmac_token":"sample-token","pre_chat_form_enabled":true,"pre_chat_form_options":"sample pre chat form options","continuity_via_email":"agent@example.com","page_id":1,"reauthorization_required":"sample reauthorization required","instagram_id":1,"messaging_service_sid":"sample messaging service sid","phone_number":"+5511999998888","medium":"sample medium","bandwidth_callback_state":"active","bandwidth_api_migration_state":"oauth2_configured","bandwidth_legacy_basic_deprecated":true,"content_templates":"sample content templates","auth_token":"sample-token","account_sid":"sample account sid","api_key_sid":"sample api key sid","twilio_credential_state":"ready","api_key_configured":true,"email":"agent@example.com","auth_method":"sample auth method","forwarding_enabled":true,"forward_to_email":"agent@example.com","branded_email_layout":"agent@example.com","imap_login":"sample imap login","imap_password":"sample imap password","imap_address":"sample imap address","imap_port":"sample imap port","imap_enabled":true,"imap_enable_ssl":"sample imap enable ssl","imap_authentication":"sample imap authentication","smtp_login":"sample smtp login","smtp_password":"sample smtp password","smtp_address":"sample smtp address","smtp_port":"sample smtp port","smtp_enabled":true,"smtp_domain":"sample smtp domain","smtp_enable_ssl_tls":"sample smtp enable ssl tls","smtp_enable_starttls_auto":"sample smtp enable starttls auto","smtp_openssl_verify_mode":"none","smtp_authentication":"sample smtp authentication","secret":"sample-token","webhook_url":"https://example.com/resource","inbox_identifier":"sample inbox identifier","additional_attributes":{},"provider":"default","bot_name":"sample bot name","message_templates":true,"provider_config":"sample provider config","business_management_token_configured":true,"hybrid_pair":{"paired":true,"id":4,"role":"cloud","sibling_inbox_id":18,"canonical_phone":"+5521900000000","primary":"cloud","inbound_authority":"cloud","unified_inbox":true,"unified_state":{"state":"complete","scanned":42,"frozen":40,"reconciled_count":2,"completed_at":"2026-10-03T12:00:00.000Z","blocked_conversations":[]},"routing":{"outbound_default":"cloud","out_of_window":"web","fallback":true,"manual_override":true,"weighted":{"mode":"weighted","web_percent":30,"version":2}},"web_channel_id":12,"web_inbox_id":18,"calling_provider":"whatsapp_web","web_voice_enabled":true,"web_inbound_calls_enabled":true,"web_call_config_sync":{"state":"pending","checked_at":"2026-10-03T12:00:00.000Z"},"web_video_calls_enabled":false,"web_group_calls_enabled":false,"web_reauthorization_required":false,"web_session_state":{"state":"connected","fresh":true,"observed_at":"2026-10-03T12:00:00.000Z","disconnected_since":null},"web_allow_message_deletion":true},"whatsapp_web_session_state":{"state":"connected","fresh":true,"observed_at":"2026-01-15T10:30:00.000Z","disconnected_since":null},"hybrid_hidden":"sample hybrid hidden","logical_inbox_id":1,"whatsapp_pending_phone":{"awaiting_pair":true,"phone":"+5511999998888","reason":"same_account_same_provider","sibling_inbox_id":1,"source":"pair_success","at":"2026-01-15T10:30:00.000Z"},"whatsapp_sibling_notice":"sample whatsapp sibling notice","whatsapp_web_contact_request":"supported","voice_enabled":true,"inbound_calls_enabled":true,"voice_configured":true,"voice_call_webhook_url":"https://example.com/resource","voice_status_webhook_url":"https://example.com/resource"},"logical_inbox_id":1,"whatsapp_transport":"sample whatsapp transport","sender":{"id":1,"account_id":1,"account_user_id":1,"availability_status":"online","auto_offline":true,"confirmed":true,"email":"agent@example.com","provider":"email","available_name":"sample available name","custom_attributes":{},"name":"Sample Name","role":"agent","outbound_agent_name_header_policy":"sample outbound agent name header policy","thumbnail":"sample thumbnail","custom_role_id":1,"access_role_id":1},"message":"Sample message text.","template_params":"sample template params","campaign_status":"active","enabled":true,"campaign_type":"ongoing","scheduled_at":1,"started_at":1,"completed_at":1,"audience":[{"type":"Label","id":15,"source":"conversation","conversation_status":"open","stage_id":21}],"trigger_rules":"sample trigger rules","trigger_only_during_business_hours":"sample trigger only during business hours","message_variants":"sample message variants","send_settings":{"conversation":{"initial_status":"pending","on_reply":"open","assignment":"inbox_rules","labels":["black-friday"],"existing":"keep"}},"recipient_stats":"sample recipient stats","estimated_cost":"sample estimated cost","actual_cost":"sample actual cost","currency":"BRL","cost_basis":"sample cost basis","media_attachments":[{}],"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","recipient_timing":"sample recipient timing","conversations_opened_by_reply":42,"cost_breakdown":{"currency":"BRL","display_currency":"sample display currency","fx":{"rate":12.5,"source":"live","as_of":"2026-01-15T10:30:00.000Z"},"partner_billed":true,"amount_source":"list_rate","billable":{"count":5,"amount":149.9},"pending_delivery":{"count":5,"amount":149.9},"free":{"count":5},"not_billed":{"failed":1,"skipped":1,"expired":1},"frozen_estimate":{"amount":149.9,"currency":"BRL","basis":"frozen"}},"dispatch_progress":{"audience_total":15570,"processed":3601,"remaining":11969},"resume_block_reason":"template_not_approved","bsuid_only_recipients_count":12,"dispatch_messages_per_second":75}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]},"patch":{"tags":["Campaigns"],"operationId":"auto_patch_api_v1_accounts_account_id_campaigns_id","summary":"Update a campaign","description":"Updates an account campaign. Optional media and variant attachments must be account-owned Active Storage signed identifiers. Invalid cross-account capabilities are rejected before changing the record. `send_settings.dispatch_control` is server-owned: a submitted value is ignored and the stored one is kept. A WhatsApp Cloud campaign that is dispatching (`processing`) or `paused` refuses a change of `enabled` or `campaign_status` with `422` (`dispatch_in_progress`); use pause, resume or cancel.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Campaign updated successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/campaign"},"example":{"id":31,"title":"Renewal reminder","description":"Reminds customers whose renewal is due this week.","account_id":1,"inbox":{"navigation_only":true,"id":1,"name":"Sample Name","website_url":"https://example.com/resource","channel_type":"Channel::Api","avatar_url":"https://example.com/resource","widget_color":"#1F93FF","website_token":"sample-token","enable_auto_assignment":true,"web_widget_script":"sample web widget script","welcome_title":"sample welcome title","welcome_tagline":"sample welcome tagline","greeting_enabled":true,"greeting_message":"sample greeting message","channel_id":1,"working_hours_enabled":true,"enable_email_collect":true,"csat_survey_enabled":true,"auto_assignment_config":{},"out_of_office_message":"sample out of office message","working_hours":[{"day_of_week":12.5,"closed_all_day":true,"open_hour":12.5,"open_minutes":12.5,"close_hour":12.5,"close_minutes":12.5,"open_all_day":true}],"timezone":"America/Sao_Paulo","callback_webhook_url":"https://example.com/resource","allow_messages_after_resolved":true,"lock_to_single_conversation":true,"sender_name_type":"friendly","auto_resolve_config":{"mode":"custom","after":30,"message":"We are closing this conversation due to inactivity.","label":"auto-resolved","allow_waiting":false},"outbound_agent_name_header_policy":"inherit","business_name":"sample business name","branded_email_layout":"agent@example.com","responder_policy":{"mode":"agent_bot","conflict":true},"hmac_mandatory":true,"selected_feature_flags":["sample selected feature flag"],"reply_time":"2026-01-15T10:30:00.000Z","messaging_service_sid":"sample messaging service sid","phone_number":"+5511999998888","bandwidth_callback_state":"active","bandwidth_api_migration_state":"oauth2_configured","medium":"sample medium","provider":"default","whatsapp_web_session_state":{"state":"connected","fresh":true,"observed_at":"2026-01-15T10:30:00.000Z","disconnected_since":null},"hybrid_pair":{"paired":true,"id":4,"role":"cloud","sibling_inbox_id":18,"canonical_phone":"+5521900000000","primary":"cloud","inbound_authority":"cloud","unified_inbox":true,"unified_state":{"state":"complete","scanned":42,"frozen":40,"reconciled_count":2,"completed_at":"2026-10-03T12:00:00.000Z","blocked_conversations":[]},"routing":{"outbound_default":"cloud","out_of_window":"web","fallback":true,"manual_override":true,"weighted":{"mode":"weighted","web_percent":30,"version":2}},"web_channel_id":12,"web_inbox_id":18,"calling_provider":"whatsapp_web","web_voice_enabled":true,"web_inbound_calls_enabled":true,"web_call_config_sync":{"state":"pending","checked_at":"2026-10-03T12:00:00.000Z"},"web_video_calls_enabled":false,"web_group_calls_enabled":false,"web_reauthorization_required":false,"web_session_state":{"state":"connected","fresh":true,"observed_at":"2026-10-03T12:00:00.000Z","disconnected_since":null},"web_allow_message_deletion":true}},"logical_inbox_id":15,"whatsapp_transport":"web","sender":{"id":1,"account_id":1,"account_user_id":1,"availability_status":"online","auto_offline":true,"confirmed":true,"email":"agent@example.com","available_name":"sample available name","name":"Sample Name","role":"agent","outbound_agent_name_header_policy":"inherit","thumbnail":"sample thumbnail","custom_role_id":1},"message":"Hello {{contact.name}}, your renewal is due soon.","template_params":{},"campaign_status":"scheduled","enabled":true,"campaign_type":"one_off","scheduled_at":1786791600,"audience":[{"type":"Label","id":15,"source":"conversation","conversation_status":"open","stage_id":21}],"trigger_rules":{},"trigger_only_during_business_hours":false,"message_variants":[{"body":"Hello {{contact.name}}.","content_type":"text","content_attributes":{},"attachment_blob_ids":[]}],"send_settings":{"conversation":{"initial_status":"pending","on_reply":"open","assignment":"inbox_rules","labels":["black-friday"],"existing":"keep"}},"recipient_stats":{"pending":20,"processing":2,"sent":10,"delivered":8,"read":5,"replied":1,"failed":0,"skipped":0},"estimated_cost":"12.50","actual_cost":"10.75","currency":"BRL","media_attachments":[{"id":91,"signed_id":"eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBBQT09In19","filename":"renewal.pdf","content_type":"application/pdf","byte_size":48192}],"created_at":"2026-08-15T10:00:00.000Z","updated_at":"2026-08-15T10:05:00.000Z"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"422":{"description":"One of the submitted media signed IDs is invalid for this account, a WhatsApp Cloud campaign in flight received a lifecycle change (`dispatch_in_progress`, with `campaign_status`), or the campaign failed validation (`message` + `attributes`) — including an invalid `send_settings.conversation` policy. A policy is re-validated only when it changes.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["invalid_campaign_media","dispatch_in_progress"],"example":"invalid_campaign_media"},"message":{"type":"string","description":"Present on a validation failure — the readable reasons, in the account locale.","example":"These labels do not exist in this account: vip."},"attributes":{"type":"array","description":"Present on a validation failure — the attributes that failed (`base` for the conversation policy).","items":{"type":"string"},"example":["base"]},"campaign_status":{"type":"string","enum":["active","completed","draft","scheduled","sending","paused","failed","processing"],"description":"Present with `dispatch_in_progress` — the status that blocked the change.","example":"processing"}}},"example":{"error":"invalid_campaign_media","message":"These labels do not exist in this account: vip.","attributes":["base"],"campaign_status":"processing"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/campaign_create_update_payload"},"example":{"whatsapp_transport":"web","campaign":{"title":"Renewal reminder","message":"Hello {{contact.name}}, your renewal is due this week.","inbox_id":15,"whatsapp_transport":"web","campaign_status":"scheduled","audience":[{"type":"Label","id":15,"source":"conversation","conversation_status":"open","stage_id":21}],"media_blob_ids":[],"message_variants":[{"body":"Hello {{contact.name}}.","content_type":"text","content_attributes":{},"attachment_blob_ids":[]}],"description":"Reminds customers whose renewal is due this week.","enabled":true,"trigger_only_during_business_hours":false,"sender_id":7,"scheduled_at":1786791600,"trigger_rules":{},"template_params":{},"send_settings":{"conversation":{"initial_status":"pending","on_reply":"open","assignment":"inbox_rules","labels":["black-friday"],"existing":"keep"}}}}}}}},"put":{"tags":["Campaigns"],"operationId":"auto_put_api_v1_accounts_account_id_campaigns_id","summary":"Update a campaign","description":"Updates an account campaign. Optional media and variant attachments must be account-owned Active Storage signed identifiers. Invalid cross-account capabilities are rejected before changing the record. `send_settings.dispatch_control` is server-owned: a submitted value is ignored and the stored one is kept. A WhatsApp Cloud campaign that is dispatching (`processing`) or `paused` refuses a change of `enabled` or `campaign_status` with `422` (`dispatch_in_progress`); use pause, resume or cancel.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Campaign updated successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/campaign"},"example":{"id":31,"title":"Renewal reminder","description":"Reminds customers whose renewal is due this week.","account_id":1,"inbox":{"navigation_only":true,"id":1,"name":"Sample Name","website_url":"https://example.com/resource","channel_type":"Channel::Api","avatar_url":"https://example.com/resource","widget_color":"#1F93FF","website_token":"sample-token","enable_auto_assignment":true,"web_widget_script":"sample web widget script","welcome_title":"sample welcome title","welcome_tagline":"sample welcome tagline","greeting_enabled":true,"greeting_message":"sample greeting message","channel_id":1,"working_hours_enabled":true,"enable_email_collect":true,"csat_survey_enabled":true,"auto_assignment_config":{},"out_of_office_message":"sample out of office message","working_hours":[{"day_of_week":12.5,"closed_all_day":true,"open_hour":12.5,"open_minutes":12.5,"close_hour":12.5,"close_minutes":12.5,"open_all_day":true}],"timezone":"America/Sao_Paulo","callback_webhook_url":"https://example.com/resource","allow_messages_after_resolved":true,"lock_to_single_conversation":true,"sender_name_type":"friendly","auto_resolve_config":{"mode":"custom","after":30,"message":"We are closing this conversation due to inactivity.","label":"auto-resolved","allow_waiting":false},"outbound_agent_name_header_policy":"inherit","business_name":"sample business name","branded_email_layout":"agent@example.com","responder_policy":{"mode":"agent_bot","conflict":true},"hmac_mandatory":true,"selected_feature_flags":["sample selected feature flag"],"reply_time":"2026-01-15T10:30:00.000Z","messaging_service_sid":"sample messaging service sid","phone_number":"+5511999998888","bandwidth_callback_state":"active","bandwidth_api_migration_state":"oauth2_configured","medium":"sample medium","provider":"default","whatsapp_web_session_state":{"state":"connected","fresh":true,"observed_at":"2026-01-15T10:30:00.000Z","disconnected_since":null},"hybrid_pair":{"paired":true,"id":4,"role":"cloud","sibling_inbox_id":18,"canonical_phone":"+5521900000000","primary":"cloud","inbound_authority":"cloud","unified_inbox":true,"unified_state":{"state":"complete","scanned":42,"frozen":40,"reconciled_count":2,"completed_at":"2026-10-03T12:00:00.000Z","blocked_conversations":[]},"routing":{"outbound_default":"cloud","out_of_window":"web","fallback":true,"manual_override":true,"weighted":{"mode":"weighted","web_percent":30,"version":2}},"web_channel_id":12,"web_inbox_id":18,"calling_provider":"whatsapp_web","web_voice_enabled":true,"web_inbound_calls_enabled":true,"web_call_config_sync":{"state":"pending","checked_at":"2026-10-03T12:00:00.000Z"},"web_video_calls_enabled":false,"web_group_calls_enabled":false,"web_reauthorization_required":false,"web_session_state":{"state":"connected","fresh":true,"observed_at":"2026-10-03T12:00:00.000Z","disconnected_since":null},"web_allow_message_deletion":true}},"logical_inbox_id":15,"whatsapp_transport":"web","sender":{"id":1,"account_id":1,"account_user_id":1,"availability_status":"online","auto_offline":true,"confirmed":true,"email":"agent@example.com","available_name":"sample available name","name":"Sample Name","role":"agent","outbound_agent_name_header_policy":"inherit","thumbnail":"sample thumbnail","custom_role_id":1},"message":"Hello {{contact.name}}, your renewal is due soon.","template_params":{},"campaign_status":"scheduled","enabled":true,"campaign_type":"one_off","scheduled_at":1786791600,"audience":[{"type":"Label","id":15,"source":"conversation","conversation_status":"open","stage_id":21}],"trigger_rules":{},"trigger_only_during_business_hours":false,"message_variants":[{"body":"Hello {{contact.name}}.","content_type":"text","content_attributes":{},"attachment_blob_ids":[]}],"send_settings":{"conversation":{"initial_status":"pending","on_reply":"open","assignment":"inbox_rules","labels":["black-friday"],"existing":"keep"}},"recipient_stats":{"pending":20,"processing":2,"sent":10,"delivered":8,"read":5,"replied":1,"failed":0,"skipped":0},"estimated_cost":"12.50","actual_cost":"10.75","currency":"BRL","media_attachments":[{"id":91,"signed_id":"eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBBQT09In19","filename":"renewal.pdf","content_type":"application/pdf","byte_size":48192}],"created_at":"2026-08-15T10:00:00.000Z","updated_at":"2026-08-15T10:05:00.000Z"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"422":{"description":"One of the submitted media signed IDs is invalid for this account, a WhatsApp Cloud campaign in flight received a lifecycle change (`dispatch_in_progress`, with `campaign_status`), or the campaign failed validation (`message` + `attributes`) — including an invalid `send_settings.conversation` policy. A policy is re-validated only when it changes.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["invalid_campaign_media","dispatch_in_progress"],"example":"invalid_campaign_media"},"message":{"type":"string","description":"Present on a validation failure — the readable reasons, in the account locale.","example":"These labels do not exist in this account: vip."},"attributes":{"type":"array","description":"Present on a validation failure — the attributes that failed (`base` for the conversation policy).","items":{"type":"string"},"example":["base"]},"campaign_status":{"type":"string","enum":["active","completed","draft","scheduled","sending","paused","failed","processing"],"description":"Present with `dispatch_in_progress` — the status that blocked the change.","example":"processing"}}},"example":{"error":"invalid_campaign_media","message":"These labels do not exist in this account: vip.","attributes":["base"],"campaign_status":"processing"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/campaign_create_update_payload"},"example":{"whatsapp_transport":"web","campaign":{"title":"Renewal reminder","message":"Hello {{contact.name}}, your renewal is due this week.","inbox_id":15,"whatsapp_transport":"web","campaign_status":"scheduled","audience":[{"type":"Label","id":15,"source":"conversation","conversation_status":"open","stage_id":21}],"media_blob_ids":[],"message_variants":[{"body":"Hello {{contact.name}}.","content_type":"text","content_attributes":{},"attachment_blob_ids":[]}],"description":"Reminds customers whose renewal is due this week.","enabled":true,"trigger_only_during_business_hours":false,"sender_id":7,"scheduled_at":1786791600,"trigger_rules":{},"template_params":{},"send_settings":{"conversation":{"initial_status":"pending","on_reply":"open","assignment":"inbox_rules","labels":["black-friday"],"existing":"keep"}}}}}}}},"delete":{"tags":["Campaigns"],"operationId":"auto_delete_api_v1_accounts_account_id_campaigns_id","summary":"Delete campaigns","description":"Deletes the campaign identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Success (no content)"},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/campaign_suppressions/settings":{"get":{"tags":["Campaign Suppressions"],"operationId":"auto_get_api_v1_accounts_account_id_campaign_suppressions_settings","summary":"Read the inbound opt-out settings","description":"The keywords that put a contact on the suppression list (whole message, normalized: accents, case, edge punctuation and emojis ignored), the keywords that take it off, and whether the contact receives a confirmation (off by default). Includes the shipped defaults so a client can offer to restore them.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The current settings.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Whether opt-out keywords are recognized.","example":true},"auto_reply":{"type":"boolean","description":"Whether the contact receives a confirmation message (off by default).","example":false},"keywords":{"type":"array","items":{"type":"string"},"example":["parar"]},"resubscribe_keywords":{"type":"array","items":{"type":"string"},"example":[]},"confirmation_message":{"description":"The operator's confirmation text (one text, or one per language), or null for the shipped text.","oneOf":[{"type":"string"},{"type":"object","additionalProperties":{"type":"string"},"description":"Confirmation text per language (pt_BR, en, es)."}],"example":null},"default_keywords":{"type":"array","items":{"type":"string"},"example":["parar"]},"default_confirmation":{"type":"object","additionalProperties":{"type":"string"},"description":"The shipped confirmation text per language (pt_BR, en, es).","example":{"en":"Done. You will no longer receive our campaign messages."}}}}}},"example":{"payload":{"enabled":true,"auto_reply":false,"keywords":["parar","sair","pausar mensagens","descadastrar","stop","unsubscribe","baja"],"resubscribe_keywords":[],"confirmation_message":null,"default_keywords":["parar","sair","pausar mensagens","descadastrar","stop","unsubscribe","baja"],"default_confirmation":{"pt_BR":"Pronto. Você não vai mais receber nossas mensagens de campanha. Se mudar de ideia, é só nos avisar por aqui.","en":"Done. You will no longer receive our campaign messages. If you change your mind, just let us know here.","es":"Listo. Ya no recibirás nuestros mensajes de campaña. Si cambias de opinión, avísanos por aquí."}}}}}},"401":{"description":"Not authenticated, or not an administrator of the account."},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]},"patch":{"tags":["Campaign Suppressions"],"operationId":"auto_patch_api_v1_accounts_account_id_campaign_suppressions_settings","summary":"Update the inbound opt-out settings","description":"Stores only the given keys. Keywords are normalized and de-duplicated. Refused with 422 and an error key when a list has more than 30 keywords, a keyword is longer than 60 characters, recognition is on with no keyword, or a confirmation is longer than 1,024 characters.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The saved settings.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Whether opt-out keywords are recognized.","example":true},"auto_reply":{"type":"boolean","description":"Whether the contact receives a confirmation message (off by default).","example":false},"keywords":{"type":"array","items":{"type":"string"},"example":["parar"]},"resubscribe_keywords":{"type":"array","items":{"type":"string"},"example":[]},"confirmation_message":{"description":"The operator's confirmation text (one text, or one per language), or null for the shipped text.","oneOf":[{"type":"string"},{"type":"object","additionalProperties":{"type":"string"},"description":"Confirmation text per language (pt_BR, en, es)."}],"example":null},"default_keywords":{"type":"array","items":{"type":"string"},"example":["parar"]},"default_confirmation":{"type":"object","additionalProperties":{"type":"string"},"description":"The shipped confirmation text per language (pt_BR, en, es).","example":{"en":"Done. You will no longer receive our campaign messages."}}}}}},"example":{"payload":{"enabled":true,"auto_reply":false,"keywords":["parar","pausar mensagens"],"resubscribe_keywords":["voltar"],"confirmation_message":{"pt_BR":"Pronto, você não recebe mais nossas campanhas."},"default_keywords":["parar","sair","pausar mensagens","descadastrar","stop","unsubscribe","baja"],"default_confirmation":{"pt_BR":"Pronto. Você não vai mais receber nossas mensagens de campanha. Se mudar de ideia, é só nos avisar por aqui.","en":"Done. You will no longer receive our campaign messages. If you change your mind, just let us know here.","es":"Listo. Ya no recibirás nuestros mensajes de campaña. Si cambias de opinión, avísanos por aquí."}}}}}},"401":{"description":"Not authenticated, or not an administrator of the account."},"404":{"description":"Account or resource not found"},"422":{"description":"The settings were refused.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["too_many_keywords","keyword_too_long","keywords_required","confirmation_too_long"],"example":"keywords_required"}}},"example":{"error":"keywords_required"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["settings"],"properties":{"settings":{"type":"object","properties":{"enabled":{"type":"boolean","example":true},"auto_reply":{"type":"boolean","example":false},"keywords":{"type":"array","maxItems":30,"items":{"type":"string","maxLength":60},"example":["parar","pausar mensagens"]},"resubscribe_keywords":{"type":"array","maxItems":30,"items":{"type":"string","maxLength":60},"example":["voltar"]},"confirmation_message":{"description":"One text for every language, or one text per language (pt_BR, en, es).","oneOf":[{"type":"string","maxLength":1024},{"type":"object","additionalProperties":false,"properties":{"pt_BR":{"type":"string","maxLength":1024},"en":{"type":"string","maxLength":1024},"es":{"type":"string","maxLength":1024}}}],"example":{"pt_BR":"Pronto, você não recebe mais nossas campanhas."}}}}}},"example":{"settings":{"enabled":true,"auto_reply":false,"keywords":["parar","pausar mensagens"],"resubscribe_keywords":["voltar"],"confirmation_message":{"pt_BR":"Pronto, você não recebe mais nossas campanhas.","en":"sample en","es":"sample es"}}}}}}}},"/api/v1/accounts/{account_id}/campaign_suppressions":{"get":{"tags":["Campaign Suppressions"],"operationId":"auto_get_api_v1_accounts_account_id_campaign_suppressions","summary":"List the contacts on the campaign suppression list","description":"Contacts on the account's campaign suppression list receive no campaign at all, of any category (marketing, utility, authentication) and on any channel (WhatsApp Cloud, WhatsApp Web, SMS and API). A contact joins the list by sending one of the configured opt-out keywords as its whole message (or tapping a quick-reply button with that text), or when an administrator adds it. Each entry carries the record that put the contact on the list. Ordered by contact id, 25 per page.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"One page of the suppression list.","content":{"application/json":{"schema":{"type":"object","properties":{"meta":{"type":"object","properties":{"count":{"type":"integer","description":"Contacts on the list matching the search.","example":1},"current_page":{"type":"integer","example":1},"per_page":{"type":"integer","example":25}}},"payload":{"type":"array","items":{"type":"object","description":"One contact on the suppression list with the record that put it there.","properties":{"contact":{"type":"object","properties":{"id":{"type":"integer","example":42},"name":{"type":["string","null"],"example":"Maria Souza"},"phone_number":{"type":["string","null"],"example":"+5521999990000"},"email":{"type":["string","null"],"example":"maria@example.com"},"thumbnail":{"type":"string","example":""}}},"record_id":{"type":["integer","null"],"description":"The consent record in force (a denial of the `campaigns` purpose).","example":901},"source":{"type":["string","null"],"enum":["keyword","agent","api","import","widget","message",null],"description":"How the contact joined the list; `keyword` = an opt-out keyword or quick-reply button.","example":"keyword"},"suppressed_at":{"type":["string","null"],"format":"date-time","example":"2026-10-01T18:20:00Z"},"note":{"type":["string","null"],"example":null},"matched_token":{"type":["string","null"],"description":"The normalized keyword the contact sent (keyword source only).","example":"pausar mensagens"},"conversation_id":{"type":["integer","null"],"description":"The conversation of the opt-out message (keyword source only).","example":3170},"inbox_id":{"type":["integer","null"],"example":7},"recorded_by":{"type":["object","null"],"description":"The administrator who added the contact; null for a keyword.","properties":{"id":{"type":"integer","example":3},"name":{"type":"string","example":"Ana Lima"}}}}}}}},"example":{"meta":{"count":1,"current_page":1,"per_page":25},"payload":[{"contact":{"id":42,"name":"Maria Souza","phone_number":"+5521999990000","email":"maria@example.com","thumbnail":""},"record_id":901,"source":"keyword","suppressed_at":"2026-10-01T18:20:00Z","note":null,"matched_token":"pausar mensagens","conversation_id":3170,"inbox_id":7,"recorded_by":null}]}}}},"401":{"description":"Not authenticated, or not an administrator of the account."},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1},"description":"Page number (25 entries per page).","example":1},{"name":"q","in":"query","required":false,"schema":{"type":"string"},"description":"Case-insensitive search on the contact name, phone number or e-mail.","example":"Maria"}]},"post":{"tags":["Campaign Suppressions"],"operationId":"auto_post_api_v1_accounts_account_id_campaign_suppressions","summary":"Add a contact to the campaign suppression list","description":"Appends a denial of the `campaigns` purpose for the contact (source `agent`, or `api` when the call is authenticated by an access token). A contact already on the list is left as it is and answered with 200 and the record in force; a new entry is answered with 201.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The contact was already on the list; nothing was appended.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","description":"One contact on the suppression list with the record that put it there.","properties":{"contact":{"type":"object","properties":{"id":{"type":"integer","example":42},"name":{"type":["string","null"],"example":"Maria Souza"},"phone_number":{"type":["string","null"],"example":"+5521999990000"},"email":{"type":["string","null"],"example":"maria@example.com"},"thumbnail":{"type":"string","example":""}}},"record_id":{"type":["integer","null"],"description":"The consent record in force (a denial of the `campaigns` purpose).","example":901},"source":{"type":["string","null"],"enum":["keyword","agent","api","import","widget","message",null],"description":"How the contact joined the list; `keyword` = an opt-out keyword or quick-reply button.","example":"keyword"},"suppressed_at":{"type":["string","null"],"format":"date-time","example":"2026-10-01T18:20:00Z"},"note":{"type":["string","null"],"example":null},"matched_token":{"type":["string","null"],"description":"The normalized keyword the contact sent (keyword source only).","example":"pausar mensagens"},"conversation_id":{"type":["integer","null"],"description":"The conversation of the opt-out message (keyword source only).","example":3170},"inbox_id":{"type":["integer","null"],"example":7},"recorded_by":{"type":["object","null"],"description":"The administrator who added the contact; null for a keyword.","properties":{"id":{"type":"integer","example":3},"name":{"type":"string","example":"Ana Lima"}}}}}}},"example":{"payload":{"contact":{"id":42,"name":"Maria Souza","phone_number":"+5521999990000","email":"maria@example.com","thumbnail":""},"record_id":901,"source":"keyword","suppressed_at":"2026-10-01T18:20:00Z","note":null,"matched_token":"pausar mensagens","conversation_id":3170,"inbox_id":7,"recorded_by":null}}}}},"401":{"description":"Not authenticated, or not an administrator of the account."},"404":{"description":"No such contact in this account."},"201":{"description":"The contact was added to the list.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","description":"One contact on the suppression list with the record that put it there.","properties":{"contact":{"type":"object","properties":{"id":{"type":"integer","example":42},"name":{"type":["string","null"],"example":"Maria Souza"},"phone_number":{"type":["string","null"],"example":"+5521999990000"},"email":{"type":["string","null"],"example":"maria@example.com"},"thumbnail":{"type":"string","example":""}}},"record_id":{"type":["integer","null"],"description":"The consent record in force (a denial of the `campaigns` purpose).","example":901},"source":{"type":["string","null"],"enum":["keyword","agent","api","import","widget","message",null],"description":"How the contact joined the list; `keyword` = an opt-out keyword or quick-reply button.","example":"keyword"},"suppressed_at":{"type":["string","null"],"format":"date-time","example":"2026-10-01T18:20:00Z"},"note":{"type":["string","null"],"example":null},"matched_token":{"type":["string","null"],"description":"The normalized keyword the contact sent (keyword source only).","example":"pausar mensagens"},"conversation_id":{"type":["integer","null"],"description":"The conversation of the opt-out message (keyword source only).","example":3170},"inbox_id":{"type":["integer","null"],"example":7},"recorded_by":{"type":["object","null"],"description":"The administrator who added the contact; null for a keyword.","properties":{"id":{"type":"integer","example":3},"name":{"type":"string","example":"Ana Lima"}}}}}}},"example":{"payload":{"contact":{"id":42,"name":"Maria Souza","phone_number":"+5521999990000","email":"maria@example.com","thumbnail":""},"record_id":902,"source":"agent","suppressed_at":"2026-10-02T10:00:00Z","note":"Asked by phone on 10/02","matched_token":null,"conversation_id":null,"inbox_id":null,"recorded_by":{"id":3,"name":"Ana Lima"}}}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["contact_id"],"properties":{"contact_id":{"type":"integer","description":"Account-scoped contact to suppress.","example":42},"note":{"type":["string","null"],"maxLength":500,"description":"Optional human-readable reason, kept with the record.","example":"Asked by phone on 10/02"}}},"example":{"contact_id":42,"note":"Asked by phone on 10/02"}}}}}},"/api/v1/accounts/{account_id}/campaign_suppressions/{id}":{"delete":{"tags":["Campaign Suppressions"],"operationId":"auto_delete_api_v1_accounts_account_id_campaign_suppressions_id","summary":"Take a contact off the campaign suppression list","description":"Appends a grant of the `campaigns` purpose recorded by the current user; the earlier denial is kept as evidence (nothing is deleted). The path id is the CONTACT id. Answers 204 with an empty body, or 422 `not_suppressed` when the contact was not on the list.","security":[{"userApiKey":[]}],"responses":{"204":{"description":"The contact was taken off the list. Empty body."},"401":{"description":"Not authenticated, or not an administrator of the account."},"404":{"description":"No such contact in this account."},"422":{"description":"The contact was not on the list.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["not_suppressed"],"example":"not_suppressed"}}},"example":{"error":"not_suppressed"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"integer"},"description":"The contact id.","example":42},{"name":"note","in":"query","required":false,"schema":{"type":"string","maxLength":500},"description":"Optional reason, kept with the record.","example":"Asked to receive campaigns again"}]}},"/api/v1/accounts/{account_id}/platform_notifications/{id}/dismiss":{"post":{"tags":["Platform Notifications"],"operationId":"auto_post_api_v1_accounts_account_id_platform_notifications_id_dismiss","summary":"Dismiss a platform notification","description":"Dismisses a platform notification for the signed-in user only, so it stops appearing for them while remaining visible to everyone else it targets. The response carries no body and the call is idempotent: dismissing an unknown notification, or one this user already dismissed, succeeds and changes nothing.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Notification dismissed for the signed-in user. Empty body."},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/platform_notifications":{"get":{"tags":["Platform Notifications"],"operationId":"auto_get_api_v1_accounts_account_id_platform_notifications","summary":"List platform notifications","description":"Returns the list of platform notifications visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"title":{"type":"string"},"content_html":{"type":"string"},"level":{"type":"string","enum":["info","success","warning","error"]},"surfaces":{"type":"string"},"cta":{"type":"string"},"video_url":{"type":"string"},"dismissible":{"type":"string"},"priority":{"type":"string"},"updated_at":{"type":"string","format":"date-time"},"media":{"type":"array","items":{"type":"object"}}}}},"example":[{"id":1,"title":"Sample title","content_html":"sample content html","level":"info","surfaces":"sample surfaces","cta":"sample cta","video_url":"https://example.com/resource","dismissible":"sample dismissible","priority":"sample priority","updated_at":"2026-01-15T10:30:00.000Z","media":[{}]}]}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."}]}},"/api/v1/accounts/{account_id}/dashboard_apps":{"get":{"tags":["Dashboard Apps"],"operationId":"auto_get_api_v1_accounts_account_id_dashboard_apps","summary":"List dashboard apps","description":"Lists the account's Dashboard App definitions. This legacy catalog remains available when native surfaces are disabled.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Dashboard App definitions in account order.","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["id","title","content","created_at"],"properties":{"id":{"type":"integer","minimum":1},"title":{"type":"string","minLength":1},"content":{"type":"array","minItems":1,"items":{"type":"object","additionalProperties":false,"required":["type","url"],"properties":{"type":{"type":"string","enum":["frame"],"description":"Dashboard Apps currently embed one frame content type."},"url":{"type":"string","format":"uri","pattern":"^https?://","description":"Absolute HTTP(S) frame URL without embedded credentials. Static query parameters and a fragment are preserved. Names beginning with `cl_` are reserved for the native V2 launch: the host removes static values in that namespace and writes only its allowlisted launch parameters. Never put credentials or personal data in the URL."},"sidebar_category":{"type":"string","enum":["support","contacts_crm","applications","commercial","productivity","automation","growth","analytics_config"],"default":"productivity","description":"Preferred native sidebar category. It is stored with the app definition because an app can have at most one sidebar installation, survives definition-only exports, and is exposed on that installation's resource."},"sidebar_icon":{"type":"string","enum":["panels_top_left","layout_dashboard","app_window","boxes","briefcase","bot","calendar_days","chart_no_axes_combined","circle_dollar_sign","clipboard_list","database","folder","globe_2","headphones","life_buoy","messages_square","package","rocket","shopping_bag","sparkles","workflow","wrench"],"default":"panels_top_left","description":"Allowlisted icon token used by the native sidebar item."}}}},"created_at":{"type":"string","format":"date-time"}}}},"example":[{"id":3,"title":"ERP","content":[{"type":"frame","url":"https://erp.example/panel","sidebar_category":"applications","sidebar_icon":"rocket"}],"created_at":"2026-08-21T12:00:00Z"}]}}},"401":{"description":"Authentication is required.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string"}}},"example":{"error":"Authentication is required"}}}},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]},"post":{"tags":["Dashboard Apps"],"operationId":"auto_post_api_v1_accounts_account_id_dashboard_apps","summary":"Create a dashboard app","description":"Creates a Dashboard App definition and, atomically, its optional native-surface installations. While the native-surfaces feature is enabled, omitting `installations` creates one enabled conversation/legacy installation; while it is disabled, omission preserves the original definition-only behavior. Sending an empty array explicitly creates only the app definition.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Dashboard App definition created with its requested installations.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["id","title","content","created_at"],"properties":{"id":{"type":"integer","minimum":1},"title":{"type":"string","minLength":1},"content":{"type":"array","minItems":1,"items":{"type":"object","additionalProperties":false,"required":["type","url"],"properties":{"type":{"type":"string","enum":["frame"],"description":"Dashboard Apps currently embed one frame content type."},"url":{"type":"string","format":"uri","pattern":"^https?://","description":"Absolute HTTP(S) frame URL without embedded credentials. Static query parameters and a fragment are preserved. Names beginning with `cl_` are reserved for the native V2 launch: the host removes static values in that namespace and writes only its allowlisted launch parameters. Never put credentials or personal data in the URL."},"sidebar_category":{"type":"string","enum":["support","contacts_crm","applications","commercial","productivity","automation","growth","analytics_config"],"default":"productivity","description":"Preferred native sidebar category. It is stored with the app definition because an app can have at most one sidebar installation, survives definition-only exports, and is exposed on that installation's resource."},"sidebar_icon":{"type":"string","enum":["panels_top_left","layout_dashboard","app_window","boxes","briefcase","bot","calendar_days","chart_no_axes_combined","circle_dollar_sign","clipboard_list","database","folder","globe_2","headphones","life_buoy","messages_square","package","rocket","shopping_bag","sparkles","workflow","wrench"],"default":"panels_top_left","description":"Allowlisted icon token used by the native sidebar item."}}}},"created_at":{"type":"string","format":"date-time"}}},"example":{"id":3,"title":"ERP","content":[{"type":"frame","url":"https://erp.example/panel","sidebar_category":"applications","sidebar_icon":"rocket"}],"created_at":"2026-08-21T12:00:00Z"}}}},"401":{"description":"Authentication or Dashboard App management permission is required.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string"}}},"example":{"error":"You are not authorized to do this action"}}}},"404":{"description":"Account or resource not found"},"422":{"description":"The Dashboard App or one of its requested installations is invalid; the transaction is rolled back.","content":{"application/json":{"schema":{"oneOf":[{"type":"object","additionalProperties":false,"required":["message","attributes"],"properties":{"message":{"type":"string"},"attributes":{"type":"array","uniqueItems":true,"items":{"type":"string","enum":["title","content"]}}}},{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","enum":["invalid_installation","invalid_audience","invalid_capabilities","invalid_sidebar_category","invalid_sidebar_icon","installation_already_exists","invalid_dashboard_app_url","dashboard_app_migration_required","unsafe_same_origin_v2"]}}}]},"example":{"error":"invalid_audience"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["dashboard_app"],"properties":{"dashboard_app":{"type":"object","additionalProperties":false,"required":["title","content"],"properties":{"title":{"type":"string","minLength":1},"content":{"type":"array","minItems":1,"items":{"type":"object","additionalProperties":false,"required":["type","url"],"properties":{"type":{"type":"string","enum":["frame"],"description":"Dashboard Apps currently embed one frame content type."},"url":{"type":"string","format":"uri","pattern":"^https?://","description":"Absolute HTTP(S) frame URL without embedded credentials. Static query parameters and a fragment are preserved. Names beginning with `cl_` are reserved for the native V2 launch: the host removes static values in that namespace and writes only its allowlisted launch parameters. Never put credentials or personal data in the URL."},"sidebar_category":{"type":"string","enum":["support","contacts_crm","applications","commercial","productivity","automation","growth","analytics_config"],"default":"productivity","description":"Preferred native sidebar category. It is stored with the app definition because an app can have at most one sidebar installation, survives definition-only exports, and is exposed on that installation's resource."},"sidebar_icon":{"type":"string","enum":["panels_top_left","layout_dashboard","app_window","boxes","briefcase","bot","calendar_days","chart_no_axes_combined","circle_dollar_sign","clipboard_list","database","folder","globe_2","headphones","life_buoy","messages_square","package","rocket","shopping_bag","sparkles","workflow","wrench"],"default":"panels_top_left","description":"Allowlisted icon token used by the native sidebar item."}}}},"installations":{"type":"array","maxItems":2,"description":"Optional conversation/sidebar installations created in the same transaction; surfaces must be unique.","items":{"type":"object","additionalProperties":false,"properties":{"surface":{"type":"string","enum":["conversation","sidebar"],"default":"conversation"},"compatibility_mode":{"type":"string","enum":["legacy","v2","dual"],"default":"legacy"},"enabled":{"type":"boolean","default":true},"position":{"type":"integer","minimum":0,"default":0,"description":"Zero-based order within the selected surface. Sidebar positions are scoped to `sidebar_category`; updating either field atomically resequences the previous and destination groups."},"sidebar_category":{"type":"string","enum":["support","contacts_crm","applications","commercial","productivity","automation","growth","analytics_config"],"default":"productivity","description":"Native category that directly contains a sidebar installation. Accepted only when `surface` is `sidebar`; omitted sidebar values use `productivity`."},"sidebar_icon":{"type":"string","enum":["panels_top_left","layout_dashboard","app_window","boxes","briefcase","bot","calendar_days","chart_no_axes_combined","circle_dollar_sign","clipboard_list","database","folder","globe_2","headphones","life_buoy","messages_square","package","rocket","shopping_bag","sparkles","workflow","wrench"],"default":"panels_top_left","description":"Allowlisted icon token for the direct native menu item. Accepted only when `surface` is `sidebar`; omitted sidebar values use `panels_top_left`."},"audience":{"oneOf":[{"type":"object","additionalProperties":false,"required":["type"],"properties":{"type":{"type":"string","enum":["all"],"description":"Every active account member may see the installation."}}},{"type":"object","additionalProperties":false,"required":["type"],"properties":{"type":{"type":"string","enum":["any"],"description":"At least one role, team membership, or explicit user selector must match."},"roles":{"type":"array","uniqueItems":true,"default":[],"items":{"type":"string","enum":["agent","administrator"]}},"team_ids":{"type":"array","uniqueItems":true,"default":[],"items":{"type":"integer","minimum":1}},"user_ids":{"type":"array","uniqueItems":true,"default":[],"items":{"type":"integer","minimum":1}}},"anyOf":[{"type":"object","required":["roles"],"properties":{"roles":{"type":"array","minItems":1,"items":{"type":"string","enum":["agent","administrator"]}}}},{"type":"object","required":["team_ids"],"properties":{"team_ids":{"type":"array","minItems":1,"items":{"type":"integer","minimum":1}}}},{"type":"object","required":["user_ids"],"properties":{"user_ids":{"type":"array","minItems":1,"items":{"type":"integer","minimum":1}}}}]}],"discriminator":{"propertyName":"type"},"default":{"type":"all"}},"capabilities":{"type":"array","minItems":5,"uniqueItems":true,"description":"Explicit V2/dual grants. When omitted, the server applies the complete useful default for the selected surface, including email, contact data where applicable, and signed identity. An explicit empty array is rejected as `invalid_capabilities`; remove only optional grants while preserving every capability required by the selected surface.","items":{"type":"string","enum":["account:read","current_user:read","current_user:email","permissions:read","appearance:read","installation:read","conversation:read","contact:read","contact:email","contact:phone","messages:read","identity:assertion"]}}}}}}}}},"example":{"dashboard_app":{"title":"ERP","content":[{"type":"frame","url":"https://erp.example/panel","sidebar_category":"applications","sidebar_icon":"rocket"}],"installations":[{"surface":"conversation","compatibility_mode":"dual","enabled":true,"position":0,"capabilities":["account:read","current_user:read","current_user:email","permissions:read","appearance:read","installation:read","conversation:read","contact:read","contact:email","contact:phone","messages:read","identity:assertion"],"audience":{"type":"all"},"sidebar_category":"productivity","sidebar_icon":"panels_top_left"}]}}}}}}},"/api/v1/accounts/{account_id}/dashboard_apps/{id}":{"get":{"tags":["Dashboard Apps"],"operationId":"auto_get_api_v1_accounts_account_id_dashboard_apps_id","summary":"Get a dashboard app","description":"Returns one Dashboard App definition belonging to the authenticated account.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Dashboard App definition.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["id","title","content","created_at"],"properties":{"id":{"type":"integer","minimum":1},"title":{"type":"string","minLength":1},"content":{"type":"array","minItems":1,"items":{"type":"object","additionalProperties":false,"required":["type","url"],"properties":{"type":{"type":"string","enum":["frame"],"description":"Dashboard Apps currently embed one frame content type."},"url":{"type":"string","format":"uri","pattern":"^https?://","description":"Absolute HTTP(S) frame URL without embedded credentials. Static query parameters and a fragment are preserved. Names beginning with `cl_` are reserved for the native V2 launch: the host removes static values in that namespace and writes only its allowlisted launch parameters. Never put credentials or personal data in the URL."},"sidebar_category":{"type":"string","enum":["support","contacts_crm","applications","commercial","productivity","automation","growth","analytics_config"],"default":"productivity","description":"Preferred native sidebar category. It is stored with the app definition because an app can have at most one sidebar installation, survives definition-only exports, and is exposed on that installation's resource."},"sidebar_icon":{"type":"string","enum":["panels_top_left","layout_dashboard","app_window","boxes","briefcase","bot","calendar_days","chart_no_axes_combined","circle_dollar_sign","clipboard_list","database","folder","globe_2","headphones","life_buoy","messages_square","package","rocket","shopping_bag","sparkles","workflow","wrench"],"default":"panels_top_left","description":"Allowlisted icon token used by the native sidebar item."}}}},"created_at":{"type":"string","format":"date-time"}}},"example":{"id":3,"title":"ERP","content":[{"type":"frame","url":"https://erp.example/panel?tenant=acme#customers","sidebar_category":"applications","sidebar_icon":"rocket"}],"created_at":"2026-08-21T12:00:00Z"}}}},"401":{"description":"Authentication is required.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string"}}},"example":{"error":"Authentication is required"}}}},"404":{"description":"No Dashboard App with this id belongs to the account.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string"}}},"example":{"error":"Resource could not be found"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]},"patch":{"tags":["Dashboard Apps"],"operationId":"auto_patch_api_v1_accounts_account_id_dashboard_apps_id","summary":"Update a dashboard app","description":"Updates only the app title or its closed frame content. Sidebar category and icon metadata are preserved when omitted; installation management uses the installation endpoint.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Updated Dashboard App definition.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["id","title","content","created_at"],"properties":{"id":{"type":"integer","minimum":1},"title":{"type":"string","minLength":1},"content":{"type":"array","minItems":1,"items":{"type":"object","additionalProperties":false,"required":["type","url"],"properties":{"type":{"type":"string","enum":["frame"],"description":"Dashboard Apps currently embed one frame content type."},"url":{"type":"string","format":"uri","pattern":"^https?://","description":"Absolute HTTP(S) frame URL without embedded credentials. Static query parameters and a fragment are preserved. Names beginning with `cl_` are reserved for the native V2 launch: the host removes static values in that namespace and writes only its allowlisted launch parameters. Never put credentials or personal data in the URL."},"sidebar_category":{"type":"string","enum":["support","contacts_crm","applications","commercial","productivity","automation","growth","analytics_config"],"default":"productivity","description":"Preferred native sidebar category. It is stored with the app definition because an app can have at most one sidebar installation, survives definition-only exports, and is exposed on that installation's resource."},"sidebar_icon":{"type":"string","enum":["panels_top_left","layout_dashboard","app_window","boxes","briefcase","bot","calendar_days","chart_no_axes_combined","circle_dollar_sign","clipboard_list","database","folder","globe_2","headphones","life_buoy","messages_square","package","rocket","shopping_bag","sparkles","workflow","wrench"],"default":"panels_top_left","description":"Allowlisted icon token used by the native sidebar item."}}}},"created_at":{"type":"string","format":"date-time"}}},"example":{"id":3,"title":"ERP Finance","content":[{"type":"frame","url":"https://erp.example/finance","sidebar_category":"applications","sidebar_icon":"rocket"}],"created_at":"2026-08-21T12:00:00Z"}}}},"401":{"description":"Authentication or Dashboard App management permission is required.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string"}}},"example":{"error":"You are not authorized to do this action"}}}},"404":{"description":"No Dashboard App with this id belongs to the account.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string"}}},"example":{"error":"Resource could not be found"}}}},"422":{"description":"The submitted title or frame content is invalid.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["message","attributes"],"properties":{"message":{"type":"string"},"attributes":{"type":"array","uniqueItems":true,"items":{"type":"string","enum":["title","content"]}}}},"example":{"message":"Content : Invalid data","attributes":["content"]}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["dashboard_app"],"properties":{"dashboard_app":{"type":"object","additionalProperties":false,"minProperties":1,"properties":{"title":{"type":"string","minLength":1},"content":{"type":"array","minItems":1,"items":{"type":"object","additionalProperties":false,"required":["type","url"],"properties":{"type":{"type":"string","enum":["frame"],"description":"Dashboard Apps currently embed one frame content type."},"url":{"type":"string","format":"uri","pattern":"^https?://","description":"Absolute HTTP(S) frame URL without embedded credentials. Static query parameters and a fragment are preserved. Names beginning with `cl_` are reserved for the native V2 launch: the host removes static values in that namespace and writes only its allowlisted launch parameters. Never put credentials or personal data in the URL."},"sidebar_category":{"type":"string","enum":["support","contacts_crm","applications","commercial","productivity","automation","growth","analytics_config"],"default":"productivity","description":"Preferred native sidebar category. It is stored with the app definition because an app can have at most one sidebar installation, survives definition-only exports, and is exposed on that installation's resource."},"sidebar_icon":{"type":"string","enum":["panels_top_left","layout_dashboard","app_window","boxes","briefcase","bot","calendar_days","chart_no_axes_combined","circle_dollar_sign","clipboard_list","database","folder","globe_2","headphones","life_buoy","messages_square","package","rocket","shopping_bag","sparkles","workflow","wrench"],"default":"panels_top_left","description":"Allowlisted icon token used by the native sidebar item."}}}}}}}},"example":{"dashboard_app":{"title":"ERP Finance","content":[{"type":"frame","url":"https://erp.example/finance","sidebar_category":"applications","sidebar_icon":"rocket"}]}}}}}},"put":{"tags":["Dashboard Apps"],"operationId":"auto_put_api_v1_accounts_account_id_dashboard_apps_id","summary":"Update a dashboard app","description":"Updates only the app title or its closed frame content. Sidebar category and icon metadata are preserved when omitted; installation management uses the installation endpoint.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Updated Dashboard App definition.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["id","title","content","created_at"],"properties":{"id":{"type":"integer","minimum":1},"title":{"type":"string","minLength":1},"content":{"type":"array","minItems":1,"items":{"type":"object","additionalProperties":false,"required":["type","url"],"properties":{"type":{"type":"string","enum":["frame"],"description":"Dashboard Apps currently embed one frame content type."},"url":{"type":"string","format":"uri","pattern":"^https?://","description":"Absolute HTTP(S) frame URL without embedded credentials. Static query parameters and a fragment are preserved. Names beginning with `cl_` are reserved for the native V2 launch: the host removes static values in that namespace and writes only its allowlisted launch parameters. Never put credentials or personal data in the URL."},"sidebar_category":{"type":"string","enum":["support","contacts_crm","applications","commercial","productivity","automation","growth","analytics_config"],"default":"productivity","description":"Preferred native sidebar category. It is stored with the app definition because an app can have at most one sidebar installation, survives definition-only exports, and is exposed on that installation's resource."},"sidebar_icon":{"type":"string","enum":["panels_top_left","layout_dashboard","app_window","boxes","briefcase","bot","calendar_days","chart_no_axes_combined","circle_dollar_sign","clipboard_list","database","folder","globe_2","headphones","life_buoy","messages_square","package","rocket","shopping_bag","sparkles","workflow","wrench"],"default":"panels_top_left","description":"Allowlisted icon token used by the native sidebar item."}}}},"created_at":{"type":"string","format":"date-time"}}},"example":{"id":3,"title":"ERP Finance","content":[{"type":"frame","url":"https://erp.example/finance","sidebar_category":"applications","sidebar_icon":"rocket"}],"created_at":"2026-08-21T12:00:00Z"}}}},"401":{"description":"Authentication or Dashboard App management permission is required.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string"}}},"example":{"error":"You are not authorized to do this action"}}}},"404":{"description":"No Dashboard App with this id belongs to the account.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string"}}},"example":{"error":"Resource could not be found"}}}},"422":{"description":"The submitted title or frame content is invalid.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["message","attributes"],"properties":{"message":{"type":"string"},"attributes":{"type":"array","uniqueItems":true,"items":{"type":"string","enum":["title","content"]}}}},"example":{"message":"Content : Invalid data","attributes":["content"]}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["dashboard_app"],"properties":{"dashboard_app":{"type":"object","additionalProperties":false,"minProperties":1,"properties":{"title":{"type":"string","minLength":1},"content":{"type":"array","minItems":1,"items":{"type":"object","additionalProperties":false,"required":["type","url"],"properties":{"type":{"type":"string","enum":["frame"],"description":"Dashboard Apps currently embed one frame content type."},"url":{"type":"string","format":"uri","pattern":"^https?://","description":"Absolute HTTP(S) frame URL without embedded credentials. Static query parameters and a fragment are preserved. Names beginning with `cl_` are reserved for the native V2 launch: the host removes static values in that namespace and writes only its allowlisted launch parameters. Never put credentials or personal data in the URL."},"sidebar_category":{"type":"string","enum":["support","contacts_crm","applications","commercial","productivity","automation","growth","analytics_config"],"default":"productivity","description":"Preferred native sidebar category. It is stored with the app definition because an app can have at most one sidebar installation, survives definition-only exports, and is exposed on that installation's resource."},"sidebar_icon":{"type":"string","enum":["panels_top_left","layout_dashboard","app_window","boxes","briefcase","bot","calendar_days","chart_no_axes_combined","circle_dollar_sign","clipboard_list","database","folder","globe_2","headphones","life_buoy","messages_square","package","rocket","shopping_bag","sparkles","workflow","wrench"],"default":"panels_top_left","description":"Allowlisted icon token used by the native sidebar item."}}}}}}}},"example":{"dashboard_app":{"title":"ERP Finance","content":[{"type":"frame","url":"https://erp.example/finance","sidebar_category":"applications","sidebar_icon":"rocket"}]}}}}}},"delete":{"tags":["Dashboard Apps"],"operationId":"auto_delete_api_v1_accounts_account_id_dashboard_apps_id","summary":"Delete a dashboard app","description":"Deletes the Dashboard App and its dependent installations; it never deletes external app data.","security":[{"userApiKey":[]}],"responses":{"204":{"description":"Dashboard App and dependent installations deleted."},"401":{"description":"Authentication or Dashboard App management permission is required.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string"}}},"example":{"error":"You are not authorized to do this action"}}}},"404":{"description":"No Dashboard App with this id belongs to the account.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string"}}},"example":{"error":"Resource could not be found"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/dashboard_app_installations/{id}/identity_assertion":{"post":{"tags":["Dashboard Apps"],"operationId":"auto_post_api_v1_accounts_account_id_dashboard_app_installations_id_identity_assertion","summary":"Mint a short-lived Dashboard App identity assertion","description":"Returns a two-minute, origin-bound signed assertion for the current authenticated member and this visible V2/dual installation. The installation must grant `identity:assertion`; email is included only with `current_user:email`. The assertion proves embedded user/account/install context to the app backend through public introspection, but is not a platform REST or MCP credential.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Short-lived signed identity assertion.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["assertion","token_type","expires_at","introspection_url"],"properties":{"assertion":{"type":"string","minLength":64,"maxLength":16384,"description":"Opaque signed JWT; pass it only to the documented introspection endpoint."},"token_type":{"type":"string","enum":["urn:conversalabs:dashboard-app-identity:v1"]},"expires_at":{"type":"string","format":"date-time"},"introspection_url":{"type":"string","format":"uri"}}},"example":{"assertion":"eyJhbGciOiJIUzI1NiIsInR5cCI6InVybjp...","token_type":"urn:conversalabs:dashboard-app-identity:v1","expires_at":"2026-08-21T12:02:00Z","introspection_url":"https://dashboard.example.com/dashboard-apps/v2/assertions/introspect"}}}},"401":{"description":"Authentication and active account membership are required.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string"}}},"example":{"error":"Authentication is required"}}}},"404":{"description":"Feature disabled, installation absent, outside the account, disabled, or outside the current member audience.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string"}}},"example":{"error":"resource_not_found"}}}},"403":{"description":"The identity capability is absent or the live installation can no longer mint identity.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","enum":["capability_denied","identity_unavailable","forbidden"]}}},"example":{"error":"capability_denied"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/dashboard_app_installations":{"get":{"tags":["Dashboard Apps"],"operationId":"auto_get_api_v1_accounts_account_id_dashboard_app_installations","summary":"List dashboard app installations","description":"Lists enabled installations visible to the authenticated member, or every installation for a manager. Manager rows outside their own runtime audience carry `visible: false`; management UIs may display them, but conversation/sidebar runtimes must not mount them. The optional surface filter is authoritative and audience details are omitted for ordinary agents.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Visible Dashboard App installations and the current account registry revision.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["payload","meta"],"properties":{"payload":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["id","dashboard_app","surface","compatibility_mode","enabled","visible","position","capabilities","transport_security","warnings","lock_version","updated_at"],"properties":{"id":{"type":"integer","minimum":1},"dashboard_app":{"type":"object","additionalProperties":false,"required":["id","title","url"],"properties":{"id":{"type":"integer","minimum":1},"title":{"type":"string","minLength":1},"url":{"type":"string","format":"uri","pattern":"^https?://"}}},"surface":{"type":"string","enum":["conversation","sidebar"]},"compatibility_mode":{"type":"string","enum":["legacy","v2","dual"]},"enabled":{"type":"boolean"},"visible":{"type":"boolean","description":"Operational visibility for the authenticated member after enabled state and audience are evaluated. Management lists may include `visible: false`; native runtimes must never mount it."},"position":{"type":"integer","minimum":0,"description":"Zero-based order after the server has resequenced the installation's surface and sidebar category."},"sidebar_category":{"type":"string","enum":["support","contacts_crm","applications","commercial","productivity","automation","growth","analytics_config"],"description":"Present only for sidebar installations; identifies the native category containing the direct menu item."},"sidebar_icon":{"type":"string","enum":["panels_top_left","layout_dashboard","app_window","boxes","briefcase","bot","calendar_days","chart_no_axes_combined","circle_dollar_sign","clipboard_list","database","folder","globe_2","headphones","life_buoy","messages_square","package","rocket","shopping_bag","sparkles","workflow","wrench"],"description":"Present only for sidebar installations; identifies the allowlisted icon rendered for the menu item."},"capabilities":{"type":"array","minItems":5,"uniqueItems":true,"description":"Closed, per-installation grant set. Core context capabilities are required. Conversation, contact, and message capabilities are valid only on the conversation surface. Personal-data fields and short-lived signed identity assertions are explicit grants; no API/session token is ever exposed.","items":{"type":"string","enum":["account:read","current_user:read","current_user:email","permissions:read","appearance:read","installation:read","conversation:read","contact:read","contact:email","contact:phone","messages:read","identity:assertion"]}},"audience":{"oneOf":[{"type":"object","additionalProperties":false,"required":["type"],"properties":{"type":{"type":"string","enum":["all"],"description":"Every active account member may see the installation."}}},{"type":"object","additionalProperties":false,"required":["type"],"properties":{"type":{"type":"string","enum":["any"],"description":"At least one role, team membership, or explicit user selector must match."},"roles":{"type":"array","uniqueItems":true,"default":[],"items":{"type":"string","enum":["agent","administrator"]}},"team_ids":{"type":"array","uniqueItems":true,"default":[],"items":{"type":"integer","minimum":1}},"user_ids":{"type":"array","uniqueItems":true,"default":[],"items":{"type":"integer","minimum":1}}},"anyOf":[{"type":"object","required":["roles"],"properties":{"roles":{"type":"array","minItems":1,"items":{"type":"string","enum":["agent","administrator"]}}}},{"type":"object","required":["team_ids"],"properties":{"team_ids":{"type":"array","minItems":1,"items":{"type":"integer","minimum":1}}}},{"type":"object","required":["user_ids"],"properties":{"user_ids":{"type":"array","minItems":1,"items":{"type":"integer","minimum":1}}}}]}],"discriminator":{"propertyName":"type"},"description":"Present only for callers allowed to manage installations; omitted for ordinary agents."},"transport_security":{"type":"string","enum":["secure_https","insecure_http"]},"warnings":{"type":"array","maxItems":1,"uniqueItems":true,"items":{"type":"string","enum":["insecure_http"]}},"lock_version":{"type":"integer","minimum":0},"updated_at":{"type":"string","format":"date-time"}}}},"meta":{"type":"object","additionalProperties":false,"required":["revision"],"properties":{"revision":{"type":"integer","minimum":0}}}}},"example":{"payload":[{"id":9,"dashboard_app":{"id":3,"title":"ERP","url":"http://erp.internal/panel"},"surface":"conversation","compatibility_mode":"dual","enabled":true,"visible":true,"position":0,"audience":{"type":"all"},"capabilities":["account:read","current_user:read","current_user:email","permissions:read","appearance:read","installation:read","conversation:read","contact:read","contact:email","contact:phone","messages:read","identity:assertion"],"transport_security":"insecure_http","warnings":["insecure_http"],"lock_version":2,"updated_at":"2026-08-21T12:00:00Z","sidebar_category":"support","sidebar_icon":"panels_top_left"}],"meta":{"revision":27}}}}},"401":{"description":"Authentication and active account membership are required.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string"}}},"example":{"error":"Authentication is required"}}}},"404":{"description":"Native Dashboard App surfaces are disabled for the account.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string"}}},"example":{"error":"resource_not_found"}}}},"403":{"description":"The authenticated principal cannot read Dashboard App installations.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string"}}},"example":{"error":"forbidden"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"surface","in":"query","required":false,"description":"Return installations for one native surface.","schema":{"type":"string","enum":["conversation","sidebar"]},"example":"conversation"}]},"post":{"tags":["Dashboard Apps"],"operationId":"auto_post_api_v1_accounts_account_id_dashboard_app_installations","summary":"Create a dashboard app installation","description":"Creates one account-scoped installation and atomically resequences its native surface.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Created Dashboard App installation.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["payload"],"properties":{"payload":{"type":"object","additionalProperties":false,"required":["id","dashboard_app","surface","compatibility_mode","enabled","visible","position","capabilities","transport_security","warnings","lock_version","updated_at"],"properties":{"id":{"type":"integer","minimum":1},"dashboard_app":{"type":"object","additionalProperties":false,"required":["id","title","url"],"properties":{"id":{"type":"integer","minimum":1},"title":{"type":"string","minLength":1},"url":{"type":"string","format":"uri","pattern":"^https?://"}}},"surface":{"type":"string","enum":["conversation","sidebar"]},"compatibility_mode":{"type":"string","enum":["legacy","v2","dual"]},"enabled":{"type":"boolean"},"visible":{"type":"boolean","description":"Operational visibility for the authenticated member after enabled state and audience are evaluated. Management lists may include `visible: false`; native runtimes must never mount it."},"position":{"type":"integer","minimum":0,"description":"Zero-based order after the server has resequenced the installation's surface and sidebar category."},"sidebar_category":{"type":"string","enum":["support","contacts_crm","applications","commercial","productivity","automation","growth","analytics_config"],"description":"Present only for sidebar installations; identifies the native category containing the direct menu item."},"sidebar_icon":{"type":"string","enum":["panels_top_left","layout_dashboard","app_window","boxes","briefcase","bot","calendar_days","chart_no_axes_combined","circle_dollar_sign","clipboard_list","database","folder","globe_2","headphones","life_buoy","messages_square","package","rocket","shopping_bag","sparkles","workflow","wrench"],"description":"Present only for sidebar installations; identifies the allowlisted icon rendered for the menu item."},"capabilities":{"type":"array","minItems":5,"uniqueItems":true,"description":"Closed, per-installation grant set. Core context capabilities are required. Conversation, contact, and message capabilities are valid only on the conversation surface. Personal-data fields and short-lived signed identity assertions are explicit grants; no API/session token is ever exposed.","items":{"type":"string","enum":["account:read","current_user:read","current_user:email","permissions:read","appearance:read","installation:read","conversation:read","contact:read","contact:email","contact:phone","messages:read","identity:assertion"]}},"audience":{"oneOf":[{"type":"object","additionalProperties":false,"required":["type"],"properties":{"type":{"type":"string","enum":["all"],"description":"Every active account member may see the installation."}}},{"type":"object","additionalProperties":false,"required":["type"],"properties":{"type":{"type":"string","enum":["any"],"description":"At least one role, team membership, or explicit user selector must match."},"roles":{"type":"array","uniqueItems":true,"default":[],"items":{"type":"string","enum":["agent","administrator"]}},"team_ids":{"type":"array","uniqueItems":true,"default":[],"items":{"type":"integer","minimum":1}},"user_ids":{"type":"array","uniqueItems":true,"default":[],"items":{"type":"integer","minimum":1}}},"anyOf":[{"type":"object","required":["roles"],"properties":{"roles":{"type":"array","minItems":1,"items":{"type":"string","enum":["agent","administrator"]}}}},{"type":"object","required":["team_ids"],"properties":{"team_ids":{"type":"array","minItems":1,"items":{"type":"integer","minimum":1}}}},{"type":"object","required":["user_ids"],"properties":{"user_ids":{"type":"array","minItems":1,"items":{"type":"integer","minimum":1}}}}]}],"discriminator":{"propertyName":"type"},"description":"Present only for callers allowed to manage installations; omitted for ordinary agents."},"transport_security":{"type":"string","enum":["secure_https","insecure_http"]},"warnings":{"type":"array","maxItems":1,"uniqueItems":true,"items":{"type":"string","enum":["insecure_http"]}},"lock_version":{"type":"integer","minimum":0},"updated_at":{"type":"string","format":"date-time"}}}}},"example":{"payload":{"id":9,"dashboard_app":{"id":3,"title":"ERP","url":"https://erp.example/panel"},"surface":"sidebar","compatibility_mode":"v2","enabled":true,"visible":true,"position":1,"sidebar_category":"commercial","sidebar_icon":"briefcase","capabilities":["account:read","current_user:read","current_user:email","permissions:read","appearance:read","installation:read","identity:assertion"],"audience":{"type":"any","roles":["administrator"],"team_ids":[],"user_ids":[]},"transport_security":"secure_https","warnings":[],"lock_version":0,"updated_at":"2026-08-21T12:00:00Z"}}}}},"401":{"description":"Authentication and active account membership are required.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string"}}},"example":{"error":"Authentication is required"}}}},"404":{"description":"Native Dashboard App surfaces are disabled for the account.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string"}}},"example":{"error":"resource_not_found"}}}},"403":{"description":"Dashboard App installation management permission is required.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string"}}},"example":{"error":"forbidden"}}}},"422":{"description":"The app, surface, mode, sidebar category, sidebar icon, position, URL, audience, or unique app-and-surface pair is invalid.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","enum":["invalid_dashboard_app","invalid_installation","invalid_audience","invalid_capabilities","invalid_sidebar_category","invalid_sidebar_icon","installation_already_exists","invalid_dashboard_app_url","dashboard_app_migration_required","unsafe_same_origin_v2"]}}},"example":{"error":"installation_already_exists"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["dashboard_app_installation"],"properties":{"dashboard_app_installation":{"type":"object","additionalProperties":false,"required":["dashboard_app_id"],"properties":{"dashboard_app_id":{"type":"integer","minimum":1},"surface":{"type":"string","enum":["conversation","sidebar"],"default":"conversation"},"compatibility_mode":{"type":"string","enum":["legacy","v2","dual"],"default":"legacy"},"enabled":{"type":"boolean","default":true},"position":{"type":"integer","minimum":0,"default":0,"description":"Zero-based order within the selected surface. Sidebar positions are scoped to `sidebar_category`; updating either field atomically resequences the previous and destination groups."},"sidebar_category":{"type":"string","enum":["support","contacts_crm","applications","commercial","productivity","automation","growth","analytics_config"],"default":"productivity","description":"Native category that directly contains a sidebar installation. Accepted only when `surface` is `sidebar`; omitted sidebar values use `productivity`."},"sidebar_icon":{"type":"string","enum":["panels_top_left","layout_dashboard","app_window","boxes","briefcase","bot","calendar_days","chart_no_axes_combined","circle_dollar_sign","clipboard_list","database","folder","globe_2","headphones","life_buoy","messages_square","package","rocket","shopping_bag","sparkles","workflow","wrench"],"default":"panels_top_left","description":"Allowlisted icon token for the direct native menu item. Accepted only when `surface` is `sidebar`; omitted sidebar values use `panels_top_left`."},"audience":{"oneOf":[{"type":"object","additionalProperties":false,"required":["type"],"properties":{"type":{"type":"string","enum":["all"],"description":"Every active account member may see the installation."}}},{"type":"object","additionalProperties":false,"required":["type"],"properties":{"type":{"type":"string","enum":["any"],"description":"At least one role, team membership, or explicit user selector must match."},"roles":{"type":"array","uniqueItems":true,"default":[],"items":{"type":"string","enum":["agent","administrator"]}},"team_ids":{"type":"array","uniqueItems":true,"default":[],"items":{"type":"integer","minimum":1}},"user_ids":{"type":"array","uniqueItems":true,"default":[],"items":{"type":"integer","minimum":1}}},"anyOf":[{"type":"object","required":["roles"],"properties":{"roles":{"type":"array","minItems":1,"items":{"type":"string","enum":["agent","administrator"]}}}},{"type":"object","required":["team_ids"],"properties":{"team_ids":{"type":"array","minItems":1,"items":{"type":"integer","minimum":1}}}},{"type":"object","required":["user_ids"],"properties":{"user_ids":{"type":"array","minItems":1,"items":{"type":"integer","minimum":1}}}}]}],"discriminator":{"propertyName":"type"},"default":{"type":"all"}},"capabilities":{"type":"array","minItems":5,"uniqueItems":true,"description":"Explicit V2/dual grants. When omitted, the server applies the complete useful default for the selected surface, including email, contact data where applicable, and signed identity. An explicit empty array is rejected as `invalid_capabilities`; remove only optional grants while preserving every capability required by the selected surface.","items":{"type":"string","enum":["account:read","current_user:read","current_user:email","permissions:read","appearance:read","installation:read","conversation:read","contact:read","contact:email","contact:phone","messages:read","identity:assertion"]}}}}}},"example":{"dashboard_app_installation":{"dashboard_app_id":3,"surface":"sidebar","compatibility_mode":"v2","enabled":true,"position":1,"sidebar_category":"commercial","sidebar_icon":"briefcase","capabilities":["account:read","current_user:read","current_user:email","permissions:read","appearance:read","installation:read","identity:assertion"],"audience":{"type":"any","roles":["administrator"],"team_ids":[],"user_ids":[]}}}}}}}},"/api/v1/accounts/{account_id}/dashboard_app_installations/{id}":{"get":{"tags":["Dashboard Apps"],"operationId":"auto_get_api_v1_accounts_account_id_dashboard_app_installations_id","summary":"Get a dashboard app installation","description":"Returns one installation only when it belongs to the account and is visible to the authenticated member.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Dashboard App installation.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["payload"],"properties":{"payload":{"type":"object","additionalProperties":false,"required":["id","dashboard_app","surface","compatibility_mode","enabled","visible","position","capabilities","transport_security","warnings","lock_version","updated_at"],"properties":{"id":{"type":"integer","minimum":1},"dashboard_app":{"type":"object","additionalProperties":false,"required":["id","title","url"],"properties":{"id":{"type":"integer","minimum":1},"title":{"type":"string","minLength":1},"url":{"type":"string","format":"uri","pattern":"^https?://"}}},"surface":{"type":"string","enum":["conversation","sidebar"]},"compatibility_mode":{"type":"string","enum":["legacy","v2","dual"]},"enabled":{"type":"boolean"},"visible":{"type":"boolean","description":"Operational visibility for the authenticated member after enabled state and audience are evaluated. Management lists may include `visible: false`; native runtimes must never mount it."},"position":{"type":"integer","minimum":0,"description":"Zero-based order after the server has resequenced the installation's surface and sidebar category."},"sidebar_category":{"type":"string","enum":["support","contacts_crm","applications","commercial","productivity","automation","growth","analytics_config"],"description":"Present only for sidebar installations; identifies the native category containing the direct menu item."},"sidebar_icon":{"type":"string","enum":["panels_top_left","layout_dashboard","app_window","boxes","briefcase","bot","calendar_days","chart_no_axes_combined","circle_dollar_sign","clipboard_list","database","folder","globe_2","headphones","life_buoy","messages_square","package","rocket","shopping_bag","sparkles","workflow","wrench"],"description":"Present only for sidebar installations; identifies the allowlisted icon rendered for the menu item."},"capabilities":{"type":"array","minItems":5,"uniqueItems":true,"description":"Closed, per-installation grant set. Core context capabilities are required. Conversation, contact, and message capabilities are valid only on the conversation surface. Personal-data fields and short-lived signed identity assertions are explicit grants; no API/session token is ever exposed.","items":{"type":"string","enum":["account:read","current_user:read","current_user:email","permissions:read","appearance:read","installation:read","conversation:read","contact:read","contact:email","contact:phone","messages:read","identity:assertion"]}},"audience":{"oneOf":[{"type":"object","additionalProperties":false,"required":["type"],"properties":{"type":{"type":"string","enum":["all"],"description":"Every active account member may see the installation."}}},{"type":"object","additionalProperties":false,"required":["type"],"properties":{"type":{"type":"string","enum":["any"],"description":"At least one role, team membership, or explicit user selector must match."},"roles":{"type":"array","uniqueItems":true,"default":[],"items":{"type":"string","enum":["agent","administrator"]}},"team_ids":{"type":"array","uniqueItems":true,"default":[],"items":{"type":"integer","minimum":1}},"user_ids":{"type":"array","uniqueItems":true,"default":[],"items":{"type":"integer","minimum":1}}},"anyOf":[{"type":"object","required":["roles"],"properties":{"roles":{"type":"array","minItems":1,"items":{"type":"string","enum":["agent","administrator"]}}}},{"type":"object","required":["team_ids"],"properties":{"team_ids":{"type":"array","minItems":1,"items":{"type":"integer","minimum":1}}}},{"type":"object","required":["user_ids"],"properties":{"user_ids":{"type":"array","minItems":1,"items":{"type":"integer","minimum":1}}}}]}],"discriminator":{"propertyName":"type"},"description":"Present only for callers allowed to manage installations; omitted for ordinary agents."},"transport_security":{"type":"string","enum":["secure_https","insecure_http"]},"warnings":{"type":"array","maxItems":1,"uniqueItems":true,"items":{"type":"string","enum":["insecure_http"]}},"lock_version":{"type":"integer","minimum":0},"updated_at":{"type":"string","format":"date-time"}}}}},"example":{"payload":{"id":9,"dashboard_app":{"id":3,"title":"ERP","url":"https://erp.example/panel"},"surface":"sidebar","compatibility_mode":"v2","enabled":true,"visible":true,"position":1,"sidebar_category":"applications","sidebar_icon":"rocket","capabilities":["account:read","current_user:read","current_user:email","permissions:read","appearance:read","installation:read","identity:assertion"],"transport_security":"secure_https","warnings":[],"lock_version":0,"updated_at":"2026-08-21T12:00:00Z","audience":{"type":"all"}}}}}},"401":{"description":"Authentication and active account membership are required.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string"}}},"example":{"error":"Authentication is required"}}}},"404":{"description":"Feature disabled, installation absent, outside the account, or outside the caller's audience.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string"}}},"example":{"error":"resource_not_found"}}}},"403":{"description":"The authenticated principal cannot read Dashboard App installations.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string"}}},"example":{"error":"forbidden"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]},"patch":{"tags":["Dashboard Apps"],"operationId":"auto_patch_api_v1_accounts_account_id_dashboard_app_installations_id","summary":"Update or reorder a dashboard app installation","description":"Updates the installation with optimistic locking. Setting `position`, `surface`, or `sidebar_category` moves it and atomically resequences the previous and destination groups; `sidebar_icon` changes the allowlisted menu icon without changing placement; `dashboard_app_id` is immutable.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Updated and resequenced Dashboard App installation.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["payload"],"properties":{"payload":{"type":"object","additionalProperties":false,"required":["id","dashboard_app","surface","compatibility_mode","enabled","visible","position","capabilities","transport_security","warnings","lock_version","updated_at"],"properties":{"id":{"type":"integer","minimum":1},"dashboard_app":{"type":"object","additionalProperties":false,"required":["id","title","url"],"properties":{"id":{"type":"integer","minimum":1},"title":{"type":"string","minLength":1},"url":{"type":"string","format":"uri","pattern":"^https?://"}}},"surface":{"type":"string","enum":["conversation","sidebar"]},"compatibility_mode":{"type":"string","enum":["legacy","v2","dual"]},"enabled":{"type":"boolean"},"visible":{"type":"boolean","description":"Operational visibility for the authenticated member after enabled state and audience are evaluated. Management lists may include `visible: false`; native runtimes must never mount it."},"position":{"type":"integer","minimum":0,"description":"Zero-based order after the server has resequenced the installation's surface and sidebar category."},"sidebar_category":{"type":"string","enum":["support","contacts_crm","applications","commercial","productivity","automation","growth","analytics_config"],"description":"Present only for sidebar installations; identifies the native category containing the direct menu item."},"sidebar_icon":{"type":"string","enum":["panels_top_left","layout_dashboard","app_window","boxes","briefcase","bot","calendar_days","chart_no_axes_combined","circle_dollar_sign","clipboard_list","database","folder","globe_2","headphones","life_buoy","messages_square","package","rocket","shopping_bag","sparkles","workflow","wrench"],"description":"Present only for sidebar installations; identifies the allowlisted icon rendered for the menu item."},"capabilities":{"type":"array","minItems":5,"uniqueItems":true,"description":"Closed, per-installation grant set. Core context capabilities are required. Conversation, contact, and message capabilities are valid only on the conversation surface. Personal-data fields and short-lived signed identity assertions are explicit grants; no API/session token is ever exposed.","items":{"type":"string","enum":["account:read","current_user:read","current_user:email","permissions:read","appearance:read","installation:read","conversation:read","contact:read","contact:email","contact:phone","messages:read","identity:assertion"]}},"audience":{"oneOf":[{"type":"object","additionalProperties":false,"required":["type"],"properties":{"type":{"type":"string","enum":["all"],"description":"Every active account member may see the installation."}}},{"type":"object","additionalProperties":false,"required":["type"],"properties":{"type":{"type":"string","enum":["any"],"description":"At least one role, team membership, or explicit user selector must match."},"roles":{"type":"array","uniqueItems":true,"default":[],"items":{"type":"string","enum":["agent","administrator"]}},"team_ids":{"type":"array","uniqueItems":true,"default":[],"items":{"type":"integer","minimum":1}},"user_ids":{"type":"array","uniqueItems":true,"default":[],"items":{"type":"integer","minimum":1}}},"anyOf":[{"type":"object","required":["roles"],"properties":{"roles":{"type":"array","minItems":1,"items":{"type":"string","enum":["agent","administrator"]}}}},{"type":"object","required":["team_ids"],"properties":{"team_ids":{"type":"array","minItems":1,"items":{"type":"integer","minimum":1}}}},{"type":"object","required":["user_ids"],"properties":{"user_ids":{"type":"array","minItems":1,"items":{"type":"integer","minimum":1}}}}]}],"discriminator":{"propertyName":"type"},"description":"Present only for callers allowed to manage installations; omitted for ordinary agents."},"transport_security":{"type":"string","enum":["secure_https","insecure_http"]},"warnings":{"type":"array","maxItems":1,"uniqueItems":true,"items":{"type":"string","enum":["insecure_http"]}},"lock_version":{"type":"integer","minimum":0},"updated_at":{"type":"string","format":"date-time"}}}}},"example":{"payload":{"id":9,"dashboard_app":{"id":3,"title":"ERP","url":"https://erp.example/panel"},"surface":"sidebar","compatibility_mode":"v2","enabled":true,"visible":true,"position":0,"sidebar_category":"growth","sidebar_icon":"rocket","capabilities":["account:read","current_user:read","current_user:email","permissions:read","appearance:read","installation:read","identity:assertion"],"audience":{"type":"all"},"transport_security":"secure_https","warnings":[],"lock_version":3,"updated_at":"2026-08-21T12:05:00Z"}}}}},"401":{"description":"Authentication and active account membership are required.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string"}}},"example":{"error":"Authentication is required"}}}},"404":{"description":"Feature disabled, installation absent, or installation belongs to another account.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string"}}},"example":{"error":"resource_not_found"}}}},"403":{"description":"Dashboard App installation management permission is required.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string"}}},"example":{"error":"forbidden"}}}},"409":{"description":"The supplied lock_version is stale; no requested change was applied.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","enum":["stale_installation"]}}},"example":{"error":"stale_installation"}}}},"422":{"description":"The surface, mode, sidebar category, sidebar icon, position, URL, audience, or unique app-and-surface pair is invalid.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","enum":["invalid_installation","invalid_audience","invalid_capabilities","invalid_sidebar_category","invalid_sidebar_icon","installation_already_exists","invalid_dashboard_app_url","dashboard_app_migration_required","unsafe_same_origin_v2"]}}},"example":{"error":"invalid_audience"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["dashboard_app_installation"],"properties":{"dashboard_app_installation":{"type":"object","additionalProperties":false,"minProperties":1,"properties":{"surface":{"type":"string","enum":["conversation","sidebar"],"default":"conversation"},"compatibility_mode":{"type":"string","enum":["legacy","v2","dual"],"default":"legacy"},"enabled":{"type":"boolean","default":true},"position":{"type":"integer","minimum":0,"default":0,"description":"Zero-based order within the selected surface. Sidebar positions are scoped to `sidebar_category`; updating either field atomically resequences the previous and destination groups."},"sidebar_category":{"type":"string","enum":["support","contacts_crm","applications","commercial","productivity","automation","growth","analytics_config"],"default":"productivity","description":"Native category that directly contains a sidebar installation. Accepted only when `surface` is `sidebar`; omitted sidebar values use `productivity`."},"sidebar_icon":{"type":"string","enum":["panels_top_left","layout_dashboard","app_window","boxes","briefcase","bot","calendar_days","chart_no_axes_combined","circle_dollar_sign","clipboard_list","database","folder","globe_2","headphones","life_buoy","messages_square","package","rocket","shopping_bag","sparkles","workflow","wrench"],"default":"panels_top_left","description":"Allowlisted icon token for the direct native menu item. Accepted only when `surface` is `sidebar`; omitted sidebar values use `panels_top_left`."},"audience":{"oneOf":[{"type":"object","additionalProperties":false,"required":["type"],"properties":{"type":{"type":"string","enum":["all"],"description":"Every active account member may see the installation."}}},{"type":"object","additionalProperties":false,"required":["type"],"properties":{"type":{"type":"string","enum":["any"],"description":"At least one role, team membership, or explicit user selector must match."},"roles":{"type":"array","uniqueItems":true,"default":[],"items":{"type":"string","enum":["agent","administrator"]}},"team_ids":{"type":"array","uniqueItems":true,"default":[],"items":{"type":"integer","minimum":1}},"user_ids":{"type":"array","uniqueItems":true,"default":[],"items":{"type":"integer","minimum":1}}},"anyOf":[{"type":"object","required":["roles"],"properties":{"roles":{"type":"array","minItems":1,"items":{"type":"string","enum":["agent","administrator"]}}}},{"type":"object","required":["team_ids"],"properties":{"team_ids":{"type":"array","minItems":1,"items":{"type":"integer","minimum":1}}}},{"type":"object","required":["user_ids"],"properties":{"user_ids":{"type":"array","minItems":1,"items":{"type":"integer","minimum":1}}}}]}],"discriminator":{"propertyName":"type"},"default":{"type":"all"}},"capabilities":{"type":"array","minItems":5,"uniqueItems":true,"description":"Explicit V2/dual grants. When omitted, the server applies the complete useful default for the selected surface, including email, contact data where applicable, and signed identity. An explicit empty array is rejected as `invalid_capabilities`; remove only optional grants while preserving every capability required by the selected surface.","items":{"type":"string","enum":["account:read","current_user:read","current_user:email","permissions:read","appearance:read","installation:read","conversation:read","contact:read","contact:email","contact:phone","messages:read","identity:assertion"]}},"lock_version":{"type":"integer","minimum":0}}}}},"example":{"dashboard_app_installation":{"sidebar_category":"growth","sidebar_icon":"rocket","position":0,"lock_version":2,"surface":"conversation","compatibility_mode":"legacy","enabled":true,"audience":{"type":"all"},"capabilities":["account:read"]}}}}}},"put":{"tags":["Dashboard Apps"],"operationId":"auto_put_api_v1_accounts_account_id_dashboard_app_installations_id","summary":"Update or reorder a dashboard app installation","description":"Updates the installation with optimistic locking. Setting `position`, `surface`, or `sidebar_category` moves it and atomically resequences the previous and destination groups; `sidebar_icon` changes the allowlisted menu icon without changing placement; `dashboard_app_id` is immutable.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Updated and resequenced Dashboard App installation.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["payload"],"properties":{"payload":{"type":"object","additionalProperties":false,"required":["id","dashboard_app","surface","compatibility_mode","enabled","visible","position","capabilities","transport_security","warnings","lock_version","updated_at"],"properties":{"id":{"type":"integer","minimum":1},"dashboard_app":{"type":"object","additionalProperties":false,"required":["id","title","url"],"properties":{"id":{"type":"integer","minimum":1},"title":{"type":"string","minLength":1},"url":{"type":"string","format":"uri","pattern":"^https?://"}}},"surface":{"type":"string","enum":["conversation","sidebar"]},"compatibility_mode":{"type":"string","enum":["legacy","v2","dual"]},"enabled":{"type":"boolean"},"visible":{"type":"boolean","description":"Operational visibility for the authenticated member after enabled state and audience are evaluated. Management lists may include `visible: false`; native runtimes must never mount it."},"position":{"type":"integer","minimum":0,"description":"Zero-based order after the server has resequenced the installation's surface and sidebar category."},"sidebar_category":{"type":"string","enum":["support","contacts_crm","applications","commercial","productivity","automation","growth","analytics_config"],"description":"Present only for sidebar installations; identifies the native category containing the direct menu item."},"sidebar_icon":{"type":"string","enum":["panels_top_left","layout_dashboard","app_window","boxes","briefcase","bot","calendar_days","chart_no_axes_combined","circle_dollar_sign","clipboard_list","database","folder","globe_2","headphones","life_buoy","messages_square","package","rocket","shopping_bag","sparkles","workflow","wrench"],"description":"Present only for sidebar installations; identifies the allowlisted icon rendered for the menu item."},"capabilities":{"type":"array","minItems":5,"uniqueItems":true,"description":"Closed, per-installation grant set. Core context capabilities are required. Conversation, contact, and message capabilities are valid only on the conversation surface. Personal-data fields and short-lived signed identity assertions are explicit grants; no API/session token is ever exposed.","items":{"type":"string","enum":["account:read","current_user:read","current_user:email","permissions:read","appearance:read","installation:read","conversation:read","contact:read","contact:email","contact:phone","messages:read","identity:assertion"]}},"audience":{"oneOf":[{"type":"object","additionalProperties":false,"required":["type"],"properties":{"type":{"type":"string","enum":["all"],"description":"Every active account member may see the installation."}}},{"type":"object","additionalProperties":false,"required":["type"],"properties":{"type":{"type":"string","enum":["any"],"description":"At least one role, team membership, or explicit user selector must match."},"roles":{"type":"array","uniqueItems":true,"default":[],"items":{"type":"string","enum":["agent","administrator"]}},"team_ids":{"type":"array","uniqueItems":true,"default":[],"items":{"type":"integer","minimum":1}},"user_ids":{"type":"array","uniqueItems":true,"default":[],"items":{"type":"integer","minimum":1}}},"anyOf":[{"type":"object","required":["roles"],"properties":{"roles":{"type":"array","minItems":1,"items":{"type":"string","enum":["agent","administrator"]}}}},{"type":"object","required":["team_ids"],"properties":{"team_ids":{"type":"array","minItems":1,"items":{"type":"integer","minimum":1}}}},{"type":"object","required":["user_ids"],"properties":{"user_ids":{"type":"array","minItems":1,"items":{"type":"integer","minimum":1}}}}]}],"discriminator":{"propertyName":"type"},"description":"Present only for callers allowed to manage installations; omitted for ordinary agents."},"transport_security":{"type":"string","enum":["secure_https","insecure_http"]},"warnings":{"type":"array","maxItems":1,"uniqueItems":true,"items":{"type":"string","enum":["insecure_http"]}},"lock_version":{"type":"integer","minimum":0},"updated_at":{"type":"string","format":"date-time"}}}}},"example":{"payload":{"id":9,"dashboard_app":{"id":3,"title":"ERP","url":"https://erp.example/panel"},"surface":"sidebar","compatibility_mode":"v2","enabled":true,"visible":true,"position":0,"sidebar_category":"growth","sidebar_icon":"rocket","capabilities":["account:read","current_user:read","current_user:email","permissions:read","appearance:read","installation:read","identity:assertion"],"audience":{"type":"all"},"transport_security":"secure_https","warnings":[],"lock_version":3,"updated_at":"2026-08-21T12:05:00Z"}}}}},"401":{"description":"Authentication and active account membership are required.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string"}}},"example":{"error":"Authentication is required"}}}},"404":{"description":"Feature disabled, installation absent, or installation belongs to another account.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string"}}},"example":{"error":"resource_not_found"}}}},"403":{"description":"Dashboard App installation management permission is required.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string"}}},"example":{"error":"forbidden"}}}},"409":{"description":"The supplied lock_version is stale; no requested change was applied.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","enum":["stale_installation"]}}},"example":{"error":"stale_installation"}}}},"422":{"description":"The surface, mode, sidebar category, sidebar icon, position, URL, audience, or unique app-and-surface pair is invalid.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","enum":["invalid_installation","invalid_audience","invalid_capabilities","invalid_sidebar_category","invalid_sidebar_icon","installation_already_exists","invalid_dashboard_app_url","dashboard_app_migration_required","unsafe_same_origin_v2"]}}},"example":{"error":"invalid_audience"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["dashboard_app_installation"],"properties":{"dashboard_app_installation":{"type":"object","additionalProperties":false,"minProperties":1,"properties":{"surface":{"type":"string","enum":["conversation","sidebar"],"default":"conversation"},"compatibility_mode":{"type":"string","enum":["legacy","v2","dual"],"default":"legacy"},"enabled":{"type":"boolean","default":true},"position":{"type":"integer","minimum":0,"default":0,"description":"Zero-based order within the selected surface. Sidebar positions are scoped to `sidebar_category`; updating either field atomically resequences the previous and destination groups."},"sidebar_category":{"type":"string","enum":["support","contacts_crm","applications","commercial","productivity","automation","growth","analytics_config"],"default":"productivity","description":"Native category that directly contains a sidebar installation. Accepted only when `surface` is `sidebar`; omitted sidebar values use `productivity`."},"sidebar_icon":{"type":"string","enum":["panels_top_left","layout_dashboard","app_window","boxes","briefcase","bot","calendar_days","chart_no_axes_combined","circle_dollar_sign","clipboard_list","database","folder","globe_2","headphones","life_buoy","messages_square","package","rocket","shopping_bag","sparkles","workflow","wrench"],"default":"panels_top_left","description":"Allowlisted icon token for the direct native menu item. Accepted only when `surface` is `sidebar`; omitted sidebar values use `panels_top_left`."},"audience":{"oneOf":[{"type":"object","additionalProperties":false,"required":["type"],"properties":{"type":{"type":"string","enum":["all"],"description":"Every active account member may see the installation."}}},{"type":"object","additionalProperties":false,"required":["type"],"properties":{"type":{"type":"string","enum":["any"],"description":"At least one role, team membership, or explicit user selector must match."},"roles":{"type":"array","uniqueItems":true,"default":[],"items":{"type":"string","enum":["agent","administrator"]}},"team_ids":{"type":"array","uniqueItems":true,"default":[],"items":{"type":"integer","minimum":1}},"user_ids":{"type":"array","uniqueItems":true,"default":[],"items":{"type":"integer","minimum":1}}},"anyOf":[{"type":"object","required":["roles"],"properties":{"roles":{"type":"array","minItems":1,"items":{"type":"string","enum":["agent","administrator"]}}}},{"type":"object","required":["team_ids"],"properties":{"team_ids":{"type":"array","minItems":1,"items":{"type":"integer","minimum":1}}}},{"type":"object","required":["user_ids"],"properties":{"user_ids":{"type":"array","minItems":1,"items":{"type":"integer","minimum":1}}}}]}],"discriminator":{"propertyName":"type"},"default":{"type":"all"}},"capabilities":{"type":"array","minItems":5,"uniqueItems":true,"description":"Explicit V2/dual grants. When omitted, the server applies the complete useful default for the selected surface, including email, contact data where applicable, and signed identity. An explicit empty array is rejected as `invalid_capabilities`; remove only optional grants while preserving every capability required by the selected surface.","items":{"type":"string","enum":["account:read","current_user:read","current_user:email","permissions:read","appearance:read","installation:read","conversation:read","contact:read","contact:email","contact:phone","messages:read","identity:assertion"]}},"lock_version":{"type":"integer","minimum":0}}}}},"example":{"dashboard_app_installation":{"sidebar_category":"growth","sidebar_icon":"rocket","position":0,"lock_version":2,"surface":"conversation","compatibility_mode":"legacy","enabled":true,"audience":{"type":"all"},"capabilities":["account:read"]}}}}}},"delete":{"tags":["Dashboard Apps"],"operationId":"auto_delete_api_v1_accounts_account_id_dashboard_app_installations_id","summary":"Delete a dashboard app installation","description":"Deletes only the installation, resequences its surface, and leaves the Dashboard App definition intact.","security":[{"userApiKey":[]}],"responses":{"204":{"description":"Installation deleted and its surface resequenced."},"401":{"description":"Authentication and active account membership are required.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string"}}},"example":{"error":"Authentication is required"}}}},"404":{"description":"Feature disabled, installation absent, or installation belongs to another account.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string"}}},"example":{"error":"resource_not_found"}}}},"403":{"description":"Dashboard App installation management permission is required.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string"}}},"example":{"error":"forbidden"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/bug_report_management/reports/{id}/history":{"get":{"tags":["Bug Reports"],"operationId":"auto_get_api_v1_accounts_account_id_bug_report_management_reports_id_history","summary":"Account bug reports history","description":"Authenticated Bug Reports operation. Uses the same domain authorization and command implementation as the console. Provider calls run only in committed workers.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Authorized response. Queued denotes local intent, never remote confirmation.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"kind":{"type":"string","description":"Open-ended domain event kind. History preserves persisted event kinds, including kinds introduced by later commands; clients must retain unknown values. Classified is one current event, not an exhaustive set.","example":"classified"},"revision":{"type":"integer"},"state":{"type":"string","enum":["pending","confirmed","uncertain","failed","superseded"]},"created_at":{"type":["string","null"],"format":"date-time"},"payload":{"type":"object","description":"Domain event projection, filtered to public payload unless read_internal is authorized.","additionalProperties":true},"author_name":{"type":["string","null"]}},"additionalProperties":false}},"meta":{"type":"object","properties":{"next_before_id":{"type":["integer","null"]}},"additionalProperties":false}},"additionalProperties":false},"example":{"payload":[{"id":1,"kind":"classified","revision":1,"state":"pending","created_at":"2026-01-15T10:30:00.000Z","payload":{},"author_name":"sample author name"}],"meta":{"next_before_id":1}}}}},"401":{"description":"Unauthorized"},"404":{"description":"The scoped record is absent.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["forbidden_scope","not_found","invalid_request","idempotency_required","idempotency_conflict","stale_revision","reason_required","summary_required","transition_pending","invalid_transition","invalid_classification","invalid_duplicate","invalid_authority","destination_unavailable","invalid_remote_clock","policy_blocked","stale_preview","preview_expired","invalid_selection","attachment_invalid","consent_required","delivery_in_flight","reconciliation_unavailable","preparation_failed","outbox_unavailable"]},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},"example":{"error":{"code":"forbidden_scope","message":"Sample message text."}}}}},"403":{"description":"The principal is outside the required scope.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["forbidden_scope","not_found","invalid_request","idempotency_required","idempotency_conflict","stale_revision","reason_required","summary_required","transition_pending","invalid_transition","invalid_classification","invalid_duplicate","invalid_authority","destination_unavailable","invalid_remote_clock","policy_blocked","stale_preview","preview_expired","invalid_selection","attachment_invalid","consent_required","delivery_in_flight","reconciliation_unavailable","preparation_failed","outbox_unavailable"]},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},"example":{"error":{"code":"forbidden_scope","message":"Sample message text."}}}}},"409":{"description":"The revision, pending intent or idempotency request conflicts.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["forbidden_scope","not_found","invalid_request","idempotency_required","idempotency_conflict","stale_revision","reason_required","summary_required","transition_pending","invalid_transition","invalid_classification","invalid_duplicate","invalid_authority","destination_unavailable","invalid_remote_clock","policy_blocked","stale_preview","preview_expired","invalid_selection","attachment_invalid","consent_required","delivery_in_flight","reconciliation_unavailable","preparation_failed","outbox_unavailable"]},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},"example":{"error":{"code":"forbidden_scope","message":"Sample message text."}}}}},"422":{"description":"The command or attachment is invalid.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["forbidden_scope","not_found","invalid_request","idempotency_required","idempotency_conflict","stale_revision","reason_required","summary_required","transition_pending","invalid_transition","invalid_classification","invalid_duplicate","invalid_authority","destination_unavailable","invalid_remote_clock","policy_blocked","stale_preview","preview_expired","invalid_selection","attachment_invalid","consent_required","delivery_in_flight","reconciliation_unavailable","preparation_failed","outbox_unavailable"]},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},"example":{"error":{"code":"forbidden_scope","message":"Sample message text."}}}}},"503":{"description":"The operation could not durably accept its required outbox work. No command effect is committed.","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["forbidden_scope","not_found","invalid_request","idempotency_required","idempotency_conflict","stale_revision","reason_required","summary_required","transition_pending","invalid_transition","invalid_classification","invalid_duplicate","invalid_authority","destination_unavailable","invalid_remote_clock","policy_blocked","stale_preview","preview_expired","invalid_selection","attachment_invalid","consent_required","delivery_in_flight","reconciliation_unavailable","preparation_failed","outbox_unavailable"]},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}]},"example":{"error":{"code":"forbidden_scope","message":"Sample message text."}}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"before_id","in":"query","required":false,"schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100}}]}},"/api/v1/accounts/{account_id}/bug_report_management/reports/{id}/messages":{"get":{"tags":["Bug Reports"],"operationId":"auto_get_api_v1_accounts_account_id_bug_report_management_reports_id_messages","summary":"Account bug reports messages","description":"Authenticated Bug Reports operation. Uses the same domain authorization and command implementation as the console. Provider calls run only in committed workers.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Authorized response. Queued denotes local intent, never remote confirmation.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"bug_report_id":{"type":"integer"},"author_kind":{"type":"string","enum":["reporter","maintainer","system","support"]},"author_name":{"type":["string","null"]},"user_id":{"type":["integer","null"]},"content":{"type":["string","null"]},"visibility":{"type":"string","enum":["public","internal"]},"origin":{"type":"string","enum":["local","account_linear","hub","install_linear"]},"client_uuid":{"type":["string","null"]},"system_key":{"type":["string","null"]},"delivery_state":{"type":"string","enum":["pending","sent","failed","skipped","uncertain","blocked"]},"created_at":{"type":["string","null"],"format":"date-time"},"edited_at":{"type":["string","null"],"format":"date-time"},"retracted_at":{"type":["string","null"],"format":"date-time"}},"additionalProperties":false}},"meta":{"type":"object","properties":{"current_page":{"type":"integer"},"total_pages":{"type":"integer"}},"additionalProperties":false}},"additionalProperties":false},"example":{"payload":[{"id":1,"bug_report_id":1,"author_kind":"reporter","author_name":"sample author name","user_id":1,"content":"Sample content text.","visibility":"public","origin":"local","client_uuid":"sample client uuid","system_key":"sample-token","delivery_state":"pending","created_at":"2026-01-15T10:30:00.000Z","edited_at":"2026-01-15T10:30:00.000Z","retracted_at":"2026-01-15T10:30:00.000Z"}],"meta":{"current_page":1,"total_pages":1}}}}},"401":{"description":"Unauthorized"},"404":{"description":"The scoped record is absent.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["forbidden_scope","not_found","invalid_request","idempotency_required","idempotency_conflict","stale_revision","reason_required","summary_required","transition_pending","invalid_transition","invalid_classification","invalid_duplicate","invalid_authority","destination_unavailable","invalid_remote_clock","policy_blocked","stale_preview","preview_expired","invalid_selection","attachment_invalid","consent_required","delivery_in_flight","reconciliation_unavailable","preparation_failed","outbox_unavailable"]},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},"example":{"error":{"code":"forbidden_scope","message":"Sample message text."}}}}},"403":{"description":"The principal is outside the required scope.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["forbidden_scope","not_found","invalid_request","idempotency_required","idempotency_conflict","stale_revision","reason_required","summary_required","transition_pending","invalid_transition","invalid_classification","invalid_duplicate","invalid_authority","destination_unavailable","invalid_remote_clock","policy_blocked","stale_preview","preview_expired","invalid_selection","attachment_invalid","consent_required","delivery_in_flight","reconciliation_unavailable","preparation_failed","outbox_unavailable"]},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},"example":{"error":{"code":"forbidden_scope","message":"Sample message text."}}}}},"409":{"description":"The revision, pending intent or idempotency request conflicts.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["forbidden_scope","not_found","invalid_request","idempotency_required","idempotency_conflict","stale_revision","reason_required","summary_required","transition_pending","invalid_transition","invalid_classification","invalid_duplicate","invalid_authority","destination_unavailable","invalid_remote_clock","policy_blocked","stale_preview","preview_expired","invalid_selection","attachment_invalid","consent_required","delivery_in_flight","reconciliation_unavailable","preparation_failed","outbox_unavailable"]},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},"example":{"error":{"code":"forbidden_scope","message":"Sample message text."}}}}},"422":{"description":"The command or attachment is invalid.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["forbidden_scope","not_found","invalid_request","idempotency_required","idempotency_conflict","stale_revision","reason_required","summary_required","transition_pending","invalid_transition","invalid_classification","invalid_duplicate","invalid_authority","destination_unavailable","invalid_remote_clock","policy_blocked","stale_preview","preview_expired","invalid_selection","attachment_invalid","consent_required","delivery_in_flight","reconciliation_unavailable","preparation_failed","outbox_unavailable"]},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},"example":{"error":{"code":"forbidden_scope","message":"Sample message text."}}}}},"503":{"description":"The operation could not durably accept its required outbox work. No command effect is committed.","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["forbidden_scope","not_found","invalid_request","idempotency_required","idempotency_conflict","stale_revision","reason_required","summary_required","transition_pending","invalid_transition","invalid_classification","invalid_duplicate","invalid_authority","destination_unavailable","invalid_remote_clock","policy_blocked","stale_preview","preview_expired","invalid_selection","attachment_invalid","consent_required","delivery_in_flight","reconciliation_unavailable","preparation_failed","outbox_unavailable"]},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}]},"example":{"error":{"code":"forbidden_scope","message":"Sample message text."}}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1}}]}},"/api/v1/accounts/{account_id}/bug_report_management/reports/{id}/classify":{"post":{"tags":["Bug Reports"],"operationId":"auto_post_api_v1_accounts_account_id_bug_report_management_reports_id_classify","summary":"Account bug reports classify","description":"Authenticated Bug Reports operation. Uses the same domain authorization and command implementation as the console. Provider calls run only in committed workers.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Authorized response. Queued denotes local intent, never remote confirmation.","content":{"application/json":{"schema":{"type":"object","properties":{"report":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"user_id":{"type":["integer","null"]},"title":{"type":"string"},"description":{"type":["string","null"]},"report_type":{"type":"string","enum":["bug","improvement","feature"]},"severity":{"type":"string","enum":["low","medium","high","urgent"]},"component":{"type":["string","null"]},"workflow_state":{"type":"string","enum":["received","triage","waiting_reporter","in_progress","resolved","closed","duplicate"]},"workflow_revision":{"type":"integer"},"state_authority":{"type":"string","enum":["local","install_linear"]},"transition_pending":{"type":"boolean"},"pending_workflow_state":{"type":["string","null"],"enum":["received","triage","waiting_reporter","in_progress","resolved","closed","duplicate",null]},"resolution_summary":{"type":["string","null"]},"messages_count":{"type":"integer"},"support_name":{"type":"string"},"support_url":{"type":["string","null"]},"attachments":{"type":"array","items":{"type":"object","properties":{"attachment_id":{"type":"integer"},"name":{"type":"string"},"content_type":{"type":"string"},"byte_size":{"type":"integer"},"url":{"type":"string"},"image":{"type":"boolean"},"video":{"type":"boolean"}},"additionalProperties":false}},"diagnostics":{"type":"object","description":"Authorized report diagnostics after the domain redactor and bounded metadata allowlist.","additionalProperties":true},"assignee_user_id":{"type":["integer","null"]},"classification":{"type":"object","description":"Classification set by the authorized classification command.","additionalProperties":true},"resolution_reason":{"type":["string","null"]},"linear_state_projection":{"type":"object","description":"Verified remote id/type/action projection maintained by the authority service.","additionalProperties":true},"linear":{"type":"object","properties":{"destination_kind":{"type":"string","enum":["none","install_linear","legacy_unknown"]},"state":{"type":"string","enum":["prepared","confirmed","blocked","uncertain","failed"]},"reason":{"type":["string","null"]}},"additionalProperties":false},"sharing":{"type":"object","properties":{"state":{"type":"string","enum":["not_shared","pending_approval","queued","prepared","sent","confirmed","uncertain","shared","blocked","failed"]},"reason":{"type":["string","null"]},"mode":{"type":"string","enum":["disabled","manual","automatic"]},"revision":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false,"required":["id","account_id","title","workflow_state","workflow_revision"]},"event":{"type":"object","properties":{"id":{"type":"integer"},"kind":{"type":"string","enum":["classified"]},"revision":{"type":"integer"},"state":{"type":"string","enum":["pending","confirmed","uncertain","failed","superseded"]}},"additionalProperties":false},"message":{"anyOf":[{"type":"object","properties":{"id":{"type":"integer"},"bug_report_id":{"type":"integer"},"author_kind":{"type":"string","enum":["reporter","maintainer","system","support"]},"author_name":{"type":["string","null"]},"user_id":{"type":["integer","null"]},"content":{"type":["string","null"]},"visibility":{"type":"string","enum":["public","internal"]},"origin":{"type":"string","enum":["local","account_linear","hub","install_linear"]},"client_uuid":{"type":["string","null"]},"system_key":{"type":["string","null"]},"delivery_state":{"type":"string","enum":["pending","sent","failed","skipped","uncertain","blocked"]},"created_at":{"type":["string","null"],"format":"date-time"},"edited_at":{"type":["string","null"],"format":"date-time"},"retracted_at":{"type":["string","null"],"format":"date-time"}},"additionalProperties":false},{"type":"null"}]}},"additionalProperties":false},"example":{"report":{"id":1,"account_id":1,"user_id":1,"title":"Sample title","description":"A short description.","report_type":"bug","severity":"low","component":"sample component","workflow_state":"received","workflow_revision":1,"state_authority":"local","transition_pending":true,"pending_workflow_state":"received","resolution_summary":"sample resolution summary","messages_count":5,"support_name":"sample support name","support_url":"https://example.com/resource","attachments":[{"attachment_id":1,"name":"Sample Name","content_type":"sample content type","byte_size":1,"url":"https://example.com/resource","image":true,"video":true}],"diagnostics":{},"assignee_user_id":1,"classification":{},"resolution_reason":"sample resolution reason","linear_state_projection":{},"linear":{"destination_kind":"none","state":"prepared","reason":"Sample reason."},"sharing":{"state":"not_shared","reason":"Sample reason.","mode":"disabled","revision":"sample revision"}},"event":{"id":1,"kind":"classified","revision":1,"state":"pending"},"message":{"id":1,"bug_report_id":1,"author_kind":"reporter","author_name":"sample author name","user_id":1,"content":"Sample content text.","visibility":"public","origin":"local","client_uuid":"sample client uuid","system_key":"sample-token","delivery_state":"pending","created_at":"2026-01-15T10:30:00.000Z","edited_at":"2026-01-15T10:30:00.000Z","retracted_at":"2026-01-15T10:30:00.000Z"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"The scoped record is absent.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["forbidden_scope","not_found","invalid_request","idempotency_required","idempotency_conflict","stale_revision","reason_required","summary_required","transition_pending","invalid_transition","invalid_classification","invalid_duplicate","invalid_authority","destination_unavailable","invalid_remote_clock","policy_blocked","stale_preview","preview_expired","invalid_selection","attachment_invalid","consent_required","delivery_in_flight","reconciliation_unavailable","preparation_failed","outbox_unavailable"]},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},"example":{"error":{"code":"forbidden_scope","message":"Sample message text."}}}}},"403":{"description":"The principal is outside the required scope.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["forbidden_scope","not_found","invalid_request","idempotency_required","idempotency_conflict","stale_revision","reason_required","summary_required","transition_pending","invalid_transition","invalid_classification","invalid_duplicate","invalid_authority","destination_unavailable","invalid_remote_clock","policy_blocked","stale_preview","preview_expired","invalid_selection","attachment_invalid","consent_required","delivery_in_flight","reconciliation_unavailable","preparation_failed","outbox_unavailable"]},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},"example":{"error":{"code":"forbidden_scope","message":"Sample message text."}}}}},"409":{"description":"The revision, pending intent or idempotency request conflicts.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["forbidden_scope","not_found","invalid_request","idempotency_required","idempotency_conflict","stale_revision","reason_required","summary_required","transition_pending","invalid_transition","invalid_classification","invalid_duplicate","invalid_authority","destination_unavailable","invalid_remote_clock","policy_blocked","stale_preview","preview_expired","invalid_selection","attachment_invalid","consent_required","delivery_in_flight","reconciliation_unavailable","preparation_failed","outbox_unavailable"]},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},"example":{"error":{"code":"forbidden_scope","message":"Sample message text."}}}}},"422":{"description":"The command or attachment is invalid.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["forbidden_scope","not_found","invalid_request","idempotency_required","idempotency_conflict","stale_revision","reason_required","summary_required","transition_pending","invalid_transition","invalid_classification","invalid_duplicate","invalid_authority","destination_unavailable","invalid_remote_clock","policy_blocked","stale_preview","preview_expired","invalid_selection","attachment_invalid","consent_required","delivery_in_flight","reconciliation_unavailable","preparation_failed","outbox_unavailable"]},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},"example":{"error":{"code":"forbidden_scope","message":"Sample message text."}}}}},"503":{"description":"The operation could not durably accept its required outbox work. No command effect is committed.","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["forbidden_scope","not_found","invalid_request","idempotency_required","idempotency_conflict","stale_revision","reason_required","summary_required","transition_pending","invalid_transition","invalid_classification","invalid_duplicate","invalid_authority","destination_unavailable","invalid_remote_clock","policy_blocked","stale_preview","preview_expired","invalid_selection","attachment_invalid","consent_required","delivery_in_flight","reconciliation_unavailable","preparation_failed","outbox_unavailable"]},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}]},"example":{"error":{"code":"forbidden_scope","message":"Sample message text."}}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"expected_revision":{"type":"integer","minimum":0},"idempotency_key":{"type":"string","minLength":1,"maxLength":128},"report_type":{"type":"string","enum":["bug","improvement","feature"]},"severity":{"type":"string","enum":["low","medium","high","urgent"]},"category":{"type":["string","null"]},"reason":{"type":"string","minLength":1,"maxLength":2000}},"additionalProperties":false,"required":["report_type","severity","reason","expected_revision","idempotency_key"]},"example":{"expected_revision":1,"idempotency_key":"sample-token","report_type":"bug","severity":"low","category":"sample category","reason":"Sample reason."}}}}}},"/api/v1/accounts/{account_id}/bug_report_management/reports/{id}/assign":{"post":{"tags":["Bug Reports"],"operationId":"auto_post_api_v1_accounts_account_id_bug_report_management_reports_id_assign","summary":"Account bug reports assign","description":"Authenticated Bug Reports operation. Uses the same domain authorization and command implementation as the console. Provider calls run only in committed workers.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Authorized response. Queued denotes local intent, never remote confirmation.","content":{"application/json":{"schema":{"type":"object","properties":{"report":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"user_id":{"type":["integer","null"]},"title":{"type":"string"},"description":{"type":["string","null"]},"report_type":{"type":"string","enum":["bug","improvement","feature"]},"severity":{"type":"string","enum":["low","medium","high","urgent"]},"component":{"type":["string","null"]},"workflow_state":{"type":"string","enum":["received","triage","waiting_reporter","in_progress","resolved","closed","duplicate"]},"workflow_revision":{"type":"integer"},"state_authority":{"type":"string","enum":["local","install_linear"]},"transition_pending":{"type":"boolean"},"pending_workflow_state":{"type":["string","null"],"enum":["received","triage","waiting_reporter","in_progress","resolved","closed","duplicate",null]},"resolution_summary":{"type":["string","null"]},"messages_count":{"type":"integer"},"support_name":{"type":"string"},"support_url":{"type":["string","null"]},"attachments":{"type":"array","items":{"type":"object","properties":{"attachment_id":{"type":"integer"},"name":{"type":"string"},"content_type":{"type":"string"},"byte_size":{"type":"integer"},"url":{"type":"string"},"image":{"type":"boolean"},"video":{"type":"boolean"}},"additionalProperties":false}},"diagnostics":{"type":"object","description":"Authorized report diagnostics after the domain redactor and bounded metadata allowlist.","additionalProperties":true},"assignee_user_id":{"type":["integer","null"]},"classification":{"type":"object","description":"Classification set by the authorized classification command.","additionalProperties":true},"resolution_reason":{"type":["string","null"]},"linear_state_projection":{"type":"object","description":"Verified remote id/type/action projection maintained by the authority service.","additionalProperties":true},"linear":{"type":"object","properties":{"destination_kind":{"type":"string","enum":["none","install_linear","legacy_unknown"]},"state":{"type":"string","enum":["prepared","confirmed","blocked","uncertain","failed"]},"reason":{"type":["string","null"]}},"additionalProperties":false},"sharing":{"type":"object","properties":{"state":{"type":"string","enum":["not_shared","pending_approval","queued","prepared","sent","confirmed","uncertain","shared","blocked","failed"]},"reason":{"type":["string","null"]},"mode":{"type":"string","enum":["disabled","manual","automatic"]},"revision":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false,"required":["id","account_id","title","workflow_state","workflow_revision"]},"event":{"type":"object","properties":{"id":{"type":"integer"},"kind":{"type":"string","enum":["assigned"]},"revision":{"type":"integer"},"state":{"type":"string","enum":["pending","confirmed","uncertain","failed","superseded"]}},"additionalProperties":false},"message":{"anyOf":[{"type":"object","properties":{"id":{"type":"integer"},"bug_report_id":{"type":"integer"},"author_kind":{"type":"string","enum":["reporter","maintainer","system","support"]},"author_name":{"type":["string","null"]},"user_id":{"type":["integer","null"]},"content":{"type":["string","null"]},"visibility":{"type":"string","enum":["public","internal"]},"origin":{"type":"string","enum":["local","account_linear","hub","install_linear"]},"client_uuid":{"type":["string","null"]},"system_key":{"type":["string","null"]},"delivery_state":{"type":"string","enum":["pending","sent","failed","skipped","uncertain","blocked"]},"created_at":{"type":["string","null"],"format":"date-time"},"edited_at":{"type":["string","null"],"format":"date-time"},"retracted_at":{"type":["string","null"],"format":"date-time"}},"additionalProperties":false},{"type":"null"}]}},"additionalProperties":false},"example":{"report":{"id":1,"account_id":1,"user_id":1,"title":"Sample title","description":"A short description.","report_type":"bug","severity":"low","component":"sample component","workflow_state":"received","workflow_revision":1,"state_authority":"local","transition_pending":true,"pending_workflow_state":"received","resolution_summary":"sample resolution summary","messages_count":5,"support_name":"sample support name","support_url":"https://example.com/resource","attachments":[{"attachment_id":1,"name":"Sample Name","content_type":"sample content type","byte_size":1,"url":"https://example.com/resource","image":true,"video":true}],"diagnostics":{},"assignee_user_id":1,"classification":{},"resolution_reason":"sample resolution reason","linear_state_projection":{},"linear":{"destination_kind":"none","state":"prepared","reason":"Sample reason."},"sharing":{"state":"not_shared","reason":"Sample reason.","mode":"disabled","revision":"sample revision"}},"event":{"id":1,"kind":"assigned","revision":1,"state":"pending"},"message":{"id":1,"bug_report_id":1,"author_kind":"reporter","author_name":"sample author name","user_id":1,"content":"Sample content text.","visibility":"public","origin":"local","client_uuid":"sample client uuid","system_key":"sample-token","delivery_state":"pending","created_at":"2026-01-15T10:30:00.000Z","edited_at":"2026-01-15T10:30:00.000Z","retracted_at":"2026-01-15T10:30:00.000Z"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"The scoped record is absent.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["forbidden_scope","not_found","invalid_request","idempotency_required","idempotency_conflict","stale_revision","reason_required","summary_required","transition_pending","invalid_transition","invalid_classification","invalid_duplicate","invalid_authority","destination_unavailable","invalid_remote_clock","policy_blocked","stale_preview","preview_expired","invalid_selection","attachment_invalid","consent_required","delivery_in_flight","reconciliation_unavailable","preparation_failed","outbox_unavailable"]},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},"example":{"error":{"code":"forbidden_scope","message":"Sample message text."}}}}},"403":{"description":"The principal is outside the required scope.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["forbidden_scope","not_found","invalid_request","idempotency_required","idempotency_conflict","stale_revision","reason_required","summary_required","transition_pending","invalid_transition","invalid_classification","invalid_duplicate","invalid_authority","destination_unavailable","invalid_remote_clock","policy_blocked","stale_preview","preview_expired","invalid_selection","attachment_invalid","consent_required","delivery_in_flight","reconciliation_unavailable","preparation_failed","outbox_unavailable"]},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},"example":{"error":{"code":"forbidden_scope","message":"Sample message text."}}}}},"409":{"description":"The revision, pending intent or idempotency request conflicts.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["forbidden_scope","not_found","invalid_request","idempotency_required","idempotency_conflict","stale_revision","reason_required","summary_required","transition_pending","invalid_transition","invalid_classification","invalid_duplicate","invalid_authority","destination_unavailable","invalid_remote_clock","policy_blocked","stale_preview","preview_expired","invalid_selection","attachment_invalid","consent_required","delivery_in_flight","reconciliation_unavailable","preparation_failed","outbox_unavailable"]},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},"example":{"error":{"code":"forbidden_scope","message":"Sample message text."}}}}},"422":{"description":"The command or attachment is invalid.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["forbidden_scope","not_found","invalid_request","idempotency_required","idempotency_conflict","stale_revision","reason_required","summary_required","transition_pending","invalid_transition","invalid_classification","invalid_duplicate","invalid_authority","destination_unavailable","invalid_remote_clock","policy_blocked","stale_preview","preview_expired","invalid_selection","attachment_invalid","consent_required","delivery_in_flight","reconciliation_unavailable","preparation_failed","outbox_unavailable"]},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},"example":{"error":{"code":"forbidden_scope","message":"Sample message text."}}}}},"503":{"description":"The operation could not durably accept its required outbox work. No command effect is committed.","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["forbidden_scope","not_found","invalid_request","idempotency_required","idempotency_conflict","stale_revision","reason_required","summary_required","transition_pending","invalid_transition","invalid_classification","invalid_duplicate","invalid_authority","destination_unavailable","invalid_remote_clock","policy_blocked","stale_preview","preview_expired","invalid_selection","attachment_invalid","consent_required","delivery_in_flight","reconciliation_unavailable","preparation_failed","outbox_unavailable"]},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}]},"example":{"error":{"code":"forbidden_scope","message":"Sample message text."}}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"expected_revision":{"type":"integer","minimum":0},"idempotency_key":{"type":"string","minLength":1,"maxLength":128},"assignee_user_id":{"type":["integer","null"]},"reason":{"type":"string","minLength":1,"maxLength":2000}},"additionalProperties":false,"required":["assignee_user_id","reason","expected_revision","idempotency_key"]},"example":{"expected_revision":1,"idempotency_key":"sample-token","assignee_user_id":1,"reason":"Sample reason."}}}}}},"/api/v1/accounts/{account_id}/bug_report_management/reports/{id}/transition":{"post":{"tags":["Bug Reports"],"operationId":"auto_post_api_v1_accounts_account_id_bug_report_management_reports_id_transition","summary":"Account bug reports transition","description":"Authenticated Bug Reports operation. Uses the same domain authorization and command implementation as the console. Provider calls run only in committed workers.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Authorized response. Queued denotes local intent, never remote confirmation.","content":{"application/json":{"schema":{"type":"object","properties":{"report":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"user_id":{"type":["integer","null"]},"title":{"type":"string"},"description":{"type":["string","null"]},"report_type":{"type":"string","enum":["bug","improvement","feature"]},"severity":{"type":"string","enum":["low","medium","high","urgent"]},"component":{"type":["string","null"]},"workflow_state":{"type":"string","enum":["received","triage","waiting_reporter","in_progress","resolved","closed","duplicate"]},"workflow_revision":{"type":"integer"},"state_authority":{"type":"string","enum":["local","install_linear"]},"transition_pending":{"type":"boolean"},"pending_workflow_state":{"type":["string","null"],"enum":["received","triage","waiting_reporter","in_progress","resolved","closed","duplicate",null]},"resolution_summary":{"type":["string","null"]},"messages_count":{"type":"integer"},"support_name":{"type":"string"},"support_url":{"type":["string","null"]},"attachments":{"type":"array","items":{"type":"object","properties":{"attachment_id":{"type":"integer"},"name":{"type":"string"},"content_type":{"type":"string"},"byte_size":{"type":"integer"},"url":{"type":"string"},"image":{"type":"boolean"},"video":{"type":"boolean"}},"additionalProperties":false}},"diagnostics":{"type":"object","description":"Authorized report diagnostics after the domain redactor and bounded metadata allowlist.","additionalProperties":true},"assignee_user_id":{"type":["integer","null"]},"classification":{"type":"object","description":"Classification set by the authorized classification command.","additionalProperties":true},"resolution_reason":{"type":["string","null"]},"linear_state_projection":{"type":"object","description":"Verified remote id/type/action projection maintained by the authority service.","additionalProperties":true},"linear":{"type":"object","properties":{"destination_kind":{"type":"string","enum":["none","install_linear","legacy_unknown"]},"state":{"type":"string","enum":["prepared","confirmed","blocked","uncertain","failed"]},"reason":{"type":["string","null"]}},"additionalProperties":false},"sharing":{"type":"object","properties":{"state":{"type":"string","enum":["not_shared","pending_approval","queued","prepared","sent","confirmed","uncertain","shared","blocked","failed"]},"reason":{"type":["string","null"]},"mode":{"type":"string","enum":["disabled","manual","automatic"]},"revision":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false,"required":["id","account_id","title","workflow_state","workflow_revision"]},"event":{"type":"object","properties":{"id":{"type":"integer"},"kind":{"type":"string","enum":["transition_requested"]},"revision":{"type":"integer"},"state":{"type":"string","enum":["pending","confirmed","uncertain","failed","superseded"]}},"additionalProperties":false},"message":{"anyOf":[{"type":"object","properties":{"id":{"type":"integer"},"bug_report_id":{"type":"integer"},"author_kind":{"type":"string","enum":["reporter","maintainer","system","support"]},"author_name":{"type":["string","null"]},"user_id":{"type":["integer","null"]},"content":{"type":["string","null"]},"visibility":{"type":"string","enum":["public","internal"]},"origin":{"type":"string","enum":["local","account_linear","hub","install_linear"]},"client_uuid":{"type":["string","null"]},"system_key":{"type":["string","null"]},"delivery_state":{"type":"string","enum":["pending","sent","failed","skipped","uncertain","blocked"]},"created_at":{"type":["string","null"],"format":"date-time"},"edited_at":{"type":["string","null"],"format":"date-time"},"retracted_at":{"type":["string","null"],"format":"date-time"}},"additionalProperties":false},{"type":"null"}]}},"additionalProperties":false},"example":{"report":{"id":1,"account_id":1,"user_id":1,"title":"Sample title","description":"A short description.","report_type":"bug","severity":"low","component":"sample component","workflow_state":"received","workflow_revision":1,"state_authority":"local","transition_pending":true,"pending_workflow_state":"received","resolution_summary":"sample resolution summary","messages_count":5,"support_name":"sample support name","support_url":"https://example.com/resource","attachments":[{"attachment_id":1,"name":"Sample Name","content_type":"sample content type","byte_size":1,"url":"https://example.com/resource","image":true,"video":true}],"diagnostics":{},"assignee_user_id":1,"classification":{},"resolution_reason":"sample resolution reason","linear_state_projection":{},"linear":{"destination_kind":"none","state":"prepared","reason":"Sample reason."},"sharing":{"state":"not_shared","reason":"Sample reason.","mode":"disabled","revision":"sample revision"}},"event":{"id":1,"kind":"transition_requested","revision":1,"state":"pending"},"message":{"id":1,"bug_report_id":1,"author_kind":"reporter","author_name":"sample author name","user_id":1,"content":"Sample content text.","visibility":"public","origin":"local","client_uuid":"sample client uuid","system_key":"sample-token","delivery_state":"pending","created_at":"2026-01-15T10:30:00.000Z","edited_at":"2026-01-15T10:30:00.000Z","retracted_at":"2026-01-15T10:30:00.000Z"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"The scoped record is absent.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["forbidden_scope","not_found","invalid_request","idempotency_required","idempotency_conflict","stale_revision","reason_required","summary_required","transition_pending","invalid_transition","invalid_classification","invalid_duplicate","invalid_authority","destination_unavailable","invalid_remote_clock","policy_blocked","stale_preview","preview_expired","invalid_selection","attachment_invalid","consent_required","delivery_in_flight","reconciliation_unavailable","preparation_failed","outbox_unavailable"]},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},"example":{"error":{"code":"forbidden_scope","message":"Sample message text."}}}}},"403":{"description":"The principal is outside the required scope.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["forbidden_scope","not_found","invalid_request","idempotency_required","idempotency_conflict","stale_revision","reason_required","summary_required","transition_pending","invalid_transition","invalid_classification","invalid_duplicate","invalid_authority","destination_unavailable","invalid_remote_clock","policy_blocked","stale_preview","preview_expired","invalid_selection","attachment_invalid","consent_required","delivery_in_flight","reconciliation_unavailable","preparation_failed","outbox_unavailable"]},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},"example":{"error":{"code":"forbidden_scope","message":"Sample message text."}}}}},"409":{"description":"The revision, pending intent or idempotency request conflicts.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["forbidden_scope","not_found","invalid_request","idempotency_required","idempotency_conflict","stale_revision","reason_required","summary_required","transition_pending","invalid_transition","invalid_classification","invalid_duplicate","invalid_authority","destination_unavailable","invalid_remote_clock","policy_blocked","stale_preview","preview_expired","invalid_selection","attachment_invalid","consent_required","delivery_in_flight","reconciliation_unavailable","preparation_failed","outbox_unavailable"]},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},"example":{"error":{"code":"forbidden_scope","message":"Sample message text."}}}}},"422":{"description":"The command or attachment is invalid.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["forbidden_scope","not_found","invalid_request","idempotency_required","idempotency_conflict","stale_revision","reason_required","summary_required","transition_pending","invalid_transition","invalid_classification","invalid_duplicate","invalid_authority","destination_unavailable","invalid_remote_clock","policy_blocked","stale_preview","preview_expired","invalid_selection","attachment_invalid","consent_required","delivery_in_flight","reconciliation_unavailable","preparation_failed","outbox_unavailable"]},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},"example":{"error":{"code":"forbidden_scope","message":"Sample message text."}}}}},"503":{"description":"The operation could not durably accept its required outbox work. No command effect is committed.","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["forbidden_scope","not_found","invalid_request","idempotency_required","idempotency_conflict","stale_revision","reason_required","summary_required","transition_pending","invalid_transition","invalid_classification","invalid_duplicate","invalid_authority","destination_unavailable","invalid_remote_clock","policy_blocked","stale_preview","preview_expired","invalid_selection","attachment_invalid","consent_required","delivery_in_flight","reconciliation_unavailable","preparation_failed","outbox_unavailable"]},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}]},"example":{"error":{"code":"forbidden_scope","message":"Sample message text."}}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"expected_revision":{"type":"integer","minimum":0},"idempotency_key":{"type":"string","minLength":1,"maxLength":128},"to":{"type":"string","enum":["received","triage","waiting_reporter","in_progress","resolved","closed","duplicate"]},"reason":{"type":"string","minLength":1,"maxLength":2000},"summary":{"type":"string","minLength":1},"duplicate_of_id":{"type":["integer","null"]}},"additionalProperties":false,"required":["to","reason","summary","expected_revision","idempotency_key"]},"example":{"expected_revision":1,"idempotency_key":"sample-token","to":"received","reason":"Sample reason.","summary":"sample summary","duplicate_of_id":1}}}}}},"/api/v1/accounts/{account_id}/bug_report_management/reports/{id}/reopen":{"post":{"tags":["Bug Reports"],"operationId":"auto_post_api_v1_accounts_account_id_bug_report_management_reports_id_reopen","summary":"Account bug reports reopen","description":"Authenticated Bug Reports operation. Uses the same domain authorization and command implementation as the console. Provider calls run only in committed workers.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Authorized response. Queued denotes local intent, never remote confirmation.","content":{"application/json":{"schema":{"type":"object","properties":{"report":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"user_id":{"type":["integer","null"]},"title":{"type":"string"},"description":{"type":["string","null"]},"report_type":{"type":"string","enum":["bug","improvement","feature"]},"severity":{"type":"string","enum":["low","medium","high","urgent"]},"component":{"type":["string","null"]},"workflow_state":{"type":"string","enum":["received","triage","waiting_reporter","in_progress","resolved","closed","duplicate"]},"workflow_revision":{"type":"integer"},"state_authority":{"type":"string","enum":["local","install_linear"]},"transition_pending":{"type":"boolean"},"pending_workflow_state":{"type":["string","null"],"enum":["received","triage","waiting_reporter","in_progress","resolved","closed","duplicate",null]},"resolution_summary":{"type":["string","null"]},"messages_count":{"type":"integer"},"support_name":{"type":"string"},"support_url":{"type":["string","null"]},"attachments":{"type":"array","items":{"type":"object","properties":{"attachment_id":{"type":"integer"},"name":{"type":"string"},"content_type":{"type":"string"},"byte_size":{"type":"integer"},"url":{"type":"string"},"image":{"type":"boolean"},"video":{"type":"boolean"}},"additionalProperties":false}},"diagnostics":{"type":"object","description":"Authorized report diagnostics after the domain redactor and bounded metadata allowlist.","additionalProperties":true},"assignee_user_id":{"type":["integer","null"]},"classification":{"type":"object","description":"Classification set by the authorized classification command.","additionalProperties":true},"resolution_reason":{"type":["string","null"]},"linear_state_projection":{"type":"object","description":"Verified remote id/type/action projection maintained by the authority service.","additionalProperties":true},"linear":{"type":"object","properties":{"destination_kind":{"type":"string","enum":["none","install_linear","legacy_unknown"]},"state":{"type":"string","enum":["prepared","confirmed","blocked","uncertain","failed"]},"reason":{"type":["string","null"]}},"additionalProperties":false},"sharing":{"type":"object","properties":{"state":{"type":"string","enum":["not_shared","pending_approval","queued","prepared","sent","confirmed","uncertain","shared","blocked","failed"]},"reason":{"type":["string","null"]},"mode":{"type":"string","enum":["disabled","manual","automatic"]},"revision":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false,"required":["id","account_id","title","workflow_state","workflow_revision"]},"event":{"type":"object","properties":{"id":{"type":"integer"},"kind":{"type":"string","enum":["transition_requested"]},"revision":{"type":"integer"},"state":{"type":"string","enum":["pending","confirmed","uncertain","failed","superseded"]}},"additionalProperties":false},"message":{"anyOf":[{"type":"object","properties":{"id":{"type":"integer"},"bug_report_id":{"type":"integer"},"author_kind":{"type":"string","enum":["reporter","maintainer","system","support"]},"author_name":{"type":["string","null"]},"user_id":{"type":["integer","null"]},"content":{"type":["string","null"]},"visibility":{"type":"string","enum":["public","internal"]},"origin":{"type":"string","enum":["local","account_linear","hub","install_linear"]},"client_uuid":{"type":["string","null"]},"system_key":{"type":["string","null"]},"delivery_state":{"type":"string","enum":["pending","sent","failed","skipped","uncertain","blocked"]},"created_at":{"type":["string","null"],"format":"date-time"},"edited_at":{"type":["string","null"],"format":"date-time"},"retracted_at":{"type":["string","null"],"format":"date-time"}},"additionalProperties":false},{"type":"null"}]}},"additionalProperties":false},"example":{"report":{"id":1,"account_id":1,"user_id":1,"title":"Sample title","description":"A short description.","report_type":"bug","severity":"low","component":"sample component","workflow_state":"received","workflow_revision":1,"state_authority":"local","transition_pending":true,"pending_workflow_state":"received","resolution_summary":"sample resolution summary","messages_count":5,"support_name":"sample support name","support_url":"https://example.com/resource","attachments":[{"attachment_id":1,"name":"Sample Name","content_type":"sample content type","byte_size":1,"url":"https://example.com/resource","image":true,"video":true}],"diagnostics":{},"assignee_user_id":1,"classification":{},"resolution_reason":"sample resolution reason","linear_state_projection":{},"linear":{"destination_kind":"none","state":"prepared","reason":"Sample reason."},"sharing":{"state":"not_shared","reason":"Sample reason.","mode":"disabled","revision":"sample revision"}},"event":{"id":1,"kind":"transition_requested","revision":1,"state":"pending"},"message":{"id":1,"bug_report_id":1,"author_kind":"reporter","author_name":"sample author name","user_id":1,"content":"Sample content text.","visibility":"public","origin":"local","client_uuid":"sample client uuid","system_key":"sample-token","delivery_state":"pending","created_at":"2026-01-15T10:30:00.000Z","edited_at":"2026-01-15T10:30:00.000Z","retracted_at":"2026-01-15T10:30:00.000Z"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"The scoped record is absent.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["forbidden_scope","not_found","invalid_request","idempotency_required","idempotency_conflict","stale_revision","reason_required","summary_required","transition_pending","invalid_transition","invalid_classification","invalid_duplicate","invalid_authority","destination_unavailable","invalid_remote_clock","policy_blocked","stale_preview","preview_expired","invalid_selection","attachment_invalid","consent_required","delivery_in_flight","reconciliation_unavailable","preparation_failed","outbox_unavailable"]},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},"example":{"error":{"code":"forbidden_scope","message":"Sample message text."}}}}},"403":{"description":"The principal is outside the required scope.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["forbidden_scope","not_found","invalid_request","idempotency_required","idempotency_conflict","stale_revision","reason_required","summary_required","transition_pending","invalid_transition","invalid_classification","invalid_duplicate","invalid_authority","destination_unavailable","invalid_remote_clock","policy_blocked","stale_preview","preview_expired","invalid_selection","attachment_invalid","consent_required","delivery_in_flight","reconciliation_unavailable","preparation_failed","outbox_unavailable"]},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},"example":{"error":{"code":"forbidden_scope","message":"Sample message text."}}}}},"409":{"description":"The revision, pending intent or idempotency request conflicts.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["forbidden_scope","not_found","invalid_request","idempotency_required","idempotency_conflict","stale_revision","reason_required","summary_required","transition_pending","invalid_transition","invalid_classification","invalid_duplicate","invalid_authority","destination_unavailable","invalid_remote_clock","policy_blocked","stale_preview","preview_expired","invalid_selection","attachment_invalid","consent_required","delivery_in_flight","reconciliation_unavailable","preparation_failed","outbox_unavailable"]},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},"example":{"error":{"code":"forbidden_scope","message":"Sample message text."}}}}},"422":{"description":"The command or attachment is invalid.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["forbidden_scope","not_found","invalid_request","idempotency_required","idempotency_conflict","stale_revision","reason_required","summary_required","transition_pending","invalid_transition","invalid_classification","invalid_duplicate","invalid_authority","destination_unavailable","invalid_remote_clock","policy_blocked","stale_preview","preview_expired","invalid_selection","attachment_invalid","consent_required","delivery_in_flight","reconciliation_unavailable","preparation_failed","outbox_unavailable"]},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},"example":{"error":{"code":"forbidden_scope","message":"Sample message text."}}}}},"503":{"description":"The operation could not durably accept its required outbox work. No command effect is committed.","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["forbidden_scope","not_found","invalid_request","idempotency_required","idempotency_conflict","stale_revision","reason_required","summary_required","transition_pending","invalid_transition","invalid_classification","invalid_duplicate","invalid_authority","destination_unavailable","invalid_remote_clock","policy_blocked","stale_preview","preview_expired","invalid_selection","attachment_invalid","consent_required","delivery_in_flight","reconciliation_unavailable","preparation_failed","outbox_unavailable"]},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}]},"example":{"error":{"code":"forbidden_scope","message":"Sample message text."}}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"expected_revision":{"type":"integer","minimum":0},"idempotency_key":{"type":"string","minLength":1,"maxLength":128},"reason":{"type":"string","minLength":1,"maxLength":2000},"summary":{"type":"string","minLength":1}},"additionalProperties":false,"required":["reason","summary","expected_revision","idempotency_key"]},"example":{"expected_revision":1,"idempotency_key":"sample-token","reason":"Sample reason.","summary":"sample summary"}}}}}},"/api/v1/accounts/{account_id}/bug_report_management/reports/{id}/reply":{"post":{"tags":["Bug Reports"],"operationId":"auto_post_api_v1_accounts_account_id_bug_report_management_reports_id_reply","summary":"Account bug reports reply","description":"Authenticated Bug Reports operation. Uses the same domain authorization and command implementation as the console. Provider calls run only in committed workers.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Authorized response. Queued denotes local intent, never remote confirmation.","content":{"application/json":{"schema":{"type":"object","properties":{"report":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"user_id":{"type":["integer","null"]},"title":{"type":"string"},"description":{"type":["string","null"]},"report_type":{"type":"string","enum":["bug","improvement","feature"]},"severity":{"type":"string","enum":["low","medium","high","urgent"]},"component":{"type":["string","null"]},"workflow_state":{"type":"string","enum":["received","triage","waiting_reporter","in_progress","resolved","closed","duplicate"]},"workflow_revision":{"type":"integer"},"state_authority":{"type":"string","enum":["local","install_linear"]},"transition_pending":{"type":"boolean"},"pending_workflow_state":{"type":["string","null"],"enum":["received","triage","waiting_reporter","in_progress","resolved","closed","duplicate",null]},"resolution_summary":{"type":["string","null"]},"messages_count":{"type":"integer"},"support_name":{"type":"string"},"support_url":{"type":["string","null"]},"attachments":{"type":"array","items":{"type":"object","properties":{"attachment_id":{"type":"integer"},"name":{"type":"string"},"content_type":{"type":"string"},"byte_size":{"type":"integer"},"url":{"type":"string"},"image":{"type":"boolean"},"video":{"type":"boolean"}},"additionalProperties":false}},"diagnostics":{"type":"object","description":"Authorized report diagnostics after the domain redactor and bounded metadata allowlist.","additionalProperties":true},"assignee_user_id":{"type":["integer","null"]},"classification":{"type":"object","description":"Classification set by the authorized classification command.","additionalProperties":true},"resolution_reason":{"type":["string","null"]},"linear_state_projection":{"type":"object","description":"Verified remote id/type/action projection maintained by the authority service.","additionalProperties":true},"linear":{"type":"object","properties":{"destination_kind":{"type":"string","enum":["none","install_linear","legacy_unknown"]},"state":{"type":"string","enum":["prepared","confirmed","blocked","uncertain","failed"]},"reason":{"type":["string","null"]}},"additionalProperties":false},"sharing":{"type":"object","properties":{"state":{"type":"string","enum":["not_shared","pending_approval","queued","prepared","sent","confirmed","uncertain","shared","blocked","failed"]},"reason":{"type":["string","null"]},"mode":{"type":"string","enum":["disabled","manual","automatic"]},"revision":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false,"required":["id","account_id","title","workflow_state","workflow_revision"]},"event":{"type":"object","properties":{"id":{"type":"integer"},"kind":{"type":"string","enum":["reporter_reply","support_reply"]},"revision":{"type":"integer"},"state":{"type":"string","enum":["pending","confirmed","uncertain","failed","superseded"]}},"additionalProperties":false},"message":{"anyOf":[{"type":"object","properties":{"id":{"type":"integer"},"bug_report_id":{"type":"integer"},"author_kind":{"type":"string","enum":["reporter","maintainer","system","support"]},"author_name":{"type":["string","null"]},"user_id":{"type":["integer","null"]},"content":{"type":["string","null"]},"visibility":{"type":"string","enum":["public","internal"]},"origin":{"type":"string","enum":["local","account_linear","hub","install_linear"]},"client_uuid":{"type":["string","null"]},"system_key":{"type":["string","null"]},"delivery_state":{"type":"string","enum":["pending","sent","failed","skipped","uncertain","blocked"]},"created_at":{"type":["string","null"],"format":"date-time"},"edited_at":{"type":["string","null"],"format":"date-time"},"retracted_at":{"type":["string","null"],"format":"date-time"}},"additionalProperties":false},{"type":"null"}]}},"additionalProperties":false},"example":{"report":{"id":1,"account_id":1,"user_id":1,"title":"Sample title","description":"A short description.","report_type":"bug","severity":"low","component":"sample component","workflow_state":"received","workflow_revision":1,"state_authority":"local","transition_pending":true,"pending_workflow_state":"received","resolution_summary":"sample resolution summary","messages_count":5,"support_name":"sample support name","support_url":"https://example.com/resource","attachments":[{"attachment_id":1,"name":"Sample Name","content_type":"sample content type","byte_size":1,"url":"https://example.com/resource","image":true,"video":true}],"diagnostics":{},"assignee_user_id":1,"classification":{},"resolution_reason":"sample resolution reason","linear_state_projection":{},"linear":{"destination_kind":"none","state":"prepared","reason":"Sample reason."},"sharing":{"state":"not_shared","reason":"Sample reason.","mode":"disabled","revision":"sample revision"}},"event":{"id":1,"kind":"reporter_reply","revision":1,"state":"pending"},"message":{"id":1,"bug_report_id":1,"author_kind":"reporter","author_name":"sample author name","user_id":1,"content":"Sample content text.","visibility":"public","origin":"local","client_uuid":"sample client uuid","system_key":"sample-token","delivery_state":"pending","created_at":"2026-01-15T10:30:00.000Z","edited_at":"2026-01-15T10:30:00.000Z","retracted_at":"2026-01-15T10:30:00.000Z"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"The scoped record is absent.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["forbidden_scope","not_found","invalid_request","idempotency_required","idempotency_conflict","stale_revision","reason_required","summary_required","transition_pending","invalid_transition","invalid_classification","invalid_duplicate","invalid_authority","destination_unavailable","invalid_remote_clock","policy_blocked","stale_preview","preview_expired","invalid_selection","attachment_invalid","consent_required","delivery_in_flight","reconciliation_unavailable","preparation_failed","outbox_unavailable"]},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},"example":{"error":{"code":"forbidden_scope","message":"Sample message text."}}}}},"403":{"description":"The principal is outside the required scope.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["forbidden_scope","not_found","invalid_request","idempotency_required","idempotency_conflict","stale_revision","reason_required","summary_required","transition_pending","invalid_transition","invalid_classification","invalid_duplicate","invalid_authority","destination_unavailable","invalid_remote_clock","policy_blocked","stale_preview","preview_expired","invalid_selection","attachment_invalid","consent_required","delivery_in_flight","reconciliation_unavailable","preparation_failed","outbox_unavailable"]},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},"example":{"error":{"code":"forbidden_scope","message":"Sample message text."}}}}},"409":{"description":"The revision, pending intent or idempotency request conflicts.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["forbidden_scope","not_found","invalid_request","idempotency_required","idempotency_conflict","stale_revision","reason_required","summary_required","transition_pending","invalid_transition","invalid_classification","invalid_duplicate","invalid_authority","destination_unavailable","invalid_remote_clock","policy_blocked","stale_preview","preview_expired","invalid_selection","attachment_invalid","consent_required","delivery_in_flight","reconciliation_unavailable","preparation_failed","outbox_unavailable"]},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},"example":{"error":{"code":"forbidden_scope","message":"Sample message text."}}}}},"422":{"description":"The command or attachment is invalid.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["forbidden_scope","not_found","invalid_request","idempotency_required","idempotency_conflict","stale_revision","reason_required","summary_required","transition_pending","invalid_transition","invalid_classification","invalid_duplicate","invalid_authority","destination_unavailable","invalid_remote_clock","policy_blocked","stale_preview","preview_expired","invalid_selection","attachment_invalid","consent_required","delivery_in_flight","reconciliation_unavailable","preparation_failed","outbox_unavailable"]},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},"example":{"error":{"code":"forbidden_scope","message":"Sample message text."}}}}},"503":{"description":"The operation could not durably accept its required outbox work. No command effect is committed.","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["forbidden_scope","not_found","invalid_request","idempotency_required","idempotency_conflict","stale_revision","reason_required","summary_required","transition_pending","invalid_transition","invalid_classification","invalid_duplicate","invalid_authority","destination_unavailable","invalid_remote_clock","policy_blocked","stale_preview","preview_expired","invalid_selection","attachment_invalid","consent_required","delivery_in_flight","reconciliation_unavailable","preparation_failed","outbox_unavailable"]},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}]},"example":{"error":{"code":"forbidden_scope","message":"Sample message text."}}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"expected_revision":{"type":"integer","minimum":0},"idempotency_key":{"type":"string","minLength":1,"maxLength":128},"content":{"type":"string","minLength":1,"maxLength":5000}},"additionalProperties":false,"required":["content","expected_revision","idempotency_key"]},"example":{"expected_revision":1,"idempotency_key":"sample-token","content":"Sample content text."}}}}}},"/api/v1/accounts/{account_id}/bug_report_management/reports/{id}/note":{"post":{"tags":["Bug Reports"],"operationId":"auto_post_api_v1_accounts_account_id_bug_report_management_reports_id_note","summary":"Account bug reports note","description":"Authenticated Bug Reports operation. Uses the same domain authorization and command implementation as the console. Provider calls run only in committed workers.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Authorized response. Queued denotes local intent, never remote confirmation.","content":{"application/json":{"schema":{"type":"object","properties":{"report":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"user_id":{"type":["integer","null"]},"title":{"type":"string"},"description":{"type":["string","null"]},"report_type":{"type":"string","enum":["bug","improvement","feature"]},"severity":{"type":"string","enum":["low","medium","high","urgent"]},"component":{"type":["string","null"]},"workflow_state":{"type":"string","enum":["received","triage","waiting_reporter","in_progress","resolved","closed","duplicate"]},"workflow_revision":{"type":"integer"},"state_authority":{"type":"string","enum":["local","install_linear"]},"transition_pending":{"type":"boolean"},"pending_workflow_state":{"type":["string","null"],"enum":["received","triage","waiting_reporter","in_progress","resolved","closed","duplicate",null]},"resolution_summary":{"type":["string","null"]},"messages_count":{"type":"integer"},"support_name":{"type":"string"},"support_url":{"type":["string","null"]},"attachments":{"type":"array","items":{"type":"object","properties":{"attachment_id":{"type":"integer"},"name":{"type":"string"},"content_type":{"type":"string"},"byte_size":{"type":"integer"},"url":{"type":"string"},"image":{"type":"boolean"},"video":{"type":"boolean"}},"additionalProperties":false}},"diagnostics":{"type":"object","description":"Authorized report diagnostics after the domain redactor and bounded metadata allowlist.","additionalProperties":true},"assignee_user_id":{"type":["integer","null"]},"classification":{"type":"object","description":"Classification set by the authorized classification command.","additionalProperties":true},"resolution_reason":{"type":["string","null"]},"linear_state_projection":{"type":"object","description":"Verified remote id/type/action projection maintained by the authority service.","additionalProperties":true},"linear":{"type":"object","properties":{"destination_kind":{"type":"string","enum":["none","install_linear","legacy_unknown"]},"state":{"type":"string","enum":["prepared","confirmed","blocked","uncertain","failed"]},"reason":{"type":["string","null"]}},"additionalProperties":false},"sharing":{"type":"object","properties":{"state":{"type":"string","enum":["not_shared","pending_approval","queued","prepared","sent","confirmed","uncertain","shared","blocked","failed"]},"reason":{"type":["string","null"]},"mode":{"type":"string","enum":["disabled","manual","automatic"]},"revision":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false,"required":["id","account_id","title","workflow_state","workflow_revision"]},"event":{"type":"object","properties":{"id":{"type":"integer"},"kind":{"type":"string","enum":["private_note"]},"revision":{"type":"integer"},"state":{"type":"string","enum":["pending","confirmed","uncertain","failed","superseded"]}},"additionalProperties":false},"message":{"anyOf":[{"type":"object","properties":{"id":{"type":"integer"},"bug_report_id":{"type":"integer"},"author_kind":{"type":"string","enum":["reporter","maintainer","system","support"]},"author_name":{"type":["string","null"]},"user_id":{"type":["integer","null"]},"content":{"type":["string","null"]},"visibility":{"type":"string","enum":["public","internal"]},"origin":{"type":"string","enum":["local","account_linear","hub","install_linear"]},"client_uuid":{"type":["string","null"]},"system_key":{"type":["string","null"]},"delivery_state":{"type":"string","enum":["pending","sent","failed","skipped","uncertain","blocked"]},"created_at":{"type":["string","null"],"format":"date-time"},"edited_at":{"type":["string","null"],"format":"date-time"},"retracted_at":{"type":["string","null"],"format":"date-time"}},"additionalProperties":false},{"type":"null"}]}},"additionalProperties":false},"example":{"report":{"id":1,"account_id":1,"user_id":1,"title":"Sample title","description":"A short description.","report_type":"bug","severity":"low","component":"sample component","workflow_state":"received","workflow_revision":1,"state_authority":"local","transition_pending":true,"pending_workflow_state":"received","resolution_summary":"sample resolution summary","messages_count":5,"support_name":"sample support name","support_url":"https://example.com/resource","attachments":[{"attachment_id":1,"name":"Sample Name","content_type":"sample content type","byte_size":1,"url":"https://example.com/resource","image":true,"video":true}],"diagnostics":{},"assignee_user_id":1,"classification":{},"resolution_reason":"sample resolution reason","linear_state_projection":{},"linear":{"destination_kind":"none","state":"prepared","reason":"Sample reason."},"sharing":{"state":"not_shared","reason":"Sample reason.","mode":"disabled","revision":"sample revision"}},"event":{"id":1,"kind":"private_note","revision":1,"state":"pending"},"message":{"id":1,"bug_report_id":1,"author_kind":"reporter","author_name":"sample author name","user_id":1,"content":"Sample content text.","visibility":"public","origin":"local","client_uuid":"sample client uuid","system_key":"sample-token","delivery_state":"pending","created_at":"2026-01-15T10:30:00.000Z","edited_at":"2026-01-15T10:30:00.000Z","retracted_at":"2026-01-15T10:30:00.000Z"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"The scoped record is absent.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["forbidden_scope","not_found","invalid_request","idempotency_required","idempotency_conflict","stale_revision","reason_required","summary_required","transition_pending","invalid_transition","invalid_classification","invalid_duplicate","invalid_authority","destination_unavailable","invalid_remote_clock","policy_blocked","stale_preview","preview_expired","invalid_selection","attachment_invalid","consent_required","delivery_in_flight","reconciliation_unavailable","preparation_failed","outbox_unavailable"]},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},"example":{"error":{"code":"forbidden_scope","message":"Sample message text."}}}}},"403":{"description":"The principal is outside the required scope.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["forbidden_scope","not_found","invalid_request","idempotency_required","idempotency_conflict","stale_revision","reason_required","summary_required","transition_pending","invalid_transition","invalid_classification","invalid_duplicate","invalid_authority","destination_unavailable","invalid_remote_clock","policy_blocked","stale_preview","preview_expired","invalid_selection","attachment_invalid","consent_required","delivery_in_flight","reconciliation_unavailable","preparation_failed","outbox_unavailable"]},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},"example":{"error":{"code":"forbidden_scope","message":"Sample message text."}}}}},"409":{"description":"The revision, pending intent or idempotency request conflicts.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["forbidden_scope","not_found","invalid_request","idempotency_required","idempotency_conflict","stale_revision","reason_required","summary_required","transition_pending","invalid_transition","invalid_classification","invalid_duplicate","invalid_authority","destination_unavailable","invalid_remote_clock","policy_blocked","stale_preview","preview_expired","invalid_selection","attachment_invalid","consent_required","delivery_in_flight","reconciliation_unavailable","preparation_failed","outbox_unavailable"]},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},"example":{"error":{"code":"forbidden_scope","message":"Sample message text."}}}}},"422":{"description":"The command or attachment is invalid.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["forbidden_scope","not_found","invalid_request","idempotency_required","idempotency_conflict","stale_revision","reason_required","summary_required","transition_pending","invalid_transition","invalid_classification","invalid_duplicate","invalid_authority","destination_unavailable","invalid_remote_clock","policy_blocked","stale_preview","preview_expired","invalid_selection","attachment_invalid","consent_required","delivery_in_flight","reconciliation_unavailable","preparation_failed","outbox_unavailable"]},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},"example":{"error":{"code":"forbidden_scope","message":"Sample message text."}}}}},"503":{"description":"The operation could not durably accept its required outbox work. No command effect is committed.","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["forbidden_scope","not_found","invalid_request","idempotency_required","idempotency_conflict","stale_revision","reason_required","summary_required","transition_pending","invalid_transition","invalid_classification","invalid_duplicate","invalid_authority","destination_unavailable","invalid_remote_clock","policy_blocked","stale_preview","preview_expired","invalid_selection","attachment_invalid","consent_required","delivery_in_flight","reconciliation_unavailable","preparation_failed","outbox_unavailable"]},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}]},"example":{"error":{"code":"forbidden_scope","message":"Sample message text."}}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"expected_revision":{"type":"integer","minimum":0},"idempotency_key":{"type":"string","minLength":1,"maxLength":128},"content":{"type":"string","minLength":1,"maxLength":5000}},"additionalProperties":false,"required":["content","expected_revision","idempotency_key"]},"example":{"expected_revision":1,"idempotency_key":"sample-token","content":"Sample content text."}}}}}},"/api/v1/accounts/{account_id}/bug_report_management/reports/{id}/revise":{"post":{"tags":["Bug Reports"],"operationId":"auto_post_api_v1_accounts_account_id_bug_report_management_reports_id_revise","summary":"Account bug reports revise","description":"Authenticated Bug Reports operation. Uses the same domain authorization and command implementation as the console. Provider calls run only in committed workers.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Authorized response. Queued denotes local intent, never remote confirmation.","content":{"application/json":{"schema":{"type":"object","properties":{"report":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"user_id":{"type":["integer","null"]},"title":{"type":"string"},"description":{"type":["string","null"]},"report_type":{"type":"string","enum":["bug","improvement","feature"]},"severity":{"type":"string","enum":["low","medium","high","urgent"]},"component":{"type":["string","null"]},"workflow_state":{"type":"string","enum":["received","triage","waiting_reporter","in_progress","resolved","closed","duplicate"]},"workflow_revision":{"type":"integer"},"state_authority":{"type":"string","enum":["local","install_linear"]},"transition_pending":{"type":"boolean"},"pending_workflow_state":{"type":["string","null"],"enum":["received","triage","waiting_reporter","in_progress","resolved","closed","duplicate",null]},"resolution_summary":{"type":["string","null"]},"messages_count":{"type":"integer"},"support_name":{"type":"string"},"support_url":{"type":["string","null"]},"attachments":{"type":"array","items":{"type":"object","properties":{"attachment_id":{"type":"integer"},"name":{"type":"string"},"content_type":{"type":"string"},"byte_size":{"type":"integer"},"url":{"type":"string"},"image":{"type":"boolean"},"video":{"type":"boolean"}},"additionalProperties":false}},"diagnostics":{"type":"object","description":"Authorized report diagnostics after the domain redactor and bounded metadata allowlist.","additionalProperties":true},"assignee_user_id":{"type":["integer","null"]},"classification":{"type":"object","description":"Classification set by the authorized classification command.","additionalProperties":true},"resolution_reason":{"type":["string","null"]},"linear_state_projection":{"type":"object","description":"Verified remote id/type/action projection maintained by the authority service.","additionalProperties":true},"linear":{"type":"object","properties":{"destination_kind":{"type":"string","enum":["none","install_linear","legacy_unknown"]},"state":{"type":"string","enum":["prepared","confirmed","blocked","uncertain","failed"]},"reason":{"type":["string","null"]}},"additionalProperties":false},"sharing":{"type":"object","properties":{"state":{"type":"string","enum":["not_shared","pending_approval","queued","prepared","sent","confirmed","uncertain","shared","blocked","failed"]},"reason":{"type":["string","null"]},"mode":{"type":"string","enum":["disabled","manual","automatic"]},"revision":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false,"required":["id","account_id","title","workflow_state","workflow_revision"]},"event":{"type":"object","properties":{"id":{"type":"integer"},"kind":{"type":"string","enum":["message_edited","message_retracted"]},"revision":{"type":"integer"},"state":{"type":"string","enum":["pending","confirmed","uncertain","failed","superseded"]}},"additionalProperties":false},"message":{"anyOf":[{"type":"object","properties":{"id":{"type":"integer"},"bug_report_id":{"type":"integer"},"author_kind":{"type":"string","enum":["reporter","maintainer","system","support"]},"author_name":{"type":["string","null"]},"user_id":{"type":["integer","null"]},"content":{"type":["string","null"]},"visibility":{"type":"string","enum":["public","internal"]},"origin":{"type":"string","enum":["local","account_linear","hub","install_linear"]},"client_uuid":{"type":["string","null"]},"system_key":{"type":["string","null"]},"delivery_state":{"type":"string","enum":["pending","sent","failed","skipped","uncertain","blocked"]},"created_at":{"type":["string","null"],"format":"date-time"},"edited_at":{"type":["string","null"],"format":"date-time"},"retracted_at":{"type":["string","null"],"format":"date-time"}},"additionalProperties":false},{"type":"null"}]}},"additionalProperties":false},"example":{"report":{"id":1,"account_id":1,"user_id":1,"title":"Sample title","description":"A short description.","report_type":"bug","severity":"low","component":"sample component","workflow_state":"received","workflow_revision":1,"state_authority":"local","transition_pending":true,"pending_workflow_state":"received","resolution_summary":"sample resolution summary","messages_count":5,"support_name":"sample support name","support_url":"https://example.com/resource","attachments":[{"attachment_id":1,"name":"Sample Name","content_type":"sample content type","byte_size":1,"url":"https://example.com/resource","image":true,"video":true}],"diagnostics":{},"assignee_user_id":1,"classification":{},"resolution_reason":"sample resolution reason","linear_state_projection":{},"linear":{"destination_kind":"none","state":"prepared","reason":"Sample reason."},"sharing":{"state":"not_shared","reason":"Sample reason.","mode":"disabled","revision":"sample revision"}},"event":{"id":1,"kind":"message_edited","revision":1,"state":"pending"},"message":{"id":1,"bug_report_id":1,"author_kind":"reporter","author_name":"sample author name","user_id":1,"content":"Sample content text.","visibility":"public","origin":"local","client_uuid":"sample client uuid","system_key":"sample-token","delivery_state":"pending","created_at":"2026-01-15T10:30:00.000Z","edited_at":"2026-01-15T10:30:00.000Z","retracted_at":"2026-01-15T10:30:00.000Z"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"The scoped record is absent.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["forbidden_scope","not_found","invalid_request","idempotency_required","idempotency_conflict","stale_revision","reason_required","summary_required","transition_pending","invalid_transition","invalid_classification","invalid_duplicate","invalid_authority","destination_unavailable","invalid_remote_clock","policy_blocked","stale_preview","preview_expired","invalid_selection","attachment_invalid","consent_required","delivery_in_flight","reconciliation_unavailable","preparation_failed","outbox_unavailable"]},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},"example":{"error":{"code":"forbidden_scope","message":"Sample message text."}}}}},"403":{"description":"The principal is outside the required scope.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["forbidden_scope","not_found","invalid_request","idempotency_required","idempotency_conflict","stale_revision","reason_required","summary_required","transition_pending","invalid_transition","invalid_classification","invalid_duplicate","invalid_authority","destination_unavailable","invalid_remote_clock","policy_blocked","stale_preview","preview_expired","invalid_selection","attachment_invalid","consent_required","delivery_in_flight","reconciliation_unavailable","preparation_failed","outbox_unavailable"]},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},"example":{"error":{"code":"forbidden_scope","message":"Sample message text."}}}}},"409":{"description":"The revision, pending intent or idempotency request conflicts.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["forbidden_scope","not_found","invalid_request","idempotency_required","idempotency_conflict","stale_revision","reason_required","summary_required","transition_pending","invalid_transition","invalid_classification","invalid_duplicate","invalid_authority","destination_unavailable","invalid_remote_clock","policy_blocked","stale_preview","preview_expired","invalid_selection","attachment_invalid","consent_required","delivery_in_flight","reconciliation_unavailable","preparation_failed","outbox_unavailable"]},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},"example":{"error":{"code":"forbidden_scope","message":"Sample message text."}}}}},"422":{"description":"The command or attachment is invalid.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["forbidden_scope","not_found","invalid_request","idempotency_required","idempotency_conflict","stale_revision","reason_required","summary_required","transition_pending","invalid_transition","invalid_classification","invalid_duplicate","invalid_authority","destination_unavailable","invalid_remote_clock","policy_blocked","stale_preview","preview_expired","invalid_selection","attachment_invalid","consent_required","delivery_in_flight","reconciliation_unavailable","preparation_failed","outbox_unavailable"]},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},"example":{"error":{"code":"forbidden_scope","message":"Sample message text."}}}}},"503":{"description":"The operation could not durably accept its required outbox work. No command effect is committed.","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["forbidden_scope","not_found","invalid_request","idempotency_required","idempotency_conflict","stale_revision","reason_required","summary_required","transition_pending","invalid_transition","invalid_classification","invalid_duplicate","invalid_authority","destination_unavailable","invalid_remote_clock","policy_blocked","stale_preview","preview_expired","invalid_selection","attachment_invalid","consent_required","delivery_in_flight","reconciliation_unavailable","preparation_failed","outbox_unavailable"]},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}]},"example":{"error":{"code":"forbidden_scope","message":"Sample message text."}}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"expected_revision":{"type":"integer","minimum":0},"idempotency_key":{"type":"string","minLength":1,"maxLength":128},"message_id":{"type":"integer"},"content":{"type":["string","null"]},"retract":{"type":"boolean"}},"additionalProperties":false,"required":["message_id","expected_revision","idempotency_key"]},"example":{"expected_revision":1,"idempotency_key":"sample-token","message_id":1,"content":"Sample content text.","retract":true}}}}}},"/api/v1/accounts/{account_id}/bug_report_management/reports":{"get":{"tags":["Bug Reports"],"operationId":"auto_get_api_v1_accounts_account_id_bug_report_management_reports","summary":"Account bug reports list","description":"Authenticated Bug Reports operation. Uses the same domain authorization and command implementation as the console. Provider calls run only in committed workers.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Authorized response. Queued denotes local intent, never remote confirmation.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"user_id":{"type":["integer","null"]},"title":{"type":"string"},"description":{"type":["string","null"]},"report_type":{"type":"string","enum":["bug","improvement","feature"]},"severity":{"type":"string","enum":["low","medium","high","urgent"]},"component":{"type":["string","null"]},"workflow_state":{"type":"string","enum":["received","triage","waiting_reporter","in_progress","resolved","closed","duplicate"]},"workflow_revision":{"type":"integer"},"state_authority":{"type":"string","enum":["local","install_linear"]},"transition_pending":{"type":"boolean"},"pending_workflow_state":{"type":["string","null"],"enum":["received","triage","waiting_reporter","in_progress","resolved","closed","duplicate",null]},"resolution_summary":{"type":["string","null"]},"messages_count":{"type":"integer"},"support_name":{"type":"string"},"support_url":{"type":["string","null"]},"attachments":{"type":"array","items":{"type":"object","properties":{"attachment_id":{"type":"integer"},"name":{"type":"string"},"content_type":{"type":"string"},"byte_size":{"type":"integer"},"url":{"type":"string"},"image":{"type":"boolean"},"video":{"type":"boolean"}},"additionalProperties":false}},"diagnostics":{"type":"object","description":"Authorized report diagnostics after the domain redactor and bounded metadata allowlist.","additionalProperties":true},"assignee_user_id":{"type":["integer","null"]},"classification":{"type":"object","description":"Classification set by the authorized classification command.","additionalProperties":true},"resolution_reason":{"type":["string","null"]},"linear_state_projection":{"type":"object","description":"Verified remote id/type/action projection maintained by the authority service.","additionalProperties":true},"linear":{"type":"object","properties":{"destination_kind":{"type":"string","enum":["none","install_linear","legacy_unknown"]},"state":{"type":"string","enum":["prepared","confirmed","blocked","uncertain","failed"]},"reason":{"type":["string","null"]}},"additionalProperties":false},"sharing":{"type":"object","properties":{"state":{"type":"string","enum":["not_shared","pending_approval","queued","prepared","sent","confirmed","uncertain","shared","blocked","failed"]},"reason":{"type":["string","null"]},"mode":{"type":"string","enum":["disabled","manual","automatic"]},"revision":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false,"required":["id","account_id","title","workflow_state","workflow_revision"]}},"meta":{"type":"object","properties":{"current_page":{"type":"integer"},"total_pages":{"type":"integer"},"total_count":{"type":"integer"}},"additionalProperties":false}},"additionalProperties":false},"example":{"payload":[{"id":1,"account_id":1,"user_id":1,"title":"Sample title","description":"A short description.","report_type":"bug","severity":"low","component":"sample component","workflow_state":"received","workflow_revision":1,"state_authority":"local","transition_pending":true,"pending_workflow_state":"received","resolution_summary":"sample resolution summary","messages_count":5,"support_name":"sample support name","support_url":"https://example.com/resource","attachments":[{"attachment_id":1,"name":"Sample Name","content_type":"sample content type","byte_size":1,"url":"https://example.com/resource","image":true,"video":true}],"diagnostics":{},"assignee_user_id":1,"classification":{},"resolution_reason":"sample resolution reason","linear_state_projection":{},"linear":{"destination_kind":"none","state":"prepared","reason":"Sample reason."},"sharing":{"state":"not_shared","reason":"Sample reason.","mode":"disabled","revision":"sample revision"}}],"meta":{"current_page":1,"total_pages":1,"total_count":5}}}}},"401":{"description":"Unauthorized"},"404":{"description":"The scoped record is absent.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["forbidden_scope","not_found","invalid_request","idempotency_required","idempotency_conflict","stale_revision","reason_required","summary_required","transition_pending","invalid_transition","invalid_classification","invalid_duplicate","invalid_authority","destination_unavailable","invalid_remote_clock","policy_blocked","stale_preview","preview_expired","invalid_selection","attachment_invalid","consent_required","delivery_in_flight","reconciliation_unavailable","preparation_failed","outbox_unavailable"]},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},"example":{"error":{"code":"forbidden_scope","message":"Sample message text."}}}}},"403":{"description":"The principal is outside the required scope.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["forbidden_scope","not_found","invalid_request","idempotency_required","idempotency_conflict","stale_revision","reason_required","summary_required","transition_pending","invalid_transition","invalid_classification","invalid_duplicate","invalid_authority","destination_unavailable","invalid_remote_clock","policy_blocked","stale_preview","preview_expired","invalid_selection","attachment_invalid","consent_required","delivery_in_flight","reconciliation_unavailable","preparation_failed","outbox_unavailable"]},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},"example":{"error":{"code":"forbidden_scope","message":"Sample message text."}}}}},"409":{"description":"The revision, pending intent or idempotency request conflicts.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["forbidden_scope","not_found","invalid_request","idempotency_required","idempotency_conflict","stale_revision","reason_required","summary_required","transition_pending","invalid_transition","invalid_classification","invalid_duplicate","invalid_authority","destination_unavailable","invalid_remote_clock","policy_blocked","stale_preview","preview_expired","invalid_selection","attachment_invalid","consent_required","delivery_in_flight","reconciliation_unavailable","preparation_failed","outbox_unavailable"]},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},"example":{"error":{"code":"forbidden_scope","message":"Sample message text."}}}}},"422":{"description":"The command or attachment is invalid.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["forbidden_scope","not_found","invalid_request","idempotency_required","idempotency_conflict","stale_revision","reason_required","summary_required","transition_pending","invalid_transition","invalid_classification","invalid_duplicate","invalid_authority","destination_unavailable","invalid_remote_clock","policy_blocked","stale_preview","preview_expired","invalid_selection","attachment_invalid","consent_required","delivery_in_flight","reconciliation_unavailable","preparation_failed","outbox_unavailable"]},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},"example":{"error":{"code":"forbidden_scope","message":"Sample message text."}}}}},"503":{"description":"The operation could not durably accept its required outbox work. No command effect is committed.","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["forbidden_scope","not_found","invalid_request","idempotency_required","idempotency_conflict","stale_revision","reason_required","summary_required","transition_pending","invalid_transition","invalid_classification","invalid_duplicate","invalid_authority","destination_unavailable","invalid_remote_clock","policy_blocked","stale_preview","preview_expired","invalid_selection","attachment_invalid","consent_required","delivery_in_flight","reconciliation_unavailable","preparation_failed","outbox_unavailable"]},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}]},"example":{"error":{"code":"forbidden_scope","message":"Sample message text."}}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workflow_state","in":"query","required":false,"schema":{"type":"string","enum":["received","triage","waiting_reporter","in_progress","resolved","closed","duplicate"]}},{"name":"state_authority","in":"query","required":false,"schema":{"type":"string","enum":["local","install_linear"]}},{"name":"assignee_user_id","in":"query","required":false,"schema":{"type":"integer"}},{"name":"severity","in":"query","required":false,"schema":{"type":"string","enum":["low","medium","high","urgent"]}},{"name":"destination_kind","in":"query","required":false,"schema":{"type":"string","enum":["none","install_linear","legacy_unknown"]}},{"name":"delivery_state","in":"query","required":false,"schema":{"type":"string","enum":["pending","sent","failed","skipped","uncertain","blocked"]}},{"name":"query","in":"query","required":false,"schema":{"type":"string","maxLength":200}},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1}}]}},"/api/v1/accounts/{account_id}/bug_report_management/reports/{id}":{"get":{"tags":["Bug Reports"],"operationId":"auto_get_api_v1_accounts_account_id_bug_report_management_reports_id","summary":"Account bug reports show","description":"Authenticated Bug Reports operation. Uses the same domain authorization and command implementation as the console. Provider calls run only in committed workers.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Authorized response. Queued denotes local intent, never remote confirmation.","content":{"application/json":{"schema":{"type":"object","properties":{"report":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"user_id":{"type":["integer","null"]},"title":{"type":"string"},"description":{"type":["string","null"]},"report_type":{"type":"string","enum":["bug","improvement","feature"]},"severity":{"type":"string","enum":["low","medium","high","urgent"]},"component":{"type":["string","null"]},"workflow_state":{"type":"string","enum":["received","triage","waiting_reporter","in_progress","resolved","closed","duplicate"]},"workflow_revision":{"type":"integer"},"state_authority":{"type":"string","enum":["local","install_linear"]},"transition_pending":{"type":"boolean"},"pending_workflow_state":{"type":["string","null"],"enum":["received","triage","waiting_reporter","in_progress","resolved","closed","duplicate",null]},"resolution_summary":{"type":["string","null"]},"messages_count":{"type":"integer"},"support_name":{"type":"string"},"support_url":{"type":["string","null"]},"attachments":{"type":"array","items":{"type":"object","properties":{"attachment_id":{"type":"integer"},"name":{"type":"string"},"content_type":{"type":"string"},"byte_size":{"type":"integer"},"url":{"type":"string"},"image":{"type":"boolean"},"video":{"type":"boolean"}},"additionalProperties":false}},"diagnostics":{"type":"object","description":"Authorized report diagnostics after the domain redactor and bounded metadata allowlist.","additionalProperties":true},"assignee_user_id":{"type":["integer","null"]},"classification":{"type":"object","description":"Classification set by the authorized classification command.","additionalProperties":true},"resolution_reason":{"type":["string","null"]},"linear_state_projection":{"type":"object","description":"Verified remote id/type/action projection maintained by the authority service.","additionalProperties":true},"linear":{"type":"object","properties":{"destination_kind":{"type":"string","enum":["none","install_linear","legacy_unknown"]},"state":{"type":"string","enum":["prepared","confirmed","blocked","uncertain","failed"]},"reason":{"type":["string","null"]}},"additionalProperties":false},"sharing":{"type":"object","properties":{"state":{"type":"string","enum":["not_shared","pending_approval","queued","prepared","sent","confirmed","uncertain","shared","blocked","failed"]},"reason":{"type":["string","null"]},"mode":{"type":"string","enum":["disabled","manual","automatic"]},"revision":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false,"required":["id","account_id","title","workflow_state","workflow_revision"]},"capabilities":{"type":"object","properties":{"read_internal":{"type":"boolean"},"read_attachments":{"type":"boolean"},"read_diagnostics":{"type":"boolean"},"reply":{"type":"boolean"},"note":{"type":"boolean"},"classify":{"type":"boolean"},"assign":{"type":"boolean"},"transition":{"type":"boolean"},"authority":{"type":"boolean"},"reconcile":{"type":"boolean"},"escalate":{"type":"boolean"}},"additionalProperties":false},"capability_reasons":{"type":"object","properties":{"read_internal":{"type":["string","null"]},"read_attachments":{"type":["string","null"]},"read_diagnostics":{"type":["string","null"]},"reply":{"type":["string","null"]},"note":{"type":["string","null"]},"classify":{"type":["string","null"]},"assign":{"type":["string","null"]},"transition":{"type":["string","null"]},"authority":{"type":["string","null"]},"reconcile":{"type":["string","null"]},"escalate":{"type":["string","null"]}},"additionalProperties":false},"linear":{"type":"object","properties":{"destination_kind":{"type":"string","enum":["none","install_linear","legacy_unknown"]},"state":{"type":"string","enum":["prepared","confirmed","blocked","uncertain","failed"]},"reason":{"type":["string","null"]}},"additionalProperties":false},"sharing":{"type":"object","properties":{"state":{"type":"string","enum":["not_shared","pending_approval","queued","prepared","sent","confirmed","uncertain","shared","blocked","failed"]},"reason":{"type":["string","null"]},"mode":{"type":"string","enum":["disabled","manual","automatic"]},"revision":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},"example":{"report":{"id":1,"account_id":1,"user_id":1,"title":"Sample title","description":"A short description.","report_type":"bug","severity":"low","component":"sample component","workflow_state":"received","workflow_revision":1,"state_authority":"local","transition_pending":true,"pending_workflow_state":"received","resolution_summary":"sample resolution summary","messages_count":5,"support_name":"sample support name","support_url":"https://example.com/resource","attachments":[{"attachment_id":1,"name":"Sample Name","content_type":"sample content type","byte_size":1,"url":"https://example.com/resource","image":true,"video":true}],"diagnostics":{},"assignee_user_id":1,"classification":{},"resolution_reason":"sample resolution reason","linear_state_projection":{},"linear":{"destination_kind":"none","state":"prepared","reason":"Sample reason."},"sharing":{"state":"not_shared","reason":"Sample reason.","mode":"disabled","revision":"sample revision"}},"capabilities":{"read_internal":true,"read_attachments":true,"read_diagnostics":true,"reply":true,"note":true,"classify":true,"assign":true,"transition":true,"authority":true,"reconcile":true,"escalate":true},"capability_reasons":{"read_internal":"sample read internal","read_attachments":"sample read attachments","read_diagnostics":"sample read diagnostics","reply":"sample reply","note":"Sample note.","classify":"sample classify","assign":"sample assign","transition":"sample transition","authority":"sample authority","reconcile":"sample reconcile","escalate":"sample escalate"},"linear":{"destination_kind":"none","state":"prepared","reason":"Sample reason."},"sharing":{"state":"not_shared","reason":"Sample reason.","mode":"disabled","revision":"sample revision"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"The scoped record is absent.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["forbidden_scope","not_found","invalid_request","idempotency_required","idempotency_conflict","stale_revision","reason_required","summary_required","transition_pending","invalid_transition","invalid_classification","invalid_duplicate","invalid_authority","destination_unavailable","invalid_remote_clock","policy_blocked","stale_preview","preview_expired","invalid_selection","attachment_invalid","consent_required","delivery_in_flight","reconciliation_unavailable","preparation_failed","outbox_unavailable"]},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},"example":{"error":{"code":"forbidden_scope","message":"Sample message text."}}}}},"403":{"description":"The principal is outside the required scope.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["forbidden_scope","not_found","invalid_request","idempotency_required","idempotency_conflict","stale_revision","reason_required","summary_required","transition_pending","invalid_transition","invalid_classification","invalid_duplicate","invalid_authority","destination_unavailable","invalid_remote_clock","policy_blocked","stale_preview","preview_expired","invalid_selection","attachment_invalid","consent_required","delivery_in_flight","reconciliation_unavailable","preparation_failed","outbox_unavailable"]},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},"example":{"error":{"code":"forbidden_scope","message":"Sample message text."}}}}},"409":{"description":"The revision, pending intent or idempotency request conflicts.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["forbidden_scope","not_found","invalid_request","idempotency_required","idempotency_conflict","stale_revision","reason_required","summary_required","transition_pending","invalid_transition","invalid_classification","invalid_duplicate","invalid_authority","destination_unavailable","invalid_remote_clock","policy_blocked","stale_preview","preview_expired","invalid_selection","attachment_invalid","consent_required","delivery_in_flight","reconciliation_unavailable","preparation_failed","outbox_unavailable"]},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},"example":{"error":{"code":"forbidden_scope","message":"Sample message text."}}}}},"422":{"description":"The command or attachment is invalid.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["forbidden_scope","not_found","invalid_request","idempotency_required","idempotency_conflict","stale_revision","reason_required","summary_required","transition_pending","invalid_transition","invalid_classification","invalid_duplicate","invalid_authority","destination_unavailable","invalid_remote_clock","policy_blocked","stale_preview","preview_expired","invalid_selection","attachment_invalid","consent_required","delivery_in_flight","reconciliation_unavailable","preparation_failed","outbox_unavailable"]},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},"example":{"error":{"code":"forbidden_scope","message":"Sample message text."}}}}},"503":{"description":"The operation could not durably accept its required outbox work. No command effect is committed.","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["forbidden_scope","not_found","invalid_request","idempotency_required","idempotency_conflict","stale_revision","reason_required","summary_required","transition_pending","invalid_transition","invalid_classification","invalid_duplicate","invalid_authority","destination_unavailable","invalid_remote_clock","policy_blocked","stale_preview","preview_expired","invalid_selection","attachment_invalid","consent_required","delivery_in_flight","reconciliation_unavailable","preparation_failed","outbox_unavailable"]},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}]},"example":{"error":{"code":"forbidden_scope","message":"Sample message text."}}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/bug_report_management/uploads/{id}/content":{"post":{"tags":["Bug Reports"],"operationId":"auto_post_api_v1_accounts_account_id_bug_report_management_uploads_id_content","summary":"Account bug reports upload content","description":"Authenticated Bug Reports operation. Uses the same domain authorization and command implementation as the console. Provider calls run only in committed workers.","security":[{"userApiKey":[]}],"responses":{"202":{"description":"Authorized response. Queued denotes local intent, never remote confirmation.","content":{"application/json":{"schema":{"type":"object","properties":{"upload_id":{"type":"integer"},"state":{"type":"string","enum":["prepared","uploading","verifying","finalized","consumed","expired","failed"]},"reason":{"type":["string","null"]},"expires_at":{"type":"string","format":"date-time"},"upload_token":{"type":"string"},"filename":{"type":["string","null"]},"byte_size":{"type":["integer","null"]},"content_type":{"type":["string","null"],"enum":["image/png","image/jpeg","image/gif","image/webp","video/mp4","video/webm","application/pdf","text/plain",null]},"attachment_ref":{"type":["string","null"]},"direct_upload":{"type":"object","properties":{"url":{"type":"string"},"headers":{"type":"object","additionalProperties":{"type":"string"},"description":"Storage-signed headers for this upload only."}},"additionalProperties":false}},"additionalProperties":false},"example":{"upload_id":1,"state":"prepared","reason":"Sample reason.","expires_at":"2026-01-15T10:30:00.000Z","upload_token":"sample-token","filename":"sample filename","byte_size":1,"content_type":"image/png","attachment_ref":"sample attachment ref","direct_upload":{"url":"https://example.com/resource","headers":{}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"The scoped record is absent.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["forbidden_scope","not_found","invalid_request","idempotency_required","idempotency_conflict","stale_revision","reason_required","summary_required","transition_pending","invalid_transition","invalid_classification","invalid_duplicate","invalid_authority","destination_unavailable","invalid_remote_clock","policy_blocked","stale_preview","preview_expired","invalid_selection","attachment_invalid","consent_required","delivery_in_flight","reconciliation_unavailable","preparation_failed","outbox_unavailable"]},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},"example":{"error":{"code":"forbidden_scope","message":"Sample message text."}}}}},"403":{"description":"The principal is outside the required scope.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["forbidden_scope","not_found","invalid_request","idempotency_required","idempotency_conflict","stale_revision","reason_required","summary_required","transition_pending","invalid_transition","invalid_classification","invalid_duplicate","invalid_authority","destination_unavailable","invalid_remote_clock","policy_blocked","stale_preview","preview_expired","invalid_selection","attachment_invalid","consent_required","delivery_in_flight","reconciliation_unavailable","preparation_failed","outbox_unavailable"]},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},"example":{"error":{"code":"forbidden_scope","message":"Sample message text."}}}}},"409":{"description":"The revision, pending intent or idempotency request conflicts.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["forbidden_scope","not_found","invalid_request","idempotency_required","idempotency_conflict","stale_revision","reason_required","summary_required","transition_pending","invalid_transition","invalid_classification","invalid_duplicate","invalid_authority","destination_unavailable","invalid_remote_clock","policy_blocked","stale_preview","preview_expired","invalid_selection","attachment_invalid","consent_required","delivery_in_flight","reconciliation_unavailable","preparation_failed","outbox_unavailable"]},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},"example":{"error":{"code":"forbidden_scope","message":"Sample message text."}}}}},"422":{"description":"The command or attachment is invalid.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["forbidden_scope","not_found","invalid_request","idempotency_required","idempotency_conflict","stale_revision","reason_required","summary_required","transition_pending","invalid_transition","invalid_classification","invalid_duplicate","invalid_authority","destination_unavailable","invalid_remote_clock","policy_blocked","stale_preview","preview_expired","invalid_selection","attachment_invalid","consent_required","delivery_in_flight","reconciliation_unavailable","preparation_failed","outbox_unavailable"]},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},"example":{"error":{"code":"forbidden_scope","message":"Sample message text."}}}}},"503":{"description":"The operation could not durably accept its required outbox work. No command effect is committed.","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["forbidden_scope","not_found","invalid_request","idempotency_required","idempotency_conflict","stale_revision","reason_required","summary_required","transition_pending","invalid_transition","invalid_classification","invalid_duplicate","invalid_authority","destination_unavailable","invalid_remote_clock","policy_blocked","stale_preview","preview_expired","invalid_selection","attachment_invalid","consent_required","delivery_in_flight","reconciliation_unavailable","preparation_failed","outbox_unavailable"]},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}]},"example":{"error":{"code":"forbidden_scope","message":"Sample message text."}}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"upload_token":{"type":"string"},"content_base64":{"type":"string","writeOnly":true,"maxLength":6990516}},"additionalProperties":false,"required":["upload_token","content_base64"]},"example":{"upload_token":"sample-token","content_base64":"sample content base64"}}}}}},"/api/v1/accounts/{account_id}/bug_report_management/uploads/{id}/finalize":{"post":{"tags":["Bug Reports"],"operationId":"auto_post_api_v1_accounts_account_id_bug_report_management_uploads_id_finalize","summary":"Account bug reports upload finalize","description":"Authenticated Bug Reports operation. Uses the same domain authorization and command implementation as the console. Provider calls run only in committed workers.","security":[{"userApiKey":[]}],"responses":{"202":{"description":"Authorized response. Queued denotes local intent, never remote confirmation.","content":{"application/json":{"schema":{"type":"object","properties":{"upload_id":{"type":"integer"},"state":{"type":"string","enum":["prepared","uploading","verifying","finalized","consumed","expired","failed"]},"reason":{"type":["string","null"]},"expires_at":{"type":"string","format":"date-time"},"upload_token":{"type":"string"},"filename":{"type":["string","null"]},"byte_size":{"type":["integer","null"]},"content_type":{"type":["string","null"],"enum":["image/png","image/jpeg","image/gif","image/webp","video/mp4","video/webm","application/pdf","text/plain",null]},"attachment_ref":{"type":["string","null"]},"direct_upload":{"type":"object","properties":{"url":{"type":"string"},"headers":{"type":"object","additionalProperties":{"type":"string"},"description":"Storage-signed headers for this upload only."}},"additionalProperties":false}},"additionalProperties":false},"example":{"upload_id":1,"state":"prepared","reason":"Sample reason.","expires_at":"2026-01-15T10:30:00.000Z","upload_token":"sample-token","filename":"sample filename","byte_size":1,"content_type":"image/png","attachment_ref":"sample attachment ref","direct_upload":{"url":"https://example.com/resource","headers":{}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"The scoped record is absent.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["forbidden_scope","not_found","invalid_request","idempotency_required","idempotency_conflict","stale_revision","reason_required","summary_required","transition_pending","invalid_transition","invalid_classification","invalid_duplicate","invalid_authority","destination_unavailable","invalid_remote_clock","policy_blocked","stale_preview","preview_expired","invalid_selection","attachment_invalid","consent_required","delivery_in_flight","reconciliation_unavailable","preparation_failed","outbox_unavailable"]},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},"example":{"error":{"code":"forbidden_scope","message":"Sample message text."}}}}},"403":{"description":"The principal is outside the required scope.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["forbidden_scope","not_found","invalid_request","idempotency_required","idempotency_conflict","stale_revision","reason_required","summary_required","transition_pending","invalid_transition","invalid_classification","invalid_duplicate","invalid_authority","destination_unavailable","invalid_remote_clock","policy_blocked","stale_preview","preview_expired","invalid_selection","attachment_invalid","consent_required","delivery_in_flight","reconciliation_unavailable","preparation_failed","outbox_unavailable"]},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},"example":{"error":{"code":"forbidden_scope","message":"Sample message text."}}}}},"409":{"description":"The revision, pending intent or idempotency request conflicts.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["forbidden_scope","not_found","invalid_request","idempotency_required","idempotency_conflict","stale_revision","reason_required","summary_required","transition_pending","invalid_transition","invalid_classification","invalid_duplicate","invalid_authority","destination_unavailable","invalid_remote_clock","policy_blocked","stale_preview","preview_expired","invalid_selection","attachment_invalid","consent_required","delivery_in_flight","reconciliation_unavailable","preparation_failed","outbox_unavailable"]},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},"example":{"error":{"code":"forbidden_scope","message":"Sample message text."}}}}},"422":{"description":"The command or attachment is invalid.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["forbidden_scope","not_found","invalid_request","idempotency_required","idempotency_conflict","stale_revision","reason_required","summary_required","transition_pending","invalid_transition","invalid_classification","invalid_duplicate","invalid_authority","destination_unavailable","invalid_remote_clock","policy_blocked","stale_preview","preview_expired","invalid_selection","attachment_invalid","consent_required","delivery_in_flight","reconciliation_unavailable","preparation_failed","outbox_unavailable"]},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},"example":{"error":{"code":"forbidden_scope","message":"Sample message text."}}}}},"503":{"description":"The operation could not durably accept its required outbox work. No command effect is committed.","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["forbidden_scope","not_found","invalid_request","idempotency_required","idempotency_conflict","stale_revision","reason_required","summary_required","transition_pending","invalid_transition","invalid_classification","invalid_duplicate","invalid_authority","destination_unavailable","invalid_remote_clock","policy_blocked","stale_preview","preview_expired","invalid_selection","attachment_invalid","consent_required","delivery_in_flight","reconciliation_unavailable","preparation_failed","outbox_unavailable"]},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}]},"example":{"error":{"code":"forbidden_scope","message":"Sample message text."}}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"upload_token":{"type":"string"}},"additionalProperties":false,"required":["upload_token"]},"example":{"upload_token":"sample-token"}}}}}},"/api/v1/accounts/{account_id}/bug_report_management/uploads":{"post":{"tags":["Bug Reports"],"operationId":"auto_post_api_v1_accounts_account_id_bug_report_management_uploads","summary":"Account bug reports upload prepare","description":"Authenticated Bug Reports operation. Uses the same domain authorization and command implementation as the console. Provider calls run only in committed workers.","security":[{"userApiKey":[]}],"responses":{"201":{"description":"Authorized response. Queued denotes local intent, never remote confirmation.","content":{"application/json":{"schema":{"type":"object","properties":{"upload_id":{"type":"integer"},"state":{"type":"string","enum":["prepared","uploading","verifying","finalized","consumed","expired","failed"]},"reason":{"type":["string","null"]},"expires_at":{"type":"string","format":"date-time"},"upload_token":{"type":"string"},"filename":{"type":["string","null"]},"byte_size":{"type":["integer","null"]},"content_type":{"type":["string","null"],"enum":["image/png","image/jpeg","image/gif","image/webp","video/mp4","video/webm","application/pdf","text/plain",null]},"attachment_ref":{"type":["string","null"]},"direct_upload":{"type":"object","properties":{"url":{"type":"string"},"headers":{"type":"object","additionalProperties":{"type":"string"},"description":"Storage-signed headers for this upload only."}},"additionalProperties":false}},"additionalProperties":false},"example":{"upload_id":1,"state":"prepared","reason":"Sample reason.","expires_at":"2026-01-15T10:30:00.000Z","upload_token":"sample-token","filename":"sample filename","byte_size":1,"content_type":"image/png","attachment_ref":"sample attachment ref","direct_upload":{"url":"https://example.com/resource","headers":{}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"The scoped record is absent.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["forbidden_scope","not_found","invalid_request","idempotency_required","idempotency_conflict","stale_revision","reason_required","summary_required","transition_pending","invalid_transition","invalid_classification","invalid_duplicate","invalid_authority","destination_unavailable","invalid_remote_clock","policy_blocked","stale_preview","preview_expired","invalid_selection","attachment_invalid","consent_required","delivery_in_flight","reconciliation_unavailable","preparation_failed","outbox_unavailable"]},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},"example":{"error":{"code":"forbidden_scope","message":"Sample message text."}}}}},"403":{"description":"The principal is outside the required scope.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["forbidden_scope","not_found","invalid_request","idempotency_required","idempotency_conflict","stale_revision","reason_required","summary_required","transition_pending","invalid_transition","invalid_classification","invalid_duplicate","invalid_authority","destination_unavailable","invalid_remote_clock","policy_blocked","stale_preview","preview_expired","invalid_selection","attachment_invalid","consent_required","delivery_in_flight","reconciliation_unavailable","preparation_failed","outbox_unavailable"]},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},"example":{"error":{"code":"forbidden_scope","message":"Sample message text."}}}}},"409":{"description":"The revision, pending intent or idempotency request conflicts.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["forbidden_scope","not_found","invalid_request","idempotency_required","idempotency_conflict","stale_revision","reason_required","summary_required","transition_pending","invalid_transition","invalid_classification","invalid_duplicate","invalid_authority","destination_unavailable","invalid_remote_clock","policy_blocked","stale_preview","preview_expired","invalid_selection","attachment_invalid","consent_required","delivery_in_flight","reconciliation_unavailable","preparation_failed","outbox_unavailable"]},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},"example":{"error":{"code":"forbidden_scope","message":"Sample message text."}}}}},"422":{"description":"The command or attachment is invalid.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["forbidden_scope","not_found","invalid_request","idempotency_required","idempotency_conflict","stale_revision","reason_required","summary_required","transition_pending","invalid_transition","invalid_classification","invalid_duplicate","invalid_authority","destination_unavailable","invalid_remote_clock","policy_blocked","stale_preview","preview_expired","invalid_selection","attachment_invalid","consent_required","delivery_in_flight","reconciliation_unavailable","preparation_failed","outbox_unavailable"]},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},"example":{"error":{"code":"forbidden_scope","message":"Sample message text."}}}}},"503":{"description":"The operation could not durably accept its required outbox work. No command effect is committed.","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["forbidden_scope","not_found","invalid_request","idempotency_required","idempotency_conflict","stale_revision","reason_required","summary_required","transition_pending","invalid_transition","invalid_classification","invalid_duplicate","invalid_authority","destination_unavailable","invalid_remote_clock","policy_blocked","stale_preview","preview_expired","invalid_selection","attachment_invalid","consent_required","delivery_in_flight","reconciliation_unavailable","preparation_failed","outbox_unavailable"]},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}]},"example":{"error":{"code":"forbidden_scope","message":"Sample message text."}}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"filename":{"type":"string","minLength":1,"maxLength":255},"byte_size":{"type":"integer","minimum":1,"maximum":26214400},"checksum":{"type":"string","description":"Base64 MD5 digest of the exact original bytes."},"content_type":{"type":"string","enum":["image/png","image/jpeg","image/gif","image/webp","video/mp4","video/webm","application/pdf","text/plain"]},"idempotency_key":{"type":"string","minLength":1,"maxLength":128}},"additionalProperties":false,"required":["filename","byte_size","checksum","content_type","idempotency_key"]},"example":{"filename":"sample filename","byte_size":1,"checksum":"sample checksum","content_type":"image/png","idempotency_key":"sample-token"}}}}}},"/api/v1/accounts/{account_id}/bug_report_management/uploads/{id}":{"get":{"tags":["Bug Reports"],"operationId":"auto_get_api_v1_accounts_account_id_bug_report_management_uploads_id","summary":"Account bug reports upload status","description":"Authenticated Bug Reports operation. Uses the same domain authorization and command implementation as the console. Provider calls run only in committed workers.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Authorized response. Queued denotes local intent, never remote confirmation.","content":{"application/json":{"schema":{"type":"object","properties":{"upload_id":{"type":"integer"},"state":{"type":"string","enum":["prepared","uploading","verifying","finalized","consumed","expired","failed"]},"reason":{"type":["string","null"]},"expires_at":{"type":"string","format":"date-time"},"upload_token":{"type":"string"},"filename":{"type":["string","null"]},"byte_size":{"type":["integer","null"]},"content_type":{"type":["string","null"],"enum":["image/png","image/jpeg","image/gif","image/webp","video/mp4","video/webm","application/pdf","text/plain",null]},"attachment_ref":{"type":["string","null"]},"direct_upload":{"type":"object","properties":{"url":{"type":"string"},"headers":{"type":"object","additionalProperties":{"type":"string"},"description":"Storage-signed headers for this upload only."}},"additionalProperties":false}},"additionalProperties":false},"example":{"upload_id":1,"state":"prepared","reason":"Sample reason.","expires_at":"2026-01-15T10:30:00.000Z","upload_token":"sample-token","filename":"sample filename","byte_size":1,"content_type":"image/png","attachment_ref":"sample attachment ref","direct_upload":{"url":"https://example.com/resource","headers":{}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"The scoped record is absent.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["forbidden_scope","not_found","invalid_request","idempotency_required","idempotency_conflict","stale_revision","reason_required","summary_required","transition_pending","invalid_transition","invalid_classification","invalid_duplicate","invalid_authority","destination_unavailable","invalid_remote_clock","policy_blocked","stale_preview","preview_expired","invalid_selection","attachment_invalid","consent_required","delivery_in_flight","reconciliation_unavailable","preparation_failed","outbox_unavailable"]},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},"example":{"error":{"code":"forbidden_scope","message":"Sample message text."}}}}},"403":{"description":"The principal is outside the required scope.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["forbidden_scope","not_found","invalid_request","idempotency_required","idempotency_conflict","stale_revision","reason_required","summary_required","transition_pending","invalid_transition","invalid_classification","invalid_duplicate","invalid_authority","destination_unavailable","invalid_remote_clock","policy_blocked","stale_preview","preview_expired","invalid_selection","attachment_invalid","consent_required","delivery_in_flight","reconciliation_unavailable","preparation_failed","outbox_unavailable"]},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},"example":{"error":{"code":"forbidden_scope","message":"Sample message text."}}}}},"409":{"description":"The revision, pending intent or idempotency request conflicts.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["forbidden_scope","not_found","invalid_request","idempotency_required","idempotency_conflict","stale_revision","reason_required","summary_required","transition_pending","invalid_transition","invalid_classification","invalid_duplicate","invalid_authority","destination_unavailable","invalid_remote_clock","policy_blocked","stale_preview","preview_expired","invalid_selection","attachment_invalid","consent_required","delivery_in_flight","reconciliation_unavailable","preparation_failed","outbox_unavailable"]},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},"example":{"error":{"code":"forbidden_scope","message":"Sample message text."}}}}},"422":{"description":"The command or attachment is invalid.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["forbidden_scope","not_found","invalid_request","idempotency_required","idempotency_conflict","stale_revision","reason_required","summary_required","transition_pending","invalid_transition","invalid_classification","invalid_duplicate","invalid_authority","destination_unavailable","invalid_remote_clock","policy_blocked","stale_preview","preview_expired","invalid_selection","attachment_invalid","consent_required","delivery_in_flight","reconciliation_unavailable","preparation_failed","outbox_unavailable"]},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},"example":{"error":{"code":"forbidden_scope","message":"Sample message text."}}}}},"503":{"description":"The operation could not durably accept its required outbox work. No command effect is committed.","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["forbidden_scope","not_found","invalid_request","idempotency_required","idempotency_conflict","stale_revision","reason_required","summary_required","transition_pending","invalid_transition","invalid_classification","invalid_duplicate","invalid_authority","destination_unavailable","invalid_remote_clock","policy_blocked","stale_preview","preview_expired","invalid_selection","attachment_invalid","consent_required","delivery_in_flight","reconciliation_unavailable","preparation_failed","outbox_unavailable"]},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}]},"example":{"error":{"code":"forbidden_scope","message":"Sample message text."}}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"upload_token","in":"query","required":false,"schema":{"type":"string"}}]},"delete":{"tags":["Bug Reports"],"operationId":"auto_delete_api_v1_accounts_account_id_bug_report_management_uploads_id","summary":"Account bug reports upload remove","description":"Authenticated Bug Reports operation. Uses the same domain authorization and command implementation as the console. Provider calls run only in committed workers.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Authorized response. Queued denotes local intent, never remote confirmation.","content":{"application/json":{"schema":{"type":"object","properties":{"upload_id":{"type":"integer"},"state":{"type":"string","enum":["expired"]}},"additionalProperties":false},"example":{"upload_id":1,"state":"expired"}}}},"401":{"description":"Unauthorized"},"404":{"description":"The scoped record is absent.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["forbidden_scope","not_found","invalid_request","idempotency_required","idempotency_conflict","stale_revision","reason_required","summary_required","transition_pending","invalid_transition","invalid_classification","invalid_duplicate","invalid_authority","destination_unavailable","invalid_remote_clock","policy_blocked","stale_preview","preview_expired","invalid_selection","attachment_invalid","consent_required","delivery_in_flight","reconciliation_unavailable","preparation_failed","outbox_unavailable"]},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},"example":{"error":{"code":"forbidden_scope","message":"Sample message text."}}}}},"403":{"description":"The principal is outside the required scope.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["forbidden_scope","not_found","invalid_request","idempotency_required","idempotency_conflict","stale_revision","reason_required","summary_required","transition_pending","invalid_transition","invalid_classification","invalid_duplicate","invalid_authority","destination_unavailable","invalid_remote_clock","policy_blocked","stale_preview","preview_expired","invalid_selection","attachment_invalid","consent_required","delivery_in_flight","reconciliation_unavailable","preparation_failed","outbox_unavailable"]},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},"example":{"error":{"code":"forbidden_scope","message":"Sample message text."}}}}},"409":{"description":"The revision, pending intent or idempotency request conflicts.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["forbidden_scope","not_found","invalid_request","idempotency_required","idempotency_conflict","stale_revision","reason_required","summary_required","transition_pending","invalid_transition","invalid_classification","invalid_duplicate","invalid_authority","destination_unavailable","invalid_remote_clock","policy_blocked","stale_preview","preview_expired","invalid_selection","attachment_invalid","consent_required","delivery_in_flight","reconciliation_unavailable","preparation_failed","outbox_unavailable"]},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},"example":{"error":{"code":"forbidden_scope","message":"Sample message text."}}}}},"422":{"description":"The command or attachment is invalid.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["forbidden_scope","not_found","invalid_request","idempotency_required","idempotency_conflict","stale_revision","reason_required","summary_required","transition_pending","invalid_transition","invalid_classification","invalid_duplicate","invalid_authority","destination_unavailable","invalid_remote_clock","policy_blocked","stale_preview","preview_expired","invalid_selection","attachment_invalid","consent_required","delivery_in_flight","reconciliation_unavailable","preparation_failed","outbox_unavailable"]},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},"example":{"error":{"code":"forbidden_scope","message":"Sample message text."}}}}},"503":{"description":"The operation could not durably accept its required outbox work. No command effect is committed.","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["forbidden_scope","not_found","invalid_request","idempotency_required","idempotency_conflict","stale_revision","reason_required","summary_required","transition_pending","invalid_transition","invalid_classification","invalid_duplicate","invalid_authority","destination_unavailable","invalid_remote_clock","policy_blocked","stale_preview","preview_expired","invalid_selection","attachment_invalid","consent_required","delivery_in_flight","reconciliation_unavailable","preparation_failed","outbox_unavailable"]},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}]},"example":{"error":{"code":"forbidden_scope","message":"Sample message text."}}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"upload_token":{"type":"string"}},"additionalProperties":false,"required":["upload_token"]},"example":{"upload_token":"sample-token"}}}}}},"/api/v1/accounts/{account_id}/bug_report_management/submissions":{"post":{"tags":["Bug Reports"],"operationId":"auto_post_api_v1_accounts_account_id_bug_report_management_submissions","summary":"Account bug reports submit","description":"Creates a local report as the authenticated account user. Accepts text and finalized owned attachment refs only; URL/blob-id/author/authority fields are refused without fetching any remote URL. Receipt confirms local creation only; optional Linear/sharing effects remain independently queued.","security":[{"userApiKey":[]}],"responses":{"201":{"description":"Authorized response. Queued denotes local intent, never remote confirmation.","content":{"application/json":{"schema":{"type":"object","properties":{"report":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"user_id":{"type":["integer","null"]},"title":{"type":"string"},"description":{"type":["string","null"]},"report_type":{"type":"string","enum":["bug","improvement","feature"]},"severity":{"type":"string","enum":["low","medium","high","urgent"]},"component":{"type":["string","null"]},"workflow_state":{"type":"string","enum":["received","triage","waiting_reporter","in_progress","resolved","closed","duplicate"]},"workflow_revision":{"type":"integer"},"state_authority":{"type":"string","enum":["local","install_linear"]},"transition_pending":{"type":"boolean"},"pending_workflow_state":{"type":["string","null"],"enum":["received","triage","waiting_reporter","in_progress","resolved","closed","duplicate",null]},"resolution_summary":{"type":["string","null"]},"messages_count":{"type":"integer"},"support_name":{"type":"string"},"support_url":{"type":["string","null"]},"attachments":{"type":"array","items":{"type":"object","properties":{"attachment_id":{"type":"integer"},"name":{"type":"string"},"content_type":{"type":"string"},"byte_size":{"type":"integer"},"url":{"type":"string"},"image":{"type":"boolean"},"video":{"type":"boolean"}},"additionalProperties":false}},"diagnostics":{"type":"object","description":"Authorized report diagnostics after the domain redactor and bounded metadata allowlist.","additionalProperties":true},"assignee_user_id":{"type":["integer","null"]},"classification":{"type":"object","description":"Classification set by the authorized classification command.","additionalProperties":true},"resolution_reason":{"type":["string","null"]},"linear_state_projection":{"type":"object","description":"Verified remote id/type/action projection maintained by the authority service.","additionalProperties":true},"linear":{"type":"object","properties":{"destination_kind":{"type":"string","enum":["none","install_linear","legacy_unknown"]},"state":{"type":"string","enum":["prepared","confirmed","blocked","uncertain","failed"]},"reason":{"type":["string","null"]}},"additionalProperties":false},"sharing":{"type":"object","properties":{"state":{"type":"string","enum":["not_shared","pending_approval","queued","prepared","sent","confirmed","uncertain","shared","blocked","failed"]},"reason":{"type":["string","null"]},"mode":{"type":"string","enum":["disabled","manual","automatic"]},"revision":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false,"required":["id","account_id","title","workflow_state","workflow_revision"]},"receipt":{"type":"object","properties":{"state":{"type":"string","enum":["confirmed"]},"report_id":{"type":"integer"},"idempotency_key":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},"example":{"report":{"id":1,"account_id":1,"user_id":1,"title":"Sample title","description":"A short description.","report_type":"bug","severity":"low","component":"sample component","workflow_state":"received","workflow_revision":1,"state_authority":"local","transition_pending":true,"pending_workflow_state":"received","resolution_summary":"sample resolution summary","messages_count":5,"support_name":"sample support name","support_url":"https://example.com/resource","attachments":[{"attachment_id":1,"name":"Sample Name","content_type":"sample content type","byte_size":1,"url":"https://example.com/resource","image":true,"video":true}],"diagnostics":{},"assignee_user_id":1,"classification":{},"resolution_reason":"sample resolution reason","linear_state_projection":{},"linear":{"destination_kind":"none","state":"prepared","reason":"Sample reason."},"sharing":{"state":"not_shared","reason":"Sample reason.","mode":"disabled","revision":"sample revision"}},"receipt":{"state":"confirmed","report_id":1,"idempotency_key":"sample-token"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"The scoped record is absent.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["forbidden_scope","not_found","invalid_request","idempotency_required","idempotency_conflict","stale_revision","reason_required","summary_required","transition_pending","invalid_transition","invalid_classification","invalid_duplicate","invalid_authority","destination_unavailable","invalid_remote_clock","policy_blocked","stale_preview","preview_expired","invalid_selection","attachment_invalid","consent_required","delivery_in_flight","reconciliation_unavailable","preparation_failed","outbox_unavailable"]},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},"example":{"error":{"code":"forbidden_scope","message":"Sample message text."}}}}},"403":{"description":"The principal is outside the required scope.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["forbidden_scope","not_found","invalid_request","idempotency_required","idempotency_conflict","stale_revision","reason_required","summary_required","transition_pending","invalid_transition","invalid_classification","invalid_duplicate","invalid_authority","destination_unavailable","invalid_remote_clock","policy_blocked","stale_preview","preview_expired","invalid_selection","attachment_invalid","consent_required","delivery_in_flight","reconciliation_unavailable","preparation_failed","outbox_unavailable"]},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},"example":{"error":{"code":"forbidden_scope","message":"Sample message text."}}}}},"409":{"description":"The revision, pending intent or idempotency request conflicts.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["forbidden_scope","not_found","invalid_request","idempotency_required","idempotency_conflict","stale_revision","reason_required","summary_required","transition_pending","invalid_transition","invalid_classification","invalid_duplicate","invalid_authority","destination_unavailable","invalid_remote_clock","policy_blocked","stale_preview","preview_expired","invalid_selection","attachment_invalid","consent_required","delivery_in_flight","reconciliation_unavailable","preparation_failed","outbox_unavailable"]},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},"example":{"error":{"code":"forbidden_scope","message":"Sample message text."}}}}},"422":{"description":"The command or attachment is invalid.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["forbidden_scope","not_found","invalid_request","idempotency_required","idempotency_conflict","stale_revision","reason_required","summary_required","transition_pending","invalid_transition","invalid_classification","invalid_duplicate","invalid_authority","destination_unavailable","invalid_remote_clock","policy_blocked","stale_preview","preview_expired","invalid_selection","attachment_invalid","consent_required","delivery_in_flight","reconciliation_unavailable","preparation_failed","outbox_unavailable"]},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},"example":{"error":{"code":"forbidden_scope","message":"Sample message text."}}}}},"503":{"description":"The operation could not durably accept its required outbox work. No command effect is committed.","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["forbidden_scope","not_found","invalid_request","idempotency_required","idempotency_conflict","stale_revision","reason_required","summary_required","transition_pending","invalid_transition","invalid_classification","invalid_duplicate","invalid_authority","destination_unavailable","invalid_remote_clock","policy_blocked","stale_preview","preview_expired","invalid_selection","attachment_invalid","consent_required","delivery_in_flight","reconciliation_unavailable","preparation_failed","outbox_unavailable"]},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}]},"example":{"error":{"code":"forbidden_scope","message":"Sample message text."}}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":500},"description":{"type":["string","null"]},"report_type":{"type":"string","enum":["bug","improvement","feature"]},"severity":{"type":"string","enum":["low","medium","high","urgent"]},"component":{"type":["string","null"]},"consent":{"type":"boolean"},"consent_version":{"type":"string"},"attachment_refs":{"type":"array","items":{"type":"string"},"maxItems":10},"idempotency_key":{"type":"string","minLength":1,"maxLength":128}},"additionalProperties":false,"required":["title","report_type","severity","idempotency_key"]},"example":{"title":"Sample title","description":"A short description.","report_type":"bug","severity":"low","component":"sample component","consent":true,"consent_version":"sample consent version","attachment_refs":["sample attachment ref"],"idempotency_key":"sample-token"}}}}}},"/api/v1/accounts/{account_id}/bug_report_management/configuration":{"get":{"tags":["Bug Reports"],"operationId":"auto_get_api_v1_accounts_account_id_bug_report_management_configuration","summary":"Account bug reports configuration","description":"Authenticated Bug Reports operation. Uses the same domain authorization and command implementation as the console. Provider calls run only in committed workers.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Authorized response. Queued denotes local intent, never remote confirmation.","content":{"application/json":{"schema":{"type":"object","properties":{"sharing":{"type":"object","properties":{"account_id":{"type":["integer","null"]},"mode":{"type":"string","enum":["disabled","manual","automatic"]},"revision":{"type":"string"},"installation_mode":{"type":"string","enum":["disabled","manual","automatic"]},"account_mode":{"type":["string","null"],"enum":["disabled","manual","automatic",null]},"source":{"type":"string"},"changed_at":{"type":["string","null"],"format":"date-time"}},"additionalProperties":false},"support":{"type":"object","properties":{"public_name":{"type":["string","null"],"maxLength":100},"signature":{"type":["string","null"],"maxLength":100},"public_url":{"type":["string","null"],"maxLength":500},"neutral_terms":{"type":"array","items":{"type":"string"},"maxItems":20},"expose_tracker_links":{"type":"boolean"},"revision":{"type":"integer"}},"additionalProperties":false},"linear":{"anyOf":[{"type":"object","properties":{"revision":{"type":"integer"},"token_configured":{"type":"boolean"},"team_id":{"type":["string","null"]},"label_ids":{"type":"array","items":{"type":"string"}},"reply_marker":{"type":["string","null"]},"readiness":{"type":"object","properties":{"state":{"type":"string","enum":["unconfigured","unverified","queued","ready","failed","prepared","sent","uncertain","blocked"]},"reason":{"type":["string","null"]},"verified_at":{"type":["string","null"],"format":"date-time"},"resource_types":{"type":"array","items":{"type":"string","enum":["Issue","Attachment","Comment"]}}},"additionalProperties":false},"webhook":{"type":"object","properties":{"state":{"type":"string","enum":["unconfigured","unverified","queued","ready","failed","prepared","sent","uncertain","blocked"]},"reason":{"type":["string","null"]},"verified_at":{"type":["string","null"],"format":"date-time"},"resource_types":{"type":"array","items":{"type":"string","enum":["Issue","Attachment","Comment"]}}},"additionalProperties":false},"teams":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"additionalProperties":false}},"labels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"additionalProperties":false}},"stale":{"type":"boolean"}},"additionalProperties":false},{"type":"null"}]},"grants":{"type":"array","items":{"type":"object","properties":{"user_id":{"type":"integer"},"account_id":{"type":"integer"},"capabilities":{"type":"array","items":{"type":"string","enum":["read_internal","read_attachments","read_diagnostics","reply","note","assign","classify","transition"]}},"revision":{"type":"integer"}},"additionalProperties":false}},"capabilities":{"type":"object","properties":{"configure_sharing":{"type":"boolean"},"configure_linear":{"type":"boolean"},"configure_support":{"type":"boolean"},"manage_support_grants":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false},"example":{"sharing":{"account_id":1,"mode":"disabled","revision":"sample revision","installation_mode":"disabled","account_mode":"disabled","source":"sample source","changed_at":"2026-01-15T10:30:00.000Z"},"support":{"public_name":"sample public name","signature":"sample signature","public_url":"https://example.com/resource","neutral_terms":["sample neutral term"],"expose_tracker_links":true,"revision":1},"linear":{"revision":1,"token_configured":true,"team_id":"sample team id","label_ids":["sample label id"],"reply_marker":"sample reply marker","readiness":{"state":"unconfigured","reason":"Sample reason.","verified_at":"2026-01-15T10:30:00.000Z","resource_types":["Issue"]},"webhook":{"state":"unconfigured","reason":"Sample reason.","verified_at":"2026-01-15T10:30:00.000Z","resource_types":["Issue"]},"teams":[{"id":"sample id","name":"Sample Name"}],"labels":[{"id":"sample id","name":"Sample Name"}],"stale":true},"grants":[{"user_id":1,"account_id":1,"capabilities":["read_internal"],"revision":1}],"capabilities":{"configure_sharing":true,"configure_linear":true,"configure_support":true,"manage_support_grants":true}}}}},"401":{"description":"Unauthorized"},"404":{"description":"The scoped record is absent.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["forbidden_scope","not_found","invalid_request","idempotency_required","idempotency_conflict","stale_revision","reason_required","summary_required","transition_pending","invalid_transition","invalid_classification","invalid_duplicate","invalid_authority","destination_unavailable","invalid_remote_clock","policy_blocked","stale_preview","preview_expired","invalid_selection","attachment_invalid","consent_required","delivery_in_flight","reconciliation_unavailable","preparation_failed","outbox_unavailable"]},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},"example":{"error":{"code":"forbidden_scope","message":"Sample message text."}}}}},"403":{"description":"The principal is outside the required scope.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["forbidden_scope","not_found","invalid_request","idempotency_required","idempotency_conflict","stale_revision","reason_required","summary_required","transition_pending","invalid_transition","invalid_classification","invalid_duplicate","invalid_authority","destination_unavailable","invalid_remote_clock","policy_blocked","stale_preview","preview_expired","invalid_selection","attachment_invalid","consent_required","delivery_in_flight","reconciliation_unavailable","preparation_failed","outbox_unavailable"]},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},"example":{"error":{"code":"forbidden_scope","message":"Sample message text."}}}}},"409":{"description":"The revision, pending intent or idempotency request conflicts.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["forbidden_scope","not_found","invalid_request","idempotency_required","idempotency_conflict","stale_revision","reason_required","summary_required","transition_pending","invalid_transition","invalid_classification","invalid_duplicate","invalid_authority","destination_unavailable","invalid_remote_clock","policy_blocked","stale_preview","preview_expired","invalid_selection","attachment_invalid","consent_required","delivery_in_flight","reconciliation_unavailable","preparation_failed","outbox_unavailable"]},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},"example":{"error":{"code":"forbidden_scope","message":"Sample message text."}}}}},"422":{"description":"The command or attachment is invalid.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["forbidden_scope","not_found","invalid_request","idempotency_required","idempotency_conflict","stale_revision","reason_required","summary_required","transition_pending","invalid_transition","invalid_classification","invalid_duplicate","invalid_authority","destination_unavailable","invalid_remote_clock","policy_blocked","stale_preview","preview_expired","invalid_selection","attachment_invalid","consent_required","delivery_in_flight","reconciliation_unavailable","preparation_failed","outbox_unavailable"]},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},"example":{"error":{"code":"forbidden_scope","message":"Sample message text."}}}}},"503":{"description":"The operation could not durably accept its required outbox work. No command effect is committed.","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["forbidden_scope","not_found","invalid_request","idempotency_required","idempotency_conflict","stale_revision","reason_required","summary_required","transition_pending","invalid_transition","invalid_classification","invalid_duplicate","invalid_authority","destination_unavailable","invalid_remote_clock","policy_blocked","stale_preview","preview_expired","invalid_selection","attachment_invalid","consent_required","delivery_in_flight","reconciliation_unavailable","preparation_failed","outbox_unavailable"]},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}]},"example":{"error":{"code":"forbidden_scope","message":"Sample message text."}}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/bug_report_management/sharing":{"post":{"tags":["Bug Reports"],"operationId":"auto_post_api_v1_accounts_account_id_bug_report_management_sharing","summary":"Account bug reports configure sharing","description":"Authenticated Bug Reports operation. Uses the same domain authorization and command implementation as the console. Provider calls run only in committed workers.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Authorized response. Queued denotes local intent, never remote confirmation.","content":{"application/json":{"schema":{"type":"object","properties":{"sharing":{"type":"object","properties":{"account_id":{"type":["integer","null"]},"mode":{"type":"string","enum":["disabled","manual","automatic"]},"revision":{"type":"string"},"installation_mode":{"type":"string","enum":["disabled","manual","automatic"]},"account_mode":{"type":["string","null"],"enum":["disabled","manual","automatic",null]},"source":{"type":"string"},"changed_at":{"type":["string","null"],"format":"date-time"}},"additionalProperties":false},"support":{"type":"object","properties":{"public_name":{"type":["string","null"],"maxLength":100},"signature":{"type":["string","null"],"maxLength":100},"public_url":{"type":["string","null"],"maxLength":500},"neutral_terms":{"type":"array","items":{"type":"string"},"maxItems":20},"expose_tracker_links":{"type":"boolean"},"revision":{"type":"integer"}},"additionalProperties":false},"linear":{"anyOf":[{"type":"object","properties":{"revision":{"type":"integer"},"token_configured":{"type":"boolean"},"team_id":{"type":["string","null"]},"label_ids":{"type":"array","items":{"type":"string"}},"reply_marker":{"type":["string","null"]},"readiness":{"type":"object","properties":{"state":{"type":"string","enum":["unconfigured","unverified","queued","ready","failed","prepared","sent","uncertain","blocked"]},"reason":{"type":["string","null"]},"verified_at":{"type":["string","null"],"format":"date-time"},"resource_types":{"type":"array","items":{"type":"string","enum":["Issue","Attachment","Comment"]}}},"additionalProperties":false},"webhook":{"type":"object","properties":{"state":{"type":"string","enum":["unconfigured","unverified","queued","ready","failed","prepared","sent","uncertain","blocked"]},"reason":{"type":["string","null"]},"verified_at":{"type":["string","null"],"format":"date-time"},"resource_types":{"type":"array","items":{"type":"string","enum":["Issue","Attachment","Comment"]}}},"additionalProperties":false},"teams":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"additionalProperties":false}},"labels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"additionalProperties":false}},"stale":{"type":"boolean"}},"additionalProperties":false},{"type":"null"}]},"grants":{"type":"array","items":{"type":"object","properties":{"user_id":{"type":"integer"},"account_id":{"type":"integer"},"capabilities":{"type":"array","items":{"type":"string","enum":["read_internal","read_attachments","read_diagnostics","reply","note","assign","classify","transition"]}},"revision":{"type":"integer"}},"additionalProperties":false}},"capabilities":{"type":"object","properties":{"configure_sharing":{"type":"boolean"},"configure_linear":{"type":"boolean"},"configure_support":{"type":"boolean"},"manage_support_grants":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false},"example":{"sharing":{"account_id":1,"mode":"disabled","revision":"sample revision","installation_mode":"disabled","account_mode":"disabled","source":"sample source","changed_at":"2026-01-15T10:30:00.000Z"},"support":{"public_name":"sample public name","signature":"sample signature","public_url":"https://example.com/resource","neutral_terms":["sample neutral term"],"expose_tracker_links":true,"revision":1},"linear":{"revision":1,"token_configured":true,"team_id":"sample team id","label_ids":["sample label id"],"reply_marker":"sample reply marker","readiness":{"state":"unconfigured","reason":"Sample reason.","verified_at":"2026-01-15T10:30:00.000Z","resource_types":["Issue"]},"webhook":{"state":"unconfigured","reason":"Sample reason.","verified_at":"2026-01-15T10:30:00.000Z","resource_types":["Issue"]},"teams":[{"id":"sample id","name":"Sample Name"}],"labels":[{"id":"sample id","name":"Sample Name"}],"stale":true},"grants":[{"user_id":1,"account_id":1,"capabilities":["read_internal"],"revision":1}],"capabilities":{"configure_sharing":true,"configure_linear":true,"configure_support":true,"manage_support_grants":true}}}}},"401":{"description":"Unauthorized"},"404":{"description":"The scoped record is absent.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["forbidden_scope","not_found","invalid_request","idempotency_required","idempotency_conflict","stale_revision","reason_required","summary_required","transition_pending","invalid_transition","invalid_classification","invalid_duplicate","invalid_authority","destination_unavailable","invalid_remote_clock","policy_blocked","stale_preview","preview_expired","invalid_selection","attachment_invalid","consent_required","delivery_in_flight","reconciliation_unavailable","preparation_failed","outbox_unavailable"]},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},"example":{"error":{"code":"forbidden_scope","message":"Sample message text."}}}}},"403":{"description":"The principal is outside the required scope.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["forbidden_scope","not_found","invalid_request","idempotency_required","idempotency_conflict","stale_revision","reason_required","summary_required","transition_pending","invalid_transition","invalid_classification","invalid_duplicate","invalid_authority","destination_unavailable","invalid_remote_clock","policy_blocked","stale_preview","preview_expired","invalid_selection","attachment_invalid","consent_required","delivery_in_flight","reconciliation_unavailable","preparation_failed","outbox_unavailable"]},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},"example":{"error":{"code":"forbidden_scope","message":"Sample message text."}}}}},"409":{"description":"The revision, pending intent or idempotency request conflicts.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["forbidden_scope","not_found","invalid_request","idempotency_required","idempotency_conflict","stale_revision","reason_required","summary_required","transition_pending","invalid_transition","invalid_classification","invalid_duplicate","invalid_authority","destination_unavailable","invalid_remote_clock","policy_blocked","stale_preview","preview_expired","invalid_selection","attachment_invalid","consent_required","delivery_in_flight","reconciliation_unavailable","preparation_failed","outbox_unavailable"]},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},"example":{"error":{"code":"forbidden_scope","message":"Sample message text."}}}}},"422":{"description":"The command or attachment is invalid.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["forbidden_scope","not_found","invalid_request","idempotency_required","idempotency_conflict","stale_revision","reason_required","summary_required","transition_pending","invalid_transition","invalid_classification","invalid_duplicate","invalid_authority","destination_unavailable","invalid_remote_clock","policy_blocked","stale_preview","preview_expired","invalid_selection","attachment_invalid","consent_required","delivery_in_flight","reconciliation_unavailable","preparation_failed","outbox_unavailable"]},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},"example":{"error":{"code":"forbidden_scope","message":"Sample message text."}}}}},"503":{"description":"The operation could not durably accept its required outbox work. No command effect is committed.","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["forbidden_scope","not_found","invalid_request","idempotency_required","idempotency_conflict","stale_revision","reason_required","summary_required","transition_pending","invalid_transition","invalid_classification","invalid_duplicate","invalid_authority","destination_unavailable","invalid_remote_clock","policy_blocked","stale_preview","preview_expired","invalid_selection","attachment_invalid","consent_required","delivery_in_flight","reconciliation_unavailable","preparation_failed","outbox_unavailable"]},"message":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}]},"example":{"error":{"code":"forbidden_scope","message":"Sample message text."}}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"expected_revision":{"type":"string","description":"Exact sharing policy revision returned in sharing.revision by the configuration response. Format: installation_id:installation_revision/account_policy_id:account_revision; the account pair is 0:0 when no account restriction exists. Submit this value unchanged.","example":"1:2/0:0"},"idempotency_key":{"type":"string","minLength":1,"maxLength":128},"reason":{"type":"string","minLength":1,"maxLength":2000},"mode":{"type":"string","enum":["disabled","manual","automatic"]}},"additionalProperties":false,"required":["expected_revision","idempotency_key","reason","mode"]},"example":{"expected_revision":"1:2/0:0","idempotency_key":"sample-token","reason":"Sample reason.","mode":"disabled"}}}}}},"/api/v1/accounts/{account_id}/bug_reports/{id}/read":{"post":{"tags":["Bug Reports"],"operationId":"auto_post_api_v1_accounts_account_id_bug_reports_id_read","summary":"Read messages","description":"Performs the read operation on the targeted message resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"reporter_last_read_at":{"type":["integer","null"]},"unread_count":{"type":"integer"}}},"example":{"reporter_last_read_at":1,"unread_count":5}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/bug_reports/{bug_report_id}/messages":{"get":{"tags":["Bug Reports"],"operationId":"auto_get_api_v1_accounts_account_id_bug_reports_bug_report_id_messages","summary":"List messages","description":"Returns the list of messages visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"bug_report_id":{"type":"integer"},"author_kind":{"type":"string","enum":["reporter","maintainer","system"],"description":"Author class for a bug-report thread turn (BugReportMessage#author_kind). Reporter turns belong to the local user; maintainer turns come from central support; system turns render an i18n key."},"author_name":{"type":"string"},"user_id":{"type":"integer"},"content":{"type":"string"},"visibility":{"type":"string","enum":["public","internal"],"description":"Public thread turns; internal notes are included only with the explicit private-read capability."},"edited_at":{"type":["integer","null"]},"retracted_at":{"type":["integer","null"]},"system_key":{"type":"string","enum":["message_retracted","status_resolved","status_closed","status_duplicate","status_removed"],"description":"i18n slug a system turn renders from (BugReportMessage#system_key), present only on system turns. A BARE lowercase slug the install uppercases into its own locale namespace — never a dotted path."},"origin":{"type":"string","enum":["local","hub","account_linear"],"description":"Where a bug-report thread turn was born (BugReportMessage#origin): local (this dashboard), hub (the central ConversaLabs hub), or account_linear (the customer's own Linear). Distinct from author_kind — a maintainer turn can arrive from either the hub or the account's Linear."},"client_uuid":{"type":"string"},"delivery_state":{"type":"string","enum":["pending","sent","failed","skipped","uncertain","blocked"],"description":"Single delivery verdict exposed by BugReportMessage#delivery_state. It intentionally hides the individual provider rails so clients never treat an unused rail as a delivery still in progress."},"created_at":{"type":"integer"},"external_created_at":{"type":["integer","null"]}}}},"meta":{"type":"object","properties":{"count":{"type":"integer"},"current_page":{"type":"string"},"total_pages":{"type":"string"},"per_page":{"type":"string"},"messages_count":{"type":"integer"},"last_maintainer_message_at":{"type":["integer","null"]},"reporter_last_read_at":{"type":["integer","null"]},"unread_count":{"type":"integer"},"unread":{"type":"boolean"},"can_reply":{"type":"boolean"},"can_reply_as_support":{"type":"boolean"},"can_write_private_note":{"type":"boolean"},"can_read_internal":{"type":"boolean"}}}}},"example":{"payload":[{"id":1,"bug_report_id":1,"author_kind":"reporter","author_name":"sample author name","user_id":1,"content":"Sample content text.","visibility":"public","edited_at":1,"retracted_at":1,"system_key":"message_retracted","origin":"local","client_uuid":"sample client uuid","delivery_state":"pending","created_at":1,"external_created_at":1}],"meta":{"count":5,"current_page":"sample current page","total_pages":"sample total pages","per_page":"sample per page","messages_count":5,"last_maintainer_message_at":1,"reporter_last_read_at":1,"unread_count":5,"unread":true,"can_reply":true,"can_reply_as_support":true,"can_write_private_note":true,"can_read_internal":true}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"bug_report_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."}]},"post":{"tags":["Bug Reports"],"operationId":"auto_post_api_v1_accounts_account_id_bug_reports_bug_report_id_messages","summary":"Create messages","description":"Creates a new message from the request payload. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"201":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"bug_report_id":{"type":"integer"},"author_kind":{"type":"string","enum":["reporter","maintainer","system"],"description":"Author class for a bug-report thread turn (BugReportMessage#author_kind). Reporter turns belong to the local user; maintainer turns come from central support; system turns render an i18n key."},"author_name":{"type":"string"},"user_id":{"type":"integer"},"content":{"type":"string"},"visibility":{"type":"string","enum":["public"],"description":"A reporter reply is always public; request parameters cannot select private visibility."},"edited_at":{"type":["integer","null"]},"retracted_at":{"type":["integer","null"]},"system_key":{"type":"string","enum":["message_retracted","status_resolved","status_closed","status_duplicate","status_removed"],"description":"i18n slug a system turn renders from (BugReportMessage#system_key), present only on system turns. A BARE lowercase slug the install uppercases into its own locale namespace — never a dotted path."},"origin":{"type":"string","enum":["local","hub","account_linear"],"description":"Where a bug-report thread turn was born (BugReportMessage#origin): local (this dashboard), hub (the central ConversaLabs hub), or account_linear (the customer's own Linear). Distinct from author_kind — a maintainer turn can arrive from either the hub or the account's Linear."},"client_uuid":{"type":"string"},"delivery_state":{"type":"string","enum":["pending","sent","failed","skipped","uncertain","blocked"],"description":"Single delivery verdict exposed by BugReportMessage#delivery_state. It intentionally hides the individual provider rails so clients never treat an unused rail as a delivery still in progress."},"created_at":{"type":"integer"},"external_created_at":{"type":["integer","null"]}}},"example":{"id":1,"bug_report_id":1,"author_kind":"reporter","author_name":"sample author name","user_id":1,"content":"Sample content text.","visibility":"public","edited_at":1,"retracted_at":1,"system_key":"message_retracted","origin":"local","client_uuid":"sample client uuid","delivery_state":"pending","created_at":1,"external_created_at":1}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"bug_report_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"content":{"type":"string"},"client_uuid":{"type":"string"}}},"example":{"content":"Sample content text.","client_uuid":"sample client uuid"}}}}}},"/api/v1/accounts/{account_id}/bug_reports":{"get":{"tags":["Bug Reports"],"operationId":"auto_get_api_v1_accounts_account_id_bug_reports","summary":"List bug reports","description":"Returns the list of bug reports visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"user_id":{"type":"integer"},"title":{"type":"string"},"description":{"type":"string"},"report_type":{"type":"string","enum":["bug","improvement","feature"]},"severity":{"type":"string","enum":["low","medium","high","urgent"]},"status":{"type":"string","enum":["submitted","syncing","synced","failed","in_progress","resolved","closed","duplicate"]},"component":{"type":"string"},"linear_issue_identifier":{"type":"string"},"linear_issue_url":{"type":"string"},"github_issue_url":{"type":"string"},"central_status":{"type":"string"},"hub_forward_status":{"type":"string","enum":["pending","sent","received","failed"]},"effective_status":{"type":"string","enum":["submitted","syncing","synced","failed","in_progress","resolved","closed","duplicate"],"description":"Status label the reporter should actually see (BugReport#effective_status). Same value set as `status`: it IS the report's own `status`, except while that is still a filing state (submitted/syncing/synced) and the central support triage has already reached a terminal verdict — then the terminal verdict is shown instead. `status_source` says which of the two produced this value."},"customer_status":{"type":"string","enum":["submitted","received","accepted","in_progress","resolved","closed","duplicate","failed"],"description":"Canonical reporter-facing lifecycle. This additive projection preserves the distinction between browser submission, durable hub receipt and human acceptance while keeping the legacy `status`, `effective_status` and `central_status` fields compatible. For hub-backed reports it follows the authoritative Linear issue, including terminal-to-active reopen transitions; unknown provider states are never exposed raw."},"status_source":{"type":"string","enum":["local","central"],"description":"Where the canonical customer lifecycle came from (BugReport#status_source). `central` means a recognized status from the hub-owned Linear issue; `local` means the compatibility status is the only recognized lifecycle available."},"messages_count":{"type":"integer"},"workflow_state":{"type":"string","enum":["received","triage","waiting_reporter","in_progress","resolved","closed","duplicate"],"description":"Effective local workflow state, including the read-only compatibility projection of legacy reports."},"workflow_revision":{"type":"string"},"state_authority":{"type":"string"},"transition_pending":{"type":"boolean"},"pending_workflow_state":{"description":"Requested workflow target while a transition is pending; null when no transition is pending.","oneOf":[{"type":"string","enum":["received","triage","waiting_reporter","in_progress","resolved","closed","duplicate"]},{"type":"null"}]},"resolution_summary":{"type":"string"},"support_name":{"type":"string"},"support_url":{"type":"string"},"thread_unread":{"type":"boolean"},"synced_at":{"type":["integer","null"]},"attachments":{"type":"boolean"},"created_at":{"type":"integer"},"updated_at":{"type":"integer"}}}},"meta":{"type":"object","properties":{"count":{"type":"integer"},"current_page":{"type":"string"}}}}},"example":{"payload":[{"id":1,"account_id":1,"user_id":1,"title":"Sample title","description":"A short description.","report_type":"bug","severity":"low","status":"submitted","component":"sample component","linear_issue_identifier":"sample linear issue identifier","linear_issue_url":"https://example.com/resource","github_issue_url":"https://example.com/resource","central_status":"sample central status","hub_forward_status":"pending","effective_status":"submitted","customer_status":"submitted","status_source":"local","messages_count":5,"workflow_state":"received","workflow_revision":"sample workflow revision","state_authority":"sample state authority","transition_pending":true,"pending_workflow_state":"received","resolution_summary":"sample resolution summary","support_name":"sample support name","support_url":"https://example.com/resource","thread_unread":true,"synced_at":1,"attachments":true,"created_at":1,"updated_at":1}],"meta":{"count":5,"current_page":"sample current page"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."},{"name":"id","in":"query","required":false,"schema":{"type":"integer"}},{"name":"title","in":"query","required":false,"schema":{"type":"string"}},{"name":"description","in":"query","required":false,"schema":{"type":"string"}},{"name":"report_type","in":"query","required":false,"schema":{"type":"string","enum":["bug","improvement","feature"]}},{"name":"severity","in":"query","required":false,"schema":{"type":"string","enum":["low","medium","high","urgent"]}},{"name":"component","in":"query","required":false,"schema":{"type":"string","enum":["meta_calling","voice_ai_provider"]}}]},"post":{"tags":["Bug Reports"],"operationId":"auto_post_api_v1_accounts_account_id_bug_reports","summary":"Submit a bug report","description":"Creates an account-scoped bug report and fans it out to the ConversaLabs hub (always) and the account's own Linear (when connected). `metadata` is a JSON string (deep diagnostic blob) posted alongside up to 10 attachments (screenshots / annotated images / screen recording). LGPD consent is captured when the report includes diagnostics. Requires the bug_reports feature.","security":[{"userApiKey":[]}],"responses":{"201":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"user_id":{"type":"integer"},"title":{"type":"string"},"description":{"type":"string"},"report_type":{"type":"string","enum":["bug","improvement","feature"]},"severity":{"type":"string","enum":["low","medium","high","urgent"]},"status":{"type":"string","enum":["submitted","syncing","synced","failed","in_progress","resolved","closed","duplicate"]},"component":{"type":"string"},"linear_issue_identifier":{"type":"string"},"linear_issue_url":{"type":"string"},"github_issue_url":{"type":"string"},"central_status":{"type":"string"},"hub_forward_status":{"type":"string","enum":["pending","sent","received","failed"]},"effective_status":{"type":"string","enum":["submitted","syncing","synced","failed","in_progress","resolved","closed","duplicate"],"description":"Status label the reporter should actually see (BugReport#effective_status). Same value set as `status`: it IS the report's own `status`, except while that is still a filing state (submitted/syncing/synced) and the central support triage has already reached a terminal verdict — then the terminal verdict is shown instead. `status_source` says which of the two produced this value."},"customer_status":{"type":"string","enum":["submitted","received","accepted","in_progress","resolved","closed","duplicate","failed"],"description":"Canonical reporter-facing lifecycle. This additive projection preserves the distinction between browser submission, durable hub receipt and human acceptance while keeping the legacy `status`, `effective_status` and `central_status` fields compatible. For hub-backed reports it follows the authoritative Linear issue, including terminal-to-active reopen transitions; unknown provider states are never exposed raw."},"status_source":{"type":"string","enum":["local","central"],"description":"Where the canonical customer lifecycle came from (BugReport#status_source). `central` means a recognized status from the hub-owned Linear issue; `local` means the compatibility status is the only recognized lifecycle available."},"messages_count":{"type":"integer"},"workflow_state":{"type":"string","enum":["received","triage","waiting_reporter","in_progress","resolved","closed","duplicate"],"description":"Effective local workflow state, including the read-only compatibility projection of legacy reports."},"workflow_revision":{"type":"string"},"state_authority":{"type":"string"},"transition_pending":{"type":"boolean"},"pending_workflow_state":{"description":"Requested workflow target while a transition is pending; null when no transition is pending.","oneOf":[{"type":"string","enum":["received","triage","waiting_reporter","in_progress","resolved","closed","duplicate"]},{"type":"null"}]},"resolution_summary":{"type":"string"},"support_name":{"type":"string"},"support_url":{"type":"string"},"thread_unread":{"type":"boolean"},"synced_at":{"type":["integer","null"]},"attachments":{"type":"boolean"},"created_at":{"type":"integer"},"updated_at":{"type":"integer"}}},"example":{"id":1,"account_id":1,"user_id":1,"title":"Sample title","description":"A short description.","report_type":"bug","severity":"low","status":"submitted","component":"sample component","linear_issue_identifier":"sample linear issue identifier","linear_issue_url":"https://example.com/resource","github_issue_url":"https://example.com/resource","central_status":"sample central status","hub_forward_status":"pending","effective_status":"submitted","customer_status":"submitted","status_source":"local","messages_count":5,"workflow_state":"received","workflow_revision":"sample workflow revision","state_authority":"sample state authority","transition_pending":true,"pending_workflow_state":"received","resolution_summary":"sample resolution summary","support_name":"sample support name","support_url":"https://example.com/resource","thread_unread":true,"synced_at":1,"attachments":true,"created_at":1,"updated_at":1}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["title"],"properties":{"title":{"type":"string","example":"Composer freezes on emoji"},"description":{"type":"string","example":"Clicking the emoji picker locks the reply box."},"report_type":{"type":"string","enum":["bug","improvement","feature"],"example":"bug"},"severity":{"type":"string","enum":["low","medium","high","urgent"],"example":"medium"},"component":{"type":"string","example":"conversation-composer"},"metadata":{"type":"string","description":"JSON string with the diagnostic blob (parsed + capped server-side).","example":"{\"runtime\":{\"browser\":\"Chrome 140\"}}"},"consent":{"type":"boolean","description":"Reporter's acceptance of the diagnostic-data terms (LGPD aceite).","example":true},"consent_version":{"type":"string","example":"v1"},"attachments":{"type":"array","items":{"type":"string","format":"binary"},"description":"Up to 10 files (images / screen recording)."}}}}}}}},"/api/v1/accounts/{account_id}/bug_reports/{id}":{"get":{"tags":["Bug Reports"],"operationId":"auto_get_api_v1_accounts_account_id_bug_reports_id","summary":"Get bug reports","description":"Returns the bug report identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"user_id":{"type":"integer"},"title":{"type":"string"},"description":{"type":"string"},"report_type":{"type":"string","enum":["bug","improvement","feature"]},"severity":{"type":"string","enum":["low","medium","high","urgent"]},"status":{"type":"string","enum":["submitted","syncing","synced","failed","in_progress","resolved","closed","duplicate"]},"component":{"type":"string"},"linear_issue_identifier":{"type":"string"},"linear_issue_url":{"type":"string"},"github_issue_url":{"type":"string"},"central_status":{"type":"string"},"hub_forward_status":{"type":"string","enum":["pending","sent","received","failed"]},"effective_status":{"type":"string","enum":["submitted","syncing","synced","failed","in_progress","resolved","closed","duplicate"],"description":"Status label the reporter should actually see (BugReport#effective_status). Same value set as `status`: it IS the report's own `status`, except while that is still a filing state (submitted/syncing/synced) and the central support triage has already reached a terminal verdict — then the terminal verdict is shown instead. `status_source` says which of the two produced this value."},"customer_status":{"type":"string","enum":["submitted","received","accepted","in_progress","resolved","closed","duplicate","failed"],"description":"Canonical reporter-facing lifecycle. This additive projection preserves the distinction between browser submission, durable hub receipt and human acceptance while keeping the legacy `status`, `effective_status` and `central_status` fields compatible. For hub-backed reports it follows the authoritative Linear issue, including terminal-to-active reopen transitions; unknown provider states are never exposed raw."},"status_source":{"type":"string","enum":["local","central"],"description":"Where the canonical customer lifecycle came from (BugReport#status_source). `central` means a recognized status from the hub-owned Linear issue; `local` means the compatibility status is the only recognized lifecycle available."},"messages_count":{"type":"integer"},"workflow_state":{"type":"string","enum":["received","triage","waiting_reporter","in_progress","resolved","closed","duplicate"],"description":"Effective local workflow state, including the read-only compatibility projection of legacy reports."},"workflow_revision":{"type":"string"},"state_authority":{"type":"string"},"transition_pending":{"type":"boolean"},"pending_workflow_state":{"description":"Requested workflow target while a transition is pending; null when no transition is pending.","oneOf":[{"type":"string","enum":["received","triage","waiting_reporter","in_progress","resolved","closed","duplicate"]},{"type":"null"}]},"resolution_summary":{"type":"string"},"support_name":{"type":"string"},"support_url":{"type":"string"},"thread_unread":{"type":"boolean"},"synced_at":{"type":["integer","null"]},"attachments":{"type":"boolean"},"created_at":{"type":"integer"},"updated_at":{"type":"integer"}}},"example":{"id":1,"account_id":1,"user_id":1,"title":"Sample title","description":"A short description.","report_type":"bug","severity":"low","status":"submitted","component":"sample component","linear_issue_identifier":"sample linear issue identifier","linear_issue_url":"https://example.com/resource","github_issue_url":"https://example.com/resource","central_status":"sample central status","hub_forward_status":"pending","effective_status":"submitted","customer_status":"submitted","status_source":"local","messages_count":5,"workflow_state":"received","workflow_revision":"sample workflow revision","state_authority":"sample state authority","transition_pending":true,"pending_workflow_state":"received","resolution_summary":"sample resolution summary","support_name":"sample support name","support_url":"https://example.com/resource","thread_unread":true,"synced_at":1,"attachments":true,"created_at":1,"updated_at":1}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/custom_script_data":{"get":{"tags":["Custom Scripts"],"operationId":"auto_get_api_v1_accounts_account_id_custom_script_data","summary":"List custom script data","description":"Returns the list of custom script data visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"name_key":{"type":"string"},"scope":{"type":"string"},"payload":{"type":"string"}}}},"example":[{"name_key":"sample-token","scope":"sample scope","payload":"sample payload"}]}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."}]},"post":{"tags":["Custom Scripts"],"operationId":"auto_post_api_v1_accounts_account_id_custom_script_data","summary":"Upsert a custom-script KV entry","description":"Writes a JSON value under name_key in the given scope (installation/account/user; default user). installation/account writes require an account admin; user scope is always self.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"name_key":{"type":"string"},"scope":{"type":"string"},"payload":{"type":"string"}}},"example":{"name_key":"sample-token","scope":"sample scope","payload":"sample payload"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name_key"],"properties":{"scope":{"type":"string","enum":["installation","account","user"],"description":"Storage scope (default user).","example":"user"},"name_key":{"type":"string","description":"The storage key.","example":"last_seen_banner"},"value":{"description":"Opaque JSON value (object/array/scalar), size-limited server-side.","example":{"dismissed":true}}}},"example":{"scope":"user","name_key":"last_seen_banner","value":{"dismissed":true}}}}}}},"/api/v1/accounts/{account_id}/custom_script_data/{name_key}":{"get":{"tags":["Custom Scripts"],"operationId":"auto_get_api_v1_accounts_account_id_custom_script_data_name_key","summary":"Get custom script data","description":"Returns the custom script data identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"name_key":{"type":"string"},"scope":{"type":"string"},"payload":{"type":"string"}}},"example":{"name_key":"sample-token","scope":"sample scope","payload":"sample payload"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"name_key","in":"path","required":true,"schema":{"type":"string"}}]},"patch":{"tags":["Custom Scripts"],"operationId":"auto_patch_api_v1_accounts_account_id_custom_script_data_name_key","summary":"Update custom script data","description":"Updates the custom script data identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"name_key":{"type":"string"},"scope":{"type":"string"},"payload":{"type":"string"}}},"example":{"name_key":"sample-token","scope":"sample scope","payload":"sample payload"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"name_key","in":"path","required":true,"schema":{"type":"string"}}]},"put":{"tags":["Custom Scripts"],"operationId":"auto_put_api_v1_accounts_account_id_custom_script_data_name_key","summary":"Update custom script data","description":"Updates the custom script data identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"name_key":{"type":"string"},"scope":{"type":"string"},"payload":{"type":"string"}}},"example":{"name_key":"sample-token","scope":"sample scope","payload":"sample payload"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"name_key","in":"path","required":true,"schema":{"type":"string"}}]},"delete":{"tags":["Custom Scripts"],"operationId":"auto_delete_api_v1_accounts_account_id_custom_script_data_name_key","summary":"Delete custom script data","description":"Deletes the custom script data identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Success (no content)"},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"name_key","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/custom_scripts/{id}/runs":{"post":{"tags":["Custom Scripts"],"operationId":"auto_post_api_v1_accounts_account_id_custom_scripts_id_runs","summary":"Report the outcome of a custom script run","description":"Reports back how an injected custom script behaved in the browser, which is what feeds the health indicator and the last error shown next to the script. The report is stored without re-triggering the hot-reload broadcast, and an identical consecutive report is discarded so a looping script cannot flood the record. System-managed branding scripts are never automatically disabled. Operator scripts are durably contained only for a reproduced global storm. A script-local DOM scan storm stops the script in its current browser session; its report and legacy unassigned reports remain non-punitive. Page paths may be included in the message; identity segments are masked and incident time is recorded without changing the response shape. Error reports send only status and message; stack traces, raw URLs and run-on metadata are not sent. The endpoint always returns an EMPTY body — HTTP 200 whether stored or discarded as a duplicate.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The report was stored, or discarded because it repeats the last one. Empty body in both cases."},"401":{"description":"Unauthorized"},"404":{"description":"No custom script with this id exists. Empty body."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","description":"Outcome of the run. The storm value is recorded as an error. It durably contains only operator scripts with reproduced global provenance; managed system scripts, DOM scan reports and legacy unassigned reports are never automatically disabled.","enum":["ok","error","unknown","storm"]},"message":{"type":"string","description":"Optional error detail from the browser. Anything beyond the first 2000 characters is discarded."}},"required":["status"]},"example":{"status":"error","message":"TypeError: Cannot read properties of null (reading 'dataset')"}}}}}},"/api/v1/accounts/{account_id}/custom_scripts/payload":{"get":{"tags":["Custom Scripts"],"operationId":"auto_get_api_v1_accounts_account_id_custom_scripts_payload","summary":"Get the active custom-script payload for the current surface","description":"Returns the sanitized, camelCased list of enabled dashboard custom scripts matching the supplied path. Data only — never raw script or style markup. Empty when the kill switch is on or nothing matches.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Ordered list of custom scripts to inject.","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","example":9},"name":{"type":"string","example":"Hide Powered By"},"surface":{"type":"string","enum":["dashboard","portal","widget"],"example":"dashboard"},"type":{"type":"string","enum":["javascript","css"],"example":"javascript"},"content":{"type":"string","example":"console.log('hi')"},"runOn":{"type":"string","enum":["page_load","route_change","persistent"],"example":"page_load"},"urlPattern":{"type":"string","example":"/app/accounts/*/conversations/*"},"allowStoreWrite":{"type":"boolean","example":false},"version":{"type":"integer","example":4},"settings":{"type":"object","additionalProperties":true,"description":"Settings map for this record; the key set depends on the settings scope."}}}},"example":[{"id":9,"name":"Hide Powered By","surface":"dashboard","type":"javascript","content":"console.log('hi')","runOn":"page_load","urlPattern":"/app/accounts/*/conversations/*","allowStoreWrite":false,"version":4,"settings":{}}]}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"path","in":"query","required":false,"description":"Dashboard path the scripts are being requested for. Scripts whose run rules target a path only come back when it matches; omitted, it is treated as an empty path.","schema":{"type":"string"},"example":"/app/accounts/1/conversations"}]}},"/api/v1/accounts/{account_id}/channels/twilio_channel":{"post":{"tags":["Channels"],"operationId":"auto_post_api_v1_accounts_account_id_channels_twilio_channel","summary":"Create a Twilio SMS or WhatsApp inbox","description":"Administrator-only creation. The Account Auth Token is always required for inbound signature validation; API Key SID and API Key Secret are an optional complete pair for outbound/provider management. For rolling compatibility, the administrator inbox representation retains the historic auth_token, account_sid, and api_key_sid fields and must be handled as sensitive; the dedicated twilio_account_auth_token, api_key_secret, and durable reconciliation snapshot are never serialized. The deprecated historical api_key_sid plus auth_token shape remains accepted as an outbound-only legacy inbox and returns 200 with account_auth_token_required; it never authenticates callbacks and must be reconnected with an Account Auth Token. Both modern credential planes are prospectively verified before either secret is stored. Callback provider work starts only after the inbox commit: an ambiguous apply returns 202 with the committed inbox and typed recovery state, so clients must open Settings rather than submit a duplicate create request.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Inbox created; modern credentials configure callbacks, while the deprecated historical API-key payload returns an outbound-only account_auth_token_required state.","content":{"application/json":{"schema":{"type":"object","required":["id","channel_type","twilio_credential_state","api_key_configured"],"properties":{"id":{"type":"integer","format":"int64","example":42},"channel_type":{"type":"string","enum":["Channel::TwilioSms"],"description":"The inbox channel class — identifies which messaging channel backs the inbox."},"twilio_credential_state":{"type":"string","enum":["ready","pending","failed","dead_letter","account_auth_token_required","reconciliation_required"],"example":"ready","description":"Durable Twilio credential lifecycle derived from Channel::TwilioSms. A reconciliation-required state is fail-closed until the provider outcome has been verified."},"api_key_configured":{"type":"boolean","example":false}}},"example":{"id":42,"channel_type":"Channel::TwilioSms","twilio_credential_state":"ready","api_key_configured":false}}}},"202":{"description":"Inbox committed; callback reconciliation remains durable and recoverable in Settings","content":{"application/json":{"schema":{"type":"object","required":["id","channel_type","twilio_credential_state","reconciliation_required","reconciliation_error_code"],"properties":{"id":{"type":"integer","format":"int64","example":42},"channel_type":{"type":"string","enum":["Channel::TwilioSms"],"description":"The inbox channel class — identifies which messaging channel backs the inbox."},"twilio_credential_state":{"type":"string","enum":["pending","failed"],"example":"failed","description":"Durable Twilio credential lifecycle derived from Channel::TwilioSms. A reconciliation-required state is fail-closed until the provider outcome has been verified."},"reconciliation_required":{"type":"boolean","enum":[true]},"reconciliation_error_code":{"type":"string","enum":["reconciliation_required"]}}},"example":{"id":42,"channel_type":"Channel::TwilioSms","twilio_credential_state":"failed","reconciliation_required":true,"reconciliation_error_code":"reconciliation_required"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"422":{"description":"Credentials were incomplete, could not be verified, or encryption is unavailable; no inbox was stored","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["account_auth_token_required","api_key_pair_required","credentials_invalid","encryption_required"]},"message":{"type":"string"}}}}},"example":{"error":{"code":"account_auth_token_required","message":"Sample message text."}}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["twilio_channel"],"properties":{"twilio_channel":{"type":"object","required":["name","medium","account_sid"],"properties":{"name":{"type":"string","example":"Support SMS"},"medium":{"type":"string","enum":["sms","whatsapp"],"example":"sms"},"account_sid":{"type":"string","writeOnly":true,"example":"ACsampleaccountsid"},"account_auth_token":{"type":"string","format":"password","writeOnly":true,"example":"sample-account-auth-token"},"auth_token":{"type":"string","format":"password","writeOnly":true,"deprecated":true,"description":"Deprecated Basic-auth compatibility alias. With api_key_sid and no api_key_secret, it is accepted only as the historical API Key Secret for an outbound-only legacy inbox; reconnect with account_auth_token before callbacks can be accepted."},"api_key_sid":{"type":"string","writeOnly":true,"example":"SKsampleapikeysid"},"api_key_secret":{"type":"string","format":"password","writeOnly":true,"example":"sample-api-key-secret"},"phone_number":{"type":["string","null"],"example":"+15550100100"},"messaging_service_sid":{"type":["string","null"],"example":"MGsamplemessagingservice"}},"oneOf":[{"required":["account_auth_token"]},{"required":["auth_token"]}]}}},"example":{"twilio_channel":{"name":"Support SMS","medium":"sms","account_sid":"ACsampleaccountsid","account_auth_token":"sample-account-auth-token","phone_number":"+15550100100"}}}}}}},"/api/v1/accounts/{account_id}/conversations/search":{"get":{"tags":["Conversations"],"operationId":"auto_get_api_v1_accounts_account_id_conversations_search","summary":"Search conversations","description":"Full-text search restricted to conversation messages. Requires a `q` query parameter.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"meta":{"type":"object","properties":{"mine_count":{"type":"integer"},"unassigned_count":{"type":"integer"},"all_count":{"type":"integer"},"mine_unread_count":{"type":"integer"},"unassigned_unread_count":{"type":"integer"},"all_unread_count":{"type":"integer"}}},"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"uuid":{"type":"string"},"created_at":{"type":"integer"},"contact":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"}}},"inbox":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"channel_type":{"type":"string","enum":["Channel::Api","Channel::Email","Channel::FacebookPage","Channel::Instagram","Channel::Line","Channel::Sms","Channel::Telegram","Channel::Tiktok","Channel::TwilioSms","Channel::TwitterProfile","Channel::WebWidget","Channel::Whatsapp"],"description":"The inbox channel class — identifies which messaging channel backs the inbox."},"logical_inbox_id":{"type":"integer"}}},"messages":{"type":"array","items":{"type":"object","properties":{"content":{"type":"string"},"id":{"type":"integer"},"sender_name":{"type":"string"},"message_type":{"type":"string","enum":["incoming","outgoing","activity","template"],"description":"Direction/kind of the message."},"created_at":{"type":"integer"}}}},"account_id":{"type":"integer"}}}}}},"example":{"meta":{"mine_count":5,"unassigned_count":5,"all_count":5,"mine_unread_count":5,"unassigned_unread_count":5,"all_unread_count":5},"payload":[{"id":1,"uuid":"sample uuid","created_at":1,"contact":{"id":1,"name":"Sample Name"},"inbox":{"id":1,"name":"Sample Name","channel_type":"Channel::Api","logical_inbox_id":1},"messages":[{"content":"Sample content text.","id":1,"sender_name":"sample sender name","message_type":"incoming","created_at":1}],"account_id":1}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"integer"}},{"name":"q","in":"query","required":true,"description":"Text to search in incoming and outgoing conversation messages.","schema":{"type":"string","minLength":1},"example":"pedido atrasado"},{"name":"page","in":"query","required":false,"description":"One-based results page.","schema":{"type":"integer","minimum":1,"default":1}}]}},"/api/v1/accounts/{account_id}/conversations/unread_counts":{"get":{"tags":["Conversations"],"operationId":"auto_get_api_v1_accounts_account_id_conversations_unread_counts","summary":"List unread counts","description":"Returns the list of unread counts visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"string"}}},"example":{"payload":"sample payload"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."}]}},"/api/v1/accounts/{account_id}/conversations/pinned":{"get":{"tags":["Conversations"],"operationId":"auto_get_api_v1_accounts_account_id_conversations_pinned","summary":"List pins","description":"Returns the list of pins visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","properties":{"meta":{"type":"object","properties":{"sender":{"type":"object","properties":{"additional_attributes":{"type":"object","additionalProperties":true,"description":"Channel- and source-specific metadata for this record (e.g. browser info, referer, social profile identifiers). The key set depends on the originating channel."},"availability_status":{"type":"string","enum":["online","offline","busy"],"description":"Realtime availability. Contacts report online/offline (presence-based); agents/users additionally report busy (their configured availability)."},"email":{"type":"string","format":"email"},"id":{"type":"integer"},"name":{"type":"string"},"phone_number":{"type":"string"},"blocked":{"type":"string"},"contact_type":{"type":"string","enum":["visitor","lead","customer"]},"identifier":{"type":"string"},"company_id":{"type":"integer"},"organization_id":{"type":"integer"},"referred_by_affiliate_id":{"type":"integer"},"referred_by_affiliate_name":{"type":["string","null"]},"owner_id":{"type":"integer"},"legal_type":{"type":"string","enum":["individual","business"]},"tax_id":{"type":"string","description":"The fiscal identifier (CPF/CNPJ/EIN/VAT); validated and stored encrypted on write. Read payloads return the real value to an authenticated human agent, and a type-aware mask (e.g. \"***.***.***-09\") when a role field rule masks it or the caller is a bot; a hidden rule omits the key. Webhooks, exports and message variables always carry the masked form."},"tax_id_type":{"type":"string","enum":["br_cpf","br_cnpj","us_ein","eu_vat","uk_vat","generic"],"description":"The fiscal identifier scheme used to validate and mask the tax_id (CPF/CNPJ check digits, EIN, EU/UK VAT or a generic fallback)."},"country":{"type":"integer"},"address":{"type":"object","additionalProperties":{"type":"string","description":"Address component value keyed by component name"},"description":"Postal address components keyed by component name."},"billing_address":{"type":"object","description":"Optional billing address override of the contact. An empty object means billing uses the principal address.","properties":{"zip":{"type":"string","description":"Postal/ZIP code (CEP in Brazil)"},"street":{"type":"string","description":"Street name"},"number":{"type":"string","description":"Street number"},"complement":{"type":"string","description":"Address complement (apartment, suite, block)"},"neighborhood":{"type":"string","description":"Neighborhood/district"},"city":{"type":"string","description":"City name"},"state":{"type":"string","description":"State/province (UF in Brazil)"},"country":{"type":"string","description":"Country of the postal address"}}},"thumbnail":{"type":"string"},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"last_activity_at":{"type":"integer"},"created_at":{"type":"integer"},"field_visibility":{"type":"string","enum":["visible","masked","hidden"],"description":"Per-field visibility resolved from the current access role's field_permissions (FieldVisibilityHelper). `visible` renders the real value, `masked` an obfuscated one, `hidden` omits the key entirely."},"contact_inboxes":{"type":"array","items":{"type":"object","properties":{"source_id":{"type":"integer"},"logical_inbox_id":{"type":"integer"},"inbox":{"type":"object","properties":{"id":{"type":"integer"},"avatar_url":{"type":"string"},"channel_id":{"type":"integer"},"name":{"type":"string"},"channel_type":{"type":"string","enum":["Channel::Api","Channel::Email","Channel::FacebookPage","Channel::Instagram","Channel::Line","Channel::Sms","Channel::Telegram","Channel::Tiktok","Channel::TwilioSms","Channel::TwitterProfile","Channel::WebWidget","Channel::Whatsapp"],"description":"The inbox channel class — identifies which messaging channel backs the inbox."},"provider":{"type":"string","enum":["default","whatsapp_cloud","whatsapp_web","google","microsoft"],"description":"Messaging provider backing the inbox channel (whatsapp_web is the WazMeow gateway; email uses google/microsoft; default otherwise)."}}}}}},"consent_state":{"type":"object","additionalProperties":{"type":"string","enum":["granted","denied","pending"],"description":"Consent state in force for this delivery channel."},"description":"LGPD consent state keyed by delivery channel (\"all\" is the account-wide scope that shadows the per-channel ones). A channel the contact never declared on is absent rather than pending, since the set of channels an account may use is open. Present only on single-contact payloads. Signals only — it never blocks a send."}}},"channel":{"type":"string"},"assignee":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":["integer","null"]},"account_user_id":{"type":["integer","null"]},"availability_status":{"type":"string","enum":["online","offline","busy"],"description":"Realtime availability. Contacts report online/offline (presence-based); agents/users additionally report busy (their configured availability)."},"auto_offline":{"type":"boolean"},"confirmed":{"type":"boolean"},"email":{"type":"string","format":"email"},"provider":{"type":"string","enum":["email","google_oauth2","saml"],"description":"Authentication provider the user signed up through."},"available_name":{"type":"string"},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"name":{"type":"string"},"role":{"type":"string","enum":["agent","administrator"]},"outbound_agent_name_header_policy":{"type":["string","null"]},"thumbnail":{"type":"string"},"custom_role_id":{"type":["integer","null"]},"access_role_id":{"type":["integer","null"]}}},"assignee_type":{"type":"string","enum":["AgentBot","User"],"description":"Type of the conversation assignee — an automation bot or a human agent."},"team":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"allow_auto_assign":{"type":"boolean","description":"When enabled, the team auto-assigns each newly team-assigned conversation to an available agent."},"icon":{"type":"string"},"icon_color":{"type":"string"},"account_id":{"type":"integer"},"is_member":{"type":"boolean"},"avatar_url":{"type":"string"},"thumbnail":{"type":"string"}}},"hmac_verified":{"type":["string","null"]}}},"id":{"type":"integer"},"messages":{"type":"string"},"account_id":{"type":"integer"},"uuid":{"type":"string"},"additional_attributes":{"type":"object","additionalProperties":true,"description":"Channel- and source-specific metadata for this record (e.g. browser info, referer, social profile identifiers). The key set depends on the originating channel."},"agent_last_seen_at":{"type":"integer"},"assignee_last_seen_at":{"type":"integer"},"can_reply":{"type":"boolean"},"contact_last_seen_at":{"type":"integer"},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"inbox_id":{"type":"integer"},"logical_inbox_id":{"type":"integer"},"labels":{"type":"string"},"muted":{"type":"boolean"},"snoozed_until":{"type":"string"},"status":{"type":"string","enum":["open","resolved","pending","snoozed"]},"created_at":{"type":"integer"},"updated_at":{"type":"number"},"automation_control_event_cursor":{"type":"string"},"timestamp":{"type":"integer"},"first_reply_created_at":{"type":"integer"},"unread_count":{"type":"integer"},"last_non_activity_message":{"type":"string"},"last_activity_at":{"type":"integer"},"priority":{"type":"string","enum":["low","medium","high","urgent"]},"owner_id":{"type":"integer"},"waiting_since":{"type":"integer"},"sla_policy_id":{"type":"integer"},"applied_sla":{"type":"string"},"sla_events":{"type":"string"}}}}}},"example":{"payload":[{"meta":{"sender":{"additional_attributes":{},"availability_status":"online","email":"agent@example.com","id":1,"name":"Sample Name","phone_number":"+5511999998888","blocked":"sample blocked","contact_type":"visitor","identifier":"sample-identifier","company_id":1,"organization_id":1,"referred_by_affiliate_id":1,"referred_by_affiliate_name":"sample referred by affiliate name","owner_id":1,"legal_type":"individual","tax_id":"sample tax id","tax_id_type":"br_cpf","country":1,"address":{},"billing_address":{"zip":"sample zip","street":"sample street","number":"sample number","complement":"sample complement","neighborhood":"sample neighborhood","city":"São Paulo","state":"active","country":"BR"},"thumbnail":"sample thumbnail","custom_attributes":{},"last_activity_at":1,"created_at":1,"field_visibility":"visible","contact_inboxes":[{"source_id":1,"logical_inbox_id":1,"inbox":{"id":1,"avatar_url":"https://example.com/resource","channel_id":1,"name":"Sample Name","channel_type":"Channel::Api","provider":"default"}}],"consent_state":{}},"channel":"sample channel","assignee":{"id":1,"account_id":1,"account_user_id":1,"availability_status":"online","auto_offline":true,"confirmed":true,"email":"agent@example.com","provider":"email","available_name":"sample available name","custom_attributes":{},"name":"Sample Name","role":"agent","outbound_agent_name_header_policy":"sample outbound agent name header policy","thumbnail":"sample thumbnail","custom_role_id":1,"access_role_id":1},"assignee_type":"AgentBot","team":{"id":1,"name":"Sample Name","description":"A short description.","allow_auto_assign":true,"icon":"sample icon","icon_color":"#1F93FF","account_id":1,"is_member":true,"avatar_url":"https://example.com/resource","thumbnail":"sample thumbnail"},"hmac_verified":"sample hmac verified"},"id":1,"messages":"sample messages","account_id":1,"uuid":"sample uuid","additional_attributes":{},"agent_last_seen_at":1,"assignee_last_seen_at":1,"can_reply":true,"contact_last_seen_at":1,"custom_attributes":{},"inbox_id":1,"logical_inbox_id":1,"labels":"sample labels","muted":true,"snoozed_until":"sample snoozed until","status":"open","created_at":1,"updated_at":12.5,"automation_control_event_cursor":"sample automation control event cursor","timestamp":1,"first_reply_created_at":1,"unread_count":5,"last_non_activity_message":"sample last non activity message","last_activity_at":1,"priority":"low","owner_id":1,"waiting_since":1,"sla_policy_id":1,"applied_sla":"sample applied sla","sla_events":"sample sla events"}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."}]}},"/api/v1/accounts/{account_id}/conversations/{conversation_id}/translation_settings":{"get":{"tags":["Conversations"],"operationId":"auto_get_api_v1_accounts_account_id_conversations_conversation_id_translation_settings","summary":"Get translation settings","description":"Returns the translation setting identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Translation override, effective conversation policy and current viewer language","content":{"application/json":{"schema":{"type":"object","required":["override","effective","provider"],"properties":{"override":{"$ref":"#/components/schemas/conversation_translation_override"},"effective":{"$ref":"#/components/schemas/effective_translation_settings"},"provider":{"$ref":"#/components/schemas/translation_provider_readiness"},"viewer":{"$ref":"#/components/schemas/translation_viewer"}}},"example":{"override":{"mode":"enabled","agent_language":"pt-BR","contact_language":"en","translate_incoming":true,"translate_outgoing":true,"translate_transcripts":true},"effective":{"enabled":true,"source":"feature_flag","agent_language":"pt-BR","contact_language":"en","translate_incoming":true,"translate_outgoing":true,"translate_transcripts":true,"provider_ready":true,"blocking_reasons":["provider_not_configured"],"detected_conversation_language":"en"},"provider":{"provider":"google_translate","ready":true,"blocking_reasons":["provider_not_configured"]},"viewer":{"language":"pt-BR","source":"profile"}}}}},"401":{"description":"Authentication is required"},"404":{"description":"Feature disabled or conversation not found"},"403":{"description":"Authenticated user cannot view this conversation"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"conversation_id","in":"path","required":true,"schema":{"type":"string"}}]},"patch":{"tags":["Conversations"],"operationId":"auto_patch_api_v1_accounts_account_id_conversations_conversation_id_translation_settings","summary":"Update translation settings","description":"Updates the translation setting identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Updated override and recalculated effective settings","content":{"application/json":{"schema":{"type":"object","required":["override","effective","provider"],"properties":{"override":{"$ref":"#/components/schemas/conversation_translation_override"},"effective":{"$ref":"#/components/schemas/effective_translation_settings"},"provider":{"$ref":"#/components/schemas/translation_provider_readiness"},"viewer":{"$ref":"#/components/schemas/translation_viewer"}}},"example":{"override":{"mode":"enabled","agent_language":"pt-BR","contact_language":"en","translate_incoming":true,"translate_outgoing":true,"translate_transcripts":true},"effective":{"enabled":true,"source":"feature_flag","agent_language":"pt-BR","contact_language":"en","translate_incoming":true,"translate_outgoing":true,"translate_transcripts":true,"provider_ready":true,"blocking_reasons":["provider_not_configured"],"detected_conversation_language":"en"},"provider":{"provider":"google_translate","ready":true,"blocking_reasons":["provider_not_configured"]},"viewer":{"language":"pt-BR","source":"profile"}}}}},"401":{"description":"Authentication is required"},"404":{"description":"Feature disabled or conversation not found"},"400":{"description":"Invalid mode, boolean or BCP-47 language code","content":{"application/json":{"schema":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","enum":["invalid_translation_settings"]},"message":{"type":"string"}}},"example":{"error":"invalid_translation_settings","message":"Sample message text."}}}},"403":{"description":"User cannot manage translation settings for this conversation"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"conversation_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["translation_settings"],"properties":{"translation_settings":{"$ref":"#/components/schemas/conversation_translation_override"}}},"example":{"translation_settings":{"mode":"enabled","agent_language":"pt-BR","contact_language":"en","translate_incoming":true,"translate_outgoing":true,"translate_transcripts":true}}}}}}},"/api/v1/accounts/{account_id}/conversations/{conversation_id}/translations/ensure":{"post":{"tags":["Conversations"],"operationId":"auto_post_api_v1_accounts_account_id_conversations_conversation_id_translations_ensure","summary":"Ensure viewer translations","description":"Performs the ensure viewer operation on the targeted translation resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"202":{"description":"Viewer-language catch-up accepted","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["override","effective","provider","viewer","target_language","target_source","accepted_message_ids"],"properties":{"override":{"$ref":"#/components/schemas/conversation_translation_override"},"effective":{"$ref":"#/components/schemas/effective_translation_settings"},"provider":{"$ref":"#/components/schemas/translation_provider_readiness"},"viewer":{"$ref":"#/components/schemas/translation_viewer"},"target_language":{"type":"string","example":"pt-BR"},"target_source":{"type":"string","enum":["profile","conversation","inbox","ui_locale","account","default"]},"accepted_message_ids":{"type":"array","maxItems":50,"items":{"type":"integer","minimum":1}}}},"example":{"override":{"mode":"enabled","agent_language":"pt-BR","contact_language":"en","translate_incoming":true,"translate_outgoing":true,"translate_transcripts":true},"effective":{"enabled":true,"source":"feature_flag","agent_language":"pt-BR","contact_language":"en","translate_incoming":true,"translate_outgoing":true,"translate_transcripts":true,"provider_ready":true,"blocking_reasons":["provider_not_configured"],"detected_conversation_language":"en"},"provider":{"provider":"google_translate","ready":true,"blocking_reasons":["provider_not_configured"]},"viewer":{"language":"pt-BR","source":"profile"},"target_language":"pt-BR","target_source":"profile","accepted_message_ids":[1]}}}},"401":{"description":"Authentication is required"},"404":{"description":"Feature disabled or conversation not found"},"400":{"description":"Invalid, excessive, external or client-targeted catch-up request","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error","message"],"properties":{"error":{"type":"string","enum":["invalid_translation_catch_up"]},"message":{"type":"string"}}},"example":{"error":"invalid_translation_catch_up","message":"Sample message text."}}}},"403":{"description":"Authenticated user cannot view this conversation, or caller is non-human"},"429":{"description":"Catch-up was already requested for this user and conversation in the current throttle window","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","enum":["translation_catch_up_rate_limited"]}}},"example":{"error":"translation_catch_up_rate_limited"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"conversation_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["message_ids"],"description":"The viewer target is derived from the authenticated profile; no client target is accepted.","properties":{"message_ids":{"type":"array","minItems":1,"maxItems":50,"uniqueItems":true,"items":{"type":"integer","minimum":1}},"include_transcripts":{"type":"boolean","default":true}}},"example":{"message_ids":[1],"include_transcripts":true}}}}}},"/api/v1/accounts/{account_id}/conversations/{conversation_id}/audio_transcription_settings":{"get":{"tags":["Conversations"],"operationId":"auto_get_api_v1_accounts_account_id_conversations_conversation_id_audio_transcription_settings","summary":"Get the audio transcription policy of a conversation","description":"Returns the stored conversation override, the effective policy after it is applied over the inbox scope, and whether a speech-to-text key is reachable.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","required":["override","effective","inbox_enabled","provider"],"properties":{"override":{"type":"object","required":["mode"],"description":"The stored conversation override. Scope keys are present only when explicitly set, and apply only while mode is `enabled`.","properties":{"mode":{"type":"string","enum":["inherit","enabled","disabled"],"description":"`inherit` follows the inbox; `enabled` transcribes even when the inbox toggle is off; `disabled` never transcribes."},"inbound":{"type":"boolean"},"outbound_agent":{"type":"boolean"}},"additionalProperties":false},"effective":{"type":"object","required":["enabled","source","inbound","outbound_agent"],"description":"The policy this conversation actually runs under, after the conversation override is applied over the inbox.","properties":{"enabled":{"type":"boolean"},"source":{"type":"string","enum":["inbox","conversation","disabled"],"description":"Where the answer came from, or `disabled` when the inbox master toggle is off."},"inbound":{"type":"boolean"},"outbound_agent":{"type":"boolean"}},"additionalProperties":false},"inbox_enabled":{"type":["boolean","null"],"description":"The inbox master toggle, so the panel can explain an override that has nothing to inherit."},"provider":{"type":"object","required":["ready","providers","blocking_reasons"],"description":"Whether a speech-to-text key is reachable for this account, and where it comes from.","properties":{"ready":{"type":"boolean","description":"False when no OpenAI or Groq key is configured, in which case transcription can never produce text."},"providers":{"type":"array","description":"Every provider with a usable key, in the order they are tried.","items":{"type":"object","required":["name","source"],"properties":{"name":{"type":"string","enum":["groq","openai"]},"source":{"type":"string","enum":["account","environment"],"description":"Whether the key comes from this account's integration or from the server environment."}},"additionalProperties":false}},"blocking_reasons":{"type":"array","description":"Empty when ready.","items":{"type":"string","enum":["provider_not_configured"]}}},"additionalProperties":false}},"additionalProperties":false},"example":{"override":{"mode":"enabled","inbound":true,"outbound_agent":true},"effective":{"enabled":true,"source":"conversation","inbound":true,"outbound_agent":true},"inbox_enabled":true,"provider":{"ready":true,"providers":[{"name":"openai","source":"environment"}],"blocking_reasons":[]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"conversation_id","in":"path","required":true,"schema":{"type":"string"}}]},"patch":{"tags":["Conversations"],"operationId":"auto_patch_api_v1_accounts_account_id_conversations_conversation_id_audio_transcription_settings","summary":"Override the audio transcription policy for a conversation","description":"Stores the override in the conversation's `additional_attributes`. `mode: enabled` transcribes this conversation even when the inbox toggle is off; `mode: disabled` never transcribes it. Scope keys are honoured only while the mode is `enabled`.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","required":["override","effective","inbox_enabled","provider"],"properties":{"override":{"type":"object","required":["mode"],"description":"The stored conversation override. Scope keys are present only when explicitly set, and apply only while mode is `enabled`.","properties":{"mode":{"type":"string","enum":["inherit","enabled","disabled"],"description":"`inherit` follows the inbox; `enabled` transcribes even when the inbox toggle is off; `disabled` never transcribes."},"inbound":{"type":"boolean"},"outbound_agent":{"type":"boolean"}},"additionalProperties":false},"effective":{"type":"object","required":["enabled","source","inbound","outbound_agent"],"description":"The policy this conversation actually runs under, after the conversation override is applied over the inbox.","properties":{"enabled":{"type":"boolean"},"source":{"type":"string","enum":["inbox","conversation","disabled"],"description":"Where the answer came from, or `disabled` when the inbox master toggle is off."},"inbound":{"type":"boolean"},"outbound_agent":{"type":"boolean"}},"additionalProperties":false},"inbox_enabled":{"type":["boolean","null"],"description":"The inbox master toggle, so the panel can explain an override that has nothing to inherit."},"provider":{"type":"object","required":["ready","providers","blocking_reasons"],"description":"Whether a speech-to-text key is reachable for this account, and where it comes from.","properties":{"ready":{"type":"boolean","description":"False when no OpenAI or Groq key is configured, in which case transcription can never produce text."},"providers":{"type":"array","description":"Every provider with a usable key, in the order they are tried.","items":{"type":"object","required":["name","source"],"properties":{"name":{"type":"string","enum":["groq","openai"]},"source":{"type":"string","enum":["account","environment"],"description":"Whether the key comes from this account's integration or from the server environment."}},"additionalProperties":false}},"blocking_reasons":{"type":"array","description":"Empty when ready.","items":{"type":"string","enum":["provider_not_configured"]}}},"additionalProperties":false}},"additionalProperties":false},"example":{"override":{"mode":"enabled","inbound":true,"outbound_agent":true},"effective":{"enabled":true,"source":"conversation","inbound":true,"outbound_agent":true},"inbox_enabled":true,"provider":{"ready":true,"providers":[{"name":"openai","source":"environment"}],"blocking_reasons":[]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"400":{"description":"The submitted settings carry an unknown mode or an unsupported key.","content":{"application/json":{"schema":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","enum":["invalid_audio_transcription_settings"]},"message":{"type":"string"}},"additionalProperties":false},"example":{"error":"invalid_audio_transcription_settings","message":"The audio transcription settings are invalid."}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"conversation_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["audio_transcription_settings"],"properties":{"audio_transcription_settings":{"type":"object","properties":{"mode":{"type":"string","enum":["inherit","enabled","disabled"]},"inbound":{"type":"boolean"},"outbound_agent":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false},"example":{"audio_transcription_settings":{"mode":"enabled","inbound":true,"outbound_agent":true}}}}}}},"/api/v1/accounts/{account_id}/conversations/{conversation_id}/messages/by_client_id":{"get":{"tags":["Conversations"],"operationId":"auto_get_api_v1_accounts_account_id_conversations_conversation_id_messages_by_client_id","summary":"Recover a message by its durable send identity","description":"Read the result of an earlier create without sending again. The receipt must belong to the authenticated author, account and originally requested conversation. This endpoint also rechecks access to the message's current canonical conversation. Missing receipts return 404, hard-deleted messages return 410. Other authors cannot query this receipt.","security":[{"agentBotApiKey":[]},{"userApiKey":[]}],"responses":{"200":{"description":"The existing message, with no new send.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/message"},"example":{"client_message_id":"sample client message id","client_message_actor":"User:7","outbound_dispatch":{"state":"queued","retryable":true},"id":1,"content":"Sample content text.","content_readiness":{"state":"waiting","quality":"pending","generation":1,"content_version":1},"account_id":1,"inbox_id":1,"logical_inbox_id":1,"echo_id":"sample echo id","conversation_id":1,"message_type":0,"created_at":1,"updated_at":1,"private":true,"status":"sent","source_id":"sample source id","content_type":"text","content_attributes":{"instagram_mention":{"media_id":"sample media id","comment_id":"sample comment id","mention_type":"comment","enrichment_status":"unresolved","replyable":true,"author_id":"sample author id","author_username":"sample author username","text":"sample text","media_type":"sample media type","media_product_type":"sample media product type","permalink":"https://example.com/resource","identity_scope":{"account_id":1,"inbox_id":1,"instagram_id":"sample instagram id"},"recovery":{"state":"scheduled","reason":"Sample reason.","attempts":1,"checked_at":"2026-01-15T10:30:00.000Z","next_retry_at":"2026-01-15T10:30:00.000Z","lease_until":"2026-01-15T10:30:00.000Z"}},"translations":{},"translation":{"original_content":"sample original content","original_html_content":"sample original html content","delivery":{"status":"translated","source_language":"pt","target_language":"en","provider":"google_translate","content_digest":"sample content digest","translated_at":"2026-01-15T10:30:00.000Z","error_code":"translation_failed","cause_code":"provider_not_configured","failed_at":"2026-01-15T10:30:00.000Z"},"views":{}},"external_error":"sample external error","contact_share":{"origin":"contact_request","transport":"cloud","status":"linked","reason":"identity_owned_by_another_contact","other_contact_ids":[1],"reconciliation_id":"sample reconciliation id"}},"sender_type":"Contact","sender_id":1,"external_source_ids":{},"additional_attributes":{},"processed_message_content":"sample processed message content","sentiment":{},"conversation":{},"attachment":{},"attachments":[{"id":1,"message_id":1,"file_type":"image","account_id":1,"extension":"sample extension","data_url":"https://example.com/resource","media_readiness_revision":"sample media readiness revision","playable_audio_url":"https://example.com/resource","playable_video_url":"https://example.com/resource","video_processing":true,"video_unavailable":true,"thumb_url":"https://example.com/resource","file_size":1,"width":1,"height":1,"coordinates_lat":12.5,"coordinates_long":12.5,"fallback_title":"sample fallback title","meta":{},"transcribed_text":"sample transcribed text","transcript_translations":{"pt-BR":"Você pode me ajudar?","es":"¿Puedes ayudarme?"},"transcript_translation_states":{}}],"sender":{}}}}},"401":{"description":"Unauthorized"},"404":{"description":"No receipt for this author and conversation, or conversation unavailable."},"410":{"description":"The original message was deleted; the identity is retained as a tombstone."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"conversation_id","in":"path","required":true,"schema":{"type":"string"}},{"in":"query","name":"client_message_id","required":true,"schema":{"type":"string","minLength":1,"maxLength":128}}]}},"/api/v1/accounts/{account_id}/conversations/{conversation_id}/messages/forward":{"post":{"tags":["Conversations"],"operationId":"auto_post_api_v1_accounts_account_id_conversations_conversation_id_messages_forward","summary":"Forward messages to other conversations","description":"Copies the selected messages of this conversation (chronological order) into up to 5 target conversations as new outgoing messages. Conversation-scoped uploads are copied to new blobs scoped to each authorized destination; account-scoped files may reuse the original blob. Works across channels. WhatsApp parity for the \"Forwarded\" badge: only THIRD-PARTY messages (and messages that were already forwarded) carry it — forwarding your own message produces a clean copy; on WhatsApp (WazMeow gateway) flagged copies show the native badge on the recipient's phone. Contact and location messages are normalized from either blobless Cloud/360 attachments or Web content attributes. WhatsApp Web and WhatsApp Cloud send native cards; Cloud contact/location forwarding does not require a binary blob. Contacts that cannot be represented safely (for example, a card without a phone number) and other providers receive a localized, non-empty text fallback. Binary image, audio, video, and file attachments still require an available blob. Success per target means the copies were created and enqueued for delivery — not that they were delivered; delivery follows each channel's normal flow and failures surface on the copied messages themselves. Non-forwardable messages (private notes, activities, deleted, failed, view-once, unsupported interactive types) are rejected with 422. An unavailable file or another per-message failure does not block the remaining selected messages. `failed_messages` identifies failed source messages by id and chronological position with a sanitized error code. Created ids remain authoritative: never repeat the entire partial batch. A failed source with committed physical copies has `partial_copy`, `retryable: false` and its own `forwarded_message_ids`. Inspect the destination and send only missing content; repeating that whole source can duplicate its already-created parts. Callback failures after a committed copy retain the confirmed row id. With a unified WhatsApp inbox, a stale target id from the frozen Web history is projected onto its canonical Cloud timeline; if that history has no safe canonical link, the per-target result is `target_unavailable` and no copy is created.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"One entry per requested target, in request order (best-effort).","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"conversation_id":{"type":"integer","description":"The target conversation display id this entry refers to.","example":212},"success":{"type":"boolean","description":"True when every selected message was copied into this target.","example":false},"forwarded_message_ids":{"type":"array","description":"Ids of the copies created in the target (partial on send_failed).","items":{"type":"integer"},"example":[9921]},"error_code":{"type":"string","description":"Present only when success is false.","enum":["unauthorized","target_is_source","target_unavailable","not_found","send_failed"],"example":"send_failed"},"failed_messages":{"type":"array","description":"Present on per-message failures; successful copies are not repeated.","items":{"type":"object","required":["message_id","position","error_code"],"properties":{"message_id":{"type":"integer","description":"Source message id."},"position":{"type":"integer","minimum":1,"description":"Position in chronological source order."},"error_code":{"type":"string","enum":["attachment_unavailable","send_failed","partial_copy"]},"retryable":{"type":"boolean","description":"False when a copy of this source already exists; do not repeat the whole source."},"forwarded_message_ids":{"type":"array","description":"Confirmed persisted copies of this failed source, including post-commit errors.","items":{"type":"integer"}}}}}}}}}},"example":{"results":[{"conversation_id":212,"success":false,"forwarded_message_ids":[9921],"error_code":"send_failed","failed_messages":[{"message_id":4581,"position":1,"error_code":"partial_copy","retryable":false,"forwarded_message_ids":[9921]}]}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"422":{"description":"Request-level validation failure (caps exceeded, message outside this conversation, or a non-forwardable message). The localized error is actionable and never exposes internal message ids.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"You can forward to up to 5 conversations at once."}}},"example":{"error":"You can forward to up to 5 conversations at once."}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"conversation_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["message_ids","target_conversation_ids"],"properties":{"message_ids":{"type":"array","description":"Ids of the messages to forward (1..30, all from this conversation).","items":{"type":"integer"},"example":[4581]},"target_conversation_ids":{"type":"array","description":"Display ids of the target conversations (1..5).","items":{"type":"integer"},"example":[212]}}},"example":{"message_ids":[4581],"target_conversation_ids":[212]}}}}}},"/api/v1/accounts/{account_id}/conversations/{conversation_id}/messages/{id}/translate":{"post":{"tags":["Conversations"],"operationId":"auto_post_api_v1_accounts_account_id_conversations_conversation_id_messages_id_translate","summary":"Translate a message into another language","description":"Translates the message text with the account's translation integration and stores the result on the message, keyed by language, so the same translation is not paid for twice. The translated text is returned in the body. When the message ALREADY carries a translation for the requested language the call short-circuits and answers `200` with an EMPTY body — read the stored translations off the message instead of expecting the text back.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Translation performed. The body carries the translated text; it is EMPTY when the message already had a translation for this language.","content":{"application/json":{"schema":{"type":"object","properties":{"content":{"type":["string","null"],"description":"The translated text. Null when the integration produced nothing — typically because the translation integration is not connected for this account, or it could not handle the requested language. Nothing is stored on the message in that case."}}},"example":{"content":"Seu pedido será enviado amanhã de manhã."}}}},"401":{"description":"Unauthorized"},"404":{"description":"No message with this id exists in the conversation."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"conversation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["target_language"],"properties":{"target_language":{"type":"string","description":"Language to translate into, as the language code the translation integration expects."}}},"example":{"target_language":"pt"}}}}}},"/api/v1/accounts/{account_id}/conversations/{conversation_id}/messages/{id}/retry":{"post":{"tags":["Conversations"],"operationId":"auto_post_api_v1_accounts_account_id_conversations_conversation_id_messages_id_retry","summary":"Retry a failed message with confirmed non-delivery","description":"Reuses the existing message only when it is public, failed, and has private evidence of definite non-delivery. A provider timeout, crash or ambiguous response is not authority to resend. Scheduled/follow-up ledgers retain their own recovery flows. Source identity is reconciled before any retry, preserving the Web provider's idempotency key.","security":[{"userApiKey":[]}],"responses":{"202":{"description":"An INBOUND WhatsApp media whose bytes never arrived (media_fetch_failed) was queued for a new download — through the durable inbound unit that produced it or the persisted provider media id. The attachment lands on the same message once it arrives.","content":{"application/json":{"schema":{"type":"object","required":["status","id"],"properties":{"status":{"type":"string","enum":["queued"]},"id":{"type":"integer","description":"The message whose media download was queued."}}},"example":{"status":"queued","id":88213}}}},"200":{"description":"An eligible retry was queued, or a known provider identity was reconciled without resending. Neither is proof of recipient delivery.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/message"},"example":{"client_message_id":"sample client message id","client_message_actor":"User:7","outbound_dispatch":{"state":"queued","retryable":true},"id":1,"content":"Sample content text.","content_readiness":{"state":"waiting","quality":"pending","generation":1,"content_version":1},"account_id":1,"inbox_id":1,"logical_inbox_id":1,"echo_id":"sample echo id","conversation_id":1,"message_type":0,"created_at":1,"updated_at":1,"private":true,"status":"sent","source_id":"sample source id","content_type":"text","content_attributes":{"instagram_mention":{"media_id":"sample media id","comment_id":"sample comment id","mention_type":"comment","enrichment_status":"unresolved","replyable":true,"author_id":"sample author id","author_username":"sample author username","text":"sample text","media_type":"sample media type","media_product_type":"sample media product type","permalink":"https://example.com/resource","identity_scope":{"account_id":1,"inbox_id":1,"instagram_id":"sample instagram id"},"recovery":{"state":"scheduled","reason":"Sample reason.","attempts":1,"checked_at":"2026-01-15T10:30:00.000Z","next_retry_at":"2026-01-15T10:30:00.000Z","lease_until":"2026-01-15T10:30:00.000Z"}},"translations":{},"translation":{"original_content":"sample original content","original_html_content":"sample original html content","delivery":{"status":"translated","source_language":"pt","target_language":"en","provider":"google_translate","content_digest":"sample content digest","translated_at":"2026-01-15T10:30:00.000Z","error_code":"translation_failed","cause_code":"provider_not_configured","failed_at":"2026-01-15T10:30:00.000Z"},"views":{}},"external_error":"sample external error","contact_share":{"origin":"contact_request","transport":"cloud","status":"linked","reason":"identity_owned_by_another_contact","other_contact_ids":[1],"reconciliation_id":"sample reconciliation id"}},"sender_type":"Contact","sender_id":1,"external_source_ids":{},"additional_attributes":{},"processed_message_content":"sample processed message content","sentiment":{},"conversation":{},"attachment":{},"attachments":[{"id":1,"message_id":1,"file_type":"image","account_id":1,"extension":"sample extension","data_url":"https://example.com/resource","media_readiness_revision":"sample media readiness revision","playable_audio_url":"https://example.com/resource","playable_video_url":"https://example.com/resource","video_processing":true,"video_unavailable":true,"thumb_url":"https://example.com/resource","file_size":1,"width":1,"height":1,"coordinates_lat":12.5,"coordinates_long":12.5,"fallback_title":"sample fallback title","meta":{},"transcribed_text":"sample transcribed text","transcript_translations":{"pt-BR":"Você pode me ajudar?","es":"¿Puedes ayudarme?"},"transcript_translation_states":{}}],"sender":{}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"409":{"description":"Not failed, managed delivery or unresolved provider outcome.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["retry_not_failed","retry_managed_delivery","dispatch_outcome_unknown"]}}},"example":{"error":"sample error","code":"retry_not_failed"}}}},"422":{"description":"The message or frozen conversation is not eligible for retry; for an inbound media, nothing is left to fetch (code media_retry_ineligible or media_retry_unavailable); a WhatsApp Cloud campaign message held back because its campaign was paused or cancelled never retries (code retry_campaign_halted) — resuming the campaign sends the contact a new message instead."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"conversation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/conversations/{conversation_id}/messages/{id}/react":{"post":{"tags":["Conversations"],"operationId":"auto_post_api_v1_accounts_account_id_conversations_conversation_id_messages_id_react","summary":"React to a message with an emoji","description":"Sends a native emoji reaction on the channel that delivered the message and mirrors it into the message, so the API and the dashboard show it exactly like a reaction that arrived from the contact. An EMPTY emoji removes the reaction. Channels that cannot react accept the call and change nothing. The response carries NO body — re-read the message to see the stored reaction.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Reaction sent and mirrored, or accepted as a no-op on a channel that cannot react. Empty body."},"401":{"description":"Unauthorized"},"404":{"description":"No message with this id exists in the conversation."},"422":{"description":"The reaction could not be delivered by the channel provider. Nothing is mirrored.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable reason, localized to the account language."}}},"example":{"error":"Could not send the reaction"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"conversation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["emoji"],"properties":{"emoji":{"type":"string","description":"Emoji to apply. An empty string removes the reaction previously left by the same actor."},"by":{"type":"string","enum":["agent","contact"],"description":"Who the reaction belongs to. Defaults to the operator. `contact` records a reaction relayed on behalf of the contact and is only meaningful on mirror-only inboxes, where reactions do not arrive through a provider webhook."}}},"example":{"emoji":"👍","by":"agent"}}}}}},"/api/v1/accounts/{account_id}/conversations/{conversation_id}/messages/{id}/edit":{"post":{"tags":["Conversations"],"operationId":"auto_post_api_v1_accounts_account_id_conversations_conversation_id_messages_id_edit","summary":"Edit the text of an already-sent message","description":"Replaces the text of an outgoing message on channels that support a real remote edit, then swaps the stored content and appends an edit trail so the \"edited\" marker renders everywhere. Channels without a remote edit accept the call and change nothing, and re-sending the current text is a no-op — both answer `200 OK`. The response carries NO body: re-read the message to obtain the new content and its edit trail, or listen for the message-updated event.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Edit applied, or accepted as a no-op because the channel cannot edit remotely or the text is unchanged. Empty body."},"401":{"description":"Unauthorized"},"404":{"description":"No message with this id exists in the conversation."},"422":{"description":"The provider's edit window for this message has elapsed, or the edit call failed. Nothing is changed locally.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable reason, localized to the account language."}}},"example":{"error":"The edit window for this message has expired."}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"conversation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["content"],"properties":{"content":{"type":"string","description":"New text of the message, replacing the previous one in full. Meaningful content preserves spaces, line breaks and literal markup; whitespace-only content is not sent."}}},"example":{"content":"Your order ships tomorrow morning, not tonight."}}}}}},"/api/v1/accounts/{account_id}/conversations/{conversation_id}/messages/{id}/vote":{"post":{"tags":["Conversations"],"operationId":"auto_post_api_v1_accounts_account_id_conversations_conversation_id_messages_id_vote","summary":"Vote on a poll message","description":"Casts a vote on the poll carried by the message and mirrors the choice into it, so the tally matches what the participants see on the channel. `options` is a LIST because a multi-select poll accepts more than one choice, and an EMPTY list is a legitimate retraction of a previous vote — not a no-op. Channels without polls accept the call and change nothing. The response carries NO body — re-read the message to see the recorded vote.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Vote sent and mirrored, or accepted as a no-op on a channel without polls. Empty body."},"401":{"description":"Unauthorized"},"404":{"description":"No message with this id exists in the conversation."},"422":{"description":"A named option does not belong to this poll, or the vote could not be delivered by the channel provider. Nothing is mirrored.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable reason, localized to the account language."}}},"example":{"error":"That option does not belong to this poll"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"conversation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["options"],"properties":{"options":{"type":"array","description":"Names of the poll options being chosen, exactly as they appear on the poll. An empty list retracts the previous vote.","items":{"type":"string"}}}},"example":{"options":["Tuesday morning"]}}}}}},"/api/v1/accounts/{account_id}/conversations/{conversation_id}/messages/{id}/rsvp":{"post":{"tags":["Conversations"],"operationId":"auto_post_api_v1_accounts_account_id_conversations_conversation_id_messages_id_rsvp","summary":"Answer the event invitation carried by a message","description":"Sends an RSVP for the calendar event the message carries and mirrors the answer into it, so the event card reads exactly like an answer that arrived from a guest. Attending with companions is not a separate answer — it is `GOING` with `extra_guest_count` of at least one. `UNKNOWN` is what clearing a previous answer sends. Channels without events accept the call and change nothing. The response carries NO body — re-read the message to see the recorded answer.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Answer sent and mirrored, or accepted as a no-op on a channel without events. Empty body."},"401":{"description":"Unauthorized"},"404":{"description":"No message with this id exists in the conversation."},"422":{"description":"The answer is outside the accepted set, or the channel provider refused it — for instance an event created before the provider supported answers. Nothing is mirrored.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable reason, localized to the account language."}}},"example":{"error":"Unknown response — expected GOING, NOT_GOING, MAYBE or UNKNOWN"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"conversation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["response"],"properties":{"response":{"type":"string","enum":["GOING","NOT_GOING","MAYBE","UNKNOWN"],"description":"The answer to record. `UNKNOWN` clears a previously given answer."},"extra_guest_count":{"type":"integer","description":"Number of companions attending in addition to the responder. Only meaningful together with `GOING`; defaults to zero."}}},"example":{"response":"GOING","extra_guest_count":1}}}}}},"/api/v1/accounts/{account_id}/conversations/{conversation_id}/messages/{id}/add_shared_contact":{"post":{"tags":["Conversations"],"operationId":"auto_post_api_v1_accounts_account_id_conversations_conversation_id_messages_id_add_shared_contact","summary":"Add a shared contact to the connected WhatsApp address book","description":"Reads the selected contact from an accessible conversation message and adds it through the connected WhatsApp Web session. An enabled hybrid pair can provide that session for a Cloud inbox. The request cannot override the phone or name carried by the message. Requires contact creation permission and conversation access. This operation does not create a platform contact.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The WhatsApp address-book provider confirmed the operation.","content":{"application/json":{"schema":{"type":"object","required":["status","destination"],"properties":{"status":{"type":"string","enum":["saved"],"description":"Confirmed result of the address-book operation."},"destination":{"type":"string","enum":["whatsapp"],"description":"Address book updated by this operation."}}},"example":{"status":"saved","destination":"whatsapp"}}}},"401":{"description":"Authentication is missing or the user lacks conversation access or contact creation permission."},"404":{"description":"The conversation or message is outside the accessible account scope."},"422":{"description":"The selected contact has no usable phone/name, or no supported WhatsApp session is available.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable reason localized to the account language."}}},"example":{"error":"This shared contact has no valid phone number."}}}},"502":{"description":"The WhatsApp provider did not confirm the operation. No success is reported.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable provider failure localized to the account language."}}},"example":{"error":"Could not add the contact to WhatsApp."}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"conversation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"contact_index":{"type":"integer","minimum":0,"default":0,"description":"Zero-based position of the shared contact in the message."}}},"example":{"contact_index":0}}}}}},"/api/v1/accounts/{account_id}/conversations/{conversation_id}/messages/{message_id}/attachments/{attachment_id}/transcription":{"patch":{"tags":["Conversations"],"operationId":"auto_patch_api_v1_accounts_account_id_conversations_conversation_id_messages_message_id_attachments_attachment_id_transcription","summary":"Write back an audio transcription","description":"Stores a speech-to-text transcription on an audio attachment of the message and pushes the updated audio bubble to the dashboard over the websocket. Intended for the Maestro AgentBot to persist a transcription it generated for an inbound audio message. The write is idempotent: the transcription is saved only when the attachment does not already have one — a second call, or a call on an already-transcribed attachment, is a no-op success that returns the stored text. A blank transcription is also a no-op. Always responds 200 with the attachment's current transcription.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The attachment's current transcription (the value just written, or the pre-existing one on a no-op).","content":{"application/json":{"schema":{"type":"object","properties":{"transcription":{"type":"string","description":"The transcription currently stored on the attachment ('' if none and none was written).","example":"Oi, gostaria de saber o horário de funcionamento de vocês."}}},"example":{"transcription":"Oi, gostaria de saber o horário de funcionamento de vocês."}}}},"401":{"description":"Unauthorized"},"404":{"description":"The message or the audio attachment was not found in this conversation.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Resource could not be found"}}},"example":{"error":"Resource could not be found"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"conversation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"message_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"attachment_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["transcription"],"properties":{"transcription":{"type":"string","description":"The transcribed text to store on the audio attachment.","example":"Oi, gostaria de saber o horário de funcionamento de vocês."}}},"example":{"transcription":"Oi, gostaria de saber o horário de funcionamento de vocês."}}}}}},"/api/v1/accounts/{account_id}/conversations/{conversation_id}/messages/{message_id}/attachments/{attachment_id}/retranscribe":{"post":{"tags":["Conversations"],"operationId":"auto_post_api_v1_accounts_account_id_conversations_conversation_id_messages_message_id_attachments_attachment_id_retranscribe","summary":"Retranscribe attachments","description":"Performs the retranscribe operation on the targeted attachment resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"transcription":{"type":"string"},"transcription_error":{"type":"string"}},"required":["transcription","transcription_error"],"additionalProperties":false},"example":{"transcription":"sample transcription","transcription_error":"sample transcription error"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"conversation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"message_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"attachment_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/conversations/{conversation_id}/participants":{"get":{"tags":["Conversations"],"operationId":"auto_get_api_v1_accounts_account_id_conversations_conversation_id_participants","summary":"Get participants","description":"Returns the participant identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":["integer","null"]},"account_user_id":{"type":["integer","null"]},"availability_status":{"type":"string","enum":["online","offline","busy"],"description":"Realtime availability. Contacts report online/offline (presence-based); agents/users additionally report busy (their configured availability)."},"auto_offline":{"type":"boolean"},"confirmed":{"type":"boolean"},"email":{"type":"string","format":"email"},"provider":{"type":"string","enum":["email","google_oauth2","saml"],"description":"The authentication provider the user account was created with."},"available_name":{"type":"string"},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"name":{"type":"string"},"role":{"type":"string","enum":["agent","administrator"]},"outbound_agent_name_header_policy":{"type":["string","null"]},"thumbnail":{"type":"string"},"custom_role_id":{"type":["integer","null"]},"access_role_id":{"type":["integer","null"]}}}},"example":[{"id":1,"account_id":1,"account_user_id":1,"availability_status":"online","auto_offline":true,"confirmed":true,"email":"agent@example.com","provider":"email","available_name":"sample available name","custom_attributes":{},"name":"Sample Name","role":"agent","outbound_agent_name_header_policy":"sample outbound agent name header policy","thumbnail":"sample thumbnail","custom_role_id":1,"access_role_id":1}]}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"conversation_id","in":"path","required":true,"schema":{"type":"string"}}]},"patch":{"tags":["Conversations"],"operationId":"auto_patch_api_v1_accounts_account_id_conversations_conversation_id_participants","summary":"Update participants","description":"Updates the participant identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":["integer","null"]},"account_user_id":{"type":["integer","null"]},"availability_status":{"type":"string","enum":["online","offline","busy"],"description":"Realtime availability. Contacts report online/offline (presence-based); agents/users additionally report busy (their configured availability)."},"auto_offline":{"type":"boolean"},"confirmed":{"type":"boolean"},"email":{"type":"string","format":"email"},"provider":{"type":"string","enum":["email","google_oauth2","saml"],"description":"The authentication provider the user account was created with."},"available_name":{"type":"string"},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"name":{"type":"string"},"role":{"type":"string","enum":["agent","administrator"]},"outbound_agent_name_header_policy":{"type":["string","null"]},"thumbnail":{"type":"string"},"custom_role_id":{"type":["integer","null"]},"access_role_id":{"type":["integer","null"]}}}},"example":[{"id":1,"account_id":1,"account_user_id":1,"availability_status":"online","auto_offline":true,"confirmed":true,"email":"agent@example.com","provider":"email","available_name":"sample available name","custom_attributes":{},"name":"Sample Name","role":"agent","outbound_agent_name_header_policy":"sample outbound agent name header policy","thumbnail":"sample thumbnail","custom_role_id":1,"access_role_id":1}]}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"conversation_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"user_ids":{"type":"array","items":{"type":"integer"}}}},"example":{"user_ids":[1]}}}}},"put":{"tags":["Conversations"],"operationId":"auto_put_api_v1_accounts_account_id_conversations_conversation_id_participants","summary":"Update participants","description":"Updates the participant identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":["integer","null"]},"account_user_id":{"type":["integer","null"]},"availability_status":{"type":"string","enum":["online","offline","busy"],"description":"Realtime availability. Contacts report online/offline (presence-based); agents/users additionally report busy (their configured availability)."},"auto_offline":{"type":"boolean"},"confirmed":{"type":"boolean"},"email":{"type":"string","format":"email"},"provider":{"type":"string","enum":["email","google_oauth2","saml"],"description":"The authentication provider the user account was created with."},"available_name":{"type":"string"},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"name":{"type":"string"},"role":{"type":"string","enum":["agent","administrator"]},"outbound_agent_name_header_policy":{"type":["string","null"]},"thumbnail":{"type":"string"},"custom_role_id":{"type":["integer","null"]},"access_role_id":{"type":["integer","null"]}}}},"example":[{"id":1,"account_id":1,"account_user_id":1,"availability_status":"online","auto_offline":true,"confirmed":true,"email":"agent@example.com","provider":"email","available_name":"sample available name","custom_attributes":{},"name":"Sample Name","role":"agent","outbound_agent_name_header_policy":"sample outbound agent name header policy","thumbnail":"sample thumbnail","custom_role_id":1,"access_role_id":1}]}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"conversation_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"user_ids":{"type":"array","items":{"type":"integer"}}}},"example":{"user_ids":[1]}}}}},"delete":{"tags":["Conversations"],"operationId":"auto_delete_api_v1_accounts_account_id_conversations_conversation_id_participants","summary":"Delete participants","description":"Deletes the participant identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Success (no content)"},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"conversation_id","in":"path","required":true,"schema":{"type":"string"}}]},"post":{"tags":["Conversations"],"operationId":"auto_post_api_v1_accounts_account_id_conversations_conversation_id_participants","summary":"Create participants","description":"Creates a new participant from the request payload. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":["integer","null"]},"account_user_id":{"type":["integer","null"]},"availability_status":{"type":"string","enum":["online","offline","busy"],"description":"Realtime availability. Contacts report online/offline (presence-based); agents/users additionally report busy (their configured availability)."},"auto_offline":{"type":"boolean"},"confirmed":{"type":"boolean"},"email":{"type":"string","format":"email"},"provider":{"type":"string","enum":["email","google_oauth2","saml"],"description":"The authentication provider the user account was created with."},"available_name":{"type":"string"},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"name":{"type":"string"},"role":{"type":"string","enum":["agent","administrator"]},"outbound_agent_name_header_policy":{"type":["string","null"]},"thumbnail":{"type":"string"},"custom_role_id":{"type":["integer","null"]},"access_role_id":{"type":["integer","null"]}}}},"example":[{"id":1,"account_id":1,"account_user_id":1,"availability_status":"online","auto_offline":true,"confirmed":true,"email":"agent@example.com","provider":"email","available_name":"sample available name","custom_attributes":{},"name":"Sample Name","role":"agent","outbound_agent_name_header_policy":"sample outbound agent name header policy","thumbnail":"sample thumbnail","custom_role_id":1,"access_role_id":1}]}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"conversation_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"user_ids":{"type":"array","items":{"type":"integer"}}}},"example":{"user_ids":[1]}}}}}},"/api/v1/accounts/{account_id}/conversations/{conversation_id}/pin":{"delete":{"tags":["Conversations"],"operationId":"auto_delete_api_v1_accounts_account_id_conversations_conversation_id_pin","summary":"Delete pins","description":"Deletes the pin identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Success (no content)"},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"conversation_id","in":"path","required":true,"schema":{"type":"string"}}]},"post":{"tags":["Conversations"],"operationId":"auto_post_api_v1_accounts_account_id_conversations_conversation_id_pin","summary":"Create pins","description":"Creates a new pin from the request payload. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"conversation_id":{"type":"integer"},"custom_filter_id":{"type":"integer"},"created_at":{"type":"integer"}}},"example":{"id":1,"conversation_id":1,"custom_filter_id":1,"created_at":1}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"conversation_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/conversations/{conversation_id}/direct_uploads":{"post":{"tags":["Conversations"],"operationId":"auto_post_api_v1_accounts_account_id_conversations_conversation_id_direct_uploads","summary":"Reserve a storage record for a conversation attachment","description":"First step of the attachment flow. It registers the file the agent picked and returns the storage record plus a pre-signed target, so the bytes travel from the browser straight to the storage service instead of through this application. Upload the raw bytes to `direct_upload.url` replaying every header in `direct_upload.headers`, then send the returned `signed_id` as the attachment of the message. Returns `200 OK` with a JSON body — the contract previously advertised an empty `204`, which only happens when the conversation cannot be resolved.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Storage record reserved. The bytes are NOT stored yet — upload them to the pre-signed URL before referencing `signed_id` on a message.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer","description":"Internal identifier of the storage record."},"key":{"type":"string","description":"Opaque key the file is written under in the storage service."},"filename":{"type":"string","description":"File name as submitted by the client."},"content_type":{"type":["string","null"],"description":"MIME type recorded for the file, as submitted by the client."},"metadata":{"type":"object","additionalProperties":true,"description":"Metadata stored with the file, as submitted by the client."},"service_name":{"type":"string","description":"Storage service the file is written to, as configured for this installation."},"byte_size":{"type":"integer","description":"Declared size of the file in bytes."},"checksum":{"type":["string","null"],"description":"Base64-encoded MD5 digest the storage service validates the upload against."},"created_at":{"type":"string","format":"date-time","description":"When the storage record was reserved."},"signed_id":{"type":"string","description":"Tamper-proof reference to the file. Send it as the message attachment once the bytes are uploaded."},"direct_upload":{"type":"object","description":"Where and how the client must upload the bytes.","properties":{"url":{"type":"string","description":"Pre-signed URL the client PUTs the raw bytes to."},"headers":{"type":"object","additionalProperties":{"type":"string"},"description":"Headers that must accompany the upload exactly as given; the pre-signed URL rejects the request otherwise. The set depends on the storage service."}}}}},"example":{"id":4821,"key":"xf9pdq0k7z2m4bn6vc1a3s5d","filename":"invoice.pdf","content_type":"application/pdf","metadata":{},"service_name":"amazon","byte_size":20451,"checksum":"qLNbHUmZ6vC0FpHZjkQeBQ==","created_at":"2026-07-27T12:04:31.000Z","signed_id":"eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBCQT09In19","direct_upload":{"url":"https://storage.example.com/uploads/xf9pdq0k7z2m4bn6vc1a3s5d?signature=sample","headers":{"Content-Type":"application/pdf","Content-MD5":"qLNbHUmZ6vC0FpHZjkQeBQ=="}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"204":{"description":"The conversation could not be resolved inside the account; no storage record is created and no body is returned."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"conversation_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["blob"],"properties":{"blob":{"type":"object","description":"Description of the file about to be uploaded.","required":["filename","byte_size","checksum"],"properties":{"filename":{"type":"string","description":"Name of the file as picked by the agent."},"byte_size":{"type":"integer","description":"Exact size of the file in bytes; the pre-signed target only accepts this size."},"checksum":{"type":"string","description":"Base64-encoded MD5 digest of the file, verified by the storage service on upload."},"content_type":{"type":"string","description":"MIME type declared for the file."},"metadata":{"type":"object","additionalProperties":true,"description":"Free-form metadata to store alongside the file, such as the analysis hints the client derived from it. Keys vary by file type."}}}}},"example":{"blob":{"filename":"invoice.pdf","byte_size":20451,"checksum":"qLNbHUmZ6vC0FpHZjkQeBQ==","content_type":"application/pdf","metadata":{}}}}}}}},"/api/v1/accounts/{account_id}/conversations/{conversation_id}/draft_messages":{"get":{"tags":["Conversations"],"operationId":"auto_get_api_v1_accounts_account_id_conversations_conversation_id_draft_messages","summary":"Get draft messages","description":"Returns the draft message identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"has_draft":{"type":"boolean","example":false}}},{"type":"object","properties":{"has_draft":{"type":"boolean","example":true},"message":{"type":"string"}}}]},"example":{"has_draft":false}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"conversation_id","in":"path","required":true,"schema":{"type":"string"}}]},"patch":{"tags":["Conversations"],"operationId":"auto_patch_api_v1_accounts_account_id_conversations_conversation_id_draft_messages","summary":"Save the conversation draft message","description":"Stores the reply an agent has typed but not yet sent on the conversation, so it survives navigating away and reopening the conversation. The draft is held in the cache rather than with the messages, one per conversation, and each save replaces the previous one; saving without a message clears the text. The response carries no body.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Draft message stored for the conversation. Empty body."},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"conversation_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"draft_message":{"type":"object","description":"Wrapper carrying the draft text. Nothing here is enforced — the controller reads the nested value and falls back to an empty string, so a body-less request succeeds and clears the draft. Declaring it required would describe a rejection that does not happen, and would contradict the clearing behavior described below.","properties":{"message":{"type":"string","description":"The unsent reply text to store. Omitting it stores an empty draft, which clears the previously saved text."}}}}},"example":{"draft_message":{"message":"Hi! Checking the order status for you now."}}}}}},"put":{"tags":["Conversations"],"operationId":"auto_put_api_v1_accounts_account_id_conversations_conversation_id_draft_messages","summary":"Save the conversation draft message","description":"Stores the reply an agent has typed but not yet sent on the conversation, so it survives navigating away and reopening the conversation. The draft is held in the cache rather than with the messages, one per conversation, and each save replaces the previous one; saving without a message clears the text. The response carries no body.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Draft message stored for the conversation. Empty body."},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"conversation_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"draft_message":{"type":"object","description":"Wrapper carrying the draft text. Nothing here is enforced — the controller reads the nested value and falls back to an empty string, so a body-less request succeeds and clears the draft. Declaring it required would describe a rejection that does not happen, and would contradict the clearing behavior described below.","properties":{"message":{"type":"string","description":"The unsent reply text to store. Omitting it stores an empty draft, which clears the previously saved text."}}}}},"example":{"draft_message":{"message":"Hi! Checking the order status for you now."}}}}}},"delete":{"tags":["Conversations"],"operationId":"auto_delete_api_v1_accounts_account_id_conversations_conversation_id_draft_messages","summary":"Delete draft messages","description":"Deletes the draft message identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Success (no content)"},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"conversation_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/conversations/{conversation_id}/calls":{"get":{"tags":["Conversations"],"operationId":"auto_get_api_v1_accounts_account_id_conversations_conversation_id_calls","summary":"List the contact's call history","description":"Returns the complete native Twilio and WhatsApp call history for the conversation's contact, newest first, filtering each conversation by the current user's access. Historical recordings, including legacy attachments, and transcripts remain readable after voice is disabled in every build.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Call history for this contact within the account.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"provider_call_id":{"type":"string"},"provider":{"type":"string","enum":["twilio","whatsapp","whatsapp_web"]},"direction":{"type":"string","enum":["incoming","outgoing"]},"status":{"type":"string","enum":["ringing","in-progress","completed","rejected","no-answer","failed"]},"duration_seconds":{"type":["integer","null"]},"end_reason":{"type":["string","null"]},"conference_sid":{"type":["string","null"]},"accepted_by_agent_id":{"type":["integer","null"]},"accepted_by_agent_name":{"type":["string","null"]},"started_at":{"type":["integer","null"],"description":"Unix timestamp in seconds."},"ended_at":{"type":["integer","string","null"],"description":"Call end timestamp in epoch seconds or a legacy serialized timestamp."},"from_number":{"type":["string","null"]},"to_number":{"type":["string","null"]},"recording_url":{"type":["string","null"]},"recording_deleted":{"type":"boolean","description":"Whether recording removal metadata marks the recording as deleted."},"recording_segments":{"type":"array","description":"Persisted WhatsApp recording segments in ordinal order, with current playback availability.","items":{"type":"object","required":["segment_id","ordinal","source","sha256","content_type","byte_size","partial","recording_url"],"properties":{"segment_id":{"type":"string","format":"uuid"},"ordinal":{"type":"integer","minimum":0},"source":{"type":"string","enum":["ai","human"]},"sha256":{"type":"string","pattern":"^[0-9a-f]{64}$"},"content_type":{"type":"string","enum":["audio/mpeg","audio/mp4","audio/ogg","application/ogg","audio/webm","video/webm","audio/wav","audio/x-wav","audio/aac","audio/x-m4a"]},"byte_size":{"type":"integer","minimum":1,"maximum":52428800,"description":"Stored segment size. Maestro deliveries are limited to 8 MiB; human uploads retain the 50 MiB recording limit."},"partial":{"type":"boolean"},"recording_url":{"type":["string","null"],"description":"Current playback URL; null when playback is unavailable. Recordings marked removed are excluded from the segment list."}}}},"transcript":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"}}}}}},"example":{"payload":[{"id":42,"provider_call_id":"CA_example","provider":"twilio","direction":"incoming","status":"completed","duration_seconds":30,"end_reason":null,"conference_sid":"conf_account_1_call_42","accepted_by_agent_id":7,"accepted_by_agent_name":"Support Agent","started_at":1788696000,"ended_at":"2026-09-06T12:00:30Z","from_number":"+15551234567","to_number":"+15557654321","recording_url":null,"recording_deleted":false,"recording_segments":[{"segment_id":"550e8400-e29b-41d4-a716-446655440000","ordinal":1,"source":"ai","sha256":"sample sha256","content_type":"audio/mpeg","byte_size":1,"partial":true,"recording_url":"https://example.com/resource"}],"transcript":"Example call transcript.","created_at":"2026-09-06T12:00:00Z"}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"conversation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."}]}},"/api/v1/accounts/{account_id}/conversations/{conversation_id}/whatsapp_cost/preview":{"get":{"tags":["Conversations"],"operationId":"auto_get_api_v1_accounts_account_id_conversations_conversation_id_whatsapp_cost_preview","summary":"Preview the WhatsApp cost of the next send","description":"What the next send in the conversation would cost, resolving the transport exactly like the send path does. Without trustworthy data (feature off, visibility `hidden`, no billing channel, or a charged send whose market, currency or tariff cannot be resolved) the answer is only `{visible: false, show_values: false}` — never \"free\" for lack of data. Money fields travel only when `show_values` is true. From 2026-10-01 a service reply is free while the billing number has its monthly free tier (`reason: free_tier`) and charged after it, and any send inside an open ad free entry point window is free (`reason: free_entry_point`); a service-reply answer carries the number's `allowance` counts.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The cost of the next send.","content":{"application/json":{"schema":{"type":"object","properties":{"visible":{"type":"boolean"},"show_values":{"type":"boolean"},"window_open":{"type":"boolean"},"window_open_until":{"type":["string","null"],"format":"date-time"},"transport_effective":{"type":"string","enum":["cloud","web"]},"regime":{"type":"string","enum":["service_billable","service_free"]},"partner_billed":{"type":"boolean"},"will_charge":{"type":"boolean"},"reason":{"type":"string","enum":["web_transport","free_customer_service","free_tier","free_entry_point","service_in_window","template","window_closed"]},"category":{"type":["string","null"],"description":"Category the send is priced as; null for a Web send or a closed window without a template.","enum":["marketing","utility","authentication","service",null]},"unit_price":{"type":"number","description":"Native unit price (values only)."},"currency":{"type":"string","description":"Native billing currency (values only)."},"amount_source":{"type":["string","null"],"enum":["list_rate","tier_estimated","override","meta_reported",null],"description":"How the amount was priced — `list_rate` (the official rate card), `tier_estimated` (a volume tier estimated by the platform), `override` (the account's own tariff) or `meta_reported` (the cost Meta reported with a max-price marketing delivery). Null when there is no priced amount."},"display_amount":{"type":["number","null"],"description":"Unit price in `display_currency` (values only)."},"display_currency":{"type":["string","null"],"description":"Values only."},"fx":{"type":["object","null"],"description":"Conversion applied to the money fields, or null when no conversion was needed (every native amount is already in `amounts_currency`) or when it was unavailable (`fx_unavailable` true).","properties":{"rate":{"type":["number","null"],"description":"The single conversion rate, or null when more than one native currency was converted (see `rates`)."},"source":{"type":"string","enum":["live","fallback"],"description":"`live` when every rate came from the live FX provider; `fallback` when any used the stored fallback rate."},"as_of":{"type":"string","format":"date-time","description":"When the rates were resolved (UTC)."},"to":{"type":["string","null"],"description":"ISO 4217 currency the amounts were converted into."},"rates":{"type":"object","description":"Rate applied per native ISO 4217 currency code (1 native unit = rate display units).","additionalProperties":{"type":"number"}}}},"category_changed":{"type":["object","null"],"description":"Set when the category the caller saw, or the one Meta replaced (`previous_category`), differs from the template's current category in the synced catalog; the answer is priced at `to`. Null otherwise.","properties":{"from":{"type":"string","enum":["marketing","utility","authentication"]},"to":{"type":"string","enum":["marketing","utility","authentication"]}}},"allowance":{"type":"object","description":"The billing number's monthly free tier, on a service reply from 2026-10-01 (counts only, as Meta reported them).","properties":{"used":{"type":"integer"},"total":{"type":"integer"},"remaining":{"type":"integer"},"month_boundary_evidence":{"type":"string","enum":["unverified"]}}}}},"example":{"visible":true,"show_values":true,"window_open":true,"window_open_until":"2026-10-21T10:00:00Z","transport_effective":"cloud","regime":"service_billable","partner_billed":false,"will_charge":true,"reason":"service_in_window","category":"service","unit_price":0.0068,"currency":"USD","amount_source":"list_rate","display_amount":0.034,"display_currency":"BRL","fx":{"rate":5.0,"source":"live","as_of":"2026-10-20T12:00:00Z","to":"BRL","rates":{"USD":5.0}},"category_changed":null,"allowance":{"used":1000,"total":1000,"remaining":0,"month_boundary_evidence":"unverified"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"The `whatsapp_cost_center` feature is off for the account (empty body), or the conversation does not exist.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}},"example":{"error":"Resource could not be found"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"conversation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"transport","in":"query","required":false,"description":"The composer's transport pick; an unknown value is `auto`.","schema":{"type":"string","enum":["cloud","web","auto"],"default":"auto"},"example":"auto"},{"name":"category","in":"query","required":false,"description":"Category of the selected template as the caller saw it; omit for a free-form reply (priced as `service`). Only a fallback when `template_name` matches a synced template, whose CURRENT category is used.","schema":{"type":"string","enum":["marketing","utility","authentication"]},"example":"marketing"},{"name":"template_name","in":"query","required":false,"description":"Name of the selected template. With it the template is priced at its current category from the billing number's synced template catalog (Meta can re-categorize a template by itself).","schema":{"type":"string"},"example":"order_update"},{"name":"template_language","in":"query","required":false,"description":"Language of the selected template, to pick the right entry of the catalog.","schema":{"type":"string"},"example":"pt_BR"},{"name":"currency","in":"query","required":false,"description":"ISO 4217 display currency the amounts are converted into. Defaults to the account display currency.","schema":{"type":"string","pattern":"^[A-Za-z]{3}$"},"example":"BRL"}]}},"/api/v1/accounts/{account_id}/conversations/{conversation_id}/whatsapp_cost/call_preview":{"get":{"tags":["Conversations"],"operationId":"auto_get_api_v1_accounts_account_id_conversations_conversation_id_whatsapp_cost_call_preview","summary":"Preview the WhatsApp cost of an outbound call","description":"What a business-initiated WhatsApp call to the conversation's contact would cost, shown before the agent places it, by the same rule the ledger applies after the call: the per-minute rate of the called number's market in the WABA billing currency and the volume tier of the month, charged per six-second pulse. A call the user places is always free (`user_initiated_free`). A call over WhatsApp Web is not billed by Meta (`billable: false`, `free_reason: web_transport`); an inbox that places no WhatsApp call (360dialog) answers `visible: false`. A price that cannot be told is a `reason`, never a number. Same visibility as the conversation cost panel: hidden → `{visible: false, show_values: false}`; without `show_values` the money fields are removed server-side.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The call price estimate.","content":{"application/json":{"schema":{"type":"object","properties":{"visible":{"type":"boolean"},"show_values":{"type":"boolean"},"billable":{"type":"boolean","description":"False when the call goes out over WhatsApp Web."},"free_reason":{"type":["string","null"],"enum":["web_transport",null]},"transport":{"type":"string","enum":["cloud"]},"pulse_seconds":{"type":"integer","description":"Length of a billing pulse (6)."},"user_initiated_free":{"type":"boolean","description":"A call placed by the user is free."},"currency":{"type":["string","null"],"description":"WABA billing currency (values only)."},"rate_per_minute":{"type":["number","null"],"description":"Price per minute in MAJOR units (values only)."},"rate_per_pulse":{"type":["number","null"],"description":"Price per six-second pulse (values only)."},"market":{"type":["string","null"],"description":"Meta pricing market of the called number."},"country_iso":{"type":["string","null"]},"tier":{"type":["string","null"],"description":"Volume tier of the month as minutes `from-to` (`+` = no upper bound).","example":"0-50000"},"month_minutes":{"type":["number","null"],"description":"Minutes the business portfolio already called this month (our records)."},"reason":{"type":["string","null"],"enum":["no_called_number","no_market","no_billing_currency","no_rate_card","market_not_in_card",null],"description":"Why there is no price; null when priced."},"evidence":{"type":"string","enum":["official_replay"]}}},"example":{"visible":true,"show_values":true,"billable":true,"free_reason":null,"transport":"cloud","pulse_seconds":6,"user_initiated_free":true,"currency":"USD","rate_per_minute":0.0108,"rate_per_pulse":0.00108,"market":"Brazil","country_iso":"BR","tier":"0-50000","month_minutes":12.5,"reason":null,"evidence":"official_replay"}}}},"401":{"description":"Unauthorized"},"404":{"description":"The `whatsapp_cost_center` feature is off for the account (empty body), or the conversation does not exist.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}},"example":{"error":"Resource could not be found"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"conversation_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/conversations/{conversation_id}/whatsapp_cost":{"get":{"tags":["Conversations"],"operationId":"auto_get_api_v1_accounts_account_id_conversations_conversation_id_whatsapp_cost","summary":"Get the WhatsApp cost of a conversation","description":"The cost of the conversation in the current billing month and one marker per message with a ledger entry. Authorized like reading the conversation. With the feature off, visibility `hidden` or no billing channel the answer is only `{visible: false, show_values: false}`. When `show_values` is false (visibility `indicator`, or a user outside the values audience) every money field is removed server-side — counts, states and reasons stay.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The conversation cost panel.","content":{"application/json":{"schema":{"type":"object","properties":{"visible":{"type":"boolean"},"show_values":{"type":"boolean"},"partner_billed":{"type":"boolean"},"currency":{"type":["string","null"],"description":"Native billing currency of the number (values only)."},"display_currency":{"type":["string","null"],"description":"Values only."},"amounts_currency":{"type":["string","null"],"description":"Currency of the totals amounts (values only)."},"fx":{"type":["object","null"],"description":"Conversion applied to the money fields, or null when no conversion was needed (every native amount is already in `amounts_currency`) or when it was unavailable (`fx_unavailable` true).","properties":{"rate":{"type":["number","null"],"description":"The single conversion rate, or null when more than one native currency was converted (see `rates`)."},"source":{"type":"string","enum":["live","fallback"],"description":"`live` when every rate came from the live FX provider; `fallback` when any used the stored fallback rate."},"as_of":{"type":"string","format":"date-time","description":"When the rates were resolved (UTC)."},"to":{"type":["string","null"],"description":"ISO 4217 currency the amounts were converted into."},"rates":{"type":"object","description":"Rate applied per native ISO 4217 currency code (1 native unit = rate display units).","additionalProperties":{"type":"number"}}}},"window_open":{"type":"boolean","description":"Whether Meta's 24-hour customer service window is open."},"window_open_until":{"type":["string","null"],"format":"date-time"},"period":{"type":"object","properties":{"from":{"type":"string","format":"date"},"to":{"type":"string","format":"date"}}},"totals":{"type":"object","properties":{"billable":{"type":"object","description":"A message count and its amount in `amounts_currency` (null when the amount cannot be expressed in one currency).","properties":{"count":{"type":"integer"},"amount":{"type":["number","null"]}}},"pending_delivery":{"type":"object","description":"A message count; these messages never carry an amount.","properties":{"count":{"type":"integer"}}},"free":{"type":"object","description":"A message count; these messages never carry an amount.","properties":{"count":{"type":"integer"}}},"not_billed":{"type":"object","description":"A message count; these messages never carry an amount.","properties":{"count":{"type":"integer"}}},"unverified":{"type":"object","description":"A message count; these messages never carry an amount.","properties":{"count":{"type":"integer"}}}}},"by_category":{"type":"object","description":"Billable messages per pricing category (`marketing`, `utility`, `authentication`, `service`; `unknown` when the entry carries none), each with its count and amount in `amounts_currency`.","additionalProperties":{"type":"object","properties":{"count":{"type":"integer"},"amount":{"type":["number","null"]}}}},"message_markers":{"type":"array","description":"One marker per message with a ledger entry, most recent first (at most 1,000).","items":{"type":"object","properties":{"message_id":{"type":"integer"},"billing_state":{"type":"string","enum":["pending_delivery","billable","free","not_billed","not_billed_expired","unverified"],"description":"Ledger state — `pending_delivery` (sent, awaiting the final status; provisional amount), `billable` (the only state that counts as cost), `free`, `not_billed` (failed), `not_billed_expired` (no final status within 30 days) or `unverified`."},"free_reason":{"type":["string","null"],"enum":["free_tier","free_customer_service","free_entry_point","business_app","web_transport",null],"description":"Why a `free` message costs nothing — `free_tier` classifies reported deliveries against the local estimated monthly service allowance; see `allowance.evidence`. Meta does not publish an allowance limit in the documentation tracked here. `free_customer_service` (inside the 24-hour customer service window, until 2026-09-30) and `free_entry_point` (inside an ad free entry point window) identify reported free events; `business_app` (sent from the WhatsApp Business app of a Coexistence number) or `web_transport` (sent through the WhatsApp Web leg of a paired number). Null for any other state."},"category":{"type":["string","null"],"enum":["marketing","utility","authentication","service",null],"description":"Meta pricing category — `marketing`, `utility`, `authentication` or `service` (a free-form reply inside the customer service window, billable from 2026-10-01)."},"amount":{"type":["number","null"],"description":"Native amount of a billable or pending entry (values only)."},"currency":{"type":["string","null"],"description":"Values only."},"amount_source":{"type":["string","null"],"enum":["list_rate","tier_estimated","override","meta_reported",null],"description":"How the amount was priced — `list_rate` (the official rate card), `tier_estimated` (a volume tier estimated by the platform), `override` (the account's own tariff) or `meta_reported` (the cost Meta reported with a max-price marketing delivery). Null when there is no priced amount."},"partner_billed":{"type":"boolean"}}}},"allowance":{"type":"object","description":"The estimated monthly service allowance of the conversation's billing number in the current billing month; it never changes an amount. Meta does not publish an allowance limit in the documentation tracked here; read `allowance.evidence`. Only `shown: false` travels when the account hid it, the month has no estimated allowance or the billing number is a WhatsApp Web (WazMeow) number, which Meta does not bill (the estimate applies to WhatsApp Cloud and 360dialog numbers). Counts only, so it also travels when `show_values` is false.","properties":{"shown":{"type":"boolean"},"evidence":{"type":"string","enum":["unverified"]},"month_boundary_evidence":{"type":"string","enum":["unverified"]},"used":{"type":"integer","description":"Service messages Meta reported inside the free tier (capped at `total`)."},"charged":{"type":"integer","description":"Service messages Meta charged this month."},"total":{"type":"integer","description":"Allowance size per number."},"remaining":{"type":"integer"},"exhausted_at":{"type":["string","null"],"format":"date","description":"Billing day the allowance ran out, or null while it lasts."}}},"calls":{"type":"object","description":"Spec 119 · Meta's cost of the WhatsApp calls of the conversation, in the WABA's native currency (the AI voice cost comes from the Maestro usage and is never added here). Without `show_values`, `amounts` is omitted and every money field of the items is removed. An `unpriced` count above zero means `amounts` is absent or only a floor, never a zero-cost claim.","properties":{"items":{"type":"array","description":"At most 100 cost lines, most recent first.","items":{"type":"object","properties":{"id":{"type":"integer"},"call_id":{"type":["integer","null"],"description":"Null once the call was deleted (the cost stays)."},"conversation_id":{"type":["integer","null"]},"inbox_id":{"type":"integer"},"direction":{"type":["string","null"],"enum":["incoming","outgoing",null],"description":"`incoming` = started by the user (free); `outgoing` = started by the business."},"billing_state":{"type":"string","enum":["estimated","reconciled","free","not_connected","unpriced"],"description":"`free` (user-initiated), `not_connected` (business call never answered, no pulse), `estimated` (Meta's rule applied to the call), `reconciled` (the day's call_analytics COST matched), `unpriced` (no market, currency or rate card for the called number)."},"free_reason":{"type":["string","null"],"enum":["user_initiated",null]},"duration_seconds":{"type":["integer","null"]},"pulses":{"type":["integer","null"],"description":"Six-second pulses, a fraction counted as a whole pulse (business-initiated calls)."},"market":{"type":["string","null"],"description":"Meta pricing market of the called number."},"country_iso":{"type":["string","null"]},"tier":{"type":["string","null"],"description":"Volume tier of the month, as minutes `from-to` (`+` = no upper bound).","example":"0-50000"},"rate_per_minute":{"type":["number","null"],"description":"Values only."},"amount":{"type":["number","null"],"description":"MAJOR units in `currency` (values only)."},"currency":{"type":["string","null"],"description":"Values only."},"amount_source":{"type":["string","null"],"enum":["list_rate","tier_rate",null],"description":"`list_rate` (the first volume tier) or `tier_rate` (a higher tier of the month). Values only."},"billing_day":{"type":["string","null"],"format":"date"},"recorded_at":{"type":["string","null"],"format":"date-time","description":"When this line was written, right after the call ended."},"unpriced_reason":{"type":["string","null"],"enum":["no_called_number","no_market","no_billing_currency","no_rate_card","market_not_in_card",null]},"meta_day":{"type":["object","null"],"description":"Meta's call_analytics figures of the call's day (`cost` is values only; null when partner billed).","properties":{"count":{"type":"integer"},"average_duration":{"type":"integer"},"cost":{"type":["string","null"]},"partner_billed":{"type":"boolean"},"synced_at":{"type":"string","format":"date-time"}}}}}},"amounts":{"type":"array","description":"Charged amount per native currency (`estimated` + `reconciled`; values only). Empty means no charge only when the sibling `unpriced` count is zero.","items":{"type":"object","properties":{"currency":{"type":"string"},"amount":{"type":"number"}}}},"unpriced":{"type":"integer","description":"Measured Meta call rows without a confirmed price."},"total_is_floor":{"type":"boolean","description":"True when `amounts` excludes one or more unpriced Meta call rows."}}}}},"example":{"visible":true,"show_values":true,"partner_billed":false,"currency":"USD","display_currency":"BRL","amounts_currency":"BRL","fx":{"rate":5.0,"source":"live","as_of":"2026-10-20T12:00:00Z","to":"BRL","rates":{"USD":5.0}},"window_open":true,"window_open_until":"2026-10-21T10:00:00Z","period":{"from":"2026-10-01","to":"2026-10-31"},"totals":{"billable":{"count":1,"amount":0.034},"pending_delivery":{"count":0},"free":{"count":1},"not_billed":{"count":0},"unverified":{"count":0}},"by_category":{"service":{"count":1,"amount":0.034}},"message_markers":[{"message_id":781,"billing_state":"free","free_reason":"free_customer_service","category":"utility","amount":null,"currency":"USD","amount_source":null,"partner_billed":false},{"message_id":780,"billing_state":"billable","free_reason":null,"category":"service","amount":0.0068,"currency":"USD","amount_source":"list_rate","partner_billed":false}],"allowance":{"shown":true,"evidence":"unverified","month_boundary_evidence":"unverified","used":640,"charged":0,"total":1000,"remaining":360,"exhausted_at":null},"calls":{"items":[{"id":31,"call_id":902,"conversation_id":77,"inbox_id":42,"direction":"outgoing","billing_state":"estimated","free_reason":null,"duration_seconds":56,"pulses":10,"market":"Brazil","country_iso":"BR","tier":"0-50000","rate_per_minute":0.0108,"amount":0.0108,"currency":"USD","amount_source":"list_rate","billing_day":"2026-10-20","recorded_at":"2026-10-20T14:02:11Z","unpriced_reason":null,"meta_day":null},{"id":30,"call_id":901,"conversation_id":77,"inbox_id":42,"direction":"incoming","billing_state":"free","free_reason":"user_initiated","duration_seconds":12,"pulses":null,"market":null,"country_iso":null,"tier":null,"rate_per_minute":null,"amount":0.0,"currency":"USD","amount_source":null,"billing_day":"2026-10-20","recorded_at":"2026-10-20T13:41:37Z","unpriced_reason":null,"meta_day":{"count":1,"average_duration":12,"cost":"0","partner_billed":false,"synced_at":"2026-10-21T04:50:00Z"}}],"amounts":[{"currency":"USD","amount":0.0108}],"unpriced":0,"total_is_floor":false}}}}},"401":{"description":"Unauthorized"},"404":{"description":"The `whatsapp_cost_center` feature is off for the account (empty body), or the conversation does not exist.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}},"example":{"error":"Resource could not be found"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"conversation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"currency","in":"query","required":false,"description":"ISO 4217 display currency the amounts are converted into. Defaults to the account display currency.","schema":{"type":"string","pattern":"^[A-Za-z]{3}$"},"example":"BRL"}]}},"/api/v1/accounts/{account_id}/conversations/{id}/mute":{"post":{"tags":["Conversations"],"operationId":"auto_post_api_v1_accounts_account_id_conversations_id_mute","summary":"Mute a conversation and block its contact","description":"Resolves the conversation and blocks the contact behind it, so further inbound traffic from that person stops reaching the inbox, then appends an activity message recording the change. The call is idempotent and answers `200 OK` with an EMPTY body — re-read the conversation to observe the resolved status and the contact to observe the block. A conversation without a contact (none of the channels can produce one) is left untouched and still answers `200`.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Conversation muted and its contact blocked. Empty body."},"401":{"description":"Unauthorized"},"404":{"description":"No conversation with this display id exists in the account."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/conversations/{id}/unmute":{"post":{"tags":["Conversations"],"operationId":"auto_post_api_v1_accounts_account_id_conversations_id_unmute","summary":"Unmute a conversation and unblock its contact","description":"Unblocks the contact behind the conversation so their messages reach the inbox again, and appends an activity message recording the change. Unlike muting, the conversation status is left as it is. The call is idempotent and answers `200 OK` with an EMPTY body — re-read the contact to observe the lifted block.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Contact unblocked. Empty body."},"401":{"description":"Unauthorized"},"404":{"description":"No conversation with this display id exists in the account."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/conversations/{id}/transcript":{"post":{"tags":["Conversations"],"operationId":"auto_post_api_v1_accounts_account_id_conversations_id_transcript","summary":"E-mail the transcript of a conversation","description":"Sends the full conversation transcript to the address given in the body. The message is queued for delivery, so a successful call answers `200 OK` with an EMPTY body and does not report whether the mail was ultimately accepted by the recipient's server. Each accepted request counts against the account's e-mail allowance for the current window.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Transcript queued for delivery. Empty body."},"401":{"description":"Unauthorized"},"404":{"description":"No conversation with this display id exists in the account."},"402":{"description":"E-mail transcripts are not part of the account's plan.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable reason the transcript was refused."}}},"example":{"error":"Email transcript is not available on your plan"}}}},"422":{"description":"The `email` field is missing from the body.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable validation failure."}}},"example":{"error":"email param missing"}}}},"429":{"description":"The account reached its e-mail allowance for the current window. No transcript is sent and the response carries no body."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email"],"properties":{"email":{"type":"string","format":"email","description":"Address the transcript is sent to. Any valid mailbox — it need not belong to an agent or to the contact."}}},"example":{"email":"supervisor@example.com"}}}}}},"/api/v1/accounts/{account_id}/conversations/{id}/update_last_seen":{"post":{"tags":["Conversations"],"operationId":"auto_post_api_v1_accounts_account_id_conversations_id_update_last_seen","summary":"Update last seen conversations","description":"Performs the update last seen operation on the targeted conversation resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"meta":{"type":"object","properties":{"sender":{"type":"object","properties":{"additional_attributes":{"type":"object","additionalProperties":true,"description":"Channel- and source-specific metadata for this record (e.g. browser info, referer, social profile identifiers). The key set depends on the originating channel."},"availability_status":{"type":"string","enum":["online","offline","busy"],"description":"Realtime availability. Contacts report online/offline (presence-based); agents/users additionally report busy (their configured availability)."},"email":{"type":"string","format":"email"},"id":{"type":"integer"},"name":{"type":"string"},"phone_number":{"type":"string"},"blocked":{"type":"string"},"contact_type":{"type":"string","enum":["visitor","lead","customer"]},"identifier":{"type":"string"},"company_id":{"type":"integer"},"organization_id":{"type":"integer"},"referred_by_affiliate_id":{"type":"integer"},"referred_by_affiliate_name":{"type":["string","null"]},"owner_id":{"type":"integer"},"legal_type":{"type":"string","enum":["individual","business"]},"tax_id":{"type":"string","description":"The fiscal identifier (CPF/CNPJ/EIN/VAT); validated and stored encrypted on write. Read payloads return the real value to an authenticated human agent, and a type-aware mask (e.g. \"***.***.***-09\") when a role field rule masks it or the caller is a bot; a hidden rule omits the key. Webhooks, exports and message variables always carry the masked form."},"tax_id_type":{"type":"string","enum":["br_cpf","br_cnpj","us_ein","eu_vat","uk_vat","generic"],"description":"The fiscal identifier scheme used to validate and mask the tax_id (CPF/CNPJ check digits, EIN, EU/UK VAT or a generic fallback)."},"country":{"type":"integer"},"address":{"type":"object","additionalProperties":{"type":"string","description":"Address component value keyed by component name"},"description":"Postal address components keyed by component name."},"billing_address":{"type":"object","description":"Optional billing address override of the contact. An empty object means billing uses the principal address.","properties":{"zip":{"type":"string","description":"Postal/ZIP code (CEP in Brazil)"},"street":{"type":"string","description":"Street name"},"number":{"type":"string","description":"Street number"},"complement":{"type":"string","description":"Address complement (apartment, suite, block)"},"neighborhood":{"type":"string","description":"Neighborhood/district"},"city":{"type":"string","description":"City name"},"state":{"type":"string","description":"State/province (UF in Brazil)"},"country":{"type":"string","description":"Country of the postal address"}}},"thumbnail":{"type":"string"},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"last_activity_at":{"type":"integer"},"created_at":{"type":"integer"},"field_visibility":{"type":"string","enum":["visible","masked","hidden"],"description":"Per-field visibility resolved from the current access role's field_permissions (FieldVisibilityHelper). `visible` renders the real value, `masked` an obfuscated one, `hidden` omits the key entirely."},"contact_inboxes":{"type":"array","items":{"type":"object","properties":{"source_id":{"type":"integer"},"logical_inbox_id":{"type":"integer"},"inbox":{"type":"object","properties":{"id":{"type":"integer"},"avatar_url":{"type":"string"},"channel_id":{"type":"integer"},"name":{"type":"string"},"channel_type":{"type":"string","enum":["Channel::Api","Channel::Email","Channel::FacebookPage","Channel::Instagram","Channel::Line","Channel::Sms","Channel::Telegram","Channel::Tiktok","Channel::TwilioSms","Channel::TwitterProfile","Channel::WebWidget","Channel::Whatsapp"],"description":"The inbox channel class — identifies which messaging channel backs the inbox."},"provider":{"type":"string","enum":["default","whatsapp_cloud","whatsapp_web","google","microsoft"],"description":"Messaging provider backing the inbox channel (whatsapp_web is the WazMeow gateway; email uses google/microsoft; default otherwise)."}}}}}},"consent_state":{"type":"object","additionalProperties":{"type":"string","enum":["granted","denied","pending"],"description":"Consent state in force for this delivery channel."},"description":"LGPD consent state keyed by delivery channel (\"all\" is the account-wide scope that shadows the per-channel ones). A channel the contact never declared on is absent rather than pending, since the set of channels an account may use is open. Present only on single-contact payloads. Signals only — it never blocks a send."}}},"channel":{"type":"string"},"assignee":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":["integer","null"]},"account_user_id":{"type":["integer","null"]},"availability_status":{"type":"string","enum":["online","offline","busy"],"description":"Realtime availability. Contacts report online/offline (presence-based); agents/users additionally report busy (their configured availability)."},"auto_offline":{"type":"boolean"},"confirmed":{"type":"boolean"},"email":{"type":"string","format":"email"},"provider":{"type":"string","enum":["email","google_oauth2","saml"],"description":"Authentication provider the user signed up through."},"available_name":{"type":"string"},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"name":{"type":"string"},"role":{"type":"string","enum":["agent","administrator"]},"outbound_agent_name_header_policy":{"type":["string","null"]},"thumbnail":{"type":"string"},"custom_role_id":{"type":["integer","null"]},"access_role_id":{"type":["integer","null"]}}},"assignee_type":{"type":"string","enum":["AgentBot","User"],"description":"Type of the conversation assignee — an automation bot or a human agent."},"team":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"allow_auto_assign":{"type":"boolean","description":"When enabled, the team auto-assigns each newly team-assigned conversation to an available agent."},"icon":{"type":"string"},"icon_color":{"type":"string"},"account_id":{"type":"integer"},"is_member":{"type":"boolean"},"avatar_url":{"type":"string"},"thumbnail":{"type":"string"}}},"hmac_verified":{"type":["string","null"]}}},"id":{"type":"integer"},"messages":{"type":"string"},"account_id":{"type":"integer"},"uuid":{"type":"string"},"additional_attributes":{"type":"object","additionalProperties":true,"description":"Channel- and source-specific metadata for this record (e.g. browser info, referer, social profile identifiers). The key set depends on the originating channel."},"agent_last_seen_at":{"type":"integer"},"assignee_last_seen_at":{"type":"integer"},"can_reply":{"type":"boolean"},"contact_last_seen_at":{"type":"integer"},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"inbox_id":{"type":"integer"},"logical_inbox_id":{"type":"integer"},"labels":{"type":"string"},"muted":{"type":"boolean"},"snoozed_until":{"type":"string"},"status":{"type":"string","enum":["open","resolved","pending","snoozed"]},"created_at":{"type":"integer"},"updated_at":{"type":"number"},"automation_control_event_cursor":{"type":"string"},"timestamp":{"type":"integer"},"first_reply_created_at":{"type":"integer"},"unread_count":{"type":"integer"},"last_non_activity_message":{"type":"string"},"last_activity_at":{"type":"integer"},"priority":{"type":"string","enum":["low","medium","high","urgent"]},"owner_id":{"type":"integer"},"waiting_since":{"type":"integer"},"sla_policy_id":{"type":"integer"},"applied_sla":{"type":"string"},"sla_events":{"type":"string"}}},"example":{"meta":{"sender":{"additional_attributes":{},"availability_status":"online","email":"agent@example.com","id":1,"name":"Sample Name","phone_number":"+5511999998888","blocked":"sample blocked","contact_type":"visitor","identifier":"sample-identifier","company_id":1,"organization_id":1,"referred_by_affiliate_id":1,"referred_by_affiliate_name":"sample referred by affiliate name","owner_id":1,"legal_type":"individual","tax_id":"sample tax id","tax_id_type":"br_cpf","country":1,"address":{},"billing_address":{"zip":"sample zip","street":"sample street","number":"sample number","complement":"sample complement","neighborhood":"sample neighborhood","city":"São Paulo","state":"active","country":"BR"},"thumbnail":"sample thumbnail","custom_attributes":{},"last_activity_at":1,"created_at":1,"field_visibility":"visible","contact_inboxes":[{"source_id":1,"logical_inbox_id":1,"inbox":{"id":1,"avatar_url":"https://example.com/resource","channel_id":1,"name":"Sample Name","channel_type":"Channel::Api","provider":"default"}}],"consent_state":{}},"channel":"sample channel","assignee":{"id":1,"account_id":1,"account_user_id":1,"availability_status":"online","auto_offline":true,"confirmed":true,"email":"agent@example.com","provider":"email","available_name":"sample available name","custom_attributes":{},"name":"Sample Name","role":"agent","outbound_agent_name_header_policy":"sample outbound agent name header policy","thumbnail":"sample thumbnail","custom_role_id":1,"access_role_id":1},"assignee_type":"AgentBot","team":{"id":1,"name":"Sample Name","description":"A short description.","allow_auto_assign":true,"icon":"sample icon","icon_color":"#1F93FF","account_id":1,"is_member":true,"avatar_url":"https://example.com/resource","thumbnail":"sample thumbnail"},"hmac_verified":"sample hmac verified"},"id":1,"messages":"sample messages","account_id":1,"uuid":"sample uuid","additional_attributes":{},"agent_last_seen_at":1,"assignee_last_seen_at":1,"can_reply":true,"contact_last_seen_at":1,"custom_attributes":{},"inbox_id":1,"logical_inbox_id":1,"labels":"sample labels","muted":true,"snoozed_until":"sample snoozed until","status":"open","created_at":1,"updated_at":12.5,"automation_control_event_cursor":"sample automation control event cursor","timestamp":1,"first_reply_created_at":1,"unread_count":5,"last_non_activity_message":"sample last non activity message","last_activity_at":1,"priority":"low","owner_id":1,"waiting_since":1,"sla_policy_id":1,"applied_sla":"sample applied sla","sla_events":"sample sla events"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"inbox_id":{"type":"integer"},"source_id":{"type":"integer"}}},"example":{"inbox_id":1,"source_id":1}}}}}},"/api/v1/accounts/{account_id}/conversations/{id}/unread":{"post":{"tags":["Conversations"],"operationId":"auto_post_api_v1_accounts_account_id_conversations_id_unread","summary":"Unread conversations","description":"Performs the unread operation on the targeted conversation resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"meta":{"type":"object","properties":{"sender":{"type":"object","properties":{"additional_attributes":{"type":"object","additionalProperties":true,"description":"Channel- and source-specific metadata for this record (e.g. browser info, referer, social profile identifiers). The key set depends on the originating channel."},"availability_status":{"type":"string","enum":["online","offline","busy"],"description":"Realtime availability. Contacts report online/offline (presence-based); agents/users additionally report busy (their configured availability)."},"email":{"type":"string","format":"email"},"id":{"type":"integer"},"name":{"type":"string"},"phone_number":{"type":"string"},"blocked":{"type":"string"},"contact_type":{"type":"string","enum":["visitor","lead","customer"]},"identifier":{"type":"string"},"company_id":{"type":"integer"},"organization_id":{"type":"integer"},"referred_by_affiliate_id":{"type":"integer"},"referred_by_affiliate_name":{"type":["string","null"]},"owner_id":{"type":"integer"},"legal_type":{"type":"string","enum":["individual","business"]},"tax_id":{"type":"string","description":"The fiscal identifier (CPF/CNPJ/EIN/VAT); validated and stored encrypted on write. Read payloads return the real value to an authenticated human agent, and a type-aware mask (e.g. \"***.***.***-09\") when a role field rule masks it or the caller is a bot; a hidden rule omits the key. Webhooks, exports and message variables always carry the masked form."},"tax_id_type":{"type":"string","enum":["br_cpf","br_cnpj","us_ein","eu_vat","uk_vat","generic"],"description":"The fiscal identifier scheme used to validate and mask the tax_id (CPF/CNPJ check digits, EIN, EU/UK VAT or a generic fallback)."},"country":{"type":"integer"},"address":{"type":"object","additionalProperties":{"type":"string","description":"Address component value keyed by component name"},"description":"Postal address components keyed by component name."},"billing_address":{"type":"object","description":"Optional billing address override of the contact. An empty object means billing uses the principal address.","properties":{"zip":{"type":"string","description":"Postal/ZIP code (CEP in Brazil)"},"street":{"type":"string","description":"Street name"},"number":{"type":"string","description":"Street number"},"complement":{"type":"string","description":"Address complement (apartment, suite, block)"},"neighborhood":{"type":"string","description":"Neighborhood/district"},"city":{"type":"string","description":"City name"},"state":{"type":"string","description":"State/province (UF in Brazil)"},"country":{"type":"string","description":"Country of the postal address"}}},"thumbnail":{"type":"string"},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"last_activity_at":{"type":"integer"},"created_at":{"type":"integer"},"field_visibility":{"type":"string","enum":["visible","masked","hidden"],"description":"Per-field visibility resolved from the current access role's field_permissions (FieldVisibilityHelper). `visible` renders the real value, `masked` an obfuscated one, `hidden` omits the key entirely."},"contact_inboxes":{"type":"array","items":{"type":"object","properties":{"source_id":{"type":"integer"},"logical_inbox_id":{"type":"integer"},"inbox":{"type":"object","properties":{"id":{"type":"integer"},"avatar_url":{"type":"string"},"channel_id":{"type":"integer"},"name":{"type":"string"},"channel_type":{"type":"string","enum":["Channel::Api","Channel::Email","Channel::FacebookPage","Channel::Instagram","Channel::Line","Channel::Sms","Channel::Telegram","Channel::Tiktok","Channel::TwilioSms","Channel::TwitterProfile","Channel::WebWidget","Channel::Whatsapp"],"description":"The inbox channel class — identifies which messaging channel backs the inbox."},"provider":{"type":"string","enum":["default","whatsapp_cloud","whatsapp_web","google","microsoft"],"description":"Messaging provider backing the inbox channel (whatsapp_web is the WazMeow gateway; email uses google/microsoft; default otherwise)."}}}}}},"consent_state":{"type":"object","additionalProperties":{"type":"string","enum":["granted","denied","pending"],"description":"Consent state in force for this delivery channel."},"description":"LGPD consent state keyed by delivery channel (\"all\" is the account-wide scope that shadows the per-channel ones). A channel the contact never declared on is absent rather than pending, since the set of channels an account may use is open. Present only on single-contact payloads. Signals only — it never blocks a send."}}},"channel":{"type":"string"},"assignee":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":["integer","null"]},"account_user_id":{"type":["integer","null"]},"availability_status":{"type":"string","enum":["online","offline","busy"],"description":"Realtime availability. Contacts report online/offline (presence-based); agents/users additionally report busy (their configured availability)."},"auto_offline":{"type":"boolean"},"confirmed":{"type":"boolean"},"email":{"type":"string","format":"email"},"provider":{"type":"string","enum":["email","google_oauth2","saml"],"description":"Authentication provider the user signed up through."},"available_name":{"type":"string"},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"name":{"type":"string"},"role":{"type":"string","enum":["agent","administrator"]},"outbound_agent_name_header_policy":{"type":["string","null"]},"thumbnail":{"type":"string"},"custom_role_id":{"type":["integer","null"]},"access_role_id":{"type":["integer","null"]}}},"assignee_type":{"type":"string","enum":["AgentBot","User"],"description":"Type of the conversation assignee — an automation bot or a human agent."},"team":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"allow_auto_assign":{"type":"boolean","description":"When enabled, the team auto-assigns each newly team-assigned conversation to an available agent."},"icon":{"type":"string"},"icon_color":{"type":"string"},"account_id":{"type":"integer"},"is_member":{"type":"boolean"},"avatar_url":{"type":"string"},"thumbnail":{"type":"string"}}},"hmac_verified":{"type":["string","null"]}}},"id":{"type":"integer"},"messages":{"type":"string"},"account_id":{"type":"integer"},"uuid":{"type":"string"},"additional_attributes":{"type":"object","additionalProperties":true,"description":"Channel- and source-specific metadata for this record (e.g. browser info, referer, social profile identifiers). The key set depends on the originating channel."},"agent_last_seen_at":{"type":"integer"},"assignee_last_seen_at":{"type":"integer"},"can_reply":{"type":"boolean"},"contact_last_seen_at":{"type":"integer"},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"inbox_id":{"type":"integer"},"logical_inbox_id":{"type":"integer"},"labels":{"type":"string"},"muted":{"type":"boolean"},"snoozed_until":{"type":"string"},"status":{"type":"string","enum":["open","resolved","pending","snoozed"]},"created_at":{"type":"integer"},"updated_at":{"type":"number"},"automation_control_event_cursor":{"type":"string"},"timestamp":{"type":"integer"},"first_reply_created_at":{"type":"integer"},"unread_count":{"type":"integer"},"last_non_activity_message":{"type":"string"},"last_activity_at":{"type":"integer"},"priority":{"type":"string","enum":["low","medium","high","urgent"]},"owner_id":{"type":"integer"},"waiting_since":{"type":"integer"},"sla_policy_id":{"type":"integer"},"applied_sla":{"type":"string"},"sla_events":{"type":"string"}}},"example":{"meta":{"sender":{"additional_attributes":{},"availability_status":"online","email":"agent@example.com","id":1,"name":"Sample Name","phone_number":"+5511999998888","blocked":"sample blocked","contact_type":"visitor","identifier":"sample-identifier","company_id":1,"organization_id":1,"referred_by_affiliate_id":1,"referred_by_affiliate_name":"sample referred by affiliate name","owner_id":1,"legal_type":"individual","tax_id":"sample tax id","tax_id_type":"br_cpf","country":1,"address":{},"billing_address":{"zip":"sample zip","street":"sample street","number":"sample number","complement":"sample complement","neighborhood":"sample neighborhood","city":"São Paulo","state":"active","country":"BR"},"thumbnail":"sample thumbnail","custom_attributes":{},"last_activity_at":1,"created_at":1,"field_visibility":"visible","contact_inboxes":[{"source_id":1,"logical_inbox_id":1,"inbox":{"id":1,"avatar_url":"https://example.com/resource","channel_id":1,"name":"Sample Name","channel_type":"Channel::Api","provider":"default"}}],"consent_state":{}},"channel":"sample channel","assignee":{"id":1,"account_id":1,"account_user_id":1,"availability_status":"online","auto_offline":true,"confirmed":true,"email":"agent@example.com","provider":"email","available_name":"sample available name","custom_attributes":{},"name":"Sample Name","role":"agent","outbound_agent_name_header_policy":"sample outbound agent name header policy","thumbnail":"sample thumbnail","custom_role_id":1,"access_role_id":1},"assignee_type":"AgentBot","team":{"id":1,"name":"Sample Name","description":"A short description.","allow_auto_assign":true,"icon":"sample icon","icon_color":"#1F93FF","account_id":1,"is_member":true,"avatar_url":"https://example.com/resource","thumbnail":"sample thumbnail"},"hmac_verified":"sample hmac verified"},"id":1,"messages":"sample messages","account_id":1,"uuid":"sample uuid","additional_attributes":{},"agent_last_seen_at":1,"assignee_last_seen_at":1,"can_reply":true,"contact_last_seen_at":1,"custom_attributes":{},"inbox_id":1,"logical_inbox_id":1,"labels":"sample labels","muted":true,"snoozed_until":"sample snoozed until","status":"open","created_at":1,"updated_at":12.5,"automation_control_event_cursor":"sample automation control event cursor","timestamp":1,"first_reply_created_at":1,"unread_count":5,"last_non_activity_message":"sample last non activity message","last_activity_at":1,"priority":"low","owner_id":1,"waiting_since":1,"sla_policy_id":1,"applied_sla":"sample applied sla","sla_events":"sample sla events"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/conversations/{id}/attachments":{"get":{"tags":["Conversations"],"operationId":"auto_get_api_v1_accounts_account_id_conversations_id_attachments","summary":"Attachments conversations","description":"Performs the attachments operation on the targeted conversation resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"meta":{"type":"object","properties":{"total_count":{"type":"integer"}}},"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"message_id":{"type":"integer"},"thumb_url":{"type":"string"},"data_url":{"type":"string"},"playable_audio_url":{"type":"string"},"playable_video_url":{"type":"string"},"video_processing":{"type":"boolean","description":"True while a browser-playable video rendition is being inspected or prepared asynchronously."},"video_unavailable":{"type":"boolean","description":"True when no safe browser-playable video rendition could be prepared; the original file remains downloadable."},"file_size":{"type":"string"},"file_type":{"type":"string","enum":["image","audio","video","file","location","fallback","share","story_mention","contact","ig_reel","ig_post","ig_story","embed"],"description":"Kind of the message attachment."},"extension":{"type":"string"},"width":{"type":"string"},"height":{"type":"string"},"content_type":{"type":"string"},"media_status":{"type":"string","enum":["available","processing","unavailable","external"],"description":"Durable media state. `processing` means the provider bytes are being copied to installation storage; `available` is locally persisted; `external` is an intentional link-only attachment; `unavailable` has no usable bytes."},"media_readiness_revision":{"type":"string"},"provider_permalink":{"type":"string","description":"Validated HTTPS URL of the original Instagram post, Reel, or Story when Meta exposes it; omitted when unavailable."},"media_processing":{"type":"string"},"media_unavailable":{"type":"string"},"media_deleted":{"type":"string"},"created_at":{"type":"integer"},"sender":{"type":"string"}}}}}},"example":{"meta":{"total_count":5},"payload":[{"id":1,"message_id":1,"thumb_url":"https://example.com/resource","data_url":"https://example.com/resource","playable_audio_url":"https://example.com/resource","playable_video_url":"https://example.com/resource","video_processing":true,"video_unavailable":true,"file_size":"sample file size","file_type":"image","extension":"sample extension","width":"sample width","height":"sample height","content_type":"sample content type","media_status":"available","media_readiness_revision":"sample media readiness revision","provider_permalink":"sample provider permalink","media_processing":"sample media processing","media_unavailable":"sample media unavailable","media_deleted":"sample media deleted","created_at":1,"sender":"sample sender"}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page of attachments (25 per page).","schema":{"type":"integer","default":1},"example":1}]}},"/api/v1/accounts/{account_id}/conversations/{id}/inbox_assistant":{"get":{"tags":["Conversations"],"operationId":"auto_get_api_v1_accounts_account_id_conversations_id_inbox_assistant","summary":"Inbox assistant conversations","description":"Performs the inbox assistant operation on the targeted conversation resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Captain assistant bound to the conversation's inbox (null when none)","content":{"application/json":{"schema":{"type":"object","properties":{"assistant":{"type":["object","null"],"properties":{"id":{"type":"integer","example":3},"name":{"type":"string","example":"Support Copilot"}},"example":{"id":3,"name":"Support Copilot"}}}},"example":{"assistant":{"id":3,"name":"Support Copilot"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/search/conversations":{"get":{"tags":["Search"],"operationId":"auto_get_api_v1_accounts_account_id_search_conversations","summary":"Search conversations","description":"Full-text search restricted to conversations. Requires a `q` query parameter.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Matching conversations.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"conversations":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Conversation display id.","example":812},"account_id":{"type":"integer","example":1},"created_at":{"type":"integer","description":"Epoch seconds.","example":1736937000},"message":{"type":["object","null"],"description":"First matching message (message model shape).","additionalProperties":true},"contact":{"type":["object","null"],"properties":{"id":{"type":"integer","example":214},"name":{"type":"string","example":"Jane Doe"},"email":{"type":["string","null"],"example":"jane@example.com"},"phone_number":{"type":["string","null"],"example":"+15551234567"}}},"inbox":{"type":["object","null"],"properties":{"id":{"type":"integer","example":4},"channel_id":{"type":"integer","example":9},"name":{"type":"string","example":"Website Support"},"channel_type":{"type":"string","example":"Channel::WebWidget","enum":["Channel::Api","Channel::Email","Channel::FacebookPage","Channel::Instagram","Channel::Line","Channel::Sms","Channel::Telegram","Channel::Tiktok","Channel::TwilioSms","Channel::TwitterProfile","Channel::WebWidget","Channel::Whatsapp"],"description":"The inbox channel class — identifies which messaging channel backs the inbox."}}},"agent":{"type":["object","null"],"properties":{"id":{"type":"integer","example":3},"available_name":{"type":"string","example":"Jane"},"email":{"type":"string","example":"jane@acme.com"},"name":{"type":"string","example":"Jane Agent"},"role":{"type":"string","enum":["administrator","agent"],"example":"agent"}}},"additional_attributes":{"type":"object","additionalProperties":true,"description":"Channel- and source-specific metadata for this record (e.g. browser info, referer, social profile identifiers). The key set depends on the originating channel."}}}}}}}},"example":{"payload":{"conversations":[{"id":812,"account_id":1,"created_at":1736937000,"message":{},"contact":{"id":214,"name":"Jane Doe","email":"jane@example.com","phone_number":"+15551234567"},"inbox":{"id":4,"channel_id":9,"name":"Website Support","channel_type":"Channel::WebWidget"},"agent":{"id":3,"available_name":"Jane","email":"jane@acme.com","name":"Jane Agent","role":"agent"},"additional_attributes":{}}]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"integer"}},{"name":"q","in":"query","required":true,"description":"Text to search in conversation messages and contact identity fields.","schema":{"type":"string","minLength":1},"example":"pedido atrasado"},{"name":"page","in":"query","required":false,"description":"One-based results page.","schema":{"type":"integer","minimum":1,"default":1}}]}},"/api/v1/accounts/{account_id}/search/messages":{"get":{"tags":["Search"],"operationId":"auto_get_api_v1_accounts_account_id_search_messages","summary":"Search messages","description":"Full-text search restricted to messages. Requires a `q` query parameter.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Matching messages.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"messages":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","example":9021},"content":{"type":["string","null"],"example":"Hello, I need help"},"inbox_id":{"type":"integer","example":4},"conversation_id":{"type":"integer","description":"Conversation display id.","example":812},"message_type":{"type":"integer","enum":[0,1,2,3],"description":"0 incoming, 1 outgoing, 2 activity, 3 template.","example":0},"content_type":{"type":"string","example":"text","enum":["text","input_text","input_textarea","input_email","input_select","cards","form","article","incoming_email","input_csat","integrations","sticker","voice_call","poll"],"description":"Structured content type of the message (drives how content_attributes is interpreted)."},"status":{"type":"string","example":"sent","enum":["sent","delivered","read","failed"],"description":"Delivery status of the message."},"content_attributes":{"type":"object","additionalProperties":true,"description":"Structured metadata accompanying the message content; the key set depends on content_type (e.g. select items, CSAT submission values, deletion flags, external delivery errors)."},"created_at":{"type":"integer","description":"Epoch seconds.","example":1736937000},"private":{"type":"boolean","example":false},"source_id":{"type":["string","null"],"example":"wamid.HBgL..."},"sender":{"type":["object","null"],"description":"Sender push-event data (contact or agent).","additionalProperties":true},"attachments":{"type":"array","items":{"type":"object"},"description":"Attachment push-event data (when present)."}}}}}}}},"example":{"payload":{"messages":[{"id":9021,"content":"Hello, I need help","inbox_id":4,"conversation_id":812,"message_type":0,"content_type":"text","status":"sent","content_attributes":{},"created_at":1736937000,"private":false,"source_id":"wamid.HBgL...","sender":{},"attachments":[{}]}]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/search/contacts":{"get":{"tags":["Search"],"operationId":"auto_get_api_v1_accounts_account_id_search_contacts","summary":"Search contacts","description":"Full-text search restricted to contacts. Requires a `q` query parameter.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Matching contacts.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"contacts":{"type":"array","items":{"type":"object","properties":{"email":{"type":["string","null"],"example":"jane@example.com"},"id":{"type":"integer","example":214},"name":{"type":"string","example":"Jane Doe"},"phone_number":{"type":["string","null"],"example":"+15551234567"},"identifier":{"type":["string","null"],"example":"cust_214"},"additional_attributes":{"type":"object","additionalProperties":true,"description":"Channel- and source-specific metadata for this record (e.g. browser info, referer, social profile identifiers). The key set depends on the originating channel."},"last_activity_at":{"type":["integer","null"],"description":"Epoch seconds.","example":1736937000}}}}}}}},"example":{"payload":{"contacts":[{"email":"jane@example.com","id":214,"name":"Jane Doe","phone_number":"+15551234567","identifier":"cust_214","additional_attributes":{},"last_activity_at":1736937000}]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/search/articles":{"get":{"tags":["Search"],"operationId":"auto_get_api_v1_accounts_account_id_search_articles","summary":"Search help center articles","description":"Full-text search restricted to help center articles. Requires a `q` query parameter.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Matching articles.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"articles":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","example":33},"title":{"type":"string","example":"How to reset your password"},"locale":{"type":"string","example":"en"},"content":{"type":"string","example":"To reset your password, open Settings..."},"slug":{"type":"string","example":"how-to-reset-your-password"},"portal_slug":{"type":"string","example":"help-center"},"account_id":{"type":"integer","example":1},"category_name":{"type":["string","null"],"example":"Account"},"status":{"type":"string","example":"published","enum":["draft","published","archived"],"description":"Publication status of the help-center article."},"updated_at":{"type":"integer","description":"Epoch seconds.","example":1736937000}}}}}}}},"example":{"payload":{"articles":[{"id":33,"title":"How to reset your password","locale":"en","content":"To reset your password, open Settings...","slug":"how-to-reset-your-password","portal_slug":"help-center","account_id":1,"category_name":"Account","status":"published","updated_at":1736937000}]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/search/organizations":{"get":{"tags":["Search"],"operationId":"auto_get_api_v1_accounts_account_id_search_organizations","summary":"Organizations search","description":"Performs the organizations operation on the targeted search resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Organizations matching the query (empty payload when the organizations module is off).","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"organizations":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","example":42},"name":{"type":"string","example":"Colégio Horizonte"},"legal_name":{"type":["string","null"],"example":"Colégio Horizonte Educação LTDA"},"domain":{"type":["string","null"],"example":"colegiohorizonte.com.br"},"lifecycle_stage":{"type":["string","null"],"example":"customer"},"industry":{"type":["string","null"],"example":"education"},"contacts_count":{"type":"integer","example":12},"thumbnail":{"type":["string","null"],"example":"https://cdn.example.com/orgs/42.png"}}}}}}}},"example":{"payload":{"organizations":[{"id":42,"name":"Colégio Horizonte","legal_name":"Colégio Horizonte Educação LTDA","domain":"colegiohorizonte.com.br","lifecycle_stage":"customer","industry":"education","contacts_count":12,"thumbnail":"https://cdn.example.com/orgs/42.png"}]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/search":{"get":{"tags":["Search"],"operationId":"auto_get_api_v1_accounts_account_id_search","summary":"Search across conversations, contacts, messages and articles","description":"Full-text search over all indexed resource types for the account. Requires a `q` query parameter. Returns the four result collections under `payload`.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Combined search results.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"conversations":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Conversation display id.","example":812},"account_id":{"type":"integer","example":1},"created_at":{"type":"integer","description":"Epoch seconds.","example":1736937000},"message":{"type":["object","null"],"description":"First matching message (message model shape).","properties":{"id":{"type":"integer","example":9021},"content":{"type":["string","null"],"example":"Hello, I need help"},"message_type":{"type":"integer","enum":[0,1,2,3],"description":"0 incoming, 1 outgoing, 2 activity, 3 template.","example":0},"content_type":{"type":"string","example":"text","enum":["text","input_text","input_textarea","input_email","input_select","cards","form","article","incoming_email","input_csat","integrations","sticker","voice_call","poll"],"description":"Structured content type of the message (drives how content_attributes is interpreted)."},"created_at":{"type":"integer","description":"Epoch seconds.","example":1736937000}}},"contact":{"type":["object","null"],"properties":{"id":{"type":"integer","example":214},"name":{"type":"string","example":"Jane Doe"},"email":{"type":["string","null"],"example":"jane@example.com"},"phone_number":{"type":["string","null"],"example":"+15551234567"}}},"inbox":{"type":["object","null"],"properties":{"id":{"type":"integer","example":4},"channel_id":{"type":"integer","example":9},"name":{"type":"string","example":"Website Support"},"channel_type":{"type":"string","example":"Channel::WebWidget","enum":["Channel::Api","Channel::Email","Channel::FacebookPage","Channel::Instagram","Channel::Line","Channel::Sms","Channel::Telegram","Channel::Tiktok","Channel::TwilioSms","Channel::TwitterProfile","Channel::WebWidget","Channel::Whatsapp"],"description":"The inbox channel class — identifies which messaging channel backs the inbox."}}},"agent":{"type":["object","null"],"properties":{"id":{"type":"integer","example":3},"available_name":{"type":"string","example":"Jane"},"email":{"type":"string","example":"jane@acme.com"},"name":{"type":"string","example":"Jane Agent"},"role":{"type":"string","enum":["administrator","agent"],"example":"agent"}}}}}},"contacts":{"type":"array","items":{"type":"object","properties":{"email":{"type":["string","null"],"example":"jane@example.com"},"id":{"type":"integer","example":214},"name":{"type":"string","example":"Jane Doe"},"phone_number":{"type":["string","null"],"example":"+15551234567"},"identifier":{"type":["string","null"],"example":"cust_214"},"additional_attributes":{"type":"object","additionalProperties":true,"description":"Channel- and source-specific metadata for this record (e.g. browser info, referer, social profile identifiers). The key set depends on the originating channel."},"last_activity_at":{"type":["integer","null"],"description":"Epoch seconds.","example":1736937000}}}},"messages":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","example":9021},"content":{"type":["string","null"],"example":"Hello, I need help"},"inbox_id":{"type":"integer","example":4},"conversation_id":{"type":"integer","description":"Conversation display id.","example":812},"message_type":{"type":"integer","enum":[0,1,2,3],"description":"0 incoming, 1 outgoing, 2 activity, 3 template.","example":0},"content_type":{"type":"string","example":"text","enum":["text","input_text","input_textarea","input_email","input_select","cards","form","article","incoming_email","input_csat","integrations","sticker","voice_call","poll"],"description":"Structured content type of the message (drives how content_attributes is interpreted)."},"status":{"type":"string","example":"sent","enum":["sent","delivered","read","failed"],"description":"Delivery status of the message."},"content_attributes":{"type":"object","additionalProperties":true,"description":"Structured metadata accompanying the message content; the key set depends on content_type (e.g. select items, CSAT submission values, deletion flags, external delivery errors)."},"created_at":{"type":"integer","description":"Epoch seconds.","example":1736937000},"private":{"type":"boolean","example":false},"source_id":{"type":["string","null"],"example":"wamid.HBgL..."},"sender":{"type":["object","null"],"description":"Sender push-event data (contact or agent).","additionalProperties":true},"attachments":{"type":"array","items":{"type":"object"},"description":"Attachment push-event data (when present)."}}}},"articles":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","example":33},"title":{"type":"string","example":"How to reset your password"},"locale":{"type":"string","example":"en"},"content":{"type":"string","example":"To reset your password, open Settings..."},"slug":{"type":"string","example":"how-to-reset-your-password"},"portal_slug":{"type":"string","example":"help-center"},"account_id":{"type":"integer","example":1},"category_name":{"type":["string","null"],"example":"Account"},"status":{"type":"string","example":"published","enum":["draft","published","archived"],"description":"Publication status of the help-center article."},"updated_at":{"type":"integer","description":"Epoch seconds.","example":1736937000}}}}}}}},"example":{"payload":{"conversations":[{"id":812,"account_id":1,"created_at":1736937000,"message":{"id":9021,"content":"Hello, I need help","message_type":0,"content_type":"text","created_at":1736937000},"contact":{"id":214,"name":"Jane Doe","email":"jane@example.com","phone_number":"+15551234567"},"inbox":{"id":4,"channel_id":9,"name":"Website Support","channel_type":"Channel::WebWidget"},"agent":{"id":3,"available_name":"Jane","email":"jane@acme.com","name":"Jane Agent","role":"agent"}}],"contacts":[{"email":"jane@example.com","id":214,"name":"Jane Doe","phone_number":"+15551234567","identifier":"cust_214","additional_attributes":{},"last_activity_at":1736937000}],"messages":[{"id":9021,"content":"Hello, I need help","inbox_id":4,"conversation_id":812,"message_type":0,"content_type":"text","status":"sent","content_attributes":{},"created_at":1736937000,"private":false,"source_id":"wamid.HBgL...","sender":{},"attachments":[{}]}],"articles":[{"id":33,"title":"How to reset your password","locale":"en","content":"To reset your password, open Settings...","slug":"how-to-reset-your-password","portal_slug":"help-center","account_id":1,"category_name":"Account","status":"published","updated_at":1736937000}]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."}]}},"/api/v1/accounts/{account_id}/companies/search":{"get":{"tags":["Companies"],"operationId":"auto_get_api_v1_accounts_account_id_companies_search","summary":"Search companies","description":"Performs the search operation on the targeted company resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}},"example":{"error":"sample error"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"q","in":"query","required":true,"description":"Search term matched against company name and domain. Blank returns 422.","schema":{"type":"string"},"example":"acme"}]}},"/api/v1/accounts/{account_id}/companies/{id}/destroy_custom_attributes":{"post":{"tags":["Companies"],"operationId":"auto_post_api_v1_accounts_account_id_companies_id_destroy_custom_attributes","summary":"Remove custom attributes from a company","description":"Deletes the listed keys from the company's custom_attributes and returns the updated company. `custom_attributes` must be an array of attribute keys (422 otherwise).","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Updated company.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer","example":8},"name":{"type":"string","example":"Acme Inc"},"contacts_count":{"type":"integer","example":34},"domain":{"type":["string","null"],"example":"acme.com"},"description":{"type":["string","null"],"example":"Enterprise customer"},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"avatar_url":{"type":"string","example":"https://cdn.example.com/company/avatar.png"},"last_activity_at":{"type":["integer","null"],"description":"Epoch seconds.","example":1736937000},"created_at":{"type":["integer","null"],"description":"Epoch seconds.","example":1736850600},"updated_at":{"type":["integer","null"],"description":"Epoch seconds.","example":1736937000}}}}},"example":{"payload":{"id":8,"name":"Acme Inc","contacts_count":34,"domain":"acme.com","description":"Enterprise customer","custom_attributes":{},"avatar_url":"https://cdn.example.com/company/avatar.png","last_activity_at":1736937000,"created_at":1736850600,"updated_at":1736937000}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"422":{"description":"custom_attributes was not an array.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"custom_attributes must be an array"}}},"example":{"error":"custom_attributes must be an array"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"custom_attributes":{"type":"array","description":"Custom-attribute keys to delete.","items":{"type":"string"},"example":["annual_revenue","industry"]}}},"example":{"custom_attributes":["annual_revenue","industry"]}}}}}},"/api/v1/accounts/{account_id}/companies/{id}/avatar":{"delete":{"tags":["Companies"],"operationId":"auto_delete_api_v1_accounts_account_id_companies_id_avatar","summary":"Avatar companies","description":"Performs the avatar operation on the targeted company resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"contacts_count":{"type":"integer"},"domain":{"type":"string"},"description":{"type":"string"},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"avatar_url":{"type":"string"},"last_activity_at":{"type":"integer"},"created_at":{"type":"integer"},"updated_at":{"type":"integer"}}}}},"example":{"payload":{"id":1,"name":"Sample Name","contacts_count":5,"domain":"example.com","description":"A short description.","custom_attributes":{},"avatar_url":"https://example.com/resource","last_activity_at":1,"created_at":1,"updated_at":1}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/companies/{company_id}/contacts/search":{"get":{"tags":["Companies"],"operationId":"auto_get_api_v1_accounts_account_id_companies_company_id_contacts_search","summary":"Search contacts","description":"Performs the search operation on the targeted contact resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Specify search string with parameter q"}}},"example":{"error":"Specify search string with parameter q"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"company_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"q","in":"query","required":true,"description":"Search term matched against the company's contacts. Blank returns 422.","schema":{"type":"string"},"example":"maria"}]}},"/api/v1/accounts/{account_id}/companies/{company_id}/contacts":{"get":{"tags":["Companies"],"operationId":"auto_get_api_v1_accounts_account_id_companies_company_id_contacts","summary":"List contacts","description":"Returns the list of contacts visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"meta":{"type":"object","properties":{"total_count":{"type":"integer"},"page":{"type":"string"}}},"payload":{"type":"array","items":{"type":"object","properties":{"additional_attributes":{"type":"object","additionalProperties":true,"description":"Channel- and source-specific metadata for this record (e.g. browser info, referer, social profile identifiers). The key set depends on the originating channel."},"availability_status":{"type":"string","enum":["online","offline","busy"],"description":"Realtime availability. Contacts report online/offline (presence-based); agents/users additionally report busy (their configured availability)."},"email":{"type":"string","format":"email"},"id":{"type":"integer"},"name":{"type":"string"},"phone_number":{"type":"string"},"blocked":{"type":"string"},"contact_type":{"type":"string","enum":["visitor","lead","customer"]},"identifier":{"type":"string"},"company_id":{"type":"integer"},"organization_id":{"type":"integer"},"referred_by_affiliate_id":{"type":"integer"},"referred_by_affiliate_name":{"type":["string","null"]},"owner_id":{"type":"integer"},"legal_type":{"type":"string","enum":["individual","business"]},"tax_id":{"type":"string","description":"The fiscal identifier (CPF/CNPJ/EIN/VAT); validated and stored encrypted on write. Read payloads return the real value to an authenticated human agent, and a type-aware mask (e.g. \"***.***.***-09\") when a role field rule masks it or the caller is a bot; a hidden rule omits the key. Webhooks, exports and message variables always carry the masked form."},"tax_id_type":{"type":"string","enum":["br_cpf","br_cnpj","us_ein","eu_vat","uk_vat","generic"],"description":"The fiscal identifier scheme used to validate and mask the tax_id (CPF/CNPJ check digits, EIN, EU/UK VAT or a generic fallback)."},"country":{"type":"integer"},"address":{"type":"object","description":"Native postal address of the contact. Blank components are omitted.","properties":{"zip":{"type":"string","description":"Postal/ZIP code (CEP in Brazil)"},"street":{"type":"string","description":"Street name"},"number":{"type":"string","description":"Street number"},"complement":{"type":"string","description":"Address complement (apartment, suite, block)"},"neighborhood":{"type":"string","description":"Neighborhood/district"},"city":{"type":"string","description":"City name"},"state":{"type":"string","description":"State/province (UF in Brazil)"},"country":{"type":"string","description":"Country of the postal address"}}},"billing_address":{"type":"object","description":"Optional billing address override of the contact. An empty object means billing uses the principal address.","properties":{"zip":{"type":"string","description":"Postal/ZIP code (CEP in Brazil)"},"street":{"type":"string","description":"Street name"},"number":{"type":"string","description":"Street number"},"complement":{"type":"string","description":"Address complement (apartment, suite, block)"},"neighborhood":{"type":"string","description":"Neighborhood/district"},"city":{"type":"string","description":"City name"},"state":{"type":"string","description":"State/province (UF in Brazil)"},"country":{"type":"string","description":"Country of the postal address"}}},"thumbnail":{"type":"string"},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"last_activity_at":{"type":"integer"},"created_at":{"type":"integer"},"field_visibility":{"type":"string","enum":["visible","masked","hidden"],"description":"Per-field visibility resolved from the current access role's field_permissions (FieldVisibilityHelper). `visible` renders the real value, `masked` an obfuscated one, `hidden` omits the key entirely."},"contact_inboxes":{"type":"array","items":{"type":"object","properties":{"source_id":{"type":"integer"},"logical_inbox_id":{"type":"integer"},"inbox":{"type":"object","properties":{"id":{"type":"integer"},"avatar_url":{"type":"string"},"channel_id":{"type":"integer"},"name":{"type":"string"},"channel_type":{"type":"string","enum":["Channel::Api","Channel::Email","Channel::FacebookPage","Channel::Instagram","Channel::Line","Channel::Sms","Channel::Telegram","Channel::Tiktok","Channel::TwilioSms","Channel::TwitterProfile","Channel::WebWidget","Channel::Whatsapp"],"description":"The inbox channel class — identifies which messaging channel backs the inbox."},"provider":{"type":"string","enum":["default","whatsapp_cloud","whatsapp_web","google","microsoft"],"description":"Messaging provider backing the inbox channel (whatsapp_web is the WazMeow gateway; email uses google/microsoft; default otherwise)."}}}}}},"consent_state":{"type":"object","additionalProperties":{"type":"string","enum":["granted","denied","pending"],"description":"Consent state in force for this delivery channel."},"description":"LGPD consent state keyed by delivery channel (\"all\" is the account-wide scope that shadows the per-channel ones). A channel the contact never declared on is absent rather than pending, since the set of channels an account may use is open. Present only on single-contact payloads. Signals only — it never blocks a send."},"linked_to_current_company":{"type":"integer"},"company":{"type":"string"}}}}}},"example":{"meta":{"total_count":5,"page":"sample page"},"payload":[{"additional_attributes":{},"availability_status":"online","email":"agent@example.com","id":1,"name":"Sample Name","phone_number":"+5511999998888","blocked":"sample blocked","contact_type":"visitor","identifier":"sample-identifier","company_id":1,"organization_id":1,"referred_by_affiliate_id":1,"referred_by_affiliate_name":"sample referred by affiliate name","owner_id":1,"legal_type":"individual","tax_id":"sample tax id","tax_id_type":"br_cpf","country":1,"address":{"zip":"sample zip","street":"sample street","number":"sample number","complement":"sample complement","neighborhood":"sample neighborhood","city":"São Paulo","state":"active","country":"BR"},"billing_address":{"zip":"sample zip","street":"sample street","number":"sample number","complement":"sample complement","neighborhood":"sample neighborhood","city":"São Paulo","state":"active","country":"BR"},"thumbnail":"sample thumbnail","custom_attributes":{},"last_activity_at":1,"created_at":1,"field_visibility":"visible","contact_inboxes":[{"source_id":1,"logical_inbox_id":1,"inbox":{"id":1,"avatar_url":"https://example.com/resource","channel_id":1,"name":"Sample Name","channel_type":"Channel::Api","provider":"default"}}],"consent_state":{},"linked_to_current_company":1,"company":"sample company"}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"company_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."}]},"post":{"tags":["Companies"],"operationId":"auto_post_api_v1_accounts_account_id_companies_company_id_contacts","summary":"Create contacts","description":"Creates a new contact from the request payload. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"additional_attributes":{"type":"object","additionalProperties":true,"description":"Channel- and source-specific metadata for this record (e.g. browser info, referer, social profile identifiers). The key set depends on the originating channel."},"availability_status":{"type":"string","enum":["online","offline","busy"],"description":"Realtime availability. Contacts report online/offline (presence-based); agents/users additionally report busy (their configured availability)."},"email":{"type":"string","format":"email"},"id":{"type":"integer"},"name":{"type":"string"},"phone_number":{"type":"string"},"blocked":{"type":"string"},"contact_type":{"type":"string","enum":["visitor","lead","customer"]},"identifier":{"type":"string"},"company_id":{"type":"integer"},"organization_id":{"type":"integer"},"referred_by_affiliate_id":{"type":"integer"},"referred_by_affiliate_name":{"type":["string","null"]},"owner_id":{"type":"integer"},"legal_type":{"type":"string","enum":["individual","business"]},"tax_id":{"type":"string","description":"The fiscal identifier (CPF/CNPJ/EIN/VAT); validated and stored encrypted on write. Read payloads return the real value to an authenticated human agent, and a type-aware mask (e.g. \"***.***.***-09\") when a role field rule masks it or the caller is a bot; a hidden rule omits the key. Webhooks, exports and message variables always carry the masked form."},"tax_id_type":{"type":"string","enum":["br_cpf","br_cnpj","us_ein","eu_vat","uk_vat","generic"],"description":"The fiscal identifier scheme used to validate and mask the tax_id (CPF/CNPJ check digits, EIN, EU/UK VAT or a generic fallback)."},"country":{"type":"integer"},"address":{"type":"object","description":"Native postal address of the contact. Blank components are omitted.","properties":{"zip":{"type":"string","description":"Postal/ZIP code (CEP in Brazil)"},"street":{"type":"string","description":"Street name"},"number":{"type":"string","description":"Street number"},"complement":{"type":"string","description":"Address complement (apartment, suite, block)"},"neighborhood":{"type":"string","description":"Neighborhood/district"},"city":{"type":"string","description":"City name"},"state":{"type":"string","description":"State/province (UF in Brazil)"},"country":{"type":"string","description":"Country of the postal address"}}},"billing_address":{"type":"object","description":"Optional billing address override of the contact. An empty object means billing uses the principal address.","properties":{"zip":{"type":"string","description":"Postal/ZIP code (CEP in Brazil)"},"street":{"type":"string","description":"Street name"},"number":{"type":"string","description":"Street number"},"complement":{"type":"string","description":"Address complement (apartment, suite, block)"},"neighborhood":{"type":"string","description":"Neighborhood/district"},"city":{"type":"string","description":"City name"},"state":{"type":"string","description":"State/province (UF in Brazil)"},"country":{"type":"string","description":"Country of the postal address"}}},"thumbnail":{"type":"string"},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"last_activity_at":{"type":"integer"},"created_at":{"type":"integer"},"field_visibility":{"type":"string","enum":["visible","masked","hidden"],"description":"Per-field visibility resolved from the current access role's field_permissions (FieldVisibilityHelper). `visible` renders the real value, `masked` an obfuscated one, `hidden` omits the key entirely."},"contact_inboxes":{"type":"array","items":{"type":"object","properties":{"source_id":{"type":"integer"},"logical_inbox_id":{"type":"integer"},"inbox":{"type":"object","properties":{"id":{"type":"integer"},"avatar_url":{"type":"string"},"channel_id":{"type":"integer"},"name":{"type":"string"},"channel_type":{"type":"string","enum":["Channel::Api","Channel::Email","Channel::FacebookPage","Channel::Instagram","Channel::Line","Channel::Sms","Channel::Telegram","Channel::Tiktok","Channel::TwilioSms","Channel::TwitterProfile","Channel::WebWidget","Channel::Whatsapp"],"description":"The inbox channel class — identifies which messaging channel backs the inbox."},"provider":{"type":"string","enum":["default","whatsapp_cloud","whatsapp_web","google","microsoft"],"description":"Messaging provider backing the inbox channel (whatsapp_web is the WazMeow gateway; email uses google/microsoft; default otherwise)."}}}}}},"consent_state":{"type":"object","additionalProperties":{"type":"string","enum":["granted","denied","pending"],"description":"Consent state in force for this delivery channel."},"description":"LGPD consent state keyed by delivery channel (\"all\" is the account-wide scope that shadows the per-channel ones). A channel the contact never declared on is absent rather than pending, since the set of channels an account may use is open. Present only on single-contact payloads. Signals only — it never blocks a send."},"linked_to_current_company":{"type":"integer"},"company":{"type":"string"}}}}},"example":{"payload":{"additional_attributes":{},"availability_status":"online","email":"agent@example.com","id":1,"name":"Sample Name","phone_number":"+5511999998888","blocked":"sample blocked","contact_type":"visitor","identifier":"sample-identifier","company_id":1,"organization_id":1,"referred_by_affiliate_id":1,"referred_by_affiliate_name":"sample referred by affiliate name","owner_id":1,"legal_type":"individual","tax_id":"sample tax id","tax_id_type":"br_cpf","country":1,"address":{"zip":"sample zip","street":"sample street","number":"sample number","complement":"sample complement","neighborhood":"sample neighborhood","city":"São Paulo","state":"active","country":"BR"},"billing_address":{"zip":"sample zip","street":"sample street","number":"sample number","complement":"sample complement","neighborhood":"sample neighborhood","city":"São Paulo","state":"active","country":"BR"},"thumbnail":"sample thumbnail","custom_attributes":{},"last_activity_at":1,"created_at":1,"field_visibility":"visible","contact_inboxes":[{"source_id":1,"logical_inbox_id":1,"inbox":{"id":1,"avatar_url":"https://example.com/resource","channel_id":1,"name":"Sample Name","channel_type":"Channel::Api","provider":"default"}}],"consent_state":{},"linked_to_current_company":1,"company":"sample company"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"company_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"contact_id":{"type":"integer"}}},"example":{"contact_id":1}}}}}},"/api/v1/accounts/{account_id}/companies/{company_id}/contacts/{id}":{"delete":{"tags":["Companies"],"operationId":"auto_delete_api_v1_accounts_account_id_companies_company_id_contacts_id","summary":"Delete contacts","description":"Deletes the contact identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Success (no content)"},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"company_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/companies/{company_id}/conversations":{"get":{"tags":["Companies"],"operationId":"auto_get_api_v1_accounts_account_id_companies_company_id_conversations","summary":"List conversations","description":"Returns the list of conversations visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","properties":{"meta":{"type":"object","properties":{"sender":{"type":"object","properties":{"additional_attributes":{"type":"object","additionalProperties":true,"description":"Channel- and source-specific metadata for this record (e.g. browser info, referer, social profile identifiers). The key set depends on the originating channel."},"availability_status":{"type":"string","enum":["online","offline","busy"],"description":"Realtime availability. Contacts report online/offline (presence-based); agents/users additionally report busy (their configured availability)."},"email":{"type":"string","format":"email"},"id":{"type":"integer"},"name":{"type":"string"},"phone_number":{"type":"string"},"blocked":{"type":"string"},"contact_type":{"type":"string","enum":["visitor","lead","customer"]},"identifier":{"type":"string"},"company_id":{"type":"integer"},"organization_id":{"type":"integer"},"referred_by_affiliate_id":{"type":"integer"},"referred_by_affiliate_name":{"type":["string","null"]},"owner_id":{"type":"integer"},"legal_type":{"type":"string","enum":["individual","business"]},"tax_id":{"type":"string","description":"The fiscal identifier (CPF/CNPJ/EIN/VAT); validated and stored encrypted on write. Read payloads return the real value to an authenticated human agent, and a type-aware mask (e.g. \"***.***.***-09\") when a role field rule masks it or the caller is a bot; a hidden rule omits the key. Webhooks, exports and message variables always carry the masked form."},"tax_id_type":{"type":"string","enum":["br_cpf","br_cnpj","us_ein","eu_vat","uk_vat","generic"],"description":"The fiscal identifier scheme used to validate and mask the tax_id (CPF/CNPJ check digits, EIN, EU/UK VAT or a generic fallback)."},"country":{"type":"integer"},"address":{"type":"object","additionalProperties":{"type":"string","description":"Address component value keyed by component name"},"description":"Postal address components keyed by component name."},"billing_address":{"type":"object","description":"Optional billing address override of the contact. An empty object means billing uses the principal address.","properties":{"zip":{"type":"string","description":"Postal/ZIP code (CEP in Brazil)"},"street":{"type":"string","description":"Street name"},"number":{"type":"string","description":"Street number"},"complement":{"type":"string","description":"Address complement (apartment, suite, block)"},"neighborhood":{"type":"string","description":"Neighborhood/district"},"city":{"type":"string","description":"City name"},"state":{"type":"string","description":"State/province (UF in Brazil)"},"country":{"type":"string","description":"Country of the postal address"}}},"thumbnail":{"type":"string"},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"last_activity_at":{"type":"integer"},"created_at":{"type":"integer"},"field_visibility":{"type":"string","enum":["visible","masked","hidden"],"description":"Per-field visibility resolved from the current access role's field_permissions (FieldVisibilityHelper). `visible` renders the real value, `masked` an obfuscated one, `hidden` omits the key entirely."},"contact_inboxes":{"type":"array","items":{"type":"object","properties":{"source_id":{"type":"integer"},"logical_inbox_id":{"type":"integer"},"inbox":{"type":"object","properties":{"id":{"type":"integer"},"avatar_url":{"type":"string"},"channel_id":{"type":"integer"},"name":{"type":"string"},"channel_type":{"type":"string","enum":["Channel::Api","Channel::Email","Channel::FacebookPage","Channel::Instagram","Channel::Line","Channel::Sms","Channel::Telegram","Channel::Tiktok","Channel::TwilioSms","Channel::TwitterProfile","Channel::WebWidget","Channel::Whatsapp"],"description":"The inbox channel class — identifies which messaging channel backs the inbox."},"provider":{"type":"string","enum":["default","whatsapp_cloud","whatsapp_web","google","microsoft"],"description":"Messaging provider backing the inbox channel (whatsapp_web is the WazMeow gateway; email uses google/microsoft; default otherwise)."}}}}}},"consent_state":{"type":"object","additionalProperties":{"type":"string","enum":["granted","denied","pending"],"description":"Consent state in force for this delivery channel."},"description":"LGPD consent state keyed by delivery channel (\"all\" is the account-wide scope that shadows the per-channel ones). A channel the contact never declared on is absent rather than pending, since the set of channels an account may use is open. Present only on single-contact payloads. Signals only — it never blocks a send."}}},"channel":{"type":"string"},"assignee":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":["integer","null"]},"account_user_id":{"type":["integer","null"]},"availability_status":{"type":"string","enum":["online","offline","busy"],"description":"Realtime availability. Contacts report online/offline (presence-based); agents/users additionally report busy (their configured availability)."},"auto_offline":{"type":"boolean"},"confirmed":{"type":"boolean"},"email":{"type":"string","format":"email"},"provider":{"type":"string","enum":["email","google_oauth2","saml"],"description":"Authentication provider the user signed up through."},"available_name":{"type":"string"},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"name":{"type":"string"},"role":{"type":"string","enum":["agent","administrator"]},"outbound_agent_name_header_policy":{"type":["string","null"]},"thumbnail":{"type":"string"},"custom_role_id":{"type":["integer","null"]},"access_role_id":{"type":["integer","null"]}}},"assignee_type":{"type":"string","enum":["AgentBot","User"],"description":"Type of the conversation assignee — an automation bot or a human agent."},"team":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"allow_auto_assign":{"type":"boolean","description":"When enabled, the team auto-assigns each newly team-assigned conversation to an available agent."},"icon":{"type":"string"},"icon_color":{"type":"string"},"account_id":{"type":"integer"},"is_member":{"type":"boolean"},"avatar_url":{"type":"string"},"thumbnail":{"type":"string"}}},"hmac_verified":{"type":["string","null"]}}},"id":{"type":"integer"},"messages":{"type":"string"},"account_id":{"type":"integer"},"uuid":{"type":"string"},"additional_attributes":{"type":"object","additionalProperties":true,"description":"Channel- and source-specific metadata for this record (e.g. browser info, referer, social profile identifiers). The key set depends on the originating channel."},"agent_last_seen_at":{"type":"integer"},"assignee_last_seen_at":{"type":"integer"},"can_reply":{"type":"boolean"},"contact_last_seen_at":{"type":"integer"},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"inbox_id":{"type":"integer"},"logical_inbox_id":{"type":"integer"},"labels":{"type":"string"},"muted":{"type":"boolean"},"snoozed_until":{"type":"string"},"status":{"type":"string","enum":["open","resolved","pending","snoozed"]},"created_at":{"type":"integer"},"updated_at":{"type":"number"},"automation_control_event_cursor":{"type":"string"},"timestamp":{"type":"integer"},"first_reply_created_at":{"type":"integer"},"unread_count":{"type":"integer"},"last_non_activity_message":{"type":"string"},"last_activity_at":{"type":"integer"},"priority":{"type":"string","enum":["low","medium","high","urgent"]},"owner_id":{"type":"integer"},"waiting_since":{"type":"integer"},"sla_policy_id":{"type":"integer"},"applied_sla":{"type":"string"},"sla_events":{"type":"string"}}}}}},"example":{"payload":[{"meta":{"sender":{"additional_attributes":{},"availability_status":"online","email":"agent@example.com","id":1,"name":"Sample Name","phone_number":"+5511999998888","blocked":"sample blocked","contact_type":"visitor","identifier":"sample-identifier","company_id":1,"organization_id":1,"referred_by_affiliate_id":1,"referred_by_affiliate_name":"sample referred by affiliate name","owner_id":1,"legal_type":"individual","tax_id":"sample tax id","tax_id_type":"br_cpf","country":1,"address":{},"billing_address":{"zip":"sample zip","street":"sample street","number":"sample number","complement":"sample complement","neighborhood":"sample neighborhood","city":"São Paulo","state":"active","country":"BR"},"thumbnail":"sample thumbnail","custom_attributes":{},"last_activity_at":1,"created_at":1,"field_visibility":"visible","contact_inboxes":[{"source_id":1,"logical_inbox_id":1,"inbox":{"id":1,"avatar_url":"https://example.com/resource","channel_id":1,"name":"Sample Name","channel_type":"Channel::Api","provider":"default"}}],"consent_state":{}},"channel":"sample channel","assignee":{"id":1,"account_id":1,"account_user_id":1,"availability_status":"online","auto_offline":true,"confirmed":true,"email":"agent@example.com","provider":"email","available_name":"sample available name","custom_attributes":{},"name":"Sample Name","role":"agent","outbound_agent_name_header_policy":"sample outbound agent name header policy","thumbnail":"sample thumbnail","custom_role_id":1,"access_role_id":1},"assignee_type":"AgentBot","team":{"id":1,"name":"Sample Name","description":"A short description.","allow_auto_assign":true,"icon":"sample icon","icon_color":"#1F93FF","account_id":1,"is_member":true,"avatar_url":"https://example.com/resource","thumbnail":"sample thumbnail"},"hmac_verified":"sample hmac verified"},"id":1,"messages":"sample messages","account_id":1,"uuid":"sample uuid","additional_attributes":{},"agent_last_seen_at":1,"assignee_last_seen_at":1,"can_reply":true,"contact_last_seen_at":1,"custom_attributes":{},"inbox_id":1,"logical_inbox_id":1,"labels":"sample labels","muted":true,"snoozed_until":"sample snoozed until","status":"open","created_at":1,"updated_at":12.5,"automation_control_event_cursor":"sample automation control event cursor","timestamp":1,"first_reply_created_at":1,"unread_count":5,"last_non_activity_message":"sample last non activity message","last_activity_at":1,"priority":"low","owner_id":1,"waiting_since":1,"sla_policy_id":1,"applied_sla":"sample applied sla","sla_events":"sample sla events"}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"company_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."}]}},"/api/v1/accounts/{account_id}/companies/{company_id}/notes":{"get":{"tags":["Companies"],"operationId":"auto_get_api_v1_accounts_account_id_companies_company_id_notes","summary":"List notes","description":"Returns the list of notes visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"content":{"type":"string"},"account_id":{"type":"integer"},"contact_id":{"type":"integer"},"user":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":["integer","null"]},"account_user_id":{"type":["integer","null"]},"availability_status":{"type":"string","enum":["online","offline","busy"],"description":"Realtime availability. Contacts report online/offline (presence-based); agents/users additionally report busy (their configured availability)."},"auto_offline":{"type":"boolean"},"confirmed":{"type":"boolean"},"email":{"type":"string","format":"email"},"provider":{"type":"string","enum":["email","google_oauth2","saml"],"description":"Authentication provider the user signed up through."},"available_name":{"type":"string"},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"name":{"type":"string"},"role":{"type":"string","enum":["agent","administrator"]},"outbound_agent_name_header_policy":{"type":["string","null"]},"thumbnail":{"type":"string"},"custom_role_id":{"type":["integer","null"]},"access_role_id":{"type":["integer","null"]}}},"created_at":{"type":"integer"},"updated_at":{"type":"integer"}}}}}},"example":{"payload":[{"id":1,"content":"Sample content text.","account_id":1,"contact_id":1,"user":{"id":1,"account_id":1,"account_user_id":1,"availability_status":"online","auto_offline":true,"confirmed":true,"email":"agent@example.com","provider":"email","available_name":"sample available name","custom_attributes":{},"name":"Sample Name","role":"agent","outbound_agent_name_header_policy":"sample outbound agent name header policy","thumbnail":"sample thumbnail","custom_role_id":1,"access_role_id":1},"created_at":1,"updated_at":1}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"company_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."}]}},"/api/v1/accounts/{account_id}/companies":{"get":{"tags":["Companies"],"operationId":"auto_get_api_v1_accounts_account_id_companies","summary":"List companies","description":"Returns the list of companies visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"meta":{"type":"object","properties":{"total_count":{"type":"integer"},"page":{"type":"string"}}},"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"contacts_count":{"type":"integer"},"domain":{"type":"string"},"description":{"type":"string"},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"avatar_url":{"type":"string"},"last_activity_at":{"type":"integer"},"created_at":{"type":"integer"},"updated_at":{"type":"integer"}}}}}},"example":{"meta":{"total_count":5,"page":"sample page"},"payload":[{"id":1,"name":"Sample Name","contacts_count":5,"domain":"example.com","description":"A short description.","custom_attributes":{},"avatar_url":"https://example.com/resource","last_activity_at":1,"created_at":1,"updated_at":1}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."}]},"post":{"tags":["Companies"],"operationId":"auto_post_api_v1_accounts_account_id_companies","summary":"Create companies","description":"Creates a new company from the request payload. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"contacts_count":{"type":"integer"},"domain":{"type":"string"},"description":{"type":"string"},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"avatar_url":{"type":"string"},"last_activity_at":{"type":"integer"},"created_at":{"type":"integer"},"updated_at":{"type":"integer"}}}}},"example":{"payload":{"id":1,"name":"Sample Name","contacts_count":5,"domain":"example.com","description":"A short description.","custom_attributes":{},"avatar_url":"https://example.com/resource","last_activity_at":1,"created_at":1,"updated_at":1}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"company":{"type":"object","properties":{"name":{"type":"string"},"domain":{"type":"string"},"description":{"type":"string"},"avatar":{"type":"string"},"additional_attributes":{"type":"object","additionalProperties":true,"description":"Channel- and source-specific metadata for this record (e.g. browser info, referer, social profile identifiers). The key set depends on the originating channel."},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."}},"required":["name"]}},"required":["company"]},"example":{"company":{"name":"Sample Name","domain":"example.com","description":"A short description.","avatar":"sample avatar","additional_attributes":{},"custom_attributes":{}}}}}}}},"/api/v1/accounts/{account_id}/companies/{id}":{"get":{"tags":["Companies"],"operationId":"auto_get_api_v1_accounts_account_id_companies_id","summary":"Get companies","description":"Returns the company identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"contacts_count":{"type":"integer"},"domain":{"type":"string"},"description":{"type":"string"},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"avatar_url":{"type":"string"},"last_activity_at":{"type":"integer"},"created_at":{"type":"integer"},"updated_at":{"type":"integer"}}}}},"example":{"payload":{"id":1,"name":"Sample Name","contacts_count":5,"domain":"example.com","description":"A short description.","custom_attributes":{},"avatar_url":"https://example.com/resource","last_activity_at":1,"created_at":1,"updated_at":1}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]},"patch":{"tags":["Companies"],"operationId":"auto_patch_api_v1_accounts_account_id_companies_id","summary":"Update companies","description":"Updates the company identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"contacts_count":{"type":"integer"},"domain":{"type":"string"},"description":{"type":"string"},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"avatar_url":{"type":"string"},"last_activity_at":{"type":"integer"},"created_at":{"type":"integer"},"updated_at":{"type":"integer"}}}}},"example":{"payload":{"id":1,"name":"Sample Name","contacts_count":5,"domain":"example.com","description":"A short description.","custom_attributes":{},"avatar_url":"https://example.com/resource","last_activity_at":1,"created_at":1,"updated_at":1}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"company":{"type":"object","properties":{"name":{"type":"string"},"domain":{"type":"string"},"description":{"type":"string"},"avatar":{"type":"string"},"additional_attributes":{"type":"object","additionalProperties":true,"description":"Channel- and source-specific metadata for this record (e.g. browser info, referer, social profile identifiers). The key set depends on the originating channel."},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."}}}},"required":["company"]},"example":{"company":{"name":"Sample Name","domain":"example.com","description":"A short description.","avatar":"sample avatar","additional_attributes":{},"custom_attributes":{}}}}}}},"put":{"tags":["Companies"],"operationId":"auto_put_api_v1_accounts_account_id_companies_id","summary":"Update companies","description":"Updates the company identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"contacts_count":{"type":"integer"},"domain":{"type":"string"},"description":{"type":"string"},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"avatar_url":{"type":"string"},"last_activity_at":{"type":"integer"},"created_at":{"type":"integer"},"updated_at":{"type":"integer"}}}}},"example":{"payload":{"id":1,"name":"Sample Name","contacts_count":5,"domain":"example.com","description":"A short description.","custom_attributes":{},"avatar_url":"https://example.com/resource","last_activity_at":1,"created_at":1,"updated_at":1}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"company":{"type":"object","properties":{"name":{"type":"string"},"domain":{"type":"string"},"description":{"type":"string"},"avatar":{"type":"string"},"additional_attributes":{"type":"object","additionalProperties":true,"description":"Channel- and source-specific metadata for this record (e.g. browser info, referer, social profile identifiers). The key set depends on the originating channel."},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."}}}},"required":["company"]},"example":{"company":{"name":"Sample Name","domain":"example.com","description":"A short description.","avatar":"sample avatar","additional_attributes":{},"custom_attributes":{}}}}}}},"delete":{"tags":["Companies"],"operationId":"auto_delete_api_v1_accounts_account_id_companies_id","summary":"Delete a company","description":"Permanently deletes the company. Returns an empty 200 response.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Company deleted (empty body)."},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/contacts/active":{"get":{"tags":["Contacts"],"operationId":"auto_get_api_v1_accounts_account_id_contacts_active","summary":"Active contacts","description":"Performs the active operation on the targeted contact resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"meta":{"type":"object","properties":{"count":{"type":"integer"},"current_page":{"type":"string"}}},"payload":{"type":"array","items":{"type":"object","properties":{"additional_attributes":{"type":"object","additionalProperties":true,"description":"Channel- and source-specific metadata for this record (e.g. browser info, referer, social profile identifiers). The key set depends on the originating channel."},"availability_status":{"type":"string","enum":["online","offline","busy"],"description":"Realtime availability. Contacts report online/offline (presence-based); agents/users additionally report busy (their configured availability)."},"email":{"type":"string","format":"email"},"id":{"type":"integer"},"name":{"type":"string"},"phone_number":{"type":"string"},"blocked":{"type":"string"},"contact_type":{"type":"string","enum":["visitor","lead","customer"]},"identifier":{"type":"string"},"company_id":{"type":"integer"},"organization_id":{"type":"integer"},"referred_by_affiliate_id":{"type":"integer"},"referred_by_affiliate_name":{"type":["string","null"]},"owner_id":{"type":"integer"},"legal_type":{"type":"string","enum":["individual","business"]},"tax_id":{"type":"string","description":"The fiscal identifier (CPF/CNPJ/EIN/VAT); validated and stored encrypted on write. Read payloads return the real value to an authenticated human agent, and a type-aware mask (e.g. \"***.***.***-09\") when a role field rule masks it or the caller is a bot; a hidden rule omits the key. Webhooks, exports and message variables always carry the masked form."},"tax_id_type":{"type":"string","enum":["br_cpf","br_cnpj","us_ein","eu_vat","uk_vat","generic"],"description":"The fiscal identifier scheme used to validate and mask the tax_id (CPF/CNPJ check digits, EIN, EU/UK VAT or a generic fallback)."},"country":{"type":"integer"},"address":{"type":"object","description":"Native postal address of the contact. Blank components are omitted.","properties":{"zip":{"type":"string","description":"Postal/ZIP code (CEP in Brazil)"},"street":{"type":"string","description":"Street name"},"number":{"type":"string","description":"Street number"},"complement":{"type":"string","description":"Address complement (apartment, suite, block)"},"neighborhood":{"type":"string","description":"Neighborhood/district"},"city":{"type":"string","description":"City name"},"state":{"type":"string","description":"State/province (UF in Brazil)"},"country":{"type":"string","description":"Country of the postal address"}}},"billing_address":{"type":"object","description":"Optional billing address override of the contact. An empty object means billing uses the principal address.","properties":{"zip":{"type":"string","description":"Postal/ZIP code (CEP in Brazil)"},"street":{"type":"string","description":"Street name"},"number":{"type":"string","description":"Street number"},"complement":{"type":"string","description":"Address complement (apartment, suite, block)"},"neighborhood":{"type":"string","description":"Neighborhood/district"},"city":{"type":"string","description":"City name"},"state":{"type":"string","description":"State/province (UF in Brazil)"},"country":{"type":"string","description":"Country of the postal address"}}},"thumbnail":{"type":"string"},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"last_activity_at":{"type":"integer"},"created_at":{"type":"integer"},"field_visibility":{"type":"string","enum":["visible","masked","hidden"],"description":"Per-field visibility resolved from the current access role's field_permissions (FieldVisibilityHelper). `visible` renders the real value, `masked` an obfuscated one, `hidden` omits the key entirely."},"contact_inboxes":{"type":"array","items":{"type":"object","properties":{"source_id":{"type":"integer"},"logical_inbox_id":{"type":"integer"},"inbox":{"type":"object","properties":{"id":{"type":"integer"},"avatar_url":{"type":"string"},"channel_id":{"type":"integer"},"name":{"type":"string"},"channel_type":{"type":"string","enum":["Channel::Api","Channel::Email","Channel::FacebookPage","Channel::Instagram","Channel::Line","Channel::Sms","Channel::Telegram","Channel::Tiktok","Channel::TwilioSms","Channel::TwitterProfile","Channel::WebWidget","Channel::Whatsapp"],"description":"The inbox channel class — identifies which messaging channel backs the inbox."},"provider":{"type":"string","enum":["default","whatsapp_cloud","whatsapp_web","google","microsoft"],"description":"Messaging provider backing the inbox channel (whatsapp_web is the WazMeow gateway; email uses google/microsoft; default otherwise)."}}}}}},"consent_state":{"type":"object","additionalProperties":{"type":"string","enum":["granted","denied","pending"],"description":"Consent state in force for this delivery channel."},"description":"LGPD consent state keyed by delivery channel (\"all\" is the account-wide scope that shadows the per-channel ones). A channel the contact never declared on is absent rather than pending, since the set of channels an account may use is open. Present only on single-contact payloads. Signals only — it never blocks a send."}}}}}},"example":{"meta":{"count":5,"current_page":"sample current page"},"payload":[{"additional_attributes":{},"availability_status":"online","email":"agent@example.com","id":1,"name":"Sample Name","phone_number":"+5511999998888","blocked":"sample blocked","contact_type":"visitor","identifier":"sample-identifier","company_id":1,"organization_id":1,"referred_by_affiliate_id":1,"referred_by_affiliate_name":"sample referred by affiliate name","owner_id":1,"legal_type":"individual","tax_id":"sample tax id","tax_id_type":"br_cpf","country":1,"address":{"zip":"sample zip","street":"sample street","number":"sample number","complement":"sample complement","neighborhood":"sample neighborhood","city":"São Paulo","state":"active","country":"BR"},"billing_address":{"zip":"sample zip","street":"sample street","number":"sample number","complement":"sample complement","neighborhood":"sample neighborhood","city":"São Paulo","state":"active","country":"BR"},"thumbnail":"sample thumbnail","custom_attributes":{},"last_activity_at":1,"created_at":1,"field_visibility":"visible","contact_inboxes":[{"source_id":1,"logical_inbox_id":1,"inbox":{"id":1,"avatar_url":"https://example.com/resource","channel_id":1,"name":"Sample Name","channel_type":"Channel::Api","provider":"default"}}],"consent_state":{}}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/contacts/glance":{"get":{"tags":["Contacts"],"operationId":"auto_get_api_v1_accounts_account_id_contacts_glance","summary":"Glance contacts","description":"Performs the glance operation on the targeted contact resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"payload":{"type":"object","additionalProperties":true,"description":"Free-form object."}}},{"type":"object","properties":{"payload":{"type":"string"}}}]},"example":{"payload":{}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"contact_ids","in":"query","required":true,"description":"Contacts to fetch glance signals for. Accepts a repeated array parameter or a single comma-separated string. Without it the response payload is always empty.","schema":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"integer"}}]},"example":"12,34,56"}]}},"/api/v1/accounts/{account_id}/contacts/import":{"post":{"tags":["Contacts"],"operationId":"auto_post_api_v1_accounts_account_id_contacts_import","summary":"Import contacts from a CSV file","description":"Uploads a CSV of contacts and registers it as an import. The file is parsed and applied asynchronously, so a successful call answers `200 OK` with an EMPTY body and reports NOTHING about the rows — poll the contacts, or the account's imports, to observe the outcome. The request must be sent as a multipart form upload.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"File accepted and queued for import. Empty body."},"401":{"description":"Unauthorized"},"404":{"description":"No account matches `account_id`."},"422":{"description":"No file was supplied in the request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable reason, localized to the account language."}}},"example":{"error":"File is blank"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["import_file"],"properties":{"import_file":{"type":"string","format":"binary","description":"The CSV file to import, one contact per row with a header line."}}}}}}}},"/api/v1/accounts/{account_id}/contacts/export":{"post":{"tags":["Contacts"],"operationId":"auto_post_api_v1_accounts_account_id_contacts_export","summary":"Export contacts","description":"Performs the export operation on the targeted contact resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Export accepted. The CSV is produced asynchronously by a background job and e-mailed to the requesting user when ready, so the response carries NO body — only a `Message` header with the confirmation text the dashboard surfaces as a toast.","headers":{"Message":{"description":"Human-readable confirmation, localized to the account language","schema":{"type":"string","example":"We will notify you once contacts export file is ready to view."}}}},"401":{"description":"Authentication or authorization failure — the caller is not a member of the account, the account is suspended, or the effective role lacks the contact-export grant (administrators always have it). Returned as `{ error: \u003cmessage\u003e }`.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"You are not authorized to do this action"}}},"example":{"error":"You are not authorized to do this action"}}}},"404":{"description":"No account matches `account_id`.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Resource could not be found"}}},"example":{"error":"Resource could not be found"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"column_names":{"type":"array","description":"Contact columns to include in the exported CSV (all columns when omitted)","items":{"type":"string"},"example":["name","email","phone_number"]},"label":{"type":"string","description":"Restrict the export to contacts carrying this label","example":"vip"},"payload":{"type":"array","description":"Advanced contact filter groups (same shape as the contacts filter endpoint)","items":{"type":"object","additionalProperties":true},"example":[{"attribute_key":"email","filter_operator":"is_present","query_operator":null}]}}},"example":{"column_names":["name","email","phone_number"],"label":"vip","payload":[{"attribute_key":"email","filter_operator":"is_present","query_operator":null}]}}}}}},"/api/v1/accounts/{account_id}/contacts/{id}/destroy_custom_attributes":{"post":{"tags":["Contacts"],"operationId":"auto_post_api_v1_accounts_account_id_contacts_id_destroy_custom_attributes","summary":"Destroy custom attributes contacts","description":"Performs the destroy custom attributes operation on the targeted contact resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"additional_attributes":{"type":"object","additionalProperties":true,"description":"Channel- and source-specific metadata for this record (e.g. browser info, referer, social profile identifiers). The key set depends on the originating channel."},"availability_status":{"type":"string","enum":["online","offline","busy"],"description":"Realtime availability. Contacts report online/offline (presence-based); agents/users additionally report busy (their configured availability)."},"email":{"type":"string","format":"email"},"id":{"type":"integer"},"name":{"type":"string"},"phone_number":{"type":"string"},"blocked":{"type":"string"},"contact_type":{"type":"string","enum":["visitor","lead","customer"]},"identifier":{"type":"string"},"company_id":{"type":"integer"},"organization_id":{"type":"integer"},"referred_by_affiliate_id":{"type":"integer"},"referred_by_affiliate_name":{"type":["string","null"]},"owner_id":{"type":"integer"},"legal_type":{"type":"string","enum":["individual","business"]},"tax_id":{"type":"string","description":"The fiscal identifier (CPF/CNPJ/EIN/VAT); validated and stored encrypted on write. Read payloads return the real value to an authenticated human agent, and a type-aware mask (e.g. \"***.***.***-09\") when a role field rule masks it or the caller is a bot; a hidden rule omits the key. Webhooks, exports and message variables always carry the masked form."},"tax_id_type":{"type":"string","enum":["br_cpf","br_cnpj","us_ein","eu_vat","uk_vat","generic"],"description":"The fiscal identifier scheme used to validate and mask the tax_id (CPF/CNPJ check digits, EIN, EU/UK VAT or a generic fallback)."},"country":{"type":"integer"},"address":{"type":"object","description":"Native postal address of the contact. Blank components are omitted.","properties":{"zip":{"type":"string","description":"Postal/ZIP code (CEP in Brazil)"},"street":{"type":"string","description":"Street name"},"number":{"type":"string","description":"Street number"},"complement":{"type":"string","description":"Address complement (apartment, suite, block)"},"neighborhood":{"type":"string","description":"Neighborhood/district"},"city":{"type":"string","description":"City name"},"state":{"type":"string","description":"State/province (UF in Brazil)"},"country":{"type":"string","description":"Country of the postal address"}}},"billing_address":{"type":"object","description":"Optional billing address override of the contact. An empty object means billing uses the principal address.","properties":{"zip":{"type":"string","description":"Postal/ZIP code (CEP in Brazil)"},"street":{"type":"string","description":"Street name"},"number":{"type":"string","description":"Street number"},"complement":{"type":"string","description":"Address complement (apartment, suite, block)"},"neighborhood":{"type":"string","description":"Neighborhood/district"},"city":{"type":"string","description":"City name"},"state":{"type":"string","description":"State/province (UF in Brazil)"},"country":{"type":"string","description":"Country of the postal address"}}},"thumbnail":{"type":"string"},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"last_activity_at":{"type":"integer"},"created_at":{"type":"integer"},"field_visibility":{"type":"string","enum":["visible","masked","hidden"],"description":"Per-field visibility resolved from the current access role's field_permissions (FieldVisibilityHelper). `visible` renders the real value, `masked` an obfuscated one, `hidden` omits the key entirely."},"contact_inboxes":{"type":"array","items":{"type":"object","properties":{"source_id":{"type":"integer"},"logical_inbox_id":{"type":"integer"},"inbox":{"type":"object","properties":{"id":{"type":"integer"},"avatar_url":{"type":"string"},"channel_id":{"type":"integer"},"name":{"type":"string"},"channel_type":{"type":"string","enum":["Channel::Api","Channel::Email","Channel::FacebookPage","Channel::Instagram","Channel::Line","Channel::Sms","Channel::Telegram","Channel::Tiktok","Channel::TwilioSms","Channel::TwitterProfile","Channel::WebWidget","Channel::Whatsapp"],"description":"The inbox channel class — identifies which messaging channel backs the inbox."},"provider":{"type":"string","enum":["default","whatsapp_cloud","whatsapp_web","google","microsoft"],"description":"Messaging provider backing the inbox channel (whatsapp_web is the WazMeow gateway; email uses google/microsoft; default otherwise)."}}}}}},"consent_state":{"type":"object","additionalProperties":{"type":"string","enum":["granted","denied","pending"],"description":"Consent state in force for this delivery channel."},"description":"LGPD consent state keyed by delivery channel (\"all\" is the account-wide scope that shadows the per-channel ones). A channel the contact never declared on is absent rather than pending, since the set of channels an account may use is open. Present only on single-contact payloads. Signals only — it never blocks a send."}}}}},"example":{"payload":{"additional_attributes":{},"availability_status":"online","email":"agent@example.com","id":1,"name":"Sample Name","phone_number":"+5511999998888","blocked":"sample blocked","contact_type":"visitor","identifier":"sample-identifier","company_id":1,"organization_id":1,"referred_by_affiliate_id":1,"referred_by_affiliate_name":"sample referred by affiliate name","owner_id":1,"legal_type":"individual","tax_id":"sample tax id","tax_id_type":"br_cpf","country":1,"address":{"zip":"sample zip","street":"sample street","number":"sample number","complement":"sample complement","neighborhood":"sample neighborhood","city":"São Paulo","state":"active","country":"BR"},"billing_address":{"zip":"sample zip","street":"sample street","number":"sample number","complement":"sample complement","neighborhood":"sample neighborhood","city":"São Paulo","state":"active","country":"BR"},"thumbnail":"sample thumbnail","custom_attributes":{},"last_activity_at":1,"created_at":1,"field_visibility":"visible","contact_inboxes":[{"source_id":1,"logical_inbox_id":1,"inbox":{"id":1,"avatar_url":"https://example.com/resource","channel_id":1,"name":"Sample Name","channel_type":"Channel::Api","provider":"default"}}],"consent_state":{}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."}}},"example":{"custom_attributes":{}}}}}}},"/api/v1/accounts/{account_id}/contacts/{id}/avatar":{"delete":{"tags":["Contacts"],"operationId":"auto_delete_api_v1_accounts_account_id_contacts_id_avatar","summary":"Avatar contacts","description":"Performs the avatar operation on the targeted contact resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"additional_attributes":{"type":"object","additionalProperties":true,"description":"Channel- and source-specific metadata for this record (e.g. browser info, referer, social profile identifiers). The key set depends on the originating channel."},"availability_status":{"type":"string","enum":["online","offline","busy"],"description":"Realtime availability. Contacts report online/offline (presence-based); agents/users additionally report busy (their configured availability)."},"email":{"type":"string","format":"email"},"id":{"type":"integer"},"name":{"type":"string"},"phone_number":{"type":"string"},"blocked":{"type":"string"},"contact_type":{"type":"string","enum":["visitor","lead","customer"]},"identifier":{"type":"string"},"company_id":{"type":"integer"},"organization_id":{"type":"integer"},"referred_by_affiliate_id":{"type":"integer"},"referred_by_affiliate_name":{"type":["string","null"]},"owner_id":{"type":"integer"},"legal_type":{"type":"string","enum":["individual","business"]},"tax_id":{"type":"string","description":"The fiscal identifier (CPF/CNPJ/EIN/VAT); validated and stored encrypted on write. Read payloads return the real value to an authenticated human agent, and a type-aware mask (e.g. \"***.***.***-09\") when a role field rule masks it or the caller is a bot; a hidden rule omits the key. Webhooks, exports and message variables always carry the masked form."},"tax_id_type":{"type":"string","enum":["br_cpf","br_cnpj","us_ein","eu_vat","uk_vat","generic"],"description":"The fiscal identifier scheme used to validate and mask the tax_id (CPF/CNPJ check digits, EIN, EU/UK VAT or a generic fallback)."},"country":{"type":"integer"},"address":{"type":"object","description":"Native postal address of the contact. Blank components are omitted.","properties":{"zip":{"type":"string","description":"Postal/ZIP code (CEP in Brazil)"},"street":{"type":"string","description":"Street name"},"number":{"type":"string","description":"Street number"},"complement":{"type":"string","description":"Address complement (apartment, suite, block)"},"neighborhood":{"type":"string","description":"Neighborhood/district"},"city":{"type":"string","description":"City name"},"state":{"type":"string","description":"State/province (UF in Brazil)"},"country":{"type":"string","description":"Country of the postal address"}}},"billing_address":{"type":"object","description":"Optional billing address override of the contact. An empty object means billing uses the principal address.","properties":{"zip":{"type":"string","description":"Postal/ZIP code (CEP in Brazil)"},"street":{"type":"string","description":"Street name"},"number":{"type":"string","description":"Street number"},"complement":{"type":"string","description":"Address complement (apartment, suite, block)"},"neighborhood":{"type":"string","description":"Neighborhood/district"},"city":{"type":"string","description":"City name"},"state":{"type":"string","description":"State/province (UF in Brazil)"},"country":{"type":"string","description":"Country of the postal address"}}},"thumbnail":{"type":"string"},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"last_activity_at":{"type":"integer"},"created_at":{"type":"integer"},"field_visibility":{"type":"string","enum":["visible","masked","hidden"],"description":"Per-field visibility resolved from the current access role's field_permissions (FieldVisibilityHelper). `visible` renders the real value, `masked` an obfuscated one, `hidden` omits the key entirely."},"contact_inboxes":{"type":"array","items":{"type":"object","properties":{"source_id":{"type":"integer"},"logical_inbox_id":{"type":"integer"},"inbox":{"type":"object","properties":{"id":{"type":"integer"},"avatar_url":{"type":"string"},"channel_id":{"type":"integer"},"name":{"type":"string"},"channel_type":{"type":"string","enum":["Channel::Api","Channel::Email","Channel::FacebookPage","Channel::Instagram","Channel::Line","Channel::Sms","Channel::Telegram","Channel::Tiktok","Channel::TwilioSms","Channel::TwitterProfile","Channel::WebWidget","Channel::Whatsapp"],"description":"The inbox channel class — identifies which messaging channel backs the inbox."},"provider":{"type":"string","enum":["default","whatsapp_cloud","whatsapp_web","google","microsoft"],"description":"Messaging provider backing the inbox channel (whatsapp_web is the WazMeow gateway; email uses google/microsoft; default otherwise)."}}}}}},"consent_state":{"type":"object","additionalProperties":{"type":"string","enum":["granted","denied","pending"],"description":"Consent state in force for this delivery channel."},"description":"LGPD consent state keyed by delivery channel (\"all\" is the account-wide scope that shadows the per-channel ones). A channel the contact never declared on is absent rather than pending, since the set of channels an account may use is open. Present only on single-contact payloads. Signals only — it never blocks a send."}}}}},"example":{"payload":{"additional_attributes":{},"availability_status":"online","email":"agent@example.com","id":1,"name":"Sample Name","phone_number":"+5511999998888","blocked":"sample blocked","contact_type":"visitor","identifier":"sample-identifier","company_id":1,"organization_id":1,"referred_by_affiliate_id":1,"referred_by_affiliate_name":"sample referred by affiliate name","owner_id":1,"legal_type":"individual","tax_id":"sample tax id","tax_id_type":"br_cpf","country":1,"address":{"zip":"sample zip","street":"sample street","number":"sample number","complement":"sample complement","neighborhood":"sample neighborhood","city":"São Paulo","state":"active","country":"BR"},"billing_address":{"zip":"sample zip","street":"sample street","number":"sample number","complement":"sample complement","neighborhood":"sample neighborhood","city":"São Paulo","state":"active","country":"BR"},"thumbnail":"sample thumbnail","custom_attributes":{},"last_activity_at":1,"created_at":1,"field_visibility":"visible","contact_inboxes":[{"source_id":1,"logical_inbox_id":1,"inbox":{"id":1,"avatar_url":"https://example.com/resource","channel_id":1,"name":"Sample Name","channel_type":"Channel::Api","provider":"default"}}],"consent_state":{}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/contacts/{contact_id}/notes":{"get":{"tags":["Contacts"],"operationId":"auto_get_api_v1_accounts_account_id_contacts_contact_id_notes","summary":"List notes","description":"Returns the list of notes visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"content":{"type":"string"},"account_id":{"type":"integer"},"contact_id":{"type":"integer"},"user":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":["integer","null"]},"account_user_id":{"type":["integer","null"]},"availability_status":{"type":"string","enum":["online","offline","busy"],"description":"Realtime availability. Contacts report online/offline (presence-based); agents/users additionally report busy (their configured availability)."},"auto_offline":{"type":"boolean"},"confirmed":{"type":"boolean"},"email":{"type":"string","format":"email"},"provider":{"type":"string","enum":["email","google_oauth2","saml"],"description":"Authentication provider the user signed up through."},"available_name":{"type":"string"},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"name":{"type":"string"},"role":{"type":"string","enum":["agent","administrator"]},"outbound_agent_name_header_policy":{"type":["string","null"]},"thumbnail":{"type":"string"},"custom_role_id":{"type":["integer","null"]},"access_role_id":{"type":["integer","null"]}}},"created_at":{"type":"integer"},"updated_at":{"type":"integer"}}}},"example":[{"id":1,"content":"Sample content text.","account_id":1,"contact_id":1,"user":{"id":1,"account_id":1,"account_user_id":1,"availability_status":"online","auto_offline":true,"confirmed":true,"email":"agent@example.com","provider":"email","available_name":"sample available name","custom_attributes":{},"name":"Sample Name","role":"agent","outbound_agent_name_header_policy":"sample outbound agent name header policy","thumbnail":"sample thumbnail","custom_role_id":1,"access_role_id":1},"created_at":1,"updated_at":1}]}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"contact_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."}]},"post":{"tags":["Contacts"],"operationId":"auto_post_api_v1_accounts_account_id_contacts_contact_id_notes","summary":"Create notes","description":"Creates a new note from the request payload. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"content":{"type":"string"},"account_id":{"type":"integer"},"contact_id":{"type":"integer"},"user":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":["integer","null"]},"account_user_id":{"type":["integer","null"]},"availability_status":{"type":"string","enum":["online","offline","busy"],"description":"Realtime availability. Contacts report online/offline (presence-based); agents/users additionally report busy (their configured availability)."},"auto_offline":{"type":"boolean"},"confirmed":{"type":"boolean"},"email":{"type":"string","format":"email"},"provider":{"type":"string","enum":["email","google_oauth2","saml"],"description":"Authentication provider the user signed up through."},"available_name":{"type":"string"},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"name":{"type":"string"},"role":{"type":"string","enum":["agent","administrator"]},"outbound_agent_name_header_policy":{"type":["string","null"]},"thumbnail":{"type":"string"},"custom_role_id":{"type":["integer","null"]},"access_role_id":{"type":["integer","null"]}}},"created_at":{"type":"integer"},"updated_at":{"type":"integer"}}},"example":{"id":1,"content":"Sample content text.","account_id":1,"contact_id":1,"user":{"id":1,"account_id":1,"account_user_id":1,"availability_status":"online","auto_offline":true,"confirmed":true,"email":"agent@example.com","provider":"email","available_name":"sample available name","custom_attributes":{},"name":"Sample Name","role":"agent","outbound_agent_name_header_policy":"sample outbound agent name header policy","thumbnail":"sample thumbnail","custom_role_id":1,"access_role_id":1},"created_at":1,"updated_at":1}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"contact_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"note":{"type":"object","properties":{"content":{"type":"string"}},"required":["content"]}},"required":["note"]},"example":{"note":{"content":"Sample content text."}}}}}}},"/api/v1/accounts/{account_id}/contacts/{contact_id}/notes/{id}":{"get":{"tags":["Contacts"],"operationId":"auto_get_api_v1_accounts_account_id_contacts_contact_id_notes_id","summary":"Get notes","description":"Returns the note identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"content":{"type":"string"},"account_id":{"type":"integer"},"contact_id":{"type":"integer"},"user":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":["integer","null"]},"account_user_id":{"type":["integer","null"]},"availability_status":{"type":"string","enum":["online","offline","busy"],"description":"Realtime availability. Contacts report online/offline (presence-based); agents/users additionally report busy (their configured availability)."},"auto_offline":{"type":"boolean"},"confirmed":{"type":"boolean"},"email":{"type":"string","format":"email"},"provider":{"type":"string","enum":["email","google_oauth2","saml"],"description":"Authentication provider the user signed up through."},"available_name":{"type":"string"},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"name":{"type":"string"},"role":{"type":"string","enum":["agent","administrator"]},"outbound_agent_name_header_policy":{"type":["string","null"]},"thumbnail":{"type":"string"},"custom_role_id":{"type":["integer","null"]},"access_role_id":{"type":["integer","null"]}}},"created_at":{"type":"integer"},"updated_at":{"type":"integer"}}},"example":{"id":1,"content":"Sample content text.","account_id":1,"contact_id":1,"user":{"id":1,"account_id":1,"account_user_id":1,"availability_status":"online","auto_offline":true,"confirmed":true,"email":"agent@example.com","provider":"email","available_name":"sample available name","custom_attributes":{},"name":"Sample Name","role":"agent","outbound_agent_name_header_policy":"sample outbound agent name header policy","thumbnail":"sample thumbnail","custom_role_id":1,"access_role_id":1},"created_at":1,"updated_at":1}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"contact_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]},"patch":{"tags":["Contacts"],"operationId":"auto_patch_api_v1_accounts_account_id_contacts_contact_id_notes_id","summary":"Update notes","description":"Updates the note identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"content":{"type":"string"},"account_id":{"type":"integer"},"contact_id":{"type":"integer"},"user":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":["integer","null"]},"account_user_id":{"type":["integer","null"]},"availability_status":{"type":"string","enum":["online","offline","busy"],"description":"Realtime availability. Contacts report online/offline (presence-based); agents/users additionally report busy (their configured availability)."},"auto_offline":{"type":"boolean"},"confirmed":{"type":"boolean"},"email":{"type":"string","format":"email"},"provider":{"type":"string","enum":["email","google_oauth2","saml"],"description":"Authentication provider the user signed up through."},"available_name":{"type":"string"},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"name":{"type":"string"},"role":{"type":"string","enum":["agent","administrator"]},"outbound_agent_name_header_policy":{"type":["string","null"]},"thumbnail":{"type":"string"},"custom_role_id":{"type":["integer","null"]},"access_role_id":{"type":["integer","null"]}}},"created_at":{"type":"integer"},"updated_at":{"type":"integer"}}},"example":{"id":1,"content":"Sample content text.","account_id":1,"contact_id":1,"user":{"id":1,"account_id":1,"account_user_id":1,"availability_status":"online","auto_offline":true,"confirmed":true,"email":"agent@example.com","provider":"email","available_name":"sample available name","custom_attributes":{},"name":"Sample Name","role":"agent","outbound_agent_name_header_policy":"sample outbound agent name header policy","thumbnail":"sample thumbnail","custom_role_id":1,"access_role_id":1},"created_at":1,"updated_at":1}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"contact_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"note":{"type":"object","properties":{"content":{"type":"string"}}}},"required":["note"]},"example":{"note":{"content":"Sample content text."}}}}}},"put":{"tags":["Contacts"],"operationId":"auto_put_api_v1_accounts_account_id_contacts_contact_id_notes_id","summary":"Update notes","description":"Updates the note identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"content":{"type":"string"},"account_id":{"type":"integer"},"contact_id":{"type":"integer"},"user":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":["integer","null"]},"account_user_id":{"type":["integer","null"]},"availability_status":{"type":"string","enum":["online","offline","busy"],"description":"Realtime availability. Contacts report online/offline (presence-based); agents/users additionally report busy (their configured availability)."},"auto_offline":{"type":"boolean"},"confirmed":{"type":"boolean"},"email":{"type":"string","format":"email"},"provider":{"type":"string","enum":["email","google_oauth2","saml"],"description":"Authentication provider the user signed up through."},"available_name":{"type":"string"},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"name":{"type":"string"},"role":{"type":"string","enum":["agent","administrator"]},"outbound_agent_name_header_policy":{"type":["string","null"]},"thumbnail":{"type":"string"},"custom_role_id":{"type":["integer","null"]},"access_role_id":{"type":["integer","null"]}}},"created_at":{"type":"integer"},"updated_at":{"type":"integer"}}},"example":{"id":1,"content":"Sample content text.","account_id":1,"contact_id":1,"user":{"id":1,"account_id":1,"account_user_id":1,"availability_status":"online","auto_offline":true,"confirmed":true,"email":"agent@example.com","provider":"email","available_name":"sample available name","custom_attributes":{},"name":"Sample Name","role":"agent","outbound_agent_name_header_policy":"sample outbound agent name header policy","thumbnail":"sample thumbnail","custom_role_id":1,"access_role_id":1},"created_at":1,"updated_at":1}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"contact_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"note":{"type":"object","properties":{"content":{"type":"string"}}}},"required":["note"]},"example":{"note":{"content":"Sample content text."}}}}}},"delete":{"tags":["Contacts"],"operationId":"auto_delete_api_v1_accounts_account_id_contacts_contact_id_notes_id","summary":"Delete notes","description":"Deletes the note identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Success (no content)"},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"contact_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/contacts/{contact_id}/organization_memberships":{"get":{"tags":["Contacts"],"operationId":"auto_get_api_v1_accounts_account_id_contacts_contact_id_organization_memberships","summary":"List organization memberships","description":"Returns the list of organization memberships visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"organization_id":{"type":"integer"},"contact_id":{"type":"integer"},"role":{"type":"string","enum":["member","captain","admin"]},"title":{"type":"string"},"primary":{"type":"string"},"started_on":{"type":"string"},"ended_on":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"organization":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"legal_name":{"type":"string"},"domain":{"type":"string"},"lifecycle_stage":{"type":"string"},"avatar_url":{"type":"string"},"tax_id":{"type":"string","description":"The fiscal identifier (CPF/CNPJ/EIN/VAT); validated and stored encrypted on write. Read payloads return the real value to an authenticated human agent, and a type-aware mask (e.g. \"***.***.***-09\") when a role field rule masks it or the caller is a bot; a hidden rule omits the key. Webhooks, exports and message variables always carry the masked form."}}}}}}}},"example":{"payload":[{"id":1,"account_id":1,"organization_id":1,"contact_id":1,"role":"member","title":"Sample title","primary":"sample primary","started_on":"sample started on","ended_on":"sample ended on","created_at":"2026-01-15T10:30:00.000Z","organization":{"id":1,"name":"Sample Name","legal_name":"sample legal name","domain":"example.com","lifecycle_stage":"sample lifecycle stage","avatar_url":"https://example.com/resource","tax_id":"sample tax id"}}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"contact_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."}]}},"/api/v1/accounts/{account_id}/contacts/{contact_id}/whatsapp_identity_reconciliations":{"get":{"tags":["Contacts"],"operationId":"auto_get_api_v1_accounts_account_id_contacts_contact_id_whatsapp_identity_reconciliations","summary":"List the contact's pending WhatsApp identity conflicts","description":"Lists identities WhatsApp reported for this contact that could not be linked without merging two contacts: a changed phone number or business-scoped user ID (BSUID), or a phone number the customer shared. Nothing is merged automatically. Each conflict is recorded on every contact involved, so it appears here and on the other contact. Merging the contacts resolves the entry, and an agent who may edit the contact can dismiss it. The newest ten entries are kept. Requires permission to view the contact.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Pending entries of the contact, oldest first. Empty when there is nothing to reconcile.","content":{"application/json":{"schema":{"type":"object","required":["payload"],"properties":{"payload":{"type":"array","items":{"type":"object","required":["id","reason","change_type","inbox_id","identifiers","other_contact_ids","detected_at"],"properties":{"id":{"type":"string","description":"Stable identifier of the entry, used to dismiss it. It does not change when WhatsApp reports the same conflict again."},"reason":{"type":"string","enum":["identity_owned_by_another_contact","identity_claimed_by_another_contact","identity_reconciliation_write_pending","identity_ambiguous","shared_phone_differs"],"description":"identity_owned_by_another_contact - the identity WhatsApp gave this contact already belongs to the contacts in other_contact_ids. identity_claimed_by_another_contact - WhatsApp gave the contacts in other_contact_ids an identity this contact holds. identity_reconciliation_write_pending - a transient failure prevented recording the bilateral conflict; this entry remains visible for repair and a redelivery retries the bilateral record. identity_ambiguous - the previous identities WhatsApp reported belong to more than one contact. shared_phone_differs - the customer shared a phone number different from the one already saved on this contact."},"change_type":{"type":"string","enum":["user_changed_number","user_changed_user_id","contact_request","web_self_contact","inbound_identifiers"],"description":"What WhatsApp reported. user_changed_number and user_changed_user_id are WhatsApp Cloud system messages; contact_request is a phone shared with the request-contact-information button; web_self_contact is the customer's own contact card shared on WhatsApp Web; inbound_identifiers is one delivery naming several identifiers of the same person (phone, business-scoped user ID, parent ID), one of which already belongs to another contact."},"inbox_id":{"type":"integer","description":"Inbox that received the report."},"identifiers":{"type":"array","items":{"type":"string"},"description":"Identities in conflict, such as a phone number in digits or a BSUID. The literal value phone_number means the conflict is on the contact's saved phone number."},"other_contact_ids":{"type":"array","items":{"type":"integer"},"description":"The other contacts involved. Empty for shared_phone_differs."},"detected_at":{"type":"string","format":"date-time","description":"When the conflict was last reported (UTC)."}}}}}},"example":{"payload":[{"id":"3f9c1a7d2b4e6f80","reason":"identity_owned_by_another_contact","change_type":"contact_request","inbox_id":12,"identifiers":["5511988887777"],"other_contact_ids":[4521],"detected_at":"2026-10-01T15:20:44Z"},{"id":"8a2d4c6e1f3b5a79","reason":"shared_phone_differs","change_type":"web_self_contact","inbox_id":13,"identifiers":["5511977776666"],"other_contact_ids":[],"detected_at":"2026-10-01T15:31:02Z"}]}}}},"401":{"description":"Authentication is missing or invalid, or the user may not view this contact."},"404":{"description":"The contact does not belong to the account."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"contact_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."}]}},"/api/v1/accounts/{account_id}/contacts/{contact_id}/whatsapp_identity_reconciliations/{id}":{"delete":{"tags":["Contacts"],"operationId":"auto_delete_api_v1_accounts_account_id_contacts_contact_id_whatsapp_identity_reconciliations_id","summary":"Dismiss a pending WhatsApp identity conflict of the contact","description":"Removes one pending entry from this contact once an agent has handled it. Nothing is merged and no other contact changes, including the other side of the same conflict. The call is idempotent: an entry that no longer exists (already dismissed, or resolved by a merge) also answers 204. The id is only looked up among this contact's entries. Requires permission to edit the contact.","security":[{"userApiKey":[]}],"responses":{"204":{"description":"The entry is no longer pending on this contact."},"401":{"description":"Authentication is missing or invalid, or the user may not edit this contact."},"404":{"description":"The contact does not belong to the account."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"contact_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Entry id returned by the list operation.","schema":{"type":"string"},"example":"3f9c1a7d2b4e6f80"}]}},"/api/v1/accounts/{account_id}/contacts/{contact_id}/attachments":{"get":{"tags":["Contacts"],"operationId":"auto_get_api_v1_accounts_account_id_contacts_contact_id_attachments","summary":"List attachments","description":"Returns the list of attachments visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"meta":{"type":"object","properties":{"total_count":{"type":"integer"}}},"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"message_id":{"type":"integer"},"thumb_url":{"type":"string"},"data_url":{"type":"string"},"playable_audio_url":{"type":"string"},"playable_video_url":{"type":"string"},"video_processing":{"type":"boolean","description":"True while a browser-playable video rendition is being inspected or prepared asynchronously."},"video_unavailable":{"type":"boolean","description":"True when no safe browser-playable video rendition could be prepared; the original file remains downloadable."},"file_size":{"type":"string"},"file_type":{"type":"string","enum":["image","audio","video","file","location","fallback","share","story_mention","contact","ig_reel","ig_post","ig_story","embed"],"description":"Kind of the message attachment."},"extension":{"type":"string"},"width":{"type":"string"},"height":{"type":"string"},"content_type":{"type":"string"},"media_status":{"type":"string","enum":["available","processing","unavailable","external"],"description":"Durable media state. `processing` means the provider bytes are being copied to installation storage; `available` is locally persisted; `external` is an intentional link-only attachment; `unavailable` has no usable bytes."},"media_readiness_revision":{"type":"string"},"provider_permalink":{"type":"string","description":"Validated HTTPS URL of the original Instagram post, Reel, or Story when Meta exposes it; omitted when unavailable."},"media_processing":{"type":"string"},"media_unavailable":{"type":"string"},"media_deleted":{"type":"string"},"created_at":{"type":"integer"},"sender":{"type":"string"},"conversation_id":{"type":"integer"}}}}}},"example":{"meta":{"total_count":5},"payload":[{"id":1,"message_id":1,"thumb_url":"https://example.com/resource","data_url":"https://example.com/resource","playable_audio_url":"https://example.com/resource","playable_video_url":"https://example.com/resource","video_processing":true,"video_unavailable":true,"file_size":"sample file size","file_type":"image","extension":"sample extension","width":"sample width","height":"sample height","content_type":"sample content type","media_status":"available","media_readiness_revision":"sample media readiness revision","provider_permalink":"sample provider permalink","media_processing":"sample media processing","media_unavailable":"sample media unavailable","media_deleted":"sample media deleted","created_at":1,"sender":"sample sender","conversation_id":1}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"contact_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."}]}},"/api/v1/accounts/{account_id}/contacts/{id}/call":{"post":{"tags":["Contacts"],"operationId":"auto_post_api_v1_accounts_account_id_contacts_id_call","summary":"Start a native Twilio voice call","description":"Requires native_twilio_voice, an assigned voice-enabled inbox, contact access and reconciled provider configuration. Returns the conversation display id and provider call identifiers. An optional conversation hint is reused only when it belongs to this contact and inbox and is open. The acting user must also be allowed to access that conversation. A request_id identifies one durable dial intention: replaying the same request returns its existing result, while conflicting reuse returns 409. An uncertain provider result never permits another dial, including requests with a different key. Reconcile through call_attempts before retrying an unconfirmed outcome.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Existing or newly confirmed call and its conversation identifiers.","content":{"application/json":{"schema":{"type":"object","required":["conversation_id","inbox_id","call_sid","conference_sid"],"properties":{"conversation_id":{"type":"integer","description":"Conversation display identifier."},"inbox_id":{"type":"integer"},"call_sid":{"type":"string","description":"Real Twilio Call SID; never a provisional identifier."},"conference_sid":{"type":"string","description":"Native conference friendly name."}}},"example":{"conversation_id":42,"inbox_id":7,"call_sid":"CAbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb","conference_sid":"conf_account_1_call_42"}}}},"401":{"description":"Authentication, contact/inbox access or the native voice capability is unavailable.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}},"example":{"error":"sample error"}}}},"404":{"description":"Account or resource not found"},"422":{"description":"A required inbox parameter is missing or request_id is invalid.","content":{"application/json":{"schema":{"oneOf":[{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}},{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["reconciliation_required","invalid_request_id","invalid_cursor","request_id_conflict","provider_receipt_conflict","call_result_unavailable","provider_rejected","configuration_changed","call_outcome_unknown","call_in_progress","call_projection_pending","call_storage_unavailable","invalid_provider_receipt","unexpected_provider_receipt"]},"attempt_id":{"type":"string","format":"uuid","description":"Durable attempt identifier","when preparation committed.":null}}}}}]},"example":{"error":"sample error"}}}},"409":{"description":"A request identity or provider receipt conflicts with its existing immutable intent.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["reconciliation_required","invalid_request_id","invalid_cursor","request_id_conflict","provider_receipt_conflict","call_result_unavailable","provider_rejected","configuration_changed","call_outcome_unknown","call_in_progress","call_projection_pending","call_storage_unavailable","invalid_provider_receipt","unexpected_provider_receipt"]},"attempt_id":{"type":"string","format":"uuid","description":"Durable attempt identifier","when preparation committed.":null}}}}},"example":{"error":{"code":"reconciliation_required","attempt_id":"550e8400-e29b-41d4-a716-446655440000"}}}}},"410":{"description":"The previously confirmed call was removed; replay cannot recreate it or dial again.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["reconciliation_required","invalid_request_id","invalid_cursor","request_id_conflict","provider_receipt_conflict","call_result_unavailable","provider_rejected","configuration_changed","call_outcome_unknown","call_in_progress","call_projection_pending","call_storage_unavailable","invalid_provider_receipt","unexpected_provider_receipt"]},"attempt_id":{"type":"string","format":"uuid","description":"Durable attempt identifier","when preparation committed.":null}}}}},"example":{"error":{"code":"reconciliation_required","attempt_id":"550e8400-e29b-41d4-a716-446655440000"}}}}},"502":{"description":"The provider rejected the dial, or configuration changed before the dial was issued.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["reconciliation_required","invalid_request_id","invalid_cursor","request_id_conflict","provider_receipt_conflict","call_result_unavailable","provider_rejected","configuration_changed","call_outcome_unknown","call_in_progress","call_projection_pending","call_storage_unavailable","invalid_provider_receipt","unexpected_provider_receipt"]},"attempt_id":{"type":"string","format":"uuid","description":"Durable attempt identifier","when preparation committed.":null}}}}},"example":{"error":{"code":"reconciliation_required","attempt_id":"550e8400-e29b-41d4-a716-446655440000"}}}}},"503":{"description":"Configuration, durable storage, local projection or provider outcome requires reconciliation. Do not blindly redial.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["reconciliation_required","invalid_request_id","invalid_cursor","request_id_conflict","provider_receipt_conflict","call_result_unavailable","provider_rejected","configuration_changed","call_outcome_unknown","call_in_progress","call_projection_pending","call_storage_unavailable","invalid_provider_receipt","unexpected_provider_receipt"]},"attempt_id":{"type":"string","format":"uuid","description":"Durable attempt identifier","when preparation committed.":null}}}}},"example":{"error":{"code":"call_outcome_unknown","attempt_id":"6e5b17c0-1df5-4f3a-9b68-61cc741d3c79"}}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["inbox_id"],"properties":{"inbox_id":{"type":"integer","description":"Voice inbox assigned to the acting agent."},"conversation_id":{"type":"integer","description":"Optional existing conversation display identifier."},"request_id":{"type":"string","minLength":1,"maxLength":128,"pattern":"^[a-zA-Z0-9_.:-]+$","description":"Optional stable identity for one dial intention; retain across transport retries."}}},"example":{"inbox_id":7,"conversation_id":42,"request_id":"dial-6e5b17c0-1df5-4f3a-9b68-61cc741d3c79"}}}}}},"/api/v1/accounts/{account_id}/contacts/{contact_id}/call_attempts":{"get":{"tags":["Contacts"],"operationId":"auto_get_api_v1_accounts_account_id_contacts_contact_id_call_attempts","summary":"List the acting user's recent native voice dial attempts","description":"Recovers attempts after a response or browser state is lost. Scoped to the current actor, account, contact and inbox; never lists another user's intents. Remains available after voice is disabled, subject to contact and inbox access. Reads durable local state without provider I/O.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Up to 25 newest attempts with an optional cursor for older rows.","content":{"application/json":{"schema":{"type":"object","required":["payload","next_cursor"],"properties":{"payload":{"type":"array","maxItems":25,"items":{"type":"object","required":["attempt_id","request_id","requested_conversation_id","state","call_status","created_at","updated_at","call"],"properties":{"attempt_id":{"type":"string","format":"uuid"},"request_id":{"type":["string","null"],"maxLength":128},"requested_conversation_id":{"type":["integer","null"],"description":"Original conversation display hint","retained to resume a prepared intent without changing its request identity.":null},"state":{"type":"string","enum":["prepared","issued","confirmed","rejected","unknown"]},"call_status":{"type":["string","null"],"enum":["ringing","in_progress","completed","no_answer","rejected","failed",null]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"call":{"oneOf":[{"type":"object","required":["conversation_id","inbox_id","call_sid","conference_sid"],"properties":{"conversation_id":{"type":"integer","description":"Conversation display identifier."},"inbox_id":{"type":"integer"},"call_sid":{"type":"string","description":"Real Twilio Call SID; never a provisional identifier."},"conference_sid":{"type":"string","description":"Native conference friendly name."}}},{"type":"null"}]}}}},"next_cursor":{"type":["integer","null"],"minimum":1}}},"example":{"payload":[{"attempt_id":"550e8400-e29b-41d4-a716-446655440000","request_id":"sample request id","requested_conversation_id":1,"state":"prepared","call_status":"ringing","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","call":{"conversation_id":1,"inbox_id":1,"call_sid":"sample call sid","conference_sid":"sample conference sid"}}],"next_cursor":1}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"422":{"description":"Missing inbox_id or invalid cursor.","content":{"application/json":{"schema":{"oneOf":[{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}},{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["reconciliation_required","invalid_request_id","invalid_cursor","request_id_conflict","provider_receipt_conflict","call_result_unavailable","provider_rejected","configuration_changed","call_outcome_unknown","call_in_progress","call_projection_pending","call_storage_unavailable","invalid_provider_receipt","unexpected_provider_receipt"]},"attempt_id":{"type":"string","format":"uuid","description":"Durable attempt identifier","when preparation committed.":null}}}}}]},"example":{"error":"sample error"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"contact_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"inbox_id","in":"query","required":true,"schema":{"type":"integer"},"description":"Inbox accessible to the acting user."},{"name":"before_id","in":"query","required":false,"schema":{"type":"integer","minimum":1},"description":"next_cursor returned by the preceding page."}]}},"/api/v1/accounts/{account_id}/contacts/{contact_id}/call_attempts/{attempt_id}":{"get":{"tags":["Contacts"],"operationId":"auto_get_api_v1_accounts_account_id_contacts_contact_id_call_attempts_attempt_id","summary":"Reconcile a native voice dial attempt","description":"Returns only the acting user's attempt for the supplied account, contact and inbox. Remains available after the voice feature is disabled, subject to contact and inbox access. May repair the local projection of an already confirmed provider receipt; never issues a call. Inspect call_status before joining: confirmed means receipt confirmed, not that the call is still active.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Durable attempt state and any materialized call.","content":{"application/json":{"schema":{"type":"object","required":["attempt_id","request_id","requested_conversation_id","state","call_status","created_at","updated_at","call"],"properties":{"attempt_id":{"type":"string","format":"uuid"},"request_id":{"type":["string","null"],"maxLength":128},"requested_conversation_id":{"type":["integer","null"],"description":"Original conversation display hint","retained to resume a prepared intent without changing its request identity.":null},"state":{"type":"string","enum":["prepared","issued","confirmed","rejected","unknown"]},"call_status":{"type":["string","null"],"enum":["ringing","in_progress","completed","no_answer","rejected","failed",null]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"call":{"oneOf":[{"type":"object","required":["conversation_id","inbox_id","call_sid","conference_sid"],"properties":{"conversation_id":{"type":"integer","description":"Conversation display identifier."},"inbox_id":{"type":"integer"},"call_sid":{"type":"string","description":"Real Twilio Call SID; never a provisional identifier."},"conference_sid":{"type":"string","description":"Native conference friendly name."}}},{"type":"null"}]}}},"example":{"attempt_id":"550e8400-e29b-41d4-a716-446655440000","request_id":"sample request id","requested_conversation_id":1,"state":"prepared","call_status":"ringing","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","call":{"conversation_id":1,"inbox_id":1,"call_sid":"sample call sid","conference_sid":"sample conference sid"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"410":{"description":"The original call was removed and cannot be recreated from the attempt.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["reconciliation_required","invalid_request_id","invalid_cursor","request_id_conflict","provider_receipt_conflict","call_result_unavailable","provider_rejected","configuration_changed","call_outcome_unknown","call_in_progress","call_projection_pending","call_storage_unavailable","invalid_provider_receipt","unexpected_provider_receipt"]},"attempt_id":{"type":"string","format":"uuid","description":"Durable attempt identifier","when preparation committed.":null}}}}},"example":{"error":{"code":"reconciliation_required","attempt_id":"550e8400-e29b-41d4-a716-446655440000"}}}}},"503":{"description":"Local projection or storage could not be reconciled yet.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["reconciliation_required","invalid_request_id","invalid_cursor","request_id_conflict","provider_receipt_conflict","call_result_unavailable","provider_rejected","configuration_changed","call_outcome_unknown","call_in_progress","call_projection_pending","call_storage_unavailable","invalid_provider_receipt","unexpected_provider_receipt"]},"attempt_id":{"type":"string","format":"uuid","description":"Durable attempt identifier","when preparation committed.":null}}}}},"example":{"error":{"code":"reconciliation_required","attempt_id":"550e8400-e29b-41d4-a716-446655440000"}}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"contact_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"attempt_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"inbox_id","in":"query","required":true,"schema":{"type":"integer"},"description":"Inbox belonging to the attempt and accessible to the acting user."}]}},"/api/v1/accounts/{account_id}/data_imports/validate_source":{"post":{"tags":["Data Imports"],"operationId":"auto_post_api_v1_accounts_account_id_data_imports_validate_source","summary":"Validate external help desk credentials","description":"Checks the selected provider credentials and import types without starting an import. Requires account authorization and data_import. Credentials are never returned.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"valid":{"type":"boolean","example":true},"totals":{"type":"string"}}},"example":{"valid":true,"totals":"sample totals"}}}},"401":{"description":"Authentication, account authorization or the data_import feature is unavailable.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}},"example":{"error":"You are not authorized to do this action"}}}},"404":{"description":"Account or resource not found"},"422":{"description":"Invalid source, import types or credentials, or the provider cannot be reached.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["valid","message"],"properties":{"valid":{"type":"boolean","enum":[false]},"message":{"type":"string"}}},"example":{"valid":false,"message":"Sample message text."}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"source_provider":{"type":"string","enum":["freshdesk","intercom"],"description":"External help desk to migrate from. Any other value is refused."},"access_token":{"type":"string"},"domain":{"type":"string"},"import_types":{"type":"array","items":{"type":"string"}}}},"example":{"name":"Sample Name","source_provider":"freshdesk","access_token":"sample-token","domain":"example.com","import_types":["sample import type"]}}}}}},"/api/v1/accounts/{account_id}/data_imports/{id}/start":{"post":{"tags":["Data Imports"],"operationId":"auto_post_api_v1_accounts_account_id_data_imports_id_start","summary":"Restart a failed or abandoned data import","description":"Returns a failed or abandoned import to the queue, reusing its stored credentials and resuming from the recorded cursor. Error entries are cleared apart from the skips already recorded, which are kept so a resumed run does not re-report them. The request is refused when the stored credential is no longer available. An import that is not restartable is returned unchanged, and when another import is already in progress that running import is returned instead of this one.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The current state of the import after the restart attempt.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer","description":"Identifier of the data import."},"name":{"type":["string","null"],"description":"Operator-supplied label. When omitted it defaults to the provider's standard import name, or to the data type and the current date on a legacy CSV contact upload."},"data_type":{"type":"string","enum":["contacts","freshdesk","intercom"],"description":"What this import carries. `contacts` is the legacy CSV contact upload; the other two are integration migrations named after their provider."},"source_type":{"type":["string","null"],"description":"How the records are obtained. Integration imports read them over the provider's API; a legacy CSV contact import leaves this blank.","enum":["api",null]},"source_provider":{"type":["string","null"],"description":"External help desk this import reads from. Blank on a legacy CSV contact import, which has no integration provider.","enum":["freshdesk","intercom",null]},"import_types":{"type":"array","description":"Which record families this run migrates. Defaults to both when the creation request omits the field.","items":{"type":"string","enum":["contacts","conversations"]}},"status":{"type":"string","enum":["pending","processing","completed","failed","completed_with_errors","abandoned"],"description":"Lifecycle state of the import run."},"stalled":{"type":"boolean","description":"True when an integration import is still pending or processing but has not advanced for fifteen minutes. Only a stalled run accepts a retry."},"total_records":{"type":["integer","null"],"description":"Every record this run accounted for — imported, skipped and errored. Written once the run finishes, so it stays blank while the import is still working."},"processed_records":{"type":["integer","null"],"description":"Records successfully written into this account. Written once the run finishes, so it stays blank while the import is still working."},"stats":{"type":"object","description":"Running counters for the integration import, rebuilt from the imported and skipped items after every page.","properties":{"contacts":{"type":"object","description":"Contact counters.","properties":{"imported":{"type":"integer","description":"Contacts written into this account."},"skipped":{"type":"integer","description":"Contacts deliberately not written, including ones a previous import already migrated."},"total":{"type":["integer","null"],"description":"Contact total reported by the provider — seeded when the credentials were validated and refreshed from every page the run walks. Absent when the provider does not report one."}}},"conversations":{"type":"object","description":"Conversation counters.","properties":{"imported":{"type":"integer","description":"Conversations written into this account."},"skipped":{"type":"integer","description":"Conversations deliberately not written."},"total":{"type":["integer","null"],"description":"Conversation total reported by the provider — seeded when the credentials were validated and refreshed from every page the run walks. Absent when the provider does not report one."}}},"messages":{"type":"object","description":"Message counters. Messages are discovered while walking conversations, so the total grows as the run progresses.","properties":{"imported":{"type":"integer","description":"Messages written into this account."},"skipped":{"type":"integer","description":"Messages deliberately not written, including ones with no importable text."},"total":{"type":["integer","null"],"description":"Messages seen so far across the conversations already walked."}}},"errors":{"type":"object","description":"Failure counter for the run.","properties":{"count":{"type":"integer","description":"Number of source objects that raised an error."}}}}},"cursor":{"type":"object","description":"Resume point per record family, so an interrupted run continues where it stopped instead of re-walking the provider from the beginning.","properties":{"contacts":{"type":"object","description":"Contact pagination state.","properties":{"starting_after":{"type":["string","null"],"description":"Provider page token to resume from. Blank once the family is fully walked."},"completed":{"type":"boolean","description":"True once the provider returned no further contact page."},"updated_at":{"type":"string","format":"date-time","description":"When this resume point was last written."}}},"conversations":{"type":"object","description":"Conversation pagination state.","properties":{"starting_after":{"type":["string","null"],"description":"Provider page token to resume from. Blank once the family is fully walked."},"completed":{"type":"boolean","description":"True once the provider returned no further conversation page."},"updated_at":{"type":"string","format":"date-time","description":"When this resume point was last written."}}}}},"created_at":{"type":"string","format":"date-time","description":"When the import was created."},"updated_at":{"type":"string","format":"date-time","description":"Last write to the import record. This is the timestamp the stalled check reads."},"started_at":{"type":["string","null"],"format":"date-time","description":"When the run began processing."},"completed_at":{"type":["string","null"],"format":"date-time","description":"When the run finished, with or without errors."},"abandoned_at":{"type":["string","null"],"format":"date-time","description":"When an operator abandoned the run."},"initiated_by":{"type":["object","null"],"description":"Agent who started the import. Blank when the record predates attribution or the agent was removed.","properties":{"id":{"type":"integer","description":"Identifier of the agent."},"name":{"type":"string","description":"Display name of the agent."},"email":{"type":"string","description":"Login e-mail of the agent."}}},"import_errors_count":{"type":"integer","description":"Total error entries for this import — the run-level failures and incomplete-conversation notices, not the per-object skip logs."},"skip_logs_count":{"type":"integer","description":"Total skip-log entries for this import, across every object kind."},"import_errors":{"type":"array","description":"Five most recent error entries, newest first. These are the run-level and completeness problems; per-object skips live in `skip_logs`.","items":{"type":"object","properties":{"id":{"type":"integer","description":"Identifier of the log entry."},"error_code":{"type":"string","description":"Machine-readable cause. Either the raised error class or a provider-specific completeness code."},"message":{"type":["string","null"],"description":"Human-readable explanation of what went wrong."},"source_object_type":{"type":["string","null"],"description":"Kind of source object this entry refers to. Blank on a run-level error, which belongs to no single object.","enum":["contact","conversation","message",null]},"source_object_id":{"type":["string","null"],"description":"Identifier of the object in the provider. Blank on a run-level error."},"details":{"type":"object","additionalProperties":true,"description":"Free-form context recorded with the entry. The key set depends on what failed; every entry carries a `kind` naming the category, and the provider that produced it."},"created_at":{"type":"string","format":"date-time","description":"When the entry was recorded."}}}},"skip_logs":{"type":"array","description":"Five most recent skip-log entries, newest first, restricted to the object kind in `skip_logs_filters` when one was requested.","items":{"type":"object","properties":{"id":{"type":"integer","description":"Identifier of the log entry."},"kind":{"type":"string","description":"Whether the object raised an error or was deliberately skipped.","enum":["failed","skipped"]},"error_code":{"type":"string","description":"Machine-readable cause. Either the raised error class or a provider-specific skip code."},"message":{"type":["string","null"],"description":"Human-readable explanation of why the object was not migrated."},"source_object_type":{"type":["string","null"],"description":"Kind of source object this entry refers to. Blank when the run failed before it could identify which object it was working on.","enum":["contact","conversation","message",null]},"source_object_id":{"type":["string","null"],"description":"Identifier of the object in the provider."},"details":{"type":"object","additionalProperties":true,"description":"Free-form context recorded with the entry. The key set depends on why the object was skipped; every entry carries a `kind` naming the category, and identifies the provider it came from — directly for an object the run tracked, under a nested `source` for a message."},"created_at":{"type":"string","format":"date-time","description":"When the entry was recorded."}}}},"skip_logs_filters":{"type":"object","description":"State of the skip-log filter for this response, plus the totals a client needs to render the filter itself.","properties":{"selected_source_object_type":{"type":["string","null"],"description":"Filter actually applied. Blank when none was requested or the requested value was not one of the accepted object kinds.","enum":["contact","conversation","message",null]},"counts_by_type":{"type":"object","additionalProperties":{"type":"integer"},"description":"Skip-log totals keyed by source object kind, counted before the filter is applied. Kinds with no entry are omitted, and entries the run could not attribute to an object are counted under the empty key."}}}}},"example":{"id":1,"name":"Sample Name","data_type":"contacts","source_type":"api","source_provider":"freshdesk","import_types":["contacts"],"status":"pending","stalled":true,"total_records":1,"processed_records":1,"stats":{"contacts":{"imported":1,"skipped":1,"total":1},"conversations":{"imported":1,"skipped":1,"total":1},"messages":{"imported":1,"skipped":1,"total":1},"errors":{"count":5}},"cursor":{"contacts":{"starting_after":"sample starting after","completed":true,"updated_at":"2026-01-15T10:30:00.000Z"},"conversations":{"starting_after":"sample starting after","completed":true,"updated_at":"2026-01-15T10:30:00.000Z"}},"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","started_at":"2026-01-15T10:30:00.000Z","completed_at":"2026-01-15T10:30:00.000Z","abandoned_at":"2026-01-15T10:30:00.000Z","initiated_by":{"id":1,"name":"Sample Name","email":"agent@example.com"},"import_errors_count":5,"skip_logs_count":5,"import_errors":[{"id":1,"error_code":"sample error code","message":"Sample message text.","source_object_type":"contact","source_object_id":"sample source object id","details":{},"created_at":"2026-01-15T10:30:00.000Z"}],"skip_logs":[{"id":1,"kind":"failed","error_code":"sample error code","message":"Sample message text.","source_object_type":"contact","source_object_id":"sample source object id","details":{},"created_at":"2026-01-15T10:30:00.000Z"}],"skip_logs_filters":{"selected_source_object_type":"contact","counts_by_type":{}}}}}},"401":{"description":"Authentication, account authorization or the data_import feature is unavailable.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}},"example":{"error":"You are not authorized to do this action"}}}},"404":{"description":"Account or resource not found"},"422":{"description":"The import cannot resume in its current state or its stored credential is unavailable.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["message"],"properties":{"message":{"type":"string"}}},"example":{"message":"Sample message text."}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"skip_logs_type":{"type":"string","enum":["contact","conversation","message"],"description":"Narrow the returned `skip_logs` slice to one source object kind. Any other value is ignored and every kind is returned."}}},"example":{"skip_logs_type":"contact"}}}}}},"/api/v1/accounts/{account_id}/data_imports/{id}/retry":{"post":{"tags":["Data Imports"],"operationId":"auto_post_api_v1_accounts_account_id_data_imports_id_retry","summary":"Retry a stalled data import","description":"Re-enqueues an import that is still pending or processing but has not advanced for fifteen minutes. The request is refused when the import is no longer stalled, when another import is already in progress, or when the stored credential is no longer available.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The current state of the import after it was re-enqueued.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer","description":"Identifier of the data import."},"name":{"type":["string","null"],"description":"Operator-supplied label. When omitted it defaults to the provider's standard import name, or to the data type and the current date on a legacy CSV contact upload."},"data_type":{"type":"string","enum":["contacts","freshdesk","intercom"],"description":"What this import carries. `contacts` is the legacy CSV contact upload; the other two are integration migrations named after their provider."},"source_type":{"type":["string","null"],"description":"How the records are obtained. Integration imports read them over the provider's API; a legacy CSV contact import leaves this blank.","enum":["api",null]},"source_provider":{"type":["string","null"],"description":"External help desk this import reads from. Blank on a legacy CSV contact import, which has no integration provider.","enum":["freshdesk","intercom",null]},"import_types":{"type":"array","description":"Which record families this run migrates. Defaults to both when the creation request omits the field.","items":{"type":"string","enum":["contacts","conversations"]}},"status":{"type":"string","enum":["pending","processing","completed","failed","completed_with_errors","abandoned"],"description":"Lifecycle state of the import run."},"stalled":{"type":"boolean","description":"True when an integration import is still pending or processing but has not advanced for fifteen minutes. Only a stalled run accepts a retry."},"total_records":{"type":["integer","null"],"description":"Every record this run accounted for — imported, skipped and errored. Written once the run finishes, so it stays blank while the import is still working."},"processed_records":{"type":["integer","null"],"description":"Records successfully written into this account. Written once the run finishes, so it stays blank while the import is still working."},"stats":{"type":"object","description":"Running counters for the integration import, rebuilt from the imported and skipped items after every page.","properties":{"contacts":{"type":"object","description":"Contact counters.","properties":{"imported":{"type":"integer","description":"Contacts written into this account."},"skipped":{"type":"integer","description":"Contacts deliberately not written, including ones a previous import already migrated."},"total":{"type":["integer","null"],"description":"Contact total reported by the provider — seeded when the credentials were validated and refreshed from every page the run walks. Absent when the provider does not report one."}}},"conversations":{"type":"object","description":"Conversation counters.","properties":{"imported":{"type":"integer","description":"Conversations written into this account."},"skipped":{"type":"integer","description":"Conversations deliberately not written."},"total":{"type":["integer","null"],"description":"Conversation total reported by the provider — seeded when the credentials were validated and refreshed from every page the run walks. Absent when the provider does not report one."}}},"messages":{"type":"object","description":"Message counters. Messages are discovered while walking conversations, so the total grows as the run progresses.","properties":{"imported":{"type":"integer","description":"Messages written into this account."},"skipped":{"type":"integer","description":"Messages deliberately not written, including ones with no importable text."},"total":{"type":["integer","null"],"description":"Messages seen so far across the conversations already walked."}}},"errors":{"type":"object","description":"Failure counter for the run.","properties":{"count":{"type":"integer","description":"Number of source objects that raised an error."}}}}},"cursor":{"type":"object","description":"Resume point per record family, so an interrupted run continues where it stopped instead of re-walking the provider from the beginning.","properties":{"contacts":{"type":"object","description":"Contact pagination state.","properties":{"starting_after":{"type":["string","null"],"description":"Provider page token to resume from. Blank once the family is fully walked."},"completed":{"type":"boolean","description":"True once the provider returned no further contact page."},"updated_at":{"type":"string","format":"date-time","description":"When this resume point was last written."}}},"conversations":{"type":"object","description":"Conversation pagination state.","properties":{"starting_after":{"type":["string","null"],"description":"Provider page token to resume from. Blank once the family is fully walked."},"completed":{"type":"boolean","description":"True once the provider returned no further conversation page."},"updated_at":{"type":"string","format":"date-time","description":"When this resume point was last written."}}}}},"created_at":{"type":"string","format":"date-time","description":"When the import was created."},"updated_at":{"type":"string","format":"date-time","description":"Last write to the import record. This is the timestamp the stalled check reads."},"started_at":{"type":["string","null"],"format":"date-time","description":"When the run began processing."},"completed_at":{"type":["string","null"],"format":"date-time","description":"When the run finished, with or without errors."},"abandoned_at":{"type":["string","null"],"format":"date-time","description":"When an operator abandoned the run."},"initiated_by":{"type":["object","null"],"description":"Agent who started the import. Blank when the record predates attribution or the agent was removed.","properties":{"id":{"type":"integer","description":"Identifier of the agent."},"name":{"type":"string","description":"Display name of the agent."},"email":{"type":"string","description":"Login e-mail of the agent."}}},"import_errors_count":{"type":"integer","description":"Total error entries for this import — the run-level failures and incomplete-conversation notices, not the per-object skip logs."},"skip_logs_count":{"type":"integer","description":"Total skip-log entries for this import, across every object kind."},"import_errors":{"type":"array","description":"Five most recent error entries, newest first. These are the run-level and completeness problems; per-object skips live in `skip_logs`.","items":{"type":"object","properties":{"id":{"type":"integer","description":"Identifier of the log entry."},"error_code":{"type":"string","description":"Machine-readable cause. Either the raised error class or a provider-specific completeness code."},"message":{"type":["string","null"],"description":"Human-readable explanation of what went wrong."},"source_object_type":{"type":["string","null"],"description":"Kind of source object this entry refers to. Blank on a run-level error, which belongs to no single object.","enum":["contact","conversation","message",null]},"source_object_id":{"type":["string","null"],"description":"Identifier of the object in the provider. Blank on a run-level error."},"details":{"type":"object","additionalProperties":true,"description":"Free-form context recorded with the entry. The key set depends on what failed; every entry carries a `kind` naming the category, and the provider that produced it."},"created_at":{"type":"string","format":"date-time","description":"When the entry was recorded."}}}},"skip_logs":{"type":"array","description":"Five most recent skip-log entries, newest first, restricted to the object kind in `skip_logs_filters` when one was requested.","items":{"type":"object","properties":{"id":{"type":"integer","description":"Identifier of the log entry."},"kind":{"type":"string","description":"Whether the object raised an error or was deliberately skipped.","enum":["failed","skipped"]},"error_code":{"type":"string","description":"Machine-readable cause. Either the raised error class or a provider-specific skip code."},"message":{"type":["string","null"],"description":"Human-readable explanation of why the object was not migrated."},"source_object_type":{"type":["string","null"],"description":"Kind of source object this entry refers to. Blank when the run failed before it could identify which object it was working on.","enum":["contact","conversation","message",null]},"source_object_id":{"type":["string","null"],"description":"Identifier of the object in the provider."},"details":{"type":"object","additionalProperties":true,"description":"Free-form context recorded with the entry. The key set depends on why the object was skipped; every entry carries a `kind` naming the category, and identifies the provider it came from — directly for an object the run tracked, under a nested `source` for a message."},"created_at":{"type":"string","format":"date-time","description":"When the entry was recorded."}}}},"skip_logs_filters":{"type":"object","description":"State of the skip-log filter for this response, plus the totals a client needs to render the filter itself.","properties":{"selected_source_object_type":{"type":["string","null"],"description":"Filter actually applied. Blank when none was requested or the requested value was not one of the accepted object kinds.","enum":["contact","conversation","message",null]},"counts_by_type":{"type":"object","additionalProperties":{"type":"integer"},"description":"Skip-log totals keyed by source object kind, counted before the filter is applied. Kinds with no entry are omitted, and entries the run could not attribute to an object are counted under the empty key."}}}}},"example":{"id":1,"name":"Sample Name","data_type":"contacts","source_type":"api","source_provider":"freshdesk","import_types":["contacts"],"status":"pending","stalled":true,"total_records":1,"processed_records":1,"stats":{"contacts":{"imported":1,"skipped":1,"total":1},"conversations":{"imported":1,"skipped":1,"total":1},"messages":{"imported":1,"skipped":1,"total":1},"errors":{"count":5}},"cursor":{"contacts":{"starting_after":"sample starting after","completed":true,"updated_at":"2026-01-15T10:30:00.000Z"},"conversations":{"starting_after":"sample starting after","completed":true,"updated_at":"2026-01-15T10:30:00.000Z"}},"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","started_at":"2026-01-15T10:30:00.000Z","completed_at":"2026-01-15T10:30:00.000Z","abandoned_at":"2026-01-15T10:30:00.000Z","initiated_by":{"id":1,"name":"Sample Name","email":"agent@example.com"},"import_errors_count":5,"skip_logs_count":5,"import_errors":[{"id":1,"error_code":"sample error code","message":"Sample message text.","source_object_type":"contact","source_object_id":"sample source object id","details":{},"created_at":"2026-01-15T10:30:00.000Z"}],"skip_logs":[{"id":1,"kind":"failed","error_code":"sample error code","message":"Sample message text.","source_object_type":"contact","source_object_id":"sample source object id","details":{},"created_at":"2026-01-15T10:30:00.000Z"}],"skip_logs_filters":{"selected_source_object_type":"contact","counts_by_type":{}}}}}},"401":{"description":"Authentication, account authorization or the data_import feature is unavailable.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}},"example":{"error":"You are not authorized to do this action"}}}},"404":{"description":"Account or resource not found"},"422":{"description":"The import cannot resume in its current state or its stored credential is unavailable.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["message"],"properties":{"message":{"type":"string"}}},"example":{"message":"Sample message text."}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"skip_logs_type":{"type":"string","enum":["contact","conversation","message"],"description":"Narrow the returned `skip_logs` slice to one source object kind. Any other value is ignored and every kind is returned."}}},"example":{"skip_logs_type":"contact"}}}}}},"/api/v1/accounts/{account_id}/data_imports/{id}/abandon":{"post":{"tags":["Data Imports"],"operationId":"auto_post_api_v1_accounts_account_id_data_imports_id_abandon","summary":"Abandon a running data import","description":"Marks a pending or processing integration import as abandoned so a new one can be started. Records already migrated are kept; an abandoned import can later be restarted and resumes from its recorded cursor. An import that is not abandonable is returned unchanged.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The current state of the import after the abandon attempt.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer","description":"Identifier of the data import."},"name":{"type":["string","null"],"description":"Operator-supplied label. When omitted it defaults to the provider's standard import name, or to the data type and the current date on a legacy CSV contact upload."},"data_type":{"type":"string","enum":["contacts","freshdesk","intercom"],"description":"What this import carries. `contacts` is the legacy CSV contact upload; the other two are integration migrations named after their provider."},"source_type":{"type":["string","null"],"description":"How the records are obtained. Integration imports read them over the provider's API; a legacy CSV contact import leaves this blank.","enum":["api",null]},"source_provider":{"type":["string","null"],"description":"External help desk this import reads from. Blank on a legacy CSV contact import, which has no integration provider.","enum":["freshdesk","intercom",null]},"import_types":{"type":"array","description":"Which record families this run migrates. Defaults to both when the creation request omits the field.","items":{"type":"string","enum":["contacts","conversations"]}},"status":{"type":"string","enum":["pending","processing","completed","failed","completed_with_errors","abandoned"],"description":"Lifecycle state of the import run."},"stalled":{"type":"boolean","description":"True when an integration import is still pending or processing but has not advanced for fifteen minutes. Only a stalled run accepts a retry."},"total_records":{"type":["integer","null"],"description":"Every record this run accounted for — imported, skipped and errored. Written once the run finishes, so it stays blank while the import is still working."},"processed_records":{"type":["integer","null"],"description":"Records successfully written into this account. Written once the run finishes, so it stays blank while the import is still working."},"stats":{"type":"object","description":"Running counters for the integration import, rebuilt from the imported and skipped items after every page.","properties":{"contacts":{"type":"object","description":"Contact counters.","properties":{"imported":{"type":"integer","description":"Contacts written into this account."},"skipped":{"type":"integer","description":"Contacts deliberately not written, including ones a previous import already migrated."},"total":{"type":["integer","null"],"description":"Contact total reported by the provider — seeded when the credentials were validated and refreshed from every page the run walks. Absent when the provider does not report one."}}},"conversations":{"type":"object","description":"Conversation counters.","properties":{"imported":{"type":"integer","description":"Conversations written into this account."},"skipped":{"type":"integer","description":"Conversations deliberately not written."},"total":{"type":["integer","null"],"description":"Conversation total reported by the provider — seeded when the credentials were validated and refreshed from every page the run walks. Absent when the provider does not report one."}}},"messages":{"type":"object","description":"Message counters. Messages are discovered while walking conversations, so the total grows as the run progresses.","properties":{"imported":{"type":"integer","description":"Messages written into this account."},"skipped":{"type":"integer","description":"Messages deliberately not written, including ones with no importable text."},"total":{"type":["integer","null"],"description":"Messages seen so far across the conversations already walked."}}},"errors":{"type":"object","description":"Failure counter for the run.","properties":{"count":{"type":"integer","description":"Number of source objects that raised an error."}}}}},"cursor":{"type":"object","description":"Resume point per record family, so an interrupted run continues where it stopped instead of re-walking the provider from the beginning.","properties":{"contacts":{"type":"object","description":"Contact pagination state.","properties":{"starting_after":{"type":["string","null"],"description":"Provider page token to resume from. Blank once the family is fully walked."},"completed":{"type":"boolean","description":"True once the provider returned no further contact page."},"updated_at":{"type":"string","format":"date-time","description":"When this resume point was last written."}}},"conversations":{"type":"object","description":"Conversation pagination state.","properties":{"starting_after":{"type":["string","null"],"description":"Provider page token to resume from. Blank once the family is fully walked."},"completed":{"type":"boolean","description":"True once the provider returned no further conversation page."},"updated_at":{"type":"string","format":"date-time","description":"When this resume point was last written."}}}}},"created_at":{"type":"string","format":"date-time","description":"When the import was created."},"updated_at":{"type":"string","format":"date-time","description":"Last write to the import record. This is the timestamp the stalled check reads."},"started_at":{"type":["string","null"],"format":"date-time","description":"When the run began processing."},"completed_at":{"type":["string","null"],"format":"date-time","description":"When the run finished, with or without errors."},"abandoned_at":{"type":["string","null"],"format":"date-time","description":"When an operator abandoned the run."},"initiated_by":{"type":["object","null"],"description":"Agent who started the import. Blank when the record predates attribution or the agent was removed.","properties":{"id":{"type":"integer","description":"Identifier of the agent."},"name":{"type":"string","description":"Display name of the agent."},"email":{"type":"string","description":"Login e-mail of the agent."}}},"import_errors_count":{"type":"integer","description":"Total error entries for this import — the run-level failures and incomplete-conversation notices, not the per-object skip logs."},"skip_logs_count":{"type":"integer","description":"Total skip-log entries for this import, across every object kind."},"import_errors":{"type":"array","description":"Five most recent error entries, newest first. These are the run-level and completeness problems; per-object skips live in `skip_logs`.","items":{"type":"object","properties":{"id":{"type":"integer","description":"Identifier of the log entry."},"error_code":{"type":"string","description":"Machine-readable cause. Either the raised error class or a provider-specific completeness code."},"message":{"type":["string","null"],"description":"Human-readable explanation of what went wrong."},"source_object_type":{"type":["string","null"],"description":"Kind of source object this entry refers to. Blank on a run-level error, which belongs to no single object.","enum":["contact","conversation","message",null]},"source_object_id":{"type":["string","null"],"description":"Identifier of the object in the provider. Blank on a run-level error."},"details":{"type":"object","additionalProperties":true,"description":"Free-form context recorded with the entry. The key set depends on what failed; every entry carries a `kind` naming the category, and the provider that produced it."},"created_at":{"type":"string","format":"date-time","description":"When the entry was recorded."}}}},"skip_logs":{"type":"array","description":"Five most recent skip-log entries, newest first, restricted to the object kind in `skip_logs_filters` when one was requested.","items":{"type":"object","properties":{"id":{"type":"integer","description":"Identifier of the log entry."},"kind":{"type":"string","description":"Whether the object raised an error or was deliberately skipped.","enum":["failed","skipped"]},"error_code":{"type":"string","description":"Machine-readable cause. Either the raised error class or a provider-specific skip code."},"message":{"type":["string","null"],"description":"Human-readable explanation of why the object was not migrated."},"source_object_type":{"type":["string","null"],"description":"Kind of source object this entry refers to. Blank when the run failed before it could identify which object it was working on.","enum":["contact","conversation","message",null]},"source_object_id":{"type":["string","null"],"description":"Identifier of the object in the provider."},"details":{"type":"object","additionalProperties":true,"description":"Free-form context recorded with the entry. The key set depends on why the object was skipped; every entry carries a `kind` naming the category, and identifies the provider it came from — directly for an object the run tracked, under a nested `source` for a message."},"created_at":{"type":"string","format":"date-time","description":"When the entry was recorded."}}}},"skip_logs_filters":{"type":"object","description":"State of the skip-log filter for this response, plus the totals a client needs to render the filter itself.","properties":{"selected_source_object_type":{"type":["string","null"],"description":"Filter actually applied. Blank when none was requested or the requested value was not one of the accepted object kinds.","enum":["contact","conversation","message",null]},"counts_by_type":{"type":"object","additionalProperties":{"type":"integer"},"description":"Skip-log totals keyed by source object kind, counted before the filter is applied. Kinds with no entry are omitted, and entries the run could not attribute to an object are counted under the empty key."}}}}},"example":{"id":1,"name":"Sample Name","data_type":"contacts","source_type":"api","source_provider":"freshdesk","import_types":["contacts"],"status":"pending","stalled":true,"total_records":1,"processed_records":1,"stats":{"contacts":{"imported":1,"skipped":1,"total":1},"conversations":{"imported":1,"skipped":1,"total":1},"messages":{"imported":1,"skipped":1,"total":1},"errors":{"count":5}},"cursor":{"contacts":{"starting_after":"sample starting after","completed":true,"updated_at":"2026-01-15T10:30:00.000Z"},"conversations":{"starting_after":"sample starting after","completed":true,"updated_at":"2026-01-15T10:30:00.000Z"}},"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","started_at":"2026-01-15T10:30:00.000Z","completed_at":"2026-01-15T10:30:00.000Z","abandoned_at":"2026-01-15T10:30:00.000Z","initiated_by":{"id":1,"name":"Sample Name","email":"agent@example.com"},"import_errors_count":5,"skip_logs_count":5,"import_errors":[{"id":1,"error_code":"sample error code","message":"Sample message text.","source_object_type":"contact","source_object_id":"sample source object id","details":{},"created_at":"2026-01-15T10:30:00.000Z"}],"skip_logs":[{"id":1,"kind":"failed","error_code":"sample error code","message":"Sample message text.","source_object_type":"contact","source_object_id":"sample source object id","details":{},"created_at":"2026-01-15T10:30:00.000Z"}],"skip_logs_filters":{"selected_source_object_type":"contact","counts_by_type":{}}}}}},"401":{"description":"Authentication, account authorization or the data_import feature is unavailable.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}},"example":{"error":"You are not authorized to do this action"}}}},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"skip_logs_type":{"type":"string","enum":["contact","conversation","message"],"description":"Narrow the returned `skip_logs` slice to one source object kind. Any other value is ignored and every kind is returned."}}},"example":{"skip_logs_type":"contact"}}}}}},"/api/v1/accounts/{account_id}/data_imports/{id}/error_logs":{"get":{"tags":["Data Imports"],"operationId":"auto_get_api_v1_accounts_account_id_data_imports_id_error_logs","summary":"Error logs data imports","description":"Performs the error logs operation on the targeted data import resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"File download","content":{"text/csv":{"schema":{"type":"string","format":"binary"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/data_imports/{id}/skip_logs":{"get":{"tags":["Data Imports"],"operationId":"auto_get_api_v1_accounts_account_id_data_imports_id_skip_logs","summary":"Skip logs data imports","description":"Performs the skip logs operation on the targeted data import resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"File download","content":{"text/csv":{"schema":{"type":"string","format":"binary"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/data_imports":{"get":{"tags":["Data Imports"],"operationId":"auto_get_api_v1_accounts_account_id_data_imports","summary":"List the account's data imports","description":"Returns a JSON payload of imports, newest first, with error and skip counts. Requires account authorization and data_import. CSV downloads use error_logs and skip_logs.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"data_type":{"type":"string","enum":["contacts","freshdesk","intercom"],"description":"contacts is the legacy CSV contact import; freshdesk and intercom read records over the provider API (source_provider matches data_type)."},"source_type":{"type":"string","enum":["api"],"description":"How this import obtains its records. Integration imports read them over the provider's API; a legacy CSV contact import leaves it blank."},"source_provider":{"type":"string","enum":["freshdesk","intercom"],"description":"External help desk this import reads from. Blank on a legacy CSV contact import, which has no integration provider."},"import_types":{"type":"array","items":{"type":"string","enum":["contacts","conversations"]},"description":"Record families selected for an integration import; empty for a legacy CSV contact import."},"status":{"type":"string","enum":["pending","processing","completed","failed","completed_with_errors","abandoned"]},"stalled":{"type":"boolean"},"total_records":{"type":["integer","null"],"description":"Records discovered at the source; null until discovery finishes."},"processed_records":{"type":"integer"},"stats":{"type":"object","additionalProperties":true,"description":"Per-family counters written by the importer (for example contacts, conversations, messages, errors, skips); keys depend on the selected import types."},"cursor":{"type":"object","additionalProperties":true,"description":"Provider pagination position kept so an interrupted import resumes without re-reading records; opaque to clients."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"started_at":{"type":["string","null"],"format":"date-time"},"completed_at":{"type":["string","null"],"format":"date-time"},"abandoned_at":{"type":["string","null"],"format":"date-time"},"initiated_by":{"type":["object","null"],"properties":{"id":{"type":"integer"},"name":{"type":"string"},"email":{"type":"string"}},"additionalProperties":false,"description":"Agent who started the import; null for legacy imports without an initiator."},"import_errors_count":{"type":"integer"},"skip_logs_count":{"type":"integer"}}}}}},"example":{"payload":[{"id":1,"name":"Sample Name","data_type":"intercom","source_type":"api","source_provider":"intercom","import_types":["contacts","conversations"],"status":"processing","stalled":false,"total_records":1280,"processed_records":640,"stats":{"contacts":{"created":400,"updated":120},"conversations":{"created":120},"messages":{"created":1830},"errors":0,"skips":3},"cursor":{"contacts":"WzE3NTQzMjEsIDQ1XQ==","conversations":null},"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","started_at":"2026-09-13T12:00:00.000Z","completed_at":null,"abandoned_at":null,"initiated_by":{"id":1,"name":"Ana Souza","email":"ana@example.com"},"import_errors_count":0,"skip_logs_count":3}]}}}},"401":{"description":"Authentication, account authorization or the data_import feature is unavailable.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}},"example":{"error":"You are not authorized to do this action"}}}},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."}]},"post":{"tags":["Data Imports"],"operationId":"auto_post_api_v1_accounts_account_id_data_imports","summary":"Start a data import from an external help desk","description":"Validates the supplied credentials against the provider, creates the import and enqueues its first job. Only one integration import may be active per account at a time; a second request while one is pending or processing is refused. The credentials are stored encrypted and are never returned.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The import was created and its first job enqueued.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer","description":"Identifier of the data import."},"name":{"type":["string","null"],"description":"Operator-supplied label. When omitted it defaults to the provider's standard import name, or to the data type and the current date on a legacy CSV contact upload."},"data_type":{"type":"string","enum":["contacts","freshdesk","intercom"],"description":"What this import carries. `contacts` is the legacy CSV contact upload; the other two are integration migrations named after their provider."},"source_type":{"type":["string","null"],"description":"How the records are obtained. Integration imports read them over the provider's API; a legacy CSV contact import leaves this blank.","enum":["api",null]},"source_provider":{"type":["string","null"],"description":"External help desk this import reads from. Blank on a legacy CSV contact import, which has no integration provider.","enum":["freshdesk","intercom",null]},"import_types":{"type":"array","description":"Which record families this run migrates. Defaults to both when the creation request omits the field.","items":{"type":"string","enum":["contacts","conversations"]}},"status":{"type":"string","enum":["pending","processing","completed","failed","completed_with_errors","abandoned"],"description":"Lifecycle state of the import run."},"stalled":{"type":"boolean","description":"True when an integration import is still pending or processing but has not advanced for fifteen minutes. Only a stalled run accepts a retry."},"total_records":{"type":["integer","null"],"description":"Every record this run accounted for — imported, skipped and errored. Written once the run finishes, so it stays blank while the import is still working."},"processed_records":{"type":["integer","null"],"description":"Records successfully written into this account. Written once the run finishes, so it stays blank while the import is still working."},"stats":{"type":"object","description":"Running counters for the integration import, rebuilt from the imported and skipped items after every page.","properties":{"contacts":{"type":"object","description":"Contact counters.","properties":{"imported":{"type":"integer","description":"Contacts written into this account."},"skipped":{"type":"integer","description":"Contacts deliberately not written, including ones a previous import already migrated."},"total":{"type":["integer","null"],"description":"Contact total reported by the provider — seeded when the credentials were validated and refreshed from every page the run walks. Absent when the provider does not report one."}}},"conversations":{"type":"object","description":"Conversation counters.","properties":{"imported":{"type":"integer","description":"Conversations written into this account."},"skipped":{"type":"integer","description":"Conversations deliberately not written."},"total":{"type":["integer","null"],"description":"Conversation total reported by the provider — seeded when the credentials were validated and refreshed from every page the run walks. Absent when the provider does not report one."}}},"messages":{"type":"object","description":"Message counters. Messages are discovered while walking conversations, so the total grows as the run progresses.","properties":{"imported":{"type":"integer","description":"Messages written into this account."},"skipped":{"type":"integer","description":"Messages deliberately not written, including ones with no importable text."},"total":{"type":["integer","null"],"description":"Messages seen so far across the conversations already walked."}}},"errors":{"type":"object","description":"Failure counter for the run.","properties":{"count":{"type":"integer","description":"Number of source objects that raised an error."}}}}},"cursor":{"type":"object","description":"Resume point per record family, so an interrupted run continues where it stopped instead of re-walking the provider from the beginning.","properties":{"contacts":{"type":"object","description":"Contact pagination state.","properties":{"starting_after":{"type":["string","null"],"description":"Provider page token to resume from. Blank once the family is fully walked."},"completed":{"type":"boolean","description":"True once the provider returned no further contact page."},"updated_at":{"type":"string","format":"date-time","description":"When this resume point was last written."}}},"conversations":{"type":"object","description":"Conversation pagination state.","properties":{"starting_after":{"type":["string","null"],"description":"Provider page token to resume from. Blank once the family is fully walked."},"completed":{"type":"boolean","description":"True once the provider returned no further conversation page."},"updated_at":{"type":"string","format":"date-time","description":"When this resume point was last written."}}}}},"created_at":{"type":"string","format":"date-time","description":"When the import was created."},"updated_at":{"type":"string","format":"date-time","description":"Last write to the import record. This is the timestamp the stalled check reads."},"started_at":{"type":["string","null"],"format":"date-time","description":"When the run began processing."},"completed_at":{"type":["string","null"],"format":"date-time","description":"When the run finished, with or without errors."},"abandoned_at":{"type":["string","null"],"format":"date-time","description":"When an operator abandoned the run."},"initiated_by":{"type":["object","null"],"description":"Agent who started the import. Blank when the record predates attribution or the agent was removed.","properties":{"id":{"type":"integer","description":"Identifier of the agent."},"name":{"type":"string","description":"Display name of the agent."},"email":{"type":"string","description":"Login e-mail of the agent."}}},"import_errors_count":{"type":"integer","description":"Total error entries for this import — the run-level failures and incomplete-conversation notices, not the per-object skip logs."},"skip_logs_count":{"type":"integer","description":"Total skip-log entries for this import, across every object kind."},"import_errors":{"type":"array","description":"Five most recent error entries, newest first. These are the run-level and completeness problems; per-object skips live in `skip_logs`.","items":{"type":"object","properties":{"id":{"type":"integer","description":"Identifier of the log entry."},"error_code":{"type":"string","description":"Machine-readable cause. Either the raised error class or a provider-specific completeness code."},"message":{"type":["string","null"],"description":"Human-readable explanation of what went wrong."},"source_object_type":{"type":["string","null"],"description":"Kind of source object this entry refers to. Blank on a run-level error, which belongs to no single object.","enum":["contact","conversation","message",null]},"source_object_id":{"type":["string","null"],"description":"Identifier of the object in the provider. Blank on a run-level error."},"details":{"type":"object","additionalProperties":true,"description":"Free-form context recorded with the entry. The key set depends on what failed; every entry carries a `kind` naming the category, and the provider that produced it."},"created_at":{"type":"string","format":"date-time","description":"When the entry was recorded."}}}},"skip_logs":{"type":"array","description":"Five most recent skip-log entries, newest first, restricted to the object kind in `skip_logs_filters` when one was requested.","items":{"type":"object","properties":{"id":{"type":"integer","description":"Identifier of the log entry."},"kind":{"type":"string","description":"Whether the object raised an error or was deliberately skipped.","enum":["failed","skipped"]},"error_code":{"type":"string","description":"Machine-readable cause. Either the raised error class or a provider-specific skip code."},"message":{"type":["string","null"],"description":"Human-readable explanation of why the object was not migrated."},"source_object_type":{"type":["string","null"],"description":"Kind of source object this entry refers to. Blank when the run failed before it could identify which object it was working on.","enum":["contact","conversation","message",null]},"source_object_id":{"type":["string","null"],"description":"Identifier of the object in the provider."},"details":{"type":"object","additionalProperties":true,"description":"Free-form context recorded with the entry. The key set depends on why the object was skipped; every entry carries a `kind` naming the category, and identifies the provider it came from — directly for an object the run tracked, under a nested `source` for a message."},"created_at":{"type":"string","format":"date-time","description":"When the entry was recorded."}}}},"skip_logs_filters":{"type":"object","description":"State of the skip-log filter for this response, plus the totals a client needs to render the filter itself.","properties":{"selected_source_object_type":{"type":["string","null"],"description":"Filter actually applied. Blank when none was requested or the requested value was not one of the accepted object kinds.","enum":["contact","conversation","message",null]},"counts_by_type":{"type":"object","additionalProperties":{"type":"integer"},"description":"Skip-log totals keyed by source object kind, counted before the filter is applied. Kinds with no entry are omitted, and entries the run could not attribute to an object are counted under the empty key."}}}}},"example":{"id":1,"name":"Sample Name","data_type":"contacts","source_type":"api","source_provider":"freshdesk","import_types":["contacts"],"status":"pending","stalled":true,"total_records":1,"processed_records":1,"stats":{"contacts":{"imported":1,"skipped":1,"total":1},"conversations":{"imported":1,"skipped":1,"total":1},"messages":{"imported":1,"skipped":1,"total":1},"errors":{"count":5}},"cursor":{"contacts":{"starting_after":"sample starting after","completed":true,"updated_at":"2026-01-15T10:30:00.000Z"},"conversations":{"starting_after":"sample starting after","completed":true,"updated_at":"2026-01-15T10:30:00.000Z"}},"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","started_at":"2026-01-15T10:30:00.000Z","completed_at":"2026-01-15T10:30:00.000Z","abandoned_at":"2026-01-15T10:30:00.000Z","initiated_by":{"id":1,"name":"Sample Name","email":"agent@example.com"},"import_errors_count":5,"skip_logs_count":5,"import_errors":[{"id":1,"error_code":"sample error code","message":"Sample message text.","source_object_type":"contact","source_object_id":"sample source object id","details":{},"created_at":"2026-01-15T10:30:00.000Z"}],"skip_logs":[{"id":1,"kind":"failed","error_code":"sample error code","message":"Sample message text.","source_object_type":"contact","source_object_id":"sample source object id","details":{},"created_at":"2026-01-15T10:30:00.000Z"}],"skip_logs_filters":{"selected_source_object_type":"contact","counts_by_type":{}}}}}},"401":{"description":"Authentication, account authorization or the data_import feature is unavailable.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}},"example":{"error":"You are not authorized to do this action"}}}},"404":{"description":"Account or resource not found"},"422":{"description":"Another import is active, or source validation failed; no import was started.","content":{"application/json":{"schema":{"oneOf":[{"type":"object","additionalProperties":false,"required":["valid","message"],"properties":{"valid":{"type":"boolean","enum":[false]},"message":{"type":"string"}}},{"type":"object","additionalProperties":false,"required":["message"],"properties":{"message":{"type":"string"}}}]},"example":{"valid":false,"message":"Sample message text."}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["source_provider","access_token"],"properties":{"source_provider":{"type":"string","description":"Which external help desk to migrate from.","enum":["freshdesk","intercom"]},"access_token":{"type":"string","description":"Credential for the provider — an API key for Freshdesk, an access key for Intercom. Stored encrypted and never echoed back."},"domain":{"type":"string","description":"Provider domain. Required for Freshdesk; ignored by Intercom."},"name":{"type":"string","description":"Optional label for the import. Defaults to the provider's standard import name."},"import_types":{"type":"array","description":"Which record families to migrate. Omit the field to migrate both; sending an empty list is refused.","items":{"type":"string","enum":["contacts","conversations"]}},"skip_logs_type":{"type":"string","enum":["contact","conversation","message"],"description":"Narrow the `skip_logs` slice of the response to one source object kind. Has no effect on the import itself."}}},"example":{"source_provider":"freshdesk","access_token":"sample-token","domain":"example.com","name":"Sample Name","import_types":["contacts"],"skip_logs_type":"contact"}}}}}},"/api/v1/accounts/{account_id}/data_imports/{id}":{"get":{"tags":["Data Imports"],"operationId":"auto_get_api_v1_accounts_account_id_data_imports_id","summary":"Get data imports","description":"Returns the data import identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"data_type":{"type":"string","enum":["contacts","freshdesk","intercom"],"description":"contacts is the legacy CSV contact import; freshdesk and intercom read records over the provider API (source_provider matches data_type)."},"source_type":{"type":"string","enum":["api"],"description":"How this import obtains its records. Integration imports read them over the provider's API; a legacy CSV contact import leaves it blank."},"source_provider":{"type":"string","enum":["freshdesk","intercom"],"description":"External help desk this import reads from. Blank on a legacy CSV contact import, which has no integration provider."},"import_types":{"type":"array","items":{"type":"string","enum":["contacts","conversations"]},"description":"Record families selected for an integration import; empty for a legacy CSV contact import."},"status":{"type":"string","enum":["pending","processing","completed","failed","completed_with_errors","abandoned"]},"stalled":{"type":"boolean"},"total_records":{"type":["integer","null"],"description":"Records discovered at the source; null until discovery finishes."},"processed_records":{"type":"integer"},"stats":{"type":"object","additionalProperties":true,"description":"Per-family counters written by the importer (for example contacts, conversations, messages, errors, skips); keys depend on the selected import types."},"cursor":{"type":"object","additionalProperties":true,"description":"Provider pagination position kept so an interrupted import resumes without re-reading records; opaque to clients."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"started_at":{"type":["string","null"],"format":"date-time"},"completed_at":{"type":["string","null"],"format":"date-time"},"abandoned_at":{"type":["string","null"],"format":"date-time"},"initiated_by":{"type":["object","null"],"properties":{"id":{"type":"integer"},"name":{"type":"string"},"email":{"type":"string"}},"additionalProperties":false,"description":"Agent who started the import; null for legacy imports without an initiator."},"import_errors_count":{"type":"integer"},"skip_logs_count":{"type":"integer"},"import_errors":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"error_code":{"type":"string"},"message":{"type":"string"},"source_object_type":{"type":"string","enum":["contact","conversation","message"],"description":"Kind of source object this entry refers to. Blank on a run-level error and on a failure raised before the run could identify the object."},"source_object_id":{"type":"integer"},"details":{"type":"string"},"created_at":{"type":"string","format":"date-time"}}}},"skip_logs":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"kind":{"type":"string","enum":["failed","skipped"],"description":"Why the source object never reached this account — the import raised an error on it, or it was deliberately skipped."},"error_code":{"type":"string"},"message":{"type":"string"},"source_object_type":{"type":"string","enum":["contact","conversation","message"],"description":"Kind of source object this entry refers to. Blank on a run-level error and on a failure raised before the run could identify the object."},"source_object_id":{"type":"integer"},"details":{"type":"string"},"created_at":{"type":"string","format":"date-time"}}}},"skip_logs_filters":{"type":"object","properties":{"selected_source_object_type":{"type":"string","enum":["contact","conversation","message"],"description":"Skip-log filter in force for this response. Blank means no filter was applied and every skipped or failed source object is listed."},"counts_by_type":{"type":"integer"}}}}},"example":{"id":1,"name":"Sample Name","data_type":"intercom","source_type":"api","source_provider":"intercom","import_types":["contacts","conversations"],"status":"processing","stalled":false,"total_records":1280,"processed_records":640,"stats":{"contacts":{"created":400,"updated":120},"conversations":{"created":120},"messages":{"created":1830},"errors":0,"skips":3},"cursor":{"contacts":"WzE3NTQzMjEsIDQ1XQ==","conversations":null},"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","started_at":"2026-09-13T12:00:00.000Z","completed_at":null,"abandoned_at":null,"initiated_by":{"id":1,"name":"Ana Souza","email":"ana@example.com"},"import_errors_count":0,"skip_logs_count":3,"import_errors":[{"id":1,"error_code":"sample error code","message":"Sample message text.","source_object_type":"contact","source_object_id":1,"details":"sample details","created_at":"2026-01-15T10:30:00.000Z"}],"skip_logs":[{"id":1,"kind":"failed","error_code":"sample error code","message":"Sample message text.","source_object_type":"contact","source_object_id":1,"details":"sample details","created_at":"2026-01-15T10:30:00.000Z"}],"skip_logs_filters":{"selected_source_object_type":"contact","counts_by_type":1}}}}},"401":{"description":"Authentication, account authorization or the data_import feature is unavailable.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}},"example":{"error":"You are not authorized to do this action"}}}},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/csat_survey_responses/metrics":{"get":{"tags":["CSAT Survey Responses"],"operationId":"auto_get_api_v1_accounts_account_id_csat_survey_responses_metrics","summary":"Metrics csat survey responses","description":"Performs the metrics operation on the targeted csat survey respons resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"total_count":{"type":"integer"},"ratings_count":{"type":"integer"},"total_sent_messages_count":{"type":"integer"}}},"example":{"total_count":5,"ratings_count":5,"total_sent_messages_count":5}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/csat_survey_responses/download":{"get":{"tags":["CSAT Survey Responses"],"operationId":"auto_get_api_v1_accounts_account_id_csat_survey_responses_download","summary":"Download CSAT survey responses as CSV","description":"Streams an attachment `csat_report.csv`. Columns: Agent name, Rating, Feedback, Contact name, Contact email address, Contact phone number, Link to the conversation, Recorded at (and Review notes on Enterprise). Honors the same filters as the index action (date range, user_ids, inbox_id, team_id, rating).","security":[{"userApiKey":[]}],"responses":{"200":{"description":"CSV attachment (filename=csat_report.csv).","content":{"text/csv":{"schema":{"type":"string","format":"binary"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/csat_survey_responses/{id}":{"patch":{"tags":["CSAT Survey Responses"],"operationId":"auto_patch_api_v1_accounts_account_id_csat_survey_responses_id","summary":"Update CSAT review notes (Enterprise)","description":"Enterprise-only. Sets internal review notes on a CSAT survey response and records who/when. Returns the updated survey response.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Updated CSAT survey response.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer","example":55},"rating":{"type":"integer","description":"Customer rating 1-5.","example":4},"feedback_message":{"type":["string","null"],"example":"Quick and helpful."},"csat_review_notes":{"type":["string","null"],"example":"Follow-up scheduled with the customer."},"review_notes_updated_at":{"type":"integer","description":"Epoch seconds when the notes were last updated.","example":1736937000},"review_notes_updated_by":{"type":["object","null"],"properties":{"id":{"type":"integer","example":3},"name":{"type":"string","example":"Jane Agent"}}},"account_id":{"type":"integer","example":1},"message_id":{"type":"integer","example":9021},"contact":{"$ref":"#/components/schemas/contact_base"},"conversation_id":{"type":"integer","description":"Conversation display id.","example":812},"assigned_agent":{"$ref":"#/components/schemas/agent"},"created_at":{"type":"integer","description":"Epoch seconds.","example":1736850600}}},"example":{"id":55,"rating":4,"feedback_message":"Quick and helpful.","csat_review_notes":"Follow-up scheduled with the customer.","review_notes_updated_at":1736937000,"review_notes_updated_by":{"id":3,"name":"Jane Agent"},"account_id":1,"message_id":9021,"contact":{"id":1,"payload":[{"additional_attributes":{},"availability_status":"online","email":"agent@example.com","id":1,"name":"Sample Name","phone_number":"+5511999998888","blocked":true,"contact_type":"visitor","identifier":"sample-identifier","referred_by_affiliate_id":1,"referred_by_affiliate_name":"sample referred by affiliate name","legal_type":"individual","tax_id":"sample tax id","tax_id_type":"br_cpf","country":"BR","address":{"zip":"sample zip","street":"sample street","number":"sample number","complement":"sample complement","neighborhood":"sample neighborhood","city":"São Paulo","state":"active","country":"BR"},"billing_address":{"zip":"sample zip","street":"sample street","number":"sample number","complement":"sample complement","neighborhood":"sample neighborhood","city":"São Paulo","state":"active","country":"BR"},"thumbnail":"sample thumbnail","custom_attributes":{"attribute_key":"attribute_value","signed_up_at":"dd/mm/yyyy"},"last_activity_at":1,"created_at":1,"contact_inboxes":[{"source_id":"sample source id","inbox":{"id":1,"avatar_url":"https://example.com/resource","channel_id":1,"name":"Sample Name","channel_type":"Channel::Api","provider":"default"}}]}]},"conversation_id":812,"assigned_agent":{"id":1,"account_id":1,"account_user_id":1,"availability_status":"online","auto_offline":true,"confirmed":true,"email":"agent@example.com","available_name":"sample available name","name":"Sample Name","role":"agent","outbound_agent_name_header_policy":"inherit","thumbnail":"sample thumbnail","custom_role_id":1},"created_at":1736850600}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"csat_review_notes":{"type":"string","description":"Internal reviewer notes for this CSAT response.","example":"Follow-up scheduled with the customer."}}},"example":{"csat_review_notes":"Follow-up scheduled with the customer."}}}}}},"/api/v1/accounts/{account_id}/csat_survey_responses":{"get":{"tags":["CSAT Survey Responses"],"operationId":"auto_get_api_v1_accounts_account_id_csat_survey_responses","summary":"List csat survey responses","description":"Returns the list of csat survey responses visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"rating":{"type":"string"},"feedback_message":{"type":"string"},"csat_review_notes":{"type":"string"},"review_notes_updated_at":{"type":["integer","null"]},"review_notes_updated_by":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"}}},"account_id":{"type":"integer"},"message_id":{"type":"integer"},"contact":{"type":"object","properties":{"additional_attributes":{"type":"object","additionalProperties":true,"description":"Channel- and source-specific metadata for this record (e.g. browser info, referer, social profile identifiers). The key set depends on the originating channel."},"availability_status":{"type":"string","enum":["online","offline","busy"],"description":"Realtime availability. Contacts report online/offline (presence-based); agents/users additionally report busy (their configured availability)."},"email":{"type":"string","format":"email"},"id":{"type":"integer"},"name":{"type":"string"},"phone_number":{"type":"string"},"blocked":{"type":"string"},"contact_type":{"type":"string","enum":["visitor","lead","customer"]},"identifier":{"type":"string"},"company_id":{"type":"integer"},"organization_id":{"type":"integer"},"referred_by_affiliate_id":{"type":"integer"},"referred_by_affiliate_name":{"type":["string","null"]},"owner_id":{"type":"integer"},"legal_type":{"type":"string","enum":["individual","business"]},"tax_id":{"type":"string","description":"The fiscal identifier (CPF/CNPJ/EIN/VAT); validated and stored encrypted on write. Read payloads return the real value to an authenticated human agent, and a type-aware mask (e.g. \"***.***.***-09\") when a role field rule masks it or the caller is a bot; a hidden rule omits the key. Webhooks, exports and message variables always carry the masked form."},"tax_id_type":{"type":"string","enum":["br_cpf","br_cnpj","us_ein","eu_vat","uk_vat","generic"],"description":"The fiscal identifier scheme used to validate and mask the tax_id (CPF/CNPJ check digits, EIN, EU/UK VAT or a generic fallback)."},"country":{"type":"integer"},"address":{"type":"object","description":"Native postal address of the contact. Blank components are omitted.","properties":{"zip":{"type":"string","description":"Postal/ZIP code (CEP in Brazil)"},"street":{"type":"string","description":"Street name"},"number":{"type":"string","description":"Street number"},"complement":{"type":"string","description":"Address complement (apartment, suite, block)"},"neighborhood":{"type":"string","description":"Neighborhood/district"},"city":{"type":"string","description":"City name"},"state":{"type":"string","description":"State/province (UF in Brazil)"},"country":{"type":"string","description":"Country of the postal address"}}},"billing_address":{"type":"object","description":"Optional billing address override of the contact. An empty object means billing uses the principal address.","properties":{"zip":{"type":"string","description":"Postal/ZIP code (CEP in Brazil)"},"street":{"type":"string","description":"Street name"},"number":{"type":"string","description":"Street number"},"complement":{"type":"string","description":"Address complement (apartment, suite, block)"},"neighborhood":{"type":"string","description":"Neighborhood/district"},"city":{"type":"string","description":"City name"},"state":{"type":"string","description":"State/province (UF in Brazil)"},"country":{"type":"string","description":"Country of the postal address"}}},"thumbnail":{"type":"string"},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"last_activity_at":{"type":"integer"},"created_at":{"type":"integer"},"field_visibility":{"type":"string","enum":["visible","masked","hidden"],"description":"Per-field visibility resolved from the current access role's field_permissions (FieldVisibilityHelper). `visible` renders the real value, `masked` an obfuscated one, `hidden` omits the key entirely."},"contact_inboxes":{"type":"array","items":{"type":"object","properties":{"source_id":{"type":"integer"},"logical_inbox_id":{"type":"integer"},"inbox":{"type":"object","properties":{"id":{"type":"integer"},"avatar_url":{"type":"string"},"channel_id":{"type":"integer"},"name":{"type":"string"},"channel_type":{"type":"string","enum":["Channel::Api","Channel::Email","Channel::FacebookPage","Channel::Instagram","Channel::Line","Channel::Sms","Channel::Telegram","Channel::Tiktok","Channel::TwilioSms","Channel::TwitterProfile","Channel::WebWidget","Channel::Whatsapp"],"description":"The channel class backing the inbox."},"provider":{"type":"string","enum":["default","whatsapp_cloud","whatsapp_web","google","microsoft"],"description":"Messaging provider backing the inbox channel (whatsapp_web is the WazMeow gateway; email uses google/microsoft; default otherwise)."}}}}}},"consent_state":{"type":"object","additionalProperties":{"type":"string","enum":["granted","denied","pending"],"description":"Consent state in force for this delivery channel."},"description":"LGPD consent state keyed by delivery channel (\"all\" is the account-wide scope that shadows the per-channel ones). A channel the contact never declared on is absent rather than pending, since the set of channels an account may use is open. Present only on single-contact payloads. Signals only — it never blocks a send."}}},"conversation_id":{"type":"integer"},"assigned_agent":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":["integer","null"]},"account_user_id":{"type":["integer","null"]},"availability_status":{"type":"string","enum":["online","offline","busy"],"description":"Realtime availability. Contacts report online/offline (presence-based); agents/users additionally report busy (their configured availability)."},"auto_offline":{"type":"boolean"},"confirmed":{"type":"boolean"},"email":{"type":"string","format":"email"},"provider":{"type":"string","enum":["email","google_oauth2","saml"],"description":"The authentication provider the user account was created with."},"available_name":{"type":"string"},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"name":{"type":"string"},"role":{"type":"string","enum":["agent","administrator"]},"outbound_agent_name_header_policy":{"type":["string","null"]},"thumbnail":{"type":"string"},"custom_role_id":{"type":["integer","null"]},"access_role_id":{"type":["integer","null"]}}},"created_at":{"type":"integer"}}}},"example":[{"id":1,"rating":"sample rating","feedback_message":"sample feedback message","csat_review_notes":"sample csat review notes","review_notes_updated_at":1,"review_notes_updated_by":{"id":1,"name":"Sample Name"},"account_id":1,"message_id":1,"contact":{"additional_attributes":{},"availability_status":"online","email":"agent@example.com","id":1,"name":"Sample Name","phone_number":"+5511999998888","blocked":"sample blocked","contact_type":"visitor","identifier":"sample-identifier","company_id":1,"organization_id":1,"referred_by_affiliate_id":1,"referred_by_affiliate_name":"sample referred by affiliate name","owner_id":1,"legal_type":"individual","tax_id":"sample tax id","tax_id_type":"br_cpf","country":1,"address":{"zip":"sample zip","street":"sample street","number":"sample number","complement":"sample complement","neighborhood":"sample neighborhood","city":"São Paulo","state":"active","country":"BR"},"billing_address":{"zip":"sample zip","street":"sample street","number":"sample number","complement":"sample complement","neighborhood":"sample neighborhood","city":"São Paulo","state":"active","country":"BR"},"thumbnail":"sample thumbnail","custom_attributes":{},"last_activity_at":1,"created_at":1,"field_visibility":"visible","contact_inboxes":[{"source_id":1,"logical_inbox_id":1,"inbox":{"id":1,"avatar_url":"https://example.com/resource","channel_id":1,"name":"Sample Name","channel_type":"Channel::Api","provider":"default"}}],"consent_state":{}},"conversation_id":1,"assigned_agent":{"id":1,"account_id":1,"account_user_id":1,"availability_status":"online","auto_offline":true,"confirmed":true,"email":"agent@example.com","provider":"email","available_name":"sample available name","custom_attributes":{},"name":"Sample Name","role":"agent","outbound_agent_name_header_policy":"sample outbound agent name header policy","thumbnail":"sample thumbnail","custom_role_id":1,"access_role_id":1},"created_at":1}]}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."}]}},"/api/v1/accounts/{account_id}/applied_slas/metrics":{"get":{"tags":["SLA Policies"],"operationId":"auto_get_api_v1_accounts_account_id_applied_slas_metrics","summary":"Metrics applied slas","description":"Performs the metrics operation on the targeted applied sla resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"total_applied_slas":{"type":"string"},"number_of_sla_misses":{"type":"string"},"hit_rate":{"type":"number"}}},"example":{"total_applied_slas":"sample total applied slas","number_of_sla_misses":"sample number of sla misses","hit_rate":12.5}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/applied_slas/download":{"get":{"tags":["SLA Policies"],"operationId":"auto_get_api_v1_accounts_account_id_applied_slas_download","summary":"Download breached SLAs as CSV","description":"Streams an attachment `breached_conversation.csv`. Columns: Conversation id, SLA policy breached, Assignee, Team, Inbox, Labels, Conversation link, Breached events (comma-joined sla event types).","security":[{"userApiKey":[]}],"responses":{"200":{"description":"CSV attachment (Content-Disposition attachment; filename=breached_conversation.csv).","content":{"text/csv":{"schema":{"type":"string","format":"binary"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/applied_slas":{"get":{"tags":["SLA Policies"],"operationId":"auto_get_api_v1_accounts_account_id_applied_slas","summary":"List applied slas","description":"Returns the list of applied slas visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"event_type":{"type":"string","enum":["frt","nrt","rt"]},"meta":{"type":"string"},"updated_at":{"type":"integer"},"created_at":{"type":"integer"}}}},"meta":{"type":"object","properties":{"count":{"type":"integer"},"current_page":{"type":"string"}}}}},"example":{"payload":[{"id":1,"event_type":"frt","meta":"sample meta","updated_at":1,"created_at":1}],"meta":{"count":5,"current_page":"sample current page"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."}]}},"/api/v1/accounts/{account_id}/calls":{"get":{"tags":["Calls"],"operationId":"auto_get_api_v1_accounts_account_id_calls","summary":"List call history for the account","description":"Paginated voice-call history (25 per page), newest first, across every calling provider, in every installation. Historical reads do not require an active calling capability. Administrators and agents holding report management see the whole account; every other agent sees only the calls they accepted, within the conversations they can still access. Optional filters narrow the list by status, direction, inbox, agent and creation window; `since` and `until` are applied only when both are given.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"One page of call records with the total count and page position.","content":{"application/json":{"schema":{"type":"object","properties":{"meta":{"type":"object","description":"Total matches and page position for the current filter.","properties":{"count":{"type":"integer","description":"Total calls matching the filters, across all pages.","example":137},"current_page":{"type":"integer","description":"The page that was returned.","example":1},"total_pages":{"type":"integer","description":"Number of pages available at 25 records per page.","example":6}}},"payload":{"type":"array","description":"Call records, newest first.","items":{"type":"object","properties":{"id":{"type":"integer","description":"Internal call identifier.","example":4821},"call_id":{"type":"string","description":"Identifier assigned by the calling provider.","example":"wa-call-sample-0001"},"provider":{"type":"string","description":"Calling provider that handled the call. `whatsapp` is WhatsApp Cloud calling and `whatsapp_web` is WhatsApp Web through the WazMeow gateway.","enum":["twilio","whatsapp","whatsapp_web"],"example":"whatsapp_web"},"status":{"type":"string","description":"Call status in display form — the stored status with underscores rendered as hyphens. Everything except `ringing` and `in-progress` is terminal.","enum":["ringing","in-progress","completed","rejected","no-answer","failed"],"example":"completed"},"direction":{"type":"string","description":"Call direction relative to the business number.","enum":["inbound","outbound"],"example":"inbound"},"duration_seconds":{"type":["integer","null"],"description":"Talk time in seconds, null while the call has not completed.","example":96},"end_reason":{"type":["string","null"],"description":"Provider-reported reason the call ended, null when the provider sent none.","example":"completed"},"started_at":{"type":["integer","null"],"description":"When the call was answered, in epoch seconds; null when it never was.","example":1767311900},"created_at":{"type":"integer","description":"When the call record was created, in epoch seconds.","example":1767311880},"message_id":{"type":["integer","null"],"description":"Conversation message that represents this call, null when none was created.","example":778103},"recording_url":{"type":["string","null"],"description":"Download URL for the attached recording, null when there is no recording.","example":"https://app.example.com/rails/active_storage/blobs/sample/recording.ogg"},"recording_deleted":{"type":"boolean","description":"Whether the recording was explicitly removed; its URL remains null.","example":false},"transcript":{"type":["string","null"],"description":"Stored transcription of the recording, null when the call was not transcribed.","example":"Olá, tudo bem? Queria confirmar o horário."},"conversation":{"type":"object","description":"The conversation the call belongs to.","properties":{"id":{"type":"integer","description":"Internal conversation identifier.","example":90210},"display_id":{"type":"integer","description":"Per-account conversation number shown in the UI.","example":1042}}},"inbox":{"type":"object","description":"The inbox the call arrived on.","properties":{"id":{"type":"integer","description":"Inbox identifier.","example":12},"name":{"type":"string","description":"Inbox name.","example":"Suporte WhatsApp"},"channel_type":{"type":"string","example":"Channel::Whatsapp","enum":["Channel::Api","Channel::Email","Channel::FacebookPage","Channel::Instagram","Channel::Line","Channel::Sms","Channel::Telegram","Channel::Tiktok","Channel::TwilioSms","Channel::TwitterProfile","Channel::WebWidget","Channel::Whatsapp"],"description":"The inbox channel class — identifies which messaging channel backs the inbox."},"medium":{"type":["string","null"],"description":"Channel medium, when the underlying channel exposes one; null otherwise.","example":"whatsapp"}}},"agent":{"type":["object","null"],"description":"Agent who accepted the call, null when nobody did.","properties":{"id":{"type":"integer","description":"Agent user identifier.","example":7},"name":{"type":"string","description":"Agent display name.","example":"Carla Souza"},"avatar":{"type":["string","null"],"description":"Agent avatar URL, null when the agent has no avatar.","example":"https://app.example.com/avatars/sample-agent.png"}}},"contact":{"type":["object","null"],"description":"Contact on the other end of the call, null when the call has no contact.","properties":{"id":{"type":"integer","description":"Contact identifier.","example":5533},"name":{"type":["string","null"],"description":"Contact display name.","example":"Ana Ribeiro"},"phone_number":{"type":["string","null"],"description":"Contact phone number in E.164, null when unknown.","example":"+5521999998888"},"avatar":{"type":["string","null"],"description":"Contact avatar URL, null when the contact has no avatar.","example":"https://app.example.com/avatars/sample-contact.png"}}}}}}}},"example":{"meta":{"count":137,"current_page":1,"total_pages":6},"payload":[{"id":4821,"call_id":"wa-call-sample-0001","provider":"whatsapp_web","status":"completed","direction":"inbound","duration_seconds":96,"end_reason":"completed","started_at":1767311900,"created_at":1767311880,"message_id":778103,"recording_url":"https://app.example.com/rails/active_storage/blobs/sample/recording.ogg","recording_deleted":false,"transcript":"Olá, tudo bem? Queria confirmar o horário.","conversation":{"id":90210,"display_id":1042},"inbox":{"id":12,"name":"Suporte WhatsApp","channel_type":"Channel::Whatsapp","medium":"whatsapp"},"agent":{"id":7,"name":"Carla Souza","avatar":"https://app.example.com/avatars/sample-agent.png"},"contact":{"id":5533,"name":"Ana Ribeiro","phone_number":"+5521999998888","avatar":"https://app.example.com/avatars/sample-contact.png"}}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"1-based page number. Defaults to 1; the page size is fixed at 25.","schema":{"type":"integer","minimum":1,"example":1}},{"name":"status","in":"query","required":false,"description":"Keep only calls in this status, written in the same display form the response returns.","schema":{"type":"string","enum":["ringing","in-progress","completed","rejected","no-answer","failed"],"example":"completed"}},{"name":"direction","in":"query","required":false,"description":"Keep only calls in this direction, written in the same display form the response returns.","schema":{"type":"string","enum":["inbound","outbound"],"example":"inbound"}},{"name":"inbox_id","in":"query","required":false,"description":"Keep only calls that arrived on this inbox.","schema":{"type":"integer","example":12}},{"name":"agent_id","in":"query","required":false,"description":"Keep only calls accepted by this agent.","schema":{"type":"integer","example":7}},{"name":"since","in":"query","required":false,"description":"Start of the creation window, in epoch seconds. Ignored unless `until` is given too.","schema":{"type":"integer","example":1767225600}},{"name":"until","in":"query","required":false,"description":"End of the creation window, in epoch seconds, inclusive. Ignored unless `since` is given too.","schema":{"type":"integer","example":1769904000}}]}},"/api/v1/accounts/{account_id}/whatsapp_web_calls/{id}/accept":{"post":{"tags":["WhatsApp Web Calls"],"operationId":"auto_post_api_v1_accounts_account_id_whatsapp_web_calls_id_accept","summary":"Accept whatsapp web calls","description":"Performs the accept operation on the targeted whatsapp web call resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"call_id":{"type":"integer"},"provider":{"type":"string","enum":["whatsapp_web"],"description":"Call provider (WhatsApp Web via the WazMeow gateway)."},"status":{"type":"string","enum":["ringing","in-progress","completed","no-answer","failed"],"description":"Display call status (hyphenated form of the stored call status)."},"state":{"type":"string"},"revision":{"type":"string"},"pipeline_version":{"type":"string"},"direction":{"type":"string","enum":["inbound","outbound"],"description":"Call direction (relative to the business number)."},"conversation_id":{"type":"integer"},"conversation_record_id":{"type":"integer"},"inbox_id":{"type":"integer"},"logical_inbox_id":{"type":"integer"},"message_id":{"type":"integer"},"accepted_by_agent_id":{"type":"integer"},"elapsed_seconds":{"type":"integer"},"video":{"type":["boolean","null"]},"is_group":{"type":["boolean","null"]},"group_jid":{"type":["string","null"]},"legacy_stream_fallback_allowed":{"type":"string"},"stream_path":{"type":"string"},"stream_ticket":{"type":"string"},"video_stream_path":{"type":"string"},"video_stream_ticket":{"type":"string"},"events_path":{"type":"string"},"events_ticket":{"type":"string"},"video_state_path":{"type":"string"},"video_state_ticket":{"type":"string"},"caller":{"type":"string"}}},"example":{"id":1,"call_id":1,"provider":"whatsapp_web","status":"ringing","state":"active","revision":"sample revision","pipeline_version":"sample pipeline version","direction":"inbound","conversation_id":1,"conversation_record_id":1,"inbox_id":1,"logical_inbox_id":1,"message_id":1,"accepted_by_agent_id":1,"elapsed_seconds":60,"video":true,"is_group":true,"group_jid":"sample group jid","legacy_stream_fallback_allowed":"sample legacy stream fallback allowed","stream_path":"sample stream path","stream_ticket":"sample stream ticket","video_stream_path":"sample video stream path","video_stream_ticket":"sample video stream ticket","events_path":"sample events path","events_ticket":"sample events ticket","video_state_path":"sample video state path","video_state_ticket":"sample video state ticket","caller":"sample caller"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"403":{"description":"The live call is claimed by another agent tab (the same tab retrying renews its own claim).","content":{"application/json":{"schema":{"type":"object","required":["error","call_ended"],"properties":{"error":{"type":"string","description":"Localized message in the agent locale."},"call_ended":{"type":"boolean","enum":[false]}}},"example":{"error":"A reserva desta chamada expirou ou pertence a outra aba de atendente. Abra a chamada novamente e tente outra vez.","call_ended":false}}}},"409":{"description":"Either the call already ended (call_ended true) or a competing tab owns the live call / the lifecycle revision is stale.","content":{"application/json":{"schema":{"oneOf":[{"type":"object","required":["error","call_ended"],"properties":{"error":{"type":"string"},"call_ended":{"type":"boolean","enum":[true]},"state":{"type":["string","null"]}}},{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"state":{"type":["string","null"]},"revision":{"type":["integer","null"]}}}]},"example":{"error":"Esta chamada já terminou","call_ended":true,"state":"no_answer"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"client_session_id":{"type":"string","maxLength":128,"description":"Stable browser-tab session id. Required for pipeline-v2 call ownership; omitted only by legacy pipeline-v1 clients."},"expected_revision":{"type":"integer","minimum":0,"description":"Optional optimistic lifecycle revision."},"idempotency_key":{"type":"string","maxLength":255,"description":"Caller-generated retry key for this command."}},"additionalProperties":false},"example":{"client_session_id":"01913dd8-8e85-75fd-9e0f-fb52127a79a0","expected_revision":2,"idempotency_key":"command-01913dd8"}}}}}},"/api/v1/accounts/{account_id}/whatsapp_web_calls/{id}/reject":{"post":{"tags":["WhatsApp Web Calls"],"operationId":"auto_post_api_v1_accounts_account_id_whatsapp_web_calls_id_reject","summary":"Reject whatsapp web calls","description":"Performs the reject operation on the targeted whatsapp web call resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"status":{"type":"string","enum":["ringing","in-progress","completed","no-answer","failed"],"description":"Display call status (hyphenated form of the stored call status)."}}},"example":{"id":1,"status":"ringing"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"403":{"description":"The live call is claimed by another agent tab (the same tab retrying renews its own claim).","content":{"application/json":{"schema":{"type":"object","required":["error","call_ended"],"properties":{"error":{"type":"string","description":"Localized message in the agent locale."},"call_ended":{"type":"boolean","enum":[false]}}},"example":{"error":"A reserva desta chamada expirou ou pertence a outra aba de atendente. Abra a chamada novamente e tente outra vez.","call_ended":false}}}},"409":{"description":"Either the call already ended (call_ended true) or a competing tab owns the live call / the lifecycle revision is stale.","content":{"application/json":{"schema":{"oneOf":[{"type":"object","required":["error","call_ended"],"properties":{"error":{"type":"string"},"call_ended":{"type":"boolean","enum":[true]},"state":{"type":["string","null"]}}},{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"state":{"type":["string","null"]},"revision":{"type":["integer","null"]}}}]},"example":{"error":"Esta chamada já terminou","call_ended":true,"state":"no_answer"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"client_session_id":{"type":"string","maxLength":128,"description":"Stable browser-tab session id. Required for pipeline-v2 call ownership; omitted only by legacy pipeline-v1 clients."},"expected_revision":{"type":"integer","minimum":0,"description":"Optional optimistic lifecycle revision."},"idempotency_key":{"type":"string","maxLength":255,"description":"Caller-generated retry key for this command."}},"additionalProperties":false},"example":{"client_session_id":"01913dd8-8e85-75fd-9e0f-fb52127a79a0","expected_revision":2,"idempotency_key":"command-01913dd8"}}}}}},"/api/v1/accounts/{account_id}/whatsapp_web_calls/{id}/terminate":{"post":{"tags":["WhatsApp Web Calls"],"operationId":"auto_post_api_v1_accounts_account_id_whatsapp_web_calls_id_terminate","summary":"Terminate whatsapp web calls","description":"Performs the terminate operation on the targeted whatsapp web call resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"status":{"type":"string","enum":["ringing","in-progress","completed","no-answer","failed"],"description":"Display call status (hyphenated form of the stored call status)."}}},"example":{"id":1,"status":"ringing"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"403":{"description":"The live call is claimed by another agent tab (the same tab retrying renews its own claim).","content":{"application/json":{"schema":{"type":"object","required":["error","call_ended"],"properties":{"error":{"type":"string","description":"Localized message in the agent locale."},"call_ended":{"type":"boolean","enum":[false]}}},"example":{"error":"A reserva desta chamada expirou ou pertence a outra aba de atendente. Abra a chamada novamente e tente outra vez.","call_ended":false}}}},"409":{"description":"Either the call already ended (call_ended true) or a competing tab owns the live call / the lifecycle revision is stale.","content":{"application/json":{"schema":{"oneOf":[{"type":"object","required":["error","call_ended"],"properties":{"error":{"type":"string"},"call_ended":{"type":"boolean","enum":[true]},"state":{"type":["string","null"]}}},{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"state":{"type":["string","null"]},"revision":{"type":["integer","null"]}}}]},"example":{"error":"Esta chamada já terminou","call_ended":true,"state":"no_answer"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"client_session_id":{"type":"string","maxLength":128,"description":"Stable browser-tab session id. Required for pipeline-v2 call ownership; omitted only by legacy pipeline-v1 clients."},"expected_revision":{"type":"integer","minimum":0,"description":"Optional optimistic lifecycle revision."},"idempotency_key":{"type":"string","maxLength":255,"description":"Caller-generated retry key for this command."}},"additionalProperties":false},"example":{"client_session_id":"01913dd8-8e85-75fd-9e0f-fb52127a79a0","expected_revision":2,"idempotency_key":"command-01913dd8"}}}}}},"/api/v1/accounts/{account_id}/whatsapp_web_calls/{id}/upload_recording":{"post":{"tags":["WhatsApp Web Calls"],"operationId":"auto_post_api_v1_accounts_account_id_whatsapp_web_calls_id_upload_recording","summary":"Upload recording whatsapp web calls","description":"Performs the upload recording operation on the targeted whatsapp web call resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"status":{"type":"string","enum":["already_uploaded","uploaded"],"description":"Outcome of attaching the call recording (idempotent)."}}},"example":{"id":1,"status":"already_uploaded"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["recording"],"properties":{"recording":{"type":"string","format":"binary","description":"Non-empty audio recording whose declared MIME type matches its bytes."},"client_session_id":{"type":"string","maxLength":128,"description":"Stable browser-tab session id. Required for pipeline-v2 call ownership; omitted only by legacy pipeline-v1 clients."}},"additionalProperties":false}}}}}},"/api/v1/accounts/{account_id}/whatsapp_web_calls/{id}/media_session":{"post":{"tags":["WhatsApp Web Calls"],"operationId":"auto_post_api_v1_accounts_account_id_whatsapp_web_calls_id_media_session","summary":"Create a secure WhatsApp Web call media session","description":"Creates short-lived, one-time stream capabilities for the agent who accepted the active call. The JSON response contains same-origin media paths only. Four Secure, HttpOnly, SameSite=Strict cookies carry the path-scoped capabilities; neither those capabilities nor the permanent WazMeow credential are returned in the response body. The installation must have the call-media ingress enabled with this call's WazMeow shard in its static allowlist.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Secret-free stream descriptors; path-scoped capabilities are set as HttpOnly cookies.","content":{"application/json":{"schema":{"type":"object","required":["id","expires_in","streams"],"properties":{"id":{"type":"string","format":"uuid","description":"Ephemeral media-session correlation id; not an authorization credential."},"expires_in":{"type":"integer","enum":[60],"description":"Capability lifetime in seconds."},"streams":{"type":"object","required":["audio","video","events","video_state"],"properties":{"audio":{"type":"object","required":["path","transport"],"properties":{"path":{"type":"string","description":"Same-origin ingress path for this stream; no bearer credential is embedded."},"transport":{"type":"string","enum":["websocket","sse"],"description":"Browser transport required for the stream."}},"additionalProperties":false},"video":{"type":"object","required":["path","transport"],"properties":{"path":{"type":"string","description":"Same-origin ingress path for this stream; no bearer credential is embedded."},"transport":{"type":"string","enum":["websocket","sse"],"description":"Browser transport required for the stream."}},"additionalProperties":false},"events":{"type":"object","required":["path","transport"],"properties":{"path":{"type":"string","description":"Same-origin ingress path for this stream; no bearer credential is embedded."},"transport":{"type":"string","enum":["websocket","sse"],"description":"Browser transport required for the stream."}},"additionalProperties":false},"video_state":{"type":"object","required":["path","transport"],"properties":{"path":{"type":"string","description":"Same-origin ingress path for this stream; no bearer credential is embedded."},"transport":{"type":"string","enum":["websocket","sse"],"description":"Browser transport required for the stream."}},"additionalProperties":false}},"additionalProperties":false}},"additionalProperties":false},"example":{"id":"4cd612ba-3b38-4d8e-86ad-96e2547e60a3","expires_in":60,"streams":{"audio":{"path":"/call-media/wazmeow-3/004246218CB8046FADF16AB7D0236582/audio","transport":"websocket"},"video":{"path":"/call-media/wazmeow-3/004246218CB8046FADF16AB7D0236582/video?fmt=participant","transport":"websocket"},"events":{"path":"/call-media/wazmeow-3/004246218CB8046FADF16AB7D0236582/events","transport":"sse"},"video_state":{"path":"/call-media/wazmeow-3/004246218CB8046FADF16AB7D0236582/video_state","transport":"sse"}}}}}},"401":{"description":"The dashboard session is missing/invalid or the agent cannot view the call conversation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"error":"You need to sign in or sign up before continuing.","description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"404":{"description":"The call is absent from this account or the agent cannot view its conversation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"},"example":{"error":"Resource could not be found","description":"A short description.","errors":[{"field":"sample field","message":"Sample message text.","code":"sample code"}]}}}},"503":{"description":"The call is terminal, belongs to another accepted agent, has no statically allowlisted WazMeow owner, or the install-wide media ingress is not ready."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/whatsapp_web_calls/{id}/video":{"post":{"tags":["WhatsApp Web Calls"],"operationId":"auto_post_api_v1_accounts_account_id_whatsapp_web_calls_id_video","summary":"Video whatsapp web calls","description":"Performs the video operation on the targeted whatsapp web call resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The gateway applied the requested boolean call control state.","content":{"application/json":{"schema":{"type":"object","required":["ok","enabled"],"properties":{"ok":{"type":"boolean"},"enabled":{"type":"boolean"}},"additionalProperties":true},"example":{"ok":true,"enabled":true}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["enabled"],"properties":{"enabled":{"type":"boolean"},"client_session_id":{"type":"string","maxLength":128,"description":"Stable browser-tab session id. Required for pipeline-v2 call ownership; omitted only by legacy pipeline-v1 clients."}},"additionalProperties":false},"example":{"enabled":true,"client_session_id":"01913dd8-8e85-75fd-9e0f-fb52127a79a0"}}}}}},"/api/v1/accounts/{account_id}/whatsapp_web_calls/{id}/screenshare":{"post":{"tags":["WhatsApp Web Calls"],"operationId":"auto_post_api_v1_accounts_account_id_whatsapp_web_calls_id_screenshare","summary":"Screenshare whatsapp web calls","description":"Performs the screenshare operation on the targeted whatsapp web call resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The gateway applied the requested boolean call control state.","content":{"application/json":{"schema":{"type":"object","required":["ok","enabled"],"properties":{"ok":{"type":"boolean"},"enabled":{"type":"boolean"}},"additionalProperties":true},"example":{"ok":true,"enabled":true}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["enabled"],"properties":{"enabled":{"type":"boolean"},"client_session_id":{"type":"string","maxLength":128,"description":"Stable browser-tab session id. Required for pipeline-v2 call ownership; omitted only by legacy pipeline-v1 clients."}},"additionalProperties":false},"example":{"enabled":true,"client_session_id":"01913dd8-8e85-75fd-9e0f-fb52127a79a0"}}}}}},"/api/v1/accounts/{account_id}/whatsapp_web_calls/{id}/reaction":{"post":{"tags":["WhatsApp Web Calls"],"operationId":"auto_post_api_v1_accounts_account_id_whatsapp_web_calls_id_reaction","summary":"Reaction whatsapp web calls","description":"Performs the reaction operation on the targeted whatsapp web call resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The gateway accepted the call control operation.","content":{"application/json":{"schema":{"type":"object","required":["ok"],"properties":{"ok":{"type":"boolean"}},"additionalProperties":true},"example":{"ok":true}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["emoji"],"properties":{"emoji":{"type":"string","maxLength":32},"client_session_id":{"type":"string","maxLength":128,"description":"Stable browser-tab session id. Required for pipeline-v2 call ownership; omitted only by legacy pipeline-v1 clients."}},"additionalProperties":false},"example":{"emoji":"👍","client_session_id":"01913dd8-8e85-75fd-9e0f-fb52127a79a0"}}}}}},"/api/v1/accounts/{account_id}/whatsapp_web_calls/{id}/hand":{"post":{"tags":["WhatsApp Web Calls"],"operationId":"auto_post_api_v1_accounts_account_id_whatsapp_web_calls_id_hand","summary":"Hand whatsapp web calls","description":"Performs the hand operation on the targeted whatsapp web call resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The gateway accepted the call control operation.","content":{"application/json":{"schema":{"type":"object","required":["ok"],"properties":{"ok":{"type":"boolean"}},"additionalProperties":true},"example":{"ok":true}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["raised"],"properties":{"raised":{"type":"boolean"},"client_session_id":{"type":"string","maxLength":128,"description":"Stable browser-tab session id. Required for pipeline-v2 call ownership; omitted only by legacy pipeline-v1 clients."}},"additionalProperties":false},"example":{"raised":true,"client_session_id":"01913dd8-8e85-75fd-9e0f-fb52127a79a0"}}}}}},"/api/v1/accounts/{account_id}/whatsapp_web_calls/{id}/group_state":{"get":{"tags":["WhatsApp Web Calls"],"operationId":"auto_get_api_v1_accounts_account_id_whatsapp_web_calls_id_group_state","summary":"Group state whatsapp web calls","description":"Performs the group state operation on the targeted whatsapp web call resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Current gateway roster and connection state for the group call.","content":{"application/json":{"schema":{"type":"object","required":["callId","participants"],"properties":{"callId":{"type":"string"},"transactionId":{"type":"string"},"participants":{"type":"array","items":{"type":"object","required":["jid","state"],"properties":{"jid":{"type":"string"},"phone":{"type":["string","null"]},"state":{"type":"string"}},"additionalProperties":true}}},"additionalProperties":true},"example":{"callId":"sample-group-call","participants":[{"jid":"participant@lid","state":"connected","phone":"+5511999998888"}],"transactionId":"sample transactionId"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"client_session_id","in":"query","required":false,"schema":{"type":"string","maxLength":128,"description":"Stable browser-tab session id. Required for pipeline-v2 call ownership; omitted only by legacy pipeline-v1 clients."},"description":"Browser-tab owner used to recover pipeline-v2 calls without exposing another tab."}]}},"/api/v1/accounts/{account_id}/whatsapp_web_calls/{id}/add_participants":{"post":{"tags":["WhatsApp Web Calls"],"operationId":"auto_post_api_v1_accounts_account_id_whatsapp_web_calls_id_add_participants","summary":"Add participants whatsapp web calls","description":"Performs the add participants operation on the targeted whatsapp web call resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Participant add result, including any identities refused by WhatsApp.","content":{"application/json":{"schema":{"type":"object","required":["ok","failed"],"properties":{"ok":{"type":"boolean"},"failed":{"type":"array","items":{"type":"string"}}},"additionalProperties":true},"example":{"ok":true,"failed":[]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["targets"],"properties":{"targets":{"type":"array","minItems":1,"items":{"type":"string"}},"client_session_id":{"type":"string","maxLength":128,"description":"Stable browser-tab session id. Required for pipeline-v2 call ownership; omitted only by legacy pipeline-v1 clients."}},"additionalProperties":false},"example":{"targets":["5511999999999@s.whatsapp.net"],"client_session_id":"01913dd8-8e85-75fd-9e0f-fb52127a79a0"}}}}}},"/api/v1/accounts/{account_id}/whatsapp_web_calls/{id}/ring_participant":{"post":{"tags":["WhatsApp Web Calls"],"operationId":"auto_post_api_v1_accounts_account_id_whatsapp_web_calls_id_ring_participant","summary":"Ring participant whatsapp web calls","description":"Performs the ring participant operation on the targeted whatsapp web call resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The gateway accepted the call control operation.","content":{"application/json":{"schema":{"type":"object","required":["ok"],"properties":{"ok":{"type":"boolean"}},"additionalProperties":true},"example":{"ok":true}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["target"],"properties":{"target":{"type":"string"},"client_session_id":{"type":"string","maxLength":128,"description":"Stable browser-tab session id. Required for pipeline-v2 call ownership; omitted only by legacy pipeline-v1 clients."}},"additionalProperties":false},"example":{"target":"5511999999999@s.whatsapp.net","client_session_id":"01913dd8-8e85-75fd-9e0f-fb52127a79a0"}}}}}},"/api/v1/accounts/{account_id}/whatsapp_web_calls/{id}/waiting_room":{"get":{"tags":["WhatsApp Web Calls"],"operationId":"auto_get_api_v1_accounts_account_id_whatsapp_web_calls_id_waiting_room","summary":"Waiting room whatsapp web calls","description":"Performs the waiting room operation on the targeted whatsapp web call resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Current waiting-room state returned by the paired WhatsApp session.","content":{"application/json":{"schema":{"type":"object","required":["callId","enabled","isAdmin","users"],"properties":{"callId":{"type":"string"},"enabled":{"type":"boolean"},"isAdmin":{"type":"boolean"},"inWaitingRoom":{"type":"boolean"},"transactionId":{"type":"string"},"users":{"type":"array","items":{"type":"object","required":["jid"],"properties":{"jid":{"type":"string"},"phone":{"type":["string","null"]}},"additionalProperties":true}}},"additionalProperties":true},"example":{"callId":"sample-group-call","enabled":true,"isAdmin":true,"users":[{"jid":"waiting-participant@lid","phone":"+5511999998888"}],"inWaitingRoom":true,"transactionId":"sample transactionId"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"client_session_id","in":"query","required":false,"schema":{"type":"string","maxLength":128,"description":"Stable browser-tab session id. Required for pipeline-v2 call ownership; omitted only by legacy pipeline-v1 clients."},"description":"Browser-tab owner used to recover pipeline-v2 calls without exposing another tab."}]}},"/api/v1/accounts/{account_id}/whatsapp_web_calls/{id}/admit":{"post":{"tags":["WhatsApp Web Calls"],"operationId":"auto_post_api_v1_accounts_account_id_whatsapp_web_calls_id_admit","summary":"Admit whatsapp web calls","description":"Performs the admit operation on the targeted whatsapp web call resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The gateway accepted the call control operation.","content":{"application/json":{"schema":{"type":"object","required":["ok"],"properties":{"ok":{"type":"boolean"}},"additionalProperties":true},"example":{"ok":true}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["user"],"properties":{"user":{"type":"string"},"client_session_id":{"type":"string","maxLength":128,"description":"Stable browser-tab session id. Required for pipeline-v2 call ownership; omitted only by legacy pipeline-v1 clients."}},"additionalProperties":false},"example":{"user":"5511999999999@s.whatsapp.net","client_session_id":"01913dd8-8e85-75fd-9e0f-fb52127a79a0"}}}}}},"/api/v1/accounts/{account_id}/whatsapp_web_calls/{id}/deny":{"post":{"tags":["WhatsApp Web Calls"],"operationId":"auto_post_api_v1_accounts_account_id_whatsapp_web_calls_id_deny","summary":"Deny whatsapp web calls","description":"Performs the deny operation on the targeted whatsapp web call resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The gateway accepted the call control operation.","content":{"application/json":{"schema":{"type":"object","required":["ok"],"properties":{"ok":{"type":"boolean"}},"additionalProperties":true},"example":{"ok":true}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["user"],"properties":{"user":{"type":"string"},"client_session_id":{"type":"string","maxLength":128,"description":"Stable browser-tab session id. Required for pipeline-v2 call ownership; omitted only by legacy pipeline-v1 clients."}},"additionalProperties":false},"example":{"user":"5511999999999@s.whatsapp.net","client_session_id":"01913dd8-8e85-75fd-9e0f-fb52127a79a0"}}}}}},"/api/v1/accounts/{account_id}/whatsapp_web_calls/{id}/approval":{"post":{"tags":["WhatsApp Web Calls"],"operationId":"auto_post_api_v1_accounts_account_id_whatsapp_web_calls_id_approval","summary":"Approval whatsapp web calls","description":"Performs the approval operation on the targeted whatsapp web call resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The gateway applied the requested boolean call control state.","content":{"application/json":{"schema":{"type":"object","required":["ok","enabled"],"properties":{"ok":{"type":"boolean"},"enabled":{"type":"boolean"}},"additionalProperties":true},"example":{"ok":true,"enabled":true}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"enabled":{"type":"boolean"},"client_session_id":{"type":"string","maxLength":128,"description":"Stable browser-tab session id. Required for pipeline-v2 call ownership; omitted only by legacy pipeline-v1 clients."}},"additionalProperties":false},"example":{"enabled":true,"client_session_id":"01913dd8-8e85-75fd-9e0f-fb52127a79a0"}}}}}},"/api/v1/accounts/{account_id}/whatsapp_web_calls/{id}/video_stats":{"get":{"tags":["WhatsApp Web Calls"],"operationId":"auto_get_api_v1_accounts_account_id_whatsapp_web_calls_id_video_stats","summary":"Video stats whatsapp web calls","description":"Performs the video stats operation on the targeted whatsapp web call resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Provider video telemetry grouped by media SSRC for the claimed call session.","content":{"application/json":{"schema":{"type":"object","required":["ssrcs"],"properties":{"ssrcs":{"type":"object","description":"Per-stream counters keyed by the provider SSRC identifier.","additionalProperties":{"type":"object","properties":{"received":{"type":"integer","minimum":0},"delivered":{"type":"integer","minimum":0},"shed":{"type":"integer","minimum":0}},"additionalProperties":true}}},"additionalProperties":true},"example":{"ssrcs":{"123":{"received":10,"delivered":9,"shed":1}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"client_session_id","in":"query","required":false,"schema":{"type":"string","maxLength":128,"description":"Stable browser-tab session id. Required for pipeline-v2 call ownership; omitted only by legacy pipeline-v1 clients."},"description":"Browser-tab owner used to recover pipeline-v2 calls without exposing another tab."}]}},"/api/v1/accounts/{account_id}/whatsapp_web_calls/active":{"get":{"tags":["WhatsApp Web Calls"],"operationId":"auto_get_api_v1_accounts_account_id_whatsapp_web_calls_active","summary":"Recover active WhatsApp Web calls visible to the authenticated agent","description":"Returns metadata-only recovery snapshots. `conversation_id` is the public conversation display_id used by the dashboard; `conversation_record_id` preserves the physical FK.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Active WhatsApp Web calls visible to the current agent.","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","required":["id","call_id","provider","status","direction","conversation_id","conversation_record_id","inbox_id","state","revision"],"properties":{"id":{"type":"integer"},"call_id":{"type":"string"},"provider":{"type":"string","enum":["whatsapp_web"],"description":"Call provider (WhatsApp Web via the WazMeow gateway)."},"status":{"type":"string","enum":["ringing","in-progress","completed","no-answer","failed"],"description":"Display call status (hyphenated form of the stored call status)."},"state":{"type":"string"},"revision":{"type":"integer"},"direction":{"type":"string","enum":["inbound","outbound"],"description":"Call direction (relative to the business number)."},"conversation_id":{"type":"integer","description":"Conversation display_id used by dashboard routes."},"conversation_record_id":{"type":"integer","description":"Internal conversation primary key."},"inbox_id":{"type":"integer"},"logical_inbox_id":{"type":"integer","description":"Present when the physical Web signaling inbox is projected as a unified Cloud inbox."},"message_id":{"type":["integer","null"]},"accepted_by_agent_id":{"type":["integer","null"]},"claimed_by_agent_id":{"type":["integer","null"]},"claim_expires_at":{"type":["string","null"],"format":"date-time"},"elapsed_seconds":{"type":"integer"},"video":{"type":"boolean"},"is_group":{"type":"boolean"},"group_jid":{"type":["string","null"]},"caller":{"type":"object","properties":{"name":{"type":["string","null"]},"phone":{"type":["string","null"]},"avatar":{"type":["string","null"]},"originator":{"type":["string","null"],"description":"Best-effort display identity of the group participant who started the call."},"group_jid":{"type":["string","null"],"description":"WhatsApp group identity, present only for group calls."}},"additionalProperties":false}}}},"example":[{"id":1,"call_id":"sample call id","provider":"whatsapp_web","status":"ringing","state":"active","revision":1,"direction":"inbound","conversation_id":1,"conversation_record_id":1,"inbox_id":1,"logical_inbox_id":1,"message_id":1,"accepted_by_agent_id":1,"claimed_by_agent_id":1,"claim_expires_at":"2026-01-15T10:30:00.000Z","elapsed_seconds":60,"video":true,"is_group":true,"group_jid":"sample group jid","caller":{"name":"Sample Name","phone":"+5511999998888","avatar":"sample avatar","originator":"sample originator","group_jid":"sample group jid"}}]}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"client_session_id","in":"query","required":false,"schema":{"type":"string","maxLength":128,"description":"Stable browser-tab session id. Required for pipeline-v2 call ownership; omitted only by legacy pipeline-v1 clients."},"description":"Browser-tab owner used to recover pipeline-v2 calls without exposing another tab."}]}},"/api/v1/accounts/{account_id}/whatsapp_web_calls/initiate":{"post":{"tags":["WhatsApp Web Calls"],"operationId":"auto_post_api_v1_accounts_account_id_whatsapp_web_calls_initiate","summary":"Start a WhatsApp Web call","description":"Dials a 1:1 or group WhatsApp Web call and returns the freshly materialized platform call row plus owner-scoped stream capabilities. `conversation_id` is the conversation display_id; the internal FK is returned separately as `conversation_record_id`.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Call created and ready for the owner tab to open its media streams.","content":{"application/json":{"schema":{"type":"object","required":["status","call_id","id","provider","inbox_id","conversation_id","conversation_record_id"],"properties":{"status":{"type":"string","enum":["calling"],"description":"Call state right after the initiate request is accepted."},"call_id":{"type":"string"},"id":{"type":"integer"},"message_id":{"type":"integer"},"provider":{"type":"string","enum":["whatsapp_web"],"description":"Call provider (WhatsApp Web via the WazMeow gateway)."},"inbox_id":{"type":"integer"},"logical_inbox_id":{"type":"integer","description":"Present when the physical Web signaling inbox is projected as a unified Cloud inbox."},"conversation_id":{"type":"integer","description":"Conversation display_id used by dashboard routes."},"conversation_record_id":{"type":"integer","description":"Internal conversation primary key."},"stream_path":{"type":"string"},"stream_ticket":{"type":"string"},"video":{"type":"boolean"},"is_group":{"type":"boolean"},"group_jid":{"type":["string","null"]},"video_stream_path":{"type":"string"},"video_stream_ticket":{"type":"string"},"events_path":{"type":"string"},"events_ticket":{"type":"string"},"video_state_path":{"type":"string"},"video_state_ticket":{"type":"string"}}},"example":{"status":"calling","call_id":"sample call id","id":1,"message_id":1,"provider":"whatsapp_web","inbox_id":1,"logical_inbox_id":1,"conversation_id":1,"conversation_record_id":1,"stream_path":"sample stream path","stream_ticket":"sample stream ticket","video":true,"is_group":true,"group_jid":"sample group jid","video_stream_path":"sample video stream path","video_stream_ticket":"sample video stream ticket","events_path":"sample events path","events_ticket":"sample events ticket","video_state_path":"sample video state path","video_state_ticket":"sample video state ticket"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["conversation_id","client_session_id"],"properties":{"conversation_id":{"type":"integer","description":"Conversation display_id to call."},"client_session_id":{"type":"string","maxLength":128,"description":"Stable browser-tab session id. Required for pipeline-v2 call ownership; omitted only by legacy pipeline-v1 clients."},"video":{"type":"boolean","description":"Requests video when the inbox supports it."},"targets":{"type":"array","items":{"type":"string"},"description":"Optional explicit group participant JIDs; omitted to ring the whole roster."},"idempotency_key":{"type":"string","maxLength":255,"description":"Caller-generated retry key for one outbound dial attempt."}},"additionalProperties":false},"example":{"conversation_id":365,"client_session_id":"01913dd8-8e85-75fd-9e0f-fb52127a79a0","video":false,"idempotency_key":"dial-365-01913dd8","targets":["sample target"]}}}}}},"/api/v1/accounts/{account_id}/whatsapp_web_calls/create_link":{"post":{"tags":["WhatsApp Web Calls"],"operationId":"auto_post_api_v1_accounts_account_id_whatsapp_web_calls_create_link","summary":"Create link whatsapp web calls","description":"Performs the create link operation on the targeted whatsapp web call resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"WhatsApp call link created and mirrored as an outgoing conversation message.","content":{"application/json":{"schema":{"type":"object","required":["token","url","video","message_id"],"properties":{"token":{"type":"string"},"url":{"type":"string","format":"uri"},"video":{"type":"boolean"},"message_id":{"type":"integer"}},"additionalProperties":false},"example":{"token":"sample-call-link","url":"https://call.whatsapp.com/video/sample-call-link","video":true,"message_id":918273}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"video":{"type":"string"},"enabled":{"type":"boolean"}}},"example":{"video":"sample video","enabled":true}}}}}},"/api/v1/accounts/{account_id}/whatsapp_web_calls/preview_link":{"get":{"tags":["WhatsApp Web Calls"],"operationId":"auto_get_api_v1_accounts_account_id_whatsapp_web_calls_preview_link","summary":"Preview link whatsapp web calls","description":"Performs the preview link operation on the targeted whatsapp web call resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Gateway metadata for the supplied WhatsApp call-link token.","content":{"application/json":{"schema":{"type":"object","required":["token","video","approvalRequired","isAdmin"],"properties":{"token":{"type":"string"},"video":{"type":"boolean"},"approvalRequired":{"type":"boolean"},"isAdmin":{"type":"boolean"},"creator":{"type":["string","null"]},"creatorPhone":{"type":["string","null"]}},"additionalProperties":true},"example":{"token":"sample-call-link","video":true,"approvalRequired":true,"isAdmin":false,"creator":"sample creator","creatorPhone":"sample creatorPhone"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/whatsapp_web_calls/join_link":{"post":{"tags":["WhatsApp Web Calls"],"operationId":"auto_post_api_v1_accounts_account_id_whatsapp_web_calls_join_link","summary":"Join link whatsapp web calls","description":"Performs the join link operation on the targeted whatsapp web call resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ringing","in-progress","completed","no-answer","failed"],"description":"Display call status (hyphenated form of the stored call status)."},"call_id":{"type":"integer"},"id":{"type":"integer"},"message_id":{"type":"integer"},"provider":{"type":"string","enum":["whatsapp_web"],"description":"Call provider (WhatsApp Web via the WazMeow gateway)."},"inbox_id":{"type":"integer"},"logical_inbox_id":{"type":"integer"},"pipeline_version":{"type":"string"},"conversation_id":{"type":"integer"},"conversation_record_id":{"type":"integer"},"legacy_stream_fallback_allowed":{"type":"string"},"stream_path":{"type":"string"},"stream_ticket":{"type":"string"},"video":{"type":["boolean","null"]},"is_group":{"type":["boolean","null"]},"group_jid":{"type":["string","null"]},"video_stream_path":{"type":"string"},"video_stream_ticket":{"type":"string"},"events_path":{"type":"string"},"events_ticket":{"type":"string"},"video_state_path":{"type":"string"},"video_state_ticket":{"type":"string"}}},"example":{"status":"ringing","call_id":1,"id":1,"message_id":1,"provider":"whatsapp_web","inbox_id":1,"logical_inbox_id":1,"pipeline_version":"sample pipeline version","conversation_id":1,"conversation_record_id":1,"legacy_stream_fallback_allowed":"sample legacy stream fallback allowed","stream_path":"sample stream path","stream_ticket":"sample stream ticket","video":true,"is_group":true,"group_jid":"sample group jid","video_stream_path":"sample video stream path","video_stream_ticket":"sample video stream ticket","events_path":"sample events path","events_ticket":"sample events ticket","video_state_path":"sample video state path","video_state_ticket":"sample video state ticket"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"video":{"type":"string"},"token":{"type":"string"},"idempotency_key":{"type":"string"}}},"example":{"video":"sample video","token":"sample-token","idempotency_key":"sample-token"}}}}}},"/api/v1/accounts/{account_id}/whatsapp_web_calls/{id}":{"get":{"tags":["WhatsApp Web Calls"],"operationId":"auto_get_api_v1_accounts_account_id_whatsapp_web_calls_id","summary":"Read WhatsApp Web call metadata and owner-scoped recovery fields","description":"Returns WhatsApp Web call metadata. `conversation_id` is the conversation display_id used by the dashboard router; `conversation_record_id` preserves the internal FK.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Authorized WhatsApp Web call payload.","content":{"application/json":{"schema":{"type":"object","required":["id","call_id","provider","status","direction","conversation_id","conversation_record_id","inbox_id"],"properties":{"id":{"type":"integer"},"call_id":{"type":"string"},"provider":{"type":"string","enum":["whatsapp_web"],"description":"Call provider (WhatsApp Web via the WazMeow gateway)."},"status":{"type":"string","enum":["ringing","in-progress","completed","no-answer","failed"],"description":"Display call status (hyphenated form of the stored call status)."},"direction":{"type":"string","enum":["inbound","outbound"],"description":"Call direction (relative to the business number)."},"conversation_id":{"type":"integer","description":"Conversation display_id used by dashboard routes."},"conversation_record_id":{"type":"integer","description":"Internal conversation primary key."},"inbox_id":{"type":"integer"},"logical_inbox_id":{"type":"integer","description":"Present when the physical Web signaling inbox is projected as a unified Cloud inbox."},"message_id":{"type":["integer","null"]},"accepted_by_agent_id":{"type":["integer","null"]},"elapsed_seconds":{"type":"integer"},"stream_path":{"type":"string"},"stream_ticket":{"type":"string"},"video":{"type":"boolean"},"is_group":{"type":"boolean"},"group_jid":{"type":["string","null"]},"video_stream_path":{"type":"string"},"video_stream_ticket":{"type":"string"},"events_path":{"type":"string"},"events_ticket":{"type":"string"},"video_state_path":{"type":"string"},"video_state_ticket":{"type":"string"},"caller":{"type":"object","properties":{"name":{"type":["string","null"]},"phone":{"type":["string","null"]},"avatar":{"type":["string","null"]},"originator":{"type":["string","null"],"description":"Best-effort display identity of the group participant who started the call."},"group_jid":{"type":["string","null"],"description":"WhatsApp group identity, present only for group calls."}},"additionalProperties":false}}},"example":{"id":1,"call_id":"sample call id","provider":"whatsapp_web","status":"ringing","direction":"inbound","conversation_id":1,"conversation_record_id":1,"inbox_id":1,"logical_inbox_id":1,"message_id":1,"accepted_by_agent_id":1,"elapsed_seconds":60,"stream_path":"sample stream path","stream_ticket":"sample stream ticket","video":true,"is_group":true,"group_jid":"sample group jid","video_stream_path":"sample video stream path","video_stream_ticket":"sample video stream ticket","events_path":"sample events path","events_ticket":"sample events ticket","video_state_path":"sample video state path","video_state_ticket":"sample video state ticket","caller":{"name":"Sample Name","phone":"+5511999998888","avatar":"sample avatar","originator":"sample originator","group_jid":"sample group jid"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"client_session_id","in":"query","required":false,"schema":{"type":"string","maxLength":128,"description":"Stable browser-tab session id. Required for pipeline-v2 call ownership; omitted only by legacy pipeline-v1 clients."},"description":"Browser-tab owner used to recover pipeline-v2 calls without exposing another tab."}]}},"/api/v1/accounts/{account_id}/whatsapp_calls/{id}/claim":{"post":{"tags":["WhatsApp Calls"],"operationId":"auto_post_api_v1_accounts_account_id_whatsapp_calls_id_claim","summary":"Claim an inbound WhatsApp call for one agent tab","description":"Atomically claims a ringing inbound call for an online account agent using its lifecycle revision. The raw claim token is returned only by this operation; only its SHA-256 digest is stored. A retry from the same authenticated agent tab while the claim is active deterministically recovers the same capability without persisting it. SDP decryption and fresh WebRTC configuration preparation complete before the CAS claim is committed, so those failures do not strand the call behind an undisclosed token.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The call is owned by this authenticated agent tab.","content":{"application/json":{"schema":{"type":"object","required":["id","call_id","state","revision","claim_token","claim_expires_at","sdp_offer","webrtc_config"],"properties":{"id":{"type":"integer"},"call_id":{"type":"string"},"provider":{"type":"string","enum":["whatsapp"],"description":"Call provider (WhatsApp Cloud)."},"status":{"type":"string","enum":["ringing","in-progress","completed","no-answer","failed"],"description":"Display call status (hyphenated form of the stored call status)."},"direction":{"type":"string","enum":["inbound","outbound"],"description":"Call direction (relative to the business number)."},"conversation_id":{"type":"integer"},"conversation_record_id":{"type":"integer"},"inbox_id":{"type":"integer"},"logical_inbox_id":{"type":"integer","description":"Present when physical call ownership differs from the unified outward inbox identity."},"message_id":{"type":"integer"},"accepted_by_agent_id":{"type":["integer","null"]},"elapsed_seconds":{"type":"integer"},"state":{"type":"string","enum":["claimed"]},"revision":{"type":"integer"},"claimed_by_agent_id":{"type":"integer"},"claim_token":{"type":"string"},"claim_expires_at":{"type":"string","format":"date-time"},"sdp_offer":{"type":"string"},"ice_servers":{"type":"array","items":{"type":"object","required":["urls"],"properties":{"urls":{"type":"array","items":{"type":"string"}},"username":{"type":"string"},"credential":{"type":"string"}},"additionalProperties":false}},"ice_transport_policy":{"type":"string","enum":["all","relay"]},"webrtc_config":{"type":"object","required":["ice_servers","ice_transport_policy","expires_at"],"properties":{"ice_servers":{"type":"array","items":{"type":"object","required":["urls"],"properties":{"urls":{"type":"array","items":{"type":"string"}},"username":{"type":"string"},"credential":{"type":"string"}},"additionalProperties":false}},"ice_transport_policy":{"type":"string","enum":["all","relay"]},"expires_at":{"type":"string","format":"date-time"}},"additionalProperties":false},"caller":{"type":"object","properties":{"name":{"type":["string","null"]},"phone":{"type":["string","null"]},"avatar":{"type":["string","null"]}},"additionalProperties":false}}},"example":{"id":91,"call_id":"wacid.inbound.91","provider":"whatsapp","status":"ringing","direction":"inbound","conversation_id":365,"inbox_id":42,"message_id":918273,"accepted_by_agent_id":null,"elapsed_seconds":0,"state":"claimed","revision":1,"claimed_by_agent_id":7,"claim_token":"1vXQW9w5y-X5JjzPvQdV2D_mEPsSyF4PiuMrp53Dd8A","claim_expires_at":"2026-08-15T12:02:00Z","sdp_offer":"v=0\r\ns=-\r\n","ice_servers":[{"urls":["stun:stun.example.net:3478"],"username":"sample username","credential":"sample credential"}],"ice_transport_policy":"all","webrtc_config":{"ice_servers":[{"urls":["stun:stun.example.net:3478"],"username":"sample username","credential":"sample credential"}],"ice_transport_policy":"all","expires_at":"2026-08-15T12:10:00Z"},"caller":{"name":"Ana","phone":"+5511999999999","avatar":null},"conversation_record_id":1,"logical_inbox_id":1}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"409":{"description":"Another tab owns the claim or expected_revision is stale.","content":{"application/json":{"schema":{"type":"object","required":["error","state","revision"],"properties":{"error":{"type":"string"},"state":{"type":"string"},"revision":{"type":"integer"}}},"example":{"error":"Another agent tab is already answering this call.","state":"claimed","revision":1}}}},"429":{"description":"Per-account/authenticated-credential mint limit exceeded; honor Retry-After before retrying."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["client_session_id","expected_revision"],"properties":{"client_session_id":{"type":"string","maxLength":128},"expected_revision":{"type":"integer","minimum":0}}},"example":{"client_session_id":"01913dd8-8e85-75fd-9e0f-fb52127a79a0","expected_revision":0}}}}}},"/api/v1/accounts/{account_id}/whatsapp_calls/{id}/release":{"post":{"tags":["WhatsApp Calls"],"operationId":"auto_post_api_v1_accounts_account_id_whatsapp_calls_id_release","summary":"Release an inbound WhatsApp call claim","description":"Releases the claim only when the authenticated agent, tab id and raw capability match. A tab that could not prepare its WebRTC answer may send an optional sanitized `reason`; it is logged and kept as the call's last release diagnostic, and never changes the release outcome (the call keeps ringing, it is never rejected).","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Claim released; the call can ring another tab again.","content":{"application/json":{"schema":{"type":"object","required":["id","state","revision"],"properties":{"id":{"type":"integer"},"state":{"type":"string"},"revision":{"type":"integer"}}},"example":{"id":91,"state":"ringing","revision":2}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"403":{"description":"Claim capability is missing, expired or owned by another tab.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}},"example":{"error":"This call claim expired or belongs to another agent tab."}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["client_session_id","claim_token","expected_revision"],"properties":{"client_session_id":{"type":"string","maxLength":128},"claim_token":{"type":"string"},"expected_revision":{"type":"integer","minimum":0},"reason":{"type":"object","additionalProperties":false,"description":"Optional browser diagnostic for why the tab released the claim. The server whitelists the stage, keeps only identifier characters in the name and strips SDP, IP addresses, phone numbers and tokens from the message.","properties":{"stage":{"type":"string","description":"Browser step that failed; unknown values are stored as `unknown`.","enum":["media","recording_settings","missing_offer","peer_connection","set_remote_description","create_answer","set_local_description","ice_gathering","ice","unknown"]},"name":{"type":"string","maxLength":64,"description":"Browser error name, such as InvalidAccessError."},"message":{"type":"string","maxLength":200,"description":"Sanitized, truncated browser error message."}}}}},"example":{"client_session_id":"01913dd8-8e85-75fd-9e0f-fb52127a79a0","claim_token":"1vXQW9w5y-X5JjzPvQdV2D_mEPsSyF4PiuMrp53Dd8A","expected_revision":1,"reason":{"stage":"set_remote_description","name":"InvalidAccessError","message":"Failed to set remote offer sdp."}}}}}}},"/api/v1/accounts/{account_id}/whatsapp_calls/{id}/pre_accept":{"post":{"tags":["WhatsApp Calls"],"operationId":"auto_post_api_v1_accounts_account_id_whatsapp_calls_id_pre_accept","summary":"Pre-accept an inbound WhatsApp call with the browser SDP answer","description":"Sends Meta's pre_accept action after validating the tab claim. The browser must wait for ICE connected or completed before calling accept. The command is durable and a transport-ambiguous result is never retried automatically.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Meta confirmed pre_accept; wait for ICE before accept.","content":{"application/json":{"schema":{"type":"object","required":["id","state","revision"],"properties":{"id":{"type":"integer"},"state":{"type":"string","enum":["negotiating"]},"revision":{"type":"integer"}}},"example":{"id":91,"state":"negotiating","revision":2}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["sdp_answer","client_session_id","claim_token","expected_revision","idempotency_key"],"properties":{"sdp_answer":{"type":"string"},"client_session_id":{"type":"string","maxLength":128},"claim_token":{"type":"string"},"expected_revision":{"type":"integer","minimum":0},"idempotency_key":{"type":"string"}}},"example":{"sdp_answer":"v=0\r\ns=-\r\n","client_session_id":"01913dd8-8e85-75fd-9e0f-fb52127a79a0","claim_token":"1vXQW9w5y-X5JjzPvQdV2D_mEPsSyF4PiuMrp53Dd8A","expected_revision":1,"idempotency_key":"01913dd8-dada-77d1-93a8-2d7a52a70d86"}}}}}},"/api/v1/accounts/{account_id}/whatsapp_calls/{id}/accept":{"post":{"tags":["WhatsApp Calls"],"operationId":"auto_post_api_v1_accounts_account_id_whatsapp_calls_id_accept","summary":"Accept a pre-negotiated inbound WhatsApp call","description":"For durable pipeline-v2 calls, validates the live agent-tab claim and requires a successful pre_accept command from the same client_session_id and SDP answer before sending Meta's accept. The legacy combined accept remains server-compatible only for pipeline-v1 calls during rollout.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Meta accepted the call and the native lifecycle is in progress.","content":{"application/json":{"schema":{"type":"object","required":["id","call_id","provider","status","state","revision"],"properties":{"id":{"type":"integer"},"call_id":{"type":"string"},"provider":{"type":"string","enum":["whatsapp"],"description":"Call provider (WhatsApp Cloud)."},"status":{"type":"string","enum":["ringing","in-progress","completed","no-answer","failed"],"description":"Display call status (hyphenated form of the stored call status)."},"state":{"type":"string","enum":["in_progress"]},"revision":{"type":"integer"},"direction":{"type":"string","enum":["inbound"],"description":"Call direction (relative to the business number)."},"conversation_id":{"type":"integer"},"conversation_record_id":{"type":"integer"},"inbox_id":{"type":"integer"},"logical_inbox_id":{"type":"integer","description":"Present when physical call ownership differs from the unified outward inbox identity."},"accepted_by_agent_id":{"type":"integer"}}},"example":{"id":1,"call_id":"sample call id","provider":"whatsapp","status":"ringing","state":"in_progress","revision":1,"direction":"inbound","conversation_id":1,"conversation_record_id":1,"inbox_id":1,"logical_inbox_id":1,"accepted_by_agent_id":1}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"403":{"description":"The live call is claimed by another agent tab (call_ended false). Messages are localized in the agent locale.","content":{"application/json":{"schema":{"type":"object","required":["error","call_ended"],"properties":{"error":{"type":"string"},"call_ended":{"type":"boolean","enum":[false]}}},"example":{"error":"This call claim expired or belongs to another agent tab. Reopen the call and try again.","call_ended":false}}}},"409":{"description":"The call already ended before the command landed (call_ended true), or the lifecycle revision is stale / a competing tab owns the live call.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"call_ended":{"type":"boolean"},"state":{"type":["string","null"]},"revision":{"type":["integer","null"]}}},"example":{"error":"This call has already ended","call_ended":true,"state":"no_answer","revision":1}}}},"422":{"description":"pre_accept is missing/mismatched, or Meta definitively rejected signaling."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["sdp_answer","client_session_id","claim_token","expected_revision","idempotency_key"],"properties":{"sdp_answer":{"type":"string"},"client_session_id":{"type":"string","maxLength":128},"claim_token":{"type":"string"},"expected_revision":{"type":"integer","minimum":0},"idempotency_key":{"type":"string"}}},"example":{"sdp_answer":"sample sdp answer","client_session_id":"sample client session id","claim_token":"sample-token","expected_revision":1,"idempotency_key":"sample-token"}}}}}},"/api/v1/accounts/{account_id}/whatsapp_calls/{id}/reject":{"post":{"tags":["WhatsApp Calls"],"operationId":"auto_post_api_v1_accounts_account_id_whatsapp_calls_id_reject","summary":"Reject a ringing inbound WhatsApp call","description":"Rejects only an inbound ringing call visible in the authenticated agent's exact online audience. Pipeline-v2 calls also require the live claim capability for this browser tab. Outbound calls can never be rejected through this operation.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Call rejected and finalized idempotently.","content":{"application/json":{"schema":{"type":"object","required":["id","status","revision"],"properties":{"id":{"type":"integer"},"status":{"type":"string","enum":["rejected"],"description":"Display call status (hyphenated form of the stored call status)."},"revision":{"type":"integer"}}},"example":{"id":1,"status":"rejected","revision":1}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"403":{"description":"Agent is outside the audience or the claim is not valid for this tab."},"422":{"description":"Call is not a ringing inbound call or Meta rejected the action."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["client_session_id","claim_token","expected_revision","idempotency_key"],"properties":{"client_session_id":{"type":"string","maxLength":128},"claim_token":{"type":"string"},"expected_revision":{"type":"integer","minimum":0},"idempotency_key":{"type":"string"}}},"example":{"client_session_id":"sample client session id","claim_token":"sample-token","expected_revision":1,"idempotency_key":"sample-token"}}}}}},"/api/v1/accounts/{account_id}/whatsapp_calls/{id}/terminate":{"post":{"tags":["WhatsApp Calls"],"operationId":"auto_post_api_v1_accounts_account_id_whatsapp_calls_id_terminate","summary":"Terminate an owned WhatsApp call","description":"Terminates provider media using a durable command. Outbound and in-progress calls require the accepted agent and exact client_session_id that owns the PeerConnection. A pipeline-v2 inbound call that is still negotiating additionally requires its live claim token. Ambiguous provider outcomes are quarantined and are never retried blindly.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Call terminated and finalized idempotently.","content":{"application/json":{"schema":{"type":"object","required":["id","status","revision"],"properties":{"id":{"type":"integer"},"status":{"type":"string","enum":["completed","no-answer"],"description":"Display call status (hyphenated form of the stored call status)."},"revision":{"type":"integer"}}},"example":{"id":1,"status":"completed","revision":1}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"403":{"description":"Call belongs to another agent/browser session or the inbound claim is invalid."},"422":{"description":"Meta definitively rejected signaling or the outcome is transport-ambiguous."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["client_session_id","idempotency_key"],"properties":{"client_session_id":{"type":"string","maxLength":128},"claim_token":{"type":"string","description":"Required for an inbound pipeline-v2 call."},"expected_revision":{"type":"integer","minimum":0,"description":"Required when claim_token is supplied."},"idempotency_key":{"type":"string"}}},"example":{"client_session_id":"sample client session id","claim_token":"sample-token","expected_revision":1,"idempotency_key":"sample-token"}}}}}},"/api/v1/accounts/{account_id}/whatsapp_calls/{id}/upload_recording":{"post":{"tags":["WhatsApp Calls"],"operationId":"auto_post_api_v1_accounts_account_id_whatsapp_calls_id_upload_recording","summary":"Attach an owned WhatsApp call recording","description":"Attaches one recording idempotently to the call message and native Call after the call has actually connected (started_at is present). The accepted agent owns the operation; an active pipeline-v2 call also requires its exact client_session_id. Empty files, files over 50 MB, and files whose Marcel-detected bytes are not an allowed audio/WebM container are rejected before Active Storage. Terminal calls may be uploaded by their accepted owner after the short claim/session lease has been cleared.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Recording attached, or an earlier identical operation already attached audio.","content":{"application/json":{"schema":{"type":"object","required":["id","status"],"properties":{"id":{"type":"integer"},"status":{"type":"string","enum":["uploaded","already_uploaded"],"description":"Outcome of attaching the call recording (idempotent)."}}},"example":{"id":1,"status":"uploaded"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"403":{"description":"Authenticated agent/tab does not own the call media."},"422":{"description":"Recording is disabled, empty, oversized, has invalid bytes, or the call has no message."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["recording"],"properties":{"recording":{"type":"string","format":"binary"},"client_session_id":{"type":"string","maxLength":128,"description":"Required while a pipeline-v2 call is active."}}}}}}}},"/api/v1/accounts/{account_id}/whatsapp_calls/active":{"get":{"tags":["WhatsApp Calls"],"operationId":"auto_get_api_v1_accounts_account_id_whatsapp_calls_active","summary":"Recover the authenticated agent's active WhatsApp call metadata","description":"Returns a bounded metadata-only snapshot after mount or WebSocket reconnect. Eligible ringing inbound calls follow the same online recipient rules as realtime delivery; in-progress and outbound calls are returned only to their accepted/initiating agent and the browser tab whose client_session_id owns the live PeerConnection. A hard refresh creates a new id and therefore never presents an old media session as recoverable. SDP, ICE servers, TURN credentials and claim capabilities are never included.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Active calls visible to this agent, newest first.","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","required":["id","call_id","provider","status","direction","conversation_id","conversation_record_id","inbox_id","state","revision"],"properties":{"id":{"type":"integer"},"call_id":{"type":"string"},"provider":{"type":"string","enum":["whatsapp"],"description":"Call provider (WhatsApp Cloud)."},"status":{"type":"string","enum":["ringing","in-progress","completed","no-answer","failed"],"description":"Display call status (hyphenated form of the stored call status)."},"direction":{"type":"string","enum":["inbound","outbound"],"description":"Call direction (relative to the business number)."},"conversation_id":{"type":"integer","description":"Conversation display_id used by dashboard routes."},"conversation_record_id":{"type":"integer","description":"Internal conversation primary key."},"inbox_id":{"type":"integer"},"logical_inbox_id":{"type":"integer","description":"Present when physical call ownership differs from the unified outward inbox identity."},"message_id":{"type":["integer","null"]},"accepted_by_agent_id":{"type":["integer","null"]},"state":{"type":"string"},"revision":{"type":"integer"},"caller":{"type":"object","properties":{"name":{"type":["string","null"]},"phone":{"type":["string","null"]},"avatar":{"type":["string","null"]}},"additionalProperties":false}}}},"example":[{"id":1,"call_id":"sample call id","provider":"whatsapp","status":"ringing","direction":"inbound","conversation_id":1,"conversation_record_id":1,"inbox_id":1,"logical_inbox_id":1,"message_id":1,"accepted_by_agent_id":1,"state":"active","revision":1,"caller":{"name":"Sample Name","phone":"+5511999998888","avatar":"sample avatar"}}]}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"client_session_id","in":"query","required":true,"schema":{"type":"string","maxLength":128},"description":"Ephemeral id retained across Cable reconnects in the current browser tab."}]}},"/api/v1/accounts/{account_id}/whatsapp_calls/webrtc_config":{"get":{"tags":["WhatsApp Calls"],"operationId":"auto_get_api_v1_accounts_account_id_whatsapp_calls_webrtc_config","summary":"Get ephemeral WhatsApp call WebRTC configuration","description":"Returns STUN/TURN servers for an inbox assigned to the authenticated agent. Coturn REST credentials are generated for this response only and expire at expires_at. Their lifetime is at least calls_max_seconds plus a safety margin; invalid shorter operator limits fail closed. ice_transport_policy is either all (TURN fallback) or relay (TURN mandatory).","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Fresh browser WebRTC configuration.","content":{"application/json":{"schema":{"type":"object","required":["ice_servers","ice_transport_policy","expires_at"],"properties":{"ice_servers":{"type":"array","items":{"type":"object","required":["urls"],"properties":{"urls":{"type":"array","items":{"type":"string"}},"username":{"type":"string"},"credential":{"type":"string"}},"additionalProperties":false}},"ice_transport_policy":{"type":"string","enum":["all","relay"]},"expires_at":{"type":"string","format":"date-time","description":"Coturn REST credential expiry. For a configured static managed-provider pair this is only the browser configuration refresh horizon; the provider controls the real credential lifetime."}}},"example":{"ice_servers":[{"urls":["stun:stun.example.net:3478"],"username":"sample username","credential":"sample credential"},{"urls":["turns:turn.example.net:443?transport=tcp"],"username":"1786795800:1:42:7","credential":"sample-credential"}],"ice_transport_policy":"all","expires_at":"2026-08-15T20:00:00Z"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"503":{"description":"STUN/TURN configuration is incomplete or invalid.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}},"example":{"error":"Secure media configuration is unavailable. Check the STUN/TURN configuration and try again."}}}},"429":{"description":"Per-account/authenticated-credential mint limit exceeded; honor Retry-After before retrying."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"inbox_id","in":"query","required":true,"schema":{"type":"integer"},"description":"WhatsApp Cloud inbox used by the call."}]}},"/api/v1/accounts/{account_id}/whatsapp_calls/initiate":{"post":{"tags":["WhatsApp Calls"],"operationId":"auto_post_api_v1_accounts_account_id_whatsapp_calls_initiate","summary":"Place an outbound WhatsApp call","description":"Durably creates the conversation, provisional Call and encrypted command ledger before forwarding the browser's SDP offer to Meta. A transport-ambiguous result is never retried blindly. The caller may identify an existing conversation, or provide a contact and inbox. When the contact has not granted call permission (Meta 138006) nothing is dialled and the response describes what the dashboard should do next: `permission_required` (nothing was sent — open the composer seeded with `suggested_body`), `permission_pending` (a request is already in flight, `retry_after_seconds` left), or `permission_requested` when `permission_body` was supplied and sent straight away.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Meta accepted the dial and the native platform call was materialized.","content":{"application/json":{"schema":{"type":"object","required":["status","call_id","id","provider","conversation_id","conversation_record_id","inbox_id"],"properties":{"status":{"type":"string","enum":["calling"],"description":"Call state right after the initiate request is accepted."},"call_id":{"type":"string","description":"Meta provider call id."},"id":{"type":"integer","description":"Native platform call id."},"message_id":{"type":"integer","description":"Native voice_call message id."},"provider":{"type":"string","enum":["whatsapp"],"description":"Call provider (WhatsApp Cloud)."},"conversation_id":{"type":"integer","description":"display_id of the existing or newly-created conversation."},"conversation_record_id":{"type":"integer","description":"Internal database id of the existing or newly-created conversation."},"inbox_id":{"type":"integer"},"logical_inbox_id":{"type":"integer","description":"Present when physical call ownership differs from the unified outward inbox identity."}}},"example":{"status":"calling","call_id":"sample call id","id":1,"message_id":1,"provider":"whatsapp","conversation_id":1,"conversation_record_id":1,"inbox_id":1,"logical_inbox_id":1}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"422":{"description":"Validation/provider failure, or a permission flow outcome (`permission_required`, `permission_pending`, or `permission_requested`). Permission outcomes include conversation_id so a contact-surface dial can continue in the newly-created timeline.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["permission_required","permission_pending","permission_requested"],"description":"Call state right after the initiate request is accepted."},"conversation_id":{"type":"integer"},"conversation_record_id":{"type":"integer"},"retry_after_seconds":{"type":"integer"},"suggested_body":{"type":"string"},"error":{"type":"string"}}},"example":{"status":"permission_required","conversation_id":1,"conversation_record_id":1,"retry_after_seconds":60,"suggested_body":"sample suggested body","error":"sample error"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["sdp_offer","client_session_id"],"oneOf":[{"type":"object","required":["conversation_id"],"properties":{"conversation_id":{"type":"integer"}}},{"type":"object","required":["contact_id","inbox_id"],"properties":{"contact_id":{"type":"integer"},"inbox_id":{"type":"integer"}}}],"properties":{"conversation_id":{"type":"integer","description":"display_id of an existing conversation to call."},"contact_id":{"type":"integer","description":"Contact to call when no conversation exists; must be supplied with inbox_id."},"inbox_id":{"type":"integer","description":"WhatsApp Cloud inbox used with contact_id when conversation_id is absent."},"sdp_offer":{"type":"string","description":"RFC 4566 SDP offer produced by the agent's browser."},"idempotency_key":{"type":"string","description":"Unique browser attempt id. Reusing it with the same payload returns the recorded success or ambiguity without placing a second Graph call."},"client_session_id":{"type":"string","maxLength":128,"description":"Ephemeral id of the browser tab that owns the PeerConnection. It scopes same-tab reconnect snapshots and is never a substitute for authentication."},"permission_body":{"type":"string","maxLength":1024,"description":"Optional. When present and the contact has no permission yet, the permission request is sent immediately with this body instead of returning `permission_required`."}}},"example":{"contact_id":918,"inbox_id":42,"idempotency_key":"initiate-01913dd8-dada-77d1-93a8-2d7a52a70d86","client_session_id":"01913dd8-8e85-75fd-9e0f-fb52127a79a0","sdp_offer":"v=0\r\no=- 46117317 2 IN IP4 127.0.0.1\r\ns=-\r\n","permission_body":"Podemos te ligar sobre o seu atendimento?"}}}}}},"/api/v1/accounts/{account_id}/whatsapp_calls/request_permission":{"post":{"tags":["WhatsApp Calls"],"operationId":"auto_post_api_v1_accounts_account_id_whatsapp_calls_request_permission","summary":"Send a WhatsApp call permission request","description":"Sends the Meta `call_permission_request` interactive message to the conversation's contact and mirrors it into the thread as a real outgoing message (source_id = the returned wamid, so delivery webhooks match it and the channel never re-sends it). When `body` is omitted the inbox override `provider_config.call_permission_request_body` is used, falling back to the default text resolved in the ACCOUNT language — the contact never receives the agent's dashboard locale. Throttled to one request per conversation every 5 minutes. Meta error 138017 (a permanent permission already exists) is a success and sends nothing; 138009 (per-contact request quota exhausted) returns a dedicated error.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The request was sent (`permission_requested`), or Meta reported that a permanent permission already exists (`permission_already_granted`, nothing sent).","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["permission_requested","permission_already_granted"],"description":"Outcome of the send."},"message_id":{"type":["integer","null"],"description":"Id of the outgoing platform message mirroring the request in the thread."},"conversation_id":{"type":"integer","description":"display_id of the conversation containing the permission request."},"permission":{"type":"object","description":"Permission state after the send, as returned by permission_state.","properties":{"status":{"type":"string","enum":["no_permission","temporary","permanent"],"description":"Display call status (hyphenated form of the stored call status)."},"expires_at":{"type":["string","null"],"description":"ISO8601 expiry of a temporary grant; null when permanent or absent."},"is_permanent":{"type":"boolean"},"requested_at":{"type":["string","null"]},"responded_at":{"type":["string","null"]},"can_request":{"type":["boolean","null"],"description":"Meta's send_call_permission_request affordance; null when unknown."},"can_call":{"type":["boolean","null"],"description":"Meta's start_call affordance; null when unknown."},"retry_after_seconds":{"type":"integer"},"limits":{"type":"array","description":"Live Meta rate-limit windows; never a hardcoded number.","items":{"type":"object","properties":{"time_period":{"type":"string","description":"ISO8601 duration, e.g. PT24H or P7D."},"max_allowed":{"type":"integer"},"current_usage":{"type":"integer"},"limit_expiration_time":{"type":"integer","description":"Unix seconds when the window resets."}}}}}}}},"example":{"status":"permission_requested","message_id":918273,"permission":{"status":"no_permission","expires_at":null,"is_permanent":false,"requested_at":"2026-07-21T22:16:04Z","responded_at":null,"can_request":true,"can_call":false,"retry_after_seconds":300,"limits":[{"time_period":"PT24H","max_allowed":1,"current_usage":1,"limit_expiration_time":1784851200}]},"conversation_id":1}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"422":{"description":"Throttled (`permission_pending`, with the remaining seconds), or a validation/send failure rendered as a localized `error` string (body too long, quota exhausted, transport failure).","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["permission_pending"],"description":"Display call status (hyphenated form of the stored call status)."},"retry_after_seconds":{"type":"integer","description":"Seconds left on the 5-minute throttle window."},"conversation_id":{"type":"integer","description":"display_id of the conversation containing the permission state."},"error":{"type":"string","description":"Localized failure message when the outcome is not `permission_pending`."}}},"example":{"status":"permission_pending","retry_after_seconds":213,"error":"A solicitação de permissão já foi enviada. Aguarde antes de tentar novamente.","conversation_id":1}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["conversation_id"],"properties":{"conversation_id":{"type":"integer","description":"display_id of the conversation whose contact is asked for permission."},"body":{"type":"string","maxLength":1024,"description":"Custom message shown to the contact. Blank falls back to the inbox override, then to the account-language default. Longer than 1024 characters (Meta's interactive body limit) is rejected rather than truncated."}}},"example":{"conversation_id":365,"body":"Podemos te ligar para falar sobre o seu pedido 1042?"}}}}}},"/api/v1/accounts/{account_id}/whatsapp_calls/permission_state":{"get":{"tags":["WhatsApp Calls"],"operationId":"auto_get_api_v1_accounts_account_id_whatsapp_calls_permission_state","summary":"Read the WhatsApp call permission state for a conversation","description":"Returns whether the contact has granted call permission (and until when), whether a new request or a dial is currently allowed, the live Meta rate-limit windows, and the message body that would be suggested to the agent. Merges the values persisted from the contact's last reply with a live `GET {phone_id}/call_permissions` lookup; if that lookup fails the response degrades to the persisted state instead of erroring.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The merged permission state.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["no_permission","temporary","permanent"],"description":"Meta's 3-value permission enum, downgraded to no_permission once expired."},"expires_at":{"type":["string","null"],"description":"ISO8601 expiry of a temporary grant; null when permanent or absent."},"is_permanent":{"type":"boolean"},"requested_at":{"type":["string","null"],"description":"ISO8601 timestamp of the last request we sent."},"responded_at":{"type":["string","null"],"description":"ISO8601 timestamp of the contact's last reply."},"can_request":{"type":["boolean","null"],"description":"Meta's send_call_permission_request affordance; null when unknown."},"can_call":{"type":["boolean","null"],"description":"Meta's start_call affordance; null when unknown."},"retry_after_seconds":{"type":"integer","description":"Seconds left on the local 5-minute re-request throttle; 0 when free."},"limits":{"type":"array","description":"Live Meta rate-limit windows; never a hardcoded number.","items":{"type":"object","properties":{"time_period":{"type":"string","description":"ISO8601 duration, e.g. PT24H or P7D."},"max_allowed":{"type":"integer"},"current_usage":{"type":"integer"},"limit_expiration_time":{"type":"integer","description":"Unix seconds when the window resets."}}}},"suggested_body":{"type":"string","description":"Prefill for the composer — the inbox override, or the default text in the account language."}}},"example":{"status":"temporary","expires_at":"2026-07-28T22:16:04Z","is_permanent":false,"requested_at":"2026-07-21T22:16:04Z","responded_at":"2026-07-21T22:19:31Z","can_request":true,"can_call":true,"retry_after_seconds":0,"limits":[{"time_period":"P7D","max_allowed":2,"current_usage":1,"limit_expiration_time":1785456000}],"suggested_body":"Gostaríamos de ligar para você em relação à sua conversa."}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"conversation_id","in":"query","required":true,"schema":{"type":"integer"},"description":"display_id of the conversation."}]}},"/api/v1/accounts/{account_id}/whatsapp_calls/{id}":{"get":{"tags":["WhatsApp Calls"],"operationId":"auto_get_api_v1_accounts_account_id_whatsapp_calls_id","summary":"Read WhatsApp call metadata or recover an owned outbound answer","description":"Always returns authorized call metadata. Inbound SDP is never returned here and is available only from claim. An outbound SDP answer and fresh WebRTC configuration are conditionally included only when accepted_by_agent_id and client_session_id match the authenticated initiating tab; other authorized agents or tabs receive metadata only.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Authorized call metadata, with optional owner-only outbound recovery fields.","content":{"application/json":{"schema":{"type":"object","required":["id","call_id","provider","status","direction","conversation_id","conversation_record_id","inbox_id","state","revision"],"properties":{"id":{"type":"integer"},"call_id":{"type":"string"},"provider":{"type":"string","enum":["whatsapp"],"description":"Call provider (WhatsApp Cloud)."},"status":{"type":"string","enum":["ringing","in-progress","completed","no-answer","failed"],"description":"Display call status (hyphenated form of the stored call status)."},"direction":{"type":"string","enum":["inbound","outbound"],"description":"Call direction (relative to the business number)."},"conversation_id":{"type":"integer","description":"Conversation display_id used by dashboard routes."},"conversation_record_id":{"type":"integer","description":"Internal conversation primary key."},"inbox_id":{"type":"integer"},"logical_inbox_id":{"type":"integer","description":"Present when physical call ownership differs from the unified outward inbox identity."},"state":{"type":"string"},"revision":{"type":"integer"},"sdp_answer":{"type":"string","description":"Present only for the owning outbound agent."},"ice_servers":{"type":"array","items":{"type":"object","required":["urls"],"properties":{"urls":{"type":"array","items":{"type":"string"}},"username":{"type":"string"},"credential":{"type":"string"}},"additionalProperties":false}},"ice_transport_policy":{"type":"string","enum":["all","relay"]},"webrtc_config":{"type":"object","required":["ice_servers","ice_transport_policy","expires_at"],"properties":{"ice_servers":{"type":"array","items":{"type":"object","required":["urls"],"properties":{"urls":{"type":"array","items":{"type":"string"}},"username":{"type":"string"},"credential":{"type":"string"}},"additionalProperties":false}},"ice_transport_policy":{"type":"string","enum":["all","relay"]},"expires_at":{"type":"string","format":"date-time"}},"additionalProperties":false}}},"example":{"id":1,"call_id":"sample call id","provider":"whatsapp","status":"ringing","direction":"inbound","conversation_id":1,"conversation_record_id":1,"inbox_id":1,"logical_inbox_id":1,"state":"active","revision":1,"sdp_answer":"sample sdp answer","ice_servers":[{"urls":["https://example.com/resource"],"username":"sample username","credential":"sample credential"}],"ice_transport_policy":"all","webrtc_config":{"ice_servers":[{"urls":["https://example.com/resource"],"username":"sample username","credential":"sample credential"}],"ice_transport_policy":"all","expires_at":"2026-01-15T10:30:00.000Z"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"429":{"description":"Per-account/authenticated-credential TURN mint limit exceeded; honor Retry-After before retrying."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"client_session_id","in":"query","required":false,"schema":{"type":"string","maxLength":128},"description":"Required only for owner-tab outbound SDP recovery; metadata remains available without it."}]}},"/api/v1/accounts/{account_id}/branded_email_layout/preview":{"post":{"tags":["Branded Email Layout"],"operationId":"auto_post_api_v1_accounts_account_id_branded_email_layout_preview","summary":"Preview an unsaved branded email layout","description":"Render an unsaved base Liquid HTML layout with synthetic people through the reply email renderer. Does not persist a template or send mail. Requires administrator and branded_email_templates; optional inbox_id must identify an email inbox in this account. Omit the layout to preview the saved effective layout; blank or null previews inheritance after clearing the selected override. Returned HTML is untrusted and must be displayed in an isolated sandbox, never injected into the caller page.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Rendered sample; no email was sent.","content":{"application/json":{"schema":{"type":"object","required":["html"],"properties":{"html":{"type":"string","description":"Untrusted rendered HTML containing synthetic message content.","example":"\u003chtml\u003e\u003cbody\u003e\u003cp\u003eSample message\u003c/p\u003e\u003c/body\u003e\u003c/html\u003e"}}},"example":{"html":"\u003chtml\u003e\u003cbody\u003e\u003cp\u003eSample message\u003c/p\u003e\u003c/body\u003e\u003c/html\u003e"}}}},"401":{"description":"Unauthenticated user or administrator access required."},"404":{"description":"The selected inbox was not found in this account."},"422":{"description":"Invalid layout, non-email inbox or disabled feature. No saved value was changed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Body must include {{ content_for_layout }}"},"error_code":{"type":"string","enum":["invalid_layout"],"description":"Present for Liquid or input validation errors.","example":"invalid_layout"}}},"example":{"error":"Body must include {{ content_for_layout }}","error_code":"invalid_layout"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/account_branded_email_layout_payload"},"example":{"inbox_id":7,"branded_email_layout":"\u003chtml\u003e\u003cbody\u003e{{ content_for_layout }}\u003c/body\u003e\u003c/html\u003e"}}}}}},"/api/v1/accounts/{account_id}/inboxes/{inbox_id}/translation_settings":{"get":{"tags":["Inboxes"],"operationId":"auto_get_api_v1_accounts_account_id_inboxes_inbox_id_translation_settings","summary":"Get translation settings","description":"Returns the translation setting identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Inbox translation defaults and provider readiness","content":{"application/json":{"schema":{"type":"object","required":["translation_settings","translation_provider"],"properties":{"translation_settings":{"$ref":"#/components/schemas/inbox_translation_settings"},"translation_provider":{"$ref":"#/components/schemas/translation_provider_readiness"}}},"example":{"translation_settings":{"enabled":true,"agent_language":"pt-BR","contact_language":"en","translate_incoming":true,"translate_outgoing":true,"translate_transcripts":true},"translation_provider":{"provider":"google_translate","ready":true,"blocking_reasons":["provider_not_configured"]}}}}},"401":{"description":"Only account administrators can read inbox translation configuration"},"404":{"description":"Feature disabled or inbox not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"inbox_id","in":"path","required":true,"schema":{"type":"string"}}]},"patch":{"tags":["Inboxes"],"operationId":"auto_patch_api_v1_accounts_account_id_inboxes_inbox_id_translation_settings","summary":"Update translation settings","description":"Updates the translation setting identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Updated inbox translation defaults","content":{"application/json":{"schema":{"type":"object","required":["translation_settings","translation_provider"],"properties":{"translation_settings":{"$ref":"#/components/schemas/inbox_translation_settings"},"translation_provider":{"$ref":"#/components/schemas/translation_provider_readiness"}}},"example":{"translation_settings":{"enabled":true,"agent_language":"pt-BR","contact_language":"en","translate_incoming":true,"translate_outgoing":true,"translate_transcripts":true},"translation_provider":{"provider":"google_translate","ready":true,"blocking_reasons":["provider_not_configured"]}}}}},"401":{"description":"Only account administrators can change inbox translation configuration"},"404":{"description":"Feature disabled or inbox not found"},"400":{"description":"Invalid translation settings","content":{"application/json":{"schema":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","enum":["invalid_translation_settings"]},"message":{"type":"string"}}},"example":{"error":"invalid_translation_settings","message":"Sample message text."}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"inbox_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["translation_settings"],"properties":{"translation_settings":{"$ref":"#/components/schemas/inbox_translation_settings_update"}}},"example":{"translation_settings":{"enabled":true,"agent_language":"sample agent language","contact_language":"sample contact language","translate_incoming":true,"translate_outgoing":true,"translate_transcripts":true}}}}}}},"/api/v1/accounts/{account_id}/inboxes/{inbox_id}/audio_transcription_settings":{"get":{"tags":["Inboxes"],"operationId":"auto_get_api_v1_accounts_account_id_inboxes_inbox_id_audio_transcription_settings","summary":"Get the audio transcription scope of an inbox","description":"Returns the master toggle, which audio it covers, and whether a speech-to-text key is actually reachable for this account. The provider block exists because the screen used to promise \"requires an OpenAI or Groq API key\" without ever saying whether one was configured, so an operator could enable transcription and get the same silence as a broken one.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","required":["audio_transcription_enabled","audio_transcription_settings","audio_transcription_provider"],"properties":{"audio_transcription_enabled":{"type":"boolean","description":"The master toggle. A new inbox is born off."},"audio_transcription_settings":{"type":"object","required":["inbound","outbound_agent"],"properties":{"inbound":{"type":"boolean","description":"Transcribe audio the contact sent."},"outbound_agent":{"type":"boolean","description":"Transcribe audio an agent recorded. Off by default — it spends AI on text the agent already knows."}},"additionalProperties":false},"audio_transcription_provider":{"type":"object","required":["ready","providers","blocking_reasons"],"description":"Whether a speech-to-text key is reachable for this account, and where it comes from.","properties":{"ready":{"type":"boolean","description":"False when no OpenAI or Groq key is configured, in which case transcription can never produce text."},"providers":{"type":"array","description":"Every provider with a usable key, in the order they are tried.","items":{"type":"object","required":["name","source"],"properties":{"name":{"type":"string","enum":["groq","openai"]},"source":{"type":"string","enum":["account","environment"],"description":"Whether the key comes from this account's integration or from the server environment."}},"additionalProperties":false}},"blocking_reasons":{"type":"array","description":"Empty when ready.","items":{"type":"string","enum":["provider_not_configured"]}}},"additionalProperties":false}},"additionalProperties":false},"example":{"audio_transcription_enabled":true,"audio_transcription_settings":{"inbound":true,"outbound_agent":false},"audio_transcription_provider":{"ready":true,"providers":[{"name":"groq","source":"account"}],"blocking_reasons":[]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"inbox_id","in":"path","required":true,"schema":{"type":"string"}}]},"patch":{"tags":["Inboxes"],"operationId":"auto_patch_api_v1_accounts_account_id_inboxes_inbox_id_audio_transcription_settings","summary":"Update the audio transcription scope of an inbox","description":"Partial update — an omitted key keeps its stored value. Unsupported keys are rejected with 400 rather than stored. Does not change the master toggle, which is an attribute of the inbox itself.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","required":["audio_transcription_enabled","audio_transcription_settings","audio_transcription_provider"],"properties":{"audio_transcription_enabled":{"type":"boolean","description":"The master toggle. A new inbox is born off."},"audio_transcription_settings":{"type":"object","required":["inbound","outbound_agent"],"properties":{"inbound":{"type":"boolean","description":"Transcribe audio the contact sent."},"outbound_agent":{"type":"boolean","description":"Transcribe audio an agent recorded. Off by default — it spends AI on text the agent already knows."}},"additionalProperties":false},"audio_transcription_provider":{"type":"object","required":["ready","providers","blocking_reasons"],"description":"Whether a speech-to-text key is reachable for this account, and where it comes from.","properties":{"ready":{"type":"boolean","description":"False when no OpenAI or Groq key is configured, in which case transcription can never produce text."},"providers":{"type":"array","description":"Every provider with a usable key, in the order they are tried.","items":{"type":"object","required":["name","source"],"properties":{"name":{"type":"string","enum":["groq","openai"]},"source":{"type":"string","enum":["account","environment"],"description":"Whether the key comes from this account's integration or from the server environment."}},"additionalProperties":false}},"blocking_reasons":{"type":"array","description":"Empty when ready.","items":{"type":"string","enum":["provider_not_configured"]}}},"additionalProperties":false}},"additionalProperties":false},"example":{"audio_transcription_enabled":true,"audio_transcription_settings":{"inbound":true,"outbound_agent":false},"audio_transcription_provider":{"ready":true,"providers":[{"name":"groq","source":"account"}],"blocking_reasons":[]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"400":{"description":"The submitted settings are not a valid object or carry unsupported keys.","content":{"application/json":{"schema":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","enum":["invalid_audio_transcription_settings"]},"message":{"type":"string"}},"additionalProperties":false},"example":{"error":"invalid_audio_transcription_settings","message":"The audio transcription settings are invalid."}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"inbox_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["audio_transcription_settings"],"properties":{"audio_transcription_settings":{"type":"object","description":"Any subset of the scope keys.","properties":{"inbound":{"type":"boolean"},"outbound_agent":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false},"example":{"audio_transcription_settings":{"inbound":true,"outbound_agent":true}}}}}}},"/api/v1/accounts/{account_id}/inboxes/{id}/assignable_agents":{"get":{"tags":["Inboxes"],"operationId":"auto_get_api_v1_accounts_account_id_inboxes_id_assignable_agents","summary":"Assignable agents inboxes","description":"Performs the assignable agents operation on the targeted inbox resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":["integer","null"]},"account_user_id":{"type":["integer","null"]},"availability_status":{"type":"string","enum":["online","offline","busy"],"description":"Realtime availability. Contacts report online/offline (presence-based); agents/users additionally report busy (their configured availability)."},"auto_offline":{"type":"boolean"},"confirmed":{"type":"boolean"},"email":{"type":"string","format":"email"},"provider":{"type":"string","enum":["email","google_oauth2","saml"],"description":"Authentication provider the user signed up through."},"available_name":{"type":"string"},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"name":{"type":"string"},"role":{"type":"string","enum":["agent","administrator"]},"outbound_agent_name_header_policy":{"type":["string","null"]},"thumbnail":{"type":"string"},"custom_role_id":{"type":["integer","null"]},"access_role_id":{"type":["integer","null"]}}}}}},"example":{"payload":[{"id":1,"account_id":1,"account_user_id":1,"availability_status":"online","auto_offline":true,"confirmed":true,"email":"agent@example.com","provider":"email","available_name":"sample available name","custom_attributes":{},"name":"Sample Name","role":"agent","outbound_agent_name_header_policy":"sample outbound agent name header policy","thumbnail":"sample thumbnail","custom_role_id":1,"access_role_id":1}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/inboxes/{id}/campaigns":{"get":{"tags":["Inboxes"],"operationId":"auto_get_api_v1_accounts_account_id_inboxes_id_campaigns","summary":"Campaigns inboxes","description":"Performs the campaigns operation on the targeted inbox resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"title":{"type":"string"},"description":{"type":"string"},"account_id":{"type":"integer"},"inbox":{"type":"object","properties":{"id":{"type":"integer"},"avatar_url":{"type":"string"},"channel_id":{"type":"integer"},"name":{"type":"string"},"channel_type":{"type":"string","enum":["Channel::Api","Channel::Email","Channel::FacebookPage","Channel::Instagram","Channel::Line","Channel::Sms","Channel::Telegram","Channel::Tiktok","Channel::TwilioSms","Channel::TwitterProfile","Channel::WebWidget","Channel::Whatsapp"],"description":"Inbox channel model class (STI type)."},"greeting_enabled":{"type":"boolean"},"greeting_message":{"type":"string"},"working_hours_enabled":{"type":"boolean"},"enable_email_collect":{"type":"string"},"csat_survey_enabled":{"type":"boolean"},"csat_config":{"type":"string"},"enable_auto_assignment":{"type":"string"},"auto_assignment_config":{"type":"string"},"out_of_office_message":{"type":"string"},"working_hours":{"type":"string"},"timezone":{"type":"string","description":"IANA timezone identifier (e.g. \"America/Sao_Paulo\", \"UTC\"). Rails timezone names are also accepted on input; an unrecognized value is ignored in favor of the next fallback.","example":"America/Sao_Paulo"},"callback_webhook_url":{"type":"string"},"allow_messages_after_resolved":{"type":"string"},"lock_to_single_conversation":{"type":"string"},"audio_transcription_enabled":{"type":"boolean"},"preserve_deleted_messages":{"type":"string"},"allow_message_deletion":{"type":"string"},"capture_view_once":{"type":"string"},"sender_name_type":{"type":"string","enum":["friendly","professional"]},"auto_resolve_config":{"type":"object","additionalProperties":true,"oneOf":[{"type":"object","maxProperties":0,"additionalProperties":true,"description":"Empty means inherit the account rule."},{"type":"object","additionalProperties":false,"required":["mode"],"properties":{"mode":{"type":"string","enum":["disabled"],"description":"Disable automatic resolution for this inbox."}},"description":"The disabled rule contains only its mode."},{"type":"object","additionalProperties":false,"required":["mode","after","message","label","allow_waiting"],"properties":{"mode":{"type":"string","enum":["custom"],"description":"Use this complete inbox rule."},"after":{"type":"integer","minimum":10,"maximum":1439856,"description":"Inactivity in minutes; required for custom mode."},"message":{"type":["string","null"],"maxLength":10000,"description":"Optional message; blank normalizes to null."},"label":{"type":["string","null"],"description":"An existing account label title, or null."},"allow_waiting":{"type":"boolean","description":"Whether waiting conversations are included."}},"description":"Complete normalized custom rule."}],"description":"Normalized JSON rule from valid model writes: empty, disabled, or complete custom configuration.","example":{"mode":"custom","after":60,"message":null,"label":null,"allow_waiting":false}},"outbound_agent_name_header_policy":{"type":"string"},"agent_bot_working_hours_mode":{"type":"string","enum":["always","inside_business_hours","outside_business_hours"]},"business_name":{"type":"string"},"responder_policy":{"type":"string"},"help_center":{"type":"object","properties":{"name":{"type":"string"},"slug":{"type":"string"}}},"tweets_enabled":{"type":"boolean"},"allowed_domains":{"type":"string"},"widget_color":{"type":"string"},"website_url":{"type":"string"},"hmac_mandatory":{"type":"string"},"welcome_title":{"type":"string"},"welcome_tagline":{"type":"string"},"web_widget_script":{"type":"string"},"website_token":{"type":"string"},"selected_feature_flags":{"type":"string"},"reply_time":{"type":"string","format":"date-time"},"hmac_token":{"type":"string"},"pre_chat_form_enabled":{"type":"boolean"},"pre_chat_form_options":{"type":"string"},"continuity_via_email":{"type":"string","format":"email"},"page_id":{"type":"integer"},"reauthorization_required":{"type":"string"},"instagram_id":{"type":"integer"},"messaging_service_sid":{"type":"string"},"phone_number":{"type":"string"},"medium":{"type":"string"},"bandwidth_callback_state":{"type":"string","enum":["active","reconnect_required","reconciling","reconciliation_required","encryption_required"]},"bandwidth_api_migration_state":{"type":"string","enum":["oauth2_configured","oauth2_required","configuration_required"]},"bandwidth_legacy_basic_deprecated":{"type":"boolean"},"content_templates":{"type":"string"},"auth_token":{"type":"string"},"account_sid":{"type":"string"},"api_key_sid":{"type":"string"},"twilio_credential_state":{"type":"string","enum":["ready","pending","failed","dead_letter","account_auth_token_required","reconciliation_required"],"description":"Durable Twilio credential lifecycle derived from Channel::TwilioSms. A reconciliation-required state is fail-closed until the provider outcome has been verified."},"api_key_configured":{"type":"boolean"},"email":{"type":"string","format":"email"},"auth_method":{"type":"string"},"forwarding_enabled":{"type":"boolean"},"forward_to_email":{"type":"string","format":"email"},"branded_email_layout":{"type":"string"},"imap_login":{"type":"string"},"imap_password":{"type":"string"},"imap_address":{"type":"string"},"imap_port":{"type":"string"},"imap_enabled":{"type":"boolean"},"imap_enable_ssl":{"type":"string"},"imap_authentication":{"type":"string"},"smtp_login":{"type":"string"},"smtp_password":{"type":"string"},"smtp_address":{"type":"string"},"smtp_port":{"type":"string"},"smtp_enabled":{"type":"boolean"},"smtp_domain":{"type":"string"},"smtp_enable_ssl_tls":{"type":"string"},"smtp_enable_starttls_auto":{"type":"string"},"smtp_openssl_verify_mode":{"type":"string","enum":["none","peer","client_once","fail_if_no_peer_cert"],"description":"OpenSSL peer-verification mode for the SMTP connection."},"smtp_authentication":{"type":"string"},"secret":{"type":"string"},"webhook_url":{"type":"string"},"inbox_identifier":{"type":"string"},"additional_attributes":{"type":"object","additionalProperties":true,"description":"Channel- and source-specific metadata for this record (e.g. browser info, referer, social profile identifiers). The key set depends on the originating channel."},"provider":{"type":"string","enum":["default","whatsapp_cloud","whatsapp_web","google","microsoft"],"description":"Messaging provider backing the inbox channel (whatsapp_web is the WazMeow gateway; email uses google/microsoft; default otherwise)."},"bot_name":{"type":"string"},"message_templates":{"type":"boolean"},"provider_config":{"type":"string"},"business_management_token_configured":{"type":"boolean"},"hybrid_pair":{"$ref":"#/components/schemas/inbox/properties/hybrid_pair"},"whatsapp_web_session_state":{"$ref":"#/components/schemas/inbox/properties/whatsapp_web_session_state"},"hybrid_hidden":{"type":"string"},"logical_inbox_id":{"type":"integer"},"whatsapp_pending_phone":{"type":"object","nullable":true,"description":"Spec 052 — set only when a WhatsApp phone-number rewrite was REFUSED because a non-sibling channel already holds the number, leaving the inbox on its `pending:` placeholder and inert. `null` in every normal case (including a routine, not-yet-scanned pairing).","additionalProperties":false,"properties":{"awaiting_pair":{"type":"boolean","description":"True while the inbox is still on its `pending:\u003cuuid\u003e` placeholder number."},"phone":{"type":"string","description":"The E.164 number the rewrite tried to claim."},"reason":{"type":"string","enum":["same_account_same_provider","other_account"],"description":"Why the rewrite was refused. `other_account` never carries any identifying detail about the other account."},"sibling_inbox_id":{"type":"integer","nullable":true,"description":"Colliding inbox in the SAME account; absent when the collision is cross-account."},"source":{"type":"string","enum":["pair_success","qr_pump"],"description":"Which path attempted the rewrite."},"at":{"type":"string","format":"date-time","description":"When the refusal was recorded."}}},"whatsapp_sibling_notice":{"type":"string"},"whatsapp_web_contact_request":{"type":"string","enum":["supported","unsupported","unknown"],"description":"WhatsApp Web inboxes only — whether this inbox's WazMeow gateway serves the request that asks a customer to share their phone number. `supported` and `unsupported` come from a no-effect probe of the gateway route, refreshed at most hourly and immediately when a real send finds the route missing; `unknown` means not probed yet or the gateway could not be reached. Only `supported` turns the feature on; with `unknown` the request is refused before any gateway call while the probe runs."},"voice_enabled":{"type":"boolean"},"inbound_calls_enabled":{"type":"boolean"},"voice_configured":{"type":"boolean"},"voice_call_webhook_url":{"type":"string"},"voice_status_webhook_url":{"type":"string"}}},"logical_inbox_id":{"type":"integer"},"whatsapp_transport":{"type":"string"},"sender":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":["integer","null"]},"account_user_id":{"type":["integer","null"]},"availability_status":{"type":"string","enum":["online","offline","busy"],"description":"Realtime availability. Contacts report online/offline (presence-based); agents/users additionally report busy (their configured availability)."},"auto_offline":{"type":"boolean"},"confirmed":{"type":"boolean"},"email":{"type":"string","format":"email"},"provider":{"type":"string","enum":["email","google_oauth2","saml"],"description":"Authentication provider the user signed up through."},"available_name":{"type":"string"},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"name":{"type":"string"},"role":{"type":"string","enum":["agent","administrator"]},"outbound_agent_name_header_policy":{"type":["string","null"]},"thumbnail":{"type":"string"},"custom_role_id":{"type":["integer","null"]},"access_role_id":{"type":["integer","null"]}}},"message":{"type":"string"},"template_params":{"type":"string"},"campaign_status":{"type":"string","enum":["active","completed","draft","scheduled","sending","paused","failed","processing"]},"enabled":{"type":"boolean"},"campaign_type":{"type":"string","enum":["ongoing","one_off"]},"scheduled_at":{"type":"integer"},"started_at":{"type":["integer","null"]},"completed_at":{"type":["integer","null"]},"audience":{"type":"array","description":"Audience sources for this campaign, unioned (a contact matched by more than one entry is targeted once). A single `All` entry dominates the rest. Contacts without a phone number are dropped on phone-dispatch channels, and a contact who refused data processing is dropped when the account requires consent.","items":{"type":"object","description":"One audience source. `type` picks it; the remaining fields qualify it and are ignored where they do not apply. An unknown value for any qualifier falls back to its safe default rather than failing the request.","properties":{"type":{"type":"string","enum":["Label","Contact","Segment","Crm","Organization","All"],"example":"Label","description":"`Label` contacts carrying a label · `Contact` one hand-picked contact · `Segment` a saved segment · `Crm` the open deals of a pipeline · `Organization` everyone linked to one company · `All` the whole account."},"id":{"type":"integer","example":15,"description":"The record this entry points at: a label id, a contact id, a saved-segment (custom filter) id, a CRM pipeline id, or a company id. Omitted for `All`."},"source":{"type":"string","enum":["contact","conversation","both","organization"],"example":"conversation","description":"For `Label`, WHERE the label was applied — `contact` (the default, and what an entry with no `source` has always meant), `conversation` (the contacts behind the labeled conversations) or `both`. For `Segment`, WHICH saved-filter family the id belongs to — `contact`, `conversation` (a conversation folder) or `organization` (a company segment, resolved to its companies' people). Ignored for other types."},"conversation_status":{"type":"string","enum":["all","open","pending","snoozed","resolved"],"example":"open","description":"Narrows a conversation-sourced `Label` to conversations in one status. Defaults to `all`. Ignored when the label is read on contacts."},"stage_id":{"type":"integer","example":21,"description":"Narrows a `Crm` entry to a single stage of the pipeline. Omitted means every stage. Only OPEN deals ever enter the audience."}}}},"trigger_rules":{"type":"string"},"trigger_only_during_business_hours":{"type":"string"},"message_variants":{"type":"string"},"send_settings":{"type":"string"},"recipient_stats":{"type":"string"},"estimated_cost":{"type":"string"},"actual_cost":{"type":"string"},"currency":{"type":"string"},"cost_basis":{"type":"string"},"media_attachments":{"type":"array","description":"Media attached to the campaign message.","items":{"type":"object","additionalProperties":true,"description":"An attachment: id, signed_id, filename, content_type (MIME) and byte_size."}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}},"example":[{"id":1,"title":"Sample title","description":"A short description.","account_id":1,"inbox":{"id":1,"avatar_url":"https://example.com/resource","channel_id":1,"name":"Sample Name","channel_type":"Channel::Api","greeting_enabled":true,"greeting_message":"sample greeting message","working_hours_enabled":true,"enable_email_collect":"agent@example.com","csat_survey_enabled":true,"csat_config":"sample csat config","enable_auto_assignment":"sample enable auto assignment","auto_assignment_config":"sample auto assignment config","out_of_office_message":"sample out of office message","working_hours":"sample working hours","timezone":"America/Sao_Paulo","callback_webhook_url":"https://example.com/resource","allow_messages_after_resolved":"sample allow messages after resolved","lock_to_single_conversation":"sample lock to single conversation","audio_transcription_enabled":true,"preserve_deleted_messages":"sample preserve deleted messages","allow_message_deletion":"sample allow message deletion","capture_view_once":"sample capture view once","sender_name_type":"friendly","auto_resolve_config":{"mode":"custom","after":60,"message":null,"label":null,"allow_waiting":false},"outbound_agent_name_header_policy":"sample outbound agent name header policy","agent_bot_working_hours_mode":"always","business_name":"sample business name","responder_policy":"sample responder policy","help_center":{"name":"Sample Name","slug":"sample-slug"},"tweets_enabled":true,"allowed_domains":"sample allowed domains","widget_color":"#1F93FF","website_url":"https://example.com/resource","hmac_mandatory":"sample hmac mandatory","welcome_title":"sample welcome title","welcome_tagline":"sample welcome tagline","web_widget_script":"sample web widget script","website_token":"sample-token","selected_feature_flags":"sample selected feature flags","reply_time":"2026-01-15T10:30:00.000Z","hmac_token":"sample-token","pre_chat_form_enabled":true,"pre_chat_form_options":"sample pre chat form options","continuity_via_email":"agent@example.com","page_id":1,"reauthorization_required":"sample reauthorization required","instagram_id":1,"messaging_service_sid":"sample messaging service sid","phone_number":"+5511999998888","medium":"sample medium","bandwidth_callback_state":"active","bandwidth_api_migration_state":"oauth2_configured","bandwidth_legacy_basic_deprecated":true,"content_templates":"sample content templates","auth_token":"sample-token","account_sid":"sample account sid","api_key_sid":"sample api key sid","twilio_credential_state":"ready","api_key_configured":true,"email":"agent@example.com","auth_method":"sample auth method","forwarding_enabled":true,"forward_to_email":"agent@example.com","branded_email_layout":"agent@example.com","imap_login":"sample imap login","imap_password":"sample imap password","imap_address":"sample imap address","imap_port":"sample imap port","imap_enabled":true,"imap_enable_ssl":"sample imap enable ssl","imap_authentication":"sample imap authentication","smtp_login":"sample smtp login","smtp_password":"sample smtp password","smtp_address":"sample smtp address","smtp_port":"sample smtp port","smtp_enabled":true,"smtp_domain":"sample smtp domain","smtp_enable_ssl_tls":"sample smtp enable ssl tls","smtp_enable_starttls_auto":"sample smtp enable starttls auto","smtp_openssl_verify_mode":"none","smtp_authentication":"sample smtp authentication","secret":"sample-token","webhook_url":"https://example.com/resource","inbox_identifier":"sample inbox identifier","additional_attributes":{},"provider":"default","bot_name":"sample bot name","message_templates":true,"provider_config":"sample provider config","business_management_token_configured":true,"hybrid_pair":{"paired":true,"id":4,"role":"cloud","sibling_inbox_id":18,"canonical_phone":"+5521900000000","primary":"cloud","inbound_authority":"cloud","unified_inbox":true,"unified_state":{"state":"complete","scanned":42,"frozen":40,"reconciled_count":2,"completed_at":"2026-10-03T12:00:00.000Z","blocked_conversations":[]},"routing":{"outbound_default":"cloud","out_of_window":"web","fallback":true,"manual_override":true,"weighted":{"mode":"weighted","web_percent":30,"version":2}},"web_channel_id":12,"web_inbox_id":18,"calling_provider":"whatsapp_web","web_voice_enabled":true,"web_inbound_calls_enabled":true,"web_call_config_sync":{"state":"pending","checked_at":"2026-10-03T12:00:00.000Z"},"web_video_calls_enabled":false,"web_group_calls_enabled":false,"web_reauthorization_required":false,"web_session_state":{"state":"connected","fresh":true,"observed_at":"2026-10-03T12:00:00.000Z","disconnected_since":null},"web_allow_message_deletion":true},"whatsapp_web_session_state":{"state":"connected","fresh":true,"observed_at":"2026-01-15T10:30:00.000Z","disconnected_since":null},"hybrid_hidden":"sample hybrid hidden","logical_inbox_id":1,"whatsapp_pending_phone":{"awaiting_pair":true,"phone":"+5511999998888","reason":"same_account_same_provider","sibling_inbox_id":1,"source":"pair_success","at":"2026-01-15T10:30:00.000Z"},"whatsapp_sibling_notice":"sample whatsapp sibling notice","whatsapp_web_contact_request":"supported","voice_enabled":true,"inbound_calls_enabled":true,"voice_configured":true,"voice_call_webhook_url":"https://example.com/resource","voice_status_webhook_url":"https://example.com/resource"},"logical_inbox_id":1,"whatsapp_transport":"sample whatsapp transport","sender":{"id":1,"account_id":1,"account_user_id":1,"availability_status":"online","auto_offline":true,"confirmed":true,"email":"agent@example.com","provider":"email","available_name":"sample available name","custom_attributes":{},"name":"Sample Name","role":"agent","outbound_agent_name_header_policy":"sample outbound agent name header policy","thumbnail":"sample thumbnail","custom_role_id":1,"access_role_id":1},"message":"Sample message text.","template_params":"sample template params","campaign_status":"active","enabled":true,"campaign_type":"ongoing","scheduled_at":1,"started_at":1,"completed_at":1,"audience":[{"type":"Label","id":15,"source":"conversation","conversation_status":"open","stage_id":21}],"trigger_rules":"sample trigger rules","trigger_only_during_business_hours":"sample trigger only during business hours","message_variants":"sample message variants","send_settings":"sample send settings","recipient_stats":"sample recipient stats","estimated_cost":"sample estimated cost","actual_cost":"sample actual cost","currency":"BRL","cost_basis":"sample cost basis","media_attachments":[{}],"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}]}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/inboxes/{id}/avatar":{"delete":{"tags":["Inboxes"],"operationId":"auto_delete_api_v1_accounts_account_id_inboxes_id_avatar","summary":"Avatar inboxes","description":"Performs the avatar operation on the targeted inbox resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Success (no content)"},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/inboxes/{id}/deletion_status":{"get":{"tags":["Inboxes"],"operationId":"auto_get_api_v1_accounts_account_id_inboxes_id_deletion_status","summary":"Read the outcome of one asynchronous inbox deletion","description":"DELETE /inboxes/{id} answers 200 as soon as DeleteObjectJob is enqueued, so it cannot report whether the destroy succeeded. Polled by the client right after the request. A 404 means the inbox no longer exists and the deletion completed — that comes from the database, so it is the only authoritative success signal. An absent record reads as `unknown`, never as success.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The recorded state of the deletion request.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"$ref":"#/components/schemas/inbox_deletion_state"}}},"example":{"payload":{"state":"failed","requested_at":"2026-08-11T18:04:11Z","failed_at":"2026-08-11T18:06:02Z","error_class":"ActiveRecord::RecordNotUnique","error_message":"PG::UniqueViolation: duplicate key value","blocked_ids":["Conversation#4711"]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/inboxes/deletion_statuses":{"get":{"tags":["Inboxes"],"operationId":"auto_get_api_v1_accounts_account_id_inboxes_deletion_statuses","summary":"List every recorded inbox deletion for the account","description":"Every in-flight or failed inbox deletion of the account, keyed by inbox id, in one round trip. Loaded when the Inboxes settings page mounts so a failure that lands after the operator navigated away is still shown on the inbox's row. Deliberately NOT part of GET /inboxes, which the dashboard fetches at boot. Empty object when nothing is recorded.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Recorded deletions keyed by inbox id. Empty when there are none.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","description":"Keyed by inbox id as a string. Only inboxes with a recorded deletion appear, so an inbox missing from this map simply has none — it is not a claim that it was deleted.","additionalProperties":{"$ref":"#/components/schemas/inbox_deletion_state"}}}},"example":{"payload":{"137":{"state":"failed","requested_at":"2026-08-11T18:04:11Z","failed_at":"2026-08-11T18:06:02Z","error_class":"ActiveRecord::RecordNotUnique","error_message":"PG::UniqueViolation: duplicate key value","blocked_ids":["Conversation#4711"]}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/inboxes/{id}/sync_templates":{"post":{"tags":["Inboxes"],"operationId":"auto_post_api_v1_accounts_account_id_inboxes_id_sync_templates","summary":"Sync templates inboxes","description":"Performs the sync templates operation on the targeted inbox resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Template sync initiated","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"Template sync initiated successfully"}}},"example":{"message":"Template sync initiated successfully"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"422":{"description":"Not a WhatsApp channel","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Template sync is only available for WhatsApp channels"}}},"example":{"error":"Template sync is only available for WhatsApp channels"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/inboxes/{id}/whatsapp_business_management_token":{"put":{"tags":["Inboxes"],"operationId":"auto_put_api_v1_accounts_account_id_inboxes_id_whatsapp_business_management_token","summary":"Whatsapp business management token inboxes","description":"Performs the whatsapp business management token operation on the targeted inbox resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"204":{"description":"Success (no content)"},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"business_management_token":{"type":"string"}}},"example":{"business_management_token":"sample-token"}}}}}},"/api/v1/accounts/{account_id}/inboxes/{id}/health":{"get":{"tags":["Inboxes"],"operationId":"auto_get_api_v1_accounts_account_id_inboxes_id_health","summary":"Read WhatsApp Cloud health and recovery state","description":"Authorizes the requested logical inbox before checking its Cloud capability. A 200 response can contain partial data; consult health_state, health_error and health_blocks. On 422, health_data contains the previous snapshot when available and must not be presented as a fresh healthy result. Meta is read live at most once every 30 seconds per inbox: inside that window the last answer is returned with `refreshed: false`. The fields number_throughput, account_notices, messaging_limit_usage, app_subscriptions, subscribed_apps, connecting_app and free_service_allowance are computed on read and also accompany the 422 snapshot.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"WhatsApp Cloud phone-number health (from Meta Graph phone number node)","content":{"application/json":{"schema":{"type":"object","properties":{"health_state":{"type":"string","enum":["complete","partial"]},"health_checked_at":{"type":"string","format":"date-time"},"health_last_success_at":{"type":["string","null"],"format":"date-time"},"health_error":{"anyOf":[{"type":"null"},{"type":"object","required":["type","message","stage"],"properties":{"type":{"type":"string","enum":["authorization","api","generic"]},"message":{"type":"string"},"stage":{"type":"string","enum":["configuration","phone","business_account","business_profile"]},"http_status":{"type":"integer"},"code":{"type":"integer"},"subcode":{"type":"integer"}}}]},"id":{"type":"string","example":"123456789012345"},"display_phone_number":{"type":"string","example":"+1 555-010-0100"},"verified_name":{"type":"string","example":"Acme Support"},"name_status":{"type":"string","example":"APPROVED"},"quality_rating":{"type":"string","enum":["GREEN","YELLOW","RED","NA","UNKNOWN"],"example":"GREEN","description":"Meta quality rating. NA means not determined yet; the live API may also answer UNKNOWN."},"quality_rating_previous":{"type":["string","null"],"enum":["GREEN","YELLOW","RED","NA","UNKNOWN",null],"description":"Rating before the last change observed between two health checks of this installation. Meta does not date quality changes.","example":"GREEN"},"quality_rating_changed_at":{"type":["string","null"],"format":"date-time","description":"When this installation observed the last quality change.","example":"2026-10-01T09:00:00Z"},"quality_observed_at":{"type":["string","null"],"format":"date-time","description":"When Meta last answered the quality rating.","example":"2026-10-01T12:00:00Z"},"quality_observed_source":{"type":["string","null"],"enum":["health_sync","campaign_probe",null],"description":"Which read observed the rating: the periodic health check or a campaign quality check.","example":"health_sync"},"messaging_limit_tier":{"type":"string","description":"Business portfolio messaging limit (whatsapp_business_manager_messaging_limit), shared by every number of the portfolio.","example":"TIER_250"},"account_mode":{"type":"string","enum":["LIVE","SANDBOX"],"description":"LIVE is a production number; SANDBOX is a test number.","example":"LIVE"},"code_verification_status":{"type":"string","example":"VERIFIED"},"webhook_configuration":{"type":"object","description":"Meta webhook_configuration node","example":{"application":"https://app.example.com/webhooks/whatsapp"},"additionalProperties":true},"expected_webhook_url":{"type":["string","null"],"example":"https://app.example.com/webhooks/whatsapp/+15550100100"},"expected_webhook_urls":{"type":"array","items":{"type":"string"},"example":["https://app.example.com/webhooks/whatsapp","https://app.example.com/webhooks/whatsapp/+15550100100"]},"throughput":{"type":"object","description":"Meta throughput node","example":{"level":"STANDARD"},"additionalProperties":true},"last_onboarded_time":{"type":"string","format":"date-time","example":"2026-01-15T10:30:00.000Z"},"platform_type":{"type":"string","example":"CLOUD_API"},"certificate":{"type":["string","null"],"example":"CmIKHg... "},"business_id":{"type":"string","example":"987654321098765"},"throughput_level":{"type":["string","null"],"enum":["STANDARD","HIGH","NOT_APPLICABLE",null],"description":"Raw throughput level stored for the number.","example":"STANDARD"},"throughput_observed_at":{"type":["string","null"],"format":"date-time","description":"When the stored throughput level was observed: the Graph read time or the webhook time.","example":"2026-10-01T08:00:00Z"},"throughput_observed_source":{"type":["string","null"],"enum":["health_sync","webhook",null],"description":"Which source observed the stored throughput level.","example":"health_sync"},"is_on_biz_app":{"type":"boolean","description":"True when the number is also used in the WhatsApp Business app (coexistence).","example":false},"refreshed":{"type":"boolean","description":"False when this is the answer of a live read made less than 30 seconds ago.","example":true},"health_blocks":{"type":"object","description":"Outcome of each optional read of this request. A block marked unavailable kept its previous value.","properties":{"send_status":{"type":"string","enum":["ok","unavailable"],"example":"ok"},"official_business_account":{"type":"string","enum":["ok","cached","unavailable"],"example":"cached"},"business_verification":{"type":"string","enum":["ok","cached","unavailable"],"example":"cached"}},"example":{"send_status":"ok","official_business_account":"cached","business_verification":"cached"}},"health_status":{"type":["object","null"],"description":"Meta Health Status API of the number. The overall value exists only for messages; LIMITED entities carry additional_info and BLOCKED entities carry errors with a possible solution.","properties":{"can_send_message":{"type":"string","enum":["AVAILABLE","LIMITED","BLOCKED"],"example":"AVAILABLE"},"entities":{"type":"array","items":{"type":"object","properties":{"entity_type":{"type":"string","enum":["PHONE_NUMBER","WABA","BUSINESS","APP","MESSAGE_TEMPLATE"],"example":"PHONE_NUMBER"},"id":{"type":"string","example":"106540352242922"},"can_send_message":{"type":"string","enum":["AVAILABLE","LIMITED","BLOCKED"],"example":"LIMITED"},"can_receive_call_sip":{"type":"string","enum":["AVAILABLE","LIMITED","BLOCKED"],"example":"AVAILABLE"},"additional_info":{"type":"array","items":{"type":"string"},"example":["Your display name has not been approved yet. Your message limit will increase after the display name is approved."]},"errors":{"type":"array","items":{"type":"object","properties":{"error_code":{"type":"integer","example":141002},"error_description":{"type":"string","example":"Message templates can only be sent out if they are approved."},"possible_solution":{"type":"string","example":"Edit or appeal the message template review decision."}},"example":{"error_code":141002,"error_description":"Message templates can only be sent out if they are approved.","possible_solution":"Edit or appeal the message template review decision."}}}},"example":{"entity_type":"PHONE_NUMBER","id":"106540352242922","can_send_message":"LIMITED","can_receive_call_sip":"AVAILABLE","additional_info":["Your display name has not been approved yet. Your message limit will increase after the display name is approved."]}},"example":[{"entity_type":"PHONE_NUMBER","id":"106540352242922","can_send_message":"LIMITED","can_receive_call_sip":"AVAILABLE","additional_info":["Your display name has not been approved yet. Your message limit will increase after the display name is approved."]},{"entity_type":"WABA","id":"102290129340398","can_send_message":"AVAILABLE"}]}},"example":{"can_send_message":"LIMITED","entities":[{"entity_type":"PHONE_NUMBER","id":"106540352242922","can_send_message":"LIMITED","can_receive_call_sip":"AVAILABLE","additional_info":["Your display name has not been approved yet. Your message limit will increase after the display name is approved."]},{"entity_type":"WABA","id":"102290129340398","can_send_message":"AVAILABLE"}]}},"health_status_checked_at":{"type":["string","null"],"format":"date-time","description":"When Meta last answered the Health Status API.","example":"2026-10-01T12:00:00Z"},"official_business_account":{"type":["object","null"],"description":"Official business account (blue badge) request status of the number.","properties":{"oba_status":{"type":"string","enum":["PENDING","APPROVED","REJECTED","UNDER_REVIEW","EXPIRED","CANCELLED","NOT_STARTED"],"description":"NOT_STARTED appears in a Meta example although outside its documented enum.","example":"APPROVED"},"status_message":{"type":"string","example":"Your request was approved."}},"example":{"oba_status":"APPROVED"}},"official_business_account_checked_at":{"type":["string","null"],"format":"date-time","example":"2026-10-01T12:00:00Z"},"business_verification_status":{"type":["string","null"],"enum":["EXPIRED","FAILED","INELIGIBLE","NOT_VERIFIED","PENDING","PENDING_NEED_MORE_INFO","PENDING_SUBMISSION","REJECTED","REVOKED","VERIFIED",null],"description":"Meta verification of the business that owns the WhatsApp Business Account.","example":"VERIFIED"},"account_review_status":{"type":["string","null"],"enum":["APPROVED","DEFERRED","PENDING","REJECTED",null],"description":"Meta review of the WhatsApp Business Account.","example":"APPROVED"},"business_verification_checked_at":{"type":["string","null"],"format":"date-time","example":"2026-10-01T12:00:00Z"},"marketing_messages_onboarding_status":{"type":["string","null"],"description":"Marketing Messages API onboarding status of the business portfolio, as Meta reports it (for example NOT_STARTED).","example":"NOT_STARTED"},"number_throughput":{"type":"object","description":"Sending speed of the number at Meta: 80 messages per second by default, up to 1,000 after an automatic upgrade, fixed at 20 on a coexistence number. A level Meta has not confirmed in the last 24 hours, or never confirmed, counts as UNKNOWN with the default ceiling of 80. Campaigns use the ceiling minus 5.","properties":{"level":{"type":"string","enum":["COEXISTENCE","STANDARD","HIGH","UNKNOWN"],"example":"STANDARD"},"meta_level":{"type":["string","null"],"enum":["STANDARD","HIGH","NOT_APPLICABLE",null],"description":"Raw level stored from Meta. NOT_APPLICABLE means the number is not registered on the Cloud API.","example":"STANDARD"},"ceiling":{"type":"integer","example":80},"campaign_rate":{"type":"integer","example":75},"source":{"type":"string","enum":["coexistence","meta","stale","default"],"example":"meta"},"checked_at":{"type":["string","null"],"format":"date-time","example":"2026-10-01T12:00:00Z"},"coexistence":{"type":"boolean","example":false}},"example":{"level":"STANDARD","meta_level":"STANDARD","ceiling":80,"campaign_rate":75,"source":"meta","checked_at":"2026-10-01T12:00:00Z","coexistence":false}},"account_notices":{"type":"array","description":"Account warnings derived from the connection lifecycle, restrictions, violations, Conversation Routing and the webhook destination.","items":{"type":"object","properties":{"kind":{"type":"string","enum":["link_reonboarding","link_removed","reauthorization_required","restriction","violation","routing_other_owner","webhook_account_events_elsewhere","webhook_number_events_elsewhere"],"example":"restriction"},"severity":{"type":"string","enum":["critical","warning"],"example":"critical"},"data":{"type":"object","additionalProperties":true,"description":"Kind-specific details, such as type and expires_at of a restriction, count of routed conversations or the webhook target.","example":{"type":"RESTRICTED_BIZ_INITIATED_MESSAGING","expires_at":"2026-10-08T00:00:00Z"}}},"example":{"kind":"restriction","severity":"critical","data":{"type":"RESTRICTED_BIZ_INITIATED_MESSAGING","expires_at":"2026-10-08T00:00:00Z"}}},"example":[{"kind":"restriction","severity":"critical","data":{"type":"RESTRICTED_BIZ_INITIATED_MESSAGING","expires_at":"2026-10-08T00:00:00Z"}}]},"messaging_limit_usage":{"type":"object","description":"ESTIMATED use of the portfolio messaging limit in the last 24 hours: unique customers who received a template outside an open service window from the Cloud inboxes of this account in the same portfolio. Other apps and accounts on the portfolio are not counted.","properties":{"tier":{"type":["string","null"],"enum":["TIER_50","TIER_250","TIER_2K","TIER_10K","TIER_100K","TIER_NOT_SET","TIER_UNLIMITED",null],"example":"TIER_2K"},"limit":{"type":["integer","null"],"example":2000},"unlimited":{"type":"boolean","example":false},"window_hours":{"type":"integer","example":24},"estimated_recipients":{"type":["integer","null"],"example":412},"inbox_count":{"type":["integer","null"],"example":2},"computed_at":{"type":["string","null"],"format":"date-time","example":"2026-10-01T12:00:00Z"},"state":{"type":"string","enum":["estimated","unavailable"],"example":"estimated"},"evidence":{"type":"string","enum":["estimate"],"example":"estimate"}},"example":{"tier":"TIER_2K","limit":2000,"unlimited":false,"window_hours":24,"estimated_recipients":412,"inbox_count":2,"computed_at":"2026-10-01T12:00:00Z","state":"estimated","evidence":"estimate"}},"free_service_allowance":{"type":"object","description":"Counts for the number's estimated monthly service allowance; read `free_service_allowance.evidence`. Meta does not publish an allowance limit in the documentation tracked here. Present only for users who may view WhatsApp costs when the cost center is enabled and the allowance is shown.","properties":{"applicable":{"type":"boolean","example":true},"per_number":{"type":"integer","example":1000},"used":{"type":"integer","example":180},"charged":{"type":"integer","example":0},"remaining":{"type":"integer","example":820},"exhausted_at":{"type":["string","null"],"format":"date","example":null},"month":{"type":"string","format":"date","example":"2026-10-01"},"evidence":{"type":"string","example":"unverified"},"month_boundary_evidence":{"type":"string","example":"unverified"}},"example":{"applicable":true,"per_number":1000,"used":180,"charged":0,"remaining":820,"exhausted_at":null,"month":"2026-10-01","evidence":"unverified","month_boundary_evidence":"unverified"}},"app_subscriptions":{"type":"object","description":"Webhook fields subscribed by the inbox's Meta app compared with the fields the platform uses: this installation's app for an Embedded Signup inbox, the inbox's own app for a manual inbox with an App Secret. Without a secret, or when the read is not possible, the list is a manual checklist. callback_ours is false when the app callback points at another host: Meta always delivers account updates, account alerts and template status to the app callback, so this installation misses them.","properties":{"state":{"type":"string","enum":["checked","not_subscribed","manual","not_configured","unavailable","invalid_secret"],"example":"checked"},"app":{"type":"string","enum":["installation","inbox"],"example":"inbox"},"app_id":{"type":"string","example":"634974688087057"},"messages_subscribed":{"type":"boolean","description":"False means the app receives no customer messages.","example":true},"callback_target":{"type":"string","description":"Host and path of the app callback URL.","example":"app.example.com/webhooks/whatsapp"},"callback_ours":{"type":"boolean","description":"Whether the app callback points at this installation.","example":true},"expected_callback":{"type":"string","description":"The callback URL this installation expects.","example":"https://app.example.com/webhooks/whatsapp"},"active":{"type":"boolean","example":true},"subscribed_fields":{"type":"array","items":{"type":"string"},"example":["messages","smb_message_echoes"]},"required_fields":{"type":"array","items":{"type":"string"},"example":["messages","smb_message_echoes","account_update"]},"missing_fields":{"type":"array","items":{"type":"string"},"example":["account_update"]},"checked_at":{"type":"string","format":"date-time","example":"2026-10-01T12:00:00Z"},"evidence":{"type":"string","enum":["live"],"example":"live"}},"example":{"state":"checked","app":"inbox","app_id":"634974688087057","messages_subscribed":true,"callback_target":"app.example.com/webhooks/whatsapp","callback_ours":true,"expected_callback":"https://app.example.com/webhooks/whatsapp","active":true,"subscribed_fields":["messages","smb_message_echoes"],"required_fields":["messages","smb_message_echoes","account_update"],"missing_fields":["account_update"],"checked_at":"2026-10-01T12:00:00Z","evidence":"live"}},"subscribed_apps":{"type":"object","description":"Meta apps subscribed to the WhatsApp Business Account and where each one delivers. Where an app without its own override delivers is known only for the app of the inbox token; for the others the delivers_here key is absent. duplicate_delivery is true when more than one app delivers to this installation, so every webhook would arrive twice.","properties":{"state":{"type":"string","enum":["checked","unavailable"],"example":"checked"},"duplicate_delivery":{"type":"boolean","example":false},"checked_at":{"type":"string","format":"date-time","example":"2026-10-01T12:00:00Z"},"evidence":{"type":"string","enum":["official_replay"],"example":"official_replay"},"apps":{"type":"array","items":{"type":"object","properties":{"app_id":{"type":"string","example":"634974688087057"},"name":{"type":"string","example":"Acme Support App"},"override_callback_uri":{"type":"string","example":"https://app.example.com/webhooks/whatsapp"},"override_ours":{"type":"boolean","example":true},"token_app":{"type":"boolean","example":true},"installation_app":{"type":"boolean","example":false},"delivers_here":{"type":"boolean","example":true}},"example":{"app_id":"634974688087057","name":"Acme Support App","token_app":true,"installation_app":false,"delivers_here":true}},"example":[{"app_id":"634974688087057","name":"Acme Support App","token_app":true,"installation_app":false,"delivers_here":true}]}},"example":{"state":"checked","duplicate_delivery":false,"checked_at":"2026-10-01T12:00:00Z","evidence":"official_replay","apps":[{"app_id":"634974688087057","name":"Acme Support App","token_app":true,"installation_app":false,"delivers_here":true}]}},"connecting_app":{"type":"object","description":"The Meta app that connected the inbox and which secret verifies the signature of its webhooks. missing means an Embedded Signup inbox whose webhooks would be refused, or a manual inbox that accepts them unverified; unknown means the inbox was connected before the app was recorded. No secret is returned.","properties":{"source":{"type":"string","enum":["embedded_signup","manual"],"example":"embedded_signup"},"app_id":{"type":"string","example":"634974688087057"},"secret":{"type":"string","enum":["current","previous","inbox","missing","unknown"],"example":"current"}},"example":{"source":"embedded_signup","app_id":"634974688087057","secret":"current"}},"inbound_silence":{"type":"object","description":"Computed on read, never stored. `silent` is true when the inbox has been connected for more than `threshold_hours` without one live inbound message on the Cloud API (history imports, standby copies and messages delivered by the paired WhatsApp Web connection do not count). It usually means another WhatsApp partner is still the primary responder of the number in Conversation Routing.","properties":{"silent":{"type":"boolean","example":false},"connected_at":{"type":["string","null"],"format":"date-time","example":"2026-10-01T12:00:00Z"},"threshold_hours":{"type":"integer","example":24}},"example":{"silent":false,"connected_at":"2026-10-01T12:00:00Z","threshold_hours":24}}}},"example":{"health_state":"complete","health_checked_at":"2026-01-15T10:30:00.000Z","health_last_success_at":"2026-01-15T10:30:00.000Z","health_error":null,"id":"123456789012345","display_phone_number":"+1 555-010-0100","verified_name":"Acme Support","name_status":"APPROVED","quality_rating":"GREEN","quality_rating_previous":"GREEN","quality_rating_changed_at":"2026-10-01T09:00:00Z","quality_observed_at":"2026-10-01T12:00:00Z","quality_observed_source":"health_sync","messaging_limit_tier":"TIER_250","account_mode":"LIVE","code_verification_status":"VERIFIED","webhook_configuration":{"application":"https://app.example.com/webhooks/whatsapp"},"expected_webhook_url":"https://app.example.com/webhooks/whatsapp/+15550100100","expected_webhook_urls":["https://app.example.com/webhooks/whatsapp","https://app.example.com/webhooks/whatsapp/+15550100100"],"throughput":{"level":"STANDARD"},"last_onboarded_time":"2026-01-15T10:30:00.000Z","platform_type":"CLOUD_API","certificate":"CmIKHg... ","business_id":"987654321098765","throughput_level":"STANDARD","throughput_observed_at":"2026-10-01T08:00:00Z","throughput_observed_source":"health_sync","is_on_biz_app":false,"refreshed":true,"health_blocks":{"send_status":"ok","official_business_account":"cached","business_verification":"cached"},"health_status":{"can_send_message":"LIMITED","entities":[{"entity_type":"PHONE_NUMBER","id":"106540352242922","can_send_message":"LIMITED","can_receive_call_sip":"AVAILABLE","additional_info":["Your display name has not been approved yet. Your message limit will increase after the display name is approved."],"errors":[{"error_code":141002,"error_description":"Message templates can only be sent out if they are approved.","possible_solution":"Edit or appeal the message template review decision."}]},{"entity_type":"WABA","id":"102290129340398","can_send_message":"AVAILABLE","can_receive_call_sip":"AVAILABLE","additional_info":["Your display name has not been approved yet. Your message limit will increase after the display name is approved."],"errors":[{"error_code":141002,"error_description":"Message templates can only be sent out if they are approved.","possible_solution":"Edit or appeal the message template review decision."}]}]},"health_status_checked_at":"2026-10-01T12:00:00Z","official_business_account":{"oba_status":"APPROVED","status_message":"Your request was approved."},"official_business_account_checked_at":"2026-10-01T12:00:00Z","business_verification_status":"VERIFIED","account_review_status":"APPROVED","business_verification_checked_at":"2026-10-01T12:00:00Z","marketing_messages_onboarding_status":"NOT_STARTED","number_throughput":{"level":"STANDARD","meta_level":"STANDARD","ceiling":80,"campaign_rate":75,"source":"meta","checked_at":"2026-10-01T12:00:00Z","coexistence":false},"account_notices":[{"kind":"restriction","severity":"critical","data":{"type":"RESTRICTED_BIZ_INITIATED_MESSAGING","expires_at":"2026-10-08T00:00:00Z"}}],"messaging_limit_usage":{"tier":"TIER_2K","limit":2000,"unlimited":false,"window_hours":24,"estimated_recipients":412,"inbox_count":2,"computed_at":"2026-10-01T12:00:00Z","state":"estimated","evidence":"estimate"},"free_service_allowance":{"applicable":true,"per_number":1000,"used":180,"charged":0,"remaining":820,"exhausted_at":null,"month":"2026-10-01","evidence":"unverified","month_boundary_evidence":"unverified"},"app_subscriptions":{"state":"checked","app":"inbox","app_id":"634974688087057","messages_subscribed":true,"callback_target":"app.example.com/webhooks/whatsapp","callback_ours":true,"expected_callback":"https://app.example.com/webhooks/whatsapp","active":true,"subscribed_fields":["messages","smb_message_echoes"],"required_fields":["messages","smb_message_echoes","account_update"],"missing_fields":["account_update"],"checked_at":"2026-10-01T12:00:00Z","evidence":"live"},"subscribed_apps":{"state":"checked","duplicate_delivery":false,"checked_at":"2026-10-01T12:00:00Z","evidence":"official_replay","apps":[{"app_id":"634974688087057","name":"Acme Support App","token_app":true,"installation_app":false,"delivers_here":true,"override_callback_uri":"https://app.example.com/webhooks/whatsapp","override_ours":true}]},"connecting_app":{"source":"embedded_signup","app_id":"634974688087057","secret":"current"},"inbound_silence":{"silent":false,"connected_at":"2026-10-01T12:00:00Z","threshold_hours":24}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"422":{"description":"Health could not be refreshed; cached data is stale, or no snapshot is available.","content":{"application/json":{"schema":{"type":"object","required":["health_state","health_data","error"],"properties":{"health_state":{"type":"string","enum":["stale","unavailable"]},"health_data":{"anyOf":[{"type":"null"},{"type":"object","properties":{"health_state":{"type":"string","enum":["complete","partial"]},"health_checked_at":{"type":"string","format":"date-time"},"health_last_success_at":{"type":["string","null"],"format":"date-time"},"health_error":{"anyOf":[{"type":"null"},{"type":"object","required":["type","message","stage"],"properties":{"type":{"type":"string","enum":["authorization","api","generic"]},"message":{"type":"string"},"stage":{"type":"string","enum":["configuration","phone","business_account","business_profile"]},"http_status":{"type":"integer"},"code":{"type":"integer"},"subcode":{"type":"integer"}}}]},"id":{"type":"string","example":"123456789012345"},"display_phone_number":{"type":"string","example":"+1 555-010-0100"},"verified_name":{"type":"string","example":"Acme Support"},"name_status":{"type":"string","example":"APPROVED"},"quality_rating":{"type":"string","enum":["GREEN","YELLOW","RED","NA","UNKNOWN"],"example":"GREEN","description":"Meta quality rating. NA means not determined yet; the live API may also answer UNKNOWN."},"quality_rating_previous":{"type":["string","null"],"enum":["GREEN","YELLOW","RED","NA","UNKNOWN",null],"description":"Rating before the last change observed between two health checks of this installation. Meta does not date quality changes.","example":"GREEN"},"quality_rating_changed_at":{"type":["string","null"],"format":"date-time","description":"When this installation observed the last quality change.","example":"2026-10-01T09:00:00Z"},"quality_observed_at":{"type":["string","null"],"format":"date-time","description":"When Meta last answered the quality rating.","example":"2026-10-01T12:00:00Z"},"quality_observed_source":{"type":["string","null"],"enum":["health_sync","campaign_probe",null],"description":"Which read observed the rating: the periodic health check or a campaign quality check.","example":"health_sync"},"messaging_limit_tier":{"type":"string","description":"Business portfolio messaging limit (whatsapp_business_manager_messaging_limit), shared by every number of the portfolio.","example":"TIER_250"},"account_mode":{"type":"string","enum":["LIVE","SANDBOX"],"description":"LIVE is a production number; SANDBOX is a test number.","example":"LIVE"},"code_verification_status":{"type":"string","example":"VERIFIED"},"webhook_configuration":{"type":"object","description":"Meta webhook_configuration node","example":{"application":"https://app.example.com/webhooks/whatsapp"},"additionalProperties":true},"expected_webhook_url":{"type":["string","null"],"example":"https://app.example.com/webhooks/whatsapp/+15550100100"},"expected_webhook_urls":{"type":"array","items":{"type":"string"},"example":["https://app.example.com/webhooks/whatsapp","https://app.example.com/webhooks/whatsapp/+15550100100"]},"throughput":{"type":"object","description":"Meta throughput node","example":{"level":"STANDARD"},"additionalProperties":true},"last_onboarded_time":{"type":"string","format":"date-time","example":"2026-01-15T10:30:00.000Z"},"platform_type":{"type":"string","example":"CLOUD_API"},"certificate":{"type":["string","null"],"example":"CmIKHg... "},"business_id":{"type":"string","example":"987654321098765"},"throughput_level":{"type":["string","null"],"enum":["STANDARD","HIGH","NOT_APPLICABLE",null],"description":"Raw throughput level stored for the number.","example":"STANDARD"},"throughput_observed_at":{"type":["string","null"],"format":"date-time","description":"When the stored throughput level was observed: the Graph read time or the webhook time.","example":"2026-10-01T08:00:00Z"},"throughput_observed_source":{"type":["string","null"],"enum":["health_sync","webhook",null],"description":"Which source observed the stored throughput level.","example":"health_sync"},"is_on_biz_app":{"type":"boolean","description":"True when the number is also used in the WhatsApp Business app (coexistence).","example":false},"refreshed":{"type":"boolean","description":"False when this is the answer of a live read made less than 30 seconds ago.","example":true},"health_blocks":{"type":"object","description":"Outcome of each optional read of this request. A block marked unavailable kept its previous value.","properties":{"send_status":{"type":"string","enum":["ok","unavailable"],"example":"ok"},"official_business_account":{"type":"string","enum":["ok","cached","unavailable"],"example":"cached"},"business_verification":{"type":"string","enum":["ok","cached","unavailable"],"example":"cached"}},"example":{"send_status":"ok","official_business_account":"cached","business_verification":"cached"}},"health_status":{"type":["object","null"],"description":"Meta Health Status API of the number. The overall value exists only for messages; LIMITED entities carry additional_info and BLOCKED entities carry errors with a possible solution.","properties":{"can_send_message":{"type":"string","enum":["AVAILABLE","LIMITED","BLOCKED"],"example":"AVAILABLE"},"entities":{"type":"array","items":{"type":"object","properties":{"entity_type":{"type":"string","enum":["PHONE_NUMBER","WABA","BUSINESS","APP","MESSAGE_TEMPLATE"],"example":"PHONE_NUMBER"},"id":{"type":"string","example":"106540352242922"},"can_send_message":{"type":"string","enum":["AVAILABLE","LIMITED","BLOCKED"],"example":"LIMITED"},"can_receive_call_sip":{"type":"string","enum":["AVAILABLE","LIMITED","BLOCKED"],"example":"AVAILABLE"},"additional_info":{"type":"array","items":{"type":"string"},"example":["Your display name has not been approved yet. Your message limit will increase after the display name is approved."]},"errors":{"type":"array","items":{"type":"object","properties":{"error_code":{"type":"integer","example":141002},"error_description":{"type":"string","example":"Message templates can only be sent out if they are approved."},"possible_solution":{"type":"string","example":"Edit or appeal the message template review decision."}},"example":{"error_code":141002,"error_description":"Message templates can only be sent out if they are approved.","possible_solution":"Edit or appeal the message template review decision."}}}},"example":{"entity_type":"PHONE_NUMBER","id":"106540352242922","can_send_message":"LIMITED","can_receive_call_sip":"AVAILABLE","additional_info":["Your display name has not been approved yet. Your message limit will increase after the display name is approved."]}},"example":[{"entity_type":"PHONE_NUMBER","id":"106540352242922","can_send_message":"LIMITED","can_receive_call_sip":"AVAILABLE","additional_info":["Your display name has not been approved yet. Your message limit will increase after the display name is approved."]},{"entity_type":"WABA","id":"102290129340398","can_send_message":"AVAILABLE"}]}},"example":{"can_send_message":"LIMITED","entities":[{"entity_type":"PHONE_NUMBER","id":"106540352242922","can_send_message":"LIMITED","can_receive_call_sip":"AVAILABLE","additional_info":["Your display name has not been approved yet. Your message limit will increase after the display name is approved."]},{"entity_type":"WABA","id":"102290129340398","can_send_message":"AVAILABLE"}]}},"health_status_checked_at":{"type":["string","null"],"format":"date-time","description":"When Meta last answered the Health Status API.","example":"2026-10-01T12:00:00Z"},"official_business_account":{"type":["object","null"],"description":"Official business account (blue badge) request status of the number.","properties":{"oba_status":{"type":"string","enum":["PENDING","APPROVED","REJECTED","UNDER_REVIEW","EXPIRED","CANCELLED","NOT_STARTED"],"description":"NOT_STARTED appears in a Meta example although outside its documented enum.","example":"APPROVED"},"status_message":{"type":"string","example":"Your request was approved."}},"example":{"oba_status":"APPROVED"}},"official_business_account_checked_at":{"type":["string","null"],"format":"date-time","example":"2026-10-01T12:00:00Z"},"business_verification_status":{"type":["string","null"],"enum":["EXPIRED","FAILED","INELIGIBLE","NOT_VERIFIED","PENDING","PENDING_NEED_MORE_INFO","PENDING_SUBMISSION","REJECTED","REVOKED","VERIFIED",null],"description":"Meta verification of the business that owns the WhatsApp Business Account.","example":"VERIFIED"},"account_review_status":{"type":["string","null"],"enum":["APPROVED","DEFERRED","PENDING","REJECTED",null],"description":"Meta review of the WhatsApp Business Account.","example":"APPROVED"},"business_verification_checked_at":{"type":["string","null"],"format":"date-time","example":"2026-10-01T12:00:00Z"},"marketing_messages_onboarding_status":{"type":["string","null"],"description":"Marketing Messages API onboarding status of the business portfolio, as Meta reports it (for example NOT_STARTED).","example":"NOT_STARTED"},"number_throughput":{"type":"object","description":"Sending speed of the number at Meta: 80 messages per second by default, up to 1,000 after an automatic upgrade, fixed at 20 on a coexistence number. A level Meta has not confirmed in the last 24 hours, or never confirmed, counts as UNKNOWN with the default ceiling of 80. Campaigns use the ceiling minus 5.","properties":{"level":{"type":"string","enum":["COEXISTENCE","STANDARD","HIGH","UNKNOWN"],"example":"STANDARD"},"meta_level":{"type":["string","null"],"enum":["STANDARD","HIGH","NOT_APPLICABLE",null],"description":"Raw level stored from Meta. NOT_APPLICABLE means the number is not registered on the Cloud API.","example":"STANDARD"},"ceiling":{"type":"integer","example":80},"campaign_rate":{"type":"integer","example":75},"source":{"type":"string","enum":["coexistence","meta","stale","default"],"example":"meta"},"checked_at":{"type":["string","null"],"format":"date-time","example":"2026-10-01T12:00:00Z"},"coexistence":{"type":"boolean","example":false}},"example":{"level":"STANDARD","meta_level":"STANDARD","ceiling":80,"campaign_rate":75,"source":"meta","checked_at":"2026-10-01T12:00:00Z","coexistence":false}},"account_notices":{"type":"array","description":"Account warnings derived from the connection lifecycle, restrictions, violations, Conversation Routing and the webhook destination.","items":{"type":"object","properties":{"kind":{"type":"string","enum":["link_reonboarding","link_removed","reauthorization_required","restriction","violation","routing_other_owner","webhook_account_events_elsewhere","webhook_number_events_elsewhere"],"example":"restriction"},"severity":{"type":"string","enum":["critical","warning"],"example":"critical"},"data":{"type":"object","additionalProperties":true,"description":"Kind-specific details, such as type and expires_at of a restriction, count of routed conversations or the webhook target.","example":{"type":"RESTRICTED_BIZ_INITIATED_MESSAGING","expires_at":"2026-10-08T00:00:00Z"}}},"example":{"kind":"restriction","severity":"critical","data":{"type":"RESTRICTED_BIZ_INITIATED_MESSAGING","expires_at":"2026-10-08T00:00:00Z"}}},"example":[{"kind":"restriction","severity":"critical","data":{"type":"RESTRICTED_BIZ_INITIATED_MESSAGING","expires_at":"2026-10-08T00:00:00Z"}}]},"messaging_limit_usage":{"type":"object","description":"ESTIMATED use of the portfolio messaging limit in the last 24 hours: unique customers who received a template outside an open service window from the Cloud inboxes of this account in the same portfolio. Other apps and accounts on the portfolio are not counted.","properties":{"tier":{"type":["string","null"],"enum":["TIER_50","TIER_250","TIER_2K","TIER_10K","TIER_100K","TIER_NOT_SET","TIER_UNLIMITED",null],"example":"TIER_2K"},"limit":{"type":["integer","null"],"example":2000},"unlimited":{"type":"boolean","example":false},"window_hours":{"type":"integer","example":24},"estimated_recipients":{"type":["integer","null"],"example":412},"inbox_count":{"type":["integer","null"],"example":2},"computed_at":{"type":["string","null"],"format":"date-time","example":"2026-10-01T12:00:00Z"},"state":{"type":"string","enum":["estimated","unavailable"],"example":"estimated"},"evidence":{"type":"string","enum":["estimate"],"example":"estimate"}},"example":{"tier":"TIER_2K","limit":2000,"unlimited":false,"window_hours":24,"estimated_recipients":412,"inbox_count":2,"computed_at":"2026-10-01T12:00:00Z","state":"estimated","evidence":"estimate"}},"free_service_allowance":{"type":"object","description":"Counts for the number's estimated monthly service allowance; read `free_service_allowance.evidence`. Meta does not publish an allowance limit in the documentation tracked here. Present only for users who may view WhatsApp costs when the cost center is enabled and the allowance is shown.","properties":{"applicable":{"type":"boolean","example":true},"per_number":{"type":"integer","example":1000},"used":{"type":"integer","example":180},"charged":{"type":"integer","example":0},"remaining":{"type":"integer","example":820},"exhausted_at":{"type":["string","null"],"format":"date","example":null},"month":{"type":"string","format":"date","example":"2026-10-01"},"evidence":{"type":"string","example":"unverified"},"month_boundary_evidence":{"type":"string","example":"unverified"}},"example":{"applicable":true,"per_number":1000,"used":180,"charged":0,"remaining":820,"exhausted_at":null,"month":"2026-10-01","evidence":"unverified","month_boundary_evidence":"unverified"}},"app_subscriptions":{"type":"object","description":"Webhook fields subscribed by the inbox's Meta app compared with the fields the platform uses: this installation's app for an Embedded Signup inbox, the inbox's own app for a manual inbox with an App Secret. Without a secret, or when the read is not possible, the list is a manual checklist. callback_ours is false when the app callback points at another host: Meta always delivers account updates, account alerts and template status to the app callback, so this installation misses them.","properties":{"state":{"type":"string","enum":["checked","not_subscribed","manual","not_configured","unavailable","invalid_secret"],"example":"checked"},"app":{"type":"string","enum":["installation","inbox"],"example":"inbox"},"app_id":{"type":"string","example":"634974688087057"},"messages_subscribed":{"type":"boolean","description":"False means the app receives no customer messages.","example":true},"callback_target":{"type":"string","description":"Host and path of the app callback URL.","example":"app.example.com/webhooks/whatsapp"},"callback_ours":{"type":"boolean","description":"Whether the app callback points at this installation.","example":true},"expected_callback":{"type":"string","description":"The callback URL this installation expects.","example":"https://app.example.com/webhooks/whatsapp"},"active":{"type":"boolean","example":true},"subscribed_fields":{"type":"array","items":{"type":"string"},"example":["messages","smb_message_echoes"]},"required_fields":{"type":"array","items":{"type":"string"},"example":["messages","smb_message_echoes","account_update"]},"missing_fields":{"type":"array","items":{"type":"string"},"example":["account_update"]},"checked_at":{"type":"string","format":"date-time","example":"2026-10-01T12:00:00Z"},"evidence":{"type":"string","enum":["live"],"example":"live"}},"example":{"state":"checked","app":"inbox","app_id":"634974688087057","messages_subscribed":true,"callback_target":"app.example.com/webhooks/whatsapp","callback_ours":true,"expected_callback":"https://app.example.com/webhooks/whatsapp","active":true,"subscribed_fields":["messages","smb_message_echoes"],"required_fields":["messages","smb_message_echoes","account_update"],"missing_fields":["account_update"],"checked_at":"2026-10-01T12:00:00Z","evidence":"live"}},"subscribed_apps":{"type":"object","description":"Meta apps subscribed to the WhatsApp Business Account and where each one delivers. Where an app without its own override delivers is known only for the app of the inbox token; for the others the delivers_here key is absent. duplicate_delivery is true when more than one app delivers to this installation, so every webhook would arrive twice.","properties":{"state":{"type":"string","enum":["checked","unavailable"],"example":"checked"},"duplicate_delivery":{"type":"boolean","example":false},"checked_at":{"type":"string","format":"date-time","example":"2026-10-01T12:00:00Z"},"evidence":{"type":"string","enum":["official_replay"],"example":"official_replay"},"apps":{"type":"array","items":{"type":"object","properties":{"app_id":{"type":"string","example":"634974688087057"},"name":{"type":"string","example":"Acme Support App"},"override_callback_uri":{"type":"string","example":"https://app.example.com/webhooks/whatsapp"},"override_ours":{"type":"boolean","example":true},"token_app":{"type":"boolean","example":true},"installation_app":{"type":"boolean","example":false},"delivers_here":{"type":"boolean","example":true}},"example":{"app_id":"634974688087057","name":"Acme Support App","token_app":true,"installation_app":false,"delivers_here":true}},"example":[{"app_id":"634974688087057","name":"Acme Support App","token_app":true,"installation_app":false,"delivers_here":true}]}},"example":{"state":"checked","duplicate_delivery":false,"checked_at":"2026-10-01T12:00:00Z","evidence":"official_replay","apps":[{"app_id":"634974688087057","name":"Acme Support App","token_app":true,"installation_app":false,"delivers_here":true}]}},"connecting_app":{"type":"object","description":"The Meta app that connected the inbox and which secret verifies the signature of its webhooks. missing means an Embedded Signup inbox whose webhooks would be refused, or a manual inbox that accepts them unverified; unknown means the inbox was connected before the app was recorded. No secret is returned.","properties":{"source":{"type":"string","enum":["embedded_signup","manual"],"example":"embedded_signup"},"app_id":{"type":"string","example":"634974688087057"},"secret":{"type":"string","enum":["current","previous","inbox","missing","unknown"],"example":"current"}},"example":{"source":"embedded_signup","app_id":"634974688087057","secret":"current"}},"inbound_silence":{"type":"object","description":"Computed on read, never stored. `silent` is true when the inbox has been connected for more than `threshold_hours` without one live inbound message on the Cloud API (history imports, standby copies and messages delivered by the paired WhatsApp Web connection do not count). It usually means another WhatsApp partner is still the primary responder of the number in Conversation Routing.","properties":{"silent":{"type":"boolean","example":false},"connected_at":{"type":["string","null"],"format":"date-time","example":"2026-10-01T12:00:00Z"},"threshold_hours":{"type":"integer","example":24}},"example":{"silent":false,"connected_at":"2026-10-01T12:00:00Z","threshold_hours":24}}}}]},"error":{"type":"object","required":["type","message","stage"],"properties":{"type":{"type":"string","enum":["authorization","api","generic"]},"message":{"type":"string"},"stage":{"type":"string","enum":["configuration","phone","business_account","business_profile"]},"http_status":{"type":"integer"},"code":{"type":"integer"},"subcode":{"type":"integer"}}}}},"example":{"health_state":"stale","health_data":null,"error":{"type":"authorization","message":"Sample message text.","stage":"configuration","http_status":1,"code":1,"subcode":1}}}}},"400":{"description":"Not a WhatsApp Cloud channel","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Health data only available for WhatsApp Cloud API channels"}}},"example":{"error":"Health data only available for WhatsApp Cloud API channels"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"refresh","in":"query","required":false,"description":"The Account Health \"Check now\" action. Also renews the cached details (official business account status, business verification, account review, the app webhook subscriptions and the apps subscribed to the WhatsApp Business Account).","schema":{"type":"boolean","default":false},"example":true}]}},"/api/v1/accounts/{account_id}/inboxes/{id}/remove_whatsapp_legacy_app":{"post":{"tags":["Inboxes"],"operationId":"auto_post_api_v1_accounts_account_id_inboxes_id_remove_whatsapp_legacy_app","summary":"Remove the previous Meta app from a migrated WhatsApp Business Account","description":"Administrator-only, explicit action after an embedded signup inbox was transferred to the customer's own Meta app. The installation's shared app stays subscribed to the WhatsApp Business Account, so every webhook arrives twice until it is removed. Before unsubscribing it, the server re-reads Meta live and refuses unless the transfer is complete, the previous app is the installation's own app on this account, no other inbox on the account still depends on it, the customer's app is subscribed and delivers this number's webhooks here, and delivery is proven: a webhook signed with the inbox App Secret arrived after the transfer or, without an App Secret, the operator confirms that a test message arrived. Meta stops delivering to the previous app immediately; the removal can be undone for 72 hours. When the stored credential of the previous app is no longer usable, the state becomes `guided` and the operator finishes in Meta's tools.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The previous app was unsubscribed and Meta no longer lists it on the account","content":{"application/json":{"schema":{"type":"object","required":["legacy_app"],"properties":{"legacy_app":{"type":"object","description":"Non-secret state of the previous app on the WhatsApp Business Account.","required":["state"],"properties":{"app_id":{"type":"string","description":"Meta app id of the previous app","example":"944871610481729"},"app_name":{"type":"string","description":"Meta app name of the previous app","example":"Setup Automatizado"},"state":{"type":"string","enum":["subscribed","guided","removed"],"description":"`subscribed` — still delivering here and removable; `guided` — the operator must remove it in Meta's tools; `removed` — unsubscribed (undo available until `undo_until`).","example":"removed"},"identified_at":{"type":"string","format":"date-time","example":"2026-10-01T19:07:12Z"},"removed_at":{"type":"string","format":"date-time","example":"2026-10-02T12:30:00Z"},"restored_at":{"type":"string","format":"date-time","example":"2026-10-02T13:05:00Z"},"undo_until":{"type":"string","format":"date-time","example":"2026-10-05T12:30:00Z"}}}}},"example":{"legacy_app":{"app_id":"944871610481729","app_name":"Setup Automatizado","state":"removed","identified_at":"2026-10-01T19:07:12Z","removed_at":"2026-10-02T12:30:00Z","undo_until":"2026-10-05T12:30:00Z","restored_at":"2026-10-02T13:05:00Z"}}}}},"401":{"description":"Missing or invalid account API credential"},"404":{"description":"Inbox does not exist in the current account"},"403":{"description":"Administrator role required"},"422":{"description":"The removal was refused; `message` says which guard failed and what to do, and `legacy_app` is the current state (for example `guided` once the previous app's credential stopped working).","content":{"application/json":{"schema":{"type":"object","required":["error","message","legacy_app"],"properties":{"error":{"type":"string","enum":["legacy_app_refused"],"example":"legacy_app_refused"},"message":{"type":"string","description":"Translated reason and next step","example":"The time to undo the removal of the app Setup Automatizado has ended."},"legacy_app":{"type":"object","description":"Non-secret state of the previous app on the WhatsApp Business Account.","required":["state"],"properties":{"app_id":{"type":"string","description":"Meta app id of the previous app","example":"944871610481729"},"app_name":{"type":"string","description":"Meta app name of the previous app","example":"Setup Automatizado"},"state":{"type":"string","enum":["subscribed","guided","removed"],"description":"`subscribed` — still delivering here and removable; `guided` — the operator must remove it in Meta's tools; `removed` — unsubscribed (undo available until `undo_until`).","example":"removed"},"identified_at":{"type":"string","format":"date-time","example":"2026-10-01T19:07:12Z"},"removed_at":{"type":"string","format":"date-time","example":"2026-10-02T12:30:00Z"},"restored_at":{"type":"string","format":"date-time","example":"2026-10-02T13:05:00Z"},"undo_until":{"type":"string","format":"date-time","example":"2026-10-05T12:30:00Z"}}}}},"example":{"error":"legacy_app_refused","message":"No webhook signed with your App Secret has arrived since the transfer. Send a test message to this number, wait a minute, and try again. The app Setup Automatizado was kept.","legacy_app":{"app_id":"944871610481729","app_name":"Setup Automatizado","state":"subscribed","identified_at":"2026-10-01T19:07:12Z","removed_at":"2026-10-02T12:30:00Z","restored_at":"2026-10-02T13:05:00Z","undo_until":"2026-10-05T12:30:00Z"}}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"test_message_confirmed":{"type":"boolean","description":"The operator confirms that a test message sent to the number after the transfer arrived in the inbox. Required when the inbox has no App Secret; ignored when it has one (the signed webhook is the proof).","example":true}}},"example":{"test_message_confirmed":true}}}}}},"/api/v1/accounts/{account_id}/inboxes/{id}/restore_whatsapp_legacy_app":{"post":{"tags":["Inboxes"],"operationId":"auto_post_api_v1_accounts_account_id_inboxes_id_restore_whatsapp_legacy_app","summary":"Undo the removal of the previous Meta app","description":"Administrator-only, explicit action available for 72 hours after the previous app was removed. It subscribes the previous app to the WhatsApp Business Account again with this number's callback and the inbox verify token, then re-reads Meta to confirm it is listed. Webhooks may arrive twice again until the app is removed.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The previous app is subscribed again","content":{"application/json":{"schema":{"type":"object","required":["legacy_app"],"properties":{"legacy_app":{"type":"object","description":"Non-secret state of the previous app on the WhatsApp Business Account.","required":["state"],"properties":{"app_id":{"type":"string","description":"Meta app id of the previous app","example":"944871610481729"},"app_name":{"type":"string","description":"Meta app name of the previous app","example":"Setup Automatizado"},"state":{"type":"string","enum":["subscribed","guided","removed"],"description":"`subscribed` — still delivering here and removable; `guided` — the operator must remove it in Meta's tools; `removed` — unsubscribed (undo available until `undo_until`).","example":"removed"},"identified_at":{"type":"string","format":"date-time","example":"2026-10-01T19:07:12Z"},"removed_at":{"type":"string","format":"date-time","example":"2026-10-02T12:30:00Z"},"restored_at":{"type":"string","format":"date-time","example":"2026-10-02T13:05:00Z"},"undo_until":{"type":"string","format":"date-time","example":"2026-10-05T12:30:00Z"}}}}},"example":{"legacy_app":{"app_id":"944871610481729","app_name":"Setup Automatizado","state":"subscribed","identified_at":"2026-10-01T19:07:12Z","restored_at":"2026-10-02T13:05:00Z","removed_at":"2026-10-02T12:30:00Z","undo_until":"2026-10-05T12:30:00Z"}}}}},"401":{"description":"Missing or invalid account API credential"},"404":{"description":"Inbox does not exist in the current account"},"403":{"description":"Administrator role required"},"422":{"description":"The undo was refused (window ended, nothing to undo, or Meta unavailable); `legacy_app` is the current state","content":{"application/json":{"schema":{"type":"object","required":["error","message","legacy_app"],"properties":{"error":{"type":"string","enum":["legacy_app_refused"],"example":"legacy_app_refused"},"message":{"type":"string","description":"Translated reason and next step","example":"The time to undo the removal of the app Setup Automatizado has ended."},"legacy_app":{"type":"object","description":"Non-secret state of the previous app on the WhatsApp Business Account.","required":["state"],"properties":{"app_id":{"type":"string","description":"Meta app id of the previous app","example":"944871610481729"},"app_name":{"type":"string","description":"Meta app name of the previous app","example":"Setup Automatizado"},"state":{"type":"string","enum":["subscribed","guided","removed"],"description":"`subscribed` — still delivering here and removable; `guided` — the operator must remove it in Meta's tools; `removed` — unsubscribed (undo available until `undo_until`).","example":"removed"},"identified_at":{"type":"string","format":"date-time","example":"2026-10-01T19:07:12Z"},"removed_at":{"type":"string","format":"date-time","example":"2026-10-02T12:30:00Z"},"restored_at":{"type":"string","format":"date-time","example":"2026-10-02T13:05:00Z"},"undo_until":{"type":"string","format":"date-time","example":"2026-10-05T12:30:00Z"}}}}},"example":{"error":"legacy_app_refused","message":"The time to undo the removal of the app Setup Automatizado has ended.","legacy_app":{"app_id":"944871610481729","app_name":"Setup Automatizado","state":"removed","identified_at":"2026-10-01T19:07:12Z","removed_at":"2026-10-01T09:00:00Z","restored_at":"2026-10-02T13:05:00Z","undo_until":"2026-10-05T12:30:00Z"}}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/inboxes/{id}/catalog_commerce":{"get":{"tags":["Inboxes"],"operationId":"auto_get_api_v1_accounts_account_id_inboxes_id_catalog_commerce","summary":"Catalog commerce inboxes","description":"Performs the catalog commerce operation on the targeted inbox resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Live WhatsApp commerce state of this number, read from Meta","content":{"application/json":{"schema":{"type":"object","properties":{"supported":{"type":"boolean","description":"False when the inbox is not a WhatsApp Cloud channel","example":true},"catalog":{"type":["object","null"],"description":"The catalog this number serves, or null when none is bound","properties":{"id":{"type":"string","example":"27625697493693610"},"name":{"type":["string","null"],"example":"Loja ConversaLabs"}}},"available_catalogs":{"type":"array","description":"Catalogs readable on this WhatsApp Business Account","items":{"type":"object","properties":{"id":{"type":"string","example":"27625697493693610"},"name":{"type":["string","null"],"example":"Loja ConversaLabs"}}}},"linked_to_waba":{"type":"boolean","description":"Whether the catalog is bound to the WABA (implicit on SMB/Coexistence)","example":true},"storefront":{"type":"object","description":"Meta whatsapp_commerce_settings for this phone number; null means the flag could not be read","properties":{"catalog_visible":{"type":["boolean","null"],"example":false},"cart_enabled":{"type":["boolean","null"],"example":false}}},"items":{"type":"object","description":"Item counts in the bound catalog","properties":{"total":{"type":"integer","example":12},"from_conversalabs":{"type":"integer","description":"Items whose retailer_id was minted here (cw_ prefix)","example":8}}},"sync":{"type":["object","null"],"description":"The catalog sync source bound to this inbox, or null when none exists","properties":{"source_id":{"type":"integer","example":3},"enabled":{"type":"boolean","example":true},"last_status":{"type":["string","null"],"enum":["pending","processing","completed","failed","partial",null],"example":"completed"},"last_run_at":{"type":["string","null"],"format":"date-time","example":"2026-08-12T03:15:00.000Z"}}},"blockers":{"type":"array","description":"Ordered machine codes for what is preventing a native product message","items":{"type":"string","enum":["catalog_not_selected","sync_source_missing","catalog_not_linked","catalog_not_visible","no_items"]},"example":["catalog_not_visible"]},"ready_to_send":{"type":"boolean","description":"True only when the blocker list is empty","example":false},"errors":{"type":"object","description":"Per-read Meta failures, keyed by what could not be read (catalogs, commerce_settings, items). Absent keys read fine.","additionalProperties":{"type":"string"},"example":{"catalogs":"meta_request_failed: list_catalogs HTTP 401 — Invalid OAuth access token"}}}},"example":{"supported":true,"catalog":{"id":"27625697493693610","name":"Loja ConversaLabs"},"available_catalogs":[{"id":"27625697493693610","name":"Loja ConversaLabs"}],"linked_to_waba":true,"storefront":{"catalog_visible":false,"cart_enabled":false},"items":{"total":12,"from_conversalabs":8},"sync":{"source_id":3,"enabled":true,"last_status":"completed","last_run_at":"2026-08-12T03:15:00.000Z"},"blockers":["catalog_not_visible"],"ready_to_send":false,"errors":{}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"400":{"description":"Not a WhatsApp Cloud channel, or Meta refused the write","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"This inbox is not a WhatsApp Cloud API inbox, so it has no catalog or storefront."}}},"example":{"error":"This inbox is not a WhatsApp Cloud API inbox, so it has no catalog or storefront."}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/inboxes/{id}/link_catalog":{"post":{"tags":["Inboxes"],"operationId":"auto_post_api_v1_accounts_account_id_inboxes_id_link_catalog","summary":"Link catalog inboxes","description":"Performs the link catalog operation on the targeted inbox resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Live WhatsApp commerce state of this number, read from Meta","content":{"application/json":{"schema":{"type":"object","properties":{"supported":{"type":"boolean","description":"False when the inbox is not a WhatsApp Cloud channel","example":true},"catalog":{"type":["object","null"],"description":"The catalog this number serves, or null when none is bound","properties":{"id":{"type":"string","example":"27625697493693610"},"name":{"type":["string","null"],"example":"Loja ConversaLabs"}}},"available_catalogs":{"type":"array","description":"Catalogs readable on this WhatsApp Business Account","items":{"type":"object","properties":{"id":{"type":"string","example":"27625697493693610"},"name":{"type":["string","null"],"example":"Loja ConversaLabs"}}}},"linked_to_waba":{"type":"boolean","description":"Whether the catalog is bound to the WABA (implicit on SMB/Coexistence)","example":true},"storefront":{"type":"object","description":"Meta whatsapp_commerce_settings for this phone number; null means the flag could not be read","properties":{"catalog_visible":{"type":["boolean","null"],"example":false},"cart_enabled":{"type":["boolean","null"],"example":false}}},"items":{"type":"object","description":"Item counts in the bound catalog","properties":{"total":{"type":"integer","example":12},"from_conversalabs":{"type":"integer","description":"Items whose retailer_id was minted here (cw_ prefix)","example":8}}},"sync":{"type":["object","null"],"description":"The catalog sync source bound to this inbox, or null when none exists","properties":{"source_id":{"type":"integer","example":3},"enabled":{"type":"boolean","example":true},"last_status":{"type":["string","null"],"enum":["pending","processing","completed","failed","partial",null],"example":"completed"},"last_run_at":{"type":["string","null"],"format":"date-time","example":"2026-08-12T03:15:00.000Z"}}},"blockers":{"type":"array","description":"Ordered machine codes for what is preventing a native product message","items":{"type":"string","enum":["catalog_not_selected","sync_source_missing","catalog_not_linked","catalog_not_visible","no_items"]},"example":["catalog_not_visible"]},"ready_to_send":{"type":"boolean","description":"True only when the blocker list is empty","example":false},"errors":{"type":"object","description":"Per-read Meta failures, keyed by what could not be read (catalogs, commerce_settings, items). Absent keys read fine.","additionalProperties":{"type":"string"},"example":{"catalogs":"meta_request_failed: list_catalogs HTTP 401 — Invalid OAuth access token"}}}},"example":{"supported":true,"catalog":{"id":"27625697493693610","name":"Loja ConversaLabs"},"available_catalogs":[{"id":"27625697493693610","name":"Loja ConversaLabs"}],"linked_to_waba":true,"storefront":{"catalog_visible":false,"cart_enabled":false},"items":{"total":12,"from_conversalabs":8},"sync":{"source_id":3,"enabled":true,"last_status":"completed","last_run_at":"2026-08-12T03:15:00.000Z"},"blockers":["catalog_not_visible"],"ready_to_send":false,"errors":{}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"400":{"description":"Not a WhatsApp Cloud channel, or Meta refused the write","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"This inbox is not a WhatsApp Cloud API inbox, so it has no catalog or storefront."}}},"example":{"error":"This inbox is not a WhatsApp Cloud API inbox, so it has no catalog or storefront."}}}},"422":{"description":"Not a WhatsApp Cloud channel, or Meta refused the write","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"This inbox is not a WhatsApp Cloud API inbox, so it has no catalog or storefront."}}},"example":{"error":"This inbox is not a WhatsApp Cloud API inbox, so it has no catalog or storefront."}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["catalog_id"],"properties":{"catalog_id":{"type":"string","description":"Meta product catalog id, from available_catalogs","example":"27625697493693610"}}},"example":{"catalog_id":"27625697493693610"}}}}}},"/api/v1/accounts/{account_id}/inboxes/{id}/update_catalog_storefront":{"post":{"tags":["Inboxes"],"operationId":"auto_post_api_v1_accounts_account_id_inboxes_id_update_catalog_storefront","summary":"Update catalog storefront inboxes","description":"Performs the update catalog storefront operation on the targeted inbox resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Live WhatsApp commerce state of this number, read from Meta","content":{"application/json":{"schema":{"type":"object","properties":{"supported":{"type":"boolean","description":"False when the inbox is not a WhatsApp Cloud channel","example":true},"catalog":{"type":["object","null"],"description":"The catalog this number serves, or null when none is bound","properties":{"id":{"type":"string","example":"27625697493693610"},"name":{"type":["string","null"],"example":"Loja ConversaLabs"}}},"available_catalogs":{"type":"array","description":"Catalogs readable on this WhatsApp Business Account","items":{"type":"object","properties":{"id":{"type":"string","example":"27625697493693610"},"name":{"type":["string","null"],"example":"Loja ConversaLabs"}}}},"linked_to_waba":{"type":"boolean","description":"Whether the catalog is bound to the WABA (implicit on SMB/Coexistence)","example":true},"storefront":{"type":"object","description":"Meta whatsapp_commerce_settings for this phone number; null means the flag could not be read","properties":{"catalog_visible":{"type":["boolean","null"],"example":false},"cart_enabled":{"type":["boolean","null"],"example":false}}},"items":{"type":"object","description":"Item counts in the bound catalog","properties":{"total":{"type":"integer","example":12},"from_conversalabs":{"type":"integer","description":"Items whose retailer_id was minted here (cw_ prefix)","example":8}}},"sync":{"type":["object","null"],"description":"The catalog sync source bound to this inbox, or null when none exists","properties":{"source_id":{"type":"integer","example":3},"enabled":{"type":"boolean","example":true},"last_status":{"type":["string","null"],"enum":["pending","processing","completed","failed","partial",null],"example":"completed"},"last_run_at":{"type":["string","null"],"format":"date-time","example":"2026-08-12T03:15:00.000Z"}}},"blockers":{"type":"array","description":"Ordered machine codes for what is preventing a native product message","items":{"type":"string","enum":["catalog_not_selected","sync_source_missing","catalog_not_linked","catalog_not_visible","no_items"]},"example":["catalog_not_visible"]},"ready_to_send":{"type":"boolean","description":"True only when the blocker list is empty","example":false},"errors":{"type":"object","description":"Per-read Meta failures, keyed by what could not be read (catalogs, commerce_settings, items). Absent keys read fine.","additionalProperties":{"type":"string"},"example":{"catalogs":"meta_request_failed: list_catalogs HTTP 401 — Invalid OAuth access token"}}}},"example":{"supported":true,"catalog":{"id":"27625697493693610","name":"Loja ConversaLabs"},"available_catalogs":[{"id":"27625697493693610","name":"Loja ConversaLabs"}],"linked_to_waba":true,"storefront":{"catalog_visible":false,"cart_enabled":false},"items":{"total":12,"from_conversalabs":8},"sync":{"source_id":3,"enabled":true,"last_status":"completed","last_run_at":"2026-08-12T03:15:00.000Z"},"blockers":["catalog_not_visible"],"ready_to_send":false,"errors":{}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"400":{"description":"Not a WhatsApp Cloud channel, or Meta refused the write","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"This inbox is not a WhatsApp Cloud API inbox, so it has no catalog or storefront."}}},"example":{"error":"This inbox is not a WhatsApp Cloud API inbox, so it has no catalog or storefront."}}}},"422":{"description":"Not a WhatsApp Cloud channel, or Meta refused the write","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"This inbox is not a WhatsApp Cloud API inbox, so it has no catalog or storefront."}}},"example":{"error":"This inbox is not a WhatsApp Cloud API inbox, so it has no catalog or storefront."}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"catalog_visible":{"type":"boolean","description":"Show the catalog on this number. Omit to leave unchanged.","example":true},"cart_enabled":{"type":"boolean","description":"Allow the customer to assemble an order. Omit to leave unchanged.","example":true}}},"example":{"catalog_visible":true,"cart_enabled":true}}}}}},"/api/v1/accounts/{account_id}/inboxes/{id}/register_webhook":{"post":{"tags":["Inboxes"],"operationId":"auto_post_api_v1_accounts_account_id_inboxes_id_register_webhook","summary":"Register webhook inboxes","description":"Performs the register webhook operation on the targeted inbox resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"error":{"type":"string","example":"This inbox is in manual webhook mode. Configure the webhook in the Meta App Dashboard."}}},{"type":"object","properties":{"message":{"type":"string","example":"Webhook registered successfully"}}}]},"example":{"error":"This inbox is in manual webhook mode. Configure the webhook in the Meta App Dashboard."}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/inboxes/{id}/rotate_webhook_verify_token":{"post":{"tags":["Inboxes"],"operationId":"auto_post_api_v1_accounts_account_id_inboxes_id_rotate_webhook_verify_token","summary":"Rotate webhook verify token inboxes","description":"Performs the rotate webhook verify token operation on the targeted inbox resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"Webhook verify token rotated"},"webhook_verify_token":{"type":"string"}}},"example":{"message":"Webhook verify token rotated","webhook_verify_token":"sample-token"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"refresh":{"type":"string"}}},"example":{"refresh":"sample refresh"}}}}}},"/api/v1/accounts/{account_id}/inboxes/{id}/reset_secret":{"post":{"tags":["Inboxes"],"operationId":"auto_post_api_v1_accounts_account_id_inboxes_id_reset_secret","summary":"Reset secret inboxes","description":"Performs the reset secret operation on the targeted inbox resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"avatar_url":{"type":"string"},"channel_id":{"type":"integer"},"name":{"type":"string"},"channel_type":{"type":"string","enum":["Channel::Api","Channel::Email","Channel::FacebookPage","Channel::Instagram","Channel::Line","Channel::Sms","Channel::Telegram","Channel::Tiktok","Channel::TwilioSms","Channel::TwitterProfile","Channel::WebWidget","Channel::Whatsapp"],"description":"The inbox channel class — identifies which messaging channel backs the inbox."},"greeting_enabled":{"type":"boolean"},"greeting_message":{"type":"string"},"working_hours_enabled":{"type":"boolean"},"enable_email_collect":{"type":"string"},"csat_survey_enabled":{"type":"boolean"},"csat_config":{"type":"string"},"enable_auto_assignment":{"type":"string"},"auto_assignment_config":{"type":"string"},"out_of_office_message":{"type":"string"},"working_hours":{"type":"string"},"timezone":{"type":"string","description":"IANA timezone identifier (e.g. \"America/Sao_Paulo\", \"UTC\"). Rails timezone names are also accepted on input; an unrecognized value is ignored in favor of the next fallback.","example":"America/Sao_Paulo"},"callback_webhook_url":{"type":"string"},"allow_messages_after_resolved":{"type":"string"},"lock_to_single_conversation":{"type":"string"},"audio_transcription_enabled":{"type":"boolean"},"preserve_deleted_messages":{"type":"string"},"allow_message_deletion":{"type":"string"},"capture_view_once":{"type":"string"},"sender_name_type":{"type":"string","enum":["friendly","professional"]},"auto_resolve_config":{"type":"object","additionalProperties":true,"oneOf":[{"type":"object","maxProperties":0,"additionalProperties":true,"description":"Empty means inherit the account rule."},{"type":"object","additionalProperties":false,"required":["mode"],"properties":{"mode":{"type":"string","enum":["disabled"],"description":"Disable automatic resolution for this inbox."}},"description":"The disabled rule contains only its mode."},{"type":"object","additionalProperties":false,"required":["mode","after","message","label","allow_waiting"],"properties":{"mode":{"type":"string","enum":["custom"],"description":"Use this complete inbox rule."},"after":{"type":"integer","minimum":10,"maximum":1439856,"description":"Inactivity in minutes; required for custom mode."},"message":{"type":["string","null"],"maxLength":10000,"description":"Optional message; blank normalizes to null."},"label":{"type":["string","null"],"description":"An existing account label title, or null."},"allow_waiting":{"type":"boolean","description":"Whether waiting conversations are included."}},"description":"Complete normalized custom rule."}],"description":"Normalized JSON rule from valid model writes: empty, disabled, or complete custom configuration.","example":{"mode":"custom","after":60,"message":null,"label":null,"allow_waiting":false}},"outbound_agent_name_header_policy":{"type":"string"},"agent_bot_working_hours_mode":{"type":"string","enum":["always","inside_business_hours","outside_business_hours"]},"business_name":{"type":"string"},"responder_policy":{"type":"string"},"help_center":{"type":"object","properties":{"name":{"type":"string"},"slug":{"type":"string"}}},"tweets_enabled":{"type":"boolean"},"allowed_domains":{"type":"string"},"widget_color":{"type":"string"},"website_url":{"type":"string"},"hmac_mandatory":{"type":"string"},"welcome_title":{"type":"string"},"welcome_tagline":{"type":"string"},"web_widget_script":{"type":"string"},"website_token":{"type":"string"},"selected_feature_flags":{"type":"string"},"reply_time":{"type":"string","format":"date-time"},"hmac_token":{"type":"string"},"pre_chat_form_enabled":{"type":"boolean"},"pre_chat_form_options":{"type":"string"},"continuity_via_email":{"type":"string","format":"email"},"page_id":{"type":"integer"},"reauthorization_required":{"type":"string"},"instagram_id":{"type":"integer"},"messaging_service_sid":{"type":"string"},"phone_number":{"type":"string"},"medium":{"type":"string"},"bandwidth_callback_state":{"type":"string","enum":["active","reconnect_required","reconciling","reconciliation_required","encryption_required"]},"bandwidth_api_migration_state":{"type":"string","enum":["oauth2_configured","oauth2_required","configuration_required"]},"bandwidth_legacy_basic_deprecated":{"type":"boolean"},"content_templates":{"type":"string"},"auth_token":{"type":"string"},"account_sid":{"type":"string"},"api_key_sid":{"type":"string"},"twilio_credential_state":{"type":"string","enum":["ready","pending","failed","dead_letter","account_auth_token_required","reconciliation_required"],"description":"Durable Twilio credential lifecycle derived from Channel::TwilioSms. A reconciliation-required state is fail-closed until the provider outcome has been verified."},"api_key_configured":{"type":"boolean"},"email":{"type":"string","format":"email"},"auth_method":{"type":"string"},"forwarding_enabled":{"type":"boolean"},"forward_to_email":{"type":"string","format":"email"},"branded_email_layout":{"type":"string"},"imap_login":{"type":"string"},"imap_password":{"type":"string"},"imap_address":{"type":"string"},"imap_port":{"type":"string"},"imap_enabled":{"type":"boolean"},"imap_enable_ssl":{"type":"string"},"imap_authentication":{"type":"string"},"smtp_login":{"type":"string"},"smtp_password":{"type":"string"},"smtp_address":{"type":"string"},"smtp_port":{"type":"string"},"smtp_enabled":{"type":"boolean"},"smtp_domain":{"type":"string"},"smtp_enable_ssl_tls":{"type":"string"},"smtp_enable_starttls_auto":{"type":"string"},"smtp_openssl_verify_mode":{"type":"string","enum":["none","peer","client_once","fail_if_no_peer_cert"],"description":"OpenSSL peer-certificate verification mode for the email channel's SMTP connection."},"smtp_authentication":{"type":"string"},"secret":{"type":"string"},"webhook_url":{"type":"string"},"inbox_identifier":{"type":"string"},"additional_attributes":{"type":"object","additionalProperties":true,"description":"Channel- and source-specific metadata for this record (e.g. browser info, referer, social profile identifiers). The key set depends on the originating channel."},"provider":{"type":"string","enum":["default","whatsapp_cloud","whatsapp_web","google","microsoft"],"description":"Messaging provider backing the inbox channel (whatsapp_web is the WazMeow gateway; email uses google/microsoft; default otherwise)."},"bot_name":{"type":"string"},"message_templates":{"type":"boolean"},"provider_config":{"type":"string"},"business_management_token_configured":{"type":"boolean"},"hybrid_pair":{"$ref":"#/components/schemas/inbox/properties/hybrid_pair"},"whatsapp_web_session_state":{"$ref":"#/components/schemas/inbox/properties/whatsapp_web_session_state"},"hybrid_hidden":{"type":"string"},"logical_inbox_id":{"type":"integer"},"whatsapp_pending_phone":{"type":"object","nullable":true,"description":"Spec 052 — set only when a WhatsApp phone-number rewrite was REFUSED because a non-sibling channel already holds the number, leaving the inbox on its `pending:` placeholder and inert. `null` in every normal case (including a routine, not-yet-scanned pairing).","additionalProperties":false,"properties":{"awaiting_pair":{"type":"boolean","description":"True while the inbox is still on its `pending:\u003cuuid\u003e` placeholder number."},"phone":{"type":"string","description":"The E.164 number the rewrite tried to claim."},"reason":{"type":"string","enum":["same_account_same_provider","other_account"],"description":"Why the rewrite was refused. `other_account` never carries any identifying detail about the other account."},"sibling_inbox_id":{"type":"integer","nullable":true,"description":"Colliding inbox in the SAME account; absent when the collision is cross-account."},"source":{"type":"string","enum":["pair_success","qr_pump"],"description":"Which path attempted the rewrite."},"at":{"type":"string","format":"date-time","description":"When the refusal was recorded."}}},"whatsapp_sibling_notice":{"type":"string"},"whatsapp_web_contact_request":{"type":"string","enum":["supported","unsupported","unknown"],"description":"WhatsApp Web inboxes only — whether this inbox's WazMeow gateway serves the request that asks a customer to share their phone number. `supported` and `unsupported` come from a no-effect probe of the gateway route, refreshed at most hourly and immediately when a real send finds the route missing; `unknown` means not probed yet or the gateway could not be reached. Only `supported` turns the feature on; with `unknown` the request is refused before any gateway call while the probe runs."},"voice_enabled":{"type":"boolean"},"inbound_calls_enabled":{"type":"boolean"},"voice_configured":{"type":"boolean"},"voice_call_webhook_url":{"type":"string"},"voice_status_webhook_url":{"type":"string"}}},"example":{"id":1,"avatar_url":"https://example.com/resource","channel_id":1,"name":"Sample Name","channel_type":"Channel::Api","greeting_enabled":true,"greeting_message":"sample greeting message","working_hours_enabled":true,"enable_email_collect":"agent@example.com","csat_survey_enabled":true,"csat_config":"sample csat config","enable_auto_assignment":"sample enable auto assignment","auto_assignment_config":"sample auto assignment config","out_of_office_message":"sample out of office message","working_hours":"sample working hours","timezone":"America/Sao_Paulo","callback_webhook_url":"https://example.com/resource","allow_messages_after_resolved":"sample allow messages after resolved","lock_to_single_conversation":"sample lock to single conversation","audio_transcription_enabled":true,"preserve_deleted_messages":"sample preserve deleted messages","allow_message_deletion":"sample allow message deletion","capture_view_once":"sample capture view once","sender_name_type":"friendly","auto_resolve_config":{"mode":"custom","after":60,"message":null,"label":null,"allow_waiting":false},"outbound_agent_name_header_policy":"sample outbound agent name header policy","agent_bot_working_hours_mode":"always","business_name":"sample business name","responder_policy":"sample responder policy","help_center":{"name":"Sample Name","slug":"sample-slug"},"tweets_enabled":true,"allowed_domains":"sample allowed domains","widget_color":"#1F93FF","website_url":"https://example.com/resource","hmac_mandatory":"sample hmac mandatory","welcome_title":"sample welcome title","welcome_tagline":"sample welcome tagline","web_widget_script":"sample web widget script","website_token":"sample-token","selected_feature_flags":"sample selected feature flags","reply_time":"2026-01-15T10:30:00.000Z","hmac_token":"sample-token","pre_chat_form_enabled":true,"pre_chat_form_options":"sample pre chat form options","continuity_via_email":"agent@example.com","page_id":1,"reauthorization_required":"sample reauthorization required","instagram_id":1,"messaging_service_sid":"sample messaging service sid","phone_number":"+5511999998888","medium":"sample medium","bandwidth_callback_state":"active","bandwidth_api_migration_state":"oauth2_configured","bandwidth_legacy_basic_deprecated":true,"content_templates":"sample content templates","auth_token":"sample-token","account_sid":"sample account sid","api_key_sid":"sample api key sid","twilio_credential_state":"ready","api_key_configured":true,"email":"agent@example.com","auth_method":"sample auth method","forwarding_enabled":true,"forward_to_email":"agent@example.com","branded_email_layout":"agent@example.com","imap_login":"sample imap login","imap_password":"sample imap password","imap_address":"sample imap address","imap_port":"sample imap port","imap_enabled":true,"imap_enable_ssl":"sample imap enable ssl","imap_authentication":"sample imap authentication","smtp_login":"sample smtp login","smtp_password":"sample smtp password","smtp_address":"sample smtp address","smtp_port":"sample smtp port","smtp_enabled":true,"smtp_domain":"sample smtp domain","smtp_enable_ssl_tls":"sample smtp enable ssl tls","smtp_enable_starttls_auto":"sample smtp enable starttls auto","smtp_openssl_verify_mode":"none","smtp_authentication":"sample smtp authentication","secret":"sample-token","webhook_url":"https://example.com/resource","inbox_identifier":"sample inbox identifier","additional_attributes":{},"provider":"default","bot_name":"sample bot name","message_templates":true,"provider_config":"sample provider config","business_management_token_configured":true,"hybrid_pair":{"paired":true,"id":4,"role":"cloud","sibling_inbox_id":18,"canonical_phone":"+5521900000000","primary":"cloud","inbound_authority":"cloud","unified_inbox":true,"unified_state":{"state":"complete","scanned":42,"frozen":40,"reconciled_count":2,"completed_at":"2026-10-03T12:00:00.000Z","blocked_conversations":[]},"routing":{"outbound_default":"cloud","out_of_window":"web","fallback":true,"manual_override":true,"weighted":{"mode":"weighted","web_percent":30,"version":2}},"web_channel_id":12,"web_inbox_id":18,"calling_provider":"whatsapp_web","web_voice_enabled":true,"web_inbound_calls_enabled":true,"web_call_config_sync":{"state":"pending","checked_at":"2026-10-03T12:00:00.000Z"},"web_video_calls_enabled":false,"web_group_calls_enabled":false,"web_reauthorization_required":false,"web_session_state":{"state":"connected","fresh":true,"observed_at":"2026-10-03T12:00:00.000Z","disconnected_since":null},"web_allow_message_deletion":true},"whatsapp_web_session_state":{"state":"connected","fresh":true,"observed_at":"2026-01-15T10:30:00.000Z","disconnected_since":null},"hybrid_hidden":"sample hybrid hidden","logical_inbox_id":1,"whatsapp_pending_phone":{"awaiting_pair":true,"phone":"+5511999998888","reason":"same_account_same_provider","sibling_inbox_id":1,"source":"pair_success","at":"2026-01-15T10:30:00.000Z"},"whatsapp_sibling_notice":"sample whatsapp sibling notice","whatsapp_web_contact_request":"supported","voice_enabled":true,"inbound_calls_enabled":true,"voice_configured":true,"voice_call_webhook_url":"https://example.com/resource","voice_status_webhook_url":"https://example.com/resource"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/inboxes/{id}/reconnect_bandwidth_callbacks":{"post":{"tags":["Inboxes"],"operationId":"auto_post_api_v1_accounts_account_id_inboxes_id_reconnect_bandwidth_callbacks","summary":"Reconcile Bandwidth SMS callbacks","description":"Administrator-only recovery action for an SMS inbox. It re-applies the encrypted callback pair with a full Bandwidth Application GET/merge/PUT. A timeout or local finalization failure remains `reconciliation_required` and this operation replays the same staged pair; credentials remain machine-to-machine only.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Callback configuration is active","content":{"application/json":{"schema":{"type":"object","required":["bandwidth_callback_state"],"properties":{"bandwidth_callback_state":{"type":"string","enum":["active"],"example":"active"}}},"examples":{"reconnected":{"value":{"bandwidth_callback_state":"active"}}}}}},"401":{"description":"Missing or invalid account API credential"},"404":{"description":"Inbox does not exist in the current account or is not an SMS inbox"},"403":{"description":"Administrator role required"},"422":{"description":"Encryption is unavailable or provider reconciliation failed; reconnect state is actionable","content":{"application/json":{"schema":{"type":"object","required":["error","bandwidth_callback_state"],"properties":{"error":{"type":"string","example":"Bandwidth application update failed (503)"},"bandwidth_callback_state":{"type":"string","enum":["encryption_required","reconciliation_required"],"example":"reconciliation_required"}}},"example":{"error":"Bandwidth application update failed (503)","bandwidth_callback_state":"reconciliation_required"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/inboxes/{id}/rotate_bandwidth_callback_credentials":{"post":{"tags":["Inboxes"],"operationId":"auto_post_api_v1_accounts_account_id_inboxes_id_rotate_bandwidth_callback_credentials","summary":"Rotate Bandwidth SMS callback credentials","description":"Administrator-only credential rotation for an SMS inbox. The server stages a new encrypted pair, retains the prior pair for a bounded 15-minute callback grace while reconciliation is ambiguous, and completes full-document Bandwidth reconciliation before responding. Concurrent retries replay the staged pair rather than minting another one; no response exposes either credential.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Callback credentials rotated and active","content":{"application/json":{"schema":{"type":"object","required":["bandwidth_callback_state"],"properties":{"bandwidth_callback_state":{"type":"string","enum":["active"],"example":"active"}}},"examples":{"rotated":{"value":{"bandwidth_callback_state":"active"}}}}}},"401":{"description":"Missing or invalid account API credential"},"404":{"description":"Inbox does not exist in the current account or is not an SMS inbox"},"403":{"description":"Administrator role required"},"422":{"description":"Encryption is unavailable or provider reconciliation failed; reconnect state is actionable","content":{"application/json":{"schema":{"type":"object","required":["error","bandwidth_callback_state"],"properties":{"error":{"type":"string","example":"Bandwidth application fetch failed (503)"},"bandwidth_callback_state":{"type":"string","enum":["encryption_required","reconciliation_required"],"example":"reconciliation_required"}}},"example":{"error":"Bandwidth application fetch failed (503)","bandwidth_callback_state":"reconciliation_required"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/inboxes/{id}/reconnect_twilio_credentials":{"post":{"tags":["Inboxes"],"operationId":"auto_post_api_v1_accounts_account_id_inboxes_id_reconnect_twilio_credentials","summary":"Remediate or reconnect Twilio credentials","description":"Administrator-only recovery for a Twilio SMS or WhatsApp inbox. API-key credentials created by older releases require an Account Auth Token before signed callbacks are accepted; the server promotes the existing secret without returning or logging it. Prospective outbound credentials are validated before persistence; an ambiguous Twilio callback apply returns reconciliation_required and is retried from a durable, encrypted generation snapshot rather than reporting a false success. A newer rotation supersedes every late provider result through generation compare-and-set. Responses are no-store and contain only actionable, non-secret state.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Credentials verified and callback configuration reapplied","content":{"application/json":{"schema":{"type":"object","required":["twilio_credential_state","twilio_credential_generation","twilio_credential_retry","api_key_configured"],"properties":{"twilio_credential_state":{"type":"string","enum":["ready","pending","failed","dead_letter","account_auth_token_required","reconciliation_required"],"example":"ready","description":"Durable Twilio credential lifecycle derived from Channel::TwilioSms. A reconciliation-required state is fail-closed until the provider outcome has been verified."},"twilio_credential_generation":{"type":"integer","format":"int64","minimum":0,"example":12},"twilio_credential_retry":{"type":"object","required":["state","generation","attempts","dead_lettered"],"properties":{"state":{"type":"string","enum":["ready","pending","failed","dead_letter","account_auth_token_required","reconciliation_required"]},"generation":{"type":"integer","format":"int64","minimum":0},"attempts":{"type":"integer","minimum":0,"maximum":8},"retry_at":{"type":["string","null"],"format":"date-time"},"dead_lettered":{"type":"boolean"},"last_error_code":{"type":["string","null"],"enum":["provider_unavailable","provider_outcome_unknown","invalid_reconciliation_intent","voice_phone_number_not_found","voice_capability_required",null]}}},"api_key_configured":{"type":"boolean","example":true}}},"example":{"twilio_credential_state":"ready","twilio_credential_generation":12,"twilio_credential_retry":{"state":"ready","generation":12,"attempts":0,"retry_at":null,"dead_lettered":false,"last_error_code":null},"api_key_configured":true}}}},"401":{"description":"Unauthorized"},"404":{"description":"No-store localized error; inbox is not a Twilio inbox in the current account"},"403":{"description":"Administrator role required","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["forbidden"]},"message":{"type":"string"}}}}},"example":{"error":{"code":"forbidden","message":"Sample message text."}}}}},"422":{"description":"Encryption is unavailable, credentials are incomplete or invalid, or a voice capability cannot be verified","content":{"application/json":{"schema":{"type":"object","required":["twilio_credential_state","twilio_credential_generation","twilio_credential_retry","api_key_configured","error"],"properties":{"twilio_credential_state":{"type":"string","enum":["ready","pending","failed","dead_letter","account_auth_token_required","reconciliation_required"],"description":"Durable Twilio credential lifecycle derived from Channel::TwilioSms. A reconciliation-required state is fail-closed until the provider outcome has been verified."},"twilio_credential_generation":{"type":"integer","format":"int64","minimum":0},"twilio_credential_retry":{"type":"object","additionalProperties":true,"description":"Secret-free durable retry status for the current generation."},"api_key_configured":{"type":"boolean"},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["account_auth_token_required","api_key_pair_required","credentials_invalid","encryption_required","voice_capability_required"]},"message":{"type":"string"}}}}},"example":{"twilio_credential_state":"ready","twilio_credential_generation":1,"twilio_credential_retry":{},"api_key_configured":true,"error":{"code":"account_auth_token_required","message":"Sample message text."}}}}},"503":{"description":"No-store localized reconciliation status. The encrypted generation remains durable and will retry or become a visible dead letter.","content":{"application/json":{"schema":{"type":"object","required":["twilio_credential_state","twilio_credential_generation","twilio_credential_retry","api_key_configured","error"],"properties":{"twilio_credential_state":{"type":"string","enum":["ready","pending","failed","dead_letter","account_auth_token_required","reconciliation_required"],"description":"Durable Twilio credential lifecycle derived from Channel::TwilioSms. A reconciliation-required state is fail-closed until the provider outcome has been verified."},"twilio_credential_generation":{"type":"integer","format":"int64","minimum":0},"twilio_credential_retry":{"type":"object","additionalProperties":true,"description":"Secret-free durable retry status for the current generation."},"api_key_configured":{"type":"boolean"},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["reconciliation_required"]},"message":{"type":"string"}}}}},"example":{"twilio_credential_state":"ready","twilio_credential_generation":1,"twilio_credential_retry":{},"api_key_configured":true,"error":{"code":"reconciliation_required","message":"Sample message text."}}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["account_auth_token"],"properties":{"account_auth_token":{"type":"string","format":"password","writeOnly":true,"example":"sample-account-auth-token"}}},"example":{"account_auth_token":"sample-account-auth-token"}}}}}},"/api/v1/accounts/{account_id}/inboxes/{id}/rotate_twilio_credentials":{"post":{"tags":["Inboxes"],"operationId":"auto_post_api_v1_accounts_account_id_inboxes_id_rotate_twilio_credentials","summary":"Rotate Twilio credentials","description":"Administrator-only, write-only Twilio credential rotation. Basic-auth inboxes supply only the Account Auth Token; API-key rotation supplies a complete new API Key SID and Secret, while omitting both retains an existing API-key pair. Voice-enabled Twilio inboxes validate and reconcile both messaging and voice callback configuration with the same generation. This operation's no-store response and logs contain only non-secret reconciliation state; it never returns the submitted Account Auth Token or dedicated API Key Secret fields.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Credentials rotated, verified, and callback configuration reapplied","content":{"application/json":{"schema":{"type":"object","required":["twilio_credential_state","twilio_credential_generation","twilio_credential_retry","api_key_configured"],"properties":{"twilio_credential_state":{"type":"string","enum":["ready","pending","failed","dead_letter","account_auth_token_required","reconciliation_required"],"example":"ready","description":"Durable Twilio credential lifecycle derived from Channel::TwilioSms. A reconciliation-required state is fail-closed until the provider outcome has been verified."},"twilio_credential_generation":{"type":"integer","format":"int64","minimum":0,"example":12},"twilio_credential_retry":{"type":"object","additionalProperties":true,"description":"Secret-free durable retry status for the current generation."},"api_key_configured":{"type":"boolean","example":true}}},"example":{"twilio_credential_state":"ready","twilio_credential_generation":12,"twilio_credential_retry":{"state":"ready","generation":12,"attempts":0,"retry_at":null,"dead_lettered":false,"last_error_code":null},"api_key_configured":true}}}},"401":{"description":"Unauthorized"},"404":{"description":"No-store localized error; inbox is not a Twilio inbox in the current account"},"403":{"description":"Administrator role required","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["forbidden"]},"message":{"type":"string"}}}}},"example":{"error":{"code":"forbidden","message":"Sample message text."}}}}},"422":{"description":"Encryption is unavailable, credentials are incomplete or invalid, or a voice capability cannot be verified","content":{"application/json":{"schema":{"type":"object","required":["twilio_credential_state","twilio_credential_generation","twilio_credential_retry","api_key_configured","error"],"properties":{"twilio_credential_state":{"type":"string","enum":["ready","pending","failed","dead_letter","account_auth_token_required","reconciliation_required"],"description":"Durable Twilio credential lifecycle derived from Channel::TwilioSms. A reconciliation-required state is fail-closed until the provider outcome has been verified."},"twilio_credential_generation":{"type":"integer","format":"int64","minimum":0},"twilio_credential_retry":{"type":"object","additionalProperties":true,"description":"Secret-free durable retry status for the current generation."},"api_key_configured":{"type":"boolean"},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["account_auth_token_required","api_key_pair_required","credentials_invalid","encryption_required","voice_capability_required"]},"message":{"type":"string"}}}}},"example":{"twilio_credential_state":"ready","twilio_credential_generation":1,"twilio_credential_retry":{},"api_key_configured":true,"error":{"code":"account_auth_token_required","message":"Sample message text."}}}}},"503":{"description":"No-store localized reconciliation status. The encrypted generation remains durable and will retry or become a visible dead letter.","content":{"application/json":{"schema":{"type":"object","required":["twilio_credential_state","twilio_credential_generation","twilio_credential_retry","api_key_configured","error"],"properties":{"twilio_credential_state":{"type":"string","enum":["ready","pending","failed","dead_letter","account_auth_token_required","reconciliation_required"],"description":"Durable Twilio credential lifecycle derived from Channel::TwilioSms. A reconciliation-required state is fail-closed until the provider outcome has been verified."},"twilio_credential_generation":{"type":"integer","format":"int64","minimum":0},"twilio_credential_retry":{"type":"object","additionalProperties":true,"description":"Secret-free durable retry status for the current generation."},"api_key_configured":{"type":"boolean"},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["reconciliation_required"]},"message":{"type":"string"}}}}},"example":{"twilio_credential_state":"ready","twilio_credential_generation":1,"twilio_credential_retry":{},"api_key_configured":true,"error":{"code":"reconciliation_required","message":"Sample message text."}}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["account_auth_token"],"properties":{"account_auth_token":{"type":"string","format":"password","writeOnly":true,"example":"sample-account-auth-token"},"api_key_sid":{"type":"string","writeOnly":true,"example":"sample-twilio-api-key-sid"},"api_key_secret":{"type":"string","format":"password","writeOnly":true,"example":"sample-api-key-secret"}}},"example":{"account_auth_token":"sample-account-auth-token","api_key_sid":"sample-twilio-api-key-sid","api_key_secret":"sample-api-key-secret"}}}}}},"/api/v1/accounts/{account_id}/inboxes/{id}/enable_whatsapp_calling":{"post":{"tags":["Inboxes"],"operationId":"auto_post_api_v1_accounts_account_id_inboxes_id_enable_whatsapp_calling","summary":"Enable WhatsApp calling on the inbox","description":"Turns WhatsApp voice calling on for the inbox by registering the calling capability with the WhatsApp provider, so the number can place and receive calls. Only a WhatsApp inbox whose provider supports calling accepts this request. The response carries no body.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"WhatsApp calling enabled on the inbox. Empty body."},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"422":{"description":"The inbox does not support WhatsApp calling, or the provider refused to enable the capability. The message reports which of the two happened.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Why the capability could not be enabled — either that the inbox does not support WhatsApp calling, or the error the provider returned."}}},"example":{"error":"Inbox does not support WhatsApp calling"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/inboxes/{id}/disable_whatsapp_calling":{"post":{"tags":["Inboxes"],"operationId":"auto_post_api_v1_accounts_account_id_inboxes_id_disable_whatsapp_calling","summary":"Disable WhatsApp calling on the inbox","description":"Turns WhatsApp voice calling off for the inbox, so agents stop placing and receiving calls on it. Only a WhatsApp inbox whose provider supports calling accepts this request. By default the calling status of the WhatsApp Business account at Meta is left untouched, so contacts may still see the call button. Send `disable_on_meta: true` to also switch that status off: the local disable always happens first, and the Meta update is best-effort. A Meta failure does not fail the request; it is reported in `meta_calling`. Only a WhatsApp Cloud inbox reaches Meta; a WazMeow (WhatsApp Web) inbox never does. On a Coexistence number paired with WhatsApp Web, the Web calling transport is disabled as before and the Meta update targets only the Cloud inbox.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"WhatsApp calling disabled on the inbox, with the outcome of the optional Meta update.","content":{"application/json":{"schema":{"type":"object","properties":{"meta_calling":{"type":"object","description":"Outcome of the optional Meta calling-status update.","properties":{"requested":{"type":"boolean","description":"Whether the request asked to also disable calling at Meta."},"status":{"type":"string","enum":["not_requested","not_applicable","disabled","failed"],"description":"not_requested when the flag was absent, not_applicable when the inbox is not a WhatsApp Cloud inbox, disabled when Meta accepted the change, failed when Meta rejected it (calling is still disabled locally)."},"warning":{"type":["string","null"],"description":"The error Meta returned when status is failed; null otherwise."}}}}},"example":{"meta_calling":{"requested":true,"status":"failed","warning":"The access token has expired."}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"422":{"description":"The inbox does not support WhatsApp calling, or the provider refused to withdraw the capability. The message reports which of the two happened.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Why the capability could not be disabled — either that the inbox does not support WhatsApp calling, or the error the provider returned."}}},"example":{"error":"Inbox does not support WhatsApp calling"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"description":"Optional opt-in flags. A body-less request disables calling only locally.","properties":{"disable_on_meta":{"type":"boolean","default":false,"description":"Also set the WhatsApp Business account calling status to DISABLED at Meta after the local disable. Ignored for a WazMeow (WhatsApp Web) inbox."}}},"example":{"disable_on_meta":true}}}}}},"/api/v1/accounts/{account_id}/inboxes/{id}/set_inbound_calls":{"post":{"tags":["Inboxes"],"operationId":"auto_post_api_v1_accounts_account_id_inboxes_id_set_inbound_calls","summary":"Toggle inbound calls on the inbox","description":"Turns the inbound-calls flag of the inbox on or off, which decides whether customers may call the number rather than only being called. It changes that single flag and leaves the rest of the channel configuration untouched, so it applies without re-checking the provider credentials. The response carries no body.\nRequires a voice-enabled inbox. Community accepts native WhatsApp calling and Twilio voice; enabling inbound Twilio calls also requires native_twilio_voice. Turning inbound calls off remains available when that account capability is disabled. Enterprise retains its existing voice guard.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Inbound-calls flag updated on the inbox. Empty body."},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"422":{"description":"The inbox has no voice channel, so inbound calls cannot be toggled on it.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Why the flag could not be toggled."}}},"example":{"error":"Inbox does not support calling"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"description":"The value is read directly from the params with no presence check, so a body-less request still succeeds — see the field description for what that actually does.","properties":{"inbound_calls_enabled":{"type":"boolean","description":"Whether customers may call the inbox. OMITTING it does NOT turn calls off: the stored value becomes null, and the channel treats \"anything that is not false\" as enabled, so an omitted value leaves inbound calls ON. Send `false` explicitly to turn them off."}}},"example":{"inbound_calls_enabled":true}}}}}},"/api/v1/accounts/{account_id}/inboxes/{inbox_id}/conference/token":{"get":{"tags":["Inboxes"],"operationId":"auto_get_api_v1_accounts_account_id_inboxes_inbox_id_conference_token","summary":"Obtain a native voice device token","description":"Issues a short-lived Twilio device token to the authenticated native softphone. Requires native_twilio_voice, inbox access and reconciled provider configuration. After the feature is disabled, only the agent owning an active call may renew by supplying its call_sid and conversation_id. This does not authorize a new call. UI-only; not an MCP tool.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Native browser voice device token.","content":{"application/json":{"schema":{"type":"object","required":["token","account_id","inbox_id"],"properties":{"token":{"type":"string","description":"Short-lived Twilio device credential."},"account_id":{"type":"integer"},"inbox_id":{"type":"integer"}}},"example":{"token":"sample-token","account_id":1,"inbox_id":7}}}},"401":{"description":"Authentication, inbox access or the native voice capability is unavailable.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}},"example":{"error":"sample error"}}}},"404":{"description":"Account or resource not found"},"503":{"description":"Provider configuration must be reconciled before this operation can run.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["reconciliation_required"]}}}}},"example":{"error":{"code":"reconciliation_required"}}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"inbox_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"call_sid","in":"query","required":false,"description":"Provider call id of the already claimed active call, for renewal after disabling voice.","schema":{"type":"string"}},{"name":"conversation_id","in":"query","required":false,"description":"Conversation display identifier paired with call_sid for active-call token renewal.","schema":{"type":"integer"}}]}},"/api/v1/accounts/{account_id}/inboxes/{inbox_id}/conference":{"delete":{"tags":["Inboxes"],"operationId":"auto_delete_api_v1_accounts_account_id_inboxes_inbox_id_conference","summary":"Leave a native voice conference","description":"Confirms termination of the identified provider call and any waiting or active conference, including rejection before pickup. Existing calls can be finalized after native_twilio_voice is disabled or its TwiML application is removed. Inbox/conversation access and usable provider credentials are still required. A failed provider request does not confirm termination; reconcile before retrying. The logical attachment and call history are retained.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","example":"success","enum":["success"],"description":"Fixed success marker for the conference action."},"id":{"type":"integer"}}},"example":{"status":"success","id":1}}}},"401":{"description":"Authentication or inbox/conversation access is unavailable.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}},"example":{"error":"sample error"}}}},"404":{"description":"Account or resource not found"},"422":{"description":"The required provider call identifier is missing.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}},"example":{"error":"sample error"}}}},"503":{"description":"Provider configuration must be reconciled before this operation can run.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["reconciliation_required"]}}}}},"example":{"error":{"code":"reconciliation_required"}}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"inbox_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["call_sid","conversation_id"],"properties":{"call_sid":{"type":"string","minLength":1,"description":"Twilio provider call identifier within this inbox and conversation."},"conversation_id":{"type":"integer","description":"Conversation display identifier within this account and inbox."}}},"example":{"call_sid":"CA_example","conversation_id":42}}}}},"post":{"tags":["Inboxes"],"operationId":"auto_post_api_v1_accounts_account_id_inboxes_inbox_id_conference","summary":"Join a native voice conference","description":"Claims the identified call for the acting agent and returns its conference identifier. Requires native_twilio_voice, inbox and conversation access and reconciled provider configuration. A concurrent claim by another agent or a call that has already ended returns 409 without changing the call or conversation.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","example":"success","enum":["success"],"description":"Fixed success marker for the conference action."},"id":{"type":"integer"},"conference_sid":{"type":"string"},"using_webrtc":{"type":"boolean","example":true}}},"example":{"status":"success","id":1,"conference_sid":"sample conference sid","using_webrtc":true}}}},"401":{"description":"Authentication, inbox/conversation access or the native voice capability is unavailable.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}},"example":{"error":"sample error"}}}},"404":{"description":"Account or resource not found"},"409":{"description":"Another agent already accepted this call, or the call has already ended.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}},"example":{"error":"sample error"}}}},"422":{"description":"The required provider call identifier is missing.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}},"example":{"error":"sample error"}}}},"503":{"description":"Provider configuration must be reconciled before this operation can run.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["reconciliation_required"]}}}}},"example":{"error":{"code":"reconciliation_required"}}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"inbox_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["call_sid","conversation_id"],"properties":{"call_sid":{"type":"string","minLength":1,"description":"Twilio provider call identifier within this inbox and conversation."},"conversation_id":{"type":"integer","description":"Conversation display identifier within this account and inbox."}}},"example":{"call_sid":"CA_example","conversation_id":42}}}}}},"/api/v1/accounts/{account_id}/inboxes/{inbox_id}/csat_template/analyze":{"post":{"tags":["Inboxes"],"operationId":"auto_post_api_v1_accounts_account_id_inboxes_inbox_id_csat_template_analyze","summary":"Analyze inbox csat templates","description":"Performs the analyze operation on the targeted inbox csat template resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Utility/marketing classification for the CSAT template message","content":{"application/json":{"schema":{"type":"object","properties":{"classification":{"type":"string","enum":["LIKELY_UTILITY","LIKELY_MARKETING","UNCLEAR"],"example":"LIKELY_UTILITY"},"optimized_message":{"type":"string","example":"How would you rate the support you received today?"}}},"example":{"classification":"LIKELY_UTILITY","optimized_message":"How would you rate the support you received today?"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"422":{"description":"Missing template message","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Message is required"}}},"example":{"error":"Message is required"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"inbox_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"template":{"type":"object","properties":{"message":{"type":"string"},"button_text":{"type":"string"},"language":{"type":"string"}}}},"required":["template"]},"example":{"template":{"message":"Sample message text.","button_text":"sample button text","language":"en"}}}}}}},"/api/v1/accounts/{account_id}/inboxes/{inbox_id}/csat_template":{"get":{"tags":["Inboxes"],"operationId":"auto_get_api_v1_accounts_account_id_inboxes_inbox_id_csat_template","summary":"Get inbox csat templates","description":"Returns the inbox csat template identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"CSAT template status (fields vary by WhatsApp Cloud vs Twilio channel)","content":{"application/json":{"schema":{"type":"object","properties":{"template_exists":{"type":"boolean","example":true},"template_name":{"type":"string","description":"WhatsApp Cloud","example":"csat_survey_inbox_7"},"template_id":{"type":"string","description":"WhatsApp Cloud","example":"123456789012345"},"friendly_name":{"type":"string","description":"Twilio","example":"csat_survey"},"content_sid":{"type":"string","description":"Twilio","example":"HXxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"},"language":{"type":"string","example":"en"},"status":{"type":"string","example":"APPROVED"},"error":{"type":["string","null"],"example":"Template not found"}}},"example":{"template_exists":true,"template_name":"csat_survey_inbox_7","template_id":"123456789012345","friendly_name":"csat_survey","content_sid":"HXxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx","language":"en","status":"APPROVED","error":"Template not found"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"inbox_id","in":"path","required":true,"schema":{"type":"string"}}]},"post":{"tags":["Inboxes"],"operationId":"auto_post_api_v1_accounts_account_id_inboxes_inbox_id_csat_template","summary":"Create inbox csat templates","description":"Creates a new inbox csat template from the request payload. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"CSAT template submitted for approval (shape varies by channel)","content":{"application/json":{"schema":{"type":"object","properties":{"template":{"type":"object","properties":{"name":{"type":"string","description":"WhatsApp Cloud","example":"csat_survey_inbox_7"},"template_id":{"type":"string","description":"WhatsApp Cloud","example":"123456789012345"},"friendly_name":{"type":"string","description":"Twilio","example":"csat_survey"},"content_sid":{"type":"string","description":"Twilio","example":"HXxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"},"status":{"type":"string","example":"PENDING"},"language":{"type":"string","example":"en"}}}}},"example":{"template":{"name":"csat_survey_inbox_7","template_id":"123456789012345","friendly_name":"csat_survey","content_sid":"HXxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx","status":"PENDING","language":"en"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"422":{"description":"Missing message or WhatsApp rejection","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Message is required"},"details":{"type":["object","null"],"example":{"code":100,"title":"Invalid parameter"},"additionalProperties":true,"description":"WhatsApp API error details (code, subcode, type, title) on submission failure."}}},"example":{"error":"Message is required","details":{"code":100,"title":"Invalid parameter"}}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"inbox_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"template":{"type":"object","properties":{"message":{"type":"string"},"button_text":{"type":"string"},"language":{"type":"string"}}}},"required":["template"]},"example":{"template":{"message":"Sample message text.","button_text":"sample button text","language":"en"}}}}}}},"/api/v1/accounts/{account_id}/inboxes/{inbox_id}/whatsapp_templates/sync":{"post":{"tags":["Inboxes"],"operationId":"auto_post_api_v1_accounts_account_id_inboxes_inbox_id_whatsapp_templates_sync","summary":"Sync WhatsApp message templates (modelos) from Meta","description":"WhatsApp message template (official WhatsApp Business API / Cloud template, \"modelo\"). Fetches the complete template catalog from Meta and refreshes the cached copy, including approval status changes, for every inbox of this account sharing the same WhatsApp Business Account.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"A complete catalog snapshot was synchronized to all physical Cloud owners in this account and WABA. Newer overlapping generations take precedence.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"template_owner":{"type":"object","additionalProperties":false,"required":["key","inbox_id","projection_inbox_id","unified"],"properties":{"key":{"type":"string","description":"Opaque account-scoped catalog owner key; contains no provider credentials or raw WABA identifier.","example":"84a1629b0cc4e0a9"},"inbox_id":{"type":"integer","description":"Physical catalog owner inbox identifier.","example":12},"projection_inbox_id":{"type":"integer","description":"Logical Cloud inbox only when unified routing is enabled; otherwise the requested inbox.","example":12},"unified":{"type":"boolean","example":false}}},"message_templates":{"type":"array","description":"Complete provider catalog, including an empty catalog when confirmed by Meta.","items":{"type":"object","additionalProperties":true,"description":"Provider message template, preserving its published fields."}},"message_templates_last_updated":{"type":["string","null"],"format":"date-time","example":"2026-09-12T12:00:00Z"}}},"example":{"success":true,"template_owner":{"key":"84a1629b0cc4e0a9","inbox_id":12,"projection_inbox_id":12,"unified":false},"message_templates":[{}],"message_templates_last_updated":"2026-09-12T12:00:00Z"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"422":{"description":"Synchronization failed or returned a partial result; the last complete catalog is preserved.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"submission_reconciliation_required"}}},"example":{"error":"submission_reconciliation_required"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"inbox_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/inboxes/{inbox_id}/whatsapp_templates/library":{"get":{"tags":["Inboxes"],"operationId":"auto_get_api_v1_accounts_account_id_inboxes_inbox_id_whatsapp_templates_library","summary":"Browse the WhatsApp message template (modelo) library","description":"WhatsApp message template (official WhatsApp Business API / Cloud template, \"modelo\"). Returns the pre-written template library in the requested locale, used as a starting point to create a new template draft for Meta approval.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"library":{"type":"string"}}},"example":{"library":"sample library"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"inbox_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"locale","in":"query","required":false,"description":"Locale of the pre-written template library. Defaults to English.","schema":{"type":"string"},"example":"pt_BR"}]}},"/api/v1/accounts/{account_id}/inboxes/{inbox_id}/whatsapp_templates/upload_media":{"post":{"tags":["Inboxes"],"operationId":"auto_post_api_v1_accounts_account_id_inboxes_inbox_id_whatsapp_templates_upload_media","summary":"Upload media whatsapp templates","description":"Performs the upload media operation on the targeted whatsapp template resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Media uploaded (handle for template samples; media_id and durable local reference for sends)","content":{"application/json":{"schema":{"type":"object","properties":{"handle":{"type":"string","description":"Resumable upload handle (purpose=sample)","example":"4:aW1hZ2U..."},"media_id":{"type":"string","description":"Media id (purpose=send)","example":"123456789012345"},"blob_signed_id":{"type":"string","description":"Account-owned durable blob reference (purpose=send)","example":"eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBBdz09In19--signature"},"media_url":{"type":"string","format":"uri","description":"Durable browser URL for the exact send media (purpose=send)","example":"https://app.example.test/rails/active_storage/blobs/redirect/header.png"},"success":{"type":"boolean","example":true}}},"example":{"handle":"4:aW1hZ2U...","media_id":"123456789012345","blob_signed_id":"eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBBdz09In19--signature","media_url":"https://app.example.test/rails/active_storage/blobs/redirect/header.png","success":true}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"422":{"description":"Missing media or Meta rejection","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"no_media_source"}}},"example":{"error":"no_media_source"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"inbox_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"purpose":{"type":"string"},"media":{"type":"string"},"media_library_asset_id":{"type":"integer"},"url":{"type":"string"}}},"example":{"purpose":"sample purpose","media":"sample media","media_library_asset_id":1,"url":"https://example.com/resource"}}}}}},"/api/v1/accounts/{account_id}/inboxes/{inbox_id}/whatsapp_templates/{id}/unarchive":{"post":{"tags":["Inboxes"],"operationId":"auto_post_api_v1_accounts_account_id_inboxes_inbox_id_whatsapp_templates_id_unarchive","summary":"Unarchive an archived WhatsApp message template (modelo)","description":"WhatsApp archives a template after 12 months without use and deletes it 28 days later; an archived template cannot be sent. This restores it on Meta to the status it had before it was archived (approved when there was none) and refreshes the cached catalog. The path id is the Meta template id, or the id of a local draft linked to one. Meta answers per template, so a refusal is returned with its reason instead of a silent success. Administrators only.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Meta answered. `success` is true only when this template was unarchived; otherwise its reason is in `failed_templates`.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"unarchived_templates":{"type":"array","description":"Meta template ids restored by this call.","items":{"type":"string"},"example":["1387372356726668"]},"failed_templates":{"type":"object","description":"Meta template id mapped to the reason Meta gave for not unarchiving it.","additionalProperties":{"type":"string"},"example":{}},"template_owner":{"type":"object","additionalProperties":false,"required":["key","inbox_id","projection_inbox_id","unified"],"properties":{"key":{"type":"string","description":"Opaque account-scoped catalog owner key; contains no provider credentials or raw WABA identifier.","example":"84a1629b0cc4e0a9"},"inbox_id":{"type":"integer","description":"Physical catalog owner inbox identifier.","example":12},"projection_inbox_id":{"type":"integer","description":"Logical Cloud inbox only when unified routing is enabled; otherwise the requested inbox.","example":12},"unified":{"type":"boolean","example":false}}},"message_templates":{"type":"array","description":"Refreshed provider catalog after the unarchive.","items":{"type":"object","additionalProperties":true,"description":"Provider message template, preserving its published fields."}},"message_templates_last_updated":{"type":["string","null"],"format":"date-time","example":"2026-10-01T12:00:00Z"}}},"example":{"success":true,"unarchived_templates":["1387372356726668"],"failed_templates":{},"template_owner":{"key":"84a1629b0cc4e0a9","inbox_id":12,"projection_inbox_id":12,"unified":false},"message_templates":[{}],"message_templates_last_updated":"2026-10-01T12:00:00Z"}}}},"401":{"description":"Unauthorized"},"404":{"description":"No archived template with this id in the inbox catalog or its drafts."},"422":{"description":"Meta rejected the request or the outcome is unknown; nothing was changed locally.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"submission_reconciliation_required"}}},"example":{"error":"submission_reconciliation_required"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"inbox_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/inboxes/{inbox_id}/whatsapp_templates":{"get":{"tags":["Inboxes"],"operationId":"auto_get_api_v1_accounts_account_id_inboxes_inbox_id_whatsapp_templates","summary":"List WhatsApp message templates (modelos) of an inbox","description":"WhatsApp message template (official WhatsApp Business API / Cloud template, \"modelo\"). Lists the templates approved or known by Meta for the inbox, from the last synchronized catalog, together with the local drafts not yet approved.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Provider catalog and active local drafts with an explicit account-scoped owner. Linked remote and draft rows represent the same template by provider id and language.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"template_owner":{"type":"object","additionalProperties":false,"required":["key","inbox_id","projection_inbox_id","unified"],"properties":{"key":{"type":"string","description":"Opaque account-scoped catalog owner key; contains no provider credentials or raw WABA identifier.","example":"84a1629b0cc4e0a9"},"inbox_id":{"type":"integer","description":"Physical catalog owner inbox identifier.","example":12},"projection_inbox_id":{"type":"integer","description":"Logical Cloud inbox only when unified routing is enabled; otherwise the requested inbox.","example":12},"unified":{"type":"boolean","example":false}}},"approved":{"type":"array","description":"Last complete provider catalog snapshot; individual entries retain provider fields.","items":{"type":"object","additionalProperties":true,"description":"Provider message template, including its id, name, language, status, category and components."}},"drafts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","example":21},"name":{"type":"string","example":"order_update"},"language":{"type":"string","example":"pt_BR"},"category":{"type":"string","enum":["MARKETING","UTILITY","AUTHENTICATION"],"example":"UTILITY"},"template_type":{"type":"string","enum":["standard","media_carousel","product_carousel","single_product","catalog","limited_time_offer","multi_product","coupon","call_permission","order_details","authentication","flow"],"example":"standard","description":"WhatsApp template type."},"status":{"type":"string","enum":["draft","pending","approved","rejected","paused","disabled","in_appeal","pending_deletion","deleted","flagged","limit_exceeded","submission_failed"],"description":"Last confirmed provider status or local draft status; separate from an unresolved submission attempt.","example":"draft"},"meta_template_id":{"type":["string","null"],"example":"123456789012345"},"components":{"type":"object","additionalProperties":true,"description":"Authored builder configuration, preserving type-specific components and media references.","example":{"body":{"text":"Your order is ready."}}},"metadata":{"type":"object","additionalProperties":true,"description":"Public durable editor metadata. Internal submission claims, history, request identities and deletion receipts are never serialized or writable.","example":{}},"submission":{"type":"object","description":"Public outcome of the last submission attempt; empty when never submitted.","properties":{"state":{"type":"string","enum":["submitting","unknown","awaiting_sync","accepted","failed"],"example":"unknown"},"updated_at":{"type":"string","format":"date-time","example":"2026-09-12T12:00:00Z"},"error":{"type":"string","example":"submission_outcome_unknown"}}},"rejection_reason":{"type":["string","null"],"example":null},"created_at":{"type":"string","format":"date-time","example":"2026-09-12T12:00:00Z"},"updated_at":{"type":"string","format":"date-time","example":"2026-09-12T12:00:00Z"}}}},"last_synced":{"type":["string","null"],"format":"date-time","example":"2026-09-12T12:00:00Z"}}}}},"example":{"payload":{"template_owner":{"key":"84a1629b0cc4e0a9","inbox_id":12,"projection_inbox_id":12,"unified":false},"approved":[{}],"drafts":[{"id":21,"name":"order_update","language":"pt_BR","category":"UTILITY","template_type":"standard","status":"draft","meta_template_id":"123456789012345","components":{"body":{"text":"Your order is ready."}},"metadata":{},"submission":{"state":"unknown","updated_at":"2026-09-12T12:00:00Z","error":"submission_outcome_unknown"},"rejection_reason":null,"created_at":"2026-09-12T12:00:00Z","updated_at":"2026-09-12T12:00:00Z"}],"last_synced":"2026-09-12T12:00:00Z"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"inbox_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."}]},"post":{"tags":["Inboxes"],"operationId":"auto_post_api_v1_accounts_account_id_inboxes_inbox_id_whatsapp_templates","summary":"Save or submit a WhatsApp message template (modelo) draft for Meta approval","description":"WhatsApp message template (official WhatsApp Business API / Cloud template, \"modelo\"). Creates a template draft for the inbox and, unless submit is false, submits it to Meta for approval so it can be sent outside the 24-hour service window. Saves the existing draft before any provider write. Reusing client_request_id returns the same local identity when content agrees. Local edits use the draft identifier. A verified meta_template_id binds an existing provider template and subsequent submissions edit that Graph node. Name and language of linked templates are immutable; approved category changes are rejected. Status and internal metadata are not writable. A pending or timed-out write is reconciled by read-only lookup and is never blindly repeated. Provider deletion retains the historical local row.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Persisted local draft with stable identity. Submission outcome is separate from provider approval.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"allOf":[{"type":"object","properties":{"id":{"type":"integer","example":21},"name":{"type":"string","example":"order_update"},"language":{"type":"string","example":"pt_BR"},"category":{"type":"string","enum":["MARKETING","UTILITY","AUTHENTICATION"],"example":"UTILITY"},"template_type":{"type":"string","enum":["standard","media_carousel","product_carousel","single_product","catalog","limited_time_offer","multi_product","coupon","call_permission","order_details","authentication","flow"],"example":"standard","description":"WhatsApp template type."},"status":{"type":"string","enum":["draft","pending","approved","rejected","paused","disabled","in_appeal","pending_deletion","deleted","flagged","limit_exceeded","submission_failed"],"description":"Last confirmed provider status or local draft status; separate from an unresolved submission attempt.","example":"draft"},"meta_template_id":{"type":["string","null"],"example":"123456789012345"},"components":{"type":"object","additionalProperties":true,"description":"Authored builder configuration, preserving type-specific components and media references.","example":{"body":{"text":"Your order is ready."}}},"metadata":{"type":"object","additionalProperties":true,"description":"Public durable editor metadata. Internal submission claims, history, request identities and deletion receipts are never serialized or writable.","example":{}},"submission":{"type":"object","description":"Public outcome of the last submission attempt; empty when never submitted.","properties":{"state":{"type":"string","enum":["submitting","unknown","awaiting_sync","accepted","failed"],"example":"unknown"},"updated_at":{"type":"string","format":"date-time","example":"2026-09-12T12:00:00Z"},"error":{"type":"string","example":"submission_outcome_unknown"}}},"rejection_reason":{"type":["string","null"],"example":null},"created_at":{"type":"string","format":"date-time","example":"2026-09-12T12:00:00Z"},"updated_at":{"type":"string","format":"date-time","example":"2026-09-12T12:00:00Z"}}},{"type":"object","properties":{"submit_result":{"type":"object","properties":{"success":{"type":"boolean","example":false},"pending":{"type":"boolean","example":true},"state":{"type":"string","enum":["idle","submitting","unknown","awaiting_sync","accepted","failed"],"example":"unknown"},"error":{"type":"string","example":"submission_outcome_unknown"}}}}}]}}},"example":{"payload":{"id":21,"name":"order_update","language":"pt_BR","category":"UTILITY","template_type":"standard","status":"draft","meta_template_id":"123456789012345","components":{"body":{"text":"Your order is ready."}},"metadata":{},"submission":{"state":"unknown","updated_at":"2026-09-12T12:00:00Z","error":"submission_outcome_unknown"},"rejection_reason":null,"created_at":"2026-09-12T12:00:00Z","updated_at":"2026-09-12T12:00:00Z","submit_result":{"success":false,"pending":true,"state":"unknown","error":"submission_outcome_unknown"}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"202":{"description":"The draft is durable but the provider result or updated catalog is pending. Synchronize or retry the unchanged identity to reconcile; do not create a replacement.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"allOf":[{"type":"object","properties":{"id":{"type":"integer","example":21},"name":{"type":"string","example":"order_update"},"language":{"type":"string","example":"pt_BR"},"category":{"type":"string","enum":["MARKETING","UTILITY","AUTHENTICATION"],"example":"UTILITY"},"template_type":{"type":"string","enum":["standard","media_carousel","product_carousel","single_product","catalog","limited_time_offer","multi_product","coupon","call_permission","order_details","authentication","flow"],"example":"standard","description":"WhatsApp template type."},"status":{"type":"string","enum":["draft","pending","approved","rejected","paused","disabled","in_appeal","pending_deletion","deleted","flagged","limit_exceeded","submission_failed"],"description":"Last confirmed provider status or local draft status; separate from an unresolved submission attempt.","example":"draft"},"meta_template_id":{"type":["string","null"],"example":"123456789012345"},"components":{"type":"object","additionalProperties":true,"description":"Authored builder configuration, preserving type-specific components and media references.","example":{"body":{"text":"Your order is ready."}}},"metadata":{"type":"object","additionalProperties":true,"description":"Public durable editor metadata. Internal submission claims, history, request identities and deletion receipts are never serialized or writable.","example":{}},"submission":{"type":"object","description":"Public outcome of the last submission attempt; empty when never submitted.","properties":{"state":{"type":"string","enum":["submitting","unknown","awaiting_sync","accepted","failed"],"example":"unknown"},"updated_at":{"type":"string","format":"date-time","example":"2026-09-12T12:00:00Z"},"error":{"type":"string","example":"submission_outcome_unknown"}}},"rejection_reason":{"type":["string","null"],"example":null},"created_at":{"type":"string","format":"date-time","example":"2026-09-12T12:00:00Z"},"updated_at":{"type":"string","format":"date-time","example":"2026-09-12T12:00:00Z"}}},{"type":"object","properties":{"submit_result":{"type":"object","properties":{"success":{"type":"boolean","example":false},"pending":{"type":"boolean","example":true},"state":{"type":"string","enum":["idle","submitting","unknown","awaiting_sync","accepted","failed"],"example":"unknown"},"error":{"type":"string","example":"submission_outcome_unknown"}}}}}]}}},"example":{"payload":{"id":21,"name":"order_update","language":"pt_BR","category":"UTILITY","template_type":"standard","status":"draft","meta_template_id":"123456789012345","components":{"body":{"text":"Your order is ready."}},"metadata":{},"submission":{"state":"unknown","updated_at":"2026-09-12T12:00:00Z","error":"submission_outcome_unknown"},"rejection_reason":null,"created_at":"2026-09-12T12:00:00Z","updated_at":"2026-09-12T12:00:00Z","submit_result":{"success":false,"pending":true,"state":"unknown","error":"submission_outcome_unknown"}}}}}},"409":{"description":"Identity conflict, immutable provider field, or unresolved submission/deletion. Retain the existing draft and reconcile before another mutation.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"submission_reconciliation_required"}}},"example":{"error":"submission_reconciliation_required"}}}},"422":{"description":"Draft model validation failed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"submission_reconciliation_required"}}},"example":{"error":"submission_reconciliation_required"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"inbox_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["whatsapp_template"],"properties":{"whatsapp_template":{"type":"object","properties":{"name":{"type":"string","example":"order_update"},"language":{"type":"string","example":"pt_BR"},"category":{"type":"string","enum":["MARKETING","UTILITY","AUTHENTICATION"],"example":"UTILITY"},"template_type":{"type":"string","enum":["standard","media_carousel","product_carousel","single_product","catalog","limited_time_offer","multi_product","coupon","call_permission","order_details","authentication","flow"],"example":"standard","description":"WhatsApp template type."},"components":{"type":"object","additionalProperties":true,"description":"Authored builder configuration for the selected template type.","example":{"body":{"text":"Your order is ready."}}},"metadata":{"type":"object","additionalProperties":true,"description":"Public durable editor metadata; reserved internal keys are ignored.","example":{}},"submit":{"type":"boolean","description":"False saves only the draft; omitted or true requests submission.","example":false},"client_request_id":{"type":"string","maxLength":128,"description":"Stable optional create identity; reuse it for retries with identical content.","example":"template-request-1"},"meta_template_id":{"type":"string","description":"Create-only binding to an existing template verified in the authorized inbox catalog.","example":"123456789012345"}}}}},"example":{"whatsapp_template":{"name":"order_update","language":"pt_BR","category":"UTILITY","template_type":"standard","components":{"body":{"text":"Your order is ready."}},"metadata":{},"submit":false,"client_request_id":"template-request-1","meta_template_id":"123456789012345"}}}}}}},"/api/v1/accounts/{account_id}/inboxes/{inbox_id}/whatsapp_templates/{id}":{"get":{"tags":["Inboxes"],"operationId":"auto_get_api_v1_accounts_account_id_inboxes_inbox_id_whatsapp_templates_id","summary":"Get one WhatsApp message template (modelo) draft","description":"WhatsApp message template (official WhatsApp Business API / Cloud template, \"modelo\"). Returns one template draft of the inbox with its content, provider status and the outcome of its last submission to Meta.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Persisted local draft with stable identity and public submission state.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer","example":21},"name":{"type":"string","example":"order_update"},"language":{"type":"string","example":"pt_BR"},"category":{"type":"string","enum":["MARKETING","UTILITY","AUTHENTICATION"],"example":"UTILITY"},"template_type":{"type":"string","enum":["standard","media_carousel","product_carousel","single_product","catalog","limited_time_offer","multi_product","coupon","call_permission","order_details","authentication","flow"],"example":"standard","description":"WhatsApp template type."},"status":{"type":"string","enum":["draft","pending","approved","rejected","paused","disabled","in_appeal","pending_deletion","deleted","flagged","limit_exceeded","submission_failed"],"description":"Last confirmed provider status or local draft status; separate from an unresolved submission attempt.","example":"draft"},"meta_template_id":{"type":["string","null"],"example":"123456789012345"},"components":{"type":"object","additionalProperties":true,"description":"Authored builder configuration, preserving type-specific components and media references.","example":{"body":{"text":"Your order is ready."}}},"metadata":{"type":"object","additionalProperties":true,"description":"Public durable editor metadata. Internal submission claims, history, request identities and deletion receipts are never serialized or writable.","example":{}},"submission":{"type":"object","description":"Public outcome of the last submission attempt; empty when never submitted.","properties":{"state":{"type":"string","enum":["submitting","unknown","awaiting_sync","accepted","failed"],"example":"unknown"},"updated_at":{"type":"string","format":"date-time","example":"2026-09-12T12:00:00Z"},"error":{"type":"string","example":"submission_outcome_unknown"}}},"rejection_reason":{"type":["string","null"],"example":null},"created_at":{"type":"string","format":"date-time","example":"2026-09-12T12:00:00Z"},"updated_at":{"type":"string","format":"date-time","example":"2026-09-12T12:00:00Z"}}}}},"example":{"payload":{"id":21,"name":"order_update","language":"pt_BR","category":"UTILITY","template_type":"standard","status":"draft","meta_template_id":"123456789012345","components":{"body":{"text":"Your order is ready."}},"metadata":{},"submission":{"state":"unknown","updated_at":"2026-09-12T12:00:00Z","error":"submission_outcome_unknown"},"rejection_reason":null,"created_at":"2026-09-12T12:00:00Z","updated_at":"2026-09-12T12:00:00Z"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"inbox_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]},"patch":{"tags":["Inboxes"],"operationId":"auto_patch_api_v1_accounts_account_id_inboxes_inbox_id_whatsapp_templates_id","summary":"Update a WhatsApp message template (modelo) draft or linked template","description":"WhatsApp message template (official WhatsApp Business API / Cloud template, \"modelo\"). Edits the same template draft, or the provider template it is linked to, and optionally resubmits it to Meta for approval. Saves the existing draft before any provider write. Reusing client_request_id returns the same local identity when content agrees. Local edits use the draft identifier. A verified meta_template_id binds an existing provider template and subsequent submissions edit that Graph node. Name and language of linked templates are immutable; approved category changes are rejected. Status and internal metadata are not writable. A pending or timed-out write is reconciled by read-only lookup and is never blindly repeated. Provider deletion retains the historical local row.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Persisted local draft with stable identity. Submission outcome is separate from provider approval.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"allOf":[{"type":"object","properties":{"id":{"type":"integer","example":21},"name":{"type":"string","example":"order_update"},"language":{"type":"string","example":"pt_BR"},"category":{"type":"string","enum":["MARKETING","UTILITY","AUTHENTICATION"],"example":"UTILITY"},"template_type":{"type":"string","enum":["standard","media_carousel","product_carousel","single_product","catalog","limited_time_offer","multi_product","coupon","call_permission","order_details","authentication","flow"],"example":"standard","description":"WhatsApp template type."},"status":{"type":"string","enum":["draft","pending","approved","rejected","paused","disabled","in_appeal","pending_deletion","deleted","flagged","limit_exceeded","submission_failed"],"description":"Last confirmed provider status or local draft status; separate from an unresolved submission attempt.","example":"draft"},"meta_template_id":{"type":["string","null"],"example":"123456789012345"},"components":{"type":"object","additionalProperties":true,"description":"Authored builder configuration, preserving type-specific components and media references.","example":{"body":{"text":"Your order is ready."}}},"metadata":{"type":"object","additionalProperties":true,"description":"Public durable editor metadata. Internal submission claims, history, request identities and deletion receipts are never serialized or writable.","example":{}},"submission":{"type":"object","description":"Public outcome of the last submission attempt; empty when never submitted.","properties":{"state":{"type":"string","enum":["submitting","unknown","awaiting_sync","accepted","failed"],"example":"unknown"},"updated_at":{"type":"string","format":"date-time","example":"2026-09-12T12:00:00Z"},"error":{"type":"string","example":"submission_outcome_unknown"}}},"rejection_reason":{"type":["string","null"],"example":null},"created_at":{"type":"string","format":"date-time","example":"2026-09-12T12:00:00Z"},"updated_at":{"type":"string","format":"date-time","example":"2026-09-12T12:00:00Z"}}},{"type":"object","properties":{"submit_result":{"type":"object","properties":{"success":{"type":"boolean","example":false},"pending":{"type":"boolean","example":true},"state":{"type":"string","enum":["idle","submitting","unknown","awaiting_sync","accepted","failed"],"example":"unknown"},"error":{"type":"string","example":"submission_outcome_unknown"}}}}}]}}},"example":{"payload":{"id":21,"name":"order_update","language":"pt_BR","category":"UTILITY","template_type":"standard","status":"draft","meta_template_id":"123456789012345","components":{"body":{"text":"Your order is ready."}},"metadata":{},"submission":{"state":"unknown","updated_at":"2026-09-12T12:00:00Z","error":"submission_outcome_unknown"},"rejection_reason":null,"created_at":"2026-09-12T12:00:00Z","updated_at":"2026-09-12T12:00:00Z","submit_result":{"success":false,"pending":true,"state":"unknown","error":"submission_outcome_unknown"}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"202":{"description":"The draft is durable but the provider result or updated catalog is pending. Synchronize or retry the unchanged identity to reconcile; do not create a replacement.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"allOf":[{"type":"object","properties":{"id":{"type":"integer","example":21},"name":{"type":"string","example":"order_update"},"language":{"type":"string","example":"pt_BR"},"category":{"type":"string","enum":["MARKETING","UTILITY","AUTHENTICATION"],"example":"UTILITY"},"template_type":{"type":"string","enum":["standard","media_carousel","product_carousel","single_product","catalog","limited_time_offer","multi_product","coupon","call_permission","order_details","authentication","flow"],"example":"standard","description":"WhatsApp template type."},"status":{"type":"string","enum":["draft","pending","approved","rejected","paused","disabled","in_appeal","pending_deletion","deleted","flagged","limit_exceeded","submission_failed"],"description":"Last confirmed provider status or local draft status; separate from an unresolved submission attempt.","example":"draft"},"meta_template_id":{"type":["string","null"],"example":"123456789012345"},"components":{"type":"object","additionalProperties":true,"description":"Authored builder configuration, preserving type-specific components and media references.","example":{"body":{"text":"Your order is ready."}}},"metadata":{"type":"object","additionalProperties":true,"description":"Public durable editor metadata. Internal submission claims, history, request identities and deletion receipts are never serialized or writable.","example":{}},"submission":{"type":"object","description":"Public outcome of the last submission attempt; empty when never submitted.","properties":{"state":{"type":"string","enum":["submitting","unknown","awaiting_sync","accepted","failed"],"example":"unknown"},"updated_at":{"type":"string","format":"date-time","example":"2026-09-12T12:00:00Z"},"error":{"type":"string","example":"submission_outcome_unknown"}}},"rejection_reason":{"type":["string","null"],"example":null},"created_at":{"type":"string","format":"date-time","example":"2026-09-12T12:00:00Z"},"updated_at":{"type":"string","format":"date-time","example":"2026-09-12T12:00:00Z"}}},{"type":"object","properties":{"submit_result":{"type":"object","properties":{"success":{"type":"boolean","example":false},"pending":{"type":"boolean","example":true},"state":{"type":"string","enum":["idle","submitting","unknown","awaiting_sync","accepted","failed"],"example":"unknown"},"error":{"type":"string","example":"submission_outcome_unknown"}}}}}]}}},"example":{"payload":{"id":21,"name":"order_update","language":"pt_BR","category":"UTILITY","template_type":"standard","status":"draft","meta_template_id":"123456789012345","components":{"body":{"text":"Your order is ready."}},"metadata":{},"submission":{"state":"unknown","updated_at":"2026-09-12T12:00:00Z","error":"submission_outcome_unknown"},"rejection_reason":null,"created_at":"2026-09-12T12:00:00Z","updated_at":"2026-09-12T12:00:00Z","submit_result":{"success":false,"pending":true,"state":"unknown","error":"submission_outcome_unknown"}}}}}},"409":{"description":"Identity conflict, immutable provider field, or unresolved submission/deletion. Retain the existing draft and reconcile before another mutation.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"submission_reconciliation_required"}}},"example":{"error":"submission_reconciliation_required"}}}},"422":{"description":"Draft model validation failed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"submission_reconciliation_required"}}},"example":{"error":"submission_reconciliation_required"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"inbox_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["whatsapp_template"],"properties":{"whatsapp_template":{"type":"object","properties":{"name":{"type":"string","example":"order_update"},"language":{"type":"string","example":"pt_BR"},"category":{"type":"string","enum":["MARKETING","UTILITY","AUTHENTICATION"],"example":"UTILITY"},"template_type":{"type":"string","enum":["standard","media_carousel","product_carousel","single_product","catalog","limited_time_offer","multi_product","coupon","call_permission","order_details","authentication","flow"],"example":"standard","description":"WhatsApp template type."},"components":{"type":"object","additionalProperties":true,"description":"Authored builder configuration for the selected template type.","example":{"body":{"text":"Your order is ready."}}},"metadata":{"type":"object","additionalProperties":true,"description":"Public durable editor metadata; reserved internal keys are ignored.","example":{}},"submit":{"type":"boolean","description":"False saves only the draft; omitted or true requests submission.","example":false},"client_request_id":{"type":"string","maxLength":128,"description":"Stable optional create identity; reuse it for retries with identical content.","example":"template-request-1"},"meta_template_id":{"type":"string","description":"Create-only binding to an existing template verified in the authorized inbox catalog.","example":"123456789012345"}}}}},"example":{"whatsapp_template":{"name":"order_update","language":"pt_BR","category":"UTILITY","template_type":"standard","components":{"body":{"text":"Your order is ready."}},"metadata":{},"submit":false,"client_request_id":"template-request-1","meta_template_id":"123456789012345"}}}}}},"put":{"tags":["Inboxes"],"operationId":"auto_put_api_v1_accounts_account_id_inboxes_inbox_id_whatsapp_templates_id","summary":"Update a WhatsApp message template (modelo) draft or linked template","description":"WhatsApp message template (official WhatsApp Business API / Cloud template, \"modelo\"). Edits the same template draft, or the provider template it is linked to, and optionally resubmits it to Meta for approval. Saves the existing draft before any provider write. Reusing client_request_id returns the same local identity when content agrees. Local edits use the draft identifier. A verified meta_template_id binds an existing provider template and subsequent submissions edit that Graph node. Name and language of linked templates are immutable; approved category changes are rejected. Status and internal metadata are not writable. A pending or timed-out write is reconciled by read-only lookup and is never blindly repeated. Provider deletion retains the historical local row.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Persisted local draft with stable identity. Submission outcome is separate from provider approval.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"allOf":[{"type":"object","properties":{"id":{"type":"integer","example":21},"name":{"type":"string","example":"order_update"},"language":{"type":"string","example":"pt_BR"},"category":{"type":"string","enum":["MARKETING","UTILITY","AUTHENTICATION"],"example":"UTILITY"},"template_type":{"type":"string","enum":["standard","media_carousel","product_carousel","single_product","catalog","limited_time_offer","multi_product","coupon","call_permission","order_details","authentication","flow"],"example":"standard","description":"WhatsApp template type."},"status":{"type":"string","enum":["draft","pending","approved","rejected","paused","disabled","in_appeal","pending_deletion","deleted","flagged","limit_exceeded","submission_failed"],"description":"Last confirmed provider status or local draft status; separate from an unresolved submission attempt.","example":"draft"},"meta_template_id":{"type":["string","null"],"example":"123456789012345"},"components":{"type":"object","additionalProperties":true,"description":"Authored builder configuration, preserving type-specific components and media references.","example":{"body":{"text":"Your order is ready."}}},"metadata":{"type":"object","additionalProperties":true,"description":"Public durable editor metadata. Internal submission claims, history, request identities and deletion receipts are never serialized or writable.","example":{}},"submission":{"type":"object","description":"Public outcome of the last submission attempt; empty when never submitted.","properties":{"state":{"type":"string","enum":["submitting","unknown","awaiting_sync","accepted","failed"],"example":"unknown"},"updated_at":{"type":"string","format":"date-time","example":"2026-09-12T12:00:00Z"},"error":{"type":"string","example":"submission_outcome_unknown"}}},"rejection_reason":{"type":["string","null"],"example":null},"created_at":{"type":"string","format":"date-time","example":"2026-09-12T12:00:00Z"},"updated_at":{"type":"string","format":"date-time","example":"2026-09-12T12:00:00Z"}}},{"type":"object","properties":{"submit_result":{"type":"object","properties":{"success":{"type":"boolean","example":false},"pending":{"type":"boolean","example":true},"state":{"type":"string","enum":["idle","submitting","unknown","awaiting_sync","accepted","failed"],"example":"unknown"},"error":{"type":"string","example":"submission_outcome_unknown"}}}}}]}}},"example":{"payload":{"id":21,"name":"order_update","language":"pt_BR","category":"UTILITY","template_type":"standard","status":"draft","meta_template_id":"123456789012345","components":{"body":{"text":"Your order is ready."}},"metadata":{},"submission":{"state":"unknown","updated_at":"2026-09-12T12:00:00Z","error":"submission_outcome_unknown"},"rejection_reason":null,"created_at":"2026-09-12T12:00:00Z","updated_at":"2026-09-12T12:00:00Z","submit_result":{"success":false,"pending":true,"state":"unknown","error":"submission_outcome_unknown"}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"202":{"description":"The draft is durable but the provider result or updated catalog is pending. Synchronize or retry the unchanged identity to reconcile; do not create a replacement.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"allOf":[{"type":"object","properties":{"id":{"type":"integer","example":21},"name":{"type":"string","example":"order_update"},"language":{"type":"string","example":"pt_BR"},"category":{"type":"string","enum":["MARKETING","UTILITY","AUTHENTICATION"],"example":"UTILITY"},"template_type":{"type":"string","enum":["standard","media_carousel","product_carousel","single_product","catalog","limited_time_offer","multi_product","coupon","call_permission","order_details","authentication","flow"],"example":"standard","description":"WhatsApp template type."},"status":{"type":"string","enum":["draft","pending","approved","rejected","paused","disabled","in_appeal","pending_deletion","deleted","flagged","limit_exceeded","submission_failed"],"description":"Last confirmed provider status or local draft status; separate from an unresolved submission attempt.","example":"draft"},"meta_template_id":{"type":["string","null"],"example":"123456789012345"},"components":{"type":"object","additionalProperties":true,"description":"Authored builder configuration, preserving type-specific components and media references.","example":{"body":{"text":"Your order is ready."}}},"metadata":{"type":"object","additionalProperties":true,"description":"Public durable editor metadata. Internal submission claims, history, request identities and deletion receipts are never serialized or writable.","example":{}},"submission":{"type":"object","description":"Public outcome of the last submission attempt; empty when never submitted.","properties":{"state":{"type":"string","enum":["submitting","unknown","awaiting_sync","accepted","failed"],"example":"unknown"},"updated_at":{"type":"string","format":"date-time","example":"2026-09-12T12:00:00Z"},"error":{"type":"string","example":"submission_outcome_unknown"}}},"rejection_reason":{"type":["string","null"],"example":null},"created_at":{"type":"string","format":"date-time","example":"2026-09-12T12:00:00Z"},"updated_at":{"type":"string","format":"date-time","example":"2026-09-12T12:00:00Z"}}},{"type":"object","properties":{"submit_result":{"type":"object","properties":{"success":{"type":"boolean","example":false},"pending":{"type":"boolean","example":true},"state":{"type":"string","enum":["idle","submitting","unknown","awaiting_sync","accepted","failed"],"example":"unknown"},"error":{"type":"string","example":"submission_outcome_unknown"}}}}}]}}},"example":{"payload":{"id":21,"name":"order_update","language":"pt_BR","category":"UTILITY","template_type":"standard","status":"draft","meta_template_id":"123456789012345","components":{"body":{"text":"Your order is ready."}},"metadata":{},"submission":{"state":"unknown","updated_at":"2026-09-12T12:00:00Z","error":"submission_outcome_unknown"},"rejection_reason":null,"created_at":"2026-09-12T12:00:00Z","updated_at":"2026-09-12T12:00:00Z","submit_result":{"success":false,"pending":true,"state":"unknown","error":"submission_outcome_unknown"}}}}}},"409":{"description":"Identity conflict, immutable provider field, or unresolved submission/deletion. Retain the existing draft and reconcile before another mutation.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"submission_reconciliation_required"}}},"example":{"error":"submission_reconciliation_required"}}}},"422":{"description":"Draft model validation failed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"submission_reconciliation_required"}}},"example":{"error":"submission_reconciliation_required"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"inbox_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["whatsapp_template"],"properties":{"whatsapp_template":{"type":"object","properties":{"name":{"type":"string","example":"order_update"},"language":{"type":"string","example":"pt_BR"},"category":{"type":"string","enum":["MARKETING","UTILITY","AUTHENTICATION"],"example":"UTILITY"},"template_type":{"type":"string","enum":["standard","media_carousel","product_carousel","single_product","catalog","limited_time_offer","multi_product","coupon","call_permission","order_details","authentication","flow"],"example":"standard","description":"WhatsApp template type."},"components":{"type":"object","additionalProperties":true,"description":"Authored builder configuration for the selected template type.","example":{"body":{"text":"Your order is ready."}}},"metadata":{"type":"object","additionalProperties":true,"description":"Public durable editor metadata; reserved internal keys are ignored.","example":{}},"submit":{"type":"boolean","description":"False saves only the draft; omitted or true requests submission.","example":false},"client_request_id":{"type":"string","maxLength":128,"description":"Stable optional create identity; reuse it for retries with identical content.","example":"template-request-1"},"meta_template_id":{"type":"string","description":"Create-only binding to an existing template verified in the authorized inbox catalog.","example":"123456789012345"}}}}},"example":{"whatsapp_template":{"name":"order_update","language":"pt_BR","category":"UTILITY","template_type":"standard","components":{"body":{"text":"Your order is ready."}},"metadata":{},"submit":false,"client_request_id":"template-request-1","meta_template_id":"123456789012345"}}}}}},"delete":{"tags":["Inboxes"],"operationId":"auto_delete_api_v1_accounts_account_id_inboxes_inbox_id_whatsapp_templates_id","summary":"Delete a WhatsApp message template (modelo)","description":"WhatsApp message template (official WhatsApp Business API / Cloud template, \"modelo\"). Deletes one exact provider template id and language or an unsubmitted local draft. A confirmed deletion removes catalog entries but retains the historical draft and its durable references. A timeout or rejection preserves the row and cache; retrying performs read-only reconciliation before any further provider mutation.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Deletion confirmed (empty body)."},"401":{"description":"Unauthorized"},"404":{"description":"No local draft or cached Meta template matches the identifier."},"409":{"description":"Provider deletion failed or remains uncertain; the historical draft is retained.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"deletion_reconciliation_required"}}},"example":{"error":"deletion_reconciliation_required"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"inbox_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/inboxes/{inbox_id}/whatsapp_web_flows":{"get":{"tags":["Inboxes"],"operationId":"auto_get_api_v1_accounts_account_id_inboxes_inbox_id_whatsapp_web_flows","summary":"List whatsapp web flows","description":"Returns the list of whatsapp web flows visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"string"}}}},"example":{"payload":["sample payload"]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"inbox_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."}]}},"/api/v1/accounts/{account_id}/inboxes/{inbox_id}/whatsapp_web_flows/{id}":{"patch":{"tags":["Inboxes"],"operationId":"auto_patch_api_v1_accounts_account_id_inboxes_inbox_id_whatsapp_web_flows_id","summary":"Update whatsapp web flows","description":"Updates the whatsapp web flow identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"flow_id":{"type":"integer"},"name":{"type":"string"},"cta":{"type":"string"}}},"example":{"flow_id":1,"name":"Sample Name","cta":"sample cta"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"inbox_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"}}},"example":{"name":"Sample Name"}}}}},"put":{"tags":["Inboxes"],"operationId":"auto_put_api_v1_accounts_account_id_inboxes_inbox_id_whatsapp_web_flows_id","summary":"Update whatsapp web flows","description":"Updates the whatsapp web flow identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"flow_id":{"type":"integer"},"name":{"type":"string"},"cta":{"type":"string"}}},"example":{"flow_id":1,"name":"Sample Name","cta":"sample cta"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"inbox_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"}}},"example":{"name":"Sample Name"}}}}},"delete":{"tags":["Inboxes"],"operationId":"auto_delete_api_v1_accounts_account_id_inboxes_inbox_id_whatsapp_web_flows_id","summary":"Delete whatsapp web flows","description":"Deletes the whatsapp web flow identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Success (no content)"},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"inbox_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/inboxes/{inbox_id}/whatsapp_flows/{id}/publish":{"post":{"tags":["Inboxes"],"operationId":"auto_post_api_v1_accounts_account_id_inboxes_inbox_id_whatsapp_flows_id_publish","summary":"Publish whatsapp flows","description":"Performs the publish operation on the targeted whatsapp flow resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"status":{"type":"string","enum":["draft","published","retired"]},"categories":{"type":"string"},"meta_flow_id":{"type":"integer"},"endpoint_uri":{"type":"string"},"data_api_version":{"type":"string"},"flow_json":{"type":"string"},"has_endpoint":{"type":"boolean"},"metadata":{"type":"object","properties":{"data_exchange_handler":{"type":"string"},"event_type_id":{"type":"integer"},"attribute_mappings":{"type":"string"},"meta_error":{"type":"string"}},"description":"Free-form metadata bag; the key set depends on the record and context."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}},"example":{"payload":{"id":1,"name":"Sample Name","status":"draft","categories":"sample categories","meta_flow_id":1,"endpoint_uri":"sample endpoint uri","data_api_version":"sample data api version","flow_json":"sample flow json","has_endpoint":true,"metadata":{"data_exchange_handler":"sample data exchange handler","event_type_id":1,"attribute_mappings":"sample attribute mappings","meta_error":"sample meta error"},"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"inbox_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/inboxes/{inbox_id}/whatsapp_flows/{id}/preview":{"get":{"tags":["Inboxes"],"operationId":"auto_get_api_v1_accounts_account_id_inboxes_inbox_id_whatsapp_flows_id_preview","summary":"Preview whatsapp flows","description":"Performs the preview operation on the targeted whatsapp flow resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"WhatsApp Flow preview URL (Meta preview node)","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"preview_url":{"type":"string","description":"Present on success","example":"https://example.com/preview?token=sample-token"},"error":{"type":"string","description":"Present on failure","example":"Flow preview failed"},"response_body":{"type":"string","description":"Raw Meta error body on failure"}}},"example":{"success":true,"preview_url":"https://example.com/preview?token=sample-token","error":"Flow preview failed","response_body":"sample response body"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"inbox_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/inboxes/{inbox_id}/whatsapp_flows/{id}/responses":{"get":{"tags":["Inboxes"],"operationId":"auto_get_api_v1_accounts_account_id_inboxes_inbox_id_whatsapp_flows_id_responses","summary":"Responses whatsapp flows","description":"Performs the responses operation on the targeted whatsapp flow resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"contact_id":{"type":"integer"},"conversation_id":{"type":"integer"},"screen":{"type":"string"},"response":{"type":"string"},"processed_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"}}}}}},"example":{"payload":[{"id":1,"contact_id":1,"conversation_id":1,"screen":"sample screen","response":"sample response","processed_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z"}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"inbox_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/inboxes/{inbox_id}/whatsapp_flows/{id}/enable_endpoint":{"post":{"tags":["Inboxes"],"operationId":"auto_post_api_v1_accounts_account_id_inboxes_inbox_id_whatsapp_flows_id_enable_endpoint","summary":"Enable endpoint whatsapp flows","description":"Performs the enable endpoint operation on the targeted whatsapp flow resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"status":{"type":"string","enum":["draft","published","retired"]},"categories":{"type":"string"},"meta_flow_id":{"type":"integer"},"endpoint_uri":{"type":"string"},"data_api_version":{"type":"string"},"flow_json":{"type":"string"},"has_endpoint":{"type":"boolean"},"metadata":{"type":"object","properties":{"data_exchange_handler":{"type":"string"},"event_type_id":{"type":"integer"},"attribute_mappings":{"type":"string"},"meta_error":{"type":"string"}},"description":"Free-form metadata bag; the key set depends on the record and context."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}},"example":{"payload":{"id":1,"name":"Sample Name","status":"draft","categories":"sample categories","meta_flow_id":1,"endpoint_uri":"sample endpoint uri","data_api_version":"sample data api version","flow_json":"sample flow json","has_endpoint":true,"metadata":{"data_exchange_handler":"sample data exchange handler","event_type_id":1,"attribute_mappings":"sample attribute mappings","meta_error":"sample meta error"},"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"inbox_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/inboxes/{inbox_id}/whatsapp_flows/library":{"get":{"tags":["Inboxes"],"operationId":"auto_get_api_v1_accounts_account_id_inboxes_inbox_id_whatsapp_flows_library","summary":"Library whatsapp flows","description":"Performs the library operation on the targeted whatsapp flow resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"library":{"type":"string"}}},"example":{"library":"sample library"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"inbox_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"locale","in":"query","required":false,"description":"Locale of the pre-built flow library. Defaults to English.","schema":{"type":"string"},"example":"pt_BR"}]}},"/api/v1/accounts/{account_id}/inboxes/{inbox_id}/whatsapp_flows/sync":{"post":{"tags":["Inboxes"],"operationId":"auto_post_api_v1_accounts_account_id_inboxes_inbox_id_whatsapp_flows_sync","summary":"Sync whatsapp flows","description":"Performs the sync operation on the targeted whatsapp flow resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","description":"WhatsApp Flows for the inbox.","items":{"type":"object","additionalProperties":true,"description":"A WhatsApp Flow record (id, name, status, categories, meta_flow_id, endpoint_uri, flow_json, metadata, ...)."}}}},"example":{"payload":[{}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"inbox_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/inboxes/{inbox_id}/whatsapp_flows":{"get":{"tags":["Inboxes"],"operationId":"auto_get_api_v1_accounts_account_id_inboxes_inbox_id_whatsapp_flows","summary":"List whatsapp flows","description":"Returns the list of whatsapp flows visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","description":"WhatsApp Flows for the inbox.","items":{"type":"object","additionalProperties":true,"description":"A WhatsApp Flow record (id, name, status, categories, meta_flow_id, endpoint_uri, flow_json, metadata, ...)."}}}},"example":{"payload":[{}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"inbox_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."}]},"post":{"tags":["Inboxes"],"operationId":"auto_post_api_v1_accounts_account_id_inboxes_inbox_id_whatsapp_flows","summary":"Create whatsapp flows","description":"Creates a new whatsapp flow from the request payload. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"status":{"type":"string","enum":["draft","published","retired"]},"categories":{"type":"string"},"meta_flow_id":{"type":"integer"},"endpoint_uri":{"type":"string"},"data_api_version":{"type":"string"},"flow_json":{"type":"string"},"has_endpoint":{"type":"boolean"},"metadata":{"type":"object","properties":{"data_exchange_handler":{"type":"string"},"event_type_id":{"type":"integer"},"attribute_mappings":{"type":"string"},"meta_error":{"type":"string"}},"description":"Free-form metadata bag; the key set depends on the record and context."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}},"example":{"payload":{"id":1,"name":"Sample Name","status":"draft","categories":"sample categories","meta_flow_id":1,"endpoint_uri":"sample endpoint uri","data_api_version":"sample data api version","flow_json":"sample flow json","has_endpoint":true,"metadata":{"data_exchange_handler":"sample data exchange handler","event_type_id":1,"attribute_mappings":"sample attribute mappings","meta_error":"sample meta error"},"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"inbox_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"whatsapp_flow":{"type":"object","properties":{"name":{"type":"string"},"status":{"type":"string","enum":["draft","published","deprecated","blocked","throttled"]},"endpoint_uri":{"type":"string"},"data_api_version":{"type":"string"},"categories":{"type":"array","items":{"type":"string"}}},"required":["name"]}},"required":["whatsapp_flow"]},"example":{"whatsapp_flow":{"name":"Sample Name","status":"draft","endpoint_uri":"sample endpoint uri","data_api_version":"sample data api version","categories":["sample categorie"]}}}}}}},"/api/v1/accounts/{account_id}/inboxes/{inbox_id}/whatsapp_flows/{id}":{"get":{"tags":["Inboxes"],"operationId":"auto_get_api_v1_accounts_account_id_inboxes_inbox_id_whatsapp_flows_id","summary":"Get whatsapp flows","description":"Returns the whatsapp flow identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"status":{"type":"string","enum":["draft","published","retired"]},"categories":{"type":"string"},"meta_flow_id":{"type":"integer"},"endpoint_uri":{"type":"string"},"data_api_version":{"type":"string"},"flow_json":{"type":"string"},"has_endpoint":{"type":"boolean"},"metadata":{"type":"object","properties":{"data_exchange_handler":{"type":"string"},"event_type_id":{"type":"integer"},"attribute_mappings":{"type":"string"},"meta_error":{"type":"string"}},"description":"Free-form metadata bag; the key set depends on the record and context."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}},"example":{"payload":{"id":1,"name":"Sample Name","status":"draft","categories":"sample categories","meta_flow_id":1,"endpoint_uri":"sample endpoint uri","data_api_version":"sample data api version","flow_json":"sample flow json","has_endpoint":true,"metadata":{"data_exchange_handler":"sample data exchange handler","event_type_id":1,"attribute_mappings":"sample attribute mappings","meta_error":"sample meta error"},"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"inbox_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]},"patch":{"tags":["Inboxes"],"operationId":"auto_patch_api_v1_accounts_account_id_inboxes_inbox_id_whatsapp_flows_id","summary":"Update whatsapp flows","description":"Updates the whatsapp flow identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"status":{"type":"string","enum":["draft","published","retired"]},"categories":{"type":"string"},"meta_flow_id":{"type":"integer"},"endpoint_uri":{"type":"string"},"data_api_version":{"type":"string"},"flow_json":{"type":"string"},"has_endpoint":{"type":"boolean"},"metadata":{"type":"object","properties":{"data_exchange_handler":{"type":"string"},"event_type_id":{"type":"integer"},"attribute_mappings":{"type":"string"},"meta_error":{"type":"string"}},"description":"Free-form metadata bag; the key set depends on the record and context."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}},"example":{"payload":{"id":1,"name":"Sample Name","status":"draft","categories":"sample categories","meta_flow_id":1,"endpoint_uri":"sample endpoint uri","data_api_version":"sample data api version","flow_json":"sample flow json","has_endpoint":true,"metadata":{"data_exchange_handler":"sample data exchange handler","event_type_id":1,"attribute_mappings":"sample attribute mappings","meta_error":"sample meta error"},"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"inbox_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"whatsapp_flow":{"type":"object","properties":{"name":{"type":"string"},"status":{"type":"string","enum":["draft","published","deprecated","blocked","throttled"]},"endpoint_uri":{"type":"string"},"data_api_version":{"type":"string"},"categories":{"type":"array","items":{"type":"string"}}}}},"required":["whatsapp_flow"]},"example":{"whatsapp_flow":{"name":"Sample Name","status":"draft","endpoint_uri":"sample endpoint uri","data_api_version":"sample data api version","categories":["sample categorie"]}}}}}},"put":{"tags":["Inboxes"],"operationId":"auto_put_api_v1_accounts_account_id_inboxes_inbox_id_whatsapp_flows_id","summary":"Update whatsapp flows","description":"Updates the whatsapp flow identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"status":{"type":"string","enum":["draft","published","retired"]},"categories":{"type":"string"},"meta_flow_id":{"type":"integer"},"endpoint_uri":{"type":"string"},"data_api_version":{"type":"string"},"flow_json":{"type":"string"},"has_endpoint":{"type":"boolean"},"metadata":{"type":"object","properties":{"data_exchange_handler":{"type":"string"},"event_type_id":{"type":"integer"},"attribute_mappings":{"type":"string"},"meta_error":{"type":"string"}},"description":"Free-form metadata bag; the key set depends on the record and context."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}},"example":{"payload":{"id":1,"name":"Sample Name","status":"draft","categories":"sample categories","meta_flow_id":1,"endpoint_uri":"sample endpoint uri","data_api_version":"sample data api version","flow_json":"sample flow json","has_endpoint":true,"metadata":{"data_exchange_handler":"sample data exchange handler","event_type_id":1,"attribute_mappings":"sample attribute mappings","meta_error":"sample meta error"},"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"inbox_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"whatsapp_flow":{"type":"object","properties":{"name":{"type":"string"},"status":{"type":"string","enum":["draft","published","deprecated","blocked","throttled"]},"endpoint_uri":{"type":"string"},"data_api_version":{"type":"string"},"categories":{"type":"array","items":{"type":"string"}}}}},"required":["whatsapp_flow"]},"example":{"whatsapp_flow":{"name":"Sample Name","status":"draft","endpoint_uri":"sample endpoint uri","data_api_version":"sample data api version","categories":["sample categorie"]}}}}}},"delete":{"tags":["Inboxes"],"operationId":"auto_delete_api_v1_accounts_account_id_inboxes_inbox_id_whatsapp_flows_id","summary":"Delete whatsapp flows","description":"Deletes the whatsapp flow identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Success (no content)"},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"inbox_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/inboxes/{inbox_id}/whatsapp_call_settings/restart_session":{"post":{"tags":["Inboxes"],"operationId":"auto_post_api_v1_accounts_account_id_inboxes_inbox_id_whatsapp_call_settings_restart_session","summary":"Restart the WhatsApp Web session to apply calling","description":"Requires whatsapp_inbox_suite, access to the logical inbox and inbox management permission. Restarts the WhatsApp Web session of the effective signaling transport so the gateway attaches its calls engine; the device stays paired. The restart runs in the background: the response reports call_config_sync.state restarting, and a later read reports applied or pending_reconnect. Refused with 409 while a call is in progress on the inbox, and with 422 when the transport is not WhatsApp Web or calling is disabled. A request repeated while a restart is already under way queues nothing and receives the same 202. Answers 503 when the restart could not be queued; nothing was changed.","security":[{"userApiKey":[]}],"responses":{"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"202":{"description":"Call settings for the authorized logical inbox and its effective signaling transport.","content":{"application/json":{"schema":{"type":"object","required":["payload"],"properties":{"payload":{"type":"object","required":["inbox_id","effective_inbox_id","provider","calling_enabled","inbound_calls_enabled"],"properties":{"inbox_id":{"type":"integer","description":"Requested logical inbox identifier."},"effective_inbox_id":{"type":"integer","description":"Physical inbox currently responsible for call signaling."},"provider":{"type":"string","enum":["whatsapp_cloud","whatsapp_web"]},"calling_enabled":{"type":"boolean"},"inbound_calls_enabled":{"type":"boolean"},"call_config_sync":{"type":["object","null"],"description":"Gateway synchronization receipt for a WhatsApp Web transport. The gateway applies calling only when the session starts, so pending_reconnect means the session still has to be restarted; applied is reported only after the gateway confirmed its calls engine is attached to the current session.","properties":{"state":{"type":"string","enum":["pending","pending_reconnect","restarting","applied","failed"]},"checked_at":{"type":"string","format":"date-time"},"engine":{"type":"string","enum":["attached","detached","unknown"],"description":"Last answer of the gateway about its calls engine on the current session."}}},"maestro_call_agent_bot_id":{"type":["integer","null"],"description":"The own AI call agent of effective_inbox_id, the channel responsible for signaling. Null when none is chosen. For an enabled hybrid pair this is the Web member's agent, even when inbox_id names the Cloud member; it is not the logical Cloud inbox's own agent."},"ai_call_agent_inactive_copy":{"type":"boolean","description":"True when effective_inbox_id holds a usable, inactive copied agent different from its own agent. The copy answers no call there until activate_copied_ai_agent is sent. False for the Web signaling member of an enabled hybrid pair, including reads through the logical Cloud inbox. The Cloud inbox's retained copy is visible when it signals itself."},"copied_ai_call_agent_bot_id":{"type":["integer","null"],"description":"Id of the usable, inactive copied agent held by effective_inbox_id, not by inbox_id. Null when ai_call_agent_inactive_copy is false, including the Web transport of an enabled pair."},"calls_recording_enabled":{"type":"boolean"},"calls_max_seconds":{"type":["integer","null"]},"video_calls_enabled":{"type":"boolean"},"group_calls_enabled":{"type":"boolean"}}}}},"example":{"payload":{"inbox_id":1,"effective_inbox_id":1,"provider":"whatsapp_cloud","calling_enabled":true,"inbound_calls_enabled":true,"call_config_sync":{"state":"pending","checked_at":"2026-01-15T10:30:00.000Z","engine":"attached"},"maestro_call_agent_bot_id":1,"ai_call_agent_inactive_copy":true,"copied_ai_call_agent_bot_id":1,"calls_recording_enabled":true,"calls_max_seconds":60,"video_calls_enabled":true,"group_calls_enabled":true}}}}},"409":{"description":"A call is in progress on the inbox; a restart would drop it.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","enum":["call_in_progress"]}}},"example":{"error":"call_in_progress"}}}},"422":{"description":"The transport is not WhatsApp Web, or calling is disabled on the inbox.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","enum":["not_a_whatsapp_web_inbox","calling_disabled"]}}},"example":{"error":"calling_disabled"}}}},"503":{"description":"The restart could not be queued; the session was not touched and the request can be repeated.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","enum":["restart_unavailable"]}}},"example":{"error":"restart_unavailable"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"inbox_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/inboxes/{inbox_id}/whatsapp_call_settings":{"get":{"tags":["Inboxes"],"operationId":"auto_get_api_v1_accounts_account_id_inboxes_inbox_id_whatsapp_call_settings","summary":"Read effective WhatsApp call settings","description":"Requires whatsapp_inbox_suite and access to the logical inbox. Returns the settings of the effective Cloud or Web signaling transport; provider credentials are never returned.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Call settings for the authorized logical inbox and its effective signaling transport.","content":{"application/json":{"schema":{"type":"object","required":["payload"],"properties":{"payload":{"type":"object","required":["inbox_id","effective_inbox_id","provider","calling_enabled","inbound_calls_enabled"],"properties":{"inbox_id":{"type":"integer","description":"Requested logical inbox identifier."},"effective_inbox_id":{"type":"integer","description":"Physical inbox currently responsible for call signaling."},"provider":{"type":"string","enum":["whatsapp_cloud","whatsapp_web"]},"calling_enabled":{"type":"boolean"},"inbound_calls_enabled":{"type":"boolean"},"call_config_sync":{"type":["object","null"],"description":"Gateway synchronization receipt for a WhatsApp Web transport. The gateway applies calling only when the session starts, so pending_reconnect means the session still has to be restarted; applied is reported only after the gateway confirmed its calls engine is attached to the current session.","properties":{"state":{"type":"string","enum":["pending","pending_reconnect","restarting","applied","failed"]},"checked_at":{"type":"string","format":"date-time"},"engine":{"type":"string","enum":["attached","detached","unknown"],"description":"Last answer of the gateway about its calls engine on the current session."}}},"maestro_call_agent_bot_id":{"type":["integer","null"],"description":"The own AI call agent of effective_inbox_id, the channel responsible for signaling. Null when none is chosen. For an enabled hybrid pair this is the Web member's agent, even when inbox_id names the Cloud member; it is not the logical Cloud inbox's own agent."},"ai_call_agent_inactive_copy":{"type":"boolean","description":"True when effective_inbox_id holds a usable, inactive copied agent different from its own agent. The copy answers no call there until activate_copied_ai_agent is sent. False for the Web signaling member of an enabled hybrid pair, including reads through the logical Cloud inbox. The Cloud inbox's retained copy is visible when it signals itself."},"copied_ai_call_agent_bot_id":{"type":["integer","null"],"description":"Id of the usable, inactive copied agent held by effective_inbox_id, not by inbox_id. Null when ai_call_agent_inactive_copy is false, including the Web transport of an enabled pair."},"calls_recording_enabled":{"type":"boolean"},"calls_max_seconds":{"type":["integer","null"]},"video_calls_enabled":{"type":"boolean"},"group_calls_enabled":{"type":"boolean"}}}}},"example":{"payload":{"inbox_id":1,"effective_inbox_id":1,"provider":"whatsapp_cloud","calling_enabled":true,"inbound_calls_enabled":true,"call_config_sync":{"state":"pending","checked_at":"2026-01-15T10:30:00.000Z","engine":"attached"},"maestro_call_agent_bot_id":1,"ai_call_agent_inactive_copy":true,"copied_ai_call_agent_bot_id":1,"calls_recording_enabled":true,"calls_max_seconds":60,"video_calls_enabled":true,"group_calls_enabled":true}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"inbox_id","in":"path","required":true,"schema":{"type":"string"}}]},"patch":{"tags":["Inboxes"],"operationId":"auto_patch_api_v1_accounts_account_id_inboxes_inbox_id_whatsapp_call_settings","summary":"Update effective WhatsApp call settings","description":"Requires whatsapp_inbox_suite, access to the logical inbox and inbox management permission. Updates the effective signaling channel's AI, recording and duration settings; only the settings present in the request change. Web-specific video and group toggles apply only to a Web transport. PUT and PATCH have the same contract. In a hybrid pair the recording, duration and inbound settings are also copied to the Cloud inbox of the pair, and the pair's AI agent is recorded beside that inbox's own agent without replacing it: the Cloud inbox keeps answering with its own agent, or with none, once the pair is undone. The copied agent is activated only by activate_copied_ai_agent; sending maestro_call_agent_bot_id with the value the inbox already has changes nothing, and sending another value without activation is the caller's own choice and drops the copy. When a different maestro_call_agent_bot_id and activate_copied_ai_agent: true are sent together, the named agent is applied first and explicit activation wins if a usable copy remains: the copied agent becomes the own agent and the copy is removed. Without a usable copy, the named agent remains. A named agent must belong to the account even when activation is also requested.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Call settings for the authorized logical inbox and its effective signaling transport.","content":{"application/json":{"schema":{"type":"object","required":["payload"],"properties":{"payload":{"type":"object","required":["inbox_id","effective_inbox_id","provider","calling_enabled","inbound_calls_enabled"],"properties":{"inbox_id":{"type":"integer","description":"Requested logical inbox identifier."},"effective_inbox_id":{"type":"integer","description":"Physical inbox currently responsible for call signaling."},"provider":{"type":"string","enum":["whatsapp_cloud","whatsapp_web"]},"calling_enabled":{"type":"boolean"},"inbound_calls_enabled":{"type":"boolean"},"call_config_sync":{"type":["object","null"],"description":"Gateway synchronization receipt for a WhatsApp Web transport. The gateway applies calling only when the session starts, so pending_reconnect means the session still has to be restarted; applied is reported only after the gateway confirmed its calls engine is attached to the current session.","properties":{"state":{"type":"string","enum":["pending","pending_reconnect","restarting","applied","failed"]},"checked_at":{"type":"string","format":"date-time"},"engine":{"type":"string","enum":["attached","detached","unknown"],"description":"Last answer of the gateway about its calls engine on the current session."}}},"maestro_call_agent_bot_id":{"type":["integer","null"],"description":"The own AI call agent of effective_inbox_id, the channel responsible for signaling. Null when none is chosen. For an enabled hybrid pair this is the Web member's agent, even when inbox_id names the Cloud member; it is not the logical Cloud inbox's own agent."},"ai_call_agent_inactive_copy":{"type":"boolean","description":"True when effective_inbox_id holds a usable, inactive copied agent different from its own agent. The copy answers no call there until activate_copied_ai_agent is sent. False for the Web signaling member of an enabled hybrid pair, including reads through the logical Cloud inbox. The Cloud inbox's retained copy is visible when it signals itself."},"copied_ai_call_agent_bot_id":{"type":["integer","null"],"description":"Id of the usable, inactive copied agent held by effective_inbox_id, not by inbox_id. Null when ai_call_agent_inactive_copy is false, including the Web transport of an enabled pair."},"calls_recording_enabled":{"type":"boolean"},"calls_max_seconds":{"type":["integer","null"]},"video_calls_enabled":{"type":"boolean"},"group_calls_enabled":{"type":"boolean"}}}}},"example":{"payload":{"inbox_id":1,"effective_inbox_id":1,"provider":"whatsapp_cloud","calling_enabled":true,"inbound_calls_enabled":true,"call_config_sync":{"state":"pending","checked_at":"2026-01-15T10:30:00.000Z","engine":"attached"},"maestro_call_agent_bot_id":1,"ai_call_agent_inactive_copy":true,"copied_ai_call_agent_bot_id":1,"calls_recording_enabled":true,"calls_max_seconds":60,"video_calls_enabled":true,"group_calls_enabled":true}}}}},"401":{"description":"Permission to read or manage the logical inbox was refused.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}},"example":{"error":"You are not authorized to do this action"}}}},"404":{"description":"The logical inbox is missing or outside the viewer's scope, or the named agent is not in the account.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}},"example":{"error":"Resource could not be found"}}}},"403":{"description":"The WhatsApp Inbox Suite is disabled, or API token access is disabled for the account.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}},"example":{"error":"feature_not_enabled"}}}},"422":{"description":"The effective channel is not a supported WhatsApp voice inbox, required settings are missing, or validation failed.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}},"example":{"error":"not_a_whatsapp_voice_inbox"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"inbox_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["whatsapp_call_settings"],"properties":{"whatsapp_call_settings":{"type":"object","description":"The settings to change. Settings left out keep their value.","properties":{"maestro_call_agent_bot_id":{"type":["integer","null"],"description":"AI call agent of the account to answer this inbox's calls. Null clears it."},"calls_recording_enabled":{"type":"boolean"},"calls_max_seconds":{"type":["integer","null"],"description":"Maximum duration of a call, in seconds. Null removes the limit."},"video_calls_enabled":{"type":"boolean","description":"Web transport only; ignored otherwise."},"group_calls_enabled":{"type":"boolean","description":"Web transport only; ignored otherwise."},"activate_copied_ai_agent":{"type":"boolean","description":"Send true to make the AI call agent a hybrid pair left beside this inbox (copied_ai_call_agent_bot_id) the inbox's own agent. Nothing else activates it. Has no effect when there is no usable copy. If a named agent is also sent, activation of a usable copy takes precedence after that named agent has been applied."}}}}},"examples":{"ordinary_settings":{"summary":"Save the own agent and other settings without activating a copy.","value":{"whatsapp_call_settings":{"maestro_call_agent_bot_id":12,"calls_recording_enabled":true,"calls_max_seconds":900,"video_calls_enabled":true,"group_calls_enabled":true,"activate_copied_ai_agent":false}}},"activation_takes_precedence":{"summary":"Explicit activation wins over a different named agent when a usable copy exists.","description":"With own agent 12 and a usable copied agent 34 on the effective Cloud channel, this request first applies agent 56, then activates agent 34. The response reports own agent 34, ai_call_agent_inactive_copy false and copied_ai_call_agent_bot_id null.","value":{"whatsapp_call_settings":{"maestro_call_agent_bot_id":56,"calls_recording_enabled":true,"calls_max_seconds":null,"video_calls_enabled":true,"group_calls_enabled":true,"activate_copied_ai_agent":true}}}}}}}},"put":{"tags":["Inboxes"],"operationId":"auto_put_api_v1_accounts_account_id_inboxes_inbox_id_whatsapp_call_settings","summary":"Update effective WhatsApp call settings","description":"Requires whatsapp_inbox_suite, access to the logical inbox and inbox management permission. Updates the effective signaling channel's AI, recording and duration settings; only the settings present in the request change. Web-specific video and group toggles apply only to a Web transport. PUT and PATCH have the same contract. In a hybrid pair the recording, duration and inbound settings are also copied to the Cloud inbox of the pair, and the pair's AI agent is recorded beside that inbox's own agent without replacing it: the Cloud inbox keeps answering with its own agent, or with none, once the pair is undone. The copied agent is activated only by activate_copied_ai_agent; sending maestro_call_agent_bot_id with the value the inbox already has changes nothing, and sending another value without activation is the caller's own choice and drops the copy. When a different maestro_call_agent_bot_id and activate_copied_ai_agent: true are sent together, the named agent is applied first and explicit activation wins if a usable copy remains: the copied agent becomes the own agent and the copy is removed. Without a usable copy, the named agent remains. A named agent must belong to the account even when activation is also requested.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Call settings for the authorized logical inbox and its effective signaling transport.","content":{"application/json":{"schema":{"type":"object","required":["payload"],"properties":{"payload":{"type":"object","required":["inbox_id","effective_inbox_id","provider","calling_enabled","inbound_calls_enabled"],"properties":{"inbox_id":{"type":"integer","description":"Requested logical inbox identifier."},"effective_inbox_id":{"type":"integer","description":"Physical inbox currently responsible for call signaling."},"provider":{"type":"string","enum":["whatsapp_cloud","whatsapp_web"]},"calling_enabled":{"type":"boolean"},"inbound_calls_enabled":{"type":"boolean"},"call_config_sync":{"type":["object","null"],"description":"Gateway synchronization receipt for a WhatsApp Web transport. The gateway applies calling only when the session starts, so pending_reconnect means the session still has to be restarted; applied is reported only after the gateway confirmed its calls engine is attached to the current session.","properties":{"state":{"type":"string","enum":["pending","pending_reconnect","restarting","applied","failed"]},"checked_at":{"type":"string","format":"date-time"},"engine":{"type":"string","enum":["attached","detached","unknown"],"description":"Last answer of the gateway about its calls engine on the current session."}}},"maestro_call_agent_bot_id":{"type":["integer","null"],"description":"The own AI call agent of effective_inbox_id, the channel responsible for signaling. Null when none is chosen. For an enabled hybrid pair this is the Web member's agent, even when inbox_id names the Cloud member; it is not the logical Cloud inbox's own agent."},"ai_call_agent_inactive_copy":{"type":"boolean","description":"True when effective_inbox_id holds a usable, inactive copied agent different from its own agent. The copy answers no call there until activate_copied_ai_agent is sent. False for the Web signaling member of an enabled hybrid pair, including reads through the logical Cloud inbox. The Cloud inbox's retained copy is visible when it signals itself."},"copied_ai_call_agent_bot_id":{"type":["integer","null"],"description":"Id of the usable, inactive copied agent held by effective_inbox_id, not by inbox_id. Null when ai_call_agent_inactive_copy is false, including the Web transport of an enabled pair."},"calls_recording_enabled":{"type":"boolean"},"calls_max_seconds":{"type":["integer","null"]},"video_calls_enabled":{"type":"boolean"},"group_calls_enabled":{"type":"boolean"}}}}},"example":{"payload":{"inbox_id":1,"effective_inbox_id":1,"provider":"whatsapp_cloud","calling_enabled":true,"inbound_calls_enabled":true,"call_config_sync":{"state":"pending","checked_at":"2026-01-15T10:30:00.000Z","engine":"attached"},"maestro_call_agent_bot_id":1,"ai_call_agent_inactive_copy":true,"copied_ai_call_agent_bot_id":1,"calls_recording_enabled":true,"calls_max_seconds":60,"video_calls_enabled":true,"group_calls_enabled":true}}}}},"401":{"description":"Permission to read or manage the logical inbox was refused.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}},"example":{"error":"You are not authorized to do this action"}}}},"404":{"description":"The logical inbox is missing or outside the viewer's scope, or the named agent is not in the account.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}},"example":{"error":"Resource could not be found"}}}},"403":{"description":"The WhatsApp Inbox Suite is disabled, or API token access is disabled for the account.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}},"example":{"error":"feature_not_enabled"}}}},"422":{"description":"The effective channel is not a supported WhatsApp voice inbox, required settings are missing, or validation failed.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}},"example":{"error":"not_a_whatsapp_voice_inbox"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"inbox_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["whatsapp_call_settings"],"properties":{"whatsapp_call_settings":{"type":"object","description":"The settings to change. Settings left out keep their value.","properties":{"maestro_call_agent_bot_id":{"type":["integer","null"],"description":"AI call agent of the account to answer this inbox's calls. Null clears it."},"calls_recording_enabled":{"type":"boolean"},"calls_max_seconds":{"type":["integer","null"],"description":"Maximum duration of a call, in seconds. Null removes the limit."},"video_calls_enabled":{"type":"boolean","description":"Web transport only; ignored otherwise."},"group_calls_enabled":{"type":"boolean","description":"Web transport only; ignored otherwise."},"activate_copied_ai_agent":{"type":"boolean","description":"Send true to make the AI call agent a hybrid pair left beside this inbox (copied_ai_call_agent_bot_id) the inbox's own agent. Nothing else activates it. Has no effect when there is no usable copy. If a named agent is also sent, activation of a usable copy takes precedence after that named agent has been applied."}}}}},"examples":{"ordinary_settings":{"summary":"Save the own agent and other settings without activating a copy.","value":{"whatsapp_call_settings":{"maestro_call_agent_bot_id":12,"calls_recording_enabled":true,"calls_max_seconds":900,"video_calls_enabled":true,"group_calls_enabled":true,"activate_copied_ai_agent":false}}},"activation_takes_precedence":{"summary":"Explicit activation wins over a different named agent when a usable copy exists.","description":"With own agent 12 and a usable copied agent 34 on the effective Cloud channel, this request first applies agent 56, then activates agent 34. The response reports own agent 34, ai_call_agent_inactive_copy false and copied_ai_call_agent_bot_id null.","value":{"whatsapp_call_settings":{"maestro_call_agent_bot_id":56,"calls_recording_enabled":true,"calls_max_seconds":null,"video_calls_enabled":true,"group_calls_enabled":true,"activate_copied_ai_agent":true}}}}}}}}},"/api/v1/accounts/{account_id}/organizations/demo":{"delete":{"tags":["Organizations"],"operationId":"auto_delete_api_v1_accounts_account_id_organizations_demo","summary":"Tear down organizations demo data","description":"Admin-only. Enqueues Organizations::DemoJob to remove all demo organizations and their associated records. Returns 202 Accepted immediately.","security":[{"userApiKey":[]}],"responses":{"202":{"description":"Demo teardown job enqueued."},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]},"post":{"tags":["Organizations"],"operationId":"auto_post_api_v1_accounts_account_id_organizations_demo","summary":"Seed organizations demo data","description":"Admin-only. Enqueues Organizations::DemoJob to seed sample companies, contacts, memberships, relationships and tasks. Poll the organizations list until the demo companies appear. Returns 202 Accepted immediately.","security":[{"userApiKey":[]}],"responses":{"202":{"description":"Demo seed job enqueued."},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/organizations/export":{"post":{"tags":["Organizations"],"operationId":"auto_post_api_v1_accounts_account_id_organizations_export","summary":"Export organizations to CSV","description":"Enqueues Account::OrganizationsExportJob with the selected columns and filters. The job delivers the CSV asynchronously. Returns 200 immediately. Omitting column_names exports the default set, which is a superset of what the import accepts (plus the read-only id, contacts_count and created_at), so an untouched export re-imports without losing a field. The postal address is written as one flat column per component (address_zip_code, address_street_name, ...) rather than a raw JSON blob, and domains is a comma-separated list with the primary first. tax_id ALWAYS leaves masked and the import refuses a masked value, so the fiscal identifier deliberately does not round-trip.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Export job enqueued successfully."},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"search":{"type":["string","null"],"example":"Colégio Horizonte"},"lifecycle_stage":{"type":["string","null"],"example":"customer"},"organization_ids":{"type":"array","items":{"type":"integer"},"example":[1,2,3]},"column_names":{"type":"array","items":{"type":"string"},"example":["name","domain","tax_id"]},"payload":{"type":["object","null"],"additionalProperties":true,"description":"Filter payload for Organizations::FilterService (account-defined criteria)."}}},"example":{"search":"Colégio Horizonte","lifecycle_stage":"customer","organization_ids":[1,2,3],"column_names":["name","domain","tax_id"],"payload":{}}}}}}},"/api/v1/accounts/{account_id}/organizations/import":{"post":{"tags":["Organizations"],"operationId":"auto_post_api_v1_accounts_account_id_organizations_import","summary":"Import organizations from CSV","description":"Uploads a CSV file, stores it as an Active Storage blob, and enqueues Account::OrganizationsImportJob to upsert organizations by name. Returns 200 immediately or 422 if no file is provided. Accepted header columns (only `name` is required; unknown columns are ignored): name, legal_name, tax_id, tax_id_type, domain, domains, lifecycle_stage, industry, size, country, email, phone, website, timezone, description, health_score, address_zip_code, address_street_name, address_street_number, address_complement, address_neighborhood, address_city, address_federal_unit, state_registration, municipal_registration. The address_* and registration columns MERGE into the stored maps, so a CSV carrying only address_city updates the city and leaves the rest of the address intact. domains is a comma-separated list whose first entry becomes the primary. A masked tax_id is never imported.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Import job enqueued successfully."},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"422":{"description":"CSV file is required.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"CSV file is required"}}},"example":{"error":"CSV file is required"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"import_file":{"type":"string","format":"binary","description":"CSV file with organizations to import."}}}}}}}},"/api/v1/accounts/{account_id}/organizations/{id}/avatar":{"delete":{"tags":["Organizations"],"operationId":"auto_delete_api_v1_accounts_account_id_organizations_id_avatar","summary":"Avatar organizations","description":"Performs the avatar operation on the targeted organization resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The organization after its avatar was removed.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"$ref":"#/components/schemas/organization"}}},"example":{"payload":{"id":1,"account_id":1,"name":"Sample Name","legal_name":"sample legal name","legal_type":"individual","tax_id":"sample tax id","tax_id_type":"br_cpf","country":"BR","domain":"example.com","domains":[{"domain":"example.com","primary":true}],"website":"sample website","industry":"sample industry","size":"11-50","lifecycle_stage":"sample lifecycle stage","parent_id":1,"parent_name":"sample parent name","children_count":5,"children":[{"id":1,"name":"Sample Name","legal_name":"sample legal name","lifecycle_stage":"sample lifecycle stage","domain":"example.com"}],"owner_id":1,"owner_name":"sample owner name","thumbnail":"https://cdn.example.com/orgs/42.png","avatar_url":"https://cdn.example.com/orgs/42.png","email":"agent@example.com","phone":"+5511999998888","address":{"zip_code":"13338-705","street_name":"Av. Paulista","street_number":"1000","complement":"Sala 42","neighborhood":"Bela Vista","city":"Indaiatuba","federal_unit":"SP"},"registrations":{"state_registration":"110042490114","municipal_registration":"1234567"},"timezone":"America/Sao_Paulo","description":"A short description.","custom_attributes":{},"additional_attributes":{},"contacts_count":5,"health_score":12.5,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","field_visibility":{"tax_id":"masked","address":"hidden","email":"masked","phone":"masked"}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/crm/items/board":{"get":{"tags":["CRM"],"operationId":"auto_get_api_v1_accounts_account_id_crm_items_board","summary":"Get the CRM kanban board (first page per stage)","description":"Scalable kanban payload for one pipeline: for every stage that has at least one matching deal, returns the FIRST page of cards (ordered by position), the authoritative deal count for the whole column, the Sum of value plus the weighted forecast grouped by currency, and has_more. The board never loads a whole pipeline at once — a column's \"load more\" reuses GET /crm/items with stage_id, page and sort=position_asc. Honors the same filters as the item list (pipeline_id, q, status, priority, health_status, team_id, assignee_id, has_conversation, visibility, period, archived). The per_page query parameter sizes each column's first page (default 25, capped for safety). Requires CRM item read authorization (administrator or agent).","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Per-stage board columns (only stages with matching deals appear).","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"stages":{"type":"array","description":"One entry per stage that has at least one matching deal.","items":{"type":"object","properties":{"stage_id":{"type":"integer","description":"The pipeline stage id (the board column).","example":42},"count":{"type":"integer","description":"Authoritative number of matching deals in this stage (the whole column, not just the loaded page).","example":484},"has_more":{"type":"boolean","description":"Whether more pages of cards exist beyond the returned first page.","example":true},"totals":{"type":"array","description":"Sum of value plus the weighted forecast per currency for the whole column (blank currency omitted).","items":{"type":"object","properties":{"currency":{"type":"string","description":"ISO 4217 currency code.","example":"USD"},"value":{"type":"number","description":"Sum of value_amount for this currency across the whole stage.","example":90000.0},"forecast":{"type":"number","description":"Sum of value_amount multiplied by stage.probability divided by 100 for this currency.","example":45000.0}}}},"items":{"type":"array","description":"First page of deal cards for this stage, ordered by position. Each card is the shared CRM item shape documented on the item CRUD endpoints.","items":{"type":"object","additionalProperties":true,"description":"A CRM deal card (same payload as GET /crm/items/{id}).","example":{"id":9001,"pipeline_id":7,"stage_id":42,"title":"Acme renewal","status":"open","value_amount":5000.0,"currency":"USD","position":0,"conversation":{"id":18201,"display_id":173,"inbox":{"id":51,"name":"WhatsApp Comercial","channel_type":"Channel::Whatsapp","provider":"whatsapp_cloud","medium":null,"voice_enabled":false}}}}}}}}}}}},"example":{"payload":{"stages":[{"stage_id":42,"count":484,"has_more":true,"totals":[{"currency":"USD","value":90000.0,"forecast":45000.0}],"items":[{"id":9001,"pipeline_id":7,"stage_id":42,"title":"Acme renewal","status":"open","value_amount":5000.0,"currency":"USD","position":0,"conversation":{"id":18201,"display_id":173,"inbox":{"id":51,"name":"WhatsApp Comercial","channel_type":"Channel::Whatsapp","provider":"whatsapp_cloud","medium":null,"voice_enabled":false}}}]}]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/crm/orders/{id}/void_preview":{"get":{"tags":["CRM"],"operationId":"auto_get_api_v1_accounts_account_id_crm_orders_id_void_preview","summary":"Preview the exact impact of voiding an order","description":"Read-only administrator preview computed by the same governed service used by DELETE. It lists reversible ledger/effect records and dependencies that make the operation fail closed. It never calls a gateway, mutates the order or queues a side effect.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Current impact for this account-scoped order.","content":{"application/json":{"schema":{"type":"object","required":["payload"],"properties":{"payload":{"type":"object","required":["order_id","paid","pending_effects","will_ignore_external"],"properties":{"order_id":{"type":"integer","minimum":1},"paid":{"type":"boolean"},"commission_accrual_ids":{"type":"array","items":{"type":"integer","minimum":1}},"closed_commission_accrual_ids":{"type":"array","items":{"type":"integer","minimum":1}},"closed_commission_statement_ids":{"type":"array","items":{"type":"integer","minimum":1}},"stock_movement_id":{"type":["integer","null"],"minimum":1},"engagement_event_ids":{"type":"array","items":{"type":"integer","minimum":1}},"sales_point_event_ids":{"type":"array","items":{"type":"integer","minimum":1}},"commerce_lifecycle_event_id":{"type":["integer","null"],"minimum":1},"confirmed_booking_ids":{"type":"array","items":{"type":"integer","minimum":1}},"invalidated_team_reward_grant_ids":{"type":"array","items":{"type":"integer","minimum":1}},"irreversible_distribution_member_ids":{"type":"array","items":{"type":"integer","minimum":1}},"pending_effects":{"type":"object","required":["flow_session_ids","follow_up_enrollment_ids","distribution_member_ids"],"properties":{"flow_session_ids":{"type":"array","items":{"type":"integer","minimum":1}},"follow_up_enrollment_ids":{"type":"array","items":{"type":"integer","minimum":1}},"distribution_member_ids":{"type":"array","items":{"type":"integer","minimum":1}}}},"will_ignore_external":{"type":"boolean"}}}}},"example":{"payload":{"order_id":1,"paid":true,"commission_accrual_ids":[1],"closed_commission_accrual_ids":[1],"closed_commission_statement_ids":[1],"stock_movement_id":1,"engagement_event_ids":[1],"sales_point_event_ids":[1],"commerce_lifecycle_event_id":1,"confirmed_booking_ids":[1],"invalidated_team_reward_grant_ids":[1],"irreversible_distribution_member_ids":[1],"pending_effects":{"flow_session_ids":[1],"follow_up_enrollment_ids":[1],"distribution_member_ids":[1]},"will_ignore_external":true}}}}},"401":{"description":"A non-administrator cannot preview a governed financial/integration order void."},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/crm/orders/{id}/restore":{"post":{"tags":["CRM"],"operationId":"auto_post_api_v1_accounts_account_id_crm_orders_id_restore","summary":"Restore a reversibly voided order","description":"Restores only a void that produced no commission, stock or engagement compensation and whose connection-scoped external identity is still free. Otherwise it fails closed.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Restored order.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/crm_order"},"example":{"id":1,"account_id":1,"contact_id":1,"contact_name":"sample contact name","contact_email":"agent@example.com","contact_phone_number":"+5511999998888","organization_id":1,"organization_name":"sample organization name","crm_item_id":1,"crm_item_title":"sample crm item title","payments_charge_id":1,"source_connection_id":1,"owner_id":1,"owner_name":"sample owner name","voided_at":"2026-01-15T10:30:00.000Z","voided_by_id":1,"void_reason":"sample void reason","void_kind":"test_data","affiliate_id":1,"affiliate_name":"sample affiliate name","gateway":"sample gateway","external_id":"sample external id","title":"Sample title","amount":149.9,"amount_refunded":12.5,"recognized_amount":149.9,"currency":"BRL","status":"pending","source":"manual","ordered_at":"2026-01-15T10:30:00.000Z","paid_at":"2026-01-15T10:30:00.000Z","metadata":{},"line_items":[{"id":1,"source_item_id":"sample source item id","catalog_product_id":1,"catalog_variant_id":1,"name_snapshot":"sample name snapshot","quantity":12.5,"unit_price":149.9,"discount":12.5,"discount_type":"fixed","line_total":149.9,"currency":"BRL","position":1,"metadata":{}}],"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"422":{"description":"Restoration requires an explicit accounting correction or the identity is in use."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/crm/orders/export":{"get":{"tags":["CRM"],"operationId":"auto_get_api_v1_accounts_account_id_crm_orders_export","summary":"Export orders","description":"Performs the export operation on the targeted order resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"File download","content":{"text/csv; charset=utf-8":{"schema":{"type":"string","format":"binary"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/crm/orders/bulk":{"post":{"tags":["CRM"],"operationId":"auto_post_api_v1_accounts_account_id_crm_orders_bulk","summary":"Remove selected orders","description":"Processes up to 500 policy-visible orders. Safe manual typos are deleted; financial or integration-sourced records require an administrator and are voided with audited compensation.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Per-record result; failed records remain untouched.","content":{"application/json":{"schema":{"type":"object","required":["processed_ids","failed_ids"],"properties":{"processed_ids":{"type":"array","items":{"type":"integer"}},"failed_ids":{"type":"array","items":{"type":"integer"}}}},"example":{"processed_ids":[1],"failed_ids":[1]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"422":{"description":"Unsupported action, empty/oversized selection, or invalid lifecycle input.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","example":"ids_required"}}},"example":{"error":"ids_required"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["ids","bulk_action"],"properties":{"ids":{"type":"array","minItems":1,"maxItems":500,"items":{"type":"integer","minimum":1}},"bulk_action":{"type":"string","enum":["delete"]},"reason":{"type":"string","maxLength":1000,"description":"Required when any selected order must be voided."},"kind":{"type":"string","enum":["test_data","duplicate","source_purged","operator_error","legacy_orphan","other"],"default":"operator_error"}}},"example":{"ids":[41,42],"bulk_action":"delete","reason":"Test records generated during setup.","kind":"test_data"}}}}}},"/api/v1/accounts/{account_id}/crm/orders/ingest_token":{"get":{"tags":["CRM"],"operationId":"auto_get_api_v1_accounts_account_id_crm_orders_ingest_token","summary":"Ingest token orders","description":"Performs the ingest token operation on the targeted order resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"token":{"type":"string"},"ingest_url":{"type":"string"}}},"example":{"token":"sample-token","ingest_url":"https://example.com/resource"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/crm/orders/rotate_ingest_token":{"post":{"tags":["CRM"],"operationId":"auto_post_api_v1_accounts_account_id_crm_orders_rotate_ingest_token","summary":"Rotate ingest token orders","description":"Performs the rotate ingest token operation on the targeted order resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"token":{"type":"string"},"ingest_url":{"type":"string"}}},"example":{"token":"sample-token","ingest_url":"https://example.com/resource"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/crm/orders":{"get":{"tags":["CRM"],"operationId":"auto_get_api_v1_accounts_account_id_crm_orders","summary":"List operational or voided CRM orders","description":"Returns the policy-visible account registry using the same allow-listed filters as CSV export and bulk actions. Active orders are returned by default; voided records must be requested explicitly.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"One bounded page plus authoritative pagination metadata.","content":{"application/json":{"schema":{"type":"object","required":["payload","meta"],"properties":{"payload":{"type":"array","items":{"$ref":"#/components/schemas/crm_order"}},"meta":{"type":"object","required":["count","current_page","total_pages","per_page"],"properties":{"count":{"type":"integer","minimum":0},"current_page":{"type":"integer","minimum":1},"total_pages":{"type":"integer","minimum":0},"per_page":{"type":"integer","minimum":1,"maximum":100}}}}},"example":{"payload":[{"id":1,"account_id":1,"contact_id":1,"contact_name":"sample contact name","contact_email":"agent@example.com","contact_phone_number":"+5511999998888","organization_id":1,"organization_name":"sample organization name","crm_item_id":1,"crm_item_title":"sample crm item title","payments_charge_id":1,"source_connection_id":1,"owner_id":1,"owner_name":"sample owner name","voided_at":"2026-01-15T10:30:00.000Z","voided_by_id":1,"void_reason":"sample void reason","void_kind":"test_data","affiliate_id":1,"affiliate_name":"sample affiliate name","gateway":"sample gateway","external_id":"sample external id","title":"Sample title","amount":149.9,"amount_refunded":12.5,"recognized_amount":149.9,"currency":"BRL","status":"pending","source":"manual","ordered_at":"2026-01-15T10:30:00.000Z","paid_at":"2026-01-15T10:30:00.000Z","metadata":{},"line_items":[{"id":1,"source_item_id":"sample source item id","catalog_product_id":1,"catalog_variant_id":1,"name_snapshot":"sample name snapshot","quantity":12.5,"unit_price":149.9,"discount":12.5,"discount_type":"fixed","line_total":149.9,"currency":"BRL","position":1,"metadata":{}}],"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}],"meta":{"count":5,"current_page":1,"total_pages":1,"per_page":1}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"422":{"description":"Invalid status, source, date, record state, sort or direction."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"1-based result page.","schema":{"type":"integer","minimum":1,"default":1}},{"name":"per_page","in":"query","required":false,"description":"Orders per page; values above 100 are capped to 100.","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"contact_id","in":"query","required":false,"schema":{"type":"integer","minimum":1}},{"name":"crm_item_id","in":"query","required":false,"description":"Restrict results to one CRM deal.","schema":{"type":"integer","minimum":1}},{"name":"gateway","in":"query","required":false,"description":"Exact open gateway/source namespace.","schema":{"type":"string"}},{"name":"owner_id","in":"query","required":false,"description":"Restrict results to one carteira owner.","schema":{"type":"integer","minimum":1}},{"name":"source","in":"query","required":false,"schema":{"type":"string","enum":["manual","webhook","api","payments","commerce"]}},{"name":"from","in":"query","required":false,"description":"Inclusive lower bound for ordered_at.","schema":{"type":"string","format":"date-time"}},{"name":"to","in":"query","required":false,"description":"Inclusive upper bound for ordered_at.","schema":{"type":"string","format":"date-time"}},{"name":"q","in":"query","required":false,"description":"Case-insensitive search across title, external id and contact name.","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"schema":{"type":"string","enum":["ordered_at","paid_at","amount","status","title"],"default":"ordered_at"}},{"name":"direction","in":"query","required":false,"schema":{"type":"string","enum":["asc","desc"],"default":"desc"}},{"name":"status","in":"query","required":false,"description":"One or more recorded statuses; a comma-separated value is also accepted.","schema":{"type":"array","items":{"type":"string","enum":["pending","paid","partially_paid","partially_refunded","overdue","refunded","canceled","failed"]}}},{"name":"record_state","in":"query","required":false,"schema":{"type":"string","enum":["active","voided","all"],"default":"active"}},{"name":"ids","in":"query","required":false,"description":"Optional repeated array of positive local order ids.","schema":{"type":"array","items":{"type":"integer","minimum":1}}}]},"post":{"tags":["CRM"],"operationId":"auto_post_api_v1_accounts_account_id_crm_orders","summary":"Register a manual CRM order","description":"Creates an operator-entered purchase record for an account contact. The registry records the sale only; it never creates or settles a gateway charge. `gateway` is an open provenance namespace such as `manual`, an ERP or a checkout. An optional opaque external_id makes retries idempotent. A manual write may never overwrite an integration-owned identity or reuse another contact's manual identity. Creating a paid, partially paid or refunded state, or explicitly assigning an affiliate, requires an administrator/sales manager and a durable reason.","security":[{"userApiKey":[]}],"responses":{"201":{"description":"Manual CRM order created through the governed registration seam.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/crm_order"},"example":{"id":1,"account_id":1,"contact_id":1,"contact_name":"sample contact name","contact_email":"agent@example.com","contact_phone_number":"+5511999998888","organization_id":1,"organization_name":"sample organization name","crm_item_id":1,"crm_item_title":"sample crm item title","payments_charge_id":1,"source_connection_id":1,"owner_id":1,"owner_name":"sample owner name","voided_at":"2026-01-15T10:30:00.000Z","voided_by_id":1,"void_reason":"sample void reason","void_kind":"test_data","affiliate_id":1,"affiliate_name":"sample affiliate name","gateway":"sample gateway","external_id":"sample external id","title":"Sample title","amount":149.9,"amount_refunded":12.5,"recognized_amount":149.9,"currency":"BRL","status":"pending","source":"manual","ordered_at":"2026-01-15T10:30:00.000Z","paid_at":"2026-01-15T10:30:00.000Z","metadata":{},"line_items":[{"id":1,"source_item_id":"sample source item id","catalog_product_id":1,"catalog_variant_id":1,"name_snapshot":"sample name snapshot","quantity":12.5,"unit_price":149.9,"discount":12.5,"discount_type":"fixed","line_total":149.9,"currency":"BRL","position":1,"metadata":{}}],"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"422":{"description":"Invalid status/association or an identity collision with an integration-owned record or another contact."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["order"],"properties":{"order":{"type":"object","required":["contact_id"],"properties":{"contact_id":{"type":"integer","minimum":1},"crm_item_id":{"type":["integer","null"],"minimum":1},"gateway":{"type":"string","default":"manual","description":"Open provenance namespace for this operator-entered record; this does not call that provider."},"external_id":{"type":"string","description":"Opaque idempotency identifier within the account and gateway namespace; omit to generate one."},"title":{"type":["string","null"]},"amount":{"type":"number","minimum":0},"currency":{"type":"string","example":"BRL"},"status":{"type":"string","enum":["pending","paid","partially_paid","overdue","refunded","canceled","failed"],"description":"The recorded payment status of the order."},"ordered_at":{"type":["string","null"],"format":"date-time"},"paid_at":{"type":["string","null"],"format":"date-time"},"affiliate_id":{"type":["integer","null"],"minimum":1},"financial_transition_reason":{"type":"string","maxLength":1000,"description":"Required for a financial status or explicit affiliate attribution."},"line_items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","minimum":1},"source_item_id":{"type":"string"},"external_id":{"type":"string"},"catalog_product_id":{"type":["integer","null"],"minimum":1},"catalog_variant_id":{"type":["integer","null"],"minimum":1},"name_snapshot":{"type":["string","null"]},"name":{"type":["string","null"]},"quantity":{"type":"number","exclusiveMinimum":0},"unit_price":{"type":"number","minimum":0},"price":{"type":"number","minimum":0},"discount":{"type":"number","minimum":0},"discount_type":{"type":"string","enum":["fixed","percent"],"description":"Whether the discount is an absolute amount or a percentage."},"currency":{"type":"string","example":"BRL"},"position":{"type":"integer","minimum":0},"metadata":{"type":"object","additionalProperties":true,"description":"Free-form metadata bag; the key set depends on the record and context."}}}}}}}},"example":{"order":{"contact_id":1,"crm_item_id":1,"gateway":"manual","external_id":"sample external id","title":"Sample title","amount":149.9,"currency":"BRL","status":"pending","ordered_at":"2026-01-15T10:30:00.000Z","paid_at":"2026-01-15T10:30:00.000Z","affiliate_id":1,"financial_transition_reason":"sample financial transition reason","line_items":[{"id":1,"source_item_id":"sample source item id","external_id":"sample external id","catalog_product_id":1,"catalog_variant_id":1,"name_snapshot":"sample name snapshot","name":"Sample Name","quantity":12.5,"unit_price":149.9,"price":149.9,"discount":12.5,"discount_type":"fixed","currency":"BRL","position":1,"metadata":{}}]}}}}}}},"/api/v1/accounts/{account_id}/crm/orders/{id}":{"get":{"tags":["CRM"],"operationId":"auto_get_api_v1_accounts_account_id_crm_orders_id","summary":"Get orders","description":"Returns the order identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"CRM order with immutable line-item snapshots.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/crm_order"},"example":{"id":1,"account_id":1,"contact_id":1,"contact_name":"sample contact name","contact_email":"agent@example.com","contact_phone_number":"+5511999998888","organization_id":1,"organization_name":"sample organization name","crm_item_id":1,"crm_item_title":"sample crm item title","payments_charge_id":1,"source_connection_id":1,"owner_id":1,"owner_name":"sample owner name","voided_at":"2026-01-15T10:30:00.000Z","voided_by_id":1,"void_reason":"sample void reason","void_kind":"test_data","affiliate_id":1,"affiliate_name":"sample affiliate name","gateway":"sample gateway","external_id":"sample external id","title":"Sample title","amount":149.9,"amount_refunded":12.5,"recognized_amount":149.9,"currency":"BRL","status":"pending","source":"manual","ordered_at":"2026-01-15T10:30:00.000Z","paid_at":"2026-01-15T10:30:00.000Z","metadata":{},"line_items":[{"id":1,"source_item_id":"sample source item id","catalog_product_id":1,"catalog_variant_id":1,"name_snapshot":"sample name snapshot","quantity":12.5,"unit_price":149.9,"discount":12.5,"discount_type":"fixed","line_total":149.9,"currency":"BRL","position":1,"metadata":{}}],"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]},"patch":{"tags":["CRM"],"operationId":"auto_patch_api_v1_accounts_account_id_crm_orders_id","summary":"Correct a manual CRM order","description":"Updates an operator-entered manual order through the governed registration seam. A payment or commerce projection accepts only audited affiliate re-attribution; all other changes must happen on the source charge/event and synchronize into the registry. Contact reassignment uses the sale graph repair flow. Gateway/external identity is immutable, status cannot regress, and financial facts (amount, currency, paid_at, line items and deal attribution) cannot change after financial side effects exist; use the sales-graph repair flow for association corrections. Entering a financial status or changing affiliate credit requires administrator/sales_manage and financial_transition_reason; the before/after receipt is retained on the order.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Updated manual CRM order.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/crm_order"},"example":{"id":1,"account_id":1,"contact_id":1,"contact_name":"sample contact name","contact_email":"agent@example.com","contact_phone_number":"+5511999998888","organization_id":1,"organization_name":"sample organization name","crm_item_id":1,"crm_item_title":"sample crm item title","payments_charge_id":1,"source_connection_id":1,"owner_id":1,"owner_name":"sample owner name","voided_at":"2026-01-15T10:30:00.000Z","voided_by_id":1,"void_reason":"sample void reason","void_kind":"test_data","affiliate_id":1,"affiliate_name":"sample affiliate name","gateway":"sample gateway","external_id":"sample external id","title":"Sample title","amount":149.9,"amount_refunded":12.5,"recognized_amount":149.9,"currency":"BRL","status":"pending","source":"manual","ordered_at":"2026-01-15T10:30:00.000Z","paid_at":"2026-01-15T10:30:00.000Z","metadata":{},"line_items":[{"id":1,"source_item_id":"sample source item id","catalog_product_id":1,"catalog_variant_id":1,"name_snapshot":"sample name snapshot","quantity":12.5,"unit_price":149.9,"discount":12.5,"discount_type":"fixed","line_total":149.9,"currency":"BRL","position":1,"metadata":{}}],"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"422":{"description":"External order, identity or settled financial facts are immutable; a financial reason is missing; contact repair used the wrong flow; or a submitted status/association is invalid."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["order"],"properties":{"order":{"type":"object","properties":{"crm_item_id":{"type":["integer","null"],"minimum":1},"title":{"type":["string","null"]},"amount":{"type":"number","minimum":0},"currency":{"type":"string","example":"BRL"},"status":{"type":"string","enum":["pending","paid","partially_paid","overdue","refunded","canceled","failed"],"description":"The recorded payment status of the order."},"ordered_at":{"type":["string","null"],"format":"date-time"},"paid_at":{"type":["string","null"],"format":"date-time"},"affiliate_id":{"type":["integer","null"],"minimum":1},"financial_transition_reason":{"type":"string","maxLength":1000,"description":"Required when status enters a financial state or affiliate credit changes."},"line_items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","minimum":1},"source_item_id":{"type":"string"},"external_id":{"type":"string"},"catalog_product_id":{"type":["integer","null"],"minimum":1},"catalog_variant_id":{"type":["integer","null"],"minimum":1},"name_snapshot":{"type":["string","null"]},"name":{"type":["string","null"]},"quantity":{"type":"number","exclusiveMinimum":0},"unit_price":{"type":"number","minimum":0},"price":{"type":"number","minimum":0},"discount":{"type":"number","minimum":0},"discount_type":{"type":"string","enum":["fixed","percent"],"description":"Whether the discount is an absolute amount or a percentage."},"currency":{"type":"string","example":"BRL"},"position":{"type":"integer","minimum":0},"metadata":{"type":"object","additionalProperties":true,"description":"Free-form metadata bag; the key set depends on the record and context."}}}}}}}},"example":{"order":{"crm_item_id":1,"title":"Sample title","amount":149.9,"currency":"BRL","status":"pending","ordered_at":"2026-01-15T10:30:00.000Z","paid_at":"2026-01-15T10:30:00.000Z","affiliate_id":1,"financial_transition_reason":"sample financial transition reason","line_items":[{"id":1,"source_item_id":"sample source item id","external_id":"sample external id","catalog_product_id":1,"catalog_variant_id":1,"name_snapshot":"sample name snapshot","name":"Sample Name","quantity":12.5,"unit_price":149.9,"price":149.9,"discount":12.5,"discount_type":"fixed","currency":"BRL","position":1,"metadata":{}}]}}}}}},"put":{"tags":["CRM"],"operationId":"auto_put_api_v1_accounts_account_id_crm_orders_id","summary":"Correct a manual CRM order","description":"Updates an operator-entered manual order through the governed registration seam. A payment or commerce projection accepts only audited affiliate re-attribution; all other changes must happen on the source charge/event and synchronize into the registry. Contact reassignment uses the sale graph repair flow. Gateway/external identity is immutable, status cannot regress, and financial facts (amount, currency, paid_at, line items and deal attribution) cannot change after financial side effects exist; use the sales-graph repair flow for association corrections. Entering a financial status or changing affiliate credit requires administrator/sales_manage and financial_transition_reason; the before/after receipt is retained on the order.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Updated manual CRM order.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/crm_order"},"example":{"id":1,"account_id":1,"contact_id":1,"contact_name":"sample contact name","contact_email":"agent@example.com","contact_phone_number":"+5511999998888","organization_id":1,"organization_name":"sample organization name","crm_item_id":1,"crm_item_title":"sample crm item title","payments_charge_id":1,"source_connection_id":1,"owner_id":1,"owner_name":"sample owner name","voided_at":"2026-01-15T10:30:00.000Z","voided_by_id":1,"void_reason":"sample void reason","void_kind":"test_data","affiliate_id":1,"affiliate_name":"sample affiliate name","gateway":"sample gateway","external_id":"sample external id","title":"Sample title","amount":149.9,"amount_refunded":12.5,"recognized_amount":149.9,"currency":"BRL","status":"pending","source":"manual","ordered_at":"2026-01-15T10:30:00.000Z","paid_at":"2026-01-15T10:30:00.000Z","metadata":{},"line_items":[{"id":1,"source_item_id":"sample source item id","catalog_product_id":1,"catalog_variant_id":1,"name_snapshot":"sample name snapshot","quantity":12.5,"unit_price":149.9,"discount":12.5,"discount_type":"fixed","line_total":149.9,"currency":"BRL","position":1,"metadata":{}}],"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"422":{"description":"External order, identity or settled financial facts are immutable; a financial reason is missing; contact repair used the wrong flow; or a submitted status/association is invalid."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["order"],"properties":{"order":{"type":"object","properties":{"crm_item_id":{"type":["integer","null"],"minimum":1},"title":{"type":["string","null"]},"amount":{"type":"number","minimum":0},"currency":{"type":"string","example":"BRL"},"status":{"type":"string","enum":["pending","paid","partially_paid","overdue","refunded","canceled","failed"],"description":"The recorded payment status of the order."},"ordered_at":{"type":["string","null"],"format":"date-time"},"paid_at":{"type":["string","null"],"format":"date-time"},"affiliate_id":{"type":["integer","null"],"minimum":1},"financial_transition_reason":{"type":"string","maxLength":1000,"description":"Required when status enters a financial state or affiliate credit changes."},"line_items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","minimum":1},"source_item_id":{"type":"string"},"external_id":{"type":"string"},"catalog_product_id":{"type":["integer","null"],"minimum":1},"catalog_variant_id":{"type":["integer","null"],"minimum":1},"name_snapshot":{"type":["string","null"]},"name":{"type":["string","null"]},"quantity":{"type":"number","exclusiveMinimum":0},"unit_price":{"type":"number","minimum":0},"price":{"type":"number","minimum":0},"discount":{"type":"number","minimum":0},"discount_type":{"type":"string","enum":["fixed","percent"],"description":"Whether the discount is an absolute amount or a percentage."},"currency":{"type":"string","example":"BRL"},"position":{"type":"integer","minimum":0},"metadata":{"type":"object","additionalProperties":true,"description":"Free-form metadata bag; the key set depends on the record and context."}}}}}}}},"example":{"order":{"crm_item_id":1,"title":"Sample title","amount":149.9,"currency":"BRL","status":"pending","ordered_at":"2026-01-15T10:30:00.000Z","paid_at":"2026-01-15T10:30:00.000Z","affiliate_id":1,"financial_transition_reason":"sample financial transition reason","line_items":[{"id":1,"source_item_id":"sample source item id","external_id":"sample external id","catalog_product_id":1,"catalog_variant_id":1,"name_snapshot":"sample name snapshot","name":"Sample Name","quantity":12.5,"unit_price":149.9,"price":149.9,"discount":12.5,"discount_type":"fixed","currency":"BRL","position":1,"metadata":{}}]}}}}}},"delete":{"tags":["CRM"],"operationId":"auto_delete_api_v1_accounts_account_id_crm_orders_id","summary":"Remove or void an order","description":"Deletes the order identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Safe manual typo deleted, or order voided and removed from operational views."},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"422":{"description":"Missing reason, closed commission statement, invalid kind, or another non-reversible invariant.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"order_void_closed_commission"}}},"example":{"error":"order_void_closed_commission"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","maxLength":1000,"description":"Required when the order is financial or integration-sourced."},"kind":{"type":"string","enum":["test_data","duplicate","source_purged","operator_error","legacy_orphan","other"],"default":"operator_error"}}},"example":{"reason":"Test generated during the platform setup.","kind":"test_data"}}}}}},"/api/v1/accounts/{account_id}/engagement/point_groups":{"get":{"tags":["Engagement"],"operationId":"auto_get_api_v1_accounts_account_id_engagement_point_groups","summary":"List point groups","description":"Returns the list of point groups visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"key":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"color":{"type":"string"},"icon":{"type":"string"},"position":{"type":"integer"},"bands":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}}},"example":{"payload":[{"id":1,"account_id":1,"key":"sample key","name":"Sample Name","description":"A short description.","color":"#1F93FF","icon":"sample icon","position":1,"bands":"sample bands","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."}]},"post":{"tags":["Engagement"],"operationId":"auto_post_api_v1_accounts_account_id_engagement_point_groups","summary":"Create point groups","description":"Creates a new point group from the request payload. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"201":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"key":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"color":{"type":"string"},"icon":{"type":"string"},"position":{"type":"integer"},"bands":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"example":{"id":1,"account_id":1,"key":"sample key","name":"Sample Name","description":"A short description.","color":"#1F93FF","icon":"sample icon","position":1,"bands":"sample bands","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"point_group":{"type":"object","properties":{"key":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"color":{"type":"string"},"icon":{"type":"string"},"position":{"type":"integer"},"bands":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Free-form object."}}},"required":["key","name"]}},"required":["point_group"]},"example":{"point_group":{"key":"sample key","name":"Sample Name","description":"A short description.","color":"#1F93FF","icon":"sample icon","position":1,"bands":[{}]}}}}}}},"/api/v1/accounts/{account_id}/engagement/point_groups/{id}":{"get":{"tags":["Engagement"],"operationId":"auto_get_api_v1_accounts_account_id_engagement_point_groups_id","summary":"Get point groups","description":"Returns the point group identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"key":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"color":{"type":"string"},"icon":{"type":"string"},"position":{"type":"integer"},"bands":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"example":{"id":1,"account_id":1,"key":"sample key","name":"Sample Name","description":"A short description.","color":"#1F93FF","icon":"sample icon","position":1,"bands":"sample bands","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]},"patch":{"tags":["Engagement"],"operationId":"auto_patch_api_v1_accounts_account_id_engagement_point_groups_id","summary":"Update point groups","description":"Updates the point group identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"key":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"color":{"type":"string"},"icon":{"type":"string"},"position":{"type":"integer"},"bands":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"example":{"id":1,"account_id":1,"key":"sample key","name":"Sample Name","description":"A short description.","color":"#1F93FF","icon":"sample icon","position":1,"bands":"sample bands","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"point_group":{"type":"object","properties":{"key":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"color":{"type":"string"},"icon":{"type":"string"},"position":{"type":"integer"},"bands":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Free-form object."}}}}},"required":["point_group"]},"example":{"point_group":{"key":"sample key","name":"Sample Name","description":"A short description.","color":"#1F93FF","icon":"sample icon","position":1,"bands":[{}]}}}}}},"put":{"tags":["Engagement"],"operationId":"auto_put_api_v1_accounts_account_id_engagement_point_groups_id","summary":"Update point groups","description":"Updates the point group identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"key":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"color":{"type":"string"},"icon":{"type":"string"},"position":{"type":"integer"},"bands":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"example":{"id":1,"account_id":1,"key":"sample key","name":"Sample Name","description":"A short description.","color":"#1F93FF","icon":"sample icon","position":1,"bands":"sample bands","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"point_group":{"type":"object","properties":{"key":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"color":{"type":"string"},"icon":{"type":"string"},"position":{"type":"integer"},"bands":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Free-form object."}}}}},"required":["point_group"]},"example":{"point_group":{"key":"sample key","name":"Sample Name","description":"A short description.","color":"#1F93FF","icon":"sample icon","position":1,"bands":[{}]}}}}}},"delete":{"tags":["Engagement"],"operationId":"auto_delete_api_v1_accounts_account_id_engagement_point_groups_id","summary":"Delete point groups","description":"Deletes the point group identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Success (no content)"},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/engagement/event_definitions":{"get":{"tags":["Engagement"],"operationId":"auto_get_api_v1_accounts_account_id_engagement_event_definitions","summary":"List event definitions","description":"Returns the list of event definitions visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"point_group_id":{"type":"integer"},"key":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"default_points":{"type":"string"},"source":{"type":"string","enum":["native","api","automation","manual"]},"dedup_policy":{"type":"string","enum":["every","once_per_contact","cooldown"]},"cooldown_seconds":{"type":"integer"},"category":{"type":"string"},"icon":{"type":"string"},"active":{"type":"boolean"},"trigger_filter":{"type":"string"},"stage_trigger":{"type":"boolean"},"wired":{"type":"boolean"},"coverage_gap":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}}},"example":{"payload":[{"id":1,"account_id":1,"point_group_id":1,"key":"sample key","name":"Sample Name","description":"A short description.","default_points":"sample default points","source":"native","dedup_policy":"every","cooldown_seconds":60,"category":"sample category","icon":"sample icon","active":true,"trigger_filter":"sample trigger filter","stage_trigger":true,"wired":true,"coverage_gap":true,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"active","in":"query","required":false,"description":"A truthy value returns only active definitions; anything else returns all of them.","schema":{"type":"boolean"},"example":true}]},"post":{"tags":["Engagement"],"operationId":"auto_post_api_v1_accounts_account_id_engagement_event_definitions","summary":"Create event definitions","description":"Creates a new event definition from the request payload. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"201":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"point_group_id":{"type":"integer"},"key":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"default_points":{"type":"string"},"source":{"type":"string","enum":["native","api","automation","manual"]},"dedup_policy":{"type":"string","enum":["every","once_per_contact","cooldown"]},"cooldown_seconds":{"type":"integer"},"category":{"type":"string"},"icon":{"type":"string"},"active":{"type":"boolean"},"trigger_filter":{"type":"string"},"stage_trigger":{"type":"boolean"},"wired":{"type":"boolean"},"coverage_gap":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"example":{"id":1,"account_id":1,"point_group_id":1,"key":"sample key","name":"Sample Name","description":"A short description.","default_points":"sample default points","source":"native","dedup_policy":"every","cooldown_seconds":60,"category":"sample category","icon":"sample icon","active":true,"trigger_filter":"sample trigger filter","stage_trigger":true,"wired":true,"coverage_gap":true,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"event_definition":{"type":"object","properties":{"key":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"point_group_id":{"type":"integer"},"default_points":{"type":"string"},"source":{"type":"string","enum":["native","api","automation","manual"]},"dedup_policy":{"type":"string","enum":["every","once_per_contact","cooldown"]},"cooldown_seconds":{"type":"integer"},"category":{"type":"string","enum":["MARKETING","UTILITY","AUTHENTICATION"]},"icon":{"type":"string"},"active":{"type":"boolean"},"trigger_filter":{"type":"object","additionalProperties":true,"description":"Free-form object."}},"required":["key","name"]}},"required":["event_definition"]},"example":{"event_definition":{"key":"sample key","name":"Sample Name","description":"A short description.","point_group_id":1,"default_points":"sample default points","source":"native","dedup_policy":"every","cooldown_seconds":60,"category":"MARKETING","icon":"sample icon","active":true,"trigger_filter":{}}}}}}}},"/api/v1/accounts/{account_id}/engagement/event_definitions/{id}":{"get":{"tags":["Engagement"],"operationId":"auto_get_api_v1_accounts_account_id_engagement_event_definitions_id","summary":"Get event definitions","description":"Returns the event definition identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"point_group_id":{"type":"integer"},"key":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"default_points":{"type":"string"},"source":{"type":"string","enum":["native","api","automation","manual"]},"dedup_policy":{"type":"string","enum":["every","once_per_contact","cooldown"]},"cooldown_seconds":{"type":"integer"},"category":{"type":"string"},"icon":{"type":"string"},"active":{"type":"boolean"},"trigger_filter":{"type":"string"},"stage_trigger":{"type":"boolean"},"wired":{"type":"boolean"},"coverage_gap":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"example":{"id":1,"account_id":1,"point_group_id":1,"key":"sample key","name":"Sample Name","description":"A short description.","default_points":"sample default points","source":"native","dedup_policy":"every","cooldown_seconds":60,"category":"sample category","icon":"sample icon","active":true,"trigger_filter":"sample trigger filter","stage_trigger":true,"wired":true,"coverage_gap":true,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]},"patch":{"tags":["Engagement"],"operationId":"auto_patch_api_v1_accounts_account_id_engagement_event_definitions_id","summary":"Update event definitions","description":"Updates the event definition identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"point_group_id":{"type":"integer"},"key":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"default_points":{"type":"string"},"source":{"type":"string","enum":["native","api","automation","manual"]},"dedup_policy":{"type":"string","enum":["every","once_per_contact","cooldown"]},"cooldown_seconds":{"type":"integer"},"category":{"type":"string"},"icon":{"type":"string"},"active":{"type":"boolean"},"trigger_filter":{"type":"string"},"stage_trigger":{"type":"boolean"},"wired":{"type":"boolean"},"coverage_gap":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"example":{"id":1,"account_id":1,"point_group_id":1,"key":"sample key","name":"Sample Name","description":"A short description.","default_points":"sample default points","source":"native","dedup_policy":"every","cooldown_seconds":60,"category":"sample category","icon":"sample icon","active":true,"trigger_filter":"sample trigger filter","stage_trigger":true,"wired":true,"coverage_gap":true,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"event_definition":{"type":"object","properties":{"key":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"point_group_id":{"type":"integer"},"default_points":{"type":"string"},"source":{"type":"string","enum":["native","api","automation","manual"]},"dedup_policy":{"type":"string","enum":["every","once_per_contact","cooldown"]},"cooldown_seconds":{"type":"integer"},"category":{"type":"string","enum":["MARKETING","UTILITY","AUTHENTICATION"]},"icon":{"type":"string"},"active":{"type":"boolean"},"trigger_filter":{"type":"object","additionalProperties":true,"description":"Free-form object."}}}},"required":["event_definition"]},"example":{"event_definition":{"key":"sample key","name":"Sample Name","description":"A short description.","point_group_id":1,"default_points":"sample default points","source":"native","dedup_policy":"every","cooldown_seconds":60,"category":"MARKETING","icon":"sample icon","active":true,"trigger_filter":{}}}}}}},"put":{"tags":["Engagement"],"operationId":"auto_put_api_v1_accounts_account_id_engagement_event_definitions_id","summary":"Update event definitions","description":"Updates the event definition identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"point_group_id":{"type":"integer"},"key":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"default_points":{"type":"string"},"source":{"type":"string","enum":["native","api","automation","manual"]},"dedup_policy":{"type":"string","enum":["every","once_per_contact","cooldown"]},"cooldown_seconds":{"type":"integer"},"category":{"type":"string"},"icon":{"type":"string"},"active":{"type":"boolean"},"trigger_filter":{"type":"string"},"stage_trigger":{"type":"boolean"},"wired":{"type":"boolean"},"coverage_gap":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"example":{"id":1,"account_id":1,"point_group_id":1,"key":"sample key","name":"Sample Name","description":"A short description.","default_points":"sample default points","source":"native","dedup_policy":"every","cooldown_seconds":60,"category":"sample category","icon":"sample icon","active":true,"trigger_filter":"sample trigger filter","stage_trigger":true,"wired":true,"coverage_gap":true,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"event_definition":{"type":"object","properties":{"key":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"point_group_id":{"type":"integer"},"default_points":{"type":"string"},"source":{"type":"string","enum":["native","api","automation","manual"]},"dedup_policy":{"type":"string","enum":["every","once_per_contact","cooldown"]},"cooldown_seconds":{"type":"integer"},"category":{"type":"string","enum":["MARKETING","UTILITY","AUTHENTICATION"]},"icon":{"type":"string"},"active":{"type":"boolean"},"trigger_filter":{"type":"object","additionalProperties":true,"description":"Free-form object."}}}},"required":["event_definition"]},"example":{"event_definition":{"key":"sample key","name":"Sample Name","description":"A short description.","point_group_id":1,"default_points":"sample default points","source":"native","dedup_policy":"every","cooldown_seconds":60,"category":"MARKETING","icon":"sample icon","active":true,"trigger_filter":{}}}}}}},"delete":{"tags":["Engagement"],"operationId":"auto_delete_api_v1_accounts_account_id_engagement_event_definitions_id","summary":"Delete event definitions","description":"Deletes the event definition identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Success (no content)"},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/engagement/events":{"get":{"tags":["Engagement"],"operationId":"auto_get_api_v1_accounts_account_id_engagement_events","summary":"List events","description":"Returns the list of events visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"contact_id":{"type":"integer"},"event_definition_id":{"type":"integer"},"event_name":{"type":"string"},"event_definition_name":{"type":["string","null"],"description":"Current display name of the event's catalog definition; null when the event has no definition."},"points":{"type":"string"},"point_group_id":{"type":"integer"},"actor_type":{"type":"string","enum":["user","automation","api","system"]},"actor_id":{"type":"integer"},"source_type":{"type":"string"},"source_id":{"type":"integer"},"channel":{"type":"string"},"occurred_at":{"type":"string","format":"date-time"},"metadata":{"type":"object","additionalProperties":true,"description":"Free-form metadata bag; the key set depends on the record and context."}}}},"meta":{"type":"object","properties":{"count":{"type":"integer"},"current_page":{"type":"string"}}}}},"example":{"payload":[{"id":1,"account_id":1,"contact_id":1,"event_definition_id":1,"event_name":"sample event name","event_definition_name":"sample event definition name","points":"sample points","point_group_id":1,"actor_type":"user","actor_id":1,"source_type":"sample source type","source_id":1,"channel":"sample channel","occurred_at":"2026-01-15T10:30:00.000Z","metadata":{}}],"meta":{"count":5,"current_page":"sample current page"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"contact_id","in":"query","required":false,"description":"Restrict to one contact. An id outside the account returns 404.","schema":{"type":"integer"},"example":331},{"name":"event_name","in":"query","required":false,"description":"Restrict to one event name, as declared in the event definitions.","schema":{"type":"string"},"example":"checkout_started"}]}},"/api/v1/accounts/{account_id}/engagement/scores":{"get":{"tags":["Engagement"],"operationId":"auto_get_api_v1_accounts_account_id_engagement_scores","summary":"List scores","description":"Returns the list of scores visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"contact_id":{"type":"integer"},"point_group_id":{"type":"integer"},"score":{"type":"string"},"last_event_at":{"type":"string","format":"date-time"},"group_key":{"type":"string"},"group_name":{"type":"string"},"band":{"type":"string"}}}}}},"example":{"payload":[{"id":1,"contact_id":1,"point_group_id":1,"score":"sample score","last_event_at":"2026-01-15T10:30:00.000Z","group_key":"sample-token","group_name":"sample group name","band":"sample band"}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"contact_id","in":"query","required":true,"description":"Contact whose score breakdown is returned. An id outside the account returns 404.","schema":{"type":"integer"},"example":331}]}},"/api/v1/accounts/{account_id}/engagement/templates":{"get":{"tags":["Engagement"],"operationId":"auto_get_api_v1_accounts_account_id_engagement_templates","summary":"List templates","description":"Returns the list of templates visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"string"}}},"example":{"data":"sample data"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."}]},"post":{"tags":["Engagement"],"operationId":"auto_post_api_v1_accounts_account_id_engagement_templates","summary":"Create templates","description":"Creates a new template from the request payload. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"201":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"string"}}},"example":{"data":"sample data"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"niche":{"type":"string"}}},"example":{"niche":"sample niche"}}}}}},"/api/v1/accounts/{account_id}/engagement/native_triggers":{"get":{"tags":["Engagement"],"operationId":"auto_get_api_v1_accounts_account_id_engagement_native_triggers","summary":"List native triggers","description":"Returns the list of native triggers visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"string"}}},"example":{"data":"sample data"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."}]}},"/api/v1/accounts/{account_id}/engagement/settings/rotate_track_token":{"post":{"tags":["Engagement"],"operationId":"auto_post_api_v1_accounts_account_id_engagement_settings_rotate_track_token","summary":"Rotate track token settings","description":"Performs the rotate track token operation on the targeted setting resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"track_token":{"type":"string"},"retention_days":{"type":"integer"},"track_url":{"type":"string"}}},"example":{"id":1,"account_id":1,"track_token":"sample-token","retention_days":7,"track_url":"https://example.com/resource"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/engagement/settings":{"get":{"tags":["Engagement"],"operationId":"auto_get_api_v1_accounts_account_id_engagement_settings","summary":"Get settings","description":"Returns the setting identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"track_token":{"type":"string"},"retention_days":{"type":"integer"},"track_url":{"type":"string"}}},"example":{"id":1,"account_id":1,"track_token":"sample-token","retention_days":7,"track_url":"https://example.com/resource"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]},"patch":{"tags":["Engagement"],"operationId":"auto_patch_api_v1_accounts_account_id_engagement_settings","summary":"Update settings","description":"Updates the setting identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"track_token":{"type":"string"},"retention_days":{"type":"integer"},"track_url":{"type":"string"}}},"example":{"id":1,"account_id":1,"track_token":"sample-token","retention_days":7,"track_url":"https://example.com/resource"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"settings":{"type":"object","description":"Merged into the engagement_settings row (Engagement::Setting).","properties":{"track_token":{"type":"string","description":"Public pixel/tracker token (usually rotated via the dedicated endpoint).","example":"9f2c1a7b3e5d4c6a8b0f2e1d9c7a5b3e"},"retention_days":{"type":["integer","null"],"description":"Event retention window; null = keep indefinitely.","example":180}}}}},"example":{"settings":{"track_token":"9f2c1a7b3e5d4c6a8b0f2e1d9c7a5b3e","retention_days":180}}}}}},"put":{"tags":["Engagement"],"operationId":"auto_put_api_v1_accounts_account_id_engagement_settings","summary":"Update settings","description":"Updates the setting identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"track_token":{"type":"string"},"retention_days":{"type":"integer"},"track_url":{"type":"string"}}},"example":{"id":1,"account_id":1,"track_token":"sample-token","retention_days":7,"track_url":"https://example.com/resource"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"settings":{"type":"object","description":"Merged into the engagement_settings row (Engagement::Setting).","properties":{"track_token":{"type":"string","description":"Public pixel/tracker token (usually rotated via the dedicated endpoint).","example":"9f2c1a7b3e5d4c6a8b0f2e1d9c7a5b3e"},"retention_days":{"type":["integer","null"],"description":"Event retention window; null = keep indefinitely.","example":180}}}}},"example":{"settings":{"track_token":"9f2c1a7b3e5d4c6a8b0f2e1d9c7a5b3e","retention_days":180}}}}}}},"/api/v1/accounts/{account_id}/wfm/status_types/reorder":{"patch":{"tags":["Team Management"],"operationId":"auto_patch_api_v1_accounts_account_id_wfm_status_types_reorder","summary":"Reorder status types","description":"Performs the reorder operation on the targeted status type resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"key":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"position":{"type":"integer"},"active":{"type":"boolean"},"family":{"type":"string","enum":["presence","timed_break","open_break"]},"base_availability":{"type":"string","enum":["online","offline","busy"]},"color":{"type":"string"},"icon":{"type":"string"},"time_limit_seconds":{"type":"integer"},"is_system":{"type":"boolean"},"counts_as_productive":{"type":"integer"},"counts_against_adherence":{"type":"integer"},"requires_reason":{"type":"string"},"over_limit_policy":{"type":"string"},"fullscreen":{"type":"string"},"show_widget":{"type":"string"},"allowed_for":{"type":"string"}}}}}},"example":{"payload":[{"id":1,"key":"sample key","name":"Sample Name","description":"A short description.","position":1,"active":true,"family":"presence","base_availability":"online","color":"#1F93FF","icon":"sample icon","time_limit_seconds":60,"is_system":true,"counts_as_productive":1,"counts_against_adherence":1,"requires_reason":"sample requires reason","over_limit_policy":"sample over limit policy","fullscreen":"sample fullscreen","show_widget":"sample show widget","allowed_for":"sample allowed for"}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"ids":{"type":"array","items":{"type":"string"}}}},"example":{"ids":["sample id"]}}}}}},"/api/v1/accounts/{account_id}/wfm/status_types":{"get":{"tags":["Team Management"],"operationId":"auto_get_api_v1_accounts_account_id_wfm_status_types","summary":"List status types","description":"Returns the list of status types visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"key":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"position":{"type":"integer"},"active":{"type":"boolean"},"family":{"type":"string","enum":["presence","timed_break","open_break"]},"base_availability":{"type":"string","enum":["online","offline","busy"]},"color":{"type":"string"},"icon":{"type":"string"},"time_limit_seconds":{"type":"integer"},"is_system":{"type":"boolean"},"counts_as_productive":{"type":"integer"},"counts_against_adherence":{"type":"integer"},"requires_reason":{"type":"string"},"over_limit_policy":{"type":"string"},"fullscreen":{"type":"string"},"show_widget":{"type":"string"},"allowed_for":{"type":"string"}}}}}},"example":{"payload":[{"id":1,"key":"sample key","name":"Sample Name","description":"A short description.","position":1,"active":true,"family":"presence","base_availability":"online","color":"#1F93FF","icon":"sample icon","time_limit_seconds":60,"is_system":true,"counts_as_productive":1,"counts_against_adherence":1,"requires_reason":"sample requires reason","over_limit_policy":"sample over limit policy","fullscreen":"sample fullscreen","show_widget":"sample show widget","allowed_for":"sample allowed for"}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."}]},"post":{"tags":["Team Management"],"operationId":"auto_post_api_v1_accounts_account_id_wfm_status_types","summary":"Create status types","description":"Creates a new status type from the request payload. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"201":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"key":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"position":{"type":"integer"},"active":{"type":"boolean"},"family":{"type":"string","enum":["presence","timed_break","open_break"]},"base_availability":{"type":"string","enum":["online","offline","busy"]},"color":{"type":"string"},"icon":{"type":"string"},"time_limit_seconds":{"type":"integer"},"is_system":{"type":"boolean"},"counts_as_productive":{"type":"integer"},"counts_against_adherence":{"type":"integer"},"requires_reason":{"type":"string"},"over_limit_policy":{"type":"string"},"fullscreen":{"type":"string"},"show_widget":{"type":"string"},"allowed_for":{"type":"string"}}},"example":{"id":1,"key":"sample key","name":"Sample Name","description":"A short description.","position":1,"active":true,"family":"presence","base_availability":"online","color":"#1F93FF","icon":"sample icon","time_limit_seconds":60,"is_system":true,"counts_as_productive":1,"counts_against_adherence":1,"requires_reason":"sample requires reason","over_limit_policy":"sample over limit policy","fullscreen":"sample fullscreen","show_widget":"sample show widget","allowed_for":"sample allowed for"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"status_type":{"type":"object","properties":{"key":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"position":{"type":"integer"},"active":{"type":"boolean"},"family":{"type":"string","enum":["presence","timed_break","open_break"]},"base_availability":{"type":"string","enum":["online","offline","busy"]},"color":{"type":"string"},"icon":{"type":"string"},"time_limit_seconds":{"type":"integer"},"counts_as_productive":{"type":"string"},"counts_against_adherence":{"type":"string"},"requires_reason":{"type":"string"},"fullscreen":{"type":"string"},"show_widget":{"type":"string"},"over_limit_policy":{"type":"object","additionalProperties":true,"description":"Free-form object."},"allowed_for":{"type":"object","additionalProperties":true,"description":"Free-form object."}},"required":["key","name"]}},"required":["status_type"]},"example":{"status_type":{"key":"sample key","name":"Sample Name","description":"A short description.","position":1,"active":true,"family":"presence","base_availability":"online","color":"#1F93FF","icon":"sample icon","time_limit_seconds":60,"counts_as_productive":"sample counts as productive","counts_against_adherence":"sample counts against adherence","requires_reason":"sample requires reason","fullscreen":"sample fullscreen","show_widget":"sample show widget","over_limit_policy":{},"allowed_for":{}}}}}}}},"/api/v1/accounts/{account_id}/wfm/status_types/{id}":{"get":{"tags":["Team Management"],"operationId":"auto_get_api_v1_accounts_account_id_wfm_status_types_id","summary":"Get status types","description":"Returns the status type identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"key":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"position":{"type":"integer"},"active":{"type":"boolean"},"family":{"type":"string","enum":["presence","timed_break","open_break"]},"base_availability":{"type":"string","enum":["online","offline","busy"]},"color":{"type":"string"},"icon":{"type":"string"},"time_limit_seconds":{"type":"integer"},"is_system":{"type":"boolean"},"counts_as_productive":{"type":"integer"},"counts_against_adherence":{"type":"integer"},"requires_reason":{"type":"string"},"over_limit_policy":{"type":"string"},"fullscreen":{"type":"string"},"show_widget":{"type":"string"},"allowed_for":{"type":"string"}}},"example":{"id":1,"key":"sample key","name":"Sample Name","description":"A short description.","position":1,"active":true,"family":"presence","base_availability":"online","color":"#1F93FF","icon":"sample icon","time_limit_seconds":60,"is_system":true,"counts_as_productive":1,"counts_against_adherence":1,"requires_reason":"sample requires reason","over_limit_policy":"sample over limit policy","fullscreen":"sample fullscreen","show_widget":"sample show widget","allowed_for":"sample allowed for"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]},"patch":{"tags":["Team Management"],"operationId":"auto_patch_api_v1_accounts_account_id_wfm_status_types_id","summary":"Update status types","description":"Updates the status type identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"key":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"position":{"type":"integer"},"active":{"type":"boolean"},"family":{"type":"string","enum":["presence","timed_break","open_break"]},"base_availability":{"type":"string","enum":["online","offline","busy"]},"color":{"type":"string"},"icon":{"type":"string"},"time_limit_seconds":{"type":"integer"},"is_system":{"type":"boolean"},"counts_as_productive":{"type":"integer"},"counts_against_adherence":{"type":"integer"},"requires_reason":{"type":"string"},"over_limit_policy":{"type":"string"},"fullscreen":{"type":"string"},"show_widget":{"type":"string"},"allowed_for":{"type":"string"}}},"example":{"id":1,"key":"sample key","name":"Sample Name","description":"A short description.","position":1,"active":true,"family":"presence","base_availability":"online","color":"#1F93FF","icon":"sample icon","time_limit_seconds":60,"is_system":true,"counts_as_productive":1,"counts_against_adherence":1,"requires_reason":"sample requires reason","over_limit_policy":"sample over limit policy","fullscreen":"sample fullscreen","show_widget":"sample show widget","allowed_for":"sample allowed for"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"status_type":{"type":"object","properties":{"key":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"position":{"type":"integer"},"active":{"type":"boolean"},"family":{"type":"string","enum":["presence","timed_break","open_break"]},"base_availability":{"type":"string","enum":["online","offline","busy"]},"color":{"type":"string"},"icon":{"type":"string"},"time_limit_seconds":{"type":"integer"},"counts_as_productive":{"type":"string"},"counts_against_adherence":{"type":"string"},"requires_reason":{"type":"string"},"fullscreen":{"type":"string"},"show_widget":{"type":"string"},"over_limit_policy":{"type":"object","additionalProperties":true,"description":"Free-form object."},"allowed_for":{"type":"object","additionalProperties":true,"description":"Free-form object."}}}},"required":["status_type"]},"example":{"status_type":{"key":"sample key","name":"Sample Name","description":"A short description.","position":1,"active":true,"family":"presence","base_availability":"online","color":"#1F93FF","icon":"sample icon","time_limit_seconds":60,"counts_as_productive":"sample counts as productive","counts_against_adherence":"sample counts against adherence","requires_reason":"sample requires reason","fullscreen":"sample fullscreen","show_widget":"sample show widget","over_limit_policy":{},"allowed_for":{}}}}}}},"put":{"tags":["Team Management"],"operationId":"auto_put_api_v1_accounts_account_id_wfm_status_types_id","summary":"Update status types","description":"Updates the status type identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"key":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"position":{"type":"integer"},"active":{"type":"boolean"},"family":{"type":"string","enum":["presence","timed_break","open_break"]},"base_availability":{"type":"string","enum":["online","offline","busy"]},"color":{"type":"string"},"icon":{"type":"string"},"time_limit_seconds":{"type":"integer"},"is_system":{"type":"boolean"},"counts_as_productive":{"type":"integer"},"counts_against_adherence":{"type":"integer"},"requires_reason":{"type":"string"},"over_limit_policy":{"type":"string"},"fullscreen":{"type":"string"},"show_widget":{"type":"string"},"allowed_for":{"type":"string"}}},"example":{"id":1,"key":"sample key","name":"Sample Name","description":"A short description.","position":1,"active":true,"family":"presence","base_availability":"online","color":"#1F93FF","icon":"sample icon","time_limit_seconds":60,"is_system":true,"counts_as_productive":1,"counts_against_adherence":1,"requires_reason":"sample requires reason","over_limit_policy":"sample over limit policy","fullscreen":"sample fullscreen","show_widget":"sample show widget","allowed_for":"sample allowed for"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"status_type":{"type":"object","properties":{"key":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"position":{"type":"integer"},"active":{"type":"boolean"},"family":{"type":"string","enum":["presence","timed_break","open_break"]},"base_availability":{"type":"string","enum":["online","offline","busy"]},"color":{"type":"string"},"icon":{"type":"string"},"time_limit_seconds":{"type":"integer"},"counts_as_productive":{"type":"string"},"counts_against_adherence":{"type":"string"},"requires_reason":{"type":"string"},"fullscreen":{"type":"string"},"show_widget":{"type":"string"},"over_limit_policy":{"type":"object","additionalProperties":true,"description":"Free-form object."},"allowed_for":{"type":"object","additionalProperties":true,"description":"Free-form object."}}}},"required":["status_type"]},"example":{"status_type":{"key":"sample key","name":"Sample Name","description":"A short description.","position":1,"active":true,"family":"presence","base_availability":"online","color":"#1F93FF","icon":"sample icon","time_limit_seconds":60,"counts_as_productive":"sample counts as productive","counts_against_adherence":"sample counts against adherence","requires_reason":"sample requires reason","fullscreen":"sample fullscreen","show_widget":"sample show widget","over_limit_policy":{},"allowed_for":{}}}}}}},"delete":{"tags":["Team Management"],"operationId":"auto_delete_api_v1_accounts_account_id_wfm_status_types_id","summary":"Delete status types","description":"Deletes the status type identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Success (no content)"},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/wfm/templates":{"get":{"tags":["Team Management"],"operationId":"auto_get_api_v1_accounts_account_id_wfm_templates","summary":"List templates","description":"Returns the list of templates visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"string"}}},"example":{"data":"sample data"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."}]},"post":{"tags":["Team Management"],"operationId":"auto_post_api_v1_accounts_account_id_wfm_templates","summary":"Create templates","description":"Creates a new template from the request payload. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"201":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"string"}}},"example":{"data":"sample data"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"niche":{"type":"string"}}},"example":{"niche":"sample niche"}}}}}},"/api/v1/accounts/{account_id}/wfm/agent_status":{"get":{"tags":["Team Management"],"operationId":"auto_get_api_v1_accounts_account_id_wfm_agent_status","summary":"Get agent status","description":"Returns the agent statu identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"current":{"type":"string"},"status_types":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"key":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"position":{"type":"integer"},"active":{"type":"boolean"},"family":{"type":"string","enum":["presence","timed_break","open_break"]},"base_availability":{"type":"string","enum":["online","offline","busy"]},"color":{"type":"string"},"icon":{"type":"string"},"time_limit_seconds":{"type":"integer"},"is_system":{"type":"boolean"},"counts_as_productive":{"type":"integer"},"counts_against_adherence":{"type":"integer"},"requires_reason":{"type":"string"},"over_limit_policy":{"type":"string"},"fullscreen":{"type":"string"},"show_widget":{"type":"string"},"allowed_for":{"type":"string"}}}}}},"example":{"current":"sample current","status_types":[{"id":1,"key":"sample key","name":"Sample Name","description":"A short description.","position":1,"active":true,"family":"presence","base_availability":"online","color":"#1F93FF","icon":"sample icon","time_limit_seconds":60,"is_system":true,"counts_as_productive":1,"counts_against_adherence":1,"requires_reason":"sample requires reason","over_limit_policy":"sample over limit policy","fullscreen":"sample fullscreen","show_widget":"sample show widget","allowed_for":"sample allowed for"}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]},"patch":{"tags":["Team Management"],"operationId":"auto_patch_api_v1_accounts_account_id_wfm_agent_status","summary":"Set the agent's own Team Management status","description":"Changes the acting agent's Team Management status via Wfm::StatusChangeService (a reason_note is required when the target status demands one) and returns the new open status event plus the full active status catalog. Unknown status -\u003e 422 unknown_status; missing reason -\u003e 422 reason_required.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The new open status event + the active status catalog.","content":{"application/json":{"schema":{"type":"object","properties":{"current":{"type":["object","null"],"properties":{"id":{"type":"integer","example":991},"status_key":{"type":"string","example":"on_break"},"status_name":{"type":"string","example":"On break"},"base_availability":{"type":"string","example":"busy"},"family":{"type":"string","example":"break"},"started_at":{"type":"string","format":"date-time","example":"2026-01-15T10:30:00.000Z"},"started_at_epoch":{"type":"integer","example":1737023400},"expected_seconds":{"type":["integer","null"],"example":1800},"within_limit":{"type":"boolean","example":true},"duration_seconds":{"type":"integer","example":0},"reason_note":{"type":["string","null"],"example":"Lunch"},"color":{"type":["string","null"],"example":"#F59E0B"},"icon":{"type":["string","null"],"example":"coffee"},"fullscreen":{"type":["boolean","null"],"example":false},"show_widget":{"type":["boolean","null"],"example":true}}},"status_types":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","example":4},"key":{"type":"string","example":"on_break"},"name":{"type":"string","example":"On break"},"description":{"type":["string","null"],"example":null},"position":{"type":"integer","example":2},"active":{"type":"boolean","example":true},"family":{"type":"string","example":"break"},"base_availability":{"type":"string","example":"busy"},"color":{"type":["string","null"],"example":"#F59E0B"},"icon":{"type":["string","null"],"example":"coffee"},"time_limit_seconds":{"type":["integer","null"],"example":1800},"is_system":{"type":"boolean","example":true},"counts_as_productive":{"type":"boolean","example":false},"counts_against_adherence":{"type":"boolean","example":true},"requires_reason":{"type":"boolean","example":false},"over_limit_policy":{"type":"string","example":"notify"},"fullscreen":{"type":"boolean","example":false},"show_widget":{"type":"boolean","example":true},"allowed_for":{"type":"array","items":{"type":"string"},"example":["agent","administrator"]}}}}}},"example":{"current":{"id":991,"status_key":"on_break","status_name":"On break","base_availability":"busy","family":"break","started_at":"2026-01-15T10:30:00.000Z","started_at_epoch":1737023400,"expected_seconds":1800,"within_limit":true,"duration_seconds":0,"reason_note":"Lunch","color":"#F59E0B","icon":"coffee","fullscreen":false,"show_widget":true},"status_types":[{"id":4,"key":"on_break","name":"On break","description":null,"position":2,"active":true,"family":"break","base_availability":"busy","color":"#F59E0B","icon":"coffee","time_limit_seconds":1800,"is_system":true,"counts_as_productive":false,"counts_against_adherence":true,"requires_reason":false,"over_limit_policy":"notify","fullscreen":false,"show_widget":true,"allowed_for":["agent","administrator"]}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["status_key"],"properties":{"status_key":{"type":"string","description":"Key of the target status type.","example":"on_break"},"reason_note":{"type":["string","null"],"description":"Required when the status type requires_reason.","example":"Lunch"}}},"example":{"status_key":"on_break","reason_note":"Lunch"}}}}},"put":{"tags":["Team Management"],"operationId":"auto_put_api_v1_accounts_account_id_wfm_agent_status","summary":"Set the agent's own Team Management status","description":"Changes the acting agent's Team Management status via Wfm::StatusChangeService (a reason_note is required when the target status demands one) and returns the new open status event plus the full active status catalog. Unknown status -\u003e 422 unknown_status; missing reason -\u003e 422 reason_required.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The new open status event + the active status catalog.","content":{"application/json":{"schema":{"type":"object","properties":{"current":{"type":["object","null"],"properties":{"id":{"type":"integer","example":991},"status_key":{"type":"string","example":"on_break"},"status_name":{"type":"string","example":"On break"},"base_availability":{"type":"string","example":"busy"},"family":{"type":"string","example":"break"},"started_at":{"type":"string","format":"date-time","example":"2026-01-15T10:30:00.000Z"},"started_at_epoch":{"type":"integer","example":1737023400},"expected_seconds":{"type":["integer","null"],"example":1800},"within_limit":{"type":"boolean","example":true},"duration_seconds":{"type":"integer","example":0},"reason_note":{"type":["string","null"],"example":"Lunch"},"color":{"type":["string","null"],"example":"#F59E0B"},"icon":{"type":["string","null"],"example":"coffee"},"fullscreen":{"type":["boolean","null"],"example":false},"show_widget":{"type":["boolean","null"],"example":true}}},"status_types":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","example":4},"key":{"type":"string","example":"on_break"},"name":{"type":"string","example":"On break"},"description":{"type":["string","null"],"example":null},"position":{"type":"integer","example":2},"active":{"type":"boolean","example":true},"family":{"type":"string","example":"break"},"base_availability":{"type":"string","example":"busy"},"color":{"type":["string","null"],"example":"#F59E0B"},"icon":{"type":["string","null"],"example":"coffee"},"time_limit_seconds":{"type":["integer","null"],"example":1800},"is_system":{"type":"boolean","example":true},"counts_as_productive":{"type":"boolean","example":false},"counts_against_adherence":{"type":"boolean","example":true},"requires_reason":{"type":"boolean","example":false},"over_limit_policy":{"type":"string","example":"notify"},"fullscreen":{"type":"boolean","example":false},"show_widget":{"type":"boolean","example":true},"allowed_for":{"type":"array","items":{"type":"string"},"example":["agent","administrator"]}}}}}},"example":{"current":{"id":991,"status_key":"on_break","status_name":"On break","base_availability":"busy","family":"break","started_at":"2026-01-15T10:30:00.000Z","started_at_epoch":1737023400,"expected_seconds":1800,"within_limit":true,"duration_seconds":0,"reason_note":"Lunch","color":"#F59E0B","icon":"coffee","fullscreen":false,"show_widget":true},"status_types":[{"id":4,"key":"on_break","name":"On break","description":null,"position":2,"active":true,"family":"break","base_availability":"busy","color":"#F59E0B","icon":"coffee","time_limit_seconds":1800,"is_system":true,"counts_as_productive":false,"counts_against_adherence":true,"requires_reason":false,"over_limit_policy":"notify","fullscreen":false,"show_widget":true,"allowed_for":["agent","administrator"]}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["status_key"],"properties":{"status_key":{"type":"string","description":"Key of the target status type.","example":"on_break"},"reason_note":{"type":["string","null"],"description":"Required when the status type requires_reason.","example":"Lunch"}}},"example":{"status_key":"on_break","reason_note":"Lunch"}}}}}},"/api/v1/accounts/{account_id}/wfm/events":{"get":{"tags":["Team Management"],"operationId":"auto_get_api_v1_accounts_account_id_wfm_events","summary":"List events","description":"Returns the list of events visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"status_key":{"type":"string"},"status_name":{"type":"string"},"base_availability":{"type":"string","enum":["online","offline","busy"]},"family":{"type":"string","enum":["presence","timed_break","open_break"]},"started_at":{"type":"string","format":"date-time"},"started_at_epoch":{"type":"integer"},"ended_at":{"type":["string","null"],"format":"date-time"},"expected_seconds":{"type":"integer"},"within_limit":{"type":"string"},"duration_seconds":{"type":"integer"},"reason_note":{"type":"string"},"color":{"type":["string","null"]},"icon":{"type":["string","null"]}}}},"meta":{"type":"object","properties":{"count":{"type":"integer"},"current_page":{"type":"string"},"per_page":{"type":"string"}}}}},"example":{"payload":[{"id":1,"status_key":"sample-token","status_name":"sample status name","base_availability":"online","family":"presence","started_at":"2026-01-15T10:30:00.000Z","started_at_epoch":1,"ended_at":"2026-01-15T10:30:00.000Z","expected_seconds":60,"within_limit":"sample within limit","duration_seconds":60,"reason_note":"sample reason note","color":"#1F93FF","icon":"sample icon"}],"meta":{"count":5,"current_page":"sample current page","per_page":"sample per page"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."}]}},"/api/v1/accounts/{account_id}/wfm/monitoring":{"get":{"tags":["Team Management"],"operationId":"auto_get_api_v1_accounts_account_id_wfm_monitoring","summary":"List monitoring","description":"Returns the list of monitoring visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"merge":{"type":"string"}}},"example":{"merge":"sample merge"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"period","in":"query","required":false,"schema":{"type":"string","enum":["today","week","month","year","custom"],"default":"today"},"description":"Aggregation window for the per-agent metrics (sessions, CSAT, performance)."},{"name":"from","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"Custom window start (only read when `period=custom`)."},{"name":"to","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"Custom window end (only read when `period=custom`)."},{"name":"team_id","in":"query","required":false,"schema":{"type":"integer"},"description":"Supervision lens — narrows the board (summary and rows) to the monitored agents that belong to this team. Applied AFTER enrollment resolution; it never widens the monitored roster."}]}},"/api/v1/accounts/{account_id}/wfm/agent_performance/{id}":{"get":{"tags":["Team Management"],"operationId":"auto_get_api_v1_accounts_account_id_wfm_agent_performance_id","summary":"Get agent performance","description":"Returns the agent performance identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"merge":{"type":"string"}}},"example":{"merge":"sample merge"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"period","in":"query","required":false,"description":"Window the metrics are computed over. Defaults to `month`; `day` is accepted as an alias of `today`; any unrecognized value also falls back to `month`. `custom` reads `from`/`to`.","schema":{"type":"string","enum":["today","week","month","year","custom"]},"example":"week"},{"name":"from","in":"query","required":false,"description":"Start of the window when `period=custom` (inclusive, from the beginning of that day).","schema":{"type":"string","format":"date"},"example":"2026-07-01"},{"name":"to","in":"query","required":false,"description":"End of the window when `period=custom` (inclusive, to the end of that day).","schema":{"type":"string","format":"date"},"example":"2026-07-31"}]}},"/api/v1/accounts/{account_id}/wfm/agent_settings/bulk_update":{"patch":{"tags":["Team Management"],"operationId":"auto_patch_api_v1_accounts_account_id_wfm_agent_settings_bulk_update","summary":"Bulk update agent settings","description":"Performs the bulk update operation on the targeted agent setting resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"account_user_id":{"type":"integer"},"user":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"}}},"monitored":{"type":"string"},"enrollment_source":{"type":"string","enum":["default","manual","team","inbox"]},"schedule_template_id":{"type":"integer"},"expected_daily_seconds":{"type":"integer"},"allowed_status_type_ids":{"type":"array","items":{"type":"integer"}}}}}}},"example":{"payload":[{"id":1,"account_user_id":1,"user":{"id":1,"name":"Sample Name"},"monitored":"sample monitored","enrollment_source":"default","schedule_template_id":1,"expected_daily_seconds":60,"allowed_status_type_ids":[1]}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"monitored":{"type":"string"},"ids":{"type":"array","items":{"type":"integer"}}}},"example":{"monitored":"sample monitored","ids":[1]}}}}}},"/api/v1/accounts/{account_id}/wfm/agent_settings":{"get":{"tags":["Team Management"],"operationId":"auto_get_api_v1_accounts_account_id_wfm_agent_settings","summary":"List agent settings","description":"Returns the list of agent settings visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"account_user_id":{"type":"integer"},"user":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"}}},"monitored":{"type":"string"},"enrollment_source":{"type":"string","enum":["default","manual","team","inbox"]},"schedule_template_id":{"type":"integer"},"expected_daily_seconds":{"type":"integer"},"allowed_status_type_ids":{"type":"array","items":{"type":"integer"}}}}}}},"example":{"payload":[{"id":1,"account_user_id":1,"user":{"id":1,"name":"Sample Name"},"monitored":"sample monitored","enrollment_source":"default","schedule_template_id":1,"expected_daily_seconds":60,"allowed_status_type_ids":[1]}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."}]}},"/api/v1/accounts/{account_id}/wfm/agent_settings/{id}":{"patch":{"tags":["Team Management"],"operationId":"auto_patch_api_v1_accounts_account_id_wfm_agent_settings_id","summary":"Update agent settings","description":"Updates the agent setting identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"account_user_id":{"type":"integer"},"user":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"}}},"monitored":{"type":"string"},"enrollment_source":{"type":"string","enum":["default","manual","team","inbox"]},"schedule_template_id":{"type":"integer"},"expected_daily_seconds":{"type":"integer"},"allowed_status_type_ids":{"type":"array","items":{"type":"integer"}}}},"example":{"id":1,"account_user_id":1,"user":{"id":1,"name":"Sample Name"},"monitored":"sample monitored","enrollment_source":"default","schedule_template_id":1,"expected_daily_seconds":60,"allowed_status_type_ids":[1]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"agent_setting":{"type":"object","properties":{"monitored":{"type":"string"},"expected_daily_seconds":{"type":"integer"},"allowed_status_type_ids":{"type":"array","items":{"type":"integer"}}}}},"required":["agent_setting"]},"example":{"agent_setting":{"monitored":"sample monitored","expected_daily_seconds":60,"allowed_status_type_ids":[1]}}}}}},"put":{"tags":["Team Management"],"operationId":"auto_put_api_v1_accounts_account_id_wfm_agent_settings_id","summary":"Update agent settings","description":"Updates the agent setting identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"account_user_id":{"type":"integer"},"user":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"}}},"monitored":{"type":"string"},"enrollment_source":{"type":"string","enum":["default","manual","team","inbox"]},"schedule_template_id":{"type":"integer"},"expected_daily_seconds":{"type":"integer"},"allowed_status_type_ids":{"type":"array","items":{"type":"integer"}}}},"example":{"id":1,"account_user_id":1,"user":{"id":1,"name":"Sample Name"},"monitored":"sample monitored","enrollment_source":"default","schedule_template_id":1,"expected_daily_seconds":60,"allowed_status_type_ids":[1]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"agent_setting":{"type":"object","properties":{"monitored":{"type":"string"},"expected_daily_seconds":{"type":"integer"},"allowed_status_type_ids":{"type":"array","items":{"type":"integer"}}}}},"required":["agent_setting"]},"example":{"agent_setting":{"monitored":"sample monitored","expected_daily_seconds":60,"allowed_status_type_ids":[1]}}}}}}},"/api/v1/accounts/{account_id}/wfm/settings":{"get":{"tags":["Team Management"],"operationId":"auto_get_api_v1_accounts_account_id_wfm_settings","summary":"Get settings","description":"Returns the setting identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"enrollment_mode":{"type":"string","enum":["all_with_exceptions","opt_in","by_team_inbox"]},"adherence_target_pct":{"type":"number"},"excluded_agent_ids":{"type":"array","items":{"type":"integer"}},"monitored_team_ids":{"type":"array","items":{"type":"integer"}},"monitored_inbox_ids":{"type":"array","items":{"type":"integer"}},"default_over_limit_policy":{"type":"string"},"business_hours":{"type":"string"},"week_start":{"type":"string"},"timezone":{"type":"string","description":"IANA timezone identifier (e.g. \"America/Sao_Paulo\", \"UTC\"). Rails timezone names are also accepted on input; an unrecognized value is ignored in favor of the next fallback.","example":"America/Sao_Paulo"}}},"example":{"id":1,"enrollment_mode":"all_with_exceptions","adherence_target_pct":12.5,"excluded_agent_ids":[1],"monitored_team_ids":[1],"monitored_inbox_ids":[1],"default_over_limit_policy":"sample default over limit policy","business_hours":"sample business hours","week_start":"sample week start","timezone":"America/Sao_Paulo"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]},"patch":{"tags":["Team Management"],"operationId":"auto_patch_api_v1_accounts_account_id_wfm_settings","summary":"Update settings","description":"Updates the setting identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"enrollment_mode":{"type":"string","enum":["all_with_exceptions","opt_in","by_team_inbox"]},"adherence_target_pct":{"type":"number"},"excluded_agent_ids":{"type":"array","items":{"type":"integer"}},"monitored_team_ids":{"type":"array","items":{"type":"integer"}},"monitored_inbox_ids":{"type":"array","items":{"type":"integer"}},"default_over_limit_policy":{"type":"string"},"business_hours":{"type":"string"},"week_start":{"type":"string"},"timezone":{"type":"string","description":"IANA timezone identifier (e.g. \"America/Sao_Paulo\", \"UTC\"). Rails timezone names are also accepted on input; an unrecognized value is ignored in favor of the next fallback.","example":"America/Sao_Paulo"}}},"example":{"id":1,"enrollment_mode":"all_with_exceptions","adherence_target_pct":12.5,"excluded_agent_ids":[1],"monitored_team_ids":[1],"monitored_inbox_ids":[1],"default_over_limit_policy":"sample default over limit policy","business_hours":"sample business hours","week_start":"sample week start","timezone":"America/Sao_Paulo"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"settings":{"type":"object","properties":{"enrollment_mode":{"type":"string","enum":["all_with_exceptions","opt_in","by_team_inbox"]},"adherence_target_pct":{"type":"number"},"week_start":{"type":"string"},"timezone":{"type":"string","description":"IANA timezone identifier (e.g. \"America/Sao_Paulo\", \"UTC\"). Rails timezone names are also accepted on input; an unrecognized value is ignored in favor of the next fallback.","example":"America/Sao_Paulo"},"excluded_agent_ids":{"type":"array","items":{"type":"integer"}},"monitored_team_ids":{"type":"array","items":{"type":"integer"}},"monitored_inbox_ids":{"type":"array","items":{"type":"integer"}},"default_over_limit_policy":{"type":"object","additionalProperties":true,"description":"Free-form object."},"business_hours":{"type":"object","additionalProperties":true,"description":"Free-form object."}}}},"required":["settings"]},"example":{"settings":{"enrollment_mode":"all_with_exceptions","adherence_target_pct":12.5,"week_start":"sample week start","timezone":"America/Sao_Paulo","excluded_agent_ids":[1],"monitored_team_ids":[1],"monitored_inbox_ids":[1],"default_over_limit_policy":{},"business_hours":{}}}}}}},"put":{"tags":["Team Management"],"operationId":"auto_put_api_v1_accounts_account_id_wfm_settings","summary":"Update settings","description":"Updates the setting identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"enrollment_mode":{"type":"string","enum":["all_with_exceptions","opt_in","by_team_inbox"]},"adherence_target_pct":{"type":"number"},"excluded_agent_ids":{"type":"array","items":{"type":"integer"}},"monitored_team_ids":{"type":"array","items":{"type":"integer"}},"monitored_inbox_ids":{"type":"array","items":{"type":"integer"}},"default_over_limit_policy":{"type":"string"},"business_hours":{"type":"string"},"week_start":{"type":"string"},"timezone":{"type":"string","description":"IANA timezone identifier (e.g. \"America/Sao_Paulo\", \"UTC\"). Rails timezone names are also accepted on input; an unrecognized value is ignored in favor of the next fallback.","example":"America/Sao_Paulo"}}},"example":{"id":1,"enrollment_mode":"all_with_exceptions","adherence_target_pct":12.5,"excluded_agent_ids":[1],"monitored_team_ids":[1],"monitored_inbox_ids":[1],"default_over_limit_policy":"sample default over limit policy","business_hours":"sample business hours","week_start":"sample week start","timezone":"America/Sao_Paulo"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"settings":{"type":"object","properties":{"enrollment_mode":{"type":"string","enum":["all_with_exceptions","opt_in","by_team_inbox"]},"adherence_target_pct":{"type":"number"},"week_start":{"type":"string"},"timezone":{"type":"string","description":"IANA timezone identifier (e.g. \"America/Sao_Paulo\", \"UTC\"). Rails timezone names are also accepted on input; an unrecognized value is ignored in favor of the next fallback.","example":"America/Sao_Paulo"},"excluded_agent_ids":{"type":"array","items":{"type":"integer"}},"monitored_team_ids":{"type":"array","items":{"type":"integer"}},"monitored_inbox_ids":{"type":"array","items":{"type":"integer"}},"default_over_limit_policy":{"type":"object","additionalProperties":true,"description":"Free-form object."},"business_hours":{"type":"object","additionalProperties":true,"description":"Free-form object."}}}},"required":["settings"]},"example":{"settings":{"enrollment_mode":"all_with_exceptions","adherence_target_pct":12.5,"week_start":"sample week start","timezone":"America/Sao_Paulo","excluded_agent_ids":[1],"monitored_team_ids":[1],"monitored_inbox_ids":[1],"default_over_limit_policy":{},"business_hours":{}}}}}}}},"/api/v1/accounts/{account_id}/wfm/schedules":{"get":{"tags":["Team Management"],"operationId":"auto_get_api_v1_accounts_account_id_wfm_schedules","summary":"List schedules","description":"Returns the list of schedules visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"timezone":{"type":"string","description":"IANA timezone identifier (e.g. \"America/Sao_Paulo\", \"UTC\"). Rails timezone names are also accepted on input; an unrecognized value is ignored in favor of the next fallback.","example":"America/Sao_Paulo"},"active":{"type":"boolean"},"recurrence":{"type":"object","additionalProperties":true,"description":"JSONB recurrence rule: frequency (daily|weekly|monthly|yearly), interval, until, count, days."},"created_at":{"type":["string","null"],"format":"date-time"},"updated_at":{"type":["string","null"],"format":"date-time"}}}}}},"example":{"payload":[{"id":1,"name":"Sample Name","timezone":"America/Sao_Paulo","active":true,"recurrence":{},"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."}]},"post":{"tags":["Team Management"],"operationId":"auto_post_api_v1_accounts_account_id_wfm_schedules","summary":"Create schedules","description":"Creates a new schedule from the request payload. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"201":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"timezone":{"type":"string","description":"IANA timezone identifier (e.g. \"America/Sao_Paulo\", \"UTC\"). Rails timezone names are also accepted on input; an unrecognized value is ignored in favor of the next fallback.","example":"America/Sao_Paulo"},"active":{"type":"boolean"},"recurrence":{"type":"object","additionalProperties":true,"description":"JSONB recurrence rule: frequency (daily|weekly|monthly|yearly), interval, until, count, days."},"created_at":{"type":["string","null"],"format":"date-time"},"updated_at":{"type":["string","null"],"format":"date-time"}}},"example":{"id":1,"name":"Sample Name","timezone":"America/Sao_Paulo","active":true,"recurrence":{},"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"schedule":{"type":"object","properties":{"name":{"type":"string"},"timezone":{"type":"string","description":"IANA timezone identifier (e.g. \"America/Sao_Paulo\", \"UTC\"). Rails timezone names are also accepted on input; an unrecognized value is ignored in favor of the next fallback.","example":"America/Sao_Paulo"},"active":{"type":"boolean"}},"required":["name"]}},"required":["schedule"]},"example":{"schedule":{"name":"Sample Name","timezone":"America/Sao_Paulo","active":true}}}}}}},"/api/v1/accounts/{account_id}/wfm/schedules/{id}":{"get":{"tags":["Team Management"],"operationId":"auto_get_api_v1_accounts_account_id_wfm_schedules_id","summary":"Get schedules","description":"Returns the schedule identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"timezone":{"type":"string","description":"IANA timezone identifier (e.g. \"America/Sao_Paulo\", \"UTC\"). Rails timezone names are also accepted on input; an unrecognized value is ignored in favor of the next fallback.","example":"America/Sao_Paulo"},"active":{"type":"boolean"},"recurrence":{"type":"object","additionalProperties":true,"description":"JSONB recurrence rule: frequency (daily|weekly|monthly|yearly), interval, until, count, days."},"created_at":{"type":["string","null"],"format":"date-time"},"updated_at":{"type":["string","null"],"format":"date-time"}}},"example":{"id":1,"name":"Sample Name","timezone":"America/Sao_Paulo","active":true,"recurrence":{},"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]},"patch":{"tags":["Team Management"],"operationId":"auto_patch_api_v1_accounts_account_id_wfm_schedules_id","summary":"Update schedules","description":"Updates the schedule identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"timezone":{"type":"string","description":"IANA timezone identifier (e.g. \"America/Sao_Paulo\", \"UTC\"). Rails timezone names are also accepted on input; an unrecognized value is ignored in favor of the next fallback.","example":"America/Sao_Paulo"},"active":{"type":"boolean"},"recurrence":{"type":"object","additionalProperties":true,"description":"JSONB recurrence rule: frequency (daily|weekly|monthly|yearly), interval, until, count, days."},"created_at":{"type":["string","null"],"format":"date-time"},"updated_at":{"type":["string","null"],"format":"date-time"}}},"example":{"id":1,"name":"Sample Name","timezone":"America/Sao_Paulo","active":true,"recurrence":{},"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"schedule":{"type":"object","properties":{"name":{"type":"string"},"timezone":{"type":"string","description":"IANA timezone identifier (e.g. \"America/Sao_Paulo\", \"UTC\"). Rails timezone names are also accepted on input; an unrecognized value is ignored in favor of the next fallback.","example":"America/Sao_Paulo"},"active":{"type":"boolean"}}}},"required":["schedule"]},"example":{"schedule":{"name":"Sample Name","timezone":"America/Sao_Paulo","active":true}}}}}},"put":{"tags":["Team Management"],"operationId":"auto_put_api_v1_accounts_account_id_wfm_schedules_id","summary":"Update schedules","description":"Updates the schedule identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"timezone":{"type":"string","description":"IANA timezone identifier (e.g. \"America/Sao_Paulo\", \"UTC\"). Rails timezone names are also accepted on input; an unrecognized value is ignored in favor of the next fallback.","example":"America/Sao_Paulo"},"active":{"type":"boolean"},"recurrence":{"type":"object","additionalProperties":true,"description":"JSONB recurrence rule: frequency (daily|weekly|monthly|yearly), interval, until, count, days."},"created_at":{"type":["string","null"],"format":"date-time"},"updated_at":{"type":["string","null"],"format":"date-time"}}},"example":{"id":1,"name":"Sample Name","timezone":"America/Sao_Paulo","active":true,"recurrence":{},"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"schedule":{"type":"object","properties":{"name":{"type":"string"},"timezone":{"type":"string","description":"IANA timezone identifier (e.g. \"America/Sao_Paulo\", \"UTC\"). Rails timezone names are also accepted on input; an unrecognized value is ignored in favor of the next fallback.","example":"America/Sao_Paulo"},"active":{"type":"boolean"}}}},"required":["schedule"]},"example":{"schedule":{"name":"Sample Name","timezone":"America/Sao_Paulo","active":true}}}}}},"delete":{"tags":["Team Management"],"operationId":"auto_delete_api_v1_accounts_account_id_wfm_schedules_id","summary":"Delete schedules","description":"Deletes the schedule identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Success (no content)"},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/wfm/shifts/generate":{"post":{"tags":["Team Management"],"operationId":"auto_post_api_v1_accounts_account_id_wfm_shifts_generate","summary":"Generate shifts","description":"Performs the generate operation on the targeted shift resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"enqueued":{"type":"boolean","example":true}}},"example":{"enqueued":true}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"schedule_id":{"type":"integer"},"from":{"type":"string"},"to":{"type":"string"}}},"example":{"schedule_id":1,"from":"sample from","to":"sample to"}}}}}},"/api/v1/accounts/{account_id}/wfm/shifts":{"get":{"tags":["Team Management"],"operationId":"auto_get_api_v1_accounts_account_id_wfm_shifts","summary":"List shifts","description":"Returns the list of shifts visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"account_user_id":{"type":"integer"},"schedule_id":{"type":"integer"},"date":{"type":"string","format":"date"},"starts_at":{"type":["string","null"],"format":"date-time"},"ends_at":{"type":["string","null"],"format":"date-time"},"status":{"type":"string","enum":["planned","published","in_progress","completed"]},"source":{"type":"string","enum":["manual","generated"]},"segments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"shift_id":{"type":"integer"},"status_type_id":{"type":"integer"},"kind":{"type":"string","enum":["work","lunch","break","meeting","training","other"]},"planned_start":{"type":["string","null"]},"planned_end":{"type":["string","null"]}}}}}}}}},"example":{"payload":[{"id":1,"account_user_id":1,"schedule_id":1,"date":"2026-01-15","starts_at":"2026-01-15T10:30:00.000Z","ends_at":"2026-01-15T10:30:00.000Z","status":"planned","source":"manual","segments":[{"id":1,"shift_id":1,"status_type_id":1,"kind":"work","planned_start":"sample planned start","planned_end":"sample planned end"}]}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."}]},"post":{"tags":["Team Management"],"operationId":"auto_post_api_v1_accounts_account_id_wfm_shifts","summary":"Create shifts","description":"Creates a new shift from the request payload. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"201":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"account_user_id":{"type":"integer"},"schedule_id":{"type":"integer"},"date":{"type":"string","format":"date"},"starts_at":{"type":["string","null"],"format":"date-time"},"ends_at":{"type":["string","null"],"format":"date-time"},"status":{"type":"string","enum":["planned","published","in_progress","completed"]},"source":{"type":"string","enum":["manual","generated"]},"segments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"shift_id":{"type":"integer"},"status_type_id":{"type":"integer"},"kind":{"type":"string","enum":["work","lunch","break","meeting","training","other"]},"planned_start":{"type":["string","null"]},"planned_end":{"type":["string","null"]}}}}}},"example":{"id":1,"account_user_id":1,"schedule_id":1,"date":"2026-01-15","starts_at":"2026-01-15T10:30:00.000Z","ends_at":"2026-01-15T10:30:00.000Z","status":"planned","source":"manual","segments":[{"id":1,"shift_id":1,"status_type_id":1,"kind":"work","planned_start":"sample planned start","planned_end":"sample planned end"}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"shift":{"type":"object","properties":{"account_user_id":{"type":"integer"},"schedule_id":{"type":"integer"},"date":{"type":"string","format":"date"},"starts_at":{"type":"string","format":"date-time"},"ends_at":{"type":"string","format":"date-time"},"status":{"type":"string","enum":["planned","published","in_progress","completed"]},"source":{"type":"string","enum":["manual","generated"]}},"required":["date","ends_at","starts_at"]}},"required":["shift"]},"example":{"shift":{"account_user_id":1,"schedule_id":1,"date":"2026-01-15","starts_at":"2026-01-15T10:30:00.000Z","ends_at":"2026-01-15T10:30:00.000Z","status":"planned","source":"manual"}}}}}}},"/api/v1/accounts/{account_id}/wfm/shifts/{id}":{"get":{"tags":["Team Management"],"operationId":"auto_get_api_v1_accounts_account_id_wfm_shifts_id","summary":"Get shifts","description":"Returns the shift identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"account_user_id":{"type":"integer"},"schedule_id":{"type":"integer"},"date":{"type":"string","format":"date"},"starts_at":{"type":["string","null"],"format":"date-time"},"ends_at":{"type":["string","null"],"format":"date-time"},"status":{"type":"string","enum":["planned","published","in_progress","completed"]},"source":{"type":"string","enum":["manual","generated"]},"segments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"shift_id":{"type":"integer"},"status_type_id":{"type":"integer"},"kind":{"type":"string","enum":["work","lunch","break","meeting","training","other"]},"planned_start":{"type":["string","null"]},"planned_end":{"type":["string","null"]}}}}}},"example":{"id":1,"account_user_id":1,"schedule_id":1,"date":"2026-01-15","starts_at":"2026-01-15T10:30:00.000Z","ends_at":"2026-01-15T10:30:00.000Z","status":"planned","source":"manual","segments":[{"id":1,"shift_id":1,"status_type_id":1,"kind":"work","planned_start":"sample planned start","planned_end":"sample planned end"}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]},"patch":{"tags":["Team Management"],"operationId":"auto_patch_api_v1_accounts_account_id_wfm_shifts_id","summary":"Update shifts","description":"Updates the shift identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"account_user_id":{"type":"integer"},"schedule_id":{"type":"integer"},"date":{"type":"string","format":"date"},"starts_at":{"type":["string","null"],"format":"date-time"},"ends_at":{"type":["string","null"],"format":"date-time"},"status":{"type":"string","enum":["planned","published","in_progress","completed"]},"source":{"type":"string","enum":["manual","generated"]},"segments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"shift_id":{"type":"integer"},"status_type_id":{"type":"integer"},"kind":{"type":"string","enum":["work","lunch","break","meeting","training","other"]},"planned_start":{"type":["string","null"]},"planned_end":{"type":["string","null"]}}}}}},"example":{"id":1,"account_user_id":1,"schedule_id":1,"date":"2026-01-15","starts_at":"2026-01-15T10:30:00.000Z","ends_at":"2026-01-15T10:30:00.000Z","status":"planned","source":"manual","segments":[{"id":1,"shift_id":1,"status_type_id":1,"kind":"work","planned_start":"sample planned start","planned_end":"sample planned end"}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"shift":{"type":"object","properties":{"account_user_id":{"type":"integer"},"schedule_id":{"type":"integer"},"date":{"type":"string","format":"date"},"starts_at":{"type":"string","format":"date-time"},"ends_at":{"type":"string","format":"date-time"},"status":{"type":"string","enum":["planned","published","in_progress","completed"]},"source":{"type":"string","enum":["manual","generated"]}}}},"required":["shift"]},"example":{"shift":{"account_user_id":1,"schedule_id":1,"date":"2026-01-15","starts_at":"2026-01-15T10:30:00.000Z","ends_at":"2026-01-15T10:30:00.000Z","status":"planned","source":"manual"}}}}}},"put":{"tags":["Team Management"],"operationId":"auto_put_api_v1_accounts_account_id_wfm_shifts_id","summary":"Update shifts","description":"Updates the shift identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"account_user_id":{"type":"integer"},"schedule_id":{"type":"integer"},"date":{"type":"string","format":"date"},"starts_at":{"type":["string","null"],"format":"date-time"},"ends_at":{"type":["string","null"],"format":"date-time"},"status":{"type":"string","enum":["planned","published","in_progress","completed"]},"source":{"type":"string","enum":["manual","generated"]},"segments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"shift_id":{"type":"integer"},"status_type_id":{"type":"integer"},"kind":{"type":"string","enum":["work","lunch","break","meeting","training","other"]},"planned_start":{"type":["string","null"]},"planned_end":{"type":["string","null"]}}}}}},"example":{"id":1,"account_user_id":1,"schedule_id":1,"date":"2026-01-15","starts_at":"2026-01-15T10:30:00.000Z","ends_at":"2026-01-15T10:30:00.000Z","status":"planned","source":"manual","segments":[{"id":1,"shift_id":1,"status_type_id":1,"kind":"work","planned_start":"sample planned start","planned_end":"sample planned end"}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"shift":{"type":"object","properties":{"account_user_id":{"type":"integer"},"schedule_id":{"type":"integer"},"date":{"type":"string","format":"date"},"starts_at":{"type":"string","format":"date-time"},"ends_at":{"type":"string","format":"date-time"},"status":{"type":"string","enum":["planned","published","in_progress","completed"]},"source":{"type":"string","enum":["manual","generated"]}}}},"required":["shift"]},"example":{"shift":{"account_user_id":1,"schedule_id":1,"date":"2026-01-15","starts_at":"2026-01-15T10:30:00.000Z","ends_at":"2026-01-15T10:30:00.000Z","status":"planned","source":"manual"}}}}}},"delete":{"tags":["Team Management"],"operationId":"auto_delete_api_v1_accounts_account_id_wfm_shifts_id","summary":"Delete shifts","description":"Deletes the shift identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Success (no content)"},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/wfm/shift_segments":{"post":{"tags":["Team Management"],"operationId":"auto_post_api_v1_accounts_account_id_wfm_shift_segments","summary":"Create shift segments","description":"Creates a new shift segment from the request payload. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"201":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"shift_id":{"type":"integer"},"status_type_id":{"type":"integer"},"kind":{"type":"string","enum":["work","lunch","break","meeting","training","other"]},"planned_start":{"type":["string","null"]},"planned_end":{"type":["string","null"]}}},"example":{"id":1,"shift_id":1,"status_type_id":1,"kind":"work","planned_start":"sample planned start","planned_end":"sample planned end"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"shift_segment":{"type":"object","properties":{"shift_id":{"type":"integer"},"status_type_id":{"type":"integer"},"kind":{"type":"string","enum":["work","lunch","break","meeting","training","other"]},"planned_start":{"type":"string"},"planned_end":{"type":"string"}},"required":["planned_end","planned_start"]}},"required":["shift_segment"]},"example":{"shift_segment":{"shift_id":1,"status_type_id":1,"kind":"work","planned_start":"sample planned start","planned_end":"sample planned end"}}}}}}},"/api/v1/accounts/{account_id}/wfm/shift_segments/{id}":{"patch":{"tags":["Team Management"],"operationId":"auto_patch_api_v1_accounts_account_id_wfm_shift_segments_id","summary":"Update shift segments","description":"Updates the shift segment identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"shift_id":{"type":"integer"},"status_type_id":{"type":"integer"},"kind":{"type":"string","enum":["work","lunch","break","meeting","training","other"]},"planned_start":{"type":["string","null"]},"planned_end":{"type":["string","null"]}}},"example":{"id":1,"shift_id":1,"status_type_id":1,"kind":"work","planned_start":"sample planned start","planned_end":"sample planned end"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"shift_segment":{"type":"object","properties":{"shift_id":{"type":"integer"},"status_type_id":{"type":"integer"},"kind":{"type":"string","enum":["work","lunch","break","meeting","training","other"]},"planned_start":{"type":"string"},"planned_end":{"type":"string"}}}},"required":["shift_segment"]},"example":{"shift_segment":{"shift_id":1,"status_type_id":1,"kind":"work","planned_start":"sample planned start","planned_end":"sample planned end"}}}}}},"put":{"tags":["Team Management"],"operationId":"auto_put_api_v1_accounts_account_id_wfm_shift_segments_id","summary":"Update shift segments","description":"Updates the shift segment identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"shift_id":{"type":"integer"},"status_type_id":{"type":"integer"},"kind":{"type":"string","enum":["work","lunch","break","meeting","training","other"]},"planned_start":{"type":["string","null"]},"planned_end":{"type":["string","null"]}}},"example":{"id":1,"shift_id":1,"status_type_id":1,"kind":"work","planned_start":"sample planned start","planned_end":"sample planned end"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"shift_segment":{"type":"object","properties":{"shift_id":{"type":"integer"},"status_type_id":{"type":"integer"},"kind":{"type":"string","enum":["work","lunch","break","meeting","training","other"]},"planned_start":{"type":"string"},"planned_end":{"type":"string"}}}},"required":["shift_segment"]},"example":{"shift_segment":{"shift_id":1,"status_type_id":1,"kind":"work","planned_start":"sample planned start","planned_end":"sample planned end"}}}}}},"delete":{"tags":["Team Management"],"operationId":"auto_delete_api_v1_accounts_account_id_wfm_shift_segments_id","summary":"Delete shift segments","description":"Deletes the shift segment identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Success (no content)"},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/wfm/queues/{id}/add_member":{"post":{"tags":["Team Management"],"operationId":"auto_post_api_v1_accounts_account_id_wfm_queues_id_add_member","summary":"Add member queues","description":"Performs the add member operation on the targeted queue resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"distribution_policy":{"type":"string","enum":["round_robin","load_balanced","manual"]},"active":{"type":"boolean"},"position":{"type":"integer"},"member_ids":{"type":"array","items":{"type":"integer"}},"inbox_ids":{"type":"array","items":{"type":"integer"}},"member_count":{"type":"integer"},"inbox_count":{"type":"integer"}}},"example":{"id":1,"name":"Sample Name","description":"A short description.","distribution_policy":"round_robin","active":true,"position":1,"member_ids":[1],"inbox_ids":[1],"member_count":5,"inbox_count":5}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"account_user_id":{"type":"integer"}}},"example":{"account_user_id":1}}}}}},"/api/v1/accounts/{account_id}/wfm/queues/{id}/remove_member":{"delete":{"tags":["Team Management"],"operationId":"auto_delete_api_v1_accounts_account_id_wfm_queues_id_remove_member","summary":"Remove member queues","description":"Performs the remove member operation on the targeted queue resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"distribution_policy":{"type":"string","enum":["round_robin","load_balanced","manual"]},"active":{"type":"boolean"},"position":{"type":"integer"},"member_ids":{"type":"array","items":{"type":"integer"}},"inbox_ids":{"type":"array","items":{"type":"integer"}},"member_count":{"type":"integer"},"inbox_count":{"type":"integer"}}},"example":{"id":1,"name":"Sample Name","description":"A short description.","distribution_policy":"round_robin","active":true,"position":1,"member_ids":[1],"inbox_ids":[1],"member_count":5,"inbox_count":5}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/wfm/queues/{id}/add_inbox":{"post":{"tags":["Team Management"],"operationId":"auto_post_api_v1_accounts_account_id_wfm_queues_id_add_inbox","summary":"Add inbox queues","description":"Performs the add inbox operation on the targeted queue resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"distribution_policy":{"type":"string","enum":["round_robin","load_balanced","manual"]},"active":{"type":"boolean"},"position":{"type":"integer"},"member_ids":{"type":"array","items":{"type":"integer"}},"inbox_ids":{"type":"array","items":{"type":"integer"}},"member_count":{"type":"integer"},"inbox_count":{"type":"integer"}}},"example":{"id":1,"name":"Sample Name","description":"A short description.","distribution_policy":"round_robin","active":true,"position":1,"member_ids":[1],"inbox_ids":[1],"member_count":5,"inbox_count":5}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"inbox_id":{"type":"integer"}}},"example":{"inbox_id":1}}}}}},"/api/v1/accounts/{account_id}/wfm/queues/{id}/remove_inbox":{"delete":{"tags":["Team Management"],"operationId":"auto_delete_api_v1_accounts_account_id_wfm_queues_id_remove_inbox","summary":"Remove inbox queues","description":"Performs the remove inbox operation on the targeted queue resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"distribution_policy":{"type":"string","enum":["round_robin","load_balanced","manual"]},"active":{"type":"boolean"},"position":{"type":"integer"},"member_ids":{"type":"array","items":{"type":"integer"}},"inbox_ids":{"type":"array","items":{"type":"integer"}},"member_count":{"type":"integer"},"inbox_count":{"type":"integer"}}},"example":{"id":1,"name":"Sample Name","description":"A short description.","distribution_policy":"round_robin","active":true,"position":1,"member_ids":[1],"inbox_ids":[1],"member_count":5,"inbox_count":5}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/wfm/queues":{"get":{"tags":["Team Management"],"operationId":"auto_get_api_v1_accounts_account_id_wfm_queues","summary":"List queues","description":"Returns the list of queues visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"distribution_policy":{"type":"string","enum":["round_robin","load_balanced","manual"]},"active":{"type":"boolean"},"position":{"type":"integer"},"member_ids":{"type":"array","items":{"type":"integer"}},"inbox_ids":{"type":"array","items":{"type":"integer"}},"member_count":{"type":"integer"},"inbox_count":{"type":"integer"}}}}}},"example":{"payload":[{"id":1,"name":"Sample Name","description":"A short description.","distribution_policy":"round_robin","active":true,"position":1,"member_ids":[1],"inbox_ids":[1],"member_count":5,"inbox_count":5}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."}]},"post":{"tags":["Team Management"],"operationId":"auto_post_api_v1_accounts_account_id_wfm_queues","summary":"Create queues","description":"Creates a new queue from the request payload. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"201":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"distribution_policy":{"type":"string","enum":["round_robin","load_balanced","manual"]},"active":{"type":"boolean"},"position":{"type":"integer"},"member_ids":{"type":"array","items":{"type":"integer"}},"inbox_ids":{"type":"array","items":{"type":"integer"}},"member_count":{"type":"integer"},"inbox_count":{"type":"integer"}}},"example":{"id":1,"name":"Sample Name","description":"A short description.","distribution_policy":"round_robin","active":true,"position":1,"member_ids":[1],"inbox_ids":[1],"member_count":5,"inbox_count":5}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"queue":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"distribution_policy":{"type":"string","enum":["round_robin","load_balanced","manual"]},"active":{"type":"boolean"},"position":{"type":"integer"}},"required":["name"]}},"required":["queue"]},"example":{"queue":{"name":"Sample Name","description":"A short description.","distribution_policy":"round_robin","active":true,"position":1}}}}}}},"/api/v1/accounts/{account_id}/wfm/queues/{id}":{"get":{"tags":["Team Management"],"operationId":"auto_get_api_v1_accounts_account_id_wfm_queues_id","summary":"Get queues","description":"Returns the queue identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"distribution_policy":{"type":"string","enum":["round_robin","load_balanced","manual"]},"active":{"type":"boolean"},"position":{"type":"integer"},"member_ids":{"type":"array","items":{"type":"integer"}},"inbox_ids":{"type":"array","items":{"type":"integer"}},"member_count":{"type":"integer"},"inbox_count":{"type":"integer"}}},"example":{"id":1,"name":"Sample Name","description":"A short description.","distribution_policy":"round_robin","active":true,"position":1,"member_ids":[1],"inbox_ids":[1],"member_count":5,"inbox_count":5}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]},"patch":{"tags":["Team Management"],"operationId":"auto_patch_api_v1_accounts_account_id_wfm_queues_id","summary":"Update queues","description":"Updates the queue identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"distribution_policy":{"type":"string","enum":["round_robin","load_balanced","manual"]},"active":{"type":"boolean"},"position":{"type":"integer"},"member_ids":{"type":"array","items":{"type":"integer"}},"inbox_ids":{"type":"array","items":{"type":"integer"}},"member_count":{"type":"integer"},"inbox_count":{"type":"integer"}}},"example":{"id":1,"name":"Sample Name","description":"A short description.","distribution_policy":"round_robin","active":true,"position":1,"member_ids":[1],"inbox_ids":[1],"member_count":5,"inbox_count":5}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"queue":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"distribution_policy":{"type":"string","enum":["round_robin","load_balanced","manual"]},"active":{"type":"boolean"},"position":{"type":"integer"}}}},"required":["queue"]},"example":{"queue":{"name":"Sample Name","description":"A short description.","distribution_policy":"round_robin","active":true,"position":1}}}}}},"put":{"tags":["Team Management"],"operationId":"auto_put_api_v1_accounts_account_id_wfm_queues_id","summary":"Update queues","description":"Updates the queue identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"distribution_policy":{"type":"string","enum":["round_robin","load_balanced","manual"]},"active":{"type":"boolean"},"position":{"type":"integer"},"member_ids":{"type":"array","items":{"type":"integer"}},"inbox_ids":{"type":"array","items":{"type":"integer"}},"member_count":{"type":"integer"},"inbox_count":{"type":"integer"}}},"example":{"id":1,"name":"Sample Name","description":"A short description.","distribution_policy":"round_robin","active":true,"position":1,"member_ids":[1],"inbox_ids":[1],"member_count":5,"inbox_count":5}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"queue":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"distribution_policy":{"type":"string","enum":["round_robin","load_balanced","manual"]},"active":{"type":"boolean"},"position":{"type":"integer"}}}},"required":["queue"]},"example":{"queue":{"name":"Sample Name","description":"A short description.","distribution_policy":"round_robin","active":true,"position":1}}}}}},"delete":{"tags":["Team Management"],"operationId":"auto_delete_api_v1_accounts_account_id_wfm_queues_id","summary":"Delete queues","description":"Deletes the queue identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Success (no content)"},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/wfm/adherence":{"get":{"tags":["Team Management"],"operationId":"auto_get_api_v1_accounts_account_id_wfm_adherence","summary":"List adherence","description":"Returns the list of adherence visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"account_user_id":{"type":"integer"},"date":{"type":"string","format":"date"},"online_seconds":{"type":"integer"},"busy_seconds":{"type":"integer"},"offline_seconds":{"type":"integer"},"productive_seconds":{"type":"integer"},"by_status":{"type":"object","additionalProperties":true,"description":"Per-status breakdown keyed by availability/Team Management status key (seconds and counts per status)."},"timed_breaks_count":{"type":"integer"},"within_limit_count":{"type":"integer"},"breaches_count":{"type":"integer"},"adherence_pct":{"type":"number"},"schedule_adherence_pct":{"type":"number"},"occupancy_pct":{"type":"number"},"logins_count":{"type":"integer"},"logouts_count":{"type":"integer"},"sessions_count":{"type":"integer"},"first_login_at":{"type":["string","null"],"format":"date-time"},"last_logout_at":{"type":["string","null"],"format":"date-time"}}}}}},"example":{"payload":[{"id":1,"account_user_id":1,"date":"2026-01-15","online_seconds":60,"busy_seconds":60,"offline_seconds":60,"productive_seconds":60,"by_status":{},"timed_breaks_count":5,"within_limit_count":5,"breaches_count":5,"adherence_pct":12.5,"schedule_adherence_pct":12.5,"occupancy_pct":12.5,"logins_count":5,"logouts_count":5,"sessions_count":5,"first_login_at":"2026-01-15T10:30:00.000Z","last_logout_at":"2026-01-15T10:30:00.000Z"}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."}]}},"/api/v1/accounts/{account_id}/tasks/tasks/board":{"get":{"tags":["Tasks"],"operationId":"auto_get_api_v1_accounts_account_id_tasks_tasks_board","summary":"Get the tasks kanban board (first page per column)","description":"Scalable kanban payload: for every board column that has at least one matching task, returns the FIRST page of cards (ordered by position), plus the authoritative task count for the whole column and has_more. The board never loads a whole column at once — a column's \"load more\" reuses GET /tasks/tasks with status (or task_list_id), page and sort=position_asc. Columns are grouped by status (default) or by list when group_by=task_list_id. Honors the same filters as the task list (status, priority, assignee_id, team_id, label, due, overdue, visibility, period, q, custom_attributes, archived). The per_page query parameter sizes each column's first page (default 25, capped for safety). Requires task read authorization (administrator or agent).","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Per-column board (only columns with matching tasks appear).","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"columns":{"type":"array","description":"One entry per board column that has at least one matching task.","items":{"type":"object","properties":{"column_key":{"type":"string","description":"The column key — the status label (backlog, todo, in_progress, in_review, done, cancelled) when grouped by status, or the list id (null for unlisted tasks) when grouped by task_list_id.","example":"todo"},"count":{"type":"integer","description":"Authoritative number of matching tasks in this column (the whole column, not just the loaded page).","example":484},"has_more":{"type":"boolean","description":"Whether more pages of cards exist beyond the returned first page.","example":true},"items":{"type":"array","description":"First page of task cards for this column, ordered by position. Each card is the shared task shape documented on the task CRUD endpoints.","items":{"type":"object","additionalProperties":true,"description":"A task card (same payload as GET /tasks/tasks/{id}).","example":{"id":9001,"title":"Call the client","status":"todo","priority":"high","position":0,"task_list_id":7,"due_at":"2026-07-20T12:00:00.000Z","overdue":false,"blocked":false,"sla_status":null,"subtasks_count":2,"assignees":[]}}}}}}}}}},"example":{"payload":{"columns":[{"column_key":"todo","count":484,"has_more":true,"items":[{"id":9001,"title":"Call the client","status":"todo","priority":"high","position":0,"task_list_id":7,"due_at":"2026-07-20T12:00:00.000Z","overdue":false,"blocked":false,"sla_status":null,"subtasks_count":2,"assignees":[]}]}]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"group_by","in":"query","required":false,"description":"Board column grouping. status (default) uses the workflow enum columns; task_list_id uses one column per list.","schema":{"type":"string","enum":["status","task_list_id"],"example":"status"}},{"name":"per_page","in":"query","required":false,"description":"Page size for each column's first page (default 25, capped for safety).","schema":{"type":"integer","example":25}},{"name":"archived","in":"query","required":false,"description":"When true, the board reflects the archived (soft-deleted) bin instead of the active tasks.","schema":{"type":"boolean","example":false}}]}},"/api/v1/accounts/{account_id}/tasks/templates/library":{"get":{"tags":["Tasks"],"operationId":"auto_get_api_v1_accounts_account_id_tasks_templates_library","summary":"Library templates","description":"Performs the library operation on the targeted template resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"subtasks_count":{"type":"integer"},"custom_attributes_count":{"type":"integer"}}}}}},"example":{"payload":[{"id":1,"name":"Sample Name","description":"A short description.","subtasks_count":5,"custom_attributes_count":5}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/tasks/templates/seed":{"post":{"tags":["Tasks"],"operationId":"auto_post_api_v1_accounts_account_id_tasks_templates_seed","summary":"Seed templates","description":"Performs the seed operation on the targeted template resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"blueprint":{"type":"object","additionalProperties":true,"description":"Task blueprint prefill payload. Known keys: title, description, priority, task_list_id, labels, custom_attributes, subtasks."},"active":{"type":"boolean"},"position":{"type":"integer"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}}},"example":{"payload":[{"id":1,"account_id":1,"name":"Sample Name","description":"A short description.","blueprint":{},"active":true,"position":1,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"template_id":{"type":"integer"}}},"example":{"template_id":1}}}}}},"/api/v1/accounts/{account_id}/catalog/categories/{id}/reposition":{"patch":{"tags":["Catalog"],"operationId":"auto_patch_api_v1_accounts_account_id_catalog_categories_id_reposition","summary":"Reposition categories","description":"Performs the reposition operation on the targeted category resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"parent_id":{"type":"integer"},"name":{"type":"string"},"slug":{"type":"string"},"position":{"type":"integer"},"products_count":{"type":"integer"},"depth":{"type":"string"},"external_id":{"type":"integer"},"external_source":{"type":"string"},"additional_attributes":{"type":"object","additionalProperties":true,"description":"Channel- and source-specific metadata for this record (e.g. browser info, referer, social profile identifiers). The key set depends on the originating channel."},"archived_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}},"example":{"payload":{"id":1,"account_id":1,"parent_id":1,"name":"Sample Name","slug":"sample-slug","position":1,"products_count":5,"depth":"sample depth","external_id":1,"external_source":"sample external source","additional_attributes":{},"archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"position":{"type":"integer"}}},"example":{"position":1}}}}}},"/api/v1/accounts/{account_id}/catalog/categories/{id}/restore":{"post":{"tags":["Catalog"],"operationId":"auto_post_api_v1_accounts_account_id_catalog_categories_id_restore","summary":"Restore categories","description":"Performs the restore operation on the targeted category resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"parent_id":{"type":"integer"},"name":{"type":"string"},"slug":{"type":"string"},"position":{"type":"integer"},"products_count":{"type":"integer"},"depth":{"type":"string"},"external_id":{"type":"integer"},"external_source":{"type":"string"},"additional_attributes":{"type":"object","additionalProperties":true,"description":"Channel- and source-specific metadata for this record (e.g. browser info, referer, social profile identifiers). The key set depends on the originating channel."},"archived_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}},"example":{"payload":{"id":1,"account_id":1,"parent_id":1,"name":"Sample Name","slug":"sample-slug","position":1,"products_count":5,"depth":"sample depth","external_id":1,"external_source":"sample external source","additional_attributes":{},"archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/catalog/categories/{id}/purge":{"delete":{"tags":["Catalog"],"operationId":"auto_delete_api_v1_accounts_account_id_catalog_categories_id_purge","summary":"Purge categories","description":"Performs the purge operation on the targeted category resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}},"example":{"error":"sample error"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/catalog/categories/bulk_archive":{"post":{"tags":["Catalog"],"operationId":"auto_post_api_v1_accounts_account_id_catalog_categories_bulk_archive","summary":"Bulk archive categories","description":"Performs the bulk archive operation on the targeted category resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"archived_ids":{"type":"array","items":{"type":"integer"}}}}}},"example":{"payload":{"archived_ids":[1]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"category_ids":{"type":"array","items":{"type":"integer"}}}},"example":{"category_ids":[1]}}}}}},"/api/v1/accounts/{account_id}/catalog/categories/bulk_restore":{"post":{"tags":["Catalog"],"operationId":"auto_post_api_v1_accounts_account_id_catalog_categories_bulk_restore","summary":"Bulk restore categories","description":"Performs the bulk restore operation on the targeted category resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"restored_ids":{"type":"array","items":{"type":"integer"}}}}}},"example":{"payload":{"restored_ids":[1]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"category_ids":{"type":"array","items":{"type":"integer"}}}},"example":{"category_ids":[1]}}}}}},"/api/v1/accounts/{account_id}/catalog/categories/bulk_purge":{"post":{"tags":["Catalog"],"operationId":"auto_post_api_v1_accounts_account_id_catalog_categories_bulk_purge","summary":"Bulk purge categories","description":"Performs the bulk purge operation on the targeted category resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"purged_ids":{"type":"array","items":{"type":"integer"}},"failed_ids":{"type":"array","items":{"type":"integer"}}}},"meta":{"type":"object","properties":{"purged":{"type":"integer"},"failed":{"type":"integer"},"failed_ids":{"type":"array","items":{"type":"integer"}}}}}},"example":{"payload":{"purged_ids":[1],"failed_ids":[1]},"meta":{"purged":1,"failed":1,"failed_ids":[1]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"category_ids":{"type":"array","items":{"type":"integer"}}}},"example":{"category_ids":[1]}}}}}},"/api/v1/accounts/{account_id}/catalog/categories/bulk_reparent":{"post":{"tags":["Catalog"],"operationId":"auto_post_api_v1_accounts_account_id_catalog_categories_bulk_reparent","summary":"Bulk reparent categories","description":"Performs the bulk reparent operation on the targeted category resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"moved_ids":{"type":"array","items":{"type":"integer"}},"failed_ids":{"type":"array","items":{"type":"integer"}},"parent_id":{"type":["integer","null"]}}},"meta":{"type":"object","properties":{"moved":{"type":"integer"},"failed":{"type":"integer"},"failed_ids":{"type":"array","items":{"type":"integer"}}}}}},"example":{"payload":{"moved_ids":[1],"failed_ids":[1],"parent_id":1},"meta":{"moved":1,"failed":1,"failed_ids":[1]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"parent_id":{"type":"integer"},"category_ids":{"type":"array","items":{"type":"integer"}}}},"example":{"parent_id":1,"category_ids":[1]}}}}}},"/api/v1/accounts/{account_id}/catalog/products/{id}/restore":{"post":{"tags":["Catalog"],"operationId":"auto_post_api_v1_accounts_account_id_catalog_products_id_restore","summary":"Restore products","description":"Performs the restore operation on the targeted product resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"kind":{"type":"string","enum":["product","service"]},"status":{"type":"string","enum":["draft","active","archived"]},"slug":{"type":"string"},"position":{"type":"integer"},"external_id":{"type":"integer"},"external_source":{"type":"string"},"external_url":{"type":"string"},"condition":{"type":"string"},"brand":{"type":"string"},"catalog_category_id":{"type":"integer"},"default_variant_id":{"type":"integer"},"variants_count":{"type":"integer"},"images_count":{"type":"integer"},"attachments_count":{"type":"integer"},"checklist_progress":{"type":"object","properties":{"done":{"type":"string"},"total":{"type":"number"}}},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"additional_attributes":{"type":"object","additionalProperties":true,"description":"Channel- and source-specific metadata for this record (e.g. browser info, referer, social profile identifiers). The key set depends on the originating channel."},"archived_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"category_name":{"type":["string","null"]},"variants":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"catalog_product_id":{"type":"integer"},"sku":{"type":"string"},"name":{"type":"string"},"price":{"type":"number"},"currency":{"type":"string"},"compare_at_price":{"type":"number"},"track_inventory":{"type":"string"},"stock_quantity":{"type":"string"},"barcode":{"type":"string"},"position":{"type":"integer"},"options":{"type":"string"},"default":{"type":"integer"},"image_id":{"type":"integer"},"external_id":{"type":"integer"},"external_source":{"type":"string"},"retailer_id":{"type":"integer"},"meta_validation":{"type":"object","properties":{"set":{"type":"object","properties":{"merge":{"type":"boolean"},"source_name":{"type":"string"}}}}},"available":{"type":"boolean"},"image":{"type":"string"},"prices":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"currency":{"type":"string"},"amount":{"type":"number"},"compare_at_amount":{"type":"number"}}}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}},"images":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"catalog_product_id":{"type":"integer"},"primary":{"type":"string"},"position":{"type":"integer"},"alt_text":{"type":"string"},"file_url":{"type":"string"},"thumb_url":{"type":"string"},"media_deleted":{"type":["boolean","null"]},"deleted_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}}}}},"example":{"payload":{"id":1,"account_id":1,"name":"Sample Name","description":"A short description.","kind":"product","status":"draft","slug":"sample-slug","position":1,"external_id":1,"external_source":"sample external source","external_url":"https://example.com/resource","condition":"sample condition","brand":"sample brand","catalog_category_id":1,"default_variant_id":1,"variants_count":5,"images_count":5,"attachments_count":5,"checklist_progress":{"done":"sample done","total":149.9},"custom_attributes":{},"additional_attributes":{},"archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","category_name":"sample category name","variants":[{"id":1,"account_id":1,"catalog_product_id":1,"sku":"sample sku","name":"Sample Name","price":149.9,"currency":"BRL","compare_at_price":149.9,"track_inventory":"sample track inventory","stock_quantity":"sample stock quantity","barcode":"sample barcode","position":1,"options":"sample options","default":1,"image_id":1,"external_id":1,"external_source":"sample external source","retailer_id":1,"meta_validation":{"set":{"merge":true,"source_name":"sample source name"}},"available":true,"image":"sample image","prices":[{"id":1,"currency":"BRL","amount":149.9,"compare_at_amount":149.9}],"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}],"images":[{"id":1,"account_id":1,"catalog_product_id":1,"primary":"sample primary","position":1,"alt_text":"sample alt text","file_url":"https://example.com/resource","thumb_url":"https://example.com/resource","media_deleted":true,"deleted_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/catalog/products/{id}/events":{"get":{"tags":["Catalog"],"operationId":"auto_get_api_v1_accounts_account_id_catalog_products_id_events","summary":"Events products","description":"Performs the events operation on the targeted product resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"catalog_product_id":{"type":"integer"},"event_type":{"type":"string","enum":["created","updated","archived","checklist_completed","attachment_added","restored","variant_added","variant_removed","stock_adjusted","price_changed"],"description":"What happened to the product."},"user_id":{"type":"integer"},"user":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"}}},"metadata":{"type":"object","additionalProperties":true,"description":"Free-form metadata bag; the key set depends on the record and context."},"created_at":{"type":"string","format":"date-time"}}}},"meta":{"type":"object","properties":{"count":{"type":"integer"},"current_page":{"type":"string"},"total_pages":{"type":"string"},"has_more":{"type":"boolean"}}}}},"example":{"payload":[{"id":1,"catalog_product_id":1,"event_type":"created","user_id":1,"user":{"id":1,"name":"Sample Name"},"metadata":{},"created_at":"2026-01-15T10:30:00.000Z"}],"meta":{"count":5,"current_page":"sample current page","total_pages":"sample total pages","has_more":true}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page of product events.","schema":{"type":"integer","default":1},"example":1}]}},"/api/v1/accounts/{account_id}/catalog/products/{id}/where_used":{"get":{"tags":["Catalog"],"operationId":"auto_get_api_v1_accounts_account_id_catalog_products_id_where_used","summary":"Where used products","description":"Performs the where used operation on the targeted product resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"deals_count":{"type":"integer"},"charges_count":{"type":"integer"}}}}},"example":{"payload":{"deals_count":5,"charges_count":5}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/catalog/products/bulk_restore":{"post":{"tags":["Catalog"],"operationId":"auto_post_api_v1_accounts_account_id_catalog_products_bulk_restore","summary":"Bulk restore products","description":"Performs the bulk restore operation on the targeted product resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"restored_ids":{"type":"array","items":{"type":"integer"}}}}}},"example":{"payload":{"restored_ids":[1]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"product_ids":{"type":"array","items":{"type":"integer"}}}},"example":{"product_ids":[1]}}}}}},"/api/v1/accounts/{account_id}/catalog/products/bulk_categorize":{"post":{"tags":["Catalog"],"operationId":"auto_post_api_v1_accounts_account_id_catalog_products_bulk_categorize","summary":"Bulk categorize products","description":"Performs the bulk categorize operation on the targeted product resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"moved_ids":{"type":"array","items":{"type":"integer"}},"failed_ids":{"type":"array","items":{"type":"integer"}},"catalog_category_id":{"type":["integer","null"]},"category_name":{"type":["string","null"]}}}}},"example":{"payload":{"moved_ids":[1],"failed_ids":[1],"catalog_category_id":1,"category_name":"sample category name"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"catalog_category_id":{"type":"integer"},"product_ids":{"type":"array","items":{"type":"integer"}}}},"example":{"catalog_category_id":1,"product_ids":[1]}}}}}},"/api/v1/accounts/{account_id}/catalog/products/{product_id}/images/{id}/set_primary":{"patch":{"tags":["Catalog"],"operationId":"auto_patch_api_v1_accounts_account_id_catalog_products_product_id_images_id_set_primary","summary":"Set primary images","description":"Performs the set primary operation on the targeted image resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"catalog_product_id":{"type":"integer"},"primary":{"type":"string"},"position":{"type":"integer"},"alt_text":{"type":"string"},"file_url":{"type":"string"},"thumb_url":{"type":"string"},"media_deleted":{"type":["boolean","null"]},"deleted_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}},"example":{"payload":{"id":1,"account_id":1,"catalog_product_id":1,"primary":"sample primary","position":1,"alt_text":"sample alt text","file_url":"https://example.com/resource","thumb_url":"https://example.com/resource","media_deleted":true,"deleted_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/catalog/products/{product_id}/images":{"get":{"tags":["Catalog"],"operationId":"auto_get_api_v1_accounts_account_id_catalog_products_product_id_images","summary":"List images","description":"Returns the list of images visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"catalog_product_id":{"type":"integer"},"primary":{"type":"string"},"position":{"type":"integer"},"alt_text":{"type":"string"},"file_url":{"type":"string"},"thumb_url":{"type":"string"},"media_deleted":{"type":["boolean","null"]},"deleted_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}}},"example":{"payload":[{"id":1,"account_id":1,"catalog_product_id":1,"primary":"sample primary","position":1,"alt_text":"sample alt text","file_url":"https://example.com/resource","thumb_url":"https://example.com/resource","media_deleted":true,"deleted_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."}]},"post":{"tags":["Catalog"],"operationId":"auto_post_api_v1_accounts_account_id_catalog_products_product_id_images","summary":"Create images","description":"Creates a new image from the request payload. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"catalog_product_id":{"type":"integer"},"primary":{"type":"string"},"position":{"type":"integer"},"alt_text":{"type":"string"},"file_url":{"type":"string"},"thumb_url":{"type":"string"},"media_deleted":{"type":["boolean","null"]},"deleted_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}},"example":{"payload":{"id":1,"account_id":1,"catalog_product_id":1,"primary":"sample primary","position":1,"alt_text":"sample alt text","file_url":"https://example.com/resource","thumb_url":"https://example.com/resource","media_deleted":true,"deleted_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"image":{"type":"object","properties":{"file":{"type":"string"},"alt_text":{"type":"string"},"position":{"type":"integer"},"primary":{"type":"string","enum":["cloud","web"]}}}},"required":["image"]},"example":{"image":{"file":"sample file","alt_text":"sample alt text","position":1,"primary":"cloud"}}}}}}},"/api/v1/accounts/{account_id}/catalog/products/{product_id}/images/{id}":{"delete":{"tags":["Catalog"],"operationId":"auto_delete_api_v1_accounts_account_id_catalog_products_product_id_images_id","summary":"Delete images","description":"Deletes the image identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Success (no content)"},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/catalog/products/{product_id}/attachments":{"get":{"tags":["Catalog"],"operationId":"auto_get_api_v1_accounts_account_id_catalog_products_product_id_attachments","summary":"List attachments","description":"Returns the list of attachments visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"catalog_product_id":{"type":"integer"},"file_name":{"type":"string"},"file_type":{"type":"string","enum":["image","audio","video","file","location","fallback","share","story_mention","contact","ig_reel","ig_post","ig_story","embed"],"description":"Kind of the message attachment."},"content_type":{"type":"string"},"byte_size":{"type":"string"},"file_url":{"type":"string"},"thumb_url":{"type":"string"},"media_deleted":{"type":["boolean","null"]},"deleted_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"integer"}}}}}},"example":{"payload":[{"id":1,"account_id":1,"catalog_product_id":1,"file_name":"sample file name","file_type":"image","content_type":"sample content type","byte_size":"sample byte size","file_url":"https://example.com/resource","thumb_url":"https://example.com/resource","media_deleted":true,"deleted_at":"2026-01-15T10:30:00.000Z","created_at":1}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."}]},"post":{"tags":["Catalog"],"operationId":"auto_post_api_v1_accounts_account_id_catalog_products_product_id_attachments","summary":"Create attachments","description":"Creates a new attachment from the request payload. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"catalog_product_id":{"type":"integer"},"file_name":{"type":"string"},"file_type":{"type":"string","enum":["image","audio","video","file","location","fallback","share","story_mention","contact","ig_reel","ig_post","ig_story","embed"],"description":"The high-level media class of an attachment, derived from its content type."},"content_type":{"type":"string"},"byte_size":{"type":"string"},"file_url":{"type":"string"},"thumb_url":{"type":"string"},"media_deleted":{"type":["boolean","null"]},"deleted_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"integer"}}}}},"example":{"payload":{"id":1,"account_id":1,"catalog_product_id":1,"file_name":"sample file name","file_type":"image","content_type":"sample content type","byte_size":"sample byte size","file_url":"https://example.com/resource","thumb_url":"https://example.com/resource","media_deleted":true,"deleted_at":"2026-01-15T10:30:00.000Z","created_at":1}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"attachment":{"type":"object","properties":{"file":{"type":"string"}}}},"required":["attachment"]},"example":{"attachment":{"file":"sample file"}}}}}}},"/api/v1/accounts/{account_id}/catalog/products/{product_id}/attachments/{id}":{"delete":{"tags":["Catalog"],"operationId":"auto_delete_api_v1_accounts_account_id_catalog_products_product_id_attachments_id","summary":"Delete attachments","description":"Deletes the attachment identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Success (no content)"},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/catalog/products/{product_id}/checklist_items/{id}/toggle":{"patch":{"tags":["Catalog"],"operationId":"auto_patch_api_v1_accounts_account_id_catalog_products_product_id_checklist_items_id_toggle","summary":"Toggle checklist items","description":"Performs the toggle operation on the targeted checklist item resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The toggled checklist item.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer","example":42},"account_id":{"type":"integer","example":1},"record_type":{"type":"string","example":"Catalog::Product","description":"Polymorphic owner type.","enum":["Catalog::Product"]},"record_id":{"type":"integer","example":88},"title":{"type":"string","example":"Confirmar disponibilidade do produto"},"completed":{"type":"boolean","example":true},"completed_at":{"type":["integer","null"],"description":"Epoch seconds; null when not completed.","example":1768473000},"completed_by_id":{"type":["integer","null"],"example":7},"assignee_id":{"type":["integer","null"],"example":7},"due_on":{"type":["string","null"],"format":"date","example":"2026-01-20"},"position":{"type":"integer","example":1},"assignee":{"type":["object","null"],"description":"Present only when an assignee is set (api/v1/models/agent partial).","properties":{"id":{"type":"integer","example":7},"account_id":{"type":"integer","example":1},"availability_status":{"type":"string","example":"online","enum":["online","offline","busy"],"description":"Realtime availability. Contacts report online/offline (presence-based); agents/users additionally report busy (their configured availability)."},"auto_offline":{"type":"boolean","example":true},"confirmed":{"type":"boolean","example":true},"email":{"type":"string","example":"agent@example.com"},"available_name":{"type":"string","example":"Ana"},"name":{"type":"string","example":"Ana Souza"},"role":{"type":"string","example":"agent","enum":["agent","administrator"],"description":"Account role of the assigned agent."},"thumbnail":{"type":"string","example":"https://cdn.example.com/avatars/7.png"}}},"created_at":{"type":"integer","description":"Epoch seconds.","example":1768470000},"updated_at":{"type":"integer","description":"Epoch seconds.","example":1768473000}}},"example":{"id":42,"account_id":1,"record_type":"Catalog::Product","record_id":88,"title":"Confirmar disponibilidade do produto","completed":true,"completed_at":1768473000,"completed_by_id":7,"assignee_id":7,"due_on":"2026-01-20","position":1,"assignee":{"id":7,"account_id":1,"availability_status":"online","auto_offline":true,"confirmed":true,"email":"agent@example.com","available_name":"Ana","name":"Ana Souza","role":"agent","thumbnail":"https://cdn.example.com/avatars/7.png"},"created_at":1768470000,"updated_at":1768473000}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/catalog/products/{product_id}/checklist_items/{id}/reposition":{"patch":{"tags":["Catalog"],"operationId":"auto_patch_api_v1_accounts_account_id_catalog_products_product_id_checklist_items_id_reposition","summary":"Move a product checklist item to a new position","description":"Writes the submitted `position` onto the checklist item and lets the model renumber the surrounding items of the same product. The action answers `200 OK` with an EMPTY body — no JSON is produced, so a client should treat a 2xx as success and re-read the checklist collection if it needs the resulting order. Requires update permission on the parent product.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Position applied. Empty body — nothing is rendered."},"401":{"description":"Unauthorized"},"404":{"description":"No such product or checklist item in this account."},"403":{"description":"The current user may not update this product."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"position":{"type":"integer"}}},"example":{"position":1}}}}}},"/api/v1/accounts/{account_id}/catalog/products/{product_id}/checklist_items":{"get":{"tags":["Catalog"],"operationId":"auto_get_api_v1_accounts_account_id_catalog_products_product_id_checklist_items","summary":"List checklist items","description":"Returns the list of checklist items visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"record_type":{"type":"string","enum":["Catalog::Product"],"description":"Polymorphic parent type of the checklist item."},"record_id":{"type":"integer"},"title":{"type":"string"},"completed":{"type":"string"},"completed_at":{"type":["integer","null"]},"completed_by_id":{"type":"integer"},"assignee_id":{"type":"integer"},"due_on":{"type":"string"},"position":{"type":"integer"},"assignee":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":["integer","null"]},"account_user_id":{"type":["integer","null"]},"availability_status":{"type":"string","enum":["online","offline","busy"],"description":"Realtime availability. Contacts report online/offline (presence-based); agents/users additionally report busy (their configured availability)."},"auto_offline":{"type":"boolean"},"confirmed":{"type":"boolean"},"email":{"type":"string","format":"email"},"provider":{"type":"string","enum":["email","google_oauth2","saml"],"description":"Authentication provider the user signed up through."},"available_name":{"type":"string"},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"name":{"type":"string"},"role":{"type":"string","enum":["agent","administrator"],"description":"Account role of the assigned agent."},"outbound_agent_name_header_policy":{"type":["string","null"]},"thumbnail":{"type":"string"},"custom_role_id":{"type":["integer","null"]},"access_role_id":{"type":["integer","null"]}}},"created_at":{"type":"integer"},"updated_at":{"type":"integer"}}}},"example":[{"id":1,"account_id":1,"record_type":"Catalog::Product","record_id":1,"title":"Sample title","completed":"sample completed","completed_at":1,"completed_by_id":1,"assignee_id":1,"due_on":"sample due on","position":1,"assignee":{"id":1,"account_id":1,"account_user_id":1,"availability_status":"online","auto_offline":true,"confirmed":true,"email":"agent@example.com","provider":"email","available_name":"sample available name","custom_attributes":{},"name":"Sample Name","role":"agent","outbound_agent_name_header_policy":"sample outbound agent name header policy","thumbnail":"sample thumbnail","custom_role_id":1,"access_role_id":1},"created_at":1,"updated_at":1}]}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."}]},"post":{"tags":["Catalog"],"operationId":"auto_post_api_v1_accounts_account_id_catalog_products_product_id_checklist_items","summary":"Create checklist items","description":"Creates a new checklist item from the request payload. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"record_type":{"type":"string","enum":["Catalog::Product"],"description":"Polymorphic parent type of the checklist item."},"record_id":{"type":"integer"},"title":{"type":"string"},"completed":{"type":"string"},"completed_at":{"type":["integer","null"]},"completed_by_id":{"type":"integer"},"assignee_id":{"type":"integer"},"due_on":{"type":"string"},"position":{"type":"integer"},"assignee":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":["integer","null"]},"account_user_id":{"type":["integer","null"]},"availability_status":{"type":"string","enum":["online","offline","busy"],"description":"Realtime availability. Contacts report online/offline (presence-based); agents/users additionally report busy (their configured availability)."},"auto_offline":{"type":"boolean"},"confirmed":{"type":"boolean"},"email":{"type":"string","format":"email"},"provider":{"type":"string","enum":["email","google_oauth2","saml"],"description":"Authentication provider the user signed up through."},"available_name":{"type":"string"},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"name":{"type":"string"},"role":{"type":"string","enum":["agent","administrator"],"description":"Account role of the assigned agent."},"outbound_agent_name_header_policy":{"type":["string","null"]},"thumbnail":{"type":"string"},"custom_role_id":{"type":["integer","null"]},"access_role_id":{"type":["integer","null"]}}},"created_at":{"type":"integer"},"updated_at":{"type":"integer"}}},"example":{"id":1,"account_id":1,"record_type":"Catalog::Product","record_id":1,"title":"Sample title","completed":"sample completed","completed_at":1,"completed_by_id":1,"assignee_id":1,"due_on":"sample due on","position":1,"assignee":{"id":1,"account_id":1,"account_user_id":1,"availability_status":"online","auto_offline":true,"confirmed":true,"email":"agent@example.com","provider":"email","available_name":"sample available name","custom_attributes":{},"name":"Sample Name","role":"agent","outbound_agent_name_header_policy":"sample outbound agent name header policy","thumbnail":"sample thumbnail","custom_role_id":1,"access_role_id":1},"created_at":1,"updated_at":1}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"checklist_item":{"type":"object","properties":{"title":{"type":"string"},"assignee_id":{"type":"integer"},"due_on":{"type":"string"}},"required":["title"]}},"required":["checklist_item"]},"example":{"checklist_item":{"title":"Sample title","assignee_id":1,"due_on":"sample due on"}}}}}}},"/api/v1/accounts/{account_id}/catalog/products/{product_id}/checklist_items/{id}":{"patch":{"tags":["Catalog"],"operationId":"auto_patch_api_v1_accounts_account_id_catalog_products_product_id_checklist_items_id","summary":"Update checklist items","description":"Updates the checklist item identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"record_type":{"type":"string","enum":["Catalog::Product"],"description":"Polymorphic parent type of the checklist item."},"record_id":{"type":"integer"},"title":{"type":"string"},"completed":{"type":"string"},"completed_at":{"type":["integer","null"]},"completed_by_id":{"type":"integer"},"assignee_id":{"type":"integer"},"due_on":{"type":"string"},"position":{"type":"integer"},"assignee":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":["integer","null"]},"account_user_id":{"type":["integer","null"]},"availability_status":{"type":"string","enum":["online","offline","busy"],"description":"Realtime availability. Contacts report online/offline (presence-based); agents/users additionally report busy (their configured availability)."},"auto_offline":{"type":"boolean"},"confirmed":{"type":"boolean"},"email":{"type":"string","format":"email"},"provider":{"type":"string","enum":["email","google_oauth2","saml"],"description":"Authentication provider the user signed up through."},"available_name":{"type":"string"},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"name":{"type":"string"},"role":{"type":"string","enum":["agent","administrator"],"description":"Account role of the assigned agent."},"outbound_agent_name_header_policy":{"type":["string","null"]},"thumbnail":{"type":"string"},"custom_role_id":{"type":["integer","null"]},"access_role_id":{"type":["integer","null"]}}},"created_at":{"type":"integer"},"updated_at":{"type":"integer"}}},"example":{"id":1,"account_id":1,"record_type":"Catalog::Product","record_id":1,"title":"Sample title","completed":"sample completed","completed_at":1,"completed_by_id":1,"assignee_id":1,"due_on":"sample due on","position":1,"assignee":{"id":1,"account_id":1,"account_user_id":1,"availability_status":"online","auto_offline":true,"confirmed":true,"email":"agent@example.com","provider":"email","available_name":"sample available name","custom_attributes":{},"name":"Sample Name","role":"agent","outbound_agent_name_header_policy":"sample outbound agent name header policy","thumbnail":"sample thumbnail","custom_role_id":1,"access_role_id":1},"created_at":1,"updated_at":1}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"checklist_item":{"type":"object","properties":{"title":{"type":"string"},"assignee_id":{"type":"integer"},"due_on":{"type":"string"}}}},"required":["checklist_item"]},"example":{"checklist_item":{"title":"Sample title","assignee_id":1,"due_on":"sample due on"}}}}}},"put":{"tags":["Catalog"],"operationId":"auto_put_api_v1_accounts_account_id_catalog_products_product_id_checklist_items_id","summary":"Update checklist items","description":"Updates the checklist item identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"record_type":{"type":"string","enum":["Catalog::Product"],"description":"Polymorphic parent type of the checklist item."},"record_id":{"type":"integer"},"title":{"type":"string"},"completed":{"type":"string"},"completed_at":{"type":["integer","null"]},"completed_by_id":{"type":"integer"},"assignee_id":{"type":"integer"},"due_on":{"type":"string"},"position":{"type":"integer"},"assignee":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":["integer","null"]},"account_user_id":{"type":["integer","null"]},"availability_status":{"type":"string","enum":["online","offline","busy"],"description":"Realtime availability. Contacts report online/offline (presence-based); agents/users additionally report busy (their configured availability)."},"auto_offline":{"type":"boolean"},"confirmed":{"type":"boolean"},"email":{"type":"string","format":"email"},"provider":{"type":"string","enum":["email","google_oauth2","saml"],"description":"Authentication provider the user signed up through."},"available_name":{"type":"string"},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"name":{"type":"string"},"role":{"type":"string","enum":["agent","administrator"],"description":"Account role of the assigned agent."},"outbound_agent_name_header_policy":{"type":["string","null"]},"thumbnail":{"type":"string"},"custom_role_id":{"type":["integer","null"]},"access_role_id":{"type":["integer","null"]}}},"created_at":{"type":"integer"},"updated_at":{"type":"integer"}}},"example":{"id":1,"account_id":1,"record_type":"Catalog::Product","record_id":1,"title":"Sample title","completed":"sample completed","completed_at":1,"completed_by_id":1,"assignee_id":1,"due_on":"sample due on","position":1,"assignee":{"id":1,"account_id":1,"account_user_id":1,"availability_status":"online","auto_offline":true,"confirmed":true,"email":"agent@example.com","provider":"email","available_name":"sample available name","custom_attributes":{},"name":"Sample Name","role":"agent","outbound_agent_name_header_policy":"sample outbound agent name header policy","thumbnail":"sample thumbnail","custom_role_id":1,"access_role_id":1},"created_at":1,"updated_at":1}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"checklist_item":{"type":"object","properties":{"title":{"type":"string"},"assignee_id":{"type":"integer"},"due_on":{"type":"string"}}}},"required":["checklist_item"]},"example":{"checklist_item":{"title":"Sample title","assignee_id":1,"due_on":"sample due on"}}}}}},"delete":{"tags":["Catalog"],"operationId":"auto_delete_api_v1_accounts_account_id_catalog_products_product_id_checklist_items_id","summary":"Delete checklist items","description":"Deletes the checklist item identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Success (no content)"},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/catalog/sync_sources/{sync_source_id}/webhook_deliveries/{id}/replay":{"post":{"tags":["Catalog"],"operationId":"auto_post_api_v1_accounts_account_id_catalog_sync_sources_sync_source_id_webhook_deliveries_id_replay","summary":"Replay webhook deliveries","description":"Performs the replay operation on the targeted webhook delivery resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"202":{"description":"Catalog-destination delivery reset and queued again under the same durable id.","content":{"application/json":{"schema":{"type":"object","required":["payload"],"properties":{"payload":{"type":"object","required":["delivery"],"properties":{"delivery":{"$ref":"#/components/schemas/webhook_delivery"}}}}},"example":{"payload":{"delivery":{"id":184,"delivery_id":"5b96d21d-6df7-4bb3-9fbf-254da374f234","event_name":"commerce_payment_confirmed","url":"https://erp.example.com/webhooks/commerce","status":"retrying","attempts":2,"manual_replays":1,"http_status":503,"response_body":"Service unavailable","last_error":"503 Service Unavailable","last_attempted_at":"2026-08-04T15:30:00.000Z","next_attempt_at":"2026-08-04T15:32:00.000Z","delivered_at":null,"created_at":"2026-08-04T15:28:00.000Z"}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"422":{"description":"The queue rejected the source-scoped replay."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"sync_source_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/catalog/sync_sources/{sync_source_id}/webhook_deliveries/bulk_replay":{"post":{"tags":["Catalog"],"operationId":"auto_post_api_v1_accounts_account_id_catalog_sync_sources_sync_source_id_webhook_deliveries_bulk_replay","summary":"Bulk replay webhook deliveries","description":"Performs the bulk replay operation on the targeted webhook delivery resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"processed_ids":{"type":"array","items":{"type":"integer"}},"failed_ids":{"type":"array","items":{"type":"integer"}}}}}},"example":{"payload":{"processed_ids":[1],"failed_ids":[1]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"202":{"description":"Per-delivery replay result for the selected catalog source, preserving partial failures.","content":{"application/json":{"schema":{"type":"object","required":["payload"],"properties":{"payload":{"type":"object","required":["processed_ids","failed_ids"],"properties":{"processed_ids":{"type":"array","items":{"type":"integer"},"example":[184]},"failed_ids":{"type":"array","items":{"type":"integer"},"example":[185]}}}}},"example":{"payload":{"processed_ids":[184],"failed_ids":[185]}}}}},"422":{"description":"No requested delivery could be queued, or the selection was empty or exceeded 500 unique ids."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"sync_source_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["ids"],"properties":{"ids":{"type":"array","minItems":1,"maxItems":500,"uniqueItems":true,"items":{"type":"integer","minimum":1},"example":[184,185]}}},"example":{"ids":[184,185]}}}}}},"/api/v1/accounts/{account_id}/catalog/sync_sources/{sync_source_id}/webhook_deliveries":{"get":{"tags":["Catalog"],"operationId":"auto_get_api_v1_accounts_account_id_catalog_sync_sources_sync_source_id_webhook_deliveries","summary":"List webhook deliveries","description":"Returns the list of webhook deliveries visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Page of durable deliveries for the selected generic catalog destination, without secret or payload content.","content":{"application/json":{"schema":{"type":"object","required":["meta","payload"],"properties":{"meta":{"type":"object","required":["count","current_page","total_pages","per_page"],"properties":{"count":{"type":"integer","example":31},"current_page":{"type":"integer","example":1},"total_pages":{"type":"integer","example":2},"per_page":{"type":"integer","example":25}}},"payload":{"type":"object","required":["deliveries"],"properties":{"deliveries":{"type":"array","items":{"$ref":"#/components/schemas/webhook_delivery"}}}}}},"example":{"meta":{"count":31,"current_page":1,"total_pages":2,"per_page":25},"payload":{"deliveries":[{"id":184,"delivery_id":"5b96d21d-6df7-4bb3-9fbf-254da374f234","event_name":"commerce_payment_confirmed","url":"https://erp.example.com/webhooks/commerce","status":"retrying","attempts":2,"manual_replays":1,"http_status":503,"response_body":"Service unavailable","last_error":"503 Service Unavailable","last_attempted_at":"2026-08-04T15:30:00.000Z","next_attempt_at":"2026-08-04T15:32:00.000Z","delivered_at":null,"created_at":"2026-08-04T15:28:00.000Z"}]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"sync_source_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"q","in":"query","required":false,"schema":{"type":"string"},"description":"Case-insensitive search across event name, destination URL and last error."},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["pending","delivering","retrying","delivered","failed"]}},{"name":"sort","in":"query","required":false,"schema":{"type":"string","enum":["created_at","last_attempted_at","attempts","status"],"default":"created_at"}},{"name":"direction","in":"query","required":false,"schema":{"type":"string","enum":["asc","desc"],"default":"desc"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1}},{"name":"per_page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":25}}]}},"/api/v1/accounts/{account_id}/catalog/sync_sources/{id}/oauth_authorize":{"post":{"tags":["Catalog"],"operationId":"auto_post_api_v1_accounts_account_id_catalog_sync_sources_id_oauth_authorize","summary":"Oauth authorize sync sources","description":"Performs the oauth authorize operation on the targeted sync source resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"authorize_url":{"type":"string"}}},"example":{"authorize_url":"https://example.com/resource"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/catalog/sync_sources/{id}/register_webhook":{"post":{"tags":["Catalog"],"operationId":"auto_post_api_v1_accounts_account_id_catalog_sync_sources_id_register_webhook","summary":"Register webhook sync sources","description":"Performs the register webhook operation on the targeted sync source resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"registered":{"type":"string"},"armed":{"type":"boolean"}}},{"type":"object","properties":{"error":{"type":"string"}}}]},"example":{"registered":"sample registered","armed":true}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/catalog/sync_sources/{id}/test_connection":{"post":{"tags":["Catalog"],"operationId":"auto_post_api_v1_accounts_account_id_catalog_sync_sources_id_test_connection","summary":"Test connection sync sources","description":"Performs the test connection operation on the targeted sync source resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Connection is valid for the saved connector. environment is present only for Hotmart; provider is present only for Kiwify.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","example":true},"environment":{"type":"string","enum":["production","sandbox"],"description":"Hotmart environment selected for this source.","example":"production"},"provider":{"type":"string","enum":["kiwify"],"description":"Present for Kiwify because it has no environment selector.","example":"kiwify"},"products_sample":{"type":"integer","description":"Products returned by the 1-item probe; zero in an empty catalog is still success.","example":3}}},"example":{"ok":true,"environment":"production","provider":"kiwify","products_sample":3}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/catalog/sync_sources/{id}/backfill_sales_preview":{"get":{"tags":["Catalog"],"operationId":"auto_get_api_v1_accounts_account_id_catalog_sync_sources_id_backfill_sales_preview","summary":"Backfill sales preview sync sources","description":"Performs the backfill sales preview operation on the targeted sync source resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Read-only preview page with existing Contact/Organization matches and the fail-closed local action for each sale.","content":{"application/json":{"schema":{"type":"object","required":["items","page_info","window","limits"],"properties":{"items":{"type":"array","items":{"type":"object","required":["provider_status","action","selectable"],"properties":{"external_id":{"type":["string","null"],"description":"Hotmart transaction or Kiwify sale identifier.","example":"HP16015479280295"},"provider_status":{"type":"string","example":"APPROVED"},"order_status":{"type":"string","enum":["pending","paid","overdue","refunded","canceled","failed"],"example":"paid"},"amount":{"type":"string","description":"Decimal amount in major units.","example":"497.00"},"currency":{"type":"string","example":"BRL"},"payment_method":{"type":["string","null"],"description":"Documented provider payment type/method preserved on the lifecycle event.","example":"CREDIT_CARD"},"occurred_at":{"type":["string","null"],"format":"date-time"},"ordered_at":{"type":["string","null"],"format":"date-time"},"product":{"type":"object","properties":{"id":{"type":["string","null"],"example":"1234567"},"name":{"type":["string","null"],"example":"Formação Completa"}}},"buyer":{"type":"object","description":"PII visible only to the authorized account administrator; never persisted by preview.","properties":{"name":{"type":["string","null"],"example":"Cliente Exemplo"},"email":{"type":["string","null"],"format":"email","example":"cliente@example.com"}}},"contact":{"type":["object","null"],"properties":{"id":{"type":"integer","example":91},"name":{"type":"string","example":"Cliente Exemplo"}}},"organization":{"type":["object","null"],"properties":{"id":{"type":"integer","example":12},"name":{"type":"string","example":"Empresa Exemplo"}}},"action":{"type":"string","enum":["create","update","repair","skip"],"example":"create"},"skip_reason":{"type":["string","null"],"enum":["missing_transaction","unsupported_status","missing_amount","missing_currency","missing_provider_timestamp","association_ambiguous","contact_not_found","contact_mismatch","organization_mismatch","live_event_already_recorded","newer_local_state","already_synchronized",null],"example":"contact_not_found"},"selectable":{"type":"boolean","example":true}}}},"page_info":{"type":"object","required":["has_next","page_size"],"properties":{"next_page_token":{"type":["string","null"]},"has_next":{"type":"boolean","example":false},"page_size":{"type":"integer","enum":[50,100],"example":50}}},"window":{"type":"object","required":["from","to"],"properties":{"from":{"type":"string","format":"date-time"},"to":{"type":"string","format":"date-time"}}},"limits":{"type":"object","required":["max_window_days","max_selected","max_scanned"],"properties":{"max_window_days":{"type":"integer","enum":[31,90],"example":31},"max_selected":{"type":"integer","enum":[500],"example":500},"max_scanned":{"type":"integer","enum":[5000],"example":5000}}}}},"example":{"items":[{"external_id":"HP16015479280295","provider_status":"APPROVED","order_status":"paid","amount":"497.00","currency":"BRL","payment_method":"CREDIT_CARD","occurred_at":"2026-01-15T10:30:00.000Z","ordered_at":"2026-01-15T10:30:00.000Z","product":{"id":"1234567","name":"Formação Completa"},"buyer":{"name":"Cliente Exemplo","email":"cliente@example.com"},"contact":{"id":91,"name":"Cliente Exemplo"},"organization":{"id":12,"name":"Empresa Exemplo"},"action":"create","skip_reason":"contact_not_found","selectable":true}],"page_info":{"next_page_token":"sample-token","has_next":false,"page_size":50},"window":{"from":"2026-01-15T10:30:00.000Z","to":"2026-01-15T10:30:00.000Z"},"limits":{"max_window_days":31,"max_selected":500,"max_scanned":5000}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"422":{"description":"Missing, invalid, or provider-oversized window, unsupported documented filter value, or an unsupported connector."},"502":{"description":"The selected provider could not be queried; no local state was written."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"start_date","in":"query","required":true,"schema":{"type":"string","format":"date"},"description":"First account-local calendar date in the bounded provider window."},{"name":"end_date","in":"query","required":true,"schema":{"type":"string","format":"date"},"description":"Last account-local calendar date; the inclusive window cannot exceed 31 days for Hotmart or 90 days for Kiwify."},{"name":"product_id","in":"query","required":false,"schema":{"type":"string","maxLength":200},"description":"Optional documented provider product filter."},{"name":"transaction_status","in":"query","required":false,"schema":{"type":"string","enum":["APPROVED","BLOCKED","CANCELLED","CHARGEBACK","COMPLETE","EXPIRED","NO_FUNDS","OVERDUE","PARTIALLY_REFUNDED","PRE_ORDER","PRINTED_BILLET","PROCESSING_TRANSACTION","PROTESTED","REFUNDED","STARTED","UNDER_ANALISYS","WAITING_PAYMENT","approved","authorized","chargedback","paid","pending","pending_refund","processing","refunded","refund_requested","refused","waiting_payment"]},"description":"Optional closed provider transaction-status filter; uppercase values are Hotmart and lowercase values are Kiwify."},{"name":"payment_method","in":"query","required":false,"schema":{"type":"string","enum":["BILLET","CASH_PAYMENT","CREDIT_CARD","DIRECT_BANK_TRANSFER","DIRECT_DEBIT","FINANCED_BILLET","FINANCED_INSTALLMENT","GOOGLE_PAY","HOTCARD","HYBRID","MANUAL_TRANSFER","PAYPAL","PAYPAL_INTERNACIONAL","PICPAY","PIX","SAMSUNG_PAY","WALLET","boleto","credit_card","pix"]},"description":"Optional closed payment filter; uppercase payment types are Hotmart and lowercase methods are Kiwify."},{"name":"affiliate_id","in":"query","required":false,"schema":{"type":"string","maxLength":200},"description":"Optional documented Kiwify affiliate identifier; omitted for Hotmart."},{"name":"page_token","in":"query","required":false,"schema":{"type":"string","maxLength":500},"description":"Opaque next-page token returned by the preceding preview page."}]}},"/api/v1/accounts/{account_id}/catalog/sync_sources/{id}/backfill_sales":{"post":{"tags":["Catalog"],"operationId":"auto_post_api_v1_accounts_account_id_catalog_sync_sources_id_backfill_sales","summary":"Backfill sales sync sources","description":"Performs the backfill sales operation on the targeted sync source resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"202":{"description":"Governed import enqueued, or the exact active request deduplicated. Poll run history for item failures, truncation and undo eligibility.","content":{"application/json":{"schema":{"type":"object","required":["run_id","duplicate"],"properties":{"run_id":{"type":"integer","description":"The catalog_sync_runs id created for this backfill.","example":501},"duplicate":{"type":"boolean","description":"True when the exact request was already pending/processing.","example":false}}},"example":{"run_id":501,"duplicate":false}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"409":{"description":"A different historical-sales import is already active for this account/source."},"422":{"description":"Missing/invalid/oversized window, empty/oversized selection, unsupported documented filter value, or a connector without documented history listing."},"502":{"description":"The import could not be queued because an infrastructure/provider boundary failed."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["start_date","end_date","only"],"properties":{"start_date":{"type":"string","format":"date","description":"First account-local calendar date in the bounded window.","example":"2026-01-01"},"end_date":{"type":"string","format":"date","description":"Last account-local calendar date; the inclusive window cannot exceed 31 days for Hotmart or 90 days for Kiwify.","example":"2026-01-31"},"only":{"type":"array","minItems":1,"maxItems":500,"uniqueItems":true,"description":"Explicit Hotmart transaction or Kiwify sale IDs selected from the read-only preview.","items":{"type":"string","minLength":1,"maxLength":200},"example":["HP16015479280295"]},"product_id":{"type":"string","maxLength":200,"description":"Optional documented provider product filter.","example":"1234567"},"transaction_status":{"type":"string","enum":["APPROVED","BLOCKED","CANCELLED","CHARGEBACK","COMPLETE","EXPIRED","NO_FUNDS","OVERDUE","PARTIALLY_REFUNDED","PRE_ORDER","PRINTED_BILLET","PROCESSING_TRANSACTION","PROTESTED","REFUNDED","STARTED","UNDER_ANALISYS","WAITING_PAYMENT","approved","authorized","chargedback","paid","pending","pending_refund","processing","refunded","refund_requested","refused","waiting_payment"],"description":"Optional closed provider transaction-status filter; uppercase values are Hotmart and lowercase values are Kiwify.","example":"APPROVED"},"payment_method":{"type":"string","enum":["BILLET","CASH_PAYMENT","CREDIT_CARD","DIRECT_BANK_TRANSFER","DIRECT_DEBIT","FINANCED_BILLET","FINANCED_INSTALLMENT","GOOGLE_PAY","HOTCARD","HYBRID","MANUAL_TRANSFER","PAYPAL","PAYPAL_INTERNACIONAL","PICPAY","PIX","SAMSUNG_PAY","WALLET","boleto","credit_card","pix"],"description":"Optional closed payment filter; uppercase payment types are Hotmart and lowercase methods are Kiwify.","example":"CREDIT_CARD"},"affiliate_id":{"type":"string","maxLength":200,"description":"Optional documented Kiwify affiliate identifier; omitted for Hotmart."}}},"example":{"start_date":"2026-01-01","end_date":"2026-01-31","only":["HP16015479280295"],"product_id":"1234567","transaction_status":"APPROVED","payment_method":"CREDIT_CARD","affiliate_id":"sample affiliate id"}}}}}},"/api/v1/accounts/{account_id}/catalog/sync_sources/{id}/undo_sales_backfill":{"post":{"tags":["Catalog"],"operationId":"auto_post_api_v1_accounts_account_id_catalog_sync_sources_id_undo_sales_backfill","summary":"Undo sales backfill sync sources","description":"Performs the undo sales backfill operation on the targeted sync source resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Every still-safe local row created by the run was removed atomically and the run was marked undone.","content":{"application/json":{"schema":{"type":"object","required":["run_id","undone_at"],"properties":{"run_id":{"type":"integer","example":501},"undone_at":{"type":"string","format":"date-time"}}},"example":{"run_id":501,"undone_at":"2026-01-15T10:30:00.000Z"}}}},"401":{"description":"Unauthorized"},"404":{"description":"The run does not belong to the current account and source."},"422":{"description":"The run is unfinished, already undone, lacks a creation ledger, or any created row was edited, linked, operated or credited."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["run_id"],"properties":{"run_id":{"type":"integer","minimum":1,"description":"A run belonging to this exact Hotmart or Kiwify source.","example":501}}},"example":{"run_id":501}}}}}},"/api/v1/accounts/{account_id}/catalog/sync_sources/{id}/subscriptions":{"get":{"tags":["Catalog"],"operationId":"auto_get_api_v1_accounts_account_id_catalog_sync_sources_id_subscriptions","summary":"Subscriptions sync sources","description":"Performs the subscriptions operation on the targeted sync source resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Hotmart subscriptions for this managed connector (upstream passthrough).","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","description":"Hotmart Payments API subscription objects (passthrough — see developers.hotmart.com).","items":{"type":"object","additionalProperties":true,"description":"One upstream Hotmart subscription object, forwarded verbatim."}},"page_info":{"type":"object","description":"Hotmart pagination block. Local code reads next_page_token for cursoring.","properties":{"next_page_token":{"type":["string","null"]}}}}},"example":{"items":[{}],"page_info":{"next_page_token":"sample-token"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/catalog/sync_sources/{id}/subscription_action":{"post":{"tags":["Catalog"],"operationId":"auto_post_api_v1_accounts_account_id_catalog_sync_sources_id_subscription_action","summary":"Subscription action sync sources","description":"Performs the subscription action operation on the targeted sync source resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Action performed (audited). `result` is the upstream Hotmart API response.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","example":true},"action":{"type":"string","enum":["cancel","reactivate","change_due_day"],"example":"cancel"},"subscriber_code":{"oneOf":[{"type":"string","example":"ABC123DE"},{"type":"array","items":{"type":"string"},"example":["ABC123DE"]}]},"result":{"type":"object","additionalProperties":true,"description":"Raw Hotmart response (passthrough)."}}},"example":{"ok":true,"action":"cancel","subscriber_code":"ABC123DE","result":{}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["subscriber_code","action_name"],"properties":{"subscriber_code":{"description":"A single subscriber code or an array (cancel/reactivate accept many).","oneOf":[{"type":"string","example":"ABC123DE"},{"type":"array","items":{"type":"string"},"example":["ABC123DE","FGH456IJ"]}]},"action_name":{"type":"string","enum":["cancel","reactivate","change_due_day"],"example":"cancel"},"send_mail":{"type":"boolean","description":"cancel only — notify the subscriber (default true).","example":true},"charge":{"type":"boolean","description":"reactivate only — charge immediately on reactivation (default false).","example":false},"due_day":{"type":"integer","description":"change_due_day only — the new billing day.","example":10}}},"example":{"subscriber_code":"ABC123DE","action_name":"cancel","send_mail":true,"charge":false,"due_day":10}}}}}},"/api/v1/accounts/{account_id}/catalog/sync_sources/{id}/refund":{"post":{"tags":["Catalog"],"operationId":"auto_post_api_v1_accounts_account_id_catalog_sync_sources_id_refund","summary":"Refund sync sources","description":"Performs the refund operation on the targeted sync source resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Refund submitted (audited). `result` is the upstream Hotmart API response.","content":{"application/json":{"schema":{"type":"object","properties":{"refunded":{"type":"boolean","example":true},"transaction":{"type":"string","example":"HP16015479280295"},"result":{"type":"object","additionalProperties":true,"description":"Raw Hotmart response (passthrough)."}}},"example":{"refunded":true,"transaction":"HP16015479280295","result":{}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["transaction"],"properties":{"transaction":{"type":"string","description":"The Hotmart sale transaction code to refund.","example":"HP16015479280295"}}},"example":{"transaction":"HP16015479280295"}}}}}},"/api/v1/accounts/{account_id}/catalog/sync_sources/{id}/coupons":{"get":{"tags":["Catalog"],"operationId":"auto_get_api_v1_accounts_account_id_catalog_sync_sources_id_coupons","summary":"Coupons sync sources","description":"Performs the coupons operation on the targeted sync source resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Hotmart coupons for this managed connector (upstream passthrough).","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","description":"Hotmart Products API coupon objects (passthrough — see developers.hotmart.com).","items":{"type":"object","additionalProperties":true,"description":"One upstream Hotmart coupon object, forwarded verbatim."}},"page_info":{"type":["object","null"],"description":"Hotmart pagination block (null when the upstream omits it).","properties":{"next_page_token":{"type":["string","null"]}}}}},"example":{"items":[{}],"page_info":{"next_page_token":"sample-token"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/catalog/sync_sources/{id}/coupon_action":{"post":{"tags":["Catalog"],"operationId":"auto_post_api_v1_accounts_account_id_catalog_sync_sources_id_coupon_action","summary":"Coupon action sync sources","description":"Performs the coupon action operation on the targeted sync source resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Coupon created or deleted (audited). Shape depends on `coupon_action`.","content":{"application/json":{"schema":{"type":"object","properties":{"created":{"type":"boolean","description":"Present on create.","example":true},"code":{"type":"string","description":"Present on create.","example":"BLACKFRIDAY"},"deleted":{"type":"boolean","description":"Present on delete.","example":true},"coupon_id":{"type":"string","description":"Present on delete.","example":"cpn_998877"},"result":{"type":"object","additionalProperties":true,"description":"Raw Hotmart response on create (passthrough)."}}},"example":{"created":true,"code":"BLACKFRIDAY","deleted":true,"coupon_id":"cpn_998877","result":{}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["coupon_action"],"properties":{"coupon_action":{"type":"string","enum":["create","delete"],"example":"create"},"product_id":{"type":"string","description":"Required for create.","example":"1234567"},"code":{"type":"string","description":"Coupon code (create).","example":"BLACKFRIDAY"},"discount":{"type":"number","description":"Percentage discount as a float (create).","example":0.15},"coupon_id":{"type":"string","description":"Required for delete.","example":"cpn_998877"}}},"example":{"coupon_action":"create","product_id":"1234567","code":"BLACKFRIDAY","discount":0.15,"coupon_id":"cpn_998877"}}}}}},"/api/v1/accounts/{account_id}/catalog/sync_sources/meta_catalogs":{"get":{"tags":["Catalog"],"operationId":"auto_get_api_v1_accounts_account_id_catalog_sync_sources_meta_catalogs","summary":"Meta catalogs sync sources","description":"Performs the meta catalogs operation on the targeted sync source resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"anyOf":[{"anyOf":[{"type":"object","properties":{"error":{"type":"string","example":"a WhatsApp Cloud inbox_id (or waba_id + graph_token) is required"}}},{"type":"object","properties":{"catalogs":{"type":"string"},"commerce":{"type":"string"}}}]},{"type":"object","properties":{"error":{"type":"string"}}}]},"example":{"error":"a WhatsApp Cloud inbox_id (or waba_id + graph_token) is required"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"inbox_id","in":"query","required":false,"description":"WhatsApp Cloud inbox whose own Graph token and WABA are reused to list the business catalogs — the zero-setup path. Either this or the explicit pair below must resolve, or the request returns 422.","schema":{"type":"integer"},"example":42},{"name":"graph_token","in":"query","required":false,"description":"Graph token to use instead of the inbox's own (needed when the inbox token lacks the catalog scope). Never stored.","schema":{"type":"string"},"example":"EAAG..."},{"name":"waba_id","in":"query","required":false,"description":"WhatsApp Business Account id to list catalogs from, when not taken from the inbox.","schema":{"type":"string"},"example":"109876543210987"}]}},"/api/v1/accounts/{account_id}/catalog/product_templates":{"get":{"tags":["Catalog"],"operationId":"auto_get_api_v1_accounts_account_id_catalog_product_templates","summary":"List product templates","description":"Returns the list of product templates visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"categories":{"type":"string"},"categories_count":{"type":"integer"},"custom_attributes_count":{"type":"integer"}}}}}},"example":{"payload":[{"id":1,"name":"Sample Name","description":"A short description.","categories":"sample categories","categories_count":5,"custom_attributes_count":5}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."}]},"post":{"tags":["Catalog"],"operationId":"auto_post_api_v1_accounts_account_id_catalog_product_templates","summary":"Create product templates","description":"Creates a new product template from the request payload. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"}}}}}},"example":{"payload":[{"id":1,"name":"Sample Name"}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"template_id":{"type":"integer"}}},"example":{"template_id":1}}}}}},"/api/v1/accounts/{account_id}/catalog/demo":{"delete":{"tags":["Catalog"],"operationId":"auto_delete_api_v1_accounts_account_id_catalog_demo","summary":"Delete demo","description":"Deletes the demo identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"202":{"description":"Success (no content)"},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]},"post":{"tags":["Catalog"],"operationId":"auto_post_api_v1_accounts_account_id_catalog_demo","summary":"Seed the demonstration catalog","description":"Enqueues the demo seeding job (sample categories, products, variants and asynchronous image fetches) and returns immediately with `202 Accepted` and an EMPTY body — the work happens off the request. Nothing is rendered, so the catalog list must be re-read (or awaited) for the seeded rows to appear. Requires permission to create catalog products.","security":[{"userApiKey":[]}],"responses":{"202":{"description":"Seeding job enqueued. Empty body — the demo rows appear asynchronously."},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"403":{"description":"The current user may not create catalog products."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/media_library/folders/{id}/reposition":{"patch":{"tags":["Media Library"],"operationId":"auto_patch_api_v1_accounts_account_id_media_library_folders_id_reposition","summary":"Reposition folders","description":"Performs the reposition operation on the targeted folder resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"parent_id":{"type":"integer"},"inbox_id":{"type":"integer"},"physical_inbox_id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"color":{"type":"string"},"kind":{"type":"string","enum":["user","system"]},"source_type":{"type":"string","enum":["inbox","contact","conversation","crm_pipeline","crm_stage","crm_item","task_list","task","catalog_category","catalog_product","internal_chat_channel","internal_chat_author","campaign","campaign_broadcast","contracts_contract","call","twilio_voice_call","whatsapp_call","macro","canned_response","ads_ad_account","conversations_root","inbox_no_contact","crm_root","tasks_root","catalog_root","internal_chat_root","uncategorized_root","campaigns_root","contracts_root","calls_root","macros_root","canned_root","ads_root"],"description":"Stable source binding for an automatic Library folder; null for user-created folders."},"source_id":{"type":"integer"},"position":{"type":"integer"},"depth":{"type":"string"},"assets_count":{"type":"integer"},"total_assets_count":{"type":"boolean"},"additional_attributes":{"type":"object","additionalProperties":true,"description":"Channel- and source-specific metadata for this record (e.g. browser info, referer, social profile identifiers). The key set depends on the originating channel."},"name_overridden":{"type":["boolean","null"]},"trash_reason":{"type":["string","null"],"enum":["source_deleted",null],"description":"Why the item entered Trash automatically; null when a user archived it."},"retired_source_type":{"type":["string","null"],"enum":["inbox","contact","conversation","crm_pipeline","crm_stage","crm_item","task_list","task","catalog_category","catalog_product","internal_chat_channel","internal_chat_author","campaign","campaign_broadcast","contracts_contract","call","twilio_voice_call","whatsapp_call","macro","canned_response","ads_ad_account","conversations_root","inbox_no_contact","crm_root","tasks_root","catalog_root","internal_chat_root","uncategorized_root","campaigns_root","contracts_root","calls_root","macros_root","canned_root","ads_root",null],"description":"Deleted source formerly represented by this Trash item; null for manual archival."},"source_deleted_at":{"type":["string","null"],"format":"date-time","description":"Time the permanently deleted source caused this item to enter Trash; null otherwise."},"has_children":{"type":"boolean"},"archived_at":{"type":"string","format":"date-time"},"created_at":{"type":"integer"},"updated_at":{"type":"integer"}}}}},"example":{"payload":{"id":1,"account_id":1,"parent_id":1,"inbox_id":1,"physical_inbox_id":1,"name":"Sample Name","description":"A short description.","color":"#1F93FF","kind":"user","source_type":"inbox","source_id":1,"position":1,"depth":"sample depth","assets_count":5,"total_assets_count":true,"additional_attributes":{},"name_overridden":true,"trash_reason":"source_deleted","retired_source_type":"inbox","source_deleted_at":"2026-01-15T10:30:00.000Z","has_children":true,"archived_at":"2026-01-15T10:30:00.000Z","created_at":1,"updated_at":1}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"position":{"type":"integer"}}},"example":{"position":1}}}}}},"/api/v1/accounts/{account_id}/media_library/folders/{id}/restore":{"post":{"tags":["Media Library"],"operationId":"auto_post_api_v1_accounts_account_id_media_library_folders_id_restore","summary":"Restore a folder from Trash","description":"Restores the archived folder. With include_contents=true, every archived descendant and media asset in the subtree is restored atomically and the original hierarchy is preserved. A folder retired after source deletion restores as a normal user folder because the automatic source no longer exists.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"parent_id":{"type":"integer"},"inbox_id":{"type":"integer"},"physical_inbox_id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"color":{"type":"string"},"kind":{"type":"string","enum":["user","system"]},"source_type":{"type":"string","enum":["inbox","contact","conversation","crm_pipeline","crm_stage","crm_item","task_list","task","catalog_category","catalog_product","internal_chat_channel","internal_chat_author","campaign","campaign_broadcast","contracts_contract","call","twilio_voice_call","whatsapp_call","macro","canned_response","ads_ad_account","conversations_root","inbox_no_contact","crm_root","tasks_root","catalog_root","internal_chat_root","uncategorized_root","campaigns_root","contracts_root","calls_root","macros_root","canned_root","ads_root"],"description":"Stable source binding for an automatic Library folder; null for user-created folders."},"source_id":{"type":"integer"},"position":{"type":"integer"},"depth":{"type":"string"},"assets_count":{"type":"integer"},"total_assets_count":{"type":"boolean"},"additional_attributes":{"type":"object","additionalProperties":true,"description":"Channel- and source-specific metadata for this record (e.g. browser info, referer, social profile identifiers). The key set depends on the originating channel."},"name_overridden":{"type":["boolean","null"]},"trash_reason":{"type":["string","null"],"enum":["source_deleted",null],"description":"Why the item entered Trash automatically; null when a user archived it."},"retired_source_type":{"type":["string","null"],"enum":["inbox","contact","conversation","crm_pipeline","crm_stage","crm_item","task_list","task","catalog_category","catalog_product","internal_chat_channel","internal_chat_author","campaign","campaign_broadcast","contracts_contract","call","twilio_voice_call","whatsapp_call","macro","canned_response","ads_ad_account","conversations_root","inbox_no_contact","crm_root","tasks_root","catalog_root","internal_chat_root","uncategorized_root","campaigns_root","contracts_root","calls_root","macros_root","canned_root","ads_root",null],"description":"Deleted source formerly represented by this Trash item; null for manual archival."},"source_deleted_at":{"type":["string","null"],"format":"date-time","description":"Time the permanently deleted source caused this item to enter Trash; null otherwise."},"has_children":{"type":"boolean"},"archived_at":{"type":"string","format":"date-time"},"created_at":{"type":"integer"},"updated_at":{"type":"integer"}}}}},"example":{"payload":{"id":1,"account_id":1,"parent_id":1,"inbox_id":1,"physical_inbox_id":1,"name":"Sample Name","description":"A short description.","color":"#1F93FF","kind":"user","source_type":"inbox","source_id":1,"position":1,"depth":"sample depth","assets_count":5,"total_assets_count":true,"additional_attributes":{},"name_overridden":true,"trash_reason":"source_deleted","retired_source_type":"inbox","source_deleted_at":"2026-01-15T10:30:00.000Z","has_children":true,"archived_at":"2026-01-15T10:30:00.000Z","created_at":1,"updated_at":1}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"include_contents":{"type":"boolean","default":false,"description":"Include every descendant folder and media asset in the lifecycle operation."}}},"example":{"include_contents":true}}}}}},"/api/v1/accounts/{account_id}/media_library/folders/{id}/purge":{"delete":{"tags":["Media Library"],"operationId":"auto_delete_api_v1_accounts_account_id_media_library_folders_id_purge","summary":"Permanently delete an archived folder structure","description":"Permanently deletes the archived folder. With include_contents=true, every folder in the subtree must be archived and all media rows must already have completed their reviewed durable storage deletion. The endpoint refuses a non-empty tree, so folder removal can never bypass storage checks.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Folder structure permanently deleted."},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"409":{"description":"The folder still contains media that has not completed permanent deletion."},"422":{"description":"The folder is active or is an automatic system folder."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"include_contents":{"type":"boolean","default":false,"description":"Include every descendant folder and media asset in the lifecycle operation."}}},"example":{"include_contents":true}}}}}},"/api/v1/accounts/{account_id}/media_library/folders/bulk_archive":{"post":{"tags":["Media Library"],"operationId":"auto_post_api_v1_accounts_account_id_media_library_folders_bulk_archive","summary":"Bulk archive folders","description":"Performs the bulk archive operation on the targeted folder resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"archived_ids":{"type":"array","items":{"type":"integer"}}}}}},"example":{"payload":{"archived_ids":[1]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"folder_ids":{"type":"array","items":{"type":"integer"}}}},"example":{"folder_ids":[1]}}}}}},"/api/v1/accounts/{account_id}/media_library/folders/bulk_restore":{"post":{"tags":["Media Library"],"operationId":"auto_post_api_v1_accounts_account_id_media_library_folders_bulk_restore","summary":"Bulk restore folders","description":"Performs the bulk restore operation on the targeted folder resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"restored_ids":{"type":"array","items":{"type":"integer"}}}}}},"example":{"payload":{"restored_ids":[1]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"folder_ids":{"type":"array","items":{"type":"integer"}},"include_contents":{"type":"string"}}},"example":{"folder_ids":[1],"include_contents":"sample include contents"}}}}}},"/api/v1/accounts/{account_id}/media_library/folders/bulk_purge":{"post":{"tags":["Media Library"],"operationId":"auto_post_api_v1_accounts_account_id_media_library_folders_bulk_purge","summary":"Bulk purge folders","description":"Performs the bulk purge operation on the targeted folder resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"purged_ids":{"type":"array","items":{"type":"integer"}},"failed_ids":{"type":"array","items":{"type":"integer"}}}}}},"example":{"payload":{"purged_ids":[1],"failed_ids":[1]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"folder_ids":{"type":"array","items":{"type":"integer"}},"include_contents":{"type":"string"}}},"example":{"folder_ids":[1],"include_contents":"sample include contents"}}}}}},"/api/v1/accounts/{account_id}/media_library/folders/bulk_reparent":{"post":{"tags":["Media Library"],"operationId":"auto_post_api_v1_accounts_account_id_media_library_folders_bulk_reparent","summary":"Bulk reparent folders","description":"Performs the bulk reparent operation on the targeted folder resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"moved_ids":{"type":"array","items":{"type":"integer"}},"failed_ids":{"type":"array","items":{"type":"integer"}},"parent_id":{"type":["integer","null"]}}}}},"example":{"payload":{"moved_ids":[1],"failed_ids":[1],"parent_id":1}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"parent_id":{"type":"integer"},"folder_ids":{"type":"array","items":{"type":"integer"}}}},"example":{"parent_id":1,"folder_ids":[1]}}}}}},"/api/v1/accounts/{account_id}/media_library/folders":{"get":{"tags":["Media Library"],"operationId":"auto_get_api_v1_accounts_account_id_media_library_folders","summary":"List folders","description":"Returns the list of folders visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"parent_id":{"type":"integer"},"inbox_id":{"type":"integer"},"physical_inbox_id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"color":{"type":"string"},"kind":{"type":"string","enum":["user","system"]},"source_type":{"type":"string","enum":["inbox","contact","conversation","crm_pipeline","crm_stage","crm_item","task_list","task","catalog_category","catalog_product","internal_chat_channel","internal_chat_author","campaign","campaign_broadcast","contracts_contract","call","twilio_voice_call","whatsapp_call","macro","canned_response","ads_ad_account","conversations_root","inbox_no_contact","crm_root","tasks_root","catalog_root","internal_chat_root","uncategorized_root","campaigns_root","contracts_root","calls_root","macros_root","canned_root","ads_root"],"description":"Stable source binding for an automatic Library folder; null for user-created folders."},"source_id":{"type":"integer"},"position":{"type":"integer"},"depth":{"type":"string"},"assets_count":{"type":"integer"},"total_assets_count":{"type":"boolean"},"additional_attributes":{"type":"object","additionalProperties":true,"description":"Channel- and source-specific metadata for this record (e.g. browser info, referer, social profile identifiers). The key set depends on the originating channel."},"name_overridden":{"type":["boolean","null"]},"trash_reason":{"type":["string","null"],"enum":["source_deleted",null],"description":"Why the item entered Trash automatically; null when a user archived it."},"retired_source_type":{"type":["string","null"],"enum":["inbox","contact","conversation","crm_pipeline","crm_stage","crm_item","task_list","task","catalog_category","catalog_product","internal_chat_channel","internal_chat_author","campaign","campaign_broadcast","contracts_contract","call","twilio_voice_call","whatsapp_call","macro","canned_response","ads_ad_account","conversations_root","inbox_no_contact","crm_root","tasks_root","catalog_root","internal_chat_root","uncategorized_root","campaigns_root","contracts_root","calls_root","macros_root","canned_root","ads_root",null],"description":"Deleted source formerly represented by this Trash item; null for manual archival."},"source_deleted_at":{"type":["string","null"],"format":"date-time","description":"Time the permanently deleted source caused this item to enter Trash; null otherwise."},"has_children":{"type":"boolean"},"archived_at":{"type":"string","format":"date-time"},"created_at":{"type":"integer"},"updated_at":{"type":"integer"}}}}}},"example":{"payload":[{"id":1,"account_id":1,"parent_id":1,"inbox_id":1,"physical_inbox_id":1,"name":"Sample Name","description":"A short description.","color":"#1F93FF","kind":"user","source_type":"inbox","source_id":1,"position":1,"depth":"sample depth","assets_count":5,"total_assets_count":true,"additional_attributes":{},"name_overridden":true,"trash_reason":"source_deleted","retired_source_type":"inbox","source_deleted_at":"2026-01-15T10:30:00.000Z","has_children":true,"archived_at":"2026-01-15T10:30:00.000Z","created_at":1,"updated_at":1}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."}]},"post":{"tags":["Media Library"],"operationId":"auto_post_api_v1_accounts_account_id_media_library_folders","summary":"Create folders","description":"Creates a new folder from the request payload. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"parent_id":{"type":"integer"},"inbox_id":{"type":"integer"},"physical_inbox_id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"color":{"type":"string"},"kind":{"type":"string","enum":["user","system"]},"source_type":{"type":"string","enum":["inbox","contact","conversation","crm_pipeline","crm_stage","crm_item","task_list","task","catalog_category","catalog_product","internal_chat_channel","internal_chat_author","campaign","campaign_broadcast","contracts_contract","call","twilio_voice_call","whatsapp_call","macro","canned_response","ads_ad_account","conversations_root","inbox_no_contact","crm_root","tasks_root","catalog_root","internal_chat_root","uncategorized_root","campaigns_root","contracts_root","calls_root","macros_root","canned_root","ads_root"],"description":"Stable source binding for an automatic Library folder; null for user-created folders."},"source_id":{"type":"integer"},"position":{"type":"integer"},"depth":{"type":"string"},"assets_count":{"type":"integer"},"total_assets_count":{"type":"boolean"},"additional_attributes":{"type":"object","additionalProperties":true,"description":"Channel- and source-specific metadata for this record (e.g. browser info, referer, social profile identifiers). The key set depends on the originating channel."},"name_overridden":{"type":["boolean","null"]},"trash_reason":{"type":["string","null"],"enum":["source_deleted",null],"description":"Why the item entered Trash automatically; null when a user archived it."},"retired_source_type":{"type":["string","null"],"enum":["inbox","contact","conversation","crm_pipeline","crm_stage","crm_item","task_list","task","catalog_category","catalog_product","internal_chat_channel","internal_chat_author","campaign","campaign_broadcast","contracts_contract","call","twilio_voice_call","whatsapp_call","macro","canned_response","ads_ad_account","conversations_root","inbox_no_contact","crm_root","tasks_root","catalog_root","internal_chat_root","uncategorized_root","campaigns_root","contracts_root","calls_root","macros_root","canned_root","ads_root",null],"description":"Deleted source formerly represented by this Trash item; null for manual archival."},"source_deleted_at":{"type":["string","null"],"format":"date-time","description":"Time the permanently deleted source caused this item to enter Trash; null otherwise."},"has_children":{"type":"boolean"},"archived_at":{"type":"string","format":"date-time"},"created_at":{"type":"integer"},"updated_at":{"type":"integer"}}}}},"example":{"payload":{"id":1,"account_id":1,"parent_id":1,"inbox_id":1,"physical_inbox_id":1,"name":"Sample Name","description":"A short description.","color":"#1F93FF","kind":"user","source_type":"inbox","source_id":1,"position":1,"depth":"sample depth","assets_count":5,"total_assets_count":true,"additional_attributes":{},"name_overridden":true,"trash_reason":"source_deleted","retired_source_type":"inbox","source_deleted_at":"2026-01-15T10:30:00.000Z","has_children":true,"archived_at":"2026-01-15T10:30:00.000Z","created_at":1,"updated_at":1}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"folder":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"color":{"type":"string"},"parent_id":{"type":"integer"},"inbox_id":{"type":"integer"},"position":{"type":"integer"},"additional_attributes":{"type":"object","additionalProperties":true,"description":"Channel- and source-specific metadata for this record (e.g. browser info, referer, social profile identifiers). The key set depends on the originating channel."}},"required":["name"]}},"required":["folder"]},"example":{"folder":{"name":"Sample Name","description":"A short description.","color":"#1F93FF","parent_id":1,"inbox_id":1,"position":1,"additional_attributes":{}}}}}}}},"/api/v1/accounts/{account_id}/media_library/folders/{id}":{"get":{"tags":["Media Library"],"operationId":"auto_get_api_v1_accounts_account_id_media_library_folders_id","summary":"Get folders","description":"Returns the folder identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"parent_id":{"type":"integer"},"inbox_id":{"type":"integer"},"physical_inbox_id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"color":{"type":"string"},"kind":{"type":"string","enum":["user","system"]},"source_type":{"type":"string","enum":["inbox","contact","conversation","crm_pipeline","crm_stage","crm_item","task_list","task","catalog_category","catalog_product","internal_chat_channel","internal_chat_author","campaign","campaign_broadcast","contracts_contract","call","twilio_voice_call","whatsapp_call","macro","canned_response","ads_ad_account","conversations_root","inbox_no_contact","crm_root","tasks_root","catalog_root","internal_chat_root","uncategorized_root","campaigns_root","contracts_root","calls_root","macros_root","canned_root","ads_root"],"description":"Stable source binding for an automatic Library folder; null for user-created folders."},"source_id":{"type":"integer"},"position":{"type":"integer"},"depth":{"type":"string"},"assets_count":{"type":"integer"},"total_assets_count":{"type":"boolean"},"additional_attributes":{"type":"object","additionalProperties":true,"description":"Channel- and source-specific metadata for this record (e.g. browser info, referer, social profile identifiers). The key set depends on the originating channel."},"name_overridden":{"type":["boolean","null"]},"trash_reason":{"type":["string","null"],"enum":["source_deleted",null],"description":"Why the item entered Trash automatically; null when a user archived it."},"retired_source_type":{"type":["string","null"],"enum":["inbox","contact","conversation","crm_pipeline","crm_stage","crm_item","task_list","task","catalog_category","catalog_product","internal_chat_channel","internal_chat_author","campaign","campaign_broadcast","contracts_contract","call","twilio_voice_call","whatsapp_call","macro","canned_response","ads_ad_account","conversations_root","inbox_no_contact","crm_root","tasks_root","catalog_root","internal_chat_root","uncategorized_root","campaigns_root","contracts_root","calls_root","macros_root","canned_root","ads_root",null],"description":"Deleted source formerly represented by this Trash item; null for manual archival."},"source_deleted_at":{"type":["string","null"],"format":"date-time","description":"Time the permanently deleted source caused this item to enter Trash; null otherwise."},"has_children":{"type":"boolean"},"archived_at":{"type":"string","format":"date-time"},"created_at":{"type":"integer"},"updated_at":{"type":"integer"}}}}},"example":{"payload":{"id":1,"account_id":1,"parent_id":1,"inbox_id":1,"physical_inbox_id":1,"name":"Sample Name","description":"A short description.","color":"#1F93FF","kind":"user","source_type":"inbox","source_id":1,"position":1,"depth":"sample depth","assets_count":5,"total_assets_count":true,"additional_attributes":{},"name_overridden":true,"trash_reason":"source_deleted","retired_source_type":"inbox","source_deleted_at":"2026-01-15T10:30:00.000Z","has_children":true,"archived_at":"2026-01-15T10:30:00.000Z","created_at":1,"updated_at":1}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]},"patch":{"tags":["Media Library"],"operationId":"auto_patch_api_v1_accounts_account_id_media_library_folders_id","summary":"Update folders","description":"Updates the folder identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"parent_id":{"type":"integer"},"inbox_id":{"type":"integer"},"physical_inbox_id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"color":{"type":"string"},"kind":{"type":"string","enum":["user","system"]},"source_type":{"type":"string","enum":["inbox","contact","conversation","crm_pipeline","crm_stage","crm_item","task_list","task","catalog_category","catalog_product","internal_chat_channel","internal_chat_author","campaign","campaign_broadcast","contracts_contract","call","twilio_voice_call","whatsapp_call","macro","canned_response","ads_ad_account","conversations_root","inbox_no_contact","crm_root","tasks_root","catalog_root","internal_chat_root","uncategorized_root","campaigns_root","contracts_root","calls_root","macros_root","canned_root","ads_root"],"description":"Stable source binding for an automatic Library folder; null for user-created folders."},"source_id":{"type":"integer"},"position":{"type":"integer"},"depth":{"type":"string"},"assets_count":{"type":"integer"},"total_assets_count":{"type":"boolean"},"additional_attributes":{"type":"object","additionalProperties":true,"description":"Channel- and source-specific metadata for this record (e.g. browser info, referer, social profile identifiers). The key set depends on the originating channel."},"name_overridden":{"type":["boolean","null"]},"trash_reason":{"type":["string","null"],"enum":["source_deleted",null],"description":"Why the item entered Trash automatically; null when a user archived it."},"retired_source_type":{"type":["string","null"],"enum":["inbox","contact","conversation","crm_pipeline","crm_stage","crm_item","task_list","task","catalog_category","catalog_product","internal_chat_channel","internal_chat_author","campaign","campaign_broadcast","contracts_contract","call","twilio_voice_call","whatsapp_call","macro","canned_response","ads_ad_account","conversations_root","inbox_no_contact","crm_root","tasks_root","catalog_root","internal_chat_root","uncategorized_root","campaigns_root","contracts_root","calls_root","macros_root","canned_root","ads_root",null],"description":"Deleted source formerly represented by this Trash item; null for manual archival."},"source_deleted_at":{"type":["string","null"],"format":"date-time","description":"Time the permanently deleted source caused this item to enter Trash; null otherwise."},"has_children":{"type":"boolean"},"archived_at":{"type":"string","format":"date-time"},"created_at":{"type":"integer"},"updated_at":{"type":"integer"}}}}},"example":{"payload":{"id":1,"account_id":1,"parent_id":1,"inbox_id":1,"physical_inbox_id":1,"name":"Sample Name","description":"A short description.","color":"#1F93FF","kind":"user","source_type":"inbox","source_id":1,"position":1,"depth":"sample depth","assets_count":5,"total_assets_count":true,"additional_attributes":{},"name_overridden":true,"trash_reason":"source_deleted","retired_source_type":"inbox","source_deleted_at":"2026-01-15T10:30:00.000Z","has_children":true,"archived_at":"2026-01-15T10:30:00.000Z","created_at":1,"updated_at":1}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"folder":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"color":{"type":"string"},"parent_id":{"type":"integer"},"inbox_id":{"type":"integer"},"position":{"type":"integer"},"additional_attributes":{"type":"object","additionalProperties":true,"description":"Channel- and source-specific metadata for this record (e.g. browser info, referer, social profile identifiers). The key set depends on the originating channel."}}}},"required":["folder"]},"example":{"folder":{"name":"Sample Name","description":"A short description.","color":"#1F93FF","parent_id":1,"inbox_id":1,"position":1,"additional_attributes":{}}}}}}},"put":{"tags":["Media Library"],"operationId":"auto_put_api_v1_accounts_account_id_media_library_folders_id","summary":"Update folders","description":"Updates the folder identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"parent_id":{"type":"integer"},"inbox_id":{"type":"integer"},"physical_inbox_id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"color":{"type":"string"},"kind":{"type":"string","enum":["user","system"]},"source_type":{"type":"string","enum":["inbox","contact","conversation","crm_pipeline","crm_stage","crm_item","task_list","task","catalog_category","catalog_product","internal_chat_channel","internal_chat_author","campaign","campaign_broadcast","contracts_contract","call","twilio_voice_call","whatsapp_call","macro","canned_response","ads_ad_account","conversations_root","inbox_no_contact","crm_root","tasks_root","catalog_root","internal_chat_root","uncategorized_root","campaigns_root","contracts_root","calls_root","macros_root","canned_root","ads_root"],"description":"Stable source binding for an automatic Library folder; null for user-created folders."},"source_id":{"type":"integer"},"position":{"type":"integer"},"depth":{"type":"string"},"assets_count":{"type":"integer"},"total_assets_count":{"type":"boolean"},"additional_attributes":{"type":"object","additionalProperties":true,"description":"Channel- and source-specific metadata for this record (e.g. browser info, referer, social profile identifiers). The key set depends on the originating channel."},"name_overridden":{"type":["boolean","null"]},"trash_reason":{"type":["string","null"],"enum":["source_deleted",null],"description":"Why the item entered Trash automatically; null when a user archived it."},"retired_source_type":{"type":["string","null"],"enum":["inbox","contact","conversation","crm_pipeline","crm_stage","crm_item","task_list","task","catalog_category","catalog_product","internal_chat_channel","internal_chat_author","campaign","campaign_broadcast","contracts_contract","call","twilio_voice_call","whatsapp_call","macro","canned_response","ads_ad_account","conversations_root","inbox_no_contact","crm_root","tasks_root","catalog_root","internal_chat_root","uncategorized_root","campaigns_root","contracts_root","calls_root","macros_root","canned_root","ads_root",null],"description":"Deleted source formerly represented by this Trash item; null for manual archival."},"source_deleted_at":{"type":["string","null"],"format":"date-time","description":"Time the permanently deleted source caused this item to enter Trash; null otherwise."},"has_children":{"type":"boolean"},"archived_at":{"type":"string","format":"date-time"},"created_at":{"type":"integer"},"updated_at":{"type":"integer"}}}}},"example":{"payload":{"id":1,"account_id":1,"parent_id":1,"inbox_id":1,"physical_inbox_id":1,"name":"Sample Name","description":"A short description.","color":"#1F93FF","kind":"user","source_type":"inbox","source_id":1,"position":1,"depth":"sample depth","assets_count":5,"total_assets_count":true,"additional_attributes":{},"name_overridden":true,"trash_reason":"source_deleted","retired_source_type":"inbox","source_deleted_at":"2026-01-15T10:30:00.000Z","has_children":true,"archived_at":"2026-01-15T10:30:00.000Z","created_at":1,"updated_at":1}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"folder":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"color":{"type":"string"},"parent_id":{"type":"integer"},"inbox_id":{"type":"integer"},"position":{"type":"integer"},"additional_attributes":{"type":"object","additionalProperties":true,"description":"Channel- and source-specific metadata for this record (e.g. browser info, referer, social profile identifiers). The key set depends on the originating channel."}}}},"required":["folder"]},"example":{"folder":{"name":"Sample Name","description":"A short description.","color":"#1F93FF","parent_id":1,"inbox_id":1,"position":1,"additional_attributes":{}}}}}}},"delete":{"tags":["Media Library"],"operationId":"auto_delete_api_v1_accounts_account_id_media_library_folders_id","summary":"Move a user folder to Trash","description":"Archives a user-created folder. With include_contents=false, direct media and child folders are preserved and promoted to the visible parent. With include_contents=true, the complete folder subtree and all of its media move to Trash atomically. Automatic system folders are protected while their source exists; after that source is permanently deleted, the folder and exclusive media move to Trash automatically while media reused elsewhere is preserved under Uncategorized.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Folder archived without hiding or orphaning preserved content.","content":{"application/json":{"schema":{"type":"object","required":["payload"],"properties":{"payload":{"type":"object","required":["folder_id","folders","archived_assets","preserved_assets"],"properties":{"folder_id":{"type":"integer","example":12},"folders":{"type":"integer","example":3},"archived_assets":{"type":"integer","example":24},"preserved_assets":{"type":"integer","example":0}}}}},"example":{"payload":{"folder_id":12,"folders":3,"archived_assets":24,"preserved_assets":0}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"422":{"description":"Automatic system folders cannot be deleted."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"include_contents":{"type":"boolean","default":false,"description":"Include every descendant folder and media asset in the lifecycle operation."}}},"example":{"include_contents":true}}}}}},"/api/v1/accounts/{account_id}/media_library/assets/{id}/send_to_conversation":{"post":{"tags":["Media Library"],"operationId":"auto_post_api_v1_accounts_account_id_media_library_assets_id_send_to_conversation","summary":"Send a media library asset to a conversation","description":"Delivers an asset that is already stored in the media library as an outgoing message in a conversation, reusing the stored file instead of uploading it again. An optional caption is sent with it, and on channels that support it the asset can be sent as a view-once media. On success the endpoint returns HTTP 200 with an EMPTY body — the created message arrives through the conversation endpoints and the realtime stream. When `X-Idempotency-Key` is present, retries resolve to the original account/conversation-scoped message without creating or enqueueing another one. Human callers send as themselves. Bot callers must authenticate as the active bot bound to the conversation's inbox; the message is then authored by that bot. Any other bot, or a user credential asserting bot authorship, is refused.","security":[{"agentBotApiKey":[]},{"userApiKey":[]}],"responses":{"200":{"description":"The asset was delivered to the conversation. Empty body."},"401":{"description":"Unauthorized"},"404":{"description":"The asset does not exist in this account, or no conversation matches the given id."},"422":{"description":"The asset could not be sent — most commonly because its stored file is missing, or because the channel rejected the delivery.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Localized reason the asset could not be delivered."}},"required":["error"]},"example":{"error":"The stored file for this asset is missing"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"X-Chatwoot-Message-Author","in":"header","required":false,"schema":{"type":"string","enum":["agent_bot"]},"description":"Optional assertion requiring authenticated AgentBot credentials. This header alone does not authenticate a caller."},{"name":"X-Idempotency-Key","in":"header","required":false,"schema":{"type":"string"},"description":"Stable caller key for retrying the exact same asset send without duplication."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"conversation_id":{"type":"integer","description":"Target conversation. The per-account display id is matched first and the internal record id is used as a fallback, so either identifier is accepted."},"caption":{"type":"string","description":"Optional text sent together with the media."},"view_once":{"type":"boolean","description":"When true the media is sent as a view-once message on channels that support it. Defaults to false."}},"required":["conversation_id"]},"example":{"conversation_id":128,"caption":"Here is the price list you asked for.","view_once":false}}}}}},"/api/v1/accounts/{account_id}/media_library/assets/{id}/restore":{"post":{"tags":["Media Library"],"operationId":"auto_post_api_v1_accounts_account_id_media_library_assets_id_restore","summary":"Restore assets","description":"Performs the restore operation on the targeted asset resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"folder_id":{"type":"integer"},"inbox_id":{"type":"integer"},"physical_inbox_id":{"type":"integer"},"uploaded_by_id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"file_type":{"type":"string","enum":["image","audio","video","file"],"description":"The high-level media class of an attachment, derived from its content type."},"media_kind":{"type":"string","enum":["gif","sticker","recording","voice"]},"source":{"type":"string","enum":["upload","conversation_capture","recording","imported","internal_chat_capture"]},"content_type":{"type":"string"},"byte_size":{"type":"string"},"width":{"type":"string"},"height":{"type":"string"},"duration":{"type":"string"},"file_name":{"type":"string"},"file_url":{"type":"string"},"stream_url":{"type":"string"},"thumb_url":{"type":"string"},"download_url":{"type":"string"},"signed_id":{"type":"string","description":"Signed Active Storage blob token. Omitted while permanent deletion is pending or when the file is absent."},"purge_pending":{"type":"boolean"},"purge_operation_id":{"type":"integer","description":"Durable deletion operation currently owning this asset. Omitted when no deletion is pending."},"archived_at":{"type":"string","format":"date-time"},"trash_reason":{"type":["string","null"],"enum":["source_deleted",null],"description":"Why the item entered Trash automatically; null when a user archived it."},"retired_source_type":{"type":["string","null"],"enum":["inbox","contact","conversation","crm_pipeline","crm_stage","crm_item","task_list","task","catalog_category","catalog_product","internal_chat_channel","internal_chat_author","campaign","campaign_broadcast","contracts_contract","call","twilio_voice_call","whatsapp_call","macro","canned_response","ads_ad_account","conversations_root","inbox_no_contact","crm_root","tasks_root","catalog_root","internal_chat_root","uncategorized_root","campaigns_root","contracts_root","calls_root","macros_root","canned_root","ads_root",null],"description":"Deleted source formerly represented by this Trash item; null for manual archival."},"source_deleted_at":{"type":["string","null"],"format":"date-time","description":"Time the permanently deleted source caused this item to enter Trash; null otherwise."},"origin":{"type":"object","properties":{"conversation_display_id":{"type":["integer","null"]},"contact_id":{"type":["integer","null"]},"contact_name":{"type":["string","null"]},"message_id":{"type":"integer"},"chat_kind":{"type":"string","enum":["status","group","community","newsletter","direct"],"description":"Which kind of chat the media came from — a status/story broadcast, a group, a community, a channel/newsletter, or a direct one-to-one conversation. Absent when there is no chat to classify (a manual upload or an ad creative); absence means unknown and is never a guess."},"internal_chat_message_id":{"type":"integer"},"crm_item_id":{"type":"integer"},"task_id":{"type":"integer"},"catalog_product_id":{"type":"integer"}}},"created_at":{"type":"integer"},"updated_at":{"type":"integer"}}}}},"example":{"payload":{"id":1,"account_id":1,"folder_id":1,"inbox_id":1,"physical_inbox_id":1,"uploaded_by_id":1,"name":"Sample Name","description":"A short description.","file_type":"image","media_kind":"gif","source":"upload","content_type":"sample content type","byte_size":"sample byte size","width":"sample width","height":"sample height","duration":"sample duration","file_name":"sample file name","file_url":"https://example.com/resource","stream_url":"https://example.com/resource","thumb_url":"https://example.com/resource","download_url":"https://example.com/resource","signed_id":"sample signed id","purge_pending":true,"purge_operation_id":1,"archived_at":"2026-01-15T10:30:00.000Z","trash_reason":"source_deleted","retired_source_type":"inbox","source_deleted_at":"2026-01-15T10:30:00.000Z","origin":{"conversation_display_id":1,"contact_id":1,"contact_name":"sample contact name","message_id":1,"chat_kind":"status","internal_chat_message_id":1,"crm_item_id":1,"task_id":1,"catalog_product_id":1},"created_at":1,"updated_at":1}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/media_library/assets/{id}/purge":{"delete":{"tags":["Media Library"],"operationId":"auto_delete_api_v1_accounts_account_id_media_library_assets_id_purge","summary":"Confirm permanent deletion of one media asset","description":"Confirms a fresh preview that contains this archived asset. Confirmation atomically freezes the reviewed aliases and reclaimable blobs, then queues the durable storage operation. HTTP 202 means accepted, not deleted; poll the returned operation until status is completed. A changed or competing snapshot is rejected without deleting anything.","security":[{"userApiKey":[]}],"responses":{"202":{"description":"Deletion accepted. Poll the operation; storage has not necessarily deleted the file yet.","content":{"application/json":{"schema":{"type":"object","required":["payload"],"properties":{"payload":{"type":"object","required":["id","status","impact","progress","attempts","error_code","updated_at"],"properties":{"id":{"type":"integer","example":190},"status":{"type":"string","enum":["draft","pending","running","completed","failed"],"example":"draft"},"impact":{"type":"object","required":["selected_asset_ids","selected_assets","affected_assets","affected_references","protected_references","requested_bytes","reclaimable_bytes","protected_bytes","modules"],"properties":{"selected_asset_ids":{"type":"array","items":{"type":"integer"},"example":[81,82]},"selected_assets":{"type":"integer","example":2},"affected_assets":{"type":"integer","example":3},"affected_references":{"type":"integer","example":5},"protected_references":{"type":"integer","example":1},"requested_bytes":{"type":"integer","example":10485760},"reclaimable_bytes":{"type":"integer","example":8388608},"protected_bytes":{"type":"integer","example":2097152},"modules":{"type":"object","description":"Active Storage record type to number of same-account references that will become deleted-media tombstones.","additionalProperties":{"type":"integer"},"example":{"Attachment":2,"Task":1}}}},"progress":{"type":"object","required":["total_blobs","processed_blobs","reclaimed_bytes","protected_blobs","completed_blob_ids"],"properties":{"total_blobs":{"type":"integer","example":2},"processed_blobs":{"type":"integer","example":0},"reclaimed_bytes":{"type":"integer","example":0},"protected_blobs":{"type":"integer","example":0},"completed_blob_ids":{"type":"array","items":{"type":"integer"},"example":[]}}},"attempts":{"type":"integer","example":0},"error_code":{"type":["string","null"],"enum":["storage_delete_failed",null],"example":null},"confirmed_at":{"type":["string","null"],"format":"date-time","example":null},"started_at":{"type":["string","null"],"format":"date-time","example":null},"finished_at":{"type":["string","null"],"format":"date-time","example":null},"updated_at":{"type":"string","format":"date-time","example":"2026-08-18T19:00:00Z"}}}}},"example":{"payload":{"id":190,"status":"pending","impact":{"selected_asset_ids":[81,82],"selected_assets":2,"affected_assets":3,"affected_references":5,"protected_references":1,"requested_bytes":10485760,"reclaimable_bytes":8388608,"protected_bytes":2097152,"modules":{"Attachment":2,"Task":1}},"progress":{"total_blobs":2,"processed_blobs":0,"reclaimed_bytes":0,"protected_blobs":0,"completed_blob_ids":[]},"attempts":0,"error_code":null,"confirmed_at":"2026-08-18T19:01:00Z","started_at":null,"finished_at":null,"updated_at":"2026-08-18T19:00:00Z"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"409":{"description":"The reviewed snapshot changed, was claimed by another operation, or no longer contains this asset."},"422":{"description":"The asset is not archived, the preview expired, or the operation was already confirmed."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["purge_operation_id"],"properties":{"purge_operation_id":{"type":"integer","description":"Draft operation returned by purge_preview.","example":190}}},"example":{"purge_operation_id":190}}}}}},"/api/v1/accounts/{account_id}/media_library/assets/bulk_move":{"post":{"tags":["Media Library"],"operationId":"auto_post_api_v1_accounts_account_id_media_library_assets_bulk_move","summary":"Bulk move assets","description":"Performs the bulk move operation on the targeted asset resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"moved_ids":{"type":"array","items":{"type":"integer"}}}}}},"example":{"payload":{"moved_ids":[1]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"folder_id":{"type":"integer"},"all_matching":{"type":"string"},"asset_ids":{"type":"array","items":{"type":"integer"}}}},"example":{"folder_id":1,"all_matching":"sample all matching","asset_ids":[1]}}}}}},"/api/v1/accounts/{account_id}/media_library/assets/bulk_archive":{"post":{"tags":["Media Library"],"operationId":"auto_post_api_v1_accounts_account_id_media_library_assets_bulk_archive","summary":"Bulk archive assets","description":"Performs the bulk archive operation on the targeted asset resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"archived_ids":{"type":"array","items":{"type":"integer"}}}}}},"example":{"payload":{"archived_ids":[1]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"all_matching":{"type":"string"},"asset_ids":{"type":"array","items":{"type":"integer"}}}},"example":{"all_matching":"sample all matching","asset_ids":[1]}}}}}},"/api/v1/accounts/{account_id}/media_library/assets/bulk_restore":{"post":{"tags":["Media Library"],"operationId":"auto_post_api_v1_accounts_account_id_media_library_assets_bulk_restore","summary":"Bulk restore assets","description":"Performs the bulk restore operation on the targeted asset resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"restored_ids":{"type":"array","items":{"type":"integer"}}}}}},"example":{"payload":{"restored_ids":[1]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"all_matching":{"type":"string"},"asset_ids":{"type":"array","items":{"type":"integer"}}}},"example":{"all_matching":"sample all matching","asset_ids":[1]}}}}}},"/api/v1/accounts/{account_id}/media_library/assets/bulk_purge":{"post":{"tags":["Media Library"],"operationId":"auto_post_api_v1_accounts_account_id_media_library_assets_bulk_purge","summary":"Confirm a reviewed bulk permanent deletion","description":"Confirms exactly the immutable selection captured by purge_preview. Filters are never replayed at execution time, so assets that start matching later cannot be deleted accidentally. Poll the returned operation and show success only after status becomes completed.","security":[{"userApiKey":[]}],"responses":{"202":{"description":"Deletion accepted. Poll the operation; storage has not necessarily deleted the file yet.","content":{"application/json":{"schema":{"type":"object","required":["payload"],"properties":{"payload":{"type":"object","required":["id","status","impact","progress","attempts","error_code","updated_at"],"properties":{"id":{"type":"integer","example":190},"status":{"type":"string","enum":["draft","pending","running","completed","failed"],"example":"draft"},"impact":{"type":"object","required":["selected_asset_ids","selected_assets","affected_assets","affected_references","protected_references","requested_bytes","reclaimable_bytes","protected_bytes","modules"],"properties":{"selected_asset_ids":{"type":"array","items":{"type":"integer"},"example":[81,82]},"selected_assets":{"type":"integer","example":2},"affected_assets":{"type":"integer","example":3},"affected_references":{"type":"integer","example":5},"protected_references":{"type":"integer","example":1},"requested_bytes":{"type":"integer","example":10485760},"reclaimable_bytes":{"type":"integer","example":8388608},"protected_bytes":{"type":"integer","example":2097152},"modules":{"type":"object","description":"Active Storage record type to number of same-account references that will become deleted-media tombstones.","additionalProperties":{"type":"integer"},"example":{"Attachment":2,"Task":1}}}},"progress":{"type":"object","required":["total_blobs","processed_blobs","reclaimed_bytes","protected_blobs","completed_blob_ids"],"properties":{"total_blobs":{"type":"integer","example":2},"processed_blobs":{"type":"integer","example":0},"reclaimed_bytes":{"type":"integer","example":0},"protected_blobs":{"type":"integer","example":0},"completed_blob_ids":{"type":"array","items":{"type":"integer"},"example":[]}}},"attempts":{"type":"integer","example":0},"error_code":{"type":["string","null"],"enum":["storage_delete_failed",null],"example":null},"confirmed_at":{"type":["string","null"],"format":"date-time","example":null},"started_at":{"type":["string","null"],"format":"date-time","example":null},"finished_at":{"type":["string","null"],"format":"date-time","example":null},"updated_at":{"type":"string","format":"date-time","example":"2026-08-18T19:00:00Z"}}}}},"example":{"payload":{"id":190,"status":"pending","impact":{"selected_asset_ids":[81,82],"selected_assets":2,"affected_assets":3,"affected_references":5,"protected_references":1,"requested_bytes":10485760,"reclaimable_bytes":8388608,"protected_bytes":2097152,"modules":{"Attachment":2,"Task":1}},"progress":{"total_blobs":2,"processed_blobs":0,"reclaimed_bytes":0,"protected_blobs":0,"completed_blob_ids":[]},"attempts":0,"error_code":null,"confirmed_at":"2026-08-18T19:01:00Z","started_at":null,"finished_at":null,"updated_at":"2026-08-18T19:00:00Z"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"409":{"description":"The reviewed snapshot changed, was claimed by another operation, or no longer contains this asset."},"422":{"description":"The asset is not archived, the preview expired, or the operation was already confirmed."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["purge_operation_id"],"properties":{"purge_operation_id":{"type":"integer","description":"Draft operation returned by purge_preview.","example":190}}},"example":{"purge_operation_id":190}}}}}},"/api/v1/accounts/{account_id}/media_library/assets/purge_preview":{"post":{"tags":["Media Library"],"operationId":"auto_post_api_v1_accounts_account_id_media_library_assets_purge_preview","summary":"Preview a permanent media deletion","description":"Creates a short-lived, immutable review snapshot for archived media. The snapshot expands every same-account Library alias of the same physical blobs, classifies all current references, and separates bytes that can be reclaimed from bytes protected by another account. Nothing is deleted until that operation id is confirmed through the member or bulk purge endpoint. If the selection is already part of a pending or failed operation, that persisted operation is returned so it can be resumed instead of creating a competing deletion.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Immutable deletion impact ready for administrator confirmation.","content":{"application/json":{"schema":{"type":"object","required":["payload"],"properties":{"payload":{"type":"object","required":["id","status","impact","progress","attempts","error_code","updated_at"],"properties":{"id":{"type":"integer","example":190},"status":{"type":"string","enum":["draft","pending","running","completed","failed"],"example":"draft"},"impact":{"type":"object","required":["selected_asset_ids","selected_assets","affected_assets","affected_references","protected_references","requested_bytes","reclaimable_bytes","protected_bytes","modules"],"properties":{"selected_asset_ids":{"type":"array","items":{"type":"integer"},"example":[81,82]},"selected_assets":{"type":"integer","example":2},"affected_assets":{"type":"integer","example":3},"affected_references":{"type":"integer","example":5},"protected_references":{"type":"integer","example":1},"requested_bytes":{"type":"integer","example":10485760},"reclaimable_bytes":{"type":"integer","example":8388608},"protected_bytes":{"type":"integer","example":2097152},"modules":{"type":"object","description":"Active Storage record type to number of same-account references that will become deleted-media tombstones.","additionalProperties":{"type":"integer"},"example":{"Attachment":2,"Task":1}}}},"progress":{"type":"object","required":["total_blobs","processed_blobs","reclaimed_bytes","protected_blobs","completed_blob_ids"],"properties":{"total_blobs":{"type":"integer","example":2},"processed_blobs":{"type":"integer","example":0},"reclaimed_bytes":{"type":"integer","example":0},"protected_blobs":{"type":"integer","example":0},"completed_blob_ids":{"type":"array","items":{"type":"integer"},"example":[]}}},"attempts":{"type":"integer","example":0},"error_code":{"type":["string","null"],"enum":["storage_delete_failed",null],"example":null},"confirmed_at":{"type":["string","null"],"format":"date-time","example":null},"started_at":{"type":["string","null"],"format":"date-time","example":null},"finished_at":{"type":["string","null"],"format":"date-time","example":null},"updated_at":{"type":"string","format":"date-time","example":"2026-08-18T19:00:00Z"}}}}},"example":{"payload":{"id":190,"status":"draft","impact":{"selected_asset_ids":[81,82],"selected_assets":2,"affected_assets":3,"affected_references":5,"protected_references":1,"requested_bytes":10485760,"reclaimable_bytes":8388608,"protected_bytes":2097152,"modules":{"Attachment":2,"Task":1}},"progress":{"total_blobs":2,"processed_blobs":0,"reclaimed_bytes":0,"protected_blobs":0,"completed_blob_ids":[]},"attempts":0,"error_code":null,"confirmed_at":null,"started_at":null,"finished_at":null,"updated_at":"2026-08-18T19:00:00Z"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"No archived media matched the reviewed selection."},"409":{"description":"The selected media belongs to more than one deletion already in progress."},"422":{"description":"The explicit selection exceeds the limit or includes media that is not archived."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"Use asset_ids for an explicit selection, or all_matching=true with the same filters used by the archived Library grid. An explicit request is limited to 500 ids.","properties":{"asset_ids":{"type":"array","items":{"type":"integer"},"example":[81,82]},"all_matching":{"type":"boolean","example":false},"folder_id":{"type":["integer","null"],"example":12},"file_type":{"type":"string","enum":["image","audio","video","file"],"example":"image","description":"The high-level media class of an attachment, derived from its content type."},"inbox_id":{"type":["integer","null"],"example":7},"source":{"type":"string","enum":["upload","conversation_capture","recording","imported","internal_chat_capture"],"example":"upload"},"chat_kind":{"type":"string","enum":["status","group","community","newsletter","direct"],"example":"direct","description":"Which kind of chat the media came from — a status/story broadcast, a group, a community, a channel/newsletter, or a direct one-to-one conversation. Absent when there is no chat to classify (a manual upload or an ad creative); absence means unknown and is never a guess."},"module":{"type":"string","enum":["conversations","crm","catalog","tasks","internal_chat","campaigns","contracts","macros","canned_responses","calls"],"example":"conversations"},"q":{"type":"string","example":"proposal"},"media_kinds":{"type":"array","items":{"type":"string","enum":["gif","sticker","recording","voice"]},"example":["gif"]},"exclude_media_kinds":{"type":"array","items":{"type":"string","enum":["gif","sticker","recording","voice"]},"example":["sticker"]}}},"example":{"asset_ids":[81,82],"all_matching":false,"folder_id":12,"file_type":"image","inbox_id":7,"source":"upload","chat_kind":"direct","module":"conversations","q":"proposal","media_kinds":["gif"],"exclude_media_kinds":["sticker"]}}}}}},"/api/v1/accounts/{account_id}/media_library/assets/storage":{"get":{"tags":["Media Library"],"operationId":"auto_get_api_v1_accounts_account_id_media_library_assets_storage","summary":"Storage assets","description":"Performs the storage operation on the targeted asset resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"total_bytes":{"type":"string"},"quota_mb":{"type":"string"},"asset_count":{"type":"integer"},"by_inbox":{"type":"array","items":{"type":"object","properties":{"inbox_id":{"type":"integer"},"name":{"type":"string"},"bytes":{"type":"string"}}}}}}}},"example":{"payload":{"total_bytes":"sample total bytes","quota_mb":"sample quota mb","asset_count":5,"by_inbox":[{"inbox_id":1,"name":"Sample Name","bytes":"sample bytes"}]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/media_library/assets":{"get":{"tags":["Media Library"],"operationId":"auto_get_api_v1_accounts_account_id_media_library_assets","summary":"List assets","description":"Returns the list of assets visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"folder_id":{"type":"integer"},"inbox_id":{"type":"integer"},"physical_inbox_id":{"type":"integer"},"uploaded_by_id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"file_type":{"type":"string","enum":["image","audio","video","file"],"description":"The high-level media class of an attachment, derived from its content type."},"media_kind":{"type":"string","enum":["gif","sticker","recording","voice"]},"source":{"type":"string","enum":["upload","conversation_capture","recording","imported","internal_chat_capture"]},"content_type":{"type":"string"},"byte_size":{"type":"string"},"width":{"type":"string"},"height":{"type":"string"},"duration":{"type":"string"},"file_name":{"type":"string"},"file_url":{"type":"string"},"stream_url":{"type":"string"},"thumb_url":{"type":"string"},"download_url":{"type":"string"},"signed_id":{"type":"string","description":"Signed Active Storage blob token. Omitted while permanent deletion is pending or when the file is absent."},"purge_pending":{"type":"boolean"},"purge_operation_id":{"type":"integer","description":"Durable deletion operation currently owning this asset. Omitted when no deletion is pending."},"archived_at":{"type":"string","format":"date-time"},"trash_reason":{"type":["string","null"],"enum":["source_deleted",null],"description":"Why the item entered Trash automatically; null when a user archived it."},"retired_source_type":{"type":["string","null"],"enum":["inbox","contact","conversation","crm_pipeline","crm_stage","crm_item","task_list","task","catalog_category","catalog_product","internal_chat_channel","internal_chat_author","campaign","campaign_broadcast","contracts_contract","call","twilio_voice_call","whatsapp_call","macro","canned_response","ads_ad_account","conversations_root","inbox_no_contact","crm_root","tasks_root","catalog_root","internal_chat_root","uncategorized_root","campaigns_root","contracts_root","calls_root","macros_root","canned_root","ads_root",null],"description":"Deleted source formerly represented by this Trash item; null for manual archival."},"source_deleted_at":{"type":["string","null"],"format":"date-time","description":"Time the permanently deleted source caused this item to enter Trash; null otherwise."},"origin":{"type":"object","properties":{"conversation_display_id":{"type":["integer","null"]},"contact_id":{"type":["integer","null"]},"contact_name":{"type":["string","null"]},"message_id":{"type":"integer"},"chat_kind":{"type":"string","enum":["status","group","community","newsletter","direct"],"description":"Which kind of chat the media came from — a status/story broadcast, a group, a community, a channel/newsletter, or a direct one-to-one conversation. Absent when there is no chat to classify (a manual upload or an ad creative); absence means unknown and is never a guess."},"internal_chat_message_id":{"type":"integer"},"crm_item_id":{"type":"integer"},"task_id":{"type":"integer"},"catalog_product_id":{"type":"integer"}}},"created_at":{"type":"integer"},"updated_at":{"type":"integer"}}}},"meta":{"type":"object","properties":{"count":{"type":"integer"},"current_page":{"type":"string"},"total_pages":{"type":"string"},"per_page":{"type":"string"},"has_more":{"type":"boolean"}}}}},"example":{"payload":[{"id":1,"account_id":1,"folder_id":1,"inbox_id":1,"physical_inbox_id":1,"uploaded_by_id":1,"name":"Sample Name","description":"A short description.","file_type":"image","media_kind":"gif","source":"upload","content_type":"sample content type","byte_size":"sample byte size","width":"sample width","height":"sample height","duration":"sample duration","file_name":"sample file name","file_url":"https://example.com/resource","stream_url":"https://example.com/resource","thumb_url":"https://example.com/resource","download_url":"https://example.com/resource","signed_id":"sample signed id","purge_pending":true,"purge_operation_id":1,"archived_at":"2026-01-15T10:30:00.000Z","trash_reason":"source_deleted","retired_source_type":"inbox","source_deleted_at":"2026-01-15T10:30:00.000Z","origin":{"conversation_display_id":1,"contact_id":1,"contact_name":"sample contact name","message_id":1,"chat_kind":"status","internal_chat_message_id":1,"crm_item_id":1,"task_id":1,"catalog_product_id":1},"created_at":1,"updated_at":1}],"meta":{"count":5,"current_page":"sample current page","total_pages":"sample total pages","per_page":"sample per page","has_more":true}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."}]},"post":{"tags":["Media Library"],"operationId":"auto_post_api_v1_accounts_account_id_media_library_assets","summary":"Create assets","description":"Creates a new asset from the request payload. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"folder_id":{"type":"integer"},"inbox_id":{"type":"integer"},"physical_inbox_id":{"type":"integer"},"uploaded_by_id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"file_type":{"type":"string","enum":["image","audio","video","file"],"description":"The high-level media class of an attachment, derived from its content type."},"media_kind":{"type":"string","enum":["gif","sticker","recording","voice"]},"source":{"type":"string","enum":["upload","conversation_capture","recording","imported","internal_chat_capture"]},"content_type":{"type":"string"},"byte_size":{"type":"string"},"width":{"type":"string"},"height":{"type":"string"},"duration":{"type":"string"},"file_name":{"type":"string"},"file_url":{"type":"string"},"stream_url":{"type":"string"},"thumb_url":{"type":"string"},"download_url":{"type":"string"},"signed_id":{"type":"string","description":"Signed Active Storage blob token. Omitted while permanent deletion is pending or when the file is absent."},"purge_pending":{"type":"boolean"},"purge_operation_id":{"type":"integer","description":"Durable deletion operation currently owning this asset. Omitted when no deletion is pending."},"archived_at":{"type":"string","format":"date-time"},"trash_reason":{"type":["string","null"],"enum":["source_deleted",null],"description":"Why the item entered Trash automatically; null when a user archived it."},"retired_source_type":{"type":["string","null"],"enum":["inbox","contact","conversation","crm_pipeline","crm_stage","crm_item","task_list","task","catalog_category","catalog_product","internal_chat_channel","internal_chat_author","campaign","campaign_broadcast","contracts_contract","call","twilio_voice_call","whatsapp_call","macro","canned_response","ads_ad_account","conversations_root","inbox_no_contact","crm_root","tasks_root","catalog_root","internal_chat_root","uncategorized_root","campaigns_root","contracts_root","calls_root","macros_root","canned_root","ads_root",null],"description":"Deleted source formerly represented by this Trash item; null for manual archival."},"source_deleted_at":{"type":["string","null"],"format":"date-time","description":"Time the permanently deleted source caused this item to enter Trash; null otherwise."},"origin":{"type":"object","properties":{"conversation_display_id":{"type":["integer","null"]},"contact_id":{"type":["integer","null"]},"contact_name":{"type":["string","null"]},"message_id":{"type":"integer"},"chat_kind":{"type":"string","enum":["status","group","community","newsletter","direct"],"description":"Which kind of chat the media came from — a status/story broadcast, a group, a community, a channel/newsletter, or a direct one-to-one conversation. Absent when there is no chat to classify (a manual upload or an ad creative); absence means unknown and is never a guess."},"internal_chat_message_id":{"type":"integer"},"crm_item_id":{"type":"integer"},"task_id":{"type":"integer"},"catalog_product_id":{"type":"integer"}}},"created_at":{"type":"integer"},"updated_at":{"type":"integer"}}}}},"example":{"payload":{"id":1,"account_id":1,"folder_id":1,"inbox_id":1,"physical_inbox_id":1,"uploaded_by_id":1,"name":"Sample Name","description":"A short description.","file_type":"image","media_kind":"gif","source":"upload","content_type":"sample content type","byte_size":"sample byte size","width":"sample width","height":"sample height","duration":"sample duration","file_name":"sample file name","file_url":"https://example.com/resource","stream_url":"https://example.com/resource","thumb_url":"https://example.com/resource","download_url":"https://example.com/resource","signed_id":"sample signed id","purge_pending":true,"purge_operation_id":1,"archived_at":"2026-01-15T10:30:00.000Z","trash_reason":"source_deleted","retired_source_type":"inbox","source_deleted_at":"2026-01-15T10:30:00.000Z","origin":{"conversation_display_id":1,"contact_id":1,"contact_name":"sample contact name","message_id":1,"chat_kind":"status","internal_chat_message_id":1,"crm_item_id":1,"task_id":1,"catalog_product_id":1},"created_at":1,"updated_at":1}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"asset":{"type":"object","properties":{"file":{"type":"string"},"folder_id":{"type":"integer"},"inbox_id":{"type":"integer"},"name":{"type":"string"},"ads_ad_account_id":{"type":"integer"}}}},"required":["asset"]},"example":{"asset":{"file":"sample file","folder_id":1,"inbox_id":1,"name":"Sample Name","ads_ad_account_id":1}}}}}}},"/api/v1/accounts/{account_id}/media_library/assets/{id}":{"get":{"tags":["Media Library"],"operationId":"auto_get_api_v1_accounts_account_id_media_library_assets_id","summary":"Get assets","description":"Returns the asset identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"folder_id":{"type":"integer"},"inbox_id":{"type":"integer"},"physical_inbox_id":{"type":"integer"},"uploaded_by_id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"file_type":{"type":"string","enum":["image","audio","video","file"],"description":"The high-level media class of an attachment, derived from its content type."},"media_kind":{"type":"string","enum":["gif","sticker","recording","voice"]},"source":{"type":"string","enum":["upload","conversation_capture","recording","imported","internal_chat_capture"]},"content_type":{"type":"string"},"byte_size":{"type":"string"},"width":{"type":"string"},"height":{"type":"string"},"duration":{"type":"string"},"file_name":{"type":"string"},"file_url":{"type":"string"},"stream_url":{"type":"string"},"thumb_url":{"type":"string"},"download_url":{"type":"string"},"signed_id":{"type":"string","description":"Signed Active Storage blob token. Omitted while permanent deletion is pending or when the file is absent."},"purge_pending":{"type":"boolean"},"purge_operation_id":{"type":"integer","description":"Durable deletion operation currently owning this asset. Omitted when no deletion is pending."},"archived_at":{"type":"string","format":"date-time"},"trash_reason":{"type":["string","null"],"enum":["source_deleted",null],"description":"Why the item entered Trash automatically; null when a user archived it."},"retired_source_type":{"type":["string","null"],"enum":["inbox","contact","conversation","crm_pipeline","crm_stage","crm_item","task_list","task","catalog_category","catalog_product","internal_chat_channel","internal_chat_author","campaign","campaign_broadcast","contracts_contract","call","twilio_voice_call","whatsapp_call","macro","canned_response","ads_ad_account","conversations_root","inbox_no_contact","crm_root","tasks_root","catalog_root","internal_chat_root","uncategorized_root","campaigns_root","contracts_root","calls_root","macros_root","canned_root","ads_root",null],"description":"Deleted source formerly represented by this Trash item; null for manual archival."},"source_deleted_at":{"type":["string","null"],"format":"date-time","description":"Time the permanently deleted source caused this item to enter Trash; null otherwise."},"origin":{"type":"object","properties":{"conversation_display_id":{"type":["integer","null"]},"contact_id":{"type":["integer","null"]},"contact_name":{"type":["string","null"]},"message_id":{"type":"integer"},"chat_kind":{"type":"string","enum":["status","group","community","newsletter","direct"],"description":"Which kind of chat the media came from — a status/story broadcast, a group, a community, a channel/newsletter, or a direct one-to-one conversation. Absent when there is no chat to classify (a manual upload or an ad creative); absence means unknown and is never a guess."},"internal_chat_message_id":{"type":"integer"},"crm_item_id":{"type":"integer"},"task_id":{"type":"integer"},"catalog_product_id":{"type":"integer"}}},"created_at":{"type":"integer"},"updated_at":{"type":"integer"}}}}},"example":{"payload":{"id":1,"account_id":1,"folder_id":1,"inbox_id":1,"physical_inbox_id":1,"uploaded_by_id":1,"name":"Sample Name","description":"A short description.","file_type":"image","media_kind":"gif","source":"upload","content_type":"sample content type","byte_size":"sample byte size","width":"sample width","height":"sample height","duration":"sample duration","file_name":"sample file name","file_url":"https://example.com/resource","stream_url":"https://example.com/resource","thumb_url":"https://example.com/resource","download_url":"https://example.com/resource","signed_id":"sample signed id","purge_pending":true,"purge_operation_id":1,"archived_at":"2026-01-15T10:30:00.000Z","trash_reason":"source_deleted","retired_source_type":"inbox","source_deleted_at":"2026-01-15T10:30:00.000Z","origin":{"conversation_display_id":1,"contact_id":1,"contact_name":"sample contact name","message_id":1,"chat_kind":"status","internal_chat_message_id":1,"crm_item_id":1,"task_id":1,"catalog_product_id":1},"created_at":1,"updated_at":1}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]},"patch":{"tags":["Media Library"],"operationId":"auto_patch_api_v1_accounts_account_id_media_library_assets_id","summary":"Update assets","description":"Updates the asset identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"folder_id":{"type":"integer"},"inbox_id":{"type":"integer"},"physical_inbox_id":{"type":"integer"},"uploaded_by_id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"file_type":{"type":"string","enum":["image","audio","video","file"],"description":"The high-level media class of an attachment, derived from its content type."},"media_kind":{"type":"string","enum":["gif","sticker","recording","voice"]},"source":{"type":"string","enum":["upload","conversation_capture","recording","imported","internal_chat_capture"]},"content_type":{"type":"string"},"byte_size":{"type":"string"},"width":{"type":"string"},"height":{"type":"string"},"duration":{"type":"string"},"file_name":{"type":"string"},"file_url":{"type":"string"},"stream_url":{"type":"string"},"thumb_url":{"type":"string"},"download_url":{"type":"string"},"signed_id":{"type":"string","description":"Signed Active Storage blob token. Omitted while permanent deletion is pending or when the file is absent."},"purge_pending":{"type":"boolean"},"purge_operation_id":{"type":"integer","description":"Durable deletion operation currently owning this asset. Omitted when no deletion is pending."},"archived_at":{"type":"string","format":"date-time"},"trash_reason":{"type":["string","null"],"enum":["source_deleted",null],"description":"Why the item entered Trash automatically; null when a user archived it."},"retired_source_type":{"type":["string","null"],"enum":["inbox","contact","conversation","crm_pipeline","crm_stage","crm_item","task_list","task","catalog_category","catalog_product","internal_chat_channel","internal_chat_author","campaign","campaign_broadcast","contracts_contract","call","twilio_voice_call","whatsapp_call","macro","canned_response","ads_ad_account","conversations_root","inbox_no_contact","crm_root","tasks_root","catalog_root","internal_chat_root","uncategorized_root","campaigns_root","contracts_root","calls_root","macros_root","canned_root","ads_root",null],"description":"Deleted source formerly represented by this Trash item; null for manual archival."},"source_deleted_at":{"type":["string","null"],"format":"date-time","description":"Time the permanently deleted source caused this item to enter Trash; null otherwise."},"origin":{"type":"object","properties":{"conversation_display_id":{"type":["integer","null"]},"contact_id":{"type":["integer","null"]},"contact_name":{"type":["string","null"]},"message_id":{"type":"integer"},"chat_kind":{"type":"string","enum":["status","group","community","newsletter","direct"],"description":"Which kind of chat the media came from — a status/story broadcast, a group, a community, a channel/newsletter, or a direct one-to-one conversation. Absent when there is no chat to classify (a manual upload or an ad creative); absence means unknown and is never a guess."},"internal_chat_message_id":{"type":"integer"},"crm_item_id":{"type":"integer"},"task_id":{"type":"integer"},"catalog_product_id":{"type":"integer"}}},"created_at":{"type":"integer"},"updated_at":{"type":"integer"}}}}},"example":{"payload":{"id":1,"account_id":1,"folder_id":1,"inbox_id":1,"physical_inbox_id":1,"uploaded_by_id":1,"name":"Sample Name","description":"A short description.","file_type":"image","media_kind":"gif","source":"upload","content_type":"sample content type","byte_size":"sample byte size","width":"sample width","height":"sample height","duration":"sample duration","file_name":"sample file name","file_url":"https://example.com/resource","stream_url":"https://example.com/resource","thumb_url":"https://example.com/resource","download_url":"https://example.com/resource","signed_id":"sample signed id","purge_pending":true,"purge_operation_id":1,"archived_at":"2026-01-15T10:30:00.000Z","trash_reason":"source_deleted","retired_source_type":"inbox","source_deleted_at":"2026-01-15T10:30:00.000Z","origin":{"conversation_display_id":1,"contact_id":1,"contact_name":"sample contact name","message_id":1,"chat_kind":"status","internal_chat_message_id":1,"crm_item_id":1,"task_id":1,"catalog_product_id":1},"created_at":1,"updated_at":1}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"asset":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"folder_id":{"type":"integer"}}}},"required":["asset"]},"example":{"asset":{"name":"Sample Name","description":"A short description.","folder_id":1}}}}}},"put":{"tags":["Media Library"],"operationId":"auto_put_api_v1_accounts_account_id_media_library_assets_id","summary":"Update assets","description":"Updates the asset identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"folder_id":{"type":"integer"},"inbox_id":{"type":"integer"},"physical_inbox_id":{"type":"integer"},"uploaded_by_id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"file_type":{"type":"string","enum":["image","audio","video","file"],"description":"The high-level media class of an attachment, derived from its content type."},"media_kind":{"type":"string","enum":["gif","sticker","recording","voice"]},"source":{"type":"string","enum":["upload","conversation_capture","recording","imported","internal_chat_capture"]},"content_type":{"type":"string"},"byte_size":{"type":"string"},"width":{"type":"string"},"height":{"type":"string"},"duration":{"type":"string"},"file_name":{"type":"string"},"file_url":{"type":"string"},"stream_url":{"type":"string"},"thumb_url":{"type":"string"},"download_url":{"type":"string"},"signed_id":{"type":"string","description":"Signed Active Storage blob token. Omitted while permanent deletion is pending or when the file is absent."},"purge_pending":{"type":"boolean"},"purge_operation_id":{"type":"integer","description":"Durable deletion operation currently owning this asset. Omitted when no deletion is pending."},"archived_at":{"type":"string","format":"date-time"},"trash_reason":{"type":["string","null"],"enum":["source_deleted",null],"description":"Why the item entered Trash automatically; null when a user archived it."},"retired_source_type":{"type":["string","null"],"enum":["inbox","contact","conversation","crm_pipeline","crm_stage","crm_item","task_list","task","catalog_category","catalog_product","internal_chat_channel","internal_chat_author","campaign","campaign_broadcast","contracts_contract","call","twilio_voice_call","whatsapp_call","macro","canned_response","ads_ad_account","conversations_root","inbox_no_contact","crm_root","tasks_root","catalog_root","internal_chat_root","uncategorized_root","campaigns_root","contracts_root","calls_root","macros_root","canned_root","ads_root",null],"description":"Deleted source formerly represented by this Trash item; null for manual archival."},"source_deleted_at":{"type":["string","null"],"format":"date-time","description":"Time the permanently deleted source caused this item to enter Trash; null otherwise."},"origin":{"type":"object","properties":{"conversation_display_id":{"type":["integer","null"]},"contact_id":{"type":["integer","null"]},"contact_name":{"type":["string","null"]},"message_id":{"type":"integer"},"chat_kind":{"type":"string","enum":["status","group","community","newsletter","direct"],"description":"Which kind of chat the media came from — a status/story broadcast, a group, a community, a channel/newsletter, or a direct one-to-one conversation. Absent when there is no chat to classify (a manual upload or an ad creative); absence means unknown and is never a guess."},"internal_chat_message_id":{"type":"integer"},"crm_item_id":{"type":"integer"},"task_id":{"type":"integer"},"catalog_product_id":{"type":"integer"}}},"created_at":{"type":"integer"},"updated_at":{"type":"integer"}}}}},"example":{"payload":{"id":1,"account_id":1,"folder_id":1,"inbox_id":1,"physical_inbox_id":1,"uploaded_by_id":1,"name":"Sample Name","description":"A short description.","file_type":"image","media_kind":"gif","source":"upload","content_type":"sample content type","byte_size":"sample byte size","width":"sample width","height":"sample height","duration":"sample duration","file_name":"sample file name","file_url":"https://example.com/resource","stream_url":"https://example.com/resource","thumb_url":"https://example.com/resource","download_url":"https://example.com/resource","signed_id":"sample signed id","purge_pending":true,"purge_operation_id":1,"archived_at":"2026-01-15T10:30:00.000Z","trash_reason":"source_deleted","retired_source_type":"inbox","source_deleted_at":"2026-01-15T10:30:00.000Z","origin":{"conversation_display_id":1,"contact_id":1,"contact_name":"sample contact name","message_id":1,"chat_kind":"status","internal_chat_message_id":1,"crm_item_id":1,"task_id":1,"catalog_product_id":1},"created_at":1,"updated_at":1}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"asset":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"folder_id":{"type":"integer"}}}},"required":["asset"]},"example":{"asset":{"name":"Sample Name","description":"A short description.","folder_id":1}}}}}},"delete":{"tags":["Media Library"],"operationId":"auto_delete_api_v1_accounts_account_id_media_library_assets_id","summary":"Delete assets","description":"Deletes the asset identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Success (no content)"},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/media_library/purge_operations/{id}/retry":{"post":{"tags":["Media Library"],"operationId":"auto_post_api_v1_accounts_account_id_media_library_purge_operations_id_retry","summary":"Retry a failed permanent media deletion","description":"Requeues a failed operation from its last completed-blob checkpoint. Already deleted storage keys are handled idempotently and the durable blob rows remain available until storage confirms every deletion.","security":[{"userApiKey":[]}],"responses":{"202":{"description":"Failed operation requeued.","content":{"application/json":{"schema":{"type":"object","required":["payload"],"properties":{"payload":{"type":"object","required":["id","status","impact","progress","attempts","error_code","updated_at"],"properties":{"id":{"type":"integer","example":190},"status":{"type":"string","enum":["draft","pending","running","completed","failed"],"example":"draft"},"impact":{"type":"object","required":["selected_asset_ids","selected_assets","affected_assets","affected_references","protected_references","requested_bytes","reclaimable_bytes","protected_bytes","modules"],"properties":{"selected_asset_ids":{"type":"array","items":{"type":"integer"},"example":[81,82]},"selected_assets":{"type":"integer","example":2},"affected_assets":{"type":"integer","example":3},"affected_references":{"type":"integer","example":5},"protected_references":{"type":"integer","example":1},"requested_bytes":{"type":"integer","example":10485760},"reclaimable_bytes":{"type":"integer","example":8388608},"protected_bytes":{"type":"integer","example":2097152},"modules":{"type":"object","description":"Active Storage record type to number of same-account references that will become deleted-media tombstones.","additionalProperties":{"type":"integer"},"example":{"Attachment":2,"Task":1}}}},"progress":{"type":"object","required":["total_blobs","processed_blobs","reclaimed_bytes","protected_blobs","completed_blob_ids"],"properties":{"total_blobs":{"type":"integer","example":2},"processed_blobs":{"type":"integer","example":0},"reclaimed_bytes":{"type":"integer","example":0},"protected_blobs":{"type":"integer","example":0},"completed_blob_ids":{"type":"array","items":{"type":"integer"},"example":[]}}},"attempts":{"type":"integer","example":0},"error_code":{"type":["string","null"],"enum":["storage_delete_failed",null],"example":null},"confirmed_at":{"type":["string","null"],"format":"date-time","example":null},"started_at":{"type":["string","null"],"format":"date-time","example":null},"finished_at":{"type":["string","null"],"format":"date-time","example":null},"updated_at":{"type":"string","format":"date-time","example":"2026-08-18T19:00:00Z"}}}}},"example":{"payload":{"id":190,"status":"draft","impact":{"selected_asset_ids":[81,82],"selected_assets":2,"affected_assets":3,"affected_references":5,"protected_references":1,"requested_bytes":10485760,"reclaimable_bytes":8388608,"protected_bytes":2097152,"modules":{"Attachment":2,"Task":1}},"progress":{"total_blobs":2,"processed_blobs":0,"reclaimed_bytes":0,"protected_blobs":0,"completed_blob_ids":[]},"attempts":0,"error_code":null,"confirmed_at":null,"started_at":null,"finished_at":null,"updated_at":"2026-08-18T19:00:00Z"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"The operation does not belong to this account or does not exist."},"422":{"description":"Only an operation currently in failed status can be retried."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/media_library/purge_operations/{id}":{"get":{"tags":["Media Library"],"operationId":"auto_get_api_v1_accounts_account_id_media_library_purge_operations_id","summary":"Read permanent media deletion status","description":"Returns durable progress for an account-scoped deletion. Completed blob ids are checkpointed, a crashed worker is recovered by lease, and failed storage attempts keep the operation available for a manual retry. Raw provider errors and storage keys are never exposed.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Current durable deletion state.","content":{"application/json":{"schema":{"type":"object","required":["payload"],"properties":{"payload":{"type":"object","required":["id","status","impact","progress","attempts","error_code","updated_at"],"properties":{"id":{"type":"integer","example":190},"status":{"type":"string","enum":["draft","pending","running","completed","failed"],"example":"draft"},"impact":{"type":"object","required":["selected_asset_ids","selected_assets","affected_assets","affected_references","protected_references","requested_bytes","reclaimable_bytes","protected_bytes","modules"],"properties":{"selected_asset_ids":{"type":"array","items":{"type":"integer"},"example":[81,82]},"selected_assets":{"type":"integer","example":2},"affected_assets":{"type":"integer","example":3},"affected_references":{"type":"integer","example":5},"protected_references":{"type":"integer","example":1},"requested_bytes":{"type":"integer","example":10485760},"reclaimable_bytes":{"type":"integer","example":8388608},"protected_bytes":{"type":"integer","example":2097152},"modules":{"type":"object","description":"Active Storage record type to number of same-account references that will become deleted-media tombstones.","additionalProperties":{"type":"integer"},"example":{"Attachment":2,"Task":1}}}},"progress":{"type":"object","required":["total_blobs","processed_blobs","reclaimed_bytes","protected_blobs","completed_blob_ids"],"properties":{"total_blobs":{"type":"integer","example":2},"processed_blobs":{"type":"integer","example":0},"reclaimed_bytes":{"type":"integer","example":0},"protected_blobs":{"type":"integer","example":0},"completed_blob_ids":{"type":"array","items":{"type":"integer"},"example":[]}}},"attempts":{"type":"integer","example":0},"error_code":{"type":["string","null"],"enum":["storage_delete_failed",null],"example":null},"confirmed_at":{"type":["string","null"],"format":"date-time","example":null},"started_at":{"type":["string","null"],"format":"date-time","example":null},"finished_at":{"type":["string","null"],"format":"date-time","example":null},"updated_at":{"type":"string","format":"date-time","example":"2026-08-18T19:00:00Z"}}}}},"example":{"payload":{"id":190,"status":"draft","impact":{"selected_asset_ids":[81,82],"selected_assets":2,"affected_assets":3,"affected_references":5,"protected_references":1,"requested_bytes":10485760,"reclaimable_bytes":8388608,"protected_bytes":2097152,"modules":{"Attachment":2,"Task":1}},"progress":{"total_blobs":2,"processed_blobs":0,"reclaimed_bytes":0,"protected_blobs":0,"completed_blob_ids":[]},"attempts":0,"error_code":null,"confirmed_at":null,"started_at":null,"finished_at":null,"updated_at":"2026-08-18T19:00:00Z"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"The operation does not belong to this account or does not exist."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/media_library/settings":{"get":{"tags":["Media Library"],"operationId":"auto_get_api_v1_accounts_account_id_media_library_settings","summary":"Get settings","description":"Returns the setting identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"auto_purge_trash_days":{"type":"integer"},"capture_all":{"type":"boolean"},"capture_inbox_ids":{"type":"array","items":{"type":"integer"}}}}}},"example":{"payload":{"id":1,"account_id":1,"auto_purge_trash_days":7,"capture_all":true,"capture_inbox_ids":[1]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]},"patch":{"tags":["Media Library"],"operationId":"auto_patch_api_v1_accounts_account_id_media_library_settings","summary":"Update settings","description":"Updates the setting identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"auto_purge_trash_days":{"type":"integer"},"capture_all":{"type":"boolean"},"capture_inbox_ids":{"type":"array","items":{"type":"integer"}}}}}},"example":{"payload":{"id":1,"account_id":1,"auto_purge_trash_days":7,"capture_all":true,"capture_inbox_ids":[1]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"setting":{"type":"object","properties":{"auto_purge_trash_days":{"type":"integer"},"capture_all":{"type":"string"},"capture_inbox_ids":{"type":"array","items":{"type":"integer"}}}}},"required":["setting"]},"example":{"setting":{"auto_purge_trash_days":7,"capture_all":"sample capture all","capture_inbox_ids":[1]}}}}}},"put":{"tags":["Media Library"],"operationId":"auto_put_api_v1_accounts_account_id_media_library_settings","summary":"Update settings","description":"Updates the setting identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"auto_purge_trash_days":{"type":"integer"},"capture_all":{"type":"boolean"},"capture_inbox_ids":{"type":"array","items":{"type":"integer"}}}}}},"example":{"payload":{"id":1,"account_id":1,"auto_purge_trash_days":7,"capture_all":true,"capture_inbox_ids":[1]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"setting":{"type":"object","properties":{"auto_purge_trash_days":{"type":"integer"},"capture_all":{"type":"string"},"capture_inbox_ids":{"type":"array","items":{"type":"integer"}}}}},"required":["setting"]},"example":{"setting":{"auto_purge_trash_days":7,"capture_all":"sample capture all","capture_inbox_ids":[1]}}}}}}},"/api/v1/accounts/{account_id}/media_library/import":{"post":{"tags":["Media Library"],"operationId":"auto_post_api_v1_accounts_account_id_media_library_import","summary":"Import existing media into the library","description":"Enqueues a full backfill that scans media already attached elsewhere in the account — conversation attachments, deal and task files, catalog images — and registers them in the media library. The existing files are reused, so the import does not increase storage usage, and it is idempotent: re-running it never duplicates an asset. The scan runs in the background, so the endpoint returns HTTP 200 with an EMPTY body as soon as the job is queued; refetch the asset list to watch the imported items appear.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The import was queued. Empty body — the imported assets do not exist yet when this response is received."},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"403":{"description":"Only administrators, or agents holding the media library management role, may start an import."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/notifications/read_all":{"post":{"tags":["Notifications"],"operationId":"auto_post_api_v1_accounts_account_id_notifications_read_all","summary":"Mark notifications as read","description":"Stamps the calling user's unread notifications in this account as read. Naming a primary actor narrows the change to the notifications raised by that one record, which is what marks a single conversation's notifications as read; omitting it marks every unread notification in the account as read. A primary actor that is not a recognised type, or that matches no record, is ignored and the call falls back to marking everything as read. The response carries no body.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Matching notifications stamped as read. Empty body."},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"primary_actor_type":{"type":"string","description":"Type of the record whose notifications should be marked as read. Any other value is ignored and every unread notification is marked instead.","enum":["Conversation","Task","Crm::Item","Payments::Charge","Calendar::Event","FollowUp::Enrollment","InternalChat::Message","AccountBrain::Insight","AccountBrain::DepartmentRun","Sales::GoalTier","Wfm::StatusEvent"]},"primary_actor_id":{"type":"integer","description":"Identifier of that record. Ignored when the type is absent or unrecognised."}}},"example":{"primary_actor_type":"Conversation","primary_actor_id":42}}}}}},"/api/v1/accounts/{account_id}/notifications/unread_count":{"get":{"tags":["Notifications"],"operationId":"auto_get_api_v1_accounts_account_id_notifications_unread_count","summary":"Unread count notifications","description":"Performs the unread count operation on the targeted notification resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Count of unread (and not snoozed) notifications for the current user","content":{"application/json":{"schema":{"type":"integer","example":5},"example":5}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/notifications/destroy_all":{"post":{"tags":["Notifications"],"operationId":"auto_post_api_v1_accounts_account_id_notifications_destroy_all","summary":"Delete notifications","description":"Deletes the calling user's notifications in this account, either all of them or only the ones already read. The deletion is queued and carried out in the background, so the call returns as soon as it is accepted and not when the records are gone. The response carries no body, so it does not report how many were removed.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Deletion queued for the matching notifications. Empty body."},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","description":"Which notifications to delete. Only `read` is special-cased; EVERY other value — including `all`, including a typo — falls through and deletes all of them. Left without an enum on purpose: the server accepts any string here, and declaring a closed set would make a generated client reject values the API takes.","example":"read"}}},"example":{"type":"read"}}}}}},"/api/v1/accounts/{account_id}/notifications/{id}/snooze":{"post":{"tags":["Notifications"],"operationId":"auto_post_api_v1_accounts_account_id_notifications_id_snooze","summary":"Snooze notifications","description":"Performs the snooze operation on the targeted notification resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Notification snoozed (raw record)","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer","example":4021},"notification_type":{"type":"string","example":"conversation_assignment","enum":["conversation_creation","conversation_assignment","assigned_conversation_new_message","conversation_mention","participating_conversation_new_message","sla_missed_first_response","sla_missed_next_response","sla_missed_resolution","task_assigned","task_due_reminder","task_sla_breached","crm_item_assigned","crm_item_sla_breached","crm_item_close_date_reminder","payment_charge_paid","payment_charge_failed","payment_charge_overdue","calendar_booking_created","calendar_event_no_show","follow_up_hitl_pending","follow_up_reply_received","follow_up_enrollment_failed","internal_chat_mention","internal_chat_direct_message","internal_chat_announcement","maestro_brain_insight","maestro_handoff_requested","maestro_action_failed","sales_tier_reached","maestro_approval_requested","wfm_break_breached"],"description":"The event that produced the notification."},"primary_actor_type":{"type":"string","example":"Conversation"},"primary_actor_id":{"type":"integer","example":8817},"secondary_actor_type":{"type":["string","null"],"example":null},"secondary_actor_id":{"type":["integer","null"],"example":null},"read_at":{"type":["string","null"],"format":"date-time","example":null},"snoozed_until":{"type":["string","null"],"format":"date-time","example":"2026-01-20T09:00:00.000Z"},"last_activity_at":{"type":["string","null"],"format":"date-time","example":"2026-01-15T10:29:00.000Z"},"meta":{"type":["object","null"],"example":{"last_snoozed_at":null},"additionalProperties":true,"description":"Free-form per-notification metadata."},"account_id":{"type":"integer","example":1},"user_id":{"type":"integer","example":7},"created_at":{"type":"string","format":"date-time","example":"2026-01-15T10:28:00.000Z"},"updated_at":{"type":"string","format":"date-time","example":"2026-01-15T10:32:00.000Z"}}},"example":{"id":4021,"notification_type":"conversation_assignment","primary_actor_type":"Conversation","primary_actor_id":8817,"secondary_actor_type":null,"secondary_actor_id":null,"read_at":null,"snoozed_until":"2026-01-20T09:00:00.000Z","last_activity_at":"2026-01-15T10:29:00.000Z","meta":{"last_snoozed_at":null},"account_id":1,"user_id":7,"created_at":"2026-01-15T10:28:00.000Z","updated_at":"2026-01-15T10:32:00.000Z"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"snoozed_until":{"type":"string","format":"date-time","description":"Snooze the notification until this time (parsed via DateRangeHelper). Omit/blank leaves it unchanged.","example":"2026-01-20T09:00:00.000Z"}}},"example":{"snoozed_until":"2026-01-20T09:00:00.000Z"}}}}}},"/api/v1/accounts/{account_id}/notifications/{id}/unread":{"post":{"tags":["Notifications"],"operationId":"auto_post_api_v1_accounts_account_id_notifications_id_unread","summary":"Unread notifications","description":"Performs the unread operation on the targeted notification resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Notification marked unread (raw record)","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer","example":4021},"notification_type":{"type":"string","example":"conversation_assignment","enum":["conversation_creation","conversation_assignment","assigned_conversation_new_message","conversation_mention","participating_conversation_new_message","sla_missed_first_response","sla_missed_next_response","sla_missed_resolution","task_assigned","task_due_reminder","task_sla_breached","crm_item_assigned","crm_item_sla_breached","crm_item_close_date_reminder","payment_charge_paid","payment_charge_failed","payment_charge_overdue","calendar_booking_created","calendar_event_no_show","follow_up_hitl_pending","follow_up_reply_received","follow_up_enrollment_failed","internal_chat_mention","internal_chat_direct_message","internal_chat_announcement","maestro_brain_insight","maestro_handoff_requested","maestro_action_failed","sales_tier_reached","maestro_approval_requested","wfm_break_breached"],"description":"The event that produced the notification."},"primary_actor_type":{"type":"string","example":"Conversation"},"primary_actor_id":{"type":"integer","example":8817},"secondary_actor_type":{"type":["string","null"],"example":"User"},"secondary_actor_id":{"type":["integer","null"],"example":12},"read_at":{"type":["string","null"],"format":"date-time","example":null},"snoozed_until":{"type":["string","null"],"format":"date-time","example":null},"last_activity_at":{"type":["string","null"],"format":"date-time","example":"2026-01-15T10:29:00.000Z"},"meta":{"type":"object","additionalProperties":true,"description":"Free-form per-notification metadata."},"account_id":{"type":"integer","example":1},"user_id":{"type":"integer","example":7},"created_at":{"type":"string","format":"date-time","example":"2026-01-15T10:28:00.000Z"},"updated_at":{"type":"string","format":"date-time","example":"2026-01-15T10:31:00.000Z"}}},"example":{"id":4021,"notification_type":"conversation_assignment","primary_actor_type":"Conversation","primary_actor_id":8817,"secondary_actor_type":"User","secondary_actor_id":12,"read_at":null,"snoozed_until":null,"last_activity_at":"2026-01-15T10:29:00.000Z","meta":{},"account_id":1,"user_id":7,"created_at":"2026-01-15T10:28:00.000Z","updated_at":"2026-01-15T10:31:00.000Z"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/notifications":{"get":{"tags":["Notifications"],"operationId":"auto_get_api_v1_accounts_account_id_notifications","summary":"List notifications","description":"Returns the list of notifications visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Paginated notifications for the current user","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"meta":{"type":"object","properties":{"unread_count":{"type":"integer","example":5},"count":{"type":"integer","example":42},"current_page":{"type":"integer","example":1}},"description":"Free-form per-notification metadata."},"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","example":4021},"notification_type":{"type":"string","enum":["conversation_creation","conversation_assignment","assigned_conversation_new_message","conversation_mention","participating_conversation_new_message","sla_missed_first_response","sla_missed_next_response","sla_missed_resolution","task_assigned","task_due_reminder","task_sla_breached","crm_item_assigned","crm_item_sla_breached","crm_item_close_date_reminder","payment_charge_paid","payment_charge_failed","payment_charge_overdue","calendar_booking_created","calendar_event_no_show","follow_up_hitl_pending","follow_up_reply_received","follow_up_enrollment_failed","internal_chat_mention","internal_chat_direct_message","internal_chat_announcement","maestro_brain_insight","maestro_handoff_requested","maestro_action_failed","sales_tier_reached","maestro_approval_requested","wfm_break_breached"],"example":"conversation_assignment","description":"The event that produced the notification."},"push_message_title":{"type":"string","example":"Conversation #123 was assigned to you"},"push_message_body":{"type":"string","example":"A new conversation is assigned to you"},"primary_actor_type":{"type":"string","example":"Conversation"},"primary_actor_id":{"type":"integer","example":8817},"primary_actor":{"type":"object","description":"primary_actor.push_event_data (polymorphic — shape depends on primary_actor_type)","additionalProperties":true,"example":{"id":8817,"display_id":123,"status":"open","inbox_id":4}},"read_at":{"type":["string","null"],"format":"date-time","example":null},"secondary_actor":{"type":["object","null"],"description":"secondary_actor.push_event_data (nil for system actions)","additionalProperties":true,"example":null},"user":{"type":"object","description":"user.push_event_data","additionalProperties":true,"example":{"id":7,"name":"Jane Agent","available_name":"Jane","avatar_url":"https://cdn.example.com/avatars/7.png"}},"created_at":{"type":"integer","description":"Unix epoch seconds","example":1737024540},"last_activity_at":{"type":"integer","description":"Unix epoch seconds","example":1737024600},"snoozed_until":{"type":["string","null"],"format":"date-time","example":null},"meta":{"type":"object","additionalProperties":true,"description":"Free-form per-notification metadata."}}}}}}}},"example":{"data":{"meta":{"unread_count":5,"count":42,"current_page":1},"payload":[{"id":4021,"notification_type":"conversation_assignment","push_message_title":"Conversation #123 was assigned to you","push_message_body":"A new conversation is assigned to you","primary_actor_type":"Conversation","primary_actor_id":8817,"primary_actor":{"id":8817,"display_id":123,"status":"open","inbox_id":4},"read_at":null,"secondary_actor":null,"user":{"id":7,"name":"Jane Agent","available_name":"Jane","avatar_url":"https://cdn.example.com/avatars/7.png"},"created_at":1737024540,"last_activity_at":1737024600,"snoozed_until":null,"meta":{}}]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."}]}},"/api/v1/accounts/{account_id}/notifications/{id}":{"patch":{"tags":["Notifications"],"operationId":"auto_patch_api_v1_accounts_account_id_notifications_id","summary":"Update notifications","description":"Updates the notification identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Notification marked read (raw record)","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer","example":4021},"notification_type":{"type":"string","example":"conversation_assignment","enum":["conversation_creation","conversation_assignment","assigned_conversation_new_message","conversation_mention","participating_conversation_new_message","sla_missed_first_response","sla_missed_next_response","sla_missed_resolution","task_assigned","task_due_reminder","task_sla_breached","crm_item_assigned","crm_item_sla_breached","crm_item_close_date_reminder","payment_charge_paid","payment_charge_failed","payment_charge_overdue","calendar_booking_created","calendar_event_no_show","follow_up_hitl_pending","follow_up_reply_received","follow_up_enrollment_failed","internal_chat_mention","internal_chat_direct_message","internal_chat_announcement","maestro_brain_insight","maestro_handoff_requested","maestro_action_failed","sales_tier_reached","maestro_approval_requested","wfm_break_breached"],"description":"The event that produced the notification."},"primary_actor_type":{"type":"string","example":"Conversation"},"primary_actor_id":{"type":"integer","example":8817},"secondary_actor_type":{"type":["string","null"],"example":"User"},"secondary_actor_id":{"type":["integer","null"],"example":12},"read_at":{"type":["string","null"],"format":"date-time","example":"2026-01-15T10:30:00.000Z"},"snoozed_until":{"type":["string","null"],"format":"date-time","example":null},"last_activity_at":{"type":["string","null"],"format":"date-time","example":"2026-01-15T10:29:00.000Z"},"meta":{"type":"object","additionalProperties":true,"description":"Free-form per-notification metadata."},"account_id":{"type":"integer","example":1},"user_id":{"type":"integer","example":7},"created_at":{"type":"string","format":"date-time","example":"2026-01-15T10:28:00.000Z"},"updated_at":{"type":"string","format":"date-time","example":"2026-01-15T10:30:00.000Z"}}},"example":{"id":4021,"notification_type":"conversation_assignment","primary_actor_type":"Conversation","primary_actor_id":8817,"secondary_actor_type":"User","secondary_actor_id":12,"read_at":"2026-01-15T10:30:00.000Z","snoozed_until":null,"last_activity_at":"2026-01-15T10:29:00.000Z","meta":{},"account_id":1,"user_id":7,"created_at":"2026-01-15T10:28:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]},"put":{"tags":["Notifications"],"operationId":"auto_put_api_v1_accounts_account_id_notifications_id","summary":"Update notifications","description":"Updates the notification identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Notification marked read (raw record)","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer","example":4021},"notification_type":{"type":"string","example":"conversation_assignment","enum":["conversation_creation","conversation_assignment","assigned_conversation_new_message","conversation_mention","participating_conversation_new_message","sla_missed_first_response","sla_missed_next_response","sla_missed_resolution","task_assigned","task_due_reminder","task_sla_breached","crm_item_assigned","crm_item_sla_breached","crm_item_close_date_reminder","payment_charge_paid","payment_charge_failed","payment_charge_overdue","calendar_booking_created","calendar_event_no_show","follow_up_hitl_pending","follow_up_reply_received","follow_up_enrollment_failed","internal_chat_mention","internal_chat_direct_message","internal_chat_announcement","maestro_brain_insight","maestro_handoff_requested","maestro_action_failed","sales_tier_reached","maestro_approval_requested","wfm_break_breached"],"description":"The event that produced the notification."},"primary_actor_type":{"type":"string","example":"Conversation"},"primary_actor_id":{"type":"integer","example":8817},"secondary_actor_type":{"type":["string","null"],"example":"User"},"secondary_actor_id":{"type":["integer","null"],"example":12},"read_at":{"type":["string","null"],"format":"date-time","example":"2026-01-15T10:30:00.000Z"},"snoozed_until":{"type":["string","null"],"format":"date-time","example":null},"last_activity_at":{"type":["string","null"],"format":"date-time","example":"2026-01-15T10:29:00.000Z"},"meta":{"type":"object","additionalProperties":true,"description":"Free-form per-notification metadata."},"account_id":{"type":"integer","example":1},"user_id":{"type":"integer","example":7},"created_at":{"type":"string","format":"date-time","example":"2026-01-15T10:28:00.000Z"},"updated_at":{"type":"string","format":"date-time","example":"2026-01-15T10:30:00.000Z"}}},"example":{"id":4021,"notification_type":"conversation_assignment","primary_actor_type":"Conversation","primary_actor_id":8817,"secondary_actor_type":"User","secondary_actor_id":12,"read_at":"2026-01-15T10:30:00.000Z","snoozed_until":null,"last_activity_at":"2026-01-15T10:29:00.000Z","meta":{},"account_id":1,"user_id":7,"created_at":"2026-01-15T10:28:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]},"delete":{"tags":["Notifications"],"operationId":"auto_delete_api_v1_accounts_account_id_notifications_id","summary":"Delete notifications","description":"Deletes the notification identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Success (no content)"},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/notification_settings":{"get":{"tags":["Notifications"],"operationId":"auto_get_api_v1_accounts_account_id_notification_settings","summary":"Get notification settings","description":"Returns the notification setting identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"user_id":{"type":"integer"},"account_id":{"type":"integer"},"all_email_flags":{"type":"string"},"selected_email_flags":{"type":"string"},"all_push_flags":{"type":"string"},"selected_push_flags":{"type":"string"}}},"example":{"id":1,"user_id":1,"account_id":1,"all_email_flags":"agent@example.com","selected_email_flags":"agent@example.com","all_push_flags":"sample all push flags","selected_push_flags":"sample selected push flags"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]},"patch":{"tags":["Notifications"],"operationId":"auto_patch_api_v1_accounts_account_id_notification_settings","summary":"Update notification settings","description":"Updates the notification setting identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"user_id":{"type":"integer"},"account_id":{"type":"integer"},"all_email_flags":{"type":"string"},"selected_email_flags":{"type":"string"},"all_push_flags":{"type":"string"},"selected_push_flags":{"type":"string"}}},"example":{"id":1,"user_id":1,"account_id":1,"all_email_flags":"agent@example.com","selected_email_flags":"agent@example.com","all_push_flags":"sample all push flags","selected_push_flags":"sample selected push flags"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"notification_settings":{"type":"object","properties":{"selected_email_flags":{"type":"array","items":{"type":"string"}},"selected_push_flags":{"type":"array","items":{"type":"string"}}}}},"required":["notification_settings"]},"example":{"notification_settings":{"selected_email_flags":["agent@example.com"],"selected_push_flags":["sample selected push flag"]}}}}}},"put":{"tags":["Notifications"],"operationId":"auto_put_api_v1_accounts_account_id_notification_settings","summary":"Update notification settings","description":"Updates the notification setting identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"user_id":{"type":"integer"},"account_id":{"type":"integer"},"all_email_flags":{"type":"string"},"selected_email_flags":{"type":"string"},"all_push_flags":{"type":"string"},"selected_push_flags":{"type":"string"}}},"example":{"id":1,"user_id":1,"account_id":1,"all_email_flags":"agent@example.com","selected_email_flags":"agent@example.com","all_push_flags":"sample all push flags","selected_push_flags":"sample selected push flags"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"notification_settings":{"type":"object","properties":{"selected_email_flags":{"type":"array","items":{"type":"string"}},"selected_push_flags":{"type":"array","items":{"type":"string"}}}}},"required":["notification_settings"]},"example":{"notification_settings":{"selected_email_flags":["agent@example.com"],"selected_push_flags":["sample selected push flag"]}}}}}}},"/api/v1/accounts/{account_id}/assignment_policies/{assignment_policy_id}/inboxes":{"get":{"tags":["Assignment Policies"],"operationId":"auto_get_api_v1_accounts_account_id_assignment_policies_assignment_policy_id_inboxes","summary":"List inboxes","description":"Returns the list of inboxes visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"inboxes":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"avatar_url":{"type":"string"},"channel_id":{"type":"integer"},"name":{"type":"string"},"channel_type":{"type":"string","enum":["Channel::Api","Channel::Email","Channel::FacebookPage","Channel::Instagram","Channel::Line","Channel::Sms","Channel::Telegram","Channel::Tiktok","Channel::TwilioSms","Channel::TwitterProfile","Channel::WebWidget","Channel::Whatsapp"],"description":"The inbox channel class — identifies which messaging channel backs the inbox."},"greeting_enabled":{"type":"boolean"},"greeting_message":{"type":"string"},"working_hours_enabled":{"type":"boolean"},"enable_email_collect":{"type":"string"},"csat_survey_enabled":{"type":"boolean"},"csat_config":{"type":"string"},"enable_auto_assignment":{"type":"string"},"auto_assignment_config":{"type":"string"},"out_of_office_message":{"type":"string"},"working_hours":{"type":"string"},"timezone":{"type":"string","description":"IANA timezone identifier (e.g. \"America/Sao_Paulo\", \"UTC\"). Rails timezone names are also accepted on input; an unrecognized value is ignored in favor of the next fallback.","example":"America/Sao_Paulo"},"callback_webhook_url":{"type":"string"},"allow_messages_after_resolved":{"type":"string"},"lock_to_single_conversation":{"type":"string"},"audio_transcription_enabled":{"type":"boolean"},"preserve_deleted_messages":{"type":"string"},"allow_message_deletion":{"type":"string"},"capture_view_once":{"type":"string"},"sender_name_type":{"type":"string","enum":["friendly","professional"]},"auto_resolve_config":{"type":"object","additionalProperties":true,"oneOf":[{"type":"object","maxProperties":0,"additionalProperties":true,"description":"Empty means inherit the account rule."},{"type":"object","additionalProperties":false,"required":["mode"],"properties":{"mode":{"type":"string","enum":["disabled"],"description":"Disable automatic resolution for this inbox."}},"description":"The disabled rule contains only its mode."},{"type":"object","additionalProperties":false,"required":["mode","after","message","label","allow_waiting"],"properties":{"mode":{"type":"string","enum":["custom"],"description":"Use this complete inbox rule."},"after":{"type":"integer","minimum":10,"maximum":1439856,"description":"Inactivity in minutes; required for custom mode."},"message":{"type":["string","null"],"maxLength":10000,"description":"Optional message; blank normalizes to null."},"label":{"type":["string","null"],"description":"An existing account label title, or null."},"allow_waiting":{"type":"boolean","description":"Whether waiting conversations are included."}},"description":"Complete normalized custom rule."}],"description":"Normalized JSON rule from valid model writes: empty, disabled, or complete custom configuration.","example":{"mode":"custom","after":60,"message":null,"label":null,"allow_waiting":false}},"outbound_agent_name_header_policy":{"type":"string"},"agent_bot_working_hours_mode":{"type":"string","enum":["always","inside_business_hours","outside_business_hours"]},"business_name":{"type":"string"},"responder_policy":{"type":"string"},"help_center":{"type":"object","properties":{"name":{"type":"string"},"slug":{"type":"string"}}},"tweets_enabled":{"type":"boolean"},"allowed_domains":{"type":"string"},"widget_color":{"type":"string"},"website_url":{"type":"string"},"hmac_mandatory":{"type":"string"},"welcome_title":{"type":"string"},"welcome_tagline":{"type":"string"},"web_widget_script":{"type":"string"},"website_token":{"type":"string"},"selected_feature_flags":{"type":"string"},"reply_time":{"type":"string","format":"date-time"},"hmac_token":{"type":"string"},"pre_chat_form_enabled":{"type":"boolean"},"pre_chat_form_options":{"type":"string"},"continuity_via_email":{"type":"string","format":"email"},"page_id":{"type":"integer"},"reauthorization_required":{"type":"string"},"instagram_id":{"type":"integer"},"messaging_service_sid":{"type":"string"},"phone_number":{"type":"string"},"medium":{"type":"string"},"bandwidth_callback_state":{"type":"string","enum":["active","reconnect_required","reconciling","reconciliation_required","encryption_required"]},"bandwidth_api_migration_state":{"type":"string","enum":["oauth2_configured","oauth2_required","configuration_required"]},"bandwidth_legacy_basic_deprecated":{"type":"boolean"},"content_templates":{"type":"string"},"auth_token":{"type":"string"},"account_sid":{"type":"string"},"api_key_sid":{"type":"string"},"twilio_credential_state":{"type":"string","enum":["ready","pending","failed","dead_letter","account_auth_token_required","reconciliation_required"],"description":"Durable Twilio credential lifecycle derived from Channel::TwilioSms. A reconciliation-required state is fail-closed until the provider outcome has been verified."},"api_key_configured":{"type":"boolean"},"email":{"type":"string","format":"email"},"auth_method":{"type":"string"},"forwarding_enabled":{"type":"boolean"},"forward_to_email":{"type":"string","format":"email"},"branded_email_layout":{"type":"string"},"imap_login":{"type":"string"},"imap_password":{"type":"string"},"imap_address":{"type":"string"},"imap_port":{"type":"string"},"imap_enabled":{"type":"boolean"},"imap_enable_ssl":{"type":"string"},"imap_authentication":{"type":"string"},"smtp_login":{"type":"string"},"smtp_password":{"type":"string"},"smtp_address":{"type":"string"},"smtp_port":{"type":"string"},"smtp_enabled":{"type":"boolean"},"smtp_domain":{"type":"string"},"smtp_enable_ssl_tls":{"type":"string"},"smtp_enable_starttls_auto":{"type":"string"},"smtp_openssl_verify_mode":{"type":"string","enum":["none","peer","client_once","fail_if_no_peer_cert"],"description":"OpenSSL peer-certificate verification mode for the email channel's SMTP connection."},"smtp_authentication":{"type":"string"},"secret":{"type":"string"},"webhook_url":{"type":"string"},"inbox_identifier":{"type":"string"},"additional_attributes":{"type":"object","additionalProperties":true,"description":"Channel- and source-specific metadata for this record (e.g. browser info, referer, social profile identifiers). The key set depends on the originating channel."},"provider":{"type":"string","enum":["default","whatsapp_cloud","whatsapp_web","google","microsoft"],"description":"Messaging provider backing the inbox channel (whatsapp_web is the WazMeow gateway; email uses google/microsoft; default otherwise)."},"bot_name":{"type":"string"},"message_templates":{"type":"boolean"},"provider_config":{"type":"string"},"business_management_token_configured":{"type":"boolean"},"hybrid_pair":{"$ref":"#/components/schemas/inbox/properties/hybrid_pair"},"whatsapp_web_session_state":{"$ref":"#/components/schemas/inbox/properties/whatsapp_web_session_state"},"hybrid_hidden":{"type":"string"},"logical_inbox_id":{"type":"integer"},"whatsapp_pending_phone":{"type":"object","nullable":true,"description":"Spec 052 — set only when a WhatsApp phone-number rewrite was REFUSED because a non-sibling channel already holds the number, leaving the inbox on its `pending:` placeholder and inert. `null` in every normal case (including a routine, not-yet-scanned pairing).","additionalProperties":false,"properties":{"awaiting_pair":{"type":"boolean","description":"True while the inbox is still on its `pending:\u003cuuid\u003e` placeholder number."},"phone":{"type":"string","description":"The E.164 number the rewrite tried to claim."},"reason":{"type":"string","enum":["same_account_same_provider","other_account"],"description":"Why the rewrite was refused. `other_account` never carries any identifying detail about the other account."},"sibling_inbox_id":{"type":"integer","nullable":true,"description":"Colliding inbox in the SAME account; absent when the collision is cross-account."},"source":{"type":"string","enum":["pair_success","qr_pump"],"description":"Which path attempted the rewrite."},"at":{"type":"string","format":"date-time","description":"When the refusal was recorded."}}},"whatsapp_sibling_notice":{"type":"string"},"whatsapp_web_contact_request":{"type":"string","enum":["supported","unsupported","unknown"],"description":"WhatsApp Web inboxes only — whether this inbox's WazMeow gateway serves the request that asks a customer to share their phone number. `supported` and `unsupported` come from a no-effect probe of the gateway route, refreshed at most hourly and immediately when a real send finds the route missing; `unknown` means not probed yet or the gateway could not be reached. Only `supported` turns the feature on; with `unknown` the request is refused before any gateway call while the probe runs."},"voice_enabled":{"type":"boolean"},"inbound_calls_enabled":{"type":"boolean"},"voice_configured":{"type":"boolean"},"voice_call_webhook_url":{"type":"string"},"voice_status_webhook_url":{"type":"string"}}}}}},"example":{"inboxes":[{"id":1,"avatar_url":"https://example.com/resource","channel_id":1,"name":"Sample Name","channel_type":"Channel::Api","greeting_enabled":true,"greeting_message":"sample greeting message","working_hours_enabled":true,"enable_email_collect":"agent@example.com","csat_survey_enabled":true,"csat_config":"sample csat config","enable_auto_assignment":"sample enable auto assignment","auto_assignment_config":"sample auto assignment config","out_of_office_message":"sample out of office message","working_hours":"sample working hours","timezone":"America/Sao_Paulo","callback_webhook_url":"https://example.com/resource","allow_messages_after_resolved":"sample allow messages after resolved","lock_to_single_conversation":"sample lock to single conversation","audio_transcription_enabled":true,"preserve_deleted_messages":"sample preserve deleted messages","allow_message_deletion":"sample allow message deletion","capture_view_once":"sample capture view once","sender_name_type":"friendly","auto_resolve_config":{"mode":"custom","after":60,"message":null,"label":null,"allow_waiting":false},"outbound_agent_name_header_policy":"sample outbound agent name header policy","agent_bot_working_hours_mode":"always","business_name":"sample business name","responder_policy":"sample responder policy","help_center":{"name":"Sample Name","slug":"sample-slug"},"tweets_enabled":true,"allowed_domains":"sample allowed domains","widget_color":"#1F93FF","website_url":"https://example.com/resource","hmac_mandatory":"sample hmac mandatory","welcome_title":"sample welcome title","welcome_tagline":"sample welcome tagline","web_widget_script":"sample web widget script","website_token":"sample-token","selected_feature_flags":"sample selected feature flags","reply_time":"2026-01-15T10:30:00.000Z","hmac_token":"sample-token","pre_chat_form_enabled":true,"pre_chat_form_options":"sample pre chat form options","continuity_via_email":"agent@example.com","page_id":1,"reauthorization_required":"sample reauthorization required","instagram_id":1,"messaging_service_sid":"sample messaging service sid","phone_number":"+5511999998888","medium":"sample medium","bandwidth_callback_state":"active","bandwidth_api_migration_state":"oauth2_configured","bandwidth_legacy_basic_deprecated":true,"content_templates":"sample content templates","auth_token":"sample-token","account_sid":"sample account sid","api_key_sid":"sample api key sid","twilio_credential_state":"ready","api_key_configured":true,"email":"agent@example.com","auth_method":"sample auth method","forwarding_enabled":true,"forward_to_email":"agent@example.com","branded_email_layout":"agent@example.com","imap_login":"sample imap login","imap_password":"sample imap password","imap_address":"sample imap address","imap_port":"sample imap port","imap_enabled":true,"imap_enable_ssl":"sample imap enable ssl","imap_authentication":"sample imap authentication","smtp_login":"sample smtp login","smtp_password":"sample smtp password","smtp_address":"sample smtp address","smtp_port":"sample smtp port","smtp_enabled":true,"smtp_domain":"sample smtp domain","smtp_enable_ssl_tls":"sample smtp enable ssl tls","smtp_enable_starttls_auto":"sample smtp enable starttls auto","smtp_openssl_verify_mode":"none","smtp_authentication":"sample smtp authentication","secret":"sample-token","webhook_url":"https://example.com/resource","inbox_identifier":"sample inbox identifier","additional_attributes":{},"provider":"default","bot_name":"sample bot name","message_templates":true,"provider_config":"sample provider config","business_management_token_configured":true,"hybrid_pair":{"paired":true,"id":4,"role":"cloud","sibling_inbox_id":18,"canonical_phone":"+5521900000000","primary":"cloud","inbound_authority":"cloud","unified_inbox":true,"unified_state":{"state":"complete","scanned":42,"frozen":40,"reconciled_count":2,"completed_at":"2026-10-03T12:00:00.000Z","blocked_conversations":[]},"routing":{"outbound_default":"cloud","out_of_window":"web","fallback":true,"manual_override":true,"weighted":{"mode":"weighted","web_percent":30,"version":2}},"web_channel_id":12,"web_inbox_id":18,"calling_provider":"whatsapp_web","web_voice_enabled":true,"web_inbound_calls_enabled":true,"web_call_config_sync":{"state":"pending","checked_at":"2026-10-03T12:00:00.000Z"},"web_video_calls_enabled":false,"web_group_calls_enabled":false,"web_reauthorization_required":false,"web_session_state":{"state":"connected","fresh":true,"observed_at":"2026-10-03T12:00:00.000Z","disconnected_since":null},"web_allow_message_deletion":true},"whatsapp_web_session_state":{"state":"connected","fresh":true,"observed_at":"2026-01-15T10:30:00.000Z","disconnected_since":null},"hybrid_hidden":"sample hybrid hidden","logical_inbox_id":1,"whatsapp_pending_phone":{"awaiting_pair":true,"phone":"+5511999998888","reason":"same_account_same_provider","sibling_inbox_id":1,"source":"pair_success","at":"2026-01-15T10:30:00.000Z"},"whatsapp_sibling_notice":"sample whatsapp sibling notice","whatsapp_web_contact_request":"supported","voice_enabled":true,"inbound_calls_enabled":true,"voice_configured":true,"voice_call_webhook_url":"https://example.com/resource","voice_status_webhook_url":"https://example.com/resource"}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"assignment_policy_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."}]},"post":{"tags":["Assignment Policies"],"operationId":"auto_post_api_v1_accounts_account_id_assignment_policies_assignment_policy_id_inboxes","summary":"Link an inbox to an assignment policy","description":"Intended to attach an inbox to the assignment policy and return the join record. NOTE: the create action is not implemented in the controller (only #index exists), so this route currently does not function; the schema reflects the intended InboxAssignmentPolicy contract from the view.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The inbox\u003c-\u003epolicy join record (intended).","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer","example":15},"inbox_id":{"type":"integer","example":3},"assignment_policy_id":{"type":"integer","example":2},"created_at":{"type":"integer","description":"epoch seconds","example":1737023400},"updated_at":{"type":"integer","description":"epoch seconds","example":1737023400}}},"example":{"id":15,"inbox_id":3,"assignment_policy_id":2,"created_at":1737023400,"updated_at":1737023400}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"assignment_policy_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["inbox_id"],"properties":{"inbox_id":{"type":"integer","description":"Inbox to attach to the policy.","example":3}}},"example":{"inbox_id":3}}}}}},"/api/v1/accounts/{account_id}/assignment_policies":{"get":{"tags":["Assignment Policies"],"operationId":"auto_get_api_v1_accounts_account_id_assignment_policies","summary":"List assignment policies","description":"Returns the list of assignment policies visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"assignment_order":{"type":"string","enum":["round_robin"]},"conversation_priority":{"type":"string","enum":["earliest_created","longest_waiting"]},"fair_distribution_limit":{"type":"string"},"fair_distribution_window":{"type":"string"},"exclude_older_than_hours":{"type":"string"},"enabled":{"type":"boolean"},"assigned_inbox_count":{"type":"integer"},"created_at":{"type":"integer"},"updated_at":{"type":"integer"}}}},"example":[{"id":1,"name":"Sample Name","description":"A short description.","assignment_order":"round_robin","conversation_priority":"earliest_created","fair_distribution_limit":"sample fair distribution limit","fair_distribution_window":"sample fair distribution window","exclude_older_than_hours":"sample exclude older than hours","enabled":true,"assigned_inbox_count":5,"created_at":1,"updated_at":1}]}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."}]},"post":{"tags":["Assignment Policies"],"operationId":"auto_post_api_v1_accounts_account_id_assignment_policies","summary":"Create assignment policies","description":"Creates a new assignment policy from the request payload. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"assignment_order":{"type":"string","enum":["round_robin"]},"conversation_priority":{"type":"string","enum":["earliest_created","longest_waiting"]},"fair_distribution_limit":{"type":"string"},"fair_distribution_window":{"type":"string"},"exclude_older_than_hours":{"type":"string"},"enabled":{"type":"boolean"},"assigned_inbox_count":{"type":"integer"},"created_at":{"type":"integer"},"updated_at":{"type":"integer"}}},"example":{"id":1,"name":"Sample Name","description":"A short description.","assignment_order":"round_robin","conversation_priority":"earliest_created","fair_distribution_limit":"sample fair distribution limit","fair_distribution_window":"sample fair distribution window","exclude_older_than_hours":"sample exclude older than hours","enabled":true,"assigned_inbox_count":5,"created_at":1,"updated_at":1}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"assignment_policy":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"assignment_order":{"type":"string","enum":["round_robin"]},"conversation_priority":{"type":"string","enum":["earliest_created","longest_waiting"]},"fair_distribution_limit":{"type":"string"},"fair_distribution_window":{"type":"string"},"enabled":{"type":"boolean"},"exclude_older_than_hours":{"type":"string"}},"required":["name"]}},"required":["assignment_policy"]},"example":{"assignment_policy":{"name":"Sample Name","description":"A short description.","assignment_order":"round_robin","conversation_priority":"earliest_created","fair_distribution_limit":"sample fair distribution limit","fair_distribution_window":"sample fair distribution window","enabled":true,"exclude_older_than_hours":"sample exclude older than hours"}}}}}}},"/api/v1/accounts/{account_id}/assignment_policies/{id}":{"get":{"tags":["Assignment Policies"],"operationId":"auto_get_api_v1_accounts_account_id_assignment_policies_id","summary":"Get assignment policies","description":"Returns the assignment policy identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"assignment_order":{"type":"string","enum":["round_robin"]},"conversation_priority":{"type":"string","enum":["earliest_created","longest_waiting"]},"fair_distribution_limit":{"type":"string"},"fair_distribution_window":{"type":"string"},"exclude_older_than_hours":{"type":"string"},"enabled":{"type":"boolean"},"assigned_inbox_count":{"type":"integer"},"created_at":{"type":"integer"},"updated_at":{"type":"integer"}}},"example":{"id":1,"name":"Sample Name","description":"A short description.","assignment_order":"round_robin","conversation_priority":"earliest_created","fair_distribution_limit":"sample fair distribution limit","fair_distribution_window":"sample fair distribution window","exclude_older_than_hours":"sample exclude older than hours","enabled":true,"assigned_inbox_count":5,"created_at":1,"updated_at":1}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]},"patch":{"tags":["Assignment Policies"],"operationId":"auto_patch_api_v1_accounts_account_id_assignment_policies_id","summary":"Update assignment policies","description":"Updates the assignment policy identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"assignment_order":{"type":"string","enum":["round_robin"]},"conversation_priority":{"type":"string","enum":["earliest_created","longest_waiting"]},"fair_distribution_limit":{"type":"string"},"fair_distribution_window":{"type":"string"},"exclude_older_than_hours":{"type":"string"},"enabled":{"type":"boolean"},"assigned_inbox_count":{"type":"integer"},"created_at":{"type":"integer"},"updated_at":{"type":"integer"}}},"example":{"id":1,"name":"Sample Name","description":"A short description.","assignment_order":"round_robin","conversation_priority":"earliest_created","fair_distribution_limit":"sample fair distribution limit","fair_distribution_window":"sample fair distribution window","exclude_older_than_hours":"sample exclude older than hours","enabled":true,"assigned_inbox_count":5,"created_at":1,"updated_at":1}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"assignment_policy":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"assignment_order":{"type":"string","enum":["round_robin"]},"conversation_priority":{"type":"string","enum":["earliest_created","longest_waiting"]},"fair_distribution_limit":{"type":"string"},"fair_distribution_window":{"type":"string"},"enabled":{"type":"boolean"},"exclude_older_than_hours":{"type":"string"}}}},"required":["assignment_policy"]},"example":{"assignment_policy":{"name":"Sample Name","description":"A short description.","assignment_order":"round_robin","conversation_priority":"earliest_created","fair_distribution_limit":"sample fair distribution limit","fair_distribution_window":"sample fair distribution window","enabled":true,"exclude_older_than_hours":"sample exclude older than hours"}}}}}},"put":{"tags":["Assignment Policies"],"operationId":"auto_put_api_v1_accounts_account_id_assignment_policies_id","summary":"Update assignment policies","description":"Updates the assignment policy identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"assignment_order":{"type":"string","enum":["round_robin"]},"conversation_priority":{"type":"string","enum":["earliest_created","longest_waiting"]},"fair_distribution_limit":{"type":"string"},"fair_distribution_window":{"type":"string"},"exclude_older_than_hours":{"type":"string"},"enabled":{"type":"boolean"},"assigned_inbox_count":{"type":"integer"},"created_at":{"type":"integer"},"updated_at":{"type":"integer"}}},"example":{"id":1,"name":"Sample Name","description":"A short description.","assignment_order":"round_robin","conversation_priority":"earliest_created","fair_distribution_limit":"sample fair distribution limit","fair_distribution_window":"sample fair distribution window","exclude_older_than_hours":"sample exclude older than hours","enabled":true,"assigned_inbox_count":5,"created_at":1,"updated_at":1}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"assignment_policy":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"assignment_order":{"type":"string","enum":["round_robin"]},"conversation_priority":{"type":"string","enum":["earliest_created","longest_waiting"]},"fair_distribution_limit":{"type":"string"},"fair_distribution_window":{"type":"string"},"enabled":{"type":"boolean"},"exclude_older_than_hours":{"type":"string"}}}},"required":["assignment_policy"]},"example":{"assignment_policy":{"name":"Sample Name","description":"A short description.","assignment_order":"round_robin","conversation_priority":"earliest_created","fair_distribution_limit":"sample fair distribution limit","fair_distribution_window":"sample fair distribution window","enabled":true,"exclude_older_than_hours":"sample exclude older than hours"}}}}}},"delete":{"tags":["Assignment Policies"],"operationId":"auto_delete_api_v1_accounts_account_id_assignment_policies_id","summary":"Delete assignment policies","description":"Deletes the assignment policy identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Success (no content)"},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/inboxes/{inbox_id}/assignment_policy":{"get":{"tags":["Inboxes"],"operationId":"auto_get_api_v1_accounts_account_id_inboxes_inbox_id_assignment_policy","summary":"Get assignment policies","description":"Returns the assignment policy identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"assignment_order":{"type":"string","enum":["round_robin"]},"conversation_priority":{"type":"string","enum":["earliest_created","longest_waiting"]},"fair_distribution_limit":{"type":"string"},"fair_distribution_window":{"type":"string"},"exclude_older_than_hours":{"type":"string"},"enabled":{"type":"boolean"},"assigned_inbox_count":{"type":"integer"},"created_at":{"type":"integer"},"updated_at":{"type":"integer"}}},"example":{"id":1,"name":"Sample Name","description":"A short description.","assignment_order":"round_robin","conversation_priority":"earliest_created","fair_distribution_limit":"sample fair distribution limit","fair_distribution_window":"sample fair distribution window","exclude_older_than_hours":"sample exclude older than hours","enabled":true,"assigned_inbox_count":5,"created_at":1,"updated_at":1}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"inbox_id","in":"path","required":true,"schema":{"type":"string"}}]},"delete":{"tags":["Inboxes"],"operationId":"auto_delete_api_v1_accounts_account_id_inboxes_inbox_id_assignment_policy","summary":"Delete assignment policies","description":"Deletes the assignment policy identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Success (no content)"},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"inbox_id","in":"path","required":true,"schema":{"type":"string"}}]},"post":{"tags":["Inboxes"],"operationId":"auto_post_api_v1_accounts_account_id_inboxes_inbox_id_assignment_policy","summary":"Create assignment policies","description":"Creates a new assignment policy from the request payload. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"assignment_order":{"type":"string","enum":["round_robin"]},"conversation_priority":{"type":"string","enum":["earliest_created","longest_waiting"]},"fair_distribution_limit":{"type":"string"},"fair_distribution_window":{"type":"string"},"exclude_older_than_hours":{"type":"string"},"enabled":{"type":"boolean"},"assigned_inbox_count":{"type":"integer"},"created_at":{"type":"integer"},"updated_at":{"type":"integer"}}},"example":{"id":1,"name":"Sample Name","description":"A short description.","assignment_order":"round_robin","conversation_priority":"earliest_created","fair_distribution_limit":"sample fair distribution limit","fair_distribution_window":"sample fair distribution window","exclude_older_than_hours":"sample exclude older than hours","enabled":true,"assigned_inbox_count":5,"created_at":1,"updated_at":1}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"inbox_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/inboxes/{inbox_id}/routing_policy":{"get":{"tags":["Inboxes"],"operationId":"auto_get_api_v1_accounts_account_id_inboxes_inbox_id_routing_policy","summary":"Get routing policies","description":"Returns the routing policy identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"strategy":{"type":"string","enum":["round_robin","balanced","skill"]},"conversation_priority":{"type":"string","enum":["earliest","longest_waiting"]},"fair_distribution_limit":{"type":"string"},"fair_distribution_window":{"type":"string"},"reassign_on_unassign":{"type":"string"},"enabled":{"type":"boolean"},"assigned_inbox_count":{"type":"integer"},"created_at":{"type":"integer"},"updated_at":{"type":"integer"},"null":{"type":"string"}}},"example":{"id":1,"name":"Sample Name","description":"A short description.","strategy":"round_robin","conversation_priority":"earliest","fair_distribution_limit":"sample fair distribution limit","fair_distribution_window":"sample fair distribution window","reassign_on_unassign":"sample reassign on unassign","enabled":true,"assigned_inbox_count":5,"created_at":1,"updated_at":1,"null":"sample null"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"inbox_id","in":"path","required":true,"schema":{"type":"string"}}]},"delete":{"tags":["Inboxes"],"operationId":"auto_delete_api_v1_accounts_account_id_inboxes_inbox_id_routing_policy","summary":"Delete routing policies","description":"Deletes the routing policy identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Success (no content)"},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"inbox_id","in":"path","required":true,"schema":{"type":"string"}}]},"post":{"tags":["Inboxes"],"operationId":"auto_post_api_v1_accounts_account_id_inboxes_inbox_id_routing_policy","summary":"Create routing policies","description":"Creates a new routing policy from the request payload. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"strategy":{"type":"string","enum":["round_robin","balanced","skill"]},"conversation_priority":{"type":"string","enum":["earliest","longest_waiting"]},"fair_distribution_limit":{"type":"string"},"fair_distribution_window":{"type":"string"},"reassign_on_unassign":{"type":"string"},"enabled":{"type":"boolean"},"assigned_inbox_count":{"type":"integer"},"created_at":{"type":"integer"},"updated_at":{"type":"integer"}}},"example":{"id":1,"name":"Sample Name","description":"A short description.","strategy":"round_robin","conversation_priority":"earliest","fair_distribution_limit":"sample fair distribution limit","fair_distribution_window":"sample fair distribution window","reassign_on_unassign":"sample reassign on unassign","enabled":true,"assigned_inbox_count":5,"created_at":1,"updated_at":1}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"inbox_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/routing_policies/templates":{"get":{"tags":["Routing Policies"],"operationId":"auto_get_api_v1_accounts_account_id_routing_policies_templates","summary":"Templates routing policies","description":"Performs the templates operation on the targeted routing policy resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"routing":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"}}}},"capacity":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"}}}}}},"example":{"routing":[{"key":"sample key","name":"Sample Name","description":"A short description."}],"capacity":[{"key":"sample key","name":"Sample Name","description":"A short description."}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/routing_policies/apply_template":{"post":{"tags":["Routing Policies"],"operationId":"auto_post_api_v1_accounts_account_id_routing_policies_apply_template","summary":"Apply template routing policies","description":"Performs the apply template operation on the targeted routing policy resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The materialized policy (idempotent by name — an admin edit is never clobbered).","content":{"application/json":{"schema":{"type":"object","properties":{"kind":{"type":"string","enum":["routing","capacity"],"description":"Which policy family the archetype materialized into.","example":"routing"},"policy":{"type":"object","additionalProperties":true,"description":"The RoutingPolicy shape for kind=routing, or the RoutingCapacityPolicy shape for kind=capacity (see their CRUD endpoints for the full field list).","properties":{"id":{"type":"integer","example":12},"name":{"type":"string","example":"Round-robin"},"description":{"type":"string","example":"Distributes conversations in an equal round-robin among available agents."},"enabled":{"type":"boolean","example":true}}}}},"example":{"kind":"routing","policy":{"id":12,"name":"Round-robin","description":"Distributes conversations in an equal round-robin among available agents.","enabled":true}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"key":{"type":"string"}}},"example":{"key":"sample key"}}}}}},"/api/v1/accounts/{account_id}/routing_policies/seed_defaults":{"post":{"tags":["Routing Policies"],"operationId":"auto_post_api_v1_accounts_account_id_routing_policies_seed_defaults","summary":"Seed defaults routing policies","description":"Performs the seed defaults operation on the targeted routing policy resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"created":{"type":"string"}}},"example":{"created":"sample created"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/routing_policies/{routing_policy_id}/inboxes":{"get":{"tags":["Routing Policies"],"operationId":"auto_get_api_v1_accounts_account_id_routing_policies_routing_policy_id_inboxes","summary":"List inboxes","description":"Returns the list of inboxes visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"inboxes":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"avatar_url":{"type":"string"},"channel_id":{"type":"integer"},"name":{"type":"string"},"channel_type":{"type":"string","enum":["Channel::Api","Channel::Email","Channel::FacebookPage","Channel::Instagram","Channel::Line","Channel::Sms","Channel::Telegram","Channel::Tiktok","Channel::TwilioSms","Channel::TwitterProfile","Channel::WebWidget","Channel::Whatsapp"],"description":"The inbox channel class — identifies which messaging channel backs the inbox."},"greeting_enabled":{"type":"boolean"},"greeting_message":{"type":"string"},"working_hours_enabled":{"type":"boolean"},"enable_email_collect":{"type":"string"},"csat_survey_enabled":{"type":"boolean"},"csat_config":{"type":"string"},"enable_auto_assignment":{"type":"string"},"auto_assignment_config":{"type":"string"},"out_of_office_message":{"type":"string"},"working_hours":{"type":"string"},"timezone":{"type":"string","description":"IANA timezone identifier (e.g. \"America/Sao_Paulo\", \"UTC\"). Rails timezone names are also accepted on input; an unrecognized value is ignored in favor of the next fallback.","example":"America/Sao_Paulo"},"callback_webhook_url":{"type":"string"},"allow_messages_after_resolved":{"type":"string"},"lock_to_single_conversation":{"type":"string"},"audio_transcription_enabled":{"type":"boolean"},"preserve_deleted_messages":{"type":"string"},"allow_message_deletion":{"type":"string"},"capture_view_once":{"type":"string"},"sender_name_type":{"type":"string","enum":["friendly","professional"]},"auto_resolve_config":{"type":"object","additionalProperties":true,"oneOf":[{"type":"object","maxProperties":0,"additionalProperties":true,"description":"Empty means inherit the account rule."},{"type":"object","additionalProperties":false,"required":["mode"],"properties":{"mode":{"type":"string","enum":["disabled"],"description":"Disable automatic resolution for this inbox."}},"description":"The disabled rule contains only its mode."},{"type":"object","additionalProperties":false,"required":["mode","after","message","label","allow_waiting"],"properties":{"mode":{"type":"string","enum":["custom"],"description":"Use this complete inbox rule."},"after":{"type":"integer","minimum":10,"maximum":1439856,"description":"Inactivity in minutes; required for custom mode."},"message":{"type":["string","null"],"maxLength":10000,"description":"Optional message; blank normalizes to null."},"label":{"type":["string","null"],"description":"An existing account label title, or null."},"allow_waiting":{"type":"boolean","description":"Whether waiting conversations are included."}},"description":"Complete normalized custom rule."}],"description":"Normalized JSON rule from valid model writes: empty, disabled, or complete custom configuration.","example":{"mode":"custom","after":60,"message":null,"label":null,"allow_waiting":false}},"outbound_agent_name_header_policy":{"type":"string"},"agent_bot_working_hours_mode":{"type":"string","enum":["always","inside_business_hours","outside_business_hours"]},"business_name":{"type":"string"},"responder_policy":{"type":"string"},"help_center":{"type":"object","properties":{"name":{"type":"string"},"slug":{"type":"string"}}},"tweets_enabled":{"type":"boolean"},"allowed_domains":{"type":"string"},"widget_color":{"type":"string"},"website_url":{"type":"string"},"hmac_mandatory":{"type":"string"},"welcome_title":{"type":"string"},"welcome_tagline":{"type":"string"},"web_widget_script":{"type":"string"},"website_token":{"type":"string"},"selected_feature_flags":{"type":"string"},"reply_time":{"type":"string","format":"date-time"},"hmac_token":{"type":"string"},"pre_chat_form_enabled":{"type":"boolean"},"pre_chat_form_options":{"type":"string"},"continuity_via_email":{"type":"string","format":"email"},"page_id":{"type":"integer"},"reauthorization_required":{"type":"string"},"instagram_id":{"type":"integer"},"messaging_service_sid":{"type":"string"},"phone_number":{"type":"string"},"medium":{"type":"string"},"bandwidth_callback_state":{"type":"string","enum":["active","reconnect_required","reconciling","reconciliation_required","encryption_required"]},"bandwidth_api_migration_state":{"type":"string","enum":["oauth2_configured","oauth2_required","configuration_required"]},"bandwidth_legacy_basic_deprecated":{"type":"boolean"},"content_templates":{"type":"string"},"auth_token":{"type":"string"},"account_sid":{"type":"string"},"api_key_sid":{"type":"string"},"twilio_credential_state":{"type":"string","enum":["ready","pending","failed","dead_letter","account_auth_token_required","reconciliation_required"],"description":"Durable Twilio credential lifecycle derived from Channel::TwilioSms. A reconciliation-required state is fail-closed until the provider outcome has been verified."},"api_key_configured":{"type":"boolean"},"email":{"type":"string","format":"email"},"auth_method":{"type":"string"},"forwarding_enabled":{"type":"boolean"},"forward_to_email":{"type":"string","format":"email"},"branded_email_layout":{"type":"string"},"imap_login":{"type":"string"},"imap_password":{"type":"string"},"imap_address":{"type":"string"},"imap_port":{"type":"string"},"imap_enabled":{"type":"boolean"},"imap_enable_ssl":{"type":"string"},"imap_authentication":{"type":"string"},"smtp_login":{"type":"string"},"smtp_password":{"type":"string"},"smtp_address":{"type":"string"},"smtp_port":{"type":"string"},"smtp_enabled":{"type":"boolean"},"smtp_domain":{"type":"string"},"smtp_enable_ssl_tls":{"type":"string"},"smtp_enable_starttls_auto":{"type":"string"},"smtp_openssl_verify_mode":{"type":"string","enum":["none","peer","client_once","fail_if_no_peer_cert"],"description":"OpenSSL peer-certificate verification mode for the email channel's SMTP connection."},"smtp_authentication":{"type":"string"},"secret":{"type":"string"},"webhook_url":{"type":"string"},"inbox_identifier":{"type":"string"},"additional_attributes":{"type":"object","additionalProperties":true,"description":"Channel- and source-specific metadata for this record (e.g. browser info, referer, social profile identifiers). The key set depends on the originating channel."},"provider":{"type":"string","enum":["default","whatsapp_cloud","whatsapp_web","google","microsoft"],"description":"Messaging provider backing the inbox channel (whatsapp_web is the WazMeow gateway; email uses google/microsoft; default otherwise)."},"bot_name":{"type":"string"},"message_templates":{"type":"boolean"},"provider_config":{"type":"string"},"business_management_token_configured":{"type":"boolean"},"hybrid_pair":{"$ref":"#/components/schemas/inbox/properties/hybrid_pair"},"whatsapp_web_session_state":{"$ref":"#/components/schemas/inbox/properties/whatsapp_web_session_state"},"hybrid_hidden":{"type":"string"},"logical_inbox_id":{"type":"integer"},"whatsapp_pending_phone":{"type":"object","nullable":true,"description":"Spec 052 — set only when a WhatsApp phone-number rewrite was REFUSED because a non-sibling channel already holds the number, leaving the inbox on its `pending:` placeholder and inert. `null` in every normal case (including a routine, not-yet-scanned pairing).","additionalProperties":false,"properties":{"awaiting_pair":{"type":"boolean","description":"True while the inbox is still on its `pending:\u003cuuid\u003e` placeholder number."},"phone":{"type":"string","description":"The E.164 number the rewrite tried to claim."},"reason":{"type":"string","enum":["same_account_same_provider","other_account"],"description":"Why the rewrite was refused. `other_account` never carries any identifying detail about the other account."},"sibling_inbox_id":{"type":"integer","nullable":true,"description":"Colliding inbox in the SAME account; absent when the collision is cross-account."},"source":{"type":"string","enum":["pair_success","qr_pump"],"description":"Which path attempted the rewrite."},"at":{"type":"string","format":"date-time","description":"When the refusal was recorded."}}},"whatsapp_sibling_notice":{"type":"string"},"whatsapp_web_contact_request":{"type":"string","enum":["supported","unsupported","unknown"],"description":"WhatsApp Web inboxes only — whether this inbox's WazMeow gateway serves the request that asks a customer to share their phone number. `supported` and `unsupported` come from a no-effect probe of the gateway route, refreshed at most hourly and immediately when a real send finds the route missing; `unknown` means not probed yet or the gateway could not be reached. Only `supported` turns the feature on; with `unknown` the request is refused before any gateway call while the probe runs."},"voice_enabled":{"type":"boolean"},"inbound_calls_enabled":{"type":"boolean"},"voice_configured":{"type":"boolean"},"voice_call_webhook_url":{"type":"string"},"voice_status_webhook_url":{"type":"string"}}}}}},"example":{"inboxes":[{"id":1,"avatar_url":"https://example.com/resource","channel_id":1,"name":"Sample Name","channel_type":"Channel::Api","greeting_enabled":true,"greeting_message":"sample greeting message","working_hours_enabled":true,"enable_email_collect":"agent@example.com","csat_survey_enabled":true,"csat_config":"sample csat config","enable_auto_assignment":"sample enable auto assignment","auto_assignment_config":"sample auto assignment config","out_of_office_message":"sample out of office message","working_hours":"sample working hours","timezone":"America/Sao_Paulo","callback_webhook_url":"https://example.com/resource","allow_messages_after_resolved":"sample allow messages after resolved","lock_to_single_conversation":"sample lock to single conversation","audio_transcription_enabled":true,"preserve_deleted_messages":"sample preserve deleted messages","allow_message_deletion":"sample allow message deletion","capture_view_once":"sample capture view once","sender_name_type":"friendly","auto_resolve_config":{"mode":"custom","after":60,"message":null,"label":null,"allow_waiting":false},"outbound_agent_name_header_policy":"sample outbound agent name header policy","agent_bot_working_hours_mode":"always","business_name":"sample business name","responder_policy":"sample responder policy","help_center":{"name":"Sample Name","slug":"sample-slug"},"tweets_enabled":true,"allowed_domains":"sample allowed domains","widget_color":"#1F93FF","website_url":"https://example.com/resource","hmac_mandatory":"sample hmac mandatory","welcome_title":"sample welcome title","welcome_tagline":"sample welcome tagline","web_widget_script":"sample web widget script","website_token":"sample-token","selected_feature_flags":"sample selected feature flags","reply_time":"2026-01-15T10:30:00.000Z","hmac_token":"sample-token","pre_chat_form_enabled":true,"pre_chat_form_options":"sample pre chat form options","continuity_via_email":"agent@example.com","page_id":1,"reauthorization_required":"sample reauthorization required","instagram_id":1,"messaging_service_sid":"sample messaging service sid","phone_number":"+5511999998888","medium":"sample medium","bandwidth_callback_state":"active","bandwidth_api_migration_state":"oauth2_configured","bandwidth_legacy_basic_deprecated":true,"content_templates":"sample content templates","auth_token":"sample-token","account_sid":"sample account sid","api_key_sid":"sample api key sid","twilio_credential_state":"ready","api_key_configured":true,"email":"agent@example.com","auth_method":"sample auth method","forwarding_enabled":true,"forward_to_email":"agent@example.com","branded_email_layout":"agent@example.com","imap_login":"sample imap login","imap_password":"sample imap password","imap_address":"sample imap address","imap_port":"sample imap port","imap_enabled":true,"imap_enable_ssl":"sample imap enable ssl","imap_authentication":"sample imap authentication","smtp_login":"sample smtp login","smtp_password":"sample smtp password","smtp_address":"sample smtp address","smtp_port":"sample smtp port","smtp_enabled":true,"smtp_domain":"sample smtp domain","smtp_enable_ssl_tls":"sample smtp enable ssl tls","smtp_enable_starttls_auto":"sample smtp enable starttls auto","smtp_openssl_verify_mode":"none","smtp_authentication":"sample smtp authentication","secret":"sample-token","webhook_url":"https://example.com/resource","inbox_identifier":"sample inbox identifier","additional_attributes":{},"provider":"default","bot_name":"sample bot name","message_templates":true,"provider_config":"sample provider config","business_management_token_configured":true,"hybrid_pair":{"paired":true,"id":4,"role":"cloud","sibling_inbox_id":18,"canonical_phone":"+5521900000000","primary":"cloud","inbound_authority":"cloud","unified_inbox":true,"unified_state":{"state":"complete","scanned":42,"frozen":40,"reconciled_count":2,"completed_at":"2026-10-03T12:00:00.000Z","blocked_conversations":[]},"routing":{"outbound_default":"cloud","out_of_window":"web","fallback":true,"manual_override":true,"weighted":{"mode":"weighted","web_percent":30,"version":2}},"web_channel_id":12,"web_inbox_id":18,"calling_provider":"whatsapp_web","web_voice_enabled":true,"web_inbound_calls_enabled":true,"web_call_config_sync":{"state":"pending","checked_at":"2026-10-03T12:00:00.000Z"},"web_video_calls_enabled":false,"web_group_calls_enabled":false,"web_reauthorization_required":false,"web_session_state":{"state":"connected","fresh":true,"observed_at":"2026-10-03T12:00:00.000Z","disconnected_since":null},"web_allow_message_deletion":true},"whatsapp_web_session_state":{"state":"connected","fresh":true,"observed_at":"2026-01-15T10:30:00.000Z","disconnected_since":null},"hybrid_hidden":"sample hybrid hidden","logical_inbox_id":1,"whatsapp_pending_phone":{"awaiting_pair":true,"phone":"+5511999998888","reason":"same_account_same_provider","sibling_inbox_id":1,"source":"pair_success","at":"2026-01-15T10:30:00.000Z"},"whatsapp_sibling_notice":"sample whatsapp sibling notice","whatsapp_web_contact_request":"supported","voice_enabled":true,"inbound_calls_enabled":true,"voice_configured":true,"voice_call_webhook_url":"https://example.com/resource","voice_status_webhook_url":"https://example.com/resource"}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"routing_policy_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."}]}},"/api/v1/accounts/{account_id}/routing_policies":{"get":{"tags":["Routing Policies"],"operationId":"auto_get_api_v1_accounts_account_id_routing_policies","summary":"List routing policies","description":"Returns the list of routing policies visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"strategy":{"type":"string","enum":["round_robin","balanced","skill"]},"conversation_priority":{"type":"string","enum":["earliest","longest_waiting"]},"fair_distribution_limit":{"type":"string"},"fair_distribution_window":{"type":"string"},"reassign_on_unassign":{"type":"string"},"enabled":{"type":"boolean"},"assigned_inbox_count":{"type":"integer"},"created_at":{"type":"integer"},"updated_at":{"type":"integer"}}}},"example":[{"id":1,"name":"Sample Name","description":"A short description.","strategy":"round_robin","conversation_priority":"earliest","fair_distribution_limit":"sample fair distribution limit","fair_distribution_window":"sample fair distribution window","reassign_on_unassign":"sample reassign on unassign","enabled":true,"assigned_inbox_count":5,"created_at":1,"updated_at":1}]}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."}]},"post":{"tags":["Routing Policies"],"operationId":"auto_post_api_v1_accounts_account_id_routing_policies","summary":"Create routing policies","description":"Creates a new routing policy from the request payload. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"strategy":{"type":"string","enum":["round_robin","balanced","skill"]},"conversation_priority":{"type":"string","enum":["earliest","longest_waiting"]},"fair_distribution_limit":{"type":"string"},"fair_distribution_window":{"type":"string"},"reassign_on_unassign":{"type":"string"},"enabled":{"type":"boolean"},"assigned_inbox_count":{"type":"integer"},"created_at":{"type":"integer"},"updated_at":{"type":"integer"}}},"example":{"id":1,"name":"Sample Name","description":"A short description.","strategy":"round_robin","conversation_priority":"earliest","fair_distribution_limit":"sample fair distribution limit","fair_distribution_window":"sample fair distribution window","reassign_on_unassign":"sample reassign on unassign","enabled":true,"assigned_inbox_count":5,"created_at":1,"updated_at":1}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"routing_policy":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"strategy":{"type":"string","enum":["round_robin","balanced","skill"]},"conversation_priority":{"type":"string","enum":["earliest","longest_waiting"]},"fair_distribution_limit":{"type":"string"},"fair_distribution_window":{"type":"string"},"reassign_on_unassign":{"type":"string"},"enabled":{"type":"boolean"}},"required":["name"]}},"required":["routing_policy"]},"example":{"routing_policy":{"name":"Sample Name","description":"A short description.","strategy":"round_robin","conversation_priority":"earliest","fair_distribution_limit":"sample fair distribution limit","fair_distribution_window":"sample fair distribution window","reassign_on_unassign":"sample reassign on unassign","enabled":true}}}}}}},"/api/v1/accounts/{account_id}/routing_policies/{id}":{"get":{"tags":["Routing Policies"],"operationId":"auto_get_api_v1_accounts_account_id_routing_policies_id","summary":"Get routing policies","description":"Returns the routing policy identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"strategy":{"type":"string","enum":["round_robin","balanced","skill"]},"conversation_priority":{"type":"string","enum":["earliest","longest_waiting"]},"fair_distribution_limit":{"type":"string"},"fair_distribution_window":{"type":"string"},"reassign_on_unassign":{"type":"string"},"enabled":{"type":"boolean"},"assigned_inbox_count":{"type":"integer"},"created_at":{"type":"integer"},"updated_at":{"type":"integer"}}},"example":{"id":1,"name":"Sample Name","description":"A short description.","strategy":"round_robin","conversation_priority":"earliest","fair_distribution_limit":"sample fair distribution limit","fair_distribution_window":"sample fair distribution window","reassign_on_unassign":"sample reassign on unassign","enabled":true,"assigned_inbox_count":5,"created_at":1,"updated_at":1}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]},"patch":{"tags":["Routing Policies"],"operationId":"auto_patch_api_v1_accounts_account_id_routing_policies_id","summary":"Update routing policies","description":"Updates the routing policy identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"strategy":{"type":"string","enum":["round_robin","balanced","skill"]},"conversation_priority":{"type":"string","enum":["earliest","longest_waiting"]},"fair_distribution_limit":{"type":"string"},"fair_distribution_window":{"type":"string"},"reassign_on_unassign":{"type":"string"},"enabled":{"type":"boolean"},"assigned_inbox_count":{"type":"integer"},"created_at":{"type":"integer"},"updated_at":{"type":"integer"}}},"example":{"id":1,"name":"Sample Name","description":"A short description.","strategy":"round_robin","conversation_priority":"earliest","fair_distribution_limit":"sample fair distribution limit","fair_distribution_window":"sample fair distribution window","reassign_on_unassign":"sample reassign on unassign","enabled":true,"assigned_inbox_count":5,"created_at":1,"updated_at":1}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"routing_policy":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"strategy":{"type":"string","enum":["round_robin","balanced","skill"]},"conversation_priority":{"type":"string","enum":["earliest","longest_waiting"]},"fair_distribution_limit":{"type":"string"},"fair_distribution_window":{"type":"string"},"reassign_on_unassign":{"type":"string"},"enabled":{"type":"boolean"}}}},"required":["routing_policy"]},"example":{"routing_policy":{"name":"Sample Name","description":"A short description.","strategy":"round_robin","conversation_priority":"earliest","fair_distribution_limit":"sample fair distribution limit","fair_distribution_window":"sample fair distribution window","reassign_on_unassign":"sample reassign on unassign","enabled":true}}}}}},"put":{"tags":["Routing Policies"],"operationId":"auto_put_api_v1_accounts_account_id_routing_policies_id","summary":"Update routing policies","description":"Updates the routing policy identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"strategy":{"type":"string","enum":["round_robin","balanced","skill"]},"conversation_priority":{"type":"string","enum":["earliest","longest_waiting"]},"fair_distribution_limit":{"type":"string"},"fair_distribution_window":{"type":"string"},"reassign_on_unassign":{"type":"string"},"enabled":{"type":"boolean"},"assigned_inbox_count":{"type":"integer"},"created_at":{"type":"integer"},"updated_at":{"type":"integer"}}},"example":{"id":1,"name":"Sample Name","description":"A short description.","strategy":"round_robin","conversation_priority":"earliest","fair_distribution_limit":"sample fair distribution limit","fair_distribution_window":"sample fair distribution window","reassign_on_unassign":"sample reassign on unassign","enabled":true,"assigned_inbox_count":5,"created_at":1,"updated_at":1}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"routing_policy":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"strategy":{"type":"string","enum":["round_robin","balanced","skill"]},"conversation_priority":{"type":"string","enum":["earliest","longest_waiting"]},"fair_distribution_limit":{"type":"string"},"fair_distribution_window":{"type":"string"},"reassign_on_unassign":{"type":"string"},"enabled":{"type":"boolean"}}}},"required":["routing_policy"]},"example":{"routing_policy":{"name":"Sample Name","description":"A short description.","strategy":"round_robin","conversation_priority":"earliest","fair_distribution_limit":"sample fair distribution limit","fair_distribution_window":"sample fair distribution window","reassign_on_unassign":"sample reassign on unassign","enabled":true}}}}}},"delete":{"tags":["Routing Policies"],"operationId":"auto_delete_api_v1_accounts_account_id_routing_policies_id","summary":"Delete routing policies","description":"Deletes the routing policy identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Success (no content)"},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/routing_capacity_policies":{"get":{"tags":["Routing Policies"],"operationId":"auto_get_api_v1_accounts_account_id_routing_capacity_policies","summary":"List routing capacity policies","description":"Returns the list of routing capacity policies visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"enabled":{"type":"boolean"},"exclusion_rules":{"type":"string"},"inbox_limits":{"type":"array","items":{"type":"object","properties":{"inbox_id":{"type":"integer"},"conversation_limit":{"type":"string"}}}},"account_user_ids":{"type":"array","items":{"type":"integer"}},"created_at":{"type":"integer"},"updated_at":{"type":"integer"}}}},"example":[{"id":1,"name":"Sample Name","description":"A short description.","enabled":true,"exclusion_rules":"sample exclusion rules","inbox_limits":[{"inbox_id":1,"conversation_limit":"sample conversation limit"}],"account_user_ids":[1],"created_at":1,"updated_at":1}]}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."}]},"post":{"tags":["Routing Policies"],"operationId":"auto_post_api_v1_accounts_account_id_routing_capacity_policies","summary":"Create routing capacity policies","description":"Creates a new routing capacity policy from the request payload. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"enabled":{"type":"boolean"},"exclusion_rules":{"type":"string"},"inbox_limits":{"type":"array","items":{"type":"object","properties":{"inbox_id":{"type":"integer"},"conversation_limit":{"type":"string"}}}},"account_user_ids":{"type":"array","items":{"type":"integer"}},"created_at":{"type":"integer"},"updated_at":{"type":"integer"}}},"example":{"id":1,"name":"Sample Name","description":"A short description.","enabled":true,"exclusion_rules":"sample exclusion rules","inbox_limits":[{"inbox_id":1,"conversation_limit":"sample conversation limit"}],"account_user_ids":[1],"created_at":1,"updated_at":1}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"routing_capacity_policy":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"enabled":{"type":"boolean"},"account_user_ids":{"type":"array","items":{"type":"integer"}},"inbox_limits":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Free-form object."}},"exclusion_rules":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Free-form object."}}},"required":["name"]}},"required":["routing_capacity_policy"]},"example":{"routing_capacity_policy":{"name":"Sample Name","description":"A short description.","enabled":true,"account_user_ids":[1],"inbox_limits":[{}],"exclusion_rules":[{}]}}}}}}},"/api/v1/accounts/{account_id}/routing_capacity_policies/{id}":{"get":{"tags":["Routing Policies"],"operationId":"auto_get_api_v1_accounts_account_id_routing_capacity_policies_id","summary":"Get routing capacity policies","description":"Returns the routing capacity policy identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"enabled":{"type":"boolean"},"exclusion_rules":{"type":"string"},"inbox_limits":{"type":"array","items":{"type":"object","properties":{"inbox_id":{"type":"integer"},"conversation_limit":{"type":"string"}}}},"account_user_ids":{"type":"array","items":{"type":"integer"}},"created_at":{"type":"integer"},"updated_at":{"type":"integer"}}},"example":{"id":1,"name":"Sample Name","description":"A short description.","enabled":true,"exclusion_rules":"sample exclusion rules","inbox_limits":[{"inbox_id":1,"conversation_limit":"sample conversation limit"}],"account_user_ids":[1],"created_at":1,"updated_at":1}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]},"patch":{"tags":["Routing Policies"],"operationId":"auto_patch_api_v1_accounts_account_id_routing_capacity_policies_id","summary":"Update routing capacity policies","description":"Updates the routing capacity policy identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"enabled":{"type":"boolean"},"exclusion_rules":{"type":"string"},"inbox_limits":{"type":"array","items":{"type":"object","properties":{"inbox_id":{"type":"integer"},"conversation_limit":{"type":"string"}}}},"account_user_ids":{"type":"array","items":{"type":"integer"}},"created_at":{"type":"integer"},"updated_at":{"type":"integer"}}},"example":{"id":1,"name":"Sample Name","description":"A short description.","enabled":true,"exclusion_rules":"sample exclusion rules","inbox_limits":[{"inbox_id":1,"conversation_limit":"sample conversation limit"}],"account_user_ids":[1],"created_at":1,"updated_at":1}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"routing_capacity_policy":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"enabled":{"type":"boolean"},"account_user_ids":{"type":"array","items":{"type":"integer"}},"inbox_limits":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Free-form object."}},"exclusion_rules":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Free-form object."}}}}},"required":["routing_capacity_policy"]},"example":{"routing_capacity_policy":{"name":"Sample Name","description":"A short description.","enabled":true,"account_user_ids":[1],"inbox_limits":[{}],"exclusion_rules":[{}]}}}}}},"put":{"tags":["Routing Policies"],"operationId":"auto_put_api_v1_accounts_account_id_routing_capacity_policies_id","summary":"Update routing capacity policies","description":"Updates the routing capacity policy identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"enabled":{"type":"boolean"},"exclusion_rules":{"type":"string"},"inbox_limits":{"type":"array","items":{"type":"object","properties":{"inbox_id":{"type":"integer"},"conversation_limit":{"type":"string"}}}},"account_user_ids":{"type":"array","items":{"type":"integer"}},"created_at":{"type":"integer"},"updated_at":{"type":"integer"}}},"example":{"id":1,"name":"Sample Name","description":"A short description.","enabled":true,"exclusion_rules":"sample exclusion rules","inbox_limits":[{"inbox_id":1,"conversation_limit":"sample conversation limit"}],"account_user_ids":[1],"created_at":1,"updated_at":1}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"routing_capacity_policy":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"enabled":{"type":"boolean"},"account_user_ids":{"type":"array","items":{"type":"integer"}},"inbox_limits":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Free-form object."}},"exclusion_rules":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Free-form object."}}}}},"required":["routing_capacity_policy"]},"example":{"routing_capacity_policy":{"name":"Sample Name","description":"A short description.","enabled":true,"account_user_ids":[1],"inbox_limits":[{}],"exclusion_rules":[{}]}}}}}},"delete":{"tags":["Routing Policies"],"operationId":"auto_delete_api_v1_accounts_account_id_routing_capacity_policies_id","summary":"Delete routing capacity policies","description":"Deletes the routing capacity policy identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Success (no content)"},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/twitter/authorization":{"post":{"tags":["Twitter"],"operationId":"auto_post_api_v1_accounts_account_id_twitter_authorization","summary":"Create authorizations","description":"Creates a new authorization from the request payload. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"url":{"type":"string"}}},"example":{"success":true,"url":"https://example.com/resource"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/microsoft/authorization":{"post":{"tags":["Microsoft"],"operationId":"auto_post_api_v1_accounts_account_id_microsoft_authorization","summary":"Create authorizations","description":"Creates a new authorization from the request payload. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"url":{"type":"string"}}},"example":{"success":true,"url":"https://example.com/resource"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"return_to":{"type":"string"}}},"example":{"return_to":"sample return to"}}}}}},"/api/v1/accounts/{account_id}/google/authorization":{"post":{"tags":["Google"],"operationId":"auto_post_api_v1_accounts_account_id_google_authorization","summary":"Create authorizations","description":"Creates a new authorization from the request payload. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"url":{"type":"string"}}},"example":{"success":true,"url":"https://example.com/resource"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"return_to":{"type":"string"}}},"example":{"return_to":"sample return to"}}}}}},"/api/v1/accounts/{account_id}/instagram/authorization":{"post":{"tags":["Instagram"],"operationId":"auto_post_api_v1_accounts_account_id_instagram_authorization","summary":"Authorize or reauthorize an Instagram connection","description":"Requests an OAuth URL. When inbox_id is supplied, the signed state binds the callback to that Instagram inbox in the current account. The callback rejects another profile and never creates a replacement inbox. Requires administrator or integration_manage permission.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"url":{"type":"string"}}},"example":{"success":true,"url":"https://example.com/resource"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"inbox_id":{"type":"integer","description":"Existing Instagram inbox to reauthorize in the current account."},"return_to":{"type":"string","enum":["onboarding"]}}},"example":{"inbox_id":1,"return_to":"onboarding"}}}}}},"/api/v1/accounts/{account_id}/tiktok/authorization":{"post":{"tags":["TikTok"],"operationId":"auto_post_api_v1_accounts_account_id_tiktok_authorization","summary":"Create authorizations","description":"Creates a new authorization from the request payload. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"url":{"type":"string"}}},"example":{"success":true,"url":"https://example.com/resource"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"return_to":{"type":"string"}}},"example":{"return_to":"sample return to"}}}}}},"/api/v1/accounts/{account_id}/notion/authorization":{"post":{"tags":["Notion"],"operationId":"auto_post_api_v1_accounts_account_id_notion_authorization","summary":"Create authorizations","description":"Creates a new authorization from the request payload. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"url":{"type":"string"}}},"example":{"success":true,"url":"https://example.com/resource"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"return_to":{"type":"string"}}},"example":{"return_to":"sample return to"}}}}}},"/api/v1/accounts/{account_id}/whatsapp/authorization":{"post":{"tags":["WhatsApp"],"operationId":"auto_post_api_v1_accounts_account_id_whatsapp_authorization","summary":"Complete WhatsApp embedded signup or reauthorize an inbox","description":"UI-only exchange of a short-lived Meta OAuth code. Without inbox_id, creates an inbox and requires an administrator or an account-scoped native role with provisioning access. With inbox_id, reauthorizes an accessible existing inbox without requiring the creation flag. Creating an inbox requires whatsapp_embedded_signup_inbox_creation in every build. Reconfiguring a healthy embedded-signup channel on self-hosted installations requires whatsapp_reconfigure; channels requiring reauthorization may reconnect. A 202 response means credentials were saved but webhook configuration or phone registration remains pending; resume recovery for the returned inbox instead of repeating creation. Provider credentials are never included in the response.","security":[{"userApiKey":[]}],"responses":{"202":{"description":"Credentials were saved but webhook configuration or phone registration is incomplete; recover this inbox.","content":{"application/json":{"schema":{"type":"object","required":["success","state","stage","id","message"],"properties":{"success":{"type":"boolean","enum":[false]},"state":{"type":"string","enum":["configuration_pending"]},"stage":{"type":"string","enum":["webhook","phone_registration"]},"id":{"type":"integer","description":"Persisted inbox identifier to use for recovery."},"message":{"type":"string"}}},"example":{"success":false,"state":"configuration_pending","stage":"webhook","id":1,"message":"Sample message text."}}}},"401":{"description":"Account authorization or the embedded-signup creation feature is unavailable.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}},"example":{"error":"sample error"}}}},"404":{"description":"Account or resource not found"},"402":{"description":"The account inbox limit prevents creating another inbox.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}},"example":{"error":"Account limit exceeded. Upgrade to a higher plan"}}}},"422":{"description":"Missing signup parameters, provider exchange failure or reauthorization is not required.","content":{"application/json":{"schema":{"oneOf":[{"type":"object","required":["success","error"],"properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"}}},{"type":"object","required":["success","message"],"properties":{"success":{"type":"boolean","enum":[false]},"message":{"type":"string"}}}]},"example":{"success":false,"error":"sample error"}}}},"200":{"description":"WhatsApp Cloud embedded-signup / reauthorization result.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"id":{"type":"integer","example":7,"description":"Inbox id."},"name":{"type":"string","example":"WhatsApp Support"},"channel_type":{"type":"string","example":"whatsapp","enum":["whatsapp"],"description":"The inbox channel class — identifies which messaging channel backs the inbox."},"message":{"type":["string","null"],"example":"Reauthorization successful","description":"Present only on reauthorization (inbox_id supplied)."}}},"example":{"success":true,"id":7,"name":"WhatsApp Support","channel_type":"whatsapp","message":"Reauthorization successful"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["code","business_id","waba_id"],"properties":{"code":{"type":"string","example":"AQD...oauthCode","description":"Meta embedded-signup OAuth exchange code."},"business_id":{"type":"string","example":"100200300400500","description":"Meta Business (portfolio) id."},"waba_id":{"type":"string","example":"110220330440550","description":"WhatsApp Business Account id."},"phone_number_id":{"type":"string","example":"120330440550660","description":"Registered phone-number id (optional)."},"inbox_id":{"type":"integer","example":7,"description":"Present -\u003e reauthorize this existing inbox instead of creating a new one."}}},"example":{"code":"AQD...oauthCode","business_id":"100200300400500","waba_id":"110220330440550","phone_number_id":"120330440550660","inbox_id":7}}}}}},"/api/v1/accounts/{account_id}/whatsapp/hybrid_pairs/{id}/activate_unified":{"post":{"tags":["WhatsApp"],"operationId":"auto_post_api_v1_accounts_account_id_whatsapp_hybrid_pairs_id_activate_unified","summary":"Activate the single operational inbox for a WhatsApp hybrid pair","description":"Queues activation of the unified (single operational) inbox. The Web inbox is hidden from day-to-day lists only; no message, call or history row is moved or deleted.\nBefore freezing anything, activation reconciles the Maestro control state of each duplicate Web timeline onto its canonical Cloud conversation (stand-down, Robô override, autonomy override) and RE-READS it to confirm the write landed. Whatever genuinely could not be carried over blocks, and is reported per conversation in `unified_state.blocked_conversations` on the pair.\nSend `acknowledged_blockers` to proceed despite blockers the operator has already seen. It is a per-conversation acknowledgement, never a blanket override: a conversation that starts blocking AFTER that list was produced still blocks. The body is optional — omit it entirely for a normal activation.","security":[{"userApiKey":[]}],"responses":{"202":{"description":"The activation request was accepted. The returned pair still describes the queued operation; `unified_state` advances asynchronously, so clients must reload it rather than infer completion.","content":{"application/json":{"schema":{"type":"object","required":["id","account_id","canonical_phone_e164","cloud_channel_id","web_channel_id","cloud_inbox_id","web_inbox_id","primary","inbound_authority","routing","enabled","unified_inbox","unified_state","web_session_state"],"properties":{"id":{"type":"integer","description":"Pair id."},"account_id":{"type":"integer","description":"Account id."},"canonical_phone_e164":{"type":"string","description":"The shared phone number in E.164."},"cloud_channel_id":{"type":"integer","description":"Cloud API channel id."},"web_channel_id":{"type":"integer","description":"WhatsApp Web channel id."},"cloud_inbox_id":{"type":["integer","null"],"description":"Inbox of the Cloud API channel."},"web_inbox_id":{"type":["integer","null"],"description":"Inbox of the WhatsApp Web channel."},"primary":{"type":"string","enum":["cloud","web"],"description":"Primary transport (only `cloud` is supported)."},"inbound_authority":{"type":"string","enum":["cloud","web","both"],"description":"Transport whose inbound events are authoritative (only `cloud` is supported)."},"routing":{"type":"object","required":["outbound_default","out_of_window","fallback","manual_override","weighted"],"additionalProperties":true,"properties":{"outbound_default":{"type":"string","enum":["cloud","web"]},"out_of_window":{"type":"string","enum":["cloud","web"]},"fallback":{"type":"boolean"},"manual_override":{"type":"boolean"},"weighted":{"type":"object","additionalProperties":false,"required":["mode","web_percent","version"],"properties":{"mode":{"type":"string","enum":["legacy","weighted"]},"web_percent":{"type":"integer","minimum":0,"maximum":100},"version":{"type":"integer","minimum":1}}}}},"enabled":{"type":"boolean","description":"Whether the pair routes traffic."},"unified_inbox":{"type":"boolean","description":"Whether both transports are served through one logical inbox."},"unified_state":{"type":"object","additionalProperties":true,"description":"The asynchronous activation audit and current state."},"web_session_state":{"type":"object","additionalProperties":false,"required":["state","fresh","observed_at","disconnected_since"],"description":"Secret-free cached observation of the physical WhatsApp Web session. `unknown` covers absent, invalid, stale or temporarily unreadable state and is never a disconnected conclusion. Refresh this GET resource for a new observation.","properties":{"state":{"type":"string","enum":["connected","disconnected","unknown"]},"fresh":{"type":"boolean"},"observed_at":{"type":["string","null"],"format":"date-time"},"disconnected_since":{"type":["string","null"],"format":"date-time","description":"Null unless the current reader result is a fresh disconnected episode."}}}}},"example":{"id":4,"account_id":1,"canonical_phone_e164":"+5521900000000","cloud_channel_id":11,"web_channel_id":12,"cloud_inbox_id":17,"web_inbox_id":18,"primary":"cloud","inbound_authority":"cloud","routing":{"outbound_default":"cloud","out_of_window":"web","fallback":true,"manual_override":true,"weighted":{"mode":"weighted","web_percent":30,"version":2}},"enabled":true,"unified_inbox":false,"unified_state":{"state":"queued","request_id":"8b1d3f57-6e9a-4c2b-8d4f-0a1b2c3d4e5f","requested_at":"2026-10-03T12:00:00.000Z"},"web_session_state":{"state":"unknown","fresh":false,"observed_at":null,"disconnected_since":null}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"422":{"description":"The activation preflight rejected the pair before an asynchronous request was queued.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}},"example":{"error":"Resolve the conflicting configuration before activating the unified inbox."}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"hybrid_pair":{"type":"object","properties":{"acknowledged_blockers":{"type":"array","maxItems":200,"description":"Conversation `display_id`s the operator acknowledged on the blockers panel. Non-positive and non-numeric entries are discarded; the list is de-duplicated and truncated to 200. It is carried in the activation audit and deliberately does NOT take part in the request identity, so retrying never depends on resending it.","items":{"type":"integer","minimum":1,"example":1117}}},"example":{"acknowledged_blockers":[1117,1204]}}}},"example":{"hybrid_pair":{"acknowledged_blockers":[1117,1204]}}}}}}},"/api/v1/accounts/{account_id}/whatsapp/hybrid_pairs/{id}/deactivate_unified":{"post":{"tags":["WhatsApp"],"operationId":"auto_post_api_v1_accounts_account_id_whatsapp_hybrid_pairs_id_deactivate_unified","summary":"Deactivate the unified inbox of a WhatsApp hybrid pair","description":"Turns the logical unified inbox off (administrators only); the pair and its routing, including `routing.weighted`, stay as they are.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The pair, with its effective routing.","content":{"application/json":{"schema":{"type":"object","required":["id","account_id","canonical_phone_e164","cloud_channel_id","web_channel_id","cloud_inbox_id","web_inbox_id","primary","inbound_authority","routing","enabled","unified_inbox","unified_state","web_session_state"],"description":"A WhatsApp hybrid pair.","properties":{"id":{"type":"integer","description":"Pair id."},"account_id":{"type":"integer","description":"Account id."},"canonical_phone_e164":{"type":"string","description":"The shared phone number in E.164."},"cloud_channel_id":{"type":"integer","description":"Cloud API channel id."},"web_channel_id":{"type":"integer","description":"WhatsApp Web channel id."},"cloud_inbox_id":{"type":["integer","null"],"description":"Inbox of the Cloud API channel."},"web_inbox_id":{"type":["integer","null"],"description":"Inbox of the WhatsApp Web channel."},"primary":{"type":"string","enum":["cloud","web"],"description":"Primary transport (only `cloud` is supported)."},"inbound_authority":{"type":"string","enum":["cloud","web","both"],"description":"Transport whose inbound events are authoritative (only `cloud` is supported)."},"routing":{"type":"object","required":["outbound_default","out_of_window","fallback","manual_override","weighted"],"additionalProperties":true,"description":"Effective routing of the pair — the stored keys over the product defaults. Keys stored by older versions may appear beside the ones listed.","properties":{"outbound_default":{"type":"string","enum":["cloud","web"],"description":"Transport of a reply inside the Cloud API customer-service window."},"out_of_window":{"type":"string","enum":["cloud","web"],"description":"Transport of a reply outside the Cloud API customer-service window."},"fallback":{"type":"boolean","description":"Whether a definitive rejection may fall back to the sibling transport."},"manual_override":{"type":"boolean","description":"Whether an agent may pick the transport in the conversation."},"weighted":{"type":"object","additionalProperties":false,"required":["mode","web_percent","version"],"description":"Per-contact weighted distribution between the two transports. `legacy` keeps the default outbound rule; `weighted` sends `web_percent`% of the eligible support sends of each contact through WhatsApp Web and the rest through Cloud API. A new percentage bumps `version`, which restarts every contact's count.","properties":{"mode":{"type":"string","enum":["legacy","weighted"],"description":"Distribution mode."},"web_percent":{"type":"integer","minimum":0,"maximum":100,"description":"Share of eligible sends routed through WhatsApp Web, in percent."},"version":{"type":"integer","minimum":1,"description":"Policy version, the optimistic-lock token of the next change."}}}}},"enabled":{"type":"boolean","description":"Whether the pair routes traffic."},"unified_inbox":{"type":"boolean","description":"Whether both transports are served through one logical inbox."},"unified_state":{"type":"object","description":"Progress and audit data for the current or most recent logical-inbox activation.","properties":{"state":{"type":"string","enum":["queued","running","complete","failed","inactive"],"description":"Current activation state."},"request_id":{"type":"string","format":"uuid","description":"Stable idempotency id of the activation request."},"requested_at":{"type":"string","format":"date-time","description":"Time the request was queued."},"started_at":{"type":"string","format":"date-time","description":"Time the worker started the request."},"completed_at":{"type":"string","format":"date-time","description":"Time activation completed."},"failed_at":{"type":"string","format":"date-time","description":"Time activation failed safely."},"deactivated_at":{"type":"string","format":"date-time","description":"Time unified mode was disabled."},"error":{"type":"string","nullable":true,"description":"Bounded failure message visible to administrators."},"error_code":{"type":"string","nullable":true,"enum":["hybrid_feature_disabled","feature_disabled","pair_disabled","cloud_authority_required","inbox_missing","migration_required","active_calls_in_progress","unresolved_web_identity","active_state_conflict","external_state_continuity","unexpected_error"],"description":"Stable failure reason for localized dashboard guidance; raw diagnostics remain administrative."},"scanned":{"type":"integer","minimum":0,"description":"Legacy Web conversations examined."},"frozen":{"type":"integer","minimum":0,"description":"Open legacy Web 1:1 conversations cross-linked and resolved."},"already_frozen":{"type":"integer","minimum":0,"description":"Conversations already handled by an earlier delivery."},"skipped_web_native":{"type":"integer","minimum":0,"description":"Groups, newsletters, broadcasts, and bots deliberately retained on Web."},"skipped_without_identity":{"type":"integer","minimum":0,"description":"Conversations left untouched because no safe Cloud identity was available."},"skipped_already_resolved":{"type":"integer","minimum":0,"description":"Conversations already resolved before activation."},"skipped_external_continuity":{"type":"integer","minimum":0,"description":"Duplicate Web timelines whose external control state was not preserved on Cloud."},"external_continuity_checked":{"type":"integer","minimum":0,"description":"Duplicate Web and Cloud timelines compared through the read-only Maestro status contract."},"history_remains_frozen":{"type":"boolean","description":"Whether deactivation intentionally preserves completed cross-links."},"capabilities":{"type":"object","additionalProperties":true,"description":"Additive capability-repair audit keyed by capability family."}},"additionalProperties":false},"web_session_state":{"type":"object","additionalProperties":false,"required":["state","fresh","observed_at","disconnected_since"],"description":"Secret-free cached observation of the physical WhatsApp Web session. It is returned by the reader at response time; `unknown` covers absent, invalid, stale or temporarily unreadable state and is never a disconnected conclusion. Refresh the GET resource for a new observation.","properties":{"state":{"type":"string","enum":["connected","disconnected","unknown"]},"fresh":{"type":"boolean"},"observed_at":{"type":["string","null"],"format":"date-time"},"disconnected_since":{"type":["string","null"],"format":"date-time","description":"Null unless the current reader result is a fresh disconnected episode."}}}}},"example":{"id":4,"account_id":1,"canonical_phone_e164":"+5521900000000","cloud_channel_id":11,"web_channel_id":12,"cloud_inbox_id":17,"web_inbox_id":18,"primary":"cloud","inbound_authority":"cloud","routing":{"outbound_default":"cloud","out_of_window":"web","fallback":true,"manual_override":true,"weighted":{"mode":"weighted","web_percent":30,"version":2}},"enabled":true,"unified_inbox":true,"unified_state":{"state":"complete","request_id":"550e8400-e29b-41d4-a716-446655440000","requested_at":"2026-01-15T10:30:00.000Z","started_at":"2026-01-15T10:30:00.000Z","completed_at":"2026-01-15T10:30:00.000Z","failed_at":"2026-01-15T10:30:00.000Z","deactivated_at":"2026-01-15T10:30:00.000Z","error":"sample error","error_code":"hybrid_feature_disabled","scanned":1,"frozen":1,"already_frozen":1,"skipped_web_native":1,"skipped_without_identity":1,"skipped_already_resolved":1,"skipped_external_continuity":1,"external_continuity_checked":1,"history_remains_frozen":true,"capabilities":{}},"web_session_state":{"state":"connected","fresh":true,"observed_at":"2026-10-03T12:00:00.000Z","disconnected_since":null}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/whatsapp/hybrid_pairs":{"post":{"tags":["WhatsApp"],"operationId":"auto_post_api_v1_accounts_account_id_whatsapp_hybrid_pairs","summary":"Pair a Cloud API inbox with a WhatsApp Web inbox","description":"Creates the hybrid pair of one number (administrators only) and runs the automatic migration health check, whose summary is returned once as `audit`. The weighted distribution starts in `legacy` mode (version 1, 0%).","security":[{"userApiKey":[]}],"responses":{"201":{"description":"The new pair and its health-check audit.","content":{"application/json":{"schema":{"type":"object","required":["id","account_id","canonical_phone_e164","cloud_channel_id","web_channel_id","cloud_inbox_id","web_inbox_id","primary","inbound_authority","routing","enabled","unified_inbox","unified_state","web_session_state"],"description":"A WhatsApp hybrid pair, plus the creation audit.","properties":{"id":{"type":"integer","description":"Pair id."},"account_id":{"type":"integer","description":"Account id."},"canonical_phone_e164":{"type":"string","description":"The shared phone number in E.164."},"cloud_channel_id":{"type":"integer","description":"Cloud API channel id."},"web_channel_id":{"type":"integer","description":"WhatsApp Web channel id."},"cloud_inbox_id":{"type":["integer","null"],"description":"Inbox of the Cloud API channel."},"web_inbox_id":{"type":["integer","null"],"description":"Inbox of the WhatsApp Web channel."},"primary":{"type":"string","enum":["cloud","web"],"description":"Primary transport (only `cloud` is supported)."},"inbound_authority":{"type":"string","enum":["cloud","web","both"],"description":"Transport whose inbound events are authoritative (only `cloud` is supported)."},"routing":{"type":"object","required":["outbound_default","out_of_window","fallback","manual_override","weighted"],"additionalProperties":true,"description":"Effective routing of the pair — the stored keys over the product defaults. Keys stored by older versions may appear beside the ones listed.","properties":{"outbound_default":{"type":"string","enum":["cloud","web"],"description":"Transport of a reply inside the Cloud API customer-service window."},"out_of_window":{"type":"string","enum":["cloud","web"],"description":"Transport of a reply outside the Cloud API customer-service window."},"fallback":{"type":"boolean","description":"Whether a definitive rejection may fall back to the sibling transport."},"manual_override":{"type":"boolean","description":"Whether an agent may pick the transport in the conversation."},"weighted":{"type":"object","additionalProperties":false,"required":["mode","web_percent","version"],"description":"Per-contact weighted distribution between the two transports. `legacy` keeps the default outbound rule; `weighted` sends `web_percent`% of the eligible support sends of each contact through WhatsApp Web and the rest through Cloud API. A new percentage bumps `version`, which restarts every contact's count.","properties":{"mode":{"type":"string","enum":["legacy","weighted"],"description":"Distribution mode."},"web_percent":{"type":"integer","minimum":0,"maximum":100,"description":"Share of eligible sends routed through WhatsApp Web, in percent."},"version":{"type":"integer","minimum":1,"description":"Policy version, the optimistic-lock token of the next change."}}}}},"enabled":{"type":"boolean","description":"Whether the pair routes traffic."},"unified_inbox":{"type":"boolean","description":"Whether both transports are served through one logical inbox."},"unified_state":{"type":"object","description":"Progress and audit data for the current or most recent logical-inbox activation.","properties":{"state":{"type":"string","enum":["queued","running","complete","failed","inactive"],"description":"Current activation state."},"request_id":{"type":"string","format":"uuid","description":"Stable idempotency id of the activation request."},"requested_at":{"type":"string","format":"date-time","description":"Time the request was queued."},"started_at":{"type":"string","format":"date-time","description":"Time the worker started the request."},"completed_at":{"type":"string","format":"date-time","description":"Time activation completed."},"failed_at":{"type":"string","format":"date-time","description":"Time activation failed safely."},"deactivated_at":{"type":"string","format":"date-time","description":"Time unified mode was disabled."},"error":{"type":"string","nullable":true,"description":"Bounded failure message visible to administrators."},"error_code":{"type":"string","nullable":true,"enum":["hybrid_feature_disabled","feature_disabled","pair_disabled","cloud_authority_required","inbox_missing","migration_required","active_calls_in_progress","unresolved_web_identity","active_state_conflict","external_state_continuity","unexpected_error"],"description":"Stable failure reason for localized dashboard guidance; raw diagnostics remain administrative."},"scanned":{"type":"integer","minimum":0,"description":"Legacy Web conversations examined."},"frozen":{"type":"integer","minimum":0,"description":"Open legacy Web 1:1 conversations cross-linked and resolved."},"already_frozen":{"type":"integer","minimum":0,"description":"Conversations already handled by an earlier delivery."},"skipped_web_native":{"type":"integer","minimum":0,"description":"Groups, newsletters, broadcasts, and bots deliberately retained on Web."},"skipped_without_identity":{"type":"integer","minimum":0,"description":"Conversations left untouched because no safe Cloud identity was available."},"skipped_already_resolved":{"type":"integer","minimum":0,"description":"Conversations already resolved before activation."},"skipped_external_continuity":{"type":"integer","minimum":0,"description":"Duplicate Web timelines whose external control state was not preserved on Cloud."},"external_continuity_checked":{"type":"integer","minimum":0,"description":"Duplicate Web and Cloud timelines compared through the read-only Maestro status contract."},"history_remains_frozen":{"type":"boolean","description":"Whether deactivation intentionally preserves completed cross-links."},"capabilities":{"type":"object","additionalProperties":true,"description":"Additive capability-repair audit keyed by capability family."}},"additionalProperties":false},"web_session_state":{"type":"object","additionalProperties":false,"required":["state","fresh","observed_at","disconnected_since"],"description":"Secret-free cached observation of the physical WhatsApp Web session. It is returned by the reader at response time; `unknown` covers absent, invalid, stale or temporarily unreadable state and is never a disconnected conclusion. Refresh the GET resource for a new observation.","properties":{"state":{"type":"string","enum":["connected","disconnected","unknown"]},"fresh":{"type":"boolean"},"observed_at":{"type":["string","null"],"format":"date-time"},"disconnected_since":{"type":["string","null"],"format":"date-time","description":"Null unless the current reader result is a fresh disconnected episode."}}},"audit":{"type":"object","additionalProperties":true,"description":"Summary of the automatic migration health check run at pairing time."}}},"example":{"id":4,"account_id":1,"canonical_phone_e164":"+5521900000000","cloud_channel_id":11,"web_channel_id":12,"cloud_inbox_id":17,"web_inbox_id":18,"primary":"cloud","inbound_authority":"cloud","routing":{"outbound_default":"cloud","out_of_window":"web","fallback":true,"manual_override":true,"weighted":{"mode":"legacy","web_percent":0,"version":1}},"enabled":true,"unified_inbox":false,"unified_state":{"state":"inactive","request_id":"550e8400-e29b-41d4-a716-446655440000","requested_at":"2026-01-15T10:30:00.000Z","started_at":"2026-01-15T10:30:00.000Z","completed_at":"2026-01-15T10:30:00.000Z","failed_at":"2026-01-15T10:30:00.000Z","deactivated_at":"2026-01-15T10:30:00.000Z","error":"sample error","error_code":"hybrid_feature_disabled","scanned":1,"frozen":1,"already_frozen":1,"skipped_web_native":1,"skipped_without_identity":1,"skipped_already_resolved":1,"skipped_external_continuity":1,"external_continuity_checked":1,"history_remains_frozen":true,"capabilities":{}},"web_session_state":{"state":"unknown","fresh":false,"observed_at":null,"disconnected_since":null},"audit":{"web_inbox_id":18,"cloud_inbox_id":17,"agent_bot":{"moved":0,"skipped_conflict":0,"records":[]},"automation_rules":{"scanned":0,"moved":0,"records":[]},"macros":{"moved":0},"campaigns":{"moved":0,"paused":0,"records":[]},"flow_builder_inboxes":{"moved":0,"records":[]},"inbox_members":{"added":0,"records":[]}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"hybrid_pair":{"type":"object","properties":{"cloud_inbox_id":{"type":"integer"},"web_inbox_id":{"type":"integer"},"primary":{"type":"string","enum":["cloud","web"]},"inbound_authority":{"type":"string","enum":["cloud","web","both"]},"outbound_default":{"type":"string"},"out_of_window":{"type":"string"},"fallback":{"type":"string"},"manual_override":{"type":"string"}}}},"required":["hybrid_pair"]},"example":{"hybrid_pair":{"cloud_inbox_id":1,"web_inbox_id":1,"primary":"cloud","inbound_authority":"cloud","outbound_default":"sample outbound default","out_of_window":"sample out of window","fallback":"sample fallback","manual_override":"sample manual override"}}}}}}},"/api/v1/accounts/{account_id}/whatsapp/hybrid_pairs/{id}":{"get":{"tags":["WhatsApp"],"operationId":"auto_get_api_v1_accounts_account_id_whatsapp_hybrid_pairs_id","summary":"Get a WhatsApp hybrid pair","description":"The pair (administrators only) with its effective routing, including the per-contact weighted distribution under `routing.weighted`.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The pair, with its effective routing.","content":{"application/json":{"schema":{"type":"object","required":["id","account_id","canonical_phone_e164","cloud_channel_id","web_channel_id","cloud_inbox_id","web_inbox_id","primary","inbound_authority","routing","enabled","unified_inbox","unified_state","web_session_state"],"description":"A WhatsApp hybrid pair.","properties":{"id":{"type":"integer","description":"Pair id."},"account_id":{"type":"integer","description":"Account id."},"canonical_phone_e164":{"type":"string","description":"The shared phone number in E.164."},"cloud_channel_id":{"type":"integer","description":"Cloud API channel id."},"web_channel_id":{"type":"integer","description":"WhatsApp Web channel id."},"cloud_inbox_id":{"type":["integer","null"],"description":"Inbox of the Cloud API channel."},"web_inbox_id":{"type":["integer","null"],"description":"Inbox of the WhatsApp Web channel."},"primary":{"type":"string","enum":["cloud","web"],"description":"Primary transport (only `cloud` is supported)."},"inbound_authority":{"type":"string","enum":["cloud","web","both"],"description":"Transport whose inbound events are authoritative (only `cloud` is supported)."},"routing":{"type":"object","required":["outbound_default","out_of_window","fallback","manual_override","weighted"],"additionalProperties":true,"description":"Effective routing of the pair — the stored keys over the product defaults. Keys stored by older versions may appear beside the ones listed.","properties":{"outbound_default":{"type":"string","enum":["cloud","web"],"description":"Transport of a reply inside the Cloud API customer-service window."},"out_of_window":{"type":"string","enum":["cloud","web"],"description":"Transport of a reply outside the Cloud API customer-service window."},"fallback":{"type":"boolean","description":"Whether a definitive rejection may fall back to the sibling transport."},"manual_override":{"type":"boolean","description":"Whether an agent may pick the transport in the conversation."},"weighted":{"type":"object","additionalProperties":false,"required":["mode","web_percent","version"],"description":"Per-contact weighted distribution between the two transports. `legacy` keeps the default outbound rule; `weighted` sends `web_percent`% of the eligible support sends of each contact through WhatsApp Web and the rest through Cloud API. A new percentage bumps `version`, which restarts every contact's count.","properties":{"mode":{"type":"string","enum":["legacy","weighted"],"description":"Distribution mode."},"web_percent":{"type":"integer","minimum":0,"maximum":100,"description":"Share of eligible sends routed through WhatsApp Web, in percent."},"version":{"type":"integer","minimum":1,"description":"Policy version, the optimistic-lock token of the next change."}}}}},"enabled":{"type":"boolean","description":"Whether the pair routes traffic."},"unified_inbox":{"type":"boolean","description":"Whether both transports are served through one logical inbox."},"unified_state":{"type":"object","description":"Progress and audit data for the current or most recent logical-inbox activation.","properties":{"state":{"type":"string","enum":["queued","running","complete","failed","inactive"],"description":"Current activation state."},"request_id":{"type":"string","format":"uuid","description":"Stable idempotency id of the activation request."},"requested_at":{"type":"string","format":"date-time","description":"Time the request was queued."},"started_at":{"type":"string","format":"date-time","description":"Time the worker started the request."},"completed_at":{"type":"string","format":"date-time","description":"Time activation completed."},"failed_at":{"type":"string","format":"date-time","description":"Time activation failed safely."},"deactivated_at":{"type":"string","format":"date-time","description":"Time unified mode was disabled."},"error":{"type":"string","nullable":true,"description":"Bounded failure message visible to administrators."},"error_code":{"type":"string","nullable":true,"enum":["hybrid_feature_disabled","feature_disabled","pair_disabled","cloud_authority_required","inbox_missing","migration_required","active_calls_in_progress","unresolved_web_identity","active_state_conflict","external_state_continuity","unexpected_error"],"description":"Stable failure reason for localized dashboard guidance; raw diagnostics remain administrative."},"scanned":{"type":"integer","minimum":0,"description":"Legacy Web conversations examined."},"frozen":{"type":"integer","minimum":0,"description":"Open legacy Web 1:1 conversations cross-linked and resolved."},"already_frozen":{"type":"integer","minimum":0,"description":"Conversations already handled by an earlier delivery."},"skipped_web_native":{"type":"integer","minimum":0,"description":"Groups, newsletters, broadcasts, and bots deliberately retained on Web."},"skipped_without_identity":{"type":"integer","minimum":0,"description":"Conversations left untouched because no safe Cloud identity was available."},"skipped_already_resolved":{"type":"integer","minimum":0,"description":"Conversations already resolved before activation."},"skipped_external_continuity":{"type":"integer","minimum":0,"description":"Duplicate Web timelines whose external control state was not preserved on Cloud."},"external_continuity_checked":{"type":"integer","minimum":0,"description":"Duplicate Web and Cloud timelines compared through the read-only Maestro status contract."},"history_remains_frozen":{"type":"boolean","description":"Whether deactivation intentionally preserves completed cross-links."},"capabilities":{"type":"object","additionalProperties":true,"description":"Additive capability-repair audit keyed by capability family."}},"additionalProperties":false},"web_session_state":{"type":"object","additionalProperties":false,"required":["state","fresh","observed_at","disconnected_since"],"description":"Secret-free cached observation of the physical WhatsApp Web session. It is returned by the reader at response time; `unknown` covers absent, invalid, stale or temporarily unreadable state and is never a disconnected conclusion. Refresh the GET resource for a new observation.","properties":{"state":{"type":"string","enum":["connected","disconnected","unknown"]},"fresh":{"type":"boolean"},"observed_at":{"type":["string","null"],"format":"date-time"},"disconnected_since":{"type":["string","null"],"format":"date-time","description":"Null unless the current reader result is a fresh disconnected episode."}}}}},"example":{"id":4,"account_id":1,"canonical_phone_e164":"+5521900000000","cloud_channel_id":11,"web_channel_id":12,"cloud_inbox_id":17,"web_inbox_id":18,"primary":"cloud","inbound_authority":"cloud","routing":{"outbound_default":"cloud","out_of_window":"web","fallback":true,"manual_override":true,"weighted":{"mode":"weighted","web_percent":30,"version":2}},"enabled":true,"unified_inbox":true,"unified_state":{"state":"complete","request_id":"550e8400-e29b-41d4-a716-446655440000","requested_at":"2026-01-15T10:30:00.000Z","started_at":"2026-01-15T10:30:00.000Z","completed_at":"2026-01-15T10:30:00.000Z","failed_at":"2026-01-15T10:30:00.000Z","deactivated_at":"2026-01-15T10:30:00.000Z","error":"sample error","error_code":"hybrid_feature_disabled","scanned":1,"frozen":1,"already_frozen":1,"skipped_web_native":1,"skipped_without_identity":1,"skipped_already_resolved":1,"skipped_external_continuity":1,"external_continuity_checked":1,"history_remains_frozen":true,"capabilities":{}},"web_session_state":{"state":"connected","fresh":true,"observed_at":"2026-10-03T12:00:00.000Z","disconnected_since":null}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]},"patch":{"tags":["WhatsApp"],"operationId":"auto_patch_api_v1_accounts_account_id_whatsapp_hybrid_pairs_id","summary":"Update the routing of a WhatsApp hybrid pair","description":"Partial edit of the pair routing (administrators only). Legacy keys are merged over the stored routing. `routing.weighted` changes the per-contact weighted distribution under optimistic locking: send the `version` you read; mode and percentage default to the stored values; a no-op keeps the version and an effective change bumps it, which restarts every contact's count. `weighted` mode requires the unified inbox. Only Cloud-primary, Cloud-authoritative pairs are supported.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The pair, with its effective routing.","content":{"application/json":{"schema":{"type":"object","required":["id","account_id","canonical_phone_e164","cloud_channel_id","web_channel_id","cloud_inbox_id","web_inbox_id","primary","inbound_authority","routing","enabled","unified_inbox","unified_state","web_session_state"],"description":"A WhatsApp hybrid pair.","properties":{"id":{"type":"integer","description":"Pair id."},"account_id":{"type":"integer","description":"Account id."},"canonical_phone_e164":{"type":"string","description":"The shared phone number in E.164."},"cloud_channel_id":{"type":"integer","description":"Cloud API channel id."},"web_channel_id":{"type":"integer","description":"WhatsApp Web channel id."},"cloud_inbox_id":{"type":["integer","null"],"description":"Inbox of the Cloud API channel."},"web_inbox_id":{"type":["integer","null"],"description":"Inbox of the WhatsApp Web channel."},"primary":{"type":"string","enum":["cloud","web"],"description":"Primary transport (only `cloud` is supported)."},"inbound_authority":{"type":"string","enum":["cloud","web","both"],"description":"Transport whose inbound events are authoritative (only `cloud` is supported)."},"routing":{"type":"object","required":["outbound_default","out_of_window","fallback","manual_override","weighted"],"additionalProperties":true,"description":"Effective routing of the pair — the stored keys over the product defaults. Keys stored by older versions may appear beside the ones listed.","properties":{"outbound_default":{"type":"string","enum":["cloud","web"],"description":"Transport of a reply inside the Cloud API customer-service window."},"out_of_window":{"type":"string","enum":["cloud","web"],"description":"Transport of a reply outside the Cloud API customer-service window."},"fallback":{"type":"boolean","description":"Whether a definitive rejection may fall back to the sibling transport."},"manual_override":{"type":"boolean","description":"Whether an agent may pick the transport in the conversation."},"weighted":{"type":"object","additionalProperties":false,"required":["mode","web_percent","version"],"description":"Per-contact weighted distribution between the two transports. `legacy` keeps the default outbound rule; `weighted` sends `web_percent`% of the eligible support sends of each contact through WhatsApp Web and the rest through Cloud API. A new percentage bumps `version`, which restarts every contact's count.","properties":{"mode":{"type":"string","enum":["legacy","weighted"],"description":"Distribution mode."},"web_percent":{"type":"integer","minimum":0,"maximum":100,"description":"Share of eligible sends routed through WhatsApp Web, in percent."},"version":{"type":"integer","minimum":1,"description":"Policy version, the optimistic-lock token of the next change."}}}}},"enabled":{"type":"boolean","description":"Whether the pair routes traffic."},"unified_inbox":{"type":"boolean","description":"Whether both transports are served through one logical inbox."},"unified_state":{"type":"object","description":"Progress and audit data for the current or most recent logical-inbox activation.","properties":{"state":{"type":"string","enum":["queued","running","complete","failed","inactive"],"description":"Current activation state."},"request_id":{"type":"string","format":"uuid","description":"Stable idempotency id of the activation request."},"requested_at":{"type":"string","format":"date-time","description":"Time the request was queued."},"started_at":{"type":"string","format":"date-time","description":"Time the worker started the request."},"completed_at":{"type":"string","format":"date-time","description":"Time activation completed."},"failed_at":{"type":"string","format":"date-time","description":"Time activation failed safely."},"deactivated_at":{"type":"string","format":"date-time","description":"Time unified mode was disabled."},"error":{"type":"string","nullable":true,"description":"Bounded failure message visible to administrators."},"error_code":{"type":"string","nullable":true,"enum":["hybrid_feature_disabled","feature_disabled","pair_disabled","cloud_authority_required","inbox_missing","migration_required","active_calls_in_progress","unresolved_web_identity","active_state_conflict","external_state_continuity","unexpected_error"],"description":"Stable failure reason for localized dashboard guidance; raw diagnostics remain administrative."},"scanned":{"type":"integer","minimum":0,"description":"Legacy Web conversations examined."},"frozen":{"type":"integer","minimum":0,"description":"Open legacy Web 1:1 conversations cross-linked and resolved."},"already_frozen":{"type":"integer","minimum":0,"description":"Conversations already handled by an earlier delivery."},"skipped_web_native":{"type":"integer","minimum":0,"description":"Groups, newsletters, broadcasts, and bots deliberately retained on Web."},"skipped_without_identity":{"type":"integer","minimum":0,"description":"Conversations left untouched because no safe Cloud identity was available."},"skipped_already_resolved":{"type":"integer","minimum":0,"description":"Conversations already resolved before activation."},"skipped_external_continuity":{"type":"integer","minimum":0,"description":"Duplicate Web timelines whose external control state was not preserved on Cloud."},"external_continuity_checked":{"type":"integer","minimum":0,"description":"Duplicate Web and Cloud timelines compared through the read-only Maestro status contract."},"history_remains_frozen":{"type":"boolean","description":"Whether deactivation intentionally preserves completed cross-links."},"capabilities":{"type":"object","additionalProperties":true,"description":"Additive capability-repair audit keyed by capability family."}},"additionalProperties":false},"web_session_state":{"type":"object","additionalProperties":false,"required":["state","fresh","observed_at","disconnected_since"],"description":"Secret-free cached observation of the physical WhatsApp Web session. It is returned by the reader at response time; `unknown` covers absent, invalid, stale or temporarily unreadable state and is never a disconnected conclusion. Refresh the GET resource for a new observation.","properties":{"state":{"type":"string","enum":["connected","disconnected","unknown"]},"fresh":{"type":"boolean"},"observed_at":{"type":["string","null"],"format":"date-time"},"disconnected_since":{"type":["string","null"],"format":"date-time","description":"Null unless the current reader result is a fresh disconnected episode."}}}}},"example":{"id":4,"account_id":1,"canonical_phone_e164":"+5521900000000","cloud_channel_id":11,"web_channel_id":12,"cloud_inbox_id":17,"web_inbox_id":18,"primary":"cloud","inbound_authority":"cloud","routing":{"outbound_default":"cloud","out_of_window":"web","fallback":true,"manual_override":true,"weighted":{"mode":"weighted","web_percent":30,"version":2}},"enabled":true,"unified_inbox":true,"unified_state":{"state":"complete","request_id":"550e8400-e29b-41d4-a716-446655440000","requested_at":"2026-01-15T10:30:00.000Z","started_at":"2026-01-15T10:30:00.000Z","completed_at":"2026-01-15T10:30:00.000Z","failed_at":"2026-01-15T10:30:00.000Z","deactivated_at":"2026-01-15T10:30:00.000Z","error":"sample error","error_code":"hybrid_feature_disabled","scanned":1,"frozen":1,"already_frozen":1,"skipped_web_native":1,"skipped_without_identity":1,"skipped_already_resolved":1,"skipped_external_continuity":1,"external_continuity_checked":1,"history_remains_frozen":true,"capabilities":{}},"web_session_state":{"state":"connected","fresh":true,"observed_at":"2026-10-03T12:00:00.000Z","disconnected_since":null}}}}},"401":{"description":"Unauthorized"},"404":{"description":"The pair does not exist in the account, or `routing.weighted` was sent while the weighted-routing feature is off for the account.","content":{"application/json":{"schema":{"anyOf":[{"type":"object","additionalProperties":false,"required":["error","feature"],"properties":{"error":{"type":"string","enum":["feature_disabled"],"description":"Stable code."},"feature":{"type":"string","enum":["whatsapp_hybrid_weighted_routing"],"description":"The feature flag that is off."}}},{"type":"object","additionalProperties":false,"required":["error"],"description":"Generic lookup failure of the account API (the conversation or inbox does not exist in this account).","properties":{"error":{"type":"string","description":"Human-readable lookup failure (\"Resource could not be found\")."}}}]},"example":{"error":"feature_disabled","feature":"whatsapp_hybrid_weighted_routing"}}}},"409":{"description":"The weighted distribution changed in another session; reload and apply the change again.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error","current_version"],"properties":{"error":{"type":"string","enum":["configuration_version_conflict"],"description":"Stable code."},"current_version":{"type":"integer","minimum":1,"description":"The version stored now."}}},"example":{"error":"configuration_version_conflict","current_version":3}}}},"422":{"description":"`invalid_configuration` with one entry per invalid `routing.weighted` field; `hybrid_unified_required` when `weighted` mode is requested without the unified inbox; or a translated sentence when the mode is not Cloud-primary/Cloud-authoritative or a legacy routing key names an unknown transport.","content":{"application/json":{"schema":{"anyOf":[{"type":"object","additionalProperties":false,"required":["error","errors"],"properties":{"error":{"type":"string","enum":["invalid_configuration"],"description":"Stable code."},"errors":{"type":"array","description":"One entry per invalid field.","items":{"type":"object","additionalProperties":false,"required":["field","code"],"properties":{"field":{"type":"string","pattern":"^routing\\.weighted(\\.[A-Za-z0-9_]+)?$","description":"The offending key (`routing.weighted`, `routing.weighted.mode`, `routing.weighted.web_percent`, `routing.weighted.version`); an unknown key inside `routing.weighted` is reported as `routing.weighted.\u003ckey\u003e` with `unknown_field`."},"code":{"type":"string","enum":["required","invalid_type","out_of_range","not_allowed","unknown_field"],"description":"Stable field error code."}}}}}},{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","description":"`hybrid_unified_required`, or a translated sentence for an unsupported mode or transport."}}}]},"example":{"error":"invalid_configuration","errors":[{"field":"routing.weighted.web_percent","code":"out_of_range"}]}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["hybrid_pair"],"properties":{"hybrid_pair":{"type":"object","description":"The keys to change; absent keys keep their stored value.","properties":{"primary":{"type":"string","enum":["cloud","web"],"description":"Primary transport; any value other than `cloud` is refused with 422."},"inbound_authority":{"type":"string","enum":["cloud","web","both"],"description":"Inbound authority; any value other than `cloud` is refused with 422."},"outbound_default":{"type":"string","enum":["cloud","web"],"description":"Transport of a reply inside the Cloud API customer-service window."},"out_of_window":{"type":"string","enum":["cloud","web"],"description":"Transport of a reply outside the Cloud API customer-service window."},"fallback":{"type":"boolean","description":"Whether a definitive rejection may fall back to the sibling transport."},"manual_override":{"type":"boolean","description":"Whether an agent may pick the transport in the conversation."},"routing":{"type":"object","additionalProperties":false,"description":"Nested routing changes.","properties":{"weighted":{"type":"object","additionalProperties":false,"required":["version"],"description":"Weighted distribution change; `version` is the expected (last read) version.","properties":{"mode":{"type":"string","enum":["legacy","weighted"],"description":"Distribution mode."},"web_percent":{"type":"integer","minimum":0,"maximum":100,"description":"Share of eligible sends through WhatsApp Web, in percent (strict integer)."},"version":{"type":"integer","minimum":1,"description":"The version read before editing."}}}}}}}}},"example":{"hybrid_pair":{"primary":"cloud","inbound_authority":"cloud","outbound_default":"cloud","out_of_window":"web","fallback":true,"manual_override":true,"routing":{"weighted":{"mode":"weighted","web_percent":30,"version":1}}}}}}}},"put":{"tags":["WhatsApp"],"operationId":"auto_put_api_v1_accounts_account_id_whatsapp_hybrid_pairs_id","summary":"Update the routing of a WhatsApp hybrid pair","description":"Partial edit of the pair routing (administrators only). Legacy keys are merged over the stored routing. `routing.weighted` changes the per-contact weighted distribution under optimistic locking: send the `version` you read; mode and percentage default to the stored values; a no-op keeps the version and an effective change bumps it, which restarts every contact's count. `weighted` mode requires the unified inbox. Only Cloud-primary, Cloud-authoritative pairs are supported.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The pair, with its effective routing.","content":{"application/json":{"schema":{"type":"object","required":["id","account_id","canonical_phone_e164","cloud_channel_id","web_channel_id","cloud_inbox_id","web_inbox_id","primary","inbound_authority","routing","enabled","unified_inbox","unified_state","web_session_state"],"description":"A WhatsApp hybrid pair.","properties":{"id":{"type":"integer","description":"Pair id."},"account_id":{"type":"integer","description":"Account id."},"canonical_phone_e164":{"type":"string","description":"The shared phone number in E.164."},"cloud_channel_id":{"type":"integer","description":"Cloud API channel id."},"web_channel_id":{"type":"integer","description":"WhatsApp Web channel id."},"cloud_inbox_id":{"type":["integer","null"],"description":"Inbox of the Cloud API channel."},"web_inbox_id":{"type":["integer","null"],"description":"Inbox of the WhatsApp Web channel."},"primary":{"type":"string","enum":["cloud","web"],"description":"Primary transport (only `cloud` is supported)."},"inbound_authority":{"type":"string","enum":["cloud","web","both"],"description":"Transport whose inbound events are authoritative (only `cloud` is supported)."},"routing":{"type":"object","required":["outbound_default","out_of_window","fallback","manual_override","weighted"],"additionalProperties":true,"description":"Effective routing of the pair — the stored keys over the product defaults. Keys stored by older versions may appear beside the ones listed.","properties":{"outbound_default":{"type":"string","enum":["cloud","web"],"description":"Transport of a reply inside the Cloud API customer-service window."},"out_of_window":{"type":"string","enum":["cloud","web"],"description":"Transport of a reply outside the Cloud API customer-service window."},"fallback":{"type":"boolean","description":"Whether a definitive rejection may fall back to the sibling transport."},"manual_override":{"type":"boolean","description":"Whether an agent may pick the transport in the conversation."},"weighted":{"type":"object","additionalProperties":false,"required":["mode","web_percent","version"],"description":"Per-contact weighted distribution between the two transports. `legacy` keeps the default outbound rule; `weighted` sends `web_percent`% of the eligible support sends of each contact through WhatsApp Web and the rest through Cloud API. A new percentage bumps `version`, which restarts every contact's count.","properties":{"mode":{"type":"string","enum":["legacy","weighted"],"description":"Distribution mode."},"web_percent":{"type":"integer","minimum":0,"maximum":100,"description":"Share of eligible sends routed through WhatsApp Web, in percent."},"version":{"type":"integer","minimum":1,"description":"Policy version, the optimistic-lock token of the next change."}}}}},"enabled":{"type":"boolean","description":"Whether the pair routes traffic."},"unified_inbox":{"type":"boolean","description":"Whether both transports are served through one logical inbox."},"unified_state":{"type":"object","description":"Progress and audit data for the current or most recent logical-inbox activation.","properties":{"state":{"type":"string","enum":["queued","running","complete","failed","inactive"],"description":"Current activation state."},"request_id":{"type":"string","format":"uuid","description":"Stable idempotency id of the activation request."},"requested_at":{"type":"string","format":"date-time","description":"Time the request was queued."},"started_at":{"type":"string","format":"date-time","description":"Time the worker started the request."},"completed_at":{"type":"string","format":"date-time","description":"Time activation completed."},"failed_at":{"type":"string","format":"date-time","description":"Time activation failed safely."},"deactivated_at":{"type":"string","format":"date-time","description":"Time unified mode was disabled."},"error":{"type":"string","nullable":true,"description":"Bounded failure message visible to administrators."},"error_code":{"type":"string","nullable":true,"enum":["hybrid_feature_disabled","feature_disabled","pair_disabled","cloud_authority_required","inbox_missing","migration_required","active_calls_in_progress","unresolved_web_identity","active_state_conflict","external_state_continuity","unexpected_error"],"description":"Stable failure reason for localized dashboard guidance; raw diagnostics remain administrative."},"scanned":{"type":"integer","minimum":0,"description":"Legacy Web conversations examined."},"frozen":{"type":"integer","minimum":0,"description":"Open legacy Web 1:1 conversations cross-linked and resolved."},"already_frozen":{"type":"integer","minimum":0,"description":"Conversations already handled by an earlier delivery."},"skipped_web_native":{"type":"integer","minimum":0,"description":"Groups, newsletters, broadcasts, and bots deliberately retained on Web."},"skipped_without_identity":{"type":"integer","minimum":0,"description":"Conversations left untouched because no safe Cloud identity was available."},"skipped_already_resolved":{"type":"integer","minimum":0,"description":"Conversations already resolved before activation."},"skipped_external_continuity":{"type":"integer","minimum":0,"description":"Duplicate Web timelines whose external control state was not preserved on Cloud."},"external_continuity_checked":{"type":"integer","minimum":0,"description":"Duplicate Web and Cloud timelines compared through the read-only Maestro status contract."},"history_remains_frozen":{"type":"boolean","description":"Whether deactivation intentionally preserves completed cross-links."},"capabilities":{"type":"object","additionalProperties":true,"description":"Additive capability-repair audit keyed by capability family."}},"additionalProperties":false},"web_session_state":{"type":"object","additionalProperties":false,"required":["state","fresh","observed_at","disconnected_since"],"description":"Secret-free cached observation of the physical WhatsApp Web session. It is returned by the reader at response time; `unknown` covers absent, invalid, stale or temporarily unreadable state and is never a disconnected conclusion. Refresh the GET resource for a new observation.","properties":{"state":{"type":"string","enum":["connected","disconnected","unknown"]},"fresh":{"type":"boolean"},"observed_at":{"type":["string","null"],"format":"date-time"},"disconnected_since":{"type":["string","null"],"format":"date-time","description":"Null unless the current reader result is a fresh disconnected episode."}}}}},"example":{"id":4,"account_id":1,"canonical_phone_e164":"+5521900000000","cloud_channel_id":11,"web_channel_id":12,"cloud_inbox_id":17,"web_inbox_id":18,"primary":"cloud","inbound_authority":"cloud","routing":{"outbound_default":"cloud","out_of_window":"web","fallback":true,"manual_override":true,"weighted":{"mode":"weighted","web_percent":30,"version":2}},"enabled":true,"unified_inbox":true,"unified_state":{"state":"complete","request_id":"550e8400-e29b-41d4-a716-446655440000","requested_at":"2026-01-15T10:30:00.000Z","started_at":"2026-01-15T10:30:00.000Z","completed_at":"2026-01-15T10:30:00.000Z","failed_at":"2026-01-15T10:30:00.000Z","deactivated_at":"2026-01-15T10:30:00.000Z","error":"sample error","error_code":"hybrid_feature_disabled","scanned":1,"frozen":1,"already_frozen":1,"skipped_web_native":1,"skipped_without_identity":1,"skipped_already_resolved":1,"skipped_external_continuity":1,"external_continuity_checked":1,"history_remains_frozen":true,"capabilities":{}},"web_session_state":{"state":"connected","fresh":true,"observed_at":"2026-10-03T12:00:00.000Z","disconnected_since":null}}}}},"401":{"description":"Unauthorized"},"404":{"description":"The pair does not exist in the account, or `routing.weighted` was sent while the weighted-routing feature is off for the account.","content":{"application/json":{"schema":{"anyOf":[{"type":"object","additionalProperties":false,"required":["error","feature"],"properties":{"error":{"type":"string","enum":["feature_disabled"],"description":"Stable code."},"feature":{"type":"string","enum":["whatsapp_hybrid_weighted_routing"],"description":"The feature flag that is off."}}},{"type":"object","additionalProperties":false,"required":["error"],"description":"Generic lookup failure of the account API (the conversation or inbox does not exist in this account).","properties":{"error":{"type":"string","description":"Human-readable lookup failure (\"Resource could not be found\")."}}}]},"example":{"error":"feature_disabled","feature":"whatsapp_hybrid_weighted_routing"}}}},"409":{"description":"The weighted distribution changed in another session; reload and apply the change again.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error","current_version"],"properties":{"error":{"type":"string","enum":["configuration_version_conflict"],"description":"Stable code."},"current_version":{"type":"integer","minimum":1,"description":"The version stored now."}}},"example":{"error":"configuration_version_conflict","current_version":3}}}},"422":{"description":"`invalid_configuration` with one entry per invalid `routing.weighted` field; `hybrid_unified_required` when `weighted` mode is requested without the unified inbox; or a translated sentence when the mode is not Cloud-primary/Cloud-authoritative or a legacy routing key names an unknown transport.","content":{"application/json":{"schema":{"anyOf":[{"type":"object","additionalProperties":false,"required":["error","errors"],"properties":{"error":{"type":"string","enum":["invalid_configuration"],"description":"Stable code."},"errors":{"type":"array","description":"One entry per invalid field.","items":{"type":"object","additionalProperties":false,"required":["field","code"],"properties":{"field":{"type":"string","pattern":"^routing\\.weighted(\\.[A-Za-z0-9_]+)?$","description":"The offending key (`routing.weighted`, `routing.weighted.mode`, `routing.weighted.web_percent`, `routing.weighted.version`); an unknown key inside `routing.weighted` is reported as `routing.weighted.\u003ckey\u003e` with `unknown_field`."},"code":{"type":"string","enum":["required","invalid_type","out_of_range","not_allowed","unknown_field"],"description":"Stable field error code."}}}}}},{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","description":"`hybrid_unified_required`, or a translated sentence for an unsupported mode or transport."}}}]},"example":{"error":"invalid_configuration","errors":[{"field":"routing.weighted.web_percent","code":"out_of_range"}]}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["hybrid_pair"],"properties":{"hybrid_pair":{"type":"object","description":"The keys to change; absent keys keep their stored value.","properties":{"primary":{"type":"string","enum":["cloud","web"],"description":"Primary transport; any value other than `cloud` is refused with 422."},"inbound_authority":{"type":"string","enum":["cloud","web","both"],"description":"Inbound authority; any value other than `cloud` is refused with 422."},"outbound_default":{"type":"string","enum":["cloud","web"],"description":"Transport of a reply inside the Cloud API customer-service window."},"out_of_window":{"type":"string","enum":["cloud","web"],"description":"Transport of a reply outside the Cloud API customer-service window."},"fallback":{"type":"boolean","description":"Whether a definitive rejection may fall back to the sibling transport."},"manual_override":{"type":"boolean","description":"Whether an agent may pick the transport in the conversation."},"routing":{"type":"object","additionalProperties":false,"description":"Nested routing changes.","properties":{"weighted":{"type":"object","additionalProperties":false,"required":["version"],"description":"Weighted distribution change; `version` is the expected (last read) version.","properties":{"mode":{"type":"string","enum":["legacy","weighted"],"description":"Distribution mode."},"web_percent":{"type":"integer","minimum":0,"maximum":100,"description":"Share of eligible sends through WhatsApp Web, in percent (strict integer)."},"version":{"type":"integer","minimum":1,"description":"The version read before editing."}}}}}}}}},"example":{"hybrid_pair":{"primary":"cloud","inbound_authority":"cloud","outbound_default":"cloud","out_of_window":"web","fallback":true,"manual_override":true,"routing":{"weighted":{"mode":"weighted","web_percent":30,"version":1}}}}}}}},"delete":{"tags":["WhatsApp"],"operationId":"auto_delete_api_v1_accounts_account_id_whatsapp_hybrid_pairs_id","summary":"Delete hybrid pairs","description":"Deletes the hybrid pair identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Success (no content)"},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/whatsapp/costs/sync":{"post":{"tags":["WhatsApp"],"operationId":"auto_post_api_v1_accounts_account_id_whatsapp_costs_sync","summary":"Sync costs","description":"Pulls Meta's pricing_analytics for the inbox's WABA into the cost snapshots. For a partner-billed WABA Meta returns volume only. Errors are sanitized codes, never Meta's message. Administrators and the inbox_manage / whatsapp_hub_manage roles only.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Number of cost snapshot rows upserted.","content":{"application/json":{"schema":{"type":"object","properties":{"synced":{"type":"integer","example":12,"description":"Snapshot rows upserted."},"partner_billed":{"type":"boolean","example":false,"description":"True when Meta refused the cost metric because the WABA is partner-billed (volume only was synced)."},"metric_types":{"type":"array","items":{"type":"string","enum":["VOLUME","COST"]},"example":["VOLUME","COST"],"description":"The pricing_analytics metrics that were synced."}}},"example":{"synced":12,"partner_billed":false,"metric_types":["VOLUME","COST"]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"422":{"description":"The inbox cannot be read — it is not a Cloud inbox, has no WhatsApp Business Account id, or is not a WhatsApp Cloud inbox at all.","content":{"application/json":{"schema":{"type":"object","properties":{"synced":{"type":"integer","example":0},"error":{"type":"string","enum":["not_cloud","no_business_account_id","not_a_cloud_inbox"],"example":"no_business_account_id"}}},"example":{"synced":0,"error":"no_business_account_id"}}}},"424":{"description":"Meta's pricing_analytics could not be read; the reason is a sanitized code.","content":{"application/json":{"schema":{"type":"object","properties":{"synced":{"type":"integer","example":0},"error":{"type":"string","enum":["meta_unavailable"],"example":"meta_unavailable"},"reason":{"type":"string","enum":["meta_auth_error","meta_rate_limited","meta_permission_denied","meta_unavailable"],"example":"meta_auth_error"},"partner_billed":{"type":"boolean","example":true,"description":"Present when the failure happened on the volume-only retry of a partner-billed WABA."}}},"example":{"synced":0,"error":"meta_unavailable","reason":"meta_auth_error","partner_billed":true}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"inbox_id","in":"query","required":true,"description":"The WhatsApp inbox; a WhatsApp Web inbox of a paired number syncs through its Cloud sibling.","schema":{"type":"integer"},"example":42}]}},"/api/v1/accounts/{account_id}/whatsapp/costs":{"get":{"tags":["WhatsApp"],"operationId":"auto_get_api_v1_accounts_account_id_whatsapp_costs","summary":"List costs","description":"Meta pricing_analytics billed cost of one WhatsApp Cloud inbox (including Coexistence) for the window, per billing currency and converted into the display currency, plus the WABA billing identity. The billing currency is the WABA's own, read from Meta — never presumed; `currency` is null until it has been read. Amounts are decimal strings in MAJOR units. Administrators and the inbox_manage / whatsapp_hub_manage roles only.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Aggregated Meta pricing_analytics billed cost for the window, with the WABA billing identity.","content":{"application/json":{"schema":{"type":"object","properties":{"display_currency":{"type":"string","example":"BRL"},"currencies":{"type":"array","items":{"type":"string"},"description":"Billing currencies present in the window (`unknown` for rows of a WABA whose currency was never read).","example":["USD"]},"by_currency":{"type":"object","additionalProperties":{"type":"string"},"description":"Raw billed cost per WABA billing currency (not converted), as a decimal string.","example":{"USD":"12.5"}},"total_display":{"type":["string","null"],"example":"64.75","description":"Sum converted to display_currency, as a decimal string; null if any currency segment lacks FX (an `unknown` segment is never converted)."},"total_volume":{"type":"integer","example":4820,"description":"Total billed conversations in the window."},"by_category":{"type":"object","additionalProperties":{"type":"string"},"description":"Cost per pricing_category, in display_currency, as a decimal string.","example":{"marketing":"40.0","utility":"24.75"}},"by_type":{"type":"object","additionalProperties":{"type":"string"},"description":"Cost totals (in the display currency) keyed by Meta pricing type, as decimal strings.","example":{"PMP":"40.0"}},"by_tier":{"type":"object","additionalProperties":{"type":"string"},"description":"Cost totals (in the display currency) keyed by Meta pricing tier, as decimal strings.","example":{"":"64.75"}},"currency":{"type":["string","null"],"example":"USD","description":"The WABA billing currency read from Meta (ISO 4217); null until it has been read."},"currency_checked_at":{"type":["string","null"],"format":"date-time","example":"2026-09-20T12:00:00Z","description":"When the billing currency was last read from Meta."},"billing_utc_offset":{"type":["string","null"],"example":"-03:00","description":"The WABA time-zone offset that defines its billing day; null until read."},"partner_billed":{"type":"boolean","example":false,"description":"True when the WABA is billed by a Solution Partner, so Meta reports volume but no cost."},"error":{"type":["string","null"],"enum":[null],"example":null,"description":"Always null on success; kept so the response shape matches the error bodies."}}},"example":{"display_currency":"BRL","currencies":["USD"],"by_currency":{"USD":"12.5"},"total_display":"64.75","total_volume":4820,"by_category":{"marketing":"40.0","utility":"24.75"},"by_type":{"PMP":"40.0"},"by_tier":{"":"64.75"},"currency":"USD","currency_checked_at":"2026-09-20T12:00:00Z","billing_utc_offset":"-03:00","partner_billed":false,"error":null}}}},"422":{"description":"The inbox is not a WhatsApp Cloud inbox.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["not_a_cloud_inbox"],"example":"not_a_cloud_inbox"}}},"example":{"error":"not_a_cloud_inbox"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"inbox_id","in":"query","required":true,"description":"The WhatsApp inbox; a WhatsApp Web inbox of a paired number reports through its Cloud sibling.","schema":{"type":"integer"},"example":42},{"name":"start","in":"query","required":false,"description":"Window start as epoch seconds. Defaults to 30 days ago.","schema":{"type":"integer"},"example":1790812800},{"name":"end","in":"query","required":false,"description":"Window end as epoch seconds. Defaults to now.","schema":{"type":"integer"},"example":1793404800},{"name":"display_currency","in":"query","required":false,"description":"ISO 4217 currency the totals are converted into. Defaults to BRL.","schema":{"type":"string"},"example":"BRL"}]}},"/api/v1/accounts/{account_id}/whatsapp/currency":{"get":{"tags":["WhatsApp"],"operationId":"auto_get_api_v1_accounts_account_id_whatsapp_currency","summary":"Get currency","description":"Returns the currency identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Billing currency, migration eligibility and display currency.","content":{"application/json":{"schema":{"type":"object","properties":{"billing_currency":{"type":["string","null"],"example":"USD","description":"The WABA billing currency read from Meta (ISO 4217); null until it has been read — never presumed."},"coexistence":{"type":"boolean","example":false},"eligible_for_migration":{"type":"boolean","example":true},"ineligibility_reason":{"type":["string","null"],"example":"coexistence","enum":["coexistence","not_cloud",null],"description":"Null when eligible."},"migration_supported":{"type":"boolean","example":false,"description":"Automated billing-currency migration is not implemented; always false."},"official_url":{"type":"string","example":"https://developers.facebook.com/documentation/business-messaging/whatsapp/pricing"},"display_currency":{"type":"string","example":"BRL","description":"Operator-persisted display currency for FX-converted figures."}}},"example":{"billing_currency":"USD","coexistence":false,"eligible_for_migration":true,"ineligibility_reason":"coexistence","migration_supported":false,"official_url":"https://developers.facebook.com/documentation/business-messaging/whatsapp/pricing","display_currency":"BRL"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]},"patch":{"tags":["WhatsApp"],"operationId":"auto_patch_api_v1_accounts_account_id_whatsapp_currency","summary":"Update currency","description":"Updates the currency identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"display_currency":{"type":"string"}}},"example":{"display_currency":"sample display currency"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"currency":{"type":"string"}}},"example":{"currency":"BRL"}}}}},"put":{"tags":["WhatsApp"],"operationId":"auto_put_api_v1_accounts_account_id_whatsapp_currency","summary":"Update currency","description":"Updates the currency identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"display_currency":{"type":"string"}}},"example":{"display_currency":"sample display currency"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"currency":{"type":"string"}}},"example":{"currency":"BRL"}}}}}},"/api/v1/accounts/{account_id}/whatsapp/currency_migration":{"get":{"tags":["WhatsApp"],"operationId":"auto_get_api_v1_accounts_account_id_whatsapp_currency_migration","summary":"Get currency migration","description":"Returns the currency migration identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Migration eligibility and (optionally) a polled migration status.","content":{"application/json":{"schema":{"type":"object","properties":{"eligible":{"type":"boolean","example":true},"ineligibility_reason":{"type":["string","null"],"example":"coexistence","enum":["not_cloud","coexistence",null]},"billing_currency":{"type":["string","null"],"example":"USD","description":"The WABA billing currency read from Meta (ISO 4217); null until it has been read — never presumed."},"migration":{"type":["object","null"],"additionalProperties":true,"description":"Raw Meta migration object (passthrough of GET /{MIGRATION_ID}). Present only when the migration_id query param is supplied. Shape is UNVERIFIED (Meta Currency Migration API, no local capture).","example":{"id":"987654321","migration_status":"in_progress"}}}},"example":{"eligible":true,"ineligibility_reason":"coexistence","billing_currency":"USD","migration":{"id":"987654321","migration_status":"in_progress"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"migration_id","in":"query","required":false,"description":"Follow one previously started migration: its live status is added to the response. Omitted, only the account's current currency state is returned.","schema":{"type":"string"},"example":"mig_8f21c0"}]},"patch":{"tags":["WhatsApp"],"operationId":"auto_patch_api_v1_accounts_account_id_whatsapp_currency_migration","summary":"Update currency migration","description":"Updates the currency migration identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Phase 2 resume - numbers moved, inbox re-pointed to the new WABA.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"destination_waba":{"type":"object","additionalProperties":true,"properties":{"id":{"type":"string","example":"110220330440551","description":"New WABA id (inbox is re-pointed to it)."},"currency":{"type":"string","example":"BRL"},"message_template_namespace":{"type":["string","null"],"example":"a1b2c3_namespace"}},"description":"New WABA the phone numbers were moved to."}},"description":"Raw Meta response of POST /{MIGRATION_ID}/resume_migration (Phase 2). Passthrough - shape UNVERIFIED (Meta Currency Migration API, no local capture)."},"example":{"destination_waba":{"id":"110220330440551","currency":"BRL","message_template_namespace":"a1b2c3_namespace"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"migration_id":{"type":"integer"}}},"example":{"migration_id":1}}}}},"put":{"tags":["WhatsApp"],"operationId":"auto_put_api_v1_accounts_account_id_whatsapp_currency_migration","summary":"Update currency migration","description":"Updates the currency migration identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Phase 2 resume - numbers moved, inbox re-pointed to the new WABA.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"destination_waba":{"type":"object","additionalProperties":true,"properties":{"id":{"type":"string","example":"110220330440551","description":"New WABA id (inbox is re-pointed to it)."},"currency":{"type":"string","example":"BRL"},"message_template_namespace":{"type":["string","null"],"example":"a1b2c3_namespace"}},"description":"New WABA the phone numbers were moved to."}},"description":"Raw Meta response of POST /{MIGRATION_ID}/resume_migration (Phase 2). Passthrough - shape UNVERIFIED (Meta Currency Migration API, no local capture)."},"example":{"destination_waba":{"id":"110220330440551","currency":"BRL","message_template_namespace":"a1b2c3_namespace"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"migration_id":{"type":"integer"}}},"example":{"migration_id":1}}}}},"post":{"tags":["WhatsApp"],"operationId":"auto_post_api_v1_accounts_account_id_whatsapp_currency_migration","summary":"Create currency migration","description":"Creates a new currency migration from the request payload. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Phase 1 initiate - WABA clone started.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"migration_id":{"type":"string","example":"987654321","description":"Meta migration id for Phase 2 / polling."},"migration_status":{"type":"string","example":"pending"}},"description":"Raw Meta response of POST /{WABA_ID}/set_payment_method_migration_intent (Phase 1). Passthrough - documented keys per Meta docs; shape UNVERIFIED (no local capture)."},"example":{"migration_id":"987654321","migration_status":"pending"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"currency":{"type":"string"},"extended_credit_id":{"type":"integer"}}},"example":{"currency":"BRL","extended_credit_id":1}}}}}},"/api/v1/accounts/{account_id}/whatsapp/call_settings":{"get":{"tags":["WhatsApp"],"operationId":"auto_get_api_v1_accounts_account_id_whatsapp_call_settings","summary":"Get call settings","description":"Returns the call setting identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"calling":{"type":"string"}}},"example":{"calling":"sample calling"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]},"patch":{"tags":["WhatsApp"],"operationId":"auto_patch_api_v1_accounts_account_id_whatsapp_call_settings","summary":"Update call settings","description":"Updates the call setting identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"calling":{"type":"string"}}},"example":{"calling":"sample calling"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"calling":{"type":"object","additionalProperties":true,"description":"Free-form object."}}},"example":{"calling":{}}}}}},"put":{"tags":["WhatsApp"],"operationId":"auto_put_api_v1_accounts_account_id_whatsapp_call_settings","summary":"Update call settings","description":"Updates the call setting identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"calling":{"type":"string"}}},"example":{"calling":"sample calling"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"calling":{"type":"object","additionalProperties":true,"description":"Free-form object."}}},"example":{"calling":{}}}}}}},"/api/v1/accounts/{account_id}/whatsapp/cost_center/summary":{"get":{"tags":["WhatsApp"],"operationId":"auto_get_api_v1_accounts_account_id_whatsapp_cost_center_summary","summary":"Summarize WhatsApp message costs","description":"Totals, daily series by category, groups and the reconciliation with Meta's pricing analytics for the billing channels of the caller's operational scope. Grouping by day, inbox or category reads the daily rollup (window up to 366 days); grouping by campaign, sender or conversation reads the ledger (window up to 90 days, at most 500 groups). Native currencies are never added together: every money field is in `amounts_currency`. Requires the `whatsapp_cost_center` feature and the cost-view permission.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Cost summary of the window.","content":{"application/json":{"schema":{"type":"object","properties":{"period":{"type":"object","description":"The reported window of billing days, in the WABA time zone.","properties":{"from":{"type":"string","format":"date"},"to":{"type":"string","format":"date"},"clamped":{"type":"boolean","description":"True when the requested window exceeded the maximum and was shortened to end on `to`."}}},"group_by":{"type":"string","enum":["day","inbox","category","campaign","sender","conversation"]},"display_currency":{"type":["string","null"],"description":"Requested ISO 4217 display currency."},"amounts_currency":{"type":["string","null"],"description":"Currency of every money field — the display currency when every native amount could be converted, the single native currency otherwise, or null when the report mixes currencies that cannot be converted (then only `native_totals_by_currency` carries amounts)."},"fx":{"type":["object","null"],"description":"Conversion applied to the money fields, or null when no conversion was needed (every native amount is already in `amounts_currency`) or when it was unavailable (`fx_unavailable` true).","properties":{"rate":{"type":["number","null"],"description":"The single conversion rate, or null when more than one native currency was converted (see `rates`)."},"source":{"type":"string","enum":["live","fallback"],"description":"`live` when every rate came from the live FX provider; `fallback` when any used the stored fallback rate."},"as_of":{"type":"string","format":"date-time","description":"When the rates were resolved (UTC)."},"to":{"type":["string","null"],"description":"ISO 4217 currency the amounts were converted into."},"rates":{"type":"object","description":"Rate applied per native ISO 4217 currency code (1 native unit = rate display units).","additionalProperties":{"type":"number"}}}},"fx_unavailable":{"type":"boolean","description":"True when a native amount could not be converted into the display currency."},"native_totals_by_currency":{"type":"object","description":"Native amounts per ISO 4217 billing currency (`unknown` when the WABA currency was never read), never converted and never added across currencies — `billable` counts as cost, `pending` is the provisional amount still awaiting delivery.","additionalProperties":{"type":"object","properties":{"billable":{"type":"number"},"pending":{"type":"number"}}}},"currencies":{"type":"array","description":"Native billing currencies present in the window (`unknown` when never read).","items":{"type":"string"}},"totals":{"type":"object","properties":{"billable":{"type":"object","description":"A message count and its amount in `amounts_currency` (null when the amount cannot be expressed in one currency).","properties":{"count":{"type":"integer"},"amount":{"type":["number","null"]}}},"pending_delivery":{"type":"object","description":"A message count and its amount in `amounts_currency` (null when the amount cannot be expressed in one currency).","properties":{"count":{"type":"integer"},"amount":{"type":["number","null"]}}},"free":{"type":"object","description":"A message count; these messages never carry an amount.","properties":{"count":{"type":"integer"}}},"not_billed":{"type":"object","description":"Messages that were not billed — `failed` (the send failed) and `expired` (no final status within 30 days).","properties":{"count":{"type":"integer"},"failed":{"type":"integer"},"expired":{"type":"integer"}}},"unverified":{"type":"object","description":"Messages whose pricing could not be confirmed (unknown pricing shape, unresolved market or missing tariff). `historical_estimate` counts how many of them are after-the-fact estimates, never confirmed charges.","properties":{"count":{"type":"integer"},"historical_estimate":{"type":"integer"}}}}},"amount_sources":{"type":"array","description":"Every pricing source used by the billable messages, sorted.","items":{"type":"string","enum":["list_rate","tier_estimated","override","meta_reported"]}},"partner_billed":{"type":"boolean","description":"True when any number in scope is billed by a Solution Partner, so Meta reports volume but no cost for it."},"historical_estimate":{"type":"object","description":"Messages priced after the fact from the rate card of the day; an estimate, never a confirmed charge.","properties":{"count":{"type":"integer"},"estimated_amount":{"type":["number","null"]},"evidence":{"type":"string","enum":["historical_estimate"]}}},"series":{"type":"array","description":"One entry per billing day of the window with the billable messages of that day by category.","items":{"type":"object","properties":{"day":{"type":"string","format":"date"},"by_category":{"type":"object","description":"Billable messages per pricing category (`marketing`, `utility`, `authentication`, `service`; `unknown` when the entry carries none), each with its count and amount in `amounts_currency`.","additionalProperties":{"type":"object","properties":{"count":{"type":"integer"},"amount":{"type":["number","null"]}}}}}}},"groups":{"type":"array","description":"Groups sorted by billable amount then count. The identity fields depend on `group_by` — `inbox` adds `channel_id` and `reconciled_at`; `campaign` adds `display_id`, `inbox_id`, `frozen_estimate_amount`, `frozen_estimate_by_currency`, `whatsapp_transport` and `campaign_status`; `sender` adds `sender`; `conversation` adds `conversation_id`.","items":{"type":"object","properties":{"key":{"type":["integer","string","null"],"description":"Group key — inbox id, campaign id, conversation display id, ISO date, category or `\u003ctype\u003e:\u003cid\u003e` for a sender."},"label":{"type":["string","null"]},"sublabel":{"type":["string","null"]},"count":{"type":"integer","description":"Every ledger message of the group, whatever its state."},"billable":{"type":"object","description":"A message count and its amount in `amounts_currency` (null when the amount cannot be expressed in one currency).","properties":{"count":{"type":"integer"},"amount":{"type":["number","null"]}}},"pending_delivery":{"type":"object","description":"A message count and its amount in `amounts_currency` (null when the amount cannot be expressed in one currency).","properties":{"count":{"type":"integer"},"amount":{"type":["number","null"]}}},"free":{"type":"object","description":"A message count; these messages never carry an amount.","properties":{"count":{"type":"integer"}}},"not_billed":{"type":"object","description":"Messages that were not billed — `failed` (the send failed) and `expired` (no final status within 30 days).","properties":{"count":{"type":"integer"},"failed":{"type":"integer"},"expired":{"type":"integer"}}},"unverified":{"type":"object","description":"A message count; these messages never carry an amount.","properties":{"count":{"type":"integer"}}},"by_category":{"type":"object","description":"Billable messages per pricing category (`marketing`, `utility`, `authentication`, `service`; `unknown` when the entry carries none), each with its count and amount in `amounts_currency`.","additionalProperties":{"type":"object","properties":{"count":{"type":"integer"},"amount":{"type":["number","null"]}}}},"amount_source":{"type":["string","null"],"enum":["list_rate","tier_estimated","override","meta_reported",null],"description":"How the amount was priced — `list_rate` (the official rate card), `tier_estimated` (a volume tier estimated by the platform), `override` (the account's own tariff) or `meta_reported` (the cost Meta reported with a max-price marketing delivery). Null when there is no priced amount."},"amount_sources":{"type":"array","description":"Every pricing source used by the billable messages, sorted.","items":{"type":"string","enum":["list_rate","tier_estimated","override","meta_reported"]}},"partner_billed":{"type":"boolean"},"currency":{"type":["string","null"],"description":"The native currency when the group has a single one."},"top_market":{"type":["string","null"],"description":"Meta pricing market with the most messages in the group."},"channel_id":{"type":["integer","null"]},"reconciled_at":{"type":["string","null"],"format":"date-time","description":"Last time Meta's pricing analytics were synced for this inbox."},"display_id":{"type":["integer","null"]},"inbox_id":{"type":["integer","null"]},"frozen_estimate_amount":{"type":["number","null"],"description":"The price frozen on the recipients at dispatch, in `amounts_currency`."},"frozen_estimate_by_currency":{"type":"object","description":"The frozen dispatch price per native ISO 4217 currency.","additionalProperties":{"type":"number"}},"whatsapp_transport":{"type":"string","enum":["cloud","web"],"description":"Transport of the campaign inbox; a WhatsApp Web campaign is not billed by Meta."},"campaign_status":{"type":"string","enum":["active","completed","draft","scheduled","sending","paused","failed","processing"]},"sender":{"type":["object","null"],"properties":{"type":{"type":"string","description":"Sender record type (for example `User` or `AgentBot`)."},"id":{"type":"integer"},"name":{"type":["string","null"]}}},"conversation_id":{"type":["integer","null"],"description":"Conversation display id."}}}},"groups_truncated":{"type":"boolean","description":"True when a ledger grouping had more than 500 groups and only the first 500 are returned."},"reconciliation":{"type":"object","description":"Ledger versus Meta's pricing analytics, for information only — the difference never corrects the ledger. Cost is compared only where Meta reports it.","properties":{"meta_volume":{"type":"integer"},"ledger_volume":{"type":"integer","description":"Billable plus free ledger messages."},"volume_difference":{"type":["integer","null"]},"meta_cost":{"type":["number","null"]},"ledger_billable_amount":{"type":["number","null"]},"difference":{"type":["number","null"]},"synced_at":{"type":["string","null"],"format":"date-time"},"partner_billed":{"type":"boolean"},"unavailable_reason":{"type":["string","null"],"enum":["not_supported","partner_billed","no_snapshots",null],"description":"Why the cost comparison is missing — no Cloud number in scope, every number partner-billed, or nothing synced yet."},"free_tier":{"type":["object","null"],"description":"Service messages inside the numbers' monthly free tier, Meta (pricing analytics SERVICE + FREE_CUSTOMER_SERVICE, from 2026-10-01) versus the ledger (`free_tier`). Null before 2026-10-01 or without synced analytics.","properties":{"meta_volume":{"type":"integer"},"ledger_volume":{"type":"integer"},"difference":{"type":"integer"}}}}}}},"example":{"period":{"from":"2026-10-01","to":"2026-10-31","clamped":false},"group_by":"campaign","display_currency":"BRL","amounts_currency":"BRL","fx":{"rate":5.0,"source":"live","as_of":"2026-10-20T12:00:00Z","to":"BRL","rates":{"USD":5.0}},"fx_unavailable":false,"native_totals_by_currency":{"USD":{"billable":0.0068,"pending":0.0}},"currencies":["USD"],"totals":{"billable":{"count":1,"amount":0.034},"pending_delivery":{"count":0,"amount":0.0},"free":{"count":1},"not_billed":{"count":0,"failed":0,"expired":0},"unverified":{"count":0,"historical_estimate":0}},"amount_sources":["list_rate"],"partner_billed":false,"historical_estimate":{"count":0,"estimated_amount":0,"evidence":"historical_estimate"},"series":[{"day":"2026-10-01","by_category":{}},{"day":"2026-10-02","by_category":{"utility":{"count":1,"amount":0.034}}}],"groups":[{"key":31,"label":"Aviso de entrega","sublabel":"Atendimento","count":1,"billable":{"count":1,"amount":0.034},"pending_delivery":{"count":0,"amount":0.0},"free":{"count":0},"not_billed":{"count":0,"failed":0,"expired":0},"unverified":{"count":0},"by_category":{"utility":{"count":1,"amount":0.034}},"amount_source":"list_rate","amount_sources":["list_rate"],"partner_billed":false,"currency":"USD","top_market":"Brazil","channel_id":null,"reconciled_at":null,"display_id":4,"inbox_id":42,"frozen_estimate_amount":0.034,"frozen_estimate_by_currency":{"USD":0.0068},"whatsapp_transport":"cloud","campaign_status":"completed","sender":null,"conversation_id":null}],"groups_truncated":false,"reconciliation":{"meta_volume":2,"ledger_volume":2,"volume_difference":0,"meta_cost":0.034,"ledger_billable_amount":0.034,"difference":0.0,"synced_at":"2026-10-20T12:00:00Z","partner_billed":false,"unavailable_reason":null,"free_tier":{"meta_volume":1,"ledger_volume":1,"difference":0}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"The `whatsapp_cost_center` feature is off for the account (empty body), or the `inbox_id` is outside the caller's operational scope.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Present only for a record outside the scope."}}},"example":{"error":"Resource could not be found"}}}},"403":{"description":"The caller may not read (or, for writes, manage) WhatsApp costs.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["forbidden"]}}},"example":{"error":"forbidden"}}}},"422":{"description":"The `inbox_id` has no billing channel (it is neither Cloud, 360dialog nor the Web leg of a paired number).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["not_a_cloud_inbox"]}}},"example":{"error":"not_a_cloud_inbox"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"inbox_id","in":"query","required":false,"description":"Restrict the report to one inbox of the caller's operational scope. A WhatsApp Web inbox of a paired number reports through its Cloud sibling.","schema":{"type":"integer"},"example":42},{"name":"from","in":"query","required":false,"description":"First billing day (ISO 8601 date, WABA time zone). Defaults to the first day of the month of `to`.","schema":{"type":"string","format":"date"},"example":"2026-10-01"},{"name":"to","in":"query","required":false,"description":"Last billing day (ISO 8601 date, WABA time zone). Defaults to today in the WABA time zone.","schema":{"type":"string","format":"date"},"example":"2026-10-31"},{"name":"group_by","in":"query","required":false,"description":"Grouping of `groups[]`. An unknown value falls back to `inbox`.","schema":{"type":"string","enum":["day","inbox","category","campaign","sender","conversation"],"default":"inbox"},"example":"inbox"},{"name":"currency","in":"query","required":false,"description":"ISO 4217 display currency the amounts are converted into. Defaults to the account display currency.","schema":{"type":"string","pattern":"^[A-Za-z]{3}$"},"example":"BRL"},{"name":"category","in":"query","required":false,"description":"Restrict to one pricing category. An unknown value is ignored.","schema":{"type":"string","enum":["marketing","utility","authentication","service"]},"example":"marketing"}]}},"/api/v1/accounts/{account_id}/whatsapp/cost_center/usage":{"get":{"tags":["WhatsApp"],"operationId":"auto_get_api_v1_accounts_account_id_whatsapp_cost_center_usage","summary":"Report WhatsApp usage for a billing month","description":"The usage of one WABA billing month, for the whole scope and per number (`by_inbox[]`): free messages by reason, the service messages of the month (`service`), billable messages by category with their unit price, the pricing regime in force and each number's estimated monthly service allowance. Its limit is not published by Meta in the documentation tracked here; read `allowance.evidence`. `resets_at` is the server's estimated month boundary in the WABA time zone, not an officially documented allowance reset. `free.\u003creason\u003e` is present (0 when nothing happened) for every reason that applies to the number and absent when it does not apply. `allowance.shown` is always present; the estimate uses reported deliveries and never changes an amount. Requires the `whatsapp_cost_center` feature and the cost-view permission.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Usage of the billing month.","content":{"application/json":{"schema":{"type":"object","properties":{"month":{"type":"string","description":"Reported billing month (`YYYY-MM`)."},"current_month":{"type":"string","description":"The current billing month in the WABA time zone (`YYYY-MM`)."},"resets_at":{"type":"string","format":"date-time","description":"When the billing month ends (UTC instant of the next month's midnight in the WABA offset)."},"utc_offset":{"type":"string","description":"WABA offset used for the month (`+00:00` when unknown)."},"utc_offset_known":{"type":"boolean"},"currency":{"type":["string","null"],"description":"The single native billing currency, or null when several (or none) are present."},"currencies":{"type":"array","items":{"type":"string"}},"display_currency":{"type":["string","null"]},"amounts_currency":{"type":["string","null"],"description":"Currency of every money field, resolved as in the summary operation."},"fx":{"type":["object","null"],"description":"Conversion applied to the money fields, or null when no conversion was needed (every native amount is already in `amounts_currency`) or when it was unavailable (`fx_unavailable` true).","properties":{"rate":{"type":["number","null"],"description":"The single conversion rate, or null when more than one native currency was converted (see `rates`)."},"source":{"type":"string","enum":["live","fallback"],"description":"`live` when every rate came from the live FX provider; `fallback` when any used the stored fallback rate."},"as_of":{"type":"string","format":"date-time","description":"When the rates were resolved (UTC)."},"to":{"type":["string","null"],"description":"ISO 4217 currency the amounts were converted into."},"rates":{"type":"object","description":"Rate applied per native ISO 4217 currency code (1 native unit = rate display units).","additionalProperties":{"type":"number"}}}},"fx_unavailable":{"type":"boolean"},"native_totals_by_currency":{"type":"object","description":"Native amounts per ISO 4217 billing currency (`unknown` when the WABA currency was never read), never converted and never added across currencies — `billable` counts as cost, `pending` is the provisional amount still awaiting delivery.","additionalProperties":{"type":"object","properties":{"billable":{"type":"number"},"pending":{"type":"number"}}}},"partner_billed":{"type":"boolean"},"has_cloud_inbox":{"type":"boolean","description":"False when the scope has no billing channel at all."},"regime":{"type":"object","description":"The pricing regime, decided by the server in the WABA time zone.","properties":{"service_billable_from":{"type":"string","format":"date"},"utility_in_window_billable_from":{"type":"string","format":"date"},"as_of":{"type":"string","enum":["service_billable","service_free"],"description":"Regime on `evaluated_on`."},"evaluated_on":{"type":"string","format":"date"}}},"totals":{"type":"object","properties":{"free":{"type":"object","description":"A message count; these messages never carry an amount.","properties":{"count":{"type":"integer"}}},"billable":{"type":"object","description":"A message count and its amount in `amounts_currency` (null when the amount cannot be expressed in one currency).","properties":{"count":{"type":"integer"},"amount":{"type":["number","null"]}}},"pending_delivery":{"type":"object","description":"A message count and its amount in `amounts_currency` (null when the amount cannot be expressed in one currency).","properties":{"count":{"type":"integer"},"amount":{"type":["number","null"]}}},"not_billed":{"type":"object","description":"Messages that were not billed — `failed` (the send failed) and `expired` (no final status within 30 days).","properties":{"count":{"type":"integer"},"failed":{"type":"integer"},"expired":{"type":"integer"}}},"unverified":{"type":"object","description":"Messages whose pricing could not be confirmed (unknown pricing shape, unresolved market or missing tariff). `historical_estimate` counts how many of them are after-the-fact estimates, never confirmed charges.","properties":{"count":{"type":"integer"},"historical_estimate":{"type":"integer"}}}}},"free":{"type":"object","description":"Free messages by reason; only the reasons that apply to the numbers are present.","properties":{"free_tier":{"type":"integer","description":"Service messages inside the monthly free tier (months from 2026-10)."},"free_customer_service":{"type":"integer","description":"Messages free inside the 24-hour customer service window (months until 2026-09)."},"free_entry_point":{"type":"integer"},"business_app":{"type":"integer","description":"Present for a Coexistence number (or when the ledger has such entries)."},"web_transport":{"type":"integer","description":"Present for a paired Cloud + WhatsApp Web number (or when the ledger has such entries)."}}},"billable":{"type":"object","description":"Billable messages of each pricing category (all four keys are always present).","additionalProperties":{"type":"object","properties":{"count":{"type":"integer"},"amount":{"type":["number","null"]},"unit_price":{"type":["number","null"],"description":"Unit price in `amounts_currency` recorded on the entries (or today's tariff when none yet); never amount divided by count."},"unit_price_varies":{"type":"boolean","description":"True when the entries of the month were priced at more than one unit price; `unit_price` is then the most used."},"native_unit_price":{"type":["number","null"]},"native_currency":{"type":["string","null"]},"amount_source":{"type":["string","null"],"enum":["list_rate","tier_estimated","override","meta_reported",null],"description":"How the amount was priced — `list_rate` (the official rate card), `tier_estimated` (a volume tier estimated by the platform), `override` (the account's own tariff) or `meta_reported` (the cost Meta reported with a max-price marketing delivery). Null when there is no priced amount."},"amount_sources":{"type":"array","description":"Every pricing source used by the billable messages, sorted.","items":{"type":"string","enum":["list_rate","tier_estimated","override","meta_reported"]}}}}},"pending_delivery":{"type":"object","description":"A message count and its amount in `amounts_currency` (null when the amount cannot be expressed in one currency).","properties":{"count":{"type":"integer"},"amount":{"type":["number","null"]}}},"not_billed":{"type":"object","properties":{"failed":{"type":"integer"},"expired":{"type":"integer"}}},"unverified":{"type":"object","description":"Messages whose pricing could not be confirmed (unknown pricing shape, unresolved market or missing tariff). `historical_estimate` counts how many of them are after-the-fact estimates, never confirmed charges.","properties":{"count":{"type":"integer"},"historical_estimate":{"type":"integer"}}},"service":{"type":"object","description":"The SERVICE messages of the month, split by why they were (not) charged.","properties":{"billed":{"type":"integer","description":"Service messages Meta charged (after the free tier)."},"free_tier":{"type":"integer","description":"Service messages inside the monthly free tier."},"free_in_window":{"type":"integer","description":"Service messages free inside the 24-hour window (until 2026-09-30)."},"free_entry_point":{"type":"integer","description":"Service messages free inside an ad free entry point window."},"free_tier_applies":{"type":"boolean","description":"Whether the month has the free tier (months from 2026-10)."}}},"allowance":{"type":"object","description":"Each number's estimated monthly service allowance. Meta does not publish an allowance limit in the documentation tracked here; read `allowance.evidence`. `used` and exhaustion describe the estimator's classification of reported deliveries, not a confirmed entitlement. Shown by default; only `shown` and `applicable` travel when the account hid it or the month has no estimated allowance. The estimated month follows the WABA time zone, which Meta does not document (`month_boundary_evidence: unverified`).","properties":{"shown":{"type":"boolean"},"applicable":{"type":"boolean","description":"Whether the month has the free tier (months from 2026-10)."},"evidence":{"type":"string","enum":["unverified"]},"month_boundary_evidence":{"type":"string","enum":["unverified"]},"per_number":{"type":"integer"},"numbers":{"type":"array","items":{"type":"object","properties":{"channel_id":{"type":"integer"},"inbox_id":{"type":["integer","null"]},"label":{"type":["string","null"]},"phone_number":{"type":"string"},"evidence":{"type":"string","enum":["unverified"]},"month_boundary_evidence":{"type":"string","enum":["unverified"]},"applicable":{"type":"boolean"},"per_number":{"type":"integer"},"service_messages":{"type":"integer","description":"Service messages Meta delivered this month (inside the tier + charged)."},"used":{"type":"integer","description":"Deliveries inside the free tier (capped at `per_number`)."},"charged":{"type":"integer","description":"Service messages Meta charged this month."},"remaining":{"type":"integer"},"exhausted_at":{"type":["string","null"],"format":"date"},"next_unit_price":{"type":["number","null"],"description":"Native price of the next service message."},"currency":{"type":["string","null"]},"display_next_unit_price":{"type":["number","null"]},"amounts_currency":{"type":["string","null"]}}}}}},"by_inbox":{"type":"array","description":"The same blocks for each billing channel of the scope.","items":{"type":"object","properties":{"inbox_id":{"type":["integer","null"]},"channel_id":{"type":"integer"},"label":{"type":["string","null"]},"phone_number":{"type":"string"},"provider":{"type":"string","enum":["whatsapp_cloud","default"],"description":"`whatsapp_cloud` (Meta Cloud API, including Coexistence) or `default` (360dialog)."},"coexistence":{"type":"boolean"},"currency":{"type":["string","null"]},"partner_billed":{"type":"boolean"},"resets_at":{"type":"string","format":"date-time"},"utc_offset":{"type":"string"},"utc_offset_known":{"type":"boolean"},"amounts_currency":{"type":["string","null"]},"fx":{"type":["object","null"],"description":"Conversion applied to the money fields, or null when no conversion was needed (every native amount is already in `amounts_currency`) or when it was unavailable (`fx_unavailable` true).","properties":{"rate":{"type":["number","null"],"description":"The single conversion rate, or null when more than one native currency was converted (see `rates`)."},"source":{"type":"string","enum":["live","fallback"],"description":"`live` when every rate came from the live FX provider; `fallback` when any used the stored fallback rate."},"as_of":{"type":"string","format":"date-time","description":"When the rates were resolved (UTC)."},"to":{"type":["string","null"],"description":"ISO 4217 currency the amounts were converted into."},"rates":{"type":"object","description":"Rate applied per native ISO 4217 currency code (1 native unit = rate display units).","additionalProperties":{"type":"number"}}}},"fx_unavailable":{"type":"boolean"},"totals":{"type":"object","properties":{"free":{"type":"object","description":"A message count; these messages never carry an amount.","properties":{"count":{"type":"integer"}}},"billable":{"type":"object","description":"A message count and its amount in `amounts_currency` (null when the amount cannot be expressed in one currency).","properties":{"count":{"type":"integer"},"amount":{"type":["number","null"]}}},"pending_delivery":{"type":"object","description":"A message count and its amount in `amounts_currency` (null when the amount cannot be expressed in one currency).","properties":{"count":{"type":"integer"},"amount":{"type":["number","null"]}}},"not_billed":{"type":"object","description":"Messages that were not billed — `failed` (the send failed) and `expired` (no final status within 30 days).","properties":{"count":{"type":"integer"},"failed":{"type":"integer"},"expired":{"type":"integer"}}},"unverified":{"type":"object","description":"Messages whose pricing could not be confirmed (unknown pricing shape, unresolved market or missing tariff). `historical_estimate` counts how many of them are after-the-fact estimates, never confirmed charges.","properties":{"count":{"type":"integer"},"historical_estimate":{"type":"integer"}}}}},"free":{"type":"object","description":"Free messages by reason; only the reasons that apply to the numbers are present.","properties":{"free_tier":{"type":"integer","description":"Service messages inside the monthly free tier (months from 2026-10)."},"free_customer_service":{"type":"integer","description":"Messages free inside the 24-hour customer service window (months until 2026-09)."},"free_entry_point":{"type":"integer"},"business_app":{"type":"integer","description":"Present for a Coexistence number (or when the ledger has such entries)."},"web_transport":{"type":"integer","description":"Present for a paired Cloud + WhatsApp Web number (or when the ledger has such entries)."}}},"billable":{"type":"object","description":"Billable messages of each pricing category (all four keys are always present).","additionalProperties":{"type":"object","properties":{"count":{"type":"integer"},"amount":{"type":["number","null"]},"unit_price":{"type":["number","null"],"description":"Unit price in `amounts_currency` recorded on the entries (or today's tariff when none yet); never amount divided by count."},"unit_price_varies":{"type":"boolean","description":"True when the entries of the month were priced at more than one unit price; `unit_price` is then the most used."},"native_unit_price":{"type":["number","null"]},"native_currency":{"type":["string","null"]},"amount_source":{"type":["string","null"],"enum":["list_rate","tier_estimated","override","meta_reported",null],"description":"How the amount was priced — `list_rate` (the official rate card), `tier_estimated` (a volume tier estimated by the platform), `override` (the account's own tariff) or `meta_reported` (the cost Meta reported with a max-price marketing delivery). Null when there is no priced amount."},"amount_sources":{"type":"array","description":"Every pricing source used by the billable messages, sorted.","items":{"type":"string","enum":["list_rate","tier_estimated","override","meta_reported"]}}}}},"pending_delivery":{"type":"object","description":"A message count and its amount in `amounts_currency` (null when the amount cannot be expressed in one currency).","properties":{"count":{"type":"integer"},"amount":{"type":["number","null"]}}},"not_billed":{"type":"object","properties":{"failed":{"type":"integer"},"expired":{"type":"integer"}}},"unverified":{"type":"object","description":"Messages whose pricing could not be confirmed (unknown pricing shape, unresolved market or missing tariff). `historical_estimate` counts how many of them are after-the-fact estimates, never confirmed charges.","properties":{"count":{"type":"integer"},"historical_estimate":{"type":"integer"}}},"service":{"type":"object","description":"The SERVICE messages of the month, split by why they were (not) charged.","properties":{"billed":{"type":"integer","description":"Service messages Meta charged (after the free tier)."},"free_tier":{"type":"integer","description":"Service messages inside the monthly free tier."},"free_in_window":{"type":"integer","description":"Service messages free inside the 24-hour window (until 2026-09-30)."},"free_entry_point":{"type":"integer","description":"Service messages free inside an ad free entry point window."},"free_tier_applies":{"type":"boolean","description":"Whether the month has the free tier (months from 2026-10)."}}},"allowance":{"type":"object","description":"Each number's estimated monthly service allowance. Meta does not publish an allowance limit in the documentation tracked here; read `allowance.evidence`. `used` and exhaustion describe the estimator's classification of reported deliveries, not a confirmed entitlement. Shown by default; only `shown` and `applicable` travel when the account hid it or the month has no estimated allowance. The estimated month follows the WABA time zone, which Meta does not document (`month_boundary_evidence: unverified`).","properties":{"shown":{"type":"boolean"},"applicable":{"type":"boolean","description":"Whether the month has the free tier (months from 2026-10)."},"evidence":{"type":"string","enum":["unverified"]},"month_boundary_evidence":{"type":"string","enum":["unverified"]},"per_number":{"type":"integer"},"numbers":{"type":"array","items":{"type":"object","properties":{"channel_id":{"type":"integer"},"inbox_id":{"type":["integer","null"]},"label":{"type":["string","null"]},"phone_number":{"type":"string"},"evidence":{"type":"string","enum":["unverified"]},"month_boundary_evidence":{"type":"string","enum":["unverified"]},"applicable":{"type":"boolean"},"per_number":{"type":"integer"},"service_messages":{"type":"integer","description":"Service messages Meta delivered this month (inside the tier + charged)."},"used":{"type":"integer","description":"Deliveries inside the free tier (capped at `per_number`)."},"charged":{"type":"integer","description":"Service messages Meta charged this month."},"remaining":{"type":"integer"},"exhausted_at":{"type":["string","null"],"format":"date"},"next_unit_price":{"type":["number","null"],"description":"Native price of the next service message."},"currency":{"type":["string","null"]},"display_next_unit_price":{"type":["number","null"]},"amounts_currency":{"type":["string","null"]}}}}}}}}}}},"example":{"month":"2026-10","current_month":"2026-10","resets_at":"2026-11-01T03:00:00Z","utc_offset":"-03:00","utc_offset_known":true,"currency":"USD","currencies":["USD"],"display_currency":"USD","amounts_currency":"USD","fx":null,"fx_unavailable":false,"native_totals_by_currency":{"USD":{"billable":0.0068,"pending":0.0}},"partner_billed":false,"has_cloud_inbox":true,"regime":{"service_billable_from":"2026-10-01","utility_in_window_billable_from":"2026-10-01","as_of":"service_billable","evaluated_on":"2026-10-20"},"totals":{"free":{"count":1000},"billable":{"count":1,"amount":0.0068},"pending_delivery":{"count":0,"amount":0.0},"not_billed":{"count":0,"failed":0,"expired":0},"unverified":{"count":0,"historical_estimate":0}},"free":{"free_tier":1000,"free_customer_service":0,"free_entry_point":0,"business_app":1,"web_transport":1},"billable":{"marketing":{"count":0,"amount":0.0,"unit_price":null,"unit_price_varies":false,"native_unit_price":null,"native_currency":null,"amount_source":null,"amount_sources":[]},"utility":{"count":0,"amount":0.0,"unit_price":null,"unit_price_varies":false,"native_unit_price":null,"native_currency":null,"amount_source":null,"amount_sources":[]},"authentication":{"count":0,"amount":0.0,"unit_price":null,"unit_price_varies":false,"native_unit_price":null,"native_currency":null,"amount_source":null,"amount_sources":[]},"service":{"count":1,"amount":0.0068,"unit_price":0.0068,"unit_price_varies":false,"native_unit_price":0.0068,"native_currency":"USD","amount_source":"list_rate","amount_sources":["list_rate"]}},"service":{"billed":1,"free_tier":1000,"free_in_window":0,"free_entry_point":0,"free_tier_applies":true},"pending_delivery":{"count":0,"amount":0.0},"not_billed":{"failed":0,"expired":0},"unverified":{"count":0,"historical_estimate":0},"allowance":{"shown":true,"applicable":true,"evidence":"unverified","month_boundary_evidence":"unverified","per_number":1000,"numbers":[{"channel_id":17,"inbox_id":42,"label":"Atendimento","phone_number":"5511999990000","evidence":"unverified","month_boundary_evidence":"unverified","applicable":true,"per_number":1000,"service_messages":1001,"used":1000,"charged":1,"remaining":0,"exhausted_at":"2026-10-20","next_unit_price":0.0068,"currency":"USD","display_next_unit_price":0.0068,"amounts_currency":"USD"}]},"by_inbox":[{"inbox_id":42,"channel_id":17,"label":"Atendimento","phone_number":"5511999990000","provider":"whatsapp_cloud","coexistence":false,"currency":"USD","partner_billed":false,"resets_at":"2026-11-01T03:00:00Z","utc_offset":"-03:00","utc_offset_known":true,"amounts_currency":"USD","fx":null,"fx_unavailable":false,"totals":{"free":{"count":1000},"billable":{"count":1,"amount":0.0068},"pending_delivery":{"count":0,"amount":0.0},"not_billed":{"count":0,"failed":0,"expired":0},"unverified":{"count":0,"historical_estimate":0}},"free":{"free_tier":1000,"free_customer_service":0,"free_entry_point":0,"business_app":1,"web_transport":1},"billable":{"marketing":{"count":0,"amount":0.0,"unit_price":null,"unit_price_varies":false,"native_unit_price":null,"native_currency":null,"amount_source":null,"amount_sources":[]},"utility":{"count":0,"amount":0.0,"unit_price":null,"unit_price_varies":false,"native_unit_price":null,"native_currency":null,"amount_source":null,"amount_sources":[]},"authentication":{"count":0,"amount":0.0,"unit_price":null,"unit_price_varies":false,"native_unit_price":null,"native_currency":null,"amount_source":null,"amount_sources":[]},"service":{"count":1,"amount":0.0068,"unit_price":0.0068,"unit_price_varies":false,"native_unit_price":0.0068,"native_currency":"USD","amount_source":"list_rate","amount_sources":["list_rate"]}},"service":{"billed":1,"free_tier":1000,"free_in_window":0,"free_entry_point":0,"free_tier_applies":true},"pending_delivery":{"count":0,"amount":0.0},"not_billed":{"failed":0,"expired":0},"unverified":{"count":0,"historical_estimate":0},"allowance":{"shown":true,"applicable":true,"evidence":"unverified","month_boundary_evidence":"unverified","per_number":1000,"numbers":[{"channel_id":17,"inbox_id":42,"label":"Atendimento","phone_number":"5511999990000","evidence":"unverified","month_boundary_evidence":"unverified","applicable":true,"per_number":1000,"service_messages":1001,"used":1000,"charged":1,"remaining":0,"exhausted_at":"2026-10-20","next_unit_price":0.0068,"currency":"USD","display_next_unit_price":0.0068,"amounts_currency":"USD"}]}}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"The `whatsapp_cost_center` feature is off for the account (empty body), or the `inbox_id` is outside the caller's operational scope.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Present only for a record outside the scope."}}},"example":{"error":"Resource could not be found"}}}},"403":{"description":"The caller may not read (or, for writes, manage) WhatsApp costs.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["forbidden"]}}},"example":{"error":"forbidden"}}}},"422":{"description":"The `inbox_id` has no billing channel (it is neither Cloud, 360dialog nor the Web leg of a paired number).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["not_a_cloud_inbox"]}}},"example":{"error":"not_a_cloud_inbox"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"inbox_id","in":"query","required":false,"description":"Restrict the report to one inbox of the caller's operational scope. A WhatsApp Web inbox of a paired number reports through its Cloud sibling.","schema":{"type":"integer"},"example":42},{"name":"month","in":"query","required":false,"description":"Billing month as `YYYY-MM`. A future or malformed month falls back to the current one.","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}$"},"example":"2026-10"},{"name":"currency","in":"query","required":false,"description":"ISO 4217 display currency the amounts are converted into. Defaults to the account display currency.","schema":{"type":"string","pattern":"^[A-Za-z]{3}$"},"example":"BRL"}]}},"/api/v1/accounts/{account_id}/whatsapp/cost_center/entries":{"get":{"tags":["WhatsApp"],"operationId":"auto_get_api_v1_accounts_account_id_whatsapp_cost_center_entries","summary":"List WhatsApp message cost entries","description":"Paginated ledger entries (one per message), most recent billing day first, inside a window of at most 90 days. Each entry keeps its native amount and currency, plus `display_amount` when convertible. Only known filter values filter; an unknown value is ignored. Requires the `whatsapp_cost_center` feature and the cost-view permission.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"One page of ledger entries.","content":{"application/json":{"schema":{"type":"object","properties":{"period":{"type":"object","description":"The reported window of billing days, in the WABA time zone.","properties":{"from":{"type":"string","format":"date"},"to":{"type":"string","format":"date"},"clamped":{"type":"boolean","description":"True when the requested window exceeded the maximum and was shortened to end on `to`."}}},"amounts_currency":{"type":["string","null"],"description":"Currency of `display_amount`."},"fx":{"type":["object","null"],"description":"Conversion applied to the money fields, or null when no conversion was needed (every native amount is already in `amounts_currency`) or when it was unavailable (`fx_unavailable` true).","properties":{"rate":{"type":["number","null"],"description":"The single conversion rate, or null when more than one native currency was converted (see `rates`)."},"source":{"type":"string","enum":["live","fallback"],"description":"`live` when every rate came from the live FX provider; `fallback` when any used the stored fallback rate."},"as_of":{"type":"string","format":"date-time","description":"When the rates were resolved (UTC)."},"to":{"type":["string","null"],"description":"ISO 4217 currency the amounts were converted into."},"rates":{"type":"object","description":"Rate applied per native ISO 4217 currency code (1 native unit = rate display units).","additionalProperties":{"type":"number"}}}},"fx_unavailable":{"type":"boolean"},"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"occurred_at":{"type":["string","null"],"format":"date-time","description":"Delivery time, else send time, else creation time (UTC)."},"billing_day":{"type":["string","null"],"format":"date"},"conversation_id":{"type":["integer","null"],"description":"Conversation display id."},"contact_name":{"type":["string","null"]},"inbox_id":{"type":"integer"},"inbox_label":{"type":["string","null"]},"channel_id":{"type":"integer"},"wamid_suffix":{"type":["string","null"],"description":"Last six characters of the WhatsApp message id."},"market":{"type":["string","null"],"description":"Meta pricing market of the recipient."},"country_iso":{"type":["string","null"],"description":"ISO 3166-1 alpha-2 country of the recipient."},"category":{"type":["string","null"],"description":"Meta pricing category of the message.","enum":["marketing","utility","authentication","service",null]},"pricing_type":{"type":["string","null"],"enum":["regular","free_customer_service","free_entry_point",null],"description":"Meta `pricing.type` of the message; null when Meta sent no pricing (inferred entry)."},"billing_state":{"type":"string","enum":["pending_delivery","billable","free","not_billed","not_billed_expired","unverified"],"description":"Ledger state — `pending_delivery` (sent, awaiting the final status; provisional amount), `billable` (the only state that counts as cost), `free`, `not_billed` (failed), `not_billed_expired` (no final status within 30 days) or `unverified`."},"free_reason":{"type":["string","null"],"enum":["free_tier","free_customer_service","free_entry_point","business_app","web_transport",null],"description":"Why a `free` message costs nothing — `free_tier` classifies reported deliveries against the local estimated monthly service allowance; see `allowance.evidence`. Meta does not publish an allowance limit in the documentation tracked here. `free_customer_service` (inside the 24-hour customer service window, until 2026-09-30) and `free_entry_point` (inside an ad free entry point window) identify reported free events; `business_app` (sent from the WhatsApp Business app of a Coexistence number) or `web_transport` (sent through the WhatsApp Web leg of a paired number). Null for any other state."},"billable_source":{"type":"string","enum":["webhook","inferred","unverified","historical_estimate"],"description":"Where billability came from — `webhook` (Meta's pricing), `inferred` (the transport, with no pricing), `unverified` (an unknown pricing shape) or `historical_estimate`."},"unit_price":{"type":["number","null"]},"amount":{"type":"number","description":"Native amount (0 for every state other than billable and pending_delivery)."},"currency":{"type":["string","null"],"description":"Native ISO 4217 billing currency."},"amount_source":{"type":["string","null"],"enum":["list_rate","tier_estimated","override","meta_reported",null],"description":"How the amount was priced — `list_rate` (the official rate card), `tier_estimated` (a volume tier estimated by the platform), `override` (the account's own tariff) or `meta_reported` (the cost Meta reported with a max-price marketing delivery). Null when there is no priced amount."},"display_amount":{"type":["number","null"]},"partner_billed":{"type":"boolean"},"tier":{"type":["string","null"],"description":"Volume tier the price came from, as `\u003cfrom\u003e-\u003cto\u003e` (`+` for an open end); null outside tier pricing."},"meta_reported_cost":{"type":["object","null"],"description":"The cost Meta reported for the delivery (`pricing.cost`, max-price marketing), kept as a reference even when the account's own tariff priced the entry (the account tariff wins); null when Meta reported none.","properties":{"amount":{"type":"number"},"currency":{"type":"string"}}},"sender":{"type":["object","null"],"properties":{"type":{"type":"string","description":"Sender record type (for example `User` or `AgentBot`)."},"id":{"type":"integer"},"name":{"type":["string","null"]}}},"campaign":{"type":["object","null"],"properties":{"id":{"type":"integer"},"display_id":{"type":"integer"},"title":{"type":"string"}}}}}},"meta":{"type":"object","properties":{"count":{"type":"integer"},"current_page":{"type":"integer"},"total_pages":{"type":"integer"},"per_page":{"type":"integer"}}}}},"example":{"period":{"from":"2026-10-01","to":"2026-10-20","clamped":false},"amounts_currency":"BRL","fx":{"rate":5.0,"source":"live","as_of":"2026-10-20T12:00:00Z","to":"BRL","rates":{"USD":5.0}},"fx_unavailable":false,"payload":[{"id":1905,"occurred_at":"2026-10-02T12:00:05Z","billing_day":"2026-10-02","conversation_id":1234,"contact_name":"Maria Souza","inbox_id":42,"inbox_label":"Atendimento","channel_id":17,"wamid_suffix":"A1B2C3","market":"Brazil","country_iso":"BR","category":"utility","pricing_type":"regular","billing_state":"billable","free_reason":null,"billable_source":"webhook","unit_price":0.0068,"amount":0.0068,"currency":"USD","amount_source":"list_rate","display_amount":0.034,"partner_billed":false,"tier":null,"meta_reported_cost":null,"sender":{"type":"User","id":7,"name":"Ana Lima"},"campaign":{"id":31,"display_id":4,"title":"Aviso de entrega"}}],"meta":{"count":30,"current_page":1,"total_pages":2,"per_page":25}}}}},"401":{"description":"Unauthorized"},"404":{"description":"The `whatsapp_cost_center` feature is off for the account (empty body), or the `inbox_id` is outside the caller's operational scope.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Present only for a record outside the scope."}}},"example":{"error":"Resource could not be found"}}}},"403":{"description":"The caller may not read (or, for writes, manage) WhatsApp costs.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["forbidden"]}}},"example":{"error":"forbidden"}}}},"422":{"description":"The `inbox_id` has no billing channel (it is neither Cloud, 360dialog nor the Web leg of a paired number).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["not_a_cloud_inbox"]}}},"example":{"error":"not_a_cloud_inbox"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"inbox_id","in":"query","required":false,"description":"Restrict the report to one inbox of the caller's operational scope. A WhatsApp Web inbox of a paired number reports through its Cloud sibling.","schema":{"type":"integer"},"example":42},{"name":"from","in":"query","required":false,"description":"First billing day (ISO 8601 date, WABA time zone). Defaults to the first day of the month of `to`.","schema":{"type":"string","format":"date"},"example":"2026-10-01"},{"name":"to","in":"query","required":false,"description":"Last billing day (ISO 8601 date, WABA time zone). Defaults to today in the WABA time zone.","schema":{"type":"string","format":"date"},"example":"2026-10-31"},{"name":"currency","in":"query","required":false,"description":"ISO 4217 display currency the amounts are converted into. Defaults to the account display currency.","schema":{"type":"string","pattern":"^[A-Za-z]{3}$"},"example":"BRL"},{"name":"category","in":"query","required":false,"description":"Restrict to one pricing category.","schema":{"type":"string","enum":["marketing","utility","authentication","service"]},"example":"service"},{"name":"state","in":"query","required":false,"description":"Restrict to one ledger state.","schema":{"type":"string","enum":["pending_delivery","billable","free","not_billed","not_billed_expired","unverified"]},"example":"billable"},{"name":"source","in":"query","required":false,"description":"Restrict to one pricing source.","schema":{"type":"string","enum":["list_rate","tier_estimated","override","meta_reported"]},"example":"list_rate"},{"name":"partner_billed","in":"query","required":false,"description":"Restrict to entries of partner-billed (true) or directly billed (false) numbers.","schema":{"type":"boolean"},"example":false},{"name":"conversation_id","in":"query","required":false,"description":"Restrict to one conversation, by its display id.","schema":{"type":"integer"},"example":1234},{"name":"page","in":"query","required":false,"description":"Page number (1-based).","schema":{"type":"integer","minimum":1,"default":1},"example":1},{"name":"per_page","in":"query","required":false,"description":"Entries per page, clamped to 1–100.","schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"example":25}]}},"/api/v1/accounts/{account_id}/whatsapp/cost_center/business_agent":{"get":{"tags":["WhatsApp"],"operationId":"auto_get_api_v1_accounts_account_id_whatsapp_cost_center_business_agent","summary":"Get the Meta Business Agent usage of the account","description":"Billable messages, billed tokens and charges of the account's Meta Business Agent over the Central's period (`from`/`to`, default the current month), read from Meta's Business Agent Usage Insights API for the WhatsApp channel. `state` says what can be shown: `not_in_use` (no configured billable account and no Conversation Routing observed on a Cloud API number), `account_id_required` (Conversation Routing was observed but the agent's billable account ID, found only in Meta's Billing Hub, is not configured), `permission_required` (Meta refused the account's WhatsApp token; it needs the `business_management` permission — `reason: no_cloud_token` when the account has no Cloud API token at all), `account_not_found`, `rate_limited`, `invalid_request`, `unavailable` (also a malformed or oversized answer, and `reason: no_egress_fixture` for a no-egress laboratory account outside the test environment, which never calls Meta), `no_usage` (Meta's explicit empty answer, or all three metrics positively reported as zero in every bucket) and `ok`. A bucket may omit an optional metric: then `measurement_complete` is false, that metric's period total is null and the answer must not be read as a zero or a silent subtotal. The charge is in the agent account's own currency, as configured by an administrator — Meta does not report it — and is never converted; days follow the agent account's timezone, which Meta does not report either. Read-only: a successful answer is cached for 15 minutes and an error for 5 minutes; `refresh=true` asks Meta again past a cached error (a cached success is kept). Requires the `whatsapp_cost_center` feature and the cost-manage permission (administrator): the charge belongs to the billable agent account and cannot be scoped to inboxes.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The usage, or the state that explains why there is none.","content":{"application/json":{"schema":{"type":"object","required":["state","in_use","signals","configured","currency","period","required_permission","evidence","currencies","billable_account_id"],"properties":{"state":{"type":"string","enum":["not_in_use","account_id_required","permission_required","account_not_found","rate_limited","invalid_request","unavailable","no_usage","ok"],"description":"What the block can show."},"reason":{"type":["string","null"],"enum":["no_cloud_token","no_egress_fixture",null],"description":"`no_cloud_token` with `permission_required` when the account has no Cloud API token to query Meta; `no_egress_fixture` with `unavailable` for a no-egress laboratory account, which never calls Meta."},"http_status":{"type":"integer","description":"Meta's HTTP status, present on a refused request."},"in_use":{"type":"boolean","description":"True when the account shows a sign of using Meta's agent."},"signals":{"type":"array","description":"The recorded signs found — a configured billable account, or Meta's Conversation Routing observed on a Cloud API number.","items":{"type":"string","enum":["configured","routing_observed"]}},"configured":{"type":"boolean","description":"True when the agent's billable account ID is configured."},"currency":{"type":["string","null"],"enum":["USD","AED","ARS","AUD","BRL","CLP","COP","EUR","GBP","IDR","INR","MXN","MYR","PEN","SAR","SGD",null],"description":"Currency of the agent account, as configured by an administrator; null when not configured."},"period":{"type":"object","required":["from","to","granularity","timezone_evidence"],"properties":{"from":{"type":"string","format":"date"},"to":{"type":"string","format":"date"},"granularity":{"type":"string","enum":["DAY"]},"timezone_evidence":{"type":"string","enum":["unverified"],"description":"Meta evaluates the days in the agent account's timezone, which its API does not report."}}},"required_permission":{"type":"string","enum":["business_management"]},"evidence":{"type":"string","enum":["official_replay"]},"currencies":{"type":"array","description":"The currencies Meta enables for a Meta Business Agent account.","items":{"type":"string","enum":["USD","AED","ARS","AUD","BRL","CLP","COP","EUR","GBP","IDR","INR","MXN","MYR","PEN","SAR","SGD"]}},"totals":{"type":"object","description":"Exact sums of the period. A metric omitted from any bucket is null; it is never a partial sum. Present with `ok` and `no_usage`.","properties":{"billable_messages":{"type":["integer","null"]},"billable_tokens":{"type":["integer","null"]},"cost":{"type":["string","null"],"description":"Charge in MAJOR units of the agent account's currency, as a decimal string."}}},"measurement_complete":{"type":"boolean","description":"True only when every returned bucket supplied all three metrics. It is true for Meta's explicit empty `usage` list, which is a positive no-use answer."},"incomplete_observed":{"type":"boolean","description":"True when Meta returned at least one bucket without a metric. Such an answer is never `no_usage` unless the response itself was empty."},"unmeasured_metrics":{"type":"array","description":"Metrics omitted by one or more returned buckets; empty when `measurement_complete` is true.","items":{"type":"string","enum":["billable_messages","billable_tokens","cost"]}},"buckets":{"type":"array","description":"One entry per day bucket returned by Meta. Present with `ok` and `no_usage`.","items":{"type":"object","properties":{"start":{"type":"string","format":"date-time"},"end":{"type":"string","format":"date-time"},"billable_messages":{"type":["integer","null"]},"billable_tokens":{"type":["integer","null"]},"cost":{"type":["string","null"]}}}},"fetched_at":{"type":"string","format":"date-time"},"billable_account_id":{"type":["string","null"],"description":"The configured billable account ID; null when not configured."}}},"example":{"state":"ok","in_use":true,"signals":["configured","routing_observed"],"configured":true,"currency":"USD","period":{"from":"2025-06-01","to":"2025-06-01","granularity":"DAY","timezone_evidence":"unverified"},"required_permission":"business_management","evidence":"official_replay","currencies":["USD","AED","ARS","AUD","BRL","CLP","COP","EUR","GBP","IDR","INR","MXN","MYR","PEN","SAR","SGD"],"totals":{"billable_messages":42,"billable_tokens":840000,"cost":"1.68"},"measurement_complete":true,"incomplete_observed":false,"unmeasured_metrics":[],"buckets":[{"start":"2025-06-01T07:00:00Z","end":"2025-06-02T07:00:00Z","billable_messages":42,"billable_tokens":840000,"cost":"1.68"}],"fetched_at":"2025-06-02T12:00:00Z","billable_account_id":"102290129340398","reason":"no_cloud_token","http_status":1}}}},"401":{"description":"Unauthorized"},"404":{"description":"The `whatsapp_cost_center` feature is off for the account (empty body), or the `inbox_id` is outside the caller's operational scope.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Present only for a record outside the scope."}}},"example":{"error":"Resource could not be found"}}}},"403":{"description":"The caller may not read (or, for writes, manage) WhatsApp costs.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["forbidden"]}}},"example":{"error":"forbidden"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"from","in":"query","required":false,"description":"First billing day (ISO 8601 date, WABA time zone). Defaults to the first day of the month of `to`.","schema":{"type":"string","format":"date"},"example":"2026-10-01"},{"name":"to","in":"query","required":false,"description":"Last billing day (ISO 8601 date, WABA time zone). Defaults to today in the WABA time zone.","schema":{"type":"string","format":"date"},"example":"2026-10-31"},{"name":"refresh","in":"query","required":false,"description":"When true, a cached error is discarded and Meta is asked again; a cached success is kept.","schema":{"type":"boolean"},"example":true}]},"patch":{"tags":["WhatsApp"],"operationId":"auto_patch_api_v1_accounts_account_id_whatsapp_cost_center_business_agent","summary":"Configure the account's Meta Business Agent billable account","description":"Stores the agent's billable account ID (Billing Hub › Accounts › Meta Business Agent accounts) and the agent account's currency, used to read its usage from Meta. A blank `billable_account_id` removes the configuration. Does not call Meta and answers the stored configuration. Requires the `whatsapp_cost_center` feature and the cost-manage permission (administrator).","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The stored configuration.","content":{"application/json":{"schema":{"type":"object","required":["configured","billable_account_id","currency","currencies","required_permission"],"properties":{"configured":{"type":"boolean","description":"True when the agent's billable account ID is configured."},"billable_account_id":{"type":["string","null"],"description":"The configured billable account ID; null when not configured."},"currency":{"type":["string","null"],"enum":["USD","AED","ARS","AUD","BRL","CLP","COP","EUR","GBP","IDR","INR","MXN","MYR","PEN","SAR","SGD",null],"description":"Currency of the agent account; null when not configured."},"currencies":{"type":"array","description":"The currencies Meta enables for a Meta Business Agent account.","items":{"type":"string","enum":["USD","AED","ARS","AUD","BRL","CLP","COP","EUR","GBP","IDR","INR","MXN","MYR","PEN","SAR","SGD"]}},"required_permission":{"type":"string","enum":["business_management"],"description":"The permission the account's WhatsApp token needs for Meta to answer the usage request."}}},"example":{"configured":true,"billable_account_id":"102290129340398","currency":"USD","currencies":["USD","AED","ARS","AUD","BRL","CLP","COP","EUR","GBP","IDR","INR","MXN","MYR","PEN","SAR","SGD"],"required_permission":"business_management"}}}},"401":{"description":"Unauthorized"},"404":{"description":"The `whatsapp_cost_center` feature is off for the account (empty body), or the `inbox_id` is outside the caller's operational scope.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Present only for a record outside the scope."}}},"example":{"error":"Resource could not be found"}}}},"403":{"description":"The caller may not read (or, for writes, manage) WhatsApp costs.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["forbidden"]}}},"example":{"error":"forbidden"}}}},"422":{"description":"The ID is not made of digits or the currency is not one Meta enables for the agent account.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["invalid_business_agent_account","invalid_business_agent_currency"]}}},"example":{"error":"invalid_business_agent_account"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"billable_account_id":{"type":"string","description":"Digits of the billable account ID; blank removes the configuration."},"currency":{"type":"string","enum":["USD","AED","ARS","AUD","BRL","CLP","COP","EUR","GBP","IDR","INR","MXN","MYR","PEN","SAR","SGD"],"description":"Currency of the agent account; required with an ID."}}},"example":{"billable_account_id":"102290129340398","currency":"USD"}}}}}},"/api/v1/accounts/{account_id}/whatsapp/cost_center/business_agent/configuration":{"get":{"tags":["WhatsApp"],"operationId":"auto_get_api_v1_accounts_account_id_whatsapp_cost_center_business_agent_configuration","summary":"Get the account's Meta Business Agent configuration","description":"The agent's billable account ID and currency as stored by an administrator, without calling Meta, so the configuration can be made before the account shows any usage. A configured ID is itself the sign that makes the usage block appear. Requires the `whatsapp_cost_center` feature and the cost-manage permission (administrator).","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The stored configuration.","content":{"application/json":{"schema":{"type":"object","required":["configured","billable_account_id","currency","currencies","required_permission"],"properties":{"configured":{"type":"boolean","description":"True when the agent's billable account ID is configured."},"billable_account_id":{"type":["string","null"],"description":"The configured billable account ID; null when not configured."},"currency":{"type":["string","null"],"enum":["USD","AED","ARS","AUD","BRL","CLP","COP","EUR","GBP","IDR","INR","MXN","MYR","PEN","SAR","SGD",null],"description":"Currency of the agent account; null when not configured."},"currencies":{"type":"array","description":"The currencies Meta enables for a Meta Business Agent account.","items":{"type":"string","enum":["USD","AED","ARS","AUD","BRL","CLP","COP","EUR","GBP","IDR","INR","MXN","MYR","PEN","SAR","SGD"]}},"required_permission":{"type":"string","enum":["business_management"],"description":"The permission the account's WhatsApp token needs for Meta to answer the usage request."}}},"example":{"configured":true,"billable_account_id":"102290129340398","currency":"USD","currencies":["USD","AED","ARS","AUD","BRL","CLP","COP","EUR","GBP","IDR","INR","MXN","MYR","PEN","SAR","SGD"],"required_permission":"business_management"}}}},"401":{"description":"Unauthorized"},"404":{"description":"The `whatsapp_cost_center` feature is off for the account (empty body), or the `inbox_id` is outside the caller's operational scope.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Present only for a record outside the scope."}}},"example":{"error":"Resource could not be found"}}}},"403":{"description":"The caller may not read (or, for writes, manage) WhatsApp costs.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["forbidden"]}}},"example":{"error":"forbidden"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/whatsapp/cost_center/calls":{"get":{"tags":["WhatsApp"],"operationId":"auto_get_api_v1_accounts_account_id_whatsapp_cost_center_calls","summary":"Report WhatsApp call costs","description":"The \"Calls\" block of the Cost Center for the billing channels of the caller's operational scope: Meta's cost of the WhatsApp Cloud calls — quantity, talk time, pulses and cost by direction, country and inbox, the volume tier of the month and the reconciliation with Meta's call_analytics. The AI voice cost of a call is reported by the Maestro usage and is never added here. Meta's rule (Calling pricing page): every user-initiated call is free; a business-initiated call is charged per six-second pulse (a fraction is a whole pulse) at the per-minute rate of the called number's market, in the WABA billing currency, in the volume tier reached by the minutes called in the calendar month. The tier is estimated from this installation's records of the business portfolio. Money is MAJOR units per native currency and is never added across currencies. Requires the `whatsapp_cost_center` feature and the cost-view permission. `unpriced` rows are measured calls without a confirmed Meta price: they never become \"no charge\". When they coexist with `amounts`, `total_is_floor` marks the known native-currency amounts as a subtotal rather than a complete total.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Call costs of the window.","content":{"application/json":{"schema":{"type":"object","properties":{"period":{"type":"object","description":"The reported window of billing days, in the WABA time zone.","properties":{"from":{"type":"string","format":"date"},"to":{"type":"string","format":"date"}}},"totals":{"type":"object","description":"Meta calling rows of the window. `seconds` and `answered` count connected calls only; `pulses` is business-initiated talk time; `unpriced` rows count here but never in `amounts`.","properties":{"calls":{"type":"integer"},"incoming":{"type":"integer"},"outgoing":{"type":"integer"},"answered":{"type":"integer"},"seconds":{"type":"integer"},"pulses":{"type":"integer"},"unpriced":{"type":"integer"},"not_connected":{"type":"integer"},"amounts":{"type":"array","description":"Charged amount per native currency (`estimated` + `reconciled`; values only). Empty means no charge only when the sibling `unpriced` count is zero.","items":{"type":"object","properties":{"currency":{"type":"string"},"amount":{"type":"number"}}}},"total_is_floor":{"type":"boolean","description":"True when one or more measured calls have no confirmed price, so `amounts` is only a floor."}}},"by_direction":{"type":"array","description":"One entry per call direction present in the window.","items":{"type":"object","properties":{"direction":{"type":["string","null"],"enum":["incoming","outgoing",null]},"calls":{"type":"integer"},"answered":{"type":"integer"},"seconds":{"type":"integer"},"pulses":{"type":"integer"},"unpriced":{"type":"integer"},"amounts":{"type":"array","description":"Charged amount per native currency (`estimated` + `reconciled`; values only). Empty means no charge only when the sibling `unpriced` count is zero.","items":{"type":"object","properties":{"currency":{"type":"string"},"amount":{"type":"number"}}}},"total_is_floor":{"type":"boolean"}}}},"by_country":{"type":"array","description":"One entry per called country and Meta pricing market (null for user-initiated calls).","items":{"type":"object","properties":{"country_iso":{"type":["string","null"]},"market":{"type":["string","null"]},"calls":{"type":"integer"},"answered":{"type":"integer"},"seconds":{"type":"integer"},"pulses":{"type":"integer"},"unpriced":{"type":"integer"},"amounts":{"type":"array","description":"Charged amount per native currency (`estimated` + `reconciled`; values only). Empty means no charge only when the sibling `unpriced` count is zero.","items":{"type":"object","properties":{"currency":{"type":"string"},"amount":{"type":"number"}}}},"total_is_floor":{"type":"boolean"}}}},"by_inbox":{"type":"array","description":"One entry per inbox that placed or received the calls.","items":{"type":"object","properties":{"inbox_id":{"type":"integer"},"name":{"type":"string"},"calls":{"type":"integer"},"answered":{"type":"integer"},"seconds":{"type":"integer"},"pulses":{"type":"integer"},"unpriced":{"type":"integer"},"amounts":{"type":"array","description":"Charged amount per native currency (`estimated` + `reconciled`; values only). Empty means no charge only when the sibling `unpriced` count is zero.","items":{"type":"object","properties":{"currency":{"type":"string"},"amount":{"type":"number"}}}},"total_is_floor":{"type":"boolean"}}}},"tier":{"type":"array","description":"Minutes called this calendar month per billing channel and the volume tier they reach (an estimate: Meta accrues across every number of the business portfolio).","items":{"type":"object","properties":{"channel_id":{"type":"integer"},"month":{"type":"string","description":"Calendar month as YYYY-MM."},"minutes":{"type":"number"},"currency":{"type":"string"},"tier":{"type":["string","null"],"description":"Minutes `from-to` of the tier (`+` = no upper bound).","example":"0-50000"},"next_threshold":{"type":["integer","null"],"description":"First minute of the next tier","null in the last one.":null},"evidence":{"type":"string","enum":["estimate"]}}}},"reconciliation":{"type":"object","description":"How the business-initiated estimates compare with Meta's call_analytics COST.","properties":{"state":{"type":"string","enum":["no_business_calls","partner_billed","reconciled","not_synced","estimated"],"description":"`no_business_calls` (no business-initiated call in the window), `partner_billed` (Meta reports volume but no cost for a number billed by a Solution Partner), `reconciled` (applicable charged days matched Meta's COST), `not_synced` (call_analytics has not been read yet or at least one business-initiated call lacks a confirmed price, so known amounts are incomplete) or `estimated` (analytics was read, but the applicable cost has not matched yet)."},"estimated":{"type":"array","description":"Charged amount per native currency (`estimated` + `reconciled`; values only). Empty means no charge only when the sibling `unpriced` count is zero.","items":{"type":"object","properties":{"currency":{"type":"string"},"amount":{"type":"number"}}}},"reconciled":{"type":"array","description":"Charged amount per native currency (`estimated` + `reconciled`; values only). Empty means no charge only when the sibling `unpriced` count is zero.","items":{"type":"object","properties":{"currency":{"type":"string"},"amount":{"type":"number"}}}},"partner_billed":{"type":"boolean"},"synced_at":{"type":["string","null"],"format":"date-time"}}},"entries":{"type":"array","description":"Meta's cost lines of the page, most recent first.","items":{"type":"object","properties":{"id":{"type":"integer"},"call_id":{"type":["integer","null"],"description":"Null once the call was deleted (the cost stays)."},"conversation_id":{"type":["integer","null"]},"inbox_id":{"type":"integer"},"direction":{"type":["string","null"],"enum":["incoming","outgoing",null],"description":"`incoming` = started by the user (free); `outgoing` = started by the business."},"billing_state":{"type":"string","enum":["estimated","reconciled","free","not_connected","unpriced"],"description":"`free` (user-initiated), `not_connected` (business call never answered, no pulse), `estimated` (Meta's rule applied to the call), `reconciled` (the day's call_analytics COST matched), `unpriced` (no market, currency or rate card for the called number)."},"free_reason":{"type":["string","null"],"enum":["user_initiated",null]},"duration_seconds":{"type":["integer","null"]},"pulses":{"type":["integer","null"],"description":"Six-second pulses, a fraction counted as a whole pulse (business-initiated calls)."},"market":{"type":["string","null"],"description":"Meta pricing market of the called number."},"country_iso":{"type":["string","null"]},"tier":{"type":["string","null"],"description":"Volume tier of the month, as minutes `from-to` (`+` = no upper bound).","example":"0-50000"},"rate_per_minute":{"type":["number","null"],"description":"Values only."},"amount":{"type":["number","null"],"description":"MAJOR units in `currency` (values only)."},"currency":{"type":["string","null"],"description":"Values only."},"amount_source":{"type":["string","null"],"enum":["list_rate","tier_rate",null],"description":"`list_rate` (the first volume tier) or `tier_rate` (a higher tier of the month). Values only."},"billing_day":{"type":["string","null"],"format":"date"},"recorded_at":{"type":["string","null"],"format":"date-time","description":"When this line was written, right after the call ended."},"unpriced_reason":{"type":["string","null"],"enum":["no_called_number","no_market","no_billing_currency","no_rate_card","market_not_in_card",null]},"meta_day":{"type":["object","null"],"description":"Meta's call_analytics figures of the call's day (`cost` is values only; null when partner billed).","properties":{"count":{"type":"integer"},"average_duration":{"type":"integer"},"cost":{"type":["string","null"]},"partner_billed":{"type":"boolean"},"synced_at":{"type":"string","format":"date-time"}}}}}},"meta":{"type":"object","properties":{"page":{"type":"integer"},"per_page":{"type":"integer"},"total":{"type":"integer"}}},"evidence":{"type":"object","description":"Evidence tier of each part of the rule.","properties":{"rule":{"type":"string","enum":["official_replay"]},"user_initiated_free":{"type":"string","enum":["live"]},"call_analytics_shape":{"type":"string","enum":["live"]},"business_initiated_pulses":{"type":"string","enum":["official_replay"]}}}}},"example":{"period":{"from":"2026-10-01","to":"2026-10-31"},"totals":{"calls":2,"incoming":1,"outgoing":1,"answered":2,"seconds":68,"pulses":10,"unpriced":0,"not_connected":0,"amounts":[{"currency":"USD","amount":0.0108}],"total_is_floor":false},"by_direction":[{"direction":"incoming","calls":1,"answered":1,"seconds":12,"pulses":0,"unpriced":0,"amounts":[{"currency":"BRL","amount":149.9}],"total_is_floor":false},{"direction":"outgoing","calls":1,"answered":1,"seconds":56,"pulses":10,"unpriced":0,"amounts":[{"currency":"USD","amount":0.0108}],"total_is_floor":false}],"by_country":[{"country_iso":null,"market":null,"calls":1,"answered":1,"seconds":12,"pulses":0,"unpriced":0,"amounts":[{"currency":"BRL","amount":149.9}],"total_is_floor":false},{"country_iso":"BR","market":"Brazil","calls":1,"answered":1,"seconds":56,"pulses":10,"unpriced":0,"amounts":[{"currency":"USD","amount":0.0108}],"total_is_floor":false}],"by_inbox":[{"inbox_id":42,"name":"Atendimento","calls":2,"answered":2,"seconds":68,"pulses":10,"unpriced":0,"amounts":[{"currency":"USD","amount":0.0108}],"total_is_floor":false}],"tier":[{"channel_id":7,"month":"2026-10","minutes":1.0,"currency":"USD","tier":"0-50000","next_threshold":50001,"evidence":"estimate"}],"reconciliation":{"state":"not_synced","estimated":[{"currency":"USD","amount":0.0108}],"reconciled":[{"currency":"BRL","amount":149.9}],"partner_billed":false,"synced_at":null},"entries":[{"id":31,"call_id":902,"conversation_id":77,"inbox_id":42,"direction":"outgoing","billing_state":"estimated","free_reason":null,"duration_seconds":56,"pulses":10,"market":"Brazil","country_iso":"BR","tier":"0-50000","rate_per_minute":0.0108,"amount":0.0108,"currency":"USD","amount_source":"list_rate","billing_day":"2026-10-20","recorded_at":"2026-10-20T14:02:11Z","unpriced_reason":null,"meta_day":null},{"id":30,"call_id":901,"conversation_id":77,"inbox_id":42,"direction":"incoming","billing_state":"free","free_reason":"user_initiated","duration_seconds":12,"pulses":null,"market":null,"country_iso":null,"tier":null,"rate_per_minute":null,"amount":0.0,"currency":"USD","amount_source":null,"billing_day":"2026-10-20","recorded_at":"2026-10-20T13:41:37Z","unpriced_reason":null,"meta_day":{"count":1,"average_duration":12,"cost":"0","partner_billed":false,"synced_at":"2026-10-21T04:50:00Z"}}],"meta":{"page":1,"per_page":25,"total":2},"evidence":{"rule":"official_replay","user_initiated_free":"live","call_analytics_shape":"live","business_initiated_pulses":"official_replay"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"The `whatsapp_cost_center` feature is off for the account (empty body), or the `inbox_id` is outside the caller's operational scope.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Present only for a record outside the scope."}}},"example":{"error":"Resource could not be found"}}}},"403":{"description":"The caller may not read (or, for writes, manage) WhatsApp costs.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["forbidden"]}}},"example":{"error":"forbidden"}}}},"422":{"description":"The `inbox_id` has no billing channel (it is neither Cloud, 360dialog nor the Web leg of a paired number).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["not_a_cloud_inbox"]}}},"example":{"error":"not_a_cloud_inbox"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"inbox_id","in":"query","required":false,"description":"Restrict the report to one inbox of the caller's operational scope. A WhatsApp Web inbox of a paired number reports through its Cloud sibling.","schema":{"type":"integer"},"example":42},{"name":"from","in":"query","required":false,"description":"First billing day (ISO 8601 date, WABA time zone). Defaults to the first day of the month of `to`.","schema":{"type":"string","format":"date"},"example":"2026-10-01"},{"name":"to","in":"query","required":false,"description":"Last billing day (ISO 8601 date, WABA time zone). Defaults to today in the WABA time zone.","schema":{"type":"string","format":"date"},"example":"2026-10-31"},{"name":"page","in":"query","required":false,"description":"Page of `entries` (25 per page, most recent first).","schema":{"type":"integer","minimum":1,"default":1},"example":1}]}},"/api/v1/accounts/{account_id}/whatsapp/cost_center/rate_cards":{"get":{"tags":["WhatsApp"],"operationId":"auto_get_api_v1_accounts_account_id_whatsapp_cost_center_rate_cards","summary":"List WhatsApp rate cards","description":"Every imported official rate card (superseded ones included — cards are never deleted) with its tariffs by market and category and its volume tiers, the account's own tariffs by market and category, and the state of Meta's official volume-tier notification. Requires the `whatsapp_cost_center` feature and the cost-management permission (administrators only — the account's negotiated tariffs are not exposed to view-only roles).","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Rate cards and the account overrides.","content":{"application/json":{"schema":{"type":"object","properties":{"can_manage":{"type":"boolean"},"cards":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"effective_from":{"type":["string","null"],"format":"date"},"currency":{"type":"string","description":"ISO 4217 currency of the card."},"evidence_tier":{"type":"string","enum":["official_replay","derived"],"description":"`official_replay` for a card imported from Meta; `derived` for a card built from another (for example `service` priced as `utility`)."},"superseded_at":{"type":["string","null"],"format":"date-time"},"source_url":{"type":["string","null"]},"source_sha256":{"type":["string","null"]},"fetched_at":{"type":["string","null"],"format":"date-time"},"markets":{"type":"array","items":{"type":"string"}},"rates":{"type":"object","description":"Tariff per Meta market, then per pricing category, in the card currency (null when not offered).","additionalProperties":{"type":"object","description":"Tariff of one Meta market, keyed by pricing category.","additionalProperties":{"type":["number","null"]}}},"tiers":{"type":"object","description":"Volume tiers per Meta market, then per pricing category.","additionalProperties":{"type":"object","description":"Volume tiers of one Meta market, keyed by pricing category.","additionalProperties":{"type":"array","items":{"type":"object","properties":{"from":{"type":"integer"},"to":{"type":["integer","null"]},"rate":{"type":["number","null"]},"rate_type":{"type":["string","null"],"enum":["list","tier",null]}}}}}}}}},"overrides":{"type":"object","description":"The account's own tariffs per Meta market, then per pricing category. A legacy per-country USD tariff is shown under its market with `legacy_country`.","additionalProperties":{"type":"object","description":"The account's tariffs of one Meta market, keyed by pricing category.","additionalProperties":{"type":"object","properties":{"currency":{"type":"string"},"rate":{"type":["number","null"]},"legacy_country":{"type":"string","description":"ISO country of a legacy per-country override."}}}}},"reference_data":{"type":"object","description":"The last automatic load of the official reference data shipped with the platform (rate cards and market map), run at boot, daily and when this tab is opened empty. It only fills what is missing and never touches the account's own tariffs.","properties":{"status":{"type":"string","enum":["never_run","succeeded","unchanged","deferred","failed","unknown"]},"at":{"type":["string","null"],"format":"date-time"},"error":{"type":["string","null"],"description":"Sanitized error class of a failed load."},"market_map_versions":{"type":"array","description":"Effective dates of the market-map versions loaded.","items":{"type":"string","format":"date"}}}},"official_tier":{"type":"object","description":"Meta's volume-tier notification stays unverified until a real one is captured.","properties":{"state":{"type":"string","enum":["unverified"]},"reason":{"type":"string","enum":["no_capture"]}}}}},"example":{"can_manage":true,"cards":[{"id":692,"effective_from":"2026-07-01","currency":"USD","evidence_tier":"official_replay","superseded_at":null,"source_url":"https://developers.facebook.com/docs/whatsapp/pricing","source_sha256":"3f1c2a9b8e7d6c5b4a3f2e1d0c9b8a7f6e5d4c3b2a1f0e9d8c7b6a5f4e3d2c1b","fetched_at":"2026-09-23T12:00:00Z","markets":["Brazil","North America"],"rates":{"Brazil":{"utility":0.0068,"marketing":0.0625,"authentication":0.0068},"North America":{"utility":0.0034,"marketing":0.025,"authentication":0.0034}},"tiers":{"Brazil":{"utility":[{"from":0,"to":250000,"rate":0.0068,"rate_type":"tier"}]}}}],"overrides":{"Brazil":{"marketing":{"currency":"USD","rate":0.07}}},"reference_data":{"status":"succeeded","at":"2026-10-01T06:20:00Z","error":null,"market_map_versions":["2026-07-01","2026-10-01"]},"official_tier":{"state":"unverified","reason":"no_capture"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"The `whatsapp_cost_center` feature is off for the account (empty body), or the `inbox_id` is outside the caller's operational scope.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Present only for a record outside the scope."}}},"example":{"error":"Resource could not be found"}}}},"403":{"description":"The caller may not read (or, for writes, manage) WhatsApp costs.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["forbidden"]}}},"example":{"error":"forbidden"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/whatsapp/cost_center/rate_cards/sync":{"post":{"tags":["WhatsApp"],"operationId":"auto_post_api_v1_accounts_account_id_whatsapp_cost_center_rate_cards_sync","summary":"Sync the official WhatsApp rate card","description":"Downloads Meta's official rate cards (the ones in force and the next quarter's, for USD, BRL and the billing currencies of the account's numbers — CSV or XLSX, recognized by their own title) and imports each one (a new card supersedes the previous one of the same effective date and currency). `ok` and `import_ok` are true only when the import succeeded, the selected card resolves to a stored row and `failed` is empty. An absent, failed, partial or unresolved import answers 200 with both flags false, `imported`/`failed` and the sanitized reason `rate_card_import_failed`. Failure of a selected individual document remains a 200 import failure. Source-page transport failures and the existing no-eligible-source/processing refusals retain 424 with a sanitized reason, never the raw error. Requires the `whatsapp_cost_center` feature and the cost-manage permission.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The source was read; import success also requires a real selected row and no failed cards.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"effective_from":{"type":["string","null"],"format":"date"},"currency":{"type":["string","null"]},"rate_card_id":{"type":["integer","null"]},"synced_at":{"type":["string","null"],"format":"date-time"},"import_ok":{"type":"boolean","description":"Same as `ok` (kept for compatibility)."},"reason":{"type":"string","enum":["rate_card_import_failed"],"description":"Present when the import is absent, failed, partial or has no stored selected row."},"imported":{"type":"array","description":"Rate cards stored by this sync.","items":{"type":"object","properties":{"currency":{"type":"string"},"effective_from":{"type":"string","format":"date"},"rate_card_id":{"type":"integer"}}}},"failed":{"type":"array","description":"Selected eligible documents or card keys that failed, or no USD card in force today. Identity fields are null when not proved. Future cards may be stored but never replace the current Redis calculator tariff.","items":{"type":"object","properties":{"currency":{"type":["string","null"]},"effective_from":{"type":["string","null"],"format":"date"},"error":{"type":"string","enum":["DownloadFailed","UnrecognizedDocument","InvalidDocument","IncompleteDocument","DocumentTooLarge","RowMissing","NoCurrentRate"],"description":"Closed sanitized failure code, never a raw exception message, URL or host."}}}}}},"examples":{"all_stored":{"summary":"Every downloaded card was stored and the selected row exists.","value":{"ok":true,"effective_from":"2026-10-01","currency":"USD","rate_card_id":701,"synced_at":"2026-10-05T04:30:00Z","import_ok":true,"imported":[{"currency":"BRL","effective_from":"2026-07-01","rate_card_id":698},{"currency":"USD","effective_from":"2026-10-01","rate_card_id":701}],"failed":[{"currency":"BRL","effective_from":"2026-01-15","error":"DownloadFailed"}],"reason":"rate_card_import_failed"}},"partial_import":{"summary":"A stored card is selected, but another import failed.","value":{"ok":false,"effective_from":"2026-10-01","currency":"USD","rate_card_id":701,"synced_at":"2026-10-05T04:30:00Z","import_ok":false,"reason":"rate_card_import_failed","imported":[{"currency":"USD","effective_from":"2026-10-01","rate_card_id":701}],"failed":[{"currency":"BRL","effective_from":"2026-10-01","error":"InvalidDocument"}]}},"nothing_imported":{"summary":"The source was read but no rate card was imported.","value":{"ok":false,"effective_from":null,"currency":null,"rate_card_id":null,"synced_at":"2026-10-05T04:30:00Z","import_ok":false,"reason":"rate_card_import_failed","imported":[{"currency":"BRL","effective_from":"2026-01-15","rate_card_id":1}],"failed":[{"currency":"BRL","effective_from":"2026-01-15","error":"DownloadFailed"}]}},"unidentified_row":{"summary":"No stored row resolves; the failure has no proved document identity.","value":{"ok":false,"effective_from":null,"currency":null,"rate_card_id":null,"synced_at":null,"import_ok":false,"reason":"rate_card_import_failed","imported":[{"currency":"BRL","effective_from":"2026-01-15","rate_card_id":1}],"failed":[{"error":"RowMissing","currency":"BRL","effective_from":"2026-01-15"}]}},"future_only":{"summary":"A future USD card was stored, but no current USD tariff replaced the calculator cache.","value":{"ok":false,"effective_from":"2026-10-01","currency":"USD","rate_card_id":701,"synced_at":null,"import_ok":false,"reason":"rate_card_import_failed","imported":[{"currency":"USD","effective_from":"2026-10-01","rate_card_id":701}],"failed":[{"currency":"USD","effective_from":null,"error":"NoCurrentRate"}]}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"The `whatsapp_cost_center` feature is off for the account (empty body), or the `inbox_id` is outside the caller's operational scope.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Present only for a record outside the scope."}}},"example":{"error":"Resource could not be found"}}}},"403":{"description":"The caller may not read (or, for writes, manage) WhatsApp costs.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["forbidden"]}}},"example":{"error":"forbidden"}}}},"424":{"description":"The source page could not be consulted, or legacy compatibility found no eligible machine-readable source. Selected document failures are reported under 200.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["meta_unavailable"]},"reason":{"type":"string","enum":["http_error","no_rates_parsed","request_failed"],"description":"`http_error` (the source answered non-2xx), `no_rates_parsed` (no machine-readable tariff table) or `request_failed` (timeout, DNS or TLS)."}}},"example":{"error":"meta_unavailable","reason":"request_failed"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/whatsapp/cost_center/rate_cards/override":{"patch":{"tags":["WhatsApp"],"operationId":"auto_patch_api_v1_accounts_account_id_whatsapp_cost_center_rate_cards_override","summary":"Set or clear a WhatsApp tariff override","description":"Sets the account's own tariff for one Meta market and pricing category, in any ISO 4217 currency, or restores the official rate card with `rate: null`. It replaces a legacy per-country override of the same market. Requires the `whatsapp_cost_center` feature and the cost-manage permission.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The overrides after the change.","content":{"application/json":{"schema":{"type":"object","properties":{"overrides":{"type":"object","description":"The account's own tariffs per Meta market, then per pricing category. A legacy per-country USD tariff is shown under its market with `legacy_country`.","additionalProperties":{"type":"object","description":"The account's tariffs of one Meta market, keyed by pricing category.","additionalProperties":{"type":"object","properties":{"currency":{"type":"string"},"rate":{"type":["number","null"]},"legacy_country":{"type":"string","description":"ISO country of a legacy per-country override."}}}}}}},"example":{"overrides":{"Brazil":{"marketing":{"currency":"USD","rate":0.07}}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"The `whatsapp_cost_center` feature is off for the account (empty body), or the `inbox_id` is outside the caller's operational scope.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Present only for a record outside the scope."}}},"example":{"error":"Resource could not be found"}}}},"403":{"description":"The caller may not read (or, for writes, manage) WhatsApp costs.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["forbidden"]}}},"example":{"error":"forbidden"}}}},"422":{"description":"Invalid market, category, currency or rate.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["invalid_market","invalid_category","invalid_currency","invalid_rate"]}}},"example":{"error":"invalid_rate"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["market","category"],"properties":{"market":{"type":"string","description":"Meta pricing market, as named on the rate card."},"category":{"type":"string","description":"Pricing category (lowercased by the server).","enum":["marketing","utility","authentication","service"]},"currency":{"type":"string","pattern":"^[A-Za-z]{3}$","description":"ISO 4217 currency of `rate`; required when `rate` is present."},"rate":{"type":["number","null"],"minimum":0,"description":"Per-message tariff in MAJOR units; null clears the override."}}},"example":{"market":"Brazil","category":"marketing","currency":"USD","rate":0.07}}}}}},"/api/v1/accounts/{account_id}/whatsapp/cost_center/settings":{"get":{"tags":["WhatsApp"],"operationId":"auto_get_api_v1_accounts_account_id_whatsapp_cost_center_settings","summary":"Get WhatsApp cost visibility settings","description":"The account's cost visibility (and whether it is the default), the allowance opt-in and the per-inbox overrides within the caller's operational scope. Requires the `whatsapp_cost_center` feature and the cost-view permission.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The cost visibility settings.","content":{"application/json":{"schema":{"type":"object","properties":{"cost_visibility":{"type":"string","enum":["hidden","indicator","values_permitted","values_all"],"description":"What agents see about cost inside a conversation — `hidden` (nothing), `indicator` (states and counts, no values), `values_permitted` (values for those allowed to see costs) or `values_all`."},"cost_visibility_source":{"type":"string","enum":["default","account"]},"cost_visibility_options":{"type":"array","items":{"type":"string","enum":["hidden","indicator","values_permitted","values_all"]}},"default_cost_visibility":{"type":"string","enum":["hidden","indicator","values_permitted","values_all"]},"show_unconfirmed_allowance":{"type":"boolean","description":"Whether each number's estimated monthly service allowance is shown (shown unless the account hid it). Meta does not publish an allowance limit in the documentation tracked here; read `allowance.evidence`. The name is kept for compatibility."},"can_manage":{"type":"boolean"},"inbox_overrides":{"type":"array","description":"Inboxes of the caller's operational scope that override the account setting.","items":{"type":"object","properties":{"inbox_id":{"type":"integer"},"inbox_label":{"type":["string","null"]},"cost_visibility":{"type":"string","enum":["hidden","indicator","values_permitted","values_all"]}}}}}},"example":{"cost_visibility":"values_permitted","cost_visibility_source":"account","cost_visibility_options":["hidden","indicator","values_permitted","values_all"],"default_cost_visibility":"indicator","show_unconfirmed_allowance":true,"can_manage":true,"inbox_overrides":[{"inbox_id":42,"inbox_label":"Atendimento","cost_visibility":"indicator"}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"The `whatsapp_cost_center` feature is off for the account (empty body), or the `inbox_id` is outside the caller's operational scope.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Present only for a record outside the scope."}}},"example":{"error":"Resource could not be found"}}}},"403":{"description":"The caller may not read (or, for writes, manage) WhatsApp costs.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["forbidden"]}}},"example":{"error":"forbidden"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]},"patch":{"tags":["WhatsApp"],"operationId":"auto_patch_api_v1_accounts_account_id_whatsapp_cost_center_settings","summary":"Update WhatsApp cost visibility settings","description":"Without `inbox_id`, updates the account setting and/or the allowance opt-in. With `inbox_id` (an inbox of the caller's operational scope), sets that inbox's override; `cost_visibility: null` makes the inbox inherit the account again. Answers the full settings. Requires the `whatsapp_cost_center` feature and the cost-manage permission.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The cost visibility settings.","content":{"application/json":{"schema":{"type":"object","properties":{"cost_visibility":{"type":"string","enum":["hidden","indicator","values_permitted","values_all"],"description":"What agents see about cost inside a conversation — `hidden` (nothing), `indicator` (states and counts, no values), `values_permitted` (values for those allowed to see costs) or `values_all`."},"cost_visibility_source":{"type":"string","enum":["default","account"]},"cost_visibility_options":{"type":"array","items":{"type":"string","enum":["hidden","indicator","values_permitted","values_all"]}},"default_cost_visibility":{"type":"string","enum":["hidden","indicator","values_permitted","values_all"]},"show_unconfirmed_allowance":{"type":"boolean","description":"Whether each number's estimated monthly service allowance is shown (shown unless the account hid it). Meta does not publish an allowance limit in the documentation tracked here; read `allowance.evidence`. The name is kept for compatibility."},"can_manage":{"type":"boolean"},"inbox_overrides":{"type":"array","description":"Inboxes of the caller's operational scope that override the account setting.","items":{"type":"object","properties":{"inbox_id":{"type":"integer"},"inbox_label":{"type":["string","null"]},"cost_visibility":{"type":"string","enum":["hidden","indicator","values_permitted","values_all"]}}}}}},"example":{"cost_visibility":"values_permitted","cost_visibility_source":"account","cost_visibility_options":["hidden","indicator","values_permitted","values_all"],"default_cost_visibility":"indicator","show_unconfirmed_allowance":true,"can_manage":true,"inbox_overrides":[{"inbox_id":42,"inbox_label":"Atendimento","cost_visibility":"indicator"}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"The `whatsapp_cost_center` feature is off for the account (empty body), or the `inbox_id` is outside the caller's operational scope.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Present only for a record outside the scope."}}},"example":{"error":"Resource could not be found"}}}},"403":{"description":"The caller may not read (or, for writes, manage) WhatsApp costs.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["forbidden"]}}},"example":{"error":"forbidden"}}}},"422":{"description":"The visibility is not one of the allowed options.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["invalid_visibility"]}}},"example":{"error":"invalid_visibility"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"inbox_id":{"type":"integer","description":"Inbox whose override is set. Omit to update the account."},"cost_visibility":{"type":["string","null"],"enum":["hidden","indicator","values_permitted","values_all",null],"description":"New visibility; null (inbox only) restores inheritance."},"visibility":{"type":["string","null"],"enum":["hidden","indicator","values_permitted","values_all",null],"description":"Alias of `cost_visibility` for the inbox override; used only when `cost_visibility` is absent."},"show_unconfirmed_allowance":{"type":"boolean","description":"Account only — show (true) or hide (false) each number's estimated monthly service allowance; its limit is not published by Meta in the documentation tracked here. Read `allowance.evidence`."}}},"example":{"cost_visibility":"values_permitted","show_unconfirmed_allowance":true,"inbox_id":1,"visibility":"hidden"}}}}}},"/api/v1/accounts/{account_id}/whatsapp/cost_center/historical_estimates":{"post":{"tags":["WhatsApp"],"operationId":"auto_post_api_v1_accounts_account_id_whatsapp_cost_center_historical_estimates","summary":"Estimate past WhatsApp message costs","description":"Counts (with `dry_run`) or enqueues the after-the-fact estimate of messages sent before cost tracking, priced from their category and the rate card of the day. Estimates stay `unverified` with source `historical_estimate` and are never shown as confirmed charges. Requires the `whatsapp_cost_center` feature and the cost-manage permission.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The candidate count, and whether the estimate was only counted (`dry_run`) or enqueued (`enqueued`).","content":{"application/json":{"schema":{"oneOf":[{"type":"object","description":"Counted only (`dry_run` requested); nothing was enqueued.","required":["count","dry_run"],"properties":{"count":{"type":"integer"},"dry_run":{"type":"boolean","enum":[true]}}},{"type":"object","description":"The estimate was enqueued for the candidate messages.","required":["count","enqueued"],"properties":{"count":{"type":"integer"},"enqueued":{"type":"boolean","enum":[true]}}}]},"example":{"count":3,"dry_run":true}}}},"401":{"description":"Unauthorized"},"404":{"description":"The `whatsapp_cost_center` feature is off for the account (empty body), or the `inbox_id` is outside the caller's operational scope.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Present only for a record outside the scope."}}},"example":{"error":"Resource could not be found"}}}},"403":{"description":"The caller may not read (or, for writes, manage) WhatsApp costs.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["forbidden"]}}},"example":{"error":"forbidden"}}}},"422":{"description":"Invalid period, or none of the `inbox_ids` is in the caller's scope.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["invalid_period","invalid_inbox"]}}},"example":{"error":"invalid_period"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["from","to"],"properties":{"from":{"type":"string","format":"date"},"to":{"type":"string","format":"date"},"inbox_ids":{"type":"array","description":"Restrict to these inboxes of the caller's operational scope; omit for every inbox.","items":{"type":"integer"}},"dry_run":{"type":"boolean","description":"Only count the candidate messages, without enqueuing."}}},"example":{"from":"2026-09-01","to":"2026-09-30","inbox_ids":[42],"dry_run":true}}}}}},"/api/v1/accounts/{account_id}/whatsapp/outbound/inboxes/{inbox_id}/settings":{"get":{"tags":["WhatsApp"],"operationId":"auto_get_api_v1_accounts_account_id_whatsapp_outbound_inboxes_inbox_id_settings","summary":"Get the WhatsApp outbound policy of an inbox","description":"Returns the outbound optimization policy of the LOGICAL inbox: in a unified WhatsApp Cloud + WhatsApp Web (WazMeow) pair the Cloud inbox owns it and the Web inbox answers as a read-only mirror (`mirror`, `owner_inbox_id`). Every key carries its effective value and origin — `system_default`, `inbox`, or `restricted` when a disabled module flag or an inactive account forces the most restrictive value (a stored value is never deleted by a flag change). `raw` is exactly what was stored, `defaults`/`options`/`limits` describe the closed schema and `permissions.update` tells whether the caller may PATCH it now. Readable with the module flags off by whoever can see the inbox. Never exposes bot configuration, secrets or Flow endpoints.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The outbound policy of the logical inbox.","content":{"application/json":{"schema":{"type":"object","required":["inbox_id","owner_inbox_id","mirror","version","updated_at","account_active","flags","capabilities","maestro_module","permissions","effective","fields","raw","defaults","options","limits"],"properties":{"inbox_id":{"type":"integer","description":"The inbox in the path."},"owner_inbox_id":{"type":"integer","description":"The logical inbox that owns the policy (the Cloud inbox of a unified pair)."},"mirror":{"type":"boolean","description":"True when the inbox in the path is a read-only mirror of `owner_inbox_id`."},"version":{"type":"integer","minimum":0,"description":"Policy version; send it as `expected_version` on PATCH (0 while nothing was saved)."},"updated_at":{"type":["string","null"],"format":"date-time","description":"Last save, or null while nothing was saved."},"account_active":{"type":"boolean","description":"Whether the account is active (an inactive account forces the lane off)."},"flags":{"type":"object","required":["batching","maestro","rich_transform","weighted_routing"],"description":"Module flags of the account.","properties":{"batching":{"type":"boolean","description":"Fragment collection (`whatsapp_outbound_batching`)."},"maestro":{"type":"boolean","description":"Maestro transformations (`whatsapp_outbound_maestro`)."},"rich_transform":{"type":"boolean","description":"Rich formats and WhatsApp Flows (`whatsapp_outbound_rich_transform`)."},"weighted_routing":{"type":"boolean","description":"Percentage routing of hybrid pairs (`whatsapp_hybrid_weighted_routing`). It only lets an administrator configure the percentage of a pair; whether this inbox uses it is `capabilities.weighted_effective`."}}},"capabilities":{"type":"object","additionalProperties":false,"required":["weighted_effective"],"description":"What the outbound lane may do in this inbox right now, as the server decides it.","properties":{"weighted_effective":{"type":"boolean","description":"True when replies of this inbox are distributed by percentage: the account flag is on, the account is active and the inbox belongs to an enabled unified hybrid pair whose percentage routing is in `weighted` mode. Otherwise replies follow the regular route."}}},"maestro_module":{"type":"object","additionalProperties":false,"required":["restricted_by"],"description":"Whether this installation may use the Maestro transformer right now. A contract checksum or grant key mismatch with the Maestro sidecar restricts the module for every inbox: no suggestion and no approval of a candidate, and new batches follow the failure policy (send the original, or pause). The value is a short-lived shared answer; reading it never calls the sidecar.","properties":{"restricted_by":{"type":["string","null"],"enum":["contract_version_mismatch","grant_key_mismatch",null],"description":"Why the module is restricted; null when it is not restricted, not known yet, or the Maestro flag is off for the account."}}},"permissions":{"type":"object","required":["update"],"description":"What the caller may do.","properties":{"update":{"type":"boolean","description":"Whether the caller may PATCH this policy through this inbox now (false on a mirror)."}}},"effective":{"type":"object","required":["enabled","idle_seconds","max_wait_seconds","mode","on_transform_failure","allowed_agent_bot_ids","operations","formats","cta_allowed_hosts","flow_mappings","daily_budget","retention_days"],"description":"Every key of the inbox policy with the value that applies now (defaults merged; a disabled module forces its most restrictive value; only still-eligible Maestro profiles and non-revoked mappings are listed).","properties":{"enabled":{"type":"boolean","description":"Whether the lane collects fragments on this inbox."},"idle_seconds":{"type":"integer","minimum":1,"maximum":30,"description":"Seconds without a new fragment before the batch leaves."},"max_wait_seconds":{"type":"integer","minimum":1,"maximum":60,"description":"Maximum collection window from the first fragment (never below `idle_seconds`)."},"mode":{"type":"string","enum":["faithful","suggest","automatic"],"description":"Maestro mode — `faithful` (the author's consolidated text leaves as typed), `suggest` (a transformation is proposed and waits for the author) or `automatic` (an approved transformation may leave without review)."},"on_transform_failure":{"type":"string","enum":["hold","original"],"description":"When a transformation fails — `hold` (pause for the author) or `original` (send the original text)."},"allowed_agent_bot_ids":{"type":"array","maxItems":20,"description":"Allowlisted Maestro profiles (AgentBots of this account linked to Maestro).","items":{"type":"integer"}},"operations":{"type":"array","description":"Transformations Maestro may apply.","items":{"type":"string","enum":["proofread","format","structure"]}},"formats":{"type":"array","description":"Output formats a transformation may produce (always includes `text`).","items":{"type":"string","enum":["text","buttons","list","cta","whatsapp_flow"]}},"cta_allowed_hosts":{"type":"array","maxItems":20,"description":"Bare hostnames a call-to-action URL may point to when the URL is not in the reply text itself: Maestro may reuse a link the team (agent or bot) already sent in the conversation only if its host is listed here. Links sent by the contact are never used, and Maestro never makes up a link.","items":{"type":"string"}},"flow_mappings":{"type":"array","maxItems":100,"description":"WhatsApp Flow mappings Maestro and agents may use.","items":{"type":"object","description":"One immutable version of a WhatsApp Flow mapping of the inbox policy. A saved version never changes; revoking it sets `revoked` and `revoked_at` once.","required":["mapping_id","version","whatsapp_flow_id","screen","seed_schema","required_fields","digest"],"properties":{"mapping_id":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$","description":"Mapping id (versions of the same mapping share it)."},"version":{"type":"integer","minimum":1,"maximum":100000,"description":"Version of this mapping."},"whatsapp_flow_id":{"type":"integer","minimum":1,"description":"WhatsApp Flow of this account, on the inbox's Cloud channel."},"screen":{"type":"string","pattern":"^[A-Za-z0-9_]{1,128}$","description":"Screen id the Flow opens on."},"seed_schema":{"type":"object","additionalProperties":true,"description":"Data the conversion may seed on that screen: `{type: object, properties: {\u003cname\u003e: {type: string|integer|boolean, minLength?, maxLength?, enum?}}, required, additionalProperties: false}` — at most 32 flat properties."},"required_fields":{"type":"array","maxItems":50,"description":"Seed fields that must be filled.","items":{"type":"string"}},"label":{"type":"string","maxLength":120,"description":"Name shown to agents."},"intent":{"type":"string","maxLength":64,"description":"What the Flow is for (lets Maestro choose it)."},"flow_cta":{"type":"string","maxLength":20,"description":"Call-to-action text of the Flow message."},"flow_revision_digest":{"type":"string","pattern":"^[0-9a-f]{64}$","description":"Digest of the published Flow revision this mapping was built from."},"digest":{"type":"string","pattern":"^[0-9a-f]{64}$","description":"SHA-256 digest of the mapping content, stamped by the server."},"revoked":{"type":"boolean","description":"Whether this version was revoked."},"revoked_at":{"type":["string","null"],"format":"date-time","description":"When it was revoked."},"created_at":{"type":"string","format":"date-time","description":"When this version was saved."},"created_by_account_user_id":{"type":["integer","null"],"description":"Account user who saved it."}}}},"daily_budget":{"type":["object","null"],"additionalProperties":false,"required":["unit","limit"],"description":"Daily Maestro budget of the inbox, or null for none.","properties":{"unit":{"type":"string","enum":["requests","output_tokens"],"description":"What the limit counts."},"limit":{"type":"integer","minimum":0,"maximum":100000000,"description":"Daily ceiling in that unit."}}},"retention_days":{"type":"integer","minimum":1,"maximum":90,"description":"Days the text of a finished batch is kept before purge (digests and counters remain)."}}},"fields":{"type":"array","description":"Every policy key with its effective value and origin.","items":{"type":"object","required":["key","value","origin","configured","restricted_by"],"properties":{"key":{"type":"string","enum":["enabled","idle_seconds","max_wait_seconds","mode","on_transform_failure","allowed_agent_bot_ids","operations","formats","cta_allowed_hosts","flow_mappings","daily_budget","retention_days"],"description":"Policy key."},"value":{"description":"Effective value of the key (its type follows the key, as in `effective`).","anyOf":[{"type":"boolean"},{"type":"integer"},{"type":"string"},{"type":"array","items":{"anyOf":[{"type":"integer"},{"type":"string"},{"type":"object","description":"One immutable version of a WhatsApp Flow mapping of the inbox policy. A saved version never changes; revoking it sets `revoked` and `revoked_at` once.","required":["mapping_id","version","whatsapp_flow_id","screen","seed_schema","required_fields","digest"],"properties":{"mapping_id":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$","description":"Mapping id (versions of the same mapping share it)."},"version":{"type":"integer","minimum":1,"maximum":100000,"description":"Version of this mapping."},"whatsapp_flow_id":{"type":"integer","minimum":1,"description":"WhatsApp Flow of this account, on the inbox's Cloud channel."},"screen":{"type":"string","pattern":"^[A-Za-z0-9_]{1,128}$","description":"Screen id the Flow opens on."},"seed_schema":{"type":"object","additionalProperties":true,"description":"Data the conversion may seed on that screen: `{type: object, properties: {\u003cname\u003e: {type: string|integer|boolean, minLength?, maxLength?, enum?}}, required, additionalProperties: false}` — at most 32 flat properties."},"required_fields":{"type":"array","maxItems":50,"description":"Seed fields that must be filled.","items":{"type":"string"}},"label":{"type":"string","maxLength":120,"description":"Name shown to agents."},"intent":{"type":"string","maxLength":64,"description":"What the Flow is for (lets Maestro choose it)."},"flow_cta":{"type":"string","maxLength":20,"description":"Call-to-action text of the Flow message."},"flow_revision_digest":{"type":"string","pattern":"^[0-9a-f]{64}$","description":"Digest of the published Flow revision this mapping was built from."},"digest":{"type":"string","pattern":"^[0-9a-f]{64}$","description":"SHA-256 digest of the mapping content, stamped by the server."},"revoked":{"type":"boolean","description":"Whether this version was revoked."},"revoked_at":{"type":["string","null"],"format":"date-time","description":"When it was revoked."},"created_at":{"type":"string","format":"date-time","description":"When this version was saved."},"created_by_account_user_id":{"type":["integer","null"],"description":"Account user who saved it."}}}]}},{"type":["object","null"],"additionalProperties":false,"required":["unit","limit"],"description":"Daily Maestro budget of the inbox, or null for none.","properties":{"unit":{"type":"string","enum":["requests","output_tokens"],"description":"What the limit counts."},"limit":{"type":"integer","minimum":0,"maximum":100000000,"description":"Daily ceiling in that unit."}}},{"type":"null"}]},"origin":{"type":"string","enum":["system_default","inbox","restricted"],"description":"`system_default` (not configured), `inbox` (saved by an administrator) or `restricted` (forced by a disabled flag or an inactive account)."},"configured":{"type":"boolean","description":"Whether the key is stored on the policy (a stored value survives a flag change)."},"restricted_by":{"type":["string","null"],"enum":["flag_disabled",null],"description":"What forces the restrictive value, or null."}}}},"raw":{"type":"object","additionalProperties":true,"propertyNames":{"enum":["enabled","idle_seconds","max_wait_seconds","mode","on_transform_failure","allowed_agent_bot_ids","operations","formats","cta_allowed_hosts","flow_mappings","daily_budget","retention_days"]},"description":"Exactly the keys an administrator stored (sparse; a missing key inherits the system default). Values have the same shapes as in `effective`, including revoked mapping versions."},"defaults":{"type":"object","required":["enabled","idle_seconds","max_wait_seconds","mode","on_transform_failure","allowed_agent_bot_ids","operations","formats","cta_allowed_hosts","flow_mappings","daily_budget","retention_days"],"description":"System defaults of every key.","properties":{"enabled":{"type":"boolean","description":"Default false."},"idle_seconds":{"type":"integer","description":"Default 10."},"max_wait_seconds":{"type":"integer","description":"Default 30."},"mode":{"type":"string","enum":["faithful","suggest","automatic"],"description":"Maestro mode — `faithful` (the author's consolidated text leaves as typed), `suggest` (a transformation is proposed and waits for the author) or `automatic` (an approved transformation may leave without review)."},"on_transform_failure":{"type":"string","enum":["hold","original"],"description":"Default `hold`."},"allowed_agent_bot_ids":{"type":"array","description":"Default empty.","items":{"type":"integer"}},"operations":{"type":"array","description":"Default empty.","items":{"type":"string","enum":["proofread","format","structure"]}},"formats":{"type":"array","description":"Default `[text]`.","items":{"type":"string","enum":["text","buttons","list","cta","whatsapp_flow"]}},"cta_allowed_hosts":{"type":"array","description":"Default empty.","items":{"type":"string"}},"flow_mappings":{"type":"array","maxItems":0,"description":"Always empty — no mapping exists by default.","items":{"type":"object","additionalProperties":true,"description":"Never present in the defaults."}},"daily_budget":{"type":"null","description":"Default null (no budget)."},"retention_days":{"type":"integer","description":"Default 7."}}},"options":{"type":"object","required":["modes","on_transform_failure","operations","formats","budget_units"],"description":"The closed choices of the policy.","properties":{"modes":{"type":"array","description":"Maestro modes, mildest first.","items":{"type":"string","enum":["faithful","suggest","automatic"],"description":"Maestro mode — `faithful` (the author's consolidated text leaves as typed), `suggest` (a transformation is proposed and waits for the author) or `automatic` (an approved transformation may leave without review)."}},"on_transform_failure":{"type":"array","description":"Failure policies.","items":{"type":"string","enum":["hold","original"]}},"operations":{"type":"array","description":"Maestro operations.","items":{"type":"string","enum":["proofread","format","structure"]}},"formats":{"type":"array","description":"Output formats.","items":{"type":"string","enum":["text","buttons","list","cta","whatsapp_flow"]}},"budget_units":{"type":"array","description":"Daily budget units.","items":{"type":"string","enum":["requests","output_tokens"]}}}},"limits":{"type":"object","required":["idle_seconds","max_wait_seconds","retention_days","max_agent_profiles","max_cta_hosts","max_flow_mappings","flow_mapping"],"description":"Numeric bounds of the policy.","properties":{"idle_seconds":{"type":"object","required":["min","max"],"description":"Inclusive bounds.","properties":{"min":{"type":"integer","description":"Lower bound."},"max":{"type":"integer","description":"Upper bound."}}},"max_wait_seconds":{"type":"object","required":["min","max"],"description":"Inclusive bounds.","properties":{"min":{"type":"integer","description":"Lower bound."},"max":{"type":"integer","description":"Upper bound."}}},"retention_days":{"type":"object","required":["min","max"],"description":"Inclusive bounds.","properties":{"min":{"type":"integer","description":"Lower bound."},"max":{"type":"integer","description":"Upper bound."}}},"max_agent_profiles":{"type":"integer","description":"Maximum allowlisted Maestro profiles (20)."},"max_cta_hosts":{"type":"integer","description":"Maximum call-to-action hosts (20)."},"max_flow_mappings":{"type":"integer","description":"Maximum stored mapping versions (100)."},"flow_mapping":{"type":"object","required":["label_max_chars","intent_max_chars","flow_cta_max_chars"],"description":"Character limits of one WhatsApp Flow mapping, published from the same constants the server validates with, so the dashboard never hard-codes them.","properties":{"label_max_chars":{"type":"integer","description":"Maximum characters of the label the agent sees during review (100)."},"intent_max_chars":{"type":"integer","description":"Maximum characters of the \"when to suggest\" intent given to Maestro (64)."},"flow_cta_max_chars":{"type":"integer","description":"Maximum characters of the button text that opens the WhatsApp Flow (20)."}}}}}}},"example":{"inbox_id":17,"owner_inbox_id":17,"mirror":false,"version":3,"updated_at":"2026-09-29T13:58:04Z","account_active":true,"flags":{"batching":true,"maestro":true,"rich_transform":true,"weighted_routing":true},"capabilities":{"weighted_effective":true},"maestro_module":{"restricted_by":null},"permissions":{"update":true},"effective":{"enabled":true,"idle_seconds":10,"max_wait_seconds":30,"mode":"suggest","on_transform_failure":"hold","allowed_agent_bot_ids":[12],"operations":["proofread","format"],"formats":["text","buttons","whatsapp_flow"],"cta_allowed_hosts":["loja.example.com"],"flow_mappings":[{"mapping_id":"agendar-visita","version":2,"whatsapp_flow_id":5,"screen":"AGENDAMENTO","seed_schema":{"type":"object","properties":{"nome":{"type":"string","maxLength":80}},"required":["nome"],"additionalProperties":false},"required_fields":["nome"],"label":"Agendar visita","intent":"schedule_visit","flow_cta":"Agendar","flow_revision_digest":"6e5bbd34b46e2d73889dec0ac0868fe13be924010c93009023664f4f46027bbe","digest":"e45805152393fb5601be8835339f62b942a9f1d01e7bbeef0b22e8d089ddc1fa","revoked":false,"revoked_at":null,"created_at":"2026-09-28T19:40:11.000Z","created_by_account_user_id":31}],"daily_budget":{"unit":"requests","limit":500},"retention_days":7},"fields":[{"key":"mode","value":"suggest","origin":"inbox","configured":true,"restricted_by":null}],"raw":{"enabled":true,"mode":"suggest","allowed_agent_bot_ids":[12],"operations":["proofread","format"],"formats":["text","buttons","whatsapp_flow"],"cta_allowed_hosts":["loja.example.com"],"flow_mappings":[{"mapping_id":"agendar-visita","version":2,"whatsapp_flow_id":5,"screen":"AGENDAMENTO","seed_schema":{"type":"object","properties":{"nome":{"type":"string","maxLength":80}},"required":["nome"],"additionalProperties":false},"required_fields":["nome"],"label":"Agendar visita","intent":"schedule_visit","flow_cta":"Agendar","flow_revision_digest":"6e5bbd34b46e2d73889dec0ac0868fe13be924010c93009023664f4f46027bbe","digest":"e45805152393fb5601be8835339f62b942a9f1d01e7bbeef0b22e8d089ddc1fa","revoked":false,"revoked_at":null,"created_at":"2026-09-28T19:40:11.000Z","created_by_account_user_id":31}],"daily_budget":{"unit":"requests","limit":500}},"defaults":{"enabled":false,"idle_seconds":10,"max_wait_seconds":30,"mode":"faithful","on_transform_failure":"hold","allowed_agent_bot_ids":[],"operations":[],"formats":["text"],"cta_allowed_hosts":[],"flow_mappings":[],"daily_budget":null,"retention_days":7},"options":{"modes":["faithful","suggest","automatic"],"on_transform_failure":["hold","original"],"operations":["proofread","format","structure"],"formats":["text","buttons","list","cta","whatsapp_flow"],"budget_units":["requests","output_tokens"]},"limits":{"idle_seconds":{"min":1,"max":30},"max_wait_seconds":{"min":1,"max":60},"retention_days":{"min":1,"max":90},"max_agent_profiles":20,"max_cta_hosts":20,"max_flow_mappings":100,"flow_mapping":{"label_max_chars":100,"intent_max_chars":64,"flow_cta_max_chars":20}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"The inbox does not exist in this account (generic lookup failure), or it is not a WhatsApp inbox this feature can configure (`inbox_not_supported`).","content":{"application/json":{"schema":{"anyOf":[{"type":"object","additionalProperties":false,"required":["error"],"description":"The inbox is not a WhatsApp inbox this lane serves (or the conversation is a WhatsApp group).","properties":{"error":{"type":"string","enum":["inbox_not_supported"],"description":"Stable code."}}},{"type":"object","additionalProperties":false,"required":["error"],"description":"Generic lookup failure of the account API (the conversation or inbox does not exist in this account).","properties":{"error":{"type":"string","description":"Human-readable lookup failure (\"Resource could not be found\")."}}}]},"example":{"error":"inbox_not_supported"}}}},"403":{"description":"The caller may not read (or, for writes, change) this outbound configuration.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","enum":["forbidden"],"description":"Policy refusal."}}},"example":{"error":"forbidden"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"in":"path","name":"inbox_id","required":true,"description":"Inbox id in the account; the Web inbox of a unified pair resolves to its Cloud owner.","schema":{"type":"integer"}}]},"patch":{"tags":["WhatsApp"],"operationId":"auto_patch_api_v1_accounts_account_id_whatsapp_outbound_inboxes_inbox_id_settings","summary":"Update the WhatsApp outbound policy of an inbox","description":"Sparse update of the logical inbox policy under optimistic locking: send `expected_version` (0 before the first save) and only the keys to change; a key set to null restores the system default. Unknown keys are refused with 422 `unknown_field`. Needs the `whatsapp_outbound_batching` flag and inbox update permission, and only the owner of a unified pair accepts writes (the Web mirror answers `configuration_owned_by_logical_inbox`). Maestro keys (`mode`, `on_transform_failure`, `allowed_agent_bot_ids`, `operations`, `daily_budget`) and rich keys (`formats`, `cta_allowed_hosts`, `flow_mappings`) need their own flag unless the change only restricts. Switching INTO `automatic` requires `automatic_consent: true` in the same request (audited opt-in). Flow mappings are append-only versions — send a new one with `whatsapp_flow_id` + `screen` (the server builds the seed schema from the published Flow and assigns `mapping_id`/`version`), revoke a saved one with `mapping_id` + `version` + `revoked: true`; saved versions omitted from the request are kept. Every save is audited.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The outbound policy of the logical inbox.","content":{"application/json":{"schema":{"type":"object","required":["inbox_id","owner_inbox_id","mirror","version","updated_at","account_active","flags","capabilities","maestro_module","permissions","effective","fields","raw","defaults","options","limits"],"properties":{"inbox_id":{"type":"integer","description":"The inbox in the path."},"owner_inbox_id":{"type":"integer","description":"The logical inbox that owns the policy (the Cloud inbox of a unified pair)."},"mirror":{"type":"boolean","description":"True when the inbox in the path is a read-only mirror of `owner_inbox_id`."},"version":{"type":"integer","minimum":0,"description":"Policy version; send it as `expected_version` on PATCH (0 while nothing was saved)."},"updated_at":{"type":["string","null"],"format":"date-time","description":"Last save, or null while nothing was saved."},"account_active":{"type":"boolean","description":"Whether the account is active (an inactive account forces the lane off)."},"flags":{"type":"object","required":["batching","maestro","rich_transform","weighted_routing"],"description":"Module flags of the account.","properties":{"batching":{"type":"boolean","description":"Fragment collection (`whatsapp_outbound_batching`)."},"maestro":{"type":"boolean","description":"Maestro transformations (`whatsapp_outbound_maestro`)."},"rich_transform":{"type":"boolean","description":"Rich formats and WhatsApp Flows (`whatsapp_outbound_rich_transform`)."},"weighted_routing":{"type":"boolean","description":"Percentage routing of hybrid pairs (`whatsapp_hybrid_weighted_routing`). It only lets an administrator configure the percentage of a pair; whether this inbox uses it is `capabilities.weighted_effective`."}}},"capabilities":{"type":"object","additionalProperties":false,"required":["weighted_effective"],"description":"What the outbound lane may do in this inbox right now, as the server decides it.","properties":{"weighted_effective":{"type":"boolean","description":"True when replies of this inbox are distributed by percentage: the account flag is on, the account is active and the inbox belongs to an enabled unified hybrid pair whose percentage routing is in `weighted` mode. Otherwise replies follow the regular route."}}},"maestro_module":{"type":"object","additionalProperties":false,"required":["restricted_by"],"description":"Whether this installation may use the Maestro transformer right now. A contract checksum or grant key mismatch with the Maestro sidecar restricts the module for every inbox: no suggestion and no approval of a candidate, and new batches follow the failure policy (send the original, or pause). The value is a short-lived shared answer; reading it never calls the sidecar.","properties":{"restricted_by":{"type":["string","null"],"enum":["contract_version_mismatch","grant_key_mismatch",null],"description":"Why the module is restricted; null when it is not restricted, not known yet, or the Maestro flag is off for the account."}}},"permissions":{"type":"object","required":["update"],"description":"What the caller may do.","properties":{"update":{"type":"boolean","description":"Whether the caller may PATCH this policy through this inbox now (false on a mirror)."}}},"effective":{"type":"object","required":["enabled","idle_seconds","max_wait_seconds","mode","on_transform_failure","allowed_agent_bot_ids","operations","formats","cta_allowed_hosts","flow_mappings","daily_budget","retention_days"],"description":"Every key of the inbox policy with the value that applies now (defaults merged; a disabled module forces its most restrictive value; only still-eligible Maestro profiles and non-revoked mappings are listed).","properties":{"enabled":{"type":"boolean","description":"Whether the lane collects fragments on this inbox."},"idle_seconds":{"type":"integer","minimum":1,"maximum":30,"description":"Seconds without a new fragment before the batch leaves."},"max_wait_seconds":{"type":"integer","minimum":1,"maximum":60,"description":"Maximum collection window from the first fragment (never below `idle_seconds`)."},"mode":{"type":"string","enum":["faithful","suggest","automatic"],"description":"Maestro mode — `faithful` (the author's consolidated text leaves as typed), `suggest` (a transformation is proposed and waits for the author) or `automatic` (an approved transformation may leave without review)."},"on_transform_failure":{"type":"string","enum":["hold","original"],"description":"When a transformation fails — `hold` (pause for the author) or `original` (send the original text)."},"allowed_agent_bot_ids":{"type":"array","maxItems":20,"description":"Allowlisted Maestro profiles (AgentBots of this account linked to Maestro).","items":{"type":"integer"}},"operations":{"type":"array","description":"Transformations Maestro may apply.","items":{"type":"string","enum":["proofread","format","structure"]}},"formats":{"type":"array","description":"Output formats a transformation may produce (always includes `text`).","items":{"type":"string","enum":["text","buttons","list","cta","whatsapp_flow"]}},"cta_allowed_hosts":{"type":"array","maxItems":20,"description":"Bare hostnames a call-to-action URL may point to when the URL is not in the reply text itself: Maestro may reuse a link the team (agent or bot) already sent in the conversation only if its host is listed here. Links sent by the contact are never used, and Maestro never makes up a link.","items":{"type":"string"}},"flow_mappings":{"type":"array","maxItems":100,"description":"WhatsApp Flow mappings Maestro and agents may use.","items":{"type":"object","description":"One immutable version of a WhatsApp Flow mapping of the inbox policy. A saved version never changes; revoking it sets `revoked` and `revoked_at` once.","required":["mapping_id","version","whatsapp_flow_id","screen","seed_schema","required_fields","digest"],"properties":{"mapping_id":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$","description":"Mapping id (versions of the same mapping share it)."},"version":{"type":"integer","minimum":1,"maximum":100000,"description":"Version of this mapping."},"whatsapp_flow_id":{"type":"integer","minimum":1,"description":"WhatsApp Flow of this account, on the inbox's Cloud channel."},"screen":{"type":"string","pattern":"^[A-Za-z0-9_]{1,128}$","description":"Screen id the Flow opens on."},"seed_schema":{"type":"object","additionalProperties":true,"description":"Data the conversion may seed on that screen: `{type: object, properties: {\u003cname\u003e: {type: string|integer|boolean, minLength?, maxLength?, enum?}}, required, additionalProperties: false}` — at most 32 flat properties."},"required_fields":{"type":"array","maxItems":50,"description":"Seed fields that must be filled.","items":{"type":"string"}},"label":{"type":"string","maxLength":120,"description":"Name shown to agents."},"intent":{"type":"string","maxLength":64,"description":"What the Flow is for (lets Maestro choose it)."},"flow_cta":{"type":"string","maxLength":20,"description":"Call-to-action text of the Flow message."},"flow_revision_digest":{"type":"string","pattern":"^[0-9a-f]{64}$","description":"Digest of the published Flow revision this mapping was built from."},"digest":{"type":"string","pattern":"^[0-9a-f]{64}$","description":"SHA-256 digest of the mapping content, stamped by the server."},"revoked":{"type":"boolean","description":"Whether this version was revoked."},"revoked_at":{"type":["string","null"],"format":"date-time","description":"When it was revoked."},"created_at":{"type":"string","format":"date-time","description":"When this version was saved."},"created_by_account_user_id":{"type":["integer","null"],"description":"Account user who saved it."}}}},"daily_budget":{"type":["object","null"],"additionalProperties":false,"required":["unit","limit"],"description":"Daily Maestro budget of the inbox, or null for none.","properties":{"unit":{"type":"string","enum":["requests","output_tokens"],"description":"What the limit counts."},"limit":{"type":"integer","minimum":0,"maximum":100000000,"description":"Daily ceiling in that unit."}}},"retention_days":{"type":"integer","minimum":1,"maximum":90,"description":"Days the text of a finished batch is kept before purge (digests and counters remain)."}}},"fields":{"type":"array","description":"Every policy key with its effective value and origin.","items":{"type":"object","required":["key","value","origin","configured","restricted_by"],"properties":{"key":{"type":"string","enum":["enabled","idle_seconds","max_wait_seconds","mode","on_transform_failure","allowed_agent_bot_ids","operations","formats","cta_allowed_hosts","flow_mappings","daily_budget","retention_days"],"description":"Policy key."},"value":{"description":"Effective value of the key (its type follows the key, as in `effective`).","anyOf":[{"type":"boolean"},{"type":"integer"},{"type":"string"},{"type":"array","items":{"anyOf":[{"type":"integer"},{"type":"string"},{"type":"object","description":"One immutable version of a WhatsApp Flow mapping of the inbox policy. A saved version never changes; revoking it sets `revoked` and `revoked_at` once.","required":["mapping_id","version","whatsapp_flow_id","screen","seed_schema","required_fields","digest"],"properties":{"mapping_id":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$","description":"Mapping id (versions of the same mapping share it)."},"version":{"type":"integer","minimum":1,"maximum":100000,"description":"Version of this mapping."},"whatsapp_flow_id":{"type":"integer","minimum":1,"description":"WhatsApp Flow of this account, on the inbox's Cloud channel."},"screen":{"type":"string","pattern":"^[A-Za-z0-9_]{1,128}$","description":"Screen id the Flow opens on."},"seed_schema":{"type":"object","additionalProperties":true,"description":"Data the conversion may seed on that screen: `{type: object, properties: {\u003cname\u003e: {type: string|integer|boolean, minLength?, maxLength?, enum?}}, required, additionalProperties: false}` — at most 32 flat properties."},"required_fields":{"type":"array","maxItems":50,"description":"Seed fields that must be filled.","items":{"type":"string"}},"label":{"type":"string","maxLength":120,"description":"Name shown to agents."},"intent":{"type":"string","maxLength":64,"description":"What the Flow is for (lets Maestro choose it)."},"flow_cta":{"type":"string","maxLength":20,"description":"Call-to-action text of the Flow message."},"flow_revision_digest":{"type":"string","pattern":"^[0-9a-f]{64}$","description":"Digest of the published Flow revision this mapping was built from."},"digest":{"type":"string","pattern":"^[0-9a-f]{64}$","description":"SHA-256 digest of the mapping content, stamped by the server."},"revoked":{"type":"boolean","description":"Whether this version was revoked."},"revoked_at":{"type":["string","null"],"format":"date-time","description":"When it was revoked."},"created_at":{"type":"string","format":"date-time","description":"When this version was saved."},"created_by_account_user_id":{"type":["integer","null"],"description":"Account user who saved it."}}}]}},{"type":["object","null"],"additionalProperties":false,"required":["unit","limit"],"description":"Daily Maestro budget of the inbox, or null for none.","properties":{"unit":{"type":"string","enum":["requests","output_tokens"],"description":"What the limit counts."},"limit":{"type":"integer","minimum":0,"maximum":100000000,"description":"Daily ceiling in that unit."}}},{"type":"null"}]},"origin":{"type":"string","enum":["system_default","inbox","restricted"],"description":"`system_default` (not configured), `inbox` (saved by an administrator) or `restricted` (forced by a disabled flag or an inactive account)."},"configured":{"type":"boolean","description":"Whether the key is stored on the policy (a stored value survives a flag change)."},"restricted_by":{"type":["string","null"],"enum":["flag_disabled",null],"description":"What forces the restrictive value, or null."}}}},"raw":{"type":"object","additionalProperties":true,"propertyNames":{"enum":["enabled","idle_seconds","max_wait_seconds","mode","on_transform_failure","allowed_agent_bot_ids","operations","formats","cta_allowed_hosts","flow_mappings","daily_budget","retention_days"]},"description":"Exactly the keys an administrator stored (sparse; a missing key inherits the system default). Values have the same shapes as in `effective`, including revoked mapping versions."},"defaults":{"type":"object","required":["enabled","idle_seconds","max_wait_seconds","mode","on_transform_failure","allowed_agent_bot_ids","operations","formats","cta_allowed_hosts","flow_mappings","daily_budget","retention_days"],"description":"System defaults of every key.","properties":{"enabled":{"type":"boolean","description":"Default false."},"idle_seconds":{"type":"integer","description":"Default 10."},"max_wait_seconds":{"type":"integer","description":"Default 30."},"mode":{"type":"string","enum":["faithful","suggest","automatic"],"description":"Maestro mode — `faithful` (the author's consolidated text leaves as typed), `suggest` (a transformation is proposed and waits for the author) or `automatic` (an approved transformation may leave without review)."},"on_transform_failure":{"type":"string","enum":["hold","original"],"description":"Default `hold`."},"allowed_agent_bot_ids":{"type":"array","description":"Default empty.","items":{"type":"integer"}},"operations":{"type":"array","description":"Default empty.","items":{"type":"string","enum":["proofread","format","structure"]}},"formats":{"type":"array","description":"Default `[text]`.","items":{"type":"string","enum":["text","buttons","list","cta","whatsapp_flow"]}},"cta_allowed_hosts":{"type":"array","description":"Default empty.","items":{"type":"string"}},"flow_mappings":{"type":"array","maxItems":0,"description":"Always empty — no mapping exists by default.","items":{"type":"object","additionalProperties":true,"description":"Never present in the defaults."}},"daily_budget":{"type":"null","description":"Default null (no budget)."},"retention_days":{"type":"integer","description":"Default 7."}}},"options":{"type":"object","required":["modes","on_transform_failure","operations","formats","budget_units"],"description":"The closed choices of the policy.","properties":{"modes":{"type":"array","description":"Maestro modes, mildest first.","items":{"type":"string","enum":["faithful","suggest","automatic"],"description":"Maestro mode — `faithful` (the author's consolidated text leaves as typed), `suggest` (a transformation is proposed and waits for the author) or `automatic` (an approved transformation may leave without review)."}},"on_transform_failure":{"type":"array","description":"Failure policies.","items":{"type":"string","enum":["hold","original"]}},"operations":{"type":"array","description":"Maestro operations.","items":{"type":"string","enum":["proofread","format","structure"]}},"formats":{"type":"array","description":"Output formats.","items":{"type":"string","enum":["text","buttons","list","cta","whatsapp_flow"]}},"budget_units":{"type":"array","description":"Daily budget units.","items":{"type":"string","enum":["requests","output_tokens"]}}}},"limits":{"type":"object","required":["idle_seconds","max_wait_seconds","retention_days","max_agent_profiles","max_cta_hosts","max_flow_mappings","flow_mapping"],"description":"Numeric bounds of the policy.","properties":{"idle_seconds":{"type":"object","required":["min","max"],"description":"Inclusive bounds.","properties":{"min":{"type":"integer","description":"Lower bound."},"max":{"type":"integer","description":"Upper bound."}}},"max_wait_seconds":{"type":"object","required":["min","max"],"description":"Inclusive bounds.","properties":{"min":{"type":"integer","description":"Lower bound."},"max":{"type":"integer","description":"Upper bound."}}},"retention_days":{"type":"object","required":["min","max"],"description":"Inclusive bounds.","properties":{"min":{"type":"integer","description":"Lower bound."},"max":{"type":"integer","description":"Upper bound."}}},"max_agent_profiles":{"type":"integer","description":"Maximum allowlisted Maestro profiles (20)."},"max_cta_hosts":{"type":"integer","description":"Maximum call-to-action hosts (20)."},"max_flow_mappings":{"type":"integer","description":"Maximum stored mapping versions (100)."},"flow_mapping":{"type":"object","required":["label_max_chars","intent_max_chars","flow_cta_max_chars"],"description":"Character limits of one WhatsApp Flow mapping, published from the same constants the server validates with, so the dashboard never hard-codes them.","properties":{"label_max_chars":{"type":"integer","description":"Maximum characters of the label the agent sees during review (100)."},"intent_max_chars":{"type":"integer","description":"Maximum characters of the \"when to suggest\" intent given to Maestro (64)."},"flow_cta_max_chars":{"type":"integer","description":"Maximum characters of the button text that opens the WhatsApp Flow (20)."}}}}}}},"example":{"inbox_id":17,"owner_inbox_id":17,"mirror":false,"version":3,"updated_at":"2026-09-29T13:58:04Z","account_active":true,"flags":{"batching":true,"maestro":true,"rich_transform":true,"weighted_routing":true},"capabilities":{"weighted_effective":true},"maestro_module":{"restricted_by":null},"permissions":{"update":true},"effective":{"enabled":true,"idle_seconds":10,"max_wait_seconds":30,"mode":"suggest","on_transform_failure":"hold","allowed_agent_bot_ids":[12],"operations":["proofread","format"],"formats":["text","buttons","whatsapp_flow"],"cta_allowed_hosts":["loja.example.com"],"flow_mappings":[{"mapping_id":"agendar-visita","version":2,"whatsapp_flow_id":5,"screen":"AGENDAMENTO","seed_schema":{"type":"object","properties":{"nome":{"type":"string","maxLength":80}},"required":["nome"],"additionalProperties":false},"required_fields":["nome"],"label":"Agendar visita","intent":"schedule_visit","flow_cta":"Agendar","flow_revision_digest":"6e5bbd34b46e2d73889dec0ac0868fe13be924010c93009023664f4f46027bbe","digest":"e45805152393fb5601be8835339f62b942a9f1d01e7bbeef0b22e8d089ddc1fa","revoked":false,"revoked_at":null,"created_at":"2026-09-28T19:40:11.000Z","created_by_account_user_id":31}],"daily_budget":{"unit":"requests","limit":500},"retention_days":7},"fields":[{"key":"mode","value":"suggest","origin":"inbox","configured":true,"restricted_by":null}],"raw":{"enabled":true,"mode":"suggest","allowed_agent_bot_ids":[12],"operations":["proofread","format"],"formats":["text","buttons","whatsapp_flow"],"cta_allowed_hosts":["loja.example.com"],"flow_mappings":[{"mapping_id":"agendar-visita","version":2,"whatsapp_flow_id":5,"screen":"AGENDAMENTO","seed_schema":{"type":"object","properties":{"nome":{"type":"string","maxLength":80}},"required":["nome"],"additionalProperties":false},"required_fields":["nome"],"label":"Agendar visita","intent":"schedule_visit","flow_cta":"Agendar","flow_revision_digest":"6e5bbd34b46e2d73889dec0ac0868fe13be924010c93009023664f4f46027bbe","digest":"e45805152393fb5601be8835339f62b942a9f1d01e7bbeef0b22e8d089ddc1fa","revoked":false,"revoked_at":null,"created_at":"2026-09-28T19:40:11.000Z","created_by_account_user_id":31}],"daily_budget":{"unit":"requests","limit":500}},"defaults":{"enabled":false,"idle_seconds":10,"max_wait_seconds":30,"mode":"faithful","on_transform_failure":"hold","allowed_agent_bot_ids":[],"operations":[],"formats":["text"],"cta_allowed_hosts":[],"flow_mappings":[],"daily_budget":null,"retention_days":7},"options":{"modes":["faithful","suggest","automatic"],"on_transform_failure":["hold","original"],"operations":["proofread","format","structure"],"formats":["text","buttons","list","cta","whatsapp_flow"],"budget_units":["requests","output_tokens"]},"limits":{"idle_seconds":{"min":1,"max":30},"max_wait_seconds":{"min":1,"max":60},"retention_days":{"min":1,"max":90},"max_agent_profiles":20,"max_cta_hosts":20,"max_flow_mappings":100,"flow_mapping":{"label_max_chars":100,"intent_max_chars":64,"flow_cta_max_chars":20}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"The inbox does not exist in this account (generic lookup failure), it is not a WhatsApp inbox this feature can configure (`inbox_not_supported`), or the batching module flag is off (`feature_disabled`).","content":{"application/json":{"schema":{"anyOf":[{"type":"object","additionalProperties":false,"required":["error"],"description":"The inbox is not a WhatsApp inbox this lane serves (or the conversation is a WhatsApp group).","properties":{"error":{"type":"string","enum":["inbox_not_supported"],"description":"Stable code."}}},{"type":"object","additionalProperties":false,"required":["error","feature"],"description":"Writes need the batching module flag; reads stay available.","properties":{"error":{"type":"string","enum":["feature_disabled"],"description":"Stable code."},"feature":{"type":"string","enum":["whatsapp_outbound_batching"],"description":"The flag that must be on."}}},{"type":"object","additionalProperties":false,"required":["error"],"description":"Generic lookup failure of the account API (the conversation or inbox does not exist in this account).","properties":{"error":{"type":"string","description":"Human-readable lookup failure (\"Resource could not be found\")."}}}]},"example":{"error":"feature_disabled","feature":"whatsapp_outbound_batching"}}}},"403":{"description":"The caller may not read (or, for writes, change) this outbound configuration.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","enum":["forbidden"],"description":"Policy refusal."}}},"example":{"error":"forbidden"}}}},"409":{"description":"`expected_version` differs from the stored version (0 means \"no row yet\"), including two concurrent FIRST writes where the other one created the row; re-read and retry.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error","current_version"],"properties":{"error":{"type":"string","enum":["configuration_version_conflict"],"description":"Stable code."},"current_version":{"type":"integer","minimum":0,"description":"The version stored now."}}},"example":{"error":"configuration_version_conflict","current_version":3}}}},"422":{"description":"`invalid_configuration` with field errors (`required`, `invalid_type`, `unknown_field`, `not_allowed`, `out_of_range`, a flag-gated key widened while its flag is off (`feature_disabled`), automatic mode without consent, mapping version rules, a Flow that cannot be mapped — `flow_not_eligible` with its closed `reason` — and the other codes listed), or `configuration_owned_by_logical_inbox` when the inbox is a unified pair's read-only Web mirror.","content":{"application/json":{"schema":{"anyOf":[{"type":"object","additionalProperties":false,"required":["error","errors"],"properties":{"error":{"type":"string","enum":["invalid_configuration"],"description":"Stable code."},"errors":{"type":"array","minItems":1,"description":"Field errors.","items":{"type":"object","additionalProperties":false,"required":["field","code"],"properties":{"field":{"type":"string","description":"Policy key or path (e.g. `max_wait_seconds`, `flow_mappings/0`, `expected_version`)."},"code":{"type":"string","pattern":"^[a-z][a-z0-9_]*$","description":"Stable validation code. Policy codes: required, invalid_type, unknown_field, not_allowed, invalid_format, duplicate, out_of_range, invalid, taken, feature_disabled, automatic_consent_required, less_than_idle_seconds, required_for_mode, must_include_text, duplicate_version, digest_mismatch, revocation_incomplete, version_removed, version_immutable, revocation_irreversible, unknown_whatsapp_flow, not_eligible, seed_schema_too_large, seed_schema_invalid, flow_not_eligible, flow_mapping_unbuildable. A NEW `flow_mappings` version is also validated by the WhatsApp Flow catalog parser, whose codes are per key and open-ended (`\u003ckey\u003e_required`, `\u003ckey\u003e_invalid`, `seed_schema_\u003creason\u003e`, `required_fields_*`), e.g. required_fields_not_in_seed_schema, required_fields_duplicated, label_invalid, intent_invalid, flow_cta_invalid. Clients translate the codes they know and fall back to a generic message for the rest.","examples":["out_of_range","required_fields_not_in_seed_schema","flow_cta_invalid"]},"reason":{"type":"string","enum":["screen_invalid","screen_missing","flow_missing","flow_not_published","flow_meta_id_missing","cloud_capability_unavailable","mapping_id_invalid","label_invalid","intent_invalid","flow_cta_invalid","screen_data_unsupported"],"description":"Closed detail of a `flow_not_eligible` mapping error (absent otherwise)."}}}}}},{"type":"object","additionalProperties":false,"required":["error","owner_inbox_id"],"properties":{"error":{"type":"string","enum":["configuration_owned_by_logical_inbox"],"description":"Stable code."},"owner_inbox_id":{"type":"integer","description":"The Cloud inbox that accepts writes for this pair."}}}]},"example":{"error":"invalid_configuration","errors":[{"field":"flow_mappings/0","code":"flow_not_eligible","reason":"flow_not_published"}]}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"in":"path","name":"inbox_id","required":true,"description":"Inbox id in the account (a unified pair's Web inbox is read-only).","schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["expected_version","settings"],"properties":{"expected_version":{"type":"integer","minimum":0,"description":"The `version` last read (0 when no policy was saved yet)."},"automatic_consent":{"type":"boolean","description":"Required as true when this request switches `mode` into `automatic`."},"settings":{"type":"object","additionalProperties":false,"description":"Keys to change (sparse). Null restores the system default of that key.","properties":{"enabled":{"type":["boolean","null"],"description":"Turn fragment collection on or off for this inbox."},"idle_seconds":{"type":["integer","null"],"minimum":1,"maximum":30,"description":"Idle seconds before a batch leaves."},"max_wait_seconds":{"type":["integer","null"],"minimum":1,"maximum":60,"description":"Maximum collection window (must be at least `idle_seconds`)."},"mode":{"type":["string","null"],"enum":["faithful","suggest","automatic",null],"description":"Maestro mode (`suggest`/`automatic` need at least one operation and one allowlisted profile)."},"on_transform_failure":{"type":["string","null"],"enum":["hold","original",null],"description":"What to do when a transformation fails."},"allowed_agent_bot_ids":{"type":["array","null"],"maxItems":20,"description":"AgentBots of this account linked to Maestro.","items":{"type":"integer","minimum":1}},"operations":{"type":["array","null"],"description":"Operations Maestro may apply.","items":{"type":"string","enum":["proofread","format","structure"]}},"formats":{"type":["array","null"],"description":"Allowed output formats (must include `text`).","items":{"type":"string","enum":["text","buttons","list","cta","whatsapp_flow"]}},"cta_allowed_hosts":{"type":["array","null"],"maxItems":20,"description":"Bare hostnames (no scheme, port, path or wildcard).","items":{"type":"string","maxLength":253}},"flow_mappings":{"type":["array","null"],"maxItems":100,"description":"Mapping versions to add or revoke. Null is ignored for this key (saved versions are never deleted).","items":{"anyOf":[{"type":"object","title":"New version built from the published Flow","required":["whatsapp_flow_id","screen"],"properties":{"mapping_id":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$","description":"Mapping to version (derived as `flow-\u003cwhatsapp_flow_id\u003e-\u003cscreen\u003e` when absent)."},"whatsapp_flow_id":{"type":"integer","minimum":1,"description":"A published WhatsApp Flow of this account on the inbox's Cloud channel."},"screen":{"type":"string","pattern":"^[A-Za-z0-9_]{1,128}$","description":"Screen id the Flow opens on."},"label":{"type":"string","maxLength":120,"description":"Name shown to agents."},"intent":{"type":"string","maxLength":64,"description":"What the Flow is for."},"flow_cta":{"type":"string","maxLength":20,"description":"Call-to-action text (no emoji)."}}},{"type":"object","title":"New version with an explicit seed schema","required":["whatsapp_flow_id","screen","seed_schema","required_fields"],"properties":{"mapping_id":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$","description":"Mapping to version."},"whatsapp_flow_id":{"type":"integer","minimum":1,"description":"WhatsApp Flow of this account on the inbox's Cloud channel."},"screen":{"type":"string","pattern":"^[A-Za-z0-9_]{1,128}$","description":"Screen id."},"label":{"type":"string","maxLength":120,"description":"Name shown to agents."},"intent":{"type":"string","maxLength":64,"description":"What the Flow is for."},"flow_cta":{"type":"string","maxLength":20,"description":"Call-to-action text."},"seed_schema":{"type":"object","additionalProperties":true,"description":"The flat seed schema subset (validated; the published Flow is not read)."},"required_fields":{"type":"array","description":"Seed fields that must be filled.","items":{"type":"string"}},"flow_revision_digest":{"type":"string","pattern":"^[0-9a-f]{64}$","description":"Digest of the Flow revision the schema was taken from."}}},{"type":"object","title":"Saved version (kept or revoked)","required":["mapping_id","version"],"properties":{"mapping_id":{"type":"string","description":"Saved mapping id."},"version":{"type":"integer","minimum":1,"description":"Saved version; its content cannot change."},"revoked":{"type":"boolean","description":"True revokes this version (irreversible)."}}}]}},"daily_budget":{"type":["object","null"],"additionalProperties":false,"required":["unit","limit"],"description":"Daily Maestro budget of the inbox, or null for none.","properties":{"unit":{"type":"string","enum":["requests","output_tokens"],"description":"What the limit counts."},"limit":{"type":"integer","minimum":0,"maximum":100000000,"description":"Daily ceiling in that unit."}}},"retention_days":{"type":["integer","null"],"minimum":1,"maximum":90,"description":"Days a finished batch's text is kept."}}}}},"example":{"expected_version":2,"automatic_consent":false,"settings":{"enabled":true,"idle_seconds":10,"max_wait_seconds":30,"mode":"suggest","on_transform_failure":"hold","allowed_agent_bot_ids":[12],"operations":["proofread","format"],"formats":["text","buttons","whatsapp_flow"],"cta_allowed_hosts":["loja.example.com"],"flow_mappings":[{"mapping_id":"agendar-visita","whatsapp_flow_id":5,"screen":"AGENDAMENTO","label":"Agendar visita","intent":"schedule_visit","flow_cta":"Agendar"}],"daily_budget":{"unit":"requests","limit":500},"retention_days":7}}}}}},"put":{"tags":["WhatsApp"],"operationId":"auto_put_api_v1_accounts_account_id_whatsapp_outbound_inboxes_inbox_id_settings","summary":"Update the WhatsApp outbound policy of an inbox","description":"Sparse update of the logical inbox policy under optimistic locking: send `expected_version` (0 before the first save) and only the keys to change; a key set to null restores the system default. Unknown keys are refused with 422 `unknown_field`. Needs the `whatsapp_outbound_batching` flag and inbox update permission, and only the owner of a unified pair accepts writes (the Web mirror answers `configuration_owned_by_logical_inbox`). Maestro keys (`mode`, `on_transform_failure`, `allowed_agent_bot_ids`, `operations`, `daily_budget`) and rich keys (`formats`, `cta_allowed_hosts`, `flow_mappings`) need their own flag unless the change only restricts. Switching INTO `automatic` requires `automatic_consent: true` in the same request (audited opt-in). Flow mappings are append-only versions — send a new one with `whatsapp_flow_id` + `screen` (the server builds the seed schema from the published Flow and assigns `mapping_id`/`version`), revoke a saved one with `mapping_id` + `version` + `revoked: true`; saved versions omitted from the request are kept. Every save is audited.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The outbound policy of the logical inbox.","content":{"application/json":{"schema":{"type":"object","required":["inbox_id","owner_inbox_id","mirror","version","updated_at","account_active","flags","capabilities","maestro_module","permissions","effective","fields","raw","defaults","options","limits"],"properties":{"inbox_id":{"type":"integer","description":"The inbox in the path."},"owner_inbox_id":{"type":"integer","description":"The logical inbox that owns the policy (the Cloud inbox of a unified pair)."},"mirror":{"type":"boolean","description":"True when the inbox in the path is a read-only mirror of `owner_inbox_id`."},"version":{"type":"integer","minimum":0,"description":"Policy version; send it as `expected_version` on PATCH (0 while nothing was saved)."},"updated_at":{"type":["string","null"],"format":"date-time","description":"Last save, or null while nothing was saved."},"account_active":{"type":"boolean","description":"Whether the account is active (an inactive account forces the lane off)."},"flags":{"type":"object","required":["batching","maestro","rich_transform","weighted_routing"],"description":"Module flags of the account.","properties":{"batching":{"type":"boolean","description":"Fragment collection (`whatsapp_outbound_batching`)."},"maestro":{"type":"boolean","description":"Maestro transformations (`whatsapp_outbound_maestro`)."},"rich_transform":{"type":"boolean","description":"Rich formats and WhatsApp Flows (`whatsapp_outbound_rich_transform`)."},"weighted_routing":{"type":"boolean","description":"Percentage routing of hybrid pairs (`whatsapp_hybrid_weighted_routing`). It only lets an administrator configure the percentage of a pair; whether this inbox uses it is `capabilities.weighted_effective`."}}},"capabilities":{"type":"object","additionalProperties":false,"required":["weighted_effective"],"description":"What the outbound lane may do in this inbox right now, as the server decides it.","properties":{"weighted_effective":{"type":"boolean","description":"True when replies of this inbox are distributed by percentage: the account flag is on, the account is active and the inbox belongs to an enabled unified hybrid pair whose percentage routing is in `weighted` mode. Otherwise replies follow the regular route."}}},"maestro_module":{"type":"object","additionalProperties":false,"required":["restricted_by"],"description":"Whether this installation may use the Maestro transformer right now. A contract checksum or grant key mismatch with the Maestro sidecar restricts the module for every inbox: no suggestion and no approval of a candidate, and new batches follow the failure policy (send the original, or pause). The value is a short-lived shared answer; reading it never calls the sidecar.","properties":{"restricted_by":{"type":["string","null"],"enum":["contract_version_mismatch","grant_key_mismatch",null],"description":"Why the module is restricted; null when it is not restricted, not known yet, or the Maestro flag is off for the account."}}},"permissions":{"type":"object","required":["update"],"description":"What the caller may do.","properties":{"update":{"type":"boolean","description":"Whether the caller may PATCH this policy through this inbox now (false on a mirror)."}}},"effective":{"type":"object","required":["enabled","idle_seconds","max_wait_seconds","mode","on_transform_failure","allowed_agent_bot_ids","operations","formats","cta_allowed_hosts","flow_mappings","daily_budget","retention_days"],"description":"Every key of the inbox policy with the value that applies now (defaults merged; a disabled module forces its most restrictive value; only still-eligible Maestro profiles and non-revoked mappings are listed).","properties":{"enabled":{"type":"boolean","description":"Whether the lane collects fragments on this inbox."},"idle_seconds":{"type":"integer","minimum":1,"maximum":30,"description":"Seconds without a new fragment before the batch leaves."},"max_wait_seconds":{"type":"integer","minimum":1,"maximum":60,"description":"Maximum collection window from the first fragment (never below `idle_seconds`)."},"mode":{"type":"string","enum":["faithful","suggest","automatic"],"description":"Maestro mode — `faithful` (the author's consolidated text leaves as typed), `suggest` (a transformation is proposed and waits for the author) or `automatic` (an approved transformation may leave without review)."},"on_transform_failure":{"type":"string","enum":["hold","original"],"description":"When a transformation fails — `hold` (pause for the author) or `original` (send the original text)."},"allowed_agent_bot_ids":{"type":"array","maxItems":20,"description":"Allowlisted Maestro profiles (AgentBots of this account linked to Maestro).","items":{"type":"integer"}},"operations":{"type":"array","description":"Transformations Maestro may apply.","items":{"type":"string","enum":["proofread","format","structure"]}},"formats":{"type":"array","description":"Output formats a transformation may produce (always includes `text`).","items":{"type":"string","enum":["text","buttons","list","cta","whatsapp_flow"]}},"cta_allowed_hosts":{"type":"array","maxItems":20,"description":"Bare hostnames a call-to-action URL may point to when the URL is not in the reply text itself: Maestro may reuse a link the team (agent or bot) already sent in the conversation only if its host is listed here. Links sent by the contact are never used, and Maestro never makes up a link.","items":{"type":"string"}},"flow_mappings":{"type":"array","maxItems":100,"description":"WhatsApp Flow mappings Maestro and agents may use.","items":{"type":"object","description":"One immutable version of a WhatsApp Flow mapping of the inbox policy. A saved version never changes; revoking it sets `revoked` and `revoked_at` once.","required":["mapping_id","version","whatsapp_flow_id","screen","seed_schema","required_fields","digest"],"properties":{"mapping_id":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$","description":"Mapping id (versions of the same mapping share it)."},"version":{"type":"integer","minimum":1,"maximum":100000,"description":"Version of this mapping."},"whatsapp_flow_id":{"type":"integer","minimum":1,"description":"WhatsApp Flow of this account, on the inbox's Cloud channel."},"screen":{"type":"string","pattern":"^[A-Za-z0-9_]{1,128}$","description":"Screen id the Flow opens on."},"seed_schema":{"type":"object","additionalProperties":true,"description":"Data the conversion may seed on that screen: `{type: object, properties: {\u003cname\u003e: {type: string|integer|boolean, minLength?, maxLength?, enum?}}, required, additionalProperties: false}` — at most 32 flat properties."},"required_fields":{"type":"array","maxItems":50,"description":"Seed fields that must be filled.","items":{"type":"string"}},"label":{"type":"string","maxLength":120,"description":"Name shown to agents."},"intent":{"type":"string","maxLength":64,"description":"What the Flow is for (lets Maestro choose it)."},"flow_cta":{"type":"string","maxLength":20,"description":"Call-to-action text of the Flow message."},"flow_revision_digest":{"type":"string","pattern":"^[0-9a-f]{64}$","description":"Digest of the published Flow revision this mapping was built from."},"digest":{"type":"string","pattern":"^[0-9a-f]{64}$","description":"SHA-256 digest of the mapping content, stamped by the server."},"revoked":{"type":"boolean","description":"Whether this version was revoked."},"revoked_at":{"type":["string","null"],"format":"date-time","description":"When it was revoked."},"created_at":{"type":"string","format":"date-time","description":"When this version was saved."},"created_by_account_user_id":{"type":["integer","null"],"description":"Account user who saved it."}}}},"daily_budget":{"type":["object","null"],"additionalProperties":false,"required":["unit","limit"],"description":"Daily Maestro budget of the inbox, or null for none.","properties":{"unit":{"type":"string","enum":["requests","output_tokens"],"description":"What the limit counts."},"limit":{"type":"integer","minimum":0,"maximum":100000000,"description":"Daily ceiling in that unit."}}},"retention_days":{"type":"integer","minimum":1,"maximum":90,"description":"Days the text of a finished batch is kept before purge (digests and counters remain)."}}},"fields":{"type":"array","description":"Every policy key with its effective value and origin.","items":{"type":"object","required":["key","value","origin","configured","restricted_by"],"properties":{"key":{"type":"string","enum":["enabled","idle_seconds","max_wait_seconds","mode","on_transform_failure","allowed_agent_bot_ids","operations","formats","cta_allowed_hosts","flow_mappings","daily_budget","retention_days"],"description":"Policy key."},"value":{"description":"Effective value of the key (its type follows the key, as in `effective`).","anyOf":[{"type":"boolean"},{"type":"integer"},{"type":"string"},{"type":"array","items":{"anyOf":[{"type":"integer"},{"type":"string"},{"type":"object","description":"One immutable version of a WhatsApp Flow mapping of the inbox policy. A saved version never changes; revoking it sets `revoked` and `revoked_at` once.","required":["mapping_id","version","whatsapp_flow_id","screen","seed_schema","required_fields","digest"],"properties":{"mapping_id":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$","description":"Mapping id (versions of the same mapping share it)."},"version":{"type":"integer","minimum":1,"maximum":100000,"description":"Version of this mapping."},"whatsapp_flow_id":{"type":"integer","minimum":1,"description":"WhatsApp Flow of this account, on the inbox's Cloud channel."},"screen":{"type":"string","pattern":"^[A-Za-z0-9_]{1,128}$","description":"Screen id the Flow opens on."},"seed_schema":{"type":"object","additionalProperties":true,"description":"Data the conversion may seed on that screen: `{type: object, properties: {\u003cname\u003e: {type: string|integer|boolean, minLength?, maxLength?, enum?}}, required, additionalProperties: false}` — at most 32 flat properties."},"required_fields":{"type":"array","maxItems":50,"description":"Seed fields that must be filled.","items":{"type":"string"}},"label":{"type":"string","maxLength":120,"description":"Name shown to agents."},"intent":{"type":"string","maxLength":64,"description":"What the Flow is for (lets Maestro choose it)."},"flow_cta":{"type":"string","maxLength":20,"description":"Call-to-action text of the Flow message."},"flow_revision_digest":{"type":"string","pattern":"^[0-9a-f]{64}$","description":"Digest of the published Flow revision this mapping was built from."},"digest":{"type":"string","pattern":"^[0-9a-f]{64}$","description":"SHA-256 digest of the mapping content, stamped by the server."},"revoked":{"type":"boolean","description":"Whether this version was revoked."},"revoked_at":{"type":["string","null"],"format":"date-time","description":"When it was revoked."},"created_at":{"type":"string","format":"date-time","description":"When this version was saved."},"created_by_account_user_id":{"type":["integer","null"],"description":"Account user who saved it."}}}]}},{"type":["object","null"],"additionalProperties":false,"required":["unit","limit"],"description":"Daily Maestro budget of the inbox, or null for none.","properties":{"unit":{"type":"string","enum":["requests","output_tokens"],"description":"What the limit counts."},"limit":{"type":"integer","minimum":0,"maximum":100000000,"description":"Daily ceiling in that unit."}}},{"type":"null"}]},"origin":{"type":"string","enum":["system_default","inbox","restricted"],"description":"`system_default` (not configured), `inbox` (saved by an administrator) or `restricted` (forced by a disabled flag or an inactive account)."},"configured":{"type":"boolean","description":"Whether the key is stored on the policy (a stored value survives a flag change)."},"restricted_by":{"type":["string","null"],"enum":["flag_disabled",null],"description":"What forces the restrictive value, or null."}}}},"raw":{"type":"object","additionalProperties":true,"propertyNames":{"enum":["enabled","idle_seconds","max_wait_seconds","mode","on_transform_failure","allowed_agent_bot_ids","operations","formats","cta_allowed_hosts","flow_mappings","daily_budget","retention_days"]},"description":"Exactly the keys an administrator stored (sparse; a missing key inherits the system default). Values have the same shapes as in `effective`, including revoked mapping versions."},"defaults":{"type":"object","required":["enabled","idle_seconds","max_wait_seconds","mode","on_transform_failure","allowed_agent_bot_ids","operations","formats","cta_allowed_hosts","flow_mappings","daily_budget","retention_days"],"description":"System defaults of every key.","properties":{"enabled":{"type":"boolean","description":"Default false."},"idle_seconds":{"type":"integer","description":"Default 10."},"max_wait_seconds":{"type":"integer","description":"Default 30."},"mode":{"type":"string","enum":["faithful","suggest","automatic"],"description":"Maestro mode — `faithful` (the author's consolidated text leaves as typed), `suggest` (a transformation is proposed and waits for the author) or `automatic` (an approved transformation may leave without review)."},"on_transform_failure":{"type":"string","enum":["hold","original"],"description":"Default `hold`."},"allowed_agent_bot_ids":{"type":"array","description":"Default empty.","items":{"type":"integer"}},"operations":{"type":"array","description":"Default empty.","items":{"type":"string","enum":["proofread","format","structure"]}},"formats":{"type":"array","description":"Default `[text]`.","items":{"type":"string","enum":["text","buttons","list","cta","whatsapp_flow"]}},"cta_allowed_hosts":{"type":"array","description":"Default empty.","items":{"type":"string"}},"flow_mappings":{"type":"array","maxItems":0,"description":"Always empty — no mapping exists by default.","items":{"type":"object","additionalProperties":true,"description":"Never present in the defaults."}},"daily_budget":{"type":"null","description":"Default null (no budget)."},"retention_days":{"type":"integer","description":"Default 7."}}},"options":{"type":"object","required":["modes","on_transform_failure","operations","formats","budget_units"],"description":"The closed choices of the policy.","properties":{"modes":{"type":"array","description":"Maestro modes, mildest first.","items":{"type":"string","enum":["faithful","suggest","automatic"],"description":"Maestro mode — `faithful` (the author's consolidated text leaves as typed), `suggest` (a transformation is proposed and waits for the author) or `automatic` (an approved transformation may leave without review)."}},"on_transform_failure":{"type":"array","description":"Failure policies.","items":{"type":"string","enum":["hold","original"]}},"operations":{"type":"array","description":"Maestro operations.","items":{"type":"string","enum":["proofread","format","structure"]}},"formats":{"type":"array","description":"Output formats.","items":{"type":"string","enum":["text","buttons","list","cta","whatsapp_flow"]}},"budget_units":{"type":"array","description":"Daily budget units.","items":{"type":"string","enum":["requests","output_tokens"]}}}},"limits":{"type":"object","required":["idle_seconds","max_wait_seconds","retention_days","max_agent_profiles","max_cta_hosts","max_flow_mappings","flow_mapping"],"description":"Numeric bounds of the policy.","properties":{"idle_seconds":{"type":"object","required":["min","max"],"description":"Inclusive bounds.","properties":{"min":{"type":"integer","description":"Lower bound."},"max":{"type":"integer","description":"Upper bound."}}},"max_wait_seconds":{"type":"object","required":["min","max"],"description":"Inclusive bounds.","properties":{"min":{"type":"integer","description":"Lower bound."},"max":{"type":"integer","description":"Upper bound."}}},"retention_days":{"type":"object","required":["min","max"],"description":"Inclusive bounds.","properties":{"min":{"type":"integer","description":"Lower bound."},"max":{"type":"integer","description":"Upper bound."}}},"max_agent_profiles":{"type":"integer","description":"Maximum allowlisted Maestro profiles (20)."},"max_cta_hosts":{"type":"integer","description":"Maximum call-to-action hosts (20)."},"max_flow_mappings":{"type":"integer","description":"Maximum stored mapping versions (100)."},"flow_mapping":{"type":"object","required":["label_max_chars","intent_max_chars","flow_cta_max_chars"],"description":"Character limits of one WhatsApp Flow mapping, published from the same constants the server validates with, so the dashboard never hard-codes them.","properties":{"label_max_chars":{"type":"integer","description":"Maximum characters of the label the agent sees during review (100)."},"intent_max_chars":{"type":"integer","description":"Maximum characters of the \"when to suggest\" intent given to Maestro (64)."},"flow_cta_max_chars":{"type":"integer","description":"Maximum characters of the button text that opens the WhatsApp Flow (20)."}}}}}}},"example":{"inbox_id":17,"owner_inbox_id":17,"mirror":false,"version":3,"updated_at":"2026-09-29T13:58:04Z","account_active":true,"flags":{"batching":true,"maestro":true,"rich_transform":true,"weighted_routing":true},"capabilities":{"weighted_effective":true},"maestro_module":{"restricted_by":null},"permissions":{"update":true},"effective":{"enabled":true,"idle_seconds":10,"max_wait_seconds":30,"mode":"suggest","on_transform_failure":"hold","allowed_agent_bot_ids":[12],"operations":["proofread","format"],"formats":["text","buttons","whatsapp_flow"],"cta_allowed_hosts":["loja.example.com"],"flow_mappings":[{"mapping_id":"agendar-visita","version":2,"whatsapp_flow_id":5,"screen":"AGENDAMENTO","seed_schema":{"type":"object","properties":{"nome":{"type":"string","maxLength":80}},"required":["nome"],"additionalProperties":false},"required_fields":["nome"],"label":"Agendar visita","intent":"schedule_visit","flow_cta":"Agendar","flow_revision_digest":"6e5bbd34b46e2d73889dec0ac0868fe13be924010c93009023664f4f46027bbe","digest":"e45805152393fb5601be8835339f62b942a9f1d01e7bbeef0b22e8d089ddc1fa","revoked":false,"revoked_at":null,"created_at":"2026-09-28T19:40:11.000Z","created_by_account_user_id":31}],"daily_budget":{"unit":"requests","limit":500},"retention_days":7},"fields":[{"key":"mode","value":"suggest","origin":"inbox","configured":true,"restricted_by":null}],"raw":{"enabled":true,"mode":"suggest","allowed_agent_bot_ids":[12],"operations":["proofread","format"],"formats":["text","buttons","whatsapp_flow"],"cta_allowed_hosts":["loja.example.com"],"flow_mappings":[{"mapping_id":"agendar-visita","version":2,"whatsapp_flow_id":5,"screen":"AGENDAMENTO","seed_schema":{"type":"object","properties":{"nome":{"type":"string","maxLength":80}},"required":["nome"],"additionalProperties":false},"required_fields":["nome"],"label":"Agendar visita","intent":"schedule_visit","flow_cta":"Agendar","flow_revision_digest":"6e5bbd34b46e2d73889dec0ac0868fe13be924010c93009023664f4f46027bbe","digest":"e45805152393fb5601be8835339f62b942a9f1d01e7bbeef0b22e8d089ddc1fa","revoked":false,"revoked_at":null,"created_at":"2026-09-28T19:40:11.000Z","created_by_account_user_id":31}],"daily_budget":{"unit":"requests","limit":500}},"defaults":{"enabled":false,"idle_seconds":10,"max_wait_seconds":30,"mode":"faithful","on_transform_failure":"hold","allowed_agent_bot_ids":[],"operations":[],"formats":["text"],"cta_allowed_hosts":[],"flow_mappings":[],"daily_budget":null,"retention_days":7},"options":{"modes":["faithful","suggest","automatic"],"on_transform_failure":["hold","original"],"operations":["proofread","format","structure"],"formats":["text","buttons","list","cta","whatsapp_flow"],"budget_units":["requests","output_tokens"]},"limits":{"idle_seconds":{"min":1,"max":30},"max_wait_seconds":{"min":1,"max":60},"retention_days":{"min":1,"max":90},"max_agent_profiles":20,"max_cta_hosts":20,"max_flow_mappings":100,"flow_mapping":{"label_max_chars":100,"intent_max_chars":64,"flow_cta_max_chars":20}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"The inbox does not exist in this account (generic lookup failure), it is not a WhatsApp inbox this feature can configure (`inbox_not_supported`), or the batching module flag is off (`feature_disabled`).","content":{"application/json":{"schema":{"anyOf":[{"type":"object","additionalProperties":false,"required":["error"],"description":"The inbox is not a WhatsApp inbox this lane serves (or the conversation is a WhatsApp group).","properties":{"error":{"type":"string","enum":["inbox_not_supported"],"description":"Stable code."}}},{"type":"object","additionalProperties":false,"required":["error","feature"],"description":"Writes need the batching module flag; reads stay available.","properties":{"error":{"type":"string","enum":["feature_disabled"],"description":"Stable code."},"feature":{"type":"string","enum":["whatsapp_outbound_batching"],"description":"The flag that must be on."}}},{"type":"object","additionalProperties":false,"required":["error"],"description":"Generic lookup failure of the account API (the conversation or inbox does not exist in this account).","properties":{"error":{"type":"string","description":"Human-readable lookup failure (\"Resource could not be found\")."}}}]},"example":{"error":"feature_disabled","feature":"whatsapp_outbound_batching"}}}},"403":{"description":"The caller may not read (or, for writes, change) this outbound configuration.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","enum":["forbidden"],"description":"Policy refusal."}}},"example":{"error":"forbidden"}}}},"409":{"description":"`expected_version` differs from the stored version (0 means \"no row yet\"), including two concurrent FIRST writes where the other one created the row; re-read and retry.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error","current_version"],"properties":{"error":{"type":"string","enum":["configuration_version_conflict"],"description":"Stable code."},"current_version":{"type":"integer","minimum":0,"description":"The version stored now."}}},"example":{"error":"configuration_version_conflict","current_version":3}}}},"422":{"description":"`invalid_configuration` with field errors (`required`, `invalid_type`, `unknown_field`, `not_allowed`, `out_of_range`, a flag-gated key widened while its flag is off (`feature_disabled`), automatic mode without consent, mapping version rules, a Flow that cannot be mapped — `flow_not_eligible` with its closed `reason` — and the other codes listed), or `configuration_owned_by_logical_inbox` when the inbox is a unified pair's read-only Web mirror.","content":{"application/json":{"schema":{"anyOf":[{"type":"object","additionalProperties":false,"required":["error","errors"],"properties":{"error":{"type":"string","enum":["invalid_configuration"],"description":"Stable code."},"errors":{"type":"array","minItems":1,"description":"Field errors.","items":{"type":"object","additionalProperties":false,"required":["field","code"],"properties":{"field":{"type":"string","description":"Policy key or path (e.g. `max_wait_seconds`, `flow_mappings/0`, `expected_version`)."},"code":{"type":"string","pattern":"^[a-z][a-z0-9_]*$","description":"Stable validation code. Policy codes: required, invalid_type, unknown_field, not_allowed, invalid_format, duplicate, out_of_range, invalid, taken, feature_disabled, automatic_consent_required, less_than_idle_seconds, required_for_mode, must_include_text, duplicate_version, digest_mismatch, revocation_incomplete, version_removed, version_immutable, revocation_irreversible, unknown_whatsapp_flow, not_eligible, seed_schema_too_large, seed_schema_invalid, flow_not_eligible, flow_mapping_unbuildable. A NEW `flow_mappings` version is also validated by the WhatsApp Flow catalog parser, whose codes are per key and open-ended (`\u003ckey\u003e_required`, `\u003ckey\u003e_invalid`, `seed_schema_\u003creason\u003e`, `required_fields_*`), e.g. required_fields_not_in_seed_schema, required_fields_duplicated, label_invalid, intent_invalid, flow_cta_invalid. Clients translate the codes they know and fall back to a generic message for the rest.","examples":["out_of_range","required_fields_not_in_seed_schema","flow_cta_invalid"]},"reason":{"type":"string","enum":["screen_invalid","screen_missing","flow_missing","flow_not_published","flow_meta_id_missing","cloud_capability_unavailable","mapping_id_invalid","label_invalid","intent_invalid","flow_cta_invalid","screen_data_unsupported"],"description":"Closed detail of a `flow_not_eligible` mapping error (absent otherwise)."}}}}}},{"type":"object","additionalProperties":false,"required":["error","owner_inbox_id"],"properties":{"error":{"type":"string","enum":["configuration_owned_by_logical_inbox"],"description":"Stable code."},"owner_inbox_id":{"type":"integer","description":"The Cloud inbox that accepts writes for this pair."}}}]},"example":{"error":"invalid_configuration","errors":[{"field":"flow_mappings/0","code":"flow_not_eligible","reason":"flow_not_published"}]}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"in":"path","name":"inbox_id","required":true,"description":"Inbox id in the account (a unified pair's Web inbox is read-only).","schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["expected_version","settings"],"properties":{"expected_version":{"type":"integer","minimum":0,"description":"The `version` last read (0 when no policy was saved yet)."},"automatic_consent":{"type":"boolean","description":"Required as true when this request switches `mode` into `automatic`."},"settings":{"type":"object","additionalProperties":false,"description":"Keys to change (sparse). Null restores the system default of that key.","properties":{"enabled":{"type":["boolean","null"],"description":"Turn fragment collection on or off for this inbox."},"idle_seconds":{"type":["integer","null"],"minimum":1,"maximum":30,"description":"Idle seconds before a batch leaves."},"max_wait_seconds":{"type":["integer","null"],"minimum":1,"maximum":60,"description":"Maximum collection window (must be at least `idle_seconds`)."},"mode":{"type":["string","null"],"enum":["faithful","suggest","automatic",null],"description":"Maestro mode (`suggest`/`automatic` need at least one operation and one allowlisted profile)."},"on_transform_failure":{"type":["string","null"],"enum":["hold","original",null],"description":"What to do when a transformation fails."},"allowed_agent_bot_ids":{"type":["array","null"],"maxItems":20,"description":"AgentBots of this account linked to Maestro.","items":{"type":"integer","minimum":1}},"operations":{"type":["array","null"],"description":"Operations Maestro may apply.","items":{"type":"string","enum":["proofread","format","structure"]}},"formats":{"type":["array","null"],"description":"Allowed output formats (must include `text`).","items":{"type":"string","enum":["text","buttons","list","cta","whatsapp_flow"]}},"cta_allowed_hosts":{"type":["array","null"],"maxItems":20,"description":"Bare hostnames (no scheme, port, path or wildcard).","items":{"type":"string","maxLength":253}},"flow_mappings":{"type":["array","null"],"maxItems":100,"description":"Mapping versions to add or revoke. Null is ignored for this key (saved versions are never deleted).","items":{"anyOf":[{"type":"object","title":"New version built from the published Flow","required":["whatsapp_flow_id","screen"],"properties":{"mapping_id":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$","description":"Mapping to version (derived as `flow-\u003cwhatsapp_flow_id\u003e-\u003cscreen\u003e` when absent)."},"whatsapp_flow_id":{"type":"integer","minimum":1,"description":"A published WhatsApp Flow of this account on the inbox's Cloud channel."},"screen":{"type":"string","pattern":"^[A-Za-z0-9_]{1,128}$","description":"Screen id the Flow opens on."},"label":{"type":"string","maxLength":120,"description":"Name shown to agents."},"intent":{"type":"string","maxLength":64,"description":"What the Flow is for."},"flow_cta":{"type":"string","maxLength":20,"description":"Call-to-action text (no emoji)."}}},{"type":"object","title":"New version with an explicit seed schema","required":["whatsapp_flow_id","screen","seed_schema","required_fields"],"properties":{"mapping_id":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$","description":"Mapping to version."},"whatsapp_flow_id":{"type":"integer","minimum":1,"description":"WhatsApp Flow of this account on the inbox's Cloud channel."},"screen":{"type":"string","pattern":"^[A-Za-z0-9_]{1,128}$","description":"Screen id."},"label":{"type":"string","maxLength":120,"description":"Name shown to agents."},"intent":{"type":"string","maxLength":64,"description":"What the Flow is for."},"flow_cta":{"type":"string","maxLength":20,"description":"Call-to-action text."},"seed_schema":{"type":"object","additionalProperties":true,"description":"The flat seed schema subset (validated; the published Flow is not read)."},"required_fields":{"type":"array","description":"Seed fields that must be filled.","items":{"type":"string"}},"flow_revision_digest":{"type":"string","pattern":"^[0-9a-f]{64}$","description":"Digest of the Flow revision the schema was taken from."}}},{"type":"object","title":"Saved version (kept or revoked)","required":["mapping_id","version"],"properties":{"mapping_id":{"type":"string","description":"Saved mapping id."},"version":{"type":"integer","minimum":1,"description":"Saved version; its content cannot change."},"revoked":{"type":"boolean","description":"True revokes this version (irreversible)."}}}]}},"daily_budget":{"type":["object","null"],"additionalProperties":false,"required":["unit","limit"],"description":"Daily Maestro budget of the inbox, or null for none.","properties":{"unit":{"type":"string","enum":["requests","output_tokens"],"description":"What the limit counts."},"limit":{"type":"integer","minimum":0,"maximum":100000000,"description":"Daily ceiling in that unit."}}},"retention_days":{"type":["integer","null"],"minimum":1,"maximum":90,"description":"Days a finished batch's text is kept."}}}}},"example":{"expected_version":2,"automatic_consent":false,"settings":{"enabled":true,"idle_seconds":10,"max_wait_seconds":30,"mode":"suggest","on_transform_failure":"hold","allowed_agent_bot_ids":[12],"operations":["proofread","format"],"formats":["text","buttons","whatsapp_flow"],"cta_allowed_hosts":["loja.example.com"],"flow_mappings":[{"mapping_id":"agendar-visita","whatsapp_flow_id":5,"screen":"AGENDAMENTO","label":"Agendar visita","intent":"schedule_visit","flow_cta":"Agendar"}],"daily_budget":{"unit":"requests","limit":500},"retention_days":7}}}}}}},"/api/v1/accounts/{account_id}/whatsapp/outbound/inboxes/{inbox_id}/preference":{"get":{"tags":["WhatsApp"],"operationId":"auto_get_api_v1_accounts_account_id_whatsapp_outbound_inboxes_inbox_id_preference","summary":"Get my WhatsApp outbound preference for an inbox","description":"Returns the CURRENT agent's own preference for the logical inbox (no user id is ever accepted). A preference can only inherit or restrict the inbox policy: a milder Maestro mode, an idle inside the inbox collection ceiling, a subset of the allowed operations/formats and one allowlisted Maestro profile. Each field shows its effective value, origin (`system_default`, `inbox`, `preference`, `restricted`) and why a stored value is ignored (`restricted_by`); `allowed` is the envelope the inbox permits right now and `profile` the Maestro profile that would transform the caller's batches. Readable with the module flags off.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The caller's own preference for the logical inbox.","content":{"application/json":{"schema":{"type":"object","required":["inbox_id","owner_inbox_id","mirror","version","updated_at","flags","permissions","overrides","fields","allowed","profile"],"properties":{"inbox_id":{"type":"integer","description":"The inbox in the path."},"owner_inbox_id":{"type":"integer","description":"The logical inbox the preference is stored against (the Cloud inbox of a unified pair)."},"mirror":{"type":"boolean","description":"True when the inbox in the path mirrors `owner_inbox_id` (same preference either way)."},"version":{"type":"integer","minimum":0,"description":"Preference version; send it as `expected_version` on PATCH (0 while nothing was saved)."},"updated_at":{"type":["string","null"],"format":"date-time","description":"Last save, or null."},"flags":{"type":"object","required":["batching","maestro","rich_transform","weighted_routing"],"description":"Module flags of the account.","properties":{"batching":{"type":"boolean","description":"Fragment collection."},"maestro":{"type":"boolean","description":"Maestro transformations."},"rich_transform":{"type":"boolean","description":"Rich formats and WhatsApp Flows."},"weighted_routing":{"type":"boolean","description":"Percentage routing of hybrid pairs."}}},"permissions":{"type":"object","required":["update"],"description":"What the caller may do.","properties":{"update":{"type":"boolean","description":"Whether the caller may PATCH the preference."}}},"overrides":{"type":"object","additionalProperties":true,"propertyNames":{"enum":["mode","idle_seconds","formats","operations","agent_bot_id"]},"description":"Exactly what the caller stored (sparse; a missing key inherits the inbox policy). `mode` string, `idle_seconds` integer, `formats`/`operations` string arrays, `agent_bot_id` integer."},"fields":{"type":"array","description":"The preference keys with their effective value and origin.","items":{"type":"object","required":["key","value","origin","inbox_value","preference_value","restricted_by"],"properties":{"key":{"type":"string","enum":["mode","idle_seconds","formats","operations"],"description":"Preference key."},"value":{"description":"Effective value for the caller (`mode` string, `idle_seconds` integer, lists of strings).","anyOf":[{"type":"string"},{"type":"integer"},{"type":"array","items":{"type":"string"}}]},"origin":{"type":"string","enum":["system_default","inbox","preference","restricted"],"description":"Where the effective value comes from."},"inbox_value":{"description":"What the inbox policy allows for this key right now.","anyOf":[{"type":"string"},{"type":"integer"},{"type":"array","items":{"type":"string"}}]},"preference_value":{"description":"The caller's stored value, or null (kept even when the policy no longer allows it).","anyOf":[{"type":"string"},{"type":"integer"},{"type":"array","items":{"type":"string"}},{"type":"null"}]},"restricted_by":{"type":["string","null"],"enum":["flag_disabled","policy_revoked",null],"description":"`flag_disabled` (a disabled module forces the value) or `policy_revoked` (the stored preference exceeds the current inbox policy and is ignored); null otherwise."}}}},"allowed":{"type":"object","required":["modes","idle_seconds","formats","operations","agent_bot_ids"],"description":"The envelope the inbox policy allows right now; a preference may only restrict inside it.","properties":{"modes":{"type":"array","description":"Modes up to the inbox mode (mildest first).","items":{"type":"string","enum":["faithful","suggest","automatic"],"description":"Maestro mode — `faithful` (the author's consolidated text leaves as typed), `suggest` (a transformation is proposed and waits for the author) or `automatic` (an approved transformation may leave without review)."}},"idle_seconds":{"type":"object","required":["min","max"],"description":"Idle bounds (max is the inbox collection ceiling).","properties":{"min":{"type":"integer","description":"Lower bound."},"max":{"type":"integer","description":"Upper bound."}}},"formats":{"type":"array","description":"Formats the inbox allows.","items":{"type":"string","enum":["text","buttons","list","cta","whatsapp_flow"]}},"operations":{"type":"array","description":"Operations the inbox allows.","items":{"type":"string","enum":["proofread","format","structure"]}},"agent_bot_ids":{"type":"array","description":"Maestro profiles the caller may pick.","items":{"type":"integer"}}}},"profile":{"type":"object","required":["agent_bot_id","resolution_source","owner_inbox_id","available","reason"],"description":"A Maestro profile resolution — never the bot configuration, secrets or the remote Maestro agent id.","properties":{"agent_bot_id":{"type":["integer","null"],"description":"The AgentBot that would transform the batches, or null when none resolves."},"resolution_source":{"type":"string","enum":["explicit_profile","inbox_binding"],"description":"`explicit_profile` (the agent picked an allowlisted profile) or `inbox_binding` (inherited from the inbox bot binding)."},"owner_inbox_id":{"type":["integer","null"],"description":"Inbox whose bot binding was inherited (a unified pair may borrow its sibling's); null for an explicit choice."},"available":{"type":"boolean","description":"Whether this profile can transform batches right now."},"reason":{"type":["string","null"],"enum":["not_allowlisted","not_maestro_linked","no_inbox_binding","inbox_binding_inactive",null],"description":"Why the profile is unavailable; null when available."}}}}},"example":{"inbox_id":17,"owner_inbox_id":17,"mirror":false,"version":2,"updated_at":"2026-09-29T14:00:37Z","flags":{"batching":true,"maestro":true,"rich_transform":true,"weighted_routing":true},"permissions":{"update":true},"overrides":{"mode":"suggest","idle_seconds":8},"fields":[{"key":"mode","value":"suggest","origin":"preference","inbox_value":"automatic","preference_value":"suggest","restricted_by":null}],"allowed":{"modes":["faithful","suggest","automatic"],"idle_seconds":{"min":1,"max":30},"formats":["text","buttons","whatsapp_flow"],"operations":["proofread","format"],"agent_bot_ids":[12]},"profile":{"agent_bot_id":12,"resolution_source":"inbox_binding","owner_inbox_id":17,"available":true,"reason":null}}}}},"401":{"description":"Unauthorized"},"404":{"description":"The inbox does not exist in this account (generic lookup failure), or it is not a WhatsApp inbox this feature can configure (`inbox_not_supported`).","content":{"application/json":{"schema":{"anyOf":[{"type":"object","additionalProperties":false,"required":["error"],"description":"The inbox is not a WhatsApp inbox this lane serves (or the conversation is a WhatsApp group).","properties":{"error":{"type":"string","enum":["inbox_not_supported"],"description":"Stable code."}}},{"type":"object","additionalProperties":false,"required":["error"],"description":"Generic lookup failure of the account API (the conversation or inbox does not exist in this account).","properties":{"error":{"type":"string","description":"Human-readable lookup failure (\"Resource could not be found\")."}}}]},"example":{"error":"inbox_not_supported"}}}},"403":{"description":"The caller may not read (or, for writes, change) this outbound configuration.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","enum":["forbidden"],"description":"Policy refusal."}}},"example":{"error":"forbidden"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"in":"path","name":"inbox_id","required":true,"description":"Inbox id in the account; the Web inbox of a unified pair resolves to its Cloud owner.","schema":{"type":"integer"}}]},"patch":{"tags":["WhatsApp"],"operationId":"auto_patch_api_v1_accounts_account_id_whatsapp_outbound_inboxes_inbox_id_preference","summary":"Update my WhatsApp outbound preference for an inbox","description":"Sparse update of the caller's own preference under optimistic locking (`expected_version`, 0 before the first save). Null restores inheritance for that key; unknown keys are refused with 422 `unknown_field`. Every stored value must fit what the inbox allows right now (`exceeds_policy`, `agent_profile_not_allowed`, `must_include_text`). Needs the `whatsapp_outbound_batching` flag. Audited.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The caller's own preference for the logical inbox.","content":{"application/json":{"schema":{"type":"object","required":["inbox_id","owner_inbox_id","mirror","version","updated_at","flags","permissions","overrides","fields","allowed","profile"],"properties":{"inbox_id":{"type":"integer","description":"The inbox in the path."},"owner_inbox_id":{"type":"integer","description":"The logical inbox the preference is stored against (the Cloud inbox of a unified pair)."},"mirror":{"type":"boolean","description":"True when the inbox in the path mirrors `owner_inbox_id` (same preference either way)."},"version":{"type":"integer","minimum":0,"description":"Preference version; send it as `expected_version` on PATCH (0 while nothing was saved)."},"updated_at":{"type":["string","null"],"format":"date-time","description":"Last save, or null."},"flags":{"type":"object","required":["batching","maestro","rich_transform","weighted_routing"],"description":"Module flags of the account.","properties":{"batching":{"type":"boolean","description":"Fragment collection."},"maestro":{"type":"boolean","description":"Maestro transformations."},"rich_transform":{"type":"boolean","description":"Rich formats and WhatsApp Flows."},"weighted_routing":{"type":"boolean","description":"Percentage routing of hybrid pairs."}}},"permissions":{"type":"object","required":["update"],"description":"What the caller may do.","properties":{"update":{"type":"boolean","description":"Whether the caller may PATCH the preference."}}},"overrides":{"type":"object","additionalProperties":true,"propertyNames":{"enum":["mode","idle_seconds","formats","operations","agent_bot_id"]},"description":"Exactly what the caller stored (sparse; a missing key inherits the inbox policy). `mode` string, `idle_seconds` integer, `formats`/`operations` string arrays, `agent_bot_id` integer."},"fields":{"type":"array","description":"The preference keys with their effective value and origin.","items":{"type":"object","required":["key","value","origin","inbox_value","preference_value","restricted_by"],"properties":{"key":{"type":"string","enum":["mode","idle_seconds","formats","operations"],"description":"Preference key."},"value":{"description":"Effective value for the caller (`mode` string, `idle_seconds` integer, lists of strings).","anyOf":[{"type":"string"},{"type":"integer"},{"type":"array","items":{"type":"string"}}]},"origin":{"type":"string","enum":["system_default","inbox","preference","restricted"],"description":"Where the effective value comes from."},"inbox_value":{"description":"What the inbox policy allows for this key right now.","anyOf":[{"type":"string"},{"type":"integer"},{"type":"array","items":{"type":"string"}}]},"preference_value":{"description":"The caller's stored value, or null (kept even when the policy no longer allows it).","anyOf":[{"type":"string"},{"type":"integer"},{"type":"array","items":{"type":"string"}},{"type":"null"}]},"restricted_by":{"type":["string","null"],"enum":["flag_disabled","policy_revoked",null],"description":"`flag_disabled` (a disabled module forces the value) or `policy_revoked` (the stored preference exceeds the current inbox policy and is ignored); null otherwise."}}}},"allowed":{"type":"object","required":["modes","idle_seconds","formats","operations","agent_bot_ids"],"description":"The envelope the inbox policy allows right now; a preference may only restrict inside it.","properties":{"modes":{"type":"array","description":"Modes up to the inbox mode (mildest first).","items":{"type":"string","enum":["faithful","suggest","automatic"],"description":"Maestro mode — `faithful` (the author's consolidated text leaves as typed), `suggest` (a transformation is proposed and waits for the author) or `automatic` (an approved transformation may leave without review)."}},"idle_seconds":{"type":"object","required":["min","max"],"description":"Idle bounds (max is the inbox collection ceiling).","properties":{"min":{"type":"integer","description":"Lower bound."},"max":{"type":"integer","description":"Upper bound."}}},"formats":{"type":"array","description":"Formats the inbox allows.","items":{"type":"string","enum":["text","buttons","list","cta","whatsapp_flow"]}},"operations":{"type":"array","description":"Operations the inbox allows.","items":{"type":"string","enum":["proofread","format","structure"]}},"agent_bot_ids":{"type":"array","description":"Maestro profiles the caller may pick.","items":{"type":"integer"}}}},"profile":{"type":"object","required":["agent_bot_id","resolution_source","owner_inbox_id","available","reason"],"description":"A Maestro profile resolution — never the bot configuration, secrets or the remote Maestro agent id.","properties":{"agent_bot_id":{"type":["integer","null"],"description":"The AgentBot that would transform the batches, or null when none resolves."},"resolution_source":{"type":"string","enum":["explicit_profile","inbox_binding"],"description":"`explicit_profile` (the agent picked an allowlisted profile) or `inbox_binding` (inherited from the inbox bot binding)."},"owner_inbox_id":{"type":["integer","null"],"description":"Inbox whose bot binding was inherited (a unified pair may borrow its sibling's); null for an explicit choice."},"available":{"type":"boolean","description":"Whether this profile can transform batches right now."},"reason":{"type":["string","null"],"enum":["not_allowlisted","not_maestro_linked","no_inbox_binding","inbox_binding_inactive",null],"description":"Why the profile is unavailable; null when available."}}}}},"example":{"inbox_id":17,"owner_inbox_id":17,"mirror":false,"version":2,"updated_at":"2026-09-29T14:00:37Z","flags":{"batching":true,"maestro":true,"rich_transform":true,"weighted_routing":true},"permissions":{"update":true},"overrides":{"mode":"suggest","idle_seconds":8},"fields":[{"key":"mode","value":"suggest","origin":"preference","inbox_value":"automatic","preference_value":"suggest","restricted_by":null}],"allowed":{"modes":["faithful","suggest","automatic"],"idle_seconds":{"min":1,"max":30},"formats":["text","buttons","whatsapp_flow"],"operations":["proofread","format"],"agent_bot_ids":[12]},"profile":{"agent_bot_id":12,"resolution_source":"inbox_binding","owner_inbox_id":17,"available":true,"reason":null}}}}},"401":{"description":"Unauthorized"},"404":{"description":"The inbox does not exist in this account (generic lookup failure), it is not a WhatsApp inbox this feature can configure (`inbox_not_supported`), or the batching module flag is off (`feature_disabled`).","content":{"application/json":{"schema":{"anyOf":[{"type":"object","additionalProperties":false,"required":["error"],"description":"The inbox is not a WhatsApp inbox this lane serves (or the conversation is a WhatsApp group).","properties":{"error":{"type":"string","enum":["inbox_not_supported"],"description":"Stable code."}}},{"type":"object","additionalProperties":false,"required":["error","feature"],"description":"Writes need the batching module flag; reads stay available.","properties":{"error":{"type":"string","enum":["feature_disabled"],"description":"Stable code."},"feature":{"type":"string","enum":["whatsapp_outbound_batching"],"description":"The flag that must be on."}}},{"type":"object","additionalProperties":false,"required":["error"],"description":"Generic lookup failure of the account API (the conversation or inbox does not exist in this account).","properties":{"error":{"type":"string","description":"Human-readable lookup failure (\"Resource could not be found\")."}}}]},"example":{"error":"feature_disabled","feature":"whatsapp_outbound_batching"}}}},"403":{"description":"The caller may not read (or, for writes, change) this outbound configuration.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","enum":["forbidden"],"description":"Policy refusal."}}},"example":{"error":"forbidden"}}}},"409":{"description":"`expected_version` differs from the stored version (0 means \"no row yet\"), including two concurrent FIRST writes where the other one created the row; re-read and retry.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error","current_version"],"properties":{"error":{"type":"string","enum":["configuration_version_conflict"],"description":"Stable code."},"current_version":{"type":"integer","minimum":0,"description":"The version stored now."}}},"example":{"error":"configuration_version_conflict","current_version":3}}}},"422":{"description":"`invalid_configuration` with field errors — the preference does not fit the inbox policy (`exceeds_policy`, `agent_profile_not_allowed`, `must_include_text`) or is malformed (`required`, `invalid_type`, `unknown_field`, `not_allowed`, `out_of_range`, …).","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error","errors"],"properties":{"error":{"type":"string","enum":["invalid_configuration"],"description":"Stable code."},"errors":{"type":"array","minItems":1,"description":"Field errors.","items":{"type":"object","additionalProperties":false,"required":["field","code"],"properties":{"field":{"type":"string","description":"Preference key (or `expected_version` / `preference`)."},"code":{"type":"string","enum":["required","invalid_type","unknown_field","not_allowed","invalid_format","duplicate","out_of_range","invalid","taken","exceeds_policy","agent_profile_not_allowed","must_include_text"],"description":"Stable validation code."}}}}}},"example":{"error":"invalid_configuration","errors":[{"field":"mode","code":"exceeds_policy"}]}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"in":"path","name":"inbox_id","required":true,"description":"Inbox id in the account (the preference is stored against the logical inbox).","schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["expected_version","preference"],"properties":{"expected_version":{"type":"integer","minimum":0,"description":"The `version` last read (0 when nothing was saved)."},"preference":{"type":"object","additionalProperties":false,"description":"Keys to change (sparse). Null restores inheritance.","properties":{"mode":{"type":["string","null"],"enum":["faithful","suggest","automatic",null],"description":"A mode no stronger than the inbox mode."},"idle_seconds":{"type":["integer","null"],"minimum":1,"maximum":30,"description":"Idle seconds inside the inbox collection ceiling."},"formats":{"type":["array","null"],"description":"Subset of the inbox formats (must include `text`).","items":{"type":"string","enum":["text","buttons","list","cta","whatsapp_flow"]}},"operations":{"type":["array","null"],"description":"Subset of the inbox operations.","items":{"type":"string","enum":["proofread","format","structure"]}},"agent_bot_id":{"type":["integer","null"],"minimum":1,"description":"One allowlisted Maestro profile of the inbox."}}}}},"example":{"expected_version":1,"preference":{"mode":"suggest","idle_seconds":8,"formats":["text","buttons"],"operations":["proofread"],"agent_bot_id":12}}}}}},"put":{"tags":["WhatsApp"],"operationId":"auto_put_api_v1_accounts_account_id_whatsapp_outbound_inboxes_inbox_id_preference","summary":"Update my WhatsApp outbound preference for an inbox","description":"Sparse update of the caller's own preference under optimistic locking (`expected_version`, 0 before the first save). Null restores inheritance for that key; unknown keys are refused with 422 `unknown_field`. Every stored value must fit what the inbox allows right now (`exceeds_policy`, `agent_profile_not_allowed`, `must_include_text`). Needs the `whatsapp_outbound_batching` flag. Audited.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The caller's own preference for the logical inbox.","content":{"application/json":{"schema":{"type":"object","required":["inbox_id","owner_inbox_id","mirror","version","updated_at","flags","permissions","overrides","fields","allowed","profile"],"properties":{"inbox_id":{"type":"integer","description":"The inbox in the path."},"owner_inbox_id":{"type":"integer","description":"The logical inbox the preference is stored against (the Cloud inbox of a unified pair)."},"mirror":{"type":"boolean","description":"True when the inbox in the path mirrors `owner_inbox_id` (same preference either way)."},"version":{"type":"integer","minimum":0,"description":"Preference version; send it as `expected_version` on PATCH (0 while nothing was saved)."},"updated_at":{"type":["string","null"],"format":"date-time","description":"Last save, or null."},"flags":{"type":"object","required":["batching","maestro","rich_transform","weighted_routing"],"description":"Module flags of the account.","properties":{"batching":{"type":"boolean","description":"Fragment collection."},"maestro":{"type":"boolean","description":"Maestro transformations."},"rich_transform":{"type":"boolean","description":"Rich formats and WhatsApp Flows."},"weighted_routing":{"type":"boolean","description":"Percentage routing of hybrid pairs."}}},"permissions":{"type":"object","required":["update"],"description":"What the caller may do.","properties":{"update":{"type":"boolean","description":"Whether the caller may PATCH the preference."}}},"overrides":{"type":"object","additionalProperties":true,"propertyNames":{"enum":["mode","idle_seconds","formats","operations","agent_bot_id"]},"description":"Exactly what the caller stored (sparse; a missing key inherits the inbox policy). `mode` string, `idle_seconds` integer, `formats`/`operations` string arrays, `agent_bot_id` integer."},"fields":{"type":"array","description":"The preference keys with their effective value and origin.","items":{"type":"object","required":["key","value","origin","inbox_value","preference_value","restricted_by"],"properties":{"key":{"type":"string","enum":["mode","idle_seconds","formats","operations"],"description":"Preference key."},"value":{"description":"Effective value for the caller (`mode` string, `idle_seconds` integer, lists of strings).","anyOf":[{"type":"string"},{"type":"integer"},{"type":"array","items":{"type":"string"}}]},"origin":{"type":"string","enum":["system_default","inbox","preference","restricted"],"description":"Where the effective value comes from."},"inbox_value":{"description":"What the inbox policy allows for this key right now.","anyOf":[{"type":"string"},{"type":"integer"},{"type":"array","items":{"type":"string"}}]},"preference_value":{"description":"The caller's stored value, or null (kept even when the policy no longer allows it).","anyOf":[{"type":"string"},{"type":"integer"},{"type":"array","items":{"type":"string"}},{"type":"null"}]},"restricted_by":{"type":["string","null"],"enum":["flag_disabled","policy_revoked",null],"description":"`flag_disabled` (a disabled module forces the value) or `policy_revoked` (the stored preference exceeds the current inbox policy and is ignored); null otherwise."}}}},"allowed":{"type":"object","required":["modes","idle_seconds","formats","operations","agent_bot_ids"],"description":"The envelope the inbox policy allows right now; a preference may only restrict inside it.","properties":{"modes":{"type":"array","description":"Modes up to the inbox mode (mildest first).","items":{"type":"string","enum":["faithful","suggest","automatic"],"description":"Maestro mode — `faithful` (the author's consolidated text leaves as typed), `suggest` (a transformation is proposed and waits for the author) or `automatic` (an approved transformation may leave without review)."}},"idle_seconds":{"type":"object","required":["min","max"],"description":"Idle bounds (max is the inbox collection ceiling).","properties":{"min":{"type":"integer","description":"Lower bound."},"max":{"type":"integer","description":"Upper bound."}}},"formats":{"type":"array","description":"Formats the inbox allows.","items":{"type":"string","enum":["text","buttons","list","cta","whatsapp_flow"]}},"operations":{"type":"array","description":"Operations the inbox allows.","items":{"type":"string","enum":["proofread","format","structure"]}},"agent_bot_ids":{"type":"array","description":"Maestro profiles the caller may pick.","items":{"type":"integer"}}}},"profile":{"type":"object","required":["agent_bot_id","resolution_source","owner_inbox_id","available","reason"],"description":"A Maestro profile resolution — never the bot configuration, secrets or the remote Maestro agent id.","properties":{"agent_bot_id":{"type":["integer","null"],"description":"The AgentBot that would transform the batches, or null when none resolves."},"resolution_source":{"type":"string","enum":["explicit_profile","inbox_binding"],"description":"`explicit_profile` (the agent picked an allowlisted profile) or `inbox_binding` (inherited from the inbox bot binding)."},"owner_inbox_id":{"type":["integer","null"],"description":"Inbox whose bot binding was inherited (a unified pair may borrow its sibling's); null for an explicit choice."},"available":{"type":"boolean","description":"Whether this profile can transform batches right now."},"reason":{"type":["string","null"],"enum":["not_allowlisted","not_maestro_linked","no_inbox_binding","inbox_binding_inactive",null],"description":"Why the profile is unavailable; null when available."}}}}},"example":{"inbox_id":17,"owner_inbox_id":17,"mirror":false,"version":2,"updated_at":"2026-09-29T14:00:37Z","flags":{"batching":true,"maestro":true,"rich_transform":true,"weighted_routing":true},"permissions":{"update":true},"overrides":{"mode":"suggest","idle_seconds":8},"fields":[{"key":"mode","value":"suggest","origin":"preference","inbox_value":"automatic","preference_value":"suggest","restricted_by":null}],"allowed":{"modes":["faithful","suggest","automatic"],"idle_seconds":{"min":1,"max":30},"formats":["text","buttons","whatsapp_flow"],"operations":["proofread","format"],"agent_bot_ids":[12]},"profile":{"agent_bot_id":12,"resolution_source":"inbox_binding","owner_inbox_id":17,"available":true,"reason":null}}}}},"401":{"description":"Unauthorized"},"404":{"description":"The inbox does not exist in this account (generic lookup failure), it is not a WhatsApp inbox this feature can configure (`inbox_not_supported`), or the batching module flag is off (`feature_disabled`).","content":{"application/json":{"schema":{"anyOf":[{"type":"object","additionalProperties":false,"required":["error"],"description":"The inbox is not a WhatsApp inbox this lane serves (or the conversation is a WhatsApp group).","properties":{"error":{"type":"string","enum":["inbox_not_supported"],"description":"Stable code."}}},{"type":"object","additionalProperties":false,"required":["error","feature"],"description":"Writes need the batching module flag; reads stay available.","properties":{"error":{"type":"string","enum":["feature_disabled"],"description":"Stable code."},"feature":{"type":"string","enum":["whatsapp_outbound_batching"],"description":"The flag that must be on."}}},{"type":"object","additionalProperties":false,"required":["error"],"description":"Generic lookup failure of the account API (the conversation or inbox does not exist in this account).","properties":{"error":{"type":"string","description":"Human-readable lookup failure (\"Resource could not be found\")."}}}]},"example":{"error":"feature_disabled","feature":"whatsapp_outbound_batching"}}}},"403":{"description":"The caller may not read (or, for writes, change) this outbound configuration.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","enum":["forbidden"],"description":"Policy refusal."}}},"example":{"error":"forbidden"}}}},"409":{"description":"`expected_version` differs from the stored version (0 means \"no row yet\"), including two concurrent FIRST writes where the other one created the row; re-read and retry.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error","current_version"],"properties":{"error":{"type":"string","enum":["configuration_version_conflict"],"description":"Stable code."},"current_version":{"type":"integer","minimum":0,"description":"The version stored now."}}},"example":{"error":"configuration_version_conflict","current_version":3}}}},"422":{"description":"`invalid_configuration` with field errors — the preference does not fit the inbox policy (`exceeds_policy`, `agent_profile_not_allowed`, `must_include_text`) or is malformed (`required`, `invalid_type`, `unknown_field`, `not_allowed`, `out_of_range`, …).","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error","errors"],"properties":{"error":{"type":"string","enum":["invalid_configuration"],"description":"Stable code."},"errors":{"type":"array","minItems":1,"description":"Field errors.","items":{"type":"object","additionalProperties":false,"required":["field","code"],"properties":{"field":{"type":"string","description":"Preference key (or `expected_version` / `preference`)."},"code":{"type":"string","enum":["required","invalid_type","unknown_field","not_allowed","invalid_format","duplicate","out_of_range","invalid","taken","exceeds_policy","agent_profile_not_allowed","must_include_text"],"description":"Stable validation code."}}}}}},"example":{"error":"invalid_configuration","errors":[{"field":"mode","code":"exceeds_policy"}]}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"in":"path","name":"inbox_id","required":true,"description":"Inbox id in the account (the preference is stored against the logical inbox).","schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["expected_version","preference"],"properties":{"expected_version":{"type":"integer","minimum":0,"description":"The `version` last read (0 when nothing was saved)."},"preference":{"type":"object","additionalProperties":false,"description":"Keys to change (sparse). Null restores inheritance.","properties":{"mode":{"type":["string","null"],"enum":["faithful","suggest","automatic",null],"description":"A mode no stronger than the inbox mode."},"idle_seconds":{"type":["integer","null"],"minimum":1,"maximum":30,"description":"Idle seconds inside the inbox collection ceiling."},"formats":{"type":["array","null"],"description":"Subset of the inbox formats (must include `text`).","items":{"type":"string","enum":["text","buttons","list","cta","whatsapp_flow"]}},"operations":{"type":["array","null"],"description":"Subset of the inbox operations.","items":{"type":"string","enum":["proofread","format","structure"]}},"agent_bot_id":{"type":["integer","null"],"minimum":1,"description":"One allowlisted Maestro profile of the inbox."}}}}},"example":{"expected_version":1,"preference":{"mode":"suggest","idle_seconds":8,"formats":["text","buttons"],"operations":["proofread"],"agent_bot_id":12}}}}}}},"/api/v1/accounts/{account_id}/whatsapp/outbound/inboxes/{inbox_id}/profiles":{"get":{"tags":["WhatsApp"],"operationId":"auto_get_api_v1_accounts_account_id_whatsapp_outbound_inboxes_inbox_id_profiles","summary":"List the Maestro profiles I may use in an inbox","description":"The Maestro profiles (AgentBots) the caller may pick for the logical inbox: only the policy allowlist's bots of this account that are still linked to Maestro, with the inherited default (and why it may be unavailable) and the profile that would effectively transform the caller's batches. Never exposes bot configuration, secrets, outgoing URLs or the remote Maestro agent id. Read-only; with the Maestro flag off the list is empty by construction.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The allowlisted profiles and the default/effective resolution.","content":{"application/json":{"schema":{"type":"object","required":["owner_inbox_id","payload","default_profile","effective_profile"],"properties":{"owner_inbox_id":{"type":"integer","description":"The logical inbox that owns the policy."},"payload":{"type":"array","description":"Allowlisted, still-eligible profiles in allowlist order.","items":{"type":"object","required":["agent_bot_id","name","description","thumbnail","default","selected"],"properties":{"agent_bot_id":{"type":"integer","description":"AgentBot id."},"name":{"type":"string","description":"Bot name."},"description":{"type":["string","null"],"description":"Bot description."},"thumbnail":{"type":"string","description":"Avatar URL, or an empty string without avatar."},"default":{"type":"boolean","description":"This is the inherited default (and it is available)."},"selected":{"type":"boolean","description":"The caller explicitly picked this profile."}}}},"default_profile":{"type":"object","required":["agent_bot_id","name","resolution_source","owner_inbox_id","available","reason"],"description":"A Maestro profile resolution with its public display name — never the bot configuration, secrets or the remote Maestro agent id.","properties":{"agent_bot_id":{"type":["integer","null"],"description":"The AgentBot that would transform the batches, or null when none resolves."},"name":{"type":["string","null"],"description":"Public display name of that AgentBot, or null when no bot resolves."},"resolution_source":{"type":"string","enum":["explicit_profile","inbox_binding"],"description":"`explicit_profile` (the agent picked an allowlisted profile) or `inbox_binding` (inherited from the inbox bot binding)."},"owner_inbox_id":{"type":["integer","null"],"description":"Inbox whose bot binding was inherited (a unified pair may borrow its sibling's); null for an explicit choice."},"available":{"type":"boolean","description":"Whether this profile can transform batches right now."},"reason":{"type":["string","null"],"enum":["not_allowlisted","not_maestro_linked","no_inbox_binding","inbox_binding_inactive",null],"description":"Why the profile is unavailable; null when available."}}},"effective_profile":{"type":"object","required":["agent_bot_id","name","resolution_source","owner_inbox_id","available","reason"],"description":"A Maestro profile resolution with its public display name — never the bot configuration, secrets or the remote Maestro agent id.","properties":{"agent_bot_id":{"type":["integer","null"],"description":"The AgentBot that would transform the batches, or null when none resolves."},"name":{"type":["string","null"],"description":"Public display name of that AgentBot, or null when no bot resolves."},"resolution_source":{"type":"string","enum":["explicit_profile","inbox_binding"],"description":"`explicit_profile` (the agent picked an allowlisted profile) or `inbox_binding` (inherited from the inbox bot binding)."},"owner_inbox_id":{"type":["integer","null"],"description":"Inbox whose bot binding was inherited (a unified pair may borrow its sibling's); null for an explicit choice."},"available":{"type":"boolean","description":"Whether this profile can transform batches right now."},"reason":{"type":["string","null"],"enum":["not_allowlisted","not_maestro_linked","no_inbox_binding","inbox_binding_inactive",null],"description":"Why the profile is unavailable; null when available."}}}}},"example":{"owner_inbox_id":17,"payload":[{"agent_bot_id":12,"name":"Revisor de atendimento","description":"Revisa ortografia e formatação das respostas.","thumbnail":"","default":true,"selected":false}],"default_profile":{"agent_bot_id":12,"name":"Revisor de atendimento","resolution_source":"inbox_binding","owner_inbox_id":17,"available":true,"reason":null},"effective_profile":{"agent_bot_id":12,"name":"Revisor de atendimento","resolution_source":"inbox_binding","owner_inbox_id":17,"available":true,"reason":null}}}}},"401":{"description":"Unauthorized"},"404":{"description":"The inbox does not exist in this account (generic lookup failure), or it is not a WhatsApp inbox this feature can configure (`inbox_not_supported`).","content":{"application/json":{"schema":{"anyOf":[{"type":"object","additionalProperties":false,"required":["error"],"description":"The inbox is not a WhatsApp inbox this lane serves (or the conversation is a WhatsApp group).","properties":{"error":{"type":"string","enum":["inbox_not_supported"],"description":"Stable code."}}},{"type":"object","additionalProperties":false,"required":["error"],"description":"Generic lookup failure of the account API (the conversation or inbox does not exist in this account).","properties":{"error":{"type":"string","description":"Human-readable lookup failure (\"Resource could not be found\")."}}}]},"example":{"error":"inbox_not_supported"}}}},"403":{"description":"The caller may not read (or, for writes, change) this outbound configuration.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","enum":["forbidden"],"description":"Policy refusal."}}},"example":{"error":"forbidden"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"in":"path","name":"inbox_id","required":true,"description":"Inbox id in the account; the Web inbox of a unified pair resolves to its Cloud owner.","schema":{"type":"integer"}}]}},"/api/v1/accounts/{account_id}/whatsapp/outbound/inboxes/{inbox_id}/flow_candidates":{"get":{"tags":["WhatsApp"],"operationId":"auto_get_api_v1_accounts_account_id_whatsapp_outbound_inboxes_inbox_id_flow_candidates","summary":"List the WhatsApp Flows I may use in an inbox","description":"The WhatsApp Flows an agent may choose when converting a batch: the newest version of each policy mapping whose Flow is published on the inbox's Cloud channel, with a compatible screen and seed schema. Sanitized — never the Meta flow id, the data-exchange endpoint, the Flow JSON or any key. Access is the inbox's own read permission plus the caller's operational scope. When the catalog exists but is unavailable for this inbox (no Cloud capability, format not allowed by the policy) the answer is 200 with an empty page and `meta.unavailable_reason`.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"One page of sanitized Flow candidates.","content":{"application/json":{"schema":{"type":"object","required":["payload","meta"],"properties":{"payload":{"type":"array","description":"Candidates ordered by label, mapping id and version.","items":{"type":"object","description":"One WhatsApp Flow the agent may choose — the newest version of a policy mapping, sanitized: local identities, names, schemas and closed reason codes only (never the Meta flow id, the data-exchange endpoint, the Flow JSON or any key).","required":["mapping_id","mapping_version","mapping_digest","label","intent","screen","seed_schema","required_fields","flow_cta","whatsapp_flow_id","flow_name","flow_status","flow_version","flow_revision_digest","flow_action","transport_requirement","proportional_eligible","evidence","maestro_compatible","maestro_unavailable_reason","eligible","unavailable_reason"],"properties":{"mapping_id":{"type":["string","null"],"description":"Mapping id, or null when a stored item could not be parsed."},"mapping_version":{"type":["integer","null"],"description":"Mapping version."},"mapping_digest":{"type":["string","null"],"pattern":"^[0-9a-f]{64}$","description":"Digest of the mapping version (a candidate conversion pins it)."},"label":{"type":["string","null"],"description":"Name shown to agents."},"intent":{"type":["string","null"],"description":"What the Flow is for."},"screen":{"type":["string","null"],"description":"Screen the Flow opens on."},"seed_schema":{"type":["object","null"],"additionalProperties":true,"description":"Flat JSON-Schema subset of the data the conversion may seed (see the policy mapping)."},"required_fields":{"type":"array","description":"Seed fields that must be filled.","items":{"type":"string"}},"flow_cta":{"type":["string","null"],"description":"Call-to-action text of the Flow message."},"whatsapp_flow_id":{"type":["integer","null"],"description":"Local WhatsApp Flow id."},"flow_name":{"type":["string","null"],"description":"Flow name."},"flow_status":{"type":["string","null"],"enum":["draft","published","deprecated","blocked","throttled",null],"description":"Flow publication status; null when the Flow is missing."},"flow_version":{"type":["string","null"],"description":"Version label of the newest published Flow revision."},"flow_revision_digest":{"type":["string","null"],"pattern":"^[0-9a-f]{64}$","description":"Digest of that published revision."},"flow_action":{"type":["string","null"],"enum":["navigate","data_exchange",null],"description":"How the Flow opens — `navigate` (static screens) or `data_exchange` (screens from the endpoint)."},"transport_requirement":{"type":"string","enum":["cloud"],"description":"A WhatsApp Flow only leaves through WhatsApp Cloud."},"proportional_eligible":{"type":"boolean","description":"Always false — a Flow never enters the percentage routing to WhatsApp Web."},"evidence":{"type":["string","null"],"enum":["official_replay","partial_contract","unverified","test_only",null],"description":"Evidence tier of the Flow action's send contract (`test_only` while the installation kill switch keeps Flow sends to test accounts); null when the Flow is missing."},"maestro_compatible":{"type":"boolean","description":"Whether Maestro may pick this mapping in a transformation."},"maestro_unavailable_reason":{"type":["string","null"],"enum":["screen_not_supported","intent_missing",null],"description":"Why Maestro may not pick it; null when compatible."},"eligible":{"type":"boolean","description":"Whether an agent may choose it now."},"unavailable_reason":{"type":["string","null"],"enum":["mapping_limit_exceeded","mapping_invalid","mapping_duplicate","mapping_revoked","mapping_digest_mismatch","mapping_superseded","flow_missing","flow_not_published","flow_meta_id_missing","flow_revision_mismatch","screen_missing","seed_schema_incompatible",null],"description":"The first failed eligibility check; null when eligible."}}}},"meta":{"type":"object","required":["count","current_page","per_page","total_pages","unavailable_reason"],"description":"Pagination and catalog availability.","properties":{"count":{"type":"integer","minimum":0,"description":"Candidates across all pages."},"current_page":{"type":"integer","minimum":1,"description":"Current page."},"per_page":{"type":"integer","minimum":1,"maximum":50,"description":"Items per page."},"total_pages":{"type":"integer","minimum":0,"description":"Number of pages."},"unavailable_reason":{"type":["string","null"],"enum":["feature_disabled","cloud_capability_unavailable","format_not_allowed",null],"description":"Why the whole catalog is unavailable for this inbox; null when available."}}}}},"example":{"payload":[{"mapping_id":"agendar-visita","mapping_version":2,"mapping_digest":"e45805152393fb5601be8835339f62b942a9f1d01e7bbeef0b22e8d089ddc1fa","label":"Agendar visita","intent":"schedule_visit","screen":"AGENDAMENTO","seed_schema":{"type":"object","properties":{"nome":{"type":"string","maxLength":80}},"required":["nome"],"additionalProperties":false},"required_fields":["nome"],"flow_cta":"Agendar","whatsapp_flow_id":5,"flow_name":"Agendamento de visita","flow_status":"published","flow_version":"3","flow_revision_digest":"6e5bbd34b46e2d73889dec0ac0868fe13be924010c93009023664f4f46027bbe","flow_action":"navigate","transport_requirement":"cloud","proportional_eligible":false,"evidence":"official_replay","maestro_compatible":true,"maestro_unavailable_reason":null,"eligible":true,"unavailable_reason":null}],"meta":{"count":1,"current_page":1,"per_page":25,"total_pages":1,"unavailable_reason":null}}}}},"401":{"description":"Missing or invalid credentials."},"404":{"description":"The inbox does not exist in the account or is outside the caller's operational scope (generic lookup failure), or the WhatsApp Flow catalog flags are off (`flow_not_eligible` with `reason: feature_disabled`).","content":{"application/json":{"schema":{"anyOf":[{"type":"object","additionalProperties":false,"required":["error","reason"],"properties":{"error":{"type":"string","enum":["flow_not_eligible"],"description":"Stable code."},"reason":{"type":"string","enum":["feature_disabled"],"description":"The WhatsApp Flow catalog flags are off for the account."}}},{"type":"object","additionalProperties":false,"required":["error"],"description":"Generic lookup failure of the account API (the conversation or inbox does not exist in this account).","properties":{"error":{"type":"string","description":"Human-readable lookup failure (\"Resource could not be found\")."}}}]},"example":{"error":"flow_not_eligible","reason":"feature_disabled"}}}},"403":{"description":"The caller is a member who may not read this inbox, or requested `layer=inbox` without permission to update the inbox outbound policy.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","enum":["forbidden"],"description":"Stable code."}}},"example":{"error":"forbidden"}}}},"422":{"description":"`layer` is neither `agent` nor `inbox`.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","enum":["invalid_layer"],"description":"Stable code."}}},"example":{"error":"invalid_layer"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"in":"path","name":"inbox_id","required":true,"description":"Inbox id in the account (a unified pair resolves to its Cloud capability inbox).","schema":{"type":"integer"}},{"in":"query","name":"q","required":false,"description":"Case-insensitive search over mapping id, label, intent and Flow name (first 100 characters used).","schema":{"type":"string"}},{"in":"query","name":"include_unavailable","required":false,"description":"Also list ineligible candidates with their `unavailable_reason`.","schema":{"type":"boolean","default":false}},{"in":"query","name":"layer","required":false,"description":"`agent` (default) is the caller's effective view — the inbox policy restricted by their own preference. `inbox` is the inbox policy alone, for the administration screen; it requires permission to update that policy.","schema":{"type":"string","enum":["agent","inbox"],"default":"agent"}},{"in":"query","name":"page","required":false,"description":"Page number (1-based).","schema":{"type":"integer","minimum":1,"default":1}},{"in":"query","name":"per_page","required":false,"description":"Items per page (at most 50).","schema":{"type":"integer","minimum":1,"maximum":50,"default":25}}]}},"/api/v1/accounts/{account_id}/whatsapp/outbound/inboxes/{inbox_id}/optimization_summary":{"get":{"tags":["WhatsApp"],"operationId":"auto_get_api_v1_accounts_account_id_whatsapp_outbound_inboxes_inbox_id_optimization_summary","summary":"Get the WhatsApp outbound optimization summary of an inbox","description":"The sending-optimization block of the WhatsApp Cost Center for ONE logical inbox over ONE explicit cohort of UTC days: consolidation of the agents' batches, weighted routing between WhatsApp Cloud and WhatsApp Web (WazMeow), the counterfactual cost, Maestro usage and operational health. `from`/`to` are inclusive YYYY-MM-DD UTC dates; without them the last 30 days are used, an inverted range is swapped and a range longer than 92 days keeps its last 92 days (`period.clamped`). Money is MAJOR units per native currency as decimal strings. Since 2026-10-01 the projected saving is MARGINAL to each number's estimated monthly service allowance; read `cost.evidence.rule`. Meta does not publish an allowance limit in the documentation tracked here. Per number and billing month, only the charges the avoided messages would have added (`max(0, S + A + W − 1000) − max(0, S − 1000)`, where S is the service messages Meta delivered in the month, A the messages consolidation avoided and W the replies the weighted routing sent by WhatsApp Web instead of Cloud) are priced, split between consolidation and the routing; avoided messages that stayed inside the tier are `free_tier_saved` (volume). Only SERVICE messages Meta delivered (charged, or inside the free tier) are priced; units inside an ad free entry point window are `free_entry_point` (volume) and undelivered ones are left out. A unit still awaiting its price is counted in `awaiting_price` without hiding the rest; `projection_available` is false only when nothing can be evaluated (`price_unconfirmed`, `no_accepted_messages`). The projected saving depends on the estimated allowance and the rate card, guarantees no billed saving and is never a Meta invoice. Same gate as the Cost Center: the `whatsapp_cost_center` flag, WhatsApp cost read permission and the caller's operational inbox scope. A GET never writes, reserves, sends or calls a provider.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The optimization summary of the cohort.","content":{"application/json":{"schema":{"type":"object","required":["inbox_id","requested_inbox_id","period","consolidation","routing","cost","ai","operations"],"properties":{"inbox_id":{"type":"integer","description":"The logical inbox the cohort was computed for."},"requested_inbox_id":{"type":"integer","description":"The inbox in the path."},"period":{"type":"object","required":["from","to","timezone","clamped"],"description":"The cohort actually used.","properties":{"from":{"type":"string","format":"date","description":"First day (inclusive)."},"to":{"type":"string","format":"date","description":"Last day (inclusive)."},"timezone":{"type":"string","enum":["UTC"],"description":"Days are UTC days."},"clamped":{"type":"boolean","description":"True when the requested range exceeded 92 days and was shortened to end on `to`."}}},"consolidation":{"type":"object","required":["materialized_batches","fragments","messages","accepted_messages","accepted_fragments","avoided_messages","fragments_per_message","excluded"],"description":"Batches that closed in the cohort. Only batches whose Message the provider ACCEPTED count as savings; canceled, expired, rejected, unknown and pending ones are reported apart.","properties":{"materialized_batches":{"type":"integer","minimum":0,"description":"Batches that became one Message."},"fragments":{"type":"integer","minimum":0,"description":"Fragments sealed into those batches."},"messages":{"type":"integer","minimum":0,"description":"Messages created (one per materialized batch)."},"accepted_messages":{"type":"integer","minimum":0,"description":"Of those, Messages the provider accepted."},"accepted_fragments":{"type":"integer","minimum":0,"description":"Fragments of the accepted batches."},"avoided_messages":{"type":"integer","minimum":0,"description":"Messages that did not have to be sent — Σ(fragments − 1) over accepted batches."},"fragments_per_message":{"type":["string","null"],"pattern":"^\\d+\\.\\d+$","description":"Accepted fragments per accepted Message (decimal string, 2 places); null without accepted Messages."},"excluded":{"type":"object","required":["canceled","expired","rejected","unknown","pending"],"description":"Batches that never count as savings.","properties":{"canceled":{"type":"integer","minimum":0,"description":"Canceled before sending."},"expired":{"type":"integer","minimum":0,"description":"Expired without sending."},"rejected":{"type":"integer","minimum":0,"description":"Message rejected by the provider."},"unknown":{"type":"integer","minimum":0,"description":"Message whose effect is not proven (pending financial reconciliation)."},"pending":{"type":"integer","minimum":0,"description":"Message still with the relay or the provider."}}}}},"routing":{"type":"object","required":["reserved","imposed","attempted","accepted","delivered","read","fallbacks","failed","unknown","reserved_web_share","accepted_web_share"],"description":"Weighted routing of the cohort, each measure read from its own authority.","properties":{"reserved":{"allOf":[{"type":"object","required":["cloud","web"],"description":"Count per transport — WhatsApp Cloud and WhatsApp Web (WazMeow).","properties":{"cloud":{"type":"integer","minimum":0,"description":"WhatsApp Cloud."},"web":{"type":"integer","minimum":0,"description":"WhatsApp Web."}}}],"description":"Entries whose route the percentage chose (consumed a routing slot)."},"imposed":{"allOf":[{"type":"object","required":["cloud","web"],"description":"Count per transport — WhatsApp Cloud and WhatsApp Web (WazMeow).","properties":{"cloud":{"type":"integer","minimum":0,"description":"WhatsApp Cloud."},"web":{"type":"integer","minimum":0,"description":"WhatsApp Web."}}}],"description":"Entries whose route was forced by capability, window or a manual choice (outside the percentage)."},"attempted":{"allOf":[{"type":"object","required":["cloud","web"],"description":"Count per transport — WhatsApp Cloud and WhatsApp Web (WazMeow).","properties":{"cloud":{"type":"integer","minimum":0,"description":"WhatsApp Cloud."},"web":{"type":"integer","minimum":0,"description":"WhatsApp Web."}}}],"description":"Parts whose provider attempt was observed, on the route actually attempted."},"accepted":{"allOf":[{"type":"object","required":["cloud","web"],"description":"Count per transport — WhatsApp Cloud and WhatsApp Web (WazMeow).","properties":{"cloud":{"type":"integer","minimum":0,"description":"WhatsApp Cloud."},"web":{"type":"integer","minimum":0,"description":"WhatsApp Web."}}}],"description":"Parts the provider accepted, on the transport that carried them."},"delivered":{"allOf":[{"type":"object","required":["cloud","web"],"description":"Count per transport — WhatsApp Cloud and WhatsApp Web (WazMeow).","properties":{"cloud":{"type":"integer","minimum":0,"description":"WhatsApp Cloud."},"web":{"type":"integer","minimum":0,"description":"WhatsApp Web."}}}],"description":"Accepted parts later reported delivered or read."},"read":{"allOf":[{"type":"object","required":["cloud","web"],"description":"Count per transport — WhatsApp Cloud and WhatsApp Web (WazMeow).","properties":{"cloud":{"type":"integer","minimum":0,"description":"WhatsApp Cloud."},"web":{"type":"integer","minimum":0,"description":"WhatsApp Web."}}}],"description":"Accepted parts later reported read."},"fallbacks":{"type":"integer","minimum":0,"description":"Accepted parts that left on a transport other than the reserved one."},"failed":{"type":"integer","minimum":0,"description":"Parts the provider rejected (never counted as accepted)."},"unknown":{"type":"integer","minimum":0,"description":"Parts whose effect is not proven."},"reserved_web_share":{"type":["string","null"],"pattern":"^\\d+\\.\\d$","description":"Percentage of WhatsApp Web among `reserved` (decimal string); null without reservations."},"accepted_web_share":{"type":["string","null"],"pattern":"^\\d+\\.\\d$","description":"Percentage of WhatsApp Web among `accepted`; null without accepted parts."}}},"cost":{"type":"object","required":["projection_available","unavailable_reason","estimated_savings","savings_by_source","observed_cost","avoided_by_source","paid_messages_avoided","free_tier_saved","before_regime","free_entry_point","awaiting_price","unpriced_units","priced_messages","unpriced_messages","free_messages","pending_reconciliation","evidence"],"description":"Counterfactual cost from the same cost ledger the Cost Center reads. Avoided units are the fragments consolidation saved on Cloud sends (N sealed fragments of an accepted Message would have been N messages) plus the replies the weighted routing reserved for and delivered by WhatsApp Web (each one a Cloud service message not sent). Per number × billing month × currency, projected money depends on the estimated monthly service allowance and each unit's market service rate. Meta does not publish an allowance limit in the documentation tracked here; read `cost.evidence.rule`. This projection guarantees no billed saving and is never a Meta invoice.","properties":{"projection_available":{"type":"boolean","description":"False only when nothing can be evaluated — no accepted message, or every avoided unit is still awaiting its price. Units still awaiting a price are counted in `awaiting_price` and the rest is still priced."},"unavailable_reason":{"type":["string","null"],"enum":["no_accepted_messages","price_unconfirmed",null],"description":"Why money is not shown; null when `projection_available` is true."},"estimated_savings":{"type":"array","description":"One entry per native billing currency, sorted by currency — never converted and never added across currencies. Empty when no billable message exists (and always empty when `projection_available` is false).","items":{"type":"object","required":["currency","amount"],"properties":{"currency":{"type":"string","description":"ISO 4217 native billing currency."},"amount":{"type":"string","pattern":"^\\d+\\.\\d+$","description":"Decimal amount in MAJOR units of that currency (e.g. \"12.4\" is 12.40), rounded to 6 decimals; never divided by 100."}}}},"savings_by_source":{"type":"object","required":["consolidation","routing"],"description":"The estimated savings split by where they came from.","properties":{"consolidation":{"type":"array","description":"One entry per native billing currency, sorted by currency — never converted and never added across currencies. Empty when no billable message exists (and always empty when `projection_available` is false).","items":{"type":"object","required":["currency","amount"],"properties":{"currency":{"type":"string","description":"ISO 4217 native billing currency."},"amount":{"type":"string","pattern":"^\\d+\\.\\d+$","description":"Decimal amount in MAJOR units of that currency (e.g. \"12.4\" is 12.40), rounded to 6 decimals; never divided by 100."}}}},"routing":{"type":"array","description":"One entry per native billing currency, sorted by currency — never converted and never added across currencies. Empty when no billable message exists (and always empty when `projection_available` is false).","items":{"type":"object","required":["currency","amount"],"properties":{"currency":{"type":"string","description":"ISO 4217 native billing currency."},"amount":{"type":"string","pattern":"^\\d+\\.\\d+$","description":"Decimal amount in MAJOR units of that currency (e.g. \"12.4\" is 12.40), rounded to 6 decimals; never divided by 100."}}}}}},"observed_cost":{"type":"array","description":"One entry per native billing currency, sorted by currency — never converted and never added across currencies. Empty when no billable message exists (and always empty when `projection_available` is false).","items":{"type":"object","required":["currency","amount"],"properties":{"currency":{"type":"string","description":"ISO 4217 native billing currency."},"amount":{"type":"string","pattern":"^\\d+\\.\\d+$","description":"Decimal amount in MAJOR units of that currency (e.g. \"12.4\" is 12.40), rounded to 6 decimals; never divided by 100."}}}},"avoided_by_source":{"type":"object","required":["consolidation","routing"],"description":"Avoided units by source (fragments saved by consolidation; replies sent by WhatsApp Web).","properties":{"consolidation":{"type":"integer","minimum":0},"routing":{"type":"integer","minimum":0}}},"paid_messages_avoided":{"type":"integer","minimum":0,"description":"Charges the avoided units would have added above the monthly free tier."},"free_tier_saved":{"type":"integer","minimum":0,"description":"Avoided units that stayed inside the monthly free tier — free-tier units kept, not money."},"before_regime":{"type":"integer","minimum":0,"description":"Avoided units in months before 2026-10-01, when service messages were free (volume only)."},"free_entry_point":{"type":"integer","minimum":0,"description":"Avoided units inside an ad free entry point window, where those messages would have been free (volume only)."},"awaiting_price":{"type":"integer","minimum":0,"description":"Avoided units whose message still has no confirmed price (no ledger row, pending delivery or unverified); kept out of the money."},"unpriced_units":{"type":"integer","minimum":0,"description":"Avoided units that would have been charged but whose market has no service rate in the rate card; their share is left out of the money."},"priced_messages":{"type":"integer","minimum":0,"description":"Accepted Messages with a confirmed price (free ones included)."},"unpriced_messages":{"type":"integer","minimum":0,"description":"Accepted Messages whose price is not confirmed yet."},"free_messages":{"type":"integer","minimum":0,"description":"Priced Messages that cost nothing (the saving there is volume only)."},"pending_reconciliation":{"type":"integer","minimum":0,"description":"Messages whose effect is unknown — pending financial reconciliation, never savings."},"evidence":{"type":"object","required":["rule","month_boundary"],"description":"Evidence tier of the pricing rule and of the free tier's month boundary (Meta does not document its time zone).","properties":{"rule":{"type":"string","enum":["unverified"]},"month_boundary":{"type":"string","enum":["unverified"]}}}}},"ai":{"type":"object","required":["requests","applied"],"description":"Maestro usage, kept apart from the consolidation savings.","properties":{"requests":{"type":"integer","minimum":0,"description":"Closed batches that asked Maestro at least once."},"applied":{"type":"integer","minimum":0,"description":"Materialized batches whose Message carries a Maestro result (approved suggestion or automatic)."}}},"operations":{"type":"object","required":["paused_reasons","pacing_deferrals","collect_seconds","queue_seconds","unknown"],"description":"Operational health of the lane, kept apart from any savings claim.","properties":{"paused_reasons":{"type":"object","description":"How many times a batch ENTERED `paused` in the cohort, per closed reason code, sorted by code. Keys are restricted to the pause/hold reason catalog; absent keys mean zero.","propertyNames":{"enum":["contact_replied","contact_merged","human_edit","transform_unavailable","transform_stale","transform_budget_exceeded","policy_revoked","flag_disabled","agent_profile_revoked","agent_profile_mismatch","text_limit_exceeded","transport_not_eligible","flow_candidate_stale","pacing_exhausted","predecessor_blocked","provider_rejected","dispatch_effect_unknown","window_closed","human_access_revoked","predecessor_pending"]},"additionalProperties":{"type":"integer","minimum":1}},"pacing_deferrals":{"type":"integer","minimum":0,"description":"Times a part waited in the cohort because its paced WhatsApp Web leg had reached the safe sending limit and no sibling transport could take it."},"collect_seconds":{"allOf":[{"type":"object","required":["p50","p95","samples"],"description":"Duration percentiles in seconds (one decimal), null without samples.","properties":{"p50":{"type":["number","null"],"description":"Median, in seconds."},"p95":{"type":["number","null"],"description":"95th percentile, in seconds."},"samples":{"type":"integer","minimum":0,"description":"Number of samples."}}}],"description":"First fragment → Message created, for materialized batches (idle wait, Maestro and review together)."},"queue_seconds":{"allOf":[{"type":"object","required":["p50","p95","samples"],"description":"Duration percentiles in seconds (one decimal), null without samples.","properties":{"p50":{"type":["number","null"],"description":"Median, in seconds."},"p95":{"type":["number","null"],"description":"95th percentile, in seconds."},"samples":{"type":"integer","minimum":0,"description":"Number of samples."}}}],"description":"Hand-off enqueued → provider attempt observed, per physical part."},"unknown":{"type":"object","required":["count","oldest_age_seconds"],"description":"Lane Messages whose effect is still not proven — a current backlog, not bound to the period.","properties":{"count":{"type":"integer","minimum":0,"description":"Messages in the backlog."},"oldest_age_seconds":{"type":["integer","null"],"minimum":0,"description":"Age of the oldest one, in seconds; null when the backlog is empty."}}}}}}},"example":{"inbox_id":17,"requested_inbox_id":17,"period":{"from":"2026-09-01","to":"2026-09-29","timezone":"UTC","clamped":false},"consolidation":{"materialized_batches":412,"fragments":1187,"messages":412,"accepted_messages":398,"accepted_fragments":1149,"avoided_messages":751,"fragments_per_message":"2.89","excluded":{"canceled":21,"expired":3,"rejected":6,"unknown":2,"pending":6}},"routing":{"reserved":{"cloud":280,"web":118},"imposed":{"cloud":37,"web":4},"attempted":{"cloud":316,"web":121},"accepted":{"cloud":311,"web":119},"delivered":{"cloud":305,"web":117},"read":{"cloud":244,"web":96},"fallbacks":3,"failed":6,"unknown":2,"reserved_web_share":"29.6","accepted_web_share":"27.7"},"cost":{"projection_available":true,"unavailable_reason":null,"estimated_savings":[{"currency":"BRL","amount":"1.4"}],"savings_by_source":{"consolidation":[{"currency":"BRL","amount":"1.05"}],"routing":[{"currency":"BRL","amount":"0.35"}]},"observed_cost":[{"currency":"BRL","amount":"15.625"}],"avoided_by_source":{"consolidation":300,"routing":100},"paid_messages_avoided":40,"free_tier_saved":360,"before_regime":0,"free_entry_point":0,"awaiting_price":0,"unpriced_units":0,"priced_messages":398,"unpriced_messages":0,"free_messages":348,"pending_reconciliation":2,"evidence":{"rule":"unverified","month_boundary":"unverified"}},"ai":{"requests":57,"applied":41},"operations":{"paused_reasons":{"contact_replied":14,"human_edit":9,"transform_stale":2},"pacing_deferrals":3,"collect_seconds":{"p50":11.4,"p95":38.2,"samples":412},"queue_seconds":{"p50":0.6,"p95":2.1,"samples":437},"unknown":{"count":2,"oldest_age_seconds":5120}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"The `whatsapp_cost_center` flag is off (empty body), the inbox does not exist or is outside the caller's operational scope (generic lookup failure), or it is not a WhatsApp inbox (`inbox_not_supported`).","content":{"application/json":{"schema":{"anyOf":[{"type":"object","additionalProperties":false,"required":["error"],"description":"The inbox is not a WhatsApp inbox this lane serves (or the conversation is a WhatsApp group).","properties":{"error":{"type":"string","enum":["inbox_not_supported"],"description":"Stable code."}}},{"type":"object","additionalProperties":false,"required":["error"],"description":"Generic lookup failure of the account API (the conversation or inbox does not exist in this account).","properties":{"error":{"type":"string","description":"Human-readable lookup failure (\"Resource could not be found\")."}}}]},"example":{"error":"inbox_not_supported"}}}},"403":{"description":"The caller may not read WhatsApp costs.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","enum":["forbidden"],"description":"Policy refusal."}}},"example":{"error":"forbidden"}}}},"422":{"description":"`from` or `to` is not a YYYY-MM-DD date.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","enum":["invalid_period"],"description":"Stable code."}}},"example":{"error":"invalid_period"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"in":"path","name":"inbox_id","required":true,"description":"Inbox id in the account (a unified pair's Web inbox resolves to its Cloud owner).","schema":{"type":"integer"}},{"in":"query","name":"from","required":false,"description":"First day of the cohort (inclusive, UTC). Defaults to 29 days before `to`.","schema":{"type":"string","format":"date"}},{"in":"query","name":"to","required":false,"description":"Last day of the cohort (inclusive, UTC). Defaults to today.","schema":{"type":"string","format":"date"}}]}},"/api/v1/accounts/{account_id}/whatsapp/outbound/conversations/{conversation_id}/fragments/receipt/{client_fragment_id}":{"get":{"tags":["WhatsApp"],"operationId":"auto_get_api_v1_accounts_account_id_whatsapp_outbound_conversations_conversation_id_fragments_receipt_client_fragment_id","summary":"Recover the receipt of one of my WhatsApp outbound fragments","description":"Recovers the durable receipt of a fragment after a lost response (timeout, reload), scoped to the account, the authenticated author and this conversation (or its canonical unified conversation). Sends nothing and never renews the collection window.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The receipt — the batch snapshot without the fragment list plus the fragment's id and ordinal.","content":{"application/json":{"schema":{"allOf":[{"type":"object","required":["schema_version","batch_id","conversation_id","inbox_id","author_id","state","state_reason","revision","server_now","first_at","last_changed_at","due_at","hard_deadline_at","expires_at","dispatch_committed_at","message_id","effective_mode","applied_mode","fragment_count","content_bytes","edit_lease","limits","routing","sequence_entry","content_purged","original_text","candidate","permissions"],"properties":{"schema_version":{"type":"integer","enum":[1],"description":"Version of this payload shape."},"batch_id":{"type":"string","format":"uuid","description":"Public id of the batch (the numeric id never leaves the server)."},"conversation_id":{"type":"integer","description":"Account-scoped conversation display id."},"inbox_id":{"type":"integer","description":"Inbox the batch was opened on (the logical inbox of the conversation)."},"author_id":{"type":["integer","null"],"description":"User id of the agent who wrote the batch."},"state":{"type":"string","enum":["collecting","processing","awaiting_review","paused","ready","materializing","materialized","canceled","expired"],"description":"Batch state — `collecting` (collection window open), `processing` (a Maestro transformation is claimed), `awaiting_review` (a candidate waits for the author), `paused` (a human decision is needed), `ready` (approved, due now), `materializing`, then the terminal `materialized` (exactly one Message exists), `canceled` or `expired` (nothing was sent). A batch state is not a delivery state."},"state_reason":{"type":["string","null"],"enum":["contact_replied","contact_merged","human_edit","transform_unavailable","transform_stale","transform_budget_exceeded","policy_revoked","flag_disabled","agent_profile_revoked","agent_profile_mismatch","text_limit_exceeded","transport_not_eligible","flow_candidate_stale","pacing_exhausted","predecessor_blocked","provider_rejected","dispatch_effect_unknown","window_closed","human_access_revoked","predecessor_pending",null],"description":"Closed pause/hold reason code (the dashboard translates it; the API never sends prose), or null when there is no reason to report."},"revision":{"type":"integer","minimum":1,"description":"Batch revision; send it back as `expected_revision` on every mutation (optimistic concurrency)."},"server_now":{"type":"string","format":"date-time","description":"Server clock at read time; clients compute countdowns from this offset, never from their own clock."},"first_at":{"type":"string","format":"date-time","description":"When the first fragment was accepted."},"last_changed_at":{"type":"string","format":"date-time","description":"Last accepted content change (typing and HTTP replays never move it)."},"due_at":{"type":["string","null"],"format":"date-time","description":"When the batch leaves by time — min(last change + idle, hard deadline); null unless collecting or ready."},"hard_deadline_at":{"type":"string","format":"date-time","description":"Fixed ceiling of the collection window (first fragment + maximum wait); never moves later."},"expires_at":{"type":["string","null"],"format":"date-time","description":"When a never-sent batch expires without sending (24 h after the last change); null once terminal or committed."},"dispatch_committed_at":{"type":["string","null"],"format":"date-time","description":"When the local dispatch commitment happened (edit and cancel close there); not provider acceptance."},"message_id":{"type":["integer","null"],"description":"The one Message this batch became (set when materialized); delivery truth belongs to that Message."},"effective_mode":{"type":"string","enum":["faithful","suggest","automatic"],"description":"Maestro mode — `faithful` (the author's consolidated text leaves as typed), `suggest` (a transformation is proposed and waits for the author) or `automatic` (an approved transformation may leave without review)."},"applied_mode":{"type":["string","null"],"enum":["faithful","original","candidate","candidate_unchanged","automatic","automatic_unchanged","fallback_original",null],"description":"What actually left — `faithful` (text as typed), `original` (author chose the original), `candidate` (approved suggestion), `candidate_unchanged` (approved suggestion in which Maestro changed nothing), `automatic` (automatic mode result), `automatic_unchanged` (automatic mode, Maestro changed nothing, the original left) or `fallback_original` (Maestro could not be used and the policy sent the original). Null until the batch is finalized."},"fragment_count":{"type":"integer","minimum":0,"maximum":32,"description":"Number of active fragments."},"content_bytes":{"type":"integer","minimum":0,"maximum":16384,"description":"UTF-8 size of the active text, in bytes."},"edit_lease":{"type":"object","required":["active","expires_at"],"description":"The 2-minute edit lease a pause grants to the editing tab (the token itself is never exposed here).","properties":{"active":{"type":"boolean","description":"Whether some tab currently holds the edit lease."},"expires_at":{"type":["string","null"],"format":"date-time","description":"When the last granted lease ends; null when none was granted."}}},"limits":{"type":"object","required":["max_text_characters","max_fragments","max_batch_bytes"],"description":"Text limits of the conversation's logical transport and of one batch.","properties":{"max_text_characters":{"type":["integer","null"],"description":"Character ceiling of one text message on this inbox's channel (4096 on WhatsApp Cloud), or null when the channel declares none."},"max_fragments":{"type":"integer","description":"Maximum number of active fragments in one batch (32)."},"max_batch_bytes":{"type":"integer","description":"Maximum UTF-8 size of the active text of one batch, in bytes (16384)."}}},"routing":{"type":"object","required":["mode","web_percent","reserved"],"description":"Routing policy of the conversation's hybrid pair (WhatsApp Cloud + WhatsApp Web via WazMeow).","properties":{"mode":{"type":"string","enum":["legacy","weighted"],"description":"`weighted` when the percentage routing of the pair is on for this lane; `legacy` otherwise."},"web_percent":{"type":["integer","null"],"minimum":0,"maximum":100,"description":"Share of new contacts routed to WhatsApp Web under `weighted`; null under `legacy`."},"reserved":{"type":"boolean","description":"True once a routing decision was recorded for this entry."}}},"sequence_entry":{"type":["object","null"],"description":"The batch's place in the conversation's dispatch order, or null.","required":["dispatch_id","state","blocking_reason","blocking_dispatch_id"],"properties":{"dispatch_id":{"type":"string","format":"uuid","description":"Public id of the sequence entry that owns this batch."},"state":{"type":"string","enum":["open","committed","held","settled","abandoned","canceled"],"description":"Sequence entry state — `open` (not committed yet), `committed` (its Messages exist and wait for their turn or the provider), `held` (a part needs a human disposition), then the terminal `settled` (every part accepted by the provider), `abandoned` (a human abandoned it) or `canceled` (canceled before the dispatch commitment)."},"blocking_reason":{"type":["string","null"],"enum":["predecessor_blocked","predecessor_pending",null],"description":"Why this entry still waits for an earlier entry of the conversation — `predecessor_blocked` (an earlier entry needs a human decision; new outputs are refused with `sequence_blocked`) or `predecessor_pending` (earlier entries are only in flight). Null when nothing blocks it."},"blocking_dispatch_id":{"type":["string","null"],"format":"uuid","description":"The earliest entry this one waits for, or null."}}},"content_purged":{"type":"boolean","description":"True once retention removed the batch text (digests and counters remain)."},"original_text":{"type":["string","null"],"description":"The consolidated original text as last sealed for processing; null before the first seal or once purged."},"candidate":{"type":["object","null"],"description":"The Maestro proposal waiting for the author's review, or null. Its `digest` is the value `accept_candidate` must present. Never carries prompts, grants, model output metadata or provider data.","properties":{"outcome":{"type":"string","enum":["unchanged","rewritten","structured","unavailable","requires_review"],"description":"Maestro outcome of the transformation."},"format":{"type":"string","enum":["text","buttons","list","cta","whatsapp_flow"],"description":"Output format of the candidate."},"text":{"type":["string","null"],"description":"Proposed text (the message body of a structured candidate)."},"data":{"type":"object","additionalProperties":true,"description":"Format-specific structure: `{}` for text; `buttons` (1–3 `{title, id?}`) plus optional `header`/`footer` for buttons; `sections` of rows plus optional `button` for a list; `{display_text, url}` for a call to action; `{seed?, cta?}` for a WhatsApp Flow. Button and row ids are assigned by the server."},"asset_ref":{"type":["object","null"],"description":"The pinned WhatsApp Flow mapping version of a `whatsapp_flow` candidate; null for any other format.","required":["mapping_id","mapping_version","mapping_digest"],"properties":{"mapping_id":{"type":"string","description":"Flow mapping id of the inbox policy."},"mapping_version":{"type":"integer","minimum":1,"description":"Immutable version of that mapping."},"mapping_digest":{"type":"string","pattern":"^[0-9a-f]{64}$","description":"SHA-256 digest of that mapping version."}}},"reason_codes":{"type":"array","maxItems":16,"description":"Closed-vocabulary codes Maestro reported for the proposal (lower snake case).","items":{"type":"string","pattern":"^[a-z][a-z0-9_]{0,63}$"}},"requires_review":{"type":"boolean","description":"Whether the proposal needs a human review before it can leave."},"digest":{"type":"string","pattern":"^[0-9a-f]{64}$","description":"SHA-256 digest of the candidate's final draft; send it back as `digest` in `accept_candidate`."}}},"permissions":{"type":"object","required":["edit","remove_fragment","pause","resume","flush","use_original","accept_candidate","suggest","cancel"],"description":"What the CURRENT caller may do with this batch right now, computed at read time from the author rule (content actions are the author's only; `cancel` is the author's or an inbox manager's), the batch state and the current lane configuration. Every key is false once the dispatch commitment happened or the batch is terminal.","properties":{"edit":{"type":"boolean","description":"Edit a fragment (paused batch, with the edit lease of the pausing tab)."},"remove_fragment":{"type":"boolean","description":"Remove a fragment (collecting or paused batch)."},"pause":{"type":"boolean","description":"Pause the batch to edit it."},"resume":{"type":"boolean","description":"Resume a paused batch (needs the batching module on)."},"flush":{"type":"boolean","description":"Send now, skipping only the idle wait (needs the batching module on)."},"use_original":{"type":"boolean","description":"Send the author's consolidated text now, without Maestro."},"accept_candidate":{"type":"boolean","description":"Approve the candidate waiting for review."},"suggest":{"type":"boolean","description":"Ask Maestro for a suggestion of the current revision."},"cancel":{"type":"boolean","description":"Cancel the batch (author or inbox manager)."}}}}},{"type":"object","required":["fragment_id","fragment_ordinal"],"properties":{"fragment_id":{"type":"string","format":"uuid","description":"Public id of the fragment."},"fragment_ordinal":{"type":"integer","minimum":1,"description":"Its ordinal in the batch."}}}]},"example":{"schema_version":1,"batch_id":"5f0c2a8e-3b1d-4c6e-9a7f-1d2e3f4a5b60","conversation_id":1284,"inbox_id":17,"author_id":9,"state":"collecting","state_reason":null,"revision":2,"server_now":"2026-09-29T14:03:12.040Z","first_at":"2026-09-29T14:03:05.100Z","last_changed_at":"2026-09-29T14:03:12.000Z","due_at":"2026-09-29T14:03:22.000Z","hard_deadline_at":"2026-09-29T14:03:35.100Z","expires_at":"2026-09-30T14:03:12.000Z","dispatch_committed_at":null,"message_id":null,"effective_mode":"faithful","applied_mode":null,"fragment_count":2,"content_bytes":74,"edit_lease":{"active":false,"expires_at":null},"limits":{"max_text_characters":4096,"max_fragments":32,"max_batch_bytes":16384},"routing":{"mode":"weighted","web_percent":30,"reserved":false},"sequence_entry":{"dispatch_id":"7e2b9c44-1d5f-4a3e-8b6c-9d0e1f2a3b4c","state":"open","blocking_reason":null,"blocking_dispatch_id":null},"content_purged":false,"original_text":null,"candidate":null,"permissions":{"edit":true,"remove_fragment":true,"pause":true,"resume":false,"flush":true,"use_original":true,"accept_candidate":false,"suggest":false,"cancel":true},"fragment_id":"1c8f5d32-7b40-4e69-9f28-3d5c7e9a1b23","fragment_ordinal":2}}}},"401":{"description":"Unauthorized"},"404":{"description":"No fragment with this id for this author in this conversation (`not_found`), or the conversation does not exist.","content":{"application/json":{"schema":{"anyOf":[{"type":"object","additionalProperties":false,"required":["error"],"description":"The batch, fragment, entry or receipt does not exist for this caller in this conversation.","properties":{"error":{"type":"string","enum":["not_found"],"description":"Stable lane code."}}},{"type":"object","additionalProperties":false,"required":["error"],"description":"Generic lookup failure of the account API (the conversation or inbox does not exist in this account).","properties":{"error":{"type":"string","description":"Human-readable lookup failure (\"Resource could not be found\")."}}}]},"example":{"error":"not_found"}}}},"403":{"description":"Policy refusal — the caller cannot see the conversation, or the action belongs to the batch/entry author (or an inbox manager for `cancel`/`abandon`). Agent bot tokens are never actors of this lane.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","enum":["forbidden"],"description":"Policy refusal."}}},"example":{"error":"forbidden"}}}},"410":{"description":"The receipt expired — retention already purged the fragment's text.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","enum":["receipt_expired"],"description":"Stable code."}}},"example":{"error":"receipt_expired"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"in":"path","name":"conversation_id","required":true,"description":"Account-scoped conversation display id.","schema":{"type":"integer"}},{"in":"path","name":"client_fragment_id","required":true,"description":"The `client_fragment_id` the fragment was created with.","schema":{"type":"string","format":"uuid"}}]}},"/api/v1/accounts/{account_id}/whatsapp/outbound/conversations/{conversation_id}/fragments":{"post":{"tags":["WhatsApp"],"operationId":"auto_post_api_v1_accounts_account_id_whatsapp_outbound_conversations_conversation_id_fragments","summary":"Add a text fragment to my WhatsApp outbound batch","description":"Persists ONE text fragment the agent confirmed (Enter) and returns a durable receipt — never a Message: no provider call, no message event, no first-reply mark. The server clock owns the collection window. The fragment joins the author's collecting batch of the same context (reply target, explicit transport, signature block) while its window is open; otherwise a new batch opens (closing the author's other collecting batches of the conversation) and bot automation of the conversation pauses. Idempotent per author and `client_fragment_id`: the same id with the same text and context returns the recorded receipt without renewing the idle timer. Writes follow the canonical conversation of a unified hybrid pair. Human agents only; needs the batching module.","security":[{"userApiKey":[]}],"responses":{"401":{"description":"Unauthorized"},"404":{"description":"The conversation does not exist in the account (generic lookup failure), the inbox or conversation is not served by this lane (`inbox_not_supported`, e.g. a WhatsApp group), or the batching module is off (`feature_disabled`).","content":{"application/json":{"schema":{"anyOf":[{"type":"object","additionalProperties":false,"required":["error"],"description":"The inbox is not a WhatsApp inbox this lane serves (or the conversation is a WhatsApp group).","properties":{"error":{"type":"string","enum":["inbox_not_supported"],"description":"Stable code."}}},{"type":"object","additionalProperties":false,"required":["error","feature"],"properties":{"error":{"type":"string","enum":["feature_disabled"],"description":"Stable code."},"feature":{"type":"string","enum":["whatsapp_outbound_batching"],"description":"The module that must be on."}}},{"type":"object","additionalProperties":false,"required":["error"],"description":"Generic lookup failure of the account API (the conversation or inbox does not exist in this account).","properties":{"error":{"type":"string","description":"Human-readable lookup failure (\"Resource could not be found\")."}}}]},"example":{"error":"feature_disabled","feature":"whatsapp_outbound_batching"}}}},"202":{"description":"The fragment is durable (new or replayed). The receipt is the batch snapshot without the fragment list plus the accepted fragment's id and ordinal. This is not a Message.","content":{"application/json":{"schema":{"allOf":[{"type":"object","required":["schema_version","batch_id","conversation_id","inbox_id","author_id","state","state_reason","revision","server_now","first_at","last_changed_at","due_at","hard_deadline_at","expires_at","dispatch_committed_at","message_id","effective_mode","applied_mode","fragment_count","content_bytes","edit_lease","limits","routing","sequence_entry","content_purged","original_text","candidate","permissions"],"properties":{"schema_version":{"type":"integer","enum":[1],"description":"Version of this payload shape."},"batch_id":{"type":"string","format":"uuid","description":"Public id of the batch (the numeric id never leaves the server)."},"conversation_id":{"type":"integer","description":"Account-scoped conversation display id."},"inbox_id":{"type":"integer","description":"Inbox the batch was opened on (the logical inbox of the conversation)."},"author_id":{"type":["integer","null"],"description":"User id of the agent who wrote the batch."},"state":{"type":"string","enum":["collecting","processing","awaiting_review","paused","ready","materializing","materialized","canceled","expired"],"description":"Batch state — `collecting` (collection window open), `processing` (a Maestro transformation is claimed), `awaiting_review` (a candidate waits for the author), `paused` (a human decision is needed), `ready` (approved, due now), `materializing`, then the terminal `materialized` (exactly one Message exists), `canceled` or `expired` (nothing was sent). A batch state is not a delivery state."},"state_reason":{"type":["string","null"],"enum":["contact_replied","contact_merged","human_edit","transform_unavailable","transform_stale","transform_budget_exceeded","policy_revoked","flag_disabled","agent_profile_revoked","agent_profile_mismatch","text_limit_exceeded","transport_not_eligible","flow_candidate_stale","pacing_exhausted","predecessor_blocked","provider_rejected","dispatch_effect_unknown","window_closed","human_access_revoked","predecessor_pending",null],"description":"Closed pause/hold reason code (the dashboard translates it; the API never sends prose), or null when there is no reason to report."},"revision":{"type":"integer","minimum":1,"description":"Batch revision; send it back as `expected_revision` on every mutation (optimistic concurrency)."},"server_now":{"type":"string","format":"date-time","description":"Server clock at read time; clients compute countdowns from this offset, never from their own clock."},"first_at":{"type":"string","format":"date-time","description":"When the first fragment was accepted."},"last_changed_at":{"type":"string","format":"date-time","description":"Last accepted content change (typing and HTTP replays never move it)."},"due_at":{"type":["string","null"],"format":"date-time","description":"When the batch leaves by time — min(last change + idle, hard deadline); null unless collecting or ready."},"hard_deadline_at":{"type":"string","format":"date-time","description":"Fixed ceiling of the collection window (first fragment + maximum wait); never moves later."},"expires_at":{"type":["string","null"],"format":"date-time","description":"When a never-sent batch expires without sending (24 h after the last change); null once terminal or committed."},"dispatch_committed_at":{"type":["string","null"],"format":"date-time","description":"When the local dispatch commitment happened (edit and cancel close there); not provider acceptance."},"message_id":{"type":["integer","null"],"description":"The one Message this batch became (set when materialized); delivery truth belongs to that Message."},"effective_mode":{"type":"string","enum":["faithful","suggest","automatic"],"description":"Maestro mode — `faithful` (the author's consolidated text leaves as typed), `suggest` (a transformation is proposed and waits for the author) or `automatic` (an approved transformation may leave without review)."},"applied_mode":{"type":["string","null"],"enum":["faithful","original","candidate","candidate_unchanged","automatic","automatic_unchanged","fallback_original",null],"description":"What actually left — `faithful` (text as typed), `original` (author chose the original), `candidate` (approved suggestion), `candidate_unchanged` (approved suggestion in which Maestro changed nothing), `automatic` (automatic mode result), `automatic_unchanged` (automatic mode, Maestro changed nothing, the original left) or `fallback_original` (Maestro could not be used and the policy sent the original). Null until the batch is finalized."},"fragment_count":{"type":"integer","minimum":0,"maximum":32,"description":"Number of active fragments."},"content_bytes":{"type":"integer","minimum":0,"maximum":16384,"description":"UTF-8 size of the active text, in bytes."},"edit_lease":{"type":"object","required":["active","expires_at"],"description":"The 2-minute edit lease a pause grants to the editing tab (the token itself is never exposed here).","properties":{"active":{"type":"boolean","description":"Whether some tab currently holds the edit lease."},"expires_at":{"type":["string","null"],"format":"date-time","description":"When the last granted lease ends; null when none was granted."}}},"limits":{"type":"object","required":["max_text_characters","max_fragments","max_batch_bytes"],"description":"Text limits of the conversation's logical transport and of one batch.","properties":{"max_text_characters":{"type":["integer","null"],"description":"Character ceiling of one text message on this inbox's channel (4096 on WhatsApp Cloud), or null when the channel declares none."},"max_fragments":{"type":"integer","description":"Maximum number of active fragments in one batch (32)."},"max_batch_bytes":{"type":"integer","description":"Maximum UTF-8 size of the active text of one batch, in bytes (16384)."}}},"routing":{"type":"object","required":["mode","web_percent","reserved"],"description":"Routing policy of the conversation's hybrid pair (WhatsApp Cloud + WhatsApp Web via WazMeow).","properties":{"mode":{"type":"string","enum":["legacy","weighted"],"description":"`weighted` when the percentage routing of the pair is on for this lane; `legacy` otherwise."},"web_percent":{"type":["integer","null"],"minimum":0,"maximum":100,"description":"Share of new contacts routed to WhatsApp Web under `weighted`; null under `legacy`."},"reserved":{"type":"boolean","description":"True once a routing decision was recorded for this entry."}}},"sequence_entry":{"type":["object","null"],"description":"The batch's place in the conversation's dispatch order, or null.","required":["dispatch_id","state","blocking_reason","blocking_dispatch_id"],"properties":{"dispatch_id":{"type":"string","format":"uuid","description":"Public id of the sequence entry that owns this batch."},"state":{"type":"string","enum":["open","committed","held","settled","abandoned","canceled"],"description":"Sequence entry state — `open` (not committed yet), `committed` (its Messages exist and wait for their turn or the provider), `held` (a part needs a human disposition), then the terminal `settled` (every part accepted by the provider), `abandoned` (a human abandoned it) or `canceled` (canceled before the dispatch commitment)."},"blocking_reason":{"type":["string","null"],"enum":["predecessor_blocked","predecessor_pending",null],"description":"Why this entry still waits for an earlier entry of the conversation — `predecessor_blocked` (an earlier entry needs a human decision; new outputs are refused with `sequence_blocked`) or `predecessor_pending` (earlier entries are only in flight). Null when nothing blocks it."},"blocking_dispatch_id":{"type":["string","null"],"format":"uuid","description":"The earliest entry this one waits for, or null."}}},"content_purged":{"type":"boolean","description":"True once retention removed the batch text (digests and counters remain)."},"original_text":{"type":["string","null"],"description":"The consolidated original text as last sealed for processing; null before the first seal or once purged."},"candidate":{"type":["object","null"],"description":"The Maestro proposal waiting for the author's review, or null. Its `digest` is the value `accept_candidate` must present. Never carries prompts, grants, model output metadata or provider data.","properties":{"outcome":{"type":"string","enum":["unchanged","rewritten","structured","unavailable","requires_review"],"description":"Maestro outcome of the transformation."},"format":{"type":"string","enum":["text","buttons","list","cta","whatsapp_flow"],"description":"Output format of the candidate."},"text":{"type":["string","null"],"description":"Proposed text (the message body of a structured candidate)."},"data":{"type":"object","additionalProperties":true,"description":"Format-specific structure: `{}` for text; `buttons` (1–3 `{title, id?}`) plus optional `header`/`footer` for buttons; `sections` of rows plus optional `button` for a list; `{display_text, url}` for a call to action; `{seed?, cta?}` for a WhatsApp Flow. Button and row ids are assigned by the server."},"asset_ref":{"type":["object","null"],"description":"The pinned WhatsApp Flow mapping version of a `whatsapp_flow` candidate; null for any other format.","required":["mapping_id","mapping_version","mapping_digest"],"properties":{"mapping_id":{"type":"string","description":"Flow mapping id of the inbox policy."},"mapping_version":{"type":"integer","minimum":1,"description":"Immutable version of that mapping."},"mapping_digest":{"type":"string","pattern":"^[0-9a-f]{64}$","description":"SHA-256 digest of that mapping version."}}},"reason_codes":{"type":"array","maxItems":16,"description":"Closed-vocabulary codes Maestro reported for the proposal (lower snake case).","items":{"type":"string","pattern":"^[a-z][a-z0-9_]{0,63}$"}},"requires_review":{"type":"boolean","description":"Whether the proposal needs a human review before it can leave."},"digest":{"type":"string","pattern":"^[0-9a-f]{64}$","description":"SHA-256 digest of the candidate's final draft; send it back as `digest` in `accept_candidate`."}}},"permissions":{"type":"object","required":["edit","remove_fragment","pause","resume","flush","use_original","accept_candidate","suggest","cancel"],"description":"What the CURRENT caller may do with this batch right now, computed at read time from the author rule (content actions are the author's only; `cancel` is the author's or an inbox manager's), the batch state and the current lane configuration. Every key is false once the dispatch commitment happened or the batch is terminal.","properties":{"edit":{"type":"boolean","description":"Edit a fragment (paused batch, with the edit lease of the pausing tab)."},"remove_fragment":{"type":"boolean","description":"Remove a fragment (collecting or paused batch)."},"pause":{"type":"boolean","description":"Pause the batch to edit it."},"resume":{"type":"boolean","description":"Resume a paused batch (needs the batching module on)."},"flush":{"type":"boolean","description":"Send now, skipping only the idle wait (needs the batching module on)."},"use_original":{"type":"boolean","description":"Send the author's consolidated text now, without Maestro."},"accept_candidate":{"type":"boolean","description":"Approve the candidate waiting for review."},"suggest":{"type":"boolean","description":"Ask Maestro for a suggestion of the current revision."},"cancel":{"type":"boolean","description":"Cancel the batch (author or inbox manager)."}}}}},{"type":"object","required":["fragment_id","fragment_ordinal"],"properties":{"fragment_id":{"type":"string","format":"uuid","description":"Public id of the accepted fragment."},"fragment_ordinal":{"type":"integer","minimum":1,"description":"Its ordinal in the batch."}}}]},"example":{"schema_version":1,"batch_id":"5f0c2a8e-3b1d-4c6e-9a7f-1d2e3f4a5b60","conversation_id":1284,"inbox_id":17,"author_id":9,"state":"collecting","state_reason":null,"revision":2,"server_now":"2026-09-29T14:03:12.040Z","first_at":"2026-09-29T14:03:05.100Z","last_changed_at":"2026-09-29T14:03:12.000Z","due_at":"2026-09-29T14:03:22.000Z","hard_deadline_at":"2026-09-29T14:03:35.100Z","expires_at":"2026-09-30T14:03:12.000Z","dispatch_committed_at":null,"message_id":null,"effective_mode":"faithful","applied_mode":null,"fragment_count":2,"content_bytes":74,"edit_lease":{"active":false,"expires_at":null},"limits":{"max_text_characters":4096,"max_fragments":32,"max_batch_bytes":16384},"routing":{"mode":"weighted","web_percent":30,"reserved":false},"sequence_entry":{"dispatch_id":"7e2b9c44-1d5f-4a3e-8b6c-9d0e1f2a3b4c","state":"open","blocking_reason":null,"blocking_dispatch_id":null},"content_purged":false,"original_text":null,"candidate":null,"permissions":{"edit":true,"remove_fragment":true,"pause":true,"resume":false,"flush":true,"use_original":true,"accept_candidate":false,"suggest":false,"cancel":true},"fragment_id":"1c8f5d32-7b40-4e69-9f28-3d5c7e9a1b23","fragment_ordinal":2}}}},"400":{"description":"Malformed request — `client_fragment_id` is not a UUID, `content` is not text or is blank, `context` has an unknown key or an invalid value, `context.in_reply_to` is not a message of this conversation, or `expected_batch_revision` is not a positive integer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error","errors"],"properties":{"error":{"type":"string","enum":["invalid_request"],"description":"Malformed request (400)."},"errors":{"type":"array","minItems":1,"description":"The offending request field(s), each with a stable validation code.","items":{"type":"object","additionalProperties":false,"required":["field","code"],"properties":{"field":{"type":"string","description":"Request field path, e.g. `content`, `context.in_reply_to`, `request_id`, `expected_revision`."},"code":{"type":"string","enum":["invalid_format","required","invalid_type","blank","not_allowed","unknown_field","out_of_range","not_found"],"description":"Stable validation code of that field."}}}}}},"example":{"error":"invalid_request","errors":[{"field":"context.in_reply_to","code":"not_found"}]}}}},"403":{"description":"Policy refusal — the caller cannot see the conversation, or the action belongs to the batch/entry author (or an inbox manager for `cancel`/`abandon`). Agent bot tokens are never actors of this lane.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","enum":["forbidden"],"description":"Policy refusal."}}},"example":{"error":"forbidden"}}}},"409":{"description":"`fragment_id_conflict` (the same `client_fragment_id` with another text, conversation or context), `batch_revision_conflict` (`expected_batch_revision` is stale), `sequence_blocked` (an earlier entry of the conversation needs a human decision — resolve `blocking_dispatch_id` first) or `conversation_changed` (the conversation was merged or moved; re-read it).","content":{"application/json":{"schema":{"anyOf":[{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","enum":["fragment_id_conflict","conversation_changed"],"description":"Stable code."}}},{"type":"object","additionalProperties":false,"required":["error","current_revision","batch_id"],"properties":{"error":{"type":"string","enum":["batch_revision_conflict"],"description":"Stable code."},"current_revision":{"type":"integer","minimum":1,"description":"The batch revision now."},"batch_id":{"type":"string","format":"uuid","description":"The batch the fragment would join."}}},{"type":"object","additionalProperties":false,"required":["error","blocking_dispatch_id"],"properties":{"error":{"type":"string","enum":["sequence_blocked"],"description":"Stable code."},"blocking_dispatch_id":{"type":"string","format":"uuid","description":"The earliest entry that needs a human decision."}}}]},"example":{"error":"sequence_blocked","blocking_dispatch_id":"2a4c6e81-3b5d-4f7a-9c1e-5b7d9f1a3c52"}}}},"410":{"description":"The replayed fragment's receipt expired — retention already purged its text.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","enum":["receipt_expired"],"description":"Stable code."}}},"example":{"error":"receipt_expired"}}}},"422":{"description":"The fragment does not fit — `max_fragments` (32 active) or `max_batch_bytes` (16384 bytes of active text).","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error","limit"],"properties":{"error":{"type":"string","enum":["text_limit_exceeded"],"description":"Stable code."},"limit":{"type":"string","enum":["max_fragments","max_batch_bytes"],"description":"The limit the new fragment would break (already accepted fragments are untouched)."}}},"example":{"error":"text_limit_exceeded","limit":"max_batch_bytes"}}}},"429":{"description":"Local quota or backpressure: the request was NOT accepted and nothing was stored. An idempotent replay of an already recorded `client_fragment_id` / `request_id` is answered before the quota and is never limited. Keep the text on the client and retry after `retry_after` seconds with the SAME identifier.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (same value as `retry_after`).","schema":{"type":"integer","minimum":1},"example":4}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error","retry_after","scope"],"properties":{"error":{"type":"string","enum":["rate_limited"],"description":"Stable code."},"retry_after":{"type":"integer","minimum":1,"description":"Whole seconds to wait before retrying."},"scope":{"type":"string","enum":["author","account","backlog"],"description":"Which limit was hit: `author` (writes of this agent in this conversation), `account` (writes of the whole account) or `backlog` (the lane queue is behind)."}}},"example":{"error":"rate_limited","retry_after":4,"scope":"author"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"in":"path","name":"conversation_id","required":true,"description":"Account-scoped conversation display id.","schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["client_fragment_id","content"],"properties":{"client_fragment_id":{"type":"string","format":"uuid","description":"Client-generated idempotency id of this fragment (UUID)."},"content":{"type":"string","description":"The text exactly as typed (whitespace is kept); not blank; at most 16384 UTF-8 bytes per batch."},"context":{"type":"object","additionalProperties":false,"description":"Compatibility context; fragments only join a batch with an equal context.","properties":{"in_reply_to":{"type":["integer","string","null"],"description":"Id of a message of this conversation to quote (integer or digit string)."},"whatsapp_transport":{"type":["string","null"],"enum":["auto","cloud","web","",null],"description":"Explicit transport chosen by the human (`cloud`, `web`); `auto`, empty or null lets the router decide."},"signature_block":{"type":["string","null"],"maxLength":1024,"description":"The exact signature block the composer would append; applied once to the consolidated text."}}},"expected_batch_revision":{"type":"integer","minimum":1,"description":"When appending to a known batch, its current revision (a mismatch is 409)."}}},"example":{"client_fragment_id":"9a7d3e10-2f4b-4c8a-b5e6-7f8091a2b3c4","content":"as duas chegam amanhã","context":{"in_reply_to":88213,"whatsapp_transport":"auto","signature_block":"Ana · Loja Centro"},"expected_batch_revision":1}}}}}},"/api/v1/accounts/{account_id}/whatsapp/outbound/conversations/{conversation_id}/batches/{batch_id}/fragments/{fragment_id}":{"patch":{"tags":["WhatsApp"],"operationId":"auto_patch_api_v1_accounts_account_id_whatsapp_outbound_conversations_conversation_id_batches_batch_id_fragments_fragment_id","summary":"Edit a fragment of my paused WhatsApp outbound batch","description":"Edits one fragment while the batch is `paused` and the request presents the edit lease the pause granted to this tab. Author only. Editing moves the revision, discards any proposal or approval, and keeps the batch paused until an explicit resume. The same bytes change nothing. Idempotent per `request_id`; `expected_revision` guards concurrency.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The batch snapshot after the edit.","content":{"application/json":{"schema":{"description":"A consistent snapshot of one batch with its active fragments.","allOf":[{"type":"object","required":["schema_version","batch_id","conversation_id","inbox_id","author_id","state","state_reason","revision","server_now","first_at","last_changed_at","due_at","hard_deadline_at","expires_at","dispatch_committed_at","message_id","effective_mode","applied_mode","fragment_count","content_bytes","edit_lease","limits","routing","sequence_entry","content_purged","original_text","candidate","permissions"],"properties":{"schema_version":{"type":"integer","enum":[1],"description":"Version of this payload shape."},"batch_id":{"type":"string","format":"uuid","description":"Public id of the batch (the numeric id never leaves the server)."},"conversation_id":{"type":"integer","description":"Account-scoped conversation display id."},"inbox_id":{"type":"integer","description":"Inbox the batch was opened on (the logical inbox of the conversation)."},"author_id":{"type":["integer","null"],"description":"User id of the agent who wrote the batch."},"state":{"type":"string","enum":["collecting","processing","awaiting_review","paused","ready","materializing","materialized","canceled","expired"],"description":"Batch state — `collecting` (collection window open), `processing` (a Maestro transformation is claimed), `awaiting_review` (a candidate waits for the author), `paused` (a human decision is needed), `ready` (approved, due now), `materializing`, then the terminal `materialized` (exactly one Message exists), `canceled` or `expired` (nothing was sent). A batch state is not a delivery state."},"state_reason":{"type":["string","null"],"enum":["contact_replied","contact_merged","human_edit","transform_unavailable","transform_stale","transform_budget_exceeded","policy_revoked","flag_disabled","agent_profile_revoked","agent_profile_mismatch","text_limit_exceeded","transport_not_eligible","flow_candidate_stale","pacing_exhausted","predecessor_blocked","provider_rejected","dispatch_effect_unknown","window_closed","human_access_revoked","predecessor_pending",null],"description":"Closed pause/hold reason code (the dashboard translates it; the API never sends prose), or null when there is no reason to report."},"revision":{"type":"integer","minimum":1,"description":"Batch revision; send it back as `expected_revision` on every mutation (optimistic concurrency)."},"server_now":{"type":"string","format":"date-time","description":"Server clock at read time; clients compute countdowns from this offset, never from their own clock."},"first_at":{"type":"string","format":"date-time","description":"When the first fragment was accepted."},"last_changed_at":{"type":"string","format":"date-time","description":"Last accepted content change (typing and HTTP replays never move it)."},"due_at":{"type":["string","null"],"format":"date-time","description":"When the batch leaves by time — min(last change + idle, hard deadline); null unless collecting or ready."},"hard_deadline_at":{"type":"string","format":"date-time","description":"Fixed ceiling of the collection window (first fragment + maximum wait); never moves later."},"expires_at":{"type":["string","null"],"format":"date-time","description":"When a never-sent batch expires without sending (24 h after the last change); null once terminal or committed."},"dispatch_committed_at":{"type":["string","null"],"format":"date-time","description":"When the local dispatch commitment happened (edit and cancel close there); not provider acceptance."},"message_id":{"type":["integer","null"],"description":"The one Message this batch became (set when materialized); delivery truth belongs to that Message."},"effective_mode":{"type":"string","enum":["faithful","suggest","automatic"],"description":"Maestro mode — `faithful` (the author's consolidated text leaves as typed), `suggest` (a transformation is proposed and waits for the author) or `automatic` (an approved transformation may leave without review)."},"applied_mode":{"type":["string","null"],"enum":["faithful","original","candidate","candidate_unchanged","automatic","automatic_unchanged","fallback_original",null],"description":"What actually left — `faithful` (text as typed), `original` (author chose the original), `candidate` (approved suggestion), `candidate_unchanged` (approved suggestion in which Maestro changed nothing), `automatic` (automatic mode result), `automatic_unchanged` (automatic mode, Maestro changed nothing, the original left) or `fallback_original` (Maestro could not be used and the policy sent the original). Null until the batch is finalized."},"fragment_count":{"type":"integer","minimum":0,"maximum":32,"description":"Number of active fragments."},"content_bytes":{"type":"integer","minimum":0,"maximum":16384,"description":"UTF-8 size of the active text, in bytes."},"edit_lease":{"type":"object","required":["active","expires_at"],"description":"The 2-minute edit lease a pause grants to the editing tab (the token itself is never exposed here).","properties":{"active":{"type":"boolean","description":"Whether some tab currently holds the edit lease."},"expires_at":{"type":["string","null"],"format":"date-time","description":"When the last granted lease ends; null when none was granted."}}},"limits":{"type":"object","required":["max_text_characters","max_fragments","max_batch_bytes"],"description":"Text limits of the conversation's logical transport and of one batch.","properties":{"max_text_characters":{"type":["integer","null"],"description":"Character ceiling of one text message on this inbox's channel (4096 on WhatsApp Cloud), or null when the channel declares none."},"max_fragments":{"type":"integer","description":"Maximum number of active fragments in one batch (32)."},"max_batch_bytes":{"type":"integer","description":"Maximum UTF-8 size of the active text of one batch, in bytes (16384)."}}},"routing":{"type":"object","required":["mode","web_percent","reserved"],"description":"Routing policy of the conversation's hybrid pair (WhatsApp Cloud + WhatsApp Web via WazMeow).","properties":{"mode":{"type":"string","enum":["legacy","weighted"],"description":"`weighted` when the percentage routing of the pair is on for this lane; `legacy` otherwise."},"web_percent":{"type":["integer","null"],"minimum":0,"maximum":100,"description":"Share of new contacts routed to WhatsApp Web under `weighted`; null under `legacy`."},"reserved":{"type":"boolean","description":"True once a routing decision was recorded for this entry."}}},"sequence_entry":{"type":["object","null"],"description":"The batch's place in the conversation's dispatch order, or null.","required":["dispatch_id","state","blocking_reason","blocking_dispatch_id"],"properties":{"dispatch_id":{"type":"string","format":"uuid","description":"Public id of the sequence entry that owns this batch."},"state":{"type":"string","enum":["open","committed","held","settled","abandoned","canceled"],"description":"Sequence entry state — `open` (not committed yet), `committed` (its Messages exist and wait for their turn or the provider), `held` (a part needs a human disposition), then the terminal `settled` (every part accepted by the provider), `abandoned` (a human abandoned it) or `canceled` (canceled before the dispatch commitment)."},"blocking_reason":{"type":["string","null"],"enum":["predecessor_blocked","predecessor_pending",null],"description":"Why this entry still waits for an earlier entry of the conversation — `predecessor_blocked` (an earlier entry needs a human decision; new outputs are refused with `sequence_blocked`) or `predecessor_pending` (earlier entries are only in flight). Null when nothing blocks it."},"blocking_dispatch_id":{"type":["string","null"],"format":"uuid","description":"The earliest entry this one waits for, or null."}}},"content_purged":{"type":"boolean","description":"True once retention removed the batch text (digests and counters remain)."},"original_text":{"type":["string","null"],"description":"The consolidated original text as last sealed for processing; null before the first seal or once purged."},"candidate":{"type":["object","null"],"description":"The Maestro proposal waiting for the author's review, or null. Its `digest` is the value `accept_candidate` must present. Never carries prompts, grants, model output metadata or provider data.","properties":{"outcome":{"type":"string","enum":["unchanged","rewritten","structured","unavailable","requires_review"],"description":"Maestro outcome of the transformation."},"format":{"type":"string","enum":["text","buttons","list","cta","whatsapp_flow"],"description":"Output format of the candidate."},"text":{"type":["string","null"],"description":"Proposed text (the message body of a structured candidate)."},"data":{"type":"object","additionalProperties":true,"description":"Format-specific structure: `{}` for text; `buttons` (1–3 `{title, id?}`) plus optional `header`/`footer` for buttons; `sections` of rows plus optional `button` for a list; `{display_text, url}` for a call to action; `{seed?, cta?}` for a WhatsApp Flow. Button and row ids are assigned by the server."},"asset_ref":{"type":["object","null"],"description":"The pinned WhatsApp Flow mapping version of a `whatsapp_flow` candidate; null for any other format.","required":["mapping_id","mapping_version","mapping_digest"],"properties":{"mapping_id":{"type":"string","description":"Flow mapping id of the inbox policy."},"mapping_version":{"type":"integer","minimum":1,"description":"Immutable version of that mapping."},"mapping_digest":{"type":"string","pattern":"^[0-9a-f]{64}$","description":"SHA-256 digest of that mapping version."}}},"reason_codes":{"type":"array","maxItems":16,"description":"Closed-vocabulary codes Maestro reported for the proposal (lower snake case).","items":{"type":"string","pattern":"^[a-z][a-z0-9_]{0,63}$"}},"requires_review":{"type":"boolean","description":"Whether the proposal needs a human review before it can leave."},"digest":{"type":"string","pattern":"^[0-9a-f]{64}$","description":"SHA-256 digest of the candidate's final draft; send it back as `digest` in `accept_candidate`."}}},"permissions":{"type":"object","required":["edit","remove_fragment","pause","resume","flush","use_original","accept_candidate","suggest","cancel"],"description":"What the CURRENT caller may do with this batch right now, computed at read time from the author rule (content actions are the author's only; `cancel` is the author's or an inbox manager's), the batch state and the current lane configuration. Every key is false once the dispatch commitment happened or the batch is terminal.","properties":{"edit":{"type":"boolean","description":"Edit a fragment (paused batch, with the edit lease of the pausing tab)."},"remove_fragment":{"type":"boolean","description":"Remove a fragment (collecting or paused batch)."},"pause":{"type":"boolean","description":"Pause the batch to edit it."},"resume":{"type":"boolean","description":"Resume a paused batch (needs the batching module on)."},"flush":{"type":"boolean","description":"Send now, skipping only the idle wait (needs the batching module on)."},"use_original":{"type":"boolean","description":"Send the author's consolidated text now, without Maestro."},"accept_candidate":{"type":"boolean","description":"Approve the candidate waiting for review."},"suggest":{"type":"boolean","description":"Ask Maestro for a suggestion of the current revision."},"cancel":{"type":"boolean","description":"Cancel the batch (author or inbox manager)."}}}}},{"type":"object","required":["fragments"],"properties":{"fragments":{"type":"array","maxItems":32,"description":"Active fragments of the batch in ordinal order; removed fragments are tombstones and are omitted.","items":{"type":"object","required":["fragment_id","ordinal","revision","content","created_at"],"properties":{"fragment_id":{"type":"string","format":"uuid","description":"Public id of the fragment."},"ordinal":{"type":"integer","minimum":1,"description":"Position of the fragment inside the batch; stable across removals."},"revision":{"type":"integer","minimum":1,"description":"Revision of this fragment (an edit increments it)."},"content":{"type":["string","null"],"description":"The exact text the agent confirmed (byte-faithful), or null once retention purged the text."},"created_at":{"type":"string","format":"date-time","description":"When the fragment was accepted (UTC)."}}}}}}]},"example":{"schema_version":1,"batch_id":"5f0c2a8e-3b1d-4c6e-9a7f-1d2e3f4a5b60","conversation_id":1284,"inbox_id":17,"author_id":9,"state":"awaiting_review","state_reason":null,"revision":4,"server_now":"2026-09-29T14:04:02.310Z","first_at":"2026-09-29T14:03:05.100Z","last_changed_at":"2026-09-29T14:03:12.000Z","due_at":null,"hard_deadline_at":"2026-09-29T14:03:35.100Z","expires_at":"2026-09-30T14:03:12.000Z","dispatch_committed_at":null,"message_id":null,"effective_mode":"suggest","applied_mode":null,"fragment_count":2,"content_bytes":74,"edit_lease":{"active":false,"expires_at":null},"limits":{"max_text_characters":4096,"max_fragments":32,"max_batch_bytes":16384},"routing":{"mode":"weighted","web_percent":30,"reserved":false},"sequence_entry":{"dispatch_id":"7e2b9c44-1d5f-4a3e-8b6c-9d0e1f2a3b4c","state":"open","blocking_reason":null,"blocking_dispatch_id":null},"content_purged":false,"original_text":"Oi, Marina! separei as duas opções que você pediu\nas duas chegam amanhã","candidate":{"outcome":"rewritten","format":"text","text":"Oi, Marina! Separei as duas opções que você pediu.\nAs duas chegam amanhã.","data":{},"asset_ref":null,"reason_codes":["grammar_adjusted","formatting_adjusted"],"requires_review":true,"digest":"3c256ec4052923b702936f7dd31fff42a19fdc896c1c7dbbbe11ac7c679368da"},"permissions":{"edit":false,"remove_fragment":false,"pause":true,"resume":false,"flush":false,"use_original":true,"accept_candidate":true,"suggest":true,"cancel":true},"fragments":[{"fragment_id":"0b9e4c21-6a3f-4d58-8e17-2c4b6d8f0a12","ordinal":1,"revision":1,"content":"Oi, Marina! separei as duas opções que você pediu","created_at":"2026-09-29T14:03:05.100Z"},{"fragment_id":"1c8f5d32-7b40-4e69-9f28-3d5c7e9a1b23","ordinal":2,"revision":1,"content":"as duas chegam amanhã","created_at":"2026-09-29T14:03:12.000Z"}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"The batch (or fragment) does not exist in this conversation (`not_found`), or the conversation does not exist.","content":{"application/json":{"schema":{"anyOf":[{"type":"object","additionalProperties":false,"required":["error"],"description":"The batch, fragment, entry or receipt does not exist for this caller in this conversation.","properties":{"error":{"type":"string","enum":["not_found"],"description":"Stable lane code."}}},{"type":"object","additionalProperties":false,"required":["error"],"description":"Generic lookup failure of the account API (the conversation or inbox does not exist in this account).","properties":{"error":{"type":"string","description":"Human-readable lookup failure (\"Resource could not be found\")."}}}]},"example":{"error":"not_found"}}}},"400":{"description":"Malformed request — `request_id` is not a UUID, `expected_revision` is missing or not a positive integer, or `content` is not text or is blank.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error","errors"],"properties":{"error":{"type":"string","enum":["invalid_request"],"description":"Malformed request (400)."},"errors":{"type":"array","minItems":1,"description":"The offending request field(s), each with a stable validation code.","items":{"type":"object","additionalProperties":false,"required":["field","code"],"properties":{"field":{"type":"string","description":"Request field path, e.g. `content`, `context.in_reply_to`, `request_id`, `expected_revision`."},"code":{"type":"string","enum":["invalid_format","required","invalid_type","blank","not_allowed","unknown_field","out_of_range","not_found"],"description":"Stable validation code of that field."}}}}}},"example":{"error":"invalid_request","errors":[{"field":"content","code":"blank"}]}}}},"403":{"description":"Policy refusal — the caller cannot see the conversation, or the action belongs to the batch/entry author (or an inbox manager for `cancel`/`abandon`). Agent bot tokens are never actors of this lane.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","enum":["forbidden"],"description":"Policy refusal."}}},"example":{"error":"forbidden"}}}},"409":{"description":"`request_id_conflict` (the id was used for another mutation) or `batch_revision_conflict`.","content":{"application/json":{"schema":{"anyOf":[{"type":"object","additionalProperties":false,"required":["error"],"description":"The same `request_id` was already used by this actor for a different payload or record.","properties":{"error":{"type":"string","enum":["request_id_conflict"],"description":"Stable code."}}},{"type":"object","additionalProperties":false,"required":["error","current_revision"],"description":"`expected_revision` differs from the current revision; re-read and retry.","properties":{"error":{"type":"string","enum":["batch_revision_conflict"],"description":"Stable code (also used for sequence entries)."},"current_revision":{"type":"integer","minimum":1,"description":"The revision the record has now."}}}]},"example":{"error":"batch_revision_conflict","current_revision":6}}}},"422":{"description":"`batch_not_editable` (not paused, committed, lease expired or held by another tab) or `text_limit_exceeded` (the new text would exceed 16384 bytes of active text).","content":{"application/json":{"schema":{"anyOf":[{"type":"object","additionalProperties":false,"required":["error","reason"],"description":"The batch no longer accepts this change — `committed` (the dispatch commitment happened or the batch is terminal), the current batch state name (the action is not allowed from it), `state` (see `state`), `flag_disabled` (the module needed by this action is off), `empty` (no active text), `edit_lease_expired` (pause again to edit) or `edit_lease_held` (another tab holds the edit lease). Approving a candidate (`accept_candidate`) is also refused while the pinned Maestro profile may no longer act: `policy_revoked` (the current mode no longer asks for a transformation), `agent_profile_revoked` (the profile left the allowlist or its inherited binding changed), or `contract_version_mismatch` / `grant_key_mismatch` (the Maestro module is restricted).","properties":{"error":{"type":"string","enum":["batch_not_editable"],"description":"Stable code."},"reason":{"type":"string","enum":["committed","state","flag_disabled","empty","edit_lease_expired","edit_lease_held","collecting","processing","awaiting_review","paused","ready","policy_revoked","agent_profile_revoked","contract_version_mismatch","grant_key_mismatch"],"description":"Why the change was refused."},"state":{"type":"string","enum":["collecting","processing","awaiting_review","paused","ready","materializing","materialized","canceled","expired"],"description":"Batch state — `collecting` (collection window open), `processing` (a Maestro transformation is claimed), `awaiting_review` (a candidate waits for the author), `paused` (a human decision is needed), `ready` (approved, due now), `materializing`, then the terminal `materialized` (exactly one Message exists), `canceled` or `expired` (nothing was sent). A batch state is not a delivery state."}}},{"type":"object","additionalProperties":false,"required":["error","limit"],"properties":{"error":{"type":"string","enum":["text_limit_exceeded"],"description":"Stable code."},"limit":{"type":"string","enum":["max_batch_bytes"],"description":"The limit the edit would break."}}}]},"example":{"error":"batch_not_editable","reason":"edit_lease_expired","state":"paused"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"in":"path","name":"conversation_id","required":true,"description":"Account-scoped conversation display id.","schema":{"type":"integer"}},{"in":"path","name":"batch_id","required":true,"description":"Public batch id.","schema":{"type":"string","format":"uuid"}},{"in":"path","name":"fragment_id","required":true,"description":"Public fragment id.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["request_id","expected_revision","content","edit_lease_token"],"properties":{"request_id":{"type":"string","format":"uuid","description":"Idempotency id of this mutation (a replay returns the recorded result)."},"expected_revision":{"type":"integer","minimum":1,"description":"The batch revision last read."},"content":{"type":"string","description":"New text of the fragment (not blank)."},"edit_lease_token":{"type":"string","format":"uuid","description":"The `edit_lease_token` the `pause` action returned to this tab."}}},"example":{"request_id":"c3e5a7b9-4d6f-4a8c-9e0b-1a2c3d4e5f60","expected_revision":5,"content":"As duas chegam amanhã de manhã.","edit_lease_token":"8b1d3f57-6e9a-4c2b-8d4f-0a1b2c3d4e5f"}}}}},"delete":{"tags":["WhatsApp"],"operationId":"auto_delete_api_v1_accounts_account_id_whatsapp_outbound_conversations_conversation_id_batches_batch_id_fragments_fragment_id","summary":"Remove a fragment from my WhatsApp outbound batch","description":"Removes one fragment (a tombstone) while the batch is `collecting` (the idle window moves; the hard deadline never does) or `paused`. Author only. Any proposal or approval is discarded. Removing the last active fragment cancels the batch and its dispatch entry — nothing is sent. Idempotent per `request_id`; `expected_revision` guards concurrency. The parameters travel in the JSON body.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The batch snapshot after the removal (state `canceled` when it was the last fragment).","content":{"application/json":{"schema":{"description":"A consistent snapshot of one batch with its active fragments.","allOf":[{"type":"object","required":["schema_version","batch_id","conversation_id","inbox_id","author_id","state","state_reason","revision","server_now","first_at","last_changed_at","due_at","hard_deadline_at","expires_at","dispatch_committed_at","message_id","effective_mode","applied_mode","fragment_count","content_bytes","edit_lease","limits","routing","sequence_entry","content_purged","original_text","candidate","permissions"],"properties":{"schema_version":{"type":"integer","enum":[1],"description":"Version of this payload shape."},"batch_id":{"type":"string","format":"uuid","description":"Public id of the batch (the numeric id never leaves the server)."},"conversation_id":{"type":"integer","description":"Account-scoped conversation display id."},"inbox_id":{"type":"integer","description":"Inbox the batch was opened on (the logical inbox of the conversation)."},"author_id":{"type":["integer","null"],"description":"User id of the agent who wrote the batch."},"state":{"type":"string","enum":["collecting","processing","awaiting_review","paused","ready","materializing","materialized","canceled","expired"],"description":"Batch state — `collecting` (collection window open), `processing` (a Maestro transformation is claimed), `awaiting_review` (a candidate waits for the author), `paused` (a human decision is needed), `ready` (approved, due now), `materializing`, then the terminal `materialized` (exactly one Message exists), `canceled` or `expired` (nothing was sent). A batch state is not a delivery state."},"state_reason":{"type":["string","null"],"enum":["contact_replied","contact_merged","human_edit","transform_unavailable","transform_stale","transform_budget_exceeded","policy_revoked","flag_disabled","agent_profile_revoked","agent_profile_mismatch","text_limit_exceeded","transport_not_eligible","flow_candidate_stale","pacing_exhausted","predecessor_blocked","provider_rejected","dispatch_effect_unknown","window_closed","human_access_revoked","predecessor_pending",null],"description":"Closed pause/hold reason code (the dashboard translates it; the API never sends prose), or null when there is no reason to report."},"revision":{"type":"integer","minimum":1,"description":"Batch revision; send it back as `expected_revision` on every mutation (optimistic concurrency)."},"server_now":{"type":"string","format":"date-time","description":"Server clock at read time; clients compute countdowns from this offset, never from their own clock."},"first_at":{"type":"string","format":"date-time","description":"When the first fragment was accepted."},"last_changed_at":{"type":"string","format":"date-time","description":"Last accepted content change (typing and HTTP replays never move it)."},"due_at":{"type":["string","null"],"format":"date-time","description":"When the batch leaves by time — min(last change + idle, hard deadline); null unless collecting or ready."},"hard_deadline_at":{"type":"string","format":"date-time","description":"Fixed ceiling of the collection window (first fragment + maximum wait); never moves later."},"expires_at":{"type":["string","null"],"format":"date-time","description":"When a never-sent batch expires without sending (24 h after the last change); null once terminal or committed."},"dispatch_committed_at":{"type":["string","null"],"format":"date-time","description":"When the local dispatch commitment happened (edit and cancel close there); not provider acceptance."},"message_id":{"type":["integer","null"],"description":"The one Message this batch became (set when materialized); delivery truth belongs to that Message."},"effective_mode":{"type":"string","enum":["faithful","suggest","automatic"],"description":"Maestro mode — `faithful` (the author's consolidated text leaves as typed), `suggest` (a transformation is proposed and waits for the author) or `automatic` (an approved transformation may leave without review)."},"applied_mode":{"type":["string","null"],"enum":["faithful","original","candidate","candidate_unchanged","automatic","automatic_unchanged","fallback_original",null],"description":"What actually left — `faithful` (text as typed), `original` (author chose the original), `candidate` (approved suggestion), `candidate_unchanged` (approved suggestion in which Maestro changed nothing), `automatic` (automatic mode result), `automatic_unchanged` (automatic mode, Maestro changed nothing, the original left) or `fallback_original` (Maestro could not be used and the policy sent the original). Null until the batch is finalized."},"fragment_count":{"type":"integer","minimum":0,"maximum":32,"description":"Number of active fragments."},"content_bytes":{"type":"integer","minimum":0,"maximum":16384,"description":"UTF-8 size of the active text, in bytes."},"edit_lease":{"type":"object","required":["active","expires_at"],"description":"The 2-minute edit lease a pause grants to the editing tab (the token itself is never exposed here).","properties":{"active":{"type":"boolean","description":"Whether some tab currently holds the edit lease."},"expires_at":{"type":["string","null"],"format":"date-time","description":"When the last granted lease ends; null when none was granted."}}},"limits":{"type":"object","required":["max_text_characters","max_fragments","max_batch_bytes"],"description":"Text limits of the conversation's logical transport and of one batch.","properties":{"max_text_characters":{"type":["integer","null"],"description":"Character ceiling of one text message on this inbox's channel (4096 on WhatsApp Cloud), or null when the channel declares none."},"max_fragments":{"type":"integer","description":"Maximum number of active fragments in one batch (32)."},"max_batch_bytes":{"type":"integer","description":"Maximum UTF-8 size of the active text of one batch, in bytes (16384)."}}},"routing":{"type":"object","required":["mode","web_percent","reserved"],"description":"Routing policy of the conversation's hybrid pair (WhatsApp Cloud + WhatsApp Web via WazMeow).","properties":{"mode":{"type":"string","enum":["legacy","weighted"],"description":"`weighted` when the percentage routing of the pair is on for this lane; `legacy` otherwise."},"web_percent":{"type":["integer","null"],"minimum":0,"maximum":100,"description":"Share of new contacts routed to WhatsApp Web under `weighted`; null under `legacy`."},"reserved":{"type":"boolean","description":"True once a routing decision was recorded for this entry."}}},"sequence_entry":{"type":["object","null"],"description":"The batch's place in the conversation's dispatch order, or null.","required":["dispatch_id","state","blocking_reason","blocking_dispatch_id"],"properties":{"dispatch_id":{"type":"string","format":"uuid","description":"Public id of the sequence entry that owns this batch."},"state":{"type":"string","enum":["open","committed","held","settled","abandoned","canceled"],"description":"Sequence entry state — `open` (not committed yet), `committed` (its Messages exist and wait for their turn or the provider), `held` (a part needs a human disposition), then the terminal `settled` (every part accepted by the provider), `abandoned` (a human abandoned it) or `canceled` (canceled before the dispatch commitment)."},"blocking_reason":{"type":["string","null"],"enum":["predecessor_blocked","predecessor_pending",null],"description":"Why this entry still waits for an earlier entry of the conversation — `predecessor_blocked` (an earlier entry needs a human decision; new outputs are refused with `sequence_blocked`) or `predecessor_pending` (earlier entries are only in flight). Null when nothing blocks it."},"blocking_dispatch_id":{"type":["string","null"],"format":"uuid","description":"The earliest entry this one waits for, or null."}}},"content_purged":{"type":"boolean","description":"True once retention removed the batch text (digests and counters remain)."},"original_text":{"type":["string","null"],"description":"The consolidated original text as last sealed for processing; null before the first seal or once purged."},"candidate":{"type":["object","null"],"description":"The Maestro proposal waiting for the author's review, or null. Its `digest` is the value `accept_candidate` must present. Never carries prompts, grants, model output metadata or provider data.","properties":{"outcome":{"type":"string","enum":["unchanged","rewritten","structured","unavailable","requires_review"],"description":"Maestro outcome of the transformation."},"format":{"type":"string","enum":["text","buttons","list","cta","whatsapp_flow"],"description":"Output format of the candidate."},"text":{"type":["string","null"],"description":"Proposed text (the message body of a structured candidate)."},"data":{"type":"object","additionalProperties":true,"description":"Format-specific structure: `{}` for text; `buttons` (1–3 `{title, id?}`) plus optional `header`/`footer` for buttons; `sections` of rows plus optional `button` for a list; `{display_text, url}` for a call to action; `{seed?, cta?}` for a WhatsApp Flow. Button and row ids are assigned by the server."},"asset_ref":{"type":["object","null"],"description":"The pinned WhatsApp Flow mapping version of a `whatsapp_flow` candidate; null for any other format.","required":["mapping_id","mapping_version","mapping_digest"],"properties":{"mapping_id":{"type":"string","description":"Flow mapping id of the inbox policy."},"mapping_version":{"type":"integer","minimum":1,"description":"Immutable version of that mapping."},"mapping_digest":{"type":"string","pattern":"^[0-9a-f]{64}$","description":"SHA-256 digest of that mapping version."}}},"reason_codes":{"type":"array","maxItems":16,"description":"Closed-vocabulary codes Maestro reported for the proposal (lower snake case).","items":{"type":"string","pattern":"^[a-z][a-z0-9_]{0,63}$"}},"requires_review":{"type":"boolean","description":"Whether the proposal needs a human review before it can leave."},"digest":{"type":"string","pattern":"^[0-9a-f]{64}$","description":"SHA-256 digest of the candidate's final draft; send it back as `digest` in `accept_candidate`."}}},"permissions":{"type":"object","required":["edit","remove_fragment","pause","resume","flush","use_original","accept_candidate","suggest","cancel"],"description":"What the CURRENT caller may do with this batch right now, computed at read time from the author rule (content actions are the author's only; `cancel` is the author's or an inbox manager's), the batch state and the current lane configuration. Every key is false once the dispatch commitment happened or the batch is terminal.","properties":{"edit":{"type":"boolean","description":"Edit a fragment (paused batch, with the edit lease of the pausing tab)."},"remove_fragment":{"type":"boolean","description":"Remove a fragment (collecting or paused batch)."},"pause":{"type":"boolean","description":"Pause the batch to edit it."},"resume":{"type":"boolean","description":"Resume a paused batch (needs the batching module on)."},"flush":{"type":"boolean","description":"Send now, skipping only the idle wait (needs the batching module on)."},"use_original":{"type":"boolean","description":"Send the author's consolidated text now, without Maestro."},"accept_candidate":{"type":"boolean","description":"Approve the candidate waiting for review."},"suggest":{"type":"boolean","description":"Ask Maestro for a suggestion of the current revision."},"cancel":{"type":"boolean","description":"Cancel the batch (author or inbox manager)."}}}}},{"type":"object","required":["fragments"],"properties":{"fragments":{"type":"array","maxItems":32,"description":"Active fragments of the batch in ordinal order; removed fragments are tombstones and are omitted.","items":{"type":"object","required":["fragment_id","ordinal","revision","content","created_at"],"properties":{"fragment_id":{"type":"string","format":"uuid","description":"Public id of the fragment."},"ordinal":{"type":"integer","minimum":1,"description":"Position of the fragment inside the batch; stable across removals."},"revision":{"type":"integer","minimum":1,"description":"Revision of this fragment (an edit increments it)."},"content":{"type":["string","null"],"description":"The exact text the agent confirmed (byte-faithful), or null once retention purged the text."},"created_at":{"type":"string","format":"date-time","description":"When the fragment was accepted (UTC)."}}}}}}]},"example":{"schema_version":1,"batch_id":"5f0c2a8e-3b1d-4c6e-9a7f-1d2e3f4a5b60","conversation_id":1284,"inbox_id":17,"author_id":9,"state":"awaiting_review","state_reason":null,"revision":4,"server_now":"2026-09-29T14:04:02.310Z","first_at":"2026-09-29T14:03:05.100Z","last_changed_at":"2026-09-29T14:03:12.000Z","due_at":null,"hard_deadline_at":"2026-09-29T14:03:35.100Z","expires_at":"2026-09-30T14:03:12.000Z","dispatch_committed_at":null,"message_id":null,"effective_mode":"suggest","applied_mode":null,"fragment_count":2,"content_bytes":74,"edit_lease":{"active":false,"expires_at":null},"limits":{"max_text_characters":4096,"max_fragments":32,"max_batch_bytes":16384},"routing":{"mode":"weighted","web_percent":30,"reserved":false},"sequence_entry":{"dispatch_id":"7e2b9c44-1d5f-4a3e-8b6c-9d0e1f2a3b4c","state":"open","blocking_reason":null,"blocking_dispatch_id":null},"content_purged":false,"original_text":"Oi, Marina! separei as duas opções que você pediu\nas duas chegam amanhã","candidate":{"outcome":"rewritten","format":"text","text":"Oi, Marina! Separei as duas opções que você pediu.\nAs duas chegam amanhã.","data":{},"asset_ref":null,"reason_codes":["grammar_adjusted","formatting_adjusted"],"requires_review":true,"digest":"3c256ec4052923b702936f7dd31fff42a19fdc896c1c7dbbbe11ac7c679368da"},"permissions":{"edit":false,"remove_fragment":false,"pause":true,"resume":false,"flush":false,"use_original":true,"accept_candidate":true,"suggest":true,"cancel":true},"fragments":[{"fragment_id":"0b9e4c21-6a3f-4d58-8e17-2c4b6d8f0a12","ordinal":1,"revision":1,"content":"Oi, Marina! separei as duas opções que você pediu","created_at":"2026-09-29T14:03:05.100Z"},{"fragment_id":"1c8f5d32-7b40-4e69-9f28-3d5c7e9a1b23","ordinal":2,"revision":1,"content":"as duas chegam amanhã","created_at":"2026-09-29T14:03:12.000Z"}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"The batch (or fragment) does not exist in this conversation (`not_found`), or the conversation does not exist.","content":{"application/json":{"schema":{"anyOf":[{"type":"object","additionalProperties":false,"required":["error"],"description":"The batch, fragment, entry or receipt does not exist for this caller in this conversation.","properties":{"error":{"type":"string","enum":["not_found"],"description":"Stable lane code."}}},{"type":"object","additionalProperties":false,"required":["error"],"description":"Generic lookup failure of the account API (the conversation or inbox does not exist in this account).","properties":{"error":{"type":"string","description":"Human-readable lookup failure (\"Resource could not be found\")."}}}]},"example":{"error":"not_found"}}}},"400":{"description":"Malformed request — `request_id` is not a UUID or `expected_revision` is missing or not a positive integer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error","errors"],"properties":{"error":{"type":"string","enum":["invalid_request"],"description":"Malformed request (400)."},"errors":{"type":"array","minItems":1,"description":"The offending request field(s), each with a stable validation code.","items":{"type":"object","additionalProperties":false,"required":["field","code"],"properties":{"field":{"type":"string","description":"Request field path, e.g. `content`, `context.in_reply_to`, `request_id`, `expected_revision`."},"code":{"type":"string","enum":["invalid_format","required","invalid_type","blank","not_allowed","unknown_field","out_of_range","not_found"],"description":"Stable validation code of that field."}}}}}},"example":{"error":"invalid_request","errors":[{"field":"request_id","code":"invalid_format"}]}}}},"403":{"description":"Policy refusal — the caller cannot see the conversation, or the action belongs to the batch/entry author (or an inbox manager for `cancel`/`abandon`). Agent bot tokens are never actors of this lane.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","enum":["forbidden"],"description":"Policy refusal."}}},"example":{"error":"forbidden"}}}},"409":{"description":"`request_id_conflict` or `batch_revision_conflict`.","content":{"application/json":{"schema":{"anyOf":[{"type":"object","additionalProperties":false,"required":["error"],"description":"The same `request_id` was already used by this actor for a different payload or record.","properties":{"error":{"type":"string","enum":["request_id_conflict"],"description":"Stable code."}}},{"type":"object","additionalProperties":false,"required":["error","current_revision"],"description":"`expected_revision` differs from the current revision; re-read and retry.","properties":{"error":{"type":"string","enum":["batch_revision_conflict"],"description":"Stable code (also used for sequence entries)."},"current_revision":{"type":"integer","minimum":1,"description":"The revision the record has now."}}}]},"example":{"error":"request_id_conflict"}}}},"422":{"description":"`batch_not_editable` — the batch is not collecting or paused, or the dispatch commitment already happened.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error","reason"],"description":"The batch no longer accepts this change — `committed` (the dispatch commitment happened or the batch is terminal), the current batch state name (the action is not allowed from it), `state` (see `state`), `flag_disabled` (the module needed by this action is off), `empty` (no active text), `edit_lease_expired` (pause again to edit) or `edit_lease_held` (another tab holds the edit lease). Approving a candidate (`accept_candidate`) is also refused while the pinned Maestro profile may no longer act: `policy_revoked` (the current mode no longer asks for a transformation), `agent_profile_revoked` (the profile left the allowlist or its inherited binding changed), or `contract_version_mismatch` / `grant_key_mismatch` (the Maestro module is restricted).","properties":{"error":{"type":"string","enum":["batch_not_editable"],"description":"Stable code."},"reason":{"type":"string","enum":["committed","state","flag_disabled","empty","edit_lease_expired","edit_lease_held","collecting","processing","awaiting_review","paused","ready","policy_revoked","agent_profile_revoked","contract_version_mismatch","grant_key_mismatch"],"description":"Why the change was refused."},"state":{"type":"string","enum":["collecting","processing","awaiting_review","paused","ready","materializing","materialized","canceled","expired"],"description":"Batch state — `collecting` (collection window open), `processing` (a Maestro transformation is claimed), `awaiting_review` (a candidate waits for the author), `paused` (a human decision is needed), `ready` (approved, due now), `materializing`, then the terminal `materialized` (exactly one Message exists), `canceled` or `expired` (nothing was sent). A batch state is not a delivery state."}}},"example":{"error":"batch_not_editable","reason":"committed","state":"materialized"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"in":"path","name":"conversation_id","required":true,"description":"Account-scoped conversation display id.","schema":{"type":"integer"}},{"in":"path","name":"batch_id","required":true,"description":"Public batch id.","schema":{"type":"string","format":"uuid"}},{"in":"path","name":"fragment_id","required":true,"description":"Public fragment id.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["request_id","expected_revision"],"properties":{"request_id":{"type":"string","format":"uuid","description":"Idempotency id of this mutation."},"expected_revision":{"type":"integer","minimum":1,"description":"The batch revision last read."}}},"example":{"request_id":"c3e5a7b9-4d6f-4a8c-9e0b-1a2c3d4e5f60","expected_revision":4}}}}}},"/api/v1/accounts/{account_id}/whatsapp/outbound/conversations/{conversation_id}/batches/{batch_id}/actions":{"post":{"tags":["WhatsApp"],"operationId":"auto_post_api_v1_accounts_account_id_whatsapp_outbound_conversations_conversation_id_batches_batch_id_actions","summary":"Apply an action to a WhatsApp outbound batch","description":"`pause` (grants a 2-minute edit lease to this tab and returns `edit_lease_token` — the only response that ever carries it), `resume` (reopens collection; past the hard deadline it seals at once), `flush` (send now — skips only the idle wait; the configured mode still applies), `use_original` (the author's consolidated text, now, without Maestro), `accept_candidate` (requires the `digest` of the candidate the author saw) and `cancel` (the author or an inbox manager, audited). Content actions are the author's. Nothing here sends by itself: the batch only becomes due now and the durable processor commits it. Once the dispatch commitment happened every action — cancel included — is refused. With the module flags off, `pause`, `use_original` and `cancel` keep working to drain accepted work. Idempotent per `request_id`; `expected_revision` guards concurrency. The body field is `action`; `action_name` is accepted as an alias for clients that cannot send `action`.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The batch snapshot after the action; `edit_lease_token` only on the response to `pause` (and its replay).","content":{"application/json":{"schema":{"allOf":[{"description":"A consistent snapshot of one batch with its active fragments.","allOf":[{"type":"object","required":["schema_version","batch_id","conversation_id","inbox_id","author_id","state","state_reason","revision","server_now","first_at","last_changed_at","due_at","hard_deadline_at","expires_at","dispatch_committed_at","message_id","effective_mode","applied_mode","fragment_count","content_bytes","edit_lease","limits","routing","sequence_entry","content_purged","original_text","candidate","permissions"],"properties":{"schema_version":{"type":"integer","enum":[1],"description":"Version of this payload shape."},"batch_id":{"type":"string","format":"uuid","description":"Public id of the batch (the numeric id never leaves the server)."},"conversation_id":{"type":"integer","description":"Account-scoped conversation display id."},"inbox_id":{"type":"integer","description":"Inbox the batch was opened on (the logical inbox of the conversation)."},"author_id":{"type":["integer","null"],"description":"User id of the agent who wrote the batch."},"state":{"type":"string","enum":["collecting","processing","awaiting_review","paused","ready","materializing","materialized","canceled","expired"],"description":"Batch state — `collecting` (collection window open), `processing` (a Maestro transformation is claimed), `awaiting_review` (a candidate waits for the author), `paused` (a human decision is needed), `ready` (approved, due now), `materializing`, then the terminal `materialized` (exactly one Message exists), `canceled` or `expired` (nothing was sent). A batch state is not a delivery state."},"state_reason":{"type":["string","null"],"enum":["contact_replied","contact_merged","human_edit","transform_unavailable","transform_stale","transform_budget_exceeded","policy_revoked","flag_disabled","agent_profile_revoked","agent_profile_mismatch","text_limit_exceeded","transport_not_eligible","flow_candidate_stale","pacing_exhausted","predecessor_blocked","provider_rejected","dispatch_effect_unknown","window_closed","human_access_revoked","predecessor_pending",null],"description":"Closed pause/hold reason code (the dashboard translates it; the API never sends prose), or null when there is no reason to report."},"revision":{"type":"integer","minimum":1,"description":"Batch revision; send it back as `expected_revision` on every mutation (optimistic concurrency)."},"server_now":{"type":"string","format":"date-time","description":"Server clock at read time; clients compute countdowns from this offset, never from their own clock."},"first_at":{"type":"string","format":"date-time","description":"When the first fragment was accepted."},"last_changed_at":{"type":"string","format":"date-time","description":"Last accepted content change (typing and HTTP replays never move it)."},"due_at":{"type":["string","null"],"format":"date-time","description":"When the batch leaves by time — min(last change + idle, hard deadline); null unless collecting or ready."},"hard_deadline_at":{"type":"string","format":"date-time","description":"Fixed ceiling of the collection window (first fragment + maximum wait); never moves later."},"expires_at":{"type":["string","null"],"format":"date-time","description":"When a never-sent batch expires without sending (24 h after the last change); null once terminal or committed."},"dispatch_committed_at":{"type":["string","null"],"format":"date-time","description":"When the local dispatch commitment happened (edit and cancel close there); not provider acceptance."},"message_id":{"type":["integer","null"],"description":"The one Message this batch became (set when materialized); delivery truth belongs to that Message."},"effective_mode":{"type":"string","enum":["faithful","suggest","automatic"],"description":"Maestro mode — `faithful` (the author's consolidated text leaves as typed), `suggest` (a transformation is proposed and waits for the author) or `automatic` (an approved transformation may leave without review)."},"applied_mode":{"type":["string","null"],"enum":["faithful","original","candidate","candidate_unchanged","automatic","automatic_unchanged","fallback_original",null],"description":"What actually left — `faithful` (text as typed), `original` (author chose the original), `candidate` (approved suggestion), `candidate_unchanged` (approved suggestion in which Maestro changed nothing), `automatic` (automatic mode result), `automatic_unchanged` (automatic mode, Maestro changed nothing, the original left) or `fallback_original` (Maestro could not be used and the policy sent the original). Null until the batch is finalized."},"fragment_count":{"type":"integer","minimum":0,"maximum":32,"description":"Number of active fragments."},"content_bytes":{"type":"integer","minimum":0,"maximum":16384,"description":"UTF-8 size of the active text, in bytes."},"edit_lease":{"type":"object","required":["active","expires_at"],"description":"The 2-minute edit lease a pause grants to the editing tab (the token itself is never exposed here).","properties":{"active":{"type":"boolean","description":"Whether some tab currently holds the edit lease."},"expires_at":{"type":["string","null"],"format":"date-time","description":"When the last granted lease ends; null when none was granted."}}},"limits":{"type":"object","required":["max_text_characters","max_fragments","max_batch_bytes"],"description":"Text limits of the conversation's logical transport and of one batch.","properties":{"max_text_characters":{"type":["integer","null"],"description":"Character ceiling of one text message on this inbox's channel (4096 on WhatsApp Cloud), or null when the channel declares none."},"max_fragments":{"type":"integer","description":"Maximum number of active fragments in one batch (32)."},"max_batch_bytes":{"type":"integer","description":"Maximum UTF-8 size of the active text of one batch, in bytes (16384)."}}},"routing":{"type":"object","required":["mode","web_percent","reserved"],"description":"Routing policy of the conversation's hybrid pair (WhatsApp Cloud + WhatsApp Web via WazMeow).","properties":{"mode":{"type":"string","enum":["legacy","weighted"],"description":"`weighted` when the percentage routing of the pair is on for this lane; `legacy` otherwise."},"web_percent":{"type":["integer","null"],"minimum":0,"maximum":100,"description":"Share of new contacts routed to WhatsApp Web under `weighted`; null under `legacy`."},"reserved":{"type":"boolean","description":"True once a routing decision was recorded for this entry."}}},"sequence_entry":{"type":["object","null"],"description":"The batch's place in the conversation's dispatch order, or null.","required":["dispatch_id","state","blocking_reason","blocking_dispatch_id"],"properties":{"dispatch_id":{"type":"string","format":"uuid","description":"Public id of the sequence entry that owns this batch."},"state":{"type":"string","enum":["open","committed","held","settled","abandoned","canceled"],"description":"Sequence entry state — `open` (not committed yet), `committed` (its Messages exist and wait for their turn or the provider), `held` (a part needs a human disposition), then the terminal `settled` (every part accepted by the provider), `abandoned` (a human abandoned it) or `canceled` (canceled before the dispatch commitment)."},"blocking_reason":{"type":["string","null"],"enum":["predecessor_blocked","predecessor_pending",null],"description":"Why this entry still waits for an earlier entry of the conversation — `predecessor_blocked` (an earlier entry needs a human decision; new outputs are refused with `sequence_blocked`) or `predecessor_pending` (earlier entries are only in flight). Null when nothing blocks it."},"blocking_dispatch_id":{"type":["string","null"],"format":"uuid","description":"The earliest entry this one waits for, or null."}}},"content_purged":{"type":"boolean","description":"True once retention removed the batch text (digests and counters remain)."},"original_text":{"type":["string","null"],"description":"The consolidated original text as last sealed for processing; null before the first seal or once purged."},"candidate":{"type":["object","null"],"description":"The Maestro proposal waiting for the author's review, or null. Its `digest` is the value `accept_candidate` must present. Never carries prompts, grants, model output metadata or provider data.","properties":{"outcome":{"type":"string","enum":["unchanged","rewritten","structured","unavailable","requires_review"],"description":"Maestro outcome of the transformation."},"format":{"type":"string","enum":["text","buttons","list","cta","whatsapp_flow"],"description":"Output format of the candidate."},"text":{"type":["string","null"],"description":"Proposed text (the message body of a structured candidate)."},"data":{"type":"object","additionalProperties":true,"description":"Format-specific structure: `{}` for text; `buttons` (1–3 `{title, id?}`) plus optional `header`/`footer` for buttons; `sections` of rows plus optional `button` for a list; `{display_text, url}` for a call to action; `{seed?, cta?}` for a WhatsApp Flow. Button and row ids are assigned by the server."},"asset_ref":{"type":["object","null"],"description":"The pinned WhatsApp Flow mapping version of a `whatsapp_flow` candidate; null for any other format.","required":["mapping_id","mapping_version","mapping_digest"],"properties":{"mapping_id":{"type":"string","description":"Flow mapping id of the inbox policy."},"mapping_version":{"type":"integer","minimum":1,"description":"Immutable version of that mapping."},"mapping_digest":{"type":"string","pattern":"^[0-9a-f]{64}$","description":"SHA-256 digest of that mapping version."}}},"reason_codes":{"type":"array","maxItems":16,"description":"Closed-vocabulary codes Maestro reported for the proposal (lower snake case).","items":{"type":"string","pattern":"^[a-z][a-z0-9_]{0,63}$"}},"requires_review":{"type":"boolean","description":"Whether the proposal needs a human review before it can leave."},"digest":{"type":"string","pattern":"^[0-9a-f]{64}$","description":"SHA-256 digest of the candidate's final draft; send it back as `digest` in `accept_candidate`."}}},"permissions":{"type":"object","required":["edit","remove_fragment","pause","resume","flush","use_original","accept_candidate","suggest","cancel"],"description":"What the CURRENT caller may do with this batch right now, computed at read time from the author rule (content actions are the author's only; `cancel` is the author's or an inbox manager's), the batch state and the current lane configuration. Every key is false once the dispatch commitment happened or the batch is terminal.","properties":{"edit":{"type":"boolean","description":"Edit a fragment (paused batch, with the edit lease of the pausing tab)."},"remove_fragment":{"type":"boolean","description":"Remove a fragment (collecting or paused batch)."},"pause":{"type":"boolean","description":"Pause the batch to edit it."},"resume":{"type":"boolean","description":"Resume a paused batch (needs the batching module on)."},"flush":{"type":"boolean","description":"Send now, skipping only the idle wait (needs the batching module on)."},"use_original":{"type":"boolean","description":"Send the author's consolidated text now, without Maestro."},"accept_candidate":{"type":"boolean","description":"Approve the candidate waiting for review."},"suggest":{"type":"boolean","description":"Ask Maestro for a suggestion of the current revision."},"cancel":{"type":"boolean","description":"Cancel the batch (author or inbox manager)."}}}}},{"type":"object","required":["fragments"],"properties":{"fragments":{"type":"array","maxItems":32,"description":"Active fragments of the batch in ordinal order; removed fragments are tombstones and are omitted.","items":{"type":"object","required":["fragment_id","ordinal","revision","content","created_at"],"properties":{"fragment_id":{"type":"string","format":"uuid","description":"Public id of the fragment."},"ordinal":{"type":"integer","minimum":1,"description":"Position of the fragment inside the batch; stable across removals."},"revision":{"type":"integer","minimum":1,"description":"Revision of this fragment (an edit increments it)."},"content":{"type":["string","null"],"description":"The exact text the agent confirmed (byte-faithful), or null once retention purged the text."},"created_at":{"type":"string","format":"date-time","description":"When the fragment was accepted (UTC)."}}}}}}]},{"type":"object","properties":{"edit_lease_token":{"type":"string","format":"uuid","description":"Edit lease of this tab — present only after `pause`; send it back when editing a fragment."}}}]},"example":{"schema_version":1,"batch_id":"5f0c2a8e-3b1d-4c6e-9a7f-1d2e3f4a5b60","conversation_id":1284,"inbox_id":17,"author_id":9,"state":"paused","state_reason":"human_edit","revision":3,"server_now":"2026-09-29T14:04:20.004Z","first_at":"2026-09-29T14:03:05.100Z","last_changed_at":"2026-09-29T14:03:12.000Z","due_at":null,"hard_deadline_at":"2026-09-29T14:03:35.100Z","expires_at":"2026-09-30T14:03:12.000Z","dispatch_committed_at":null,"message_id":null,"effective_mode":"suggest","applied_mode":null,"fragment_count":2,"content_bytes":74,"edit_lease":{"active":true,"expires_at":"2026-09-29T14:06:20.000Z"},"limits":{"max_text_characters":4096,"max_fragments":32,"max_batch_bytes":16384},"routing":{"mode":"weighted","web_percent":30,"reserved":false},"sequence_entry":{"dispatch_id":"7e2b9c44-1d5f-4a3e-8b6c-9d0e1f2a3b4c","state":"open","blocking_reason":null,"blocking_dispatch_id":null},"content_purged":false,"original_text":null,"candidate":null,"permissions":{"edit":true,"remove_fragment":true,"pause":true,"resume":true,"flush":true,"use_original":true,"accept_candidate":false,"suggest":true,"cancel":true},"fragments":[{"fragment_id":"0b9e4c21-6a3f-4d58-8e17-2c4b6d8f0a12","ordinal":1,"revision":1,"content":"Oi, Marina! separei as duas opções que você pediu","created_at":"2026-09-29T14:03:05.100Z"},{"fragment_id":"1c8f5d32-7b40-4e69-9f28-3d5c7e9a1b23","ordinal":2,"revision":1,"content":"as duas chegam amanhã","created_at":"2026-09-29T14:03:12.000Z"}],"edit_lease_token":"8b1d3f57-6e9a-4c2b-8d4f-0a1b2c3d4e5f"}}}},"401":{"description":"Unauthorized"},"404":{"description":"The batch (or fragment) does not exist in this conversation (`not_found`), or the conversation does not exist.","content":{"application/json":{"schema":{"anyOf":[{"type":"object","additionalProperties":false,"required":["error"],"description":"The batch, fragment, entry or receipt does not exist for this caller in this conversation.","properties":{"error":{"type":"string","enum":["not_found"],"description":"Stable lane code."}}},{"type":"object","additionalProperties":false,"required":["error"],"description":"Generic lookup failure of the account API (the conversation or inbox does not exist in this account).","properties":{"error":{"type":"string","description":"Human-readable lookup failure (\"Resource could not be found\")."}}}]},"example":{"error":"not_found"}}}},"400":{"description":"Malformed request — unknown `action`, `request_id` not a UUID, `expected_revision` missing or invalid, or `digest` missing for `accept_candidate`.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error","errors"],"properties":{"error":{"type":"string","enum":["invalid_request"],"description":"Malformed request (400)."},"errors":{"type":"array","minItems":1,"description":"The offending request field(s), each with a stable validation code.","items":{"type":"object","additionalProperties":false,"required":["field","code"],"properties":{"field":{"type":"string","description":"Request field path, e.g. `content`, `context.in_reply_to`, `request_id`, `expected_revision`."},"code":{"type":"string","enum":["invalid_format","required","invalid_type","blank","not_allowed","unknown_field","out_of_range","not_found"],"description":"Stable validation code of that field."}}}}}},"example":{"error":"invalid_request","errors":[{"field":"digest","code":"required"}]}}}},"403":{"description":"Policy refusal — the caller cannot see the conversation, or the action belongs to the batch/entry author (or an inbox manager for `cancel`/`abandon`). Agent bot tokens are never actors of this lane.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","enum":["forbidden"],"description":"Policy refusal."}}},"example":{"error":"forbidden"}}}},"409":{"description":"`request_id_conflict`, `batch_revision_conflict`, or `transform_stale` (the `digest` is not the candidate under review any more — re-read before approving).","content":{"application/json":{"schema":{"anyOf":[{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","enum":["request_id_conflict","transform_stale"],"description":"Stable code."}}},{"type":"object","additionalProperties":false,"required":["error","current_revision"],"description":"`expected_revision` differs from the current revision; re-read and retry.","properties":{"error":{"type":"string","enum":["batch_revision_conflict"],"description":"Stable code (also used for sequence entries)."},"current_revision":{"type":"integer","minimum":1,"description":"The revision the record has now."}}}]},"example":{"error":"transform_stale"}}}},"422":{"description":"`batch_not_editable` — the action is not allowed from the current state, the dispatch commitment already happened, the module this action needs is off (`flag_disabled`), or there is no active text (`empty`). For `accept_candidate` the pinned Maestro profile must still be allowed NOW: `flag_disabled`, `policy_revoked`, `agent_profile_revoked`, `contract_version_mismatch` or `grant_key_mismatch` refuse the approval.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error","reason"],"description":"The batch no longer accepts this change — `committed` (the dispatch commitment happened or the batch is terminal), the current batch state name (the action is not allowed from it), `state` (see `state`), `flag_disabled` (the module needed by this action is off), `empty` (no active text), `edit_lease_expired` (pause again to edit) or `edit_lease_held` (another tab holds the edit lease). Approving a candidate (`accept_candidate`) is also refused while the pinned Maestro profile may no longer act: `policy_revoked` (the current mode no longer asks for a transformation), `agent_profile_revoked` (the profile left the allowlist or its inherited binding changed), or `contract_version_mismatch` / `grant_key_mismatch` (the Maestro module is restricted).","properties":{"error":{"type":"string","enum":["batch_not_editable"],"description":"Stable code."},"reason":{"type":"string","enum":["committed","state","flag_disabled","empty","edit_lease_expired","edit_lease_held","collecting","processing","awaiting_review","paused","ready","policy_revoked","agent_profile_revoked","contract_version_mismatch","grant_key_mismatch"],"description":"Why the change was refused."},"state":{"type":"string","enum":["collecting","processing","awaiting_review","paused","ready","materializing","materialized","canceled","expired"],"description":"Batch state — `collecting` (collection window open), `processing` (a Maestro transformation is claimed), `awaiting_review` (a candidate waits for the author), `paused` (a human decision is needed), `ready` (approved, due now), `materializing`, then the terminal `materialized` (exactly one Message exists), `canceled` or `expired` (nothing was sent). A batch state is not a delivery state."}}},"example":{"error":"batch_not_editable","reason":"flag_disabled","state":"paused"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"in":"path","name":"conversation_id","required":true,"description":"Account-scoped conversation display id.","schema":{"type":"integer"}},{"in":"path","name":"batch_id","required":true,"description":"Public batch id.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"anyOf":[{"type":"object","required":["request_id","expected_revision","action"],"properties":{"request_id":{"type":"string","format":"uuid","description":"Idempotency id of this action."},"expected_revision":{"type":"integer","minimum":1,"description":"The batch revision last read."},"action":{"type":"string","enum":["pause","resume","flush","use_original","accept_candidate","cancel"],"description":"The action to apply."},"digest":{"type":"string","pattern":"^[0-9a-f]{64}$","description":"Required for `accept_candidate` — the candidate `digest` the author approved."}}},{"type":"object","required":["request_id","expected_revision","action_name"],"properties":{"request_id":{"type":"string","format":"uuid","description":"Idempotency id of this action."},"expected_revision":{"type":"integer","minimum":1,"description":"The batch revision last read."},"action_name":{"type":"string","enum":["pause","resume","flush","use_original","accept_candidate","cancel"],"description":"The action to apply."},"digest":{"type":"string","pattern":"^[0-9a-f]{64}$","description":"Required for `accept_candidate`."}}}]},"example":{"request_id":"c3e5a7b9-4d6f-4a8c-9e0b-1a2c3d4e5f60","expected_revision":4,"action":"accept_candidate","digest":"3c256ec4052923b702936f7dd31fff42a19fdc896c1c7dbbbe11ac7c679368da"}}}}}},"/api/v1/accounts/{account_id}/whatsapp/outbound/conversations/{conversation_id}/batches/{batch_id}/preview":{"post":{"tags":["WhatsApp"],"operationId":"auto_post_api_v1_accounts_account_id_whatsapp_outbound_conversations_conversation_id_batches_batch_id_preview","summary":"Preview what a WhatsApp outbound batch would send","description":"What would leave for the CURRENT revision, computed by the server with the same preparation the commitment uses: the final draft (signature applied once), the text ceiling of every transport the conversation can use and the digest. A candidate under review shows its stored final draft and the digest `accept_candidate` must present. Strictly read-only — no quota, ordinal, AI call, Flow token, Message or write of any kind. Outbound translation, when the inbox has it, still happens once on the send path; the preview shows the text before translation. Author only.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The preview; `status` is `ready` or `blocked` (with `reason`).","content":{"application/json":{"schema":{"type":"object","required":["batch_id","revision","state","source","status","reason","text","character_count","digest","draft","limits"],"properties":{"batch_id":{"type":"string","format":"uuid","description":"Public batch id."},"revision":{"type":"integer","minimum":1,"description":"Revision the preview was computed for."},"state":{"type":"string","enum":["collecting","processing","awaiting_review","paused","ready","materializing","materialized","canceled","expired"],"description":"Batch state — `collecting` (collection window open), `processing` (a Maestro transformation is claimed), `awaiting_review` (a candidate waits for the author), `paused` (a human decision is needed), `ready` (approved, due now), `materializing`, then the terminal `materialized` (exactly one Message exists), `canceled` or `expired` (nothing was sent). A batch state is not a delivery state."},"source":{"type":"string","enum":["candidate","original"],"description":"`candidate` (the proposal under review) or `original` (the consolidated text of the author)."},"status":{"type":"string","enum":["ready","blocked"],"description":"Whether this draft could leave now."},"reason":{"type":["string","null"],"enum":["empty","text_limit_exceeded","transport_not_eligible","window_closed","flow_candidate_stale",null],"description":"Why it is blocked; null when ready."},"text":{"type":["string","null"],"description":"Text of the first part (a blocked preview still shows the consolidated text)."},"character_count":{"type":["integer","null"],"description":"Characters of `text`."},"digest":{"type":["string","null"],"pattern":"^[0-9a-f]{64}$","description":"Digest of the final draft (for a candidate, the value `accept_candidate` must present); null when blocked."},"draft":{"description":"The final draft (only `parts` with the text when blocked); null for an empty batch.","anyOf":[{"type":"object","required":["parts"],"description":"A provider-neutral outbound draft (schema version 1): ordered parts, each becoming one physical Message. The schema is closed — unknown keys are refused, never dropped. Keys a part does not use are omitted in responses; on input a null value is ignored.","properties":{"schema_version":{"type":"integer","enum":[1],"description":"Draft schema version (`version` and `draft_version` are accepted aliases on input)."},"delay_ms":{"type":"integer","minimum":0,"maximum":5000,"description":"Pause between consecutive parts, in milliseconds."},"parts":{"type":"array","minItems":1,"maxItems":50,"description":"The ordered parts; at most one part may quote an earlier message.","items":{"type":"object","description":"One physical Message. It must carry content, attachments or a structured payload.","properties":{"content":{"type":["string","null"],"maxLength":150000,"description":"Message text."},"content_type":{"type":"string","enum":["text","input_select","sticker","poll"],"description":"Content type of the Message (default `text`)."},"content_attributes":{"type":"object","additionalProperties":true,"propertyNames":{"enum":["in_reply_to","in_reply_to_external_id","items","email","interactive","wa_interactive","poll","catalog_product","media_kind","view_once","mention_all","mentioned_jids","mentions","is_forwarded","link_preview","location","contact","cta_buttons"]},"description":"Outbound metadata with a closed set of root keys (`in_reply_to` is the id of a message of the same conversation; `interactive` is a WhatsApp Cloud interactive payload, `wa_interactive` a WazMeow one; `cta_buttons`, `poll`, `location`, `contact`, `catalog_product` and the others carry their existing provider payloads, revalidated before dispatch). An unknown root key is refused."},"attachments":{"type":"array","maxItems":15,"description":"Signed references of already uploaded files.","items":{"anyOf":[{"type":"object","required":["signed_id"],"properties":{"signed_id":{"type":"string","description":"Signed id of an uploaded blob (`blob_signed_id` and `blobSignedId` are accepted aliases on input)."}}},{"type":"string","description":"The signed blob id itself (accepted on input; responses always use the object form)."}]}},"items":{"type":["array","null"],"maxItems":100,"description":"Select or poll options.","items":{"type":"object","additionalProperties":true,"description":"One option object as the provider adapters consume it."}},"is_voice_message":{"type":"boolean","description":"Send the audio attachment as a voice note."},"email_html_content":{"type":["string","null"],"description":"HTML body (e-mail channels only; unused on WhatsApp)."},"to_emails":{"type":["array","null"],"description":"E-mail recipients (e-mail channels only).","items":{"type":"string","format":"email"}},"cc_emails":{"type":["array","null"],"description":"E-mail copy recipients (e-mail channels only).","items":{"type":"string","format":"email"}},"bcc_emails":{"type":["array","null"],"description":"E-mail blind-copy recipients (e-mail channels only).","items":{"type":"string","format":"email"}},"template_params":{"type":["object","null"],"additionalProperties":true,"description":"Approved WhatsApp template identity and parameters."},"flow_params":{"type":["object","null"],"additionalProperties":true,"description":"WhatsApp Flow identity and parameters."},"whatsapp_transport":{"type":["string","null"],"enum":["cloud","web","auto",null],"description":"Explicit transport of a hybrid pair — `cloud` (WhatsApp Cloud) or `web` (WhatsApp Web via WazMeow). `auto` or null lets the router decide; responses only carry `cloud` or `web`."}}}},"attachments":{"type":"array","description":"Union of the attachment references of all parts (recomputed by the server; on input it must match the parts).","items":{"anyOf":[{"type":"object","required":["signed_id"],"properties":{"signed_id":{"type":"string","description":"Signed id of an uploaded blob (`blob_signed_id` and `blobSignedId` are accepted aliases on input)."}}},{"type":"string","description":"The signed blob id itself (accepted on input; responses always use the object form)."}]}}}},{"type":"null"}]},"limits":{"type":"object","required":["max_text_characters","max_fragments","max_batch_bytes"],"description":"Text limits of the conversation's logical transport and of one batch.","properties":{"max_text_characters":{"type":["integer","null"],"description":"Character ceiling of one text message on this inbox's channel (4096 on WhatsApp Cloud), or null when the channel declares none."},"max_fragments":{"type":"integer","description":"Maximum number of active fragments in one batch (32)."},"max_batch_bytes":{"type":"integer","description":"Maximum UTF-8 size of the active text of one batch, in bytes (16384)."}}}}},"example":{"batch_id":"5f0c2a8e-3b1d-4c6e-9a7f-1d2e3f4a5b60","revision":4,"state":"collecting","source":"original","status":"ready","reason":null,"text":"Oi, Marina! Separei as duas opções que você pediu.\nAs duas chegam amanhã.\n\nAna · Loja Centro","character_count":92,"digest":"eb7dc94b2f4be977cd1e595f9737329d29ca4eb57ab0e17c9c50ab2f0ce44a40","draft":{"schema_version":1,"delay_ms":0,"parts":[{"content":"Oi, Marina! Separei as duas opções que você pediu.\nAs duas chegam amanhã.\n\nAna · Loja Centro","content_type":"text","content_attributes":{"in_reply_to":88213},"attachments":[],"items":null,"is_voice_message":false,"email_html_content":null,"to_emails":null,"cc_emails":null,"bcc_emails":null,"template_params":null,"flow_params":null,"whatsapp_transport":null}],"attachments":[]},"limits":{"max_text_characters":4096,"max_fragments":32,"max_batch_bytes":16384}}}}},"401":{"description":"Unauthorized"},"404":{"description":"The batch (or fragment) does not exist in this conversation (`not_found`), or the conversation does not exist.","content":{"application/json":{"schema":{"anyOf":[{"type":"object","additionalProperties":false,"required":["error"],"description":"The batch, fragment, entry or receipt does not exist for this caller in this conversation.","properties":{"error":{"type":"string","enum":["not_found"],"description":"Stable lane code."}}},{"type":"object","additionalProperties":false,"required":["error"],"description":"Generic lookup failure of the account API (the conversation or inbox does not exist in this account).","properties":{"error":{"type":"string","description":"Human-readable lookup failure (\"Resource could not be found\")."}}}]},"example":{"error":"not_found"}}}},"400":{"description":"`expected_revision` is not a positive integer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error","errors"],"properties":{"error":{"type":"string","enum":["invalid_request"],"description":"Malformed request (400)."},"errors":{"type":"array","minItems":1,"description":"The offending request field(s), each with a stable validation code.","items":{"type":"object","additionalProperties":false,"required":["field","code"],"properties":{"field":{"type":"string","description":"Request field path, e.g. `content`, `context.in_reply_to`, `request_id`, `expected_revision`."},"code":{"type":"string","enum":["invalid_format","required","invalid_type","blank","not_allowed","unknown_field","out_of_range","not_found"],"description":"Stable validation code of that field."}}}}}},"example":{"error":"invalid_request","errors":[{"field":"expected_revision","code":"invalid_type"}]}}}},"403":{"description":"Policy refusal — the caller cannot see the conversation, or the action belongs to the batch/entry author (or an inbox manager for `cancel`/`abandon`). Agent bot tokens are never actors of this lane.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","enum":["forbidden"],"description":"Policy refusal."}}},"example":{"error":"forbidden"}}}},"409":{"description":"`batch_revision_conflict` — the batch moved past `expected_revision`.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error","current_revision"],"description":"`expected_revision` differs from the current revision; re-read and retry.","properties":{"error":{"type":"string","enum":["batch_revision_conflict"],"description":"Stable code (also used for sequence entries)."},"current_revision":{"type":"integer","minimum":1,"description":"The revision the record has now."}}},"example":{"error":"batch_revision_conflict","current_revision":5}}}},"410":{"description":"`receipt_expired` — retention already purged the batch text.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","enum":["receipt_expired"],"description":"Stable code."}}},"example":{"error":"receipt_expired"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"in":"path","name":"conversation_id","required":true,"description":"Account-scoped conversation display id.","schema":{"type":"integer"}},{"in":"path","name":"batch_id","required":true,"description":"Public batch id.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"expected_revision":{"type":"integer","minimum":1,"description":"When present, the preview is refused (409) unless the batch is still at this revision."}}},"example":{"expected_revision":4}}}}}},"/api/v1/accounts/{account_id}/whatsapp/outbound/conversations/{conversation_id}/batches/{batch_id}/suggest":{"post":{"tags":["WhatsApp"],"operationId":"auto_post_api_v1_accounts_account_id_whatsapp_outbound_conversations_conversation_id_batches_batch_id_suggest","summary":"Ask Maestro for a suggestion on my WhatsApp outbound batch","description":"The author asks Maestro to propose a transformation of the CURRENT revision. Answers 202: the request is recorded, the batch is sealed into `processing` and the transformation runs in the background (never under a lock). The result can only reach `awaiting_review` — a human-requested suggestion never sends by itself, whatever the mode. Allowed from `collecting`, `awaiting_review` or `paused`, only while Maestro is available to this agent now (flag and an effective mode of `suggest` or `automatic`). Idempotent per `request_id`.","security":[{"userApiKey":[]}],"responses":{"202":{"description":"The suggestion was requested (or replayed); the snapshot shows the batch in `processing`.","content":{"application/json":{"schema":{"description":"A consistent snapshot of one batch with its active fragments.","allOf":[{"type":"object","required":["schema_version","batch_id","conversation_id","inbox_id","author_id","state","state_reason","revision","server_now","first_at","last_changed_at","due_at","hard_deadline_at","expires_at","dispatch_committed_at","message_id","effective_mode","applied_mode","fragment_count","content_bytes","edit_lease","limits","routing","sequence_entry","content_purged","original_text","candidate","permissions"],"properties":{"schema_version":{"type":"integer","enum":[1],"description":"Version of this payload shape."},"batch_id":{"type":"string","format":"uuid","description":"Public id of the batch (the numeric id never leaves the server)."},"conversation_id":{"type":"integer","description":"Account-scoped conversation display id."},"inbox_id":{"type":"integer","description":"Inbox the batch was opened on (the logical inbox of the conversation)."},"author_id":{"type":["integer","null"],"description":"User id of the agent who wrote the batch."},"state":{"type":"string","enum":["collecting","processing","awaiting_review","paused","ready","materializing","materialized","canceled","expired"],"description":"Batch state — `collecting` (collection window open), `processing` (a Maestro transformation is claimed), `awaiting_review` (a candidate waits for the author), `paused` (a human decision is needed), `ready` (approved, due now), `materializing`, then the terminal `materialized` (exactly one Message exists), `canceled` or `expired` (nothing was sent). A batch state is not a delivery state."},"state_reason":{"type":["string","null"],"enum":["contact_replied","contact_merged","human_edit","transform_unavailable","transform_stale","transform_budget_exceeded","policy_revoked","flag_disabled","agent_profile_revoked","agent_profile_mismatch","text_limit_exceeded","transport_not_eligible","flow_candidate_stale","pacing_exhausted","predecessor_blocked","provider_rejected","dispatch_effect_unknown","window_closed","human_access_revoked","predecessor_pending",null],"description":"Closed pause/hold reason code (the dashboard translates it; the API never sends prose), or null when there is no reason to report."},"revision":{"type":"integer","minimum":1,"description":"Batch revision; send it back as `expected_revision` on every mutation (optimistic concurrency)."},"server_now":{"type":"string","format":"date-time","description":"Server clock at read time; clients compute countdowns from this offset, never from their own clock."},"first_at":{"type":"string","format":"date-time","description":"When the first fragment was accepted."},"last_changed_at":{"type":"string","format":"date-time","description":"Last accepted content change (typing and HTTP replays never move it)."},"due_at":{"type":["string","null"],"format":"date-time","description":"When the batch leaves by time — min(last change + idle, hard deadline); null unless collecting or ready."},"hard_deadline_at":{"type":"string","format":"date-time","description":"Fixed ceiling of the collection window (first fragment + maximum wait); never moves later."},"expires_at":{"type":["string","null"],"format":"date-time","description":"When a never-sent batch expires without sending (24 h after the last change); null once terminal or committed."},"dispatch_committed_at":{"type":["string","null"],"format":"date-time","description":"When the local dispatch commitment happened (edit and cancel close there); not provider acceptance."},"message_id":{"type":["integer","null"],"description":"The one Message this batch became (set when materialized); delivery truth belongs to that Message."},"effective_mode":{"type":"string","enum":["faithful","suggest","automatic"],"description":"Maestro mode — `faithful` (the author's consolidated text leaves as typed), `suggest` (a transformation is proposed and waits for the author) or `automatic` (an approved transformation may leave without review)."},"applied_mode":{"type":["string","null"],"enum":["faithful","original","candidate","candidate_unchanged","automatic","automatic_unchanged","fallback_original",null],"description":"What actually left — `faithful` (text as typed), `original` (author chose the original), `candidate` (approved suggestion), `candidate_unchanged` (approved suggestion in which Maestro changed nothing), `automatic` (automatic mode result), `automatic_unchanged` (automatic mode, Maestro changed nothing, the original left) or `fallback_original` (Maestro could not be used and the policy sent the original). Null until the batch is finalized."},"fragment_count":{"type":"integer","minimum":0,"maximum":32,"description":"Number of active fragments."},"content_bytes":{"type":"integer","minimum":0,"maximum":16384,"description":"UTF-8 size of the active text, in bytes."},"edit_lease":{"type":"object","required":["active","expires_at"],"description":"The 2-minute edit lease a pause grants to the editing tab (the token itself is never exposed here).","properties":{"active":{"type":"boolean","description":"Whether some tab currently holds the edit lease."},"expires_at":{"type":["string","null"],"format":"date-time","description":"When the last granted lease ends; null when none was granted."}}},"limits":{"type":"object","required":["max_text_characters","max_fragments","max_batch_bytes"],"description":"Text limits of the conversation's logical transport and of one batch.","properties":{"max_text_characters":{"type":["integer","null"],"description":"Character ceiling of one text message on this inbox's channel (4096 on WhatsApp Cloud), or null when the channel declares none."},"max_fragments":{"type":"integer","description":"Maximum number of active fragments in one batch (32)."},"max_batch_bytes":{"type":"integer","description":"Maximum UTF-8 size of the active text of one batch, in bytes (16384)."}}},"routing":{"type":"object","required":["mode","web_percent","reserved"],"description":"Routing policy of the conversation's hybrid pair (WhatsApp Cloud + WhatsApp Web via WazMeow).","properties":{"mode":{"type":"string","enum":["legacy","weighted"],"description":"`weighted` when the percentage routing of the pair is on for this lane; `legacy` otherwise."},"web_percent":{"type":["integer","null"],"minimum":0,"maximum":100,"description":"Share of new contacts routed to WhatsApp Web under `weighted`; null under `legacy`."},"reserved":{"type":"boolean","description":"True once a routing decision was recorded for this entry."}}},"sequence_entry":{"type":["object","null"],"description":"The batch's place in the conversation's dispatch order, or null.","required":["dispatch_id","state","blocking_reason","blocking_dispatch_id"],"properties":{"dispatch_id":{"type":"string","format":"uuid","description":"Public id of the sequence entry that owns this batch."},"state":{"type":"string","enum":["open","committed","held","settled","abandoned","canceled"],"description":"Sequence entry state — `open` (not committed yet), `committed` (its Messages exist and wait for their turn or the provider), `held` (a part needs a human disposition), then the terminal `settled` (every part accepted by the provider), `abandoned` (a human abandoned it) or `canceled` (canceled before the dispatch commitment)."},"blocking_reason":{"type":["string","null"],"enum":["predecessor_blocked","predecessor_pending",null],"description":"Why this entry still waits for an earlier entry of the conversation — `predecessor_blocked` (an earlier entry needs a human decision; new outputs are refused with `sequence_blocked`) or `predecessor_pending` (earlier entries are only in flight). Null when nothing blocks it."},"blocking_dispatch_id":{"type":["string","null"],"format":"uuid","description":"The earliest entry this one waits for, or null."}}},"content_purged":{"type":"boolean","description":"True once retention removed the batch text (digests and counters remain)."},"original_text":{"type":["string","null"],"description":"The consolidated original text as last sealed for processing; null before the first seal or once purged."},"candidate":{"type":["object","null"],"description":"The Maestro proposal waiting for the author's review, or null. Its `digest` is the value `accept_candidate` must present. Never carries prompts, grants, model output metadata or provider data.","properties":{"outcome":{"type":"string","enum":["unchanged","rewritten","structured","unavailable","requires_review"],"description":"Maestro outcome of the transformation."},"format":{"type":"string","enum":["text","buttons","list","cta","whatsapp_flow"],"description":"Output format of the candidate."},"text":{"type":["string","null"],"description":"Proposed text (the message body of a structured candidate)."},"data":{"type":"object","additionalProperties":true,"description":"Format-specific structure: `{}` for text; `buttons` (1–3 `{title, id?}`) plus optional `header`/`footer` for buttons; `sections` of rows plus optional `button` for a list; `{display_text, url}` for a call to action; `{seed?, cta?}` for a WhatsApp Flow. Button and row ids are assigned by the server."},"asset_ref":{"type":["object","null"],"description":"The pinned WhatsApp Flow mapping version of a `whatsapp_flow` candidate; null for any other format.","required":["mapping_id","mapping_version","mapping_digest"],"properties":{"mapping_id":{"type":"string","description":"Flow mapping id of the inbox policy."},"mapping_version":{"type":"integer","minimum":1,"description":"Immutable version of that mapping."},"mapping_digest":{"type":"string","pattern":"^[0-9a-f]{64}$","description":"SHA-256 digest of that mapping version."}}},"reason_codes":{"type":"array","maxItems":16,"description":"Closed-vocabulary codes Maestro reported for the proposal (lower snake case).","items":{"type":"string","pattern":"^[a-z][a-z0-9_]{0,63}$"}},"requires_review":{"type":"boolean","description":"Whether the proposal needs a human review before it can leave."},"digest":{"type":"string","pattern":"^[0-9a-f]{64}$","description":"SHA-256 digest of the candidate's final draft; send it back as `digest` in `accept_candidate`."}}},"permissions":{"type":"object","required":["edit","remove_fragment","pause","resume","flush","use_original","accept_candidate","suggest","cancel"],"description":"What the CURRENT caller may do with this batch right now, computed at read time from the author rule (content actions are the author's only; `cancel` is the author's or an inbox manager's), the batch state and the current lane configuration. Every key is false once the dispatch commitment happened or the batch is terminal.","properties":{"edit":{"type":"boolean","description":"Edit a fragment (paused batch, with the edit lease of the pausing tab)."},"remove_fragment":{"type":"boolean","description":"Remove a fragment (collecting or paused batch)."},"pause":{"type":"boolean","description":"Pause the batch to edit it."},"resume":{"type":"boolean","description":"Resume a paused batch (needs the batching module on)."},"flush":{"type":"boolean","description":"Send now, skipping only the idle wait (needs the batching module on)."},"use_original":{"type":"boolean","description":"Send the author's consolidated text now, without Maestro."},"accept_candidate":{"type":"boolean","description":"Approve the candidate waiting for review."},"suggest":{"type":"boolean","description":"Ask Maestro for a suggestion of the current revision."},"cancel":{"type":"boolean","description":"Cancel the batch (author or inbox manager)."}}}}},{"type":"object","required":["fragments"],"properties":{"fragments":{"type":"array","maxItems":32,"description":"Active fragments of the batch in ordinal order; removed fragments are tombstones and are omitted.","items":{"type":"object","required":["fragment_id","ordinal","revision","content","created_at"],"properties":{"fragment_id":{"type":"string","format":"uuid","description":"Public id of the fragment."},"ordinal":{"type":"integer","minimum":1,"description":"Position of the fragment inside the batch; stable across removals."},"revision":{"type":"integer","minimum":1,"description":"Revision of this fragment (an edit increments it)."},"content":{"type":["string","null"],"description":"The exact text the agent confirmed (byte-faithful), or null once retention purged the text."},"created_at":{"type":"string","format":"date-time","description":"When the fragment was accepted (UTC)."}}}}}}]},"example":{"schema_version":1,"batch_id":"5f0c2a8e-3b1d-4c6e-9a7f-1d2e3f4a5b60","conversation_id":1284,"inbox_id":17,"author_id":9,"state":"awaiting_review","state_reason":null,"revision":4,"server_now":"2026-09-29T14:04:02.310Z","first_at":"2026-09-29T14:03:05.100Z","last_changed_at":"2026-09-29T14:03:12.000Z","due_at":null,"hard_deadline_at":"2026-09-29T14:03:35.100Z","expires_at":"2026-09-30T14:03:12.000Z","dispatch_committed_at":null,"message_id":null,"effective_mode":"suggest","applied_mode":null,"fragment_count":2,"content_bytes":74,"edit_lease":{"active":false,"expires_at":null},"limits":{"max_text_characters":4096,"max_fragments":32,"max_batch_bytes":16384},"routing":{"mode":"weighted","web_percent":30,"reserved":false},"sequence_entry":{"dispatch_id":"7e2b9c44-1d5f-4a3e-8b6c-9d0e1f2a3b4c","state":"open","blocking_reason":null,"blocking_dispatch_id":null},"content_purged":false,"original_text":"Oi, Marina! separei as duas opções que você pediu\nas duas chegam amanhã","candidate":{"outcome":"rewritten","format":"text","text":"Oi, Marina! Separei as duas opções que você pediu.\nAs duas chegam amanhã.","data":{},"asset_ref":null,"reason_codes":["grammar_adjusted","formatting_adjusted"],"requires_review":true,"digest":"3c256ec4052923b702936f7dd31fff42a19fdc896c1c7dbbbe11ac7c679368da"},"permissions":{"edit":false,"remove_fragment":false,"pause":true,"resume":false,"flush":false,"use_original":true,"accept_candidate":true,"suggest":true,"cancel":true},"fragments":[{"fragment_id":"0b9e4c21-6a3f-4d58-8e17-2c4b6d8f0a12","ordinal":1,"revision":1,"content":"Oi, Marina! separei as duas opções que você pediu","created_at":"2026-09-29T14:03:05.100Z"},{"fragment_id":"1c8f5d32-7b40-4e69-9f28-3d5c7e9a1b23","ordinal":2,"revision":1,"content":"as duas chegam amanhã","created_at":"2026-09-29T14:03:12.000Z"}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"The batch (or fragment) does not exist in this conversation (`not_found`), or the conversation does not exist.","content":{"application/json":{"schema":{"anyOf":[{"type":"object","additionalProperties":false,"required":["error"],"description":"The batch, fragment, entry or receipt does not exist for this caller in this conversation.","properties":{"error":{"type":"string","enum":["not_found"],"description":"Stable lane code."}}},{"type":"object","additionalProperties":false,"required":["error"],"description":"Generic lookup failure of the account API (the conversation or inbox does not exist in this account).","properties":{"error":{"type":"string","description":"Human-readable lookup failure (\"Resource could not be found\")."}}}]},"example":{"error":"not_found"}}}},"400":{"description":"Malformed request — `request_id` is not a UUID or `expected_revision` is missing or invalid.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error","errors"],"properties":{"error":{"type":"string","enum":["invalid_request"],"description":"Malformed request (400)."},"errors":{"type":"array","minItems":1,"description":"The offending request field(s), each with a stable validation code.","items":{"type":"object","additionalProperties":false,"required":["field","code"],"properties":{"field":{"type":"string","description":"Request field path, e.g. `content`, `context.in_reply_to`, `request_id`, `expected_revision`."},"code":{"type":"string","enum":["invalid_format","required","invalid_type","blank","not_allowed","unknown_field","out_of_range","not_found"],"description":"Stable validation code of that field."}}}}}},"example":{"error":"invalid_request","errors":[{"field":"expected_revision","code":"required"}]}}}},"403":{"description":"Policy refusal — the caller cannot see the conversation, or the action belongs to the batch/entry author (or an inbox manager for `cancel`/`abandon`). Agent bot tokens are never actors of this lane.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","enum":["forbidden"],"description":"Policy refusal."}}},"example":{"error":"forbidden"}}}},"409":{"description":"`request_id_conflict` or `batch_revision_conflict`.","content":{"application/json":{"schema":{"anyOf":[{"type":"object","additionalProperties":false,"required":["error"],"description":"The same `request_id` was already used by this actor for a different payload or record.","properties":{"error":{"type":"string","enum":["request_id_conflict"],"description":"Stable code."}}},{"type":"object","additionalProperties":false,"required":["error","current_revision"],"description":"`expected_revision` differs from the current revision; re-read and retry.","properties":{"error":{"type":"string","enum":["batch_revision_conflict"],"description":"Stable code (also used for sequence entries)."},"current_revision":{"type":"integer","minimum":1,"description":"The revision the record has now."}}}]},"example":{"error":"batch_revision_conflict","current_revision":3}}}},"422":{"description":"`batch_not_editable` (`reason: state` with the current `state`, or `empty`) or `transform_unavailable` (Maestro is not available to this agent now).","content":{"application/json":{"schema":{"anyOf":[{"type":"object","additionalProperties":false,"required":["error","reason"],"description":"The batch no longer accepts this change — `committed` (the dispatch commitment happened or the batch is terminal), the current batch state name (the action is not allowed from it), `state` (see `state`), `flag_disabled` (the module needed by this action is off), `empty` (no active text), `edit_lease_expired` (pause again to edit) or `edit_lease_held` (another tab holds the edit lease). Approving a candidate (`accept_candidate`) is also refused while the pinned Maestro profile may no longer act: `policy_revoked` (the current mode no longer asks for a transformation), `agent_profile_revoked` (the profile left the allowlist or its inherited binding changed), or `contract_version_mismatch` / `grant_key_mismatch` (the Maestro module is restricted).","properties":{"error":{"type":"string","enum":["batch_not_editable"],"description":"Stable code."},"reason":{"type":"string","enum":["committed","state","flag_disabled","empty","edit_lease_expired","edit_lease_held","collecting","processing","awaiting_review","paused","ready","policy_revoked","agent_profile_revoked","contract_version_mismatch","grant_key_mismatch"],"description":"Why the change was refused."},"state":{"type":"string","enum":["collecting","processing","awaiting_review","paused","ready","materializing","materialized","canceled","expired"],"description":"Batch state — `collecting` (collection window open), `processing` (a Maestro transformation is claimed), `awaiting_review` (a candidate waits for the author), `paused` (a human decision is needed), `ready` (approved, due now), `materializing`, then the terminal `materialized` (exactly one Message exists), `canceled` or `expired` (nothing was sent). A batch state is not a delivery state."}}},{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","enum":["transform_unavailable"],"description":"Stable code."}}}]},"example":{"error":"transform_unavailable","reason":"committed","state":"collecting"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"in":"path","name":"conversation_id","required":true,"description":"Account-scoped conversation display id.","schema":{"type":"integer"}},{"in":"path","name":"batch_id","required":true,"description":"Public batch id.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["request_id","expected_revision"],"properties":{"request_id":{"type":"string","format":"uuid","description":"Idempotency id of this request."},"expected_revision":{"type":"integer","minimum":1,"description":"The batch revision last read."}}},"example":{"request_id":"c3e5a7b9-4d6f-4a8c-9e0b-1a2c3d4e5f60","expected_revision":2}}}}}},"/api/v1/accounts/{account_id}/whatsapp/outbound/conversations/{conversation_id}/batches":{"get":{"tags":["WhatsApp"],"operationId":"auto_get_api_v1_accounts_account_id_whatsapp_outbound_conversations_conversation_id_batches","summary":"List the WhatsApp outbound batches of a conversation","description":"The conversation's batches (and those of its canonical unified conversation) that still matter — every non-terminal one plus terminal ones changed in the last 24 hours — oldest first, each with its active fragments and the caller's permissions. Reading follows the conversation's visibility; fragments of another author are visible but never editable. Works with the module flags off.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"One page of batch snapshots.","content":{"application/json":{"schema":{"type":"object","required":["payload","meta"],"properties":{"payload":{"type":"array","description":"Batch snapshots in creation order.","items":{"description":"A consistent snapshot of one batch with its active fragments.","allOf":[{"type":"object","required":["schema_version","batch_id","conversation_id","inbox_id","author_id","state","state_reason","revision","server_now","first_at","last_changed_at","due_at","hard_deadline_at","expires_at","dispatch_committed_at","message_id","effective_mode","applied_mode","fragment_count","content_bytes","edit_lease","limits","routing","sequence_entry","content_purged","original_text","candidate","permissions"],"properties":{"schema_version":{"type":"integer","enum":[1],"description":"Version of this payload shape."},"batch_id":{"type":"string","format":"uuid","description":"Public id of the batch (the numeric id never leaves the server)."},"conversation_id":{"type":"integer","description":"Account-scoped conversation display id."},"inbox_id":{"type":"integer","description":"Inbox the batch was opened on (the logical inbox of the conversation)."},"author_id":{"type":["integer","null"],"description":"User id of the agent who wrote the batch."},"state":{"type":"string","enum":["collecting","processing","awaiting_review","paused","ready","materializing","materialized","canceled","expired"],"description":"Batch state — `collecting` (collection window open), `processing` (a Maestro transformation is claimed), `awaiting_review` (a candidate waits for the author), `paused` (a human decision is needed), `ready` (approved, due now), `materializing`, then the terminal `materialized` (exactly one Message exists), `canceled` or `expired` (nothing was sent). A batch state is not a delivery state."},"state_reason":{"type":["string","null"],"enum":["contact_replied","contact_merged","human_edit","transform_unavailable","transform_stale","transform_budget_exceeded","policy_revoked","flag_disabled","agent_profile_revoked","agent_profile_mismatch","text_limit_exceeded","transport_not_eligible","flow_candidate_stale","pacing_exhausted","predecessor_blocked","provider_rejected","dispatch_effect_unknown","window_closed","human_access_revoked","predecessor_pending",null],"description":"Closed pause/hold reason code (the dashboard translates it; the API never sends prose), or null when there is no reason to report."},"revision":{"type":"integer","minimum":1,"description":"Batch revision; send it back as `expected_revision` on every mutation (optimistic concurrency)."},"server_now":{"type":"string","format":"date-time","description":"Server clock at read time; clients compute countdowns from this offset, never from their own clock."},"first_at":{"type":"string","format":"date-time","description":"When the first fragment was accepted."},"last_changed_at":{"type":"string","format":"date-time","description":"Last accepted content change (typing and HTTP replays never move it)."},"due_at":{"type":["string","null"],"format":"date-time","description":"When the batch leaves by time — min(last change + idle, hard deadline); null unless collecting or ready."},"hard_deadline_at":{"type":"string","format":"date-time","description":"Fixed ceiling of the collection window (first fragment + maximum wait); never moves later."},"expires_at":{"type":["string","null"],"format":"date-time","description":"When a never-sent batch expires without sending (24 h after the last change); null once terminal or committed."},"dispatch_committed_at":{"type":["string","null"],"format":"date-time","description":"When the local dispatch commitment happened (edit and cancel close there); not provider acceptance."},"message_id":{"type":["integer","null"],"description":"The one Message this batch became (set when materialized); delivery truth belongs to that Message."},"effective_mode":{"type":"string","enum":["faithful","suggest","automatic"],"description":"Maestro mode — `faithful` (the author's consolidated text leaves as typed), `suggest` (a transformation is proposed and waits for the author) or `automatic` (an approved transformation may leave without review)."},"applied_mode":{"type":["string","null"],"enum":["faithful","original","candidate","candidate_unchanged","automatic","automatic_unchanged","fallback_original",null],"description":"What actually left — `faithful` (text as typed), `original` (author chose the original), `candidate` (approved suggestion), `candidate_unchanged` (approved suggestion in which Maestro changed nothing), `automatic` (automatic mode result), `automatic_unchanged` (automatic mode, Maestro changed nothing, the original left) or `fallback_original` (Maestro could not be used and the policy sent the original). Null until the batch is finalized."},"fragment_count":{"type":"integer","minimum":0,"maximum":32,"description":"Number of active fragments."},"content_bytes":{"type":"integer","minimum":0,"maximum":16384,"description":"UTF-8 size of the active text, in bytes."},"edit_lease":{"type":"object","required":["active","expires_at"],"description":"The 2-minute edit lease a pause grants to the editing tab (the token itself is never exposed here).","properties":{"active":{"type":"boolean","description":"Whether some tab currently holds the edit lease."},"expires_at":{"type":["string","null"],"format":"date-time","description":"When the last granted lease ends; null when none was granted."}}},"limits":{"type":"object","required":["max_text_characters","max_fragments","max_batch_bytes"],"description":"Text limits of the conversation's logical transport and of one batch.","properties":{"max_text_characters":{"type":["integer","null"],"description":"Character ceiling of one text message on this inbox's channel (4096 on WhatsApp Cloud), or null when the channel declares none."},"max_fragments":{"type":"integer","description":"Maximum number of active fragments in one batch (32)."},"max_batch_bytes":{"type":"integer","description":"Maximum UTF-8 size of the active text of one batch, in bytes (16384)."}}},"routing":{"type":"object","required":["mode","web_percent","reserved"],"description":"Routing policy of the conversation's hybrid pair (WhatsApp Cloud + WhatsApp Web via WazMeow).","properties":{"mode":{"type":"string","enum":["legacy","weighted"],"description":"`weighted` when the percentage routing of the pair is on for this lane; `legacy` otherwise."},"web_percent":{"type":["integer","null"],"minimum":0,"maximum":100,"description":"Share of new contacts routed to WhatsApp Web under `weighted`; null under `legacy`."},"reserved":{"type":"boolean","description":"True once a routing decision was recorded for this entry."}}},"sequence_entry":{"type":["object","null"],"description":"The batch's place in the conversation's dispatch order, or null.","required":["dispatch_id","state","blocking_reason","blocking_dispatch_id"],"properties":{"dispatch_id":{"type":"string","format":"uuid","description":"Public id of the sequence entry that owns this batch."},"state":{"type":"string","enum":["open","committed","held","settled","abandoned","canceled"],"description":"Sequence entry state — `open` (not committed yet), `committed` (its Messages exist and wait for their turn or the provider), `held` (a part needs a human disposition), then the terminal `settled` (every part accepted by the provider), `abandoned` (a human abandoned it) or `canceled` (canceled before the dispatch commitment)."},"blocking_reason":{"type":["string","null"],"enum":["predecessor_blocked","predecessor_pending",null],"description":"Why this entry still waits for an earlier entry of the conversation — `predecessor_blocked` (an earlier entry needs a human decision; new outputs are refused with `sequence_blocked`) or `predecessor_pending` (earlier entries are only in flight). Null when nothing blocks it."},"blocking_dispatch_id":{"type":["string","null"],"format":"uuid","description":"The earliest entry this one waits for, or null."}}},"content_purged":{"type":"boolean","description":"True once retention removed the batch text (digests and counters remain)."},"original_text":{"type":["string","null"],"description":"The consolidated original text as last sealed for processing; null before the first seal or once purged."},"candidate":{"type":["object","null"],"description":"The Maestro proposal waiting for the author's review, or null. Its `digest` is the value `accept_candidate` must present. Never carries prompts, grants, model output metadata or provider data.","properties":{"outcome":{"type":"string","enum":["unchanged","rewritten","structured","unavailable","requires_review"],"description":"Maestro outcome of the transformation."},"format":{"type":"string","enum":["text","buttons","list","cta","whatsapp_flow"],"description":"Output format of the candidate."},"text":{"type":["string","null"],"description":"Proposed text (the message body of a structured candidate)."},"data":{"type":"object","additionalProperties":true,"description":"Format-specific structure: `{}` for text; `buttons` (1–3 `{title, id?}`) plus optional `header`/`footer` for buttons; `sections` of rows plus optional `button` for a list; `{display_text, url}` for a call to action; `{seed?, cta?}` for a WhatsApp Flow. Button and row ids are assigned by the server."},"asset_ref":{"type":["object","null"],"description":"The pinned WhatsApp Flow mapping version of a `whatsapp_flow` candidate; null for any other format.","required":["mapping_id","mapping_version","mapping_digest"],"properties":{"mapping_id":{"type":"string","description":"Flow mapping id of the inbox policy."},"mapping_version":{"type":"integer","minimum":1,"description":"Immutable version of that mapping."},"mapping_digest":{"type":"string","pattern":"^[0-9a-f]{64}$","description":"SHA-256 digest of that mapping version."}}},"reason_codes":{"type":"array","maxItems":16,"description":"Closed-vocabulary codes Maestro reported for the proposal (lower snake case).","items":{"type":"string","pattern":"^[a-z][a-z0-9_]{0,63}$"}},"requires_review":{"type":"boolean","description":"Whether the proposal needs a human review before it can leave."},"digest":{"type":"string","pattern":"^[0-9a-f]{64}$","description":"SHA-256 digest of the candidate's final draft; send it back as `digest` in `accept_candidate`."}}},"permissions":{"type":"object","required":["edit","remove_fragment","pause","resume","flush","use_original","accept_candidate","suggest","cancel"],"description":"What the CURRENT caller may do with this batch right now, computed at read time from the author rule (content actions are the author's only; `cancel` is the author's or an inbox manager's), the batch state and the current lane configuration. Every key is false once the dispatch commitment happened or the batch is terminal.","properties":{"edit":{"type":"boolean","description":"Edit a fragment (paused batch, with the edit lease of the pausing tab)."},"remove_fragment":{"type":"boolean","description":"Remove a fragment (collecting or paused batch)."},"pause":{"type":"boolean","description":"Pause the batch to edit it."},"resume":{"type":"boolean","description":"Resume a paused batch (needs the batching module on)."},"flush":{"type":"boolean","description":"Send now, skipping only the idle wait (needs the batching module on)."},"use_original":{"type":"boolean","description":"Send the author's consolidated text now, without Maestro."},"accept_candidate":{"type":"boolean","description":"Approve the candidate waiting for review."},"suggest":{"type":"boolean","description":"Ask Maestro for a suggestion of the current revision."},"cancel":{"type":"boolean","description":"Cancel the batch (author or inbox manager)."}}}}},{"type":"object","required":["fragments"],"properties":{"fragments":{"type":"array","maxItems":32,"description":"Active fragments of the batch in ordinal order; removed fragments are tombstones and are omitted.","items":{"type":"object","required":["fragment_id","ordinal","revision","content","created_at"],"properties":{"fragment_id":{"type":"string","format":"uuid","description":"Public id of the fragment."},"ordinal":{"type":"integer","minimum":1,"description":"Position of the fragment inside the batch; stable across removals."},"revision":{"type":"integer","minimum":1,"description":"Revision of this fragment (an edit increments it)."},"content":{"type":["string","null"],"description":"The exact text the agent confirmed (byte-faithful), or null once retention purged the text."},"created_at":{"type":"string","format":"date-time","description":"When the fragment was accepted (UTC)."}}}}}}]}},"meta":{"type":"object","required":["page","per_page","total_count","next_page"],"description":"Page-number pagination.","properties":{"page":{"type":"integer","minimum":1,"description":"Current page (1-based)."},"per_page":{"type":"integer","minimum":1,"maximum":100,"description":"Items per page."},"total_count":{"type":"integer","minimum":0,"description":"Items across all pages."},"next_page":{"type":["integer","null"],"description":"Next page number, or null on the last page."}}}}},"example":{"payload":[{"schema_version":1,"batch_id":"5f0c2a8e-3b1d-4c6e-9a7f-1d2e3f4a5b60","conversation_id":1284,"inbox_id":17,"author_id":9,"state":"awaiting_review","state_reason":null,"revision":4,"server_now":"2026-09-29T14:04:02.310Z","first_at":"2026-09-29T14:03:05.100Z","last_changed_at":"2026-09-29T14:03:12.000Z","due_at":null,"hard_deadline_at":"2026-09-29T14:03:35.100Z","expires_at":"2026-09-30T14:03:12.000Z","dispatch_committed_at":null,"message_id":null,"effective_mode":"suggest","applied_mode":null,"fragment_count":2,"content_bytes":74,"edit_lease":{"active":false,"expires_at":null},"limits":{"max_text_characters":4096,"max_fragments":32,"max_batch_bytes":16384},"routing":{"mode":"weighted","web_percent":30,"reserved":false},"sequence_entry":{"dispatch_id":"7e2b9c44-1d5f-4a3e-8b6c-9d0e1f2a3b4c","state":"open","blocking_reason":null,"blocking_dispatch_id":null},"content_purged":false,"original_text":"Oi, Marina! separei as duas opções que você pediu\nas duas chegam amanhã","candidate":{"outcome":"rewritten","format":"text","text":"Oi, Marina! Separei as duas opções que você pediu.\nAs duas chegam amanhã.","data":{},"asset_ref":null,"reason_codes":["grammar_adjusted","formatting_adjusted"],"requires_review":true,"digest":"3c256ec4052923b702936f7dd31fff42a19fdc896c1c7dbbbe11ac7c679368da"},"permissions":{"edit":false,"remove_fragment":false,"pause":true,"resume":false,"flush":false,"use_original":true,"accept_candidate":true,"suggest":true,"cancel":true},"fragments":[{"fragment_id":"0b9e4c21-6a3f-4d58-8e17-2c4b6d8f0a12","ordinal":1,"revision":1,"content":"Oi, Marina! separei as duas opções que você pediu","created_at":"2026-09-29T14:03:05.100Z"},{"fragment_id":"1c8f5d32-7b40-4e69-9f28-3d5c7e9a1b23","ordinal":2,"revision":1,"content":"as duas chegam amanhã","created_at":"2026-09-29T14:03:12.000Z"}]}],"meta":{"page":1,"per_page":25,"total_count":1,"next_page":null}}}}},"401":{"description":"Unauthorized"},"404":{"description":"The conversation does not exist in the account.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"description":"Generic lookup failure of the account API (the conversation or inbox does not exist in this account).","properties":{"error":{"type":"string","description":"Human-readable lookup failure (\"Resource could not be found\")."}}},"example":{"error":"Resource could not be found"}}}},"403":{"description":"Policy refusal — the caller cannot see the conversation, or the action belongs to the batch/entry author (or an inbox manager for `cancel`/`abandon`). Agent bot tokens are never actors of this lane.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","enum":["forbidden"],"description":"Policy refusal."}}},"example":{"error":"forbidden"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"in":"path","name":"conversation_id","required":true,"description":"Account-scoped conversation display id.","schema":{"type":"integer"}},{"in":"query","name":"page","required":false,"description":"Page number (1-based).","schema":{"type":"integer","minimum":1,"default":1}},{"in":"query","name":"per_page","required":false,"description":"Items per page (at most 100).","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}}]}},"/api/v1/accounts/{account_id}/whatsapp/outbound/conversations/{conversation_id}/batches/{batch_id}":{"get":{"tags":["WhatsApp"],"operationId":"auto_get_api_v1_accounts_account_id_whatsapp_outbound_conversations_conversation_id_batches_batch_id","summary":"Get a WhatsApp outbound batch","description":"A consistent snapshot of one batch — state, revision, server clock and collection window, active fragments, the candidate under review, limits, routing summary, its dispatch entry and the caller's permissions. Clients reconcile a lost realtime update with this read. Never exposes claim or edit tokens, policy snapshots or Maestro/provider internals.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The batch snapshot.","content":{"application/json":{"schema":{"description":"A consistent snapshot of one batch with its active fragments.","allOf":[{"type":"object","required":["schema_version","batch_id","conversation_id","inbox_id","author_id","state","state_reason","revision","server_now","first_at","last_changed_at","due_at","hard_deadline_at","expires_at","dispatch_committed_at","message_id","effective_mode","applied_mode","fragment_count","content_bytes","edit_lease","limits","routing","sequence_entry","content_purged","original_text","candidate","permissions"],"properties":{"schema_version":{"type":"integer","enum":[1],"description":"Version of this payload shape."},"batch_id":{"type":"string","format":"uuid","description":"Public id of the batch (the numeric id never leaves the server)."},"conversation_id":{"type":"integer","description":"Account-scoped conversation display id."},"inbox_id":{"type":"integer","description":"Inbox the batch was opened on (the logical inbox of the conversation)."},"author_id":{"type":["integer","null"],"description":"User id of the agent who wrote the batch."},"state":{"type":"string","enum":["collecting","processing","awaiting_review","paused","ready","materializing","materialized","canceled","expired"],"description":"Batch state — `collecting` (collection window open), `processing` (a Maestro transformation is claimed), `awaiting_review` (a candidate waits for the author), `paused` (a human decision is needed), `ready` (approved, due now), `materializing`, then the terminal `materialized` (exactly one Message exists), `canceled` or `expired` (nothing was sent). A batch state is not a delivery state."},"state_reason":{"type":["string","null"],"enum":["contact_replied","contact_merged","human_edit","transform_unavailable","transform_stale","transform_budget_exceeded","policy_revoked","flag_disabled","agent_profile_revoked","agent_profile_mismatch","text_limit_exceeded","transport_not_eligible","flow_candidate_stale","pacing_exhausted","predecessor_blocked","provider_rejected","dispatch_effect_unknown","window_closed","human_access_revoked","predecessor_pending",null],"description":"Closed pause/hold reason code (the dashboard translates it; the API never sends prose), or null when there is no reason to report."},"revision":{"type":"integer","minimum":1,"description":"Batch revision; send it back as `expected_revision` on every mutation (optimistic concurrency)."},"server_now":{"type":"string","format":"date-time","description":"Server clock at read time; clients compute countdowns from this offset, never from their own clock."},"first_at":{"type":"string","format":"date-time","description":"When the first fragment was accepted."},"last_changed_at":{"type":"string","format":"date-time","description":"Last accepted content change (typing and HTTP replays never move it)."},"due_at":{"type":["string","null"],"format":"date-time","description":"When the batch leaves by time — min(last change + idle, hard deadline); null unless collecting or ready."},"hard_deadline_at":{"type":"string","format":"date-time","description":"Fixed ceiling of the collection window (first fragment + maximum wait); never moves later."},"expires_at":{"type":["string","null"],"format":"date-time","description":"When a never-sent batch expires without sending (24 h after the last change); null once terminal or committed."},"dispatch_committed_at":{"type":["string","null"],"format":"date-time","description":"When the local dispatch commitment happened (edit and cancel close there); not provider acceptance."},"message_id":{"type":["integer","null"],"description":"The one Message this batch became (set when materialized); delivery truth belongs to that Message."},"effective_mode":{"type":"string","enum":["faithful","suggest","automatic"],"description":"Maestro mode — `faithful` (the author's consolidated text leaves as typed), `suggest` (a transformation is proposed and waits for the author) or `automatic` (an approved transformation may leave without review)."},"applied_mode":{"type":["string","null"],"enum":["faithful","original","candidate","candidate_unchanged","automatic","automatic_unchanged","fallback_original",null],"description":"What actually left — `faithful` (text as typed), `original` (author chose the original), `candidate` (approved suggestion), `candidate_unchanged` (approved suggestion in which Maestro changed nothing), `automatic` (automatic mode result), `automatic_unchanged` (automatic mode, Maestro changed nothing, the original left) or `fallback_original` (Maestro could not be used and the policy sent the original). Null until the batch is finalized."},"fragment_count":{"type":"integer","minimum":0,"maximum":32,"description":"Number of active fragments."},"content_bytes":{"type":"integer","minimum":0,"maximum":16384,"description":"UTF-8 size of the active text, in bytes."},"edit_lease":{"type":"object","required":["active","expires_at"],"description":"The 2-minute edit lease a pause grants to the editing tab (the token itself is never exposed here).","properties":{"active":{"type":"boolean","description":"Whether some tab currently holds the edit lease."},"expires_at":{"type":["string","null"],"format":"date-time","description":"When the last granted lease ends; null when none was granted."}}},"limits":{"type":"object","required":["max_text_characters","max_fragments","max_batch_bytes"],"description":"Text limits of the conversation's logical transport and of one batch.","properties":{"max_text_characters":{"type":["integer","null"],"description":"Character ceiling of one text message on this inbox's channel (4096 on WhatsApp Cloud), or null when the channel declares none."},"max_fragments":{"type":"integer","description":"Maximum number of active fragments in one batch (32)."},"max_batch_bytes":{"type":"integer","description":"Maximum UTF-8 size of the active text of one batch, in bytes (16384)."}}},"routing":{"type":"object","required":["mode","web_percent","reserved"],"description":"Routing policy of the conversation's hybrid pair (WhatsApp Cloud + WhatsApp Web via WazMeow).","properties":{"mode":{"type":"string","enum":["legacy","weighted"],"description":"`weighted` when the percentage routing of the pair is on for this lane; `legacy` otherwise."},"web_percent":{"type":["integer","null"],"minimum":0,"maximum":100,"description":"Share of new contacts routed to WhatsApp Web under `weighted`; null under `legacy`."},"reserved":{"type":"boolean","description":"True once a routing decision was recorded for this entry."}}},"sequence_entry":{"type":["object","null"],"description":"The batch's place in the conversation's dispatch order, or null.","required":["dispatch_id","state","blocking_reason","blocking_dispatch_id"],"properties":{"dispatch_id":{"type":"string","format":"uuid","description":"Public id of the sequence entry that owns this batch."},"state":{"type":"string","enum":["open","committed","held","settled","abandoned","canceled"],"description":"Sequence entry state — `open` (not committed yet), `committed` (its Messages exist and wait for their turn or the provider), `held` (a part needs a human disposition), then the terminal `settled` (every part accepted by the provider), `abandoned` (a human abandoned it) or `canceled` (canceled before the dispatch commitment)."},"blocking_reason":{"type":["string","null"],"enum":["predecessor_blocked","predecessor_pending",null],"description":"Why this entry still waits for an earlier entry of the conversation — `predecessor_blocked` (an earlier entry needs a human decision; new outputs are refused with `sequence_blocked`) or `predecessor_pending` (earlier entries are only in flight). Null when nothing blocks it."},"blocking_dispatch_id":{"type":["string","null"],"format":"uuid","description":"The earliest entry this one waits for, or null."}}},"content_purged":{"type":"boolean","description":"True once retention removed the batch text (digests and counters remain)."},"original_text":{"type":["string","null"],"description":"The consolidated original text as last sealed for processing; null before the first seal or once purged."},"candidate":{"type":["object","null"],"description":"The Maestro proposal waiting for the author's review, or null. Its `digest` is the value `accept_candidate` must present. Never carries prompts, grants, model output metadata or provider data.","properties":{"outcome":{"type":"string","enum":["unchanged","rewritten","structured","unavailable","requires_review"],"description":"Maestro outcome of the transformation."},"format":{"type":"string","enum":["text","buttons","list","cta","whatsapp_flow"],"description":"Output format of the candidate."},"text":{"type":["string","null"],"description":"Proposed text (the message body of a structured candidate)."},"data":{"type":"object","additionalProperties":true,"description":"Format-specific structure: `{}` for text; `buttons` (1–3 `{title, id?}`) plus optional `header`/`footer` for buttons; `sections` of rows plus optional `button` for a list; `{display_text, url}` for a call to action; `{seed?, cta?}` for a WhatsApp Flow. Button and row ids are assigned by the server."},"asset_ref":{"type":["object","null"],"description":"The pinned WhatsApp Flow mapping version of a `whatsapp_flow` candidate; null for any other format.","required":["mapping_id","mapping_version","mapping_digest"],"properties":{"mapping_id":{"type":"string","description":"Flow mapping id of the inbox policy."},"mapping_version":{"type":"integer","minimum":1,"description":"Immutable version of that mapping."},"mapping_digest":{"type":"string","pattern":"^[0-9a-f]{64}$","description":"SHA-256 digest of that mapping version."}}},"reason_codes":{"type":"array","maxItems":16,"description":"Closed-vocabulary codes Maestro reported for the proposal (lower snake case).","items":{"type":"string","pattern":"^[a-z][a-z0-9_]{0,63}$"}},"requires_review":{"type":"boolean","description":"Whether the proposal needs a human review before it can leave."},"digest":{"type":"string","pattern":"^[0-9a-f]{64}$","description":"SHA-256 digest of the candidate's final draft; send it back as `digest` in `accept_candidate`."}}},"permissions":{"type":"object","required":["edit","remove_fragment","pause","resume","flush","use_original","accept_candidate","suggest","cancel"],"description":"What the CURRENT caller may do with this batch right now, computed at read time from the author rule (content actions are the author's only; `cancel` is the author's or an inbox manager's), the batch state and the current lane configuration. Every key is false once the dispatch commitment happened or the batch is terminal.","properties":{"edit":{"type":"boolean","description":"Edit a fragment (paused batch, with the edit lease of the pausing tab)."},"remove_fragment":{"type":"boolean","description":"Remove a fragment (collecting or paused batch)."},"pause":{"type":"boolean","description":"Pause the batch to edit it."},"resume":{"type":"boolean","description":"Resume a paused batch (needs the batching module on)."},"flush":{"type":"boolean","description":"Send now, skipping only the idle wait (needs the batching module on)."},"use_original":{"type":"boolean","description":"Send the author's consolidated text now, without Maestro."},"accept_candidate":{"type":"boolean","description":"Approve the candidate waiting for review."},"suggest":{"type":"boolean","description":"Ask Maestro for a suggestion of the current revision."},"cancel":{"type":"boolean","description":"Cancel the batch (author or inbox manager)."}}}}},{"type":"object","required":["fragments"],"properties":{"fragments":{"type":"array","maxItems":32,"description":"Active fragments of the batch in ordinal order; removed fragments are tombstones and are omitted.","items":{"type":"object","required":["fragment_id","ordinal","revision","content","created_at"],"properties":{"fragment_id":{"type":"string","format":"uuid","description":"Public id of the fragment."},"ordinal":{"type":"integer","minimum":1,"description":"Position of the fragment inside the batch; stable across removals."},"revision":{"type":"integer","minimum":1,"description":"Revision of this fragment (an edit increments it)."},"content":{"type":["string","null"],"description":"The exact text the agent confirmed (byte-faithful), or null once retention purged the text."},"created_at":{"type":"string","format":"date-time","description":"When the fragment was accepted (UTC)."}}}}}}]},"example":{"schema_version":1,"batch_id":"5f0c2a8e-3b1d-4c6e-9a7f-1d2e3f4a5b60","conversation_id":1284,"inbox_id":17,"author_id":9,"state":"awaiting_review","state_reason":null,"revision":4,"server_now":"2026-09-29T14:04:02.310Z","first_at":"2026-09-29T14:03:05.100Z","last_changed_at":"2026-09-29T14:03:12.000Z","due_at":null,"hard_deadline_at":"2026-09-29T14:03:35.100Z","expires_at":"2026-09-30T14:03:12.000Z","dispatch_committed_at":null,"message_id":null,"effective_mode":"suggest","applied_mode":null,"fragment_count":2,"content_bytes":74,"edit_lease":{"active":false,"expires_at":null},"limits":{"max_text_characters":4096,"max_fragments":32,"max_batch_bytes":16384},"routing":{"mode":"weighted","web_percent":30,"reserved":false},"sequence_entry":{"dispatch_id":"7e2b9c44-1d5f-4a3e-8b6c-9d0e1f2a3b4c","state":"open","blocking_reason":null,"blocking_dispatch_id":null},"content_purged":false,"original_text":"Oi, Marina! separei as duas opções que você pediu\nas duas chegam amanhã","candidate":{"outcome":"rewritten","format":"text","text":"Oi, Marina! Separei as duas opções que você pediu.\nAs duas chegam amanhã.","data":{},"asset_ref":null,"reason_codes":["grammar_adjusted","formatting_adjusted"],"requires_review":true,"digest":"3c256ec4052923b702936f7dd31fff42a19fdc896c1c7dbbbe11ac7c679368da"},"permissions":{"edit":false,"remove_fragment":false,"pause":true,"resume":false,"flush":false,"use_original":true,"accept_candidate":true,"suggest":true,"cancel":true},"fragments":[{"fragment_id":"0b9e4c21-6a3f-4d58-8e17-2c4b6d8f0a12","ordinal":1,"revision":1,"content":"Oi, Marina! separei as duas opções que você pediu","created_at":"2026-09-29T14:03:05.100Z"},{"fragment_id":"1c8f5d32-7b40-4e69-9f28-3d5c7e9a1b23","ordinal":2,"revision":1,"content":"as duas chegam amanhã","created_at":"2026-09-29T14:03:12.000Z"}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"The batch (or fragment) does not exist in this conversation (`not_found`), or the conversation does not exist.","content":{"application/json":{"schema":{"anyOf":[{"type":"object","additionalProperties":false,"required":["error"],"description":"The batch, fragment, entry or receipt does not exist for this caller in this conversation.","properties":{"error":{"type":"string","enum":["not_found"],"description":"Stable lane code."}}},{"type":"object","additionalProperties":false,"required":["error"],"description":"Generic lookup failure of the account API (the conversation or inbox does not exist in this account).","properties":{"error":{"type":"string","description":"Human-readable lookup failure (\"Resource could not be found\")."}}}]},"example":{"error":"not_found"}}}},"403":{"description":"Policy refusal — the caller cannot see the conversation, or the action belongs to the batch/entry author (or an inbox manager for `cancel`/`abandon`). Agent bot tokens are never actors of this lane.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","enum":["forbidden"],"description":"Policy refusal."}}},"example":{"error":"forbidden"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"in":"path","name":"conversation_id","required":true,"description":"Account-scoped conversation display id.","schema":{"type":"integer"}},{"in":"path","name":"batch_id","required":true,"description":"Public batch id.","schema":{"type":"string","format":"uuid"}}]}},"/api/v1/accounts/{account_id}/whatsapp/outbound/conversations/{conversation_id}/dispatches/receipt/{request_id}":{"get":{"tags":["WhatsApp"],"operationId":"auto_get_api_v1_accounts_account_id_whatsapp_outbound_conversations_conversation_id_dispatches_receipt_request_id","summary":"Recover the receipt of one of my WhatsApp outbound dispatches","description":"Recovers the entry a lost `create` response produced, scoped to the account, the authenticated actor and this conversation (or its canonical unified conversation). 200 when its Messages exist, 202 while it has none; sends nothing.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The entry with its Messages.","content":{"application/json":{"schema":{"type":"object","description":"One entry of the conversation's human dispatch order: a text `batch` or a `dispatch_group` (one or more physical Messages). Delivery truth after `dispatched` stays with the Message and its dispatch guard.","required":["dispatch_id","conversation_id","kind","ordinal","state","state_reason","revision","author_id","blocking_reason","blocking_dispatch_id","message_ids","handoff_state","delivery","batch_id","dispatch_committed_at","created_at","updated_at","disposition","permissions"],"properties":{"dispatch_id":{"type":"string","format":"uuid","description":"Public id of the entry (the numeric id never leaves the server)."},"conversation_id":{"type":"integer","description":"Account-scoped conversation display id."},"kind":{"type":"string","enum":["batch","dispatch_group"],"description":"`batch` (a collected text batch) or `dispatch_group` (a composer output sent as one ordered group)."},"ordinal":{"type":"integer","minimum":1,"description":"Position in the conversation's dispatch order; an entry leaves only after every lower one finished."},"state":{"type":"string","enum":["open","committed","held","settled","abandoned","canceled"],"description":"Sequence entry state — `open` (not committed yet), `committed` (its Messages exist and wait for their turn or the provider), `held` (a part needs a human disposition), then the terminal `settled` (every part accepted by the provider), `abandoned` (a human abandoned it) or `canceled` (canceled before the dispatch commitment)."},"state_reason":{"type":["string","null"],"enum":["contact_replied","contact_merged","human_edit","transform_unavailable","transform_stale","transform_budget_exceeded","policy_revoked","flag_disabled","agent_profile_revoked","agent_profile_mismatch","text_limit_exceeded","transport_not_eligible","flow_candidate_stale","pacing_exhausted","predecessor_blocked","provider_rejected","dispatch_effect_unknown","window_closed","human_access_revoked","predecessor_pending",null],"description":"Closed pause/hold reason code (the dashboard translates it; the API never sends prose), or null when there is no reason to report."},"revision":{"type":"integer","minimum":1,"description":"Entry revision; send it back as `expected_revision` on a disposition."},"author_id":{"type":["integer","null"],"description":"User id of the agent who produced the entry."},"blocking_reason":{"type":["string","null"],"enum":["predecessor_blocked","predecessor_pending",null],"description":"Why this entry still waits for an earlier entry of the conversation — `predecessor_blocked` (an earlier entry needs a human decision; new outputs are refused with `sequence_blocked`) or `predecessor_pending` (earlier entries are only in flight). Null when nothing blocks it."},"blocking_dispatch_id":{"type":["string","null"],"format":"uuid","description":"The earliest entry this one waits for, or null."},"message_ids":{"type":"array","description":"Ids of the entry's Messages in part order (empty until committed).","items":{"type":"integer"}},"handoff_state":{"type":["string","null"],"enum":["held","pending","enqueued","dispatched","abandoned",null],"description":"One value for the whole entry — the least advanced part wins (held \u003e pending \u003e enqueued \u003e dispatched \u003e abandoned). Null while the entry has no Messages."},"delivery":{"type":"array","description":"The existing public dispatch-guard projection of each part, in part order.","items":{"type":"object","required":["message_id","part_position","handoff_state","state","retryable"],"properties":{"message_id":{"type":"integer","description":"The part's Message."},"part_position":{"type":"integer","minimum":0,"description":"Zero-based position of the part."},"handoff_state":{"type":"string","enum":["pending","enqueued","dispatched","held","abandoned"],"description":"Queue hand-off state of this part (the provider job is published by the relay)."},"state":{"type":["string","null"],"enum":["queued","dispatching","retry_queued","accepted","failed","unknown","sent","delivered","read",null],"description":"Public delivery state of the Message — before provider acceptance `queued`, `dispatching`, `retry_queued`, `failed` or `unknown` (effect not proven); once the provider accepted it, the Message status (`sent`, `delivered`, `read`) or `accepted`. Null when the Message is not provider-dispatchable."},"retryable":{"type":"boolean","description":"Whether the dispatch guard recorded a definitive, retryable rejection."}}}},"batch_id":{"type":["string","null"],"format":"uuid","description":"The batch of a `batch` entry; null for a `dispatch_group`."},"dispatch_committed_at":{"type":["string","null"],"format":"date-time","description":"When the entry's Messages were committed locally (not provider acceptance)."},"created_at":{"type":"string","format":"date-time","description":"When the entry was opened."},"updated_at":{"type":"string","format":"date-time","description":"Last change of the entry."},"disposition":{"type":["object","null"],"description":"The human disposition of a held entry, or null.","required":["kind","reason","actor_id","disposed_at"],"properties":{"kind":{"type":"string","enum":["released","abandoned"],"description":"`released` (the same Messages were released) or `abandoned` (nothing more is sent)."},"reason":{"type":["string","null"],"enum":["contact_replied","contact_merged","human_edit","transform_unavailable","transform_stale","transform_budget_exceeded","policy_revoked","flag_disabled","agent_profile_revoked","agent_profile_mismatch","text_limit_exceeded","transport_not_eligible","flow_candidate_stale","pacing_exhausted","predecessor_blocked","provider_rejected","dispatch_effect_unknown","window_closed","human_access_revoked","predecessor_pending",null],"description":"Closed pause/hold reason code (the dashboard translates it; the API never sends prose), or null when there is no reason to report."},"actor_id":{"type":["integer","null"],"description":"User who decided."},"disposed_at":{"type":["string","null"],"format":"date-time","description":"When the disposition was recorded."}}},"permissions":{"type":"object","required":["release_same_message","abandon"],"description":"What the CURRENT caller may do with this entry right now.","properties":{"release_same_message":{"type":"boolean","description":"Release the SAME Messages of a held entry (author only; no part may have an unproven effect and the current policy must still allow sending)."},"abandon":{"type":"boolean","description":"Abandon a held entry (author or inbox manager)."}}}}},"example":{"dispatch_id":"4d6a8b20-9c1e-4f3a-a7b5-6c8d0e2f4a61","conversation_id":1284,"kind":"dispatch_group","ordinal":3,"state":"committed","state_reason":null,"revision":2,"author_id":9,"blocking_reason":"predecessor_pending","blocking_dispatch_id":"7e2b9c44-1d5f-4a3e-8b6c-9d0e1f2a3b4c","message_ids":[90412,90413],"handoff_state":"pending","delivery":[{"message_id":90412,"part_position":0,"handoff_state":"pending","state":"queued","retryable":false},{"message_id":90413,"part_position":1,"handoff_state":"pending","state":"queued","retryable":false}],"batch_id":null,"dispatch_committed_at":"2026-09-29T14:05:40.512Z","created_at":"2026-09-29T14:05:40.498Z","updated_at":"2026-09-29T14:05:40.512Z","disposition":null,"permissions":{"release_same_message":false,"abandon":false}}}}},"401":{"description":"Unauthorized"},"404":{"description":"No entry for this actor and `request_id` in this conversation (`not_found`), or the conversation does not exist.","content":{"application/json":{"schema":{"anyOf":[{"type":"object","additionalProperties":false,"required":["error"],"description":"The batch, fragment, entry or receipt does not exist for this caller in this conversation.","properties":{"error":{"type":"string","enum":["not_found"],"description":"Stable lane code."}}},{"type":"object","additionalProperties":false,"required":["error"],"description":"Generic lookup failure of the account API (the conversation or inbox does not exist in this account).","properties":{"error":{"type":"string","description":"Human-readable lookup failure (\"Resource could not be found\")."}}}]},"example":{"error":"not_found"}}}},"202":{"description":"The entry exists but has no Messages yet.","content":{"application/json":{"schema":{"type":"object","description":"One entry of the conversation's human dispatch order: a text `batch` or a `dispatch_group` (one or more physical Messages). Delivery truth after `dispatched` stays with the Message and its dispatch guard.","required":["dispatch_id","conversation_id","kind","ordinal","state","state_reason","revision","author_id","blocking_reason","blocking_dispatch_id","message_ids","handoff_state","delivery","batch_id","dispatch_committed_at","created_at","updated_at","disposition","permissions"],"properties":{"dispatch_id":{"type":"string","format":"uuid","description":"Public id of the entry (the numeric id never leaves the server)."},"conversation_id":{"type":"integer","description":"Account-scoped conversation display id."},"kind":{"type":"string","enum":["batch","dispatch_group"],"description":"`batch` (a collected text batch) or `dispatch_group` (a composer output sent as one ordered group)."},"ordinal":{"type":"integer","minimum":1,"description":"Position in the conversation's dispatch order; an entry leaves only after every lower one finished."},"state":{"type":"string","enum":["open","committed","held","settled","abandoned","canceled"],"description":"Sequence entry state — `open` (not committed yet), `committed` (its Messages exist and wait for their turn or the provider), `held` (a part needs a human disposition), then the terminal `settled` (every part accepted by the provider), `abandoned` (a human abandoned it) or `canceled` (canceled before the dispatch commitment)."},"state_reason":{"type":["string","null"],"enum":["contact_replied","contact_merged","human_edit","transform_unavailable","transform_stale","transform_budget_exceeded","policy_revoked","flag_disabled","agent_profile_revoked","agent_profile_mismatch","text_limit_exceeded","transport_not_eligible","flow_candidate_stale","pacing_exhausted","predecessor_blocked","provider_rejected","dispatch_effect_unknown","window_closed","human_access_revoked","predecessor_pending",null],"description":"Closed pause/hold reason code (the dashboard translates it; the API never sends prose), or null when there is no reason to report."},"revision":{"type":"integer","minimum":1,"description":"Entry revision; send it back as `expected_revision` on a disposition."},"author_id":{"type":["integer","null"],"description":"User id of the agent who produced the entry."},"blocking_reason":{"type":["string","null"],"enum":["predecessor_blocked","predecessor_pending",null],"description":"Why this entry still waits for an earlier entry of the conversation — `predecessor_blocked` (an earlier entry needs a human decision; new outputs are refused with `sequence_blocked`) or `predecessor_pending` (earlier entries are only in flight). Null when nothing blocks it."},"blocking_dispatch_id":{"type":["string","null"],"format":"uuid","description":"The earliest entry this one waits for, or null."},"message_ids":{"type":"array","description":"Ids of the entry's Messages in part order (empty until committed).","items":{"type":"integer"}},"handoff_state":{"type":["string","null"],"enum":["held","pending","enqueued","dispatched","abandoned",null],"description":"One value for the whole entry — the least advanced part wins (held \u003e pending \u003e enqueued \u003e dispatched \u003e abandoned). Null while the entry has no Messages."},"delivery":{"type":"array","description":"The existing public dispatch-guard projection of each part, in part order.","items":{"type":"object","required":["message_id","part_position","handoff_state","state","retryable"],"properties":{"message_id":{"type":"integer","description":"The part's Message."},"part_position":{"type":"integer","minimum":0,"description":"Zero-based position of the part."},"handoff_state":{"type":"string","enum":["pending","enqueued","dispatched","held","abandoned"],"description":"Queue hand-off state of this part (the provider job is published by the relay)."},"state":{"type":["string","null"],"enum":["queued","dispatching","retry_queued","accepted","failed","unknown","sent","delivered","read",null],"description":"Public delivery state of the Message — before provider acceptance `queued`, `dispatching`, `retry_queued`, `failed` or `unknown` (effect not proven); once the provider accepted it, the Message status (`sent`, `delivered`, `read`) or `accepted`. Null when the Message is not provider-dispatchable."},"retryable":{"type":"boolean","description":"Whether the dispatch guard recorded a definitive, retryable rejection."}}}},"batch_id":{"type":["string","null"],"format":"uuid","description":"The batch of a `batch` entry; null for a `dispatch_group`."},"dispatch_committed_at":{"type":["string","null"],"format":"date-time","description":"When the entry's Messages were committed locally (not provider acceptance)."},"created_at":{"type":"string","format":"date-time","description":"When the entry was opened."},"updated_at":{"type":"string","format":"date-time","description":"Last change of the entry."},"disposition":{"type":["object","null"],"description":"The human disposition of a held entry, or null.","required":["kind","reason","actor_id","disposed_at"],"properties":{"kind":{"type":"string","enum":["released","abandoned"],"description":"`released` (the same Messages were released) or `abandoned` (nothing more is sent)."},"reason":{"type":["string","null"],"enum":["contact_replied","contact_merged","human_edit","transform_unavailable","transform_stale","transform_budget_exceeded","policy_revoked","flag_disabled","agent_profile_revoked","agent_profile_mismatch","text_limit_exceeded","transport_not_eligible","flow_candidate_stale","pacing_exhausted","predecessor_blocked","provider_rejected","dispatch_effect_unknown","window_closed","human_access_revoked","predecessor_pending",null],"description":"Closed pause/hold reason code (the dashboard translates it; the API never sends prose), or null when there is no reason to report."},"actor_id":{"type":["integer","null"],"description":"User who decided."},"disposed_at":{"type":["string","null"],"format":"date-time","description":"When the disposition was recorded."}}},"permissions":{"type":"object","required":["release_same_message","abandon"],"description":"What the CURRENT caller may do with this entry right now.","properties":{"release_same_message":{"type":"boolean","description":"Release the SAME Messages of a held entry (author only; no part may have an unproven effect and the current policy must still allow sending)."},"abandon":{"type":"boolean","description":"Abandon a held entry (author or inbox manager)."}}}}},"example":{"dispatch_id":"4d6a8b20-9c1e-4f3a-a7b5-6c8d0e2f4a61","conversation_id":1284,"kind":"dispatch_group","ordinal":3,"state":"committed","state_reason":null,"revision":2,"author_id":9,"blocking_reason":"predecessor_pending","blocking_dispatch_id":"7e2b9c44-1d5f-4a3e-8b6c-9d0e1f2a3b4c","message_ids":[90412,90413],"handoff_state":"pending","delivery":[{"message_id":90412,"part_position":0,"handoff_state":"pending","state":"queued","retryable":false},{"message_id":90413,"part_position":1,"handoff_state":"pending","state":"queued","retryable":false}],"batch_id":null,"dispatch_committed_at":"2026-09-29T14:05:40.512Z","created_at":"2026-09-29T14:05:40.498Z","updated_at":"2026-09-29T14:05:40.512Z","disposition":null,"permissions":{"release_same_message":false,"abandon":false}}}}},"400":{"description":"`request_id` is not a UUID.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error","errors"],"properties":{"error":{"type":"string","enum":["invalid_request"],"description":"Malformed request (400)."},"errors":{"type":"array","minItems":1,"description":"The offending request field(s), each with a stable validation code.","items":{"type":"object","additionalProperties":false,"required":["field","code"],"properties":{"field":{"type":"string","description":"Request field path, e.g. `content`, `context.in_reply_to`, `request_id`, `expected_revision`."},"code":{"type":"string","enum":["invalid_format","required","invalid_type","blank","not_allowed","unknown_field","out_of_range","not_found"],"description":"Stable validation code of that field."}}}}}},"example":{"error":"invalid_request","errors":[{"field":"request_id","code":"invalid_format"}]}}}},"403":{"description":"Policy refusal — the caller cannot see the conversation, or the action belongs to the batch/entry author (or an inbox manager for `cancel`/`abandon`). Agent bot tokens are never actors of this lane.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","enum":["forbidden"],"description":"Policy refusal."}}},"example":{"error":"forbidden"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"in":"path","name":"conversation_id","required":true,"description":"Account-scoped conversation display id.","schema":{"type":"integer"}},{"in":"path","name":"request_id","required":true,"description":"The `request_id` the dispatch was created with.","schema":{"type":"string","format":"uuid"}}]}},"/api/v1/accounts/{account_id}/whatsapp/outbound/conversations/{conversation_id}/dispatches/{dispatch_id}/actions":{"post":{"tags":["WhatsApp"],"operationId":"auto_post_api_v1_accounts_account_id_whatsapp_outbound_conversations_conversation_id_dispatches_dispatch_id_actions","summary":"Decide a held WhatsApp outbound dispatch entry","description":"The human disposition of a `held` entry. `release_same_message` (the entry's author only) releases the SAME Messages in the same order — no new Message and no new bytes — and is allowed only when no part has an unproven effect and the current policy still allows sending; an `unknown` effect is never released by choice. `abandon` (the author or an inbox manager, audited) ends the entry without sending anything more and releases its successors. Abandoning works with the module flags off. Idempotent per `request_id`; `expected_revision` guards concurrency. The body field is `action`; `action_name` is accepted as an alias.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The entry after the disposition (`committed` again when released, `abandoned` otherwise).","content":{"application/json":{"schema":{"type":"object","description":"One entry of the conversation's human dispatch order: a text `batch` or a `dispatch_group` (one or more physical Messages). Delivery truth after `dispatched` stays with the Message and its dispatch guard.","required":["dispatch_id","conversation_id","kind","ordinal","state","state_reason","revision","author_id","blocking_reason","blocking_dispatch_id","message_ids","handoff_state","delivery","batch_id","dispatch_committed_at","created_at","updated_at","disposition","permissions"],"properties":{"dispatch_id":{"type":"string","format":"uuid","description":"Public id of the entry (the numeric id never leaves the server)."},"conversation_id":{"type":"integer","description":"Account-scoped conversation display id."},"kind":{"type":"string","enum":["batch","dispatch_group"],"description":"`batch` (a collected text batch) or `dispatch_group` (a composer output sent as one ordered group)."},"ordinal":{"type":"integer","minimum":1,"description":"Position in the conversation's dispatch order; an entry leaves only after every lower one finished."},"state":{"type":"string","enum":["open","committed","held","settled","abandoned","canceled"],"description":"Sequence entry state — `open` (not committed yet), `committed` (its Messages exist and wait for their turn or the provider), `held` (a part needs a human disposition), then the terminal `settled` (every part accepted by the provider), `abandoned` (a human abandoned it) or `canceled` (canceled before the dispatch commitment)."},"state_reason":{"type":["string","null"],"enum":["contact_replied","contact_merged","human_edit","transform_unavailable","transform_stale","transform_budget_exceeded","policy_revoked","flag_disabled","agent_profile_revoked","agent_profile_mismatch","text_limit_exceeded","transport_not_eligible","flow_candidate_stale","pacing_exhausted","predecessor_blocked","provider_rejected","dispatch_effect_unknown","window_closed","human_access_revoked","predecessor_pending",null],"description":"Closed pause/hold reason code (the dashboard translates it; the API never sends prose), or null when there is no reason to report."},"revision":{"type":"integer","minimum":1,"description":"Entry revision; send it back as `expected_revision` on a disposition."},"author_id":{"type":["integer","null"],"description":"User id of the agent who produced the entry."},"blocking_reason":{"type":["string","null"],"enum":["predecessor_blocked","predecessor_pending",null],"description":"Why this entry still waits for an earlier entry of the conversation — `predecessor_blocked` (an earlier entry needs a human decision; new outputs are refused with `sequence_blocked`) or `predecessor_pending` (earlier entries are only in flight). Null when nothing blocks it."},"blocking_dispatch_id":{"type":["string","null"],"format":"uuid","description":"The earliest entry this one waits for, or null."},"message_ids":{"type":"array","description":"Ids of the entry's Messages in part order (empty until committed).","items":{"type":"integer"}},"handoff_state":{"type":["string","null"],"enum":["held","pending","enqueued","dispatched","abandoned",null],"description":"One value for the whole entry — the least advanced part wins (held \u003e pending \u003e enqueued \u003e dispatched \u003e abandoned). Null while the entry has no Messages."},"delivery":{"type":"array","description":"The existing public dispatch-guard projection of each part, in part order.","items":{"type":"object","required":["message_id","part_position","handoff_state","state","retryable"],"properties":{"message_id":{"type":"integer","description":"The part's Message."},"part_position":{"type":"integer","minimum":0,"description":"Zero-based position of the part."},"handoff_state":{"type":"string","enum":["pending","enqueued","dispatched","held","abandoned"],"description":"Queue hand-off state of this part (the provider job is published by the relay)."},"state":{"type":["string","null"],"enum":["queued","dispatching","retry_queued","accepted","failed","unknown","sent","delivered","read",null],"description":"Public delivery state of the Message — before provider acceptance `queued`, `dispatching`, `retry_queued`, `failed` or `unknown` (effect not proven); once the provider accepted it, the Message status (`sent`, `delivered`, `read`) or `accepted`. Null when the Message is not provider-dispatchable."},"retryable":{"type":"boolean","description":"Whether the dispatch guard recorded a definitive, retryable rejection."}}}},"batch_id":{"type":["string","null"],"format":"uuid","description":"The batch of a `batch` entry; null for a `dispatch_group`."},"dispatch_committed_at":{"type":["string","null"],"format":"date-time","description":"When the entry's Messages were committed locally (not provider acceptance)."},"created_at":{"type":"string","format":"date-time","description":"When the entry was opened."},"updated_at":{"type":"string","format":"date-time","description":"Last change of the entry."},"disposition":{"type":["object","null"],"description":"The human disposition of a held entry, or null.","required":["kind","reason","actor_id","disposed_at"],"properties":{"kind":{"type":"string","enum":["released","abandoned"],"description":"`released` (the same Messages were released) or `abandoned` (nothing more is sent)."},"reason":{"type":["string","null"],"enum":["contact_replied","contact_merged","human_edit","transform_unavailable","transform_stale","transform_budget_exceeded","policy_revoked","flag_disabled","agent_profile_revoked","agent_profile_mismatch","text_limit_exceeded","transport_not_eligible","flow_candidate_stale","pacing_exhausted","predecessor_blocked","provider_rejected","dispatch_effect_unknown","window_closed","human_access_revoked","predecessor_pending",null],"description":"Closed pause/hold reason code (the dashboard translates it; the API never sends prose), or null when there is no reason to report."},"actor_id":{"type":["integer","null"],"description":"User who decided."},"disposed_at":{"type":["string","null"],"format":"date-time","description":"When the disposition was recorded."}}},"permissions":{"type":"object","required":["release_same_message","abandon"],"description":"What the CURRENT caller may do with this entry right now.","properties":{"release_same_message":{"type":"boolean","description":"Release the SAME Messages of a held entry (author only; no part may have an unproven effect and the current policy must still allow sending)."},"abandon":{"type":"boolean","description":"Abandon a held entry (author or inbox manager)."}}}}},"example":{"dispatch_id":"4d6a8b20-9c1e-4f3a-a7b5-6c8d0e2f4a61","conversation_id":1284,"kind":"dispatch_group","ordinal":3,"state":"committed","state_reason":null,"revision":4,"author_id":9,"blocking_reason":null,"blocking_dispatch_id":null,"message_ids":[90412,90413],"handoff_state":"pending","delivery":[{"message_id":90412,"part_position":0,"handoff_state":"dispatched","state":"sent","retryable":false},{"message_id":90413,"part_position":1,"handoff_state":"pending","state":"retry_queued","retryable":false}],"batch_id":null,"dispatch_committed_at":"2026-09-29T14:05:40.512Z","created_at":"2026-09-29T14:05:40.498Z","updated_at":"2026-09-29T14:09:02.117Z","disposition":{"kind":"released","reason":"provider_rejected","actor_id":9,"disposed_at":"2026-09-29T14:09:02.117Z"},"permissions":{"release_same_message":false,"abandon":false}}}}},"401":{"description":"Unauthorized"},"404":{"description":"The entry does not exist in this conversation (`not_found`), or the conversation does not exist.","content":{"application/json":{"schema":{"anyOf":[{"type":"object","additionalProperties":false,"required":["error"],"description":"The batch, fragment, entry or receipt does not exist for this caller in this conversation.","properties":{"error":{"type":"string","enum":["not_found"],"description":"Stable lane code."}}},{"type":"object","additionalProperties":false,"required":["error"],"description":"Generic lookup failure of the account API (the conversation or inbox does not exist in this account).","properties":{"error":{"type":"string","description":"Human-readable lookup failure (\"Resource could not be found\")."}}}]},"example":{"error":"not_found"}}}},"400":{"description":"Malformed request — unknown `action`, `request_id` not a UUID, or `expected_revision` missing or invalid.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error","errors"],"properties":{"error":{"type":"string","enum":["invalid_request"],"description":"Malformed request (400)."},"errors":{"type":"array","minItems":1,"description":"The offending request field(s), each with a stable validation code.","items":{"type":"object","additionalProperties":false,"required":["field","code"],"properties":{"field":{"type":"string","description":"Request field path, e.g. `content`, `context.in_reply_to`, `request_id`, `expected_revision`."},"code":{"type":"string","enum":["invalid_format","required","invalid_type","blank","not_allowed","unknown_field","out_of_range","not_found"],"description":"Stable validation code of that field."}}}}}},"example":{"error":"invalid_request","errors":[{"field":"action","code":"not_allowed"}]}}}},"403":{"description":"Policy refusal — the caller cannot see the conversation, or the action belongs to the batch/entry author (or an inbox manager for `cancel`/`abandon`). Agent bot tokens are never actors of this lane.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","enum":["forbidden"],"description":"Policy refusal."}}},"example":{"error":"forbidden"}}}},"409":{"description":"`request_id_conflict` or `batch_revision_conflict` (the code also covers entry revisions).","content":{"application/json":{"schema":{"anyOf":[{"type":"object","additionalProperties":false,"required":["error"],"description":"The same `request_id` was already used by this actor for a different payload or record.","properties":{"error":{"type":"string","enum":["request_id_conflict"],"description":"Stable code."}}},{"type":"object","additionalProperties":false,"required":["error","current_revision"],"description":"`expected_revision` differs from the current revision; re-read and retry.","properties":{"error":{"type":"string","enum":["batch_revision_conflict"],"description":"Stable code (also used for sequence entries)."},"current_revision":{"type":"integer","minimum":1,"description":"The revision the record has now."}}}]},"example":{"error":"batch_revision_conflict","current_revision":4}}}},"422":{"description":"`disposition_not_allowed` — the entry is not `held` (`reason: state`), a part has an unproven effect (`dispatch_effect_unknown`), or the current policy no longer allows sending (`flag_disabled`).","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error","reason"],"properties":{"error":{"type":"string","enum":["disposition_not_allowed"],"description":"Stable code."},"reason":{"type":"string","enum":["state","dispatch_effect_unknown","flag_disabled"],"description":"Why the disposition was refused."},"state":{"type":"string","enum":["open","committed","held","settled","abandoned","canceled"],"description":"Sequence entry state — `open` (not committed yet), `committed` (its Messages exist and wait for their turn or the provider), `held` (a part needs a human disposition), then the terminal `settled` (every part accepted by the provider), `abandoned` (a human abandoned it) or `canceled` (canceled before the dispatch commitment)."}}},"example":{"error":"disposition_not_allowed","reason":"dispatch_effect_unknown","state":"held"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"in":"path","name":"conversation_id","required":true,"description":"Account-scoped conversation display id.","schema":{"type":"integer"}},{"in":"path","name":"dispatch_id","required":true,"description":"Public dispatch entry id.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"anyOf":[{"type":"object","required":["request_id","expected_revision","action"],"properties":{"request_id":{"type":"string","format":"uuid","description":"Idempotency id of this disposition."},"expected_revision":{"type":"integer","minimum":1,"description":"The entry revision last read."},"action":{"type":"string","enum":["release_same_message","abandon"],"description":"The disposition."}}},{"type":"object","required":["request_id","expected_revision","action_name"],"properties":{"request_id":{"type":"string","format":"uuid","description":"Idempotency id of this disposition."},"expected_revision":{"type":"integer","minimum":1,"description":"The entry revision last read."},"action_name":{"type":"string","enum":["release_same_message","abandon"],"description":"The disposition."}}}]},"example":{"request_id":"c3e5a7b9-4d6f-4a8c-9e0b-1a2c3d4e5f60","expected_revision":3,"action":"release_same_message"}}}}}},"/api/v1/accounts/{account_id}/whatsapp/outbound/conversations/{conversation_id}/dispatches":{"get":{"tags":["WhatsApp"],"operationId":"auto_get_api_v1_accounts_account_id_whatsapp_outbound_conversations_conversation_id_dispatches","summary":"List the WhatsApp outbound dispatch order of a conversation","description":"The conversation's dispatch entries that still matter — every non-terminal one (`open`, `committed`, `held`) plus terminal ones changed in the last 24 hours — in conversation order, with blocking predecessor, parts, hand-off state, the public delivery projection of each Message and the caller's dispositions. Works with the module flags off.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"One page of dispatch entries.","content":{"application/json":{"schema":{"type":"object","required":["payload","meta"],"properties":{"payload":{"type":"array","description":"Entries in ordinal order.","items":{"type":"object","description":"One entry of the conversation's human dispatch order: a text `batch` or a `dispatch_group` (one or more physical Messages). Delivery truth after `dispatched` stays with the Message and its dispatch guard.","required":["dispatch_id","conversation_id","kind","ordinal","state","state_reason","revision","author_id","blocking_reason","blocking_dispatch_id","message_ids","handoff_state","delivery","batch_id","dispatch_committed_at","created_at","updated_at","disposition","permissions"],"properties":{"dispatch_id":{"type":"string","format":"uuid","description":"Public id of the entry (the numeric id never leaves the server)."},"conversation_id":{"type":"integer","description":"Account-scoped conversation display id."},"kind":{"type":"string","enum":["batch","dispatch_group"],"description":"`batch` (a collected text batch) or `dispatch_group` (a composer output sent as one ordered group)."},"ordinal":{"type":"integer","minimum":1,"description":"Position in the conversation's dispatch order; an entry leaves only after every lower one finished."},"state":{"type":"string","enum":["open","committed","held","settled","abandoned","canceled"],"description":"Sequence entry state — `open` (not committed yet), `committed` (its Messages exist and wait for their turn or the provider), `held` (a part needs a human disposition), then the terminal `settled` (every part accepted by the provider), `abandoned` (a human abandoned it) or `canceled` (canceled before the dispatch commitment)."},"state_reason":{"type":["string","null"],"enum":["contact_replied","contact_merged","human_edit","transform_unavailable","transform_stale","transform_budget_exceeded","policy_revoked","flag_disabled","agent_profile_revoked","agent_profile_mismatch","text_limit_exceeded","transport_not_eligible","flow_candidate_stale","pacing_exhausted","predecessor_blocked","provider_rejected","dispatch_effect_unknown","window_closed","human_access_revoked","predecessor_pending",null],"description":"Closed pause/hold reason code (the dashboard translates it; the API never sends prose), or null when there is no reason to report."},"revision":{"type":"integer","minimum":1,"description":"Entry revision; send it back as `expected_revision` on a disposition."},"author_id":{"type":["integer","null"],"description":"User id of the agent who produced the entry."},"blocking_reason":{"type":["string","null"],"enum":["predecessor_blocked","predecessor_pending",null],"description":"Why this entry still waits for an earlier entry of the conversation — `predecessor_blocked` (an earlier entry needs a human decision; new outputs are refused with `sequence_blocked`) or `predecessor_pending` (earlier entries are only in flight). Null when nothing blocks it."},"blocking_dispatch_id":{"type":["string","null"],"format":"uuid","description":"The earliest entry this one waits for, or null."},"message_ids":{"type":"array","description":"Ids of the entry's Messages in part order (empty until committed).","items":{"type":"integer"}},"handoff_state":{"type":["string","null"],"enum":["held","pending","enqueued","dispatched","abandoned",null],"description":"One value for the whole entry — the least advanced part wins (held \u003e pending \u003e enqueued \u003e dispatched \u003e abandoned). Null while the entry has no Messages."},"delivery":{"type":"array","description":"The existing public dispatch-guard projection of each part, in part order.","items":{"type":"object","required":["message_id","part_position","handoff_state","state","retryable"],"properties":{"message_id":{"type":"integer","description":"The part's Message."},"part_position":{"type":"integer","minimum":0,"description":"Zero-based position of the part."},"handoff_state":{"type":"string","enum":["pending","enqueued","dispatched","held","abandoned"],"description":"Queue hand-off state of this part (the provider job is published by the relay)."},"state":{"type":["string","null"],"enum":["queued","dispatching","retry_queued","accepted","failed","unknown","sent","delivered","read",null],"description":"Public delivery state of the Message — before provider acceptance `queued`, `dispatching`, `retry_queued`, `failed` or `unknown` (effect not proven); once the provider accepted it, the Message status (`sent`, `delivered`, `read`) or `accepted`. Null when the Message is not provider-dispatchable."},"retryable":{"type":"boolean","description":"Whether the dispatch guard recorded a definitive, retryable rejection."}}}},"batch_id":{"type":["string","null"],"format":"uuid","description":"The batch of a `batch` entry; null for a `dispatch_group`."},"dispatch_committed_at":{"type":["string","null"],"format":"date-time","description":"When the entry's Messages were committed locally (not provider acceptance)."},"created_at":{"type":"string","format":"date-time","description":"When the entry was opened."},"updated_at":{"type":"string","format":"date-time","description":"Last change of the entry."},"disposition":{"type":["object","null"],"description":"The human disposition of a held entry, or null.","required":["kind","reason","actor_id","disposed_at"],"properties":{"kind":{"type":"string","enum":["released","abandoned"],"description":"`released` (the same Messages were released) or `abandoned` (nothing more is sent)."},"reason":{"type":["string","null"],"enum":["contact_replied","contact_merged","human_edit","transform_unavailable","transform_stale","transform_budget_exceeded","policy_revoked","flag_disabled","agent_profile_revoked","agent_profile_mismatch","text_limit_exceeded","transport_not_eligible","flow_candidate_stale","pacing_exhausted","predecessor_blocked","provider_rejected","dispatch_effect_unknown","window_closed","human_access_revoked","predecessor_pending",null],"description":"Closed pause/hold reason code (the dashboard translates it; the API never sends prose), or null when there is no reason to report."},"actor_id":{"type":["integer","null"],"description":"User who decided."},"disposed_at":{"type":["string","null"],"format":"date-time","description":"When the disposition was recorded."}}},"permissions":{"type":"object","required":["release_same_message","abandon"],"description":"What the CURRENT caller may do with this entry right now.","properties":{"release_same_message":{"type":"boolean","description":"Release the SAME Messages of a held entry (author only; no part may have an unproven effect and the current policy must still allow sending)."},"abandon":{"type":"boolean","description":"Abandon a held entry (author or inbox manager)."}}}}}},"meta":{"type":"object","required":["page","per_page","total_count","next_page"],"description":"Page-number pagination.","properties":{"page":{"type":"integer","minimum":1,"description":"Current page (1-based)."},"per_page":{"type":"integer","minimum":1,"maximum":100,"description":"Items per page."},"total_count":{"type":"integer","minimum":0,"description":"Items across all pages."},"next_page":{"type":["integer","null"],"description":"Next page number, or null on the last page."}}}}},"example":{"payload":[{"dispatch_id":"4d6a8b20-9c1e-4f3a-a7b5-6c8d0e2f4a61","conversation_id":1284,"kind":"dispatch_group","ordinal":3,"state":"committed","state_reason":null,"revision":2,"author_id":9,"blocking_reason":"predecessor_pending","blocking_dispatch_id":"7e2b9c44-1d5f-4a3e-8b6c-9d0e1f2a3b4c","message_ids":[90412,90413],"handoff_state":"pending","delivery":[{"message_id":90412,"part_position":0,"handoff_state":"pending","state":"queued","retryable":false},{"message_id":90413,"part_position":1,"handoff_state":"pending","state":"queued","retryable":false}],"batch_id":null,"dispatch_committed_at":"2026-09-29T14:05:40.512Z","created_at":"2026-09-29T14:05:40.498Z","updated_at":"2026-09-29T14:05:40.512Z","disposition":null,"permissions":{"release_same_message":false,"abandon":false}}],"meta":{"page":1,"per_page":25,"total_count":1,"next_page":null}}}}},"401":{"description":"Unauthorized"},"404":{"description":"The conversation does not exist in the account.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"description":"Generic lookup failure of the account API (the conversation or inbox does not exist in this account).","properties":{"error":{"type":"string","description":"Human-readable lookup failure (\"Resource could not be found\")."}}},"example":{"error":"Resource could not be found"}}}},"400":{"description":"`state` contains an unknown state.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error","errors"],"properties":{"error":{"type":"string","enum":["invalid_request"],"description":"Malformed request (400)."},"errors":{"type":"array","minItems":1,"description":"The offending request field(s), each with a stable validation code.","items":{"type":"object","additionalProperties":false,"required":["field","code"],"properties":{"field":{"type":"string","description":"Request field path, e.g. `content`, `context.in_reply_to`, `request_id`, `expected_revision`."},"code":{"type":"string","enum":["invalid_format","required","invalid_type","blank","not_allowed","unknown_field","out_of_range","not_found"],"description":"Stable validation code of that field."}}}}}},"example":{"error":"invalid_request","errors":[{"field":"state","code":"not_allowed"}]}}}},"403":{"description":"Policy refusal — the caller cannot see the conversation, or the action belongs to the batch/entry author (or an inbox manager for `cancel`/`abandon`). Agent bot tokens are never actors of this lane.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","enum":["forbidden"],"description":"Policy refusal."}}},"example":{"error":"forbidden"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"in":"path","name":"conversation_id","required":true,"description":"Account-scoped conversation display id.","schema":{"type":"integer"}},{"in":"query","name":"state","required":false,"description":"Comma-separated states to keep: open, committed, held, settled, abandoned, canceled.","schema":{"type":"string"},"example":"open,held"},{"in":"query","name":"page","required":false,"description":"Page number (1-based).","schema":{"type":"integer","minimum":1,"default":1}},{"in":"query","name":"per_page","required":false,"description":"Items per page (at most 100).","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}}]},"post":{"tags":["WhatsApp"],"operationId":"auto_post_api_v1_accounts_account_id_whatsapp_outbound_conversations_conversation_id_dispatches","summary":"Send a WhatsApp composer output in conversation order","description":"A human composer output that does not fit a text batch (attachments, audio, template, interactive, a manual WhatsApp Flow, another quote, transport or signature) — or every composer output when only the percentage routing is on — enters the conversation's order as ONE `dispatch_group` entry. The draft is prepared first (preflight, text ceiling; a block is 422 and nothing is created), then the entry, its Messages and their queue hand-offs are committed atomically; the provider jobs are published only when every earlier entry finished. Idempotent per actor and `request_id` with a digest of the conversation and the normalized draft: the same request returns the same entry, anything else is `request_id_conflict`. Writes follow the canonical conversation of a unified hybrid pair. Refused with `sequence_blocked` while an earlier entry needs a human decision.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The entry with its committed Messages (new or replayed).","content":{"application/json":{"schema":{"type":"object","description":"One entry of the conversation's human dispatch order: a text `batch` or a `dispatch_group` (one or more physical Messages). Delivery truth after `dispatched` stays with the Message and its dispatch guard.","required":["dispatch_id","conversation_id","kind","ordinal","state","state_reason","revision","author_id","blocking_reason","blocking_dispatch_id","message_ids","handoff_state","delivery","batch_id","dispatch_committed_at","created_at","updated_at","disposition","permissions"],"properties":{"dispatch_id":{"type":"string","format":"uuid","description":"Public id of the entry (the numeric id never leaves the server)."},"conversation_id":{"type":"integer","description":"Account-scoped conversation display id."},"kind":{"type":"string","enum":["batch","dispatch_group"],"description":"`batch` (a collected text batch) or `dispatch_group` (a composer output sent as one ordered group)."},"ordinal":{"type":"integer","minimum":1,"description":"Position in the conversation's dispatch order; an entry leaves only after every lower one finished."},"state":{"type":"string","enum":["open","committed","held","settled","abandoned","canceled"],"description":"Sequence entry state — `open` (not committed yet), `committed` (its Messages exist and wait for their turn or the provider), `held` (a part needs a human disposition), then the terminal `settled` (every part accepted by the provider), `abandoned` (a human abandoned it) or `canceled` (canceled before the dispatch commitment)."},"state_reason":{"type":["string","null"],"enum":["contact_replied","contact_merged","human_edit","transform_unavailable","transform_stale","transform_budget_exceeded","policy_revoked","flag_disabled","agent_profile_revoked","agent_profile_mismatch","text_limit_exceeded","transport_not_eligible","flow_candidate_stale","pacing_exhausted","predecessor_blocked","provider_rejected","dispatch_effect_unknown","window_closed","human_access_revoked","predecessor_pending",null],"description":"Closed pause/hold reason code (the dashboard translates it; the API never sends prose), or null when there is no reason to report."},"revision":{"type":"integer","minimum":1,"description":"Entry revision; send it back as `expected_revision` on a disposition."},"author_id":{"type":["integer","null"],"description":"User id of the agent who produced the entry."},"blocking_reason":{"type":["string","null"],"enum":["predecessor_blocked","predecessor_pending",null],"description":"Why this entry still waits for an earlier entry of the conversation — `predecessor_blocked` (an earlier entry needs a human decision; new outputs are refused with `sequence_blocked`) or `predecessor_pending` (earlier entries are only in flight). Null when nothing blocks it."},"blocking_dispatch_id":{"type":["string","null"],"format":"uuid","description":"The earliest entry this one waits for, or null."},"message_ids":{"type":"array","description":"Ids of the entry's Messages in part order (empty until committed).","items":{"type":"integer"}},"handoff_state":{"type":["string","null"],"enum":["held","pending","enqueued","dispatched","abandoned",null],"description":"One value for the whole entry — the least advanced part wins (held \u003e pending \u003e enqueued \u003e dispatched \u003e abandoned). Null while the entry has no Messages."},"delivery":{"type":"array","description":"The existing public dispatch-guard projection of each part, in part order.","items":{"type":"object","required":["message_id","part_position","handoff_state","state","retryable"],"properties":{"message_id":{"type":"integer","description":"The part's Message."},"part_position":{"type":"integer","minimum":0,"description":"Zero-based position of the part."},"handoff_state":{"type":"string","enum":["pending","enqueued","dispatched","held","abandoned"],"description":"Queue hand-off state of this part (the provider job is published by the relay)."},"state":{"type":["string","null"],"enum":["queued","dispatching","retry_queued","accepted","failed","unknown","sent","delivered","read",null],"description":"Public delivery state of the Message — before provider acceptance `queued`, `dispatching`, `retry_queued`, `failed` or `unknown` (effect not proven); once the provider accepted it, the Message status (`sent`, `delivered`, `read`) or `accepted`. Null when the Message is not provider-dispatchable."},"retryable":{"type":"boolean","description":"Whether the dispatch guard recorded a definitive, retryable rejection."}}}},"batch_id":{"type":["string","null"],"format":"uuid","description":"The batch of a `batch` entry; null for a `dispatch_group`."},"dispatch_committed_at":{"type":["string","null"],"format":"date-time","description":"When the entry's Messages were committed locally (not provider acceptance)."},"created_at":{"type":"string","format":"date-time","description":"When the entry was opened."},"updated_at":{"type":"string","format":"date-time","description":"Last change of the entry."},"disposition":{"type":["object","null"],"description":"The human disposition of a held entry, or null.","required":["kind","reason","actor_id","disposed_at"],"properties":{"kind":{"type":"string","enum":["released","abandoned"],"description":"`released` (the same Messages were released) or `abandoned` (nothing more is sent)."},"reason":{"type":["string","null"],"enum":["contact_replied","contact_merged","human_edit","transform_unavailable","transform_stale","transform_budget_exceeded","policy_revoked","flag_disabled","agent_profile_revoked","agent_profile_mismatch","text_limit_exceeded","transport_not_eligible","flow_candidate_stale","pacing_exhausted","predecessor_blocked","provider_rejected","dispatch_effect_unknown","window_closed","human_access_revoked","predecessor_pending",null],"description":"Closed pause/hold reason code (the dashboard translates it; the API never sends prose), or null when there is no reason to report."},"actor_id":{"type":["integer","null"],"description":"User who decided."},"disposed_at":{"type":["string","null"],"format":"date-time","description":"When the disposition was recorded."}}},"permissions":{"type":"object","required":["release_same_message","abandon"],"description":"What the CURRENT caller may do with this entry right now.","properties":{"release_same_message":{"type":"boolean","description":"Release the SAME Messages of a held entry (author only; no part may have an unproven effect and the current policy must still allow sending)."},"abandon":{"type":"boolean","description":"Abandon a held entry (author or inbox manager)."}}}}},"example":{"dispatch_id":"4d6a8b20-9c1e-4f3a-a7b5-6c8d0e2f4a61","conversation_id":1284,"kind":"dispatch_group","ordinal":3,"state":"committed","state_reason":null,"revision":2,"author_id":9,"blocking_reason":"predecessor_pending","blocking_dispatch_id":"7e2b9c44-1d5f-4a3e-8b6c-9d0e1f2a3b4c","message_ids":[90412,90413],"handoff_state":"pending","delivery":[{"message_id":90412,"part_position":0,"handoff_state":"pending","state":"queued","retryable":false},{"message_id":90413,"part_position":1,"handoff_state":"pending","state":"queued","retryable":false}],"batch_id":null,"dispatch_committed_at":"2026-09-29T14:05:40.512Z","created_at":"2026-09-29T14:05:40.498Z","updated_at":"2026-09-29T14:05:40.512Z","disposition":null,"permissions":{"release_same_message":false,"abandon":false}}}}},"401":{"description":"Unauthorized"},"404":{"description":"The conversation does not exist (generic lookup failure), it is not served by this lane (`inbox_not_supported`, e.g. a WhatsApp group), or neither the batching module nor the percentage routing allows sending (`feature_disabled`).","content":{"application/json":{"schema":{"anyOf":[{"type":"object","additionalProperties":false,"required":["error"],"description":"The inbox is not a WhatsApp inbox this lane serves (or the conversation is a WhatsApp group).","properties":{"error":{"type":"string","enum":["inbox_not_supported"],"description":"Stable code."}}},{"type":"object","additionalProperties":false,"required":["error","feature"],"properties":{"error":{"type":"string","enum":["feature_disabled"],"description":"Stable code."},"feature":{"type":"string","enum":["whatsapp_outbound"],"description":"The outbound lane is off for this inbox."}}},{"type":"object","additionalProperties":false,"required":["error"],"description":"Generic lookup failure of the account API (the conversation or inbox does not exist in this account).","properties":{"error":{"type":"string","description":"Human-readable lookup failure (\"Resource could not be found\")."}}}]},"example":{"error":"feature_disabled","feature":"whatsapp_outbound"}}}},"202":{"description":"The entry exists but has no Messages yet.","content":{"application/json":{"schema":{"type":"object","description":"One entry of the conversation's human dispatch order: a text `batch` or a `dispatch_group` (one or more physical Messages). Delivery truth after `dispatched` stays with the Message and its dispatch guard.","required":["dispatch_id","conversation_id","kind","ordinal","state","state_reason","revision","author_id","blocking_reason","blocking_dispatch_id","message_ids","handoff_state","delivery","batch_id","dispatch_committed_at","created_at","updated_at","disposition","permissions"],"properties":{"dispatch_id":{"type":"string","format":"uuid","description":"Public id of the entry (the numeric id never leaves the server)."},"conversation_id":{"type":"integer","description":"Account-scoped conversation display id."},"kind":{"type":"string","enum":["batch","dispatch_group"],"description":"`batch` (a collected text batch) or `dispatch_group` (a composer output sent as one ordered group)."},"ordinal":{"type":"integer","minimum":1,"description":"Position in the conversation's dispatch order; an entry leaves only after every lower one finished."},"state":{"type":"string","enum":["open","committed","held","settled","abandoned","canceled"],"description":"Sequence entry state — `open` (not committed yet), `committed` (its Messages exist and wait for their turn or the provider), `held` (a part needs a human disposition), then the terminal `settled` (every part accepted by the provider), `abandoned` (a human abandoned it) or `canceled` (canceled before the dispatch commitment)."},"state_reason":{"type":["string","null"],"enum":["contact_replied","contact_merged","human_edit","transform_unavailable","transform_stale","transform_budget_exceeded","policy_revoked","flag_disabled","agent_profile_revoked","agent_profile_mismatch","text_limit_exceeded","transport_not_eligible","flow_candidate_stale","pacing_exhausted","predecessor_blocked","provider_rejected","dispatch_effect_unknown","window_closed","human_access_revoked","predecessor_pending",null],"description":"Closed pause/hold reason code (the dashboard translates it; the API never sends prose), or null when there is no reason to report."},"revision":{"type":"integer","minimum":1,"description":"Entry revision; send it back as `expected_revision` on a disposition."},"author_id":{"type":["integer","null"],"description":"User id of the agent who produced the entry."},"blocking_reason":{"type":["string","null"],"enum":["predecessor_blocked","predecessor_pending",null],"description":"Why this entry still waits for an earlier entry of the conversation — `predecessor_blocked` (an earlier entry needs a human decision; new outputs are refused with `sequence_blocked`) or `predecessor_pending` (earlier entries are only in flight). Null when nothing blocks it."},"blocking_dispatch_id":{"type":["string","null"],"format":"uuid","description":"The earliest entry this one waits for, or null."},"message_ids":{"type":"array","description":"Ids of the entry's Messages in part order (empty until committed).","items":{"type":"integer"}},"handoff_state":{"type":["string","null"],"enum":["held","pending","enqueued","dispatched","abandoned",null],"description":"One value for the whole entry — the least advanced part wins (held \u003e pending \u003e enqueued \u003e dispatched \u003e abandoned). Null while the entry has no Messages."},"delivery":{"type":"array","description":"The existing public dispatch-guard projection of each part, in part order.","items":{"type":"object","required":["message_id","part_position","handoff_state","state","retryable"],"properties":{"message_id":{"type":"integer","description":"The part's Message."},"part_position":{"type":"integer","minimum":0,"description":"Zero-based position of the part."},"handoff_state":{"type":"string","enum":["pending","enqueued","dispatched","held","abandoned"],"description":"Queue hand-off state of this part (the provider job is published by the relay)."},"state":{"type":["string","null"],"enum":["queued","dispatching","retry_queued","accepted","failed","unknown","sent","delivered","read",null],"description":"Public delivery state of the Message — before provider acceptance `queued`, `dispatching`, `retry_queued`, `failed` or `unknown` (effect not proven); once the provider accepted it, the Message status (`sent`, `delivered`, `read`) or `accepted`. Null when the Message is not provider-dispatchable."},"retryable":{"type":"boolean","description":"Whether the dispatch guard recorded a definitive, retryable rejection."}}}},"batch_id":{"type":["string","null"],"format":"uuid","description":"The batch of a `batch` entry; null for a `dispatch_group`."},"dispatch_committed_at":{"type":["string","null"],"format":"date-time","description":"When the entry's Messages were committed locally (not provider acceptance)."},"created_at":{"type":"string","format":"date-time","description":"When the entry was opened."},"updated_at":{"type":"string","format":"date-time","description":"Last change of the entry."},"disposition":{"type":["object","null"],"description":"The human disposition of a held entry, or null.","required":["kind","reason","actor_id","disposed_at"],"properties":{"kind":{"type":"string","enum":["released","abandoned"],"description":"`released` (the same Messages were released) or `abandoned` (nothing more is sent)."},"reason":{"type":["string","null"],"enum":["contact_replied","contact_merged","human_edit","transform_unavailable","transform_stale","transform_budget_exceeded","policy_revoked","flag_disabled","agent_profile_revoked","agent_profile_mismatch","text_limit_exceeded","transport_not_eligible","flow_candidate_stale","pacing_exhausted","predecessor_blocked","provider_rejected","dispatch_effect_unknown","window_closed","human_access_revoked","predecessor_pending",null],"description":"Closed pause/hold reason code (the dashboard translates it; the API never sends prose), or null when there is no reason to report."},"actor_id":{"type":["integer","null"],"description":"User who decided."},"disposed_at":{"type":["string","null"],"format":"date-time","description":"When the disposition was recorded."}}},"permissions":{"type":"object","required":["release_same_message","abandon"],"description":"What the CURRENT caller may do with this entry right now.","properties":{"release_same_message":{"type":"boolean","description":"Release the SAME Messages of a held entry (author only; no part may have an unproven effect and the current policy must still allow sending)."},"abandon":{"type":"boolean","description":"Abandon a held entry (author or inbox manager)."}}}}},"example":{"dispatch_id":"4d6a8b20-9c1e-4f3a-a7b5-6c8d0e2f4a61","conversation_id":1284,"kind":"dispatch_group","ordinal":3,"state":"committed","state_reason":null,"revision":2,"author_id":9,"blocking_reason":"predecessor_pending","blocking_dispatch_id":"7e2b9c44-1d5f-4a3e-8b6c-9d0e1f2a3b4c","message_ids":[90412,90413],"handoff_state":"pending","delivery":[{"message_id":90412,"part_position":0,"handoff_state":"pending","state":"queued","retryable":false},{"message_id":90413,"part_position":1,"handoff_state":"pending","state":"queued","retryable":false}],"batch_id":null,"dispatch_committed_at":"2026-09-29T14:05:40.512Z","created_at":"2026-09-29T14:05:40.498Z","updated_at":"2026-09-29T14:05:40.512Z","disposition":null,"permissions":{"release_same_message":false,"abandon":false}}}}},"400":{"description":"Malformed request — `request_id` is not a UUID, `draft` is missing, or the draft breaks its closed schema (the `draft` error carries the draft validation code).","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error","errors"],"properties":{"error":{"type":"string","enum":["invalid_request"],"description":"Malformed request (400)."},"errors":{"type":"array","minItems":1,"description":"The offending field with its stable code.","items":{"type":"object","additionalProperties":false,"required":["field","code"],"properties":{"field":{"type":"string","enum":["request_id","draft"],"description":"Offending field."},"code":{"type":"string","enum":["invalid_format","required","draft_must_be_an_object","unpermitted_parameters","unsupported_version","invalid_version","invalid_delay","parts_must_be_an_array","parts_empty","too_many_parts","unknown_keys","private_message_not_schedulable","message_type_not_outgoing","parts_cannot_mix_with_flat_payload","envelope_attachments_conflict","unknown_part_keys","invalid_content_type","content_too_long","duplicate_alias","unknown_content_attributes","invalid_quoted_message_id","items_must_be_an_array","items_must_be_objects","too_many_rich_items","invalid_json","json_object_required","rich_object_required","rich_array_required","rich_payload_too_large","too_many_attachments","unknown_attachment_reference_keys","attachment_requires_active_storage_reference","invalid_whatsapp_transport","invalid_email_recipient","part_has_no_payload","multiple_quoted_parts","json_too_deep","non_finite_number","non_json_value"],"description":"Stable validation code."}}}}}},"example":{"error":"invalid_request","errors":[{"field":"draft","code":"part_has_no_payload"}]}}}},"403":{"description":"Policy refusal — the caller cannot see the conversation, or the action belongs to the batch/entry author (or an inbox manager for `cancel`/`abandon`). Agent bot tokens are never actors of this lane.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","enum":["forbidden"],"description":"Policy refusal."}}},"example":{"error":"forbidden"}}}},"409":{"description":"`request_id_conflict` (the id was used with another draft or conversation), `sequence_blocked` (resolve `blocking_dispatch_id` first) or `conversation_changed` (the conversation was merged or moved, or the entry closed during the commitment — `reason` names it when known).","content":{"application/json":{"schema":{"anyOf":[{"type":"object","additionalProperties":false,"required":["error"],"description":"The same `request_id` was already used by this actor for a different payload or record.","properties":{"error":{"type":"string","enum":["request_id_conflict"],"description":"Stable code."}}},{"type":"object","additionalProperties":false,"required":["error","blocking_dispatch_id"],"properties":{"error":{"type":"string","enum":["sequence_blocked"],"description":"Stable code."},"blocking_dispatch_id":{"type":"string","format":"uuid","description":"The earliest entry that needs a human decision."}}},{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","enum":["conversation_changed"],"description":"Stable code."},"reason":{"type":"string","enum":["author_mismatch","entry_closed"],"description":"What changed during the commitment (absent when the conversation itself changed)."}}}]},"example":{"error":"request_id_conflict"}}}},"422":{"description":"The prepared draft cannot leave — `text_limit_exceeded` (no transport of the conversation carries that length), `transport_not_eligible`, `window_closed` (the customer service window is closed for this output) or `flow_candidate_stale`. Nothing was created; the composer keeps the content.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","enum":["text_limit_exceeded","transport_not_eligible","window_closed","flow_candidate_stale"],"description":"Stable code."}}},"example":{"error":"window_closed"}}}},"429":{"description":"Local quota or backpressure: the request was NOT accepted and nothing was stored. An idempotent replay of an already recorded `client_fragment_id` / `request_id` is answered before the quota and is never limited. Keep the text on the client and retry after `retry_after` seconds with the SAME identifier.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (same value as `retry_after`).","schema":{"type":"integer","minimum":1},"example":4}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error","retry_after","scope"],"properties":{"error":{"type":"string","enum":["rate_limited"],"description":"Stable code."},"retry_after":{"type":"integer","minimum":1,"description":"Whole seconds to wait before retrying."},"scope":{"type":"string","enum":["author","account","backlog"],"description":"Which limit was hit: `author` (writes of this agent in this conversation), `account` (writes of the whole account) or `backlog` (the lane queue is behind)."}}},"example":{"error":"rate_limited","retry_after":4,"scope":"author"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"in":"path","name":"conversation_id","required":true,"description":"Account-scoped conversation display id.","schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["request_id","draft"],"properties":{"request_id":{"type":"string","format":"uuid","description":"Idempotency id of this output (UUID)."},"draft":{"type":"object","required":["parts"],"description":"A provider-neutral outbound draft (schema version 1): ordered parts, each becoming one physical Message. The schema is closed — unknown keys are refused, never dropped. Keys a part does not use are omitted in responses; on input a null value is ignored.","properties":{"schema_version":{"type":"integer","enum":[1],"description":"Draft schema version (`version` and `draft_version` are accepted aliases on input)."},"delay_ms":{"type":"integer","minimum":0,"maximum":5000,"description":"Pause between consecutive parts, in milliseconds."},"parts":{"type":"array","minItems":1,"maxItems":50,"description":"The ordered parts; at most one part may quote an earlier message.","items":{"type":"object","description":"One physical Message. It must carry content, attachments or a structured payload.","properties":{"content":{"type":["string","null"],"maxLength":150000,"description":"Message text."},"content_type":{"type":"string","enum":["text","input_select","sticker","poll"],"description":"Content type of the Message (default `text`)."},"content_attributes":{"type":"object","additionalProperties":true,"propertyNames":{"enum":["in_reply_to","in_reply_to_external_id","items","email","interactive","wa_interactive","poll","catalog_product","media_kind","view_once","mention_all","mentioned_jids","mentions","is_forwarded","link_preview","location","contact","cta_buttons"]},"description":"Outbound metadata with a closed set of root keys (`in_reply_to` is the id of a message of the same conversation; `interactive` is a WhatsApp Cloud interactive payload, `wa_interactive` a WazMeow one; `cta_buttons`, `poll`, `location`, `contact`, `catalog_product` and the others carry their existing provider payloads, revalidated before dispatch). An unknown root key is refused."},"attachments":{"type":"array","maxItems":15,"description":"Signed references of already uploaded files.","items":{"anyOf":[{"type":"object","required":["signed_id"],"properties":{"signed_id":{"type":"string","description":"Signed id of an uploaded blob (`blob_signed_id` and `blobSignedId` are accepted aliases on input)."}}},{"type":"string","description":"The signed blob id itself (accepted on input; responses always use the object form)."}]}},"items":{"type":["array","null"],"maxItems":100,"description":"Select or poll options.","items":{"type":"object","additionalProperties":true,"description":"One option object as the provider adapters consume it."}},"is_voice_message":{"type":"boolean","description":"Send the audio attachment as a voice note."},"email_html_content":{"type":["string","null"],"description":"HTML body (e-mail channels only; unused on WhatsApp)."},"to_emails":{"type":["array","null"],"description":"E-mail recipients (e-mail channels only).","items":{"type":"string","format":"email"}},"cc_emails":{"type":["array","null"],"description":"E-mail copy recipients (e-mail channels only).","items":{"type":"string","format":"email"}},"bcc_emails":{"type":["array","null"],"description":"E-mail blind-copy recipients (e-mail channels only).","items":{"type":"string","format":"email"}},"template_params":{"type":["object","null"],"additionalProperties":true,"description":"Approved WhatsApp template identity and parameters."},"flow_params":{"type":["object","null"],"additionalProperties":true,"description":"WhatsApp Flow identity and parameters."},"whatsapp_transport":{"type":["string","null"],"enum":["cloud","web","auto",null],"description":"Explicit transport of a hybrid pair — `cloud` (WhatsApp Cloud) or `web` (WhatsApp Web via WazMeow). `auto` or null lets the router decide; responses only carry `cloud` or `web`."}}}},"attachments":{"type":"array","description":"Union of the attachment references of all parts (recomputed by the server; on input it must match the parts).","items":{"anyOf":[{"type":"object","required":["signed_id"],"properties":{"signed_id":{"type":"string","description":"Signed id of an uploaded blob (`blob_signed_id` and `blobSignedId` are accepted aliases on input)."}}},{"type":"string","description":"The signed blob id itself (accepted on input; responses always use the object form)."}]}}}}}},"example":{"request_id":"c3e5a7b9-4d6f-4a8c-9e0b-1a2c3d4e5f60","draft":{"schema_version":1,"delay_ms":0,"parts":[{"content":"Oi, Marina! Separei as duas opções que você pediu.\nAs duas chegam amanhã.\n\nAna · Loja Centro","content_type":"text","content_attributes":{"in_reply_to":88213},"attachments":[],"items":null,"is_voice_message":false,"email_html_content":null,"to_emails":null,"cc_emails":null,"bcc_emails":null,"template_params":null,"flow_params":null,"whatsapp_transport":null}],"attachments":[]}}}}}}},"/api/v1/accounts/{account_id}/whatsapp/outbound/conversations/{conversation_id}/dispatches/{dispatch_id}":{"get":{"tags":["WhatsApp"],"operationId":"auto_get_api_v1_accounts_account_id_whatsapp_outbound_conversations_conversation_id_dispatches_dispatch_id","summary":"Get a WhatsApp outbound dispatch entry","description":"Snapshot of one entry of the conversation's dispatch order — state, revision, blocking predecessor, its Messages with hand-off state and the existing public delivery projection, the human disposition and what the caller may decide now.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The entry snapshot.","content":{"application/json":{"schema":{"type":"object","description":"One entry of the conversation's human dispatch order: a text `batch` or a `dispatch_group` (one or more physical Messages). Delivery truth after `dispatched` stays with the Message and its dispatch guard.","required":["dispatch_id","conversation_id","kind","ordinal","state","state_reason","revision","author_id","blocking_reason","blocking_dispatch_id","message_ids","handoff_state","delivery","batch_id","dispatch_committed_at","created_at","updated_at","disposition","permissions"],"properties":{"dispatch_id":{"type":"string","format":"uuid","description":"Public id of the entry (the numeric id never leaves the server)."},"conversation_id":{"type":"integer","description":"Account-scoped conversation display id."},"kind":{"type":"string","enum":["batch","dispatch_group"],"description":"`batch` (a collected text batch) or `dispatch_group` (a composer output sent as one ordered group)."},"ordinal":{"type":"integer","minimum":1,"description":"Position in the conversation's dispatch order; an entry leaves only after every lower one finished."},"state":{"type":"string","enum":["open","committed","held","settled","abandoned","canceled"],"description":"Sequence entry state — `open` (not committed yet), `committed` (its Messages exist and wait for their turn or the provider), `held` (a part needs a human disposition), then the terminal `settled` (every part accepted by the provider), `abandoned` (a human abandoned it) or `canceled` (canceled before the dispatch commitment)."},"state_reason":{"type":["string","null"],"enum":["contact_replied","contact_merged","human_edit","transform_unavailable","transform_stale","transform_budget_exceeded","policy_revoked","flag_disabled","agent_profile_revoked","agent_profile_mismatch","text_limit_exceeded","transport_not_eligible","flow_candidate_stale","pacing_exhausted","predecessor_blocked","provider_rejected","dispatch_effect_unknown","window_closed","human_access_revoked","predecessor_pending",null],"description":"Closed pause/hold reason code (the dashboard translates it; the API never sends prose), or null when there is no reason to report."},"revision":{"type":"integer","minimum":1,"description":"Entry revision; send it back as `expected_revision` on a disposition."},"author_id":{"type":["integer","null"],"description":"User id of the agent who produced the entry."},"blocking_reason":{"type":["string","null"],"enum":["predecessor_blocked","predecessor_pending",null],"description":"Why this entry still waits for an earlier entry of the conversation — `predecessor_blocked` (an earlier entry needs a human decision; new outputs are refused with `sequence_blocked`) or `predecessor_pending` (earlier entries are only in flight). Null when nothing blocks it."},"blocking_dispatch_id":{"type":["string","null"],"format":"uuid","description":"The earliest entry this one waits for, or null."},"message_ids":{"type":"array","description":"Ids of the entry's Messages in part order (empty until committed).","items":{"type":"integer"}},"handoff_state":{"type":["string","null"],"enum":["held","pending","enqueued","dispatched","abandoned",null],"description":"One value for the whole entry — the least advanced part wins (held \u003e pending \u003e enqueued \u003e dispatched \u003e abandoned). Null while the entry has no Messages."},"delivery":{"type":"array","description":"The existing public dispatch-guard projection of each part, in part order.","items":{"type":"object","required":["message_id","part_position","handoff_state","state","retryable"],"properties":{"message_id":{"type":"integer","description":"The part's Message."},"part_position":{"type":"integer","minimum":0,"description":"Zero-based position of the part."},"handoff_state":{"type":"string","enum":["pending","enqueued","dispatched","held","abandoned"],"description":"Queue hand-off state of this part (the provider job is published by the relay)."},"state":{"type":["string","null"],"enum":["queued","dispatching","retry_queued","accepted","failed","unknown","sent","delivered","read",null],"description":"Public delivery state of the Message — before provider acceptance `queued`, `dispatching`, `retry_queued`, `failed` or `unknown` (effect not proven); once the provider accepted it, the Message status (`sent`, `delivered`, `read`) or `accepted`. Null when the Message is not provider-dispatchable."},"retryable":{"type":"boolean","description":"Whether the dispatch guard recorded a definitive, retryable rejection."}}}},"batch_id":{"type":["string","null"],"format":"uuid","description":"The batch of a `batch` entry; null for a `dispatch_group`."},"dispatch_committed_at":{"type":["string","null"],"format":"date-time","description":"When the entry's Messages were committed locally (not provider acceptance)."},"created_at":{"type":"string","format":"date-time","description":"When the entry was opened."},"updated_at":{"type":"string","format":"date-time","description":"Last change of the entry."},"disposition":{"type":["object","null"],"description":"The human disposition of a held entry, or null.","required":["kind","reason","actor_id","disposed_at"],"properties":{"kind":{"type":"string","enum":["released","abandoned"],"description":"`released` (the same Messages were released) or `abandoned` (nothing more is sent)."},"reason":{"type":["string","null"],"enum":["contact_replied","contact_merged","human_edit","transform_unavailable","transform_stale","transform_budget_exceeded","policy_revoked","flag_disabled","agent_profile_revoked","agent_profile_mismatch","text_limit_exceeded","transport_not_eligible","flow_candidate_stale","pacing_exhausted","predecessor_blocked","provider_rejected","dispatch_effect_unknown","window_closed","human_access_revoked","predecessor_pending",null],"description":"Closed pause/hold reason code (the dashboard translates it; the API never sends prose), or null when there is no reason to report."},"actor_id":{"type":["integer","null"],"description":"User who decided."},"disposed_at":{"type":["string","null"],"format":"date-time","description":"When the disposition was recorded."}}},"permissions":{"type":"object","required":["release_same_message","abandon"],"description":"What the CURRENT caller may do with this entry right now.","properties":{"release_same_message":{"type":"boolean","description":"Release the SAME Messages of a held entry (author only; no part may have an unproven effect and the current policy must still allow sending)."},"abandon":{"type":"boolean","description":"Abandon a held entry (author or inbox manager)."}}}}},"example":{"dispatch_id":"4d6a8b20-9c1e-4f3a-a7b5-6c8d0e2f4a61","conversation_id":1284,"kind":"dispatch_group","ordinal":3,"state":"committed","state_reason":null,"revision":2,"author_id":9,"blocking_reason":"predecessor_pending","blocking_dispatch_id":"7e2b9c44-1d5f-4a3e-8b6c-9d0e1f2a3b4c","message_ids":[90412,90413],"handoff_state":"pending","delivery":[{"message_id":90412,"part_position":0,"handoff_state":"pending","state":"queued","retryable":false},{"message_id":90413,"part_position":1,"handoff_state":"pending","state":"queued","retryable":false}],"batch_id":null,"dispatch_committed_at":"2026-09-29T14:05:40.512Z","created_at":"2026-09-29T14:05:40.498Z","updated_at":"2026-09-29T14:05:40.512Z","disposition":null,"permissions":{"release_same_message":false,"abandon":false}}}}},"401":{"description":"Unauthorized"},"404":{"description":"The entry does not exist in this conversation (`not_found`), or the conversation does not exist.","content":{"application/json":{"schema":{"anyOf":[{"type":"object","additionalProperties":false,"required":["error"],"description":"The batch, fragment, entry or receipt does not exist for this caller in this conversation.","properties":{"error":{"type":"string","enum":["not_found"],"description":"Stable lane code."}}},{"type":"object","additionalProperties":false,"required":["error"],"description":"Generic lookup failure of the account API (the conversation or inbox does not exist in this account).","properties":{"error":{"type":"string","description":"Human-readable lookup failure (\"Resource could not be found\")."}}}]},"example":{"error":"not_found"}}}},"403":{"description":"Policy refusal — the caller cannot see the conversation, or the action belongs to the batch/entry author (or an inbox manager for `cancel`/`abandon`). Agent bot tokens are never actors of this lane.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","enum":["forbidden"],"description":"Policy refusal."}}},"example":{"error":"forbidden"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"in":"path","name":"conversation_id","required":true,"description":"Account-scoped conversation display id.","schema":{"type":"integer"}},{"in":"path","name":"dispatch_id","required":true,"description":"Public dispatch entry id.","schema":{"type":"string","format":"uuid"}}]}},"/api/v1/accounts/{account_id}/payments/connections/{id}/import":{"post":{"tags":["Payments"],"operationId":"auto_post_api_v1_accounts_account_id_payments_connections_id_import","summary":"Import the records the operator selected from a preview","description":"Performs the import operation on the targeted connection resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"202":{"description":"The run row, created as pending; the sweep runs asynchronously and is bounded to one per connection.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/payment_import_run"},"example":{"id":42,"connection_id":1,"resource_type":"subscription","dry_run":true,"trigger":"manual","status":"completed","window_from":"2026-07-01T00:00:00Z","window_to":"2026-07-31T23:59:59Z","error":"gateway_does_not_support_listing","started_at":"2026-01-15T10:30:00.000Z","finished_at":"2026-01-15T10:30:00.000Z","duration_seconds":37,"undone_at":"2026-01-15T10:30:00.000Z","undone_by_id":7,"undoable":true,"created_at":"2026-01-15T10:30:00.000Z","scanned":120,"truncated":false,"create":{"count":3,"amount":"2991.0","amounts":{"BRL":"2991.0"},"ids":["pay_gbfikms77ucf8on2"],"reasons":{"before_watermark":12,"ignored_by_operator":1}},"update":{"count":3,"amount":"2991.0","amounts":{"BRL":"2991.0"},"ids":["pay_gbfikms77ucf8on2"],"reasons":{"before_watermark":12,"ignored_by_operator":1}},"skip":{"count":3,"amount":"2991.0","amounts":{"BRL":"2991.0"},"ids":["pay_gbfikms77ucf8on2"],"reasons":{"before_watermark":12,"ignored_by_operator":1}},"failed_ids":[{"external_id":"pay_gbfikms77ucf8on2","error":"Validation failed: Amount is not a number"}],"failed":false,"associations":{"contact":8,"organization":2,"charge":4,"unmatched_contact":3}}}}},"422":{"description":"The selection was missing, empty or above 5,000 ids; the preview was absent, stale, from another scope or generated with different parameters; one or more selected records were not importable in the preview, or selected charges still lacked a customer; an existing local charge contact was incorrectly overridden through the import shortcut; or the requested resource/window/email combination was invalid or unsupported by the gateway.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Stable validation code for preview/customer-resolution errors, or a localized validation message for legacy input errors.","example":"unresolved_selected_customers"},"unresolved_ids":{"type":"array","description":"Selected gateway charge ids that still need an existing or proposed contact.","items":{"type":"string"},"example":["pay_gbfikms77ucf8on2"]}}},"example":{"error":"unresolved_selected_customers","unresolved_ids":["pay_gbfikms77ucf8on2"]}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"What the operator chose to let in, after reviewing the preview.","properties":{"import":{"type":"object","description":"Import parameters.","required":["only","preview_run_id"],"properties":{"resource_type":{"type":"string","enum":["charges","customers","subscriptions"],"default":"charges","example":"subscriptions"},"window_from":{"type":"string","format":"date-time","example":"2026-07-01T00:00:00Z"},"window_to":{"type":"string","format":"date-time","example":"2026-07-31T23:59:59Z"},"max_records":{"type":"integer","minimum":1,"maximum":5000,"default":500,"example":500},"email":{"type":"string","format":"email","description":"Required for Mercado Pago customer search.","example":"buyer@example.com"},"preview_run_id":{"type":"integer","minimum":1,"description":"Required for every import. It must identify a completed dry preview for this account, connection, resource type and the exact same window, limit and email scope; the server rejects a changed, foreign or incomplete preview.","example":41},"only":{"type":"array","minItems":1,"maxItems":5000,"description":"Gateway record ids the operator ticked in the completed preview. A real import without an explicit non-empty selection is rejected. A record on the resource-scoped ignore list is refused even when listed here.","items":{"type":"string"},"example":["pay_gbfikms77ucf8on2"]},"customer_resolutions":{"type":"array","description":"Manual customer decisions for selected charges that had no exact match in the preview. Each row chooses an existing account contact with contact_id or proposes a delayed contact creation. A proposed contact requires name plus at least one of email, phone/phone_number or doc/tax_id. Unselected rows are ignored.","items":{"type":"object","required":["external_id"],"properties":{"external_id":{"type":"string","description":"Exact gateway charge id from the preview.","example":"pay_gbfikms77ucf8on2"},"contact_id":{"type":"integer","minimum":1,"description":"Existing contact in this account.","example":4821},"contact":{"type":"object","description":"Contact proposed for creation only after this import is confirmed.","properties":{"name":{"type":"string","example":"Ana Silva"},"email":{"type":"string","format":"email","example":"ana@example.com"},"phone":{"type":"string","example":"+5511999999999"},"phone_number":{"type":"string","example":"+5511999999999"},"doc":{"type":"string","example":"19119119100"},"tax_id":{"type":"string","example":"19119119100"}}}}},"example":[{"external_id":"pay_gbfikms77ucf8on2","contact_id":4821},{"external_id":"pay_000012345679","contact":{"name":"Bruno Souza","email":"bruno@example.com","phone":"+5511988887777","phone_number":"+5511988887777","doc":"52998224725","tax_id":"52998224725"}}]}}}}},"example":{"import":{"resource_type":"subscriptions","window_from":"2026-07-01T00:00:00Z","window_to":"2026-07-31T23:59:59Z","max_records":500,"email":"buyer@example.com","preview_run_id":41,"only":["pay_gbfikms77ucf8on2"],"customer_resolutions":[{"external_id":"pay_gbfikms77ucf8on2","contact_id":4821,"contact":{"name":"Ana Silva","email":"ana@example.com","phone":"+5511999999999","phone_number":"+5511999999999","doc":"19119119100","tax_id":"19119119100"}},{"external_id":"pay_000012345679","contact":{"name":"Bruno Souza","email":"bruno@example.com","phone":"+5511988887777","phone_number":"+5511988887777","doc":"52998224725","tax_id":"52998224725"},"contact_id":4821}]}}}}}}},"/api/v1/accounts/{account_id}/payments/connections/{id}/import_preview":{"post":{"tags":["Payments"],"operationId":"auto_post_api_v1_accounts_account_id_payments_connections_id_import_preview","summary":"Preview what a gateway import would bring in, writing nothing","description":"Performs the import preview operation on the targeted connection resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"202":{"description":"The run row, created as pending; the sweep itself is asynchronous. Poll the run to read the buckets.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/payment_import_run"},"example":{"id":42,"connection_id":1,"resource_type":"subscription","dry_run":true,"trigger":"manual","status":"completed","window_from":"2026-07-01T00:00:00Z","window_to":"2026-07-31T23:59:59Z","error":"gateway_does_not_support_listing","started_at":"2026-01-15T10:30:00.000Z","finished_at":"2026-01-15T10:30:00.000Z","duration_seconds":37,"undone_at":"2026-01-15T10:30:00.000Z","undone_by_id":7,"undoable":true,"created_at":"2026-01-15T10:30:00.000Z","scanned":120,"truncated":false,"create":{"count":3,"amount":"2991.0","amounts":{"BRL":"2991.0"},"ids":["pay_gbfikms77ucf8on2"],"reasons":{"before_watermark":12,"ignored_by_operator":1}},"update":{"count":3,"amount":"2991.0","amounts":{"BRL":"2991.0"},"ids":["pay_gbfikms77ucf8on2"],"reasons":{"before_watermark":12,"ignored_by_operator":1}},"skip":{"count":3,"amount":"2991.0","amounts":{"BRL":"2991.0"},"ids":["pay_gbfikms77ucf8on2"],"reasons":{"before_watermark":12,"ignored_by_operator":1}},"failed_ids":[{"external_id":"pay_gbfikms77ucf8on2","error":"Validation failed: Amount is not a number"}],"failed":false,"associations":{"contact":8,"organization":2,"charge":4,"unmatched_contact":3}}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","description":"Window and bounds for the preview sweep. Nothing is written.","properties":{"import":{"type":"object","description":"Preview parameters.","properties":{"resource_type":{"type":"string","enum":["charges","customers","subscriptions"],"default":"charges","description":"Charges use gateway date filters when documented; customers and subscriptions are governed directory imports.","example":"subscriptions"},"window_from":{"type":"string","format":"date-time","description":"Start of the window. Defaults to the connection watermark (import_from).","example":"2026-07-01T00:00:00Z"},"window_to":{"type":"string","format":"date-time","description":"End of the window. Open-ended when omitted.","example":"2026-07-31T23:59:59Z"},"max_records":{"type":"integer","minimum":1,"maximum":5000,"default":500,"description":"Ceiling for this run. Capped server-side; a truncated run reports truncated=true.","example":500},"email":{"type":"string","format":"email","description":"Required for Mercado Pago customer search; ignored for other resources.","example":"buyer@example.com"}}}}},"example":{"import":{"resource_type":"subscriptions","window_from":"2026-07-01T00:00:00Z","window_to":"2026-07-31T23:59:59Z","max_records":500,"email":"buyer@example.com"}}}}}}},"/api/v1/accounts/{account_id}/payments/connections/{id}/ingestion_settings":{"patch":{"tags":["Payments"],"operationId":"auto_patch_api_v1_accounts_account_id_payments_connections_id_ingestion_settings","summary":"Ingestion settings connections","description":"Performs the ingestion settings operation on the targeted connection resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The connection with its sanitized, updated ingestion settings.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/payment_connection"},"example":{"id":1,"account_id":1,"name":"Sample Name","gateway":"asaas","environment":"sandbox","status":"pending","is_default":true,"capabilities":{},"has_api_key":true,"has_secret_key":true,"has_webhook_token":true,"last_reconciliation":{"status":"success","started_at":"2026-01-15T10:30:00.000Z","finished_at":"2026-01-15T10:30:00.000Z","processed_count":5,"failed_count":5,"failed_ids":[{"resource":"charge","external_id":"sample external id","local_id":1,"reason":"gateway_error"}]},"settings":{"orphan_adoption_policy":"disabled","import_from":"2026-07-01T00:00:00Z"},"archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","max_installments_by_type":{"credit_card":1,"boleto":1,"pix":1},"installable_billing_types":["credit_card"],"installment_cycles":{"native_installment":["monthly"],"native_recurrence_capped":["weekly"]},"plan_creation_released":{"credit_card":false,"boleto":false,"pix":false},"plan_send_released":{"credit_card":false,"boleto":false,"pix":false},"gateway_option_defaults":{},"money_unit":"major","webhook_signature_scheme":"header_token","client_certificate":{"present":true,"status":"missing","days_remaining":1,"subject":"Sample subject","issuer":"sample issuer","fingerprint":"sample fingerprint","expires_at":"2026-01-15T10:30:00.000Z"},"capabilities_v2":{"money_unit":"major","webhook_signature_scheme":"header_token","methods":{}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"422":{"description":"The policy, watermark or their combination was invalid.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","example":"Set an import watermark before enabling adoption from the watermark."}}},"example":{"error":"Set an import watermark before enabling adoption from the watermark."}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["connection"],"properties":{"connection":{"type":"object","description":"Per-connection historical-ingestion safeguards. `from_watermark` is accepted only when import_from is set; an empty import_from clears an existing watermark unless that policy would remain selected.","properties":{"orphan_adoption_policy":{"type":"string","enum":["disabled","from_watermark","all"],"description":"Whether verified gateway webhooks may create an unknown local charge.","example":"from_watermark"},"import_from":{"type":"string","description":"ISO-8601 watermark; use an empty string to clear it when the selected policy permits.","example":"2026-07-01T00:00:00Z"}}}}},"example":{"connection":{"orphan_adoption_policy":"from_watermark","import_from":"2026-07-01T00:00:00Z"}}}}}}},"/api/v1/accounts/{account_id}/payments/connections/{connection_id}/import_runs/{id}/items":{"get":{"tags":["Payments"],"operationId":"auto_get_api_v1_accounts_account_id_payments_connections_connection_id_import_runs_id_items","summary":"Browse the detailed rows captured by an import preview","description":"Returns the immutable, allowlisted rows from one account-and-connection-scoped import run. Search, filters, sorting and pagination operate on the stored preview; this endpoint never calls a gateway and never imports data. Legacy runs without detailed snapshots expose their bucket ids as minimal rows.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Filtered preview page with totals and available filter values computed from the whole run.","content":{"application/json":{"schema":{"type":"object","required":["payload","meta"],"properties":{"payload":{"type":"array","items":{"$ref":"#/components/schemas/payment_import_preview_item"}},"meta":{"type":"object","required":["count","total_count","current_page","total_pages","per_page","available_filters"],"properties":{"count":{"type":"integer","description":"Rows matching the active filters.","example":26},"total_count":{"type":"integer","description":"All rows in the run before filters.","example":120},"current_page":{"type":"integer","example":2},"total_pages":{"type":"integer","example":6},"per_page":{"type":"integer","example":25},"available_filters":{"type":"object","properties":{"buckets":{"type":"array","items":{"type":"string","enum":["create","update","skip"]},"example":["create","update","skip"]},"statuses":{"type":"array","items":{"type":"string","enum":["pending","awaiting_payment","confirmed","paid","overdue","refunded","partially_refunded","canceled","failed","active","paused","expired"]},"example":["paid","pending"]},"currencies":{"type":"array","items":{"type":"string"},"example":["BRL","USD"]},"skip_reasons":{"type":"array","items":{"type":"string","enum":["not_selected","before_watermark","ignored_by_operator","already_in_sync","already_in_sync_repaired","no_gateway_id","unmatched_contact","contact_already_linked","unknown_subscription_status","unknown_subscription_cycle","invalid_subscription_amount"]},"example":["already_in_sync"]}}}}}}},"example":{"payload":[{"external_id":"pay_000012345678","resource_type":"charge","bucket":"create","status":"paid","amount":"149.90","currency":"BRL","billing_type":"pix","cycle":"monthly","external_reference":"order_9821","occurred_at":"2026-07-30T12:00:00Z","created_at":"2026-07-28T12:00:00Z","paid_at":"2026-07-30T12:00:00Z","due_date":"2026-08-10","customer_gateway_id":"cus_000193068297","contact_id":4821,"contact_match":"gateway_customer","contact_resolution":"resolved","customer_name":"Ana Silva","customer_email":"ana@example.com","customer_phone":"+5511999999999","customer_document":"19119119100","skip_reason":"already_in_sync"}],"meta":{"count":26,"total_count":120,"current_page":2,"total_pages":6,"per_page":25,"available_filters":{"buckets":["create","update","skip"],"statuses":["paid","pending"],"currencies":["BRL","USD"],"skip_reasons":["already_in_sync"]}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"The preview run does not belong to the current account and connection."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"connection_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"q","in":"query","required":false,"description":"Case-insensitive search across gateway id, external reference and customer identity fields.","schema":{"type":"string"}},{"name":"bucket","in":"query","required":false,"schema":{"type":"string","enum":["create","update","skip"]}},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["pending","awaiting_payment","confirmed","paid","overdue","refunded","partially_refunded","canceled","failed","active","paused","expired"]}},{"name":"currency","in":"query","required":false,"schema":{"type":"string","example":"BRL"}},{"name":"skip_reason","in":"query","required":false,"schema":{"type":"string","enum":["not_selected","before_watermark","ignored_by_operator","already_in_sync","already_in_sync_repaired","no_gateway_id","unmatched_contact","contact_already_linked","unknown_subscription_status","unknown_subscription_cycle","invalid_subscription_amount"]}},{"name":"sort","in":"query","required":false,"schema":{"type":"string","enum":["occurred_at","amount","external_id","bucket","status","customer_name"],"default":"occurred_at"}},{"name":"direction","in":"query","required":false,"schema":{"type":"string","enum":["asc","desc"],"default":"desc"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1}},{"name":"per_page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":25}}]}},"/api/v1/accounts/{account_id}/payments/connections/{connection_id}/import_runs/{id}/undo":{"post":{"tags":["Payments"],"operationId":"auto_post_api_v1_accounts_account_id_payments_connections_connection_id_import_runs_id_undo","summary":"Reverse locally created records from an import run","description":"Deletes only records that this exact completed import created, without calling the gateway. The administrator must type the confirmation token. The server locks the run and refuses the whole reversal if any created charge, customer mapping, subscription, order or commerce record has later movement or changed provenance.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The run after a safe local reversal; `undone_at` and `undone_by_id` are populated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/payment_import_run"},"example":{"id":42,"connection_id":1,"resource_type":"subscription","dry_run":true,"trigger":"manual","status":"completed","window_from":"2026-07-01T00:00:00Z","window_to":"2026-07-31T23:59:59Z","error":"gateway_does_not_support_listing","started_at":"2026-01-15T10:30:00.000Z","finished_at":"2026-01-15T10:30:00.000Z","duration_seconds":37,"undone_at":"2026-01-15T10:30:00.000Z","undone_by_id":7,"undoable":true,"created_at":"2026-01-15T10:30:00.000Z","scanned":120,"truncated":false,"create":{"count":3,"amount":"2991.0","amounts":{"BRL":"2991.0"},"ids":["pay_gbfikms77ucf8on2"],"reasons":{"before_watermark":12,"ignored_by_operator":1}},"update":{"count":3,"amount":"2991.0","amounts":{"BRL":"2991.0"},"ids":["pay_gbfikms77ucf8on2"],"reasons":{"before_watermark":12,"ignored_by_operator":1}},"skip":{"count":3,"amount":"2991.0","amounts":{"BRL":"2991.0"},"ids":["pay_gbfikms77ucf8on2"],"reasons":{"before_watermark":12,"ignored_by_operator":1}},"failed_ids":[{"external_id":"pay_gbfikms77ucf8on2","error":"Validation failed: Amount is not a number"}],"failed":false,"associations":{"contact":8,"organization":2,"charge":4,"unmatched_contact":3}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"422":{"description":"Confirmation was absent, or the import is not safely reversible. No records are changed.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","example":"This import can no longer be reversed safely (charge_moved_after_import). No records were changed."}}},"example":{"error":"This import can no longer be reversed safely (charge_moved_after_import). No records were changed."}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"connection_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["confirmation"],"properties":{"confirmation":{"type":"string","enum":["undo"],"description":"Literal confirmation token required for this destructive local reversal."}}},"example":{"confirmation":"undo"}}}}}},"/api/v1/accounts/{account_id}/payments/connections/{connection_id}/import_runs":{"get":{"tags":["Payments"],"operationId":"auto_get_api_v1_accounts_account_id_payments_connections_connection_id_import_runs","summary":"List the import runs recorded for a connection","description":"Returns the list of import runs visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Import runs for this connection, newest first.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"$ref":"#/components/schemas/payment_import_run"}},"meta":{"type":"object","description":"Pagination envelope.","properties":{"count":{"type":"integer","description":"Total runs for this connection.","example":12},"current_page":{"type":"integer","example":1}}}}},"example":{"payload":[{"id":42,"connection_id":1,"resource_type":"subscription","dry_run":true,"trigger":"manual","status":"completed","window_from":"2026-07-01T00:00:00Z","window_to":"2026-07-31T23:59:59Z","error":"gateway_does_not_support_listing","started_at":"2026-01-15T10:30:00.000Z","finished_at":"2026-01-15T10:30:00.000Z","duration_seconds":37,"undone_at":"2026-01-15T10:30:00.000Z","undone_by_id":7,"undoable":true,"created_at":"2026-01-15T10:30:00.000Z","scanned":120,"truncated":false,"create":{"count":3,"amount":"2991.0","amounts":{"BRL":"2991.0"},"ids":["pay_gbfikms77ucf8on2"],"reasons":{"before_watermark":12,"ignored_by_operator":1}},"update":{"count":3,"amount":"2991.0","amounts":{"BRL":"2991.0"},"ids":["pay_gbfikms77ucf8on2"],"reasons":{"before_watermark":12,"ignored_by_operator":1}},"skip":{"count":3,"amount":"2991.0","amounts":{"BRL":"2991.0"},"ids":["pay_gbfikms77ucf8on2"],"reasons":{"before_watermark":12,"ignored_by_operator":1}},"failed_ids":[{"external_id":"pay_gbfikms77ucf8on2","error":"Validation failed: Amount is not a number"}],"failed":false,"associations":{"contact":8,"organization":2,"charge":4,"unmatched_contact":3}}],"meta":{"count":12,"current_page":1}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"connection_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."}]}},"/api/v1/accounts/{account_id}/payments/connections/{connection_id}/import_runs/{id}":{"get":{"tags":["Payments"],"operationId":"auto_get_api_v1_accounts_account_id_payments_connections_connection_id_import_runs_id","summary":"Get one import run with its counters and outcome","description":"Returns the import run identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"One import run, including the per-record failures.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/payment_import_run"},"example":{"id":42,"connection_id":1,"resource_type":"subscription","dry_run":true,"trigger":"manual","status":"completed","window_from":"2026-07-01T00:00:00Z","window_to":"2026-07-31T23:59:59Z","error":"gateway_does_not_support_listing","started_at":"2026-01-15T10:30:00.000Z","finished_at":"2026-01-15T10:30:00.000Z","duration_seconds":37,"undone_at":"2026-01-15T10:30:00.000Z","undone_by_id":7,"undoable":true,"created_at":"2026-01-15T10:30:00.000Z","scanned":120,"truncated":false,"create":{"count":3,"amount":"2991.0","amounts":{"BRL":"2991.0"},"ids":["pay_gbfikms77ucf8on2"],"reasons":{"before_watermark":12,"ignored_by_operator":1}},"update":{"count":3,"amount":"2991.0","amounts":{"BRL":"2991.0"},"ids":["pay_gbfikms77ucf8on2"],"reasons":{"before_watermark":12,"ignored_by_operator":1}},"skip":{"count":3,"amount":"2991.0","amounts":{"BRL":"2991.0"},"ids":["pay_gbfikms77ucf8on2"],"reasons":{"before_watermark":12,"ignored_by_operator":1}},"failed_ids":[{"external_id":"pay_gbfikms77ucf8on2","error":"Validation failed: Amount is not a number"}],"failed":false,"associations":{"contact":8,"organization":2,"charge":4,"unmatched_contact":3}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"connection_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/payments/ignored_externals":{"get":{"tags":["Payments"],"operationId":"auto_get_api_v1_accounts_account_id_payments_ignored_externals","summary":"List durable gateway exclusions","description":"Lists connection-scoped durable exclusions and matching legacy gateway-wide fallbacks. Administrators use this list to explicitly allow a record again. Resource type keeps charge, customer and subscription identities independent.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Paginated durable exclusions, newest first.","content":{"application/json":{"schema":{"type":"object","required":["payload","meta"],"properties":{"payload":{"type":"array","items":{"$ref":"#/components/schemas/payment_ignored_external"}},"meta":{"type":"object","properties":{"count":{"type":"integer","example":2},"current_page":{"type":"integer","example":1}}}}},"example":{"payload":[{"id":51,"connection_id":9,"gateway":"asaas","resource_type":"charge","external_id":"pay_000012345678","reason":"Not a sale for this account.","created_by_id":7,"import_run_id":1,"created_at":"2026-01-15T10:30:00.000Z"}],"meta":{"count":2,"current_page":1}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1}},{"name":"per_page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"gateway","in":"query","required":false,"description":"Restrict exclusions to the selected connection gateway.","schema":{"type":"string","enum":["asaas","mercado_pago"]}},{"name":"connection_id","in":"query","required":false,"description":"Return this connection's exclusions plus matching legacy gateway-wide fallbacks.","schema":{"type":"integer","minimum":1}},{"name":"resource_type","in":"query","required":false,"description":"Restrict exclusions to the resource currently being previewed.","schema":{"type":"string","enum":["charge","customer","subscription"]}}]},"post":{"tags":["Payments"],"operationId":"auto_post_api_v1_accounts_account_id_payments_ignored_externals","summary":"Permanently exclude one gateway record","description":"Creates or returns an idempotent exclusion for one connection-owned gateway record. It immediately applies to future imports and webhook adoption; it does not delete a charge already stored locally.","security":[{"userApiKey":[]}],"responses":{"201":{"description":"Newly created exclusion, or the existing row for an idempotent repeat.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/payment_ignored_external"},"example":{"id":51,"connection_id":9,"gateway":"asaas","resource_type":"charge","external_id":"pay_000012345678","reason":"Not a sale for this account.","created_by_id":7,"import_run_id":1,"created_at":"2026-01-15T10:30:00.000Z"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["ignored_external"],"properties":{"ignored_external":{"type":"object","required":["connection_id","gateway","external_id"],"properties":{"connection_id":{"type":"integer","minimum":1,"example":9},"gateway":{"type":"string","enum":["asaas","mercado_pago"],"example":"asaas"},"resource_type":{"type":"string","enum":["charge","customer","subscription"],"default":"charge","example":"subscription"},"external_id":{"type":"string","example":"pay_000012345678"},"reason":{"type":["string","null"],"example":"Not a sale for this account."}}}}},"example":{"ignored_external":{"connection_id":9,"gateway":"asaas","resource_type":"charge","external_id":"pay_000012345678","reason":"Not a sale for this account."}}}}}}},"/api/v1/accounts/{account_id}/payments/ignored_externals/{id}":{"delete":{"tags":["Payments"],"operationId":"auto_delete_api_v1_accounts_account_id_payments_ignored_externals_id","summary":"Allow a previously excluded gateway record again","description":"Removes one durable exclusion. The record may be considered again only on a later import or a new verified webhook; this endpoint never creates or imports it immediately.","security":[{"userApiKey":[]}],"responses":{"204":{"description":"Exclusion removed; no content."},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/payments/charges/{id}/mark_as_paid":{"post":{"tags":["Payments"],"operationId":"auto_post_api_v1_accounts_account_id_payments_charges_id_mark_as_paid","summary":"Mark as paid charges","description":"Performs the mark as paid operation on the targeted charge resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"payments_connection_id":{"type":"integer"},"contact_id":{"type":"integer"},"organization_id":{"type":"integer"},"organization_name":{"type":["string","null"]},"conversation_id":{"type":"integer"},"crm_item_id":{"type":"integer"},"crm_item_title":{"type":["string","null"]},"payments_subscription_id":{"type":"integer"},"gateway_charge_id":{"type":"integer"},"external_reference":{"type":"string"},"billing_type":{"type":"string","enum":["pix","boleto","credit_card","hosted_link","undefined","debit_card"],"description":"How the payer is charged. `undefined` lets the payer pick on the hosted invoice."},"status":{"type":"string","enum":["pending","awaiting_payment","confirmed","paid","overdue","refunded","partially_refunded","canceled","failed"]},"amount":{"type":"number"},"amount_refunded":{"type":"string"},"subtotal_amount":{"type":"number"},"discount":{"type":"string"},"discount_type":{"type":"string","enum":["fixed","percent"],"description":"Whether the discount is an absolute amount or a percentage."},"discount_reason":{"type":"string"},"currency":{"type":"string"},"original_amount":{"type":"number"},"original_currency":{"type":"string"},"fx_rate":{"type":"number"},"installments":{"type":"string"},"installment_mode":{"type":"string","enum":["absorb","passthrough"]},"installment_interest_rate":{"type":["number","null"]},"due_date":{"type":"string","format":"date"},"paid_at":{"type":"string","format":"date-time"},"refunded_at":{"type":"string","format":"date-time"},"description":{"type":"string"},"hosted_url":{"type":"string"},"pix_payload":{"type":"string"},"pix_qr_base64":{"type":"string"},"boleto_url":{"type":"string"},"metadata":{"type":"object","additionalProperties":true,"description":"Free-form metadata bag; the key set depends on the record and context."},"gateway_options":{"type":["string","null"]},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"settled":{"type":"boolean"},"archived_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"contact_name":{"type":"string"},"contact_email":{"type":"string","format":"email"},"payer_email":{"type":"string","format":"email"},"contact_phone_number":{"type":"string"},"gateway_customer_id":{"type":"integer"},"gateway":{"type":["string","null"]},"can_mark_as_paid":{"type":["boolean","null"]},"manually_paid":{"type":["string","null"]},"conversation_display_id":{"type":["integer","null"]},"line_items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"catalog_variant_id":{"type":"integer"},"catalog_product_id":{"type":"integer"},"name_snapshot":{"type":"string"},"quantity":{"type":"string"},"unit_price":{"type":"number"},"discount":{"type":"string"},"discount_type":{"type":"string","enum":["fixed","percent"],"description":"Whether the discount is an absolute amount or a percentage."},"line_total":{"type":"number"},"currency":{"type":"string"},"position":{"type":"integer"},"metadata":{"type":"object","additionalProperties":true,"description":"Free-form metadata bag; the key set depends on the record and context."}}}},"installment_plan_id":{"type":"integer"},"installment_number":{"type":"string"},"installments_count":{"type":["integer","null"]},"installment_plan":{"type":"object","properties":{"extract":{"type":"string"},"open_installments_count":{"type":"integer"},"notification_preferences":{"type":"string"},"gateway":{"type":["string","null"]},"conversation_display_id":{"type":["integer","null"]},"contact_name":{"type":"string"},"next_due_date":{"type":["string","null"],"format":"date"},"projected_schedule":{"type":"string"},"materialized_installment_numbers":{"type":"array","items":{"type":"string"}},"payment_book_degraded":{"type":"boolean"},"payment_book":{"type":"object","properties":{"state":{"type":"string"},"degraded":{"type":"boolean"},"stale":{"type":"boolean"},"refresh_failed":{"type":"boolean"},"stalled":{"type":"string"},"url":{"type":"string"}}},"financial_evidence":{"type":"object","properties":{"set":{"type":"string"}}},"gateway_payment_book":{"type":"object","properties":{"url":{"type":"string"}}},"allowed_actions":{"type":"object","properties":{"update_notification_preferences":{"type":"string"},"payment_book":{"type":"string"},"send_to_conversation":{"type":"string"},"send_installment":{"type":"string"},"update":{"type":"boolean"},"cancel":{"type":"string"},"destroy":{"type":"boolean"},"refund":{"type":"string"}}}}},"can_undo_mark_as_paid":{"type":["boolean","null"]},"can_refund":{"type":["boolean","null"]}}}}},"example":{"payload":{"id":1,"account_id":1,"payments_connection_id":1,"contact_id":1,"organization_id":1,"organization_name":"sample organization name","conversation_id":1,"crm_item_id":1,"crm_item_title":"sample crm item title","payments_subscription_id":1,"gateway_charge_id":1,"external_reference":"sample external reference","billing_type":"pix","status":"pending","amount":149.9,"amount_refunded":"sample amount refunded","subtotal_amount":149.9,"discount":"sample discount","discount_type":"fixed","discount_reason":"sample discount reason","currency":"BRL","original_amount":149.9,"original_currency":"sample original currency","fx_rate":12.5,"installments":"sample installments","installment_mode":"absorb","installment_interest_rate":12.5,"due_date":"2026-01-15","paid_at":"2026-01-15T10:30:00.000Z","refunded_at":"2026-01-15T10:30:00.000Z","description":"A short description.","hosted_url":"https://example.com/resource","pix_payload":"sample pix payload","pix_qr_base64":"sample pix qr base64","boleto_url":"https://example.com/resource","metadata":{},"gateway_options":"sample gateway options","custom_attributes":{},"settled":true,"archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","contact_name":"sample contact name","contact_email":"agent@example.com","payer_email":"agent@example.com","contact_phone_number":"+5511999998888","gateway_customer_id":1,"gateway":"sample gateway","can_mark_as_paid":true,"manually_paid":"sample manually paid","conversation_display_id":1,"line_items":[{"id":1,"catalog_variant_id":1,"catalog_product_id":1,"name_snapshot":"sample name snapshot","quantity":"sample quantity","unit_price":149.9,"discount":"sample discount","discount_type":"fixed","line_total":149.9,"currency":"BRL","position":1,"metadata":{}}],"installment_plan_id":1,"installment_number":"sample installment number","installments_count":5,"installment_plan":{"extract":"sample extract","open_installments_count":5,"notification_preferences":"sample notification preferences","gateway":"sample gateway","conversation_display_id":1,"contact_name":"sample contact name","next_due_date":"2026-01-15","projected_schedule":"sample projected schedule","materialized_installment_numbers":["sample materialized installment number"],"payment_book_degraded":true,"payment_book":{"state":"active","degraded":true,"stale":true,"refresh_failed":true,"stalled":"sample stalled","url":"https://example.com/resource"},"financial_evidence":{"set":"sample set"},"gateway_payment_book":{"url":"https://example.com/resource"},"allowed_actions":{"update_notification_preferences":"sample update notification preferences","payment_book":"sample payment book","send_to_conversation":"sample send to conversation","send_installment":"sample send installment","update":true,"cancel":"sample cancel","destroy":true,"refund":"sample refund"}},"can_undo_mark_as_paid":true,"can_refund":true}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string"}}},"example":{"reason":"Sample reason."}}}}}},"/api/v1/accounts/{account_id}/payments/charges/{id}/undo_mark_as_paid":{"post":{"tags":["Payments"],"operationId":"auto_post_api_v1_accounts_account_id_payments_charges_id_undo_mark_as_paid","summary":"Undo mark as paid charges","description":"Performs the undo mark as paid operation on the targeted charge resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"payments_connection_id":{"type":"integer"},"contact_id":{"type":"integer"},"organization_id":{"type":"integer"},"organization_name":{"type":["string","null"]},"conversation_id":{"type":"integer"},"crm_item_id":{"type":"integer"},"crm_item_title":{"type":["string","null"]},"payments_subscription_id":{"type":"integer"},"gateway_charge_id":{"type":"integer"},"external_reference":{"type":"string"},"billing_type":{"type":"string","enum":["pix","boleto","credit_card","hosted_link","undefined","debit_card"],"description":"How the payer is charged. `undefined` lets the payer pick on the hosted invoice."},"status":{"type":"string","enum":["pending","awaiting_payment","confirmed","paid","overdue","refunded","partially_refunded","canceled","failed"]},"amount":{"type":"number"},"amount_refunded":{"type":"string"},"subtotal_amount":{"type":"number"},"discount":{"type":"string"},"discount_type":{"type":"string","enum":["fixed","percent"],"description":"Whether the discount is an absolute amount or a percentage."},"discount_reason":{"type":"string"},"currency":{"type":"string"},"original_amount":{"type":"number"},"original_currency":{"type":"string"},"fx_rate":{"type":"number"},"installments":{"type":"string"},"installment_mode":{"type":"string","enum":["absorb","passthrough"]},"installment_interest_rate":{"type":["number","null"]},"due_date":{"type":"string","format":"date"},"paid_at":{"type":"string","format":"date-time"},"refunded_at":{"type":"string","format":"date-time"},"description":{"type":"string"},"hosted_url":{"type":"string"},"pix_payload":{"type":"string"},"pix_qr_base64":{"type":"string"},"boleto_url":{"type":"string"},"metadata":{"type":"object","additionalProperties":true,"description":"Free-form metadata bag; the key set depends on the record and context."},"gateway_options":{"type":["string","null"]},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"settled":{"type":"boolean"},"archived_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"contact_name":{"type":"string"},"contact_email":{"type":"string","format":"email"},"payer_email":{"type":"string","format":"email"},"contact_phone_number":{"type":"string"},"gateway_customer_id":{"type":"integer"},"gateway":{"type":["string","null"]},"can_mark_as_paid":{"type":["boolean","null"]},"manually_paid":{"type":["string","null"]},"conversation_display_id":{"type":["integer","null"]},"line_items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"catalog_variant_id":{"type":"integer"},"catalog_product_id":{"type":"integer"},"name_snapshot":{"type":"string"},"quantity":{"type":"string"},"unit_price":{"type":"number"},"discount":{"type":"string"},"discount_type":{"type":"string","enum":["fixed","percent"],"description":"Whether the discount is an absolute amount or a percentage."},"line_total":{"type":"number"},"currency":{"type":"string"},"position":{"type":"integer"},"metadata":{"type":"object","additionalProperties":true,"description":"Free-form metadata bag; the key set depends on the record and context."}}}},"installment_plan_id":{"type":"integer"},"installment_number":{"type":"string"},"installments_count":{"type":["integer","null"]},"installment_plan":{"type":"object","properties":{"extract":{"type":"string"},"open_installments_count":{"type":"integer"},"notification_preferences":{"type":"string"},"gateway":{"type":["string","null"]},"conversation_display_id":{"type":["integer","null"]},"contact_name":{"type":"string"},"next_due_date":{"type":["string","null"],"format":"date"},"projected_schedule":{"type":"string"},"materialized_installment_numbers":{"type":"array","items":{"type":"string"}},"payment_book_degraded":{"type":"boolean"},"payment_book":{"type":"object","properties":{"state":{"type":"string"},"degraded":{"type":"boolean"},"stale":{"type":"boolean"},"refresh_failed":{"type":"boolean"},"stalled":{"type":"string"},"url":{"type":"string"}}},"financial_evidence":{"type":"object","properties":{"set":{"type":"string"}}},"gateway_payment_book":{"type":"object","properties":{"url":{"type":"string"}}},"allowed_actions":{"type":"object","properties":{"update_notification_preferences":{"type":"string"},"payment_book":{"type":"string"},"send_to_conversation":{"type":"string"},"send_installment":{"type":"string"},"update":{"type":"boolean"},"cancel":{"type":"string"},"destroy":{"type":"boolean"},"refund":{"type":"string"}}}}},"can_undo_mark_as_paid":{"type":["boolean","null"]},"can_refund":{"type":["boolean","null"]}}}}},"example":{"payload":{"id":1,"account_id":1,"payments_connection_id":1,"contact_id":1,"organization_id":1,"organization_name":"sample organization name","conversation_id":1,"crm_item_id":1,"crm_item_title":"sample crm item title","payments_subscription_id":1,"gateway_charge_id":1,"external_reference":"sample external reference","billing_type":"pix","status":"pending","amount":149.9,"amount_refunded":"sample amount refunded","subtotal_amount":149.9,"discount":"sample discount","discount_type":"fixed","discount_reason":"sample discount reason","currency":"BRL","original_amount":149.9,"original_currency":"sample original currency","fx_rate":12.5,"installments":"sample installments","installment_mode":"absorb","installment_interest_rate":12.5,"due_date":"2026-01-15","paid_at":"2026-01-15T10:30:00.000Z","refunded_at":"2026-01-15T10:30:00.000Z","description":"A short description.","hosted_url":"https://example.com/resource","pix_payload":"sample pix payload","pix_qr_base64":"sample pix qr base64","boleto_url":"https://example.com/resource","metadata":{},"gateway_options":"sample gateway options","custom_attributes":{},"settled":true,"archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","contact_name":"sample contact name","contact_email":"agent@example.com","payer_email":"agent@example.com","contact_phone_number":"+5511999998888","gateway_customer_id":1,"gateway":"sample gateway","can_mark_as_paid":true,"manually_paid":"sample manually paid","conversation_display_id":1,"line_items":[{"id":1,"catalog_variant_id":1,"catalog_product_id":1,"name_snapshot":"sample name snapshot","quantity":"sample quantity","unit_price":149.9,"discount":"sample discount","discount_type":"fixed","line_total":149.9,"currency":"BRL","position":1,"metadata":{}}],"installment_plan_id":1,"installment_number":"sample installment number","installments_count":5,"installment_plan":{"extract":"sample extract","open_installments_count":5,"notification_preferences":"sample notification preferences","gateway":"sample gateway","conversation_display_id":1,"contact_name":"sample contact name","next_due_date":"2026-01-15","projected_schedule":"sample projected schedule","materialized_installment_numbers":["sample materialized installment number"],"payment_book_degraded":true,"payment_book":{"state":"active","degraded":true,"stale":true,"refresh_failed":true,"stalled":"sample stalled","url":"https://example.com/resource"},"financial_evidence":{"set":"sample set"},"gateway_payment_book":{"url":"https://example.com/resource"},"allowed_actions":{"update_notification_preferences":"sample update notification preferences","payment_book":"sample payment book","send_to_conversation":"sample send to conversation","send_installment":"sample send installment","update":true,"cancel":"sample cancel","destroy":true,"refund":"sample refund"}},"can_undo_mark_as_paid":true,"can_refund":true}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string"}}},"example":{"reason":"Sample reason."}}}}}},"/api/v1/accounts/{account_id}/payments/charges/bulk_mark_as_paid":{"post":{"tags":["Payments"],"operationId":"auto_post_api_v1_accounts_account_id_payments_charges_bulk_mark_as_paid","summary":"Mark selected open charges as manually paid","description":"Administrator-only, best-effort operation. Every eligible charge is settled through its provider capability, audited with the same required justification, and projected into its linked CRM order. Ineligible or unavailable records are returned in failed_ids.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Best-effort result with every requested identifier accounted for.","content":{"application/json":{"schema":{"type":"object","required":["succeeded_ids","failed_ids"],"properties":{"succeeded_ids":{"type":"array","items":{"type":"integer"}},"failed_ids":{"type":"array","items":{"type":"integer"}}}},"example":{"succeeded_ids":[1],"failed_ids":[1]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"422":{"description":"Missing or invalid identifiers, batch above 500 records, or invalid justification."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["charge_ids","reason"],"properties":{"charge_ids":{"type":"array","minItems":1,"maxItems":500,"items":{"type":"integer","minimum":1}},"reason":{"type":"string","minLength":1,"maxLength":1000}}},"example":{"charge_ids":[41,42],"reason":"Bank deposits matched to the selected invoices."}}}}}},"/api/v1/accounts/{account_id}/payments/charges/bulk_cancel":{"post":{"tags":["Payments"],"operationId":"auto_post_api_v1_accounts_account_id_payments_charges_bulk_cancel","summary":"Bulk cancel charges","description":"Performs the bulk cancel operation on the targeted charge resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"succeeded_ids":{"type":"array","items":{"type":"integer"}},"failed_ids":{"type":"array","items":{"type":"integer"}}}},"example":{"succeeded_ids":[1],"failed_ids":[1]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string"},"charge_ids":{"type":"array","items":{"type":"integer"}}}},"example":{"reason":"Sample reason.","charge_ids":[1]}}}}}},"/api/v1/accounts/{account_id}/payments/charges/bulk_refund":{"post":{"tags":["Payments"],"operationId":"auto_post_api_v1_accounts_account_id_payments_charges_bulk_refund","summary":"Bulk refund charges","description":"Performs the bulk refund operation on the targeted charge resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"succeeded_ids":{"type":"array","items":{"type":"integer"}},"failed_ids":{"type":"array","items":{"type":"integer"}}}},"example":{"succeeded_ids":[1],"failed_ids":[1]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string"},"charge_ids":{"type":"array","items":{"type":"integer"}}}},"example":{"reason":"Sample reason.","charge_ids":[1]}}}}}},"/api/v1/accounts/{account_id}/payments/subscriptions/{id}/repair":{"post":{"tags":["Payments"],"operationId":"auto_post_api_v1_accounts_account_id_payments_subscriptions_id_repair","summary":"Repair subscriptions","description":"Performs the repair operation on the targeted subscription resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"payments_connection_id":{"type":"integer"},"contact_id":{"type":"integer"},"organization_id":{"type":"integer"},"organization_name":{"type":["string","null"]},"conversation_id":{"type":"integer"},"conversation_display_id":{"type":["integer","null"]},"payments_plan_id":{"type":"integer"},"gateway_subscription_id":{"type":"integer"},"status":{"type":"string","enum":["active","paused","overdue","canceled","expired","pending"]},"cycle":{"type":"string","enum":["weekly","biweekly","monthly","quarterly","semiannually","yearly","bimonthly"]},"billing_type":{"type":"string","enum":["pix","boleto","credit_card","hosted_link","undefined","debit_card"],"description":"How the payer is charged. `undefined` lets the payer pick on the hosted invoice."},"amount":{"type":"number"},"subtotal_amount":{"type":"number"},"discount":{"type":"string"},"discount_type":{"type":"string","enum":["fixed","percent"],"description":"Whether the discount is an absolute amount or a percentage."},"discount_reason":{"type":"string"},"currency":{"type":"string"},"next_due_date":{"type":"string","format":"date"},"max_payments":{"type":"string"},"end_date":{"type":"string","format":"date"},"started_at":{"type":"string","format":"date-time"},"canceled_at":{"type":"string","format":"date-time"},"metadata":{"type":"object","additionalProperties":true,"description":"Free-form metadata bag; the key set depends on the record and context."},"gateway_options":{"type":["string","null"]},"archived_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"contact_name":{"type":"string"},"contact_email":{"type":"string","format":"email"},"payer_email":{"type":"string","format":"email"},"contact_phone_number":{"type":"string"},"gateway":{"type":["string","null"],"enum":["asaas","mercado_pago",null],"description":"Native payment gateway of the required connection that owns this plan or subscription."},"capabilities":{"type":["string","null"]},"plan_name":{"type":["string","null"]},"link_state":{"type":"string","enum":["linked","unlinked"],"description":"Whether the subscription resolves to a Contact. `linked` carries one; `unlinked` does not, and is kept visible on purpose so an unmatched payer can be reconciled later instead of disappearing. The list filter and the badge read this key; `association_status` is the same truth in the older matched/unmatched spelling."},"association_status":{"type":"string","enum":["matched","unmatched"],"description":"Whether the subscription resolves to a Contact. `matched` carries one; `unmatched` does not, because no gateway customer, e-mail, phone or document matched exactly when the subscription was imported or adopted. Always one of the two: it is derived from the current link, so a manually-created subscription and a row that predates the key both answer correctly. This is the long-standing spelling of the same truth as `link_state`."}}}}},"example":{"payload":{"id":1,"account_id":1,"payments_connection_id":1,"contact_id":1,"organization_id":1,"organization_name":"sample organization name","conversation_id":1,"conversation_display_id":1,"payments_plan_id":1,"gateway_subscription_id":1,"status":"active","cycle":"weekly","billing_type":"pix","amount":149.9,"subtotal_amount":149.9,"discount":"sample discount","discount_type":"fixed","discount_reason":"sample discount reason","currency":"BRL","next_due_date":"2026-01-15","max_payments":"sample max payments","end_date":"2026-01-15","started_at":"2026-01-15T10:30:00.000Z","canceled_at":"2026-01-15T10:30:00.000Z","metadata":{},"gateway_options":"sample gateway options","archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","contact_name":"sample contact name","contact_email":"agent@example.com","payer_email":"agent@example.com","contact_phone_number":"+5511999998888","gateway":"asaas","capabilities":"sample capabilities","plan_name":"sample plan name","link_state":"linked","association_status":"matched"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"subscription":{"type":"object","properties":{"contact_id":{"type":"integer"},"organization_id":{"type":"integer"},"payments_plan_id":{"type":"integer"},"rebind":{"type":"string"},"contact":{"type":"object","additionalProperties":true,"description":"Free-form object."}}}},"required":["subscription"]},"example":{"subscription":{"contact_id":1,"organization_id":1,"payments_plan_id":1,"rebind":"sample rebind","contact":{}}}}}}}},"/api/v1/accounts/{account_id}/payments/subscriptions/bulk_archive":{"post":{"tags":["Payments"],"operationId":"auto_post_api_v1_accounts_account_id_payments_subscriptions_bulk_archive","summary":"Bulk archive subscriptions","description":"Performs the bulk archive operation on the targeted subscription resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"archived_ids":{"type":"array","items":{"type":"integer"}}}},"meta":{"type":"object","properties":{"archived":{"type":"integer"},"failed":{"type":"integer"},"failed_ids":{"type":"array","items":{"type":"integer"}}}}}},"example":{"payload":{"archived_ids":[1]},"meta":{"archived":1,"failed":1,"failed_ids":[1]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"subscription_ids":{"type":"array","items":{"type":"integer"}}}},"example":{"subscription_ids":[1]}}}}}},"/api/v1/accounts/{account_id}/payments/subscriptions/bulk_restore":{"post":{"tags":["Payments"],"operationId":"auto_post_api_v1_accounts_account_id_payments_subscriptions_bulk_restore","summary":"Bulk restore subscriptions","description":"Performs the bulk restore operation on the targeted subscription resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"restored_ids":{"type":"array","items":{"type":"integer"}}}},"meta":{"type":"object","properties":{"restored":{"type":"integer"},"failed":{"type":"integer"},"failed_ids":{"type":"array","items":{"type":"integer"}}}}}},"example":{"payload":{"restored_ids":[1]},"meta":{"restored":1,"failed":1,"failed_ids":[1]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"subscription_ids":{"type":"array","items":{"type":"integer"}}}},"example":{"subscription_ids":[1]}}}}}},"/api/v1/accounts/{account_id}/payments/subscriptions/bulk_destroy":{"post":{"tags":["Payments"],"operationId":"auto_post_api_v1_accounts_account_id_payments_subscriptions_bulk_destroy","summary":"Bulk destroy subscriptions","description":"Performs the bulk destroy operation on the targeted subscription resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"destroyed_ids":{"type":"array","items":{"type":"integer"}},"failed_ids":{"type":"array","items":{"type":"integer"}}}},"meta":{"type":"object","properties":{"destroyed":{"type":"integer"},"failed":{"type":"integer"},"failed_ids":{"type":"array","items":{"type":"integer"}}}}}},"example":{"payload":{"destroyed_ids":[1],"failed_ids":[1]},"meta":{"destroyed":1,"failed":1,"failed_ids":[1]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"subscription_ids":{"type":"array","items":{"type":"integer"}}}},"example":{"subscription_ids":[1]}}}}}},"/api/v1/accounts/{account_id}/payments/plans/bulk_archive":{"post":{"tags":["Payment Plans"],"operationId":"auto_post_api_v1_accounts_account_id_payments_plans_bulk_archive","summary":"Archive payment plans in bulk","description":"Performs the bulk archive operation on the targeted plan resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Per-record archive result.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"archived_ids":{"type":"array","items":{"type":"integer"},"example":[41]},"failed_ids":{"type":"array","items":{"type":"integer"},"example":[42]},"failures":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","example":42},"error":{"type":"string","example":"Record could not be archived."}}}}}}}},"example":{"payload":{"archived_ids":[41],"failed_ids":[42],"failures":[{"id":42,"error":"Record could not be archived."}]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"plan_ids":{"type":"array","items":{"type":"integer"},"example":[41,42]}},"required":["plan_ids"]},"example":{"plan_ids":[41,42]}}}}}},"/api/v1/accounts/{account_id}/payments/plans/bulk_restore":{"post":{"tags":["Payment Plans"],"operationId":"auto_post_api_v1_accounts_account_id_payments_plans_bulk_restore","summary":"Restore payment plans in bulk","description":"Performs the bulk restore operation on the targeted plan resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Per-record restore result.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"restored_ids":{"type":"array","items":{"type":"integer"},"example":[41]},"failed_ids":{"type":"array","items":{"type":"integer"},"example":[42]},"failures":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","example":42},"error":{"type":"string","example":"Record could not be restored."}}}}}}}},"example":{"payload":{"restored_ids":[41],"failed_ids":[42],"failures":[{"id":42,"error":"Record could not be restored."}]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"plan_ids":{"type":"array","items":{"type":"integer"},"example":[41,42]}},"required":["plan_ids"]},"example":{"plan_ids":[41,42]}}}}}},"/api/v1/accounts/{account_id}/payments/plans/bulk_destroy":{"post":{"tags":["Payment Plans"],"operationId":"auto_post_api_v1_accounts_account_id_payments_plans_bulk_destroy","summary":"Permanently delete archived payment plans in bulk","description":"Performs the bulk destroy operation on the targeted plan resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Per-record permanent-delete result.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"destroyed_ids":{"type":"array","items":{"type":"integer"},"example":[41]},"failed_ids":{"type":"array","items":{"type":"integer"},"example":[42]},"failures":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","example":42},"error":{"type":"string","example":"Archive the plan before deleting it permanently."}}}}}}}},"example":{"payload":{"destroyed_ids":[41],"failed_ids":[42],"failures":[{"id":42,"error":"Archive the plan before deleting it permanently."}]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"plan_ids":{"type":"array","items":{"type":"integer"},"example":[41,42]}},"required":["plan_ids"]},"example":{"plan_ids":[41,42]}}}}}},"/api/v1/accounts/{account_id}/payments/offers/{id}/accept":{"post":{"tags":["Payment Offers"],"operationId":"auto_post_api_v1_accounts_account_id_payments_offers_id_accept","summary":"Accept an active upsell or downsell once","description":"Requires an idempotency key. Replays with the same contact, offer and material payment data return the same charge; archived, inactive and order-bump offers are rejected.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The newly minted charge for the accepted offer.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer","example":701},"account_id":{"type":"integer","example":1},"payments_connection_id":{"type":["integer","null"],"example":5},"contact_id":{"type":"integer","example":55},"organization_id":{"type":["integer","null"],"example":27},"organization_name":{"type":["string","null"],"example":"Example Company"},"conversation_id":{"type":["integer","null"],"example":900},"crm_item_id":{"type":["integer","null"],"example":null},"payments_subscription_id":{"type":["integer","null"],"example":null},"gateway_charge_id":{"type":["string","null"],"example":"pay_080225913252"},"external_reference":{"type":["string","null"],"example":"701"},"billing_type":{"type":"string","enum":["pix","boleto","credit_card","hosted_link","undefined","debit_card"],"example":"pix","description":"How the payer is charged. `undefined` lets the payer pick on the hosted invoice."},"status":{"type":"string","enum":["pending","awaiting_payment","confirmed","paid","overdue","refunded","partially_refunded","canceled","failed"],"example":"pending"},"amount":{"type":"number","description":"Gateway net (subtotal_amount − discount), MAJOR units","example":49.9},"amount_refunded":{"type":"number","example":0.0},"subtotal_amount":{"type":["number","null"],"example":49.9},"discount":{"type":["number","null"],"example":0.0},"discount_type":{"type":["string","null"],"enum":["fixed","percent",null],"example":null,"description":"Whether the discount is an absolute amount or a percentage."},"discount_reason":{"type":["string","null"],"example":null},"currency":{"type":"string","example":"BRL"},"original_amount":{"type":["number","null"],"description":"Pre-FX amount (nil for same-currency).","example":null},"original_currency":{"type":["string","null"],"example":null},"fx_rate":{"type":["number","null"],"example":null},"installments":{"type":["integer","null"],"example":1},"due_date":{"type":["string","null"],"format":"date","example":"2026-01-22"},"paid_at":{"type":["string","null"],"format":"date-time","example":null},"refunded_at":{"type":["string","null"],"format":"date-time","example":null},"description":{"type":["string","null"],"example":"Oferta - Upsell Plano Pro"},"hosted_url":{"type":["string","null"],"example":"https://checkout.example.com/pay/701"},"pix_payload":{"type":["string","null"],"description":"PIX copia-e-cola.","example":"00020126...5204000053039865802BR"},"pix_qr_base64":{"type":["string","null"],"description":"Base64 PNG of the PIX QR.","example":"iVBORw0KGgoAAAANSUhEUg=="},"boleto_url":{"type":["string","null"],"example":null},"metadata":{"type":"object","additionalProperties":true,"description":"Free-form metadata carried on the offer / line item."},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"settled":{"type":"boolean","example":false},"archived_at":{"type":["string","null"],"format":"date-time","example":null},"created_at":{"type":"string","format":"date-time","example":"2026-01-15T10:30:00.000Z"},"updated_at":{"type":"string","format":"date-time","example":"2026-01-15T10:30:00.000Z"},"contact_name":{"type":["string","null"],"example":"João da Silva"},"gateway":{"type":["string","null"],"description":"Immutable source namespace stored on the charge; may be an external source without a native connection.","example":"asaas"},"can_mark_as_paid":{"type":"boolean","description":"True only for gateways exposing a manual-settle API (Asaas receiveInCash).","example":true},"manually_paid":{"type":"boolean","example":false},"conversation_display_id":{"type":["integer","null"],"example":42},"line_items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","example":9001},"catalog_variant_id":{"type":["integer","null"],"example":null},"catalog_product_id":{"type":["integer","null"],"example":88},"name_snapshot":{"type":"string","example":"Upsell Plano Pro"},"quantity":{"type":"number","example":1},"unit_price":{"type":"number","example":49.9},"discount":{"type":["number","null"],"example":0.0},"discount_type":{"type":["string","null"],"enum":["fixed","percent",null],"example":null,"description":"Whether the discount is an absolute amount or a percentage."},"line_total":{"type":"number","example":49.9},"currency":{"type":"string","example":"BRL"},"position":{"type":"integer","example":0},"metadata":{"type":"object","additionalProperties":true,"description":"Free-form metadata carried on the offer / line item."}}}}}}}},"example":{"payload":{"id":701,"account_id":1,"payments_connection_id":5,"contact_id":55,"organization_id":27,"organization_name":"Example Company","conversation_id":900,"crm_item_id":null,"payments_subscription_id":null,"gateway_charge_id":"pay_080225913252","external_reference":"701","billing_type":"pix","status":"pending","amount":49.9,"amount_refunded":0.0,"subtotal_amount":49.9,"discount":0.0,"discount_type":null,"discount_reason":null,"currency":"BRL","original_amount":null,"original_currency":null,"fx_rate":null,"installments":1,"due_date":"2026-01-22","paid_at":null,"refunded_at":null,"description":"Oferta - Upsell Plano Pro","hosted_url":"https://checkout.example.com/pay/701","pix_payload":"00020126...5204000053039865802BR","pix_qr_base64":"iVBORw0KGgoAAAANSUhEUg==","boleto_url":null,"metadata":{},"custom_attributes":{},"settled":false,"archived_at":null,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","contact_name":"João da Silva","gateway":"asaas","can_mark_as_paid":true,"manually_paid":false,"conversation_display_id":42,"line_items":[{"id":9001,"catalog_variant_id":null,"catalog_product_id":88,"name_snapshot":"Upsell Plano Pro","quantity":1,"unit_price":49.9,"discount":0.0,"discount_type":null,"line_total":49.9,"currency":"BRL","position":0,"metadata":{}}]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"422":{"description":"Missing/reused idempotency key, unavailable offer, order-bump kind, invalid payer data or gateway failure."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"X-Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Conventional alternative to the required body idempotency_key (at most 255 UTF-8 bytes; no control characters)."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["contact_id"],"properties":{"contact_id":{"type":"integer","minimum":1},"organization_id":{"type":["integer","null"],"minimum":1,"description":"Explicit company payer from this account. The contact must belong to it; missing company fiscal fields are rejected without contact fallback."},"conversation_id":{"type":["integer","null"],"minimum":1},"idempotency_key":{"type":"string","minLength":1,"maxLength":255,"description":"Required when X-Idempotency-Key is absent; at most 255 UTF-8 bytes and no control characters."}}},"example":{"contact_id":1,"organization_id":1,"conversation_id":1,"idempotency_key":"sample-token"}}}}}},"/api/v1/accounts/{account_id}/payments/offers/{id}/archive":{"post":{"tags":["Payment Offers"],"operationId":"auto_post_api_v1_accounts_account_id_payments_offers_id_archive","summary":"Archive and deactivate an offer","description":"Performs the archive operation on the targeted offer resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Success (no content)"},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/payments/offers/{id}/restore":{"post":{"tags":["Payment Offers"],"operationId":"auto_post_api_v1_accounts_account_id_payments_offers_id_restore","summary":"Restore an offer as inactive","description":"Performs the restore operation on the targeted offer resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The restored, inactive offer.","content":{"application/json":{"schema":{"type":"object","required":["payload"],"properties":{"payload":{"$ref":"#/components/schemas/payment_offer"}}},"example":{"payload":{"id":44,"account_id":1,"name":"Priority onboarding","kind":"upsell","amount":49.9,"currency":"BRL","billing_type":"pix","connection_id":5,"catalog_product_id":88,"description":"Add priority onboarding to this purchase.","active":true,"settings":{},"archived_at":null,"created_at":"2026-08-05T12:00:00Z","updated_at":"2026-08-05T12:00:00Z","gateway":"asaas","connection_name":"Main Asaas","capabilities":{},"catalog_product_name":"Pro plan"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/payments/offers/{id}/purge":{"delete":{"tags":["Payment Offers"],"operationId":"auto_delete_api_v1_accounts_account_id_payments_offers_id_purge","summary":"Permanently delete an archived offer","description":"Performs the purge operation on the targeted offer resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Success (no content)"},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"422":{"description":"The offer must be archived before permanent deletion."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/payments/offers/bulk_archive":{"post":{"tags":["Payment Offers"],"operationId":"auto_post_api_v1_accounts_account_id_payments_offers_bulk_archive","summary":"Archive offers in bulk","description":"Performs the bulk archive operation on the targeted offer resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Per-record archive result.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"archived_ids":{"type":"array","items":{"type":"integer"},"example":[51]},"failed_ids":{"type":"array","items":{"type":"integer"},"example":[52]},"failures":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","example":52},"error":{"type":"string","example":"Record could not be archived."}}}}}}}},"example":{"payload":{"archived_ids":[51],"failed_ids":[52],"failures":[{"id":52,"error":"Record could not be archived."}]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"offer_ids":{"type":"array","items":{"type":"integer"},"example":[51,52]}},"required":["offer_ids"]},"example":{"offer_ids":[51,52]}}}}}},"/api/v1/accounts/{account_id}/payments/offers/bulk_restore":{"post":{"tags":["Payment Offers"],"operationId":"auto_post_api_v1_accounts_account_id_payments_offers_bulk_restore","summary":"Restore offers in bulk","description":"Performs the bulk restore operation on the targeted offer resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Per-record restore result.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"restored_ids":{"type":"array","items":{"type":"integer"},"example":[51]},"failed_ids":{"type":"array","items":{"type":"integer"},"example":[52]},"failures":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","example":52},"error":{"type":"string","example":"Record could not be restored."}}}}}}}},"example":{"payload":{"restored_ids":[51],"failed_ids":[52],"failures":[{"id":52,"error":"Record could not be restored."}]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"offer_ids":{"type":"array","items":{"type":"integer"},"example":[51,52]}},"required":["offer_ids"]},"example":{"offer_ids":[51,52]}}}}}},"/api/v1/accounts/{account_id}/payments/offers/bulk_destroy":{"post":{"tags":["Payment Offers"],"operationId":"auto_post_api_v1_accounts_account_id_payments_offers_bulk_destroy","summary":"Permanently delete archived offers in bulk","description":"Performs the bulk destroy operation on the targeted offer resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Per-record permanent-delete result.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"destroyed_ids":{"type":"array","items":{"type":"integer"},"example":[51]},"failed_ids":{"type":"array","items":{"type":"integer"},"example":[52]},"failures":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","example":52},"error":{"type":"string","example":"Archive the offer before deleting it permanently."}}}}}}}},"example":{"payload":{"destroyed_ids":[51],"failed_ids":[52],"failures":[{"id":52,"error":"Archive the offer before deleting it permanently."}]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"offer_ids":{"type":"array","items":{"type":"integer"},"example":[51,52]}},"required":["offer_ids"]},"example":{"offer_ids":[51,52]}}}}}},"/api/v1/accounts/{account_id}/payments/offers":{"get":{"tags":["Payment Offers"],"operationId":"auto_get_api_v1_accounts_account_id_payments_offers","summary":"List the administrative offer catalog","description":"Lists active or archived offers with server-side search, kind/status/connection/product filters, ordering and real pagination.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"A truthful server-paginated page of account-scoped offers.","content":{"application/json":{"schema":{"type":"object","required":["payload","meta"],"properties":{"payload":{"type":"array","items":{"$ref":"#/components/schemas/payment_offer"}},"meta":{"type":"object","required":["count","current_page","total_pages","per_page","has_more"],"properties":{"count":{"type":"integer","example":31},"current_page":{"type":"integer","example":1},"total_pages":{"type":"integer","example":2},"per_page":{"type":"integer","example":25},"has_more":{"type":"boolean","example":true}}}}},"example":{"payload":[{"id":44,"account_id":1,"name":"Priority onboarding","kind":"upsell","amount":49.9,"currency":"BRL","billing_type":"pix","connection_id":5,"catalog_product_id":88,"description":"Add priority onboarding to this purchase.","active":true,"settings":{},"archived_at":null,"created_at":"2026-08-05T12:00:00Z","updated_at":"2026-08-05T12:00:00Z","gateway":"asaas","connection_name":"Main Asaas","capabilities":{},"catalog_product_name":"Pro plan"}],"meta":{"count":31,"current_page":1,"total_pages":2,"per_page":25,"has_more":true}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"q","in":"query","required":false,"schema":{"type":"string"}},{"name":"archived","in":"query","required":false,"schema":{"type":"boolean","default":false}},{"name":"kind","in":"query","required":false,"description":"Restrict to one offer kind.","schema":{"type":"string","enum":["order_bump","upsell","downsell"]},"example":"order_bump"},{"name":"active","in":"query","required":false,"schema":{"type":"boolean"}},{"name":"connection_id","in":"query","required":false,"schema":{"type":"integer","minimum":1}},{"name":"catalog_product_id","in":"query","required":false,"schema":{"type":"integer","minimum":1}},{"name":"sort","in":"query","required":false,"schema":{"type":"string","enum":["created_at","name","amount","kind","active"],"default":"created_at"}},{"name":"direction","in":"query","required":false,"schema":{"type":"string","enum":["asc","desc"],"default":"desc"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1}},{"name":"per_page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":25}}]},"post":{"tags":["Payment Offers"],"operationId":"auto_post_api_v1_accounts_account_id_payments_offers","summary":"Create an administrative offer","description":"Creates a priced order bump, upsell or downsell. Account-scoped connection and product references are validated before persistence.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The created offer.","content":{"application/json":{"schema":{"type":"object","required":["payload"],"properties":{"payload":{"$ref":"#/components/schemas/payment_offer"}}},"example":{"payload":{"id":44,"account_id":1,"name":"Priority onboarding","kind":"upsell","amount":49.9,"currency":"BRL","billing_type":"pix","connection_id":5,"catalog_product_id":88,"description":"Add priority onboarding to this purchase.","active":true,"settings":{},"archived_at":null,"created_at":"2026-08-05T12:00:00Z","updated_at":"2026-08-05T12:00:00Z","gateway":"asaas","connection_name":"Main Asaas","capabilities":{},"catalog_product_name":"Pro plan"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"422":{"description":"Invalid price, method, capability or account-scoped reference."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["offer"],"properties":{"offer":{"type":"object","required":["name","kind","amount","currency","billing_type"],"properties":{"name":{"type":"string","example":"Priority onboarding"},"kind":{"type":"string","enum":["order_bump","upsell","downsell"]},"amount":{"type":"number","exclusiveMinimum":0,"example":49.9},"currency":{"type":"string","minLength":3,"maxLength":3,"example":"BRL"},"billing_type":{"type":"string","enum":["pix","boleto","credit_card","hosted_link","debit_card"],"description":"How the payer is charged. `undefined` lets the payer pick on the hosted invoice."},"connection_id":{"type":["integer","null"],"minimum":1},"catalog_product_id":{"type":["integer","null"],"minimum":1},"description":{"type":["string","null"]},"active":{"type":"boolean","default":true},"settings":{"type":"object","additionalProperties":true,"description":"Free-form JSON persisted with the offer for checkout and funnel integrations. This API does not define or interpret individual settings keys."}}}}},"example":{"offer":{"name":"Priority onboarding","kind":"order_bump","amount":49.9,"currency":"BRL","billing_type":"pix","connection_id":1,"catalog_product_id":1,"description":"A short description.","active":true,"settings":{}}}}}}}},"/api/v1/accounts/{account_id}/payments/offers/{id}":{"get":{"tags":["Payment Offers"],"operationId":"auto_get_api_v1_accounts_account_id_payments_offers_id","summary":"Get an administrative offer","description":"Returns the offer identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The account-scoped offer.","content":{"application/json":{"schema":{"type":"object","required":["payload"],"properties":{"payload":{"$ref":"#/components/schemas/payment_offer"}}},"example":{"payload":{"id":44,"account_id":1,"name":"Priority onboarding","kind":"upsell","amount":49.9,"currency":"BRL","billing_type":"pix","connection_id":5,"catalog_product_id":88,"description":"Add priority onboarding to this purchase.","active":true,"settings":{},"archived_at":null,"created_at":"2026-08-05T12:00:00Z","updated_at":"2026-08-05T12:00:00Z","gateway":"asaas","connection_name":"Main Asaas","capabilities":{},"catalog_product_name":"Pro plan"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]},"patch":{"tags":["Payment Offers"],"operationId":"auto_patch_api_v1_accounts_account_id_payments_offers_id","summary":"Update an administrative offer","description":"Updates the offer identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The updated offer.","content":{"application/json":{"schema":{"type":"object","required":["payload"],"properties":{"payload":{"$ref":"#/components/schemas/payment_offer"}}},"example":{"payload":{"id":44,"account_id":1,"name":"Priority onboarding","kind":"upsell","amount":49.9,"currency":"BRL","billing_type":"pix","connection_id":5,"catalog_product_id":88,"description":"Add priority onboarding to this purchase.","active":true,"settings":{},"archived_at":null,"created_at":"2026-08-05T12:00:00Z","updated_at":"2026-08-05T12:00:00Z","gateway":"asaas","connection_name":"Main Asaas","capabilities":{},"catalog_product_name":"Pro plan"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"422":{"description":"Invalid price, method, capability or account-scoped reference."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["offer"],"properties":{"offer":{"type":"object","properties":{"name":{"type":"string"},"kind":{"type":"string","enum":["order_bump","upsell","downsell"]},"amount":{"type":"number","exclusiveMinimum":0},"currency":{"type":"string","minLength":3,"maxLength":3},"billing_type":{"type":"string","enum":["pix","boleto","credit_card","hosted_link","debit_card"],"description":"How the payer is charged. `undefined` lets the payer pick on the hosted invoice."},"connection_id":{"type":["integer","null"],"minimum":1},"catalog_product_id":{"type":["integer","null"],"minimum":1},"description":{"type":["string","null"]},"active":{"type":"boolean"},"settings":{"type":"object","additionalProperties":true,"description":"Free-form JSON persisted with the offer for checkout and funnel integrations. This API does not define or interpret individual settings keys."}}}}},"example":{"offer":{"name":"Sample Name","kind":"order_bump","amount":149.9,"currency":"BRL","billing_type":"pix","connection_id":1,"catalog_product_id":1,"description":"A short description.","active":true,"settings":{}}}}}}},"put":{"tags":["Payment Offers"],"operationId":"auto_put_api_v1_accounts_account_id_payments_offers_id","summary":"Update an administrative offer","description":"Updates the offer identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The updated offer.","content":{"application/json":{"schema":{"type":"object","required":["payload"],"properties":{"payload":{"$ref":"#/components/schemas/payment_offer"}}},"example":{"payload":{"id":44,"account_id":1,"name":"Priority onboarding","kind":"upsell","amount":49.9,"currency":"BRL","billing_type":"pix","connection_id":5,"catalog_product_id":88,"description":"Add priority onboarding to this purchase.","active":true,"settings":{},"archived_at":null,"created_at":"2026-08-05T12:00:00Z","updated_at":"2026-08-05T12:00:00Z","gateway":"asaas","connection_name":"Main Asaas","capabilities":{},"catalog_product_name":"Pro plan"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"422":{"description":"Invalid price, method, capability or account-scoped reference."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["offer"],"properties":{"offer":{"type":"object","properties":{"name":{"type":"string"},"kind":{"type":"string","enum":["order_bump","upsell","downsell"]},"amount":{"type":"number","exclusiveMinimum":0},"currency":{"type":"string","minLength":3,"maxLength":3},"billing_type":{"type":"string","enum":["pix","boleto","credit_card","hosted_link","debit_card"],"description":"How the payer is charged. `undefined` lets the payer pick on the hosted invoice."},"connection_id":{"type":["integer","null"],"minimum":1},"catalog_product_id":{"type":["integer","null"],"minimum":1},"description":{"type":["string","null"]},"active":{"type":"boolean"},"settings":{"type":"object","additionalProperties":true,"description":"Free-form JSON persisted with the offer for checkout and funnel integrations. This API does not define or interpret individual settings keys."}}}}},"example":{"offer":{"name":"Sample Name","kind":"order_bump","amount":149.9,"currency":"BRL","billing_type":"pix","connection_id":1,"catalog_product_id":1,"description":"A short description.","active":true,"settings":{}}}}}}},"delete":{"tags":["Payment Offers"],"operationId":"auto_delete_api_v1_accounts_account_id_payments_offers_id","summary":"Archive an offer through the legacy delete route","description":"Compatibility route. It archives and deactivates the offer; it does not permanently delete it.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Success (no content)"},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/payments/settings/preview":{"post":{"tags":["Payments"],"operationId":"auto_post_api_v1_accounts_account_id_payments_settings_preview","summary":"Preview settings","description":"Performs the preview operation on the targeted setting resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The rendered body per channel plus the resolved out-of-window template. Nothing is persisted.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"locale":{"type":"string","description":"The locale the preview rendered in.","example":"pt_BR"},"sample_present":{"type":"boolean","description":"False when the account has no record of this module yet — the variables then render blank.","example":true},"variables":{"type":"object","description":"The resolved variable map of the module drop (token -\u003e value). Keys are module-specific.","additionalProperties":{"type":"string"},"example":{"amount":"49.9","currency":"BRL","due_date":"2026-08-01","pay_url":"https://pay.example/abc"}},"rendered":{"type":"string","description":"The body with its Liquid resolved (before per-channel rendering).","example":"Olá Ana Silva, sua cobrança de 49.9 está pronta."},"rendered_by_channel":{"type":"object","description":"One entry per channel type the ACCOUNT has an inbox of, rendered by Messages::MarkdownRendererService.","additionalProperties":{"type":"string"},"example":{"Channel::Whatsapp":"Olá Ana Silva, sua cobrança de 49.9 está pronta."}},"buttons":{"type":"array","description":"The NATIVE interactive buttons the send will attach for this type, already capped to what the chosen provider renders — Meta's `cta_url` carries exactly ONE button, so a second one is dropped here rather than promised. Empty when the type ships no button, the operator turned the switch off, or the channel has no interactive surface.","items":{"type":"object","properties":{"type":{"type":"string","enum":["cta_url","cta_copy"],"description":"cta_url opens a link; cta_copy copies a code to the clipboard (WhatsApp Web / API only).","example":"cta_url"},"text":{"type":"string","description":"The button caption","from the module's auxiliary labels.":null,"example":"Pagar agora"},"url":{"type":"string","description":"Present for cta_url.","example":"https://checkout.example/c/1"},"code":{"type":"string","description":"Present for cta_copy.","example":"00020126580014BR.GOV.BCB.PIX"}}},"example":[{"type":"cta_url","text":"Pagar agora","url":"https://checkout.example/c/1"}]},"defaults":{"type":"object","description":"The SHIPPED copy behind each key named in the request's `types` / `labels` — what an empty cell actually sends, so the editor can show it instead of only claiming it exists. Both maps are empty when the account has no record of this module yet (the shipped lines interpolate that record and are never fabricated).","properties":{"bodies":{"type":"object","description":"message type -\u003e shipped body, in the previewed locale.","additionalProperties":{"type":"string"},"example":{"cart_abandoned":"Abandoned cart"}},"labels":{"type":"object","description":"label key -\u003e shipped text, in the previewed locale.","additionalProperties":{"type":"string"},"example":{"pay_label":"Pay / resume:"}}}},"hsm":{"type":["object","null"],"description":"The resolved out-of-window template params, or null when none applies.","properties":{"name":{"type":"string","example":"payments_send_charge_pt_br"},"language":{"type":"string","example":"pt_BR"},"processed_params":{"type":"object","description":"Meta component params: `body` is a 1-indexed map, `buttons` is present only for a dynamic URL button.","additionalProperties":true,"example":{"body":{"1":"49.9"}}}}}}}}},"example":{"payload":{"locale":"pt_BR","sample_present":true,"variables":{"amount":"49.9","currency":"BRL","due_date":"2026-08-01","pay_url":"https://pay.example/abc"},"rendered":"Olá Ana Silva, sua cobrança de 49.9 está pronta.","rendered_by_channel":{"Channel::Whatsapp":"Olá Ana Silva, sua cobrança de 49.9 está pronta."},"buttons":[{"type":"cta_url","text":"Pagar agora","url":"https://checkout.example/c/1","code":"00020126580014BR.GOV.BCB.PIX"}],"defaults":{"bodies":{"cart_abandoned":"Abandoned cart"},"labels":{"pay_label":"Pay / resume:"}},"hsm":{"name":"payments_send_charge_pt_br","language":"pt_BR","processed_params":{"body":{"1":"49.9"}}}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"The unsaved cell the operator is looking at — nothing is persisted.","properties":{"type":{"type":"string","description":"Message type being previewed.","example":"send_charge"},"locale":{"type":"string","description":"Locale to render in; omitted falls back to the record cascade (contact -\u003e conversation -\u003e account).","example":"pt_BR"},"body":{"type":"string","description":"Markdown body with `{{ variable }}` tokens, exactly as authored in the editor.","example":"Olá {{ contact.name }}, sua cobrança de {{ payment.amount }} está pronta."},"scope":{"type":["string","null"],"description":"Per-surface override scope (e.g. `automation:12`). Omit for the account default.","example":"automation:12"},"whatsapp_template":{"type":"object","description":"The approved HSM the editor is holding. Omitted, the stored per-type x per-locale template is resolved instead.","properties":{"name":{"type":"string","example":"payments_send_charge_pt_br"},"language":{"type":"string","example":"pt_BR"},"url_button":{"type":"string","description":"Variable name or literal filling a dynamic URL button.","example":"pay_url"},"params":{"type":"array","description":"Positional body params: a variable name resolves from the message variable map, anything else is a literal.","items":{"type":"string"},"example":["amount"]}}}}},"example":{"type":"send_charge","locale":"pt_BR","body":"Olá {{ contact.name }}, sua cobrança de {{ payment.amount }} está pronta.","scope":"automation:12","whatsapp_template":{"name":"payments_send_charge_pt_br","language":"pt_BR","url_button":"pay_url","params":["amount"]}}}}}}},"/api/v1/accounts/{account_id}/payments/settings/test_send":{"post":{"tags":["Payments"],"operationId":"auto_post_api_v1_accounts_account_id_payments_settings_test_send","summary":"Test send settings","description":"Performs the test send operation on the targeted setting resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The outcome of the send, which honours the WhatsApp 24h window exactly as the real sender does.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"status":{"type":"string","enum":["sent","skipped","failed"],"description":"sent = a message was created; skipped = nothing was sent (see reason); failed = the send raised.","example":"sent"},"reason":{"type":["string","null"],"description":"Canonical skip/failure reason: `whatsapp_window_closed` (the 24h window is closed and no approved template is configured) or `empty_body`. Null when sent.","example":"whatsapp_window_closed"},"content":{"type":"string","description":"The rendered body that was sent (or would have been).","example":"Olá Ana Silva, sua cobrança de 49.9 está pronta."},"message_id":{"type":["integer","null"],"description":"The created message id; null on skip/failure.","example":9001}}}}},"example":{"payload":{"status":"sent","reason":"whatsapp_window_closed","content":"Olá Ana Silva, sua cobrança de 49.9 está pronta.","message_id":9001}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"422":{"description":"No conversation was given (`conversation_required`), so there is nothing to send into.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"conversation_required"}}},"example":{"error":"conversation_required"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["conversation_id"],"description":"Sends ONE real message into an EXISTING conversation. Never creates a conversation.","properties":{"conversation_id":{"type":"string","description":"Conversation display_id (an internal id is accepted as a fallback).","example":"42"},"type":{"type":"string","description":"Message type being tested.","example":"send_charge"},"locale":{"type":"string","example":"pt_BR"},"body":{"type":"string","description":"Markdown body","exactly as authored in the editor.":null,"example":"Olá {{ contact.name }}, sua cobrança de {{ payment.amount }} está pronta."},"scope":{"type":["string","null"],"example":"automation:12"},"whatsapp_template":{"type":"object","description":"The approved HSM the editor is holding, used when the 24h window is closed.","properties":{"name":{"type":"string","example":"payments_send_charge_pt_br"},"language":{"type":"string","example":"pt_BR"},"url_button":{"type":"string","example":"pay_url"},"params":{"type":"array","items":{"type":"string"},"example":["amount"]}}}}},"example":{"conversation_id":"42","type":"send_charge","locale":"pt_BR","body":"Olá {{ contact.name }}, sua cobrança de {{ payment.amount }} está pronta.","scope":"automation:12","whatsapp_template":{"name":"payments_send_charge_pt_br","language":"pt_BR","url_button":"pay_url","params":["amount"]}}}}}}},"/api/v1/accounts/{account_id}/payments/settings":{"get":{"tags":["Payments"],"operationId":"auto_get_api_v1_accounts_account_id_payments_settings","summary":"Get settings","description":"Returns the setting identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"scope":{"type":"string"},"messages":{"type":"string"},"delivery":{"type":"string"}}}}},"example":{"payload":{"scope":"sample scope","messages":"sample messages","delivery":"sample delivery"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]},"patch":{"tags":["Payments"],"operationId":"auto_patch_api_v1_accounts_account_id_payments_settings","summary":"Update settings","description":"Updates the setting identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"scope":{"type":"string"},"messages":{"type":"string"},"delivery":{"type":"string"}}}}},"example":{"payload":{"scope":"sample scope","messages":"sample messages","delivery":"sample delivery"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"scope":{"type":"string"},"clear":{"type":"array","items":{"type":"string"}}},"additionalProperties":true},"example":{"scope":"sample scope","clear":["sample clear"]}}}}},"put":{"tags":["Payments"],"operationId":"auto_put_api_v1_accounts_account_id_payments_settings","summary":"Update settings","description":"Updates the setting identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"scope":{"type":"string"},"messages":{"type":"string"},"delivery":{"type":"string"}}}}},"example":{"payload":{"scope":"sample scope","messages":"sample messages","delivery":"sample delivery"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"scope":{"type":"string"},"clear":{"type":"array","items":{"type":"string"}}},"additionalProperties":true},"example":{"scope":"sample scope","clear":["sample clear"]}}}}},"delete":{"tags":["Payments"],"operationId":"auto_delete_api_v1_accounts_account_id_payments_settings","summary":"Delete settings","description":"Deletes the setting identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"scope":{"type":"string"},"messages":{"type":"string"},"delivery":{"type":"string"}}}}},"example":{"payload":{"scope":"sample scope","messages":"sample messages","delivery":"sample delivery"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/commerce/latest_event":{"get":{"tags":["Commerce"],"operationId":"auto_get_api_v1_accounts_account_id_commerce_latest_event","summary":"Get a contact's latest commerce event","description":"Returns the most recent commerce lifecycle event for one contact, so an assistant can answer \"did this customer abandon a cart or leave a PIX pending?\" and offer a recovery. Responds 204 with no body when the contact has no commerce history, which callers read as \"nothing to recover\". The contact is account-scoped. Historical imports remain readable with `historical=true`, but the send action rejects them. Not gated by the `commerce_recovery` feature.","security":[{"userApiKey":[]}],"responses":{"204":{"description":"The contact has no commerce lifecycle events — there is nothing to recover."},"401":{"description":"Unauthorized"},"404":{"description":"No contact with this id in this account."},"200":{"description":"The contact's most recent commerce lifecycle event, including its recovery-card delivery outcome.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","description":"The most recent lifecycle event for this contact.","properties":{"id":{"type":"integer","description":"Lifecycle event id.","example":4821},"source":{"type":"string","description":"Emitter of the event — a catalog connector source type (kiwify, hotmart, nuvemshop, shopify, generic …), a native billing gateway (asaas, mercado_pago) or \"payments\".","example":"kiwify"},"stage":{"type":"string","enum":["cart_abandoned","order_placed","payment_pending","payment_confirmed","payment_declined","overdue","due_soon","refunded","chargeback","subscription_late","subscription_canceled"],"description":"Normalized purchase-lifecycle stage.","example":"cart_abandoned"},"amount":{"type":["number","null"],"description":"Value in MAJOR currency units (197.9 == R$ 197","90":null,"never cents).":null,"example":197.9},"currency":{"type":["string","null"],"description":"ISO-4217 code qualifying `amount`.","example":"BRL"},"payment_method":{"type":["string","null"],"description":"Instrument as the emitter named it (pix","boleto":null,"credit_card …).":null,"example":"pix"},"checkout_url":{"type":["string","null"],"description":"Buyer-facing checkout/cart URL that resumes the purchase.","example":"https://pay.kiwify.com.br/abc123"},"payment_url":{"type":["string","null"],"description":"Direct pay URL for an already-issued charge.","example":"https://pay.kiwify.com.br/charge/xyz789"},"pix_payload":{"type":["string","null"],"description":"PIX copia-e-cola string rendered by the card.","example":"00020126580014br.gov.bcb.pix0136a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d5204000053039865802BR6009SAO PAULO62070503***63041D3F"},"boleto_line":{"type":["string","null"],"description":"Boleto linha digitável.","example":"34191.79001 01043.510047 91020.150008 1 98770000019790"},"boleto_url":{"type":["string","null"],"description":"Printable boleto URL.","example":"https://cobranca.example.com/boleto/1a2b3c"},"expires_at":{"type":["string","null"],"format":"date-time","description":"When the PIX/boleto/checkout stops being payable.","example":"2026-07-19T23:59:59.000Z"},"contact_id":{"type":["integer","null"],"description":"The contact this event belongs to.","example":3312},"conversation_id":{"type":["integer","null"],"description":"Conversation this event is anchored to.","example":178},"created_at":{"type":"string","format":"date-time","description":"When the event was ingested.","example":"2026-07-18T14:32:10.000Z"},"historical":{"type":"boolean","description":"True for imported/adopted audit history; customer-facing sends are forbidden.","example":false},"delivery_status":{"type":["string","null"],"example":"sent","enum":["sent","skipped","failed",null],"description":"Outcome of the commerce recovery-card send, written by Commerce::DeliveryOutcome. Null means no send has been attempted for this event yet, which is the case for every event created before the recovery wave and for any event no automation rule ever acted on."},"delivery_reason":{"type":["string","null"],"example":"throttled","description":"Why the recovery card was or was not delivered. For sent/skipped this is a canonical token shared with the follow-up engine (no_contact, no_conversation, no_channel_inbox, whatsapp_window_closed, throttled, maestro_paused, channel_unavailable, sequence_not_published) plus commerce's own already_sent, test_send, operator_ignored and historical_event. Deliberately NOT declared as a closed set — for a failed delivery it carries the truncated provider/error message instead."},"card_sent_at":{"type":["string","null"],"format":"date-time","description":"First local card dispatch recorded as sent; preserved across resends and not a provider receipt.","example":"2026-07-18T14:35:02.000Z"},"card_message_id":{"type":["integer","null"],"description":"Id of the in-conversation message the card produced.","example":90312},"resend_count":{"type":"integer","description":"Re-deliveries after the first send.","example":0},"contact_name":{"type":["string","null"],"description":"Denormalized contact name.","example":"Marina Alves"}}}}},"example":{"payload":{"id":4821,"source":"kiwify","stage":"cart_abandoned","amount":197.9,"currency":"BRL","payment_method":"pix","checkout_url":"https://pay.kiwify.com.br/abc123","payment_url":"https://pay.kiwify.com.br/charge/xyz789","pix_payload":"00020126580014br.gov.bcb.pix0136a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d5204000053039865802BR6009SAO PAULO62070503***63041D3F","boleto_line":null,"boleto_url":null,"expires_at":"2026-07-19T23:59:59.000Z","contact_id":3312,"conversation_id":178,"created_at":"2026-07-18T14:32:10.000Z","historical":false,"delivery_status":"sent","delivery_reason":null,"card_sent_at":"2026-07-18T14:35:02.000Z","card_message_id":90312,"resend_count":0,"contact_name":"Marina Alves"}}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"},"description":"Account the contact belongs to."},{"name":"contact_id","in":"query","required":true,"schema":{"type":"integer"},"description":"Contact whose latest commerce event is wanted.","example":3312}]}},"/api/v1/accounts/{account_id}/commerce/send_recovery_card":{"post":{"tags":["Commerce"],"operationId":"auto_post_api_v1_accounts_account_id_commerce_send_recovery_card","summary":"Send a commerce recovery card to a conversation","description":"Surfaces an existing commerce lifecycle event as an outgoing in-conversation recovery card (channel-agnostic — PIX copia-e-cola, boleto line and pay links render on any channel) and returns the event with the delivery outcome that was just recorded. Both ids are account-scoped; `conversation_id` is matched strictly by public display id. Imported/adopted rows return 422 `historical_event` before target resolution and can never send a customer message. Delivery passes the shared send-window guard, so a 200 does not by itself mean the customer received it — read `delivery_status` on the returned event. When `X-Idempotency-Key` is present, retries return the original card outcome without creating or enqueueing the card sequence again. The key is scoped to the target account and conversation. Not gated by the `commerce_recovery` feature. Human callers send as themselves. Bot callers must authenticate as the active bot bound to the conversation's inbox; the card is then authored by that bot. Any other bot, or a user credential asserting bot authorship, is refused.","security":[{"agentBotApiKey":[]},{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"source":{"type":"string"},"external_id":{"type":"integer"},"stage":{"type":"string","enum":["","cart_abandoned","order_placed","payment_pending","payment_confirmed","payment_declined","overdue","due_soon","refunded","chargeback","subscription_late","subscription_canceled"]},"amount":{"type":"number"},"currency":{"type":"string"},"payment_method":{"type":"string","description":"Meio de pagamento do negócio. O conjunto base é pix, boleto, credit_card, debit_card, bank_transfer, cash, hosted_link e other; uma conta pode acrescentar chaves próprias em Sales::Setting `payment_categories.custom_methods`, então o conjunto NÃO é fechado. `other` é escolha do usuário; valor desconhecido vindo de provider é sempre nulo."},"checkout_url":{"type":"string"},"payment_url":{"type":"string"},"pix_payload":{"type":"string"},"boleto_line":{"type":"string"},"boleto_url":{"type":"string"},"expires_at":{"type":"string","format":"date-time"},"contact_id":{"type":"integer"},"contact_email":{"type":"string","format":"email"},"contact_phone_number":{"type":"string"},"payments_charge_id":{"type":"integer"},"conversation_id":{"type":"integer"},"conversation_display_id":{"type":["integer","null"]},"created_at":{"type":"string","format":"date-time"},"historical":{"type":"boolean"},"delivery_status":{"type":"string","enum":["sent","skipped","failed"],"description":"Outcome of the commerce recovery-card send, written by Commerce::DeliveryOutcome. Null means no send has been attempted for this event yet, which is the case for every event created before the recovery wave and for any event no automation rule ever acted on."},"delivery_reason":{"type":"string","description":"Why the recovery card was or was not delivered. For sent/skipped this is a canonical token shared with the follow-up engine (no_contact, no_conversation, no_channel_inbox, whatsapp_window_closed, throttled, maestro_paused, channel_unavailable, sequence_not_published) plus commerce's own already_sent, test_send, operator_ignored and historical_event. Deliberately NOT declared as a closed set — for a failed delivery it carries the truncated provider/error message instead."},"card_sent_at":{"type":"string","format":"date-time"},"card_message_id":{"type":"integer"},"resend_count":{"type":"integer"},"outcome":{"type":"string"},"owner_id":{"type":"integer"},"owner_name":{"type":["string","null"]},"operator_note":{"type":"string"},"ignored_at":{"type":"string","format":"date-time"},"ignored_by_id":{"type":"integer"},"ignored_by_name":{"type":["string","null"]},"contact_name":{"type":"string"}}}}},"example":{"payload":{"id":1,"source":"sample source","external_id":1,"stage":"","amount":149.9,"currency":"BRL","payment_method":"sample payment method","checkout_url":"https://example.com/resource","payment_url":"https://example.com/resource","pix_payload":"sample pix payload","boleto_line":"sample boleto line","boleto_url":"https://example.com/resource","expires_at":"2026-01-15T10:30:00.000Z","contact_id":1,"contact_email":"agent@example.com","contact_phone_number":"+5511999998888","payments_charge_id":1,"conversation_id":1,"conversation_display_id":1,"created_at":"2026-01-15T10:30:00.000Z","historical":true,"delivery_status":"sent","delivery_reason":"sample delivery reason","card_sent_at":"2026-01-15T10:30:00.000Z","card_message_id":1,"resend_count":5,"outcome":"sample outcome","owner_id":1,"owner_name":"sample owner name","operator_note":"sample operator note","ignored_at":"2026-01-15T10:30:00.000Z","ignored_by_id":1,"ignored_by_name":"sample ignored by name","contact_name":"sample contact name"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"422":{"description":"The lifecycle event is imported/adopted audit history; no message was created or sent.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","enum":["historical_event"],"example":"historical_event"}}},"example":{"error":"historical_event"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"X-Chatwoot-Message-Author","in":"header","required":false,"schema":{"type":"string","enum":["agent_bot"]},"description":"Optional assertion requiring authenticated AgentBot credentials. This header alone does not authenticate a caller."},{"name":"X-Idempotency-Key","in":"header","required":false,"schema":{"type":"string"},"description":"Stable caller key for retrying the exact same recovery-card send without duplication."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["commerce_event_id","conversation_id"],"properties":{"commerce_event_id":{"type":"integer","description":"The lifecycle event to render as a card.","example":4821},"conversation_id":{"type":"integer","description":"Target conversation public display id.","example":178}}},"example":{"commerce_event_id":4821,"conversation_id":178}}}}}},"/api/v1/accounts/{account_id}/commerce/lifecycle_events/{id}/resend":{"post":{"tags":["Commerce"],"operationId":"auto_post_api_v1_accounts_account_id_commerce_lifecycle_events_id_resend","summary":"Resend a commerce recovery card","description":"Re-delivers the recovery card for one lifecycle event and returns the event with its refreshed delivery outcome. Without an explicit target the shared resolver reuses a safe existing conversation; `conversation_display_id` is the canonical public target and the legacy `conversation_id` alias is interpreted as that same display id, never as a database id. A card that was already delivered is NOT sent again — the attempt is recorded as skipped with reason already_sent — unless `force` is true. Imported/adopted rows are immutable history and return 422 `historical_event`, even with `force`; no conversation is resolved or created. Sending still passes the shared send-window guard, so a WhatsApp conversation outside the 24h window is recorded as skipped with reason whatsapp_window_closed rather than failing the request. Requires the `commerce_recovery` account feature to be enabled.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The event after the attempt, carrying the outcome that was just recorded. A 200 means the local attempt was processed and its outcome persisted. `sent` means the card was created and dispatched locally; it is not a final provider delivery receipt.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","description":"The lifecycle event with its refreshed recovery-card delivery outcome.","properties":{"id":{"type":"integer","description":"Lifecycle event id.","example":4821},"source":{"type":"string","description":"Emitter of the event — a catalog connector source type (kiwify, hotmart, nuvemshop, shopify, generic …), a native billing gateway (asaas, mercado_pago) or \"payments\".","example":"kiwify"},"stage":{"type":"string","enum":["cart_abandoned","order_placed","payment_pending","payment_confirmed","payment_declined","overdue","due_soon","refunded","chargeback","subscription_late","subscription_canceled"],"description":"Normalized purchase-lifecycle stage.","example":"cart_abandoned"},"amount":{"type":["number","null"],"description":"Value in MAJOR currency units (197.9 == R$ 197","90":null,"never cents).":null,"example":197.9},"currency":{"type":["string","null"],"description":"ISO-4217 code qualifying `amount`.","example":"BRL"},"payment_method":{"type":["string","null"],"description":"Instrument as the emitter named it (pix","boleto":null,"credit_card …).":null,"example":"pix"},"checkout_url":{"type":["string","null"],"description":"Buyer-facing checkout/cart URL that resumes the purchase.","example":"https://pay.kiwify.com.br/abc123"},"payment_url":{"type":["string","null"],"description":"Direct pay URL for an already-issued charge.","example":"https://pay.kiwify.com.br/charge/xyz789"},"pix_payload":{"type":["string","null"],"description":"PIX copia-e-cola string rendered by the card.","example":"00020126580014br.gov.bcb.pix0136a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d5204000053039865802BR6009SAO PAULO62070503***63041D3F"},"boleto_line":{"type":["string","null"],"description":"Boleto linha digitável.","example":"34191.79001 01043.510047 91020.150008 1 98770000019790"},"boleto_url":{"type":["string","null"],"description":"Printable boleto URL.","example":"https://cobranca.example.com/boleto/1a2b3c"},"expires_at":{"type":["string","null"],"format":"date-time","description":"When the PIX/boleto/checkout stops being payable.","example":"2026-07-19T23:59:59.000Z"},"contact_id":{"type":["integer","null"],"description":"Resolved contact; null when the emitter sent no matchable identifier.","example":3312},"conversation_id":{"type":["integer","null"],"description":"Conversation this event is anchored to.","example":178},"created_at":{"type":"string","format":"date-time","description":"When the event was ingested.","example":"2026-07-18T14:32:10.000Z"},"historical":{"type":"boolean","description":"True for imported/adopted audit history; resend is forbidden.","example":false},"delivery_status":{"type":["string","null"],"example":"sent","enum":["sent","skipped","failed",null],"description":"Outcome of the commerce recovery-card send, written by Commerce::DeliveryOutcome. Null means no send has been attempted for this event yet, which is the case for every event created before the recovery wave and for any event no automation rule ever acted on."},"delivery_reason":{"type":["string","null"],"example":"already_sent","description":"Why the recovery card was or was not delivered. For sent/skipped this is a canonical token shared with the follow-up engine (no_contact, no_conversation, no_channel_inbox, whatsapp_window_closed, throttled, maestro_paused, channel_unavailable, sequence_not_published) plus commerce's own already_sent, test_send, operator_ignored and historical_event. Deliberately NOT declared as a closed set — for a failed delivery it carries the truncated provider/error message instead."},"card_sent_at":{"type":["string","null"],"format":"date-time","description":"First local card dispatch recorded as sent; preserved across resends and not a provider receipt.","example":"2026-07-18T14:35:02.000Z"},"card_message_id":{"type":["integer","null"],"description":"Id of the in-conversation message the card produced.","example":90312},"resend_count":{"type":"integer","description":"Re-deliveries after the first send.","example":2},"contact_name":{"type":["string","null"],"description":"Denormalized contact name.","example":"Marina Alves"}}}}},"example":{"payload":{"id":4821,"source":"kiwify","stage":"cart_abandoned","amount":197.9,"currency":"BRL","payment_method":"pix","checkout_url":"https://pay.kiwify.com.br/abc123","payment_url":"https://pay.kiwify.com.br/charge/xyz789","pix_payload":"00020126580014br.gov.bcb.pix0136a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d5204000053039865802BR6009SAO PAULO62070503***63041D3F","boleto_line":null,"boleto_url":null,"expires_at":"2026-07-19T23:59:59.000Z","contact_id":3312,"conversation_id":178,"created_at":"2026-07-18T14:32:10.000Z","historical":false,"delivery_status":"sent","delivery_reason":null,"card_sent_at":"2026-07-18T14:35:02.000Z","card_message_id":90312,"resend_count":2,"contact_name":"Marina Alves"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"No lifecycle event with this id in this account."},"403":{"description":"The `commerce_recovery` account feature is disabled (body `{\"error\":\"feature_not_enabled\"}`), or the current user's role does not allow resending.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["feature_not_enabled"],"example":"feature_not_enabled"}}},"example":{"error":"feature_not_enabled"}}}},"422":{"description":"The event is immutable imported/adopted history, or no safe conversation resolved in this account. Nothing was sent; historical rows are never recoverable through force or target overrides.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["historical_event","no_contact","no_conversation","conversation_not_found"],"example":"historical_event"}}},"example":{"error":"historical_event"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","description":"Every field is optional; an empty body reuses a safe existing conversation.","properties":{"conversation_display_id":{"type":["integer","null"],"description":"Canonical public display id of the target conversation.","example":178},"conversation_id":{"type":["integer","null"],"description":"Legacy alias for `conversation_display_id`; still interpreted strictly as a public display id. Omit both target fields to use the shared resolver.","example":178},"create_conversation":{"type":["boolean","null"],"description":"Explicitly allow creation only when no reusable conversation exists. Historical rows reject before this side effect.","example":false},"force":{"type":["boolean","null"],"description":"Bypass the already-delivered dedupe guard and send again. Defaults to false, which is the safe behaviour — a duplicate is refused and recorded as skipped/already_sent.","example":true}}},"example":{"conversation_display_id":178,"create_conversation":false,"force":true,"conversation_id":178}}}}}},"/api/v1/accounts/{account_id}/commerce/lifecycle_events/{id}/ignore":{"post":{"tags":["Commerce"],"operationId":"auto_post_api_v1_accounts_account_id_commerce_lifecycle_events_id_ignore","summary":"Ignore a commerce recovery opportunity","description":"Removes the opportunity from automatic recovery, pending-card backlog, latest actionable lookups and operational recovery metrics. The original event stays visible in history and the decision is audit logged. Repeating the action is idempotent.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Full lifecycle event with ignored_at and ignored_by populated.","content":{"application/json":{"schema":{"type":"object","required":["payload"],"properties":{"payload":{"$ref":"#/components/schemas/commerce_lifecycle_event_operational"}}},"example":{"payload":{"outcome":"recovered","owner_id":7,"owner_name":"Ana Souza","operator_note":"Customer completed payment after the follow-up call.","ignored_at":"2026-08-05T14:30:00.000Z","ignored_by_id":9,"ignored_by_name":"Carlos Lima"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"No lifecycle event with this id exists in this account."},"403":{"description":"The feature is disabled or the current role cannot manage commerce recovery."},"422":{"description":"The authenticated actor no longer belongs to this account."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/commerce/lifecycle_events/{id}/unignore":{"post":{"tags":["Commerce"],"operationId":"auto_post_api_v1_accounts_account_id_commerce_lifecycle_events_id_unignore","summary":"Reopen an ignored commerce recovery opportunity","description":"Clears ignored_at and ignored_by, making the opportunity eligible for recovery again. Existing outcome, owner and note are preserved. This action sends no message by itself and is idempotent.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Full lifecycle event with ignored_at and ignored_by cleared.","content":{"application/json":{"schema":{"type":"object","required":["payload"],"properties":{"payload":{"$ref":"#/components/schemas/commerce_lifecycle_event_operational"}}},"example":{"payload":{"outcome":"recovered","owner_id":7,"owner_name":"Ana Souza","operator_note":"Customer completed payment after the follow-up call.","ignored_at":"2026-08-05T14:30:00.000Z","ignored_by_id":9,"ignored_by_name":"Carlos Lima"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"No lifecycle event with this id exists in this account."},"403":{"description":"The feature is disabled or the current role cannot manage commerce recovery."},"422":{"description":"The authenticated actor no longer belongs to this account."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/commerce/lifecycle_events/send_backlog":{"post":{"tags":["Commerce"],"operationId":"auto_post_api_v1_accounts_account_id_commerce_lifecycle_events_send_backlog","summary":"Queue pending commerce recovery cards","description":"Queues up to 50 of the oldest live actionable events whose recovery card was never attempted, optionally within the same creation window shown on the recovery page. Returns 202 as soon as the bounded fan-out job is accepted; read the lifecycle timeline later for each actual sent, skipped or failed outcome. The drain reuses existing conversations only, applies the WhatsApp window and connection send-rate guards, and never includes imported or gateway-adopted history. The reserved `due_soon` stage is not actionable until a real producer exists. Requires `commerce_recovery`.","security":[{"userApiKey":[]}],"responses":{"202":{"description":"The bounded drain was accepted. No delivery result is implied by this receipt.","content":{"application/json":{"schema":{"type":"object","required":["payload"],"properties":{"payload":{"type":"object","required":["status","job_id"],"properties":{"status":{"type":"string","enum":["queued"],"example":"queued"},"job_id":{"type":"string","description":"Active Job identifier for operational correlation.","example":"7f7ab1dc-2519-4cd2-a085-284f8df63412"}}}}},"example":{"payload":{"status":"queued","job_id":"7f7ab1dc-2519-4cd2-a085-284f8df63412"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"403":{"description":"The feature is disabled or the current role cannot manage commerce recovery."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"since":{"type":["string","null"],"format":"date-time","description":"Inclusive lower bound on event creation time; an unparseable value is ignored."},"until":{"type":["string","null"],"format":"date-time","description":"Inclusive upper bound on event creation time; an unparseable value is ignored."}}},"example":{"since":"2026-07-01T00:00:00.000Z","until":"2026-07-31T23:59:59.000Z"}}}}}},"/api/v1/accounts/{account_id}/commerce/lifecycle_events/bulk":{"post":{"tags":["Commerce"],"operationId":"auto_post_api_v1_accounts_account_id_commerce_lifecycle_events_bulk","summary":"Apply one action to a selection of recovery opportunities","description":"Applies a single action to an explicit list of lifecycle-event ids, one record at a time, through the same seam the per-row buttons use. There is deliberately no destroy action: the feed is the audit trail of what the gateway reported, so removing an opportunity from recovery is `ignore`, which is reversible and audited. `resend` queues the same per-event delivery job the backlog drain uses (pacing, locking and outcomes unchanged) and refuses a row that is historical, ignored, already attempted or in a stage that sends no card. Every refused record is returned with its reason instead of being dropped. An id outside the account is indistinguishable from an absent one. Requires `commerce_recovery`.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Per-record outcome. `processed_ids` applied; every other id is reported with a reason.","content":{"application/json":{"schema":{"type":"object","required":["payload"],"properties":{"payload":{"type":"object","required":["processed_ids","failed"],"properties":{"processed_ids":{"type":"array","items":{"type":"integer"},"description":"Records the action really applied to. For `resend`, delivery was accepted — the row outcome still lands in the timeline."},"failed":{"type":"array","description":"One entry per refused record, with the stable reason code.","items":{"type":"object","required":["id","error"],"properties":{"id":{"type":"integer","example":8823},"error":{"type":"string","enum":["not_found","historical_event","operator_ignored","already_attempted","stage_not_actionable","invalid_actor","action_failed"],"example":"already_attempted"}}}}}}}},"example":{"payload":{"processed_ids":[8821,8822],"failed":[{"id":8823,"error":"already_attempted"}]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"422":{"description":"`invalid_bulk_action` (outside the closed set), `ids_required` (an empty selection is never widened to the whole account) or `bulk_limit_exceeded` (more than 500 records in one run).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","enum":["invalid_bulk_action","ids_required","bulk_limit_exceeded"],"example":"ids_required"}}},"example":{"error":"ids_required"}}}},"403":{"description":"The feature is disabled or the current role cannot manage commerce recovery."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["ids","bulk_action"],"properties":{"ids":{"type":"array","maxItems":500,"items":{"type":"integer"},"description":"Lifecycle-event ids to act on; duplicates and non-positive values are discarded."},"bulk_action":{"type":"string","enum":["ignore","unignore","resend"],"description":"The single action applied to every selected record."}}},"example":{"ids":[8821,8822],"bulk_action":"ignore"}}}}}},"/api/v1/accounts/{account_id}/commerce/lifecycle_events":{"get":{"tags":["Commerce"],"operationId":"auto_get_api_v1_accounts_account_id_commerce_lifecycle_events","summary":"List commerce lifecycle events","description":"Returns the account's commerce lifecycle events (cart abandoned, pending PIX/boleto, declined, overdue, refunded …) newest first, each carrying the recorded OUTCOME of its recovery-card delivery — sent, skipped or failed with a canonical reason, or null when no delivery was ever attempted. This is the read behind the \"Recuperação de vendas\" page. Imported/adopted rows remain visible with `historical=true`, but every customer-facing send is blocked for them. Filterable by stage, source, delivery status, operational outcome, owner, ignored state, contact and creation window. Paginated at 25 per page (`per_page` is clamped to 100) so one render can never load the whole table. Requires the `commerce_recovery` account feature to be enabled.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"One page of lifecycle events, newest first, plus pagination meta.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","description":"The page of events, ordered by creation time descending.","items":{"type":"object","description":"A normalized commerce lifecycle event plus its recovery-card delivery outcome.","properties":{"id":{"type":"integer","description":"Lifecycle event id.","example":4821},"source":{"type":"string","description":"Emitter of the event — the catalog connector's source type (kiwify, hotmart, nuvemshop, shopify, generic …) or, when the native billing engine produced it, the payments gateway (asaas, mercado_pago) or the literal \"payments\". Open set: a new connector contributes a new value without a contract change.","example":"kiwify"},"stage":{"type":"string","enum":["cart_abandoned","order_placed","payment_pending","payment_confirmed","payment_declined","overdue","due_soon","refunded","chargeback","subscription_late","subscription_canceled"],"description":"Normalized purchase-lifecycle stage. The four produced actionable ones (cart_abandoned, payment_pending, payment_declined, overdue) are the recoverable set a recovery card is offered for and the set the recovery rate uses. `due_soon` is retained only as a backwards-compatible stored value; no current producer emits it.","example":"cart_abandoned"},"amount":{"type":["number","null"],"description":"Order/charge value in MAJOR currency units — 197.9 means R$ 197,90, never cents.","example":197.9},"currency":{"type":["string","null"],"description":"ISO-4217 code qualifying `amount`.","example":"BRL"},"payment_method":{"type":["string","null"],"description":"Instrument as the emitter named it (pix, boleto, credit_card …). Open set — connector vocabulary.","example":"pix"},"checkout_url":{"type":["string","null"],"description":"Buyer-facing checkout/cart URL that resumes the purchase.","example":"https://pay.kiwify.com.br/abc123"},"payment_url":{"type":["string","null"],"description":"Direct pay URL for an already-issued charge. Preferred over checkout_url when both are present.","example":"https://pay.kiwify.com.br/charge/xyz789"},"pix_payload":{"type":["string","null"],"description":"PIX copia-e-cola string; the recovery card renders it as copyable text.","example":"00020126580014br.gov.bcb.pix0136a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d5204000053039865802BR6009SAO PAULO62070503***63041D3F"},"boleto_line":{"type":["string","null"],"description":"Boleto linha digitável.","example":"34191.79001 01043.510047 91020.150008 1 98770000019790"},"boleto_url":{"type":["string","null"],"description":"Printable boleto URL.","example":"https://cobranca.example.com/boleto/1a2b3c"},"expires_at":{"type":["string","null"],"format":"date-time","description":"When the PIX/boleto/checkout stops being payable.","example":"2026-07-19T23:59:59.000Z"},"contact_id":{"type":["integer","null"],"description":"Resolved contact. Null when the emitter sent no matchable identifier — delivery then exits as skipped with reason no_contact.","example":3312},"conversation_id":{"type":["integer","null"],"description":"Conversation this event is anchored to","when one was resolved.":null,"example":178},"created_at":{"type":"string","format":"date-time","description":"When the event was ingested.","example":"2026-07-18T14:32:10.000Z"},"historical":{"type":"boolean","description":"True for imported/adopted audit history. Recovery-card sends are always rejected for these rows.","example":false},"delivery_status":{"type":["string","null"],"example":"sent","enum":["sent","skipped","failed",null],"description":"Outcome of the commerce recovery-card send, written by Commerce::DeliveryOutcome. Null means no send has been attempted for this event yet, which is the case for every event created before the recovery wave and for any event no automation rule ever acted on."},"delivery_reason":{"type":["string","null"],"example":"whatsapp_window_closed","description":"Why the recovery card was or was not delivered. For sent/skipped this is a canonical token shared with the follow-up engine (no_contact, no_conversation, no_channel_inbox, whatsapp_window_closed, throttled, maestro_paused, channel_unavailable, sequence_not_published) plus commerce's own already_sent, test_send, operator_ignored and historical_event. Deliberately NOT declared as a closed set — for a failed delivery it carries the truncated provider/error message instead."},"card_sent_at":{"type":["string","null"],"format":"date-time","description":"First local card creation and dispatch recorded as sent. Preserved across resends — it records provenance, not provider receipt or the latest attempt.","example":"2026-07-18T14:35:02.000Z"},"card_message_id":{"type":["integer","null"],"description":"Id of the in-conversation message the card produced.","example":90312},"resend_count":{"type":"integer","description":"How many times the card was re-delivered after the first send. Zero on a first (or never) delivery.","example":1},"outcome":{"type":["string","null"],"enum":["recovered","lost",null],"description":"Terminal operator verdict; null means open.","example":"recovered"},"owner_id":{"type":["integer","null"],"description":"Account user responsible for the opportunity.","example":7},"owner_name":{"type":["string","null"],"description":"Display name of the responsible account user.","example":"Ana Souza"},"operator_note":{"type":["string","null"],"maxLength":2000,"description":"Internal operator note.","example":"Customer completed payment after follow-up."},"ignored_at":{"type":["string","null"],"format":"date-time","description":"When this opportunity was removed from active recovery.","example":null},"ignored_by_id":{"type":["integer","null"],"description":"Account user who ignored this opportunity.","example":null},"ignored_by_name":{"type":["string","null"],"description":"Display name of the user who ignored it.","example":null},"contact_name":{"type":["string","null"],"description":"Denormalized contact name so the timeline renders a person rather than an id.","example":"Marina Alves"}}}},"meta":{"type":"object","description":"Pagination counters for the filtered set, so the page never needs a second count request.","properties":{"count":{"type":"integer","description":"Total events matching the filters","across all pages.":null,"example":137},"current_page":{"type":"integer","description":"1-based index of the page returned.","example":1},"total_pages":{"type":"integer","description":"Number of pages at the current page size.","example":6},"per_page":{"type":"integer","description":"Page size actually applied (after clamping).","example":25},"has_more":{"type":"boolean","description":"True when a further page exists.","example":true}}}}},"example":{"payload":[{"id":4821,"source":"kiwify","stage":"cart_abandoned","amount":197.9,"currency":"BRL","payment_method":"pix","checkout_url":"https://pay.kiwify.com.br/abc123","payment_url":"https://pay.kiwify.com.br/charge/xyz789","pix_payload":"00020126580014br.gov.bcb.pix0136a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d5204000053039865802BR6009SAO PAULO62070503***63041D3F","boleto_line":null,"boleto_url":null,"expires_at":"2026-07-19T23:59:59.000Z","contact_id":3312,"conversation_id":178,"created_at":"2026-07-18T14:32:10.000Z","historical":false,"delivery_status":"sent","delivery_reason":null,"card_sent_at":"2026-07-18T14:35:02.000Z","card_message_id":90312,"resend_count":1,"outcome":"recovered","owner_id":7,"owner_name":"Ana Souza","operator_note":"Customer completed payment after follow-up.","ignored_at":null,"ignored_by_id":null,"ignored_by_name":null,"contact_name":"Marina Alves"},{"id":4817,"source":"asaas","stage":"overdue","amount":89.0,"currency":"BRL","payment_method":"boleto","checkout_url":null,"payment_url":"https://www.asaas.com/i/9f2c1a7b3e5d","pix_payload":null,"boleto_line":"34191.79001 01043.510047 91020.150008 1 98770000008900","boleto_url":"https://cobranca.example.com/boleto/9f2c1a","expires_at":"2026-07-17T23:59:59.000Z","contact_id":3187,"conversation_id":null,"created_at":"2026-07-18T09:12:44.000Z","historical":true,"delivery_status":"skipped","delivery_reason":"whatsapp_window_closed","card_sent_at":null,"card_message_id":null,"resend_count":0,"outcome":null,"owner_id":null,"owner_name":null,"operator_note":null,"ignored_at":null,"ignored_by_id":null,"ignored_by_name":null,"contact_name":"Rafael Souza"}],"meta":{"count":137,"current_page":1,"total_pages":6,"per_page":25,"has_more":true}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"403":{"description":"The `commerce_recovery` account feature is disabled (body `{\"error\":\"feature_not_enabled\"}`), or the current user's role does not allow reading commerce events.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["feature_not_enabled"],"example":"feature_not_enabled"}}},"example":{"error":"feature_not_enabled"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"},"description":"Account the events belong to."},{"name":"stage","in":"query","required":false,"description":"Restrict to one lifecycle stage.","schema":{"type":"string","enum":["cart_abandoned","order_placed","payment_pending","payment_confirmed","payment_declined","overdue","due_soon","refunded","chargeback","subscription_late","subscription_canceled"]},"example":"cart_abandoned"},{"name":"source","in":"query","required":false,"description":"Restrict to one emitter — a catalog connector source type (kiwify, hotmart, nuvemshop, shopify, generic …) or a native billing gateway (asaas, mercado_pago).","schema":{"type":"string"},"example":"kiwify"},{"name":"delivery_status","in":"query","required":false,"description":"Restrict to one recorded delivery outcome. Use `not_attempted` for the null-status backlog.","schema":{"type":"string","enum":["sent","skipped","failed","not_attempted"]},"example":"skipped"},{"name":"outcome","in":"query","required":false,"description":"Restrict to one terminal operator verdict.","schema":{"type":"string","enum":["recovered","lost"]},"example":"recovered"},{"name":"owner_id","in":"query","required":false,"description":"Restrict to opportunities assigned to one user in this account.","schema":{"type":"integer","minimum":1},"example":7},{"name":"ignored","in":"query","required":false,"description":"True returns ignored history; false returns opportunities still eligible for recovery.","schema":{"type":"boolean"},"example":false},{"name":"contact_id","in":"query","required":false,"description":"Restrict to one contact.","schema":{"type":"integer"},"example":3312},{"name":"since","in":"query","required":false,"description":"Lower bound (inclusive) on creation time. Any parseable timestamp; an unparseable value is ignored rather than erroring.","schema":{"type":"string","format":"date-time"},"example":"2026-07-01T00:00:00.000Z"},{"name":"until","in":"query","required":false,"description":"Upper bound (inclusive) on creation time. Same parsing rule as `since`.","schema":{"type":"string","format":"date-time"},"example":"2026-07-31T23:59:59.000Z"},{"name":"page","in":"query","required":false,"description":"1-based page number.","schema":{"type":"integer","minimum":1},"example":1},{"name":"per_page","in":"query","required":false,"description":"Rows per page. Defaults to 25 when omitted and is clamped to the 1..100 range.","schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"example":25}]}},"/api/v1/accounts/{account_id}/commerce/lifecycle_events/{id}":{"patch":{"tags":["Commerce"],"operationId":"auto_patch_api_v1_accounts_account_id_commerce_lifecycle_events_id","summary":"Update a commerce recovery opportunity","description":"Assigns an account user, records an internal note, or sets/clears the terminal business verdict. This action never changes gateway lifecycle stage, financial values or recovery-card delivery history. Changes are account-scoped and audit logged; note contents are not copied into audit metadata. Requires the `commerce_recovery` account feature.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Full lifecycle event after its operational metadata was updated.","content":{"application/json":{"schema":{"type":"object","required":["payload"],"properties":{"payload":{"$ref":"#/components/schemas/commerce_lifecycle_event_operational"}}},"example":{"payload":{"outcome":"recovered","owner_id":7,"owner_name":"Ana Souza","operator_note":"Customer completed payment after the follow-up call.","ignored_at":"2026-08-05T14:30:00.000Z","ignored_by_id":9,"ignored_by_name":"Carlos Lima"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"No lifecycle event with this id exists in this account."},"403":{"description":"The feature is disabled or the current role cannot manage commerce recovery."},"422":{"description":"The owner, outcome or note is invalid; no operational field was changed.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","enum":["invalid_actor","invalid_owner","invalid_outcome","operator_note_too_long","no_operational_changes"],"example":"invalid_owner"}}},"example":{"error":"invalid_owner"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/commerce_lifecycle_event_operational_payload"},"example":{"lifecycle_event":{"outcome":"recovered","owner_id":7,"operator_note":"Customer completed payment after the follow-up call."}}}}}},"put":{"tags":["Commerce"],"operationId":"auto_put_api_v1_accounts_account_id_commerce_lifecycle_events_id","summary":"Update a commerce recovery opportunity","description":"Assigns an account user, records an internal note, or sets/clears the terminal business verdict. This action never changes gateway lifecycle stage, financial values or recovery-card delivery history. Changes are account-scoped and audit logged; note contents are not copied into audit metadata. Requires the `commerce_recovery` account feature.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Full lifecycle event after its operational metadata was updated.","content":{"application/json":{"schema":{"type":"object","required":["payload"],"properties":{"payload":{"$ref":"#/components/schemas/commerce_lifecycle_event_operational"}}},"example":{"payload":{"outcome":"recovered","owner_id":7,"owner_name":"Ana Souza","operator_note":"Customer completed payment after the follow-up call.","ignored_at":"2026-08-05T14:30:00.000Z","ignored_by_id":9,"ignored_by_name":"Carlos Lima"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"No lifecycle event with this id exists in this account."},"403":{"description":"The feature is disabled or the current role cannot manage commerce recovery."},"422":{"description":"The owner, outcome or note is invalid; no operational field was changed.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","enum":["invalid_actor","invalid_owner","invalid_outcome","operator_note_too_long","no_operational_changes"],"example":"invalid_owner"}}},"example":{"error":"invalid_owner"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/commerce_lifecycle_event_operational_payload"},"example":{"lifecycle_event":{"outcome":"recovered","owner_id":7,"operator_note":"Customer completed payment after the follow-up call."}}}}}}},"/api/v1/accounts/{account_id}/commerce/recovery_metrics":{"get":{"tags":["Commerce"],"operationId":"auto_get_api_v1_accounts_account_id_commerce_recovery_metrics","summary":"Get commerce recovery metrics","description":"Aggregate view of commerce recovery over an optional actionable-event cohort — the four-stage actionable funnel, recovery-card delivery split, non-delivery reasons and recovery rate all use that same stage universe. A settlement is attributed only when `payment_confirmed` follows an attempt recorded as sent with the same contact, source and external order/charge id. Each canonical confirmation is assigned once to the latest eligible attempt; `order_placed` remains pending and never enters recovered revenue. Recovered revenue uses the settlement amount and is grouped by its recorded currency, never summed across currencies or forced to BRL. This is a follow-the-money correlation, not a causal claim. Requires the `commerce_recovery` account feature.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The recovery report for the requested actionable cohort, with stable zero/empty buckets.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","description":"The recovery report.","properties":{"funnel":{"type":"array","description":"Count and currency-separated value per actionable stage, in canonical recovery order. Stages with no events in the cohort are omitted.","items":{"type":"object","properties":{"stage":{"type":"string","enum":["cart_abandoned","payment_pending","payment_declined","overdue"],"description":"The lifecycle stage this row aggregates.","example":"cart_abandoned"},"count":{"type":"integer","description":"Events at this stage in the window.","example":84},"amount":{"type":["number","null"],"description":"Backward-compatible scalar total; populated only when this stage has exactly one currency bucket, otherwise null.","example":null},"currency":{"type":["string","null"],"description":"Currency qualifying the scalar `amount`; null for zero or multiple currency buckets.","example":null},"amounts":{"type":"array","description":"Stable currency-separated totals for this stage; empty when no event carries an amount.","items":{"type":"object","properties":{"currency":{"type":["string","null"],"description":"Recorded currency code; null when the source omitted it.","example":"BRL"},"amount":{"type":["number","null"],"description":"Stage total in this currency's MAJOR unit.","example":14623.6}}}}}}},"delivery":{"type":"object","description":"Actionable recovery-card events split by recorded outcome. All four keys are always present; absent outcomes are zero. `not_attempted` covers actionable events no rule ever acted on and is never folded into another bucket.","properties":{"sent":{"type":"integer","description":"Cards that reached the customer.","example":61},"skipped":{"type":"integer","description":"Deliveries deliberately not made; see `reasons`.","example":19},"failed":{"type":"integer","description":"Deliveries attempted that errored; see `reasons`.","example":4},"not_attempted":{"type":"integer","description":"Events with no delivery attempt recorded at all.","example":53}}},"reasons":{"type":"object","description":"Why deliveries did not reach the customer, keyed by reason and ordered most frequent first. Keys are the canonical tokens shared with the follow-up engine (no_contact, no_conversation, no_channel_inbox, whatsapp_window_closed, throttled, channel_unavailable, sequence_not_published) plus commerce's own already_sent and test_send; for a failed delivery the key can instead be a truncated provider error, so treat the key set as open.","additionalProperties":{"type":"integer","description":"Number of skipped/failed deliveries carrying this reason."}},"recovered_amount":{"type":["number","null"],"description":"Backward-compatible scalar settlement total; populated only when exactly one recovered currency bucket exists, otherwise null.","example":null},"recovered_currency":{"type":["string","null"],"description":"Currency qualifying `recovered_amount`; null for zero or multiple recovered currency buckets.","example":null},"recovered_amounts":{"type":"array","description":"Stable settlement-value totals grouped by recorded currency; empty when no settlement was attributed.","items":{"type":"object","properties":{"currency":{"type":["string","null"],"description":"Recorded settlement currency; null when the source omitted it.","example":"BRL"},"amount":{"type":["number","null"],"description":"Attributed settlement total in this currency's MAJOR unit.","example":3318.7}}}},"recovered_count":{"type":"integer","description":"Canonical settlements uniquely attributed to a prior delivered attempt with the same contact/source/external id.","example":13},"attempted_count":{"type":"integer","description":"Delivered events in the same four-stage actionable cohort — the denominator of `recovery_rate`.","example":61},"recovery_rate":{"type":["number","null"],"format":"float","minimum":0,"maximum":1,"description":"recovered_count / attempted_count as a fraction between 0.0 and 1.0, rounded to 4 decimals. NULL when nothing was attempted in the window — clients must render an explicit \"no data\" rather than a misleading 0%.","example":0.2131}}}}},"example":{"payload":{"funnel":[{"stage":"cart_abandoned","count":84,"amount":null,"currency":null,"amounts":[{"currency":"BRL","amount":14623.6},{"currency":"USD","amount":2000.0}]},{"stage":"payment_pending","count":31,"amount":5890.0,"currency":"BRL","amounts":[{"currency":"BRL","amount":5890.0}]}],"delivery":{"sent":61,"skipped":19,"failed":4,"not_attempted":31},"reasons":{"whatsapp_window_closed":11,"no_conversation":5,"already_sent":3,"channel_unavailable":4},"recovered_amount":null,"recovered_currency":null,"recovered_amounts":[{"currency":"BRL","amount":3318.7},{"currency":"USD","amount":1000.0}],"recovered_count":13,"attempted_count":61,"recovery_rate":0.2131}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"403":{"description":"The `commerce_recovery` account feature is disabled (body `{\"error\":\"feature_not_enabled\"}`), or the current user's role does not allow reading commerce metrics.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["feature_not_enabled"],"example":"feature_not_enabled"}}},"example":{"error":"feature_not_enabled"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"},"description":"Account the metrics are computed for."},{"name":"since","in":"query","required":false,"description":"Lower bound (inclusive) on actionable-attempt creation time. Any parseable timestamp; an unparseable value degrades to no bound rather than erroring.","schema":{"type":"string","format":"date-time"},"example":"2026-07-01T00:00:00.000Z"},{"name":"until","in":"query","required":false,"description":"Upper bound (inclusive) on actionable-attempt creation time. A later matching settlement may occur after this cohort bound. Same parsing rule as `since`.","schema":{"type":"string","format":"date-time"},"example":"2026-07-31T23:59:59.000Z"}]}},"/api/v1/accounts/{account_id}/commerce/reconciliation_items/{id}/link":{"post":{"tags":["Commerce"],"operationId":"auto_post_api_v1_accounts_account_id_commerce_reconciliation_items_id_link","summary":"Link reconciliation items","description":"Performs the link operation on the targeted reconciliation item resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The reconciled queue item. The durable order/charge or order/event link was applied without creating a sale.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/commerce_reconciliation_item_response"},"example":{"payload":{"id":41,"source_type":"payments_charge","source_id":5821,"state":"pending","reason":"charge_without_order_link","suggestions":[{"source_type":"crm_order","source_id":9102,"confidence":1.0,"reason":"exact_gateway_external_id"}],"resolution":{"operation":"link","relationship_key":"charge:5821:order:9102","source_type":"payments_charge","source_id":5821,"target_type":"crm_order","target_id":9102,"reason":"operator_ignored","ignored_external_id":73,"ignored_external_created":true,"canonical_item_id":40,"fingerprint":"57bd093c095c62da2abdc0c8c81a0dfcd9f750c48f3a8f85468a24d517967e6c"},"resolved_at":"2026-08-14T12:30:00Z","resolved_by_id":7,"created_at":"2026-08-14T11:00:00Z","updated_at":"2026-08-14T12:30:00Z","source":null}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["reconciliation_item"],"properties":{"reconciliation_item":{"type":"object","required":["target_type","target_id"],"properties":{"target_type":{"type":"string","enum":["payments_charge","crm_order","commerce_event"],"example":"crm_order"},"target_id":{"type":"integer","minimum":1,"example":42}}}}},"example":{"reconciliation_item":{"target_type":"crm_order","target_id":42}}}}}}},"/api/v1/accounts/{account_id}/commerce/reconciliation_items/{id}/ignore":{"post":{"tags":["Commerce"],"operationId":"auto_post_api_v1_accounts_account_id_commerce_reconciliation_items_id_ignore","summary":"Ignore reconciliation items","description":"Performs the ignore operation on the targeted reconciliation item resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The queue item marked ignored, with the operator decision recorded in the audit trail.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/commerce_reconciliation_item_response"},"example":{"payload":{"id":41,"source_type":"payments_charge","source_id":5821,"state":"pending","reason":"charge_without_order_link","suggestions":[{"source_type":"crm_order","source_id":9102,"confidence":1.0,"reason":"exact_gateway_external_id"}],"resolution":{"operation":"link","relationship_key":"charge:5821:order:9102","source_type":"payments_charge","source_id":5821,"target_type":"crm_order","target_id":9102,"reason":"operator_ignored","ignored_external_id":73,"ignored_external_created":true,"canonical_item_id":40,"fingerprint":"57bd093c095c62da2abdc0c8c81a0dfcd9f750c48f3a8f85468a24d517967e6c"},"resolved_at":"2026-08-14T12:30:00Z","resolved_by_id":7,"created_at":"2026-08-14T11:00:00Z","updated_at":"2026-08-14T12:30:00Z","source":null}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","maxLength":500,"example":"Not our historical sale"}}},"example":{"reason":"Not our historical sale"}}}}}},"/api/v1/accounts/{account_id}/commerce/reconciliation_items/{id}/undo":{"post":{"tags":["Commerce"],"operationId":"auto_post_api_v1_accounts_account_id_commerce_reconciliation_items_id_undo","summary":"Undo reconciliation items","description":"Performs the undo operation on the targeted reconciliation item resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The reopened queue item after a safe reversal of the recorded reconciliation decision.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/commerce_reconciliation_item_response"},"example":{"payload":{"id":41,"source_type":"payments_charge","source_id":5821,"state":"pending","reason":"charge_without_order_link","suggestions":[{"source_type":"crm_order","source_id":9102,"confidence":1.0,"reason":"exact_gateway_external_id"}],"resolution":{"operation":"link","relationship_key":"charge:5821:order:9102","source_type":"payments_charge","source_id":5821,"target_type":"crm_order","target_id":9102,"reason":"operator_ignored","ignored_external_id":73,"ignored_external_created":true,"canonical_item_id":40,"fingerprint":"57bd093c095c62da2abdc0c8c81a0dfcd9f750c48f3a8f85468a24d517967e6c"},"resolved_at":"2026-08-14T12:30:00Z","resolved_by_id":7,"created_at":"2026-08-14T11:00:00Z","updated_at":"2026-08-14T12:30:00Z","source":null}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/commerce/reconciliation_items/{id}/merge":{"post":{"tags":["Commerce"],"operationId":"auto_post_api_v1_accounts_account_id_commerce_reconciliation_items_id_merge","summary":"Merge reconciliation items","description":"Performs the merge operation on the targeted reconciliation item resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The duplicate queue row consolidated under its already-linked counterpart; no financial source was mutated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/commerce_reconciliation_item_response"},"example":{"payload":{"id":41,"source_type":"payments_charge","source_id":5821,"state":"pending","reason":"charge_without_order_link","suggestions":[{"source_type":"crm_order","source_id":9102,"confidence":1.0,"reason":"exact_gateway_external_id"}],"resolution":{"operation":"link","relationship_key":"charge:5821:order:9102","source_type":"payments_charge","source_id":5821,"target_type":"crm_order","target_id":9102,"reason":"operator_ignored","ignored_external_id":73,"ignored_external_created":true,"canonical_item_id":40,"fingerprint":"57bd093c095c62da2abdc0c8c81a0dfcd9f750c48f3a8f85468a24d517967e6c"},"resolved_at":"2026-08-14T12:30:00Z","resolved_by_id":7,"created_at":"2026-08-14T11:00:00Z","updated_at":"2026-08-14T12:30:00Z","source":null}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/commerce/reconciliation_items/integrity":{"get":{"tags":["Commerce"],"operationId":"auto_get_api_v1_accounts_account_id_commerce_reconciliation_items_integrity","summary":"Audit commercial graph integrity","description":"Audits contacts, organizations, memberships, deals, orders, catalog lines, charges, settlement dates, ownership and seller-commission cardinality for the current account. The endpoint never repairs records or guesses missing customer data; use its ids with the governed source import and sale-graph preview/apply flows. Requires Commerce Recovery and commerce_manage.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Exact account-scoped counts with PII-free bounded samples.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/commerce_integrity_audit_response"},"example":{"payload":{"active_payment_orders_without_charge":{"count":2,"sample_ids":[67,68]},"charges_without_order":{"count":2,"sample_ids":[67,68]},"voided_externals_without_ignore":{"count":2,"sample_ids":[67,68]},"connection_mismatches":{"count":2,"sample_ids":[67,68]},"paid_orders_without_paid_at":{"count":2,"sample_ids":[67,68]},"settled_charges_without_paid_at":{"count":2,"sample_ids":[67,68]},"orders_with_missing_linked_charge":{"count":2,"sample_ids":[67,68]},"charge_order_contact_mismatches":{"count":2,"sample_ids":[67,68]},"charge_order_organization_mismatches":{"count":2,"sample_ids":[67,68]},"charge_order_deal_mismatches":{"count":2,"sample_ids":[67,68]},"charge_order_amount_mismatches":{"count":2,"sample_ids":[67,68]},"charge_order_currency_mismatches":{"count":2,"sample_ids":[67,68]},"charge_order_status_mismatches":{"count":2,"sample_ids":[67,68]},"charge_order_gateway_mismatches":{"count":2,"sample_ids":[67,68]},"charge_order_external_id_mismatches":{"count":2,"sample_ids":[67,68]},"order_deal_contact_mismatches":{"count":2,"sample_ids":[67,68]},"order_deal_organization_mismatches":{"count":2,"sample_ids":[67,68]},"order_deal_owner_mismatches":{"count":2,"sample_ids":[67,68]},"charge_order_owner_mismatches":{"count":2,"sample_ids":[67,68]},"paid_orders_without_seller_commission":{"count":2,"sample_ids":[67,68]},"paid_orders_with_multiple_seller_commissions":{"count":2,"sample_ids":[67,68]},"paid_orders_with_commission_payee_mismatch":{"count":2,"sample_ids":[67,68]},"commercial_contacts_incomplete":{"count":1,"sample":[{"id":1704,"missing_fields":["tax_id","address"]}]},"commercial_organizations_incomplete":{"count":1,"sample":[{"id":41,"missing_fields":["legal_name","tax_id","address"]}]},"operational_orders_without_owner":{"count":2,"sample_ids":[67,68]},"operational_orders_without_deal":{"count":2,"sample_ids":[67,68]},"operational_orders_without_catalog_items":{"count":2,"sample_ids":[67,68]},"charges_without_catalog_items":{"count":2,"sample_ids":[67,68]},"paid_order_contacts_not_customer":{"count":2,"sample_ids":[67,68]},"paid_order_deals_not_won":{"count":2,"sample_ids":[67,68]},"contact_primary_organization_without_membership":{"count":2,"sample_ids":[67,68]},"order_organization_without_membership":{"count":2,"sample_ids":[67,68]},"charge_organization_without_membership":{"count":2,"sample_ids":[67,68]},"potential_duplicate_orders":{"count":2,"sample_ids":[67,68]}}}}}},"401":{"description":"The authenticated caller lacks the permission required to audit commercial integrity."},"404":{"description":"Account or resource not found"},"403":{"description":"Commerce Recovery is disabled for the account."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/commerce/reconciliation_items/detect":{"post":{"tags":["Commerce"],"operationId":"auto_post_api_v1_accounts_account_id_commerce_reconciliation_items_detect","summary":"Detect reconciliation items","description":"Performs the detect operation on the targeted reconciliation item resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"202":{"description":"Reconciliation detection job queued.","content":{"application/json":{"schema":{"type":"object","required":["queued"],"properties":{"queued":{"type":"boolean","example":true}}},"example":{"queued":true}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/commerce/reconciliation_items/bulk":{"post":{"tags":["Commerce"],"operationId":"auto_post_api_v1_accounts_account_id_commerce_reconciliation_items_bulk","summary":"Bulk reconciliation items","description":"Performs the bulk operation on the targeted reconciliation item resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Per-item result. failed_ids and errors identify rows that were not mutated."},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["reconciliation_item"],"properties":{"reconciliation_item":{"type":"object","required":["ids","bulk_action"],"properties":{"ids":{"type":"array","minItems":1,"maxItems":500,"items":{"type":"integer","minimum":1},"example":[41,42]},"bulk_action":{"type":"string","enum":["ignore","undo"],"example":"ignore"},"reason":{"type":"string","maxLength":500,"example":"Historical duplicate"}}}}},"example":{"reconciliation_item":{"ids":[41,42],"bulk_action":"ignore","reason":"Historical duplicate"}}}}}}},"/api/v1/accounts/{account_id}/commerce/reconciliation_items/catalog_projection_preview":{"post":{"tags":["Commerce"],"operationId":"auto_post_api_v1_accounts_account_id_commerce_reconciliation_items_catalog_projection_preview","summary":"Preview an exact catalog-line projection","description":"Validates one account-scoped order against an explicitly selected Payments charge or CRM deal, then returns the complete immutable line plan and concurrency fingerprint without writing. Product and variant ids must already be persisted on the source lines; names, prices and amounts are never used to infer catalog identity. Requires Catalog, Orders Registry and the selected source feature.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Read-only plan, blocking conflicts and fingerprint for these exact records.","content":{"application/json":{"schema":{"type":"object","required":["payload"],"properties":{"payload":{"$ref":"#/components/schemas/commerce_catalog_line_projection"}}},"example":{"payload":{"order":{"id":9102,"account_id":1},"requested_source":{"type":"Payments::Charge","id":5821},"mode":"direct_charge","blocked":false,"conflicts":[{"code":"source_line_items_missing","line_id":734,"count":101,"planned_index":0,"variant_id":87,"receipt_id":912,"error_class":"ArgumentError"}],"planned":{"operation":"project_order","charge_line_items":[{"source_item_id":"payments-charge-line-734","catalog_product_id":41,"catalog_variant_id":87,"name_snapshot":"Plano Comercial","quantity":"1.0","unit_price":"997.0","discount":"0.0","discount_type":"fixed","currency":"BRL","position":0,"line_total":"997.0","metadata":{"provider_item_id":"item_001","catalog_line_projection":{"version":1,"source_type":"Payments::Charge","source_id":5821,"stable_source_item_id":"payments-charge-line-734"}}}],"order_line_items":[{"source_item_id":"payments-charge-line-734","catalog_product_id":41,"catalog_variant_id":87,"name_snapshot":"Plano Comercial","quantity":"1.0","unit_price":"997.0","discount":"0.0","discount_type":"fixed","currency":"BRL","position":0,"line_total":"997.0","metadata":{"provider_item_id":"item_001","catalog_line_projection":{"version":1,"source_type":"Payments::Charge","source_id":5821,"stable_source_item_id":"payments-charge-line-734"}}}],"order_metadata":{"version":1,"mode":"direct_charge","source_type":"Payments::Charge","source_id":5821,"line_count":1,"currency":"BRL","subtotal":"997.0","charge_discount":"0.0","charge_discount_type":"fixed","net_total":"997.0","line_digest":"5904202fbd937b303d34f366e2bd0149b746be65e80acba0f66a4325735b99fb","reconstructed":false,"reconstruction":{"source_type":"Crm::Item","source_id":934,"actor_id":12,"reason":"Contrato conferido pelo administrador."}}},"digest":"63430ddc94fb70c5e529111053055c6a0ce2e9685a270998fdca4db6a2aca60d","fingerprint":"57bd093c095c62da2abdc0c8c81a0dfcd9f750c48f3a8f85468a24d517967e6c","applied":true,"replayed":false}}}}},"401":{"description":"Authentication is missing or the caller cannot inspect one of the selected records."},"404":{"description":"The account-scoped order or source does not exist."},"422":{"description":"Unsupported source type. Valid account-scoped records return blocking conflicts in the 200 plan.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","example":"invalid_catalog_projection_source"}}},"example":{"error":"invalid_catalog_projection_source"}}}},"403":{"description":"A required feature or module permission is missing."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["catalog_projection"],"properties":{"catalog_projection":{"type":"object","required":["source_type","source_id","order_id"],"properties":{"source_type":{"type":"string","enum":["payments_charge","crm_item"],"example":"payments_charge"},"source_id":{"type":"integer","minimum":1,"example":5821},"order_id":{"type":"integer","minimum":1,"example":9102},"reason":{"type":"string","minLength":1,"maxLength":1000,"description":"Required only when empty charge lines must be reconstructed from the exact linked deal.","example":"Contrato e cobrança conferidos pelo administrador."}}}}},"example":{"catalog_projection":{"source_type":"payments_charge","source_id":5821,"order_id":9102,"reason":"Contrato e cobrança conferidos pelo administrador."}}}}}}},"/api/v1/accounts/{account_id}/commerce/reconciliation_items/catalog_projection_apply":{"post":{"tags":["Commerce"],"operationId":"auto_post_api_v1_accounts_account_id_commerce_reconciliation_items_catalog_projection_apply","summary":"Apply a previewed catalog-line projection","description":"Revalidates and locks the exact sale aggregate, rejects stale fingerprints and blocking conflicts, then atomically writes immutable line snapshots and server-owned provenance. A CRM-deal reconstruction additionally requires an account administrator, a reason and native audit availability. The operation verifies existing inventory receipts but never creates a stock movement.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Applied projection or an idempotent exact replay, with a post-apply plan fingerprint.","content":{"application/json":{"schema":{"type":"object","required":["payload"],"properties":{"payload":{"$ref":"#/components/schemas/commerce_catalog_line_projection"}}},"example":{"payload":{"order":{"id":9102,"account_id":1},"requested_source":{"type":"Payments::Charge","id":5821},"mode":"direct_charge","blocked":false,"conflicts":[{"code":"source_line_items_missing","line_id":734,"count":101,"planned_index":0,"variant_id":87,"receipt_id":912,"error_class":"ArgumentError"}],"planned":{"operation":"project_order","charge_line_items":[{"source_item_id":"payments-charge-line-734","catalog_product_id":41,"catalog_variant_id":87,"name_snapshot":"Plano Comercial","quantity":"1.0","unit_price":"997.0","discount":"0.0","discount_type":"fixed","currency":"BRL","position":0,"line_total":"997.0","metadata":{"provider_item_id":"item_001","catalog_line_projection":{"version":1,"source_type":"Payments::Charge","source_id":5821,"stable_source_item_id":"payments-charge-line-734"}}}],"order_line_items":[{"source_item_id":"payments-charge-line-734","catalog_product_id":41,"catalog_variant_id":87,"name_snapshot":"Plano Comercial","quantity":"1.0","unit_price":"997.0","discount":"0.0","discount_type":"fixed","currency":"BRL","position":0,"line_total":"997.0","metadata":{"provider_item_id":"item_001","catalog_line_projection":{"version":1,"source_type":"Payments::Charge","source_id":5821,"stable_source_item_id":"payments-charge-line-734"}}}],"order_metadata":{"version":1,"mode":"direct_charge","source_type":"Payments::Charge","source_id":5821,"line_count":1,"currency":"BRL","subtotal":"997.0","charge_discount":"0.0","charge_discount_type":"fixed","net_total":"997.0","line_digest":"5904202fbd937b303d34f366e2bd0149b746be65e80acba0f66a4325735b99fb","reconstructed":false,"reconstruction":{"source_type":"Crm::Item","source_id":934,"actor_id":12,"reason":"Contrato conferido pelo administrador."}}},"digest":"63430ddc94fb70c5e529111053055c6a0ce2e9685a270998fdca4db6a2aca60d","fingerprint":"57bd093c095c62da2abdc0c8c81a0dfcd9f750c48f3a8f85468a24d517967e6c","applied":true,"replayed":false}}}}},"401":{"description":"Authentication is missing or the caller cannot update one of the selected records."},"404":{"description":"The account-scoped order or source does not exist."},"422":{"description":"Missing or stale fingerprint, blocking graph conflict, invalid reconstruction authority, or invalid source type.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","example":"catalog_line_changed_since_preview"}}},"example":{"error":"catalog_line_changed_since_preview"}}}},"403":{"description":"A required feature or module permission is missing."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["catalog_projection"],"properties":{"catalog_projection":{"type":"object","required":["source_type","source_id","order_id","fingerprint"],"properties":{"source_type":{"type":"string","enum":["payments_charge","crm_item"],"example":"payments_charge"},"source_id":{"type":"integer","minimum":1,"example":5821},"order_id":{"type":"integer","minimum":1,"example":9102},"reason":{"type":"string","minLength":1,"maxLength":1000,"description":"Required only for an administrator-reviewed reconstruction from exact deal lines.","example":"Contrato e cobrança conferidos pelo administrador."},"fingerprint":{"type":"string","minLength":64,"maxLength":64,"description":"Fingerprint returned by preview for the same source, order, actor and reason.","example":"57bd093c095c62da2abdc0c8c81a0dfcd9f750c48f3a8f85468a24d517967e6c"}}}}},"example":{"catalog_projection":{"source_type":"payments_charge","source_id":5821,"order_id":9102,"fingerprint":"57bd093c095c62da2abdc0c8c81a0dfcd9f750c48f3a8f85468a24d517967e6c","reason":"Contrato e cobrança conferidos pelo administrador."}}}}}}},"/api/v1/accounts/{account_id}/commerce/reconciliation_items/repair_preview":{"post":{"tags":["Commerce"],"operationId":"auto_post_api_v1_accounts_account_id_commerce_reconciliation_items_repair_preview","summary":"Preview a complete sale-association repair","description":"Discovers the account-scoped Payments charge, its directly linked subscription, CRM order and Commerce Recovery event for one sale, then returns a field-level diff, conflicts, historical safeguards and commission impact. Nothing is written. Automatic contact resolution accepts exact identifiers only; a new contact remains a proposal until apply. Duplicate-order consolidation is optional, administrator-only and accepts one gateway-backed canonical order plus manual shadow rows from the same sale.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Complete read-only repair plan and concurrency fingerprint.","content":{"application/json":{"schema":{"type":"object","required":["payload"],"properties":{"payload":{"$ref":"#/components/schemas/commerce_sales_graph_repair"}}},"example":{"payload":{"source":{"type":"payments_charge","id":5821},"target_contact":{"id":4821,"name":"Ana Silva","email":"ana@example.com","phone_number":"+5511999999999","proposed":false,"matched_by":"selected","created":false},"records":[{"source_type":"payments_charge","id":5821,"external_id":"pay_000012345678","status":"paid","contact":{"id":4821,"name":"Ana Silva","email":"ana@example.com","phone_number":"+5511999999999"},"organization_id":27,"crm_item_id":934,"conversation_id":11901,"owner_id":7,"affiliate_id":19,"historical":true,"voided":false}],"changes":[{"source_type":"crm_order","source_id":9102,"field":"contact_id","from":4100,"to":4821}],"conflicts":[{"code":"conversation_contact_mismatch","details":{"source_type":"payments_charge","source_id":5821}}],"blocked":false,"historical":true,"commission_impact":[{"order_id":9102,"paid":true,"owner_id":[7,12],"affiliate_id":[19,31],"requires_confirmation":true}],"consolidation":{"canonical_order_id":9102,"retiring_orders":[{"order_id":9101,"paid":true,"commission_accrual_ids":[],"closed_commission_accrual_ids":[],"closed_commission_statement_ids":[],"stock_movement_id":null,"engagement_event_ids":[],"sales_point_event_ids":[],"commerce_lifecycle_event_id":null,"confirmed_booking_ids":[],"invalidated_team_reward_grant_ids":[],"irreversible_distribution_member_ids":[],"pending_effects":{},"will_ignore_external":false}],"reason":"Duplicate manual record for the canonical gateway charge."},"fingerprint":"57bd093c095c62da2abdc0c8c81a0dfcd9f750c48f3a8f85468a24d517967e6c"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"422":{"description":"Invalid source, contact identity, conversation, association, consolidation or account scope.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","example":"sales_graph_contact_identity_required"}}},"example":{"error":"sales_graph_contact_identity_required"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["sales_graph"],"properties":{"sales_graph":{"type":"object","required":["source_type","source_id","conversation_action"],"properties":{"source_type":{"type":"string","enum":["payments_charge","crm_order","commerce_event"],"example":"payments_charge"},"source_id":{"type":"integer","minimum":1,"example":5821},"contact_id":{"type":"integer","minimum":1,"description":"Existing contact selected inside this account.","example":4821},"contact":{"type":"object","description":"Proposed contact when contact_id is omitted. Requires name and at least one exact identity signal: email, phone/phone_number or doc/tax_id.","properties":{"name":{"type":"string","example":"Ana Silva"},"email":{"type":"string","format":"email","example":"ana@example.com"},"phone":{"type":"string","example":"+5511999999999"},"phone_number":{"type":"string","example":"+5511999999999"},"doc":{"type":"string","example":"19119119100"},"tax_id":{"type":"string","example":"19119119100"}}},"conversation_action":{"type":"string","enum":["preserve","unlink","replace"],"description":"Preserve a compatible conversation, unlink it, or replace it with a conversation belonging to the target contact.","example":"preserve"},"conversation_display_id":{"type":"integer","minimum":1,"description":"Public conversation number selected in the dashboard. Required for replace unless legacy conversation_id is supplied.","example":842},"conversation_id":{"type":"integer","minimum":1,"deprecated":true,"description":"Legacy internal conversation id. Prefer conversation_display_id.","example":11901},"associations":{"type":"object","description":"Optional account-scoped organizational, deal and attribution changes.","properties":{"organization_id":{"type":["integer","null"],"example":27},"crm_item_id":{"type":["integer","null"],"example":934},"owner_id":{"type":["integer","null"],"example":12},"affiliate_id":{"type":["integer","null"],"example":31},"confirm_commission_adjustment":{"type":"boolean","description":"Explicit audited confirmation required before owner or affiliate attribution is applied.","example":true}}},"consolidation":{"type":"object","description":"Administrator-only retirement of manual duplicate orders after strict economic-identity and dependency checks.","required":["canonical_order_id","retiring_order_ids","reason"],"properties":{"canonical_order_id":{"type":"integer","minimum":1,"example":9102},"retiring_order_ids":{"type":"array","minItems":1,"maxItems":100,"uniqueItems":true,"items":{"type":"integer","minimum":1},"example":[9101]},"reason":{"type":"string","minLength":1,"maxLength":1000,"example":"Registro manual duplicado da cobrança canônica"}}}}}}},"example":{"sales_graph":{"source_type":"payments_charge","source_id":5821,"contact_id":4821,"contact":{"name":"Ana Silva","email":"ana@example.com","phone":"+5511999999999","phone_number":"+5511999999999","doc":"19119119100","tax_id":"19119119100"},"conversation_action":"preserve","conversation_display_id":842,"associations":{"organization_id":27,"crm_item_id":934,"owner_id":12,"affiliate_id":31,"confirm_commission_adjustment":true},"consolidation":{"canonical_order_id":9102,"retiring_order_ids":[9101],"reason":"Registro manual duplicado da cobrança canônica"},"conversation_id":11901}}}}}}},"/api/v1/accounts/{account_id}/commerce/reconciliation_items/repair":{"post":{"tags":["Commerce"],"operationId":"auto_post_api_v1_accounts_account_id_commerce_reconciliation_items_repair","summary":"Apply a previewed sale-association repair atomically","description":"Locks and re-discovers the complete sale graph, refuses stale fingerprints or conflicts, optionally creates the proposed contact, and applies every association change in one transaction. Historical projections are internal-only: no recovery message, automation or external conversion is emitted. Financial facts on the canonical order never change. Attribution changes require explicit audited confirmation. An approved duplicate consolidation keeps the canonical payment order and archives only the selected manual shadow rows through the governed order-void service.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Applied graph, including any historical internal projections and the new post-apply fingerprint.","content":{"application/json":{"schema":{"type":"object","required":["payload"],"properties":{"payload":{"$ref":"#/components/schemas/commerce_sales_graph_repair"}}},"example":{"payload":{"source":{"type":"payments_charge","id":5821},"target_contact":{"id":4821,"name":"Ana Silva","email":"ana@example.com","phone_number":"+5511999999999","proposed":false,"matched_by":"selected","created":false},"records":[{"source_type":"payments_charge","id":5821,"external_id":"pay_000012345678","status":"paid","contact":{"id":4821,"name":"Ana Silva","email":"ana@example.com","phone_number":"+5511999999999"},"organization_id":27,"crm_item_id":934,"conversation_id":11901,"owner_id":7,"affiliate_id":19,"historical":true,"voided":false}],"changes":[{"source_type":"crm_order","source_id":9102,"field":"contact_id","from":4100,"to":4821}],"conflicts":[{"code":"conversation_contact_mismatch","details":{"source_type":"payments_charge","source_id":5821}}],"blocked":false,"historical":true,"commission_impact":[{"order_id":9102,"paid":true,"owner_id":[7,12],"affiliate_id":[19,31],"requires_confirmation":true}],"consolidation":{"canonical_order_id":9102,"retiring_orders":[{"order_id":9101,"paid":true,"commission_accrual_ids":[],"closed_commission_accrual_ids":[],"closed_commission_statement_ids":[],"stock_movement_id":null,"engagement_event_ids":[],"sales_point_event_ids":[],"commerce_lifecycle_event_id":null,"confirmed_booking_ids":[],"invalidated_team_reward_grant_ids":[],"irreversible_distribution_member_ids":[],"pending_effects":{},"will_ignore_external":false}],"reason":"Duplicate manual record for the canonical gateway charge."},"fingerprint":"57bd093c095c62da2abdc0c8c81a0dfcd9f750c48f3a8f85468a24d517967e6c"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"422":{"description":"Invalid or stale preview, blocking conflict, cross-account association, or missing commission confirmation.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","example":"sales_graph_changed_since_preview"}}},"example":{"error":"sales_graph_changed_since_preview"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["sales_graph"],"properties":{"sales_graph":{"type":"object","required":["source_type","source_id","conversation_action","fingerprint"],"properties":{"source_type":{"type":"string","enum":["payments_charge","crm_order","commerce_event"],"example":"payments_charge"},"source_id":{"type":"integer","minimum":1,"example":5821},"contact_id":{"type":"integer","minimum":1,"description":"Existing contact selected inside this account.","example":4821},"contact":{"type":"object","description":"Proposed contact created only inside the successful apply transaction.","properties":{"name":{"type":"string","example":"Ana Silva"},"email":{"type":"string","format":"email","example":"ana@example.com"},"phone":{"type":"string","example":"+5511999999999"},"phone_number":{"type":"string","example":"+5511999999999"},"doc":{"type":"string","example":"19119119100"},"tax_id":{"type":"string","example":"19119119100"}}},"conversation_action":{"type":"string","enum":["preserve","unlink","replace"],"example":"preserve"},"conversation_display_id":{"type":"integer","minimum":1,"description":"Public conversation number selected in the dashboard. Required for replace unless legacy conversation_id is supplied.","example":842},"conversation_id":{"type":"integer","minimum":1,"deprecated":true,"description":"Legacy internal conversation id. Prefer conversation_display_id.","example":11901},"associations":{"type":"object","properties":{"organization_id":{"type":["integer","null"],"example":27},"crm_item_id":{"type":["integer","null"],"example":934},"owner_id":{"type":["integer","null"],"example":12},"affiliate_id":{"type":["integer","null"],"example":31},"confirm_commission_adjustment":{"type":"boolean","example":true}}},"consolidation":{"type":"object","description":"Must exactly match the consolidation reviewed in preview.","required":["canonical_order_id","retiring_order_ids","reason"],"properties":{"canonical_order_id":{"type":"integer","minimum":1,"example":9102},"retiring_order_ids":{"type":"array","minItems":1,"maxItems":100,"uniqueItems":true,"items":{"type":"integer","minimum":1},"example":[9101]},"reason":{"type":"string","minLength":1,"maxLength":1000,"example":"Registro manual duplicado da cobrança canônica"}}},"fingerprint":{"type":"string","minLength":64,"maxLength":64,"description":"Fingerprint returned by preview for these exact choices.","example":"57bd093c095c62da2abdc0c8c81a0dfcd9f750c48f3a8f85468a24d517967e6c"}}}}},"example":{"sales_graph":{"source_type":"payments_charge","source_id":5821,"contact_id":4821,"contact":{"name":"Ana Silva","email":"ana@example.com","phone":"+5511999999999","phone_number":"+5511999999999","doc":"19119119100","tax_id":"19119119100"},"conversation_action":"preserve","conversation_display_id":842,"associations":{"organization_id":27,"crm_item_id":934,"owner_id":12,"affiliate_id":31,"confirm_commission_adjustment":true},"consolidation":{"canonical_order_id":9102,"retiring_order_ids":[9101],"reason":"Registro manual duplicado da cobrança canônica"},"fingerprint":"57bd093c095c62da2abdc0c8c81a0dfcd9f750c48f3a8f85468a24d517967e6c","conversation_id":11901}}}}}}},"/api/v1/accounts/{account_id}/commerce/reconciliation_items":{"get":{"tags":["Commerce"],"operationId":"auto_get_api_v1_accounts_account_id_commerce_reconciliation_items","summary":"List reconciliation items","description":"Returns the list of reconciliation items visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Account-scoped reconciliation rows with current customer and commercial context. Protected fields are masked or omitted according to the caller's field-level permissions.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/commerce_reconciliation_items_response"},"example":{"payload":[{"id":41,"source_type":"payments_charge","source_id":5821,"state":"pending","reason":"charge_without_order_link","suggestions":[{"source_type":"crm_order","source_id":9102,"confidence":1.0,"reason":"exact_gateway_external_id"}],"resolution":{"operation":"link","relationship_key":"charge:5821:order:9102","source_type":"payments_charge","source_id":5821,"target_type":"crm_order","target_id":9102,"reason":"operator_ignored","ignored_external_id":73,"ignored_external_created":true,"canonical_item_id":40,"fingerprint":"57bd093c095c62da2abdc0c8c81a0dfcd9f750c48f3a8f85468a24d517967e6c"},"resolved_at":"2026-08-14T12:30:00Z","resolved_by_id":7,"created_at":"2026-08-14T11:00:00Z","updated_at":"2026-08-14T12:30:00Z","source":null}],"meta":{"count":42,"current_page":1,"total_pages":2,"per_page":25,"has_more":true}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"422":{"description":"A state, source type, sort field or direction was outside the closed query vocabulary."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"q","in":"query","required":false,"description":"Exact source id or case-insensitive reconciliation reason search.","schema":{"type":"string"},"example":"charge_without_order_link"},{"name":"state","in":"query","required":false,"schema":{"type":"string","enum":["pending","linked","ignored","duplicate"]},"example":"pending"},{"name":"source_type","in":"query","required":false,"schema":{"type":"string","enum":["payments_charge","crm_order","commerce_event"]},"example":"payments_charge"},{"name":"sort","in":"query","required":false,"schema":{"type":"string","enum":["created_at","state","source_type","source_id"],"default":"created_at"},"example":"created_at"},{"name":"direction","in":"query","required":false,"schema":{"type":"string","enum":["asc","desc"],"default":"desc"},"example":"desc"},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1},"example":1},{"name":"per_page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"example":25}]}},"/api/v1/accounts/{account_id}/commerce/settings/preview":{"post":{"tags":["Commerce"],"operationId":"auto_post_api_v1_accounts_account_id_commerce_settings_preview","summary":"Preview settings","description":"Performs the preview operation on the targeted setting resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The rendered body per channel plus the resolved out-of-window template. Nothing is persisted.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"locale":{"type":"string","description":"The locale the preview rendered in.","example":"pt_BR"},"sample_present":{"type":"boolean","description":"False when the account has no record of this module yet — the variables then render blank.","example":true},"variables":{"type":"object","description":"The resolved variable map of the module drop (token -\u003e value). Keys are module-specific.","additionalProperties":{"type":"string"},"example":{"amount":"99.0","currency":"BRL","pay_url":"https://checkout.example/c/1","stage":"cart_abandoned"}},"rendered":{"type":"string","description":"The body with its Liquid resolved (before per-channel rendering).","example":"Olá Ana Silva, seu carrinho ainda está aberto: https://checkout.example/c/1"},"rendered_by_channel":{"type":"object","description":"One entry per channel type the ACCOUNT has an inbox of, rendered by Messages::MarkdownRendererService.","additionalProperties":{"type":"string"},"example":{"Channel::Whatsapp":"Olá Ana Silva, seu carrinho ainda está aberto: https://checkout.example/c/1"}},"buttons":{"type":"array","description":"The NATIVE interactive buttons the send will attach for this type, already capped to what the chosen provider renders — Meta's `cta_url` carries exactly ONE button, so a second one is dropped here rather than promised. Empty when the type ships no button, the operator turned the switch off, or the channel has no interactive surface.","items":{"type":"object","properties":{"type":{"type":"string","enum":["cta_url","cta_copy"],"description":"cta_url opens a link; cta_copy copies a code to the clipboard (WhatsApp Web / API only).","example":"cta_url"},"text":{"type":"string","description":"The button caption","from the module's auxiliary labels.":null,"example":"Pagar agora"},"url":{"type":"string","description":"Present for cta_url.","example":"https://checkout.example/c/1"},"code":{"type":"string","description":"Present for cta_copy.","example":"00020126580014BR.GOV.BCB.PIX"}}},"example":[{"type":"cta_url","text":"Pagar agora","url":"https://checkout.example/c/1"}]},"defaults":{"type":"object","description":"The SHIPPED copy behind each key named in the request's `types` / `labels` — what an empty cell actually sends, so the editor can show it instead of only claiming it exists. Both maps are empty when the account has no record of this module yet (the shipped lines interpolate that record and are never fabricated).","properties":{"bodies":{"type":"object","description":"message type -\u003e shipped body, in the previewed locale.","additionalProperties":{"type":"string"},"example":{"cart_abandoned":"Abandoned cart"}},"labels":{"type":"object","description":"label key -\u003e shipped text, in the previewed locale.","additionalProperties":{"type":"string"},"example":{"pay_label":"Pay / resume:"}}}},"hsm":{"type":["object","null"],"description":"The resolved out-of-window template params, or null when none applies.","properties":{"name":{"type":"string","example":"commerce_cart_abandoned_pt_br"},"language":{"type":"string","example":"pt_BR"},"processed_params":{"type":"object","description":"Meta component params: `body` is a 1-indexed map, `buttons` is present only for a dynamic URL button.","additionalProperties":true,"example":{"body":{"1":"BRL 99.00"}}}}}}}}},"example":{"payload":{"locale":"pt_BR","sample_present":true,"variables":{"amount":"99.0","currency":"BRL","pay_url":"https://checkout.example/c/1","stage":"cart_abandoned"},"rendered":"Olá Ana Silva, seu carrinho ainda está aberto: https://checkout.example/c/1","rendered_by_channel":{"Channel::Whatsapp":"Olá Ana Silva, seu carrinho ainda está aberto: https://checkout.example/c/1"},"buttons":[{"type":"cta_url","text":"Pagar agora","url":"https://checkout.example/c/1","code":"00020126580014BR.GOV.BCB.PIX"}],"defaults":{"bodies":{"cart_abandoned":"Abandoned cart"},"labels":{"pay_label":"Pay / resume:"}},"hsm":{"name":"commerce_cart_abandoned_pt_br","language":"pt_BR","processed_params":{"body":{"1":"BRL 99.00"}}}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"The unsaved cell the operator is looking at — nothing is persisted.","properties":{"type":{"type":"string","description":"Message type being previewed.","example":"cart_abandoned"},"locale":{"type":"string","description":"Locale to render in; omitted falls back to the record cascade (contact -\u003e conversation -\u003e account).","example":"pt_BR"},"body":{"type":"string","description":"Markdown body with `{{ variable }}` tokens, exactly as authored in the editor.","example":"Olá {{ contact.name }}, seu carrinho ainda está aberto: {{ commerce.pay_url }}"},"scope":{"type":["string","null"],"description":"Per-surface override scope (e.g. `automation:12`). Omit for the account default.","example":"automation:12"},"whatsapp_template":{"type":"object","description":"The approved HSM the editor is holding. Omitted, the stored per-type x per-locale template is resolved instead.","properties":{"name":{"type":"string","example":"commerce_cart_abandoned_pt_br"},"language":{"type":"string","example":"pt_BR"},"url_button":{"type":"string","description":"Variable name or literal filling a dynamic URL button.","example":"pay_url"},"params":{"type":"array","description":"Positional body params: a variable name resolves from the message variable map, anything else is a literal.","items":{"type":"string"},"example":["amount"]}}}}},"example":{"type":"cart_abandoned","locale":"pt_BR","body":"Olá {{ contact.name }}, seu carrinho ainda está aberto: {{ commerce.pay_url }}","scope":"automation:12","whatsapp_template":{"name":"commerce_cart_abandoned_pt_br","language":"pt_BR","url_button":"pay_url","params":["amount"]}}}}}}},"/api/v1/accounts/{account_id}/commerce/settings/test_send":{"post":{"tags":["Commerce"],"operationId":"auto_post_api_v1_accounts_account_id_commerce_settings_test_send","summary":"Test send settings","description":"Performs the test send operation on the targeted setting resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The outcome of the send, which honours the WhatsApp 24h window exactly as the real sender does.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"status":{"type":"string","enum":["sent","skipped","failed"],"description":"sent = a message was created; skipped = nothing was sent (see reason); failed = the send raised.","example":"sent"},"reason":{"type":["string","null"],"description":"Canonical skip/failure reason: `whatsapp_window_closed` (the 24h window is closed and no approved template is configured) or `empty_body`. Null when sent.","example":"whatsapp_window_closed"},"content":{"type":"string","description":"The rendered body that was sent (or would have been).","example":"Olá Ana Silva, seu carrinho ainda está aberto: https://checkout.example/c/1"},"message_id":{"type":["integer","null"],"description":"The created message id; null on skip/failure.","example":9001}}}}},"example":{"payload":{"status":"sent","reason":"whatsapp_window_closed","content":"Olá Ana Silva, seu carrinho ainda está aberto: https://checkout.example/c/1","message_id":9001}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"422":{"description":"No conversation was given (`conversation_required`), so there is nothing to send into.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"conversation_required"}}},"example":{"error":"conversation_required"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["conversation_id"],"description":"Sends ONE real message into an EXISTING conversation. Never creates a conversation.","properties":{"conversation_id":{"type":"string","description":"Conversation display_id (an internal id is accepted as a fallback).","example":"42"},"type":{"type":"string","description":"Message type being tested.","example":"cart_abandoned"},"locale":{"type":"string","example":"pt_BR"},"body":{"type":"string","description":"Markdown body","exactly as authored in the editor.":null,"example":"Olá {{ contact.name }}, seu carrinho ainda está aberto: {{ commerce.pay_url }}"},"scope":{"type":["string","null"],"example":"automation:12"},"whatsapp_template":{"type":"object","description":"The approved HSM the editor is holding, used when the 24h window is closed.","properties":{"name":{"type":"string","example":"commerce_cart_abandoned_pt_br"},"language":{"type":"string","example":"pt_BR"},"url_button":{"type":"string","example":"pay_url"},"params":{"type":"array","items":{"type":"string"},"example":["amount"]}}}}},"example":{"conversation_id":"42","type":"cart_abandoned","locale":"pt_BR","body":"Olá {{ contact.name }}, seu carrinho ainda está aberto: {{ commerce.pay_url }}","scope":"automation:12","whatsapp_template":{"name":"commerce_cart_abandoned_pt_br","language":"pt_BR","url_button":"pay_url","params":["amount"]}}}}}}},"/api/v1/accounts/{account_id}/commerce/settings":{"get":{"tags":["Commerce"],"operationId":"auto_get_api_v1_accounts_account_id_commerce_settings","summary":"Get commerce recovery settings","description":"Returns resolved recovery copy, delivery settings and the per-stage automatic cadence. Every cadence stage defaults to false unless the account explicitly opted in. `due_soon` is retained only as a historical stored stage and is not offered because no producer emits it.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"properties":{"payload":{"properties":{"cadence":{"type":["object","null"],"description":"Null only for a raw scoped read with no cadence override.","properties":{"stages":{"type":"object","additionalProperties":false,"properties":{"cart_abandoned":{"type":"boolean","default":false},"payment_pending":{"type":"boolean","default":false},"payment_declined":{"type":"boolean","default":false},"overdue":{"type":"boolean","default":false}}}}}}}}},"example":{"payload":{"cadence":{"stages":{"cart_abandoned":false,"payment_pending":false,"payment_declined":false,"overdue":false}}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]},"patch":{"tags":["Commerce"],"operationId":"auto_patch_api_v1_accounts_account_id_commerce_settings","summary":"Update commerce recovery settings","description":"Deep-merges the supplied settings. Automatic delivery remains off for every omitted stage and always excludes imported or adopted lifecycle history.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"properties":{"payload":{"properties":{"cadence":{"type":"object","properties":{"stages":{"type":"object","additionalProperties":false,"properties":{"cart_abandoned":{"type":"boolean","default":false},"payment_pending":{"type":"boolean","default":false},"payment_declined":{"type":"boolean","default":false},"overdue":{"type":"boolean","default":false}}}}}}}}},"example":{"payload":{"cadence":{"stages":{"cart_abandoned":false,"payment_pending":false,"payment_declined":false,"overdue":false}}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"scope":{"type":["string","null"],"example":"automation:12"},"cadence":{"type":"object","properties":{"stages":{"type":"object","additionalProperties":false,"properties":{"cart_abandoned":{"type":"boolean","default":false},"payment_pending":{"type":"boolean","default":false},"payment_declined":{"type":"boolean","default":false},"overdue":{"type":"boolean","default":false}}}}}},"example":{"cadence":{"stages":{"cart_abandoned":true,"payment_pending":false,"payment_declined":false,"overdue":true}}}},"example":{"cadence":{"stages":{"cart_abandoned":true,"payment_pending":false,"payment_declined":false,"overdue":true}},"scope":"automation:12"}}}}},"put":{"tags":["Commerce"],"operationId":"auto_put_api_v1_accounts_account_id_commerce_settings","summary":"Update commerce recovery settings","description":"Deep-merges the supplied settings. Automatic delivery remains off for every omitted stage and always excludes imported or adopted lifecycle history.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"properties":{"payload":{"properties":{"cadence":{"type":"object","properties":{"stages":{"type":"object","additionalProperties":false,"properties":{"cart_abandoned":{"type":"boolean","default":false},"payment_pending":{"type":"boolean","default":false},"payment_declined":{"type":"boolean","default":false},"overdue":{"type":"boolean","default":false}}}}}}}}},"example":{"payload":{"cadence":{"stages":{"cart_abandoned":false,"payment_pending":false,"payment_declined":false,"overdue":false}}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"scope":{"type":["string","null"],"example":"automation:12"},"cadence":{"type":"object","properties":{"stages":{"type":"object","additionalProperties":false,"properties":{"cart_abandoned":{"type":"boolean","default":false},"payment_pending":{"type":"boolean","default":false},"payment_declined":{"type":"boolean","default":false},"overdue":{"type":"boolean","default":false}}}}}},"example":{"cadence":{"stages":{"cart_abandoned":true,"payment_pending":false,"payment_declined":false,"overdue":true}}}},"example":{"cadence":{"stages":{"cart_abandoned":true,"payment_pending":false,"payment_declined":false,"overdue":true}},"scope":"automation:12"}}}}},"delete":{"tags":["Commerce"],"operationId":"auto_delete_api_v1_accounts_account_id_commerce_settings","summary":"Delete settings","description":"Deletes the setting identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"scope":{"type":"string"},"messages":{"type":"string"},"delivery":{"type":"string"},"cadence":{"type":"string"}}}}},"example":{"payload":{"scope":"sample scope","messages":"sample messages","delivery":"sample delivery","cadence":"sample cadence"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/message_schedules/preview":{"post":{"tags":["Message Schedules"],"operationId":"auto_post_api_v1_accounts_account_id_message_schedules_preview","summary":"Preview a message schedule without persisting it","description":"Normalizes the outbound draft, resolves every policy layer, validates channel capability and returns the next five civil occurrences. It creates neither a schedule nor a message.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Authoritative normalized preview.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","additionalProperties":false,"properties":{"name":{"type":"string","example":"Appointment reminder"},"kind":{"type":"string","enum":["one_time","sequence","recurring_single","recurring_sequence"],"example":"one_time","description":"Temporal shape of the scheduled message plan."},"starts_at":{"type":"string","format":"date-time","example":"2026-08-22T13:00:00.000Z"},"timezone":{"type":"string","example":"America/Sao_Paulo"},"rrule":{"type":["string","null"],"example":null},"recurrence":{"type":["object","null"],"additionalProperties":true,"description":"Normalized recurrence authoring object, or null for non-recurring kinds."},"policy_overrides":{"type":"object","additionalProperties":false,"description":"Explicit schedule-level overrides; omitted leaves inherit from inbox/account.","properties":{"on_inbound_reply":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["continue","pause","cancel","skip"],"example":"pause"}}},"on_conversation_resolved":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["continue","pause","cancel","skip"],"example":"continue"}}},"misfire":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["skip","manual_review","send_latest","catch_up_bounded"],"example":"send_latest"},"grace_seconds":{"type":"integer","minimum":0,"example":60},"max_occurrences":{"type":"integer","minimum":1,"maximum":500,"example":10},"spacing_seconds":{"type":"integer","minimum":0,"example":5}}},"transient_failure":{"type":"object","additionalProperties":false,"properties":{"max_attempts":{"type":"integer","minimum":1,"maximum":10,"example":3},"backoff_seconds":{"type":"array","maxItems":9,"items":{"type":"integer","minimum":0,"maximum":86400},"example":[30,120]},"exhausted_action":{"type":"string","enum":["skip","pause","cancel","manual_review"],"example":"manual_review"}}},"permanent_failure":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["skip","pause","cancel","manual_review"],"example":"manual_review"}}},"resume_behavior":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["preserve_schedule","shift_by_pause","skip_missed","catch_up_bounded"],"example":"preserve_schedule"},"max_occurrences":{"type":"integer","minimum":1,"maximum":500,"example":10},"spacing_seconds":{"type":"integer","minimum":0,"example":5}}},"quiet_hours":{"type":"object","additionalProperties":false,"properties":{"enabled":{"type":"boolean","example":false},"start":{"type":"string","pattern":"^(?:[01][0-9]|2[0-3]):[0-5][0-9]$","example":"22:00"},"end":{"type":"string","pattern":"^(?:[01][0-9]|2[0-3]):[0-5][0-9]$","example":"08:00"},"days":{"type":"array","uniqueItems":true,"items":{"type":"integer","minimum":0,"maximum":6},"example":[0,1,2,3,4,5,6]},"action":{"type":"string","enum":["allow","defer","skip","manual_review"],"example":"defer"}}},"overlap":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["allow","skip_new","defer_new","cancel_previous","manual_review"],"example":"allow"},"defer_seconds":{"type":"integer","minimum":1,"example":60}}},"inbox_change":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["follow_logical","cancel","pause","manual_review"],"example":"follow_logical"}}},"sender":{"type":"object","additionalProperties":false,"properties":{"type":{"type":"string","enum":["assigned_agent","schedule_creator","user","agent_bot","system"],"example":"system"},"id":{"type":["integer","null"],"minimum":1,"example":null},"missing":{"type":"string","enum":["fail","system","assigned_agent"],"example":"fail"}}},"variables":{"type":"object","additionalProperties":false,"properties":{"resolve_at":{"type":"string","enum":["publication","dispatch"],"example":"dispatch"},"missing":{"type":"string","enum":["fail","blank","skip"],"example":"fail"}}},"dst":{"type":"object","additionalProperties":false,"properties":{"nonexistent":{"type":"string","enum":["skip","shift_forward","shift_backward"],"example":"shift_forward"},"ambiguous":{"type":"string","enum":["first","second","skip"],"example":"first"}}},"materialization":{"type":"object","additionalProperties":false,"properties":{"horizon_seconds":{"type":"integer","minimum":1,"maximum":2592000,"example":2592000},"max_occurrences":{"type":"integer","minimum":1,"maximum":500,"example":500}}},"claim":{"type":"object","additionalProperties":false,"properties":{"lease_seconds":{"type":"integer","minimum":1,"maximum":900,"example":120},"recovery_grace_seconds":{"type":"integer","minimum":0,"maximum":3600,"example":30}}}}},"sender_config":{"type":"object","additionalProperties":true,"description":"Server-authored sender context."},"target_config":{"type":"object","additionalProperties":true,"description":"Server-authored target context."},"resolved_items":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"client_id":{"type":"string","example":"item-1"},"position":{"type":"integer","example":1},"timing":{"type":"object","additionalProperties":true,"description":"Normalized anchor and offset."},"policy_overrides":{"type":"object","additionalProperties":false,"description":"Explicit schedule-level overrides; omitted leaves inherit from inbox/account.","properties":{"on_inbound_reply":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["continue","pause","cancel","skip"],"example":"pause"}}},"on_conversation_resolved":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["continue","pause","cancel","skip"],"example":"continue"}}},"misfire":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["skip","manual_review","send_latest","catch_up_bounded"],"example":"send_latest"},"grace_seconds":{"type":"integer","minimum":0,"example":60},"max_occurrences":{"type":"integer","minimum":1,"maximum":500,"example":10},"spacing_seconds":{"type":"integer","minimum":0,"example":5}}},"transient_failure":{"type":"object","additionalProperties":false,"properties":{"max_attempts":{"type":"integer","minimum":1,"maximum":10,"example":3},"backoff_seconds":{"type":"array","maxItems":9,"items":{"type":"integer","minimum":0,"maximum":86400},"example":[30,120]},"exhausted_action":{"type":"string","enum":["skip","pause","cancel","manual_review"],"example":"manual_review"}}},"permanent_failure":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["skip","pause","cancel","manual_review"],"example":"manual_review"}}},"resume_behavior":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["preserve_schedule","shift_by_pause","skip_missed","catch_up_bounded"],"example":"preserve_schedule"},"max_occurrences":{"type":"integer","minimum":1,"maximum":500,"example":10},"spacing_seconds":{"type":"integer","minimum":0,"example":5}}},"quiet_hours":{"type":"object","additionalProperties":false,"properties":{"enabled":{"type":"boolean","example":false},"start":{"type":"string","pattern":"^(?:[01][0-9]|2[0-3]):[0-5][0-9]$","example":"22:00"},"end":{"type":"string","pattern":"^(?:[01][0-9]|2[0-3]):[0-5][0-9]$","example":"08:00"},"days":{"type":"array","uniqueItems":true,"items":{"type":"integer","minimum":0,"maximum":6},"example":[0,1,2,3,4,5,6]},"action":{"type":"string","enum":["allow","defer","skip","manual_review"],"example":"defer"}}},"overlap":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["allow","skip_new","defer_new","cancel_previous","manual_review"],"example":"allow"},"defer_seconds":{"type":"integer","minimum":1,"example":60}}},"inbox_change":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["follow_logical","cancel","pause","manual_review"],"example":"follow_logical"}}},"sender":{"type":"object","additionalProperties":false,"properties":{"type":{"type":"string","enum":["assigned_agent","schedule_creator","user","agent_bot","system"],"example":"system"},"id":{"type":["integer","null"],"minimum":1,"example":null},"missing":{"type":"string","enum":["fail","system","assigned_agent"],"example":"fail"}}},"variables":{"type":"object","additionalProperties":false,"properties":{"resolve_at":{"type":"string","enum":["publication","dispatch"],"example":"dispatch"},"missing":{"type":"string","enum":["fail","blank","skip"],"example":"fail"}}},"dst":{"type":"object","additionalProperties":false,"properties":{"nonexistent":{"type":"string","enum":["skip","shift_forward","shift_backward"],"example":"shift_forward"},"ambiguous":{"type":"string","enum":["first","second","skip"],"example":"first"}}},"materialization":{"type":"object","additionalProperties":false,"properties":{"horizon_seconds":{"type":"integer","minimum":1,"maximum":2592000,"example":2592000},"max_occurrences":{"type":"integer","minimum":1,"maximum":500,"example":500}}},"claim":{"type":"object","additionalProperties":false,"properties":{"lease_seconds":{"type":"integer","minimum":1,"maximum":900,"example":120},"recovery_grace_seconds":{"type":"integer","minimum":0,"maximum":3600,"example":30}}}}},"normalized_draft":{"type":"object","additionalProperties":false,"required":["parts"],"properties":{"version":{"type":"integer","enum":[1],"example":1},"schema_version":{"type":"integer","enum":[1],"example":1},"delay_ms":{"type":"integer","minimum":0,"maximum":300000,"example":0},"parts":{"type":"array","minItems":1,"maxItems":50,"items":{"type":"object","additionalProperties":false,"properties":{"content":{"type":"string","maxLength":150000,"example":"Olá, seu atendimento está marcado para amanhã."},"content_type":{"type":"string","enum":["text","input_select","sticker","poll"],"example":"text"},"content_attributes":{"type":"object","additionalProperties":false,"description":"Closed outbound metadata roots; rich provider objects remain JSON-shaped and are revalidated before dispatch.","properties":{"in_reply_to":{"type":"integer","example":88},"in_reply_to_external_id":{"type":"string","example":"wamid.example"},"items":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Provider-native option object."}},"email":{"type":"object","additionalProperties":true,"description":"Structured outbound e-mail metadata."},"interactive":{"type":"object","additionalProperties":true,"description":"WhatsApp Cloud interactive payload."},"wa_interactive":{"type":"object","additionalProperties":true,"description":"WazMeow interactive payload."},"poll":{"type":"object","additionalProperties":true,"description":"Poll payload."},"catalog_product":{"type":"object","additionalProperties":true,"description":"Catalog product payload."},"media_kind":{"type":"string","enum":["image","video","audio","document","sticker"],"example":"image"},"view_once":{"type":"boolean","example":false},"mention_all":{"type":"boolean","example":false},"mentioned_jids":{"type":"array","items":{"type":"string"},"example":[]},"mentions":{"type":"object","additionalProperties":true,"description":"Mention map keyed by provider identifier."},"is_forwarded":{"type":"boolean","example":false},"link_preview":{"type":"object","additionalProperties":true,"description":"Link preview metadata."},"location":{"type":"object","additionalProperties":true,"description":"Location payload."},"contact":{"type":"object","additionalProperties":true,"description":"Contact card payload."},"cta_buttons":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Call-to-action button."}}}},"attachments":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["signed_id"],"properties":{"signed_id":{"type":"string","description":"ActiveStorage signed blob id.","example":"eyJfcmFpbHMiOnsibWVzc2FnZSI6ImJsb2IifX0"},"filename":{"type":"string","example":"reminder.pdf"},"content_type":{"type":"string","example":"application/pdf"},"byte_size":{"type":"integer","minimum":0,"example":2048}}}},"items":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Structured select or poll option."}},"is_voice_message":{"type":"boolean","example":false},"email_html_content":{"type":"string","example":"\u003cp\u003eAppointment reminder\u003c/p\u003e"},"to_emails":{"type":"array","items":{"type":"string","format":"email"},"example":["customer@example.com"]},"cc_emails":{"type":"array","items":{"type":"string","format":"email"},"example":[]},"bcc_emails":{"type":"array","items":{"type":"string","format":"email"},"example":[]},"template_params":{"type":"object","additionalProperties":true,"description":"Approved template identity and parameters."},"flow_params":{"type":"object","additionalProperties":true,"description":"WhatsApp Flow identity and parameters."},"whatsapp_transport":{"type":"string","enum":["cloud","web"],"example":"cloud"}}}},"attachments":{"type":"array","description":"Union of the signed attachment references present in parts.","items":{"type":"object","additionalProperties":false,"required":["signed_id"],"properties":{"signed_id":{"type":"string","description":"ActiveStorage signed blob id.","example":"eyJfcmFpbHMiOnsibWVzc2FnZSI6ImJsb2IifX0"},"filename":{"type":"string","example":"reminder.pdf"},"content_type":{"type":"string","example":"application/pdf"},"byte_size":{"type":"integer","minimum":0,"example":2048}}}}}},"resolved_policies":{"type":"object","additionalProperties":false,"properties":{"policy":{"type":"object","additionalProperties":false,"description":"Explicit schedule-level overrides; omitted leaves inherit from inbox/account.","properties":{"on_inbound_reply":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["continue","pause","cancel","skip"],"example":"pause"}}},"on_conversation_resolved":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["continue","pause","cancel","skip"],"example":"continue"}}},"misfire":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["skip","manual_review","send_latest","catch_up_bounded"],"example":"send_latest"},"grace_seconds":{"type":"integer","minimum":0,"example":60},"max_occurrences":{"type":"integer","minimum":1,"maximum":500,"example":10},"spacing_seconds":{"type":"integer","minimum":0,"example":5}}},"transient_failure":{"type":"object","additionalProperties":false,"properties":{"max_attempts":{"type":"integer","minimum":1,"maximum":10,"example":3},"backoff_seconds":{"type":"array","maxItems":9,"items":{"type":"integer","minimum":0,"maximum":86400},"example":[30,120]},"exhausted_action":{"type":"string","enum":["skip","pause","cancel","manual_review"],"example":"manual_review"}}},"permanent_failure":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["skip","pause","cancel","manual_review"],"example":"manual_review"}}},"resume_behavior":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["preserve_schedule","shift_by_pause","skip_missed","catch_up_bounded"],"example":"preserve_schedule"},"max_occurrences":{"type":"integer","minimum":1,"maximum":500,"example":10},"spacing_seconds":{"type":"integer","minimum":0,"example":5}}},"quiet_hours":{"type":"object","additionalProperties":false,"properties":{"enabled":{"type":"boolean","example":false},"start":{"type":"string","pattern":"^(?:[01][0-9]|2[0-3]):[0-5][0-9]$","example":"22:00"},"end":{"type":"string","pattern":"^(?:[01][0-9]|2[0-3]):[0-5][0-9]$","example":"08:00"},"days":{"type":"array","uniqueItems":true,"items":{"type":"integer","minimum":0,"maximum":6},"example":[0,1,2,3,4,5,6]},"action":{"type":"string","enum":["allow","defer","skip","manual_review"],"example":"defer"}}},"overlap":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["allow","skip_new","defer_new","cancel_previous","manual_review"],"example":"allow"},"defer_seconds":{"type":"integer","minimum":1,"example":60}}},"inbox_change":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["follow_logical","cancel","pause","manual_review"],"example":"follow_logical"}}},"sender":{"type":"object","additionalProperties":false,"properties":{"type":{"type":"string","enum":["assigned_agent","schedule_creator","user","agent_bot","system"],"example":"system"},"id":{"type":["integer","null"],"minimum":1,"example":null},"missing":{"type":"string","enum":["fail","system","assigned_agent"],"example":"fail"}}},"variables":{"type":"object","additionalProperties":false,"properties":{"resolve_at":{"type":"string","enum":["publication","dispatch"],"example":"dispatch"},"missing":{"type":"string","enum":["fail","blank","skip"],"example":"fail"}}},"dst":{"type":"object","additionalProperties":false,"properties":{"nonexistent":{"type":"string","enum":["skip","shift_forward","shift_backward"],"example":"shift_forward"},"ambiguous":{"type":"string","enum":["first","second","skip"],"example":"first"}}},"materialization":{"type":"object","additionalProperties":false,"properties":{"horizon_seconds":{"type":"integer","minimum":1,"maximum":2592000,"example":2592000},"max_occurrences":{"type":"integer","minimum":1,"maximum":500,"example":500}}},"claim":{"type":"object","additionalProperties":false,"properties":{"lease_seconds":{"type":"integer","minimum":1,"maximum":900,"example":120},"recovery_grace_seconds":{"type":"integer","minimum":0,"maximum":3600,"example":30}}}}},"sources":{"type":"object","additionalProperties":{"type":"string"},"description":"Effective source keyed by policy path."},"fields":{"type":"object","additionalProperties":{"type":"object","additionalProperties":false,"properties":{"value":{"description":"Resolved scalar, null or integer-array policy value.","oneOf":[{"type":"string"},{"type":"integer"},{"type":"boolean"},{"type":"null"},{"type":"array","items":{"type":"integer"}}]},"source":{"type":["string","null"],"example":"account"}}},"description":"Resolved value and source keyed by policy path."}}},"policy_sources":{"type":"object","additionalProperties":{"type":"string"},"description":"Effective source keyed by policy path."},"blockers":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Actionable validation issue with at least a stable code and item position.","properties":{"code":{"type":"string","example":"policy_incomplete"},"item_position":{"type":"integer","example":1},"client_id":{"type":"string","example":"item-1"},"detail":{"type":"string","example":"sender.type is required"}}}},"warnings":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Actionable validation issue with at least a stable code and item position.","properties":{"code":{"type":"string","example":"policy_incomplete"},"item_position":{"type":"integer","example":1},"client_id":{"type":"string","example":"item-1"},"detail":{"type":"string","example":"sender.type is required"}}}},"next5":{"type":"array","maxItems":5,"items":{"type":"string","format":"date-time"}},"effective_target":{"type":"object","additionalProperties":true,"description":"Logical and physical delivery target projection."},"capability":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Capability row for one draft part."}},"capabilities":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Capability row for one draft part."}}}}},"blockers":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Actionable validation issue with at least a stable code and item position.","properties":{"code":{"type":"string","example":"policy_incomplete"},"item_position":{"type":"integer","example":1},"client_id":{"type":"string","example":"item-1"},"detail":{"type":"string","example":"sender.type is required"}}}},"warnings":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Actionable validation issue with at least a stable code and item position.","properties":{"code":{"type":"string","example":"policy_incomplete"},"item_position":{"type":"integer","example":1},"client_id":{"type":"string","example":"item-1"},"detail":{"type":"string","example":"sender.type is required"}}}},"next_occurrences":{"type":"array","maxItems":5,"items":{"type":"string","format":"date-time"}},"normalized_draft":{"oneOf":[{"type":"object","additionalProperties":false,"required":["parts"],"properties":{"version":{"type":"integer","enum":[1],"example":1},"schema_version":{"type":"integer","enum":[1],"example":1},"delay_ms":{"type":"integer","minimum":0,"maximum":300000,"example":0},"parts":{"type":"array","minItems":1,"maxItems":50,"items":{"type":"object","additionalProperties":false,"properties":{"content":{"type":"string","maxLength":150000,"example":"Olá, seu atendimento está marcado para amanhã."},"content_type":{"type":"string","enum":["text","input_select","sticker","poll"],"example":"text"},"content_attributes":{"type":"object","additionalProperties":false,"description":"Closed outbound metadata roots; rich provider objects remain JSON-shaped and are revalidated before dispatch.","properties":{"in_reply_to":{"type":"integer","example":88},"in_reply_to_external_id":{"type":"string","example":"wamid.example"},"items":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Provider-native option object."}},"email":{"type":"object","additionalProperties":true,"description":"Structured outbound e-mail metadata."},"interactive":{"type":"object","additionalProperties":true,"description":"WhatsApp Cloud interactive payload."},"wa_interactive":{"type":"object","additionalProperties":true,"description":"WazMeow interactive payload."},"poll":{"type":"object","additionalProperties":true,"description":"Poll payload."},"catalog_product":{"type":"object","additionalProperties":true,"description":"Catalog product payload."},"media_kind":{"type":"string","enum":["image","video","audio","document","sticker"],"example":"image"},"view_once":{"type":"boolean","example":false},"mention_all":{"type":"boolean","example":false},"mentioned_jids":{"type":"array","items":{"type":"string"},"example":[]},"mentions":{"type":"object","additionalProperties":true,"description":"Mention map keyed by provider identifier."},"is_forwarded":{"type":"boolean","example":false},"link_preview":{"type":"object","additionalProperties":true,"description":"Link preview metadata."},"location":{"type":"object","additionalProperties":true,"description":"Location payload."},"contact":{"type":"object","additionalProperties":true,"description":"Contact card payload."},"cta_buttons":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Call-to-action button."}}}},"attachments":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["signed_id"],"properties":{"signed_id":{"type":"string","description":"ActiveStorage signed blob id.","example":"eyJfcmFpbHMiOnsibWVzc2FnZSI6ImJsb2IifX0"},"filename":{"type":"string","example":"reminder.pdf"},"content_type":{"type":"string","example":"application/pdf"},"byte_size":{"type":"integer","minimum":0,"example":2048}}}},"items":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Structured select or poll option."}},"is_voice_message":{"type":"boolean","example":false},"email_html_content":{"type":"string","example":"\u003cp\u003eAppointment reminder\u003c/p\u003e"},"to_emails":{"type":"array","items":{"type":"string","format":"email"},"example":["customer@example.com"]},"cc_emails":{"type":"array","items":{"type":"string","format":"email"},"example":[]},"bcc_emails":{"type":"array","items":{"type":"string","format":"email"},"example":[]},"template_params":{"type":"object","additionalProperties":true,"description":"Approved template identity and parameters."},"flow_params":{"type":"object","additionalProperties":true,"description":"WhatsApp Flow identity and parameters."},"whatsapp_transport":{"type":"string","enum":["cloud","web"],"example":"cloud"}}}},"attachments":{"type":"array","description":"Union of the signed attachment references present in parts.","items":{"type":"object","additionalProperties":false,"required":["signed_id"],"properties":{"signed_id":{"type":"string","description":"ActiveStorage signed blob id.","example":"eyJfcmFpbHMiOnsibWVzc2FnZSI6ImJsb2IifX0"},"filename":{"type":"string","example":"reminder.pdf"},"content_type":{"type":"string","example":"application/pdf"},"byte_size":{"type":"integer","minimum":0,"example":2048}}}}}},{"type":"object","additionalProperties":false,"properties":{"items":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"client_id":{"type":"string"},"position":{"type":"integer"},"draft":{"type":"object","additionalProperties":false,"required":["parts"],"properties":{"version":{"type":"integer","enum":[1],"example":1},"schema_version":{"type":"integer","enum":[1],"example":1},"delay_ms":{"type":"integer","minimum":0,"maximum":300000,"example":0},"parts":{"type":"array","minItems":1,"maxItems":50,"items":{"type":"object","additionalProperties":false,"properties":{"content":{"type":"string","maxLength":150000,"example":"Olá, seu atendimento está marcado para amanhã."},"content_type":{"type":"string","enum":["text","input_select","sticker","poll"],"example":"text"},"content_attributes":{"type":"object","additionalProperties":false,"description":"Closed outbound metadata roots; rich provider objects remain JSON-shaped and are revalidated before dispatch.","properties":{"in_reply_to":{"type":"integer","example":88},"in_reply_to_external_id":{"type":"string","example":"wamid.example"},"items":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Provider-native option object."}},"email":{"type":"object","additionalProperties":true,"description":"Structured outbound e-mail metadata."},"interactive":{"type":"object","additionalProperties":true,"description":"WhatsApp Cloud interactive payload."},"wa_interactive":{"type":"object","additionalProperties":true,"description":"WazMeow interactive payload."},"poll":{"type":"object","additionalProperties":true,"description":"Poll payload."},"catalog_product":{"type":"object","additionalProperties":true,"description":"Catalog product payload."},"media_kind":{"type":"string","enum":["image","video","audio","document","sticker"],"example":"image"},"view_once":{"type":"boolean","example":false},"mention_all":{"type":"boolean","example":false},"mentioned_jids":{"type":"array","items":{"type":"string"},"example":[]},"mentions":{"type":"object","additionalProperties":true,"description":"Mention map keyed by provider identifier."},"is_forwarded":{"type":"boolean","example":false},"link_preview":{"type":"object","additionalProperties":true,"description":"Link preview metadata."},"location":{"type":"object","additionalProperties":true,"description":"Location payload."},"contact":{"type":"object","additionalProperties":true,"description":"Contact card payload."},"cta_buttons":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Call-to-action button."}}}},"attachments":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["signed_id"],"properties":{"signed_id":{"type":"string","description":"ActiveStorage signed blob id.","example":"eyJfcmFpbHMiOnsibWVzc2FnZSI6ImJsb2IifX0"},"filename":{"type":"string","example":"reminder.pdf"},"content_type":{"type":"string","example":"application/pdf"},"byte_size":{"type":"integer","minimum":0,"example":2048}}}},"items":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Structured select or poll option."}},"is_voice_message":{"type":"boolean","example":false},"email_html_content":{"type":"string","example":"\u003cp\u003eAppointment reminder\u003c/p\u003e"},"to_emails":{"type":"array","items":{"type":"string","format":"email"},"example":["customer@example.com"]},"cc_emails":{"type":"array","items":{"type":"string","format":"email"},"example":[]},"bcc_emails":{"type":"array","items":{"type":"string","format":"email"},"example":[]},"template_params":{"type":"object","additionalProperties":true,"description":"Approved template identity and parameters."},"flow_params":{"type":"object","additionalProperties":true,"description":"WhatsApp Flow identity and parameters."},"whatsapp_transport":{"type":"string","enum":["cloud","web"],"example":"cloud"}}}},"attachments":{"type":"array","description":"Union of the signed attachment references present in parts.","items":{"type":"object","additionalProperties":false,"required":["signed_id"],"properties":{"signed_id":{"type":"string","description":"ActiveStorage signed blob id.","example":"eyJfcmFpbHMiOnsibWVzc2FnZSI6ImJsb2IifX0"},"filename":{"type":"string","example":"reminder.pdf"},"content_type":{"type":"string","example":"application/pdf"},"byte_size":{"type":"integer","minimum":0,"example":2048}}}}}}}}}}}]},"resolved_policies":{"allOf":[{"type":"object","additionalProperties":false,"properties":{"policy":{"type":"object","additionalProperties":false,"description":"Explicit schedule-level overrides; omitted leaves inherit from inbox/account.","properties":{"on_inbound_reply":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["continue","pause","cancel","skip"],"example":"pause"}}},"on_conversation_resolved":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["continue","pause","cancel","skip"],"example":"continue"}}},"misfire":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["skip","manual_review","send_latest","catch_up_bounded"],"example":"send_latest"},"grace_seconds":{"type":"integer","minimum":0,"example":60},"max_occurrences":{"type":"integer","minimum":1,"maximum":500,"example":10},"spacing_seconds":{"type":"integer","minimum":0,"example":5}}},"transient_failure":{"type":"object","additionalProperties":false,"properties":{"max_attempts":{"type":"integer","minimum":1,"maximum":10,"example":3},"backoff_seconds":{"type":"array","maxItems":9,"items":{"type":"integer","minimum":0,"maximum":86400},"example":[30,120]},"exhausted_action":{"type":"string","enum":["skip","pause","cancel","manual_review"],"example":"manual_review"}}},"permanent_failure":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["skip","pause","cancel","manual_review"],"example":"manual_review"}}},"resume_behavior":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["preserve_schedule","shift_by_pause","skip_missed","catch_up_bounded"],"example":"preserve_schedule"},"max_occurrences":{"type":"integer","minimum":1,"maximum":500,"example":10},"spacing_seconds":{"type":"integer","minimum":0,"example":5}}},"quiet_hours":{"type":"object","additionalProperties":false,"properties":{"enabled":{"type":"boolean","example":false},"start":{"type":"string","pattern":"^(?:[01][0-9]|2[0-3]):[0-5][0-9]$","example":"22:00"},"end":{"type":"string","pattern":"^(?:[01][0-9]|2[0-3]):[0-5][0-9]$","example":"08:00"},"days":{"type":"array","uniqueItems":true,"items":{"type":"integer","minimum":0,"maximum":6},"example":[0,1,2,3,4,5,6]},"action":{"type":"string","enum":["allow","defer","skip","manual_review"],"example":"defer"}}},"overlap":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["allow","skip_new","defer_new","cancel_previous","manual_review"],"example":"allow"},"defer_seconds":{"type":"integer","minimum":1,"example":60}}},"inbox_change":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["follow_logical","cancel","pause","manual_review"],"example":"follow_logical"}}},"sender":{"type":"object","additionalProperties":false,"properties":{"type":{"type":"string","enum":["assigned_agent","schedule_creator","user","agent_bot","system"],"example":"system"},"id":{"type":["integer","null"],"minimum":1,"example":null},"missing":{"type":"string","enum":["fail","system","assigned_agent"],"example":"fail"}}},"variables":{"type":"object","additionalProperties":false,"properties":{"resolve_at":{"type":"string","enum":["publication","dispatch"],"example":"dispatch"},"missing":{"type":"string","enum":["fail","blank","skip"],"example":"fail"}}},"dst":{"type":"object","additionalProperties":false,"properties":{"nonexistent":{"type":"string","enum":["skip","shift_forward","shift_backward"],"example":"shift_forward"},"ambiguous":{"type":"string","enum":["first","second","skip"],"example":"first"}}},"materialization":{"type":"object","additionalProperties":false,"properties":{"horizon_seconds":{"type":"integer","minimum":1,"maximum":2592000,"example":2592000},"max_occurrences":{"type":"integer","minimum":1,"maximum":500,"example":500}}},"claim":{"type":"object","additionalProperties":false,"properties":{"lease_seconds":{"type":"integer","minimum":1,"maximum":900,"example":120},"recovery_grace_seconds":{"type":"integer","minimum":0,"maximum":3600,"example":30}}}}},"sources":{"type":"object","additionalProperties":{"type":"string"},"description":"Effective source keyed by policy path."},"fields":{"type":"object","additionalProperties":{"type":"object","additionalProperties":false,"properties":{"value":{"description":"Resolved scalar, null or integer-array policy value.","oneOf":[{"type":"string"},{"type":"integer"},{"type":"boolean"},{"type":"null"},{"type":"array","items":{"type":"integer"}}]},"source":{"type":["string","null"],"example":"account"}}},"description":"Resolved value and source keyed by policy path."}}},{"type":"object","properties":{"by_item":{"type":"object","additionalProperties":{"type":"object","additionalProperties":false,"properties":{"policy":{"type":"object","additionalProperties":false,"description":"Explicit schedule-level overrides; omitted leaves inherit from inbox/account.","properties":{"on_inbound_reply":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["continue","pause","cancel","skip"],"example":"pause"}}},"on_conversation_resolved":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["continue","pause","cancel","skip"],"example":"continue"}}},"misfire":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["skip","manual_review","send_latest","catch_up_bounded"],"example":"send_latest"},"grace_seconds":{"type":"integer","minimum":0,"example":60},"max_occurrences":{"type":"integer","minimum":1,"maximum":500,"example":10},"spacing_seconds":{"type":"integer","minimum":0,"example":5}}},"transient_failure":{"type":"object","additionalProperties":false,"properties":{"max_attempts":{"type":"integer","minimum":1,"maximum":10,"example":3},"backoff_seconds":{"type":"array","maxItems":9,"items":{"type":"integer","minimum":0,"maximum":86400},"example":[30,120]},"exhausted_action":{"type":"string","enum":["skip","pause","cancel","manual_review"],"example":"manual_review"}}},"permanent_failure":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["skip","pause","cancel","manual_review"],"example":"manual_review"}}},"resume_behavior":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["preserve_schedule","shift_by_pause","skip_missed","catch_up_bounded"],"example":"preserve_schedule"},"max_occurrences":{"type":"integer","minimum":1,"maximum":500,"example":10},"spacing_seconds":{"type":"integer","minimum":0,"example":5}}},"quiet_hours":{"type":"object","additionalProperties":false,"properties":{"enabled":{"type":"boolean","example":false},"start":{"type":"string","pattern":"^(?:[01][0-9]|2[0-3]):[0-5][0-9]$","example":"22:00"},"end":{"type":"string","pattern":"^(?:[01][0-9]|2[0-3]):[0-5][0-9]$","example":"08:00"},"days":{"type":"array","uniqueItems":true,"items":{"type":"integer","minimum":0,"maximum":6},"example":[0,1,2,3,4,5,6]},"action":{"type":"string","enum":["allow","defer","skip","manual_review"],"example":"defer"}}},"overlap":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["allow","skip_new","defer_new","cancel_previous","manual_review"],"example":"allow"},"defer_seconds":{"type":"integer","minimum":1,"example":60}}},"inbox_change":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["follow_logical","cancel","pause","manual_review"],"example":"follow_logical"}}},"sender":{"type":"object","additionalProperties":false,"properties":{"type":{"type":"string","enum":["assigned_agent","schedule_creator","user","agent_bot","system"],"example":"system"},"id":{"type":["integer","null"],"minimum":1,"example":null},"missing":{"type":"string","enum":["fail","system","assigned_agent"],"example":"fail"}}},"variables":{"type":"object","additionalProperties":false,"properties":{"resolve_at":{"type":"string","enum":["publication","dispatch"],"example":"dispatch"},"missing":{"type":"string","enum":["fail","blank","skip"],"example":"fail"}}},"dst":{"type":"object","additionalProperties":false,"properties":{"nonexistent":{"type":"string","enum":["skip","shift_forward","shift_backward"],"example":"shift_forward"},"ambiguous":{"type":"string","enum":["first","second","skip"],"example":"first"}}},"materialization":{"type":"object","additionalProperties":false,"properties":{"horizon_seconds":{"type":"integer","minimum":1,"maximum":2592000,"example":2592000},"max_occurrences":{"type":"integer","minimum":1,"maximum":500,"example":500}}},"claim":{"type":"object","additionalProperties":false,"properties":{"lease_seconds":{"type":"integer","minimum":1,"maximum":900,"example":120},"recovery_grace_seconds":{"type":"integer","minimum":0,"maximum":3600,"example":30}}}}},"sources":{"type":"object","additionalProperties":{"type":"string"},"description":"Effective source keyed by policy path."},"fields":{"type":"object","additionalProperties":{"type":"object","additionalProperties":false,"properties":{"value":{"description":"Resolved scalar, null or integer-array policy value.","oneOf":[{"type":"string"},{"type":"integer"},{"type":"boolean"},{"type":"null"},{"type":"array","items":{"type":"integer"}}]},"source":{"type":["string","null"],"example":"account"}}},"description":"Resolved value and source keyed by policy path."}}},"description":"Per-item resolution keyed by client_id."}}}]},"capabilities":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Capability row for one draft part."}},"effective_target":{"type":"object","additionalProperties":true,"description":"Logical and physical delivery target projection."},"effective_transport":{"oneOf":[{"type":"string","enum":["cloud","web"]},{"type":"array","items":{"type":"string","enum":["cloud","web"]}}]}}}}},"example":{"payload":{"name":"Appointment reminder","kind":"one_time","starts_at":"2026-08-22T13:00:00.000Z","timezone":"America/Sao_Paulo","blockers":[{"code":"policy_incomplete","item_position":1,"client_id":"item-1","detail":"sender.type is required"}],"warnings":[{"code":"policy_incomplete","item_position":1,"client_id":"item-1","detail":"sender.type is required"}],"next_occurrences":["2026-08-22T13:00:00.000Z"],"effective_transport":"cloud","rrule":null,"recurrence":{},"policy_overrides":{"on_inbound_reply":{"action":"pause"},"on_conversation_resolved":{"action":"continue"},"misfire":{"action":"send_latest","grace_seconds":60,"max_occurrences":10,"spacing_seconds":5},"transient_failure":{"max_attempts":3,"backoff_seconds":[30,120],"exhausted_action":"manual_review"},"permanent_failure":{"action":"manual_review"},"resume_behavior":{"action":"preserve_schedule","max_occurrences":10,"spacing_seconds":5},"quiet_hours":{"enabled":false,"start":"22:00","end":"08:00","days":[0,1,2,3,4,5,6],"action":"defer"},"overlap":{"action":"allow","defer_seconds":60},"inbox_change":{"action":"follow_logical"},"sender":{"type":"system","id":null,"missing":"fail"},"variables":{"resolve_at":"dispatch","missing":"fail"},"dst":{"nonexistent":"shift_forward","ambiguous":"first"},"materialization":{"horizon_seconds":2592000,"max_occurrences":500},"claim":{"lease_seconds":120,"recovery_grace_seconds":30}},"sender_config":{},"target_config":{},"resolved_items":[{"client_id":"item-1","position":1,"timing":{},"policy_overrides":{"on_inbound_reply":{"action":"pause"},"on_conversation_resolved":{"action":"continue"},"misfire":{"action":"send_latest","grace_seconds":60,"max_occurrences":10,"spacing_seconds":5},"transient_failure":{"max_attempts":3,"backoff_seconds":[30,120],"exhausted_action":"manual_review"},"permanent_failure":{"action":"manual_review"},"resume_behavior":{"action":"preserve_schedule","max_occurrences":10,"spacing_seconds":5},"quiet_hours":{"enabled":false,"start":"22:00","end":"08:00","days":[0,1,2,3,4,5,6],"action":"defer"},"overlap":{"action":"allow","defer_seconds":60},"inbox_change":{"action":"follow_logical"},"sender":{"type":"system","id":null,"missing":"fail"},"variables":{"resolve_at":"dispatch","missing":"fail"},"dst":{"nonexistent":"shift_forward","ambiguous":"first"},"materialization":{"horizon_seconds":2592000,"max_occurrences":500},"claim":{"lease_seconds":120,"recovery_grace_seconds":30}},"normalized_draft":{"version":1,"schema_version":1,"delay_ms":0,"parts":[{"content":"Olá, seu atendimento está marcado para amanhã.","content_type":"text","content_attributes":{"in_reply_to":88,"in_reply_to_external_id":"wamid.example","items":[{}],"email":{},"interactive":{},"wa_interactive":{},"poll":{},"catalog_product":{},"media_kind":"image","view_once":false,"mention_all":false,"mentioned_jids":[],"mentions":{},"is_forwarded":false,"link_preview":{},"location":{},"contact":{},"cta_buttons":[{}]},"attachments":[{"signed_id":"eyJfcmFpbHMiOnsibWVzc2FnZSI6ImJsb2IifX0","filename":"reminder.pdf","content_type":"application/pdf","byte_size":2048}],"items":[{}],"is_voice_message":false,"email_html_content":"\u003cp\u003eAppointment reminder\u003c/p\u003e","to_emails":["customer@example.com"],"cc_emails":[],"bcc_emails":[],"template_params":{},"flow_params":{},"whatsapp_transport":"cloud"}],"attachments":[{"signed_id":"eyJfcmFpbHMiOnsibWVzc2FnZSI6ImJsb2IifX0","filename":"reminder.pdf","content_type":"application/pdf","byte_size":2048}]},"resolved_policies":{"policy":{"on_inbound_reply":{"action":"pause"},"on_conversation_resolved":{"action":"continue"},"misfire":{"action":"send_latest","grace_seconds":60,"max_occurrences":10,"spacing_seconds":5},"transient_failure":{"max_attempts":3,"backoff_seconds":[30,120],"exhausted_action":"manual_review"},"permanent_failure":{"action":"manual_review"},"resume_behavior":{"action":"preserve_schedule","max_occurrences":10,"spacing_seconds":5},"quiet_hours":{"enabled":false,"start":"22:00","end":"08:00","days":[0,1,2,3,4,5,6],"action":"defer"},"overlap":{"action":"allow","defer_seconds":60},"inbox_change":{"action":"follow_logical"},"sender":{"type":"system","id":null,"missing":"fail"},"variables":{"resolve_at":"dispatch","missing":"fail"},"dst":{"nonexistent":"shift_forward","ambiguous":"first"},"materialization":{"horizon_seconds":2592000,"max_occurrences":500},"claim":{"lease_seconds":120,"recovery_grace_seconds":30}},"sources":{},"fields":{}},"policy_sources":{},"blockers":[{"code":"policy_incomplete","item_position":1,"client_id":"item-1","detail":"sender.type is required"}],"warnings":[{"code":"policy_incomplete","item_position":1,"client_id":"item-1","detail":"sender.type is required"}],"next5":["2026-01-15T10:30:00.000Z"],"effective_target":{},"capability":[{}],"capabilities":[{}]}],"normalized_draft":{"version":1,"schema_version":1,"delay_ms":0,"parts":[{"content":"Olá, seu atendimento está marcado para amanhã.","content_type":"text","content_attributes":{"in_reply_to":88,"in_reply_to_external_id":"wamid.example","items":[{}],"email":{},"interactive":{},"wa_interactive":{},"poll":{},"catalog_product":{},"media_kind":"image","view_once":false,"mention_all":false,"mentioned_jids":[],"mentions":{},"is_forwarded":false,"link_preview":{},"location":{},"contact":{},"cta_buttons":[{}]},"attachments":[{"signed_id":"eyJfcmFpbHMiOnsibWVzc2FnZSI6ImJsb2IifX0","filename":"reminder.pdf","content_type":"application/pdf","byte_size":2048}],"items":[{}],"is_voice_message":false,"email_html_content":"\u003cp\u003eAppointment reminder\u003c/p\u003e","to_emails":["customer@example.com"],"cc_emails":[],"bcc_emails":[],"template_params":{},"flow_params":{},"whatsapp_transport":"cloud"}],"attachments":[{"signed_id":"eyJfcmFpbHMiOnsibWVzc2FnZSI6ImJsb2IifX0","filename":"reminder.pdf","content_type":"application/pdf","byte_size":2048}]},"resolved_policies":{"policy":{"on_inbound_reply":{"action":"pause"},"on_conversation_resolved":{"action":"continue"},"misfire":{"action":"send_latest","grace_seconds":60,"max_occurrences":10,"spacing_seconds":5},"transient_failure":{"max_attempts":3,"backoff_seconds":[30,120],"exhausted_action":"manual_review"},"permanent_failure":{"action":"manual_review"},"resume_behavior":{"action":"preserve_schedule","max_occurrences":10,"spacing_seconds":5},"quiet_hours":{"enabled":false,"start":"22:00","end":"08:00","days":[0,1,2,3,4,5,6],"action":"defer"},"overlap":{"action":"allow","defer_seconds":60},"inbox_change":{"action":"follow_logical"},"sender":{"type":"system","id":null,"missing":"fail"},"variables":{"resolve_at":"dispatch","missing":"fail"},"dst":{"nonexistent":"shift_forward","ambiguous":"first"},"materialization":{"horizon_seconds":2592000,"max_occurrences":500},"claim":{"lease_seconds":120,"recovery_grace_seconds":30}},"sources":{},"fields":{},"by_item":{}},"capabilities":[{}],"effective_target":{}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"conversation_id":{"type":"integer","description":"Public display id of the existing target conversation.","example":42},"name":{"type":"string","maxLength":255,"example":"Appointment reminder"},"kind":{"type":"string","enum":["one_time","sequence","recurring_single","recurring_sequence"],"example":"one_time","description":"Temporal shape of the scheduled message plan."},"starts_at":{"type":"string","format":"date-time","description":"First civil occurrence represented as an ISO-8601 instant.","example":"2026-08-22T13:00:00.000Z"},"timezone":{"type":"string","description":"IANA timezone used for recurrence and DST decisions. When omitted or blank it inherits the effective scheduling timezone of the conversation inbox (inbox setting, then account setting, then the account timezone, then UTC); an explicit invalid value is rejected with invalid_timezone. On update a blank value keeps the published timezone.","example":"America/Sao_Paulo"},"recurrence":{"type":["object","null"],"additionalProperties":false,"description":"Required only for recurring kinds; COUNT/UNTIL stays outside rrule.","properties":{"rrule":{"type":"string","description":"RFC 5545 recurrence body without RRULE prefix, COUNT or UNTIL.","example":"FREQ=WEEKLY;INTERVAL=1;BYDAY=MO,WE"},"end_mode":{"type":"string","enum":["never","until","count"],"example":"count"},"until":{"type":["string","null"],"format":"date-time","example":null},"count":{"type":["integer","null"],"minimum":1,"maximum":10000,"example":8}}},"policies":{"type":"object","additionalProperties":false,"description":"Explicit schedule-level overrides; omitted leaves inherit from inbox/account.","properties":{"on_inbound_reply":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["continue","pause","cancel","skip"],"example":"pause"}}},"on_conversation_resolved":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["continue","pause","cancel","skip"],"example":"continue"}}},"misfire":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["skip","manual_review","send_latest","catch_up_bounded"],"example":"send_latest"},"grace_seconds":{"type":"integer","minimum":0,"example":60},"max_occurrences":{"type":"integer","minimum":1,"maximum":500,"example":10},"spacing_seconds":{"type":"integer","minimum":0,"example":5}}},"transient_failure":{"type":"object","additionalProperties":false,"properties":{"max_attempts":{"type":"integer","minimum":1,"maximum":10,"example":3},"backoff_seconds":{"type":"array","maxItems":9,"items":{"type":"integer","minimum":0,"maximum":86400},"example":[30,120]},"exhausted_action":{"type":"string","enum":["skip","pause","cancel","manual_review"],"example":"manual_review"}}},"permanent_failure":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["skip","pause","cancel","manual_review"],"example":"manual_review"}}},"resume_behavior":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["preserve_schedule","shift_by_pause","skip_missed","catch_up_bounded"],"example":"preserve_schedule"},"max_occurrences":{"type":"integer","minimum":1,"maximum":500,"example":10},"spacing_seconds":{"type":"integer","minimum":0,"example":5}}},"quiet_hours":{"type":"object","additionalProperties":false,"properties":{"enabled":{"type":"boolean","example":false},"start":{"type":"string","pattern":"^(?:[01][0-9]|2[0-3]):[0-5][0-9]$","example":"22:00"},"end":{"type":"string","pattern":"^(?:[01][0-9]|2[0-3]):[0-5][0-9]$","example":"08:00"},"days":{"type":"array","uniqueItems":true,"items":{"type":"integer","minimum":0,"maximum":6},"example":[0,1,2,3,4,5,6]},"action":{"type":"string","enum":["allow","defer","skip","manual_review"],"example":"defer"}}},"overlap":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["allow","skip_new","defer_new","cancel_previous","manual_review"],"example":"allow"},"defer_seconds":{"type":"integer","minimum":1,"example":60}}},"inbox_change":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["follow_logical","cancel","pause","manual_review"],"example":"follow_logical"}}},"sender":{"type":"object","additionalProperties":false,"properties":{"type":{"type":"string","enum":["assigned_agent","schedule_creator","user","agent_bot","system"],"example":"system"},"id":{"type":["integer","null"],"minimum":1,"example":null},"missing":{"type":"string","enum":["fail","system","assigned_agent"],"example":"fail"}}},"variables":{"type":"object","additionalProperties":false,"properties":{"resolve_at":{"type":"string","enum":["publication","dispatch"],"example":"dispatch"},"missing":{"type":"string","enum":["fail","blank","skip"],"example":"fail"}}},"dst":{"type":"object","additionalProperties":false,"properties":{"nonexistent":{"type":"string","enum":["skip","shift_forward","shift_backward"],"example":"shift_forward"},"ambiguous":{"type":"string","enum":["first","second","skip"],"example":"first"}}},"materialization":{"type":"object","additionalProperties":false,"properties":{"horizon_seconds":{"type":"integer","minimum":1,"maximum":2592000,"example":2592000},"max_occurrences":{"type":"integer","minimum":1,"maximum":500,"example":500}}},"claim":{"type":"object","additionalProperties":false,"properties":{"lease_seconds":{"type":"integer","minimum":1,"maximum":900,"example":120},"recovery_grace_seconds":{"type":"integer","minimum":0,"maximum":3600,"example":30}}}}},"source_message_id":{"type":"integer","description":"Existing outgoing message to clone server-side; mutually exclusive with items.","example":91},"items":{"type":"array","minItems":1,"maxItems":500,"items":{"type":"object","additionalProperties":false,"required":["client_id","position","timing","draft"],"properties":{"client_id":{"type":"string","minLength":1,"example":"item-1"},"position":{"type":"integer","minimum":1,"example":1},"timing":{"type":"object","additionalProperties":false,"required":["anchor","offset_seconds"],"properties":{"anchor":{"type":"string","enum":["schedule_start","previous_scheduled","previous_dispatched"],"example":"schedule_start"},"offset_seconds":{"type":"integer","minimum":0,"example":0}}},"draft":{"type":"object","additionalProperties":false,"required":["parts"],"properties":{"version":{"type":"integer","enum":[1],"example":1},"schema_version":{"type":"integer","enum":[1],"example":1},"delay_ms":{"type":"integer","minimum":0,"maximum":300000,"example":0},"parts":{"type":"array","minItems":1,"maxItems":50,"items":{"type":"object","additionalProperties":false,"properties":{"content":{"type":"string","maxLength":150000,"example":"Olá, seu atendimento está marcado para amanhã."},"content_type":{"type":"string","enum":["text","input_select","sticker","poll"],"example":"text"},"content_attributes":{"type":"object","additionalProperties":false,"description":"Closed outbound metadata roots; rich provider objects remain JSON-shaped and are revalidated before dispatch.","properties":{"in_reply_to":{"type":"integer","example":88},"in_reply_to_external_id":{"type":"string","example":"wamid.example"},"items":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Provider-native option object."}},"email":{"type":"object","additionalProperties":true,"description":"Structured outbound e-mail metadata."},"interactive":{"type":"object","additionalProperties":true,"description":"WhatsApp Cloud interactive payload."},"wa_interactive":{"type":"object","additionalProperties":true,"description":"WazMeow interactive payload."},"poll":{"type":"object","additionalProperties":true,"description":"Poll payload."},"catalog_product":{"type":"object","additionalProperties":true,"description":"Catalog product payload."},"media_kind":{"type":"string","enum":["image","video","audio","document","sticker"],"example":"image"},"view_once":{"type":"boolean","example":false},"mention_all":{"type":"boolean","example":false},"mentioned_jids":{"type":"array","items":{"type":"string"},"example":[]},"mentions":{"type":"object","additionalProperties":true,"description":"Mention map keyed by provider identifier."},"is_forwarded":{"type":"boolean","example":false},"link_preview":{"type":"object","additionalProperties":true,"description":"Link preview metadata."},"location":{"type":"object","additionalProperties":true,"description":"Location payload."},"contact":{"type":"object","additionalProperties":true,"description":"Contact card payload."},"cta_buttons":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Call-to-action button."}}}},"attachments":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["signed_id"],"properties":{"signed_id":{"type":"string","description":"ActiveStorage signed blob id.","example":"eyJfcmFpbHMiOnsibWVzc2FnZSI6ImJsb2IifX0"},"filename":{"type":"string","example":"reminder.pdf"},"content_type":{"type":"string","example":"application/pdf"},"byte_size":{"type":"integer","minimum":0,"example":2048}}}},"items":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Structured select or poll option."}},"is_voice_message":{"type":"boolean","example":false},"email_html_content":{"type":"string","example":"\u003cp\u003eAppointment reminder\u003c/p\u003e"},"to_emails":{"type":"array","items":{"type":"string","format":"email"},"example":["customer@example.com"]},"cc_emails":{"type":"array","items":{"type":"string","format":"email"},"example":[]},"bcc_emails":{"type":"array","items":{"type":"string","format":"email"},"example":[]},"template_params":{"type":"object","additionalProperties":true,"description":"Approved template identity and parameters."},"flow_params":{"type":"object","additionalProperties":true,"description":"WhatsApp Flow identity and parameters."},"whatsapp_transport":{"type":"string","enum":["cloud","web"],"example":"cloud"}}}},"attachments":{"type":"array","description":"Union of the signed attachment references present in parts.","items":{"type":"object","additionalProperties":false,"required":["signed_id"],"properties":{"signed_id":{"type":"string","description":"ActiveStorage signed blob id.","example":"eyJfcmFpbHMiOnsibWVzc2FnZSI6ImJsb2IifX0"},"filename":{"type":"string","example":"reminder.pdf"},"content_type":{"type":"string","example":"application/pdf"},"byte_size":{"type":"integer","minimum":0,"example":2048}}}}}},"policy_overrides":{"type":"object","additionalProperties":false,"description":"Explicit schedule-level overrides; omitted leaves inherit from inbox/account.","properties":{"on_inbound_reply":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["continue","pause","cancel","skip"],"example":"pause"}}},"on_conversation_resolved":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["continue","pause","cancel","skip"],"example":"continue"}}},"misfire":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["skip","manual_review","send_latest","catch_up_bounded"],"example":"send_latest"},"grace_seconds":{"type":"integer","minimum":0,"example":60},"max_occurrences":{"type":"integer","minimum":1,"maximum":500,"example":10},"spacing_seconds":{"type":"integer","minimum":0,"example":5}}},"transient_failure":{"type":"object","additionalProperties":false,"properties":{"max_attempts":{"type":"integer","minimum":1,"maximum":10,"example":3},"backoff_seconds":{"type":"array","maxItems":9,"items":{"type":"integer","minimum":0,"maximum":86400},"example":[30,120]},"exhausted_action":{"type":"string","enum":["skip","pause","cancel","manual_review"],"example":"manual_review"}}},"permanent_failure":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["skip","pause","cancel","manual_review"],"example":"manual_review"}}},"resume_behavior":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["preserve_schedule","shift_by_pause","skip_missed","catch_up_bounded"],"example":"preserve_schedule"},"max_occurrences":{"type":"integer","minimum":1,"maximum":500,"example":10},"spacing_seconds":{"type":"integer","minimum":0,"example":5}}},"quiet_hours":{"type":"object","additionalProperties":false,"properties":{"enabled":{"type":"boolean","example":false},"start":{"type":"string","pattern":"^(?:[01][0-9]|2[0-3]):[0-5][0-9]$","example":"22:00"},"end":{"type":"string","pattern":"^(?:[01][0-9]|2[0-3]):[0-5][0-9]$","example":"08:00"},"days":{"type":"array","uniqueItems":true,"items":{"type":"integer","minimum":0,"maximum":6},"example":[0,1,2,3,4,5,6]},"action":{"type":"string","enum":["allow","defer","skip","manual_review"],"example":"defer"}}},"overlap":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["allow","skip_new","defer_new","cancel_previous","manual_review"],"example":"allow"},"defer_seconds":{"type":"integer","minimum":1,"example":60}}},"inbox_change":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["follow_logical","cancel","pause","manual_review"],"example":"follow_logical"}}},"sender":{"type":"object","additionalProperties":false,"properties":{"type":{"type":"string","enum":["assigned_agent","schedule_creator","user","agent_bot","system"],"example":"system"},"id":{"type":["integer","null"],"minimum":1,"example":null},"missing":{"type":"string","enum":["fail","system","assigned_agent"],"example":"fail"}}},"variables":{"type":"object","additionalProperties":false,"properties":{"resolve_at":{"type":"string","enum":["publication","dispatch"],"example":"dispatch"},"missing":{"type":"string","enum":["fail","blank","skip"],"example":"fail"}}},"dst":{"type":"object","additionalProperties":false,"properties":{"nonexistent":{"type":"string","enum":["skip","shift_forward","shift_backward"],"example":"shift_forward"},"ambiguous":{"type":"string","enum":["first","second","skip"],"example":"first"}}},"materialization":{"type":"object","additionalProperties":false,"properties":{"horizon_seconds":{"type":"integer","minimum":1,"maximum":2592000,"example":2592000},"max_occurrences":{"type":"integer","minimum":1,"maximum":500,"example":500}}},"claim":{"type":"object","additionalProperties":false,"properties":{"lease_seconds":{"type":"integer","minimum":1,"maximum":900,"example":120},"recovery_grace_seconds":{"type":"integer","minimum":0,"maximum":3600,"example":30}}}}}}}}},"required":["conversation_id","name","kind","starts_at"]},"example":{"conversation_id":42,"name":"Appointment reminder","kind":"one_time","starts_at":"2026-08-22T13:00:00.000Z","timezone":"America/Sao_Paulo","policies":{"on_inbound_reply":{"action":"pause"},"on_conversation_resolved":{"action":"continue"},"misfire":{"action":"send_latest","grace_seconds":60,"max_occurrences":10,"spacing_seconds":5},"transient_failure":{"max_attempts":3,"backoff_seconds":[30,120],"exhausted_action":"manual_review"},"permanent_failure":{"action":"manual_review"},"resume_behavior":{"action":"preserve_schedule","max_occurrences":10,"spacing_seconds":5},"quiet_hours":{"enabled":false,"start":"22:00","end":"08:00","days":[0,1,2,3,4,5,6],"action":"defer"},"overlap":{"action":"allow","defer_seconds":60},"inbox_change":{"action":"follow_logical"},"sender":{"type":"system","id":null,"missing":"fail"},"variables":{"resolve_at":"dispatch","missing":"fail"},"dst":{"nonexistent":"shift_forward","ambiguous":"first"},"materialization":{"horizon_seconds":2592000,"max_occurrences":500},"claim":{"lease_seconds":120,"recovery_grace_seconds":30}},"items":[{"client_id":"item-1","position":1,"timing":{"anchor":"schedule_start","offset_seconds":0},"draft":{"schema_version":1,"parts":[{"content":"Appointment reminder","content_type":"text","content_attributes":{"in_reply_to":88,"in_reply_to_external_id":"wamid.example","items":[{}],"email":{},"interactive":{},"wa_interactive":{},"poll":{},"catalog_product":{},"media_kind":"image","view_once":false,"mention_all":false,"mentioned_jids":[],"mentions":{},"is_forwarded":false,"link_preview":{},"location":{},"contact":{},"cta_buttons":[{}]},"attachments":[{"signed_id":"eyJfcmFpbHMiOnsibWVzc2FnZSI6ImJsb2IifX0","filename":"reminder.pdf","content_type":"application/pdf","byte_size":2048}],"items":[{}],"is_voice_message":false,"email_html_content":"\u003cp\u003eAppointment reminder\u003c/p\u003e","to_emails":["customer@example.com"],"cc_emails":[],"bcc_emails":[],"template_params":{},"flow_params":{},"whatsapp_transport":"cloud"}],"version":1,"delay_ms":0,"attachments":[{"signed_id":"eyJfcmFpbHMiOnsibWVzc2FnZSI6ImJsb2IifX0","filename":"reminder.pdf","content_type":"application/pdf","byte_size":2048}]},"policy_overrides":{"on_inbound_reply":{"action":"pause"},"on_conversation_resolved":{"action":"continue"},"misfire":{"action":"send_latest","grace_seconds":60,"max_occurrences":10,"spacing_seconds":5},"transient_failure":{"max_attempts":3,"backoff_seconds":[30,120],"exhausted_action":"manual_review"},"permanent_failure":{"action":"manual_review"},"resume_behavior":{"action":"preserve_schedule","max_occurrences":10,"spacing_seconds":5},"quiet_hours":{"enabled":false,"start":"22:00","end":"08:00","days":[0,1,2,3,4,5,6],"action":"defer"},"overlap":{"action":"allow","defer_seconds":60},"inbox_change":{"action":"follow_logical"},"sender":{"type":"system","id":null,"missing":"fail"},"variables":{"resolve_at":"dispatch","missing":"fail"},"dst":{"nonexistent":"shift_forward","ambiguous":"first"},"materialization":{"horizon_seconds":2592000,"max_occurrences":500},"claim":{"lease_seconds":120,"recovery_grace_seconds":30}}}],"recurrence":{"rrule":"FREQ=WEEKLY;INTERVAL=1;BYDAY=MO,WE","end_mode":"count","until":null,"count":8},"source_message_id":91}}}}}},"/api/v1/accounts/{account_id}/message_schedules/bulk":{"post":{"tags":["Message Schedules"],"operationId":"auto_post_api_v1_accounts_account_id_message_schedules_bulk","summary":"Apply one lifecycle action atomically to multiple schedules","description":"Applies one action to 1-100 explicitly selected schedules visible and manageable by the authenticated user. Each entry requires its selected lock_version and a unique id. Pause accepts active schedules; resume accepts paused schedules; cancel accepts active, paused and needs_attention; archive additionally accepts completed and canceled. Resume uses the immutable published resume policy of each schedule's first item ordered by position. Other items may have different policies. Validation or a transaction failure rolls back the whole batch, including delivery jobs prepared by resume. Delivery already started cannot be canceled by this operation. After a lost response, reload current states and versions before choosing another action.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Updated schedule summaries; no record is changed if any entry is invalid.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"integer","example":701},"name":{"type":"string","example":"Appointment reminder"},"status":{"type":"string","enum":["draft","active","paused","needs_attention","completed","canceled","archived"],"example":"active","description":"Lifecycle state of the message schedule."},"inbox_id":{"type":"integer","example":7},"contact_id":{"type":"integer","example":81},"created_by_id":{"type":"integer","example":9},"conversation_id":{"type":"integer","description":"Public conversation display id.","example":42},"next_occurrence_at":{"type":["string","null"],"format":"date-time","example":"2026-08-22T13:00:00.000Z"},"materialized_through_at":{"type":["string","null"],"format":"date-time","example":"2026-08-22T13:00:00.000Z"},"published_at":{"type":["string","null"],"format":"date-time","example":"2026-08-21T16:00:00.000Z"},"paused_at":{"type":["string","null"],"format":"date-time","example":null},"needs_attention_at":{"type":["string","null"],"format":"date-time","example":null},"completed_at":{"type":["string","null"],"format":"date-time","example":null},"canceled_at":{"type":["string","null"],"format":"date-time","example":null},"archived_at":{"type":["string","null"],"format":"date-time","example":null},"lock_version":{"type":"integer","example":1},"created_at":{"type":"string","format":"date-time","example":"2026-08-21T16:00:00.000Z"},"updated_at":{"type":"string","format":"date-time","example":"2026-08-21T16:00:00.000Z"},"created_by":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"integer","example":9},"name":{"type":"string","example":"Ana Agent"}}},"kind":{"type":"string","enum":["one_time","sequence","recurring_single","recurring_sequence"],"example":"one_time","description":"Temporal shape of the scheduled message plan."},"timezone":{"type":"string","example":"America/Sao_Paulo"},"starts_at":{"type":"string","format":"date-time","example":"2026-08-22T13:00:00.000Z"},"rrule":{"type":["string","null"],"example":null},"version_number":{"type":"integer","example":1}}}}}},"example":{"payload":[{"id":701,"name":"Appointment reminder","status":"active","inbox_id":7,"contact_id":81,"created_by_id":9,"conversation_id":42,"next_occurrence_at":"2026-08-22T13:00:00.000Z","materialized_through_at":"2026-08-22T13:00:00.000Z","published_at":"2026-08-21T16:00:00.000Z","paused_at":null,"needs_attention_at":null,"completed_at":null,"canceled_at":null,"archived_at":null,"lock_version":1,"created_at":"2026-08-21T16:00:00.000Z","updated_at":"2026-08-21T16:00:00.000Z","created_by":{"id":9,"name":"Ana Agent"},"kind":"one_time","timezone":"America/Sao_Paulo","starts_at":"2026-08-22T13:00:00.000Z","rrule":null,"version_number":1}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"400":{"description":"A supplied lock version is not an integer; no record is changed.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","example":"invalid_lock_version"}}},"example":{"error":"invalid_lock_version"}}}},"403":{"description":"Message scheduling or API access is disabled for this account.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","example":"feature_not_enabled"}}},"example":{"error":"feature_not_enabled"}}}},"409":{"description":"A lock is stale, a schedule is executing or an action is invalid for one record; no record is changed.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","example":"stale_lock_version"},"details":{"oneOf":[{"type":"object","additionalProperties":false,"required":["current_lock_version"],"properties":{"current_lock_version":{"type":"integer","minimum":0,"example":2}}},{"type":"object","additionalProperties":false,"required":["id","status"],"properties":{"id":{"type":"integer","minimum":1,"example":701},"status":{"type":"string","enum":["draft","active","paused","needs_attention","completed","canceled","archived"],"example":"completed","description":"Lifecycle state of the message schedule."}}}]}}},"example":{"error":"stale_lock_version","details":{"current_lock_version":2}}}}},"422":{"description":"Invalid entries, size, duplicates or action, or a resume policy failure; the whole batch is rolled back.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","example":"invalid_bulk_entry"},"details":{"type":"string","description":"Optional explanation of a resume failure.","example":"schedule is not paused"}}},"example":{"error":"resume_failed","details":"schedule is not paused"}}}},"428":{"description":"A selected schedule is missing its required lock version; no record is changed.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","example":"lock_version_required"}}},"example":{"error":"lock_version_required"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["action","schedules"],"properties":{"action":{"type":"string","enum":["pause","resume","cancel","archive"],"example":"pause"},"schedules":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"object","additionalProperties":false,"required":["id","lock_version"],"properties":{"id":{"type":"integer","minimum":1,"example":701},"lock_version":{"type":"integer","minimum":0,"example":1}}}}}},"example":{"action":"pause","schedules":[{"id":701,"lock_version":1}]}}}}}},"/api/v1/accounts/{account_id}/message_schedules/{id}/pause":{"post":{"tags":["Message Schedules"],"operationId":"auto_post_api_v1_accounts_account_id_message_schedules_id_pause","summary":"Pause message schedules","description":"Performs the pause operation on the targeted message schedule resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Idempotent replay of the already published schedule.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"allOf":[{"type":"object","additionalProperties":false,"properties":{"id":{"type":"integer","example":701},"name":{"type":"string","example":"Appointment reminder"},"status":{"type":"string","enum":["draft","active","paused","needs_attention","completed","canceled","archived"],"example":"active","description":"Lifecycle state of the message schedule."},"inbox_id":{"type":"integer","example":7},"contact_id":{"type":"integer","example":81},"created_by_id":{"type":"integer","example":9},"conversation_id":{"type":"integer","description":"Public conversation display id.","example":42},"next_occurrence_at":{"type":["string","null"],"format":"date-time","example":"2026-08-22T13:00:00.000Z"},"materialized_through_at":{"type":["string","null"],"format":"date-time","example":"2026-08-22T13:00:00.000Z"},"published_at":{"type":["string","null"],"format":"date-time","example":"2026-08-21T16:00:00.000Z"},"paused_at":{"type":["string","null"],"format":"date-time","example":null},"needs_attention_at":{"type":["string","null"],"format":"date-time","example":null},"completed_at":{"type":["string","null"],"format":"date-time","example":null},"canceled_at":{"type":["string","null"],"format":"date-time","example":null},"archived_at":{"type":["string","null"],"format":"date-time","example":null},"lock_version":{"type":"integer","example":1},"created_at":{"type":"string","format":"date-time","example":"2026-08-21T16:00:00.000Z"},"updated_at":{"type":"string","format":"date-time","example":"2026-08-21T16:00:00.000Z"},"created_by":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"integer","example":9},"name":{"type":"string","example":"Ana Agent"}}},"kind":{"type":"string","enum":["one_time","sequence","recurring_single","recurring_sequence"],"example":"one_time","description":"Temporal shape of the scheduled message plan."},"timezone":{"type":"string","example":"America/Sao_Paulo"},"starts_at":{"type":"string","format":"date-time","example":"2026-08-22T13:00:00.000Z"},"rrule":{"type":["string","null"],"example":null},"version_number":{"type":"integer","example":1}}},{"type":"object","properties":{"resolved_policies":{"type":"object","description":"Complete immutable policy snapshot keyed by item stable key.","additionalProperties":{"type":"object","additionalProperties":false,"description":"Explicit schedule-level overrides; omitted leaves inherit from inbox/account.","properties":{"on_inbound_reply":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["continue","pause","cancel","skip"],"example":"pause"}}},"on_conversation_resolved":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["continue","pause","cancel","skip"],"example":"continue"}}},"misfire":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["skip","manual_review","send_latest","catch_up_bounded"],"example":"send_latest"},"grace_seconds":{"type":"integer","minimum":0,"example":60},"max_occurrences":{"type":"integer","minimum":1,"maximum":500,"example":10},"spacing_seconds":{"type":"integer","minimum":0,"example":5}}},"transient_failure":{"type":"object","additionalProperties":false,"properties":{"max_attempts":{"type":"integer","minimum":1,"maximum":10,"example":3},"backoff_seconds":{"type":"array","maxItems":9,"items":{"type":"integer","minimum":0,"maximum":86400},"example":[30,120]},"exhausted_action":{"type":"string","enum":["skip","pause","cancel","manual_review"],"example":"manual_review"}}},"permanent_failure":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["skip","pause","cancel","manual_review"],"example":"manual_review"}}},"resume_behavior":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["preserve_schedule","shift_by_pause","skip_missed","catch_up_bounded"],"example":"preserve_schedule"},"max_occurrences":{"type":"integer","minimum":1,"maximum":500,"example":10},"spacing_seconds":{"type":"integer","minimum":0,"example":5}}},"quiet_hours":{"type":"object","additionalProperties":false,"properties":{"enabled":{"type":"boolean","example":false},"start":{"type":"string","pattern":"^(?:[01][0-9]|2[0-3]):[0-5][0-9]$","example":"22:00"},"end":{"type":"string","pattern":"^(?:[01][0-9]|2[0-3]):[0-5][0-9]$","example":"08:00"},"days":{"type":"array","uniqueItems":true,"items":{"type":"integer","minimum":0,"maximum":6},"example":[0,1,2,3,4,5,6]},"action":{"type":"string","enum":["allow","defer","skip","manual_review"],"example":"defer"}}},"overlap":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["allow","skip_new","defer_new","cancel_previous","manual_review"],"example":"allow"},"defer_seconds":{"type":"integer","minimum":1,"example":60}}},"inbox_change":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["follow_logical","cancel","pause","manual_review"],"example":"follow_logical"}}},"sender":{"type":"object","additionalProperties":false,"properties":{"type":{"type":"string","enum":["assigned_agent","schedule_creator","user","agent_bot","system"],"example":"system"},"id":{"type":["integer","null"],"minimum":1,"example":null},"missing":{"type":"string","enum":["fail","system","assigned_agent"],"example":"fail"}}},"variables":{"type":"object","additionalProperties":false,"properties":{"resolve_at":{"type":"string","enum":["publication","dispatch"],"example":"dispatch"},"missing":{"type":"string","enum":["fail","blank","skip"],"example":"fail"}}},"dst":{"type":"object","additionalProperties":false,"properties":{"nonexistent":{"type":"string","enum":["skip","shift_forward","shift_backward"],"example":"shift_forward"},"ambiguous":{"type":"string","enum":["first","second","skip"],"example":"first"}}},"materialization":{"type":"object","additionalProperties":false,"properties":{"horizon_seconds":{"type":"integer","minimum":1,"maximum":2592000,"example":2592000},"max_occurrences":{"type":"integer","minimum":1,"maximum":500,"example":500}}},"claim":{"type":"object","additionalProperties":false,"properties":{"lease_seconds":{"type":"integer","minimum":1,"maximum":900,"example":120},"recovery_grace_seconds":{"type":"integer","minimum":0,"maximum":3600,"example":30}}}}}},"policy_sources":{"type":"object","description":"Source map keyed by item stable key, then by policy path.","additionalProperties":{"type":"object","description":"Effective source keyed by policy path for this item.","additionalProperties":{"type":"string"}}},"sender_config":{"type":"object","additionalProperties":true,"description":"Server-authored sender snapshot; clients cannot submit it."},"target_config":{"type":"object","additionalProperties":true,"description":"Server-authored immutable conversation/inbox/contact target."},"items":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"integer","example":801},"stable_key":{"type":"string","format":"uuid","example":"2dc1f16c-5191-4b3b-97b4-8f33e93dc969"},"position":{"type":"integer","minimum":1,"example":1},"timing":{"type":"object","additionalProperties":false,"properties":{"anchor":{"type":"string","enum":["schedule_start","previous_scheduled","previous_dispatched"],"example":"schedule_start"},"offset_seconds":{"type":"integer","minimum":0,"example":0}}},"draft":{"type":"object","additionalProperties":false,"required":["parts"],"properties":{"version":{"type":"integer","enum":[1],"example":1},"schema_version":{"type":"integer","enum":[1],"example":1},"delay_ms":{"type":"integer","minimum":0,"maximum":300000,"example":0},"parts":{"type":"array","minItems":1,"maxItems":50,"items":{"type":"object","additionalProperties":false,"properties":{"content":{"type":"string","maxLength":150000,"example":"Olá, seu atendimento está marcado para amanhã."},"content_type":{"type":"string","enum":["text","input_select","sticker","poll"],"example":"text"},"content_attributes":{"type":"object","additionalProperties":false,"description":"Closed outbound metadata roots; rich provider objects remain JSON-shaped and are revalidated before dispatch.","properties":{"in_reply_to":{"type":"integer","example":88},"in_reply_to_external_id":{"type":"string","example":"wamid.example"},"items":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Provider-native option object."}},"email":{"type":"object","additionalProperties":true,"description":"Structured outbound e-mail metadata."},"interactive":{"type":"object","additionalProperties":true,"description":"WhatsApp Cloud interactive payload."},"wa_interactive":{"type":"object","additionalProperties":true,"description":"WazMeow interactive payload."},"poll":{"type":"object","additionalProperties":true,"description":"Poll payload."},"catalog_product":{"type":"object","additionalProperties":true,"description":"Catalog product payload."},"media_kind":{"type":"string","enum":["image","video","audio","document","sticker"],"example":"image"},"view_once":{"type":"boolean","example":false},"mention_all":{"type":"boolean","example":false},"mentioned_jids":{"type":"array","items":{"type":"string"},"example":[]},"mentions":{"type":"object","additionalProperties":true,"description":"Mention map keyed by provider identifier."},"is_forwarded":{"type":"boolean","example":false},"link_preview":{"type":"object","additionalProperties":true,"description":"Link preview metadata."},"location":{"type":"object","additionalProperties":true,"description":"Location payload."},"contact":{"type":"object","additionalProperties":true,"description":"Contact card payload."},"cta_buttons":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Call-to-action button."}}}},"attachments":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["signed_id"],"properties":{"signed_id":{"type":"string","description":"ActiveStorage signed blob id.","example":"eyJfcmFpbHMiOnsibWVzc2FnZSI6ImJsb2IifX0"},"filename":{"type":"string","example":"reminder.pdf"},"content_type":{"type":"string","example":"application/pdf"},"byte_size":{"type":"integer","minimum":0,"example":2048}}}},"items":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Structured select or poll option."}},"is_voice_message":{"type":"boolean","example":false},"email_html_content":{"type":"string","example":"\u003cp\u003eAppointment reminder\u003c/p\u003e"},"to_emails":{"type":"array","items":{"type":"string","format":"email"},"example":["customer@example.com"]},"cc_emails":{"type":"array","items":{"type":"string","format":"email"},"example":[]},"bcc_emails":{"type":"array","items":{"type":"string","format":"email"},"example":[]},"template_params":{"type":"object","additionalProperties":true,"description":"Approved template identity and parameters."},"flow_params":{"type":"object","additionalProperties":true,"description":"WhatsApp Flow identity and parameters."},"whatsapp_transport":{"type":"string","enum":["cloud","web"],"example":"cloud"}}}},"attachments":{"type":"array","description":"Union of the signed attachment references present in parts.","items":{"type":"object","additionalProperties":false,"required":["signed_id"],"properties":{"signed_id":{"type":"string","description":"ActiveStorage signed blob id.","example":"eyJfcmFpbHMiOnsibWVzc2FnZSI6ImJsb2IifX0"},"filename":{"type":"string","example":"reminder.pdf"},"content_type":{"type":"string","example":"application/pdf"},"byte_size":{"type":"integer","minimum":0,"example":2048}}}}}},"policy_overrides":{"type":"object","additionalProperties":false,"description":"Explicit schedule-level overrides; omitted leaves inherit from inbox/account.","properties":{"on_inbound_reply":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["continue","pause","cancel","skip"],"example":"pause"}}},"on_conversation_resolved":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["continue","pause","cancel","skip"],"example":"continue"}}},"misfire":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["skip","manual_review","send_latest","catch_up_bounded"],"example":"send_latest"},"grace_seconds":{"type":"integer","minimum":0,"example":60},"max_occurrences":{"type":"integer","minimum":1,"maximum":500,"example":10},"spacing_seconds":{"type":"integer","minimum":0,"example":5}}},"transient_failure":{"type":"object","additionalProperties":false,"properties":{"max_attempts":{"type":"integer","minimum":1,"maximum":10,"example":3},"backoff_seconds":{"type":"array","maxItems":9,"items":{"type":"integer","minimum":0,"maximum":86400},"example":[30,120]},"exhausted_action":{"type":"string","enum":["skip","pause","cancel","manual_review"],"example":"manual_review"}}},"permanent_failure":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["skip","pause","cancel","manual_review"],"example":"manual_review"}}},"resume_behavior":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["preserve_schedule","shift_by_pause","skip_missed","catch_up_bounded"],"example":"preserve_schedule"},"max_occurrences":{"type":"integer","minimum":1,"maximum":500,"example":10},"spacing_seconds":{"type":"integer","minimum":0,"example":5}}},"quiet_hours":{"type":"object","additionalProperties":false,"properties":{"enabled":{"type":"boolean","example":false},"start":{"type":"string","pattern":"^(?:[01][0-9]|2[0-3]):[0-5][0-9]$","example":"22:00"},"end":{"type":"string","pattern":"^(?:[01][0-9]|2[0-3]):[0-5][0-9]$","example":"08:00"},"days":{"type":"array","uniqueItems":true,"items":{"type":"integer","minimum":0,"maximum":6},"example":[0,1,2,3,4,5,6]},"action":{"type":"string","enum":["allow","defer","skip","manual_review"],"example":"defer"}}},"overlap":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["allow","skip_new","defer_new","cancel_previous","manual_review"],"example":"allow"},"defer_seconds":{"type":"integer","minimum":1,"example":60}}},"inbox_change":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["follow_logical","cancel","pause","manual_review"],"example":"follow_logical"}}},"sender":{"type":"object","additionalProperties":false,"properties":{"type":{"type":"string","enum":["assigned_agent","schedule_creator","user","agent_bot","system"],"example":"system"},"id":{"type":["integer","null"],"minimum":1,"example":null},"missing":{"type":"string","enum":["fail","system","assigned_agent"],"example":"fail"}}},"variables":{"type":"object","additionalProperties":false,"properties":{"resolve_at":{"type":"string","enum":["publication","dispatch"],"example":"dispatch"},"missing":{"type":"string","enum":["fail","blank","skip"],"example":"fail"}}},"dst":{"type":"object","additionalProperties":false,"properties":{"nonexistent":{"type":"string","enum":["skip","shift_forward","shift_backward"],"example":"shift_forward"},"ambiguous":{"type":"string","enum":["first","second","skip"],"example":"first"}}},"materialization":{"type":"object","additionalProperties":false,"properties":{"horizon_seconds":{"type":"integer","minimum":1,"maximum":2592000,"example":2592000},"max_occurrences":{"type":"integer","minimum":1,"maximum":500,"example":500}}},"claim":{"type":"object","additionalProperties":false,"properties":{"lease_seconds":{"type":"integer","minimum":1,"maximum":900,"example":120},"recovery_grace_seconds":{"type":"integer","minimum":0,"maximum":3600,"example":30}}}}},"attachments_count":{"type":"integer","minimum":0,"example":0},"lock_version":{"type":"integer","example":0}}}}}}]}}},"example":{"payload":{"id":701,"name":"Appointment reminder","status":"active","conversation_id":42,"kind":"one_time","timezone":"America/Sao_Paulo","starts_at":"2026-08-22T13:00:00.000Z","version_number":1,"items":[{"id":801,"stable_key":"2dc1f16c-5191-4b3b-97b4-8f33e93dc969","position":1,"timing":{"anchor":"schedule_start","offset_seconds":0},"draft":{"version":1,"schema_version":1,"delay_ms":0,"parts":[{"content":"Olá, seu atendimento está marcado para amanhã.","content_type":"text","content_attributes":{"in_reply_to":88,"in_reply_to_external_id":"wamid.example","items":[{}],"email":{},"interactive":{},"wa_interactive":{},"poll":{},"catalog_product":{},"media_kind":"image","view_once":false,"mention_all":false,"mentioned_jids":[],"mentions":{},"is_forwarded":false,"link_preview":{},"location":{},"contact":{},"cta_buttons":[{}]},"attachments":[{"signed_id":"eyJfcmFpbHMiOnsibWVzc2FnZSI6ImJsb2IifX0","filename":"reminder.pdf","content_type":"application/pdf","byte_size":2048}],"items":[{}],"is_voice_message":false,"email_html_content":"\u003cp\u003eAppointment reminder\u003c/p\u003e","to_emails":["customer@example.com"],"cc_emails":[],"bcc_emails":[],"template_params":{},"flow_params":{},"whatsapp_transport":"cloud"}],"attachments":[{"signed_id":"eyJfcmFpbHMiOnsibWVzc2FnZSI6ImJsb2IifX0","filename":"reminder.pdf","content_type":"application/pdf","byte_size":2048}]},"policy_overrides":{"on_inbound_reply":{"action":"pause"},"on_conversation_resolved":{"action":"continue"},"misfire":{"action":"send_latest","grace_seconds":60,"max_occurrences":10,"spacing_seconds":5},"transient_failure":{"max_attempts":3,"backoff_seconds":[30,120],"exhausted_action":"manual_review"},"permanent_failure":{"action":"manual_review"},"resume_behavior":{"action":"preserve_schedule","max_occurrences":10,"spacing_seconds":5},"quiet_hours":{"enabled":false,"start":"22:00","end":"08:00","days":[0,1,2,3,4,5,6],"action":"defer"},"overlap":{"action":"allow","defer_seconds":60},"inbox_change":{"action":"follow_logical"},"sender":{"type":"system","id":null,"missing":"fail"},"variables":{"resolve_at":"dispatch","missing":"fail"},"dst":{"nonexistent":"shift_forward","ambiguous":"first"},"materialization":{"horizon_seconds":2592000,"max_occurrences":500},"claim":{"lease_seconds":120,"recovery_grace_seconds":30}},"attachments_count":0,"lock_version":0}],"inbox_id":7,"contact_id":81,"created_by_id":9,"next_occurrence_at":"2026-08-22T13:00:00.000Z","materialized_through_at":"2026-08-22T13:00:00.000Z","published_at":"2026-08-21T16:00:00.000Z","paused_at":null,"needs_attention_at":null,"completed_at":null,"canceled_at":null,"archived_at":null,"lock_version":1,"created_at":"2026-08-21T16:00:00.000Z","updated_at":"2026-08-21T16:00:00.000Z","created_by":{"id":9,"name":"Ana Agent"},"rrule":null,"resolved_policies":{},"policy_sources":{},"sender_config":{},"target_config":{}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"409":{"description":"Stale lock, concurrent dispatch or invalid lifecycle state."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["lock_version","scope"],"properties":{"lock_version":{"type":"integer","minimum":0,"example":1},"scope":{"type":"string","enum":["all_future"],"example":"all_future"}}},"example":{"lock_version":1,"scope":"all_future"}}}}}},"/api/v1/accounts/{account_id}/message_schedules/{id}/resume":{"post":{"tags":["Message Schedules"],"operationId":"auto_post_api_v1_accounts_account_id_message_schedules_id_resume","summary":"Resume message schedules","description":"Performs the resume operation on the targeted message schedule resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Idempotent replay of the already published schedule.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"allOf":[{"type":"object","additionalProperties":false,"properties":{"id":{"type":"integer","example":701},"name":{"type":"string","example":"Appointment reminder"},"status":{"type":"string","enum":["draft","active","paused","needs_attention","completed","canceled","archived"],"example":"active","description":"Lifecycle state of the message schedule."},"inbox_id":{"type":"integer","example":7},"contact_id":{"type":"integer","example":81},"created_by_id":{"type":"integer","example":9},"conversation_id":{"type":"integer","description":"Public conversation display id.","example":42},"next_occurrence_at":{"type":["string","null"],"format":"date-time","example":"2026-08-22T13:00:00.000Z"},"materialized_through_at":{"type":["string","null"],"format":"date-time","example":"2026-08-22T13:00:00.000Z"},"published_at":{"type":["string","null"],"format":"date-time","example":"2026-08-21T16:00:00.000Z"},"paused_at":{"type":["string","null"],"format":"date-time","example":null},"needs_attention_at":{"type":["string","null"],"format":"date-time","example":null},"completed_at":{"type":["string","null"],"format":"date-time","example":null},"canceled_at":{"type":["string","null"],"format":"date-time","example":null},"archived_at":{"type":["string","null"],"format":"date-time","example":null},"lock_version":{"type":"integer","example":1},"created_at":{"type":"string","format":"date-time","example":"2026-08-21T16:00:00.000Z"},"updated_at":{"type":"string","format":"date-time","example":"2026-08-21T16:00:00.000Z"},"created_by":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"integer","example":9},"name":{"type":"string","example":"Ana Agent"}}},"kind":{"type":"string","enum":["one_time","sequence","recurring_single","recurring_sequence"],"example":"one_time","description":"Temporal shape of the scheduled message plan."},"timezone":{"type":"string","example":"America/Sao_Paulo"},"starts_at":{"type":"string","format":"date-time","example":"2026-08-22T13:00:00.000Z"},"rrule":{"type":["string","null"],"example":null},"version_number":{"type":"integer","example":1}}},{"type":"object","properties":{"resolved_policies":{"type":"object","description":"Complete immutable policy snapshot keyed by item stable key.","additionalProperties":{"type":"object","additionalProperties":false,"description":"Explicit schedule-level overrides; omitted leaves inherit from inbox/account.","properties":{"on_inbound_reply":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["continue","pause","cancel","skip"],"example":"pause"}}},"on_conversation_resolved":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["continue","pause","cancel","skip"],"example":"continue"}}},"misfire":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["skip","manual_review","send_latest","catch_up_bounded"],"example":"send_latest"},"grace_seconds":{"type":"integer","minimum":0,"example":60},"max_occurrences":{"type":"integer","minimum":1,"maximum":500,"example":10},"spacing_seconds":{"type":"integer","minimum":0,"example":5}}},"transient_failure":{"type":"object","additionalProperties":false,"properties":{"max_attempts":{"type":"integer","minimum":1,"maximum":10,"example":3},"backoff_seconds":{"type":"array","maxItems":9,"items":{"type":"integer","minimum":0,"maximum":86400},"example":[30,120]},"exhausted_action":{"type":"string","enum":["skip","pause","cancel","manual_review"],"example":"manual_review"}}},"permanent_failure":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["skip","pause","cancel","manual_review"],"example":"manual_review"}}},"resume_behavior":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["preserve_schedule","shift_by_pause","skip_missed","catch_up_bounded"],"example":"preserve_schedule"},"max_occurrences":{"type":"integer","minimum":1,"maximum":500,"example":10},"spacing_seconds":{"type":"integer","minimum":0,"example":5}}},"quiet_hours":{"type":"object","additionalProperties":false,"properties":{"enabled":{"type":"boolean","example":false},"start":{"type":"string","pattern":"^(?:[01][0-9]|2[0-3]):[0-5][0-9]$","example":"22:00"},"end":{"type":"string","pattern":"^(?:[01][0-9]|2[0-3]):[0-5][0-9]$","example":"08:00"},"days":{"type":"array","uniqueItems":true,"items":{"type":"integer","minimum":0,"maximum":6},"example":[0,1,2,3,4,5,6]},"action":{"type":"string","enum":["allow","defer","skip","manual_review"],"example":"defer"}}},"overlap":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["allow","skip_new","defer_new","cancel_previous","manual_review"],"example":"allow"},"defer_seconds":{"type":"integer","minimum":1,"example":60}}},"inbox_change":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["follow_logical","cancel","pause","manual_review"],"example":"follow_logical"}}},"sender":{"type":"object","additionalProperties":false,"properties":{"type":{"type":"string","enum":["assigned_agent","schedule_creator","user","agent_bot","system"],"example":"system"},"id":{"type":["integer","null"],"minimum":1,"example":null},"missing":{"type":"string","enum":["fail","system","assigned_agent"],"example":"fail"}}},"variables":{"type":"object","additionalProperties":false,"properties":{"resolve_at":{"type":"string","enum":["publication","dispatch"],"example":"dispatch"},"missing":{"type":"string","enum":["fail","blank","skip"],"example":"fail"}}},"dst":{"type":"object","additionalProperties":false,"properties":{"nonexistent":{"type":"string","enum":["skip","shift_forward","shift_backward"],"example":"shift_forward"},"ambiguous":{"type":"string","enum":["first","second","skip"],"example":"first"}}},"materialization":{"type":"object","additionalProperties":false,"properties":{"horizon_seconds":{"type":"integer","minimum":1,"maximum":2592000,"example":2592000},"max_occurrences":{"type":"integer","minimum":1,"maximum":500,"example":500}}},"claim":{"type":"object","additionalProperties":false,"properties":{"lease_seconds":{"type":"integer","minimum":1,"maximum":900,"example":120},"recovery_grace_seconds":{"type":"integer","minimum":0,"maximum":3600,"example":30}}}}}},"policy_sources":{"type":"object","description":"Source map keyed by item stable key, then by policy path.","additionalProperties":{"type":"object","description":"Effective source keyed by policy path for this item.","additionalProperties":{"type":"string"}}},"sender_config":{"type":"object","additionalProperties":true,"description":"Server-authored sender snapshot; clients cannot submit it."},"target_config":{"type":"object","additionalProperties":true,"description":"Server-authored immutable conversation/inbox/contact target."},"items":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"integer","example":801},"stable_key":{"type":"string","format":"uuid","example":"2dc1f16c-5191-4b3b-97b4-8f33e93dc969"},"position":{"type":"integer","minimum":1,"example":1},"timing":{"type":"object","additionalProperties":false,"properties":{"anchor":{"type":"string","enum":["schedule_start","previous_scheduled","previous_dispatched"],"example":"schedule_start"},"offset_seconds":{"type":"integer","minimum":0,"example":0}}},"draft":{"type":"object","additionalProperties":false,"required":["parts"],"properties":{"version":{"type":"integer","enum":[1],"example":1},"schema_version":{"type":"integer","enum":[1],"example":1},"delay_ms":{"type":"integer","minimum":0,"maximum":300000,"example":0},"parts":{"type":"array","minItems":1,"maxItems":50,"items":{"type":"object","additionalProperties":false,"properties":{"content":{"type":"string","maxLength":150000,"example":"Olá, seu atendimento está marcado para amanhã."},"content_type":{"type":"string","enum":["text","input_select","sticker","poll"],"example":"text"},"content_attributes":{"type":"object","additionalProperties":false,"description":"Closed outbound metadata roots; rich provider objects remain JSON-shaped and are revalidated before dispatch.","properties":{"in_reply_to":{"type":"integer","example":88},"in_reply_to_external_id":{"type":"string","example":"wamid.example"},"items":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Provider-native option object."}},"email":{"type":"object","additionalProperties":true,"description":"Structured outbound e-mail metadata."},"interactive":{"type":"object","additionalProperties":true,"description":"WhatsApp Cloud interactive payload."},"wa_interactive":{"type":"object","additionalProperties":true,"description":"WazMeow interactive payload."},"poll":{"type":"object","additionalProperties":true,"description":"Poll payload."},"catalog_product":{"type":"object","additionalProperties":true,"description":"Catalog product payload."},"media_kind":{"type":"string","enum":["image","video","audio","document","sticker"],"example":"image"},"view_once":{"type":"boolean","example":false},"mention_all":{"type":"boolean","example":false},"mentioned_jids":{"type":"array","items":{"type":"string"},"example":[]},"mentions":{"type":"object","additionalProperties":true,"description":"Mention map keyed by provider identifier."},"is_forwarded":{"type":"boolean","example":false},"link_preview":{"type":"object","additionalProperties":true,"description":"Link preview metadata."},"location":{"type":"object","additionalProperties":true,"description":"Location payload."},"contact":{"type":"object","additionalProperties":true,"description":"Contact card payload."},"cta_buttons":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Call-to-action button."}}}},"attachments":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["signed_id"],"properties":{"signed_id":{"type":"string","description":"ActiveStorage signed blob id.","example":"eyJfcmFpbHMiOnsibWVzc2FnZSI6ImJsb2IifX0"},"filename":{"type":"string","example":"reminder.pdf"},"content_type":{"type":"string","example":"application/pdf"},"byte_size":{"type":"integer","minimum":0,"example":2048}}}},"items":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Structured select or poll option."}},"is_voice_message":{"type":"boolean","example":false},"email_html_content":{"type":"string","example":"\u003cp\u003eAppointment reminder\u003c/p\u003e"},"to_emails":{"type":"array","items":{"type":"string","format":"email"},"example":["customer@example.com"]},"cc_emails":{"type":"array","items":{"type":"string","format":"email"},"example":[]},"bcc_emails":{"type":"array","items":{"type":"string","format":"email"},"example":[]},"template_params":{"type":"object","additionalProperties":true,"description":"Approved template identity and parameters."},"flow_params":{"type":"object","additionalProperties":true,"description":"WhatsApp Flow identity and parameters."},"whatsapp_transport":{"type":"string","enum":["cloud","web"],"example":"cloud"}}}},"attachments":{"type":"array","description":"Union of the signed attachment references present in parts.","items":{"type":"object","additionalProperties":false,"required":["signed_id"],"properties":{"signed_id":{"type":"string","description":"ActiveStorage signed blob id.","example":"eyJfcmFpbHMiOnsibWVzc2FnZSI6ImJsb2IifX0"},"filename":{"type":"string","example":"reminder.pdf"},"content_type":{"type":"string","example":"application/pdf"},"byte_size":{"type":"integer","minimum":0,"example":2048}}}}}},"policy_overrides":{"type":"object","additionalProperties":false,"description":"Explicit schedule-level overrides; omitted leaves inherit from inbox/account.","properties":{"on_inbound_reply":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["continue","pause","cancel","skip"],"example":"pause"}}},"on_conversation_resolved":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["continue","pause","cancel","skip"],"example":"continue"}}},"misfire":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["skip","manual_review","send_latest","catch_up_bounded"],"example":"send_latest"},"grace_seconds":{"type":"integer","minimum":0,"example":60},"max_occurrences":{"type":"integer","minimum":1,"maximum":500,"example":10},"spacing_seconds":{"type":"integer","minimum":0,"example":5}}},"transient_failure":{"type":"object","additionalProperties":false,"properties":{"max_attempts":{"type":"integer","minimum":1,"maximum":10,"example":3},"backoff_seconds":{"type":"array","maxItems":9,"items":{"type":"integer","minimum":0,"maximum":86400},"example":[30,120]},"exhausted_action":{"type":"string","enum":["skip","pause","cancel","manual_review"],"example":"manual_review"}}},"permanent_failure":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["skip","pause","cancel","manual_review"],"example":"manual_review"}}},"resume_behavior":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["preserve_schedule","shift_by_pause","skip_missed","catch_up_bounded"],"example":"preserve_schedule"},"max_occurrences":{"type":"integer","minimum":1,"maximum":500,"example":10},"spacing_seconds":{"type":"integer","minimum":0,"example":5}}},"quiet_hours":{"type":"object","additionalProperties":false,"properties":{"enabled":{"type":"boolean","example":false},"start":{"type":"string","pattern":"^(?:[01][0-9]|2[0-3]):[0-5][0-9]$","example":"22:00"},"end":{"type":"string","pattern":"^(?:[01][0-9]|2[0-3]):[0-5][0-9]$","example":"08:00"},"days":{"type":"array","uniqueItems":true,"items":{"type":"integer","minimum":0,"maximum":6},"example":[0,1,2,3,4,5,6]},"action":{"type":"string","enum":["allow","defer","skip","manual_review"],"example":"defer"}}},"overlap":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["allow","skip_new","defer_new","cancel_previous","manual_review"],"example":"allow"},"defer_seconds":{"type":"integer","minimum":1,"example":60}}},"inbox_change":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["follow_logical","cancel","pause","manual_review"],"example":"follow_logical"}}},"sender":{"type":"object","additionalProperties":false,"properties":{"type":{"type":"string","enum":["assigned_agent","schedule_creator","user","agent_bot","system"],"example":"system"},"id":{"type":["integer","null"],"minimum":1,"example":null},"missing":{"type":"string","enum":["fail","system","assigned_agent"],"example":"fail"}}},"variables":{"type":"object","additionalProperties":false,"properties":{"resolve_at":{"type":"string","enum":["publication","dispatch"],"example":"dispatch"},"missing":{"type":"string","enum":["fail","blank","skip"],"example":"fail"}}},"dst":{"type":"object","additionalProperties":false,"properties":{"nonexistent":{"type":"string","enum":["skip","shift_forward","shift_backward"],"example":"shift_forward"},"ambiguous":{"type":"string","enum":["first","second","skip"],"example":"first"}}},"materialization":{"type":"object","additionalProperties":false,"properties":{"horizon_seconds":{"type":"integer","minimum":1,"maximum":2592000,"example":2592000},"max_occurrences":{"type":"integer","minimum":1,"maximum":500,"example":500}}},"claim":{"type":"object","additionalProperties":false,"properties":{"lease_seconds":{"type":"integer","minimum":1,"maximum":900,"example":120},"recovery_grace_seconds":{"type":"integer","minimum":0,"maximum":3600,"example":30}}}}},"attachments_count":{"type":"integer","minimum":0,"example":0},"lock_version":{"type":"integer","example":0}}}}}}]}}},"example":{"payload":{"id":701,"name":"Appointment reminder","status":"active","conversation_id":42,"kind":"one_time","timezone":"America/Sao_Paulo","starts_at":"2026-08-22T13:00:00.000Z","version_number":1,"items":[{"id":801,"stable_key":"2dc1f16c-5191-4b3b-97b4-8f33e93dc969","position":1,"timing":{"anchor":"schedule_start","offset_seconds":0},"draft":{"version":1,"schema_version":1,"delay_ms":0,"parts":[{"content":"Olá, seu atendimento está marcado para amanhã.","content_type":"text","content_attributes":{"in_reply_to":88,"in_reply_to_external_id":"wamid.example","items":[{}],"email":{},"interactive":{},"wa_interactive":{},"poll":{},"catalog_product":{},"media_kind":"image","view_once":false,"mention_all":false,"mentioned_jids":[],"mentions":{},"is_forwarded":false,"link_preview":{},"location":{},"contact":{},"cta_buttons":[{}]},"attachments":[{"signed_id":"eyJfcmFpbHMiOnsibWVzc2FnZSI6ImJsb2IifX0","filename":"reminder.pdf","content_type":"application/pdf","byte_size":2048}],"items":[{}],"is_voice_message":false,"email_html_content":"\u003cp\u003eAppointment reminder\u003c/p\u003e","to_emails":["customer@example.com"],"cc_emails":[],"bcc_emails":[],"template_params":{},"flow_params":{},"whatsapp_transport":"cloud"}],"attachments":[{"signed_id":"eyJfcmFpbHMiOnsibWVzc2FnZSI6ImJsb2IifX0","filename":"reminder.pdf","content_type":"application/pdf","byte_size":2048}]},"policy_overrides":{"on_inbound_reply":{"action":"pause"},"on_conversation_resolved":{"action":"continue"},"misfire":{"action":"send_latest","grace_seconds":60,"max_occurrences":10,"spacing_seconds":5},"transient_failure":{"max_attempts":3,"backoff_seconds":[30,120],"exhausted_action":"manual_review"},"permanent_failure":{"action":"manual_review"},"resume_behavior":{"action":"preserve_schedule","max_occurrences":10,"spacing_seconds":5},"quiet_hours":{"enabled":false,"start":"22:00","end":"08:00","days":[0,1,2,3,4,5,6],"action":"defer"},"overlap":{"action":"allow","defer_seconds":60},"inbox_change":{"action":"follow_logical"},"sender":{"type":"system","id":null,"missing":"fail"},"variables":{"resolve_at":"dispatch","missing":"fail"},"dst":{"nonexistent":"shift_forward","ambiguous":"first"},"materialization":{"horizon_seconds":2592000,"max_occurrences":500},"claim":{"lease_seconds":120,"recovery_grace_seconds":30}},"attachments_count":0,"lock_version":0}],"inbox_id":7,"contact_id":81,"created_by_id":9,"next_occurrence_at":"2026-08-22T13:00:00.000Z","materialized_through_at":"2026-08-22T13:00:00.000Z","published_at":"2026-08-21T16:00:00.000Z","paused_at":null,"needs_attention_at":null,"completed_at":null,"canceled_at":null,"archived_at":null,"lock_version":1,"created_at":"2026-08-21T16:00:00.000Z","updated_at":"2026-08-21T16:00:00.000Z","created_by":{"id":9,"name":"Ana Agent"},"rrule":null,"resolved_policies":{},"policy_sources":{},"sender_config":{},"target_config":{}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"409":{"description":"Stale lock, policy mismatch or invalid lifecycle state."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["lock_version","scope","resume_action"],"properties":{"lock_version":{"type":"integer","minimum":0,"example":1},"scope":{"type":"string","enum":["all_future"],"example":"all_future"},"resume_action":{"type":"string","enum":["preserve_schedule","shift_by_pause","skip_missed","catch_up_bounded"],"description":"Must match the schedule's published resume_behavior action.","example":"preserve_schedule"}}},"example":{"lock_version":1,"scope":"all_future","resume_action":"preserve_schedule"}}}}}},"/api/v1/accounts/{account_id}/message_schedules/{id}/cancel":{"post":{"tags":["Message Schedules"],"operationId":"auto_post_api_v1_accounts_account_id_message_schedules_id_cancel","summary":"Cancel message schedules","description":"Performs the cancel operation on the targeted message schedule resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Idempotent replay of the already published schedule.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"allOf":[{"type":"object","additionalProperties":false,"properties":{"id":{"type":"integer","example":701},"name":{"type":"string","example":"Appointment reminder"},"status":{"type":"string","enum":["draft","active","paused","needs_attention","completed","canceled","archived"],"example":"active","description":"Lifecycle state of the message schedule."},"inbox_id":{"type":"integer","example":7},"contact_id":{"type":"integer","example":81},"created_by_id":{"type":"integer","example":9},"conversation_id":{"type":"integer","description":"Public conversation display id.","example":42},"next_occurrence_at":{"type":["string","null"],"format":"date-time","example":"2026-08-22T13:00:00.000Z"},"materialized_through_at":{"type":["string","null"],"format":"date-time","example":"2026-08-22T13:00:00.000Z"},"published_at":{"type":["string","null"],"format":"date-time","example":"2026-08-21T16:00:00.000Z"},"paused_at":{"type":["string","null"],"format":"date-time","example":null},"needs_attention_at":{"type":["string","null"],"format":"date-time","example":null},"completed_at":{"type":["string","null"],"format":"date-time","example":null},"canceled_at":{"type":["string","null"],"format":"date-time","example":null},"archived_at":{"type":["string","null"],"format":"date-time","example":null},"lock_version":{"type":"integer","example":1},"created_at":{"type":"string","format":"date-time","example":"2026-08-21T16:00:00.000Z"},"updated_at":{"type":"string","format":"date-time","example":"2026-08-21T16:00:00.000Z"},"created_by":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"integer","example":9},"name":{"type":"string","example":"Ana Agent"}}},"kind":{"type":"string","enum":["one_time","sequence","recurring_single","recurring_sequence"],"example":"one_time","description":"Temporal shape of the scheduled message plan."},"timezone":{"type":"string","example":"America/Sao_Paulo"},"starts_at":{"type":"string","format":"date-time","example":"2026-08-22T13:00:00.000Z"},"rrule":{"type":["string","null"],"example":null},"version_number":{"type":"integer","example":1}}},{"type":"object","properties":{"resolved_policies":{"type":"object","description":"Complete immutable policy snapshot keyed by item stable key.","additionalProperties":{"type":"object","additionalProperties":false,"description":"Explicit schedule-level overrides; omitted leaves inherit from inbox/account.","properties":{"on_inbound_reply":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["continue","pause","cancel","skip"],"example":"pause"}}},"on_conversation_resolved":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["continue","pause","cancel","skip"],"example":"continue"}}},"misfire":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["skip","manual_review","send_latest","catch_up_bounded"],"example":"send_latest"},"grace_seconds":{"type":"integer","minimum":0,"example":60},"max_occurrences":{"type":"integer","minimum":1,"maximum":500,"example":10},"spacing_seconds":{"type":"integer","minimum":0,"example":5}}},"transient_failure":{"type":"object","additionalProperties":false,"properties":{"max_attempts":{"type":"integer","minimum":1,"maximum":10,"example":3},"backoff_seconds":{"type":"array","maxItems":9,"items":{"type":"integer","minimum":0,"maximum":86400},"example":[30,120]},"exhausted_action":{"type":"string","enum":["skip","pause","cancel","manual_review"],"example":"manual_review"}}},"permanent_failure":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["skip","pause","cancel","manual_review"],"example":"manual_review"}}},"resume_behavior":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["preserve_schedule","shift_by_pause","skip_missed","catch_up_bounded"],"example":"preserve_schedule"},"max_occurrences":{"type":"integer","minimum":1,"maximum":500,"example":10},"spacing_seconds":{"type":"integer","minimum":0,"example":5}}},"quiet_hours":{"type":"object","additionalProperties":false,"properties":{"enabled":{"type":"boolean","example":false},"start":{"type":"string","pattern":"^(?:[01][0-9]|2[0-3]):[0-5][0-9]$","example":"22:00"},"end":{"type":"string","pattern":"^(?:[01][0-9]|2[0-3]):[0-5][0-9]$","example":"08:00"},"days":{"type":"array","uniqueItems":true,"items":{"type":"integer","minimum":0,"maximum":6},"example":[0,1,2,3,4,5,6]},"action":{"type":"string","enum":["allow","defer","skip","manual_review"],"example":"defer"}}},"overlap":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["allow","skip_new","defer_new","cancel_previous","manual_review"],"example":"allow"},"defer_seconds":{"type":"integer","minimum":1,"example":60}}},"inbox_change":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["follow_logical","cancel","pause","manual_review"],"example":"follow_logical"}}},"sender":{"type":"object","additionalProperties":false,"properties":{"type":{"type":"string","enum":["assigned_agent","schedule_creator","user","agent_bot","system"],"example":"system"},"id":{"type":["integer","null"],"minimum":1,"example":null},"missing":{"type":"string","enum":["fail","system","assigned_agent"],"example":"fail"}}},"variables":{"type":"object","additionalProperties":false,"properties":{"resolve_at":{"type":"string","enum":["publication","dispatch"],"example":"dispatch"},"missing":{"type":"string","enum":["fail","blank","skip"],"example":"fail"}}},"dst":{"type":"object","additionalProperties":false,"properties":{"nonexistent":{"type":"string","enum":["skip","shift_forward","shift_backward"],"example":"shift_forward"},"ambiguous":{"type":"string","enum":["first","second","skip"],"example":"first"}}},"materialization":{"type":"object","additionalProperties":false,"properties":{"horizon_seconds":{"type":"integer","minimum":1,"maximum":2592000,"example":2592000},"max_occurrences":{"type":"integer","minimum":1,"maximum":500,"example":500}}},"claim":{"type":"object","additionalProperties":false,"properties":{"lease_seconds":{"type":"integer","minimum":1,"maximum":900,"example":120},"recovery_grace_seconds":{"type":"integer","minimum":0,"maximum":3600,"example":30}}}}}},"policy_sources":{"type":"object","description":"Source map keyed by item stable key, then by policy path.","additionalProperties":{"type":"object","description":"Effective source keyed by policy path for this item.","additionalProperties":{"type":"string"}}},"sender_config":{"type":"object","additionalProperties":true,"description":"Server-authored sender snapshot; clients cannot submit it."},"target_config":{"type":"object","additionalProperties":true,"description":"Server-authored immutable conversation/inbox/contact target."},"items":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"integer","example":801},"stable_key":{"type":"string","format":"uuid","example":"2dc1f16c-5191-4b3b-97b4-8f33e93dc969"},"position":{"type":"integer","minimum":1,"example":1},"timing":{"type":"object","additionalProperties":false,"properties":{"anchor":{"type":"string","enum":["schedule_start","previous_scheduled","previous_dispatched"],"example":"schedule_start"},"offset_seconds":{"type":"integer","minimum":0,"example":0}}},"draft":{"type":"object","additionalProperties":false,"required":["parts"],"properties":{"version":{"type":"integer","enum":[1],"example":1},"schema_version":{"type":"integer","enum":[1],"example":1},"delay_ms":{"type":"integer","minimum":0,"maximum":300000,"example":0},"parts":{"type":"array","minItems":1,"maxItems":50,"items":{"type":"object","additionalProperties":false,"properties":{"content":{"type":"string","maxLength":150000,"example":"Olá, seu atendimento está marcado para amanhã."},"content_type":{"type":"string","enum":["text","input_select","sticker","poll"],"example":"text"},"content_attributes":{"type":"object","additionalProperties":false,"description":"Closed outbound metadata roots; rich provider objects remain JSON-shaped and are revalidated before dispatch.","properties":{"in_reply_to":{"type":"integer","example":88},"in_reply_to_external_id":{"type":"string","example":"wamid.example"},"items":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Provider-native option object."}},"email":{"type":"object","additionalProperties":true,"description":"Structured outbound e-mail metadata."},"interactive":{"type":"object","additionalProperties":true,"description":"WhatsApp Cloud interactive payload."},"wa_interactive":{"type":"object","additionalProperties":true,"description":"WazMeow interactive payload."},"poll":{"type":"object","additionalProperties":true,"description":"Poll payload."},"catalog_product":{"type":"object","additionalProperties":true,"description":"Catalog product payload."},"media_kind":{"type":"string","enum":["image","video","audio","document","sticker"],"example":"image"},"view_once":{"type":"boolean","example":false},"mention_all":{"type":"boolean","example":false},"mentioned_jids":{"type":"array","items":{"type":"string"},"example":[]},"mentions":{"type":"object","additionalProperties":true,"description":"Mention map keyed by provider identifier."},"is_forwarded":{"type":"boolean","example":false},"link_preview":{"type":"object","additionalProperties":true,"description":"Link preview metadata."},"location":{"type":"object","additionalProperties":true,"description":"Location payload."},"contact":{"type":"object","additionalProperties":true,"description":"Contact card payload."},"cta_buttons":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Call-to-action button."}}}},"attachments":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["signed_id"],"properties":{"signed_id":{"type":"string","description":"ActiveStorage signed blob id.","example":"eyJfcmFpbHMiOnsibWVzc2FnZSI6ImJsb2IifX0"},"filename":{"type":"string","example":"reminder.pdf"},"content_type":{"type":"string","example":"application/pdf"},"byte_size":{"type":"integer","minimum":0,"example":2048}}}},"items":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Structured select or poll option."}},"is_voice_message":{"type":"boolean","example":false},"email_html_content":{"type":"string","example":"\u003cp\u003eAppointment reminder\u003c/p\u003e"},"to_emails":{"type":"array","items":{"type":"string","format":"email"},"example":["customer@example.com"]},"cc_emails":{"type":"array","items":{"type":"string","format":"email"},"example":[]},"bcc_emails":{"type":"array","items":{"type":"string","format":"email"},"example":[]},"template_params":{"type":"object","additionalProperties":true,"description":"Approved template identity and parameters."},"flow_params":{"type":"object","additionalProperties":true,"description":"WhatsApp Flow identity and parameters."},"whatsapp_transport":{"type":"string","enum":["cloud","web"],"example":"cloud"}}}},"attachments":{"type":"array","description":"Union of the signed attachment references present in parts.","items":{"type":"object","additionalProperties":false,"required":["signed_id"],"properties":{"signed_id":{"type":"string","description":"ActiveStorage signed blob id.","example":"eyJfcmFpbHMiOnsibWVzc2FnZSI6ImJsb2IifX0"},"filename":{"type":"string","example":"reminder.pdf"},"content_type":{"type":"string","example":"application/pdf"},"byte_size":{"type":"integer","minimum":0,"example":2048}}}}}},"policy_overrides":{"type":"object","additionalProperties":false,"description":"Explicit schedule-level overrides; omitted leaves inherit from inbox/account.","properties":{"on_inbound_reply":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["continue","pause","cancel","skip"],"example":"pause"}}},"on_conversation_resolved":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["continue","pause","cancel","skip"],"example":"continue"}}},"misfire":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["skip","manual_review","send_latest","catch_up_bounded"],"example":"send_latest"},"grace_seconds":{"type":"integer","minimum":0,"example":60},"max_occurrences":{"type":"integer","minimum":1,"maximum":500,"example":10},"spacing_seconds":{"type":"integer","minimum":0,"example":5}}},"transient_failure":{"type":"object","additionalProperties":false,"properties":{"max_attempts":{"type":"integer","minimum":1,"maximum":10,"example":3},"backoff_seconds":{"type":"array","maxItems":9,"items":{"type":"integer","minimum":0,"maximum":86400},"example":[30,120]},"exhausted_action":{"type":"string","enum":["skip","pause","cancel","manual_review"],"example":"manual_review"}}},"permanent_failure":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["skip","pause","cancel","manual_review"],"example":"manual_review"}}},"resume_behavior":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["preserve_schedule","shift_by_pause","skip_missed","catch_up_bounded"],"example":"preserve_schedule"},"max_occurrences":{"type":"integer","minimum":1,"maximum":500,"example":10},"spacing_seconds":{"type":"integer","minimum":0,"example":5}}},"quiet_hours":{"type":"object","additionalProperties":false,"properties":{"enabled":{"type":"boolean","example":false},"start":{"type":"string","pattern":"^(?:[01][0-9]|2[0-3]):[0-5][0-9]$","example":"22:00"},"end":{"type":"string","pattern":"^(?:[01][0-9]|2[0-3]):[0-5][0-9]$","example":"08:00"},"days":{"type":"array","uniqueItems":true,"items":{"type":"integer","minimum":0,"maximum":6},"example":[0,1,2,3,4,5,6]},"action":{"type":"string","enum":["allow","defer","skip","manual_review"],"example":"defer"}}},"overlap":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["allow","skip_new","defer_new","cancel_previous","manual_review"],"example":"allow"},"defer_seconds":{"type":"integer","minimum":1,"example":60}}},"inbox_change":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["follow_logical","cancel","pause","manual_review"],"example":"follow_logical"}}},"sender":{"type":"object","additionalProperties":false,"properties":{"type":{"type":"string","enum":["assigned_agent","schedule_creator","user","agent_bot","system"],"example":"system"},"id":{"type":["integer","null"],"minimum":1,"example":null},"missing":{"type":"string","enum":["fail","system","assigned_agent"],"example":"fail"}}},"variables":{"type":"object","additionalProperties":false,"properties":{"resolve_at":{"type":"string","enum":["publication","dispatch"],"example":"dispatch"},"missing":{"type":"string","enum":["fail","blank","skip"],"example":"fail"}}},"dst":{"type":"object","additionalProperties":false,"properties":{"nonexistent":{"type":"string","enum":["skip","shift_forward","shift_backward"],"example":"shift_forward"},"ambiguous":{"type":"string","enum":["first","second","skip"],"example":"first"}}},"materialization":{"type":"object","additionalProperties":false,"properties":{"horizon_seconds":{"type":"integer","minimum":1,"maximum":2592000,"example":2592000},"max_occurrences":{"type":"integer","minimum":1,"maximum":500,"example":500}}},"claim":{"type":"object","additionalProperties":false,"properties":{"lease_seconds":{"type":"integer","minimum":1,"maximum":900,"example":120},"recovery_grace_seconds":{"type":"integer","minimum":0,"maximum":3600,"example":30}}}}},"attachments_count":{"type":"integer","minimum":0,"example":0},"lock_version":{"type":"integer","example":0}}}}}}]}}},"example":{"payload":{"id":701,"name":"Appointment reminder","status":"active","conversation_id":42,"kind":"one_time","timezone":"America/Sao_Paulo","starts_at":"2026-08-22T13:00:00.000Z","version_number":1,"items":[{"id":801,"stable_key":"2dc1f16c-5191-4b3b-97b4-8f33e93dc969","position":1,"timing":{"anchor":"schedule_start","offset_seconds":0},"draft":{"version":1,"schema_version":1,"delay_ms":0,"parts":[{"content":"Olá, seu atendimento está marcado para amanhã.","content_type":"text","content_attributes":{"in_reply_to":88,"in_reply_to_external_id":"wamid.example","items":[{}],"email":{},"interactive":{},"wa_interactive":{},"poll":{},"catalog_product":{},"media_kind":"image","view_once":false,"mention_all":false,"mentioned_jids":[],"mentions":{},"is_forwarded":false,"link_preview":{},"location":{},"contact":{},"cta_buttons":[{}]},"attachments":[{"signed_id":"eyJfcmFpbHMiOnsibWVzc2FnZSI6ImJsb2IifX0","filename":"reminder.pdf","content_type":"application/pdf","byte_size":2048}],"items":[{}],"is_voice_message":false,"email_html_content":"\u003cp\u003eAppointment reminder\u003c/p\u003e","to_emails":["customer@example.com"],"cc_emails":[],"bcc_emails":[],"template_params":{},"flow_params":{},"whatsapp_transport":"cloud"}],"attachments":[{"signed_id":"eyJfcmFpbHMiOnsibWVzc2FnZSI6ImJsb2IifX0","filename":"reminder.pdf","content_type":"application/pdf","byte_size":2048}]},"policy_overrides":{"on_inbound_reply":{"action":"pause"},"on_conversation_resolved":{"action":"continue"},"misfire":{"action":"send_latest","grace_seconds":60,"max_occurrences":10,"spacing_seconds":5},"transient_failure":{"max_attempts":3,"backoff_seconds":[30,120],"exhausted_action":"manual_review"},"permanent_failure":{"action":"manual_review"},"resume_behavior":{"action":"preserve_schedule","max_occurrences":10,"spacing_seconds":5},"quiet_hours":{"enabled":false,"start":"22:00","end":"08:00","days":[0,1,2,3,4,5,6],"action":"defer"},"overlap":{"action":"allow","defer_seconds":60},"inbox_change":{"action":"follow_logical"},"sender":{"type":"system","id":null,"missing":"fail"},"variables":{"resolve_at":"dispatch","missing":"fail"},"dst":{"nonexistent":"shift_forward","ambiguous":"first"},"materialization":{"horizon_seconds":2592000,"max_occurrences":500},"claim":{"lease_seconds":120,"recovery_grace_seconds":30}},"attachments_count":0,"lock_version":0}],"inbox_id":7,"contact_id":81,"created_by_id":9,"next_occurrence_at":"2026-08-22T13:00:00.000Z","materialized_through_at":"2026-08-22T13:00:00.000Z","published_at":"2026-08-21T16:00:00.000Z","paused_at":null,"needs_attention_at":null,"completed_at":null,"canceled_at":null,"archived_at":null,"lock_version":1,"created_at":"2026-08-21T16:00:00.000Z","updated_at":"2026-08-21T16:00:00.000Z","created_by":{"id":9,"name":"Ana Agent"},"rrule":null,"resolved_policies":{},"policy_sources":{},"sender_config":{},"target_config":{}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"409":{"description":"Stale lock, concurrent dispatch or invalid lifecycle state."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["lock_version","scope"],"properties":{"lock_version":{"type":"integer","minimum":0,"example":1},"scope":{"type":"string","enum":["all_future"],"example":"all_future"}}},"example":{"lock_version":1,"scope":"all_future"}}}}}},"/api/v1/accounts/{account_id}/message_schedules/{id}/archive":{"post":{"tags":["Message Schedules"],"operationId":"auto_post_api_v1_accounts_account_id_message_schedules_id_archive","summary":"Archive message schedules","description":"Performs the archive operation on the targeted message schedule resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Idempotent replay of the already published schedule.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"allOf":[{"type":"object","additionalProperties":false,"properties":{"id":{"type":"integer","example":701},"name":{"type":"string","example":"Appointment reminder"},"status":{"type":"string","enum":["draft","active","paused","needs_attention","completed","canceled","archived"],"example":"active","description":"Lifecycle state of the message schedule."},"inbox_id":{"type":"integer","example":7},"contact_id":{"type":"integer","example":81},"created_by_id":{"type":"integer","example":9},"conversation_id":{"type":"integer","description":"Public conversation display id.","example":42},"next_occurrence_at":{"type":["string","null"],"format":"date-time","example":"2026-08-22T13:00:00.000Z"},"materialized_through_at":{"type":["string","null"],"format":"date-time","example":"2026-08-22T13:00:00.000Z"},"published_at":{"type":["string","null"],"format":"date-time","example":"2026-08-21T16:00:00.000Z"},"paused_at":{"type":["string","null"],"format":"date-time","example":null},"needs_attention_at":{"type":["string","null"],"format":"date-time","example":null},"completed_at":{"type":["string","null"],"format":"date-time","example":null},"canceled_at":{"type":["string","null"],"format":"date-time","example":null},"archived_at":{"type":["string","null"],"format":"date-time","example":null},"lock_version":{"type":"integer","example":1},"created_at":{"type":"string","format":"date-time","example":"2026-08-21T16:00:00.000Z"},"updated_at":{"type":"string","format":"date-time","example":"2026-08-21T16:00:00.000Z"},"created_by":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"integer","example":9},"name":{"type":"string","example":"Ana Agent"}}},"kind":{"type":"string","enum":["one_time","sequence","recurring_single","recurring_sequence"],"example":"one_time","description":"Temporal shape of the scheduled message plan."},"timezone":{"type":"string","example":"America/Sao_Paulo"},"starts_at":{"type":"string","format":"date-time","example":"2026-08-22T13:00:00.000Z"},"rrule":{"type":["string","null"],"example":null},"version_number":{"type":"integer","example":1}}},{"type":"object","properties":{"resolved_policies":{"type":"object","description":"Complete immutable policy snapshot keyed by item stable key.","additionalProperties":{"type":"object","additionalProperties":false,"description":"Explicit schedule-level overrides; omitted leaves inherit from inbox/account.","properties":{"on_inbound_reply":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["continue","pause","cancel","skip"],"example":"pause"}}},"on_conversation_resolved":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["continue","pause","cancel","skip"],"example":"continue"}}},"misfire":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["skip","manual_review","send_latest","catch_up_bounded"],"example":"send_latest"},"grace_seconds":{"type":"integer","minimum":0,"example":60},"max_occurrences":{"type":"integer","minimum":1,"maximum":500,"example":10},"spacing_seconds":{"type":"integer","minimum":0,"example":5}}},"transient_failure":{"type":"object","additionalProperties":false,"properties":{"max_attempts":{"type":"integer","minimum":1,"maximum":10,"example":3},"backoff_seconds":{"type":"array","maxItems":9,"items":{"type":"integer","minimum":0,"maximum":86400},"example":[30,120]},"exhausted_action":{"type":"string","enum":["skip","pause","cancel","manual_review"],"example":"manual_review"}}},"permanent_failure":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["skip","pause","cancel","manual_review"],"example":"manual_review"}}},"resume_behavior":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["preserve_schedule","shift_by_pause","skip_missed","catch_up_bounded"],"example":"preserve_schedule"},"max_occurrences":{"type":"integer","minimum":1,"maximum":500,"example":10},"spacing_seconds":{"type":"integer","minimum":0,"example":5}}},"quiet_hours":{"type":"object","additionalProperties":false,"properties":{"enabled":{"type":"boolean","example":false},"start":{"type":"string","pattern":"^(?:[01][0-9]|2[0-3]):[0-5][0-9]$","example":"22:00"},"end":{"type":"string","pattern":"^(?:[01][0-9]|2[0-3]):[0-5][0-9]$","example":"08:00"},"days":{"type":"array","uniqueItems":true,"items":{"type":"integer","minimum":0,"maximum":6},"example":[0,1,2,3,4,5,6]},"action":{"type":"string","enum":["allow","defer","skip","manual_review"],"example":"defer"}}},"overlap":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["allow","skip_new","defer_new","cancel_previous","manual_review"],"example":"allow"},"defer_seconds":{"type":"integer","minimum":1,"example":60}}},"inbox_change":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["follow_logical","cancel","pause","manual_review"],"example":"follow_logical"}}},"sender":{"type":"object","additionalProperties":false,"properties":{"type":{"type":"string","enum":["assigned_agent","schedule_creator","user","agent_bot","system"],"example":"system"},"id":{"type":["integer","null"],"minimum":1,"example":null},"missing":{"type":"string","enum":["fail","system","assigned_agent"],"example":"fail"}}},"variables":{"type":"object","additionalProperties":false,"properties":{"resolve_at":{"type":"string","enum":["publication","dispatch"],"example":"dispatch"},"missing":{"type":"string","enum":["fail","blank","skip"],"example":"fail"}}},"dst":{"type":"object","additionalProperties":false,"properties":{"nonexistent":{"type":"string","enum":["skip","shift_forward","shift_backward"],"example":"shift_forward"},"ambiguous":{"type":"string","enum":["first","second","skip"],"example":"first"}}},"materialization":{"type":"object","additionalProperties":false,"properties":{"horizon_seconds":{"type":"integer","minimum":1,"maximum":2592000,"example":2592000},"max_occurrences":{"type":"integer","minimum":1,"maximum":500,"example":500}}},"claim":{"type":"object","additionalProperties":false,"properties":{"lease_seconds":{"type":"integer","minimum":1,"maximum":900,"example":120},"recovery_grace_seconds":{"type":"integer","minimum":0,"maximum":3600,"example":30}}}}}},"policy_sources":{"type":"object","description":"Source map keyed by item stable key, then by policy path.","additionalProperties":{"type":"object","description":"Effective source keyed by policy path for this item.","additionalProperties":{"type":"string"}}},"sender_config":{"type":"object","additionalProperties":true,"description":"Server-authored sender snapshot; clients cannot submit it."},"target_config":{"type":"object","additionalProperties":true,"description":"Server-authored immutable conversation/inbox/contact target."},"items":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"integer","example":801},"stable_key":{"type":"string","format":"uuid","example":"2dc1f16c-5191-4b3b-97b4-8f33e93dc969"},"position":{"type":"integer","minimum":1,"example":1},"timing":{"type":"object","additionalProperties":false,"properties":{"anchor":{"type":"string","enum":["schedule_start","previous_scheduled","previous_dispatched"],"example":"schedule_start"},"offset_seconds":{"type":"integer","minimum":0,"example":0}}},"draft":{"type":"object","additionalProperties":false,"required":["parts"],"properties":{"version":{"type":"integer","enum":[1],"example":1},"schema_version":{"type":"integer","enum":[1],"example":1},"delay_ms":{"type":"integer","minimum":0,"maximum":300000,"example":0},"parts":{"type":"array","minItems":1,"maxItems":50,"items":{"type":"object","additionalProperties":false,"properties":{"content":{"type":"string","maxLength":150000,"example":"Olá, seu atendimento está marcado para amanhã."},"content_type":{"type":"string","enum":["text","input_select","sticker","poll"],"example":"text"},"content_attributes":{"type":"object","additionalProperties":false,"description":"Closed outbound metadata roots; rich provider objects remain JSON-shaped and are revalidated before dispatch.","properties":{"in_reply_to":{"type":"integer","example":88},"in_reply_to_external_id":{"type":"string","example":"wamid.example"},"items":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Provider-native option object."}},"email":{"type":"object","additionalProperties":true,"description":"Structured outbound e-mail metadata."},"interactive":{"type":"object","additionalProperties":true,"description":"WhatsApp Cloud interactive payload."},"wa_interactive":{"type":"object","additionalProperties":true,"description":"WazMeow interactive payload."},"poll":{"type":"object","additionalProperties":true,"description":"Poll payload."},"catalog_product":{"type":"object","additionalProperties":true,"description":"Catalog product payload."},"media_kind":{"type":"string","enum":["image","video","audio","document","sticker"],"example":"image"},"view_once":{"type":"boolean","example":false},"mention_all":{"type":"boolean","example":false},"mentioned_jids":{"type":"array","items":{"type":"string"},"example":[]},"mentions":{"type":"object","additionalProperties":true,"description":"Mention map keyed by provider identifier."},"is_forwarded":{"type":"boolean","example":false},"link_preview":{"type":"object","additionalProperties":true,"description":"Link preview metadata."},"location":{"type":"object","additionalProperties":true,"description":"Location payload."},"contact":{"type":"object","additionalProperties":true,"description":"Contact card payload."},"cta_buttons":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Call-to-action button."}}}},"attachments":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["signed_id"],"properties":{"signed_id":{"type":"string","description":"ActiveStorage signed blob id.","example":"eyJfcmFpbHMiOnsibWVzc2FnZSI6ImJsb2IifX0"},"filename":{"type":"string","example":"reminder.pdf"},"content_type":{"type":"string","example":"application/pdf"},"byte_size":{"type":"integer","minimum":0,"example":2048}}}},"items":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Structured select or poll option."}},"is_voice_message":{"type":"boolean","example":false},"email_html_content":{"type":"string","example":"\u003cp\u003eAppointment reminder\u003c/p\u003e"},"to_emails":{"type":"array","items":{"type":"string","format":"email"},"example":["customer@example.com"]},"cc_emails":{"type":"array","items":{"type":"string","format":"email"},"example":[]},"bcc_emails":{"type":"array","items":{"type":"string","format":"email"},"example":[]},"template_params":{"type":"object","additionalProperties":true,"description":"Approved template identity and parameters."},"flow_params":{"type":"object","additionalProperties":true,"description":"WhatsApp Flow identity and parameters."},"whatsapp_transport":{"type":"string","enum":["cloud","web"],"example":"cloud"}}}},"attachments":{"type":"array","description":"Union of the signed attachment references present in parts.","items":{"type":"object","additionalProperties":false,"required":["signed_id"],"properties":{"signed_id":{"type":"string","description":"ActiveStorage signed blob id.","example":"eyJfcmFpbHMiOnsibWVzc2FnZSI6ImJsb2IifX0"},"filename":{"type":"string","example":"reminder.pdf"},"content_type":{"type":"string","example":"application/pdf"},"byte_size":{"type":"integer","minimum":0,"example":2048}}}}}},"policy_overrides":{"type":"object","additionalProperties":false,"description":"Explicit schedule-level overrides; omitted leaves inherit from inbox/account.","properties":{"on_inbound_reply":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["continue","pause","cancel","skip"],"example":"pause"}}},"on_conversation_resolved":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["continue","pause","cancel","skip"],"example":"continue"}}},"misfire":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["skip","manual_review","send_latest","catch_up_bounded"],"example":"send_latest"},"grace_seconds":{"type":"integer","minimum":0,"example":60},"max_occurrences":{"type":"integer","minimum":1,"maximum":500,"example":10},"spacing_seconds":{"type":"integer","minimum":0,"example":5}}},"transient_failure":{"type":"object","additionalProperties":false,"properties":{"max_attempts":{"type":"integer","minimum":1,"maximum":10,"example":3},"backoff_seconds":{"type":"array","maxItems":9,"items":{"type":"integer","minimum":0,"maximum":86400},"example":[30,120]},"exhausted_action":{"type":"string","enum":["skip","pause","cancel","manual_review"],"example":"manual_review"}}},"permanent_failure":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["skip","pause","cancel","manual_review"],"example":"manual_review"}}},"resume_behavior":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["preserve_schedule","shift_by_pause","skip_missed","catch_up_bounded"],"example":"preserve_schedule"},"max_occurrences":{"type":"integer","minimum":1,"maximum":500,"example":10},"spacing_seconds":{"type":"integer","minimum":0,"example":5}}},"quiet_hours":{"type":"object","additionalProperties":false,"properties":{"enabled":{"type":"boolean","example":false},"start":{"type":"string","pattern":"^(?:[01][0-9]|2[0-3]):[0-5][0-9]$","example":"22:00"},"end":{"type":"string","pattern":"^(?:[01][0-9]|2[0-3]):[0-5][0-9]$","example":"08:00"},"days":{"type":"array","uniqueItems":true,"items":{"type":"integer","minimum":0,"maximum":6},"example":[0,1,2,3,4,5,6]},"action":{"type":"string","enum":["allow","defer","skip","manual_review"],"example":"defer"}}},"overlap":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["allow","skip_new","defer_new","cancel_previous","manual_review"],"example":"allow"},"defer_seconds":{"type":"integer","minimum":1,"example":60}}},"inbox_change":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["follow_logical","cancel","pause","manual_review"],"example":"follow_logical"}}},"sender":{"type":"object","additionalProperties":false,"properties":{"type":{"type":"string","enum":["assigned_agent","schedule_creator","user","agent_bot","system"],"example":"system"},"id":{"type":["integer","null"],"minimum":1,"example":null},"missing":{"type":"string","enum":["fail","system","assigned_agent"],"example":"fail"}}},"variables":{"type":"object","additionalProperties":false,"properties":{"resolve_at":{"type":"string","enum":["publication","dispatch"],"example":"dispatch"},"missing":{"type":"string","enum":["fail","blank","skip"],"example":"fail"}}},"dst":{"type":"object","additionalProperties":false,"properties":{"nonexistent":{"type":"string","enum":["skip","shift_forward","shift_backward"],"example":"shift_forward"},"ambiguous":{"type":"string","enum":["first","second","skip"],"example":"first"}}},"materialization":{"type":"object","additionalProperties":false,"properties":{"horizon_seconds":{"type":"integer","minimum":1,"maximum":2592000,"example":2592000},"max_occurrences":{"type":"integer","minimum":1,"maximum":500,"example":500}}},"claim":{"type":"object","additionalProperties":false,"properties":{"lease_seconds":{"type":"integer","minimum":1,"maximum":900,"example":120},"recovery_grace_seconds":{"type":"integer","minimum":0,"maximum":3600,"example":30}}}}},"attachments_count":{"type":"integer","minimum":0,"example":0},"lock_version":{"type":"integer","example":0}}}}}}]}}},"example":{"payload":{"id":701,"name":"Appointment reminder","status":"active","conversation_id":42,"kind":"one_time","timezone":"America/Sao_Paulo","starts_at":"2026-08-22T13:00:00.000Z","version_number":1,"items":[{"id":801,"stable_key":"2dc1f16c-5191-4b3b-97b4-8f33e93dc969","position":1,"timing":{"anchor":"schedule_start","offset_seconds":0},"draft":{"version":1,"schema_version":1,"delay_ms":0,"parts":[{"content":"Olá, seu atendimento está marcado para amanhã.","content_type":"text","content_attributes":{"in_reply_to":88,"in_reply_to_external_id":"wamid.example","items":[{}],"email":{},"interactive":{},"wa_interactive":{},"poll":{},"catalog_product":{},"media_kind":"image","view_once":false,"mention_all":false,"mentioned_jids":[],"mentions":{},"is_forwarded":false,"link_preview":{},"location":{},"contact":{},"cta_buttons":[{}]},"attachments":[{"signed_id":"eyJfcmFpbHMiOnsibWVzc2FnZSI6ImJsb2IifX0","filename":"reminder.pdf","content_type":"application/pdf","byte_size":2048}],"items":[{}],"is_voice_message":false,"email_html_content":"\u003cp\u003eAppointment reminder\u003c/p\u003e","to_emails":["customer@example.com"],"cc_emails":[],"bcc_emails":[],"template_params":{},"flow_params":{},"whatsapp_transport":"cloud"}],"attachments":[{"signed_id":"eyJfcmFpbHMiOnsibWVzc2FnZSI6ImJsb2IifX0","filename":"reminder.pdf","content_type":"application/pdf","byte_size":2048}]},"policy_overrides":{"on_inbound_reply":{"action":"pause"},"on_conversation_resolved":{"action":"continue"},"misfire":{"action":"send_latest","grace_seconds":60,"max_occurrences":10,"spacing_seconds":5},"transient_failure":{"max_attempts":3,"backoff_seconds":[30,120],"exhausted_action":"manual_review"},"permanent_failure":{"action":"manual_review"},"resume_behavior":{"action":"preserve_schedule","max_occurrences":10,"spacing_seconds":5},"quiet_hours":{"enabled":false,"start":"22:00","end":"08:00","days":[0,1,2,3,4,5,6],"action":"defer"},"overlap":{"action":"allow","defer_seconds":60},"inbox_change":{"action":"follow_logical"},"sender":{"type":"system","id":null,"missing":"fail"},"variables":{"resolve_at":"dispatch","missing":"fail"},"dst":{"nonexistent":"shift_forward","ambiguous":"first"},"materialization":{"horizon_seconds":2592000,"max_occurrences":500},"claim":{"lease_seconds":120,"recovery_grace_seconds":30}},"attachments_count":0,"lock_version":0}],"inbox_id":7,"contact_id":81,"created_by_id":9,"next_occurrence_at":"2026-08-22T13:00:00.000Z","materialized_through_at":"2026-08-22T13:00:00.000Z","published_at":"2026-08-21T16:00:00.000Z","paused_at":null,"needs_attention_at":null,"completed_at":null,"canceled_at":null,"archived_at":null,"lock_version":1,"created_at":"2026-08-21T16:00:00.000Z","updated_at":"2026-08-21T16:00:00.000Z","created_by":{"id":9,"name":"Ana Agent"},"rrule":null,"resolved_policies":{},"policy_sources":{},"sender_config":{},"target_config":{}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"409":{"description":"Stale lock, concurrent dispatch or invalid lifecycle state."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["lock_version","scope"],"properties":{"lock_version":{"type":"integer","minimum":0,"example":1},"scope":{"type":"string","enum":["all_future"],"example":"all_future"}}},"example":{"lock_version":1,"scope":"all_future"}}}}}},"/api/v1/accounts/{account_id}/message_schedules/{id}/retry":{"post":{"tags":["Message Schedules"],"operationId":"auto_post_api_v1_accounts_account_id_message_schedules_id_retry","summary":"Retry message schedules","description":"Performs the retry operation on the targeted message schedule resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Idempotent replay of the already published schedule.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"allOf":[{"type":"object","additionalProperties":false,"properties":{"id":{"type":"integer","example":701},"name":{"type":"string","example":"Appointment reminder"},"status":{"type":"string","enum":["draft","active","paused","needs_attention","completed","canceled","archived"],"example":"active","description":"Lifecycle state of the message schedule."},"inbox_id":{"type":"integer","example":7},"contact_id":{"type":"integer","example":81},"created_by_id":{"type":"integer","example":9},"conversation_id":{"type":"integer","description":"Public conversation display id.","example":42},"next_occurrence_at":{"type":["string","null"],"format":"date-time","example":"2026-08-22T13:00:00.000Z"},"materialized_through_at":{"type":["string","null"],"format":"date-time","example":"2026-08-22T13:00:00.000Z"},"published_at":{"type":["string","null"],"format":"date-time","example":"2026-08-21T16:00:00.000Z"},"paused_at":{"type":["string","null"],"format":"date-time","example":null},"needs_attention_at":{"type":["string","null"],"format":"date-time","example":null},"completed_at":{"type":["string","null"],"format":"date-time","example":null},"canceled_at":{"type":["string","null"],"format":"date-time","example":null},"archived_at":{"type":["string","null"],"format":"date-time","example":null},"lock_version":{"type":"integer","example":1},"created_at":{"type":"string","format":"date-time","example":"2026-08-21T16:00:00.000Z"},"updated_at":{"type":"string","format":"date-time","example":"2026-08-21T16:00:00.000Z"},"created_by":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"integer","example":9},"name":{"type":"string","example":"Ana Agent"}}},"kind":{"type":"string","enum":["one_time","sequence","recurring_single","recurring_sequence"],"example":"one_time","description":"Temporal shape of the scheduled message plan."},"timezone":{"type":"string","example":"America/Sao_Paulo"},"starts_at":{"type":"string","format":"date-time","example":"2026-08-22T13:00:00.000Z"},"rrule":{"type":["string","null"],"example":null},"version_number":{"type":"integer","example":1}}},{"type":"object","properties":{"resolved_policies":{"type":"object","description":"Complete immutable policy snapshot keyed by item stable key.","additionalProperties":{"type":"object","additionalProperties":false,"description":"Explicit schedule-level overrides; omitted leaves inherit from inbox/account.","properties":{"on_inbound_reply":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["continue","pause","cancel","skip"],"example":"pause"}}},"on_conversation_resolved":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["continue","pause","cancel","skip"],"example":"continue"}}},"misfire":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["skip","manual_review","send_latest","catch_up_bounded"],"example":"send_latest"},"grace_seconds":{"type":"integer","minimum":0,"example":60},"max_occurrences":{"type":"integer","minimum":1,"maximum":500,"example":10},"spacing_seconds":{"type":"integer","minimum":0,"example":5}}},"transient_failure":{"type":"object","additionalProperties":false,"properties":{"max_attempts":{"type":"integer","minimum":1,"maximum":10,"example":3},"backoff_seconds":{"type":"array","maxItems":9,"items":{"type":"integer","minimum":0,"maximum":86400},"example":[30,120]},"exhausted_action":{"type":"string","enum":["skip","pause","cancel","manual_review"],"example":"manual_review"}}},"permanent_failure":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["skip","pause","cancel","manual_review"],"example":"manual_review"}}},"resume_behavior":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["preserve_schedule","shift_by_pause","skip_missed","catch_up_bounded"],"example":"preserve_schedule"},"max_occurrences":{"type":"integer","minimum":1,"maximum":500,"example":10},"spacing_seconds":{"type":"integer","minimum":0,"example":5}}},"quiet_hours":{"type":"object","additionalProperties":false,"properties":{"enabled":{"type":"boolean","example":false},"start":{"type":"string","pattern":"^(?:[01][0-9]|2[0-3]):[0-5][0-9]$","example":"22:00"},"end":{"type":"string","pattern":"^(?:[01][0-9]|2[0-3]):[0-5][0-9]$","example":"08:00"},"days":{"type":"array","uniqueItems":true,"items":{"type":"integer","minimum":0,"maximum":6},"example":[0,1,2,3,4,5,6]},"action":{"type":"string","enum":["allow","defer","skip","manual_review"],"example":"defer"}}},"overlap":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["allow","skip_new","defer_new","cancel_previous","manual_review"],"example":"allow"},"defer_seconds":{"type":"integer","minimum":1,"example":60}}},"inbox_change":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["follow_logical","cancel","pause","manual_review"],"example":"follow_logical"}}},"sender":{"type":"object","additionalProperties":false,"properties":{"type":{"type":"string","enum":["assigned_agent","schedule_creator","user","agent_bot","system"],"example":"system"},"id":{"type":["integer","null"],"minimum":1,"example":null},"missing":{"type":"string","enum":["fail","system","assigned_agent"],"example":"fail"}}},"variables":{"type":"object","additionalProperties":false,"properties":{"resolve_at":{"type":"string","enum":["publication","dispatch"],"example":"dispatch"},"missing":{"type":"string","enum":["fail","blank","skip"],"example":"fail"}}},"dst":{"type":"object","additionalProperties":false,"properties":{"nonexistent":{"type":"string","enum":["skip","shift_forward","shift_backward"],"example":"shift_forward"},"ambiguous":{"type":"string","enum":["first","second","skip"],"example":"first"}}},"materialization":{"type":"object","additionalProperties":false,"properties":{"horizon_seconds":{"type":"integer","minimum":1,"maximum":2592000,"example":2592000},"max_occurrences":{"type":"integer","minimum":1,"maximum":500,"example":500}}},"claim":{"type":"object","additionalProperties":false,"properties":{"lease_seconds":{"type":"integer","minimum":1,"maximum":900,"example":120},"recovery_grace_seconds":{"type":"integer","minimum":0,"maximum":3600,"example":30}}}}}},"policy_sources":{"type":"object","description":"Source map keyed by item stable key, then by policy path.","additionalProperties":{"type":"object","description":"Effective source keyed by policy path for this item.","additionalProperties":{"type":"string"}}},"sender_config":{"type":"object","additionalProperties":true,"description":"Server-authored sender snapshot; clients cannot submit it."},"target_config":{"type":"object","additionalProperties":true,"description":"Server-authored immutable conversation/inbox/contact target."},"items":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"integer","example":801},"stable_key":{"type":"string","format":"uuid","example":"2dc1f16c-5191-4b3b-97b4-8f33e93dc969"},"position":{"type":"integer","minimum":1,"example":1},"timing":{"type":"object","additionalProperties":false,"properties":{"anchor":{"type":"string","enum":["schedule_start","previous_scheduled","previous_dispatched"],"example":"schedule_start"},"offset_seconds":{"type":"integer","minimum":0,"example":0}}},"draft":{"type":"object","additionalProperties":false,"required":["parts"],"properties":{"version":{"type":"integer","enum":[1],"example":1},"schema_version":{"type":"integer","enum":[1],"example":1},"delay_ms":{"type":"integer","minimum":0,"maximum":300000,"example":0},"parts":{"type":"array","minItems":1,"maxItems":50,"items":{"type":"object","additionalProperties":false,"properties":{"content":{"type":"string","maxLength":150000,"example":"Olá, seu atendimento está marcado para amanhã."},"content_type":{"type":"string","enum":["text","input_select","sticker","poll"],"example":"text"},"content_attributes":{"type":"object","additionalProperties":false,"description":"Closed outbound metadata roots; rich provider objects remain JSON-shaped and are revalidated before dispatch.","properties":{"in_reply_to":{"type":"integer","example":88},"in_reply_to_external_id":{"type":"string","example":"wamid.example"},"items":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Provider-native option object."}},"email":{"type":"object","additionalProperties":true,"description":"Structured outbound e-mail metadata."},"interactive":{"type":"object","additionalProperties":true,"description":"WhatsApp Cloud interactive payload."},"wa_interactive":{"type":"object","additionalProperties":true,"description":"WazMeow interactive payload."},"poll":{"type":"object","additionalProperties":true,"description":"Poll payload."},"catalog_product":{"type":"object","additionalProperties":true,"description":"Catalog product payload."},"media_kind":{"type":"string","enum":["image","video","audio","document","sticker"],"example":"image"},"view_once":{"type":"boolean","example":false},"mention_all":{"type":"boolean","example":false},"mentioned_jids":{"type":"array","items":{"type":"string"},"example":[]},"mentions":{"type":"object","additionalProperties":true,"description":"Mention map keyed by provider identifier."},"is_forwarded":{"type":"boolean","example":false},"link_preview":{"type":"object","additionalProperties":true,"description":"Link preview metadata."},"location":{"type":"object","additionalProperties":true,"description":"Location payload."},"contact":{"type":"object","additionalProperties":true,"description":"Contact card payload."},"cta_buttons":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Call-to-action button."}}}},"attachments":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["signed_id"],"properties":{"signed_id":{"type":"string","description":"ActiveStorage signed blob id.","example":"eyJfcmFpbHMiOnsibWVzc2FnZSI6ImJsb2IifX0"},"filename":{"type":"string","example":"reminder.pdf"},"content_type":{"type":"string","example":"application/pdf"},"byte_size":{"type":"integer","minimum":0,"example":2048}}}},"items":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Structured select or poll option."}},"is_voice_message":{"type":"boolean","example":false},"email_html_content":{"type":"string","example":"\u003cp\u003eAppointment reminder\u003c/p\u003e"},"to_emails":{"type":"array","items":{"type":"string","format":"email"},"example":["customer@example.com"]},"cc_emails":{"type":"array","items":{"type":"string","format":"email"},"example":[]},"bcc_emails":{"type":"array","items":{"type":"string","format":"email"},"example":[]},"template_params":{"type":"object","additionalProperties":true,"description":"Approved template identity and parameters."},"flow_params":{"type":"object","additionalProperties":true,"description":"WhatsApp Flow identity and parameters."},"whatsapp_transport":{"type":"string","enum":["cloud","web"],"example":"cloud"}}}},"attachments":{"type":"array","description":"Union of the signed attachment references present in parts.","items":{"type":"object","additionalProperties":false,"required":["signed_id"],"properties":{"signed_id":{"type":"string","description":"ActiveStorage signed blob id.","example":"eyJfcmFpbHMiOnsibWVzc2FnZSI6ImJsb2IifX0"},"filename":{"type":"string","example":"reminder.pdf"},"content_type":{"type":"string","example":"application/pdf"},"byte_size":{"type":"integer","minimum":0,"example":2048}}}}}},"policy_overrides":{"type":"object","additionalProperties":false,"description":"Explicit schedule-level overrides; omitted leaves inherit from inbox/account.","properties":{"on_inbound_reply":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["continue","pause","cancel","skip"],"example":"pause"}}},"on_conversation_resolved":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["continue","pause","cancel","skip"],"example":"continue"}}},"misfire":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["skip","manual_review","send_latest","catch_up_bounded"],"example":"send_latest"},"grace_seconds":{"type":"integer","minimum":0,"example":60},"max_occurrences":{"type":"integer","minimum":1,"maximum":500,"example":10},"spacing_seconds":{"type":"integer","minimum":0,"example":5}}},"transient_failure":{"type":"object","additionalProperties":false,"properties":{"max_attempts":{"type":"integer","minimum":1,"maximum":10,"example":3},"backoff_seconds":{"type":"array","maxItems":9,"items":{"type":"integer","minimum":0,"maximum":86400},"example":[30,120]},"exhausted_action":{"type":"string","enum":["skip","pause","cancel","manual_review"],"example":"manual_review"}}},"permanent_failure":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["skip","pause","cancel","manual_review"],"example":"manual_review"}}},"resume_behavior":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["preserve_schedule","shift_by_pause","skip_missed","catch_up_bounded"],"example":"preserve_schedule"},"max_occurrences":{"type":"integer","minimum":1,"maximum":500,"example":10},"spacing_seconds":{"type":"integer","minimum":0,"example":5}}},"quiet_hours":{"type":"object","additionalProperties":false,"properties":{"enabled":{"type":"boolean","example":false},"start":{"type":"string","pattern":"^(?:[01][0-9]|2[0-3]):[0-5][0-9]$","example":"22:00"},"end":{"type":"string","pattern":"^(?:[01][0-9]|2[0-3]):[0-5][0-9]$","example":"08:00"},"days":{"type":"array","uniqueItems":true,"items":{"type":"integer","minimum":0,"maximum":6},"example":[0,1,2,3,4,5,6]},"action":{"type":"string","enum":["allow","defer","skip","manual_review"],"example":"defer"}}},"overlap":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["allow","skip_new","defer_new","cancel_previous","manual_review"],"example":"allow"},"defer_seconds":{"type":"integer","minimum":1,"example":60}}},"inbox_change":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["follow_logical","cancel","pause","manual_review"],"example":"follow_logical"}}},"sender":{"type":"object","additionalProperties":false,"properties":{"type":{"type":"string","enum":["assigned_agent","schedule_creator","user","agent_bot","system"],"example":"system"},"id":{"type":["integer","null"],"minimum":1,"example":null},"missing":{"type":"string","enum":["fail","system","assigned_agent"],"example":"fail"}}},"variables":{"type":"object","additionalProperties":false,"properties":{"resolve_at":{"type":"string","enum":["publication","dispatch"],"example":"dispatch"},"missing":{"type":"string","enum":["fail","blank","skip"],"example":"fail"}}},"dst":{"type":"object","additionalProperties":false,"properties":{"nonexistent":{"type":"string","enum":["skip","shift_forward","shift_backward"],"example":"shift_forward"},"ambiguous":{"type":"string","enum":["first","second","skip"],"example":"first"}}},"materialization":{"type":"object","additionalProperties":false,"properties":{"horizon_seconds":{"type":"integer","minimum":1,"maximum":2592000,"example":2592000},"max_occurrences":{"type":"integer","minimum":1,"maximum":500,"example":500}}},"claim":{"type":"object","additionalProperties":false,"properties":{"lease_seconds":{"type":"integer","minimum":1,"maximum":900,"example":120},"recovery_grace_seconds":{"type":"integer","minimum":0,"maximum":3600,"example":30}}}}},"attachments_count":{"type":"integer","minimum":0,"example":0},"lock_version":{"type":"integer","example":0}}}}}}]}}},"example":{"payload":{"id":701,"name":"Appointment reminder","status":"active","conversation_id":42,"kind":"one_time","timezone":"America/Sao_Paulo","starts_at":"2026-08-22T13:00:00.000Z","version_number":1,"items":[{"id":801,"stable_key":"2dc1f16c-5191-4b3b-97b4-8f33e93dc969","position":1,"timing":{"anchor":"schedule_start","offset_seconds":0},"draft":{"version":1,"schema_version":1,"delay_ms":0,"parts":[{"content":"Olá, seu atendimento está marcado para amanhã.","content_type":"text","content_attributes":{"in_reply_to":88,"in_reply_to_external_id":"wamid.example","items":[{}],"email":{},"interactive":{},"wa_interactive":{},"poll":{},"catalog_product":{},"media_kind":"image","view_once":false,"mention_all":false,"mentioned_jids":[],"mentions":{},"is_forwarded":false,"link_preview":{},"location":{},"contact":{},"cta_buttons":[{}]},"attachments":[{"signed_id":"eyJfcmFpbHMiOnsibWVzc2FnZSI6ImJsb2IifX0","filename":"reminder.pdf","content_type":"application/pdf","byte_size":2048}],"items":[{}],"is_voice_message":false,"email_html_content":"\u003cp\u003eAppointment reminder\u003c/p\u003e","to_emails":["customer@example.com"],"cc_emails":[],"bcc_emails":[],"template_params":{},"flow_params":{},"whatsapp_transport":"cloud"}],"attachments":[{"signed_id":"eyJfcmFpbHMiOnsibWVzc2FnZSI6ImJsb2IifX0","filename":"reminder.pdf","content_type":"application/pdf","byte_size":2048}]},"policy_overrides":{"on_inbound_reply":{"action":"pause"},"on_conversation_resolved":{"action":"continue"},"misfire":{"action":"send_latest","grace_seconds":60,"max_occurrences":10,"spacing_seconds":5},"transient_failure":{"max_attempts":3,"backoff_seconds":[30,120],"exhausted_action":"manual_review"},"permanent_failure":{"action":"manual_review"},"resume_behavior":{"action":"preserve_schedule","max_occurrences":10,"spacing_seconds":5},"quiet_hours":{"enabled":false,"start":"22:00","end":"08:00","days":[0,1,2,3,4,5,6],"action":"defer"},"overlap":{"action":"allow","defer_seconds":60},"inbox_change":{"action":"follow_logical"},"sender":{"type":"system","id":null,"missing":"fail"},"variables":{"resolve_at":"dispatch","missing":"fail"},"dst":{"nonexistent":"shift_forward","ambiguous":"first"},"materialization":{"horizon_seconds":2592000,"max_occurrences":500},"claim":{"lease_seconds":120,"recovery_grace_seconds":30}},"attachments_count":0,"lock_version":0}],"inbox_id":7,"contact_id":81,"created_by_id":9,"next_occurrence_at":"2026-08-22T13:00:00.000Z","materialized_through_at":"2026-08-22T13:00:00.000Z","published_at":"2026-08-21T16:00:00.000Z","paused_at":null,"needs_attention_at":null,"completed_at":null,"canceled_at":null,"archived_at":null,"lock_version":1,"created_at":"2026-08-21T16:00:00.000Z","updated_at":"2026-08-21T16:00:00.000Z","created_by":{"id":9,"name":"Ana Agent"},"rrule":null,"resolved_policies":{},"policy_sources":{},"sender_config":{},"target_config":{}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"409":{"description":"Stale lock, concurrent dispatch or invalid lifecycle state."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["lock_version","scope"],"properties":{"lock_version":{"type":"integer","minimum":0,"example":1},"scope":{"type":"string","enum":["all_future"],"example":"all_future"}}},"example":{"lock_version":1,"scope":"all_future"}}}}}},"/api/v1/accounts/{account_id}/message_schedules/{id}/reconcile":{"post":{"tags":["Message Schedules"],"operationId":"auto_post_api_v1_accounts_account_id_message_schedules_id_reconcile","summary":"Reconcile message schedules","description":"Performs the reconcile operation on the targeted message schedule resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Idempotent replay of the already published schedule.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"allOf":[{"type":"object","additionalProperties":false,"properties":{"id":{"type":"integer","example":701},"name":{"type":"string","example":"Appointment reminder"},"status":{"type":"string","enum":["draft","active","paused","needs_attention","completed","canceled","archived"],"example":"active","description":"Lifecycle state of the message schedule."},"inbox_id":{"type":"integer","example":7},"contact_id":{"type":"integer","example":81},"created_by_id":{"type":"integer","example":9},"conversation_id":{"type":"integer","description":"Public conversation display id.","example":42},"next_occurrence_at":{"type":["string","null"],"format":"date-time","example":"2026-08-22T13:00:00.000Z"},"materialized_through_at":{"type":["string","null"],"format":"date-time","example":"2026-08-22T13:00:00.000Z"},"published_at":{"type":["string","null"],"format":"date-time","example":"2026-08-21T16:00:00.000Z"},"paused_at":{"type":["string","null"],"format":"date-time","example":null},"needs_attention_at":{"type":["string","null"],"format":"date-time","example":null},"completed_at":{"type":["string","null"],"format":"date-time","example":null},"canceled_at":{"type":["string","null"],"format":"date-time","example":null},"archived_at":{"type":["string","null"],"format":"date-time","example":null},"lock_version":{"type":"integer","example":1},"created_at":{"type":"string","format":"date-time","example":"2026-08-21T16:00:00.000Z"},"updated_at":{"type":"string","format":"date-time","example":"2026-08-21T16:00:00.000Z"},"created_by":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"integer","example":9},"name":{"type":"string","example":"Ana Agent"}}},"kind":{"type":"string","enum":["one_time","sequence","recurring_single","recurring_sequence"],"example":"one_time","description":"Temporal shape of the scheduled message plan."},"timezone":{"type":"string","example":"America/Sao_Paulo"},"starts_at":{"type":"string","format":"date-time","example":"2026-08-22T13:00:00.000Z"},"rrule":{"type":["string","null"],"example":null},"version_number":{"type":"integer","example":1}}},{"type":"object","properties":{"resolved_policies":{"type":"object","description":"Complete immutable policy snapshot keyed by item stable key.","additionalProperties":{"type":"object","additionalProperties":false,"description":"Explicit schedule-level overrides; omitted leaves inherit from inbox/account.","properties":{"on_inbound_reply":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["continue","pause","cancel","skip"],"example":"pause"}}},"on_conversation_resolved":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["continue","pause","cancel","skip"],"example":"continue"}}},"misfire":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["skip","manual_review","send_latest","catch_up_bounded"],"example":"send_latest"},"grace_seconds":{"type":"integer","minimum":0,"example":60},"max_occurrences":{"type":"integer","minimum":1,"maximum":500,"example":10},"spacing_seconds":{"type":"integer","minimum":0,"example":5}}},"transient_failure":{"type":"object","additionalProperties":false,"properties":{"max_attempts":{"type":"integer","minimum":1,"maximum":10,"example":3},"backoff_seconds":{"type":"array","maxItems":9,"items":{"type":"integer","minimum":0,"maximum":86400},"example":[30,120]},"exhausted_action":{"type":"string","enum":["skip","pause","cancel","manual_review"],"example":"manual_review"}}},"permanent_failure":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["skip","pause","cancel","manual_review"],"example":"manual_review"}}},"resume_behavior":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["preserve_schedule","shift_by_pause","skip_missed","catch_up_bounded"],"example":"preserve_schedule"},"max_occurrences":{"type":"integer","minimum":1,"maximum":500,"example":10},"spacing_seconds":{"type":"integer","minimum":0,"example":5}}},"quiet_hours":{"type":"object","additionalProperties":false,"properties":{"enabled":{"type":"boolean","example":false},"start":{"type":"string","pattern":"^(?:[01][0-9]|2[0-3]):[0-5][0-9]$","example":"22:00"},"end":{"type":"string","pattern":"^(?:[01][0-9]|2[0-3]):[0-5][0-9]$","example":"08:00"},"days":{"type":"array","uniqueItems":true,"items":{"type":"integer","minimum":0,"maximum":6},"example":[0,1,2,3,4,5,6]},"action":{"type":"string","enum":["allow","defer","skip","manual_review"],"example":"defer"}}},"overlap":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["allow","skip_new","defer_new","cancel_previous","manual_review"],"example":"allow"},"defer_seconds":{"type":"integer","minimum":1,"example":60}}},"inbox_change":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["follow_logical","cancel","pause","manual_review"],"example":"follow_logical"}}},"sender":{"type":"object","additionalProperties":false,"properties":{"type":{"type":"string","enum":["assigned_agent","schedule_creator","user","agent_bot","system"],"example":"system"},"id":{"type":["integer","null"],"minimum":1,"example":null},"missing":{"type":"string","enum":["fail","system","assigned_agent"],"example":"fail"}}},"variables":{"type":"object","additionalProperties":false,"properties":{"resolve_at":{"type":"string","enum":["publication","dispatch"],"example":"dispatch"},"missing":{"type":"string","enum":["fail","blank","skip"],"example":"fail"}}},"dst":{"type":"object","additionalProperties":false,"properties":{"nonexistent":{"type":"string","enum":["skip","shift_forward","shift_backward"],"example":"shift_forward"},"ambiguous":{"type":"string","enum":["first","second","skip"],"example":"first"}}},"materialization":{"type":"object","additionalProperties":false,"properties":{"horizon_seconds":{"type":"integer","minimum":1,"maximum":2592000,"example":2592000},"max_occurrences":{"type":"integer","minimum":1,"maximum":500,"example":500}}},"claim":{"type":"object","additionalProperties":false,"properties":{"lease_seconds":{"type":"integer","minimum":1,"maximum":900,"example":120},"recovery_grace_seconds":{"type":"integer","minimum":0,"maximum":3600,"example":30}}}}}},"policy_sources":{"type":"object","description":"Source map keyed by item stable key, then by policy path.","additionalProperties":{"type":"object","description":"Effective source keyed by policy path for this item.","additionalProperties":{"type":"string"}}},"sender_config":{"type":"object","additionalProperties":true,"description":"Server-authored sender snapshot; clients cannot submit it."},"target_config":{"type":"object","additionalProperties":true,"description":"Server-authored immutable conversation/inbox/contact target."},"items":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"integer","example":801},"stable_key":{"type":"string","format":"uuid","example":"2dc1f16c-5191-4b3b-97b4-8f33e93dc969"},"position":{"type":"integer","minimum":1,"example":1},"timing":{"type":"object","additionalProperties":false,"properties":{"anchor":{"type":"string","enum":["schedule_start","previous_scheduled","previous_dispatched"],"example":"schedule_start"},"offset_seconds":{"type":"integer","minimum":0,"example":0}}},"draft":{"type":"object","additionalProperties":false,"required":["parts"],"properties":{"version":{"type":"integer","enum":[1],"example":1},"schema_version":{"type":"integer","enum":[1],"example":1},"delay_ms":{"type":"integer","minimum":0,"maximum":300000,"example":0},"parts":{"type":"array","minItems":1,"maxItems":50,"items":{"type":"object","additionalProperties":false,"properties":{"content":{"type":"string","maxLength":150000,"example":"Olá, seu atendimento está marcado para amanhã."},"content_type":{"type":"string","enum":["text","input_select","sticker","poll"],"example":"text"},"content_attributes":{"type":"object","additionalProperties":false,"description":"Closed outbound metadata roots; rich provider objects remain JSON-shaped and are revalidated before dispatch.","properties":{"in_reply_to":{"type":"integer","example":88},"in_reply_to_external_id":{"type":"string","example":"wamid.example"},"items":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Provider-native option object."}},"email":{"type":"object","additionalProperties":true,"description":"Structured outbound e-mail metadata."},"interactive":{"type":"object","additionalProperties":true,"description":"WhatsApp Cloud interactive payload."},"wa_interactive":{"type":"object","additionalProperties":true,"description":"WazMeow interactive payload."},"poll":{"type":"object","additionalProperties":true,"description":"Poll payload."},"catalog_product":{"type":"object","additionalProperties":true,"description":"Catalog product payload."},"media_kind":{"type":"string","enum":["image","video","audio","document","sticker"],"example":"image"},"view_once":{"type":"boolean","example":false},"mention_all":{"type":"boolean","example":false},"mentioned_jids":{"type":"array","items":{"type":"string"},"example":[]},"mentions":{"type":"object","additionalProperties":true,"description":"Mention map keyed by provider identifier."},"is_forwarded":{"type":"boolean","example":false},"link_preview":{"type":"object","additionalProperties":true,"description":"Link preview metadata."},"location":{"type":"object","additionalProperties":true,"description":"Location payload."},"contact":{"type":"object","additionalProperties":true,"description":"Contact card payload."},"cta_buttons":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Call-to-action button."}}}},"attachments":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["signed_id"],"properties":{"signed_id":{"type":"string","description":"ActiveStorage signed blob id.","example":"eyJfcmFpbHMiOnsibWVzc2FnZSI6ImJsb2IifX0"},"filename":{"type":"string","example":"reminder.pdf"},"content_type":{"type":"string","example":"application/pdf"},"byte_size":{"type":"integer","minimum":0,"example":2048}}}},"items":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Structured select or poll option."}},"is_voice_message":{"type":"boolean","example":false},"email_html_content":{"type":"string","example":"\u003cp\u003eAppointment reminder\u003c/p\u003e"},"to_emails":{"type":"array","items":{"type":"string","format":"email"},"example":["customer@example.com"]},"cc_emails":{"type":"array","items":{"type":"string","format":"email"},"example":[]},"bcc_emails":{"type":"array","items":{"type":"string","format":"email"},"example":[]},"template_params":{"type":"object","additionalProperties":true,"description":"Approved template identity and parameters."},"flow_params":{"type":"object","additionalProperties":true,"description":"WhatsApp Flow identity and parameters."},"whatsapp_transport":{"type":"string","enum":["cloud","web"],"example":"cloud"}}}},"attachments":{"type":"array","description":"Union of the signed attachment references present in parts.","items":{"type":"object","additionalProperties":false,"required":["signed_id"],"properties":{"signed_id":{"type":"string","description":"ActiveStorage signed blob id.","example":"eyJfcmFpbHMiOnsibWVzc2FnZSI6ImJsb2IifX0"},"filename":{"type":"string","example":"reminder.pdf"},"content_type":{"type":"string","example":"application/pdf"},"byte_size":{"type":"integer","minimum":0,"example":2048}}}}}},"policy_overrides":{"type":"object","additionalProperties":false,"description":"Explicit schedule-level overrides; omitted leaves inherit from inbox/account.","properties":{"on_inbound_reply":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["continue","pause","cancel","skip"],"example":"pause"}}},"on_conversation_resolved":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["continue","pause","cancel","skip"],"example":"continue"}}},"misfire":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["skip","manual_review","send_latest","catch_up_bounded"],"example":"send_latest"},"grace_seconds":{"type":"integer","minimum":0,"example":60},"max_occurrences":{"type":"integer","minimum":1,"maximum":500,"example":10},"spacing_seconds":{"type":"integer","minimum":0,"example":5}}},"transient_failure":{"type":"object","additionalProperties":false,"properties":{"max_attempts":{"type":"integer","minimum":1,"maximum":10,"example":3},"backoff_seconds":{"type":"array","maxItems":9,"items":{"type":"integer","minimum":0,"maximum":86400},"example":[30,120]},"exhausted_action":{"type":"string","enum":["skip","pause","cancel","manual_review"],"example":"manual_review"}}},"permanent_failure":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["skip","pause","cancel","manual_review"],"example":"manual_review"}}},"resume_behavior":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["preserve_schedule","shift_by_pause","skip_missed","catch_up_bounded"],"example":"preserve_schedule"},"max_occurrences":{"type":"integer","minimum":1,"maximum":500,"example":10},"spacing_seconds":{"type":"integer","minimum":0,"example":5}}},"quiet_hours":{"type":"object","additionalProperties":false,"properties":{"enabled":{"type":"boolean","example":false},"start":{"type":"string","pattern":"^(?:[01][0-9]|2[0-3]):[0-5][0-9]$","example":"22:00"},"end":{"type":"string","pattern":"^(?:[01][0-9]|2[0-3]):[0-5][0-9]$","example":"08:00"},"days":{"type":"array","uniqueItems":true,"items":{"type":"integer","minimum":0,"maximum":6},"example":[0,1,2,3,4,5,6]},"action":{"type":"string","enum":["allow","defer","skip","manual_review"],"example":"defer"}}},"overlap":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["allow","skip_new","defer_new","cancel_previous","manual_review"],"example":"allow"},"defer_seconds":{"type":"integer","minimum":1,"example":60}}},"inbox_change":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["follow_logical","cancel","pause","manual_review"],"example":"follow_logical"}}},"sender":{"type":"object","additionalProperties":false,"properties":{"type":{"type":"string","enum":["assigned_agent","schedule_creator","user","agent_bot","system"],"example":"system"},"id":{"type":["integer","null"],"minimum":1,"example":null},"missing":{"type":"string","enum":["fail","system","assigned_agent"],"example":"fail"}}},"variables":{"type":"object","additionalProperties":false,"properties":{"resolve_at":{"type":"string","enum":["publication","dispatch"],"example":"dispatch"},"missing":{"type":"string","enum":["fail","blank","skip"],"example":"fail"}}},"dst":{"type":"object","additionalProperties":false,"properties":{"nonexistent":{"type":"string","enum":["skip","shift_forward","shift_backward"],"example":"shift_forward"},"ambiguous":{"type":"string","enum":["first","second","skip"],"example":"first"}}},"materialization":{"type":"object","additionalProperties":false,"properties":{"horizon_seconds":{"type":"integer","minimum":1,"maximum":2592000,"example":2592000},"max_occurrences":{"type":"integer","minimum":1,"maximum":500,"example":500}}},"claim":{"type":"object","additionalProperties":false,"properties":{"lease_seconds":{"type":"integer","minimum":1,"maximum":900,"example":120},"recovery_grace_seconds":{"type":"integer","minimum":0,"maximum":3600,"example":30}}}}},"attachments_count":{"type":"integer","minimum":0,"example":0},"lock_version":{"type":"integer","example":0}}}}}}]}}},"example":{"payload":{"id":701,"name":"Appointment reminder","status":"active","conversation_id":42,"kind":"one_time","timezone":"America/Sao_Paulo","starts_at":"2026-08-22T13:00:00.000Z","version_number":1,"items":[{"id":801,"stable_key":"2dc1f16c-5191-4b3b-97b4-8f33e93dc969","position":1,"timing":{"anchor":"schedule_start","offset_seconds":0},"draft":{"version":1,"schema_version":1,"delay_ms":0,"parts":[{"content":"Olá, seu atendimento está marcado para amanhã.","content_type":"text","content_attributes":{"in_reply_to":88,"in_reply_to_external_id":"wamid.example","items":[{}],"email":{},"interactive":{},"wa_interactive":{},"poll":{},"catalog_product":{},"media_kind":"image","view_once":false,"mention_all":false,"mentioned_jids":[],"mentions":{},"is_forwarded":false,"link_preview":{},"location":{},"contact":{},"cta_buttons":[{}]},"attachments":[{"signed_id":"eyJfcmFpbHMiOnsibWVzc2FnZSI6ImJsb2IifX0","filename":"reminder.pdf","content_type":"application/pdf","byte_size":2048}],"items":[{}],"is_voice_message":false,"email_html_content":"\u003cp\u003eAppointment reminder\u003c/p\u003e","to_emails":["customer@example.com"],"cc_emails":[],"bcc_emails":[],"template_params":{},"flow_params":{},"whatsapp_transport":"cloud"}],"attachments":[{"signed_id":"eyJfcmFpbHMiOnsibWVzc2FnZSI6ImJsb2IifX0","filename":"reminder.pdf","content_type":"application/pdf","byte_size":2048}]},"policy_overrides":{"on_inbound_reply":{"action":"pause"},"on_conversation_resolved":{"action":"continue"},"misfire":{"action":"send_latest","grace_seconds":60,"max_occurrences":10,"spacing_seconds":5},"transient_failure":{"max_attempts":3,"backoff_seconds":[30,120],"exhausted_action":"manual_review"},"permanent_failure":{"action":"manual_review"},"resume_behavior":{"action":"preserve_schedule","max_occurrences":10,"spacing_seconds":5},"quiet_hours":{"enabled":false,"start":"22:00","end":"08:00","days":[0,1,2,3,4,5,6],"action":"defer"},"overlap":{"action":"allow","defer_seconds":60},"inbox_change":{"action":"follow_logical"},"sender":{"type":"system","id":null,"missing":"fail"},"variables":{"resolve_at":"dispatch","missing":"fail"},"dst":{"nonexistent":"shift_forward","ambiguous":"first"},"materialization":{"horizon_seconds":2592000,"max_occurrences":500},"claim":{"lease_seconds":120,"recovery_grace_seconds":30}},"attachments_count":0,"lock_version":0}],"inbox_id":7,"contact_id":81,"created_by_id":9,"next_occurrence_at":"2026-08-22T13:00:00.000Z","materialized_through_at":"2026-08-22T13:00:00.000Z","published_at":"2026-08-21T16:00:00.000Z","paused_at":null,"needs_attention_at":null,"completed_at":null,"canceled_at":null,"archived_at":null,"lock_version":1,"created_at":"2026-08-21T16:00:00.000Z","updated_at":"2026-08-21T16:00:00.000Z","created_by":{"id":9,"name":"Ana Agent"},"rrule":null,"resolved_policies":{},"policy_sources":{},"sender_config":{},"target_config":{}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"409":{"description":"Stale lock or invalid reconciliation state."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["lock_version","scope","outcome"],"properties":{"lock_version":{"type":"integer","minimum":0,"example":1},"scope":{"type":"string","enum":["all_future"],"example":"all_future"},"outcome":{"type":"string","enum":["sent","failed","canceled"],"example":"sent"}}},"example":{"lock_version":1,"scope":"all_future","outcome":"sent"}}}}}},"/api/v1/accounts/{account_id}/message_schedules/{message_schedule_id}/occurrences/{id}/send_now":{"post":{"tags":["Message Schedules"],"operationId":"auto_post_api_v1_accounts_account_id_message_schedules_message_schedule_id_occurrences_id_send_now","summary":"Send or copy one occurrence now","description":"With consume_occurrence=true, moves the occurrence due time to now and consumes it through the durable dispatcher. With false, sends an immediate copy and leaves the occurrence untouched.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Updated occurrence.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"allOf":[{"type":"object","additionalProperties":false,"properties":{"id":{"type":"integer","example":9001},"schedule_id":{"type":"integer","example":701},"schedule_version_id":{"type":"integer","example":801},"schedule_item_id":{"type":"integer","example":811},"cycle_index":{"type":"integer","minimum":0,"example":0},"ordinal":{"type":"integer","minimum":1,"example":1},"cycle_at":{"type":"string","format":"date-time","example":"2026-08-22T13:00:00.000Z"},"due_at":{"type":["string","null"],"format":"date-time","example":"2026-08-22T13:00:00.000Z"},"state":{"type":"string","enum":["scheduled","claimed","dispatching","queued","sent","delivered","read","retry_scheduled","skipped","failed","canceled","needs_attention"],"example":"scheduled"},"status":{"type":"string","enum":["scheduled","claimed","dispatching","queued","sent","delivered","read","retry_scheduled","skipped","failed","canceled","needs_attention"],"example":"scheduled","description":"Runtime and delivery state of the scheduled occurrence."},"attempt_count":{"type":"integer","minimum":0,"example":0},"claim_count":{"type":"integer","minimum":0,"example":0},"retry_at":{"type":["string","null"],"format":"date-time","example":null},"error_code":{"type":["string","null"],"example":null},"terminal_reason":{"type":["string","null"],"example":null},"dispatched_at":{"type":["string","null"],"format":"date-time","example":null},"completed_at":{"type":["string","null"],"format":"date-time","example":null},"canceled_at":{"type":["string","null"],"format":"date-time","example":null},"needs_attention_at":{"type":["string","null"],"format":"date-time","example":null},"lock_version":{"type":"integer","minimum":0,"example":0},"created_at":{"type":"string","format":"date-time","example":"2026-08-21T16:00:00.000Z"},"updated_at":{"type":"string","format":"date-time","example":"2026-08-21T16:00:00.000Z"}}},{"type":"object","properties":{"copied_message_ids":{"type":"array","items":{"type":"integer"},"example":[]}}}]}}},"example":{"payload":{"id":9001,"status":"scheduled","state":"scheduled","copied_message_ids":[],"schedule_id":701,"schedule_version_id":801,"schedule_item_id":811,"cycle_index":0,"ordinal":1,"cycle_at":"2026-08-22T13:00:00.000Z","due_at":"2026-08-22T13:00:00.000Z","attempt_count":0,"claim_count":0,"retry_at":null,"error_code":null,"terminal_reason":null,"dispatched_at":null,"completed_at":null,"canceled_at":null,"needs_attention_at":null,"lock_version":0,"created_at":"2026-08-21T16:00:00.000Z","updated_at":"2026-08-21T16:00:00.000Z"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"409":{"description":"Stale lock, executing occurrence or invalid state."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"message_schedule_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["lock_version","scope","consume_occurrence"],"properties":{"lock_version":{"type":"integer","minimum":0,"example":0},"scope":{"type":"string","enum":["this_occurrence"],"example":"this_occurrence"},"consume_occurrence":{"type":"boolean","example":true}}},"example":{"lock_version":0,"scope":"this_occurrence","consume_occurrence":true}}}}}},"/api/v1/accounts/{account_id}/message_schedules/{message_schedule_id}/occurrences/{id}/skip":{"post":{"tags":["Message Schedules"],"operationId":"auto_post_api_v1_accounts_account_id_message_schedules_message_schedule_id_occurrences_id_skip","summary":"Skip one occurrence scope","description":"Performs the skip operation on the targeted message schedule occurrence resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Updated occurrence.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"allOf":[{"type":"object","additionalProperties":false,"properties":{"id":{"type":"integer","example":9001},"schedule_id":{"type":"integer","example":701},"schedule_version_id":{"type":"integer","example":801},"schedule_item_id":{"type":"integer","example":811},"cycle_index":{"type":"integer","minimum":0,"example":0},"ordinal":{"type":"integer","minimum":1,"example":1},"cycle_at":{"type":"string","format":"date-time","example":"2026-08-22T13:00:00.000Z"},"due_at":{"type":["string","null"],"format":"date-time","example":"2026-08-22T13:00:00.000Z"},"state":{"type":"string","enum":["scheduled","claimed","dispatching","queued","sent","delivered","read","retry_scheduled","skipped","failed","canceled","needs_attention"],"example":"scheduled"},"status":{"type":"string","enum":["scheduled","claimed","dispatching","queued","sent","delivered","read","retry_scheduled","skipped","failed","canceled","needs_attention"],"example":"scheduled","description":"Runtime and delivery state of the scheduled occurrence."},"attempt_count":{"type":"integer","minimum":0,"example":0},"claim_count":{"type":"integer","minimum":0,"example":0},"retry_at":{"type":["string","null"],"format":"date-time","example":null},"error_code":{"type":["string","null"],"example":null},"terminal_reason":{"type":["string","null"],"example":null},"dispatched_at":{"type":["string","null"],"format":"date-time","example":null},"completed_at":{"type":["string","null"],"format":"date-time","example":null},"canceled_at":{"type":["string","null"],"format":"date-time","example":null},"needs_attention_at":{"type":["string","null"],"format":"date-time","example":null},"lock_version":{"type":"integer","minimum":0,"example":0},"created_at":{"type":"string","format":"date-time","example":"2026-08-21T16:00:00.000Z"},"updated_at":{"type":"string","format":"date-time","example":"2026-08-21T16:00:00.000Z"}}},{"type":"object","properties":{"copied_message_ids":{"type":"array","items":{"type":"integer"},"example":[]}}}]}}},"example":{"payload":{"id":9001,"status":"scheduled","state":"scheduled","copied_message_ids":[],"schedule_id":701,"schedule_version_id":801,"schedule_item_id":811,"cycle_index":0,"ordinal":1,"cycle_at":"2026-08-22T13:00:00.000Z","due_at":"2026-08-22T13:00:00.000Z","attempt_count":0,"claim_count":0,"retry_at":null,"error_code":null,"terminal_reason":null,"dispatched_at":null,"completed_at":null,"canceled_at":null,"needs_attention_at":null,"lock_version":0,"created_at":"2026-08-21T16:00:00.000Z","updated_at":"2026-08-21T16:00:00.000Z"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"409":{"description":"Stale lock, executing occurrence or invalid state."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"message_schedule_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["lock_version","scope"],"properties":{"lock_version":{"type":"integer","minimum":0,"example":0},"scope":{"type":"string","enum":["this_occurrence","this_and_future","all_future"],"example":"this_occurrence"}}},"example":{"lock_version":0,"scope":"this_occurrence"}}}}}},"/api/v1/accounts/{account_id}/message_schedules/{message_schedule_id}/occurrences/{id}/retry":{"post":{"tags":["Message Schedules"],"operationId":"auto_post_api_v1_accounts_account_id_message_schedules_message_schedule_id_occurrences_id_retry","summary":"Retry a failed occurrence","description":"Performs the retry operation on the targeted message schedule occurrence resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Updated occurrence.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"allOf":[{"type":"object","additionalProperties":false,"properties":{"id":{"type":"integer","example":9001},"schedule_id":{"type":"integer","example":701},"schedule_version_id":{"type":"integer","example":801},"schedule_item_id":{"type":"integer","example":811},"cycle_index":{"type":"integer","minimum":0,"example":0},"ordinal":{"type":"integer","minimum":1,"example":1},"cycle_at":{"type":"string","format":"date-time","example":"2026-08-22T13:00:00.000Z"},"due_at":{"type":["string","null"],"format":"date-time","example":"2026-08-22T13:00:00.000Z"},"state":{"type":"string","enum":["scheduled","claimed","dispatching","queued","sent","delivered","read","retry_scheduled","skipped","failed","canceled","needs_attention"],"example":"scheduled"},"status":{"type":"string","enum":["scheduled","claimed","dispatching","queued","sent","delivered","read","retry_scheduled","skipped","failed","canceled","needs_attention"],"example":"scheduled","description":"Runtime and delivery state of the scheduled occurrence."},"attempt_count":{"type":"integer","minimum":0,"example":0},"claim_count":{"type":"integer","minimum":0,"example":0},"retry_at":{"type":["string","null"],"format":"date-time","example":null},"error_code":{"type":["string","null"],"example":null},"terminal_reason":{"type":["string","null"],"example":null},"dispatched_at":{"type":["string","null"],"format":"date-time","example":null},"completed_at":{"type":["string","null"],"format":"date-time","example":null},"canceled_at":{"type":["string","null"],"format":"date-time","example":null},"needs_attention_at":{"type":["string","null"],"format":"date-time","example":null},"lock_version":{"type":"integer","minimum":0,"example":0},"created_at":{"type":"string","format":"date-time","example":"2026-08-21T16:00:00.000Z"},"updated_at":{"type":"string","format":"date-time","example":"2026-08-21T16:00:00.000Z"}}},{"type":"object","properties":{"copied_message_ids":{"type":"array","items":{"type":"integer"},"example":[]}}}]}}},"example":{"payload":{"id":9001,"status":"scheduled","state":"scheduled","copied_message_ids":[],"schedule_id":701,"schedule_version_id":801,"schedule_item_id":811,"cycle_index":0,"ordinal":1,"cycle_at":"2026-08-22T13:00:00.000Z","due_at":"2026-08-22T13:00:00.000Z","attempt_count":0,"claim_count":0,"retry_at":null,"error_code":null,"terminal_reason":null,"dispatched_at":null,"completed_at":null,"canceled_at":null,"needs_attention_at":null,"lock_version":0,"created_at":"2026-08-21T16:00:00.000Z","updated_at":"2026-08-21T16:00:00.000Z"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"409":{"description":"Stale lock, ambiguous external effect or invalid state."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"message_schedule_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["lock_version","scope"],"properties":{"lock_version":{"type":"integer","minimum":0,"example":0},"scope":{"type":"string","enum":["this_occurrence"],"example":"this_occurrence"}}},"example":{"lock_version":0,"scope":"this_occurrence"}}}}}},"/api/v1/accounts/{account_id}/message_schedules/{message_schedule_id}/occurrences/{id}/reconcile":{"post":{"tags":["Message Schedules"],"operationId":"auto_post_api_v1_accounts_account_id_message_schedules_message_schedule_id_occurrences_id_reconcile","summary":"Reconcile an ambiguous occurrence manually","description":"Performs the reconcile operation on the targeted message schedule occurrence resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Updated occurrence.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"allOf":[{"type":"object","additionalProperties":false,"properties":{"id":{"type":"integer","example":9001},"schedule_id":{"type":"integer","example":701},"schedule_version_id":{"type":"integer","example":801},"schedule_item_id":{"type":"integer","example":811},"cycle_index":{"type":"integer","minimum":0,"example":0},"ordinal":{"type":"integer","minimum":1,"example":1},"cycle_at":{"type":"string","format":"date-time","example":"2026-08-22T13:00:00.000Z"},"due_at":{"type":["string","null"],"format":"date-time","example":"2026-08-22T13:00:00.000Z"},"state":{"type":"string","enum":["scheduled","claimed","dispatching","queued","sent","delivered","read","retry_scheduled","skipped","failed","canceled","needs_attention"],"example":"scheduled"},"status":{"type":"string","enum":["scheduled","claimed","dispatching","queued","sent","delivered","read","retry_scheduled","skipped","failed","canceled","needs_attention"],"example":"scheduled","description":"Runtime and delivery state of the scheduled occurrence."},"attempt_count":{"type":"integer","minimum":0,"example":0},"claim_count":{"type":"integer","minimum":0,"example":0},"retry_at":{"type":["string","null"],"format":"date-time","example":null},"error_code":{"type":["string","null"],"example":null},"terminal_reason":{"type":["string","null"],"example":null},"dispatched_at":{"type":["string","null"],"format":"date-time","example":null},"completed_at":{"type":["string","null"],"format":"date-time","example":null},"canceled_at":{"type":["string","null"],"format":"date-time","example":null},"needs_attention_at":{"type":["string","null"],"format":"date-time","example":null},"lock_version":{"type":"integer","minimum":0,"example":0},"created_at":{"type":"string","format":"date-time","example":"2026-08-21T16:00:00.000Z"},"updated_at":{"type":"string","format":"date-time","example":"2026-08-21T16:00:00.000Z"}}},{"type":"object","properties":{"copied_message_ids":{"type":"array","items":{"type":"integer"},"example":[]}}}]}}},"example":{"payload":{"id":9001,"status":"scheduled","state":"scheduled","copied_message_ids":[],"schedule_id":701,"schedule_version_id":801,"schedule_item_id":811,"cycle_index":0,"ordinal":1,"cycle_at":"2026-08-22T13:00:00.000Z","due_at":"2026-08-22T13:00:00.000Z","attempt_count":0,"claim_count":0,"retry_at":null,"error_code":null,"terminal_reason":null,"dispatched_at":null,"completed_at":null,"canceled_at":null,"needs_attention_at":null,"lock_version":0,"created_at":"2026-08-21T16:00:00.000Z","updated_at":"2026-08-21T16:00:00.000Z"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"409":{"description":"Stale lock or invalid reconciliation state."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"message_schedule_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["lock_version","scope","outcome"],"properties":{"lock_version":{"type":"integer","minimum":0,"example":0},"scope":{"type":"string","enum":["this_occurrence"],"example":"this_occurrence"},"outcome":{"type":"string","enum":["sent","failed","canceled"],"example":"sent"}}},"example":{"lock_version":0,"scope":"this_occurrence","outcome":"sent"}}}}}},"/api/v1/accounts/{account_id}/message_schedules/{message_schedule_id}/occurrences":{"get":{"tags":["Message Schedules"],"operationId":"auto_get_api_v1_accounts_account_id_message_schedules_message_schedule_id_occurrences","summary":"List materialized occurrences for a schedule","description":"Returns the list of message schedule occurrences visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Paginated occurrence ledger, newest cycle first.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"integer","example":9001},"schedule_id":{"type":"integer","example":701},"schedule_version_id":{"type":"integer","example":801},"schedule_item_id":{"type":"integer","example":811},"cycle_index":{"type":"integer","minimum":0,"example":0},"ordinal":{"type":"integer","minimum":1,"example":1},"cycle_at":{"type":"string","format":"date-time","example":"2026-08-22T13:00:00.000Z"},"due_at":{"type":["string","null"],"format":"date-time","example":"2026-08-22T13:00:00.000Z"},"state":{"type":"string","enum":["scheduled","claimed","dispatching","queued","sent","delivered","read","retry_scheduled","skipped","failed","canceled","needs_attention"],"example":"scheduled"},"status":{"type":"string","enum":["scheduled","claimed","dispatching","queued","sent","delivered","read","retry_scheduled","skipped","failed","canceled","needs_attention"],"example":"scheduled","description":"Runtime and delivery state of the scheduled occurrence."},"attempt_count":{"type":"integer","minimum":0,"example":0},"claim_count":{"type":"integer","minimum":0,"example":0},"retry_at":{"type":["string","null"],"format":"date-time","example":null},"error_code":{"type":["string","null"],"example":null},"terminal_reason":{"type":["string","null"],"example":null},"dispatched_at":{"type":["string","null"],"format":"date-time","example":null},"completed_at":{"type":["string","null"],"format":"date-time","example":null},"canceled_at":{"type":["string","null"],"format":"date-time","example":null},"needs_attention_at":{"type":["string","null"],"format":"date-time","example":null},"lock_version":{"type":"integer","minimum":0,"example":0},"created_at":{"type":"string","format":"date-time","example":"2026-08-21T16:00:00.000Z"},"updated_at":{"type":"string","format":"date-time","example":"2026-08-21T16:00:00.000Z"}}}},"meta":{"type":"object","additionalProperties":false,"properties":{"count":{"type":"integer","minimum":0,"example":1},"current_page":{"type":"integer","minimum":1,"example":1},"total_pages":{"type":"integer","minimum":0,"example":1},"per_page":{"type":"integer","minimum":1,"maximum":100,"example":25}}}}},"example":{"payload":[{"id":9001,"schedule_id":701,"schedule_version_id":801,"schedule_item_id":811,"cycle_index":0,"ordinal":1,"cycle_at":"2026-08-22T13:00:00.000Z","due_at":"2026-08-22T13:00:00.000Z","state":"scheduled","status":"scheduled","attempt_count":0,"claim_count":0,"retry_at":null,"error_code":null,"terminal_reason":null,"dispatched_at":null,"completed_at":null,"canceled_at":null,"needs_attention_at":null,"lock_version":0,"created_at":"2026-08-21T16:00:00.000Z","updated_at":"2026-08-21T16:00:00.000Z"}],"meta":{"count":0,"current_page":1,"total_pages":0,"per_page":10}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"message_schedule_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."}]}},"/api/v1/accounts/{account_id}/message_schedules/{message_schedule_id}/occurrences/{id}":{"patch":{"tags":["Message Schedules"],"operationId":"auto_patch_api_v1_accounts_account_id_message_schedules_message_schedule_id_occurrences_id","summary":"Reschedule one occurrence scope","description":"Updates the message schedule occurrence identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Updated occurrence.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"allOf":[{"type":"object","additionalProperties":false,"properties":{"id":{"type":"integer","example":9001},"schedule_id":{"type":"integer","example":701},"schedule_version_id":{"type":"integer","example":801},"schedule_item_id":{"type":"integer","example":811},"cycle_index":{"type":"integer","minimum":0,"example":0},"ordinal":{"type":"integer","minimum":1,"example":1},"cycle_at":{"type":"string","format":"date-time","example":"2026-08-22T13:00:00.000Z"},"due_at":{"type":["string","null"],"format":"date-time","example":"2026-08-22T13:00:00.000Z"},"state":{"type":"string","enum":["scheduled","claimed","dispatching","queued","sent","delivered","read","retry_scheduled","skipped","failed","canceled","needs_attention"],"example":"scheduled"},"status":{"type":"string","enum":["scheduled","claimed","dispatching","queued","sent","delivered","read","retry_scheduled","skipped","failed","canceled","needs_attention"],"example":"scheduled","description":"Runtime and delivery state of the scheduled occurrence."},"attempt_count":{"type":"integer","minimum":0,"example":0},"claim_count":{"type":"integer","minimum":0,"example":0},"retry_at":{"type":["string","null"],"format":"date-time","example":null},"error_code":{"type":["string","null"],"example":null},"terminal_reason":{"type":["string","null"],"example":null},"dispatched_at":{"type":["string","null"],"format":"date-time","example":null},"completed_at":{"type":["string","null"],"format":"date-time","example":null},"canceled_at":{"type":["string","null"],"format":"date-time","example":null},"needs_attention_at":{"type":["string","null"],"format":"date-time","example":null},"lock_version":{"type":"integer","minimum":0,"example":0},"created_at":{"type":"string","format":"date-time","example":"2026-08-21T16:00:00.000Z"},"updated_at":{"type":"string","format":"date-time","example":"2026-08-21T16:00:00.000Z"}}},{"type":"object","properties":{"copied_message_ids":{"type":"array","items":{"type":"integer"},"example":[]}}}]}}},"example":{"payload":{"id":9001,"status":"scheduled","state":"scheduled","copied_message_ids":[],"schedule_id":701,"schedule_version_id":801,"schedule_item_id":811,"cycle_index":0,"ordinal":1,"cycle_at":"2026-08-22T13:00:00.000Z","due_at":"2026-08-22T13:00:00.000Z","attempt_count":0,"claim_count":0,"retry_at":null,"error_code":null,"terminal_reason":null,"dispatched_at":null,"completed_at":null,"canceled_at":null,"needs_attention_at":null,"lock_version":0,"created_at":"2026-08-21T16:00:00.000Z","updated_at":"2026-08-21T16:00:00.000Z"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"409":{"description":"Stale lock, executing occurrence or invalid state."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"message_schedule_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["lock_version","scope","due_at"],"properties":{"lock_version":{"type":"integer","minimum":0,"example":0},"scope":{"type":"string","enum":["this_occurrence","this_and_future","all_future"],"example":"this_occurrence"},"due_at":{"type":"string","format":"date-time","example":"2026-08-22T14:00:00.000Z"}}},"example":{"lock_version":0,"scope":"this_occurrence","due_at":"2026-08-22T14:00:00.000Z"}}}}},"put":{"tags":["Message Schedules"],"operationId":"auto_put_api_v1_accounts_account_id_message_schedules_message_schedule_id_occurrences_id","summary":"Reschedule one occurrence scope","description":"Updates the message schedule occurrence identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Updated occurrence.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"allOf":[{"type":"object","additionalProperties":false,"properties":{"id":{"type":"integer","example":9001},"schedule_id":{"type":"integer","example":701},"schedule_version_id":{"type":"integer","example":801},"schedule_item_id":{"type":"integer","example":811},"cycle_index":{"type":"integer","minimum":0,"example":0},"ordinal":{"type":"integer","minimum":1,"example":1},"cycle_at":{"type":"string","format":"date-time","example":"2026-08-22T13:00:00.000Z"},"due_at":{"type":["string","null"],"format":"date-time","example":"2026-08-22T13:00:00.000Z"},"state":{"type":"string","enum":["scheduled","claimed","dispatching","queued","sent","delivered","read","retry_scheduled","skipped","failed","canceled","needs_attention"],"example":"scheduled"},"status":{"type":"string","enum":["scheduled","claimed","dispatching","queued","sent","delivered","read","retry_scheduled","skipped","failed","canceled","needs_attention"],"example":"scheduled","description":"Runtime and delivery state of the scheduled occurrence."},"attempt_count":{"type":"integer","minimum":0,"example":0},"claim_count":{"type":"integer","minimum":0,"example":0},"retry_at":{"type":["string","null"],"format":"date-time","example":null},"error_code":{"type":["string","null"],"example":null},"terminal_reason":{"type":["string","null"],"example":null},"dispatched_at":{"type":["string","null"],"format":"date-time","example":null},"completed_at":{"type":["string","null"],"format":"date-time","example":null},"canceled_at":{"type":["string","null"],"format":"date-time","example":null},"needs_attention_at":{"type":["string","null"],"format":"date-time","example":null},"lock_version":{"type":"integer","minimum":0,"example":0},"created_at":{"type":"string","format":"date-time","example":"2026-08-21T16:00:00.000Z"},"updated_at":{"type":"string","format":"date-time","example":"2026-08-21T16:00:00.000Z"}}},{"type":"object","properties":{"copied_message_ids":{"type":"array","items":{"type":"integer"},"example":[]}}}]}}},"example":{"payload":{"id":9001,"status":"scheduled","state":"scheduled","copied_message_ids":[],"schedule_id":701,"schedule_version_id":801,"schedule_item_id":811,"cycle_index":0,"ordinal":1,"cycle_at":"2026-08-22T13:00:00.000Z","due_at":"2026-08-22T13:00:00.000Z","attempt_count":0,"claim_count":0,"retry_at":null,"error_code":null,"terminal_reason":null,"dispatched_at":null,"completed_at":null,"canceled_at":null,"needs_attention_at":null,"lock_version":0,"created_at":"2026-08-21T16:00:00.000Z","updated_at":"2026-08-21T16:00:00.000Z"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"409":{"description":"Stale lock, executing occurrence or invalid state."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"message_schedule_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["lock_version","scope","due_at"],"properties":{"lock_version":{"type":"integer","minimum":0,"example":0},"scope":{"type":"string","enum":["this_occurrence","this_and_future","all_future"],"example":"this_occurrence"},"due_at":{"type":"string","format":"date-time","example":"2026-08-22T14:00:00.000Z"}}},"example":{"lock_version":0,"scope":"this_occurrence","due_at":"2026-08-22T14:00:00.000Z"}}}}}},"/api/v1/accounts/{account_id}/message_schedules":{"get":{"tags":["Message Schedules"],"operationId":"auto_get_api_v1_accounts_account_id_message_schedules","summary":"List visible message schedules","description":"Lists only schedules visible through account, role, inbox and conversation scope. Filters are combined. Results are ordered by next occurrence ascending (nulls last), then schedule id descending. Inbox and conversation filters require positive identifiers. When a canonical identifier and its legacy alias are both supplied, they must agree; empty, invalid or conflicting values are rejected instead of broadening the selection.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Paginated schedule summaries.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"integer","example":701},"name":{"type":"string","example":"Appointment reminder"},"status":{"type":"string","enum":["draft","active","paused","needs_attention","completed","canceled","archived"],"example":"active","description":"Lifecycle state of the message schedule."},"inbox_id":{"type":"integer","example":7},"contact_id":{"type":"integer","example":81},"created_by_id":{"type":"integer","example":9},"conversation_id":{"type":"integer","description":"Public conversation display id.","example":42},"next_occurrence_at":{"type":["string","null"],"format":"date-time","example":"2026-08-22T13:00:00.000Z"},"materialized_through_at":{"type":["string","null"],"format":"date-time","example":"2026-08-22T13:00:00.000Z"},"published_at":{"type":["string","null"],"format":"date-time","example":"2026-08-21T16:00:00.000Z"},"paused_at":{"type":["string","null"],"format":"date-time","example":null},"needs_attention_at":{"type":["string","null"],"format":"date-time","example":null},"completed_at":{"type":["string","null"],"format":"date-time","example":null},"canceled_at":{"type":["string","null"],"format":"date-time","example":null},"archived_at":{"type":["string","null"],"format":"date-time","example":null},"lock_version":{"type":"integer","example":1},"created_at":{"type":"string","format":"date-time","example":"2026-08-21T16:00:00.000Z"},"updated_at":{"type":"string","format":"date-time","example":"2026-08-21T16:00:00.000Z"},"created_by":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"integer","example":9},"name":{"type":"string","example":"Ana Agent"}}},"kind":{"type":"string","enum":["one_time","sequence","recurring_single","recurring_sequence"],"example":"one_time","description":"Temporal shape of the scheduled message plan."},"timezone":{"type":"string","example":"America/Sao_Paulo"},"starts_at":{"type":"string","format":"date-time","example":"2026-08-22T13:00:00.000Z"},"rrule":{"type":["string","null"],"example":null},"version_number":{"type":"integer","example":1}}}},"meta":{"type":"object","additionalProperties":false,"properties":{"count":{"type":"integer","minimum":0,"example":1},"current_page":{"type":"integer","minimum":1,"example":1},"total_pages":{"type":"integer","minimum":0,"example":1},"per_page":{"type":"integer","minimum":1,"maximum":100,"example":25}}}}},"example":{"payload":[{"id":701,"name":"Appointment reminder","status":"active","inbox_id":7,"contact_id":81,"created_by_id":9,"conversation_id":42,"next_occurrence_at":"2026-08-22T13:00:00.000Z","materialized_through_at":"2026-08-22T13:00:00.000Z","published_at":"2026-08-21T16:00:00.000Z","paused_at":null,"needs_attention_at":null,"completed_at":null,"canceled_at":null,"archived_at":null,"lock_version":1,"created_at":"2026-08-21T16:00:00.000Z","updated_at":"2026-08-21T16:00:00.000Z","created_by":{"id":9,"name":"Ana Agent"},"kind":"one_time","timezone":"America/Sao_Paulo","starts_at":"2026-08-22T13:00:00.000Z","rrule":null,"version_number":1}],"meta":{"count":0,"current_page":1,"total_pages":0,"per_page":25}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"422":{"description":"A supplied identifier, enum, date or scope filter is invalid; no broader list is returned.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","example":"invalid_conversation_id"}}},"example":{"error":"invalid_conversation_id"}}}},"403":{"description":"Message scheduling or API access is disabled for this account.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","example":"feature_not_enabled"}}},"example":{"error":"feature_not_enabled"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"q","in":"query","description":"Case-insensitive text contained in the schedule name.","schema":{"type":"string","example":"reminder"}},{"name":"status","in":"query","description":"Exact schedule lifecycle state.","schema":{"type":"string","enum":["draft","active","paused","needs_attention","completed","canceled","archived"],"example":"active"}},{"name":"kind","in":"query","description":"Exact temporal kind of the published schedule version.","schema":{"type":"string","enum":["one_time","sequence","recurring_single","recurring_sequence"],"example":"one_time"}},{"name":"scope","in":"query","description":"Upcoming includes active, paused and needs_attention; history includes completed, canceled and archived. Mine uses the authenticated user; conversation uses the supplied conversation filter.","schema":{"type":"string","enum":["all","mine","conversation","upcoming","recurring","history"],"example":"upcoming"}},{"name":"inbox_id","in":"query","description":"Inbox identifier within the visible account scope.","schema":{"type":"integer","minimum":1,"example":7}},{"name":"inbox","in":"query","description":"Legacy alias for inbox_id; if both are supplied, they must identify the same inbox.","schema":{"type":"integer","minimum":1,"example":7}},{"name":"conversation_id","in":"query","description":"Public conversation display id, not the internal database id.","schema":{"type":"integer","minimum":1,"example":42}},{"name":"conversation","in":"query","description":"Legacy alias for conversation_id; if both are supplied, they must identify the same conversation.","schema":{"type":"integer","minimum":1,"example":42}},{"name":"channel","in":"query","description":"Inbox channel type, accepted with or without the Channel:: prefix.","schema":{"type":"string","example":"Whatsapp"}},{"name":"created_by","in":"query","description":"Identifier of the user who created the schedule.","schema":{"type":"integer","example":9}},{"name":"responsible","in":"query","description":"Identifier of the user currently assigned to the conversation.","schema":{"type":"integer","example":9}},{"name":"date_from","in":"query","description":"Inclusive ISO8601 lower bound of the next occurrence.","schema":{"type":"string","format":"date-time","example":"2026-09-19T00:00:00Z"}},{"name":"date_to","in":"query","description":"Inclusive ISO8601 upper bound of the next occurrence.","schema":{"type":"string","format":"date-time","example":"2026-09-20T00:00:00Z"}},{"name":"page","in":"query","description":"Page number, normalized to at least one.","schema":{"type":"integer","minimum":1,"default":1,"example":1}},{"name":"per_page","in":"query","description":"Page size, defaulting to 25 and capped at 100.","schema":{"type":"integer","minimum":1,"maximum":100,"default":25,"example":25}}]},"post":{"tags":["Message Schedules"],"operationId":"auto_post_api_v1_accounts_account_id_message_schedules","summary":"Create and publish a message schedule","description":"Creates a schedule for exactly one existing conversation, validates the channel and the fully resolved policy, publishes version 1 and materializes future occurrences. `X-Idempotency-Key` replays an identical request and returns 200; reusing the key for a different semantic definition returns 409. No message is created before it is due.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Idempotent replay of the already published schedule.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"allOf":[{"type":"object","additionalProperties":false,"properties":{"id":{"type":"integer","example":701},"name":{"type":"string","example":"Appointment reminder"},"status":{"type":"string","enum":["draft","active","paused","needs_attention","completed","canceled","archived"],"example":"active","description":"Lifecycle state of the message schedule."},"inbox_id":{"type":"integer","example":7},"contact_id":{"type":"integer","example":81},"created_by_id":{"type":"integer","example":9},"conversation_id":{"type":"integer","description":"Public conversation display id.","example":42},"next_occurrence_at":{"type":["string","null"],"format":"date-time","example":"2026-08-22T13:00:00.000Z"},"materialized_through_at":{"type":["string","null"],"format":"date-time","example":"2026-08-22T13:00:00.000Z"},"published_at":{"type":["string","null"],"format":"date-time","example":"2026-08-21T16:00:00.000Z"},"paused_at":{"type":["string","null"],"format":"date-time","example":null},"needs_attention_at":{"type":["string","null"],"format":"date-time","example":null},"completed_at":{"type":["string","null"],"format":"date-time","example":null},"canceled_at":{"type":["string","null"],"format":"date-time","example":null},"archived_at":{"type":["string","null"],"format":"date-time","example":null},"lock_version":{"type":"integer","example":1},"created_at":{"type":"string","format":"date-time","example":"2026-08-21T16:00:00.000Z"},"updated_at":{"type":"string","format":"date-time","example":"2026-08-21T16:00:00.000Z"},"created_by":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"integer","example":9},"name":{"type":"string","example":"Ana Agent"}}},"kind":{"type":"string","enum":["one_time","sequence","recurring_single","recurring_sequence"],"example":"one_time","description":"Temporal shape of the scheduled message plan."},"timezone":{"type":"string","example":"America/Sao_Paulo"},"starts_at":{"type":"string","format":"date-time","example":"2026-08-22T13:00:00.000Z"},"rrule":{"type":["string","null"],"example":null},"version_number":{"type":"integer","example":1}}},{"type":"object","properties":{"resolved_policies":{"type":"object","description":"Complete immutable policy snapshot keyed by item stable key.","additionalProperties":{"type":"object","additionalProperties":false,"description":"Explicit schedule-level overrides; omitted leaves inherit from inbox/account.","properties":{"on_inbound_reply":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["continue","pause","cancel","skip"],"example":"pause"}}},"on_conversation_resolved":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["continue","pause","cancel","skip"],"example":"continue"}}},"misfire":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["skip","manual_review","send_latest","catch_up_bounded"],"example":"send_latest"},"grace_seconds":{"type":"integer","minimum":0,"example":60},"max_occurrences":{"type":"integer","minimum":1,"maximum":500,"example":10},"spacing_seconds":{"type":"integer","minimum":0,"example":5}}},"transient_failure":{"type":"object","additionalProperties":false,"properties":{"max_attempts":{"type":"integer","minimum":1,"maximum":10,"example":3},"backoff_seconds":{"type":"array","maxItems":9,"items":{"type":"integer","minimum":0,"maximum":86400},"example":[30,120]},"exhausted_action":{"type":"string","enum":["skip","pause","cancel","manual_review"],"example":"manual_review"}}},"permanent_failure":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["skip","pause","cancel","manual_review"],"example":"manual_review"}}},"resume_behavior":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["preserve_schedule","shift_by_pause","skip_missed","catch_up_bounded"],"example":"preserve_schedule"},"max_occurrences":{"type":"integer","minimum":1,"maximum":500,"example":10},"spacing_seconds":{"type":"integer","minimum":0,"example":5}}},"quiet_hours":{"type":"object","additionalProperties":false,"properties":{"enabled":{"type":"boolean","example":false},"start":{"type":"string","pattern":"^(?:[01][0-9]|2[0-3]):[0-5][0-9]$","example":"22:00"},"end":{"type":"string","pattern":"^(?:[01][0-9]|2[0-3]):[0-5][0-9]$","example":"08:00"},"days":{"type":"array","uniqueItems":true,"items":{"type":"integer","minimum":0,"maximum":6},"example":[0,1,2,3,4,5,6]},"action":{"type":"string","enum":["allow","defer","skip","manual_review"],"example":"defer"}}},"overlap":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["allow","skip_new","defer_new","cancel_previous","manual_review"],"example":"allow"},"defer_seconds":{"type":"integer","minimum":1,"example":60}}},"inbox_change":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["follow_logical","cancel","pause","manual_review"],"example":"follow_logical"}}},"sender":{"type":"object","additionalProperties":false,"properties":{"type":{"type":"string","enum":["assigned_agent","schedule_creator","user","agent_bot","system"],"example":"system"},"id":{"type":["integer","null"],"minimum":1,"example":null},"missing":{"type":"string","enum":["fail","system","assigned_agent"],"example":"fail"}}},"variables":{"type":"object","additionalProperties":false,"properties":{"resolve_at":{"type":"string","enum":["publication","dispatch"],"example":"dispatch"},"missing":{"type":"string","enum":["fail","blank","skip"],"example":"fail"}}},"dst":{"type":"object","additionalProperties":false,"properties":{"nonexistent":{"type":"string","enum":["skip","shift_forward","shift_backward"],"example":"shift_forward"},"ambiguous":{"type":"string","enum":["first","second","skip"],"example":"first"}}},"materialization":{"type":"object","additionalProperties":false,"properties":{"horizon_seconds":{"type":"integer","minimum":1,"maximum":2592000,"example":2592000},"max_occurrences":{"type":"integer","minimum":1,"maximum":500,"example":500}}},"claim":{"type":"object","additionalProperties":false,"properties":{"lease_seconds":{"type":"integer","minimum":1,"maximum":900,"example":120},"recovery_grace_seconds":{"type":"integer","minimum":0,"maximum":3600,"example":30}}}}}},"policy_sources":{"type":"object","description":"Source map keyed by item stable key, then by policy path.","additionalProperties":{"type":"object","description":"Effective source keyed by policy path for this item.","additionalProperties":{"type":"string"}}},"sender_config":{"type":"object","additionalProperties":true,"description":"Server-authored sender snapshot; clients cannot submit it."},"target_config":{"type":"object","additionalProperties":true,"description":"Server-authored immutable conversation/inbox/contact target."},"items":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"integer","example":801},"stable_key":{"type":"string","format":"uuid","example":"2dc1f16c-5191-4b3b-97b4-8f33e93dc969"},"position":{"type":"integer","minimum":1,"example":1},"timing":{"type":"object","additionalProperties":false,"properties":{"anchor":{"type":"string","enum":["schedule_start","previous_scheduled","previous_dispatched"],"example":"schedule_start"},"offset_seconds":{"type":"integer","minimum":0,"example":0}}},"draft":{"type":"object","additionalProperties":false,"required":["parts"],"properties":{"version":{"type":"integer","enum":[1],"example":1},"schema_version":{"type":"integer","enum":[1],"example":1},"delay_ms":{"type":"integer","minimum":0,"maximum":300000,"example":0},"parts":{"type":"array","minItems":1,"maxItems":50,"items":{"type":"object","additionalProperties":false,"properties":{"content":{"type":"string","maxLength":150000,"example":"Olá, seu atendimento está marcado para amanhã."},"content_type":{"type":"string","enum":["text","input_select","sticker","poll"],"example":"text"},"content_attributes":{"type":"object","additionalProperties":false,"description":"Closed outbound metadata roots; rich provider objects remain JSON-shaped and are revalidated before dispatch.","properties":{"in_reply_to":{"type":"integer","example":88},"in_reply_to_external_id":{"type":"string","example":"wamid.example"},"items":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Provider-native option object."}},"email":{"type":"object","additionalProperties":true,"description":"Structured outbound e-mail metadata."},"interactive":{"type":"object","additionalProperties":true,"description":"WhatsApp Cloud interactive payload."},"wa_interactive":{"type":"object","additionalProperties":true,"description":"WazMeow interactive payload."},"poll":{"type":"object","additionalProperties":true,"description":"Poll payload."},"catalog_product":{"type":"object","additionalProperties":true,"description":"Catalog product payload."},"media_kind":{"type":"string","enum":["image","video","audio","document","sticker"],"example":"image"},"view_once":{"type":"boolean","example":false},"mention_all":{"type":"boolean","example":false},"mentioned_jids":{"type":"array","items":{"type":"string"},"example":[]},"mentions":{"type":"object","additionalProperties":true,"description":"Mention map keyed by provider identifier."},"is_forwarded":{"type":"boolean","example":false},"link_preview":{"type":"object","additionalProperties":true,"description":"Link preview metadata."},"location":{"type":"object","additionalProperties":true,"description":"Location payload."},"contact":{"type":"object","additionalProperties":true,"description":"Contact card payload."},"cta_buttons":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Call-to-action button."}}}},"attachments":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["signed_id"],"properties":{"signed_id":{"type":"string","description":"ActiveStorage signed blob id.","example":"eyJfcmFpbHMiOnsibWVzc2FnZSI6ImJsb2IifX0"},"filename":{"type":"string","example":"reminder.pdf"},"content_type":{"type":"string","example":"application/pdf"},"byte_size":{"type":"integer","minimum":0,"example":2048}}}},"items":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Structured select or poll option."}},"is_voice_message":{"type":"boolean","example":false},"email_html_content":{"type":"string","example":"\u003cp\u003eAppointment reminder\u003c/p\u003e"},"to_emails":{"type":"array","items":{"type":"string","format":"email"},"example":["customer@example.com"]},"cc_emails":{"type":"array","items":{"type":"string","format":"email"},"example":[]},"bcc_emails":{"type":"array","items":{"type":"string","format":"email"},"example":[]},"template_params":{"type":"object","additionalProperties":true,"description":"Approved template identity and parameters."},"flow_params":{"type":"object","additionalProperties":true,"description":"WhatsApp Flow identity and parameters."},"whatsapp_transport":{"type":"string","enum":["cloud","web"],"example":"cloud"}}}},"attachments":{"type":"array","description":"Union of the signed attachment references present in parts.","items":{"type":"object","additionalProperties":false,"required":["signed_id"],"properties":{"signed_id":{"type":"string","description":"ActiveStorage signed blob id.","example":"eyJfcmFpbHMiOnsibWVzc2FnZSI6ImJsb2IifX0"},"filename":{"type":"string","example":"reminder.pdf"},"content_type":{"type":"string","example":"application/pdf"},"byte_size":{"type":"integer","minimum":0,"example":2048}}}}}},"policy_overrides":{"type":"object","additionalProperties":false,"description":"Explicit schedule-level overrides; omitted leaves inherit from inbox/account.","properties":{"on_inbound_reply":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["continue","pause","cancel","skip"],"example":"pause"}}},"on_conversation_resolved":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["continue","pause","cancel","skip"],"example":"continue"}}},"misfire":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["skip","manual_review","send_latest","catch_up_bounded"],"example":"send_latest"},"grace_seconds":{"type":"integer","minimum":0,"example":60},"max_occurrences":{"type":"integer","minimum":1,"maximum":500,"example":10},"spacing_seconds":{"type":"integer","minimum":0,"example":5}}},"transient_failure":{"type":"object","additionalProperties":false,"properties":{"max_attempts":{"type":"integer","minimum":1,"maximum":10,"example":3},"backoff_seconds":{"type":"array","maxItems":9,"items":{"type":"integer","minimum":0,"maximum":86400},"example":[30,120]},"exhausted_action":{"type":"string","enum":["skip","pause","cancel","manual_review"],"example":"manual_review"}}},"permanent_failure":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["skip","pause","cancel","manual_review"],"example":"manual_review"}}},"resume_behavior":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["preserve_schedule","shift_by_pause","skip_missed","catch_up_bounded"],"example":"preserve_schedule"},"max_occurrences":{"type":"integer","minimum":1,"maximum":500,"example":10},"spacing_seconds":{"type":"integer","minimum":0,"example":5}}},"quiet_hours":{"type":"object","additionalProperties":false,"properties":{"enabled":{"type":"boolean","example":false},"start":{"type":"string","pattern":"^(?:[01][0-9]|2[0-3]):[0-5][0-9]$","example":"22:00"},"end":{"type":"string","pattern":"^(?:[01][0-9]|2[0-3]):[0-5][0-9]$","example":"08:00"},"days":{"type":"array","uniqueItems":true,"items":{"type":"integer","minimum":0,"maximum":6},"example":[0,1,2,3,4,5,6]},"action":{"type":"string","enum":["allow","defer","skip","manual_review"],"example":"defer"}}},"overlap":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["allow","skip_new","defer_new","cancel_previous","manual_review"],"example":"allow"},"defer_seconds":{"type":"integer","minimum":1,"example":60}}},"inbox_change":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["follow_logical","cancel","pause","manual_review"],"example":"follow_logical"}}},"sender":{"type":"object","additionalProperties":false,"properties":{"type":{"type":"string","enum":["assigned_agent","schedule_creator","user","agent_bot","system"],"example":"system"},"id":{"type":["integer","null"],"minimum":1,"example":null},"missing":{"type":"string","enum":["fail","system","assigned_agent"],"example":"fail"}}},"variables":{"type":"object","additionalProperties":false,"properties":{"resolve_at":{"type":"string","enum":["publication","dispatch"],"example":"dispatch"},"missing":{"type":"string","enum":["fail","blank","skip"],"example":"fail"}}},"dst":{"type":"object","additionalProperties":false,"properties":{"nonexistent":{"type":"string","enum":["skip","shift_forward","shift_backward"],"example":"shift_forward"},"ambiguous":{"type":"string","enum":["first","second","skip"],"example":"first"}}},"materialization":{"type":"object","additionalProperties":false,"properties":{"horizon_seconds":{"type":"integer","minimum":1,"maximum":2592000,"example":2592000},"max_occurrences":{"type":"integer","minimum":1,"maximum":500,"example":500}}},"claim":{"type":"object","additionalProperties":false,"properties":{"lease_seconds":{"type":"integer","minimum":1,"maximum":900,"example":120},"recovery_grace_seconds":{"type":"integer","minimum":0,"maximum":3600,"example":30}}}}},"attachments_count":{"type":"integer","minimum":0,"example":0},"lock_version":{"type":"integer","example":0}}}}}}]}}},"example":{"payload":{"id":701,"name":"Appointment reminder","status":"active","conversation_id":42,"kind":"one_time","timezone":"America/Sao_Paulo","starts_at":"2026-08-22T13:00:00.000Z","version_number":1,"items":[{"id":801,"stable_key":"2dc1f16c-5191-4b3b-97b4-8f33e93dc969","position":1,"timing":{"anchor":"schedule_start","offset_seconds":0},"draft":{"version":1,"schema_version":1,"delay_ms":0,"parts":[{"content":"Olá, seu atendimento está marcado para amanhã.","content_type":"text","content_attributes":{"in_reply_to":88,"in_reply_to_external_id":"wamid.example","items":[{}],"email":{},"interactive":{},"wa_interactive":{},"poll":{},"catalog_product":{},"media_kind":"image","view_once":false,"mention_all":false,"mentioned_jids":[],"mentions":{},"is_forwarded":false,"link_preview":{},"location":{},"contact":{},"cta_buttons":[{}]},"attachments":[{"signed_id":"eyJfcmFpbHMiOnsibWVzc2FnZSI6ImJsb2IifX0","filename":"reminder.pdf","content_type":"application/pdf","byte_size":2048}],"items":[{}],"is_voice_message":false,"email_html_content":"\u003cp\u003eAppointment reminder\u003c/p\u003e","to_emails":["customer@example.com"],"cc_emails":[],"bcc_emails":[],"template_params":{},"flow_params":{},"whatsapp_transport":"cloud"}],"attachments":[{"signed_id":"eyJfcmFpbHMiOnsibWVzc2FnZSI6ImJsb2IifX0","filename":"reminder.pdf","content_type":"application/pdf","byte_size":2048}]},"policy_overrides":{"on_inbound_reply":{"action":"pause"},"on_conversation_resolved":{"action":"continue"},"misfire":{"action":"send_latest","grace_seconds":60,"max_occurrences":10,"spacing_seconds":5},"transient_failure":{"max_attempts":3,"backoff_seconds":[30,120],"exhausted_action":"manual_review"},"permanent_failure":{"action":"manual_review"},"resume_behavior":{"action":"preserve_schedule","max_occurrences":10,"spacing_seconds":5},"quiet_hours":{"enabled":false,"start":"22:00","end":"08:00","days":[0,1,2,3,4,5,6],"action":"defer"},"overlap":{"action":"allow","defer_seconds":60},"inbox_change":{"action":"follow_logical"},"sender":{"type":"system","id":null,"missing":"fail"},"variables":{"resolve_at":"dispatch","missing":"fail"},"dst":{"nonexistent":"shift_forward","ambiguous":"first"},"materialization":{"horizon_seconds":2592000,"max_occurrences":500},"claim":{"lease_seconds":120,"recovery_grace_seconds":30}},"attachments_count":0,"lock_version":0}],"inbox_id":7,"contact_id":81,"created_by_id":9,"next_occurrence_at":"2026-08-22T13:00:00.000Z","materialized_through_at":"2026-08-22T13:00:00.000Z","published_at":"2026-08-21T16:00:00.000Z","paused_at":null,"needs_attention_at":null,"completed_at":null,"canceled_at":null,"archived_at":null,"lock_version":1,"created_at":"2026-08-21T16:00:00.000Z","updated_at":"2026-08-21T16:00:00.000Z","created_by":{"id":9,"name":"Ana Agent"},"rrule":null,"resolved_policies":{},"policy_sources":{},"sender_config":{},"target_config":{}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"201":{"description":"Schedule created and published.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"allOf":[{"type":"object","additionalProperties":false,"properties":{"id":{"type":"integer","example":701},"name":{"type":"string","example":"Appointment reminder"},"status":{"type":"string","enum":["draft","active","paused","needs_attention","completed","canceled","archived"],"example":"active","description":"Lifecycle state of the message schedule."},"inbox_id":{"type":"integer","example":7},"contact_id":{"type":"integer","example":81},"created_by_id":{"type":"integer","example":9},"conversation_id":{"type":"integer","description":"Public conversation display id.","example":42},"next_occurrence_at":{"type":["string","null"],"format":"date-time","example":"2026-08-22T13:00:00.000Z"},"materialized_through_at":{"type":["string","null"],"format":"date-time","example":"2026-08-22T13:00:00.000Z"},"published_at":{"type":["string","null"],"format":"date-time","example":"2026-08-21T16:00:00.000Z"},"paused_at":{"type":["string","null"],"format":"date-time","example":null},"needs_attention_at":{"type":["string","null"],"format":"date-time","example":null},"completed_at":{"type":["string","null"],"format":"date-time","example":null},"canceled_at":{"type":["string","null"],"format":"date-time","example":null},"archived_at":{"type":["string","null"],"format":"date-time","example":null},"lock_version":{"type":"integer","example":1},"created_at":{"type":"string","format":"date-time","example":"2026-08-21T16:00:00.000Z"},"updated_at":{"type":"string","format":"date-time","example":"2026-08-21T16:00:00.000Z"},"created_by":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"integer","example":9},"name":{"type":"string","example":"Ana Agent"}}},"kind":{"type":"string","enum":["one_time","sequence","recurring_single","recurring_sequence"],"example":"one_time","description":"Temporal shape of the scheduled message plan."},"timezone":{"type":"string","example":"America/Sao_Paulo"},"starts_at":{"type":"string","format":"date-time","example":"2026-08-22T13:00:00.000Z"},"rrule":{"type":["string","null"],"example":null},"version_number":{"type":"integer","example":1}}},{"type":"object","properties":{"resolved_policies":{"type":"object","description":"Complete immutable policy snapshot keyed by item stable key.","additionalProperties":{"type":"object","additionalProperties":false,"description":"Explicit schedule-level overrides; omitted leaves inherit from inbox/account.","properties":{"on_inbound_reply":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["continue","pause","cancel","skip"],"example":"pause"}}},"on_conversation_resolved":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["continue","pause","cancel","skip"],"example":"continue"}}},"misfire":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["skip","manual_review","send_latest","catch_up_bounded"],"example":"send_latest"},"grace_seconds":{"type":"integer","minimum":0,"example":60},"max_occurrences":{"type":"integer","minimum":1,"maximum":500,"example":10},"spacing_seconds":{"type":"integer","minimum":0,"example":5}}},"transient_failure":{"type":"object","additionalProperties":false,"properties":{"max_attempts":{"type":"integer","minimum":1,"maximum":10,"example":3},"backoff_seconds":{"type":"array","maxItems":9,"items":{"type":"integer","minimum":0,"maximum":86400},"example":[30,120]},"exhausted_action":{"type":"string","enum":["skip","pause","cancel","manual_review"],"example":"manual_review"}}},"permanent_failure":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["skip","pause","cancel","manual_review"],"example":"manual_review"}}},"resume_behavior":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["preserve_schedule","shift_by_pause","skip_missed","catch_up_bounded"],"example":"preserve_schedule"},"max_occurrences":{"type":"integer","minimum":1,"maximum":500,"example":10},"spacing_seconds":{"type":"integer","minimum":0,"example":5}}},"quiet_hours":{"type":"object","additionalProperties":false,"properties":{"enabled":{"type":"boolean","example":false},"start":{"type":"string","pattern":"^(?:[01][0-9]|2[0-3]):[0-5][0-9]$","example":"22:00"},"end":{"type":"string","pattern":"^(?:[01][0-9]|2[0-3]):[0-5][0-9]$","example":"08:00"},"days":{"type":"array","uniqueItems":true,"items":{"type":"integer","minimum":0,"maximum":6},"example":[0,1,2,3,4,5,6]},"action":{"type":"string","enum":["allow","defer","skip","manual_review"],"example":"defer"}}},"overlap":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["allow","skip_new","defer_new","cancel_previous","manual_review"],"example":"allow"},"defer_seconds":{"type":"integer","minimum":1,"example":60}}},"inbox_change":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["follow_logical","cancel","pause","manual_review"],"example":"follow_logical"}}},"sender":{"type":"object","additionalProperties":false,"properties":{"type":{"type":"string","enum":["assigned_agent","schedule_creator","user","agent_bot","system"],"example":"system"},"id":{"type":["integer","null"],"minimum":1,"example":null},"missing":{"type":"string","enum":["fail","system","assigned_agent"],"example":"fail"}}},"variables":{"type":"object","additionalProperties":false,"properties":{"resolve_at":{"type":"string","enum":["publication","dispatch"],"example":"dispatch"},"missing":{"type":"string","enum":["fail","blank","skip"],"example":"fail"}}},"dst":{"type":"object","additionalProperties":false,"properties":{"nonexistent":{"type":"string","enum":["skip","shift_forward","shift_backward"],"example":"shift_forward"},"ambiguous":{"type":"string","enum":["first","second","skip"],"example":"first"}}},"materialization":{"type":"object","additionalProperties":false,"properties":{"horizon_seconds":{"type":"integer","minimum":1,"maximum":2592000,"example":2592000},"max_occurrences":{"type":"integer","minimum":1,"maximum":500,"example":500}}},"claim":{"type":"object","additionalProperties":false,"properties":{"lease_seconds":{"type":"integer","minimum":1,"maximum":900,"example":120},"recovery_grace_seconds":{"type":"integer","minimum":0,"maximum":3600,"example":30}}}}}},"policy_sources":{"type":"object","description":"Source map keyed by item stable key, then by policy path.","additionalProperties":{"type":"object","description":"Effective source keyed by policy path for this item.","additionalProperties":{"type":"string"}}},"sender_config":{"type":"object","additionalProperties":true,"description":"Server-authored sender snapshot; clients cannot submit it."},"target_config":{"type":"object","additionalProperties":true,"description":"Server-authored immutable conversation/inbox/contact target."},"items":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"integer","example":801},"stable_key":{"type":"string","format":"uuid","example":"2dc1f16c-5191-4b3b-97b4-8f33e93dc969"},"position":{"type":"integer","minimum":1,"example":1},"timing":{"type":"object","additionalProperties":false,"properties":{"anchor":{"type":"string","enum":["schedule_start","previous_scheduled","previous_dispatched"],"example":"schedule_start"},"offset_seconds":{"type":"integer","minimum":0,"example":0}}},"draft":{"type":"object","additionalProperties":false,"required":["parts"],"properties":{"version":{"type":"integer","enum":[1],"example":1},"schema_version":{"type":"integer","enum":[1],"example":1},"delay_ms":{"type":"integer","minimum":0,"maximum":300000,"example":0},"parts":{"type":"array","minItems":1,"maxItems":50,"items":{"type":"object","additionalProperties":false,"properties":{"content":{"type":"string","maxLength":150000,"example":"Olá, seu atendimento está marcado para amanhã."},"content_type":{"type":"string","enum":["text","input_select","sticker","poll"],"example":"text"},"content_attributes":{"type":"object","additionalProperties":false,"description":"Closed outbound metadata roots; rich provider objects remain JSON-shaped and are revalidated before dispatch.","properties":{"in_reply_to":{"type":"integer","example":88},"in_reply_to_external_id":{"type":"string","example":"wamid.example"},"items":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Provider-native option object."}},"email":{"type":"object","additionalProperties":true,"description":"Structured outbound e-mail metadata."},"interactive":{"type":"object","additionalProperties":true,"description":"WhatsApp Cloud interactive payload."},"wa_interactive":{"type":"object","additionalProperties":true,"description":"WazMeow interactive payload."},"poll":{"type":"object","additionalProperties":true,"description":"Poll payload."},"catalog_product":{"type":"object","additionalProperties":true,"description":"Catalog product payload."},"media_kind":{"type":"string","enum":["image","video","audio","document","sticker"],"example":"image"},"view_once":{"type":"boolean","example":false},"mention_all":{"type":"boolean","example":false},"mentioned_jids":{"type":"array","items":{"type":"string"},"example":[]},"mentions":{"type":"object","additionalProperties":true,"description":"Mention map keyed by provider identifier."},"is_forwarded":{"type":"boolean","example":false},"link_preview":{"type":"object","additionalProperties":true,"description":"Link preview metadata."},"location":{"type":"object","additionalProperties":true,"description":"Location payload."},"contact":{"type":"object","additionalProperties":true,"description":"Contact card payload."},"cta_buttons":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Call-to-action button."}}}},"attachments":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["signed_id"],"properties":{"signed_id":{"type":"string","description":"ActiveStorage signed blob id.","example":"eyJfcmFpbHMiOnsibWVzc2FnZSI6ImJsb2IifX0"},"filename":{"type":"string","example":"reminder.pdf"},"content_type":{"type":"string","example":"application/pdf"},"byte_size":{"type":"integer","minimum":0,"example":2048}}}},"items":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Structured select or poll option."}},"is_voice_message":{"type":"boolean","example":false},"email_html_content":{"type":"string","example":"\u003cp\u003eAppointment reminder\u003c/p\u003e"},"to_emails":{"type":"array","items":{"type":"string","format":"email"},"example":["customer@example.com"]},"cc_emails":{"type":"array","items":{"type":"string","format":"email"},"example":[]},"bcc_emails":{"type":"array","items":{"type":"string","format":"email"},"example":[]},"template_params":{"type":"object","additionalProperties":true,"description":"Approved template identity and parameters."},"flow_params":{"type":"object","additionalProperties":true,"description":"WhatsApp Flow identity and parameters."},"whatsapp_transport":{"type":"string","enum":["cloud","web"],"example":"cloud"}}}},"attachments":{"type":"array","description":"Union of the signed attachment references present in parts.","items":{"type":"object","additionalProperties":false,"required":["signed_id"],"properties":{"signed_id":{"type":"string","description":"ActiveStorage signed blob id.","example":"eyJfcmFpbHMiOnsibWVzc2FnZSI6ImJsb2IifX0"},"filename":{"type":"string","example":"reminder.pdf"},"content_type":{"type":"string","example":"application/pdf"},"byte_size":{"type":"integer","minimum":0,"example":2048}}}}}},"policy_overrides":{"type":"object","additionalProperties":false,"description":"Explicit schedule-level overrides; omitted leaves inherit from inbox/account.","properties":{"on_inbound_reply":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["continue","pause","cancel","skip"],"example":"pause"}}},"on_conversation_resolved":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["continue","pause","cancel","skip"],"example":"continue"}}},"misfire":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["skip","manual_review","send_latest","catch_up_bounded"],"example":"send_latest"},"grace_seconds":{"type":"integer","minimum":0,"example":60},"max_occurrences":{"type":"integer","minimum":1,"maximum":500,"example":10},"spacing_seconds":{"type":"integer","minimum":0,"example":5}}},"transient_failure":{"type":"object","additionalProperties":false,"properties":{"max_attempts":{"type":"integer","minimum":1,"maximum":10,"example":3},"backoff_seconds":{"type":"array","maxItems":9,"items":{"type":"integer","minimum":0,"maximum":86400},"example":[30,120]},"exhausted_action":{"type":"string","enum":["skip","pause","cancel","manual_review"],"example":"manual_review"}}},"permanent_failure":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["skip","pause","cancel","manual_review"],"example":"manual_review"}}},"resume_behavior":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["preserve_schedule","shift_by_pause","skip_missed","catch_up_bounded"],"example":"preserve_schedule"},"max_occurrences":{"type":"integer","minimum":1,"maximum":500,"example":10},"spacing_seconds":{"type":"integer","minimum":0,"example":5}}},"quiet_hours":{"type":"object","additionalProperties":false,"properties":{"enabled":{"type":"boolean","example":false},"start":{"type":"string","pattern":"^(?:[01][0-9]|2[0-3]):[0-5][0-9]$","example":"22:00"},"end":{"type":"string","pattern":"^(?:[01][0-9]|2[0-3]):[0-5][0-9]$","example":"08:00"},"days":{"type":"array","uniqueItems":true,"items":{"type":"integer","minimum":0,"maximum":6},"example":[0,1,2,3,4,5,6]},"action":{"type":"string","enum":["allow","defer","skip","manual_review"],"example":"defer"}}},"overlap":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["allow","skip_new","defer_new","cancel_previous","manual_review"],"example":"allow"},"defer_seconds":{"type":"integer","minimum":1,"example":60}}},"inbox_change":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["follow_logical","cancel","pause","manual_review"],"example":"follow_logical"}}},"sender":{"type":"object","additionalProperties":false,"properties":{"type":{"type":"string","enum":["assigned_agent","schedule_creator","user","agent_bot","system"],"example":"system"},"id":{"type":["integer","null"],"minimum":1,"example":null},"missing":{"type":"string","enum":["fail","system","assigned_agent"],"example":"fail"}}},"variables":{"type":"object","additionalProperties":false,"properties":{"resolve_at":{"type":"string","enum":["publication","dispatch"],"example":"dispatch"},"missing":{"type":"string","enum":["fail","blank","skip"],"example":"fail"}}},"dst":{"type":"object","additionalProperties":false,"properties":{"nonexistent":{"type":"string","enum":["skip","shift_forward","shift_backward"],"example":"shift_forward"},"ambiguous":{"type":"string","enum":["first","second","skip"],"example":"first"}}},"materialization":{"type":"object","additionalProperties":false,"properties":{"horizon_seconds":{"type":"integer","minimum":1,"maximum":2592000,"example":2592000},"max_occurrences":{"type":"integer","minimum":1,"maximum":500,"example":500}}},"claim":{"type":"object","additionalProperties":false,"properties":{"lease_seconds":{"type":"integer","minimum":1,"maximum":900,"example":120},"recovery_grace_seconds":{"type":"integer","minimum":0,"maximum":3600,"example":30}}}}},"attachments_count":{"type":"integer","minimum":0,"example":0},"lock_version":{"type":"integer","example":0}}}}}}]}}},"example":{"payload":{"id":701,"name":"Appointment reminder","status":"active","conversation_id":42,"kind":"one_time","timezone":"America/Sao_Paulo","starts_at":"2026-08-22T13:00:00.000Z","version_number":1,"items":[{"id":801,"stable_key":"2dc1f16c-5191-4b3b-97b4-8f33e93dc969","position":1,"timing":{"anchor":"schedule_start","offset_seconds":0},"draft":{"version":1,"schema_version":1,"delay_ms":0,"parts":[{"content":"Olá, seu atendimento está marcado para amanhã.","content_type":"text","content_attributes":{"in_reply_to":88,"in_reply_to_external_id":"wamid.example","items":[{}],"email":{},"interactive":{},"wa_interactive":{},"poll":{},"catalog_product":{},"media_kind":"image","view_once":false,"mention_all":false,"mentioned_jids":[],"mentions":{},"is_forwarded":false,"link_preview":{},"location":{},"contact":{},"cta_buttons":[{}]},"attachments":[{"signed_id":"eyJfcmFpbHMiOnsibWVzc2FnZSI6ImJsb2IifX0","filename":"reminder.pdf","content_type":"application/pdf","byte_size":2048}],"items":[{}],"is_voice_message":false,"email_html_content":"\u003cp\u003eAppointment reminder\u003c/p\u003e","to_emails":["customer@example.com"],"cc_emails":[],"bcc_emails":[],"template_params":{},"flow_params":{},"whatsapp_transport":"cloud"}],"attachments":[{"signed_id":"eyJfcmFpbHMiOnsibWVzc2FnZSI6ImJsb2IifX0","filename":"reminder.pdf","content_type":"application/pdf","byte_size":2048}]},"policy_overrides":{"on_inbound_reply":{"action":"pause"},"on_conversation_resolved":{"action":"continue"},"misfire":{"action":"send_latest","grace_seconds":60,"max_occurrences":10,"spacing_seconds":5},"transient_failure":{"max_attempts":3,"backoff_seconds":[30,120],"exhausted_action":"manual_review"},"permanent_failure":{"action":"manual_review"},"resume_behavior":{"action":"preserve_schedule","max_occurrences":10,"spacing_seconds":5},"quiet_hours":{"enabled":false,"start":"22:00","end":"08:00","days":[0,1,2,3,4,5,6],"action":"defer"},"overlap":{"action":"allow","defer_seconds":60},"inbox_change":{"action":"follow_logical"},"sender":{"type":"system","id":null,"missing":"fail"},"variables":{"resolve_at":"dispatch","missing":"fail"},"dst":{"nonexistent":"shift_forward","ambiguous":"first"},"materialization":{"horizon_seconds":2592000,"max_occurrences":500},"claim":{"lease_seconds":120,"recovery_grace_seconds":30}},"attachments_count":0,"lock_version":0}],"inbox_id":7,"contact_id":81,"created_by_id":9,"next_occurrence_at":"2026-08-22T13:00:00.000Z","materialized_through_at":"2026-08-22T13:00:00.000Z","published_at":"2026-08-21T16:00:00.000Z","paused_at":null,"needs_attention_at":null,"completed_at":null,"canceled_at":null,"archived_at":null,"lock_version":1,"created_at":"2026-08-21T16:00:00.000Z","updated_at":"2026-08-21T16:00:00.000Z","created_by":{"id":9,"name":"Ana Agent"},"rrule":null,"resolved_policies":{},"policy_sources":{},"sender_config":{},"target_config":{}}}}}},"409":{"description":"The idempotency key belongs to a different definition."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"X-Idempotency-Key","in":"header","required":true,"description":"Stable 1–128 character key for this logical create request.","schema":{"type":"string","pattern":"^[A-Za-z0-9._:-]{1,128}$"},"example":"appointment-reminder-42-20260821"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"conversation_id":{"type":"integer","description":"Public display id of the existing target conversation.","example":42},"name":{"type":"string","maxLength":255,"example":"Appointment reminder"},"kind":{"type":"string","enum":["one_time","sequence","recurring_single","recurring_sequence"],"example":"one_time","description":"Temporal shape of the scheduled message plan."},"starts_at":{"type":"string","format":"date-time","description":"First civil occurrence represented as an ISO-8601 instant.","example":"2026-08-22T13:00:00.000Z"},"timezone":{"type":"string","description":"IANA timezone used for recurrence and DST decisions. When omitted or blank it inherits the effective scheduling timezone of the conversation inbox (inbox setting, then account setting, then the account timezone, then UTC); an explicit invalid value is rejected with invalid_timezone. On update a blank value keeps the published timezone.","example":"America/Sao_Paulo"},"recurrence":{"type":["object","null"],"additionalProperties":false,"description":"Required only for recurring kinds; COUNT/UNTIL stays outside rrule.","properties":{"rrule":{"type":"string","description":"RFC 5545 recurrence body without RRULE prefix, COUNT or UNTIL.","example":"FREQ=WEEKLY;INTERVAL=1;BYDAY=MO,WE"},"end_mode":{"type":"string","enum":["never","until","count"],"example":"count"},"until":{"type":["string","null"],"format":"date-time","example":null},"count":{"type":["integer","null"],"minimum":1,"maximum":10000,"example":8}}},"policies":{"type":"object","additionalProperties":false,"description":"Explicit schedule-level overrides; omitted leaves inherit from inbox/account.","properties":{"on_inbound_reply":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["continue","pause","cancel","skip"],"example":"pause"}}},"on_conversation_resolved":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["continue","pause","cancel","skip"],"example":"continue"}}},"misfire":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["skip","manual_review","send_latest","catch_up_bounded"],"example":"send_latest"},"grace_seconds":{"type":"integer","minimum":0,"example":60},"max_occurrences":{"type":"integer","minimum":1,"maximum":500,"example":10},"spacing_seconds":{"type":"integer","minimum":0,"example":5}}},"transient_failure":{"type":"object","additionalProperties":false,"properties":{"max_attempts":{"type":"integer","minimum":1,"maximum":10,"example":3},"backoff_seconds":{"type":"array","maxItems":9,"items":{"type":"integer","minimum":0,"maximum":86400},"example":[30,120]},"exhausted_action":{"type":"string","enum":["skip","pause","cancel","manual_review"],"example":"manual_review"}}},"permanent_failure":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["skip","pause","cancel","manual_review"],"example":"manual_review"}}},"resume_behavior":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["preserve_schedule","shift_by_pause","skip_missed","catch_up_bounded"],"example":"preserve_schedule"},"max_occurrences":{"type":"integer","minimum":1,"maximum":500,"example":10},"spacing_seconds":{"type":"integer","minimum":0,"example":5}}},"quiet_hours":{"type":"object","additionalProperties":false,"properties":{"enabled":{"type":"boolean","example":false},"start":{"type":"string","pattern":"^(?:[01][0-9]|2[0-3]):[0-5][0-9]$","example":"22:00"},"end":{"type":"string","pattern":"^(?:[01][0-9]|2[0-3]):[0-5][0-9]$","example":"08:00"},"days":{"type":"array","uniqueItems":true,"items":{"type":"integer","minimum":0,"maximum":6},"example":[0,1,2,3,4,5,6]},"action":{"type":"string","enum":["allow","defer","skip","manual_review"],"example":"defer"}}},"overlap":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["allow","skip_new","defer_new","cancel_previous","manual_review"],"example":"allow"},"defer_seconds":{"type":"integer","minimum":1,"example":60}}},"inbox_change":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["follow_logical","cancel","pause","manual_review"],"example":"follow_logical"}}},"sender":{"type":"object","additionalProperties":false,"properties":{"type":{"type":"string","enum":["assigned_agent","schedule_creator","user","agent_bot","system"],"example":"system"},"id":{"type":["integer","null"],"minimum":1,"example":null},"missing":{"type":"string","enum":["fail","system","assigned_agent"],"example":"fail"}}},"variables":{"type":"object","additionalProperties":false,"properties":{"resolve_at":{"type":"string","enum":["publication","dispatch"],"example":"dispatch"},"missing":{"type":"string","enum":["fail","blank","skip"],"example":"fail"}}},"dst":{"type":"object","additionalProperties":false,"properties":{"nonexistent":{"type":"string","enum":["skip","shift_forward","shift_backward"],"example":"shift_forward"},"ambiguous":{"type":"string","enum":["first","second","skip"],"example":"first"}}},"materialization":{"type":"object","additionalProperties":false,"properties":{"horizon_seconds":{"type":"integer","minimum":1,"maximum":2592000,"example":2592000},"max_occurrences":{"type":"integer","minimum":1,"maximum":500,"example":500}}},"claim":{"type":"object","additionalProperties":false,"properties":{"lease_seconds":{"type":"integer","minimum":1,"maximum":900,"example":120},"recovery_grace_seconds":{"type":"integer","minimum":0,"maximum":3600,"example":30}}}}},"source_message_id":{"type":"integer","description":"Existing outgoing message to clone server-side; mutually exclusive with items.","example":91},"items":{"type":"array","minItems":1,"maxItems":500,"items":{"type":"object","additionalProperties":false,"required":["client_id","position","timing","draft"],"properties":{"client_id":{"type":"string","minLength":1,"example":"item-1"},"position":{"type":"integer","minimum":1,"example":1},"timing":{"type":"object","additionalProperties":false,"required":["anchor","offset_seconds"],"properties":{"anchor":{"type":"string","enum":["schedule_start","previous_scheduled","previous_dispatched"],"example":"schedule_start"},"offset_seconds":{"type":"integer","minimum":0,"example":0}}},"draft":{"type":"object","additionalProperties":false,"required":["parts"],"properties":{"version":{"type":"integer","enum":[1],"example":1},"schema_version":{"type":"integer","enum":[1],"example":1},"delay_ms":{"type":"integer","minimum":0,"maximum":300000,"example":0},"parts":{"type":"array","minItems":1,"maxItems":50,"items":{"type":"object","additionalProperties":false,"properties":{"content":{"type":"string","maxLength":150000,"example":"Olá, seu atendimento está marcado para amanhã."},"content_type":{"type":"string","enum":["text","input_select","sticker","poll"],"example":"text"},"content_attributes":{"type":"object","additionalProperties":false,"description":"Closed outbound metadata roots; rich provider objects remain JSON-shaped and are revalidated before dispatch.","properties":{"in_reply_to":{"type":"integer","example":88},"in_reply_to_external_id":{"type":"string","example":"wamid.example"},"items":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Provider-native option object."}},"email":{"type":"object","additionalProperties":true,"description":"Structured outbound e-mail metadata."},"interactive":{"type":"object","additionalProperties":true,"description":"WhatsApp Cloud interactive payload."},"wa_interactive":{"type":"object","additionalProperties":true,"description":"WazMeow interactive payload."},"poll":{"type":"object","additionalProperties":true,"description":"Poll payload."},"catalog_product":{"type":"object","additionalProperties":true,"description":"Catalog product payload."},"media_kind":{"type":"string","enum":["image","video","audio","document","sticker"],"example":"image"},"view_once":{"type":"boolean","example":false},"mention_all":{"type":"boolean","example":false},"mentioned_jids":{"type":"array","items":{"type":"string"},"example":[]},"mentions":{"type":"object","additionalProperties":true,"description":"Mention map keyed by provider identifier."},"is_forwarded":{"type":"boolean","example":false},"link_preview":{"type":"object","additionalProperties":true,"description":"Link preview metadata."},"location":{"type":"object","additionalProperties":true,"description":"Location payload."},"contact":{"type":"object","additionalProperties":true,"description":"Contact card payload."},"cta_buttons":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Call-to-action button."}}}},"attachments":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["signed_id"],"properties":{"signed_id":{"type":"string","description":"ActiveStorage signed blob id.","example":"eyJfcmFpbHMiOnsibWVzc2FnZSI6ImJsb2IifX0"},"filename":{"type":"string","example":"reminder.pdf"},"content_type":{"type":"string","example":"application/pdf"},"byte_size":{"type":"integer","minimum":0,"example":2048}}}},"items":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Structured select or poll option."}},"is_voice_message":{"type":"boolean","example":false},"email_html_content":{"type":"string","example":"\u003cp\u003eAppointment reminder\u003c/p\u003e"},"to_emails":{"type":"array","items":{"type":"string","format":"email"},"example":["customer@example.com"]},"cc_emails":{"type":"array","items":{"type":"string","format":"email"},"example":[]},"bcc_emails":{"type":"array","items":{"type":"string","format":"email"},"example":[]},"template_params":{"type":"object","additionalProperties":true,"description":"Approved template identity and parameters."},"flow_params":{"type":"object","additionalProperties":true,"description":"WhatsApp Flow identity and parameters."},"whatsapp_transport":{"type":"string","enum":["cloud","web"],"example":"cloud"}}}},"attachments":{"type":"array","description":"Union of the signed attachment references present in parts.","items":{"type":"object","additionalProperties":false,"required":["signed_id"],"properties":{"signed_id":{"type":"string","description":"ActiveStorage signed blob id.","example":"eyJfcmFpbHMiOnsibWVzc2FnZSI6ImJsb2IifX0"},"filename":{"type":"string","example":"reminder.pdf"},"content_type":{"type":"string","example":"application/pdf"},"byte_size":{"type":"integer","minimum":0,"example":2048}}}}}},"policy_overrides":{"type":"object","additionalProperties":false,"description":"Explicit schedule-level overrides; omitted leaves inherit from inbox/account.","properties":{"on_inbound_reply":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["continue","pause","cancel","skip"],"example":"pause"}}},"on_conversation_resolved":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["continue","pause","cancel","skip"],"example":"continue"}}},"misfire":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["skip","manual_review","send_latest","catch_up_bounded"],"example":"send_latest"},"grace_seconds":{"type":"integer","minimum":0,"example":60},"max_occurrences":{"type":"integer","minimum":1,"maximum":500,"example":10},"spacing_seconds":{"type":"integer","minimum":0,"example":5}}},"transient_failure":{"type":"object","additionalProperties":false,"properties":{"max_attempts":{"type":"integer","minimum":1,"maximum":10,"example":3},"backoff_seconds":{"type":"array","maxItems":9,"items":{"type":"integer","minimum":0,"maximum":86400},"example":[30,120]},"exhausted_action":{"type":"string","enum":["skip","pause","cancel","manual_review"],"example":"manual_review"}}},"permanent_failure":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["skip","pause","cancel","manual_review"],"example":"manual_review"}}},"resume_behavior":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["preserve_schedule","shift_by_pause","skip_missed","catch_up_bounded"],"example":"preserve_schedule"},"max_occurrences":{"type":"integer","minimum":1,"maximum":500,"example":10},"spacing_seconds":{"type":"integer","minimum":0,"example":5}}},"quiet_hours":{"type":"object","additionalProperties":false,"properties":{"enabled":{"type":"boolean","example":false},"start":{"type":"string","pattern":"^(?:[01][0-9]|2[0-3]):[0-5][0-9]$","example":"22:00"},"end":{"type":"string","pattern":"^(?:[01][0-9]|2[0-3]):[0-5][0-9]$","example":"08:00"},"days":{"type":"array","uniqueItems":true,"items":{"type":"integer","minimum":0,"maximum":6},"example":[0,1,2,3,4,5,6]},"action":{"type":"string","enum":["allow","defer","skip","manual_review"],"example":"defer"}}},"overlap":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["allow","skip_new","defer_new","cancel_previous","manual_review"],"example":"allow"},"defer_seconds":{"type":"integer","minimum":1,"example":60}}},"inbox_change":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["follow_logical","cancel","pause","manual_review"],"example":"follow_logical"}}},"sender":{"type":"object","additionalProperties":false,"properties":{"type":{"type":"string","enum":["assigned_agent","schedule_creator","user","agent_bot","system"],"example":"system"},"id":{"type":["integer","null"],"minimum":1,"example":null},"missing":{"type":"string","enum":["fail","system","assigned_agent"],"example":"fail"}}},"variables":{"type":"object","additionalProperties":false,"properties":{"resolve_at":{"type":"string","enum":["publication","dispatch"],"example":"dispatch"},"missing":{"type":"string","enum":["fail","blank","skip"],"example":"fail"}}},"dst":{"type":"object","additionalProperties":false,"properties":{"nonexistent":{"type":"string","enum":["skip","shift_forward","shift_backward"],"example":"shift_forward"},"ambiguous":{"type":"string","enum":["first","second","skip"],"example":"first"}}},"materialization":{"type":"object","additionalProperties":false,"properties":{"horizon_seconds":{"type":"integer","minimum":1,"maximum":2592000,"example":2592000},"max_occurrences":{"type":"integer","minimum":1,"maximum":500,"example":500}}},"claim":{"type":"object","additionalProperties":false,"properties":{"lease_seconds":{"type":"integer","minimum":1,"maximum":900,"example":120},"recovery_grace_seconds":{"type":"integer","minimum":0,"maximum":3600,"example":30}}}}}}}}},"required":["conversation_id","name","kind","starts_at"]},"example":{"conversation_id":42,"name":"Appointment reminder","kind":"one_time","starts_at":"2026-08-22T13:00:00.000Z","timezone":"America/Sao_Paulo","policies":{"on_inbound_reply":{"action":"pause"},"on_conversation_resolved":{"action":"continue"},"misfire":{"action":"send_latest","grace_seconds":60,"max_occurrences":10,"spacing_seconds":5},"transient_failure":{"max_attempts":3,"backoff_seconds":[30,120],"exhausted_action":"manual_review"},"permanent_failure":{"action":"manual_review"},"resume_behavior":{"action":"preserve_schedule","max_occurrences":10,"spacing_seconds":5},"quiet_hours":{"enabled":false,"start":"22:00","end":"08:00","days":[0,1,2,3,4,5,6],"action":"defer"},"overlap":{"action":"allow","defer_seconds":60},"inbox_change":{"action":"follow_logical"},"sender":{"type":"system","id":null,"missing":"fail"},"variables":{"resolve_at":"dispatch","missing":"fail"},"dst":{"nonexistent":"shift_forward","ambiguous":"first"},"materialization":{"horizon_seconds":2592000,"max_occurrences":500},"claim":{"lease_seconds":120,"recovery_grace_seconds":30}},"items":[{"client_id":"item-1","position":1,"timing":{"anchor":"schedule_start","offset_seconds":0},"draft":{"schema_version":1,"delay_ms":0,"parts":[{"content":"Olá, seu atendimento está marcado para amanhã.","content_type":"text","content_attributes":{"in_reply_to":88,"in_reply_to_external_id":"wamid.example","items":[{}],"email":{},"interactive":{},"wa_interactive":{},"poll":{},"catalog_product":{},"media_kind":"image","view_once":false,"mention_all":false,"mentioned_jids":[],"mentions":{},"is_forwarded":false,"link_preview":{},"location":{},"contact":{},"cta_buttons":[{}]},"attachments":[{"signed_id":"eyJfcmFpbHMiOnsibWVzc2FnZSI6ImJsb2IifX0","filename":"reminder.pdf","content_type":"application/pdf","byte_size":2048}],"items":[{}],"is_voice_message":false,"email_html_content":"\u003cp\u003eAppointment reminder\u003c/p\u003e","to_emails":["customer@example.com"],"cc_emails":[],"bcc_emails":[],"template_params":{},"flow_params":{},"whatsapp_transport":"cloud"}],"version":1,"attachments":[{"signed_id":"eyJfcmFpbHMiOnsibWVzc2FnZSI6ImJsb2IifX0","filename":"reminder.pdf","content_type":"application/pdf","byte_size":2048}]},"policy_overrides":{"on_inbound_reply":{"action":"pause"},"on_conversation_resolved":{"action":"continue"},"misfire":{"action":"send_latest","grace_seconds":60,"max_occurrences":10,"spacing_seconds":5},"transient_failure":{"max_attempts":3,"backoff_seconds":[30,120],"exhausted_action":"manual_review"},"permanent_failure":{"action":"manual_review"},"resume_behavior":{"action":"preserve_schedule","max_occurrences":10,"spacing_seconds":5},"quiet_hours":{"enabled":false,"start":"22:00","end":"08:00","days":[0,1,2,3,4,5,6],"action":"defer"},"overlap":{"action":"allow","defer_seconds":60},"inbox_change":{"action":"follow_logical"},"sender":{"type":"system","id":null,"missing":"fail"},"variables":{"resolve_at":"dispatch","missing":"fail"},"dst":{"nonexistent":"shift_forward","ambiguous":"first"},"materialization":{"horizon_seconds":2592000,"max_occurrences":500},"claim":{"lease_seconds":120,"recovery_grace_seconds":30}}}],"recurrence":{"rrule":"FREQ=WEEKLY;INTERVAL=1;BYDAY=MO,WE","end_mode":"count","until":null,"count":8},"source_message_id":91}}}}}},"/api/v1/accounts/{account_id}/message_schedules/{id}":{"get":{"tags":["Message Schedules"],"operationId":"auto_get_api_v1_accounts_account_id_message_schedules_id","summary":"Get one message schedule and its published definition","description":"Returns the message schedule identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Idempotent replay of the already published schedule.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"allOf":[{"type":"object","additionalProperties":false,"properties":{"id":{"type":"integer","example":701},"name":{"type":"string","example":"Appointment reminder"},"status":{"type":"string","enum":["draft","active","paused","needs_attention","completed","canceled","archived"],"example":"active","description":"Lifecycle state of the message schedule."},"inbox_id":{"type":"integer","example":7},"contact_id":{"type":"integer","example":81},"created_by_id":{"type":"integer","example":9},"conversation_id":{"type":"integer","description":"Public conversation display id.","example":42},"next_occurrence_at":{"type":["string","null"],"format":"date-time","example":"2026-08-22T13:00:00.000Z"},"materialized_through_at":{"type":["string","null"],"format":"date-time","example":"2026-08-22T13:00:00.000Z"},"published_at":{"type":["string","null"],"format":"date-time","example":"2026-08-21T16:00:00.000Z"},"paused_at":{"type":["string","null"],"format":"date-time","example":null},"needs_attention_at":{"type":["string","null"],"format":"date-time","example":null},"completed_at":{"type":["string","null"],"format":"date-time","example":null},"canceled_at":{"type":["string","null"],"format":"date-time","example":null},"archived_at":{"type":["string","null"],"format":"date-time","example":null},"lock_version":{"type":"integer","example":1},"created_at":{"type":"string","format":"date-time","example":"2026-08-21T16:00:00.000Z"},"updated_at":{"type":"string","format":"date-time","example":"2026-08-21T16:00:00.000Z"},"created_by":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"integer","example":9},"name":{"type":"string","example":"Ana Agent"}}},"kind":{"type":"string","enum":["one_time","sequence","recurring_single","recurring_sequence"],"example":"one_time","description":"Temporal shape of the scheduled message plan."},"timezone":{"type":"string","example":"America/Sao_Paulo"},"starts_at":{"type":"string","format":"date-time","example":"2026-08-22T13:00:00.000Z"},"rrule":{"type":["string","null"],"example":null},"version_number":{"type":"integer","example":1}}},{"type":"object","properties":{"resolved_policies":{"type":"object","description":"Complete immutable policy snapshot keyed by item stable key.","additionalProperties":{"type":"object","additionalProperties":false,"description":"Explicit schedule-level overrides; omitted leaves inherit from inbox/account.","properties":{"on_inbound_reply":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["continue","pause","cancel","skip"],"example":"pause"}}},"on_conversation_resolved":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["continue","pause","cancel","skip"],"example":"continue"}}},"misfire":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["skip","manual_review","send_latest","catch_up_bounded"],"example":"send_latest"},"grace_seconds":{"type":"integer","minimum":0,"example":60},"max_occurrences":{"type":"integer","minimum":1,"maximum":500,"example":10},"spacing_seconds":{"type":"integer","minimum":0,"example":5}}},"transient_failure":{"type":"object","additionalProperties":false,"properties":{"max_attempts":{"type":"integer","minimum":1,"maximum":10,"example":3},"backoff_seconds":{"type":"array","maxItems":9,"items":{"type":"integer","minimum":0,"maximum":86400},"example":[30,120]},"exhausted_action":{"type":"string","enum":["skip","pause","cancel","manual_review"],"example":"manual_review"}}},"permanent_failure":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["skip","pause","cancel","manual_review"],"example":"manual_review"}}},"resume_behavior":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["preserve_schedule","shift_by_pause","skip_missed","catch_up_bounded"],"example":"preserve_schedule"},"max_occurrences":{"type":"integer","minimum":1,"maximum":500,"example":10},"spacing_seconds":{"type":"integer","minimum":0,"example":5}}},"quiet_hours":{"type":"object","additionalProperties":false,"properties":{"enabled":{"type":"boolean","example":false},"start":{"type":"string","pattern":"^(?:[01][0-9]|2[0-3]):[0-5][0-9]$","example":"22:00"},"end":{"type":"string","pattern":"^(?:[01][0-9]|2[0-3]):[0-5][0-9]$","example":"08:00"},"days":{"type":"array","uniqueItems":true,"items":{"type":"integer","minimum":0,"maximum":6},"example":[0,1,2,3,4,5,6]},"action":{"type":"string","enum":["allow","defer","skip","manual_review"],"example":"defer"}}},"overlap":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["allow","skip_new","defer_new","cancel_previous","manual_review"],"example":"allow"},"defer_seconds":{"type":"integer","minimum":1,"example":60}}},"inbox_change":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["follow_logical","cancel","pause","manual_review"],"example":"follow_logical"}}},"sender":{"type":"object","additionalProperties":false,"properties":{"type":{"type":"string","enum":["assigned_agent","schedule_creator","user","agent_bot","system"],"example":"system"},"id":{"type":["integer","null"],"minimum":1,"example":null},"missing":{"type":"string","enum":["fail","system","assigned_agent"],"example":"fail"}}},"variables":{"type":"object","additionalProperties":false,"properties":{"resolve_at":{"type":"string","enum":["publication","dispatch"],"example":"dispatch"},"missing":{"type":"string","enum":["fail","blank","skip"],"example":"fail"}}},"dst":{"type":"object","additionalProperties":false,"properties":{"nonexistent":{"type":"string","enum":["skip","shift_forward","shift_backward"],"example":"shift_forward"},"ambiguous":{"type":"string","enum":["first","second","skip"],"example":"first"}}},"materialization":{"type":"object","additionalProperties":false,"properties":{"horizon_seconds":{"type":"integer","minimum":1,"maximum":2592000,"example":2592000},"max_occurrences":{"type":"integer","minimum":1,"maximum":500,"example":500}}},"claim":{"type":"object","additionalProperties":false,"properties":{"lease_seconds":{"type":"integer","minimum":1,"maximum":900,"example":120},"recovery_grace_seconds":{"type":"integer","minimum":0,"maximum":3600,"example":30}}}}}},"policy_sources":{"type":"object","description":"Source map keyed by item stable key, then by policy path.","additionalProperties":{"type":"object","description":"Effective source keyed by policy path for this item.","additionalProperties":{"type":"string"}}},"sender_config":{"type":"object","additionalProperties":true,"description":"Server-authored sender snapshot; clients cannot submit it."},"target_config":{"type":"object","additionalProperties":true,"description":"Server-authored immutable conversation/inbox/contact target."},"items":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"integer","example":801},"stable_key":{"type":"string","format":"uuid","example":"2dc1f16c-5191-4b3b-97b4-8f33e93dc969"},"position":{"type":"integer","minimum":1,"example":1},"timing":{"type":"object","additionalProperties":false,"properties":{"anchor":{"type":"string","enum":["schedule_start","previous_scheduled","previous_dispatched"],"example":"schedule_start"},"offset_seconds":{"type":"integer","minimum":0,"example":0}}},"draft":{"type":"object","additionalProperties":false,"required":["parts"],"properties":{"version":{"type":"integer","enum":[1],"example":1},"schema_version":{"type":"integer","enum":[1],"example":1},"delay_ms":{"type":"integer","minimum":0,"maximum":300000,"example":0},"parts":{"type":"array","minItems":1,"maxItems":50,"items":{"type":"object","additionalProperties":false,"properties":{"content":{"type":"string","maxLength":150000,"example":"Olá, seu atendimento está marcado para amanhã."},"content_type":{"type":"string","enum":["text","input_select","sticker","poll"],"example":"text"},"content_attributes":{"type":"object","additionalProperties":false,"description":"Closed outbound metadata roots; rich provider objects remain JSON-shaped and are revalidated before dispatch.","properties":{"in_reply_to":{"type":"integer","example":88},"in_reply_to_external_id":{"type":"string","example":"wamid.example"},"items":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Provider-native option object."}},"email":{"type":"object","additionalProperties":true,"description":"Structured outbound e-mail metadata."},"interactive":{"type":"object","additionalProperties":true,"description":"WhatsApp Cloud interactive payload."},"wa_interactive":{"type":"object","additionalProperties":true,"description":"WazMeow interactive payload."},"poll":{"type":"object","additionalProperties":true,"description":"Poll payload."},"catalog_product":{"type":"object","additionalProperties":true,"description":"Catalog product payload."},"media_kind":{"type":"string","enum":["image","video","audio","document","sticker"],"example":"image"},"view_once":{"type":"boolean","example":false},"mention_all":{"type":"boolean","example":false},"mentioned_jids":{"type":"array","items":{"type":"string"},"example":[]},"mentions":{"type":"object","additionalProperties":true,"description":"Mention map keyed by provider identifier."},"is_forwarded":{"type":"boolean","example":false},"link_preview":{"type":"object","additionalProperties":true,"description":"Link preview metadata."},"location":{"type":"object","additionalProperties":true,"description":"Location payload."},"contact":{"type":"object","additionalProperties":true,"description":"Contact card payload."},"cta_buttons":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Call-to-action button."}}}},"attachments":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["signed_id"],"properties":{"signed_id":{"type":"string","description":"ActiveStorage signed blob id.","example":"eyJfcmFpbHMiOnsibWVzc2FnZSI6ImJsb2IifX0"},"filename":{"type":"string","example":"reminder.pdf"},"content_type":{"type":"string","example":"application/pdf"},"byte_size":{"type":"integer","minimum":0,"example":2048}}}},"items":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Structured select or poll option."}},"is_voice_message":{"type":"boolean","example":false},"email_html_content":{"type":"string","example":"\u003cp\u003eAppointment reminder\u003c/p\u003e"},"to_emails":{"type":"array","items":{"type":"string","format":"email"},"example":["customer@example.com"]},"cc_emails":{"type":"array","items":{"type":"string","format":"email"},"example":[]},"bcc_emails":{"type":"array","items":{"type":"string","format":"email"},"example":[]},"template_params":{"type":"object","additionalProperties":true,"description":"Approved template identity and parameters."},"flow_params":{"type":"object","additionalProperties":true,"description":"WhatsApp Flow identity and parameters."},"whatsapp_transport":{"type":"string","enum":["cloud","web"],"example":"cloud"}}}},"attachments":{"type":"array","description":"Union of the signed attachment references present in parts.","items":{"type":"object","additionalProperties":false,"required":["signed_id"],"properties":{"signed_id":{"type":"string","description":"ActiveStorage signed blob id.","example":"eyJfcmFpbHMiOnsibWVzc2FnZSI6ImJsb2IifX0"},"filename":{"type":"string","example":"reminder.pdf"},"content_type":{"type":"string","example":"application/pdf"},"byte_size":{"type":"integer","minimum":0,"example":2048}}}}}},"policy_overrides":{"type":"object","additionalProperties":false,"description":"Explicit schedule-level overrides; omitted leaves inherit from inbox/account.","properties":{"on_inbound_reply":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["continue","pause","cancel","skip"],"example":"pause"}}},"on_conversation_resolved":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["continue","pause","cancel","skip"],"example":"continue"}}},"misfire":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["skip","manual_review","send_latest","catch_up_bounded"],"example":"send_latest"},"grace_seconds":{"type":"integer","minimum":0,"example":60},"max_occurrences":{"type":"integer","minimum":1,"maximum":500,"example":10},"spacing_seconds":{"type":"integer","minimum":0,"example":5}}},"transient_failure":{"type":"object","additionalProperties":false,"properties":{"max_attempts":{"type":"integer","minimum":1,"maximum":10,"example":3},"backoff_seconds":{"type":"array","maxItems":9,"items":{"type":"integer","minimum":0,"maximum":86400},"example":[30,120]},"exhausted_action":{"type":"string","enum":["skip","pause","cancel","manual_review"],"example":"manual_review"}}},"permanent_failure":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["skip","pause","cancel","manual_review"],"example":"manual_review"}}},"resume_behavior":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["preserve_schedule","shift_by_pause","skip_missed","catch_up_bounded"],"example":"preserve_schedule"},"max_occurrences":{"type":"integer","minimum":1,"maximum":500,"example":10},"spacing_seconds":{"type":"integer","minimum":0,"example":5}}},"quiet_hours":{"type":"object","additionalProperties":false,"properties":{"enabled":{"type":"boolean","example":false},"start":{"type":"string","pattern":"^(?:[01][0-9]|2[0-3]):[0-5][0-9]$","example":"22:00"},"end":{"type":"string","pattern":"^(?:[01][0-9]|2[0-3]):[0-5][0-9]$","example":"08:00"},"days":{"type":"array","uniqueItems":true,"items":{"type":"integer","minimum":0,"maximum":6},"example":[0,1,2,3,4,5,6]},"action":{"type":"string","enum":["allow","defer","skip","manual_review"],"example":"defer"}}},"overlap":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["allow","skip_new","defer_new","cancel_previous","manual_review"],"example":"allow"},"defer_seconds":{"type":"integer","minimum":1,"example":60}}},"inbox_change":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["follow_logical","cancel","pause","manual_review"],"example":"follow_logical"}}},"sender":{"type":"object","additionalProperties":false,"properties":{"type":{"type":"string","enum":["assigned_agent","schedule_creator","user","agent_bot","system"],"example":"system"},"id":{"type":["integer","null"],"minimum":1,"example":null},"missing":{"type":"string","enum":["fail","system","assigned_agent"],"example":"fail"}}},"variables":{"type":"object","additionalProperties":false,"properties":{"resolve_at":{"type":"string","enum":["publication","dispatch"],"example":"dispatch"},"missing":{"type":"string","enum":["fail","blank","skip"],"example":"fail"}}},"dst":{"type":"object","additionalProperties":false,"properties":{"nonexistent":{"type":"string","enum":["skip","shift_forward","shift_backward"],"example":"shift_forward"},"ambiguous":{"type":"string","enum":["first","second","skip"],"example":"first"}}},"materialization":{"type":"object","additionalProperties":false,"properties":{"horizon_seconds":{"type":"integer","minimum":1,"maximum":2592000,"example":2592000},"max_occurrences":{"type":"integer","minimum":1,"maximum":500,"example":500}}},"claim":{"type":"object","additionalProperties":false,"properties":{"lease_seconds":{"type":"integer","minimum":1,"maximum":900,"example":120},"recovery_grace_seconds":{"type":"integer","minimum":0,"maximum":3600,"example":30}}}}},"attachments_count":{"type":"integer","minimum":0,"example":0},"lock_version":{"type":"integer","example":0}}}}}}]}}},"example":{"payload":{"id":701,"name":"Appointment reminder","status":"active","conversation_id":42,"kind":"one_time","timezone":"America/Sao_Paulo","starts_at":"2026-08-22T13:00:00.000Z","version_number":1,"items":[{"id":801,"stable_key":"2dc1f16c-5191-4b3b-97b4-8f33e93dc969","position":1,"timing":{"anchor":"schedule_start","offset_seconds":0},"draft":{"version":1,"schema_version":1,"delay_ms":0,"parts":[{"content":"Olá, seu atendimento está marcado para amanhã.","content_type":"text","content_attributes":{"in_reply_to":88,"in_reply_to_external_id":"wamid.example","items":[{}],"email":{},"interactive":{},"wa_interactive":{},"poll":{},"catalog_product":{},"media_kind":"image","view_once":false,"mention_all":false,"mentioned_jids":[],"mentions":{},"is_forwarded":false,"link_preview":{},"location":{},"contact":{},"cta_buttons":[{}]},"attachments":[{"signed_id":"eyJfcmFpbHMiOnsibWVzc2FnZSI6ImJsb2IifX0","filename":"reminder.pdf","content_type":"application/pdf","byte_size":2048}],"items":[{}],"is_voice_message":false,"email_html_content":"\u003cp\u003eAppointment reminder\u003c/p\u003e","to_emails":["customer@example.com"],"cc_emails":[],"bcc_emails":[],"template_params":{},"flow_params":{},"whatsapp_transport":"cloud"}],"attachments":[{"signed_id":"eyJfcmFpbHMiOnsibWVzc2FnZSI6ImJsb2IifX0","filename":"reminder.pdf","content_type":"application/pdf","byte_size":2048}]},"policy_overrides":{"on_inbound_reply":{"action":"pause"},"on_conversation_resolved":{"action":"continue"},"misfire":{"action":"send_latest","grace_seconds":60,"max_occurrences":10,"spacing_seconds":5},"transient_failure":{"max_attempts":3,"backoff_seconds":[30,120],"exhausted_action":"manual_review"},"permanent_failure":{"action":"manual_review"},"resume_behavior":{"action":"preserve_schedule","max_occurrences":10,"spacing_seconds":5},"quiet_hours":{"enabled":false,"start":"22:00","end":"08:00","days":[0,1,2,3,4,5,6],"action":"defer"},"overlap":{"action":"allow","defer_seconds":60},"inbox_change":{"action":"follow_logical"},"sender":{"type":"system","id":null,"missing":"fail"},"variables":{"resolve_at":"dispatch","missing":"fail"},"dst":{"nonexistent":"shift_forward","ambiguous":"first"},"materialization":{"horizon_seconds":2592000,"max_occurrences":500},"claim":{"lease_seconds":120,"recovery_grace_seconds":30}},"attachments_count":0,"lock_version":0}],"inbox_id":7,"contact_id":81,"created_by_id":9,"next_occurrence_at":"2026-08-22T13:00:00.000Z","materialized_through_at":"2026-08-22T13:00:00.000Z","published_at":"2026-08-21T16:00:00.000Z","paused_at":null,"needs_attention_at":null,"completed_at":null,"canceled_at":null,"archived_at":null,"lock_version":1,"created_at":"2026-08-21T16:00:00.000Z","updated_at":"2026-08-21T16:00:00.000Z","created_by":{"id":9,"name":"Ana Agent"},"rrule":null,"resolved_policies":{},"policy_sources":{},"sender_config":{},"target_config":{}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]},"patch":{"tags":["Message Schedules"],"operationId":"auto_patch_api_v1_accounts_account_id_message_schedules_id","summary":"Publish a new version of a message schedule","description":"Applies the supplied definition fields to the current published definition, revalidates the complete result and publishes a new immutable version. Only future unprocessed occurrences are replaced. A paused schedule stays paused (editing never resumes it); canceled, completed and archived schedules are refused with schedule_not_editable. A stale lock or a concurrent dispatch returns 409 without partial state.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Idempotent replay of the already published schedule.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"allOf":[{"type":"object","additionalProperties":false,"properties":{"id":{"type":"integer","example":701},"name":{"type":"string","example":"Appointment reminder"},"status":{"type":"string","enum":["draft","active","paused","needs_attention","completed","canceled","archived"],"example":"active","description":"Lifecycle state of the message schedule."},"inbox_id":{"type":"integer","example":7},"contact_id":{"type":"integer","example":81},"created_by_id":{"type":"integer","example":9},"conversation_id":{"type":"integer","description":"Public conversation display id.","example":42},"next_occurrence_at":{"type":["string","null"],"format":"date-time","example":"2026-08-22T13:00:00.000Z"},"materialized_through_at":{"type":["string","null"],"format":"date-time","example":"2026-08-22T13:00:00.000Z"},"published_at":{"type":["string","null"],"format":"date-time","example":"2026-08-21T16:00:00.000Z"},"paused_at":{"type":["string","null"],"format":"date-time","example":null},"needs_attention_at":{"type":["string","null"],"format":"date-time","example":null},"completed_at":{"type":["string","null"],"format":"date-time","example":null},"canceled_at":{"type":["string","null"],"format":"date-time","example":null},"archived_at":{"type":["string","null"],"format":"date-time","example":null},"lock_version":{"type":"integer","example":1},"created_at":{"type":"string","format":"date-time","example":"2026-08-21T16:00:00.000Z"},"updated_at":{"type":"string","format":"date-time","example":"2026-08-21T16:00:00.000Z"},"created_by":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"integer","example":9},"name":{"type":"string","example":"Ana Agent"}}},"kind":{"type":"string","enum":["one_time","sequence","recurring_single","recurring_sequence"],"example":"one_time","description":"Temporal shape of the scheduled message plan."},"timezone":{"type":"string","example":"America/Sao_Paulo"},"starts_at":{"type":"string","format":"date-time","example":"2026-08-22T13:00:00.000Z"},"rrule":{"type":["string","null"],"example":null},"version_number":{"type":"integer","example":1}}},{"type":"object","properties":{"resolved_policies":{"type":"object","description":"Complete immutable policy snapshot keyed by item stable key.","additionalProperties":{"type":"object","additionalProperties":false,"description":"Explicit schedule-level overrides; omitted leaves inherit from inbox/account.","properties":{"on_inbound_reply":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["continue","pause","cancel","skip"],"example":"pause"}}},"on_conversation_resolved":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["continue","pause","cancel","skip"],"example":"continue"}}},"misfire":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["skip","manual_review","send_latest","catch_up_bounded"],"example":"send_latest"},"grace_seconds":{"type":"integer","minimum":0,"example":60},"max_occurrences":{"type":"integer","minimum":1,"maximum":500,"example":10},"spacing_seconds":{"type":"integer","minimum":0,"example":5}}},"transient_failure":{"type":"object","additionalProperties":false,"properties":{"max_attempts":{"type":"integer","minimum":1,"maximum":10,"example":3},"backoff_seconds":{"type":"array","maxItems":9,"items":{"type":"integer","minimum":0,"maximum":86400},"example":[30,120]},"exhausted_action":{"type":"string","enum":["skip","pause","cancel","manual_review"],"example":"manual_review"}}},"permanent_failure":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["skip","pause","cancel","manual_review"],"example":"manual_review"}}},"resume_behavior":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["preserve_schedule","shift_by_pause","skip_missed","catch_up_bounded"],"example":"preserve_schedule"},"max_occurrences":{"type":"integer","minimum":1,"maximum":500,"example":10},"spacing_seconds":{"type":"integer","minimum":0,"example":5}}},"quiet_hours":{"type":"object","additionalProperties":false,"properties":{"enabled":{"type":"boolean","example":false},"start":{"type":"string","pattern":"^(?:[01][0-9]|2[0-3]):[0-5][0-9]$","example":"22:00"},"end":{"type":"string","pattern":"^(?:[01][0-9]|2[0-3]):[0-5][0-9]$","example":"08:00"},"days":{"type":"array","uniqueItems":true,"items":{"type":"integer","minimum":0,"maximum":6},"example":[0,1,2,3,4,5,6]},"action":{"type":"string","enum":["allow","defer","skip","manual_review"],"example":"defer"}}},"overlap":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["allow","skip_new","defer_new","cancel_previous","manual_review"],"example":"allow"},"defer_seconds":{"type":"integer","minimum":1,"example":60}}},"inbox_change":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["follow_logical","cancel","pause","manual_review"],"example":"follow_logical"}}},"sender":{"type":"object","additionalProperties":false,"properties":{"type":{"type":"string","enum":["assigned_agent","schedule_creator","user","agent_bot","system"],"example":"system"},"id":{"type":["integer","null"],"minimum":1,"example":null},"missing":{"type":"string","enum":["fail","system","assigned_agent"],"example":"fail"}}},"variables":{"type":"object","additionalProperties":false,"properties":{"resolve_at":{"type":"string","enum":["publication","dispatch"],"example":"dispatch"},"missing":{"type":"string","enum":["fail","blank","skip"],"example":"fail"}}},"dst":{"type":"object","additionalProperties":false,"properties":{"nonexistent":{"type":"string","enum":["skip","shift_forward","shift_backward"],"example":"shift_forward"},"ambiguous":{"type":"string","enum":["first","second","skip"],"example":"first"}}},"materialization":{"type":"object","additionalProperties":false,"properties":{"horizon_seconds":{"type":"integer","minimum":1,"maximum":2592000,"example":2592000},"max_occurrences":{"type":"integer","minimum":1,"maximum":500,"example":500}}},"claim":{"type":"object","additionalProperties":false,"properties":{"lease_seconds":{"type":"integer","minimum":1,"maximum":900,"example":120},"recovery_grace_seconds":{"type":"integer","minimum":0,"maximum":3600,"example":30}}}}}},"policy_sources":{"type":"object","description":"Source map keyed by item stable key, then by policy path.","additionalProperties":{"type":"object","description":"Effective source keyed by policy path for this item.","additionalProperties":{"type":"string"}}},"sender_config":{"type":"object","additionalProperties":true,"description":"Server-authored sender snapshot; clients cannot submit it."},"target_config":{"type":"object","additionalProperties":true,"description":"Server-authored immutable conversation/inbox/contact target."},"items":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"integer","example":801},"stable_key":{"type":"string","format":"uuid","example":"2dc1f16c-5191-4b3b-97b4-8f33e93dc969"},"position":{"type":"integer","minimum":1,"example":1},"timing":{"type":"object","additionalProperties":false,"properties":{"anchor":{"type":"string","enum":["schedule_start","previous_scheduled","previous_dispatched"],"example":"schedule_start"},"offset_seconds":{"type":"integer","minimum":0,"example":0}}},"draft":{"type":"object","additionalProperties":false,"required":["parts"],"properties":{"version":{"type":"integer","enum":[1],"example":1},"schema_version":{"type":"integer","enum":[1],"example":1},"delay_ms":{"type":"integer","minimum":0,"maximum":300000,"example":0},"parts":{"type":"array","minItems":1,"maxItems":50,"items":{"type":"object","additionalProperties":false,"properties":{"content":{"type":"string","maxLength":150000,"example":"Olá, seu atendimento está marcado para amanhã."},"content_type":{"type":"string","enum":["text","input_select","sticker","poll"],"example":"text"},"content_attributes":{"type":"object","additionalProperties":false,"description":"Closed outbound metadata roots; rich provider objects remain JSON-shaped and are revalidated before dispatch.","properties":{"in_reply_to":{"type":"integer","example":88},"in_reply_to_external_id":{"type":"string","example":"wamid.example"},"items":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Provider-native option object."}},"email":{"type":"object","additionalProperties":true,"description":"Structured outbound e-mail metadata."},"interactive":{"type":"object","additionalProperties":true,"description":"WhatsApp Cloud interactive payload."},"wa_interactive":{"type":"object","additionalProperties":true,"description":"WazMeow interactive payload."},"poll":{"type":"object","additionalProperties":true,"description":"Poll payload."},"catalog_product":{"type":"object","additionalProperties":true,"description":"Catalog product payload."},"media_kind":{"type":"string","enum":["image","video","audio","document","sticker"],"example":"image"},"view_once":{"type":"boolean","example":false},"mention_all":{"type":"boolean","example":false},"mentioned_jids":{"type":"array","items":{"type":"string"},"example":[]},"mentions":{"type":"object","additionalProperties":true,"description":"Mention map keyed by provider identifier."},"is_forwarded":{"type":"boolean","example":false},"link_preview":{"type":"object","additionalProperties":true,"description":"Link preview metadata."},"location":{"type":"object","additionalProperties":true,"description":"Location payload."},"contact":{"type":"object","additionalProperties":true,"description":"Contact card payload."},"cta_buttons":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Call-to-action button."}}}},"attachments":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["signed_id"],"properties":{"signed_id":{"type":"string","description":"ActiveStorage signed blob id.","example":"eyJfcmFpbHMiOnsibWVzc2FnZSI6ImJsb2IifX0"},"filename":{"type":"string","example":"reminder.pdf"},"content_type":{"type":"string","example":"application/pdf"},"byte_size":{"type":"integer","minimum":0,"example":2048}}}},"items":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Structured select or poll option."}},"is_voice_message":{"type":"boolean","example":false},"email_html_content":{"type":"string","example":"\u003cp\u003eAppointment reminder\u003c/p\u003e"},"to_emails":{"type":"array","items":{"type":"string","format":"email"},"example":["customer@example.com"]},"cc_emails":{"type":"array","items":{"type":"string","format":"email"},"example":[]},"bcc_emails":{"type":"array","items":{"type":"string","format":"email"},"example":[]},"template_params":{"type":"object","additionalProperties":true,"description":"Approved template identity and parameters."},"flow_params":{"type":"object","additionalProperties":true,"description":"WhatsApp Flow identity and parameters."},"whatsapp_transport":{"type":"string","enum":["cloud","web"],"example":"cloud"}}}},"attachments":{"type":"array","description":"Union of the signed attachment references present in parts.","items":{"type":"object","additionalProperties":false,"required":["signed_id"],"properties":{"signed_id":{"type":"string","description":"ActiveStorage signed blob id.","example":"eyJfcmFpbHMiOnsibWVzc2FnZSI6ImJsb2IifX0"},"filename":{"type":"string","example":"reminder.pdf"},"content_type":{"type":"string","example":"application/pdf"},"byte_size":{"type":"integer","minimum":0,"example":2048}}}}}},"policy_overrides":{"type":"object","additionalProperties":false,"description":"Explicit schedule-level overrides; omitted leaves inherit from inbox/account.","properties":{"on_inbound_reply":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["continue","pause","cancel","skip"],"example":"pause"}}},"on_conversation_resolved":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["continue","pause","cancel","skip"],"example":"continue"}}},"misfire":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["skip","manual_review","send_latest","catch_up_bounded"],"example":"send_latest"},"grace_seconds":{"type":"integer","minimum":0,"example":60},"max_occurrences":{"type":"integer","minimum":1,"maximum":500,"example":10},"spacing_seconds":{"type":"integer","minimum":0,"example":5}}},"transient_failure":{"type":"object","additionalProperties":false,"properties":{"max_attempts":{"type":"integer","minimum":1,"maximum":10,"example":3},"backoff_seconds":{"type":"array","maxItems":9,"items":{"type":"integer","minimum":0,"maximum":86400},"example":[30,120]},"exhausted_action":{"type":"string","enum":["skip","pause","cancel","manual_review"],"example":"manual_review"}}},"permanent_failure":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["skip","pause","cancel","manual_review"],"example":"manual_review"}}},"resume_behavior":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["preserve_schedule","shift_by_pause","skip_missed","catch_up_bounded"],"example":"preserve_schedule"},"max_occurrences":{"type":"integer","minimum":1,"maximum":500,"example":10},"spacing_seconds":{"type":"integer","minimum":0,"example":5}}},"quiet_hours":{"type":"object","additionalProperties":false,"properties":{"enabled":{"type":"boolean","example":false},"start":{"type":"string","pattern":"^(?:[01][0-9]|2[0-3]):[0-5][0-9]$","example":"22:00"},"end":{"type":"string","pattern":"^(?:[01][0-9]|2[0-3]):[0-5][0-9]$","example":"08:00"},"days":{"type":"array","uniqueItems":true,"items":{"type":"integer","minimum":0,"maximum":6},"example":[0,1,2,3,4,5,6]},"action":{"type":"string","enum":["allow","defer","skip","manual_review"],"example":"defer"}}},"overlap":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["allow","skip_new","defer_new","cancel_previous","manual_review"],"example":"allow"},"defer_seconds":{"type":"integer","minimum":1,"example":60}}},"inbox_change":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["follow_logical","cancel","pause","manual_review"],"example":"follow_logical"}}},"sender":{"type":"object","additionalProperties":false,"properties":{"type":{"type":"string","enum":["assigned_agent","schedule_creator","user","agent_bot","system"],"example":"system"},"id":{"type":["integer","null"],"minimum":1,"example":null},"missing":{"type":"string","enum":["fail","system","assigned_agent"],"example":"fail"}}},"variables":{"type":"object","additionalProperties":false,"properties":{"resolve_at":{"type":"string","enum":["publication","dispatch"],"example":"dispatch"},"missing":{"type":"string","enum":["fail","blank","skip"],"example":"fail"}}},"dst":{"type":"object","additionalProperties":false,"properties":{"nonexistent":{"type":"string","enum":["skip","shift_forward","shift_backward"],"example":"shift_forward"},"ambiguous":{"type":"string","enum":["first","second","skip"],"example":"first"}}},"materialization":{"type":"object","additionalProperties":false,"properties":{"horizon_seconds":{"type":"integer","minimum":1,"maximum":2592000,"example":2592000},"max_occurrences":{"type":"integer","minimum":1,"maximum":500,"example":500}}},"claim":{"type":"object","additionalProperties":false,"properties":{"lease_seconds":{"type":"integer","minimum":1,"maximum":900,"example":120},"recovery_grace_seconds":{"type":"integer","minimum":0,"maximum":3600,"example":30}}}}},"attachments_count":{"type":"integer","minimum":0,"example":0},"lock_version":{"type":"integer","example":0}}}}}}]}}},"example":{"payload":{"id":701,"name":"Appointment reminder","status":"active","conversation_id":42,"kind":"one_time","timezone":"America/Sao_Paulo","starts_at":"2026-08-22T13:00:00.000Z","version_number":1,"items":[{"id":801,"stable_key":"2dc1f16c-5191-4b3b-97b4-8f33e93dc969","position":1,"timing":{"anchor":"schedule_start","offset_seconds":0},"draft":{"version":1,"schema_version":1,"delay_ms":0,"parts":[{"content":"Olá, seu atendimento está marcado para amanhã.","content_type":"text","content_attributes":{"in_reply_to":88,"in_reply_to_external_id":"wamid.example","items":[{}],"email":{},"interactive":{},"wa_interactive":{},"poll":{},"catalog_product":{},"media_kind":"image","view_once":false,"mention_all":false,"mentioned_jids":[],"mentions":{},"is_forwarded":false,"link_preview":{},"location":{},"contact":{},"cta_buttons":[{}]},"attachments":[{"signed_id":"eyJfcmFpbHMiOnsibWVzc2FnZSI6ImJsb2IifX0","filename":"reminder.pdf","content_type":"application/pdf","byte_size":2048}],"items":[{}],"is_voice_message":false,"email_html_content":"\u003cp\u003eAppointment reminder\u003c/p\u003e","to_emails":["customer@example.com"],"cc_emails":[],"bcc_emails":[],"template_params":{},"flow_params":{},"whatsapp_transport":"cloud"}],"attachments":[{"signed_id":"eyJfcmFpbHMiOnsibWVzc2FnZSI6ImJsb2IifX0","filename":"reminder.pdf","content_type":"application/pdf","byte_size":2048}]},"policy_overrides":{"on_inbound_reply":{"action":"pause"},"on_conversation_resolved":{"action":"continue"},"misfire":{"action":"send_latest","grace_seconds":60,"max_occurrences":10,"spacing_seconds":5},"transient_failure":{"max_attempts":3,"backoff_seconds":[30,120],"exhausted_action":"manual_review"},"permanent_failure":{"action":"manual_review"},"resume_behavior":{"action":"preserve_schedule","max_occurrences":10,"spacing_seconds":5},"quiet_hours":{"enabled":false,"start":"22:00","end":"08:00","days":[0,1,2,3,4,5,6],"action":"defer"},"overlap":{"action":"allow","defer_seconds":60},"inbox_change":{"action":"follow_logical"},"sender":{"type":"system","id":null,"missing":"fail"},"variables":{"resolve_at":"dispatch","missing":"fail"},"dst":{"nonexistent":"shift_forward","ambiguous":"first"},"materialization":{"horizon_seconds":2592000,"max_occurrences":500},"claim":{"lease_seconds":120,"recovery_grace_seconds":30}},"attachments_count":0,"lock_version":0}],"inbox_id":7,"contact_id":81,"created_by_id":9,"next_occurrence_at":"2026-08-22T13:00:00.000Z","materialized_through_at":"2026-08-22T13:00:00.000Z","published_at":"2026-08-21T16:00:00.000Z","paused_at":null,"needs_attention_at":null,"completed_at":null,"canceled_at":null,"archived_at":null,"lock_version":1,"created_at":"2026-08-21T16:00:00.000Z","updated_at":"2026-08-21T16:00:00.000Z","created_by":{"id":9,"name":"Ana Agent"},"rrule":null,"resolved_policies":{},"policy_sources":{},"sender_config":{},"target_config":{}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"409":{"description":"Stale lock version or schedule currently executing."},"422":{"description":"The schedule has ended (canceled, completed or archived) or the merged definition is invalid.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Error code plus optional details (the current status for schedule_not_editable, the blocker or validation list otherwise).","required":["error"],"properties":{"error":{"type":"string","example":"schedule_not_editable"}}},"example":{"error":"schedule_not_editable","details":"canceled"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"conversation_id":{"type":"integer","description":"Public display id of the existing target conversation.","example":42},"name":{"type":"string","maxLength":255,"example":"Appointment reminder"},"kind":{"type":"string","enum":["one_time","sequence","recurring_single","recurring_sequence"],"example":"one_time","description":"Temporal shape of the scheduled message plan."},"starts_at":{"type":"string","format":"date-time","description":"First civil occurrence represented as an ISO-8601 instant.","example":"2026-08-22T13:00:00.000Z"},"timezone":{"type":"string","description":"IANA timezone used for recurrence and DST decisions. When omitted or blank it inherits the effective scheduling timezone of the conversation inbox (inbox setting, then account setting, then the account timezone, then UTC); an explicit invalid value is rejected with invalid_timezone. On update a blank value keeps the published timezone.","example":"America/Sao_Paulo"},"recurrence":{"type":["object","null"],"additionalProperties":false,"description":"Required only for recurring kinds; COUNT/UNTIL stays outside rrule.","properties":{"rrule":{"type":"string","description":"RFC 5545 recurrence body without RRULE prefix, COUNT or UNTIL.","example":"FREQ=WEEKLY;INTERVAL=1;BYDAY=MO,WE"},"end_mode":{"type":"string","enum":["never","until","count"],"example":"count"},"until":{"type":["string","null"],"format":"date-time","example":null},"count":{"type":["integer","null"],"minimum":1,"maximum":10000,"example":8}}},"policies":{"type":"object","additionalProperties":false,"description":"Explicit schedule-level overrides; omitted leaves inherit from inbox/account.","properties":{"on_inbound_reply":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["continue","pause","cancel","skip"],"example":"pause"}}},"on_conversation_resolved":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["continue","pause","cancel","skip"],"example":"continue"}}},"misfire":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["skip","manual_review","send_latest","catch_up_bounded"],"example":"send_latest"},"grace_seconds":{"type":"integer","minimum":0,"example":60},"max_occurrences":{"type":"integer","minimum":1,"maximum":500,"example":10},"spacing_seconds":{"type":"integer","minimum":0,"example":5}}},"transient_failure":{"type":"object","additionalProperties":false,"properties":{"max_attempts":{"type":"integer","minimum":1,"maximum":10,"example":3},"backoff_seconds":{"type":"array","maxItems":9,"items":{"type":"integer","minimum":0,"maximum":86400},"example":[30,120]},"exhausted_action":{"type":"string","enum":["skip","pause","cancel","manual_review"],"example":"manual_review"}}},"permanent_failure":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["skip","pause","cancel","manual_review"],"example":"manual_review"}}},"resume_behavior":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["preserve_schedule","shift_by_pause","skip_missed","catch_up_bounded"],"example":"preserve_schedule"},"max_occurrences":{"type":"integer","minimum":1,"maximum":500,"example":10},"spacing_seconds":{"type":"integer","minimum":0,"example":5}}},"quiet_hours":{"type":"object","additionalProperties":false,"properties":{"enabled":{"type":"boolean","example":false},"start":{"type":"string","pattern":"^(?:[01][0-9]|2[0-3]):[0-5][0-9]$","example":"22:00"},"end":{"type":"string","pattern":"^(?:[01][0-9]|2[0-3]):[0-5][0-9]$","example":"08:00"},"days":{"type":"array","uniqueItems":true,"items":{"type":"integer","minimum":0,"maximum":6},"example":[0,1,2,3,4,5,6]},"action":{"type":"string","enum":["allow","defer","skip","manual_review"],"example":"defer"}}},"overlap":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["allow","skip_new","defer_new","cancel_previous","manual_review"],"example":"allow"},"defer_seconds":{"type":"integer","minimum":1,"example":60}}},"inbox_change":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["follow_logical","cancel","pause","manual_review"],"example":"follow_logical"}}},"sender":{"type":"object","additionalProperties":false,"properties":{"type":{"type":"string","enum":["assigned_agent","schedule_creator","user","agent_bot","system"],"example":"system"},"id":{"type":["integer","null"],"minimum":1,"example":null},"missing":{"type":"string","enum":["fail","system","assigned_agent"],"example":"fail"}}},"variables":{"type":"object","additionalProperties":false,"properties":{"resolve_at":{"type":"string","enum":["publication","dispatch"],"example":"dispatch"},"missing":{"type":"string","enum":["fail","blank","skip"],"example":"fail"}}},"dst":{"type":"object","additionalProperties":false,"properties":{"nonexistent":{"type":"string","enum":["skip","shift_forward","shift_backward"],"example":"shift_forward"},"ambiguous":{"type":"string","enum":["first","second","skip"],"example":"first"}}},"materialization":{"type":"object","additionalProperties":false,"properties":{"horizon_seconds":{"type":"integer","minimum":1,"maximum":2592000,"example":2592000},"max_occurrences":{"type":"integer","minimum":1,"maximum":500,"example":500}}},"claim":{"type":"object","additionalProperties":false,"properties":{"lease_seconds":{"type":"integer","minimum":1,"maximum":900,"example":120},"recovery_grace_seconds":{"type":"integer","minimum":0,"maximum":3600,"example":30}}}}},"source_message_id":{"type":"integer","description":"Existing outgoing message to clone server-side; mutually exclusive with items.","example":91},"items":{"type":"array","minItems":1,"maxItems":500,"items":{"type":"object","additionalProperties":false,"required":["client_id","position","timing","draft"],"properties":{"client_id":{"type":"string","minLength":1,"example":"item-1"},"position":{"type":"integer","minimum":1,"example":1},"timing":{"type":"object","additionalProperties":false,"required":["anchor","offset_seconds"],"properties":{"anchor":{"type":"string","enum":["schedule_start","previous_scheduled","previous_dispatched"],"example":"schedule_start"},"offset_seconds":{"type":"integer","minimum":0,"example":0}}},"draft":{"type":"object","additionalProperties":false,"required":["parts"],"properties":{"version":{"type":"integer","enum":[1],"example":1},"schema_version":{"type":"integer","enum":[1],"example":1},"delay_ms":{"type":"integer","minimum":0,"maximum":300000,"example":0},"parts":{"type":"array","minItems":1,"maxItems":50,"items":{"type":"object","additionalProperties":false,"properties":{"content":{"type":"string","maxLength":150000,"example":"Olá, seu atendimento está marcado para amanhã."},"content_type":{"type":"string","enum":["text","input_select","sticker","poll"],"example":"text"},"content_attributes":{"type":"object","additionalProperties":false,"description":"Closed outbound metadata roots; rich provider objects remain JSON-shaped and are revalidated before dispatch.","properties":{"in_reply_to":{"type":"integer","example":88},"in_reply_to_external_id":{"type":"string","example":"wamid.example"},"items":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Provider-native option object."}},"email":{"type":"object","additionalProperties":true,"description":"Structured outbound e-mail metadata."},"interactive":{"type":"object","additionalProperties":true,"description":"WhatsApp Cloud interactive payload."},"wa_interactive":{"type":"object","additionalProperties":true,"description":"WazMeow interactive payload."},"poll":{"type":"object","additionalProperties":true,"description":"Poll payload."},"catalog_product":{"type":"object","additionalProperties":true,"description":"Catalog product payload."},"media_kind":{"type":"string","enum":["image","video","audio","document","sticker"],"example":"image"},"view_once":{"type":"boolean","example":false},"mention_all":{"type":"boolean","example":false},"mentioned_jids":{"type":"array","items":{"type":"string"},"example":[]},"mentions":{"type":"object","additionalProperties":true,"description":"Mention map keyed by provider identifier."},"is_forwarded":{"type":"boolean","example":false},"link_preview":{"type":"object","additionalProperties":true,"description":"Link preview metadata."},"location":{"type":"object","additionalProperties":true,"description":"Location payload."},"contact":{"type":"object","additionalProperties":true,"description":"Contact card payload."},"cta_buttons":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Call-to-action button."}}}},"attachments":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["signed_id"],"properties":{"signed_id":{"type":"string","description":"ActiveStorage signed blob id.","example":"eyJfcmFpbHMiOnsibWVzc2FnZSI6ImJsb2IifX0"},"filename":{"type":"string","example":"reminder.pdf"},"content_type":{"type":"string","example":"application/pdf"},"byte_size":{"type":"integer","minimum":0,"example":2048}}}},"items":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Structured select or poll option."}},"is_voice_message":{"type":"boolean","example":false},"email_html_content":{"type":"string","example":"\u003cp\u003eAppointment reminder\u003c/p\u003e"},"to_emails":{"type":"array","items":{"type":"string","format":"email"},"example":["customer@example.com"]},"cc_emails":{"type":"array","items":{"type":"string","format":"email"},"example":[]},"bcc_emails":{"type":"array","items":{"type":"string","format":"email"},"example":[]},"template_params":{"type":"object","additionalProperties":true,"description":"Approved template identity and parameters."},"flow_params":{"type":"object","additionalProperties":true,"description":"WhatsApp Flow identity and parameters."},"whatsapp_transport":{"type":"string","enum":["cloud","web"],"example":"cloud"}}}},"attachments":{"type":"array","description":"Union of the signed attachment references present in parts.","items":{"type":"object","additionalProperties":false,"required":["signed_id"],"properties":{"signed_id":{"type":"string","description":"ActiveStorage signed blob id.","example":"eyJfcmFpbHMiOnsibWVzc2FnZSI6ImJsb2IifX0"},"filename":{"type":"string","example":"reminder.pdf"},"content_type":{"type":"string","example":"application/pdf"},"byte_size":{"type":"integer","minimum":0,"example":2048}}}}}},"policy_overrides":{"type":"object","additionalProperties":false,"description":"Explicit schedule-level overrides; omitted leaves inherit from inbox/account.","properties":{"on_inbound_reply":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["continue","pause","cancel","skip"],"example":"pause"}}},"on_conversation_resolved":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["continue","pause","cancel","skip"],"example":"continue"}}},"misfire":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["skip","manual_review","send_latest","catch_up_bounded"],"example":"send_latest"},"grace_seconds":{"type":"integer","minimum":0,"example":60},"max_occurrences":{"type":"integer","minimum":1,"maximum":500,"example":10},"spacing_seconds":{"type":"integer","minimum":0,"example":5}}},"transient_failure":{"type":"object","additionalProperties":false,"properties":{"max_attempts":{"type":"integer","minimum":1,"maximum":10,"example":3},"backoff_seconds":{"type":"array","maxItems":9,"items":{"type":"integer","minimum":0,"maximum":86400},"example":[30,120]},"exhausted_action":{"type":"string","enum":["skip","pause","cancel","manual_review"],"example":"manual_review"}}},"permanent_failure":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["skip","pause","cancel","manual_review"],"example":"manual_review"}}},"resume_behavior":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["preserve_schedule","shift_by_pause","skip_missed","catch_up_bounded"],"example":"preserve_schedule"},"max_occurrences":{"type":"integer","minimum":1,"maximum":500,"example":10},"spacing_seconds":{"type":"integer","minimum":0,"example":5}}},"quiet_hours":{"type":"object","additionalProperties":false,"properties":{"enabled":{"type":"boolean","example":false},"start":{"type":"string","pattern":"^(?:[01][0-9]|2[0-3]):[0-5][0-9]$","example":"22:00"},"end":{"type":"string","pattern":"^(?:[01][0-9]|2[0-3]):[0-5][0-9]$","example":"08:00"},"days":{"type":"array","uniqueItems":true,"items":{"type":"integer","minimum":0,"maximum":6},"example":[0,1,2,3,4,5,6]},"action":{"type":"string","enum":["allow","defer","skip","manual_review"],"example":"defer"}}},"overlap":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["allow","skip_new","defer_new","cancel_previous","manual_review"],"example":"allow"},"defer_seconds":{"type":"integer","minimum":1,"example":60}}},"inbox_change":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["follow_logical","cancel","pause","manual_review"],"example":"follow_logical"}}},"sender":{"type":"object","additionalProperties":false,"properties":{"type":{"type":"string","enum":["assigned_agent","schedule_creator","user","agent_bot","system"],"example":"system"},"id":{"type":["integer","null"],"minimum":1,"example":null},"missing":{"type":"string","enum":["fail","system","assigned_agent"],"example":"fail"}}},"variables":{"type":"object","additionalProperties":false,"properties":{"resolve_at":{"type":"string","enum":["publication","dispatch"],"example":"dispatch"},"missing":{"type":"string","enum":["fail","blank","skip"],"example":"fail"}}},"dst":{"type":"object","additionalProperties":false,"properties":{"nonexistent":{"type":"string","enum":["skip","shift_forward","shift_backward"],"example":"shift_forward"},"ambiguous":{"type":"string","enum":["first","second","skip"],"example":"first"}}},"materialization":{"type":"object","additionalProperties":false,"properties":{"horizon_seconds":{"type":"integer","minimum":1,"maximum":2592000,"example":2592000},"max_occurrences":{"type":"integer","minimum":1,"maximum":500,"example":500}}},"claim":{"type":"object","additionalProperties":false,"properties":{"lease_seconds":{"type":"integer","minimum":1,"maximum":900,"example":120},"recovery_grace_seconds":{"type":"integer","minimum":0,"maximum":3600,"example":30}}}}}}}},"lock_version":{"type":"integer","minimum":0,"example":1}},"required":["lock_version"]},"example":{"lock_version":1,"name":"Updated appointment reminder","starts_at":"2026-08-22T14:00:00.000Z","conversation_id":42,"kind":"one_time","timezone":"America/Sao_Paulo","recurrence":{"rrule":"FREQ=WEEKLY;INTERVAL=1;BYDAY=MO,WE","end_mode":"count","until":null,"count":8},"policies":{"on_inbound_reply":{"action":"pause"},"on_conversation_resolved":{"action":"continue"},"misfire":{"action":"send_latest","grace_seconds":60,"max_occurrences":10,"spacing_seconds":5},"transient_failure":{"max_attempts":3,"backoff_seconds":[30,120],"exhausted_action":"manual_review"},"permanent_failure":{"action":"manual_review"},"resume_behavior":{"action":"preserve_schedule","max_occurrences":10,"spacing_seconds":5},"quiet_hours":{"enabled":false,"start":"22:00","end":"08:00","days":[0,1,2,3,4,5,6],"action":"defer"},"overlap":{"action":"allow","defer_seconds":60},"inbox_change":{"action":"follow_logical"},"sender":{"type":"system","id":null,"missing":"fail"},"variables":{"resolve_at":"dispatch","missing":"fail"},"dst":{"nonexistent":"shift_forward","ambiguous":"first"},"materialization":{"horizon_seconds":2592000,"max_occurrences":500},"claim":{"lease_seconds":120,"recovery_grace_seconds":30}},"source_message_id":91,"items":[{"client_id":"item-1","position":1,"timing":{"anchor":"schedule_start","offset_seconds":0},"draft":{"version":1,"schema_version":1,"delay_ms":0,"parts":[{"content":"Olá, seu atendimento está marcado para amanhã.","content_type":"text","content_attributes":{"in_reply_to":88,"in_reply_to_external_id":"wamid.example","items":[{}],"email":{},"interactive":{},"wa_interactive":{},"poll":{},"catalog_product":{},"media_kind":"image","view_once":false,"mention_all":false,"mentioned_jids":[],"mentions":{},"is_forwarded":false,"link_preview":{},"location":{},"contact":{},"cta_buttons":[{}]},"attachments":[{"signed_id":"eyJfcmFpbHMiOnsibWVzc2FnZSI6ImJsb2IifX0","filename":"reminder.pdf","content_type":"application/pdf","byte_size":2048}],"items":[{}],"is_voice_message":false,"email_html_content":"\u003cp\u003eAppointment reminder\u003c/p\u003e","to_emails":["customer@example.com"],"cc_emails":[],"bcc_emails":[],"template_params":{},"flow_params":{},"whatsapp_transport":"cloud"}],"attachments":[{"signed_id":"eyJfcmFpbHMiOnsibWVzc2FnZSI6ImJsb2IifX0","filename":"reminder.pdf","content_type":"application/pdf","byte_size":2048}]},"policy_overrides":{"on_inbound_reply":{"action":"pause"},"on_conversation_resolved":{"action":"continue"},"misfire":{"action":"send_latest","grace_seconds":60,"max_occurrences":10,"spacing_seconds":5},"transient_failure":{"max_attempts":3,"backoff_seconds":[30,120],"exhausted_action":"manual_review"},"permanent_failure":{"action":"manual_review"},"resume_behavior":{"action":"preserve_schedule","max_occurrences":10,"spacing_seconds":5},"quiet_hours":{"enabled":false,"start":"22:00","end":"08:00","days":[0,1,2,3,4,5,6],"action":"defer"},"overlap":{"action":"allow","defer_seconds":60},"inbox_change":{"action":"follow_logical"},"sender":{"type":"system","id":null,"missing":"fail"},"variables":{"resolve_at":"dispatch","missing":"fail"},"dst":{"nonexistent":"shift_forward","ambiguous":"first"},"materialization":{"horizon_seconds":2592000,"max_occurrences":500},"claim":{"lease_seconds":120,"recovery_grace_seconds":30}}}]}}}}},"put":{"tags":["Message Schedules"],"operationId":"auto_put_api_v1_accounts_account_id_message_schedules_id","summary":"Publish a new version of a message schedule","description":"Applies the supplied definition fields to the current published definition, revalidates the complete result and publishes a new immutable version. Only future unprocessed occurrences are replaced. A paused schedule stays paused (editing never resumes it); canceled, completed and archived schedules are refused with schedule_not_editable. A stale lock or a concurrent dispatch returns 409 without partial state.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Idempotent replay of the already published schedule.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"allOf":[{"type":"object","additionalProperties":false,"properties":{"id":{"type":"integer","example":701},"name":{"type":"string","example":"Appointment reminder"},"status":{"type":"string","enum":["draft","active","paused","needs_attention","completed","canceled","archived"],"example":"active","description":"Lifecycle state of the message schedule."},"inbox_id":{"type":"integer","example":7},"contact_id":{"type":"integer","example":81},"created_by_id":{"type":"integer","example":9},"conversation_id":{"type":"integer","description":"Public conversation display id.","example":42},"next_occurrence_at":{"type":["string","null"],"format":"date-time","example":"2026-08-22T13:00:00.000Z"},"materialized_through_at":{"type":["string","null"],"format":"date-time","example":"2026-08-22T13:00:00.000Z"},"published_at":{"type":["string","null"],"format":"date-time","example":"2026-08-21T16:00:00.000Z"},"paused_at":{"type":["string","null"],"format":"date-time","example":null},"needs_attention_at":{"type":["string","null"],"format":"date-time","example":null},"completed_at":{"type":["string","null"],"format":"date-time","example":null},"canceled_at":{"type":["string","null"],"format":"date-time","example":null},"archived_at":{"type":["string","null"],"format":"date-time","example":null},"lock_version":{"type":"integer","example":1},"created_at":{"type":"string","format":"date-time","example":"2026-08-21T16:00:00.000Z"},"updated_at":{"type":"string","format":"date-time","example":"2026-08-21T16:00:00.000Z"},"created_by":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"integer","example":9},"name":{"type":"string","example":"Ana Agent"}}},"kind":{"type":"string","enum":["one_time","sequence","recurring_single","recurring_sequence"],"example":"one_time","description":"Temporal shape of the scheduled message plan."},"timezone":{"type":"string","example":"America/Sao_Paulo"},"starts_at":{"type":"string","format":"date-time","example":"2026-08-22T13:00:00.000Z"},"rrule":{"type":["string","null"],"example":null},"version_number":{"type":"integer","example":1}}},{"type":"object","properties":{"resolved_policies":{"type":"object","description":"Complete immutable policy snapshot keyed by item stable key.","additionalProperties":{"type":"object","additionalProperties":false,"description":"Explicit schedule-level overrides; omitted leaves inherit from inbox/account.","properties":{"on_inbound_reply":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["continue","pause","cancel","skip"],"example":"pause"}}},"on_conversation_resolved":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["continue","pause","cancel","skip"],"example":"continue"}}},"misfire":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["skip","manual_review","send_latest","catch_up_bounded"],"example":"send_latest"},"grace_seconds":{"type":"integer","minimum":0,"example":60},"max_occurrences":{"type":"integer","minimum":1,"maximum":500,"example":10},"spacing_seconds":{"type":"integer","minimum":0,"example":5}}},"transient_failure":{"type":"object","additionalProperties":false,"properties":{"max_attempts":{"type":"integer","minimum":1,"maximum":10,"example":3},"backoff_seconds":{"type":"array","maxItems":9,"items":{"type":"integer","minimum":0,"maximum":86400},"example":[30,120]},"exhausted_action":{"type":"string","enum":["skip","pause","cancel","manual_review"],"example":"manual_review"}}},"permanent_failure":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["skip","pause","cancel","manual_review"],"example":"manual_review"}}},"resume_behavior":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["preserve_schedule","shift_by_pause","skip_missed","catch_up_bounded"],"example":"preserve_schedule"},"max_occurrences":{"type":"integer","minimum":1,"maximum":500,"example":10},"spacing_seconds":{"type":"integer","minimum":0,"example":5}}},"quiet_hours":{"type":"object","additionalProperties":false,"properties":{"enabled":{"type":"boolean","example":false},"start":{"type":"string","pattern":"^(?:[01][0-9]|2[0-3]):[0-5][0-9]$","example":"22:00"},"end":{"type":"string","pattern":"^(?:[01][0-9]|2[0-3]):[0-5][0-9]$","example":"08:00"},"days":{"type":"array","uniqueItems":true,"items":{"type":"integer","minimum":0,"maximum":6},"example":[0,1,2,3,4,5,6]},"action":{"type":"string","enum":["allow","defer","skip","manual_review"],"example":"defer"}}},"overlap":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["allow","skip_new","defer_new","cancel_previous","manual_review"],"example":"allow"},"defer_seconds":{"type":"integer","minimum":1,"example":60}}},"inbox_change":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["follow_logical","cancel","pause","manual_review"],"example":"follow_logical"}}},"sender":{"type":"object","additionalProperties":false,"properties":{"type":{"type":"string","enum":["assigned_agent","schedule_creator","user","agent_bot","system"],"example":"system"},"id":{"type":["integer","null"],"minimum":1,"example":null},"missing":{"type":"string","enum":["fail","system","assigned_agent"],"example":"fail"}}},"variables":{"type":"object","additionalProperties":false,"properties":{"resolve_at":{"type":"string","enum":["publication","dispatch"],"example":"dispatch"},"missing":{"type":"string","enum":["fail","blank","skip"],"example":"fail"}}},"dst":{"type":"object","additionalProperties":false,"properties":{"nonexistent":{"type":"string","enum":["skip","shift_forward","shift_backward"],"example":"shift_forward"},"ambiguous":{"type":"string","enum":["first","second","skip"],"example":"first"}}},"materialization":{"type":"object","additionalProperties":false,"properties":{"horizon_seconds":{"type":"integer","minimum":1,"maximum":2592000,"example":2592000},"max_occurrences":{"type":"integer","minimum":1,"maximum":500,"example":500}}},"claim":{"type":"object","additionalProperties":false,"properties":{"lease_seconds":{"type":"integer","minimum":1,"maximum":900,"example":120},"recovery_grace_seconds":{"type":"integer","minimum":0,"maximum":3600,"example":30}}}}}},"policy_sources":{"type":"object","description":"Source map keyed by item stable key, then by policy path.","additionalProperties":{"type":"object","description":"Effective source keyed by policy path for this item.","additionalProperties":{"type":"string"}}},"sender_config":{"type":"object","additionalProperties":true,"description":"Server-authored sender snapshot; clients cannot submit it."},"target_config":{"type":"object","additionalProperties":true,"description":"Server-authored immutable conversation/inbox/contact target."},"items":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"integer","example":801},"stable_key":{"type":"string","format":"uuid","example":"2dc1f16c-5191-4b3b-97b4-8f33e93dc969"},"position":{"type":"integer","minimum":1,"example":1},"timing":{"type":"object","additionalProperties":false,"properties":{"anchor":{"type":"string","enum":["schedule_start","previous_scheduled","previous_dispatched"],"example":"schedule_start"},"offset_seconds":{"type":"integer","minimum":0,"example":0}}},"draft":{"type":"object","additionalProperties":false,"required":["parts"],"properties":{"version":{"type":"integer","enum":[1],"example":1},"schema_version":{"type":"integer","enum":[1],"example":1},"delay_ms":{"type":"integer","minimum":0,"maximum":300000,"example":0},"parts":{"type":"array","minItems":1,"maxItems":50,"items":{"type":"object","additionalProperties":false,"properties":{"content":{"type":"string","maxLength":150000,"example":"Olá, seu atendimento está marcado para amanhã."},"content_type":{"type":"string","enum":["text","input_select","sticker","poll"],"example":"text"},"content_attributes":{"type":"object","additionalProperties":false,"description":"Closed outbound metadata roots; rich provider objects remain JSON-shaped and are revalidated before dispatch.","properties":{"in_reply_to":{"type":"integer","example":88},"in_reply_to_external_id":{"type":"string","example":"wamid.example"},"items":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Provider-native option object."}},"email":{"type":"object","additionalProperties":true,"description":"Structured outbound e-mail metadata."},"interactive":{"type":"object","additionalProperties":true,"description":"WhatsApp Cloud interactive payload."},"wa_interactive":{"type":"object","additionalProperties":true,"description":"WazMeow interactive payload."},"poll":{"type":"object","additionalProperties":true,"description":"Poll payload."},"catalog_product":{"type":"object","additionalProperties":true,"description":"Catalog product payload."},"media_kind":{"type":"string","enum":["image","video","audio","document","sticker"],"example":"image"},"view_once":{"type":"boolean","example":false},"mention_all":{"type":"boolean","example":false},"mentioned_jids":{"type":"array","items":{"type":"string"},"example":[]},"mentions":{"type":"object","additionalProperties":true,"description":"Mention map keyed by provider identifier."},"is_forwarded":{"type":"boolean","example":false},"link_preview":{"type":"object","additionalProperties":true,"description":"Link preview metadata."},"location":{"type":"object","additionalProperties":true,"description":"Location payload."},"contact":{"type":"object","additionalProperties":true,"description":"Contact card payload."},"cta_buttons":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Call-to-action button."}}}},"attachments":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["signed_id"],"properties":{"signed_id":{"type":"string","description":"ActiveStorage signed blob id.","example":"eyJfcmFpbHMiOnsibWVzc2FnZSI6ImJsb2IifX0"},"filename":{"type":"string","example":"reminder.pdf"},"content_type":{"type":"string","example":"application/pdf"},"byte_size":{"type":"integer","minimum":0,"example":2048}}}},"items":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Structured select or poll option."}},"is_voice_message":{"type":"boolean","example":false},"email_html_content":{"type":"string","example":"\u003cp\u003eAppointment reminder\u003c/p\u003e"},"to_emails":{"type":"array","items":{"type":"string","format":"email"},"example":["customer@example.com"]},"cc_emails":{"type":"array","items":{"type":"string","format":"email"},"example":[]},"bcc_emails":{"type":"array","items":{"type":"string","format":"email"},"example":[]},"template_params":{"type":"object","additionalProperties":true,"description":"Approved template identity and parameters."},"flow_params":{"type":"object","additionalProperties":true,"description":"WhatsApp Flow identity and parameters."},"whatsapp_transport":{"type":"string","enum":["cloud","web"],"example":"cloud"}}}},"attachments":{"type":"array","description":"Union of the signed attachment references present in parts.","items":{"type":"object","additionalProperties":false,"required":["signed_id"],"properties":{"signed_id":{"type":"string","description":"ActiveStorage signed blob id.","example":"eyJfcmFpbHMiOnsibWVzc2FnZSI6ImJsb2IifX0"},"filename":{"type":"string","example":"reminder.pdf"},"content_type":{"type":"string","example":"application/pdf"},"byte_size":{"type":"integer","minimum":0,"example":2048}}}}}},"policy_overrides":{"type":"object","additionalProperties":false,"description":"Explicit schedule-level overrides; omitted leaves inherit from inbox/account.","properties":{"on_inbound_reply":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["continue","pause","cancel","skip"],"example":"pause"}}},"on_conversation_resolved":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["continue","pause","cancel","skip"],"example":"continue"}}},"misfire":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["skip","manual_review","send_latest","catch_up_bounded"],"example":"send_latest"},"grace_seconds":{"type":"integer","minimum":0,"example":60},"max_occurrences":{"type":"integer","minimum":1,"maximum":500,"example":10},"spacing_seconds":{"type":"integer","minimum":0,"example":5}}},"transient_failure":{"type":"object","additionalProperties":false,"properties":{"max_attempts":{"type":"integer","minimum":1,"maximum":10,"example":3},"backoff_seconds":{"type":"array","maxItems":9,"items":{"type":"integer","minimum":0,"maximum":86400},"example":[30,120]},"exhausted_action":{"type":"string","enum":["skip","pause","cancel","manual_review"],"example":"manual_review"}}},"permanent_failure":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["skip","pause","cancel","manual_review"],"example":"manual_review"}}},"resume_behavior":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["preserve_schedule","shift_by_pause","skip_missed","catch_up_bounded"],"example":"preserve_schedule"},"max_occurrences":{"type":"integer","minimum":1,"maximum":500,"example":10},"spacing_seconds":{"type":"integer","minimum":0,"example":5}}},"quiet_hours":{"type":"object","additionalProperties":false,"properties":{"enabled":{"type":"boolean","example":false},"start":{"type":"string","pattern":"^(?:[01][0-9]|2[0-3]):[0-5][0-9]$","example":"22:00"},"end":{"type":"string","pattern":"^(?:[01][0-9]|2[0-3]):[0-5][0-9]$","example":"08:00"},"days":{"type":"array","uniqueItems":true,"items":{"type":"integer","minimum":0,"maximum":6},"example":[0,1,2,3,4,5,6]},"action":{"type":"string","enum":["allow","defer","skip","manual_review"],"example":"defer"}}},"overlap":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["allow","skip_new","defer_new","cancel_previous","manual_review"],"example":"allow"},"defer_seconds":{"type":"integer","minimum":1,"example":60}}},"inbox_change":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["follow_logical","cancel","pause","manual_review"],"example":"follow_logical"}}},"sender":{"type":"object","additionalProperties":false,"properties":{"type":{"type":"string","enum":["assigned_agent","schedule_creator","user","agent_bot","system"],"example":"system"},"id":{"type":["integer","null"],"minimum":1,"example":null},"missing":{"type":"string","enum":["fail","system","assigned_agent"],"example":"fail"}}},"variables":{"type":"object","additionalProperties":false,"properties":{"resolve_at":{"type":"string","enum":["publication","dispatch"],"example":"dispatch"},"missing":{"type":"string","enum":["fail","blank","skip"],"example":"fail"}}},"dst":{"type":"object","additionalProperties":false,"properties":{"nonexistent":{"type":"string","enum":["skip","shift_forward","shift_backward"],"example":"shift_forward"},"ambiguous":{"type":"string","enum":["first","second","skip"],"example":"first"}}},"materialization":{"type":"object","additionalProperties":false,"properties":{"horizon_seconds":{"type":"integer","minimum":1,"maximum":2592000,"example":2592000},"max_occurrences":{"type":"integer","minimum":1,"maximum":500,"example":500}}},"claim":{"type":"object","additionalProperties":false,"properties":{"lease_seconds":{"type":"integer","minimum":1,"maximum":900,"example":120},"recovery_grace_seconds":{"type":"integer","minimum":0,"maximum":3600,"example":30}}}}},"attachments_count":{"type":"integer","minimum":0,"example":0},"lock_version":{"type":"integer","example":0}}}}}}]}}},"example":{"payload":{"id":701,"name":"Appointment reminder","status":"active","conversation_id":42,"kind":"one_time","timezone":"America/Sao_Paulo","starts_at":"2026-08-22T13:00:00.000Z","version_number":1,"items":[{"id":801,"stable_key":"2dc1f16c-5191-4b3b-97b4-8f33e93dc969","position":1,"timing":{"anchor":"schedule_start","offset_seconds":0},"draft":{"version":1,"schema_version":1,"delay_ms":0,"parts":[{"content":"Olá, seu atendimento está marcado para amanhã.","content_type":"text","content_attributes":{"in_reply_to":88,"in_reply_to_external_id":"wamid.example","items":[{}],"email":{},"interactive":{},"wa_interactive":{},"poll":{},"catalog_product":{},"media_kind":"image","view_once":false,"mention_all":false,"mentioned_jids":[],"mentions":{},"is_forwarded":false,"link_preview":{},"location":{},"contact":{},"cta_buttons":[{}]},"attachments":[{"signed_id":"eyJfcmFpbHMiOnsibWVzc2FnZSI6ImJsb2IifX0","filename":"reminder.pdf","content_type":"application/pdf","byte_size":2048}],"items":[{}],"is_voice_message":false,"email_html_content":"\u003cp\u003eAppointment reminder\u003c/p\u003e","to_emails":["customer@example.com"],"cc_emails":[],"bcc_emails":[],"template_params":{},"flow_params":{},"whatsapp_transport":"cloud"}],"attachments":[{"signed_id":"eyJfcmFpbHMiOnsibWVzc2FnZSI6ImJsb2IifX0","filename":"reminder.pdf","content_type":"application/pdf","byte_size":2048}]},"policy_overrides":{"on_inbound_reply":{"action":"pause"},"on_conversation_resolved":{"action":"continue"},"misfire":{"action":"send_latest","grace_seconds":60,"max_occurrences":10,"spacing_seconds":5},"transient_failure":{"max_attempts":3,"backoff_seconds":[30,120],"exhausted_action":"manual_review"},"permanent_failure":{"action":"manual_review"},"resume_behavior":{"action":"preserve_schedule","max_occurrences":10,"spacing_seconds":5},"quiet_hours":{"enabled":false,"start":"22:00","end":"08:00","days":[0,1,2,3,4,5,6],"action":"defer"},"overlap":{"action":"allow","defer_seconds":60},"inbox_change":{"action":"follow_logical"},"sender":{"type":"system","id":null,"missing":"fail"},"variables":{"resolve_at":"dispatch","missing":"fail"},"dst":{"nonexistent":"shift_forward","ambiguous":"first"},"materialization":{"horizon_seconds":2592000,"max_occurrences":500},"claim":{"lease_seconds":120,"recovery_grace_seconds":30}},"attachments_count":0,"lock_version":0}],"inbox_id":7,"contact_id":81,"created_by_id":9,"next_occurrence_at":"2026-08-22T13:00:00.000Z","materialized_through_at":"2026-08-22T13:00:00.000Z","published_at":"2026-08-21T16:00:00.000Z","paused_at":null,"needs_attention_at":null,"completed_at":null,"canceled_at":null,"archived_at":null,"lock_version":1,"created_at":"2026-08-21T16:00:00.000Z","updated_at":"2026-08-21T16:00:00.000Z","created_by":{"id":9,"name":"Ana Agent"},"rrule":null,"resolved_policies":{},"policy_sources":{},"sender_config":{},"target_config":{}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"409":{"description":"Stale lock version or schedule currently executing."},"422":{"description":"The schedule has ended (canceled, completed or archived) or the merged definition is invalid.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Error code plus optional details (the current status for schedule_not_editable, the blocker or validation list otherwise).","required":["error"],"properties":{"error":{"type":"string","example":"schedule_not_editable"}}},"example":{"error":"schedule_not_editable","details":"canceled"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"conversation_id":{"type":"integer","description":"Public display id of the existing target conversation.","example":42},"name":{"type":"string","maxLength":255,"example":"Appointment reminder"},"kind":{"type":"string","enum":["one_time","sequence","recurring_single","recurring_sequence"],"example":"one_time","description":"Temporal shape of the scheduled message plan."},"starts_at":{"type":"string","format":"date-time","description":"First civil occurrence represented as an ISO-8601 instant.","example":"2026-08-22T13:00:00.000Z"},"timezone":{"type":"string","description":"IANA timezone used for recurrence and DST decisions. When omitted or blank it inherits the effective scheduling timezone of the conversation inbox (inbox setting, then account setting, then the account timezone, then UTC); an explicit invalid value is rejected with invalid_timezone. On update a blank value keeps the published timezone.","example":"America/Sao_Paulo"},"recurrence":{"type":["object","null"],"additionalProperties":false,"description":"Required only for recurring kinds; COUNT/UNTIL stays outside rrule.","properties":{"rrule":{"type":"string","description":"RFC 5545 recurrence body without RRULE prefix, COUNT or UNTIL.","example":"FREQ=WEEKLY;INTERVAL=1;BYDAY=MO,WE"},"end_mode":{"type":"string","enum":["never","until","count"],"example":"count"},"until":{"type":["string","null"],"format":"date-time","example":null},"count":{"type":["integer","null"],"minimum":1,"maximum":10000,"example":8}}},"policies":{"type":"object","additionalProperties":false,"description":"Explicit schedule-level overrides; omitted leaves inherit from inbox/account.","properties":{"on_inbound_reply":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["continue","pause","cancel","skip"],"example":"pause"}}},"on_conversation_resolved":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["continue","pause","cancel","skip"],"example":"continue"}}},"misfire":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["skip","manual_review","send_latest","catch_up_bounded"],"example":"send_latest"},"grace_seconds":{"type":"integer","minimum":0,"example":60},"max_occurrences":{"type":"integer","minimum":1,"maximum":500,"example":10},"spacing_seconds":{"type":"integer","minimum":0,"example":5}}},"transient_failure":{"type":"object","additionalProperties":false,"properties":{"max_attempts":{"type":"integer","minimum":1,"maximum":10,"example":3},"backoff_seconds":{"type":"array","maxItems":9,"items":{"type":"integer","minimum":0,"maximum":86400},"example":[30,120]},"exhausted_action":{"type":"string","enum":["skip","pause","cancel","manual_review"],"example":"manual_review"}}},"permanent_failure":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["skip","pause","cancel","manual_review"],"example":"manual_review"}}},"resume_behavior":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["preserve_schedule","shift_by_pause","skip_missed","catch_up_bounded"],"example":"preserve_schedule"},"max_occurrences":{"type":"integer","minimum":1,"maximum":500,"example":10},"spacing_seconds":{"type":"integer","minimum":0,"example":5}}},"quiet_hours":{"type":"object","additionalProperties":false,"properties":{"enabled":{"type":"boolean","example":false},"start":{"type":"string","pattern":"^(?:[01][0-9]|2[0-3]):[0-5][0-9]$","example":"22:00"},"end":{"type":"string","pattern":"^(?:[01][0-9]|2[0-3]):[0-5][0-9]$","example":"08:00"},"days":{"type":"array","uniqueItems":true,"items":{"type":"integer","minimum":0,"maximum":6},"example":[0,1,2,3,4,5,6]},"action":{"type":"string","enum":["allow","defer","skip","manual_review"],"example":"defer"}}},"overlap":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["allow","skip_new","defer_new","cancel_previous","manual_review"],"example":"allow"},"defer_seconds":{"type":"integer","minimum":1,"example":60}}},"inbox_change":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["follow_logical","cancel","pause","manual_review"],"example":"follow_logical"}}},"sender":{"type":"object","additionalProperties":false,"properties":{"type":{"type":"string","enum":["assigned_agent","schedule_creator","user","agent_bot","system"],"example":"system"},"id":{"type":["integer","null"],"minimum":1,"example":null},"missing":{"type":"string","enum":["fail","system","assigned_agent"],"example":"fail"}}},"variables":{"type":"object","additionalProperties":false,"properties":{"resolve_at":{"type":"string","enum":["publication","dispatch"],"example":"dispatch"},"missing":{"type":"string","enum":["fail","blank","skip"],"example":"fail"}}},"dst":{"type":"object","additionalProperties":false,"properties":{"nonexistent":{"type":"string","enum":["skip","shift_forward","shift_backward"],"example":"shift_forward"},"ambiguous":{"type":"string","enum":["first","second","skip"],"example":"first"}}},"materialization":{"type":"object","additionalProperties":false,"properties":{"horizon_seconds":{"type":"integer","minimum":1,"maximum":2592000,"example":2592000},"max_occurrences":{"type":"integer","minimum":1,"maximum":500,"example":500}}},"claim":{"type":"object","additionalProperties":false,"properties":{"lease_seconds":{"type":"integer","minimum":1,"maximum":900,"example":120},"recovery_grace_seconds":{"type":"integer","minimum":0,"maximum":3600,"example":30}}}}},"source_message_id":{"type":"integer","description":"Existing outgoing message to clone server-side; mutually exclusive with items.","example":91},"items":{"type":"array","minItems":1,"maxItems":500,"items":{"type":"object","additionalProperties":false,"required":["client_id","position","timing","draft"],"properties":{"client_id":{"type":"string","minLength":1,"example":"item-1"},"position":{"type":"integer","minimum":1,"example":1},"timing":{"type":"object","additionalProperties":false,"required":["anchor","offset_seconds"],"properties":{"anchor":{"type":"string","enum":["schedule_start","previous_scheduled","previous_dispatched"],"example":"schedule_start"},"offset_seconds":{"type":"integer","minimum":0,"example":0}}},"draft":{"type":"object","additionalProperties":false,"required":["parts"],"properties":{"version":{"type":"integer","enum":[1],"example":1},"schema_version":{"type":"integer","enum":[1],"example":1},"delay_ms":{"type":"integer","minimum":0,"maximum":300000,"example":0},"parts":{"type":"array","minItems":1,"maxItems":50,"items":{"type":"object","additionalProperties":false,"properties":{"content":{"type":"string","maxLength":150000,"example":"Olá, seu atendimento está marcado para amanhã."},"content_type":{"type":"string","enum":["text","input_select","sticker","poll"],"example":"text"},"content_attributes":{"type":"object","additionalProperties":false,"description":"Closed outbound metadata roots; rich provider objects remain JSON-shaped and are revalidated before dispatch.","properties":{"in_reply_to":{"type":"integer","example":88},"in_reply_to_external_id":{"type":"string","example":"wamid.example"},"items":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Provider-native option object."}},"email":{"type":"object","additionalProperties":true,"description":"Structured outbound e-mail metadata."},"interactive":{"type":"object","additionalProperties":true,"description":"WhatsApp Cloud interactive payload."},"wa_interactive":{"type":"object","additionalProperties":true,"description":"WazMeow interactive payload."},"poll":{"type":"object","additionalProperties":true,"description":"Poll payload."},"catalog_product":{"type":"object","additionalProperties":true,"description":"Catalog product payload."},"media_kind":{"type":"string","enum":["image","video","audio","document","sticker"],"example":"image"},"view_once":{"type":"boolean","example":false},"mention_all":{"type":"boolean","example":false},"mentioned_jids":{"type":"array","items":{"type":"string"},"example":[]},"mentions":{"type":"object","additionalProperties":true,"description":"Mention map keyed by provider identifier."},"is_forwarded":{"type":"boolean","example":false},"link_preview":{"type":"object","additionalProperties":true,"description":"Link preview metadata."},"location":{"type":"object","additionalProperties":true,"description":"Location payload."},"contact":{"type":"object","additionalProperties":true,"description":"Contact card payload."},"cta_buttons":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Call-to-action button."}}}},"attachments":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["signed_id"],"properties":{"signed_id":{"type":"string","description":"ActiveStorage signed blob id.","example":"eyJfcmFpbHMiOnsibWVzc2FnZSI6ImJsb2IifX0"},"filename":{"type":"string","example":"reminder.pdf"},"content_type":{"type":"string","example":"application/pdf"},"byte_size":{"type":"integer","minimum":0,"example":2048}}}},"items":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Structured select or poll option."}},"is_voice_message":{"type":"boolean","example":false},"email_html_content":{"type":"string","example":"\u003cp\u003eAppointment reminder\u003c/p\u003e"},"to_emails":{"type":"array","items":{"type":"string","format":"email"},"example":["customer@example.com"]},"cc_emails":{"type":"array","items":{"type":"string","format":"email"},"example":[]},"bcc_emails":{"type":"array","items":{"type":"string","format":"email"},"example":[]},"template_params":{"type":"object","additionalProperties":true,"description":"Approved template identity and parameters."},"flow_params":{"type":"object","additionalProperties":true,"description":"WhatsApp Flow identity and parameters."},"whatsapp_transport":{"type":"string","enum":["cloud","web"],"example":"cloud"}}}},"attachments":{"type":"array","description":"Union of the signed attachment references present in parts.","items":{"type":"object","additionalProperties":false,"required":["signed_id"],"properties":{"signed_id":{"type":"string","description":"ActiveStorage signed blob id.","example":"eyJfcmFpbHMiOnsibWVzc2FnZSI6ImJsb2IifX0"},"filename":{"type":"string","example":"reminder.pdf"},"content_type":{"type":"string","example":"application/pdf"},"byte_size":{"type":"integer","minimum":0,"example":2048}}}}}},"policy_overrides":{"type":"object","additionalProperties":false,"description":"Explicit schedule-level overrides; omitted leaves inherit from inbox/account.","properties":{"on_inbound_reply":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["continue","pause","cancel","skip"],"example":"pause"}}},"on_conversation_resolved":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["continue","pause","cancel","skip"],"example":"continue"}}},"misfire":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["skip","manual_review","send_latest","catch_up_bounded"],"example":"send_latest"},"grace_seconds":{"type":"integer","minimum":0,"example":60},"max_occurrences":{"type":"integer","minimum":1,"maximum":500,"example":10},"spacing_seconds":{"type":"integer","minimum":0,"example":5}}},"transient_failure":{"type":"object","additionalProperties":false,"properties":{"max_attempts":{"type":"integer","minimum":1,"maximum":10,"example":3},"backoff_seconds":{"type":"array","maxItems":9,"items":{"type":"integer","minimum":0,"maximum":86400},"example":[30,120]},"exhausted_action":{"type":"string","enum":["skip","pause","cancel","manual_review"],"example":"manual_review"}}},"permanent_failure":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["skip","pause","cancel","manual_review"],"example":"manual_review"}}},"resume_behavior":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["preserve_schedule","shift_by_pause","skip_missed","catch_up_bounded"],"example":"preserve_schedule"},"max_occurrences":{"type":"integer","minimum":1,"maximum":500,"example":10},"spacing_seconds":{"type":"integer","minimum":0,"example":5}}},"quiet_hours":{"type":"object","additionalProperties":false,"properties":{"enabled":{"type":"boolean","example":false},"start":{"type":"string","pattern":"^(?:[01][0-9]|2[0-3]):[0-5][0-9]$","example":"22:00"},"end":{"type":"string","pattern":"^(?:[01][0-9]|2[0-3]):[0-5][0-9]$","example":"08:00"},"days":{"type":"array","uniqueItems":true,"items":{"type":"integer","minimum":0,"maximum":6},"example":[0,1,2,3,4,5,6]},"action":{"type":"string","enum":["allow","defer","skip","manual_review"],"example":"defer"}}},"overlap":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["allow","skip_new","defer_new","cancel_previous","manual_review"],"example":"allow"},"defer_seconds":{"type":"integer","minimum":1,"example":60}}},"inbox_change":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["follow_logical","cancel","pause","manual_review"],"example":"follow_logical"}}},"sender":{"type":"object","additionalProperties":false,"properties":{"type":{"type":"string","enum":["assigned_agent","schedule_creator","user","agent_bot","system"],"example":"system"},"id":{"type":["integer","null"],"minimum":1,"example":null},"missing":{"type":"string","enum":["fail","system","assigned_agent"],"example":"fail"}}},"variables":{"type":"object","additionalProperties":false,"properties":{"resolve_at":{"type":"string","enum":["publication","dispatch"],"example":"dispatch"},"missing":{"type":"string","enum":["fail","blank","skip"],"example":"fail"}}},"dst":{"type":"object","additionalProperties":false,"properties":{"nonexistent":{"type":"string","enum":["skip","shift_forward","shift_backward"],"example":"shift_forward"},"ambiguous":{"type":"string","enum":["first","second","skip"],"example":"first"}}},"materialization":{"type":"object","additionalProperties":false,"properties":{"horizon_seconds":{"type":"integer","minimum":1,"maximum":2592000,"example":2592000},"max_occurrences":{"type":"integer","minimum":1,"maximum":500,"example":500}}},"claim":{"type":"object","additionalProperties":false,"properties":{"lease_seconds":{"type":"integer","minimum":1,"maximum":900,"example":120},"recovery_grace_seconds":{"type":"integer","minimum":0,"maximum":3600,"example":30}}}}}}}},"lock_version":{"type":"integer","minimum":0,"example":1}},"required":["lock_version"]},"example":{"lock_version":1,"name":"Updated appointment reminder","starts_at":"2026-08-22T14:00:00.000Z","conversation_id":42,"kind":"one_time","timezone":"America/Sao_Paulo","recurrence":{"rrule":"FREQ=WEEKLY;INTERVAL=1;BYDAY=MO,WE","end_mode":"count","until":null,"count":8},"policies":{"on_inbound_reply":{"action":"pause"},"on_conversation_resolved":{"action":"continue"},"misfire":{"action":"send_latest","grace_seconds":60,"max_occurrences":10,"spacing_seconds":5},"transient_failure":{"max_attempts":3,"backoff_seconds":[30,120],"exhausted_action":"manual_review"},"permanent_failure":{"action":"manual_review"},"resume_behavior":{"action":"preserve_schedule","max_occurrences":10,"spacing_seconds":5},"quiet_hours":{"enabled":false,"start":"22:00","end":"08:00","days":[0,1,2,3,4,5,6],"action":"defer"},"overlap":{"action":"allow","defer_seconds":60},"inbox_change":{"action":"follow_logical"},"sender":{"type":"system","id":null,"missing":"fail"},"variables":{"resolve_at":"dispatch","missing":"fail"},"dst":{"nonexistent":"shift_forward","ambiguous":"first"},"materialization":{"horizon_seconds":2592000,"max_occurrences":500},"claim":{"lease_seconds":120,"recovery_grace_seconds":30}},"source_message_id":91,"items":[{"client_id":"item-1","position":1,"timing":{"anchor":"schedule_start","offset_seconds":0},"draft":{"version":1,"schema_version":1,"delay_ms":0,"parts":[{"content":"Olá, seu atendimento está marcado para amanhã.","content_type":"text","content_attributes":{"in_reply_to":88,"in_reply_to_external_id":"wamid.example","items":[{}],"email":{},"interactive":{},"wa_interactive":{},"poll":{},"catalog_product":{},"media_kind":"image","view_once":false,"mention_all":false,"mentioned_jids":[],"mentions":{},"is_forwarded":false,"link_preview":{},"location":{},"contact":{},"cta_buttons":[{}]},"attachments":[{"signed_id":"eyJfcmFpbHMiOnsibWVzc2FnZSI6ImJsb2IifX0","filename":"reminder.pdf","content_type":"application/pdf","byte_size":2048}],"items":[{}],"is_voice_message":false,"email_html_content":"\u003cp\u003eAppointment reminder\u003c/p\u003e","to_emails":["customer@example.com"],"cc_emails":[],"bcc_emails":[],"template_params":{},"flow_params":{},"whatsapp_transport":"cloud"}],"attachments":[{"signed_id":"eyJfcmFpbHMiOnsibWVzc2FnZSI6ImJsb2IifX0","filename":"reminder.pdf","content_type":"application/pdf","byte_size":2048}]},"policy_overrides":{"on_inbound_reply":{"action":"pause"},"on_conversation_resolved":{"action":"continue"},"misfire":{"action":"send_latest","grace_seconds":60,"max_occurrences":10,"spacing_seconds":5},"transient_failure":{"max_attempts":3,"backoff_seconds":[30,120],"exhausted_action":"manual_review"},"permanent_failure":{"action":"manual_review"},"resume_behavior":{"action":"preserve_schedule","max_occurrences":10,"spacing_seconds":5},"quiet_hours":{"enabled":false,"start":"22:00","end":"08:00","days":[0,1,2,3,4,5,6],"action":"defer"},"overlap":{"action":"allow","defer_seconds":60},"inbox_change":{"action":"follow_logical"},"sender":{"type":"system","id":null,"missing":"fail"},"variables":{"resolve_at":"dispatch","missing":"fail"},"dst":{"nonexistent":"shift_forward","ambiguous":"first"},"materialization":{"horizon_seconds":2592000,"max_occurrences":500},"claim":{"lease_seconds":120,"recovery_grace_seconds":30}}}]}}}}}},"/api/v1/accounts/{account_id}/message_scheduling/settings":{"get":{"tags":["Message Scheduling"],"operationId":"auto_get_api_v1_accounts_account_id_message_scheduling_settings","summary":"Get effective message scheduling policies","description":"Returns the raw account or inbox override and the fully resolved policy with source attribution.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Raw setting and effective policy for the requested scope.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","additionalProperties":false,"properties":{"setting":{"type":"object","additionalProperties":false,"properties":{"id":{"type":["integer","null"],"example":61},"inbox_id":{"type":["integer","null"],"example":null},"timezone":{"type":["string","null"],"example":"America/Sao_Paulo"},"policy_template":{"type":"object","additionalProperties":false,"description":"Explicit schedule-level overrides; omitted leaves inherit from inbox/account.","properties":{"on_inbound_reply":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["continue","pause","cancel","skip"],"example":"pause"}}},"on_conversation_resolved":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["continue","pause","cancel","skip"],"example":"continue"}}},"misfire":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["skip","manual_review","send_latest","catch_up_bounded"],"example":"send_latest"},"grace_seconds":{"type":"integer","minimum":0,"example":60},"max_occurrences":{"type":"integer","minimum":1,"maximum":500,"example":10},"spacing_seconds":{"type":"integer","minimum":0,"example":5}}},"transient_failure":{"type":"object","additionalProperties":false,"properties":{"max_attempts":{"type":"integer","minimum":1,"maximum":10,"example":3},"backoff_seconds":{"type":"array","maxItems":9,"items":{"type":"integer","minimum":0,"maximum":86400},"example":[30,120]},"exhausted_action":{"type":"string","enum":["skip","pause","cancel","manual_review"],"example":"manual_review"}}},"permanent_failure":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["skip","pause","cancel","manual_review"],"example":"manual_review"}}},"resume_behavior":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["preserve_schedule","shift_by_pause","skip_missed","catch_up_bounded"],"example":"preserve_schedule"},"max_occurrences":{"type":"integer","minimum":1,"maximum":500,"example":10},"spacing_seconds":{"type":"integer","minimum":0,"example":5}}},"quiet_hours":{"type":"object","additionalProperties":false,"properties":{"enabled":{"type":"boolean","example":false},"start":{"type":"string","pattern":"^(?:[01][0-9]|2[0-3]):[0-5][0-9]$","example":"22:00"},"end":{"type":"string","pattern":"^(?:[01][0-9]|2[0-3]):[0-5][0-9]$","example":"08:00"},"days":{"type":"array","uniqueItems":true,"items":{"type":"integer","minimum":0,"maximum":6},"example":[0,1,2,3,4,5,6]},"action":{"type":"string","enum":["allow","defer","skip","manual_review"],"example":"defer"}}},"overlap":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["allow","skip_new","defer_new","cancel_previous","manual_review"],"example":"allow"},"defer_seconds":{"type":"integer","minimum":1,"example":60}}},"inbox_change":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["follow_logical","cancel","pause","manual_review"],"example":"follow_logical"}}},"sender":{"type":"object","additionalProperties":false,"properties":{"type":{"type":"string","enum":["assigned_agent","schedule_creator","user","agent_bot","system"],"example":"system"},"id":{"type":["integer","null"],"minimum":1,"example":null},"missing":{"type":"string","enum":["fail","system","assigned_agent"],"example":"fail"}}},"variables":{"type":"object","additionalProperties":false,"properties":{"resolve_at":{"type":"string","enum":["publication","dispatch"],"example":"dispatch"},"missing":{"type":"string","enum":["fail","blank","skip"],"example":"fail"}}},"dst":{"type":"object","additionalProperties":false,"properties":{"nonexistent":{"type":"string","enum":["skip","shift_forward","shift_backward"],"example":"shift_forward"},"ambiguous":{"type":"string","enum":["first","second","skip"],"example":"first"}}},"materialization":{"type":"object","additionalProperties":false,"properties":{"horizon_seconds":{"type":"integer","minimum":1,"maximum":2592000,"example":2592000},"max_occurrences":{"type":"integer","minimum":1,"maximum":500,"example":500}}},"claim":{"type":"object","additionalProperties":false,"properties":{"lease_seconds":{"type":"integer","minimum":1,"maximum":900,"example":120},"recovery_grace_seconds":{"type":"integer","minimum":0,"maximum":3600,"example":30}}}}},"configured_at":{"type":["string","null"],"format":"date-time","example":"2026-08-21T16:00:00.000Z"},"configured_by_id":{"type":["integer","null"],"example":9},"lock_version":{"type":"integer","minimum":0,"example":0}}},"resolved_policies":{"type":"object","additionalProperties":false,"properties":{"policy":{"type":"object","additionalProperties":false,"description":"Explicit schedule-level overrides; omitted leaves inherit from inbox/account.","properties":{"on_inbound_reply":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["continue","pause","cancel","skip"],"example":"pause"}}},"on_conversation_resolved":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["continue","pause","cancel","skip"],"example":"continue"}}},"misfire":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["skip","manual_review","send_latest","catch_up_bounded"],"example":"send_latest"},"grace_seconds":{"type":"integer","minimum":0,"example":60},"max_occurrences":{"type":"integer","minimum":1,"maximum":500,"example":10},"spacing_seconds":{"type":"integer","minimum":0,"example":5}}},"transient_failure":{"type":"object","additionalProperties":false,"properties":{"max_attempts":{"type":"integer","minimum":1,"maximum":10,"example":3},"backoff_seconds":{"type":"array","maxItems":9,"items":{"type":"integer","minimum":0,"maximum":86400},"example":[30,120]},"exhausted_action":{"type":"string","enum":["skip","pause","cancel","manual_review"],"example":"manual_review"}}},"permanent_failure":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["skip","pause","cancel","manual_review"],"example":"manual_review"}}},"resume_behavior":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["preserve_schedule","shift_by_pause","skip_missed","catch_up_bounded"],"example":"preserve_schedule"},"max_occurrences":{"type":"integer","minimum":1,"maximum":500,"example":10},"spacing_seconds":{"type":"integer","minimum":0,"example":5}}},"quiet_hours":{"type":"object","additionalProperties":false,"properties":{"enabled":{"type":"boolean","example":false},"start":{"type":"string","pattern":"^(?:[01][0-9]|2[0-3]):[0-5][0-9]$","example":"22:00"},"end":{"type":"string","pattern":"^(?:[01][0-9]|2[0-3]):[0-5][0-9]$","example":"08:00"},"days":{"type":"array","uniqueItems":true,"items":{"type":"integer","minimum":0,"maximum":6},"example":[0,1,2,3,4,5,6]},"action":{"type":"string","enum":["allow","defer","skip","manual_review"],"example":"defer"}}},"overlap":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["allow","skip_new","defer_new","cancel_previous","manual_review"],"example":"allow"},"defer_seconds":{"type":"integer","minimum":1,"example":60}}},"inbox_change":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["follow_logical","cancel","pause","manual_review"],"example":"follow_logical"}}},"sender":{"type":"object","additionalProperties":false,"properties":{"type":{"type":"string","enum":["assigned_agent","schedule_creator","user","agent_bot","system"],"example":"system"},"id":{"type":["integer","null"],"minimum":1,"example":null},"missing":{"type":"string","enum":["fail","system","assigned_agent"],"example":"fail"}}},"variables":{"type":"object","additionalProperties":false,"properties":{"resolve_at":{"type":"string","enum":["publication","dispatch"],"example":"dispatch"},"missing":{"type":"string","enum":["fail","blank","skip"],"example":"fail"}}},"dst":{"type":"object","additionalProperties":false,"properties":{"nonexistent":{"type":"string","enum":["skip","shift_forward","shift_backward"],"example":"shift_forward"},"ambiguous":{"type":"string","enum":["first","second","skip"],"example":"first"}}},"materialization":{"type":"object","additionalProperties":false,"properties":{"horizon_seconds":{"type":"integer","minimum":1,"maximum":2592000,"example":2592000},"max_occurrences":{"type":"integer","minimum":1,"maximum":500,"example":500}}},"claim":{"type":"object","additionalProperties":false,"properties":{"lease_seconds":{"type":"integer","minimum":1,"maximum":900,"example":120},"recovery_grace_seconds":{"type":"integer","minimum":0,"maximum":3600,"example":30}}}}},"sources":{"type":"object","additionalProperties":{"type":"string"},"description":"Effective source keyed by policy path."},"fields":{"type":"object","additionalProperties":{"type":"object","additionalProperties":false,"properties":{"value":{"description":"Resolved scalar, null or integer-array policy value.","oneOf":[{"type":"string"},{"type":"integer"},{"type":"boolean"},{"type":"null"},{"type":"array","items":{"type":"integer"}}]},"source":{"type":["string","null"],"example":"account"}}},"description":"Resolved value and source keyed by policy path."}}},"effective_timezone":{"type":"string","description":"Timezone a new schedule in this scope starts from: the inbox setting, then the account setting, then the account timezone, then UTC. Never null.","example":"America/Sao_Paulo"},"inherited_timezone":{"type":"string","description":"Timezone an inbox without its own inherits: the account setting, then the account timezone, then UTC. Always an IANA identifier.","example":"America/Sao_Paulo"}}}}},"example":{"payload":{"setting":{"id":61,"inbox_id":null,"timezone":"America/Sao_Paulo","policy_template":{"on_inbound_reply":{"action":"pause"},"on_conversation_resolved":{"action":"continue"},"misfire":{"action":"send_latest","grace_seconds":60,"max_occurrences":10,"spacing_seconds":5},"transient_failure":{"max_attempts":3,"backoff_seconds":[30,120],"exhausted_action":"manual_review"},"permanent_failure":{"action":"manual_review"},"resume_behavior":{"action":"preserve_schedule","max_occurrences":10,"spacing_seconds":5},"quiet_hours":{"enabled":false,"start":"22:00","end":"08:00","days":[0,1,2,3,4,5,6],"action":"defer"},"overlap":{"action":"allow","defer_seconds":60},"inbox_change":{"action":"follow_logical"},"sender":{"type":"system","id":null,"missing":"fail"},"variables":{"resolve_at":"dispatch","missing":"fail"},"dst":{"nonexistent":"shift_forward","ambiguous":"first"},"materialization":{"horizon_seconds":2592000,"max_occurrences":500},"claim":{"lease_seconds":120,"recovery_grace_seconds":30}},"lock_version":0,"configured_at":"2026-08-21T16:00:00.000Z","configured_by_id":9},"resolved_policies":{"policy":{"on_inbound_reply":{"action":"pause"},"on_conversation_resolved":{"action":"continue"},"misfire":{"action":"send_latest","grace_seconds":60,"max_occurrences":10,"spacing_seconds":5},"transient_failure":{"max_attempts":3,"backoff_seconds":[30,120],"exhausted_action":"manual_review"},"permanent_failure":{"action":"manual_review"},"resume_behavior":{"action":"preserve_schedule","max_occurrences":10,"spacing_seconds":5},"quiet_hours":{"enabled":false,"start":"22:00","end":"08:00","days":[0,1,2,3,4,5,6],"action":"defer"},"overlap":{"action":"allow","defer_seconds":60},"inbox_change":{"action":"follow_logical"},"sender":{"type":"system","id":null,"missing":"fail"},"variables":{"resolve_at":"dispatch","missing":"fail"},"dst":{"nonexistent":"shift_forward","ambiguous":"first"},"materialization":{"horizon_seconds":2592000,"max_occurrences":500},"claim":{"lease_seconds":120,"recovery_grace_seconds":30}},"sources":{},"fields":{}},"effective_timezone":"America/Sao_Paulo","inherited_timezone":"America/Sao_Paulo"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]},"patch":{"tags":["Message Scheduling"],"operationId":"auto_patch_api_v1_accounts_account_id_message_scheduling_settings","summary":"Update account or inbox scheduling policies","description":"Account scope requires every policy leaf. Inbox scope may contain only explicit overrides and inherits the remaining values. Optimistic locking prevents overwriting a concurrent edit.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Raw setting and effective policy for the requested scope.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","additionalProperties":false,"properties":{"setting":{"type":"object","additionalProperties":false,"properties":{"id":{"type":["integer","null"],"example":61},"inbox_id":{"type":["integer","null"],"example":null},"timezone":{"type":["string","null"],"example":"America/Sao_Paulo"},"policy_template":{"type":"object","additionalProperties":false,"description":"Explicit schedule-level overrides; omitted leaves inherit from inbox/account.","properties":{"on_inbound_reply":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["continue","pause","cancel","skip"],"example":"pause"}}},"on_conversation_resolved":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["continue","pause","cancel","skip"],"example":"continue"}}},"misfire":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["skip","manual_review","send_latest","catch_up_bounded"],"example":"send_latest"},"grace_seconds":{"type":"integer","minimum":0,"example":60},"max_occurrences":{"type":"integer","minimum":1,"maximum":500,"example":10},"spacing_seconds":{"type":"integer","minimum":0,"example":5}}},"transient_failure":{"type":"object","additionalProperties":false,"properties":{"max_attempts":{"type":"integer","minimum":1,"maximum":10,"example":3},"backoff_seconds":{"type":"array","maxItems":9,"items":{"type":"integer","minimum":0,"maximum":86400},"example":[30,120]},"exhausted_action":{"type":"string","enum":["skip","pause","cancel","manual_review"],"example":"manual_review"}}},"permanent_failure":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["skip","pause","cancel","manual_review"],"example":"manual_review"}}},"resume_behavior":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["preserve_schedule","shift_by_pause","skip_missed","catch_up_bounded"],"example":"preserve_schedule"},"max_occurrences":{"type":"integer","minimum":1,"maximum":500,"example":10},"spacing_seconds":{"type":"integer","minimum":0,"example":5}}},"quiet_hours":{"type":"object","additionalProperties":false,"properties":{"enabled":{"type":"boolean","example":false},"start":{"type":"string","pattern":"^(?:[01][0-9]|2[0-3]):[0-5][0-9]$","example":"22:00"},"end":{"type":"string","pattern":"^(?:[01][0-9]|2[0-3]):[0-5][0-9]$","example":"08:00"},"days":{"type":"array","uniqueItems":true,"items":{"type":"integer","minimum":0,"maximum":6},"example":[0,1,2,3,4,5,6]},"action":{"type":"string","enum":["allow","defer","skip","manual_review"],"example":"defer"}}},"overlap":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["allow","skip_new","defer_new","cancel_previous","manual_review"],"example":"allow"},"defer_seconds":{"type":"integer","minimum":1,"example":60}}},"inbox_change":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["follow_logical","cancel","pause","manual_review"],"example":"follow_logical"}}},"sender":{"type":"object","additionalProperties":false,"properties":{"type":{"type":"string","enum":["assigned_agent","schedule_creator","user","agent_bot","system"],"example":"system"},"id":{"type":["integer","null"],"minimum":1,"example":null},"missing":{"type":"string","enum":["fail","system","assigned_agent"],"example":"fail"}}},"variables":{"type":"object","additionalProperties":false,"properties":{"resolve_at":{"type":"string","enum":["publication","dispatch"],"example":"dispatch"},"missing":{"type":"string","enum":["fail","blank","skip"],"example":"fail"}}},"dst":{"type":"object","additionalProperties":false,"properties":{"nonexistent":{"type":"string","enum":["skip","shift_forward","shift_backward"],"example":"shift_forward"},"ambiguous":{"type":"string","enum":["first","second","skip"],"example":"first"}}},"materialization":{"type":"object","additionalProperties":false,"properties":{"horizon_seconds":{"type":"integer","minimum":1,"maximum":2592000,"example":2592000},"max_occurrences":{"type":"integer","minimum":1,"maximum":500,"example":500}}},"claim":{"type":"object","additionalProperties":false,"properties":{"lease_seconds":{"type":"integer","minimum":1,"maximum":900,"example":120},"recovery_grace_seconds":{"type":"integer","minimum":0,"maximum":3600,"example":30}}}}},"configured_at":{"type":["string","null"],"format":"date-time","example":"2026-08-21T16:00:00.000Z"},"configured_by_id":{"type":["integer","null"],"example":9},"lock_version":{"type":"integer","minimum":0,"example":0}}},"resolved_policies":{"type":"object","additionalProperties":false,"properties":{"policy":{"type":"object","additionalProperties":false,"description":"Explicit schedule-level overrides; omitted leaves inherit from inbox/account.","properties":{"on_inbound_reply":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["continue","pause","cancel","skip"],"example":"pause"}}},"on_conversation_resolved":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["continue","pause","cancel","skip"],"example":"continue"}}},"misfire":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["skip","manual_review","send_latest","catch_up_bounded"],"example":"send_latest"},"grace_seconds":{"type":"integer","minimum":0,"example":60},"max_occurrences":{"type":"integer","minimum":1,"maximum":500,"example":10},"spacing_seconds":{"type":"integer","minimum":0,"example":5}}},"transient_failure":{"type":"object","additionalProperties":false,"properties":{"max_attempts":{"type":"integer","minimum":1,"maximum":10,"example":3},"backoff_seconds":{"type":"array","maxItems":9,"items":{"type":"integer","minimum":0,"maximum":86400},"example":[30,120]},"exhausted_action":{"type":"string","enum":["skip","pause","cancel","manual_review"],"example":"manual_review"}}},"permanent_failure":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["skip","pause","cancel","manual_review"],"example":"manual_review"}}},"resume_behavior":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["preserve_schedule","shift_by_pause","skip_missed","catch_up_bounded"],"example":"preserve_schedule"},"max_occurrences":{"type":"integer","minimum":1,"maximum":500,"example":10},"spacing_seconds":{"type":"integer","minimum":0,"example":5}}},"quiet_hours":{"type":"object","additionalProperties":false,"properties":{"enabled":{"type":"boolean","example":false},"start":{"type":"string","pattern":"^(?:[01][0-9]|2[0-3]):[0-5][0-9]$","example":"22:00"},"end":{"type":"string","pattern":"^(?:[01][0-9]|2[0-3]):[0-5][0-9]$","example":"08:00"},"days":{"type":"array","uniqueItems":true,"items":{"type":"integer","minimum":0,"maximum":6},"example":[0,1,2,3,4,5,6]},"action":{"type":"string","enum":["allow","defer","skip","manual_review"],"example":"defer"}}},"overlap":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["allow","skip_new","defer_new","cancel_previous","manual_review"],"example":"allow"},"defer_seconds":{"type":"integer","minimum":1,"example":60}}},"inbox_change":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["follow_logical","cancel","pause","manual_review"],"example":"follow_logical"}}},"sender":{"type":"object","additionalProperties":false,"properties":{"type":{"type":"string","enum":["assigned_agent","schedule_creator","user","agent_bot","system"],"example":"system"},"id":{"type":["integer","null"],"minimum":1,"example":null},"missing":{"type":"string","enum":["fail","system","assigned_agent"],"example":"fail"}}},"variables":{"type":"object","additionalProperties":false,"properties":{"resolve_at":{"type":"string","enum":["publication","dispatch"],"example":"dispatch"},"missing":{"type":"string","enum":["fail","blank","skip"],"example":"fail"}}},"dst":{"type":"object","additionalProperties":false,"properties":{"nonexistent":{"type":"string","enum":["skip","shift_forward","shift_backward"],"example":"shift_forward"},"ambiguous":{"type":"string","enum":["first","second","skip"],"example":"first"}}},"materialization":{"type":"object","additionalProperties":false,"properties":{"horizon_seconds":{"type":"integer","minimum":1,"maximum":2592000,"example":2592000},"max_occurrences":{"type":"integer","minimum":1,"maximum":500,"example":500}}},"claim":{"type":"object","additionalProperties":false,"properties":{"lease_seconds":{"type":"integer","minimum":1,"maximum":900,"example":120},"recovery_grace_seconds":{"type":"integer","minimum":0,"maximum":3600,"example":30}}}}},"sources":{"type":"object","additionalProperties":{"type":"string"},"description":"Effective source keyed by policy path."},"fields":{"type":"object","additionalProperties":{"type":"object","additionalProperties":false,"properties":{"value":{"description":"Resolved scalar, null or integer-array policy value.","oneOf":[{"type":"string"},{"type":"integer"},{"type":"boolean"},{"type":"null"},{"type":"array","items":{"type":"integer"}}]},"source":{"type":["string","null"],"example":"account"}}},"description":"Resolved value and source keyed by policy path."}}},"effective_timezone":{"type":"string","description":"Timezone a new schedule in this scope starts from: the inbox setting, then the account setting, then the account timezone, then UTC. Never null.","example":"America/Sao_Paulo"},"inherited_timezone":{"type":"string","description":"Timezone an inbox without its own inherits: the account setting, then the account timezone, then UTC. Always an IANA identifier.","example":"America/Sao_Paulo"}}}}},"example":{"payload":{"setting":{"id":61,"inbox_id":null,"timezone":"America/Sao_Paulo","policy_template":{"on_inbound_reply":{"action":"pause"},"on_conversation_resolved":{"action":"continue"},"misfire":{"action":"send_latest","grace_seconds":60,"max_occurrences":10,"spacing_seconds":5},"transient_failure":{"max_attempts":3,"backoff_seconds":[30,120],"exhausted_action":"manual_review"},"permanent_failure":{"action":"manual_review"},"resume_behavior":{"action":"preserve_schedule","max_occurrences":10,"spacing_seconds":5},"quiet_hours":{"enabled":false,"start":"22:00","end":"08:00","days":[0,1,2,3,4,5,6],"action":"defer"},"overlap":{"action":"allow","defer_seconds":60},"inbox_change":{"action":"follow_logical"},"sender":{"type":"system","id":null,"missing":"fail"},"variables":{"resolve_at":"dispatch","missing":"fail"},"dst":{"nonexistent":"shift_forward","ambiguous":"first"},"materialization":{"horizon_seconds":2592000,"max_occurrences":500},"claim":{"lease_seconds":120,"recovery_grace_seconds":30}},"lock_version":0,"configured_at":"2026-08-21T16:00:00.000Z","configured_by_id":9},"resolved_policies":{"policy":{"on_inbound_reply":{"action":"pause"},"on_conversation_resolved":{"action":"continue"},"misfire":{"action":"send_latest","grace_seconds":60,"max_occurrences":10,"spacing_seconds":5},"transient_failure":{"max_attempts":3,"backoff_seconds":[30,120],"exhausted_action":"manual_review"},"permanent_failure":{"action":"manual_review"},"resume_behavior":{"action":"preserve_schedule","max_occurrences":10,"spacing_seconds":5},"quiet_hours":{"enabled":false,"start":"22:00","end":"08:00","days":[0,1,2,3,4,5,6],"action":"defer"},"overlap":{"action":"allow","defer_seconds":60},"inbox_change":{"action":"follow_logical"},"sender":{"type":"system","id":null,"missing":"fail"},"variables":{"resolve_at":"dispatch","missing":"fail"},"dst":{"nonexistent":"shift_forward","ambiguous":"first"},"materialization":{"horizon_seconds":2592000,"max_occurrences":500},"claim":{"lease_seconds":120,"recovery_grace_seconds":30}},"sources":{},"fields":{}},"effective_timezone":"America/Sao_Paulo","inherited_timezone":"America/Sao_Paulo"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"409":{"description":"The lock version is stale; reload before saving."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["lock_version","policy_template"],"properties":{"inbox_id":{"type":["integer","null"],"description":"Omit or null for account scope.","example":null},"timezone":{"type":["string","null"],"description":"IANA timezone for this scope. Required for the account scope; for an inbox, null clears its own timezone so it inherits the account setting again.","example":"America/Sao_Paulo"},"policy_template":{"type":"object","additionalProperties":false,"description":"Explicit schedule-level overrides; omitted leaves inherit from inbox/account.","properties":{"on_inbound_reply":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["continue","pause","cancel","skip"],"example":"pause"}}},"on_conversation_resolved":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["continue","pause","cancel","skip"],"example":"continue"}}},"misfire":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["skip","manual_review","send_latest","catch_up_bounded"],"example":"send_latest"},"grace_seconds":{"type":"integer","minimum":0,"example":60},"max_occurrences":{"type":"integer","minimum":1,"maximum":500,"example":10},"spacing_seconds":{"type":"integer","minimum":0,"example":5}}},"transient_failure":{"type":"object","additionalProperties":false,"properties":{"max_attempts":{"type":"integer","minimum":1,"maximum":10,"example":3},"backoff_seconds":{"type":"array","maxItems":9,"items":{"type":"integer","minimum":0,"maximum":86400},"example":[30,120]},"exhausted_action":{"type":"string","enum":["skip","pause","cancel","manual_review"],"example":"manual_review"}}},"permanent_failure":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["skip","pause","cancel","manual_review"],"example":"manual_review"}}},"resume_behavior":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["preserve_schedule","shift_by_pause","skip_missed","catch_up_bounded"],"example":"preserve_schedule"},"max_occurrences":{"type":"integer","minimum":1,"maximum":500,"example":10},"spacing_seconds":{"type":"integer","minimum":0,"example":5}}},"quiet_hours":{"type":"object","additionalProperties":false,"properties":{"enabled":{"type":"boolean","example":false},"start":{"type":"string","pattern":"^(?:[01][0-9]|2[0-3]):[0-5][0-9]$","example":"22:00"},"end":{"type":"string","pattern":"^(?:[01][0-9]|2[0-3]):[0-5][0-9]$","example":"08:00"},"days":{"type":"array","uniqueItems":true,"items":{"type":"integer","minimum":0,"maximum":6},"example":[0,1,2,3,4,5,6]},"action":{"type":"string","enum":["allow","defer","skip","manual_review"],"example":"defer"}}},"overlap":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["allow","skip_new","defer_new","cancel_previous","manual_review"],"example":"allow"},"defer_seconds":{"type":"integer","minimum":1,"example":60}}},"inbox_change":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["follow_logical","cancel","pause","manual_review"],"example":"follow_logical"}}},"sender":{"type":"object","additionalProperties":false,"properties":{"type":{"type":"string","enum":["assigned_agent","schedule_creator","user","agent_bot","system"],"example":"system"},"id":{"type":["integer","null"],"minimum":1,"example":null},"missing":{"type":"string","enum":["fail","system","assigned_agent"],"example":"fail"}}},"variables":{"type":"object","additionalProperties":false,"properties":{"resolve_at":{"type":"string","enum":["publication","dispatch"],"example":"dispatch"},"missing":{"type":"string","enum":["fail","blank","skip"],"example":"fail"}}},"dst":{"type":"object","additionalProperties":false,"properties":{"nonexistent":{"type":"string","enum":["skip","shift_forward","shift_backward"],"example":"shift_forward"},"ambiguous":{"type":"string","enum":["first","second","skip"],"example":"first"}}},"materialization":{"type":"object","additionalProperties":false,"properties":{"horizon_seconds":{"type":"integer","minimum":1,"maximum":2592000,"example":2592000},"max_occurrences":{"type":"integer","minimum":1,"maximum":500,"example":500}}},"claim":{"type":"object","additionalProperties":false,"properties":{"lease_seconds":{"type":"integer","minimum":1,"maximum":900,"example":120},"recovery_grace_seconds":{"type":"integer","minimum":0,"maximum":3600,"example":30}}}}},"lock_version":{"type":"integer","minimum":0,"example":0}}},"example":{"inbox_id":7,"timezone":"America/Sao_Paulo","policy_template":{"on_inbound_reply":{"action":"pause"},"on_conversation_resolved":{"action":"continue"},"misfire":{"action":"send_latest","grace_seconds":60,"max_occurrences":10,"spacing_seconds":5},"transient_failure":{"max_attempts":3,"backoff_seconds":[30,120],"exhausted_action":"manual_review"},"permanent_failure":{"action":"manual_review"},"resume_behavior":{"action":"preserve_schedule","max_occurrences":10,"spacing_seconds":5},"quiet_hours":{"enabled":false,"start":"22:00","end":"08:00","days":[0,1,2,3,4,5,6],"action":"defer"},"overlap":{"action":"allow","defer_seconds":60},"inbox_change":{"action":"follow_logical"},"sender":{"type":"system","id":null,"missing":"fail"},"variables":{"resolve_at":"dispatch","missing":"fail"},"dst":{"nonexistent":"shift_forward","ambiguous":"first"},"materialization":{"horizon_seconds":2592000,"max_occurrences":500},"claim":{"lease_seconds":120,"recovery_grace_seconds":30}},"lock_version":0}}}}},"put":{"tags":["Message Scheduling"],"operationId":"auto_put_api_v1_accounts_account_id_message_scheduling_settings","summary":"Update account or inbox scheduling policies","description":"Account scope requires every policy leaf. Inbox scope may contain only explicit overrides and inherits the remaining values. Optimistic locking prevents overwriting a concurrent edit.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Raw setting and effective policy for the requested scope.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","additionalProperties":false,"properties":{"setting":{"type":"object","additionalProperties":false,"properties":{"id":{"type":["integer","null"],"example":61},"inbox_id":{"type":["integer","null"],"example":null},"timezone":{"type":["string","null"],"example":"America/Sao_Paulo"},"policy_template":{"type":"object","additionalProperties":false,"description":"Explicit schedule-level overrides; omitted leaves inherit from inbox/account.","properties":{"on_inbound_reply":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["continue","pause","cancel","skip"],"example":"pause"}}},"on_conversation_resolved":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["continue","pause","cancel","skip"],"example":"continue"}}},"misfire":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["skip","manual_review","send_latest","catch_up_bounded"],"example":"send_latest"},"grace_seconds":{"type":"integer","minimum":0,"example":60},"max_occurrences":{"type":"integer","minimum":1,"maximum":500,"example":10},"spacing_seconds":{"type":"integer","minimum":0,"example":5}}},"transient_failure":{"type":"object","additionalProperties":false,"properties":{"max_attempts":{"type":"integer","minimum":1,"maximum":10,"example":3},"backoff_seconds":{"type":"array","maxItems":9,"items":{"type":"integer","minimum":0,"maximum":86400},"example":[30,120]},"exhausted_action":{"type":"string","enum":["skip","pause","cancel","manual_review"],"example":"manual_review"}}},"permanent_failure":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["skip","pause","cancel","manual_review"],"example":"manual_review"}}},"resume_behavior":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["preserve_schedule","shift_by_pause","skip_missed","catch_up_bounded"],"example":"preserve_schedule"},"max_occurrences":{"type":"integer","minimum":1,"maximum":500,"example":10},"spacing_seconds":{"type":"integer","minimum":0,"example":5}}},"quiet_hours":{"type":"object","additionalProperties":false,"properties":{"enabled":{"type":"boolean","example":false},"start":{"type":"string","pattern":"^(?:[01][0-9]|2[0-3]):[0-5][0-9]$","example":"22:00"},"end":{"type":"string","pattern":"^(?:[01][0-9]|2[0-3]):[0-5][0-9]$","example":"08:00"},"days":{"type":"array","uniqueItems":true,"items":{"type":"integer","minimum":0,"maximum":6},"example":[0,1,2,3,4,5,6]},"action":{"type":"string","enum":["allow","defer","skip","manual_review"],"example":"defer"}}},"overlap":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["allow","skip_new","defer_new","cancel_previous","manual_review"],"example":"allow"},"defer_seconds":{"type":"integer","minimum":1,"example":60}}},"inbox_change":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["follow_logical","cancel","pause","manual_review"],"example":"follow_logical"}}},"sender":{"type":"object","additionalProperties":false,"properties":{"type":{"type":"string","enum":["assigned_agent","schedule_creator","user","agent_bot","system"],"example":"system"},"id":{"type":["integer","null"],"minimum":1,"example":null},"missing":{"type":"string","enum":["fail","system","assigned_agent"],"example":"fail"}}},"variables":{"type":"object","additionalProperties":false,"properties":{"resolve_at":{"type":"string","enum":["publication","dispatch"],"example":"dispatch"},"missing":{"type":"string","enum":["fail","blank","skip"],"example":"fail"}}},"dst":{"type":"object","additionalProperties":false,"properties":{"nonexistent":{"type":"string","enum":["skip","shift_forward","shift_backward"],"example":"shift_forward"},"ambiguous":{"type":"string","enum":["first","second","skip"],"example":"first"}}},"materialization":{"type":"object","additionalProperties":false,"properties":{"horizon_seconds":{"type":"integer","minimum":1,"maximum":2592000,"example":2592000},"max_occurrences":{"type":"integer","minimum":1,"maximum":500,"example":500}}},"claim":{"type":"object","additionalProperties":false,"properties":{"lease_seconds":{"type":"integer","minimum":1,"maximum":900,"example":120},"recovery_grace_seconds":{"type":"integer","minimum":0,"maximum":3600,"example":30}}}}},"configured_at":{"type":["string","null"],"format":"date-time","example":"2026-08-21T16:00:00.000Z"},"configured_by_id":{"type":["integer","null"],"example":9},"lock_version":{"type":"integer","minimum":0,"example":0}}},"resolved_policies":{"type":"object","additionalProperties":false,"properties":{"policy":{"type":"object","additionalProperties":false,"description":"Explicit schedule-level overrides; omitted leaves inherit from inbox/account.","properties":{"on_inbound_reply":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["continue","pause","cancel","skip"],"example":"pause"}}},"on_conversation_resolved":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["continue","pause","cancel","skip"],"example":"continue"}}},"misfire":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["skip","manual_review","send_latest","catch_up_bounded"],"example":"send_latest"},"grace_seconds":{"type":"integer","minimum":0,"example":60},"max_occurrences":{"type":"integer","minimum":1,"maximum":500,"example":10},"spacing_seconds":{"type":"integer","minimum":0,"example":5}}},"transient_failure":{"type":"object","additionalProperties":false,"properties":{"max_attempts":{"type":"integer","minimum":1,"maximum":10,"example":3},"backoff_seconds":{"type":"array","maxItems":9,"items":{"type":"integer","minimum":0,"maximum":86400},"example":[30,120]},"exhausted_action":{"type":"string","enum":["skip","pause","cancel","manual_review"],"example":"manual_review"}}},"permanent_failure":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["skip","pause","cancel","manual_review"],"example":"manual_review"}}},"resume_behavior":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["preserve_schedule","shift_by_pause","skip_missed","catch_up_bounded"],"example":"preserve_schedule"},"max_occurrences":{"type":"integer","minimum":1,"maximum":500,"example":10},"spacing_seconds":{"type":"integer","minimum":0,"example":5}}},"quiet_hours":{"type":"object","additionalProperties":false,"properties":{"enabled":{"type":"boolean","example":false},"start":{"type":"string","pattern":"^(?:[01][0-9]|2[0-3]):[0-5][0-9]$","example":"22:00"},"end":{"type":"string","pattern":"^(?:[01][0-9]|2[0-3]):[0-5][0-9]$","example":"08:00"},"days":{"type":"array","uniqueItems":true,"items":{"type":"integer","minimum":0,"maximum":6},"example":[0,1,2,3,4,5,6]},"action":{"type":"string","enum":["allow","defer","skip","manual_review"],"example":"defer"}}},"overlap":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["allow","skip_new","defer_new","cancel_previous","manual_review"],"example":"allow"},"defer_seconds":{"type":"integer","minimum":1,"example":60}}},"inbox_change":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["follow_logical","cancel","pause","manual_review"],"example":"follow_logical"}}},"sender":{"type":"object","additionalProperties":false,"properties":{"type":{"type":"string","enum":["assigned_agent","schedule_creator","user","agent_bot","system"],"example":"system"},"id":{"type":["integer","null"],"minimum":1,"example":null},"missing":{"type":"string","enum":["fail","system","assigned_agent"],"example":"fail"}}},"variables":{"type":"object","additionalProperties":false,"properties":{"resolve_at":{"type":"string","enum":["publication","dispatch"],"example":"dispatch"},"missing":{"type":"string","enum":["fail","blank","skip"],"example":"fail"}}},"dst":{"type":"object","additionalProperties":false,"properties":{"nonexistent":{"type":"string","enum":["skip","shift_forward","shift_backward"],"example":"shift_forward"},"ambiguous":{"type":"string","enum":["first","second","skip"],"example":"first"}}},"materialization":{"type":"object","additionalProperties":false,"properties":{"horizon_seconds":{"type":"integer","minimum":1,"maximum":2592000,"example":2592000},"max_occurrences":{"type":"integer","minimum":1,"maximum":500,"example":500}}},"claim":{"type":"object","additionalProperties":false,"properties":{"lease_seconds":{"type":"integer","minimum":1,"maximum":900,"example":120},"recovery_grace_seconds":{"type":"integer","minimum":0,"maximum":3600,"example":30}}}}},"sources":{"type":"object","additionalProperties":{"type":"string"},"description":"Effective source keyed by policy path."},"fields":{"type":"object","additionalProperties":{"type":"object","additionalProperties":false,"properties":{"value":{"description":"Resolved scalar, null or integer-array policy value.","oneOf":[{"type":"string"},{"type":"integer"},{"type":"boolean"},{"type":"null"},{"type":"array","items":{"type":"integer"}}]},"source":{"type":["string","null"],"example":"account"}}},"description":"Resolved value and source keyed by policy path."}}},"effective_timezone":{"type":"string","description":"Timezone a new schedule in this scope starts from: the inbox setting, then the account setting, then the account timezone, then UTC. Never null.","example":"America/Sao_Paulo"},"inherited_timezone":{"type":"string","description":"Timezone an inbox without its own inherits: the account setting, then the account timezone, then UTC. Always an IANA identifier.","example":"America/Sao_Paulo"}}}}},"example":{"payload":{"setting":{"id":61,"inbox_id":null,"timezone":"America/Sao_Paulo","policy_template":{"on_inbound_reply":{"action":"pause"},"on_conversation_resolved":{"action":"continue"},"misfire":{"action":"send_latest","grace_seconds":60,"max_occurrences":10,"spacing_seconds":5},"transient_failure":{"max_attempts":3,"backoff_seconds":[30,120],"exhausted_action":"manual_review"},"permanent_failure":{"action":"manual_review"},"resume_behavior":{"action":"preserve_schedule","max_occurrences":10,"spacing_seconds":5},"quiet_hours":{"enabled":false,"start":"22:00","end":"08:00","days":[0,1,2,3,4,5,6],"action":"defer"},"overlap":{"action":"allow","defer_seconds":60},"inbox_change":{"action":"follow_logical"},"sender":{"type":"system","id":null,"missing":"fail"},"variables":{"resolve_at":"dispatch","missing":"fail"},"dst":{"nonexistent":"shift_forward","ambiguous":"first"},"materialization":{"horizon_seconds":2592000,"max_occurrences":500},"claim":{"lease_seconds":120,"recovery_grace_seconds":30}},"lock_version":0,"configured_at":"2026-08-21T16:00:00.000Z","configured_by_id":9},"resolved_policies":{"policy":{"on_inbound_reply":{"action":"pause"},"on_conversation_resolved":{"action":"continue"},"misfire":{"action":"send_latest","grace_seconds":60,"max_occurrences":10,"spacing_seconds":5},"transient_failure":{"max_attempts":3,"backoff_seconds":[30,120],"exhausted_action":"manual_review"},"permanent_failure":{"action":"manual_review"},"resume_behavior":{"action":"preserve_schedule","max_occurrences":10,"spacing_seconds":5},"quiet_hours":{"enabled":false,"start":"22:00","end":"08:00","days":[0,1,2,3,4,5,6],"action":"defer"},"overlap":{"action":"allow","defer_seconds":60},"inbox_change":{"action":"follow_logical"},"sender":{"type":"system","id":null,"missing":"fail"},"variables":{"resolve_at":"dispatch","missing":"fail"},"dst":{"nonexistent":"shift_forward","ambiguous":"first"},"materialization":{"horizon_seconds":2592000,"max_occurrences":500},"claim":{"lease_seconds":120,"recovery_grace_seconds":30}},"sources":{},"fields":{}},"effective_timezone":"America/Sao_Paulo","inherited_timezone":"America/Sao_Paulo"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"409":{"description":"The lock version is stale; reload before saving."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["lock_version","policy_template"],"properties":{"inbox_id":{"type":["integer","null"],"description":"Omit or null for account scope.","example":null},"timezone":{"type":["string","null"],"description":"IANA timezone for this scope. Required for the account scope; for an inbox, null clears its own timezone so it inherits the account setting again.","example":"America/Sao_Paulo"},"policy_template":{"type":"object","additionalProperties":false,"description":"Explicit schedule-level overrides; omitted leaves inherit from inbox/account.","properties":{"on_inbound_reply":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["continue","pause","cancel","skip"],"example":"pause"}}},"on_conversation_resolved":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["continue","pause","cancel","skip"],"example":"continue"}}},"misfire":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["skip","manual_review","send_latest","catch_up_bounded"],"example":"send_latest"},"grace_seconds":{"type":"integer","minimum":0,"example":60},"max_occurrences":{"type":"integer","minimum":1,"maximum":500,"example":10},"spacing_seconds":{"type":"integer","minimum":0,"example":5}}},"transient_failure":{"type":"object","additionalProperties":false,"properties":{"max_attempts":{"type":"integer","minimum":1,"maximum":10,"example":3},"backoff_seconds":{"type":"array","maxItems":9,"items":{"type":"integer","minimum":0,"maximum":86400},"example":[30,120]},"exhausted_action":{"type":"string","enum":["skip","pause","cancel","manual_review"],"example":"manual_review"}}},"permanent_failure":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["skip","pause","cancel","manual_review"],"example":"manual_review"}}},"resume_behavior":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["preserve_schedule","shift_by_pause","skip_missed","catch_up_bounded"],"example":"preserve_schedule"},"max_occurrences":{"type":"integer","minimum":1,"maximum":500,"example":10},"spacing_seconds":{"type":"integer","minimum":0,"example":5}}},"quiet_hours":{"type":"object","additionalProperties":false,"properties":{"enabled":{"type":"boolean","example":false},"start":{"type":"string","pattern":"^(?:[01][0-9]|2[0-3]):[0-5][0-9]$","example":"22:00"},"end":{"type":"string","pattern":"^(?:[01][0-9]|2[0-3]):[0-5][0-9]$","example":"08:00"},"days":{"type":"array","uniqueItems":true,"items":{"type":"integer","minimum":0,"maximum":6},"example":[0,1,2,3,4,5,6]},"action":{"type":"string","enum":["allow","defer","skip","manual_review"],"example":"defer"}}},"overlap":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["allow","skip_new","defer_new","cancel_previous","manual_review"],"example":"allow"},"defer_seconds":{"type":"integer","minimum":1,"example":60}}},"inbox_change":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["follow_logical","cancel","pause","manual_review"],"example":"follow_logical"}}},"sender":{"type":"object","additionalProperties":false,"properties":{"type":{"type":"string","enum":["assigned_agent","schedule_creator","user","agent_bot","system"],"example":"system"},"id":{"type":["integer","null"],"minimum":1,"example":null},"missing":{"type":"string","enum":["fail","system","assigned_agent"],"example":"fail"}}},"variables":{"type":"object","additionalProperties":false,"properties":{"resolve_at":{"type":"string","enum":["publication","dispatch"],"example":"dispatch"},"missing":{"type":"string","enum":["fail","blank","skip"],"example":"fail"}}},"dst":{"type":"object","additionalProperties":false,"properties":{"nonexistent":{"type":"string","enum":["skip","shift_forward","shift_backward"],"example":"shift_forward"},"ambiguous":{"type":"string","enum":["first","second","skip"],"example":"first"}}},"materialization":{"type":"object","additionalProperties":false,"properties":{"horizon_seconds":{"type":"integer","minimum":1,"maximum":2592000,"example":2592000},"max_occurrences":{"type":"integer","minimum":1,"maximum":500,"example":500}}},"claim":{"type":"object","additionalProperties":false,"properties":{"lease_seconds":{"type":"integer","minimum":1,"maximum":900,"example":120},"recovery_grace_seconds":{"type":"integer","minimum":0,"maximum":3600,"example":30}}}}},"lock_version":{"type":"integer","minimum":0,"example":0}}},"example":{"inbox_id":7,"timezone":"America/Sao_Paulo","policy_template":{"on_inbound_reply":{"action":"pause"},"on_conversation_resolved":{"action":"continue"},"misfire":{"action":"send_latest","grace_seconds":60,"max_occurrences":10,"spacing_seconds":5},"transient_failure":{"max_attempts":3,"backoff_seconds":[30,120],"exhausted_action":"manual_review"},"permanent_failure":{"action":"manual_review"},"resume_behavior":{"action":"preserve_schedule","max_occurrences":10,"spacing_seconds":5},"quiet_hours":{"enabled":false,"start":"22:00","end":"08:00","days":[0,1,2,3,4,5,6],"action":"defer"},"overlap":{"action":"allow","defer_seconds":60},"inbox_change":{"action":"follow_logical"},"sender":{"type":"system","id":null,"missing":"fail"},"variables":{"resolve_at":"dispatch","missing":"fail"},"dst":{"nonexistent":"shift_forward","ambiguous":"first"},"materialization":{"horizon_seconds":2592000,"max_occurrences":500},"claim":{"lease_seconds":120,"recovery_grace_seconds":30}},"lock_version":0}}}}}},"/api/v1/accounts/{account_id}/follow_up/sequences/{id}/publish":{"post":{"tags":["Follow-up"],"operationId":"auto_post_api_v1_accounts_account_id_follow_up_sequences_id_publish","summary":"Publish sequences","description":"Performs the publish operation on the targeted sequence resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"status":{"type":"string","enum":["draft","active","paused","archived"]},"trigger_type":{"type":"string","enum":["manual","event","inactivity","schedule","ai_proposed"]},"trigger_event":{"type":"string"},"target_type":{"type":"string","enum":["contact","conversation","crm_item","calendar_event","payment_charge"]},"published_version_id":{"type":"integer"},"activated_at":{"type":"string","format":"date-time"},"inactivity_watermark_at":{"type":"string","format":"date-time"},"inactivity_backfill_policy":{"type":"string","enum":["future_only","explicit_backfill"]},"inactivity_backfill_confirmed_at":{"type":"string","format":"date-time"},"trigger_conditions":{"type":"string"},"exit_conditions":{"type":"string"},"ai_config":{"type":"string"},"settings":{"type":"string"},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"steps_count":{"type":"integer"},"enrollments_count":{"type":"integer"},"archived_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"steps":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"follow_up_sequence_id":{"type":"integer"},"follow_up_template_id":{"type":"integer"},"position":{"type":"integer"},"name":{"type":"string"},"delay_value":{"type":"number"},"delay_unit":{"type":"string","enum":["minutes","hours","days","business_days"]},"channel":{"type":"string","enum":["auto","same_conversation","email","sms","whatsapp"]},"content_type":{"type":"string","enum":["text","template","rich"]},"message_template":{"type":"string"},"compose_mode":{"type":"string","enum":["static","ai_assisted","ai_full"]},"ai_intent":{"type":"string"},"branch_conditions":{"type":"string"},"actions":{"type":"string"},"skip_conditions":{"type":"string"},"whatsapp_template":{"type":"string"},"settings":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}}}}},"example":{"payload":{"id":1,"account_id":1,"name":"Sample Name","description":"A short description.","status":"draft","trigger_type":"manual","trigger_event":"sample trigger event","target_type":"contact","published_version_id":1,"activated_at":"2026-01-15T10:30:00.000Z","inactivity_watermark_at":"2026-01-15T10:30:00.000Z","inactivity_backfill_policy":"future_only","inactivity_backfill_confirmed_at":"2026-01-15T10:30:00.000Z","trigger_conditions":"sample trigger conditions","exit_conditions":"sample exit conditions","ai_config":"sample ai config","settings":"sample settings","custom_attributes":{},"steps_count":5,"enrollments_count":5,"archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","steps":[{"id":1,"follow_up_sequence_id":1,"follow_up_template_id":1,"position":1,"name":"Sample Name","delay_value":149.9,"delay_unit":"minutes","channel":"auto","content_type":"text","message_template":"sample message template","compose_mode":"static","ai_intent":"sample ai intent","branch_conditions":"sample branch conditions","actions":"sample actions","skip_conditions":"sample skip conditions","whatsapp_template":"sample whatsapp template","settings":"sample settings","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/follow_up/sequences/{id}/activate":{"post":{"tags":["Follow-up"],"operationId":"auto_post_api_v1_accounts_account_id_follow_up_sequences_id_activate","summary":"Activate sequences","description":"Performs the activate operation on the targeted sequence resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"status":{"type":"string","enum":["draft","active","paused","archived"]},"trigger_type":{"type":"string","enum":["manual","event","inactivity","schedule","ai_proposed"]},"trigger_event":{"type":"string"},"target_type":{"type":"string","enum":["contact","conversation","crm_item","calendar_event","payment_charge"]},"published_version_id":{"type":"integer"},"activated_at":{"type":"string","format":"date-time"},"inactivity_watermark_at":{"type":"string","format":"date-time"},"inactivity_backfill_policy":{"type":"string","enum":["future_only","explicit_backfill"]},"inactivity_backfill_confirmed_at":{"type":"string","format":"date-time"},"trigger_conditions":{"type":"string"},"exit_conditions":{"type":"string"},"ai_config":{"type":"string"},"settings":{"type":"string"},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"steps_count":{"type":"integer"},"enrollments_count":{"type":"integer"},"archived_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"steps":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"follow_up_sequence_id":{"type":"integer"},"follow_up_template_id":{"type":"integer"},"position":{"type":"integer"},"name":{"type":"string"},"delay_value":{"type":"number"},"delay_unit":{"type":"string","enum":["minutes","hours","days","business_days"]},"channel":{"type":"string","enum":["auto","same_conversation","email","sms","whatsapp"]},"content_type":{"type":"string","enum":["text","template","rich"]},"message_template":{"type":"string"},"compose_mode":{"type":"string","enum":["static","ai_assisted","ai_full"]},"ai_intent":{"type":"string"},"branch_conditions":{"type":"string"},"actions":{"type":"string"},"skip_conditions":{"type":"string"},"whatsapp_template":{"type":"string"},"settings":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}}}}},"example":{"payload":{"id":1,"account_id":1,"name":"Sample Name","description":"A short description.","status":"draft","trigger_type":"manual","trigger_event":"sample trigger event","target_type":"contact","published_version_id":1,"activated_at":"2026-01-15T10:30:00.000Z","inactivity_watermark_at":"2026-01-15T10:30:00.000Z","inactivity_backfill_policy":"future_only","inactivity_backfill_confirmed_at":"2026-01-15T10:30:00.000Z","trigger_conditions":"sample trigger conditions","exit_conditions":"sample exit conditions","ai_config":"sample ai config","settings":"sample settings","custom_attributes":{},"steps_count":5,"enrollments_count":5,"archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","steps":[{"id":1,"follow_up_sequence_id":1,"follow_up_template_id":1,"position":1,"name":"Sample Name","delay_value":149.9,"delay_unit":"minutes","channel":"auto","content_type":"text","message_template":"sample message template","compose_mode":"static","ai_intent":"sample ai intent","branch_conditions":"sample branch conditions","actions":"sample actions","skip_conditions":"sample skip conditions","whatsapp_template":"sample whatsapp template","settings":"sample settings","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/follow_up/sequences/{id}/pause":{"post":{"tags":["Follow-up"],"operationId":"auto_post_api_v1_accounts_account_id_follow_up_sequences_id_pause","summary":"Pause sequences","description":"Performs the pause operation on the targeted sequence resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"status":{"type":"string","enum":["draft","active","paused","archived"]},"trigger_type":{"type":"string","enum":["manual","event","inactivity","schedule","ai_proposed"]},"trigger_event":{"type":"string"},"target_type":{"type":"string","enum":["contact","conversation","crm_item","calendar_event","payment_charge"]},"published_version_id":{"type":"integer"},"activated_at":{"type":"string","format":"date-time"},"inactivity_watermark_at":{"type":"string","format":"date-time"},"inactivity_backfill_policy":{"type":"string","enum":["future_only","explicit_backfill"]},"inactivity_backfill_confirmed_at":{"type":"string","format":"date-time"},"trigger_conditions":{"type":"string"},"exit_conditions":{"type":"string"},"ai_config":{"type":"string"},"settings":{"type":"string"},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"steps_count":{"type":"integer"},"enrollments_count":{"type":"integer"},"archived_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"steps":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"follow_up_sequence_id":{"type":"integer"},"follow_up_template_id":{"type":"integer"},"position":{"type":"integer"},"name":{"type":"string"},"delay_value":{"type":"number"},"delay_unit":{"type":"string","enum":["minutes","hours","days","business_days"]},"channel":{"type":"string","enum":["auto","same_conversation","email","sms","whatsapp"]},"content_type":{"type":"string","enum":["text","template","rich"]},"message_template":{"type":"string"},"compose_mode":{"type":"string","enum":["static","ai_assisted","ai_full"]},"ai_intent":{"type":"string"},"branch_conditions":{"type":"string"},"actions":{"type":"string"},"skip_conditions":{"type":"string"},"whatsapp_template":{"type":"string"},"settings":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}}}}},"example":{"payload":{"id":1,"account_id":1,"name":"Sample Name","description":"A short description.","status":"draft","trigger_type":"manual","trigger_event":"sample trigger event","target_type":"contact","published_version_id":1,"activated_at":"2026-01-15T10:30:00.000Z","inactivity_watermark_at":"2026-01-15T10:30:00.000Z","inactivity_backfill_policy":"future_only","inactivity_backfill_confirmed_at":"2026-01-15T10:30:00.000Z","trigger_conditions":"sample trigger conditions","exit_conditions":"sample exit conditions","ai_config":"sample ai config","settings":"sample settings","custom_attributes":{},"steps_count":5,"enrollments_count":5,"archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","steps":[{"id":1,"follow_up_sequence_id":1,"follow_up_template_id":1,"position":1,"name":"Sample Name","delay_value":149.9,"delay_unit":"minutes","channel":"auto","content_type":"text","message_template":"sample message template","compose_mode":"static","ai_intent":"sample ai intent","branch_conditions":"sample branch conditions","actions":"sample actions","skip_conditions":"sample skip conditions","whatsapp_template":"sample whatsapp template","settings":"sample settings","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/follow_up/sequences/{id}/duplicate":{"post":{"tags":["Follow-up"],"operationId":"auto_post_api_v1_accounts_account_id_follow_up_sequences_id_duplicate","summary":"Duplicate sequences","description":"Performs the duplicate operation on the targeted sequence resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"status":{"type":"string","enum":["draft","active","paused","archived"]},"trigger_type":{"type":"string","enum":["manual","event","inactivity","schedule","ai_proposed"]},"trigger_event":{"type":"string"},"target_type":{"type":"string","enum":["contact","conversation","crm_item","calendar_event","payment_charge"]},"published_version_id":{"type":"integer"},"activated_at":{"type":"string","format":"date-time"},"inactivity_watermark_at":{"type":"string","format":"date-time"},"inactivity_backfill_policy":{"type":"string","enum":["future_only","explicit_backfill"]},"inactivity_backfill_confirmed_at":{"type":"string","format":"date-time"},"trigger_conditions":{"type":"string"},"exit_conditions":{"type":"string"},"ai_config":{"type":"string"},"settings":{"type":"string"},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"steps_count":{"type":"integer"},"enrollments_count":{"type":"integer"},"archived_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"steps":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"follow_up_sequence_id":{"type":"integer"},"follow_up_template_id":{"type":"integer"},"position":{"type":"integer"},"name":{"type":"string"},"delay_value":{"type":"number"},"delay_unit":{"type":"string","enum":["minutes","hours","days","business_days"]},"channel":{"type":"string","enum":["auto","same_conversation","email","sms","whatsapp"]},"content_type":{"type":"string","enum":["text","template","rich"]},"message_template":{"type":"string"},"compose_mode":{"type":"string","enum":["static","ai_assisted","ai_full"]},"ai_intent":{"type":"string"},"branch_conditions":{"type":"string"},"actions":{"type":"string"},"skip_conditions":{"type":"string"},"whatsapp_template":{"type":"string"},"settings":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}}}}},"example":{"payload":{"id":1,"account_id":1,"name":"Sample Name","description":"A short description.","status":"draft","trigger_type":"manual","trigger_event":"sample trigger event","target_type":"contact","published_version_id":1,"activated_at":"2026-01-15T10:30:00.000Z","inactivity_watermark_at":"2026-01-15T10:30:00.000Z","inactivity_backfill_policy":"future_only","inactivity_backfill_confirmed_at":"2026-01-15T10:30:00.000Z","trigger_conditions":"sample trigger conditions","exit_conditions":"sample exit conditions","ai_config":"sample ai config","settings":"sample settings","custom_attributes":{},"steps_count":5,"enrollments_count":5,"archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","steps":[{"id":1,"follow_up_sequence_id":1,"follow_up_template_id":1,"position":1,"name":"Sample Name","delay_value":149.9,"delay_unit":"minutes","channel":"auto","content_type":"text","message_template":"sample message template","compose_mode":"static","ai_intent":"sample ai intent","branch_conditions":"sample branch conditions","actions":"sample actions","skip_conditions":"sample skip conditions","whatsapp_template":"sample whatsapp template","settings":"sample settings","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/follow_up/sequences/{id}/archive":{"post":{"tags":["Follow-up"],"operationId":"auto_post_api_v1_accounts_account_id_follow_up_sequences_id_archive","summary":"Archive sequences","description":"Performs the archive operation on the targeted sequence resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"status":{"type":"string","enum":["draft","active","paused","archived"]},"trigger_type":{"type":"string","enum":["manual","event","inactivity","schedule","ai_proposed"]},"trigger_event":{"type":"string"},"target_type":{"type":"string","enum":["contact","conversation","crm_item","calendar_event","payment_charge"]},"published_version_id":{"type":"integer"},"activated_at":{"type":"string","format":"date-time"},"inactivity_watermark_at":{"type":"string","format":"date-time"},"inactivity_backfill_policy":{"type":"string","enum":["future_only","explicit_backfill"]},"inactivity_backfill_confirmed_at":{"type":"string","format":"date-time"},"trigger_conditions":{"type":"string"},"exit_conditions":{"type":"string"},"ai_config":{"type":"string"},"settings":{"type":"string"},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"steps_count":{"type":"integer"},"enrollments_count":{"type":"integer"},"archived_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"steps":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"follow_up_sequence_id":{"type":"integer"},"follow_up_template_id":{"type":"integer"},"position":{"type":"integer"},"name":{"type":"string"},"delay_value":{"type":"number"},"delay_unit":{"type":"string","enum":["minutes","hours","days","business_days"]},"channel":{"type":"string","enum":["auto","same_conversation","email","sms","whatsapp"]},"content_type":{"type":"string","enum":["text","template","rich"]},"message_template":{"type":"string"},"compose_mode":{"type":"string","enum":["static","ai_assisted","ai_full"]},"ai_intent":{"type":"string"},"branch_conditions":{"type":"string"},"actions":{"type":"string"},"skip_conditions":{"type":"string"},"whatsapp_template":{"type":"string"},"settings":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}}}}},"example":{"payload":{"id":1,"account_id":1,"name":"Sample Name","description":"A short description.","status":"draft","trigger_type":"manual","trigger_event":"sample trigger event","target_type":"contact","published_version_id":1,"activated_at":"2026-01-15T10:30:00.000Z","inactivity_watermark_at":"2026-01-15T10:30:00.000Z","inactivity_backfill_policy":"future_only","inactivity_backfill_confirmed_at":"2026-01-15T10:30:00.000Z","trigger_conditions":"sample trigger conditions","exit_conditions":"sample exit conditions","ai_config":"sample ai config","settings":"sample settings","custom_attributes":{},"steps_count":5,"enrollments_count":5,"archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","steps":[{"id":1,"follow_up_sequence_id":1,"follow_up_template_id":1,"position":1,"name":"Sample Name","delay_value":149.9,"delay_unit":"minutes","channel":"auto","content_type":"text","message_template":"sample message template","compose_mode":"static","ai_intent":"sample ai intent","branch_conditions":"sample branch conditions","actions":"sample actions","skip_conditions":"sample skip conditions","whatsapp_template":"sample whatsapp template","settings":"sample settings","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/follow_up/sequences/{id}/restore":{"post":{"tags":["Follow-up"],"operationId":"auto_post_api_v1_accounts_account_id_follow_up_sequences_id_restore","summary":"Restore sequences","description":"Performs the restore operation on the targeted sequence resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"status":{"type":"string","enum":["draft","active","paused","archived"]},"trigger_type":{"type":"string","enum":["manual","event","inactivity","schedule","ai_proposed"]},"trigger_event":{"type":"string"},"target_type":{"type":"string","enum":["contact","conversation","crm_item","calendar_event","payment_charge"]},"published_version_id":{"type":"integer"},"activated_at":{"type":"string","format":"date-time"},"inactivity_watermark_at":{"type":"string","format":"date-time"},"inactivity_backfill_policy":{"type":"string","enum":["future_only","explicit_backfill"]},"inactivity_backfill_confirmed_at":{"type":"string","format":"date-time"},"trigger_conditions":{"type":"string"},"exit_conditions":{"type":"string"},"ai_config":{"type":"string"},"settings":{"type":"string"},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"steps_count":{"type":"integer"},"enrollments_count":{"type":"integer"},"archived_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"steps":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"follow_up_sequence_id":{"type":"integer"},"follow_up_template_id":{"type":"integer"},"position":{"type":"integer"},"name":{"type":"string"},"delay_value":{"type":"number"},"delay_unit":{"type":"string","enum":["minutes","hours","days","business_days"]},"channel":{"type":"string","enum":["auto","same_conversation","email","sms","whatsapp"]},"content_type":{"type":"string","enum":["text","template","rich"]},"message_template":{"type":"string"},"compose_mode":{"type":"string","enum":["static","ai_assisted","ai_full"]},"ai_intent":{"type":"string"},"branch_conditions":{"type":"string"},"actions":{"type":"string"},"skip_conditions":{"type":"string"},"whatsapp_template":{"type":"string"},"settings":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}}}}},"example":{"payload":{"id":1,"account_id":1,"name":"Sample Name","description":"A short description.","status":"draft","trigger_type":"manual","trigger_event":"sample trigger event","target_type":"contact","published_version_id":1,"activated_at":"2026-01-15T10:30:00.000Z","inactivity_watermark_at":"2026-01-15T10:30:00.000Z","inactivity_backfill_policy":"future_only","inactivity_backfill_confirmed_at":"2026-01-15T10:30:00.000Z","trigger_conditions":"sample trigger conditions","exit_conditions":"sample exit conditions","ai_config":"sample ai config","settings":"sample settings","custom_attributes":{},"steps_count":5,"enrollments_count":5,"archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","steps":[{"id":1,"follow_up_sequence_id":1,"follow_up_template_id":1,"position":1,"name":"Sample Name","delay_value":149.9,"delay_unit":"minutes","channel":"auto","content_type":"text","message_template":"sample message template","compose_mode":"static","ai_intent":"sample ai intent","branch_conditions":"sample branch conditions","actions":"sample actions","skip_conditions":"sample skip conditions","whatsapp_template":"sample whatsapp template","settings":"sample settings","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/follow_up/sequences/{id}/inactivity_backfill_preview":{"post":{"tags":["Follow-up"],"operationId":"auto_post_api_v1_accounts_account_id_follow_up_sequences_id_inactivity_backfill_preview","summary":"Preview historical inactivity enrollment","description":"Calculates the exact historical conversations currently eligible for this active inactivity sequence. Returns a short-lived signed token bound to the sequence version, boundary, count and candidate digest. It does not change the sequence or create an enrollment.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Exact audience preview and its short-lived confirmation token.","content":{"application/json":{"schema":{"type":"object","properties":{"count":{"type":"integer","example":18},"sample_conversation_ids":{"type":"array","items":{"type":"integer","example":4821}},"from":{"type":"string","format":"date-time","example":"2026-08-01T03:00:00Z"},"expires_at":{"type":"string","format":"date-time","example":"2026-08-20T23:15:00Z"},"confirmation_token":{"type":"string","description":"Signed, expiring token bound to this exact candidate audience.","example":"eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaEpJZyJ9fQ"}}},"example":{"count":18,"sample_conversation_ids":[4821],"from":"2026-08-01T03:00:00Z","expires_at":"2026-08-20T23:15:00Z","confirmation_token":"eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaEpJZyJ9fQ"}}}},"401":{"description":"Unauthorized."},"404":{"description":"Account or resource not found"},"403":{"description":"Feature not enabled or insufficient access."},"422":{"description":"Sequence or boundary is not eligible for explicit backfill."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["from"],"properties":{"from":{"type":"string","format":"date-time","description":"Earliest last-activity instant to consider, exclusive.","example":"2026-08-01T00:00:00-03:00"},"sample_size":{"type":"integer","minimum":0,"maximum":100,"description":"Maximum number of candidate ids returned as an inspection sample.","example":20}}},"example":{"from":"2026-08-01T00:00:00-03:00","sample_size":20}}}}}},"/api/v1/accounts/{account_id}/follow_up/sequences/{id}/inactivity_backfill_confirm":{"post":{"tags":["Follow-up"],"operationId":"auto_post_api_v1_accounts_account_id_follow_up_sequences_id_inactivity_backfill_confirm","summary":"Confirm historical inactivity enrollment","description":"Queues only the exact conversation ids represented by a valid, unexpired preview token after rechecking that the sequence and candidate snapshot have not changed. Later conversations cannot inherit this approval. Maestro pause and unknown-state holds remain pending and enforced.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Updated follow-up sequence with the exact historical snapshot queued in safe batches."},"401":{"description":"Unauthorized."},"404":{"description":"Sequence not found in this account."},"403":{"description":"Feature not enabled or insufficient access."},"422":{"description":"Token invalid, expired, or no longer matches the exact candidate audience."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["confirmation_token"],"properties":{"confirmation_token":{"type":"string","description":"Token returned by the preview operation.","example":"eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaEpJZyJ9fQ"}}},"example":{"confirmation_token":"eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaEpJZyJ9fQ"}}}}}},"/api/v1/accounts/{account_id}/follow_up/sequences/{id}/schedule_preview":{"get":{"tags":["Follow-up"],"operationId":"auto_get_api_v1_accounts_account_id_follow_up_sequences_id_schedule_preview","summary":"Preview the cadence schedule","description":"Returns a dry-run of the scheduling resolver over the sequence's ordered steps starting from the current time: each step's cumulative ETA (absolute UTC instant) and the IANA timezone it schedules in, plus that timezone's source layer in the resolution cascade. No enrollment is created and no message is sent.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The per-step schedule preview (one entry per ordered step).","content":{"application/json":{"schema":{"type":"object","properties":{"steps":{"type":"array","description":"One entry per ordered step, in position order, with a cumulative ETA.","items":{"type":"object","properties":{"step_id":{"type":"integer","description":"The follow_up_steps id.","example":88},"position":{"type":"integer","description":"The step's 1-based position in the cadence.","example":2},"eta":{"type":"string","format":"date-time","description":"The computed next-run instant (ISO-8601, UTC).","example":"2026-07-20T12:00:00Z"},"timezone":{"type":"string","description":"The resolved IANA timezone this step schedules in.","example":"America/Sao_Paulo"},"timezone_source":{"type":"string","description":"Which cascade layer supplied the resolved timezone (explicit settings first, then the AUTO chain).","enum":["step","sequence","inbox_setting","account_setting","enrollment","contact","account","inbox","default"],"example":"account"}}}}}},"example":{"steps":[{"step_id":88,"position":2,"eta":"2026-07-20T12:00:00Z","timezone":"America/Sao_Paulo","timezone_source":"account"}]}}}},"401":{"description":"Unauthorized."},"404":{"description":"Sequence not found in this account."},"403":{"description":"Feature not enabled or insufficient access."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/follow_up/sequences/bulk_destroy":{"post":{"tags":["Follow-up"],"operationId":"auto_post_api_v1_accounts_account_id_follow_up_sequences_bulk_destroy","summary":"Bulk destroy sequences","description":"Performs the bulk destroy operation on the targeted sequence resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"ids":{"type":"string"}}}}},"example":{"payload":{"ids":"sample ids"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"sequence_ids":{"type":"array","items":{"type":"integer"}}}},"example":{"sequence_ids":[1]}}}}}},"/api/v1/accounts/{account_id}/follow_up/sequences/bulk_archive":{"post":{"tags":["Follow-up"],"operationId":"auto_post_api_v1_accounts_account_id_follow_up_sequences_bulk_archive","summary":"Bulk archive sequences","description":"Performs the bulk archive operation on the targeted sequence resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"ids":{"type":"string"}}}}},"example":{"payload":{"ids":"sample ids"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"sequence_ids":{"type":"array","items":{"type":"integer"}}}},"example":{"sequence_ids":[1]}}}}}},"/api/v1/accounts/{account_id}/follow_up/sequences/bulk_restore":{"post":{"tags":["Follow-up"],"operationId":"auto_post_api_v1_accounts_account_id_follow_up_sequences_bulk_restore","summary":"Bulk restore sequences","description":"Performs the bulk restore operation on the targeted sequence resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"ids":{"type":"string"}}}}},"example":{"payload":{"ids":"sample ids"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"sequence_ids":{"type":"array","items":{"type":"integer"}}}},"example":{"sequence_ids":[1]}}}}}},"/api/v1/accounts/{account_id}/follow_up/sequences/{sequence_id}/steps/reposition":{"post":{"tags":["Follow-up"],"operationId":"auto_post_api_v1_accounts_account_id_follow_up_sequences_sequence_id_steps_reposition","summary":"Reposition follow-up steps","description":"Sets each step's position from the supplied {id, position} pairs and returns the reordered steps.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"follow_up_sequence_id":{"type":"integer"},"follow_up_template_id":{"type":"integer"},"position":{"type":"integer"},"name":{"type":"string"},"delay_value":{"type":"number"},"delay_unit":{"type":"string","enum":["minutes","hours","days","business_days"]},"channel":{"type":"string","enum":["auto","same_conversation","email","sms","whatsapp"]},"content_type":{"type":"string","enum":["text","template","rich"]},"message_template":{"type":"string"},"compose_mode":{"type":"string","enum":["static","ai_assisted","ai_full"]},"ai_intent":{"type":"string"},"branch_conditions":{"type":"string"},"actions":{"type":"string"},"skip_conditions":{"type":"string"},"whatsapp_template":{"type":"string"},"settings":{"type":"object","additionalProperties":true,"description":"Per-step overrides. Scheduling keys pin when the step sends; `button` adds an optional native call-to-action to the step's own message inside the 24h window (outside it, the link travels in the WhatsApp template's URL button instead). A key is written only when it overrides the default, so an all-inherit step with no button stores `{}`.","properties":{"send_time_mode":{"type":"string","enum":["inherit","fixed"],"description":"`fixed` pins the step to `send_at_local` in the resolved timezone; `inherit` (the default, stored as no key at all) lets the step fire as soon as its delay elapses."},"send_at_local":{"type":"string","example":"09:30","description":"Local wall-clock time `HH:MM` used when `send_time_mode` is `fixed`."},"timezone":{"type":"string","description":"IANA timezone that overrides the resolved cascade (contact, sequence, account) for this step. Absent means the cascade decides."},"button":{"type":"object","description":"Optional call-to-action rendered as a native button by the channels that support one (WhatsApp Cloud as an interactive `cta_url`, WhatsApp Web as a buttons message, the API channel as `cta_buttons`); on any other channel only the link written in the body ships. Both fields go through the same Liquid rendering as the message body. Both are required - a half-filled button is dropped rather than sent, because the gateway would reject the whole message.","properties":{"text":{"type":"string","example":"Pagar agora","description":"Button caption."},"url":{"type":"string","example":"https://app.example/p/{{ contact.identifier }}","description":"Destination link; may contain Liquid, resolved per contact at send time."}}}}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}}},"example":{"payload":[{"id":1,"follow_up_sequence_id":1,"follow_up_template_id":1,"position":1,"name":"Sample Name","delay_value":149.9,"delay_unit":"minutes","channel":"auto","content_type":"text","message_template":"sample message template","compose_mode":"static","ai_intent":"sample ai intent","branch_conditions":"sample branch conditions","actions":"sample actions","skip_conditions":"sample skip conditions","whatsapp_template":"sample whatsapp template","settings":{"send_time_mode":"inherit","send_at_local":"09:30","timezone":"America/Sao_Paulo","button":{"text":"Pagar agora","url":"https://app.example/p/{{ contact.identifier }}"}},"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"sequence_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["positions"],"properties":{"positions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","example":55},"position":{"type":"integer","example":2}}},"example":[{"id":55,"position":1},{"id":56,"position":2}]}}},"example":{"positions":[{"id":55,"position":1},{"id":56,"position":2}]}}}}}},"/api/v1/accounts/{account_id}/follow_up/sequences/{sequence_id}/steps":{"get":{"tags":["Follow-up"],"operationId":"auto_get_api_v1_accounts_account_id_follow_up_sequences_sequence_id_steps","summary":"List steps","description":"Returns the list of steps visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"follow_up_sequence_id":{"type":"integer"},"follow_up_template_id":{"type":"integer"},"position":{"type":"integer"},"name":{"type":"string"},"delay_value":{"type":"number"},"delay_unit":{"type":"string","enum":["minutes","hours","days","business_days"]},"channel":{"type":"string","enum":["auto","same_conversation","email","sms","whatsapp"]},"content_type":{"type":"string","enum":["text","template","rich"]},"message_template":{"type":"string"},"compose_mode":{"type":"string","enum":["static","ai_assisted","ai_full"]},"ai_intent":{"type":"string"},"branch_conditions":{"type":"string"},"actions":{"type":"string"},"skip_conditions":{"type":"string"},"whatsapp_template":{"type":"string"},"settings":{"type":"object","additionalProperties":true,"description":"Per-step overrides. Scheduling keys pin when the step sends; `button` adds an optional native call-to-action to the step's own message inside the 24h window (outside it, the link travels in the WhatsApp template's URL button instead). A key is written only when it overrides the default, so an all-inherit step with no button stores `{}`.","properties":{"send_time_mode":{"type":"string","enum":["inherit","fixed"],"description":"`fixed` pins the step to `send_at_local` in the resolved timezone; `inherit` (the default, stored as no key at all) lets the step fire as soon as its delay elapses."},"send_at_local":{"type":"string","example":"09:30","description":"Local wall-clock time `HH:MM` used when `send_time_mode` is `fixed`."},"timezone":{"type":"string","description":"IANA timezone that overrides the resolved cascade (contact, sequence, account) for this step. Absent means the cascade decides."},"button":{"type":"object","description":"Optional call-to-action rendered as a native button by the channels that support one (WhatsApp Cloud as an interactive `cta_url`, WhatsApp Web as a buttons message, the API channel as `cta_buttons`); on any other channel only the link written in the body ships. Both fields go through the same Liquid rendering as the message body. Both are required - a half-filled button is dropped rather than sent, because the gateway would reject the whole message.","properties":{"text":{"type":"string","example":"Pagar agora","description":"Button caption."},"url":{"type":"string","example":"https://app.example/p/{{ contact.identifier }}","description":"Destination link; may contain Liquid, resolved per contact at send time."}}}}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}}},"example":{"payload":[{"id":1,"follow_up_sequence_id":1,"follow_up_template_id":1,"position":1,"name":"Sample Name","delay_value":149.9,"delay_unit":"minutes","channel":"auto","content_type":"text","message_template":"sample message template","compose_mode":"static","ai_intent":"sample ai intent","branch_conditions":"sample branch conditions","actions":"sample actions","skip_conditions":"sample skip conditions","whatsapp_template":"sample whatsapp template","settings":{"send_time_mode":"inherit","send_at_local":"09:30","timezone":"America/Sao_Paulo","button":{"text":"Pagar agora","url":"https://app.example/p/{{ contact.identifier }}"}},"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"sequence_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."}]},"post":{"tags":["Follow-up"],"operationId":"auto_post_api_v1_accounts_account_id_follow_up_sequences_sequence_id_steps","summary":"Create steps","description":"Creates a new step from the request payload. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"follow_up_sequence_id":{"type":"integer"},"follow_up_template_id":{"type":"integer"},"position":{"type":"integer"},"name":{"type":"string"},"delay_value":{"type":"number"},"delay_unit":{"type":"string","enum":["minutes","hours","days","business_days"]},"channel":{"type":"string","enum":["auto","same_conversation","email","sms","whatsapp"]},"content_type":{"type":"string","enum":["text","template","rich"]},"message_template":{"type":"string"},"compose_mode":{"type":"string","enum":["static","ai_assisted","ai_full"]},"ai_intent":{"type":"string"},"branch_conditions":{"type":"string"},"actions":{"type":"string"},"skip_conditions":{"type":"string"},"whatsapp_template":{"type":"string"},"settings":{"type":"object","additionalProperties":true,"description":"Per-step overrides. Scheduling keys pin when the step sends; `button` adds an optional native call-to-action to the step's own message inside the 24h window (outside it, the link travels in the WhatsApp template's URL button instead). A key is written only when it overrides the default, so an all-inherit step with no button stores `{}`.","properties":{"send_time_mode":{"type":"string","enum":["inherit","fixed"],"description":"`fixed` pins the step to `send_at_local` in the resolved timezone; `inherit` (the default, stored as no key at all) lets the step fire as soon as its delay elapses."},"send_at_local":{"type":"string","example":"09:30","description":"Local wall-clock time `HH:MM` used when `send_time_mode` is `fixed`."},"timezone":{"type":"string","description":"IANA timezone that overrides the resolved cascade (contact, sequence, account) for this step. Absent means the cascade decides."},"button":{"type":"object","description":"Optional call-to-action rendered as a native button by the channels that support one (WhatsApp Cloud as an interactive `cta_url`, WhatsApp Web as a buttons message, the API channel as `cta_buttons`); on any other channel only the link written in the body ships. Both fields go through the same Liquid rendering as the message body. Both are required - a half-filled button is dropped rather than sent, because the gateway would reject the whole message.","properties":{"text":{"type":"string","example":"Pagar agora","description":"Button caption."},"url":{"type":"string","example":"https://app.example/p/{{ contact.identifier }}","description":"Destination link; may contain Liquid, resolved per contact at send time."}}}}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}},"example":{"payload":{"id":1,"follow_up_sequence_id":1,"follow_up_template_id":1,"position":1,"name":"Sample Name","delay_value":149.9,"delay_unit":"minutes","channel":"auto","content_type":"text","message_template":"sample message template","compose_mode":"static","ai_intent":"sample ai intent","branch_conditions":"sample branch conditions","actions":"sample actions","skip_conditions":"sample skip conditions","whatsapp_template":"sample whatsapp template","settings":{"send_time_mode":"inherit","send_at_local":"09:30","timezone":"America/Sao_Paulo","button":{"text":"Pagar agora","url":"https://app.example/p/{{ contact.identifier }}"}},"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"sequence_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"position":{"type":"integer"},"delay_value":{"type":"number"},"delay_unit":{"type":"string","enum":["minutes","hours","days","business_days"]},"channel":{"type":"string","enum":["auto","same_conversation","email","sms","whatsapp"]},"content_type":{"type":"string","enum":["text","template","rich"]},"message_template":{"type":"string"},"compose_mode":{"type":"string","enum":["static","ai_assisted","ai_full"]},"ai_intent":{"type":"string"},"follow_up_template_id":{"type":"integer"},"whatsapp_template":{"type":"object","additionalProperties":true,"description":"Free-form object."}},"required":["position"]},"example":{"name":"Sample Name","position":1,"delay_value":149.9,"delay_unit":"minutes","channel":"auto","content_type":"text","message_template":"sample message template","compose_mode":"static","ai_intent":"sample ai intent","follow_up_template_id":1,"whatsapp_template":{}}}}}}},"/api/v1/accounts/{account_id}/follow_up/sequences/{sequence_id}/steps/{id}":{"patch":{"tags":["Follow-up"],"operationId":"auto_patch_api_v1_accounts_account_id_follow_up_sequences_sequence_id_steps_id","summary":"Update steps","description":"Updates the step identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"follow_up_sequence_id":{"type":"integer"},"follow_up_template_id":{"type":"integer"},"position":{"type":"integer"},"name":{"type":"string"},"delay_value":{"type":"number"},"delay_unit":{"type":"string","enum":["minutes","hours","days","business_days"]},"channel":{"type":"string","enum":["auto","same_conversation","email","sms","whatsapp"]},"content_type":{"type":"string","enum":["text","template","rich"]},"message_template":{"type":"string"},"compose_mode":{"type":"string","enum":["static","ai_assisted","ai_full"]},"ai_intent":{"type":"string"},"branch_conditions":{"type":"string"},"actions":{"type":"string"},"skip_conditions":{"type":"string"},"whatsapp_template":{"type":"string"},"settings":{"type":"object","additionalProperties":true,"description":"Per-step overrides. Scheduling keys pin when the step sends; `button` adds an optional native call-to-action to the step's own message inside the 24h window (outside it, the link travels in the WhatsApp template's URL button instead). A key is written only when it overrides the default, so an all-inherit step with no button stores `{}`.","properties":{"send_time_mode":{"type":"string","enum":["inherit","fixed"],"description":"`fixed` pins the step to `send_at_local` in the resolved timezone; `inherit` (the default, stored as no key at all) lets the step fire as soon as its delay elapses."},"send_at_local":{"type":"string","example":"09:30","description":"Local wall-clock time `HH:MM` used when `send_time_mode` is `fixed`."},"timezone":{"type":"string","description":"IANA timezone that overrides the resolved cascade (contact, sequence, account) for this step. Absent means the cascade decides."},"button":{"type":"object","description":"Optional call-to-action rendered as a native button by the channels that support one (WhatsApp Cloud as an interactive `cta_url`, WhatsApp Web as a buttons message, the API channel as `cta_buttons`); on any other channel only the link written in the body ships. Both fields go through the same Liquid rendering as the message body. Both are required - a half-filled button is dropped rather than sent, because the gateway would reject the whole message.","properties":{"text":{"type":"string","example":"Pagar agora","description":"Button caption."},"url":{"type":"string","example":"https://app.example/p/{{ contact.identifier }}","description":"Destination link; may contain Liquid, resolved per contact at send time."}}}}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}},"example":{"payload":{"id":1,"follow_up_sequence_id":1,"follow_up_template_id":1,"position":1,"name":"Sample Name","delay_value":149.9,"delay_unit":"minutes","channel":"auto","content_type":"text","message_template":"sample message template","compose_mode":"static","ai_intent":"sample ai intent","branch_conditions":"sample branch conditions","actions":"sample actions","skip_conditions":"sample skip conditions","whatsapp_template":"sample whatsapp template","settings":{"send_time_mode":"inherit","send_at_local":"09:30","timezone":"America/Sao_Paulo","button":{"text":"Pagar agora","url":"https://app.example/p/{{ contact.identifier }}"}},"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"sequence_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"position":{"type":"integer"},"delay_value":{"type":"number"},"delay_unit":{"type":"string","enum":["minutes","hours","days","business_days"]},"channel":{"type":"string","enum":["auto","same_conversation","email","sms","whatsapp"]},"content_type":{"type":"string","enum":["text","template","rich"]},"message_template":{"type":"string"},"compose_mode":{"type":"string","enum":["static","ai_assisted","ai_full"]},"ai_intent":{"type":"string"},"follow_up_template_id":{"type":"integer"},"whatsapp_template":{"type":"object","additionalProperties":true,"description":"Free-form object."}}},"example":{"name":"Sample Name","position":1,"delay_value":149.9,"delay_unit":"minutes","channel":"auto","content_type":"text","message_template":"sample message template","compose_mode":"static","ai_intent":"sample ai intent","follow_up_template_id":1,"whatsapp_template":{}}}}}},"put":{"tags":["Follow-up"],"operationId":"auto_put_api_v1_accounts_account_id_follow_up_sequences_sequence_id_steps_id","summary":"Update steps","description":"Updates the step identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"follow_up_sequence_id":{"type":"integer"},"follow_up_template_id":{"type":"integer"},"position":{"type":"integer"},"name":{"type":"string"},"delay_value":{"type":"number"},"delay_unit":{"type":"string","enum":["minutes","hours","days","business_days"]},"channel":{"type":"string","enum":["auto","same_conversation","email","sms","whatsapp"]},"content_type":{"type":"string","enum":["text","template","rich"]},"message_template":{"type":"string"},"compose_mode":{"type":"string","enum":["static","ai_assisted","ai_full"]},"ai_intent":{"type":"string"},"branch_conditions":{"type":"string"},"actions":{"type":"string"},"skip_conditions":{"type":"string"},"whatsapp_template":{"type":"string"},"settings":{"type":"object","additionalProperties":true,"description":"Per-step overrides. Scheduling keys pin when the step sends; `button` adds an optional native call-to-action to the step's own message inside the 24h window (outside it, the link travels in the WhatsApp template's URL button instead). A key is written only when it overrides the default, so an all-inherit step with no button stores `{}`.","properties":{"send_time_mode":{"type":"string","enum":["inherit","fixed"],"description":"`fixed` pins the step to `send_at_local` in the resolved timezone; `inherit` (the default, stored as no key at all) lets the step fire as soon as its delay elapses."},"send_at_local":{"type":"string","example":"09:30","description":"Local wall-clock time `HH:MM` used when `send_time_mode` is `fixed`."},"timezone":{"type":"string","description":"IANA timezone that overrides the resolved cascade (contact, sequence, account) for this step. Absent means the cascade decides."},"button":{"type":"object","description":"Optional call-to-action rendered as a native button by the channels that support one (WhatsApp Cloud as an interactive `cta_url`, WhatsApp Web as a buttons message, the API channel as `cta_buttons`); on any other channel only the link written in the body ships. Both fields go through the same Liquid rendering as the message body. Both are required - a half-filled button is dropped rather than sent, because the gateway would reject the whole message.","properties":{"text":{"type":"string","example":"Pagar agora","description":"Button caption."},"url":{"type":"string","example":"https://app.example/p/{{ contact.identifier }}","description":"Destination link; may contain Liquid, resolved per contact at send time."}}}}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}},"example":{"payload":{"id":1,"follow_up_sequence_id":1,"follow_up_template_id":1,"position":1,"name":"Sample Name","delay_value":149.9,"delay_unit":"minutes","channel":"auto","content_type":"text","message_template":"sample message template","compose_mode":"static","ai_intent":"sample ai intent","branch_conditions":"sample branch conditions","actions":"sample actions","skip_conditions":"sample skip conditions","whatsapp_template":"sample whatsapp template","settings":{"send_time_mode":"inherit","send_at_local":"09:30","timezone":"America/Sao_Paulo","button":{"text":"Pagar agora","url":"https://app.example/p/{{ contact.identifier }}"}},"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"sequence_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"position":{"type":"integer"},"delay_value":{"type":"number"},"delay_unit":{"type":"string","enum":["minutes","hours","days","business_days"]},"channel":{"type":"string","enum":["auto","same_conversation","email","sms","whatsapp"]},"content_type":{"type":"string","enum":["text","template","rich"]},"message_template":{"type":"string"},"compose_mode":{"type":"string","enum":["static","ai_assisted","ai_full"]},"ai_intent":{"type":"string"},"follow_up_template_id":{"type":"integer"},"whatsapp_template":{"type":"object","additionalProperties":true,"description":"Free-form object."}}},"example":{"name":"Sample Name","position":1,"delay_value":149.9,"delay_unit":"minutes","channel":"auto","content_type":"text","message_template":"sample message template","compose_mode":"static","ai_intent":"sample ai intent","follow_up_template_id":1,"whatsapp_template":{}}}}}},"delete":{"tags":["Follow-up"],"operationId":"auto_delete_api_v1_accounts_account_id_follow_up_sequences_sequence_id_steps_id","summary":"Delete steps","description":"Deletes the step identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Success (no content)"},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"sequence_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/follow_up/sequences":{"get":{"tags":["Follow-up"],"operationId":"auto_get_api_v1_accounts_account_id_follow_up_sequences","summary":"List sequences","description":"Returns the list of sequences visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"status":{"type":"string","enum":["draft","active","paused","archived"]},"trigger_type":{"type":"string","enum":["manual","event","inactivity","schedule","ai_proposed"]},"trigger_event":{"type":"string"},"target_type":{"type":"string","enum":["contact","conversation","crm_item","calendar_event","payment_charge"]},"published_version_id":{"type":"integer"},"activated_at":{"type":"string","format":"date-time"},"inactivity_watermark_at":{"type":"string","format":"date-time"},"inactivity_backfill_policy":{"type":"string","enum":["future_only","explicit_backfill"]},"inactivity_backfill_confirmed_at":{"type":"string","format":"date-time"},"trigger_conditions":{"type":"string"},"exit_conditions":{"type":"string"},"ai_config":{"type":"string"},"settings":{"type":"string"},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"steps_count":{"type":"integer"},"enrollments_count":{"type":"integer"},"archived_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"steps":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"follow_up_sequence_id":{"type":"integer"},"follow_up_template_id":{"type":"integer"},"position":{"type":"integer"},"name":{"type":"string"},"delay_value":{"type":"number"},"delay_unit":{"type":"string","enum":["minutes","hours","days","business_days"]},"channel":{"type":"string","enum":["auto","same_conversation","email","sms","whatsapp"]},"content_type":{"type":"string","enum":["text","template","rich"]},"message_template":{"type":"string"},"compose_mode":{"type":"string","enum":["static","ai_assisted","ai_full"]},"ai_intent":{"type":"string"},"branch_conditions":{"type":"string"},"actions":{"type":"string"},"skip_conditions":{"type":"string"},"whatsapp_template":{"type":"string"},"settings":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}}}},"meta":{"type":"object","properties":{"trigger_events":{"type":"string"},"goal_events":{"type":"string"},"count":{"type":"integer"},"current_page":{"type":"string"},"total_pages":{"type":"string"},"per_page":{"type":"string"},"has_more":{"type":"boolean"}}}}},"example":{"payload":[{"id":1,"account_id":1,"name":"Sample Name","description":"A short description.","status":"draft","trigger_type":"manual","trigger_event":"sample trigger event","target_type":"contact","published_version_id":1,"activated_at":"2026-01-15T10:30:00.000Z","inactivity_watermark_at":"2026-01-15T10:30:00.000Z","inactivity_backfill_policy":"future_only","inactivity_backfill_confirmed_at":"2026-01-15T10:30:00.000Z","trigger_conditions":"sample trigger conditions","exit_conditions":"sample exit conditions","ai_config":"sample ai config","settings":"sample settings","custom_attributes":{},"steps_count":5,"enrollments_count":5,"archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","steps":[{"id":1,"follow_up_sequence_id":1,"follow_up_template_id":1,"position":1,"name":"Sample Name","delay_value":149.9,"delay_unit":"minutes","channel":"auto","content_type":"text","message_template":"sample message template","compose_mode":"static","ai_intent":"sample ai intent","branch_conditions":"sample branch conditions","actions":"sample actions","skip_conditions":"sample skip conditions","whatsapp_template":"sample whatsapp template","settings":"sample settings","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}]}],"meta":{"trigger_events":"sample trigger events","goal_events":"sample goal events","count":5,"current_page":"sample current page","total_pages":"sample total pages","per_page":"sample per page","has_more":true}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."}]},"post":{"tags":["Follow-up"],"operationId":"auto_post_api_v1_accounts_account_id_follow_up_sequences","summary":"Create sequences","description":"Creates a follow-up sequence. exit_conditions.on_crm_lost is an optional boolean that ends enrollments linked to a lost deal in the same account. exit_conditions.on_contact_labels is an optional array of exact contact label names that end the enrollment. These conditions are checked before delivery, after AI composition, and at draft approval. AI composition must return a structured send, skip or exit decision; invalid output is never dispatched as customer text.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"status":{"type":"string","enum":["draft","active","paused","archived"]},"trigger_type":{"type":"string","enum":["manual","event","inactivity","schedule","ai_proposed"]},"trigger_event":{"type":"string"},"target_type":{"type":"string","enum":["contact","conversation","crm_item","calendar_event","payment_charge"]},"published_version_id":{"type":"integer"},"activated_at":{"type":"string","format":"date-time"},"inactivity_watermark_at":{"type":"string","format":"date-time"},"inactivity_backfill_policy":{"type":"string","enum":["future_only","explicit_backfill"]},"inactivity_backfill_confirmed_at":{"type":"string","format":"date-time"},"trigger_conditions":{"type":"string"},"exit_conditions":{"type":"string"},"ai_config":{"type":"string"},"settings":{"type":"string"},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"steps_count":{"type":"integer"},"enrollments_count":{"type":"integer"},"archived_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"steps":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"follow_up_sequence_id":{"type":"integer"},"follow_up_template_id":{"type":"integer"},"position":{"type":"integer"},"name":{"type":"string"},"delay_value":{"type":"number"},"delay_unit":{"type":"string","enum":["minutes","hours","days","business_days"]},"channel":{"type":"string","enum":["auto","same_conversation","email","sms","whatsapp"]},"content_type":{"type":"string","enum":["text","template","rich"]},"message_template":{"type":"string"},"compose_mode":{"type":"string","enum":["static","ai_assisted","ai_full"]},"ai_intent":{"type":"string"},"branch_conditions":{"type":"string"},"actions":{"type":"string"},"skip_conditions":{"type":"string"},"whatsapp_template":{"type":"string"},"settings":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}}}}},"example":{"payload":{"id":1,"account_id":1,"name":"Sample Name","description":"A short description.","status":"draft","trigger_type":"manual","trigger_event":"sample trigger event","target_type":"contact","published_version_id":1,"activated_at":"2026-01-15T10:30:00.000Z","inactivity_watermark_at":"2026-01-15T10:30:00.000Z","inactivity_backfill_policy":"future_only","inactivity_backfill_confirmed_at":"2026-01-15T10:30:00.000Z","trigger_conditions":"sample trigger conditions","exit_conditions":"sample exit conditions","ai_config":"sample ai config","settings":"sample settings","custom_attributes":{},"steps_count":5,"enrollments_count":5,"archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","steps":[{"id":1,"follow_up_sequence_id":1,"follow_up_template_id":1,"position":1,"name":"Sample Name","delay_value":149.9,"delay_unit":"minutes","channel":"auto","content_type":"text","message_template":"sample message template","compose_mode":"static","ai_intent":"sample ai intent","branch_conditions":"sample branch conditions","actions":"sample actions","skip_conditions":"sample skip conditions","whatsapp_template":"sample whatsapp template","settings":"sample settings","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"status":{"type":"string","enum":["draft","active","paused","archived"]},"trigger_type":{"type":"string","enum":["manual","event","inactivity","schedule","ai_proposed"]},"trigger_event":{"type":"string","enum":["new_follower","new_comment","mention","follower_milestone","scheduled"]},"target_type":{"type":"string","enum":["contact","conversation","crm_item","calendar_event","payment_charge"]},"exit_conditions":{"type":"object","description":"Live exit rules checked before delivery and draft approval.","properties":{"on_reply":{"type":"boolean","default":true},"on_resolved":{"type":"boolean"},"on_crm_lost":{"type":"boolean","description":"Exit when the linked deal in this account is lost."},"on_contact_labels":{"type":"array","items":{"type":"string"},"description":"Exact contact label names that stop the enrollment."},"goal_event":{"type":"string","enum":["","payment_charge.paid","crm_item.won","calendar_event.booked","calendar_event.completed"]}}}},"required":["name"]},"example":{"name":"Sample Name","description":"A short description.","status":"draft","trigger_type":"manual","trigger_event":"new_follower","target_type":"contact","exit_conditions":{"on_reply":true,"on_resolved":true,"on_crm_lost":true,"on_contact_labels":["sample on contact label"],"goal_event":""}}}}}}},"/api/v1/accounts/{account_id}/follow_up/sequences/{id}":{"get":{"tags":["Follow-up"],"operationId":"auto_get_api_v1_accounts_account_id_follow_up_sequences_id","summary":"Get sequences","description":"Returns the sequence identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"status":{"type":"string","enum":["draft","active","paused","archived"]},"trigger_type":{"type":"string","enum":["manual","event","inactivity","schedule","ai_proposed"]},"trigger_event":{"type":"string"},"target_type":{"type":"string","enum":["contact","conversation","crm_item","calendar_event","payment_charge"]},"published_version_id":{"type":"integer"},"activated_at":{"type":"string","format":"date-time"},"inactivity_watermark_at":{"type":"string","format":"date-time"},"inactivity_backfill_policy":{"type":"string","enum":["future_only","explicit_backfill"]},"inactivity_backfill_confirmed_at":{"type":"string","format":"date-time"},"trigger_conditions":{"type":"string"},"exit_conditions":{"type":"string"},"ai_config":{"type":"string"},"settings":{"type":"string"},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"steps_count":{"type":"integer"},"enrollments_count":{"type":"integer"},"archived_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"steps":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"follow_up_sequence_id":{"type":"integer"},"follow_up_template_id":{"type":"integer"},"position":{"type":"integer"},"name":{"type":"string"},"delay_value":{"type":"number"},"delay_unit":{"type":"string","enum":["minutes","hours","days","business_days"]},"channel":{"type":"string","enum":["auto","same_conversation","email","sms","whatsapp"]},"content_type":{"type":"string","enum":["text","template","rich"]},"message_template":{"type":"string"},"compose_mode":{"type":"string","enum":["static","ai_assisted","ai_full"]},"ai_intent":{"type":"string"},"branch_conditions":{"type":"string"},"actions":{"type":"string"},"skip_conditions":{"type":"string"},"whatsapp_template":{"type":"string"},"settings":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}}}}},"example":{"payload":{"id":1,"account_id":1,"name":"Sample Name","description":"A short description.","status":"draft","trigger_type":"manual","trigger_event":"sample trigger event","target_type":"contact","published_version_id":1,"activated_at":"2026-01-15T10:30:00.000Z","inactivity_watermark_at":"2026-01-15T10:30:00.000Z","inactivity_backfill_policy":"future_only","inactivity_backfill_confirmed_at":"2026-01-15T10:30:00.000Z","trigger_conditions":"sample trigger conditions","exit_conditions":"sample exit conditions","ai_config":"sample ai config","settings":"sample settings","custom_attributes":{},"steps_count":5,"enrollments_count":5,"archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","steps":[{"id":1,"follow_up_sequence_id":1,"follow_up_template_id":1,"position":1,"name":"Sample Name","delay_value":149.9,"delay_unit":"minutes","channel":"auto","content_type":"text","message_template":"sample message template","compose_mode":"static","ai_intent":"sample ai intent","branch_conditions":"sample branch conditions","actions":"sample actions","skip_conditions":"sample skip conditions","whatsapp_template":"sample whatsapp template","settings":"sample settings","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]},"patch":{"tags":["Follow-up"],"operationId":"auto_patch_api_v1_accounts_account_id_follow_up_sequences_id","summary":"Update sequences","description":"Updates a follow-up sequence. exit_conditions.on_crm_lost is an optional boolean that ends enrollments linked to a lost deal in the same account. exit_conditions.on_contact_labels is an optional array of exact contact label names that end the enrollment. These conditions are checked before delivery, after AI composition, and at draft approval. AI composition must return a structured send, skip or exit decision; invalid output is never dispatched as customer text.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"status":{"type":"string","enum":["draft","active","paused","archived"]},"trigger_type":{"type":"string","enum":["manual","event","inactivity","schedule","ai_proposed"]},"trigger_event":{"type":"string"},"target_type":{"type":"string","enum":["contact","conversation","crm_item","calendar_event","payment_charge"]},"published_version_id":{"type":"integer"},"activated_at":{"type":"string","format":"date-time"},"inactivity_watermark_at":{"type":"string","format":"date-time"},"inactivity_backfill_policy":{"type":"string","enum":["future_only","explicit_backfill"]},"inactivity_backfill_confirmed_at":{"type":"string","format":"date-time"},"trigger_conditions":{"type":"string"},"exit_conditions":{"type":"string"},"ai_config":{"type":"string"},"settings":{"type":"string"},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"steps_count":{"type":"integer"},"enrollments_count":{"type":"integer"},"archived_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"steps":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"follow_up_sequence_id":{"type":"integer"},"follow_up_template_id":{"type":"integer"},"position":{"type":"integer"},"name":{"type":"string"},"delay_value":{"type":"number"},"delay_unit":{"type":"string","enum":["minutes","hours","days","business_days"]},"channel":{"type":"string","enum":["auto","same_conversation","email","sms","whatsapp"]},"content_type":{"type":"string","enum":["text","template","rich"]},"message_template":{"type":"string"},"compose_mode":{"type":"string","enum":["static","ai_assisted","ai_full"]},"ai_intent":{"type":"string"},"branch_conditions":{"type":"string"},"actions":{"type":"string"},"skip_conditions":{"type":"string"},"whatsapp_template":{"type":"string"},"settings":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}}}}},"example":{"payload":{"id":1,"account_id":1,"name":"Sample Name","description":"A short description.","status":"draft","trigger_type":"manual","trigger_event":"sample trigger event","target_type":"contact","published_version_id":1,"activated_at":"2026-01-15T10:30:00.000Z","inactivity_watermark_at":"2026-01-15T10:30:00.000Z","inactivity_backfill_policy":"future_only","inactivity_backfill_confirmed_at":"2026-01-15T10:30:00.000Z","trigger_conditions":"sample trigger conditions","exit_conditions":"sample exit conditions","ai_config":"sample ai config","settings":"sample settings","custom_attributes":{},"steps_count":5,"enrollments_count":5,"archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","steps":[{"id":1,"follow_up_sequence_id":1,"follow_up_template_id":1,"position":1,"name":"Sample Name","delay_value":149.9,"delay_unit":"minutes","channel":"auto","content_type":"text","message_template":"sample message template","compose_mode":"static","ai_intent":"sample ai intent","branch_conditions":"sample branch conditions","actions":"sample actions","skip_conditions":"sample skip conditions","whatsapp_template":"sample whatsapp template","settings":"sample settings","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"status":{"type":"string","enum":["draft","active","paused","archived"]},"trigger_type":{"type":"string","enum":["manual","event","inactivity","schedule","ai_proposed"]},"trigger_event":{"type":"string","enum":["new_follower","new_comment","mention","follower_milestone","scheduled"]},"target_type":{"type":"string","enum":["contact","conversation","crm_item","calendar_event","payment_charge"]},"exit_conditions":{"type":"object","description":"Live exit rules checked before delivery and draft approval.","properties":{"on_reply":{"type":"boolean","default":true},"on_resolved":{"type":"boolean"},"on_crm_lost":{"type":"boolean","description":"Exit when the linked deal in this account is lost."},"on_contact_labels":{"type":"array","items":{"type":"string"},"description":"Exact contact label names that stop the enrollment."},"goal_event":{"type":"string","enum":["","payment_charge.paid","crm_item.won","calendar_event.booked","calendar_event.completed"]}}}}},"example":{"name":"Sample Name","description":"A short description.","status":"draft","trigger_type":"manual","trigger_event":"new_follower","target_type":"contact","exit_conditions":{"on_reply":true,"on_resolved":true,"on_crm_lost":true,"on_contact_labels":["sample on contact label"],"goal_event":""}}}}}},"put":{"tags":["Follow-up"],"operationId":"auto_put_api_v1_accounts_account_id_follow_up_sequences_id","summary":"Update sequences","description":"Updates a follow-up sequence. exit_conditions.on_crm_lost is an optional boolean that ends enrollments linked to a lost deal in the same account. exit_conditions.on_contact_labels is an optional array of exact contact label names that end the enrollment. These conditions are checked before delivery, after AI composition, and at draft approval. AI composition must return a structured send, skip or exit decision; invalid output is never dispatched as customer text.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"status":{"type":"string","enum":["draft","active","paused","archived"]},"trigger_type":{"type":"string","enum":["manual","event","inactivity","schedule","ai_proposed"]},"trigger_event":{"type":"string"},"target_type":{"type":"string","enum":["contact","conversation","crm_item","calendar_event","payment_charge"]},"published_version_id":{"type":"integer"},"activated_at":{"type":"string","format":"date-time"},"inactivity_watermark_at":{"type":"string","format":"date-time"},"inactivity_backfill_policy":{"type":"string","enum":["future_only","explicit_backfill"]},"inactivity_backfill_confirmed_at":{"type":"string","format":"date-time"},"trigger_conditions":{"type":"string"},"exit_conditions":{"type":"string"},"ai_config":{"type":"string"},"settings":{"type":"string"},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"steps_count":{"type":"integer"},"enrollments_count":{"type":"integer"},"archived_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"steps":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"follow_up_sequence_id":{"type":"integer"},"follow_up_template_id":{"type":"integer"},"position":{"type":"integer"},"name":{"type":"string"},"delay_value":{"type":"number"},"delay_unit":{"type":"string","enum":["minutes","hours","days","business_days"]},"channel":{"type":"string","enum":["auto","same_conversation","email","sms","whatsapp"]},"content_type":{"type":"string","enum":["text","template","rich"]},"message_template":{"type":"string"},"compose_mode":{"type":"string","enum":["static","ai_assisted","ai_full"]},"ai_intent":{"type":"string"},"branch_conditions":{"type":"string"},"actions":{"type":"string"},"skip_conditions":{"type":"string"},"whatsapp_template":{"type":"string"},"settings":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}}}}},"example":{"payload":{"id":1,"account_id":1,"name":"Sample Name","description":"A short description.","status":"draft","trigger_type":"manual","trigger_event":"sample trigger event","target_type":"contact","published_version_id":1,"activated_at":"2026-01-15T10:30:00.000Z","inactivity_watermark_at":"2026-01-15T10:30:00.000Z","inactivity_backfill_policy":"future_only","inactivity_backfill_confirmed_at":"2026-01-15T10:30:00.000Z","trigger_conditions":"sample trigger conditions","exit_conditions":"sample exit conditions","ai_config":"sample ai config","settings":"sample settings","custom_attributes":{},"steps_count":5,"enrollments_count":5,"archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","steps":[{"id":1,"follow_up_sequence_id":1,"follow_up_template_id":1,"position":1,"name":"Sample Name","delay_value":149.9,"delay_unit":"minutes","channel":"auto","content_type":"text","message_template":"sample message template","compose_mode":"static","ai_intent":"sample ai intent","branch_conditions":"sample branch conditions","actions":"sample actions","skip_conditions":"sample skip conditions","whatsapp_template":"sample whatsapp template","settings":"sample settings","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"status":{"type":"string","enum":["draft","active","paused","archived"]},"trigger_type":{"type":"string","enum":["manual","event","inactivity","schedule","ai_proposed"]},"trigger_event":{"type":"string","enum":["new_follower","new_comment","mention","follower_milestone","scheduled"]},"target_type":{"type":"string","enum":["contact","conversation","crm_item","calendar_event","payment_charge"]},"exit_conditions":{"type":"object","description":"Live exit rules checked before delivery and draft approval.","properties":{"on_reply":{"type":"boolean","default":true},"on_resolved":{"type":"boolean"},"on_crm_lost":{"type":"boolean","description":"Exit when the linked deal in this account is lost."},"on_contact_labels":{"type":"array","items":{"type":"string"},"description":"Exact contact label names that stop the enrollment."},"goal_event":{"type":"string","enum":["","payment_charge.paid","crm_item.won","calendar_event.booked","calendar_event.completed"]}}}}},"example":{"name":"Sample Name","description":"A short description.","status":"draft","trigger_type":"manual","trigger_event":"new_follower","target_type":"contact","exit_conditions":{"on_reply":true,"on_resolved":true,"on_crm_lost":true,"on_contact_labels":["sample on contact label"],"goal_event":""}}}}}},"delete":{"tags":["Follow-up"],"operationId":"auto_delete_api_v1_accounts_account_id_follow_up_sequences_id","summary":"Delete sequences","description":"Deletes the sequence identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Success (no content)"},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/follow_up/enrollments/{id}/cancel":{"post":{"tags":["Follow-up"],"operationId":"auto_post_api_v1_accounts_account_id_follow_up_enrollments_id_cancel","summary":"Cancel enrollments","description":"Performs the cancel operation on the targeted enrollment resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"follow_up_sequence_id":{"type":"integer"},"follow_up_sequence_version_id":{"type":"integer"},"sequence_name":{"type":["string","null"]},"contact_id":{"type":"integer"},"conversation_id":{"type":"integer"},"crm_item_id":{"type":"integer"},"calendar_event_id":{"type":"integer"},"payments_charge_id":{"type":"integer"},"assignee_id":{"type":"integer"},"status":{"type":"string","enum":["active","paused","completed","exited","failed"]},"current_step_position":{"type":"integer"},"next_run_at":{"type":"string","format":"date-time"},"exit_reason":{"type":"string"},"timezone":{"type":"string","description":"IANA timezone identifier (e.g. \"America/Sao_Paulo\", \"UTC\"). Rails timezone names are also accepted on input; an unrecognized value is ignored in favor of the next fallback.","example":"America/Sao_Paulo"},"failure_reason":{"type":"string"},"enrolled_via":{"type":"string","enum":["manual","automation","macro","flow","trigger","maestro","api"]},"enrolled_by_id":{"type":"integer"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"step_runs":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"position":{"type":"integer"},"status":{"type":"string","enum":["active","paused","completed","exited","failed"]},"compose_mode":{"type":"string","enum":["static","ai_assisted","ai_full"]},"message_id":{"type":"integer"},"scheduled_at":{"type":"string","format":"date-time"},"sent_at":{"type":"string","format":"date-time"},"replied_at":{"type":"string","format":"date-time"},"error":{"type":"string"},"skip_reason":{"type":"string"},"draft":{"type":"boolean"}}}}}}}},"example":{"payload":{"id":1,"account_id":1,"follow_up_sequence_id":1,"follow_up_sequence_version_id":1,"sequence_name":"sample sequence name","contact_id":1,"conversation_id":1,"crm_item_id":1,"calendar_event_id":1,"payments_charge_id":1,"assignee_id":1,"status":"active","current_step_position":1,"next_run_at":"2026-01-15T10:30:00.000Z","exit_reason":"sample exit reason","timezone":"America/Sao_Paulo","failure_reason":"sample failure reason","enrolled_via":"manual","enrolled_by_id":1,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","step_runs":[{"id":1,"position":1,"status":"active","compose_mode":"static","message_id":1,"scheduled_at":"2026-01-15T10:30:00.000Z","sent_at":"2026-01-15T10:30:00.000Z","replied_at":"2026-01-15T10:30:00.000Z","error":"sample error","skip_reason":"sample skip reason","draft":true}]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/follow_up/enrollments/{id}/pause":{"post":{"tags":["Follow-up"],"operationId":"auto_post_api_v1_accounts_account_id_follow_up_enrollments_id_pause","summary":"Pause enrollments","description":"Performs the pause operation on the targeted enrollment resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"follow_up_sequence_id":{"type":"integer"},"follow_up_sequence_version_id":{"type":"integer"},"sequence_name":{"type":["string","null"]},"contact_id":{"type":"integer"},"conversation_id":{"type":"integer"},"crm_item_id":{"type":"integer"},"calendar_event_id":{"type":"integer"},"payments_charge_id":{"type":"integer"},"assignee_id":{"type":"integer"},"status":{"type":"string","enum":["active","paused","completed","exited","failed"]},"current_step_position":{"type":"integer"},"next_run_at":{"type":"string","format":"date-time"},"exit_reason":{"type":"string"},"timezone":{"type":"string","description":"IANA timezone identifier (e.g. \"America/Sao_Paulo\", \"UTC\"). Rails timezone names are also accepted on input; an unrecognized value is ignored in favor of the next fallback.","example":"America/Sao_Paulo"},"failure_reason":{"type":"string"},"enrolled_via":{"type":"string","enum":["manual","automation","macro","flow","trigger","maestro","api"]},"enrolled_by_id":{"type":"integer"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"step_runs":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"position":{"type":"integer"},"status":{"type":"string","enum":["active","paused","completed","exited","failed"]},"compose_mode":{"type":"string","enum":["static","ai_assisted","ai_full"]},"message_id":{"type":"integer"},"scheduled_at":{"type":"string","format":"date-time"},"sent_at":{"type":"string","format":"date-time"},"replied_at":{"type":"string","format":"date-time"},"error":{"type":"string"},"skip_reason":{"type":"string"},"draft":{"type":"boolean"}}}}}}}},"example":{"payload":{"id":1,"account_id":1,"follow_up_sequence_id":1,"follow_up_sequence_version_id":1,"sequence_name":"sample sequence name","contact_id":1,"conversation_id":1,"crm_item_id":1,"calendar_event_id":1,"payments_charge_id":1,"assignee_id":1,"status":"active","current_step_position":1,"next_run_at":"2026-01-15T10:30:00.000Z","exit_reason":"sample exit reason","timezone":"America/Sao_Paulo","failure_reason":"sample failure reason","enrolled_via":"manual","enrolled_by_id":1,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","step_runs":[{"id":1,"position":1,"status":"active","compose_mode":"static","message_id":1,"scheduled_at":"2026-01-15T10:30:00.000Z","sent_at":"2026-01-15T10:30:00.000Z","replied_at":"2026-01-15T10:30:00.000Z","error":"sample error","skip_reason":"sample skip reason","draft":true}]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/follow_up/enrollments/{id}/resume":{"post":{"tags":["Follow-up"],"operationId":"auto_post_api_v1_accounts_account_id_follow_up_enrollments_id_resume","summary":"Resume enrollments","description":"Performs the resume operation on the targeted enrollment resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"follow_up_sequence_id":{"type":"integer"},"follow_up_sequence_version_id":{"type":"integer"},"sequence_name":{"type":["string","null"]},"contact_id":{"type":"integer"},"conversation_id":{"type":"integer"},"crm_item_id":{"type":"integer"},"calendar_event_id":{"type":"integer"},"payments_charge_id":{"type":"integer"},"assignee_id":{"type":"integer"},"status":{"type":"string","enum":["active","paused","completed","exited","failed"]},"current_step_position":{"type":"integer"},"next_run_at":{"type":"string","format":"date-time"},"exit_reason":{"type":"string"},"timezone":{"type":"string","description":"IANA timezone identifier (e.g. \"America/Sao_Paulo\", \"UTC\"). Rails timezone names are also accepted on input; an unrecognized value is ignored in favor of the next fallback.","example":"America/Sao_Paulo"},"failure_reason":{"type":"string"},"enrolled_via":{"type":"string","enum":["manual","automation","macro","flow","trigger","maestro","api"]},"enrolled_by_id":{"type":"integer"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"step_runs":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"position":{"type":"integer"},"status":{"type":"string","enum":["active","paused","completed","exited","failed"]},"compose_mode":{"type":"string","enum":["static","ai_assisted","ai_full"]},"message_id":{"type":"integer"},"scheduled_at":{"type":"string","format":"date-time"},"sent_at":{"type":"string","format":"date-time"},"replied_at":{"type":"string","format":"date-time"},"error":{"type":"string"},"skip_reason":{"type":"string"},"draft":{"type":"boolean"}}}}}}}},"example":{"payload":{"id":1,"account_id":1,"follow_up_sequence_id":1,"follow_up_sequence_version_id":1,"sequence_name":"sample sequence name","contact_id":1,"conversation_id":1,"crm_item_id":1,"calendar_event_id":1,"payments_charge_id":1,"assignee_id":1,"status":"active","current_step_position":1,"next_run_at":"2026-01-15T10:30:00.000Z","exit_reason":"sample exit reason","timezone":"America/Sao_Paulo","failure_reason":"sample failure reason","enrolled_via":"manual","enrolled_by_id":1,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","step_runs":[{"id":1,"position":1,"status":"active","compose_mode":"static","message_id":1,"scheduled_at":"2026-01-15T10:30:00.000Z","sent_at":"2026-01-15T10:30:00.000Z","replied_at":"2026-01-15T10:30:00.000Z","error":"sample error","skip_reason":"sample skip reason","draft":true}]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/follow_up/enrollments/{id}/skip":{"post":{"tags":["Follow-up"],"operationId":"auto_post_api_v1_accounts_account_id_follow_up_enrollments_id_skip","summary":"Skip enrollments","description":"Performs the skip operation on the targeted enrollment resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"follow_up_sequence_id":{"type":"integer"},"follow_up_sequence_version_id":{"type":"integer"},"sequence_name":{"type":["string","null"]},"contact_id":{"type":"integer"},"conversation_id":{"type":"integer"},"crm_item_id":{"type":"integer"},"calendar_event_id":{"type":"integer"},"payments_charge_id":{"type":"integer"},"assignee_id":{"type":"integer"},"status":{"type":"string","enum":["active","paused","completed","exited","failed"]},"current_step_position":{"type":"integer"},"next_run_at":{"type":"string","format":"date-time"},"exit_reason":{"type":"string"},"timezone":{"type":"string","description":"IANA timezone identifier (e.g. \"America/Sao_Paulo\", \"UTC\"). Rails timezone names are also accepted on input; an unrecognized value is ignored in favor of the next fallback.","example":"America/Sao_Paulo"},"failure_reason":{"type":"string"},"enrolled_via":{"type":"string","enum":["manual","automation","macro","flow","trigger","maestro","api"]},"enrolled_by_id":{"type":"integer"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"step_runs":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"position":{"type":"integer"},"status":{"type":"string","enum":["active","paused","completed","exited","failed"]},"compose_mode":{"type":"string","enum":["static","ai_assisted","ai_full"]},"message_id":{"type":"integer"},"scheduled_at":{"type":"string","format":"date-time"},"sent_at":{"type":"string","format":"date-time"},"replied_at":{"type":"string","format":"date-time"},"error":{"type":"string"},"skip_reason":{"type":"string"},"draft":{"type":"boolean"}}}}}}}},"example":{"payload":{"id":1,"account_id":1,"follow_up_sequence_id":1,"follow_up_sequence_version_id":1,"sequence_name":"sample sequence name","contact_id":1,"conversation_id":1,"crm_item_id":1,"calendar_event_id":1,"payments_charge_id":1,"assignee_id":1,"status":"active","current_step_position":1,"next_run_at":"2026-01-15T10:30:00.000Z","exit_reason":"sample exit reason","timezone":"America/Sao_Paulo","failure_reason":"sample failure reason","enrolled_via":"manual","enrolled_by_id":1,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","step_runs":[{"id":1,"position":1,"status":"active","compose_mode":"static","message_id":1,"scheduled_at":"2026-01-15T10:30:00.000Z","sent_at":"2026-01-15T10:30:00.000Z","replied_at":"2026-01-15T10:30:00.000Z","error":"sample error","skip_reason":"sample skip reason","draft":true}]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/follow_up/enrollments/{id}/events":{"get":{"tags":["Follow-up"],"operationId":"auto_get_api_v1_accounts_account_id_follow_up_enrollments_id_events","summary":"Events enrollments","description":"Performs the events operation on the targeted enrollment resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"event_type":{"type":"string","enum":["created","advanced","step_sent","step_skipped","step_failed","replied","paused","resumed","canceled","completed","exited","failed","draft_pending","draft_approved","draft_rejected"],"description":"What happened to the enrollment."},"from_status":{"type":"string","enum":["active","paused","completed","exited","failed"]},"to_status":{"type":"string","enum":["active","paused","completed","exited","failed"]},"user_id":{"type":"integer"},"occurred_at":{"type":"string","format":"date-time"},"metadata":{"type":"object","additionalProperties":true,"description":"Free-form metadata bag; the key set depends on the record and context."}}}},"meta":{"type":"object","properties":{"count":{"type":"integer"},"current_page":{"type":"string"},"total_pages":{"type":"string"},"has_more":{"type":"boolean"}}}}},"example":{"payload":[{"id":1,"event_type":"created","from_status":"active","to_status":"active","user_id":1,"occurred_at":"2026-01-15T10:30:00.000Z","metadata":{}}],"meta":{"count":5,"current_page":"sample current page","total_pages":"sample total pages","has_more":true}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page of enrollment events.","schema":{"type":"integer","default":1},"example":1}]}},"/api/v1/accounts/{account_id}/follow_up/enrollments/{id}/approve_draft":{"post":{"tags":["Follow-up"],"operationId":"auto_post_api_v1_accounts_account_id_follow_up_enrollments_id_approve_draft","summary":"Approve draft enrollments","description":"Performs the approve draft operation on the targeted enrollment resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"follow_up_sequence_id":{"type":"integer"},"follow_up_sequence_version_id":{"type":"integer"},"sequence_name":{"type":["string","null"]},"contact_id":{"type":"integer"},"conversation_id":{"type":"integer"},"crm_item_id":{"type":"integer"},"calendar_event_id":{"type":"integer"},"payments_charge_id":{"type":"integer"},"assignee_id":{"type":"integer"},"status":{"type":"string","enum":["active","paused","completed","exited","failed"]},"current_step_position":{"type":"integer"},"next_run_at":{"type":"string","format":"date-time"},"exit_reason":{"type":"string"},"timezone":{"type":"string","description":"IANA timezone identifier (e.g. \"America/Sao_Paulo\", \"UTC\"). Rails timezone names are also accepted on input; an unrecognized value is ignored in favor of the next fallback.","example":"America/Sao_Paulo"},"failure_reason":{"type":"string"},"enrolled_via":{"type":"string","enum":["manual","automation","macro","flow","trigger","maestro","api"]},"enrolled_by_id":{"type":"integer"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"step_runs":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"position":{"type":"integer"},"status":{"type":"string","enum":["active","paused","completed","exited","failed"]},"compose_mode":{"type":"string","enum":["static","ai_assisted","ai_full"]},"message_id":{"type":"integer"},"scheduled_at":{"type":"string","format":"date-time"},"sent_at":{"type":"string","format":"date-time"},"replied_at":{"type":"string","format":"date-time"},"error":{"type":"string"},"skip_reason":{"type":"string"},"draft":{"type":"boolean"}}}}}}}},"example":{"payload":{"id":1,"account_id":1,"follow_up_sequence_id":1,"follow_up_sequence_version_id":1,"sequence_name":"sample sequence name","contact_id":1,"conversation_id":1,"crm_item_id":1,"calendar_event_id":1,"payments_charge_id":1,"assignee_id":1,"status":"active","current_step_position":1,"next_run_at":"2026-01-15T10:30:00.000Z","exit_reason":"sample exit reason","timezone":"America/Sao_Paulo","failure_reason":"sample failure reason","enrolled_via":"manual","enrolled_by_id":1,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","step_runs":[{"id":1,"position":1,"status":"active","compose_mode":"static","message_id":1,"scheduled_at":"2026-01-15T10:30:00.000Z","sent_at":"2026-01-15T10:30:00.000Z","replied_at":"2026-01-15T10:30:00.000Z","error":"sample error","skip_reason":"sample skip reason","draft":true}]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"step_run_id":{"type":"integer"},"body":{"type":"string"}}},"example":{"step_run_id":1,"body":"Sample body text."}}}}}},"/api/v1/accounts/{account_id}/follow_up/enrollments/{id}/reject_draft":{"post":{"tags":["Follow-up"],"operationId":"auto_post_api_v1_accounts_account_id_follow_up_enrollments_id_reject_draft","summary":"Reject draft enrollments","description":"Performs the reject draft operation on the targeted enrollment resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"follow_up_sequence_id":{"type":"integer"},"follow_up_sequence_version_id":{"type":"integer"},"sequence_name":{"type":["string","null"]},"contact_id":{"type":"integer"},"conversation_id":{"type":"integer"},"crm_item_id":{"type":"integer"},"calendar_event_id":{"type":"integer"},"payments_charge_id":{"type":"integer"},"assignee_id":{"type":"integer"},"status":{"type":"string","enum":["active","paused","completed","exited","failed"]},"current_step_position":{"type":"integer"},"next_run_at":{"type":"string","format":"date-time"},"exit_reason":{"type":"string"},"timezone":{"type":"string","description":"IANA timezone identifier (e.g. \"America/Sao_Paulo\", \"UTC\"). Rails timezone names are also accepted on input; an unrecognized value is ignored in favor of the next fallback.","example":"America/Sao_Paulo"},"failure_reason":{"type":"string"},"enrolled_via":{"type":"string","enum":["manual","automation","macro","flow","trigger","maestro","api"]},"enrolled_by_id":{"type":"integer"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"step_runs":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"position":{"type":"integer"},"status":{"type":"string","enum":["active","paused","completed","exited","failed"]},"compose_mode":{"type":"string","enum":["static","ai_assisted","ai_full"]},"message_id":{"type":"integer"},"scheduled_at":{"type":"string","format":"date-time"},"sent_at":{"type":"string","format":"date-time"},"replied_at":{"type":"string","format":"date-time"},"error":{"type":"string"},"skip_reason":{"type":"string"},"draft":{"type":"boolean"}}}}}}}},"example":{"payload":{"id":1,"account_id":1,"follow_up_sequence_id":1,"follow_up_sequence_version_id":1,"sequence_name":"sample sequence name","contact_id":1,"conversation_id":1,"crm_item_id":1,"calendar_event_id":1,"payments_charge_id":1,"assignee_id":1,"status":"active","current_step_position":1,"next_run_at":"2026-01-15T10:30:00.000Z","exit_reason":"sample exit reason","timezone":"America/Sao_Paulo","failure_reason":"sample failure reason","enrolled_via":"manual","enrolled_by_id":1,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","step_runs":[{"id":1,"position":1,"status":"active","compose_mode":"static","message_id":1,"scheduled_at":"2026-01-15T10:30:00.000Z","sent_at":"2026-01-15T10:30:00.000Z","replied_at":"2026-01-15T10:30:00.000Z","error":"sample error","skip_reason":"sample skip reason","draft":true}]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"step_run_id":{"type":"integer"}}},"example":{"step_run_id":1}}}}}},"/api/v1/accounts/{account_id}/follow_up/enrollments/bulk":{"post":{"tags":["Follow-up"],"operationId":"auto_post_api_v1_accounts_account_id_follow_up_enrollments_bulk","summary":"Bulk enrollments","description":"Performs the bulk operation on the targeted enrollment resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"ids":{"type":"string"}}}}},"example":{"payload":{"ids":"sample ids"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"enrollment_ids":{"type":"array","items":{"type":"integer"}},"operation":{"type":"string"}}},"example":{"enrollment_ids":[1],"operation":"sample operation"}}}}}},"/api/v1/accounts/{account_id}/follow_up/enrollments/bulk_destroy":{"post":{"tags":["Follow-up"],"operationId":"auto_post_api_v1_accounts_account_id_follow_up_enrollments_bulk_destroy","summary":"Bulk destroy enrollments","description":"Performs the bulk destroy operation on the targeted enrollment resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"ids":{"type":"string"}}}}},"example":{"payload":{"ids":"sample ids"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"enrollment_ids":{"type":"array","items":{"type":"integer"}},"operation":{"type":"string"}}},"example":{"enrollment_ids":[1],"operation":"sample operation"}}}}}},"/api/v1/accounts/{account_id}/follow_up/enrollments/preview":{"post":{"tags":["Follow-up"],"operationId":"auto_post_api_v1_accounts_account_id_follow_up_enrollments_preview","summary":"Preview enrollments","description":"Performs the preview operation on the targeted enrollment resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"body":{"type":"string"}}}}},"example":{"payload":{"body":"Sample body text."}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"403":{"description":"API access is disabled for the account, the access role lacks follow_up_manage, the Follow-up feature is off, or the conversation whose contact would be previewed is not visible to the caller. Nothing is rendered on any of them.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Reason, by origin. \"API access is not enabled for this account\" when the account has the API off; feature_not_enabled when the Follow-up feature is off; forbidden both when the access role lacks follow_up_manage and when conversation visibility is denied. Not a closed set: inherited denials of this family are rendered by shared controller layers.","example":"forbidden"}},"required":["error"]},"examples":{"conversation_or_module_denied":{"summary":"Access role without follow_up_manage, or a conversation the caller cannot see","value":{"error":"forbidden"}},"feature_disabled":{"summary":"Follow-up feature off for the account","value":{"error":"feature_not_enabled"}},"api_access_disabled":{"summary":"Token-authenticated request on an account with the API off","value":{"error":"API access is not enabled for this account"}}}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"contact_id":{"type":"integer"},"body":{"type":"string"},"conversation_id":{"type":"integer"}}},"example":{"contact_id":1,"body":"Sample body text.","conversation_id":1}}}}}},"/api/v1/accounts/{account_id}/follow_up/enrollments/test_send":{"post":{"tags":["Follow-up"],"operationId":"auto_post_api_v1_accounts_account_id_follow_up_enrollments_test_send","summary":"Send a one-off Follow-up test message","description":"Renders a Follow-up message body through the Liquid template engine and sends the result as a real outgoing message into the chosen conversation, without creating an enrollment or persisting anything else. The template is evaluated against a throw-away enrollment bound to that conversation and its contact, so the same variables a live sequence would resolve are filled with that contact's real values. The message is attributed to the authenticated user. Use it to validate a step's copy end to end before publishing the sequence; use the preview endpoint instead when the rendered text should be returned rather than delivered. The response carries no body — a 200 means the message was created in the conversation. Requires the follow_ups feature and Follow-up enrollment authorization, plus visibility of the source and effective delivery conversations.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The rendered message was created in the target conversation. No response body is returned."},"401":{"description":"Unauthorized"},"404":{"description":"A record the request depends on no longer exists — most often the target conversation physically deleted between its resolution and delivery, which the builder detects when it reloads source and target under the lock. The message is not created.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Fixed text rendered by the shared request exception handler.","example":"Resource could not be found"}},"required":["error"]},"example":{"error":"Resource could not be found"}}}},"403":{"description":"API access is disabled for the account, the caller's access role does not grant the follow_up_manage permission, the follow_ups feature is disabled, or the source or effective delivery conversation is not visible to the caller. No message is created on any of them.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Reason, by origin. \"API access is not enabled for this account\" when the account has the API off; feature_not_enabled when the Follow-up feature is off; forbidden both when the access role lacks follow_up_manage and when source or delivery conversation visibility is denied. Not a closed set: inherited denials of this family are rendered by shared controller layers.","example":"forbidden"}},"required":["error"]},"examples":{"conversation_or_module_denied":{"summary":"Access role without follow_up_manage, or a conversation the caller cannot see","value":{"error":"forbidden"}},"feature_disabled":{"summary":"Follow-up feature off for the account","value":{"error":"feature_not_enabled"}},"api_access_disabled":{"summary":"Token-authenticated request on an account with the API off","value":{"error":"API access is not enabled for this account"}}}}}},"422":{"description":"No conversation could be resolved from conversation_id, or the rendered message failed validation and was not created, or the effective delivery conversation is unavailable or changed before delivery.","content":{"application/json":{"schema":{"oneOf":[{"type":"object","description":"Returned when conversation_id is missing or matches no conversation in the account.","properties":{"error":{"type":"string","description":"Machine-readable reason — the request named no resolvable target conversation.","enum":["conversation_required"],"example":"conversation_required"}},"required":["error"]},{"type":"object","description":"Standard validation failure returned when the rendered message could not be persisted.","properties":{"message":{"type":"string","description":"Human-readable validation errors, joined by commas.","example":"Content is too long (maximum is 150000 characters)"},"attributes":{"type":"array","description":"Names of the message attributes that failed validation.","items":{"type":"string","description":"An invalid attribute name.","example":"content"},"example":["content"]}},"required":["message","attributes"]},{"type":"object","description":"The effective delivery conversation is unavailable or changed before delivery, or the shared request exception handler rendered another translated 422 for this request. Open text, not a closed set.","properties":{"error":{"type":"string","description":"Human-readable message in the user's locale, falling back to the account locale.","not":{"enum":["conversation_required"]},"example":"This historical Web conversation is frozen. Continue from the current conversation for this contact."}},"required":["error"]}]},"examples":{"conversation_required":{"summary":"No conversation_id, or none that resolves in the account","value":{"error":"conversation_required"}},"delivery_conversation_unavailable":{"summary":"Frozen or changed delivery conversation, in the caller's locale","value":{"error":"This historical Web conversation is frozen. Continue from the current conversation for this contact."}},"message_validation":{"summary":"The rendered message failed validation and was not created","value":{"message":"Content is too long (maximum is 150000 characters)","attributes":["content"]}}}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"conversation_id":{"type":"integer","description":"Target conversation. Resolved by the account-scoped display id first (the number shown in the inbox) and, failing that, by the global conversation id. A request without it is rejected with 422 because there is nowhere to deliver the message.","example":1274},"body":{"type":"string","description":"Message body to render. May contain Liquid tags, which are resolved against the target conversation's contact before the message is sent.","example":"Hi {{ contact.name }}, just checking in about your quote."}},"required":["conversation_id"]},"example":{"conversation_id":1274,"body":"Hi {{ contact.name }}, just checking in about your quote."}}}}}},"/api/v1/accounts/{account_id}/follow_up/enrollments":{"get":{"tags":["Follow-up"],"operationId":"auto_get_api_v1_accounts_account_id_follow_up_enrollments","summary":"List enrollments","description":"Returns the list of enrollments visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"follow_up_sequence_id":{"type":"integer"},"follow_up_sequence_version_id":{"type":"integer"},"sequence_name":{"type":["string","null"]},"contact_id":{"type":"integer"},"conversation_id":{"type":"integer"},"crm_item_id":{"type":"integer"},"calendar_event_id":{"type":"integer"},"payments_charge_id":{"type":"integer"},"assignee_id":{"type":"integer"},"status":{"type":"string","enum":["active","paused","completed","exited","failed"]},"current_step_position":{"type":"integer"},"next_run_at":{"type":"string","format":"date-time"},"exit_reason":{"type":"string"},"timezone":{"type":"string","description":"IANA timezone identifier (e.g. \"America/Sao_Paulo\", \"UTC\"). Rails timezone names are also accepted on input; an unrecognized value is ignored in favor of the next fallback.","example":"America/Sao_Paulo"},"failure_reason":{"type":"string"},"enrolled_via":{"type":"string","enum":["manual","automation","macro","flow","trigger","maestro","api"]},"enrolled_by_id":{"type":"integer"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"step_runs":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"position":{"type":"integer"},"status":{"type":"string","enum":["active","paused","completed","exited","failed"]},"compose_mode":{"type":"string","enum":["static","ai_assisted","ai_full"]},"message_id":{"type":"integer"},"scheduled_at":{"type":"string","format":"date-time"},"sent_at":{"type":"string","format":"date-time"},"replied_at":{"type":"string","format":"date-time"},"error":{"type":"string"},"skip_reason":{"type":"string"},"draft":{"type":"boolean"}}}}}}},"meta":{"type":"object","properties":{"count":{"type":"integer"},"current_page":{"type":"string"},"total_pages":{"type":"string"},"per_page":{"type":"string"},"has_more":{"type":"boolean"}}}}},"example":{"payload":[{"id":1,"account_id":1,"follow_up_sequence_id":1,"follow_up_sequence_version_id":1,"sequence_name":"sample sequence name","contact_id":1,"conversation_id":1,"crm_item_id":1,"calendar_event_id":1,"payments_charge_id":1,"assignee_id":1,"status":"active","current_step_position":1,"next_run_at":"2026-01-15T10:30:00.000Z","exit_reason":"sample exit reason","timezone":"America/Sao_Paulo","failure_reason":"sample failure reason","enrolled_via":"manual","enrolled_by_id":1,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","step_runs":[{"id":1,"position":1,"status":"active","compose_mode":"static","message_id":1,"scheduled_at":"2026-01-15T10:30:00.000Z","sent_at":"2026-01-15T10:30:00.000Z","replied_at":"2026-01-15T10:30:00.000Z","error":"sample error","skip_reason":"sample skip reason","draft":true}]}],"meta":{"count":5,"current_page":"sample current page","total_pages":"sample total pages","per_page":"sample per page","has_more":true}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."}]},"post":{"tags":["Follow-up"],"operationId":"auto_post_api_v1_accounts_account_id_follow_up_enrollments","summary":"Create enrollments","description":"Creates a new enrollment from the request payload. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The created (or existing idempotent) enrollment."},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"403":{"description":"API access is disabled for the account, the access role lacks follow_up_manage, the Follow-up feature is off, or the conversation chosen for the enrollment is not visible to the caller. No enrollment is created on any of them.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Reason, by origin. \"API access is not enabled for this account\" when the account has the API off; feature_not_enabled when the Follow-up feature is off; forbidden both when the access role lacks follow_up_manage and when conversation visibility is denied. Not a closed set: inherited denials of this family are rendered by shared controller layers.","example":"forbidden"}},"required":["error"]},"examples":{"conversation_or_module_denied":{"summary":"Access role without follow_up_manage, or a conversation the caller cannot see","value":{"error":"forbidden"}},"feature_disabled":{"summary":"Follow-up feature off for the account","value":{"error":"feature_not_enabled"}},"api_access_disabled":{"summary":"Token-authenticated request on an account with the API off","value":{"error":"API access is not enabled for this account"}}}}}},"422":{"description":"The enrollment was rejected by a builder reason or failed record validation.","content":{"application/json":{"schema":{"oneOf":[{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","description":"Machine-readable builder rejection reason.","example":"sequence_not_published"}}},{"type":"object","additionalProperties":false,"required":["message","attributes"],"properties":{"message":{"type":"string","description":"Validation errors joined into one message."},"attributes":{"type":"array","description":"Names of the record attributes with validation errors.","items":{"type":"string"}}}}]},"examples":{"unpublished_sequence":{"summary":"The sequence has no published version","value":{"error":"sequence_not_published"}},"invalid_record":{"summary":"The enrollment record failed validation","value":{"message":"Contact must exist","attributes":["contact"]}}}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["sequence_id","contact_id"],"properties":{"sequence_id":{"type":"integer","description":"The published sequence to enroll into.","example":12},"contact_id":{"type":"integer","description":"The contact to enroll.","example":88},"conversation_id":{"type":["integer","null"],"description":"Optional conversation display_id/id to anchor the cadence.","example":3001},"crm_item_id":{"type":["integer","null"],"description":"Optional linked CRM deal.","example":77},"calendar_event_id":{"type":["integer","null"],"description":"Optional linked calendar event.","example":55},"payments_charge_id":{"type":["integer","null"],"description":"Optional linked charge.","example":91},"assignee_id":{"type":["integer","null"],"description":"Optional assignee user id.","example":7},"timezone":{"type":["string","null"],"description":"Optional IANA timezone stored on the enrollment; it outranks the AUTO chain (same rank as the contact timezone) while explicit step/sequence/inbox/account settings still win. An invalid value is ignored (logged), never breaking the enroll.","example":"America/Manaus"}}},"example":{"sequence_id":12,"contact_id":88,"timezone":"America/Manaus","conversation_id":3001,"crm_item_id":77,"calendar_event_id":55,"payments_charge_id":91,"assignee_id":7}}}}}},"/api/v1/accounts/{account_id}/follow_up/enrollments/{id}":{"get":{"tags":["Follow-up"],"operationId":"auto_get_api_v1_accounts_account_id_follow_up_enrollments_id","summary":"Get enrollments","description":"Returns the enrollment identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"follow_up_sequence_id":{"type":"integer"},"follow_up_sequence_version_id":{"type":"integer"},"sequence_name":{"type":["string","null"]},"contact_id":{"type":"integer"},"conversation_id":{"type":"integer"},"crm_item_id":{"type":"integer"},"calendar_event_id":{"type":"integer"},"payments_charge_id":{"type":"integer"},"assignee_id":{"type":"integer"},"status":{"type":"string","enum":["active","paused","completed","exited","failed"]},"current_step_position":{"type":"integer"},"next_run_at":{"type":"string","format":"date-time"},"exit_reason":{"type":"string"},"timezone":{"type":"string","description":"IANA timezone identifier (e.g. \"America/Sao_Paulo\", \"UTC\"). Rails timezone names are also accepted on input; an unrecognized value is ignored in favor of the next fallback.","example":"America/Sao_Paulo"},"failure_reason":{"type":"string"},"enrolled_via":{"type":"string","enum":["manual","automation","macro","flow","trigger","maestro","api"]},"enrolled_by_id":{"type":"integer"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"step_runs":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"position":{"type":"integer"},"status":{"type":"string","enum":["active","paused","completed","exited","failed"]},"compose_mode":{"type":"string","enum":["static","ai_assisted","ai_full"]},"message_id":{"type":"integer"},"scheduled_at":{"type":"string","format":"date-time"},"sent_at":{"type":"string","format":"date-time"},"replied_at":{"type":"string","format":"date-time"},"error":{"type":"string"},"skip_reason":{"type":"string"},"draft":{"type":"boolean"}}}}}}}},"example":{"payload":{"id":1,"account_id":1,"follow_up_sequence_id":1,"follow_up_sequence_version_id":1,"sequence_name":"sample sequence name","contact_id":1,"conversation_id":1,"crm_item_id":1,"calendar_event_id":1,"payments_charge_id":1,"assignee_id":1,"status":"active","current_step_position":1,"next_run_at":"2026-01-15T10:30:00.000Z","exit_reason":"sample exit reason","timezone":"America/Sao_Paulo","failure_reason":"sample failure reason","enrolled_via":"manual","enrolled_by_id":1,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","step_runs":[{"id":1,"position":1,"status":"active","compose_mode":"static","message_id":1,"scheduled_at":"2026-01-15T10:30:00.000Z","sent_at":"2026-01-15T10:30:00.000Z","replied_at":"2026-01-15T10:30:00.000Z","error":"sample error","skip_reason":"sample skip reason","draft":true}]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/follow_up/templates/{id}/archive":{"post":{"tags":["Follow-up"],"operationId":"auto_post_api_v1_accounts_account_id_follow_up_templates_id_archive","summary":"Archive templates","description":"Performs the archive operation on the targeted template resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"name":{"type":"string"},"body":{"type":"string"},"variables":{"type":"string"},"channel":{"type":"string","enum":["auto","same_conversation","email","sms","whatsapp"]},"category":{"type":"string"},"active":{"type":"boolean"},"archived_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}},"example":{"payload":{"id":1,"account_id":1,"name":"Sample Name","body":"Sample body text.","variables":"sample variables","channel":"auto","category":"sample category","active":true,"archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/follow_up/templates/{id}/restore":{"post":{"tags":["Follow-up"],"operationId":"auto_post_api_v1_accounts_account_id_follow_up_templates_id_restore","summary":"Restore templates","description":"Performs the restore operation on the targeted template resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"name":{"type":"string"},"body":{"type":"string"},"variables":{"type":"string"},"channel":{"type":"string","enum":["auto","same_conversation","email","sms","whatsapp"]},"category":{"type":"string"},"active":{"type":"boolean"},"archived_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}},"example":{"payload":{"id":1,"account_id":1,"name":"Sample Name","body":"Sample body text.","variables":"sample variables","channel":"auto","category":"sample category","active":true,"archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/follow_up/templates":{"get":{"tags":["Follow-up"],"operationId":"auto_get_api_v1_accounts_account_id_follow_up_templates","summary":"List templates","description":"Returns the list of templates visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"name":{"type":"string"},"body":{"type":"string"},"variables":{"type":"string"},"channel":{"type":"string","enum":["auto","same_conversation","email","sms","whatsapp"]},"category":{"type":"string"},"active":{"type":"boolean"},"archived_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}},"meta":{"type":"object","properties":{"count":{"type":"integer"},"current_page":{"type":"string"},"total_pages":{"type":"string"},"per_page":{"type":"string"},"has_more":{"type":"boolean"}}}}},"example":{"payload":[{"id":1,"account_id":1,"name":"Sample Name","body":"Sample body text.","variables":"sample variables","channel":"auto","category":"sample category","active":true,"archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}],"meta":{"count":5,"current_page":"sample current page","total_pages":"sample total pages","per_page":"sample per page","has_more":true}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."}]},"post":{"tags":["Follow-up"],"operationId":"auto_post_api_v1_accounts_account_id_follow_up_templates","summary":"Create templates","description":"Creates a new template from the request payload. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"name":{"type":"string"},"body":{"type":"string"},"variables":{"type":"string"},"channel":{"type":"string","enum":["auto","same_conversation","email","sms","whatsapp"]},"category":{"type":"string"},"active":{"type":"boolean"},"archived_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}},"example":{"payload":{"id":1,"account_id":1,"name":"Sample Name","body":"Sample body text.","variables":"sample variables","channel":"auto","category":"sample category","active":true,"archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"body":{"type":"string"},"channel":{"type":"string","enum":["auto","same_conversation","email","sms","whatsapp"]},"category":{"type":"string","enum":["MARKETING","UTILITY","AUTHENTICATION"]},"active":{"type":"boolean"}},"required":["name"]},"example":{"name":"Sample Name","body":"Sample body text.","channel":"auto","category":"MARKETING","active":true}}}}}},"/api/v1/accounts/{account_id}/follow_up/templates/{id}":{"get":{"tags":["Follow-up"],"operationId":"auto_get_api_v1_accounts_account_id_follow_up_templates_id","summary":"Get templates","description":"Returns the template identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"name":{"type":"string"},"body":{"type":"string"},"variables":{"type":"string"},"channel":{"type":"string","enum":["auto","same_conversation","email","sms","whatsapp"]},"category":{"type":"string"},"active":{"type":"boolean"},"archived_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}},"example":{"payload":{"id":1,"account_id":1,"name":"Sample Name","body":"Sample body text.","variables":"sample variables","channel":"auto","category":"sample category","active":true,"archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]},"patch":{"tags":["Follow-up"],"operationId":"auto_patch_api_v1_accounts_account_id_follow_up_templates_id","summary":"Update templates","description":"Updates the template identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"name":{"type":"string"},"body":{"type":"string"},"variables":{"type":"string"},"channel":{"type":"string","enum":["auto","same_conversation","email","sms","whatsapp"]},"category":{"type":"string"},"active":{"type":"boolean"},"archived_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}},"example":{"payload":{"id":1,"account_id":1,"name":"Sample Name","body":"Sample body text.","variables":"sample variables","channel":"auto","category":"sample category","active":true,"archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"body":{"type":"string"},"channel":{"type":"string","enum":["auto","same_conversation","email","sms","whatsapp"]},"category":{"type":"string","enum":["MARKETING","UTILITY","AUTHENTICATION"]},"active":{"type":"boolean"}}},"example":{"name":"Sample Name","body":"Sample body text.","channel":"auto","category":"MARKETING","active":true}}}}},"put":{"tags":["Follow-up"],"operationId":"auto_put_api_v1_accounts_account_id_follow_up_templates_id","summary":"Update templates","description":"Updates the template identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"name":{"type":"string"},"body":{"type":"string"},"variables":{"type":"string"},"channel":{"type":"string","enum":["auto","same_conversation","email","sms","whatsapp"]},"category":{"type":"string"},"active":{"type":"boolean"},"archived_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}},"example":{"payload":{"id":1,"account_id":1,"name":"Sample Name","body":"Sample body text.","variables":"sample variables","channel":"auto","category":"sample category","active":true,"archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"body":{"type":"string"},"channel":{"type":"string","enum":["auto","same_conversation","email","sms","whatsapp"]},"category":{"type":"string","enum":["MARKETING","UTILITY","AUTHENTICATION"]},"active":{"type":"boolean"}}},"example":{"name":"Sample Name","body":"Sample body text.","channel":"auto","category":"MARKETING","active":true}}}}},"delete":{"tags":["Follow-up"],"operationId":"auto_delete_api_v1_accounts_account_id_follow_up_templates_id","summary":"Delete templates","description":"Deletes the template identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Success (no content)"},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/follow_up/settings":{"get":{"tags":["Follow-up"],"operationId":"auto_get_api_v1_accounts_account_id_follow_up_settings","summary":"Get settings","description":"Returns the setting identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The resolved follow-up settings for the scope.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"inbox_id":{"type":["integer","null"],"description":"The scope inbox (null = account default).","example":42},"data":{"type":"object","description":"Raw stored override blob for the scope. Free-form; known keys below.","additionalProperties":true,"properties":{"timezone":{"type":["string","null"],"description":"Explicit IANA timezone for this scope; omit for automatic resolution.","example":"America/Sao_Paulo"},"use_contact_timezone":{"type":"boolean","description":"When true (default) a contact's own timezone outranks the AUTO chain.","example":true},"maestro_pause":{"type":"object","description":"Hold the cadence while Maestro is standing down (a human agent is handling the conversation): the detector does not enroll and the advance defers the next step. It holds, never exits — the cadence resumes on its own once the agent lets go. On by default (Segurar) unless a layer explicitly opts out. A sequence may override it via its own `settings`.","properties":{"hold":{"type":"boolean","description":"Whether this scope holds. Omit to inherit; the platform default (when nothing in the cascade decides) is true.","example":true},"defer_minutes":{"type":"integer","description":"How long a held enrollment waits before the next re-check. Default 15.","example":15}},"example":{"hold":true,"defer_minutes":15}}}},"resolved":{"type":"object","description":"The full merged config (DEFAULTS ← account ← inbox ← sequence ← step). Free-form.","additionalProperties":true},"resolved_timezone":{"type":"string","description":"The EFFECTIVE default timezone after the cascade + AUTO chain.","example":"America/Sao_Paulo"},"timezone_source":{"type":"string","description":"Which layer supplied the resolved timezone.","enum":["step","sequence","inbox_setting","account_setting","enrollment","contact","account","inbox","default"],"example":"account"}}}}},"example":{"payload":{"inbox_id":42,"data":{"timezone":"America/Sao_Paulo","use_contact_timezone":true,"maestro_pause":{"hold":true,"defer_minutes":15}},"resolved":{},"resolved_timezone":"America/Sao_Paulo","timezone_source":"account"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]},"patch":{"tags":["Follow-up"],"operationId":"auto_patch_api_v1_accounts_account_id_follow_up_settings","summary":"Update follow-up settings","description":"Upserts the follow_up_settings row for the given inbox (or the account default when inbox_id is blank) with the supplied opaque data blob, then returns the resolved config. Admin-only.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The upserted + re-resolved settings (same shape as GET).","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"inbox_id":{"type":["integer","null"],"description":"The scope that was written (null = account default).","example":42},"data":{"type":"object","description":"The raw override blob now stored for the scope — the request `data` as persisted. Free-form; known keys below.","additionalProperties":true,"properties":{"timezone":{"type":["string","null"],"description":"Explicit IANA timezone for this scope; omit for automatic resolution.","example":"America/Sao_Paulo"},"use_contact_timezone":{"type":"boolean","description":"When true (default) a contact's own timezone outranks the AUTO chain.","example":true},"maestro_pause":{"type":"object","description":"Hold the cadence while Maestro is standing down (a human agent is handling the conversation): the detector does not enroll and the advance defers the next step. It holds, never exits — the cadence resumes on its own once the agent lets go. On by default (Segurar) unless a layer explicitly opts out. A sequence may override it via its own `settings`.","properties":{"hold":{"type":"boolean","description":"Whether this scope holds. Omit to inherit; the platform default (when nothing in the cascade decides) is true.","example":true},"defer_minutes":{"type":"integer","description":"How long a held enrollment waits before the next re-check. Default 15.","example":15}},"example":{"hold":true,"defer_minutes":15}}}},"resolved":{"type":"object","description":"The full merged config recomputed after the write (DEFAULTS ← account ← inbox ← sequence ← step). Free-form.","additionalProperties":true},"resolved_timezone":{"type":"string","description":"The EFFECTIVE default timezone after the cascade + AUTO chain.","example":"America/Sao_Paulo"},"timezone_source":{"type":"string","description":"Which layer supplied the resolved timezone. This endpoint builds the resolver with account and inbox ONLY — no sequence, step, enrollment or contact — so the four layers that depend on them are structurally unreachable here and are not listed. The enum is what this endpoint can actually return, not the full set the resolver knows.","enum":["inbox_setting","account_setting","account","inbox","default"],"example":"inbox_setting"}}}}},"example":{"payload":{"inbox_id":42,"data":{"timezone":"America/Sao_Paulo","use_contact_timezone":true,"maestro_pause":{"hold":true,"defer_minutes":15}},"resolved":{"quiet_hours":{"enabled":false,"start":"21:00","end":"08:00"},"timezone":"America/Sao_Paulo","use_contact_timezone":true,"rate_limit":{"per_contact_per_day":3},"max_steps":10,"default_compose_mode":"static","business_days":[1,2,3,4,5]},"resolved_timezone":"America/Sao_Paulo","timezone_source":"inbox_setting"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"inbox_id":{"type":["integer","null"],"description":"Scope selector — omit/blank targets the account default; an id targets that inbox.","example":42},"data":{"type":"object","description":"The scope override blob. Free-form; known keys below.","additionalProperties":true,"properties":{"timezone":{"type":["string","null"],"description":"Explicit IANA timezone; omit for automatic resolution.","example":"America/Sao_Paulo"},"use_contact_timezone":{"type":"boolean","description":"When true (default) a contact's own timezone outranks the AUTO chain.","example":true},"maestro_pause":{"type":"object","description":"Hold the cadence while Maestro is standing down (a human agent is handling the conversation): the detector does not enroll and the advance defers the next step. It holds, never exits — the cadence resumes on its own once the agent lets go. On by default (Segurar) unless a layer explicitly opts out. A sequence may override it via its own `settings`.","properties":{"hold":{"type":"boolean","description":"Whether this scope holds. Omit to inherit; the platform default (when nothing in the cascade decides) is true.","example":true},"defer_minutes":{"type":"integer","description":"How long a held enrollment waits before the next re-check. Default 15.","example":15}},"example":{"hold":true,"defer_minutes":15}}}}}},"example":{"data":{"timezone":"America/Sao_Paulo","use_contact_timezone":true,"maestro_pause":{"hold":true,"defer_minutes":15}},"inbox_id":42}}}}},"put":{"tags":["Follow-up"],"operationId":"auto_put_api_v1_accounts_account_id_follow_up_settings","summary":"Update follow-up settings","description":"Upserts the follow_up_settings row for the given inbox (or the account default when inbox_id is blank) with the supplied opaque data blob, then returns the resolved config. Admin-only.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The upserted + re-resolved settings (same shape as GET).","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"inbox_id":{"type":["integer","null"],"description":"The scope that was written (null = account default).","example":42},"data":{"type":"object","description":"The raw override blob now stored for the scope — the request `data` as persisted. Free-form; known keys below.","additionalProperties":true,"properties":{"timezone":{"type":["string","null"],"description":"Explicit IANA timezone for this scope; omit for automatic resolution.","example":"America/Sao_Paulo"},"use_contact_timezone":{"type":"boolean","description":"When true (default) a contact's own timezone outranks the AUTO chain.","example":true},"maestro_pause":{"type":"object","description":"Hold the cadence while Maestro is standing down (a human agent is handling the conversation): the detector does not enroll and the advance defers the next step. It holds, never exits — the cadence resumes on its own once the agent lets go. On by default (Segurar) unless a layer explicitly opts out. A sequence may override it via its own `settings`.","properties":{"hold":{"type":"boolean","description":"Whether this scope holds. Omit to inherit; the platform default (when nothing in the cascade decides) is true.","example":true},"defer_minutes":{"type":"integer","description":"How long a held enrollment waits before the next re-check. Default 15.","example":15}},"example":{"hold":true,"defer_minutes":15}}}},"resolved":{"type":"object","description":"The full merged config recomputed after the write (DEFAULTS ← account ← inbox ← sequence ← step). Free-form.","additionalProperties":true},"resolved_timezone":{"type":"string","description":"The EFFECTIVE default timezone after the cascade + AUTO chain.","example":"America/Sao_Paulo"},"timezone_source":{"type":"string","description":"Which layer supplied the resolved timezone. This endpoint builds the resolver with account and inbox ONLY — no sequence, step, enrollment or contact — so the four layers that depend on them are structurally unreachable here and are not listed. The enum is what this endpoint can actually return, not the full set the resolver knows.","enum":["inbox_setting","account_setting","account","inbox","default"],"example":"inbox_setting"}}}}},"example":{"payload":{"inbox_id":42,"data":{"timezone":"America/Sao_Paulo","use_contact_timezone":true,"maestro_pause":{"hold":true,"defer_minutes":15}},"resolved":{"quiet_hours":{"enabled":false,"start":"21:00","end":"08:00"},"timezone":"America/Sao_Paulo","use_contact_timezone":true,"rate_limit":{"per_contact_per_day":3},"max_steps":10,"default_compose_mode":"static","business_days":[1,2,3,4,5]},"resolved_timezone":"America/Sao_Paulo","timezone_source":"inbox_setting"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"inbox_id":{"type":["integer","null"],"description":"Scope selector — omit/blank targets the account default; an id targets that inbox.","example":42},"data":{"type":"object","description":"The scope override blob. Free-form; known keys below.","additionalProperties":true,"properties":{"timezone":{"type":["string","null"],"description":"Explicit IANA timezone; omit for automatic resolution.","example":"America/Sao_Paulo"},"use_contact_timezone":{"type":"boolean","description":"When true (default) a contact's own timezone outranks the AUTO chain.","example":true},"maestro_pause":{"type":"object","description":"Hold the cadence while Maestro is standing down (a human agent is handling the conversation): the detector does not enroll and the advance defers the next step. It holds, never exits — the cadence resumes on its own once the agent lets go. On by default (Segurar) unless a layer explicitly opts out. A sequence may override it via its own `settings`.","properties":{"hold":{"type":"boolean","description":"Whether this scope holds. Omit to inherit; the platform default (when nothing in the cascade decides) is true.","example":true},"defer_minutes":{"type":"integer","description":"How long a held enrollment waits before the next re-check. Default 15.","example":15}},"example":{"hold":true,"defer_minutes":15}}}}}},"example":{"data":{"timezone":"America/Sao_Paulo","use_contact_timezone":true,"maestro_pause":{"hold":true,"defer_minutes":15}},"inbox_id":42}}}}}},"/api/v1/accounts/{account_id}/follow_up/reports":{"get":{"tags":["Follow-up"],"operationId":"auto_get_api_v1_accounts_account_id_follow_up_reports","summary":"List reports","description":"Returns the list of reports visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"string"}}},"example":{"payload":"sample payload"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."}]}},"/api/v1/accounts/{account_id}/follow_up/sequence_templates":{"get":{"tags":["Follow-up"],"operationId":"auto_get_api_v1_accounts_account_id_follow_up_sequence_templates","summary":"List sequence templates","description":"Returns the list of sequence templates visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"trigger_type":{"type":"string","enum":["manual","event","inactivity","schedule","ai_proposed"],"description":"What starts the follow-up sequence."},"target_type":{"type":"string","enum":["contact","conversation","crm_item","calendar_event","payment_charge"],"description":"The kind of record the sequence enrolls."},"name":{"type":"string"},"description":{"type":"string"},"steps_count":{"type":"integer"},"custom_attributes_count":{"type":"integer"},"channels":{"type":"array","items":{"type":"string"}}}}}}},"example":{"payload":[{"id":1,"trigger_type":"manual","target_type":"contact","name":"Sample Name","description":"A short description.","steps_count":5,"custom_attributes_count":5,"channels":["sample channel"]}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."}]},"post":{"tags":["Follow-up"],"operationId":"auto_post_api_v1_accounts_account_id_follow_up_sequence_templates","summary":"Create a follow-up sequence from a template","description":"Builds a new follow-up sequence (with its steps) from a built-in template in the account's locale (FollowUp::SequenceFromTemplateService) and returns the created sequence.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The created sequence with its steps.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer","example":21},"account_id":{"type":"integer","example":1},"name":{"type":"string","example":"Abandoned cart"},"description":{"type":["string","null"],"example":"Recover abandoned carts"},"status":{"type":"string","example":"draft","enum":["draft","active","paused","archived"],"description":"Lifecycle state of the follow-up sequence."},"trigger_type":{"type":"string","example":"manual","enum":["manual","event","inactivity","schedule","ai_proposed"],"description":"What starts the follow-up sequence."},"trigger_event":{"type":["string","null"],"example":null},"target_type":{"type":"string","enum":["contact","conversation","crm_item","calendar_event","payment_charge"],"description":"The kind of record the sequence enrolls.","example":"contact"},"published_version_id":{"type":["integer","null"],"example":null},"trigger_conditions":{"type":"object","additionalProperties":true,"example":{},"description":"Free-form conditions that must hold for the trigger to enroll."},"exit_conditions":{"type":"object","additionalProperties":true,"example":{},"description":"Free-form conditions that end the enrollment early."},"ai_config":{"type":"object","additionalProperties":true,"example":{},"description":"Free-form AI configuration for the sequence (model, tone, guardrails)."},"settings":{"type":"object","additionalProperties":true,"example":{},"description":"Free-form sequence settings; the key set depends on the sequence."},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"steps_count":{"type":"integer","example":3},"enrollments_count":{"type":"integer","example":0},"archived_at":{"type":["string","null"],"format":"date-time","example":null},"created_at":{"type":"string","format":"date-time","example":"2026-01-15T10:30:00.000Z"},"updated_at":{"type":"string","format":"date-time","example":"2026-01-15T10:30:00.000Z"},"steps":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","example":55},"follow_up_sequence_id":{"type":"integer","example":21},"follow_up_template_id":{"type":["integer","null"],"example":null},"position":{"type":"integer","example":1},"name":{"type":"string","example":"Reminder"},"delay_value":{"type":"integer","example":1},"delay_unit":{"type":"string","example":"hours"},"channel":{"type":"string","example":"whatsapp"},"content_type":{"type":"string","example":"text","enum":["text","template","rich"],"description":"How the step body is composed."},"message_template":{"type":["string","null"],"example":"Hi {{contact.name}}!"},"compose_mode":{"type":"string","enum":["static","ai_assisted","ai_full"],"description":"How the step message is composed (static text vs AI-assisted vs fully AI-authored).","example":"static"},"ai_intent":{"type":["string","null"],"example":null},"branch_conditions":{"type":"object","additionalProperties":true,"example":{},"description":"Free-form branch conditions evaluated on the step."},"actions":{"type":"array","items":{"type":"object","additionalProperties":true},"example":[]},"skip_conditions":{"type":"object","additionalProperties":true,"example":{},"description":"Free-form conditions that skip the step."},"whatsapp_template":{"type":["object","null"],"additionalProperties":true,"example":null,"description":"WhatsApp template binding for the step (name, language, parameters); null when the step sends free text."},"created_at":{"type":"string","format":"date-time","example":"2026-01-15T10:30:00.000Z"},"updated_at":{"type":"string","format":"date-time","example":"2026-01-15T10:30:00.000Z"}}}}}}}},"example":{"payload":{"id":21,"account_id":1,"name":"Abandoned cart","description":"Recover abandoned carts","status":"draft","trigger_type":"manual","trigger_event":null,"target_type":"contact","published_version_id":null,"trigger_conditions":{},"exit_conditions":{},"ai_config":{},"settings":{},"custom_attributes":{},"steps_count":3,"enrollments_count":0,"archived_at":null,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","steps":[{"id":55,"follow_up_sequence_id":21,"follow_up_template_id":null,"position":1,"name":"Reminder","delay_value":1,"delay_unit":"hours","channel":"whatsapp","content_type":"text","message_template":"Hi {{contact.name}}!","compose_mode":"static","ai_intent":null,"branch_conditions":{},"actions":[],"skip_conditions":{},"whatsapp_template":null,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["template_id"],"properties":{"template_id":{"type":"string","description":"Id/key of the built-in sequence template.","example":"abandoned_cart"}}},"example":{"template_id":"abandoned_cart"}}}}}},"/api/v1/accounts/{account_id}/follow_up/demo":{"delete":{"tags":["Follow-up"],"operationId":"auto_delete_api_v1_accounts_account_id_follow_up_demo","summary":"Delete demo","description":"Deletes the demo identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"202":{"description":"Success (no content)"},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]},"post":{"tags":["Follow-up"],"operationId":"auto_post_api_v1_accounts_account_id_follow_up_demo","summary":"Seed Follow-up demo data","description":"Enqueues the Follow-up demo seed for the account and returns immediately. The background job builds an end-to-end sample: a demo inbox with contacts and conversations, published sequences with their message templates, and enrollments already advanced through step runs and audit events, so the Follow-up screens can be explored with lifelike data. The endpoint takes no request body and returns no response body: it answers 202 as soon as the job is enqueued, and the client polls the sequence list until the demo sequences appear. The DELETE sibling on the same path removes the demo data again. Requires the follow_ups feature to be enabled and an administrator caller.","security":[{"userApiKey":[]}],"responses":{"202":{"description":"Accepted — the demo seed job was enqueued. No response body is returned; poll the sequence list until the demo sequences appear."},"401":{"description":"Unauthorized"},"403":{"description":"The follow_ups feature is disabled for the account, or the caller's access role does not grant the follow_up_manage permission.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable reason. feature_not_enabled means the account does not have the Follow-up feature turned on; forbidden means the caller's access role lacks follow_up_manage.","enum":["feature_not_enabled","forbidden"],"example":"feature_not_enabled"}}},"example":{"error":"feature_not_enabled"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/contracts/companies/{id}/archive":{"post":{"tags":["Contracts"],"operationId":"auto_post_api_v1_accounts_account_id_contracts_companies_id_archive","summary":"Archive an issuing company","description":"Soft-deletes an issuing company by stamping its archive timestamp. The record is kept — it disappears from the default company list, is listed again when the list is requested with the archived filter, and can be brought back with the restore action. Contracts already issued by the company are untouched. On success the endpoint returns HTTP 200 with an EMPTY body; refetch the company to read its new state.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The company is archived. Empty body."},"401":{"description":"Unauthorized"},"404":{"description":"No company with this id exists in the account."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/contracts/companies/{id}/restore":{"post":{"tags":["Contracts"],"operationId":"auto_post_api_v1_accounts_account_id_contracts_companies_id_restore","summary":"Restore companies","description":"Performs the restore operation on the targeted company resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"legal_name":{"type":"string"},"document":{"type":"string"},"document_type":{"type":"string","enum":["cnpj","cpf","other"]},"email":{"type":"string","format":"email"},"phone":{"type":"string"},"address":{"type":"object","additionalProperties":{"type":"string","description":"Address component value keyed by component name"},"description":"Postal address components keyed by component name."},"branding":{"type":"string"},"settings":{"type":"string"},"can_issue":{"type":"boolean"},"is_default":{"type":"boolean"},"archived":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"logo_url":{"type":"string"},"certificate":{"type":"object","properties":{"present":{"type":"boolean"},"valid":{"type":"boolean"},"filename":{"type":"string"},"subject":{"type":"string"},"expires_at":{"type":"string","format":"date-time"}}}}}}},"example":{"payload":{"id":1,"name":"Sample Name","legal_name":"sample legal name","document":"sample document","document_type":"cnpj","email":"agent@example.com","phone":"+5511999998888","address":{},"branding":"sample branding","settings":"sample settings","can_issue":true,"is_default":true,"archived":true,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","logo_url":"https://example.com/resource","certificate":{"present":true,"valid":true,"filename":"sample filename","subject":"Sample subject","expires_at":"2026-01-15T10:30:00.000Z"}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/contracts/companies/{id}/set_default":{"post":{"tags":["Contracts"],"operationId":"auto_post_api_v1_accounts_account_id_contracts_companies_id_set_default","summary":"Set default companies","description":"Performs the set default operation on the targeted company resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"legal_name":{"type":"string"},"document":{"type":"string"},"document_type":{"type":"string","enum":["cnpj","cpf","other"]},"email":{"type":"string","format":"email"},"phone":{"type":"string"},"address":{"type":"object","additionalProperties":{"type":"string","description":"Address component value keyed by component name"},"description":"Postal address components keyed by component name."},"branding":{"type":"string"},"settings":{"type":"string"},"can_issue":{"type":"boolean"},"is_default":{"type":"boolean"},"archived":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"logo_url":{"type":"string"},"certificate":{"type":"object","properties":{"present":{"type":"boolean"},"valid":{"type":"boolean"},"filename":{"type":"string"},"subject":{"type":"string"},"expires_at":{"type":"string","format":"date-time"}}}}}}},"example":{"payload":{"id":1,"name":"Sample Name","legal_name":"sample legal name","document":"sample document","document_type":"cnpj","email":"agent@example.com","phone":"+5511999998888","address":{},"branding":"sample branding","settings":"sample settings","can_issue":true,"is_default":true,"archived":true,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","logo_url":"https://example.com/resource","certificate":{"present":true,"valid":true,"filename":"sample filename","subject":"Sample subject","expires_at":"2026-01-15T10:30:00.000Z"}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/contracts/companies/{id}/upload_certificate":{"post":{"tags":["Contracts"],"operationId":"auto_post_api_v1_accounts_account_id_contracts_companies_id_upload_certificate","summary":"Upload certificate companies","description":"Performs the upload certificate operation on the targeted company resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"legal_name":{"type":"string"},"document":{"type":"string"},"document_type":{"type":"string","enum":["cnpj","cpf","other"]},"email":{"type":"string","format":"email"},"phone":{"type":"string"},"address":{"type":"object","additionalProperties":{"type":"string","description":"Address component value keyed by component name"},"description":"Postal address components keyed by component name."},"branding":{"type":"string"},"settings":{"type":"string"},"can_issue":{"type":"boolean"},"is_default":{"type":"boolean"},"archived":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"logo_url":{"type":"string"},"certificate":{"type":"object","properties":{"present":{"type":"boolean"},"valid":{"type":"boolean"},"filename":{"type":"string"},"subject":{"type":"string"},"expires_at":{"type":"string","format":"date-time"}}}}}}},"example":{"payload":{"id":1,"name":"Sample Name","legal_name":"sample legal name","document":"sample document","document_type":"cnpj","email":"agent@example.com","phone":"+5511999998888","address":{},"branding":"sample branding","settings":"sample settings","can_issue":true,"is_default":true,"archived":true,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","logo_url":"https://example.com/resource","certificate":{"present":true,"valid":true,"filename":"sample filename","subject":"Sample subject","expires_at":"2026-01-15T10:30:00.000Z"}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"certificate":{"type":"string"},"password":{"type":"string"}}},"example":{"certificate":"sample certificate","password":"sample-password"}}}}}},"/api/v1/accounts/{account_id}/contracts/companies/{id}/remove_certificate":{"post":{"tags":["Contracts"],"operationId":"auto_post_api_v1_accounts_account_id_contracts_companies_id_remove_certificate","summary":"Remove certificate companies","description":"Performs the remove certificate operation on the targeted company resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"legal_name":{"type":"string"},"document":{"type":"string"},"document_type":{"type":"string","enum":["cnpj","cpf","other"]},"email":{"type":"string","format":"email"},"phone":{"type":"string"},"address":{"type":"object","additionalProperties":{"type":"string","description":"Address component value keyed by component name"},"description":"Postal address components keyed by component name."},"branding":{"type":"string"},"settings":{"type":"string"},"can_issue":{"type":"boolean"},"is_default":{"type":"boolean"},"archived":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"logo_url":{"type":"string"},"certificate":{"type":"object","properties":{"present":{"type":"boolean"},"valid":{"type":"boolean"},"filename":{"type":"string"},"subject":{"type":"string"},"expires_at":{"type":"string","format":"date-time"}}}}}}},"example":{"payload":{"id":1,"name":"Sample Name","legal_name":"sample legal name","document":"sample document","document_type":"cnpj","email":"agent@example.com","phone":"+5511999998888","address":{},"branding":"sample branding","settings":"sample settings","can_issue":true,"is_default":true,"archived":true,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","logo_url":"https://example.com/resource","certificate":{"present":true,"valid":true,"filename":"sample filename","subject":"Sample subject","expires_at":"2026-01-15T10:30:00.000Z"}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/contracts/companies/{id}/remove_logo":{"post":{"tags":["Contracts"],"operationId":"auto_post_api_v1_accounts_account_id_contracts_companies_id_remove_logo","summary":"Remove logo companies","description":"Performs the remove logo operation on the targeted company resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"legal_name":{"type":"string"},"document":{"type":"string"},"document_type":{"type":"string","enum":["cnpj","cpf","other"]},"email":{"type":"string","format":"email"},"phone":{"type":"string"},"address":{"type":"object","additionalProperties":{"type":"string","description":"Address component value keyed by component name"},"description":"Postal address components keyed by component name."},"branding":{"type":"string"},"settings":{"type":"string"},"can_issue":{"type":"boolean"},"is_default":{"type":"boolean"},"archived":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"logo_url":{"type":"string"},"certificate":{"type":"object","properties":{"present":{"type":"boolean"},"valid":{"type":"boolean"},"filename":{"type":"string"},"subject":{"type":"string"},"expires_at":{"type":"string","format":"date-time"}}}}}}},"example":{"payload":{"id":1,"name":"Sample Name","legal_name":"sample legal name","document":"sample document","document_type":"cnpj","email":"agent@example.com","phone":"+5511999998888","address":{},"branding":"sample branding","settings":"sample settings","can_issue":true,"is_default":true,"archived":true,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","logo_url":"https://example.com/resource","certificate":{"present":true,"valid":true,"filename":"sample filename","subject":"Sample subject","expires_at":"2026-01-15T10:30:00.000Z"}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/contracts/companies":{"get":{"tags":["Contracts"],"operationId":"auto_get_api_v1_accounts_account_id_contracts_companies","summary":"List companies","description":"Returns the list of companies visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"legal_name":{"type":"string"},"document":{"type":"string"},"document_type":{"type":"string","enum":["cnpj","cpf","other"]},"email":{"type":"string","format":"email"},"phone":{"type":"string"},"address":{"type":"object","additionalProperties":{"type":"string","description":"Address component value keyed by component name"},"description":"Postal address components keyed by component name."},"branding":{"type":"string"},"settings":{"type":"string"},"can_issue":{"type":"boolean"},"is_default":{"type":"boolean"},"archived":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"logo_url":{"type":"string"},"certificate":{"type":"object","properties":{"present":{"type":"boolean"},"valid":{"type":"boolean"},"filename":{"type":"string"},"subject":{"type":"string"},"expires_at":{"type":"string","format":"date-time"}}}}}}}},"example":{"payload":[{"id":1,"name":"Sample Name","legal_name":"sample legal name","document":"sample document","document_type":"cnpj","email":"agent@example.com","phone":"+5511999998888","address":{},"branding":"sample branding","settings":"sample settings","can_issue":true,"is_default":true,"archived":true,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","logo_url":"https://example.com/resource","certificate":{"present":true,"valid":true,"filename":"sample filename","subject":"Sample subject","expires_at":"2026-01-15T10:30:00.000Z"}}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."}]},"post":{"tags":["Contracts"],"operationId":"auto_post_api_v1_accounts_account_id_contracts_companies","summary":"Create companies","description":"Creates a new company from the request payload. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"legal_name":{"type":"string"},"document":{"type":"string"},"document_type":{"type":"string","enum":["cnpj","cpf","other"]},"email":{"type":"string","format":"email"},"phone":{"type":"string"},"address":{"type":"object","additionalProperties":{"type":"string","description":"Address component value keyed by component name"},"description":"Postal address components keyed by component name."},"branding":{"type":"string"},"settings":{"type":"string"},"can_issue":{"type":"boolean"},"is_default":{"type":"boolean"},"archived":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"logo_url":{"type":"string"},"certificate":{"type":"object","properties":{"present":{"type":"boolean"},"valid":{"type":"boolean"},"filename":{"type":"string"},"subject":{"type":"string"},"expires_at":{"type":"string","format":"date-time"}}}}}}},"example":{"payload":{"id":1,"name":"Sample Name","legal_name":"sample legal name","document":"sample document","document_type":"cnpj","email":"agent@example.com","phone":"+5511999998888","address":{},"branding":"sample branding","settings":"sample settings","can_issue":true,"is_default":true,"archived":true,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","logo_url":"https://example.com/resource","certificate":{"present":true,"valid":true,"filename":"sample filename","subject":"Sample subject","expires_at":"2026-01-15T10:30:00.000Z"}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"company":{"type":"object","properties":{"name":{"type":"string"},"legal_name":{"type":"string"},"document":{"type":"string"},"document_type":{"type":"string","enum":["cnpj","cpf","other"]},"email":{"type":"string","format":"email"},"phone":{"type":"string"},"can_issue":{"type":"boolean"},"is_default":{"type":"boolean"},"address":{"type":"object","additionalProperties":{"type":"string","description":"Address component value keyed by component name"},"description":"Postal address components keyed by component name."},"branding":{"type":"object","additionalProperties":true,"description":"Free-form object."},"settings":{"type":"object","additionalProperties":true,"description":"Free-form object."}},"required":["name"]}},"required":["company"]},"example":{"company":{"name":"Sample Name","legal_name":"sample legal name","document":"sample document","document_type":"cnpj","email":"agent@example.com","phone":"+5511999998888","can_issue":true,"is_default":true,"address":{},"branding":{},"settings":{}}}}}}}},"/api/v1/accounts/{account_id}/contracts/companies/{id}":{"get":{"tags":["Contracts"],"operationId":"auto_get_api_v1_accounts_account_id_contracts_companies_id","summary":"Get companies","description":"Returns the company identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"legal_name":{"type":"string"},"document":{"type":"string"},"document_type":{"type":"string","enum":["cnpj","cpf","other"]},"email":{"type":"string","format":"email"},"phone":{"type":"string"},"address":{"type":"object","additionalProperties":{"type":"string","description":"Address component value keyed by component name"},"description":"Postal address components keyed by component name."},"branding":{"type":"string"},"settings":{"type":"string"},"can_issue":{"type":"boolean"},"is_default":{"type":"boolean"},"archived":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"logo_url":{"type":"string"},"certificate":{"type":"object","properties":{"present":{"type":"boolean"},"valid":{"type":"boolean"},"filename":{"type":"string"},"subject":{"type":"string"},"expires_at":{"type":"string","format":"date-time"}}}}}}},"example":{"payload":{"id":1,"name":"Sample Name","legal_name":"sample legal name","document":"sample document","document_type":"cnpj","email":"agent@example.com","phone":"+5511999998888","address":{},"branding":"sample branding","settings":"sample settings","can_issue":true,"is_default":true,"archived":true,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","logo_url":"https://example.com/resource","certificate":{"present":true,"valid":true,"filename":"sample filename","subject":"Sample subject","expires_at":"2026-01-15T10:30:00.000Z"}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]},"patch":{"tags":["Contracts"],"operationId":"auto_patch_api_v1_accounts_account_id_contracts_companies_id","summary":"Update companies","description":"Updates the company identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"legal_name":{"type":"string"},"document":{"type":"string"},"document_type":{"type":"string","enum":["cnpj","cpf","other"]},"email":{"type":"string","format":"email"},"phone":{"type":"string"},"address":{"type":"object","additionalProperties":{"type":"string","description":"Address component value keyed by component name"},"description":"Postal address components keyed by component name."},"branding":{"type":"string"},"settings":{"type":"string"},"can_issue":{"type":"boolean"},"is_default":{"type":"boolean"},"archived":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"logo_url":{"type":"string"},"certificate":{"type":"object","properties":{"present":{"type":"boolean"},"valid":{"type":"boolean"},"filename":{"type":"string"},"subject":{"type":"string"},"expires_at":{"type":"string","format":"date-time"}}}}}}},"example":{"payload":{"id":1,"name":"Sample Name","legal_name":"sample legal name","document":"sample document","document_type":"cnpj","email":"agent@example.com","phone":"+5511999998888","address":{},"branding":"sample branding","settings":"sample settings","can_issue":true,"is_default":true,"archived":true,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","logo_url":"https://example.com/resource","certificate":{"present":true,"valid":true,"filename":"sample filename","subject":"Sample subject","expires_at":"2026-01-15T10:30:00.000Z"}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"company":{"type":"object","properties":{"name":{"type":"string"},"legal_name":{"type":"string"},"document":{"type":"string"},"document_type":{"type":"string","enum":["cnpj","cpf","other"]},"email":{"type":"string","format":"email"},"phone":{"type":"string"},"can_issue":{"type":"boolean"},"is_default":{"type":"boolean"},"address":{"type":"object","additionalProperties":{"type":"string","description":"Address component value keyed by component name"},"description":"Postal address components keyed by component name."},"branding":{"type":"object","additionalProperties":true,"description":"Free-form object."},"settings":{"type":"object","additionalProperties":true,"description":"Free-form object."}}}},"required":["company"]},"example":{"company":{"name":"Sample Name","legal_name":"sample legal name","document":"sample document","document_type":"cnpj","email":"agent@example.com","phone":"+5511999998888","can_issue":true,"is_default":true,"address":{},"branding":{},"settings":{}}}}}}},"put":{"tags":["Contracts"],"operationId":"auto_put_api_v1_accounts_account_id_contracts_companies_id","summary":"Update companies","description":"Updates the company identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"legal_name":{"type":"string"},"document":{"type":"string"},"document_type":{"type":"string","enum":["cnpj","cpf","other"]},"email":{"type":"string","format":"email"},"phone":{"type":"string"},"address":{"type":"object","additionalProperties":{"type":"string","description":"Address component value keyed by component name"},"description":"Postal address components keyed by component name."},"branding":{"type":"string"},"settings":{"type":"string"},"can_issue":{"type":"boolean"},"is_default":{"type":"boolean"},"archived":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"logo_url":{"type":"string"},"certificate":{"type":"object","properties":{"present":{"type":"boolean"},"valid":{"type":"boolean"},"filename":{"type":"string"},"subject":{"type":"string"},"expires_at":{"type":"string","format":"date-time"}}}}}}},"example":{"payload":{"id":1,"name":"Sample Name","legal_name":"sample legal name","document":"sample document","document_type":"cnpj","email":"agent@example.com","phone":"+5511999998888","address":{},"branding":"sample branding","settings":"sample settings","can_issue":true,"is_default":true,"archived":true,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","logo_url":"https://example.com/resource","certificate":{"present":true,"valid":true,"filename":"sample filename","subject":"Sample subject","expires_at":"2026-01-15T10:30:00.000Z"}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"company":{"type":"object","properties":{"name":{"type":"string"},"legal_name":{"type":"string"},"document":{"type":"string"},"document_type":{"type":"string","enum":["cnpj","cpf","other"]},"email":{"type":"string","format":"email"},"phone":{"type":"string"},"can_issue":{"type":"boolean"},"is_default":{"type":"boolean"},"address":{"type":"object","additionalProperties":{"type":"string","description":"Address component value keyed by component name"},"description":"Postal address components keyed by component name."},"branding":{"type":"object","additionalProperties":true,"description":"Free-form object."},"settings":{"type":"object","additionalProperties":true,"description":"Free-form object."}}}},"required":["company"]},"example":{"company":{"name":"Sample Name","legal_name":"sample legal name","document":"sample document","document_type":"cnpj","email":"agent@example.com","phone":"+5511999998888","can_issue":true,"is_default":true,"address":{},"branding":{},"settings":{}}}}}}},"delete":{"tags":["Contracts"],"operationId":"auto_delete_api_v1_accounts_account_id_contracts_companies_id","summary":"Delete companies","description":"Deletes the company identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Success (no content)"},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/contracts/templates/{id}/archive":{"post":{"tags":["Contracts"],"operationId":"auto_post_api_v1_accounts_account_id_contracts_templates_id_archive","summary":"Archive a contract template","description":"Soft-deletes a contract template by stamping its archive timestamp. The template stops appearing in the authoring list and can no longer be picked when creating a contract, but existing contracts created from it are untouched and the template can be restored. Archiving is also the required first step before a template can be permanently deleted. On success the endpoint returns HTTP 200 with an EMPTY body.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The template is archived. Empty body."},"401":{"description":"Unauthorized"},"404":{"description":"No template with this id exists in the account."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/contracts/templates/{id}/restore":{"post":{"tags":["Contracts"],"operationId":"auto_post_api_v1_accounts_account_id_contracts_templates_id_restore","summary":"Restore templates","description":"Performs the restore operation on the targeted template resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"category":{"type":"string"},"status":{"type":"string","enum":["draft","active"]},"source_format":{"type":"string","enum":["markdown","html","docx","pdf","upload"]},"body":{"type":"string"},"jurisdiction":{"type":"string"},"default_tier":{"type":"string","enum":["simple","advanced","qualified"]},"default_locale":{"type":"string"},"variables":{"type":"string"},"variable_keys":{"type":"string"},"settings":{"type":"string"},"created_by_id":{"type":"integer"},"is_library":{"type":"boolean"},"library_slug":{"type":"string"},"locale":{"type":"string"},"preview":{"type":"string"},"archived":{"type":"boolean"},"archived_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"source_file":{"type":"object","properties":{"url":{"type":"string"},"filename":{"type":"string"},"content_type":{"type":"string"},"byte_size":{"type":"string"}}}}}}},"example":{"payload":{"id":1,"name":"Sample Name","category":"sample category","status":"draft","source_format":"markdown","body":"Sample body text.","jurisdiction":"sample jurisdiction","default_tier":"simple","default_locale":"sample default locale","variables":"sample variables","variable_keys":"sample variable keys","settings":"sample settings","created_by_id":1,"is_library":true,"library_slug":"sample library slug","locale":"en","preview":"sample preview","archived":true,"archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","source_file":{"url":"https://example.com/resource","filename":"sample filename","content_type":"sample content type","byte_size":"sample byte size"}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/contracts/templates/{id}/duplicate":{"post":{"tags":["Contracts"],"operationId":"auto_post_api_v1_accounts_account_id_contracts_templates_id_duplicate","summary":"Duplicate templates","description":"Performs the duplicate operation on the targeted template resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"category":{"type":"string"},"status":{"type":"string","enum":["draft","active"]},"source_format":{"type":"string","enum":["markdown","html","docx","pdf","upload"]},"body":{"type":"string"},"jurisdiction":{"type":"string"},"default_tier":{"type":"string","enum":["simple","advanced","qualified"]},"default_locale":{"type":"string"},"variables":{"type":"string"},"variable_keys":{"type":"string"},"settings":{"type":"string"},"created_by_id":{"type":"integer"},"is_library":{"type":"boolean"},"library_slug":{"type":"string"},"locale":{"type":"string"},"preview":{"type":"string"},"archived":{"type":"boolean"},"archived_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"source_file":{"type":"object","properties":{"url":{"type":"string"},"filename":{"type":"string"},"content_type":{"type":"string"},"byte_size":{"type":"string"}}}}}}},"example":{"payload":{"id":1,"name":"Sample Name","category":"sample category","status":"draft","source_format":"markdown","body":"Sample body text.","jurisdiction":"sample jurisdiction","default_tier":"simple","default_locale":"sample default locale","variables":"sample variables","variable_keys":"sample variable keys","settings":"sample settings","created_by_id":1,"is_library":true,"library_slug":"sample library slug","locale":"en","preview":"sample preview","archived":true,"archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","source_file":{"url":"https://example.com/resource","filename":"sample filename","content_type":"sample content type","byte_size":"sample byte size"}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/contracts/templates/{id}/use":{"post":{"tags":["Contracts"],"operationId":"auto_post_api_v1_accounts_account_id_contracts_templates_id_use","summary":"Use templates","description":"Performs the use operation on the targeted template resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"category":{"type":"string"},"status":{"type":"string","enum":["draft","active"]},"source_format":{"type":"string","enum":["markdown","html","docx","pdf","upload"]},"body":{"type":"string"},"jurisdiction":{"type":"string"},"default_tier":{"type":"string","enum":["simple","advanced","qualified"]},"default_locale":{"type":"string"},"variables":{"type":"string"},"variable_keys":{"type":"string"},"settings":{"type":"string"},"created_by_id":{"type":"integer"},"is_library":{"type":"boolean"},"library_slug":{"type":"string"},"locale":{"type":"string"},"preview":{"type":"string"},"archived":{"type":"boolean"},"archived_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"source_file":{"type":"object","properties":{"url":{"type":"string"},"filename":{"type":"string"},"content_type":{"type":"string"},"byte_size":{"type":"string"}}}}}}},"example":{"payload":{"id":1,"name":"Sample Name","category":"sample category","status":"draft","source_format":"markdown","body":"Sample body text.","jurisdiction":"sample jurisdiction","default_tier":"simple","default_locale":"sample default locale","variables":"sample variables","variable_keys":"sample variable keys","settings":"sample settings","created_by_id":1,"is_library":true,"library_slug":"sample library slug","locale":"en","preview":"sample preview","archived":true,"archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","source_file":{"url":"https://example.com/resource","filename":"sample filename","content_type":"sample content type","byte_size":"sample byte size"}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/contracts/templates":{"get":{"tags":["Contracts"],"operationId":"auto_get_api_v1_accounts_account_id_contracts_templates","summary":"List templates","description":"Returns the list of templates visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"category":{"type":"string"},"status":{"type":"string","enum":["draft","active"]},"source_format":{"type":"string","enum":["markdown","html","docx","pdf","upload"]},"body":{"type":"string"},"jurisdiction":{"type":"string"},"default_tier":{"type":"string","enum":["simple","advanced","qualified"]},"default_locale":{"type":"string"},"variables":{"type":"string"},"variable_keys":{"type":"string"},"settings":{"type":"string"},"created_by_id":{"type":"integer"},"is_library":{"type":"boolean"},"library_slug":{"type":"string"},"locale":{"type":"string"},"preview":{"type":"string"},"archived":{"type":"boolean"},"archived_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"source_file":{"type":"object","properties":{"url":{"type":"string"},"filename":{"type":"string"},"content_type":{"type":"string"},"byte_size":{"type":"string"}}}}}},"meta":{"type":"object","properties":{"count":{"type":"integer"},"current_page":{"type":"string"},"total_pages":{"type":"string"},"per_page":{"type":"string"},"has_more":{"type":"boolean"}}}}},"example":{"payload":[{"id":1,"name":"Sample Name","category":"sample category","status":"draft","source_format":"markdown","body":"Sample body text.","jurisdiction":"sample jurisdiction","default_tier":"simple","default_locale":"sample default locale","variables":"sample variables","variable_keys":"sample variable keys","settings":"sample settings","created_by_id":1,"is_library":true,"library_slug":"sample library slug","locale":"en","preview":"sample preview","archived":true,"archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","source_file":{"url":"https://example.com/resource","filename":"sample filename","content_type":"sample content type","byte_size":"sample byte size"}}],"meta":{"count":5,"current_page":"sample current page","total_pages":"sample total pages","per_page":"sample per page","has_more":true}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."}]},"post":{"tags":["Contracts"],"operationId":"auto_post_api_v1_accounts_account_id_contracts_templates","summary":"Create templates","description":"Creates a new template from the request payload. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"category":{"type":"string"},"status":{"type":"string","enum":["draft","active"]},"source_format":{"type":"string","enum":["markdown","html","docx","pdf","upload"]},"body":{"type":"string"},"jurisdiction":{"type":"string"},"default_tier":{"type":"string","enum":["simple","advanced","qualified"]},"default_locale":{"type":"string"},"variables":{"type":"string"},"variable_keys":{"type":"string"},"settings":{"type":"string"},"created_by_id":{"type":"integer"},"is_library":{"type":"boolean"},"library_slug":{"type":"string"},"locale":{"type":"string"},"preview":{"type":"string"},"archived":{"type":"boolean"},"archived_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"source_file":{"type":"object","properties":{"url":{"type":"string"},"filename":{"type":"string"},"content_type":{"type":"string"},"byte_size":{"type":"string"}}}}}}},"example":{"payload":{"id":1,"name":"Sample Name","category":"sample category","status":"draft","source_format":"markdown","body":"Sample body text.","jurisdiction":"sample jurisdiction","default_tier":"simple","default_locale":"sample default locale","variables":"sample variables","variable_keys":"sample variable keys","settings":"sample settings","created_by_id":1,"is_library":true,"library_slug":"sample library slug","locale":"en","preview":"sample preview","archived":true,"archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","source_file":{"url":"https://example.com/resource","filename":"sample filename","content_type":"sample content type","byte_size":"sample byte size"}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"template":{"type":"object","properties":{"name":{"type":"string"},"category":{"type":"string","enum":["MARKETING","UTILITY","AUTHENTICATION"]},"status":{"type":"string","enum":["draft","active"]},"source_format":{"type":"string","enum":["markdown","html","docx","pdf","upload"]},"body":{"type":"string"},"jurisdiction":{"type":"string"},"default_tier":{"type":"string","enum":["simple","advanced","qualified"]},"default_locale":{"type":"string"},"variables":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Free-form object."}},"settings":{"type":"object","additionalProperties":true,"description":"Free-form object."}},"required":["name"]}},"required":["template"]},"example":{"template":{"name":"Sample Name","category":"MARKETING","status":"draft","source_format":"markdown","body":"Sample body text.","jurisdiction":"sample jurisdiction","default_tier":"simple","default_locale":"sample default locale","variables":[{}],"settings":{}}}}}}}},"/api/v1/accounts/{account_id}/contracts/templates/{id}":{"get":{"tags":["Contracts"],"operationId":"auto_get_api_v1_accounts_account_id_contracts_templates_id","summary":"Get templates","description":"Returns the template identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"category":{"type":"string"},"status":{"type":"string","enum":["draft","active"]},"source_format":{"type":"string","enum":["markdown","html","docx","pdf","upload"]},"body":{"type":"string"},"jurisdiction":{"type":"string"},"default_tier":{"type":"string","enum":["simple","advanced","qualified"]},"default_locale":{"type":"string"},"variables":{"type":"string"},"variable_keys":{"type":"string"},"settings":{"type":"string"},"created_by_id":{"type":"integer"},"is_library":{"type":"boolean"},"library_slug":{"type":"string"},"locale":{"type":"string"},"preview":{"type":"string"},"archived":{"type":"boolean"},"archived_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"source_file":{"type":"object","properties":{"url":{"type":"string"},"filename":{"type":"string"},"content_type":{"type":"string"},"byte_size":{"type":"string"}}}}}}},"example":{"payload":{"id":1,"name":"Sample Name","category":"sample category","status":"draft","source_format":"markdown","body":"Sample body text.","jurisdiction":"sample jurisdiction","default_tier":"simple","default_locale":"sample default locale","variables":"sample variables","variable_keys":"sample variable keys","settings":"sample settings","created_by_id":1,"is_library":true,"library_slug":"sample library slug","locale":"en","preview":"sample preview","archived":true,"archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","source_file":{"url":"https://example.com/resource","filename":"sample filename","content_type":"sample content type","byte_size":"sample byte size"}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]},"patch":{"tags":["Contracts"],"operationId":"auto_patch_api_v1_accounts_account_id_contracts_templates_id","summary":"Update templates","description":"Updates the template identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"category":{"type":"string"},"status":{"type":"string","enum":["draft","active"]},"source_format":{"type":"string","enum":["markdown","html","docx","pdf","upload"]},"body":{"type":"string"},"jurisdiction":{"type":"string"},"default_tier":{"type":"string","enum":["simple","advanced","qualified"]},"default_locale":{"type":"string"},"variables":{"type":"string"},"variable_keys":{"type":"string"},"settings":{"type":"string"},"created_by_id":{"type":"integer"},"is_library":{"type":"boolean"},"library_slug":{"type":"string"},"locale":{"type":"string"},"preview":{"type":"string"},"archived":{"type":"boolean"},"archived_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"source_file":{"type":"object","properties":{"url":{"type":"string"},"filename":{"type":"string"},"content_type":{"type":"string"},"byte_size":{"type":"string"}}}}}}},"example":{"payload":{"id":1,"name":"Sample Name","category":"sample category","status":"draft","source_format":"markdown","body":"Sample body text.","jurisdiction":"sample jurisdiction","default_tier":"simple","default_locale":"sample default locale","variables":"sample variables","variable_keys":"sample variable keys","settings":"sample settings","created_by_id":1,"is_library":true,"library_slug":"sample library slug","locale":"en","preview":"sample preview","archived":true,"archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","source_file":{"url":"https://example.com/resource","filename":"sample filename","content_type":"sample content type","byte_size":"sample byte size"}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"template":{"type":"object","properties":{"name":{"type":"string"},"category":{"type":"string","enum":["MARKETING","UTILITY","AUTHENTICATION"]},"status":{"type":"string","enum":["draft","active"]},"source_format":{"type":"string","enum":["markdown","html","docx","pdf","upload"]},"body":{"type":"string"},"jurisdiction":{"type":"string"},"default_tier":{"type":"string","enum":["simple","advanced","qualified"]},"default_locale":{"type":"string"},"variables":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Free-form object."}},"settings":{"type":"object","additionalProperties":true,"description":"Free-form object."}}}},"required":["template"]},"example":{"template":{"name":"Sample Name","category":"MARKETING","status":"draft","source_format":"markdown","body":"Sample body text.","jurisdiction":"sample jurisdiction","default_tier":"simple","default_locale":"sample default locale","variables":[{}],"settings":{}}}}}}},"put":{"tags":["Contracts"],"operationId":"auto_put_api_v1_accounts_account_id_contracts_templates_id","summary":"Update templates","description":"Updates the template identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"category":{"type":"string"},"status":{"type":"string","enum":["draft","active"]},"source_format":{"type":"string","enum":["markdown","html","docx","pdf","upload"]},"body":{"type":"string"},"jurisdiction":{"type":"string"},"default_tier":{"type":"string","enum":["simple","advanced","qualified"]},"default_locale":{"type":"string"},"variables":{"type":"string"},"variable_keys":{"type":"string"},"settings":{"type":"string"},"created_by_id":{"type":"integer"},"is_library":{"type":"boolean"},"library_slug":{"type":"string"},"locale":{"type":"string"},"preview":{"type":"string"},"archived":{"type":"boolean"},"archived_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"source_file":{"type":"object","properties":{"url":{"type":"string"},"filename":{"type":"string"},"content_type":{"type":"string"},"byte_size":{"type":"string"}}}}}}},"example":{"payload":{"id":1,"name":"Sample Name","category":"sample category","status":"draft","source_format":"markdown","body":"Sample body text.","jurisdiction":"sample jurisdiction","default_tier":"simple","default_locale":"sample default locale","variables":"sample variables","variable_keys":"sample variable keys","settings":"sample settings","created_by_id":1,"is_library":true,"library_slug":"sample library slug","locale":"en","preview":"sample preview","archived":true,"archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","source_file":{"url":"https://example.com/resource","filename":"sample filename","content_type":"sample content type","byte_size":"sample byte size"}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"template":{"type":"object","properties":{"name":{"type":"string"},"category":{"type":"string","enum":["MARKETING","UTILITY","AUTHENTICATION"]},"status":{"type":"string","enum":["draft","active"]},"source_format":{"type":"string","enum":["markdown","html","docx","pdf","upload"]},"body":{"type":"string"},"jurisdiction":{"type":"string"},"default_tier":{"type":"string","enum":["simple","advanced","qualified"]},"default_locale":{"type":"string"},"variables":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Free-form object."}},"settings":{"type":"object","additionalProperties":true,"description":"Free-form object."}}}},"required":["template"]},"example":{"template":{"name":"Sample Name","category":"MARKETING","status":"draft","source_format":"markdown","body":"Sample body text.","jurisdiction":"sample jurisdiction","default_tier":"simple","default_locale":"sample default locale","variables":[{}],"settings":{}}}}}}},"delete":{"tags":["Contracts"],"operationId":"auto_delete_api_v1_accounts_account_id_contracts_templates_id","summary":"Delete templates","description":"Deletes the template identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Success (no content)"},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/contracts/clauses/{id}/archive":{"post":{"tags":["Contracts"],"operationId":"auto_post_api_v1_accounts_account_id_contracts_clauses_id_archive","summary":"Archive a reusable clause","description":"Soft-deletes a clause from the reusable clause library by stamping its archive timestamp. The clause stops being offered when composing a template but stays readable through the archived filter and can be restored. Templates that already embed the clause are untouched. On success the endpoint returns HTTP 200 with an EMPTY body.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The clause is archived. Empty body."},"401":{"description":"Unauthorized"},"404":{"description":"No clause with this id exists in the account."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/contracts/clauses/{id}/restore":{"post":{"tags":["Contracts"],"operationId":"auto_post_api_v1_accounts_account_id_contracts_clauses_id_restore","summary":"Restore clauses","description":"Performs the restore operation on the targeted claus resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"title":{"type":"string"},"body_markdown":{"type":"string"},"category":{"type":"string"},"is_system":{"type":"boolean"},"variables":{"type":"string"},"archived":{"type":"boolean"},"archived_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}},"example":{"payload":{"id":1,"title":"Sample title","body_markdown":"sample body markdown","category":"sample category","is_system":true,"variables":"sample variables","archived":true,"archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/contracts/clauses":{"get":{"tags":["Contracts"],"operationId":"auto_get_api_v1_accounts_account_id_contracts_clauses","summary":"List clauses","description":"Returns the list of clauses visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"title":{"type":"string"},"body_markdown":{"type":"string"},"category":{"type":"string"},"is_system":{"type":"boolean"},"variables":{"type":"string"},"archived":{"type":"boolean"},"archived_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}},"meta":{"type":"object","properties":{"count":{"type":"integer"},"current_page":{"type":"string"},"total_pages":{"type":"string"},"per_page":{"type":"string"},"has_more":{"type":"boolean"}}}}},"example":{"payload":[{"id":1,"title":"Sample title","body_markdown":"sample body markdown","category":"sample category","is_system":true,"variables":"sample variables","archived":true,"archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}],"meta":{"count":5,"current_page":"sample current page","total_pages":"sample total pages","per_page":"sample per page","has_more":true}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."}]},"post":{"tags":["Contracts"],"operationId":"auto_post_api_v1_accounts_account_id_contracts_clauses","summary":"Create clauses","description":"Creates a new claus from the request payload. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"title":{"type":"string"},"body_markdown":{"type":"string"},"category":{"type":"string"},"is_system":{"type":"boolean"},"variables":{"type":"string"},"archived":{"type":"boolean"},"archived_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}},"example":{"payload":{"id":1,"title":"Sample title","body_markdown":"sample body markdown","category":"sample category","is_system":true,"variables":"sample variables","archived":true,"archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"clause":{"type":"object","properties":{"title":{"type":"string"},"body_markdown":{"type":"string"},"category":{"type":"string","enum":["MARKETING","UTILITY","AUTHENTICATION"]},"variables":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Free-form object."}}},"required":["title"]}},"required":["clause"]},"example":{"clause":{"title":"Sample title","body_markdown":"sample body markdown","category":"MARKETING","variables":[{}]}}}}}}},"/api/v1/accounts/{account_id}/contracts/clauses/{id}":{"get":{"tags":["Contracts"],"operationId":"auto_get_api_v1_accounts_account_id_contracts_clauses_id","summary":"Get clauses","description":"Returns the claus identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"title":{"type":"string"},"body_markdown":{"type":"string"},"category":{"type":"string"},"is_system":{"type":"boolean"},"variables":{"type":"string"},"archived":{"type":"boolean"},"archived_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}},"example":{"payload":{"id":1,"title":"Sample title","body_markdown":"sample body markdown","category":"sample category","is_system":true,"variables":"sample variables","archived":true,"archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]},"patch":{"tags":["Contracts"],"operationId":"auto_patch_api_v1_accounts_account_id_contracts_clauses_id","summary":"Update clauses","description":"Updates the claus identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"title":{"type":"string"},"body_markdown":{"type":"string"},"category":{"type":"string"},"is_system":{"type":"boolean"},"variables":{"type":"string"},"archived":{"type":"boolean"},"archived_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}},"example":{"payload":{"id":1,"title":"Sample title","body_markdown":"sample body markdown","category":"sample category","is_system":true,"variables":"sample variables","archived":true,"archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"clause":{"type":"object","properties":{"title":{"type":"string"},"body_markdown":{"type":"string"},"category":{"type":"string","enum":["MARKETING","UTILITY","AUTHENTICATION"]},"variables":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Free-form object."}}}}},"required":["clause"]},"example":{"clause":{"title":"Sample title","body_markdown":"sample body markdown","category":"MARKETING","variables":[{}]}}}}}},"put":{"tags":["Contracts"],"operationId":"auto_put_api_v1_accounts_account_id_contracts_clauses_id","summary":"Update clauses","description":"Updates the claus identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"title":{"type":"string"},"body_markdown":{"type":"string"},"category":{"type":"string"},"is_system":{"type":"boolean"},"variables":{"type":"string"},"archived":{"type":"boolean"},"archived_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}},"example":{"payload":{"id":1,"title":"Sample title","body_markdown":"sample body markdown","category":"sample category","is_system":true,"variables":"sample variables","archived":true,"archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"clause":{"type":"object","properties":{"title":{"type":"string"},"body_markdown":{"type":"string"},"category":{"type":"string","enum":["MARKETING","UTILITY","AUTHENTICATION"]},"variables":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Free-form object."}}}}},"required":["clause"]},"example":{"clause":{"title":"Sample title","body_markdown":"sample body markdown","category":"MARKETING","variables":[{}]}}}}}},"delete":{"tags":["Contracts"],"operationId":"auto_delete_api_v1_accounts_account_id_contracts_clauses_id","summary":"Delete clauses","description":"Deletes the claus identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Success (no content)"},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/contracts/settings/upload_logo":{"post":{"tags":["Contracts"],"operationId":"auto_post_api_v1_accounts_account_id_contracts_settings_upload_logo","summary":"Set the account-default contract logo","description":"Administrators may attach a new multipart image or reuse an Active Storage signed identifier owned by this account. Cross-account, malformed, and unattached legacy blob capabilities are rejected.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Logo attached; returns the resolved contract settings."},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"422":{"description":"A logo was not supplied or the signed blob is invalid for this account.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","example":"invalid_attachment_blob"}}},"example":{"error":"invalid_attachment_blob"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["logo_blob_signed_id"],"properties":{"logo_blob_signed_id":{"type":"string","minLength":1,"description":"Account-owned Active Storage signed identifier."}}},"example":{"logo_blob_signed_id":"sample logo blob signed id"}},"multipart/form-data":{"schema":{"type":"object","additionalProperties":false,"anyOf":[{"required":["logo"]},{"required":["setting"]}],"properties":{"logo":{"type":"string","format":"binary","description":"Top-level logo file accepted for backward compatibility."},"setting":{"type":"object","additionalProperties":false,"required":["logo"],"properties":{"logo":{"type":"string","format":"binary","description":"Preferred nested logo file."}}}}}}}}}},"/api/v1/accounts/{account_id}/contracts/settings/remove_logo":{"post":{"tags":["Contracts"],"operationId":"auto_post_api_v1_accounts_account_id_contracts_settings_remove_logo","summary":"Remove logo settings","description":"Performs the remove logo operation on the targeted setting resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"data":{"type":"string"},"resolved":{"type":"object","properties":{"set":{"type":"string"}}},"a1_certificate_present":{"type":"boolean"},"logo_url":{"type":"string"}}}}},"example":{"payload":{"id":1,"data":"sample data","resolved":{"set":"sample set"},"a1_certificate_present":true,"logo_url":"https://example.com/resource"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/contracts/settings":{"get":{"tags":["Contracts"],"operationId":"auto_get_api_v1_accounts_account_id_contracts_settings","summary":"Get settings","description":"Returns the setting identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"data":{"type":"string"},"resolved":{"type":"object","properties":{"set":{"type":"string"}}},"a1_certificate_present":{"type":"boolean"},"logo_url":{"type":"string"}}}}},"example":{"payload":{"id":1,"data":"sample data","resolved":{"set":"sample set"},"a1_certificate_present":true,"logo_url":"https://example.com/resource"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]},"patch":{"tags":["Contracts"],"operationId":"auto_patch_api_v1_accounts_account_id_contracts_settings","summary":"Update the contracts module settings","description":"Merges the given tunables into the account's contract settings and returns the settings. Administrators only. Two of the tunables govern the AI agent and are both off by default: `ai_can_send_for_signature` lets the agent send a contract for signature to the contact of the conversation it is handling, and `ai_can_auto_sign_company` additionally lets that send apply the issuing company's signature without a person reviewing it. Each change to either switch is recorded by the server under `data.ai_policy_audit` (value, user and time); a client-supplied `ai_policy_audit` is ignored.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"data":{"type":"string"},"resolved":{"type":"object","properties":{"set":{"type":"string"}}},"a1_certificate_present":{"type":"boolean"},"logo_url":{"type":"string"}}}}},"example":{"payload":{"id":1,"data":"sample data","resolved":{"set":"sample set"},"a1_certificate_present":true,"logo_url":"https://example.com/resource"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"setting":{"type":"object","properties":{"data":{"type":"object","description":"Tunables deep-merged into the settings row (Contracts::Setting::DEFAULTS).","properties":{"default_tier":{"type":"string","enum":["simple","advanced","qualified"],"example":"simple"},"default_locale":{"type":"string","example":"en"},"default_expiry_days":{"type":"integer","example":30},"retention_years":{"type":"integer","example":5},"region":{"type":"string","example":"BR"},"reminder_policy":{"type":"object","properties":{"enabled":{"type":"boolean","example":true},"sequence_id":{"type":["integer","null"],"example":null}}},"branding":{"type":"object","additionalProperties":true,"description":"Account-level document theme overrides."},"ai_can_send_for_signature":{"type":"boolean","description":"Allows the AI agent (the active AgentBot of an inbox) to send a contract for signature, and only to the contact of the conversation it is handling. Off by default; only the literal boolean true turns it on, any non-boolean value is rejected with 422.","example":false},"ai_can_auto_sign_company":{"type":"boolean","description":"Allows a send made by the AI agent to apply the issuing company signature in the same step, with no person reviewing a legally binding document. Has no effect while ai_can_send_for_signature is off. Off by default; with it off the contract waits for a person to sign for the company.","example":false}}},"a1_certificate":{"type":"string","description":"Base64 PKCS#12 (.pfx) bundle for the qualified tier. Write-only, encrypted at rest, never returned."}}}}},"example":{"setting":{"data":{"default_tier":"simple","default_locale":"en","default_expiry_days":30,"retention_years":5,"region":"BR","reminder_policy":{"enabled":true,"sequence_id":null},"branding":{},"ai_can_send_for_signature":false,"ai_can_auto_sign_company":false},"a1_certificate":"sample a1 certificate"}}}}}},"put":{"tags":["Contracts"],"operationId":"auto_put_api_v1_accounts_account_id_contracts_settings","summary":"Update the contracts module settings","description":"Merges the given tunables into the account's contract settings and returns the settings. Administrators only. Two of the tunables govern the AI agent and are both off by default: `ai_can_send_for_signature` lets the agent send a contract for signature to the contact of the conversation it is handling, and `ai_can_auto_sign_company` additionally lets that send apply the issuing company's signature without a person reviewing it. Each change to either switch is recorded by the server under `data.ai_policy_audit` (value, user and time); a client-supplied `ai_policy_audit` is ignored.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"data":{"type":"string"},"resolved":{"type":"object","properties":{"set":{"type":"string"}}},"a1_certificate_present":{"type":"boolean"},"logo_url":{"type":"string"}}}}},"example":{"payload":{"id":1,"data":"sample data","resolved":{"set":"sample set"},"a1_certificate_present":true,"logo_url":"https://example.com/resource"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"setting":{"type":"object","properties":{"data":{"type":"object","description":"Tunables deep-merged into the settings row (Contracts::Setting::DEFAULTS).","properties":{"default_tier":{"type":"string","enum":["simple","advanced","qualified"],"example":"simple"},"default_locale":{"type":"string","example":"en"},"default_expiry_days":{"type":"integer","example":30},"retention_years":{"type":"integer","example":5},"region":{"type":"string","example":"BR"},"reminder_policy":{"type":"object","properties":{"enabled":{"type":"boolean","example":true},"sequence_id":{"type":["integer","null"],"example":null}}},"branding":{"type":"object","additionalProperties":true,"description":"Account-level document theme overrides."},"ai_can_send_for_signature":{"type":"boolean","description":"Allows the AI agent (the active AgentBot of an inbox) to send a contract for signature, and only to the contact of the conversation it is handling. Off by default; only the literal boolean true turns it on, any non-boolean value is rejected with 422.","example":false},"ai_can_auto_sign_company":{"type":"boolean","description":"Allows a send made by the AI agent to apply the issuing company signature in the same step, with no person reviewing a legally binding document. Has no effect while ai_can_send_for_signature is off. Off by default; with it off the contract waits for a person to sign for the company.","example":false}}},"a1_certificate":{"type":"string","description":"Base64 PKCS#12 (.pfx) bundle for the qualified tier. Write-only, encrypted at rest, never returned."}}}}},"example":{"setting":{"data":{"default_tier":"simple","default_locale":"en","default_expiry_days":30,"retention_years":5,"region":"BR","reminder_policy":{"enabled":true,"sequence_id":null},"branding":{},"ai_can_send_for_signature":false,"ai_can_auto_sign_company":false},"a1_certificate":"sample a1 certificate"}}}}}}},"/api/v1/accounts/{account_id}/contracts/message_settings/preview":{"post":{"tags":["Contracts"],"operationId":"auto_post_api_v1_accounts_account_id_contracts_message_settings_preview","summary":"Preview message settings","description":"Performs the preview operation on the targeted message setting resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The rendered body per channel plus the resolved out-of-window template. Nothing is persisted.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"locale":{"type":"string","description":"The locale the preview rendered in.","example":"pt_BR"},"sample_present":{"type":"boolean","description":"False when the account has no record of this module yet — the variables then render blank.","example":true},"variables":{"type":"object","description":"The resolved variable map of the module drop (token -\u003e value). Keys are module-specific.","additionalProperties":{"type":"string"},"example":{"title":"Prestação de serviços","status":"pending_signature","sign_url":"https://app.example/contracts/sign/abc"}},"rendered":{"type":"string","description":"The body with its Liquid resolved (before per-channel rendering).","example":"Olá Ana Silva, assine Prestação de serviços: https://app.example/contracts/sign/abc"},"rendered_by_channel":{"type":"object","description":"One entry per channel type the ACCOUNT has an inbox of, rendered by Messages::MarkdownRendererService.","additionalProperties":{"type":"string"},"example":{"Channel::Whatsapp":"Olá Ana Silva, assine Prestação de serviços: https://app.example/contracts/sign/abc"}},"buttons":{"type":"array","description":"The NATIVE interactive buttons the send will attach for this type, already capped to what the chosen provider renders — Meta's `cta_url` carries exactly ONE button, so a second one is dropped here rather than promised. Empty when the type ships no button, the operator turned the switch off, or the channel has no interactive surface.","items":{"type":"object","properties":{"type":{"type":"string","enum":["cta_url","cta_copy"],"description":"cta_url opens a link; cta_copy copies a code to the clipboard (WhatsApp Web / API only).","example":"cta_url"},"text":{"type":"string","description":"The button caption","from the module's auxiliary labels.":null,"example":"Pagar agora"},"url":{"type":"string","description":"Present for cta_url.","example":"https://checkout.example/c/1"},"code":{"type":"string","description":"Present for cta_copy.","example":"00020126580014BR.GOV.BCB.PIX"}}},"example":[{"type":"cta_url","text":"Pagar agora","url":"https://checkout.example/c/1"}]},"defaults":{"type":"object","description":"The SHIPPED copy behind each key named in the request's `types` / `labels` — what an empty cell actually sends, so the editor can show it instead of only claiming it exists. Both maps are empty when the account has no record of this module yet (the shipped lines interpolate that record and are never fabricated).","properties":{"bodies":{"type":"object","description":"message type -\u003e shipped body, in the previewed locale.","additionalProperties":{"type":"string"},"example":{"cart_abandoned":"Abandoned cart"}},"labels":{"type":"object","description":"label key -\u003e shipped text, in the previewed locale.","additionalProperties":{"type":"string"},"example":{"pay_label":"Pay / resume:"}}}},"hsm":{"type":["object","null"],"description":"The resolved out-of-window template params, or null when none applies.","properties":{"name":{"type":"string","example":"contracts_send_contract_pt_br"},"language":{"type":"string","example":"pt_BR"},"processed_params":{"type":"object","description":"Meta component params: `body` is a 1-indexed map, `buttons` is present only for a dynamic URL button.","additionalProperties":true,"example":{"body":{"1":"Prestação de serviços"}}}}}}}}},"example":{"payload":{"locale":"pt_BR","sample_present":true,"variables":{"title":"Prestação de serviços","status":"pending_signature","sign_url":"https://app.example/contracts/sign/abc"},"rendered":"Olá Ana Silva, assine Prestação de serviços: https://app.example/contracts/sign/abc","rendered_by_channel":{"Channel::Whatsapp":"Olá Ana Silva, assine Prestação de serviços: https://app.example/contracts/sign/abc"},"buttons":[{"type":"cta_url","text":"Pagar agora","url":"https://checkout.example/c/1","code":"00020126580014BR.GOV.BCB.PIX"}],"defaults":{"bodies":{"cart_abandoned":"Abandoned cart"},"labels":{"pay_label":"Pay / resume:"}},"hsm":{"name":"contracts_send_contract_pt_br","language":"pt_BR","processed_params":{"body":{"1":"Prestação de serviços"}}}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"The unsaved cell the operator is looking at — nothing is persisted.","properties":{"type":{"type":"string","description":"Message type being previewed.","example":"send_contract"},"locale":{"type":"string","description":"Locale to render in; omitted falls back to the record cascade (contact -\u003e conversation -\u003e account).","example":"pt_BR"},"body":{"type":"string","description":"Markdown body with `{{ variable }}` tokens, exactly as authored in the editor.","example":"Olá {{ contact.name }}, assine {{ contract.title }}: {{ contract.sign_url }}"},"scope":{"type":["string","null"],"description":"Per-surface override scope (e.g. `automation:12`). Omit for the account default.","example":"automation:12"},"whatsapp_template":{"type":"object","description":"The approved HSM the editor is holding. Omitted, the stored per-type x per-locale template is resolved instead.","properties":{"name":{"type":"string","example":"contracts_send_contract_pt_br"},"language":{"type":"string","example":"pt_BR"},"url_button":{"type":"string","description":"Variable name or literal filling a dynamic URL button.","example":"sign_url"},"params":{"type":"array","description":"Positional body params: a variable name resolves from the message variable map, anything else is a literal.","items":{"type":"string"},"example":["title"]}}}}},"example":{"type":"send_contract","locale":"pt_BR","body":"Olá {{ contact.name }}, assine {{ contract.title }}: {{ contract.sign_url }}","scope":"automation:12","whatsapp_template":{"name":"contracts_send_contract_pt_br","language":"pt_BR","url_button":"sign_url","params":["title"]}}}}}}},"/api/v1/accounts/{account_id}/contracts/message_settings/test_send":{"post":{"tags":["Contracts"],"operationId":"auto_post_api_v1_accounts_account_id_contracts_message_settings_test_send","summary":"Test send message settings","description":"Performs the test send operation on the targeted message setting resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The outcome of the send, which honours the WhatsApp 24h window exactly as the real sender does.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"status":{"type":"string","enum":["sent","skipped","failed"],"description":"sent = a message was created; skipped = nothing was sent (see reason); failed = the send raised.","example":"sent"},"reason":{"type":["string","null"],"description":"Canonical skip/failure reason: `whatsapp_window_closed` (the 24h window is closed and no approved template is configured) or `empty_body`. Null when sent.","example":"whatsapp_window_closed"},"content":{"type":"string","description":"The rendered body that was sent (or would have been).","example":"Olá Ana Silva, assine Prestação de serviços: https://app.example/contracts/sign/abc"},"message_id":{"type":["integer","null"],"description":"The created message id; null on skip/failure.","example":9001}}}}},"example":{"payload":{"status":"sent","reason":"whatsapp_window_closed","content":"Olá Ana Silva, assine Prestação de serviços: https://app.example/contracts/sign/abc","message_id":9001}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"422":{"description":"No conversation was given (`conversation_required`), so there is nothing to send into.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"conversation_required"}}},"example":{"error":"conversation_required"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["conversation_id"],"description":"Sends ONE real message into an EXISTING conversation. Never creates a conversation.","properties":{"conversation_id":{"type":"string","description":"Conversation display_id (an internal id is accepted as a fallback).","example":"42"},"type":{"type":"string","description":"Message type being tested.","example":"send_contract"},"locale":{"type":"string","example":"pt_BR"},"body":{"type":"string","description":"Markdown body","exactly as authored in the editor.":null,"example":"Olá {{ contact.name }}, assine {{ contract.title }}: {{ contract.sign_url }}"},"scope":{"type":["string","null"],"example":"automation:12"},"whatsapp_template":{"type":"object","description":"The approved HSM the editor is holding, used when the 24h window is closed.","properties":{"name":{"type":"string","example":"contracts_send_contract_pt_br"},"language":{"type":"string","example":"pt_BR"},"url_button":{"type":"string","example":"sign_url"},"params":{"type":"array","items":{"type":"string"},"example":["title"]}}}}},"example":{"conversation_id":"42","type":"send_contract","locale":"pt_BR","body":"Olá {{ contact.name }}, assine {{ contract.title }}: {{ contract.sign_url }}","scope":"automation:12","whatsapp_template":{"name":"contracts_send_contract_pt_br","language":"pt_BR","url_button":"sign_url","params":["title"]}}}}}}},"/api/v1/accounts/{account_id}/contracts/message_settings":{"get":{"tags":["Contracts"],"operationId":"auto_get_api_v1_accounts_account_id_contracts_message_settings","summary":"Get message settings","description":"Returns the message setting identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"scope":{"type":"string"},"messages":{"type":"string"},"delivery":{"type":"object","description":"Who was actually reached. It exists so a 200 can never again mean only \"the request did not crash\": the send and remind endpoints used to answer with an empty body while delivery failures were swallowed, so an operator was told \"sent\" for a message that never left.","properties":{"status":{"type":"string","enum":["delivered","partial","failed","skipped","blocked"],"description":"delivered = every pending signer was reached · partial = some were, some were not · failed = none were (the contract may still have advanced — that is exactly what the caller must see) · skipped = there was nobody to deliver to · blocked = the pre-flight refused the send, so nothing changed at all.","example":"partial"},"signers":{"type":"array","description":"One entry per pending signer. Empty when status is `skipped`.","items":{"type":"object","properties":{"signer_id":{"type":"integer","description":"The signer this entry is about.","example":4711},"name":{"type":"string","description":"The signer's name","so the operator reads who instead of an id.":null,"example":"Maria Souza"},"role":{"type":"string","enum":["contractor","contracted","witness","guarantor"],"description":"The party's role in the contract.","example":"contractor"},"status":{"type":"string","enum":["delivered","failed","blocked"],"description":"Whether this specific party received the request.","example":"failed"},"reason":{"type":"string","enum":["no_destination","no_inbox","channel_unavailable","hsm_template_without_url_button","no_signing_link","delivery_error","ai_not_active_in_conversation","ai_email_destination","ai_conversation_to_create","ai_other_conversation","publication_pending"],"description":"A canonical token, never a sentence, so a dashboard and an agentic executor can both branch on it. Absent on ordinary success. publication_pending means a Message was durably recorded and the token/PDF remain valid, while queue publication or a callback needs confirmation; do not send a new sequence with another key. The `ai_*` tokens appear only when the caller is the AI agent and mean a person must send the contract.","example":"no_destination"},"message_ids":{"type":"array","items":{"type":"integer"},"description":"Durable Message ids of a bot delivery, reused on a retry with the same idempotency key."},"publication_errors":{"type":"array","items":{"type":"object","properties":{"error_class":{"type":"string","description":"Sanitized exception class only; no exception message or provider payload."}}},"description":"Publication failures recorded after a durable Message; present on bot sends."},"channel":{"type":"string","enum":["conversation","email"],"description":"Where the request went. Absent when the entry failed.","example":"email"}}}}}}}}}},"example":{"payload":{"scope":"sample scope","messages":"sample messages","delivery":{"status":"partial","signers":[{"signer_id":4711,"name":"Maria Souza","role":"contractor","status":"failed","reason":"no_destination","message_ids":[1],"publication_errors":[{"error_class":"sample error class"}],"channel":"email"}]}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]},"patch":{"tags":["Contracts"],"operationId":"auto_patch_api_v1_accounts_account_id_contracts_message_settings","summary":"Update message settings","description":"Updates the message setting identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"scope":{"type":"string"},"messages":{"type":"string"},"delivery":{"type":"object","description":"Who was actually reached. It exists so a 200 can never again mean only \"the request did not crash\": the send and remind endpoints used to answer with an empty body while delivery failures were swallowed, so an operator was told \"sent\" for a message that never left.","properties":{"status":{"type":"string","enum":["delivered","partial","failed","skipped","blocked"],"description":"delivered = every pending signer was reached · partial = some were, some were not · failed = none were (the contract may still have advanced — that is exactly what the caller must see) · skipped = there was nobody to deliver to · blocked = the pre-flight refused the send, so nothing changed at all.","example":"partial"},"signers":{"type":"array","description":"One entry per pending signer. Empty when status is `skipped`.","items":{"type":"object","properties":{"signer_id":{"type":"integer","description":"The signer this entry is about.","example":4711},"name":{"type":"string","description":"The signer's name","so the operator reads who instead of an id.":null,"example":"Maria Souza"},"role":{"type":"string","enum":["contractor","contracted","witness","guarantor"],"description":"The party's role in the contract.","example":"contractor"},"status":{"type":"string","enum":["delivered","failed","blocked"],"description":"Whether this specific party received the request.","example":"failed"},"reason":{"type":"string","enum":["no_destination","no_inbox","channel_unavailable","hsm_template_without_url_button","no_signing_link","delivery_error","ai_not_active_in_conversation","ai_email_destination","ai_conversation_to_create","ai_other_conversation","publication_pending"],"description":"A canonical token, never a sentence, so a dashboard and an agentic executor can both branch on it. Absent on ordinary success. publication_pending means a Message was durably recorded and the token/PDF remain valid, while queue publication or a callback needs confirmation; do not send a new sequence with another key. The `ai_*` tokens appear only when the caller is the AI agent and mean a person must send the contract.","example":"no_destination"},"message_ids":{"type":"array","items":{"type":"integer"},"description":"Durable Message ids of a bot delivery, reused on a retry with the same idempotency key."},"publication_errors":{"type":"array","items":{"type":"object","properties":{"error_class":{"type":"string","description":"Sanitized exception class only; no exception message or provider payload."}}},"description":"Publication failures recorded after a durable Message; present on bot sends."},"channel":{"type":"string","enum":["conversation","email"],"description":"Where the request went. Absent when the entry failed.","example":"email"}}}}}}}}}},"example":{"payload":{"scope":"sample scope","messages":"sample messages","delivery":{"status":"partial","signers":[{"signer_id":4711,"name":"Maria Souza","role":"contractor","status":"failed","reason":"no_destination","message_ids":[1],"publication_errors":[{"error_class":"sample error class"}],"channel":"email"}]}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"scope":{"type":"string"},"clear":{"type":"array","items":{"type":"string"}}},"additionalProperties":true},"example":{"scope":"sample scope","clear":["sample clear"]}}}}},"put":{"tags":["Contracts"],"operationId":"auto_put_api_v1_accounts_account_id_contracts_message_settings","summary":"Update message settings","description":"Updates the message setting identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"scope":{"type":"string"},"messages":{"type":"string"},"delivery":{"type":"object","description":"Who was actually reached. It exists so a 200 can never again mean only \"the request did not crash\": the send and remind endpoints used to answer with an empty body while delivery failures were swallowed, so an operator was told \"sent\" for a message that never left.","properties":{"status":{"type":"string","enum":["delivered","partial","failed","skipped","blocked"],"description":"delivered = every pending signer was reached · partial = some were, some were not · failed = none were (the contract may still have advanced — that is exactly what the caller must see) · skipped = there was nobody to deliver to · blocked = the pre-flight refused the send, so nothing changed at all.","example":"partial"},"signers":{"type":"array","description":"One entry per pending signer. Empty when status is `skipped`.","items":{"type":"object","properties":{"signer_id":{"type":"integer","description":"The signer this entry is about.","example":4711},"name":{"type":"string","description":"The signer's name","so the operator reads who instead of an id.":null,"example":"Maria Souza"},"role":{"type":"string","enum":["contractor","contracted","witness","guarantor"],"description":"The party's role in the contract.","example":"contractor"},"status":{"type":"string","enum":["delivered","failed","blocked"],"description":"Whether this specific party received the request.","example":"failed"},"reason":{"type":"string","enum":["no_destination","no_inbox","channel_unavailable","hsm_template_without_url_button","no_signing_link","delivery_error","ai_not_active_in_conversation","ai_email_destination","ai_conversation_to_create","ai_other_conversation","publication_pending"],"description":"A canonical token, never a sentence, so a dashboard and an agentic executor can both branch on it. Absent on ordinary success. publication_pending means a Message was durably recorded and the token/PDF remain valid, while queue publication or a callback needs confirmation; do not send a new sequence with another key. The `ai_*` tokens appear only when the caller is the AI agent and mean a person must send the contract.","example":"no_destination"},"message_ids":{"type":"array","items":{"type":"integer"},"description":"Durable Message ids of a bot delivery, reused on a retry with the same idempotency key."},"publication_errors":{"type":"array","items":{"type":"object","properties":{"error_class":{"type":"string","description":"Sanitized exception class only; no exception message or provider payload."}}},"description":"Publication failures recorded after a durable Message; present on bot sends."},"channel":{"type":"string","enum":["conversation","email"],"description":"Where the request went. Absent when the entry failed.","example":"email"}}}}}}}}}},"example":{"payload":{"scope":"sample scope","messages":"sample messages","delivery":{"status":"partial","signers":[{"signer_id":4711,"name":"Maria Souza","role":"contractor","status":"failed","reason":"no_destination","message_ids":[1],"publication_errors":[{"error_class":"sample error class"}],"channel":"email"}]}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"scope":{"type":"string"},"clear":{"type":"array","items":{"type":"string"}}},"additionalProperties":true},"example":{"scope":"sample scope","clear":["sample clear"]}}}}},"delete":{"tags":["Contracts"],"operationId":"auto_delete_api_v1_accounts_account_id_contracts_message_settings","summary":"Delete message settings","description":"Deletes the message setting identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"scope":{"type":"string"},"messages":{"type":"string"},"delivery":{"type":"object","description":"Who was actually reached. It exists so a 200 can never again mean only \"the request did not crash\": the send and remind endpoints used to answer with an empty body while delivery failures were swallowed, so an operator was told \"sent\" for a message that never left.","properties":{"status":{"type":"string","enum":["delivered","partial","failed","skipped","blocked"],"description":"delivered = every pending signer was reached · partial = some were, some were not · failed = none were (the contract may still have advanced — that is exactly what the caller must see) · skipped = there was nobody to deliver to · blocked = the pre-flight refused the send, so nothing changed at all.","example":"partial"},"signers":{"type":"array","description":"One entry per pending signer. Empty when status is `skipped`.","items":{"type":"object","properties":{"signer_id":{"type":"integer","description":"The signer this entry is about.","example":4711},"name":{"type":"string","description":"The signer's name","so the operator reads who instead of an id.":null,"example":"Maria Souza"},"role":{"type":"string","enum":["contractor","contracted","witness","guarantor"],"description":"The party's role in the contract.","example":"contractor"},"status":{"type":"string","enum":["delivered","failed","blocked"],"description":"Whether this specific party received the request.","example":"failed"},"reason":{"type":"string","enum":["no_destination","no_inbox","channel_unavailable","hsm_template_without_url_button","no_signing_link","delivery_error","ai_not_active_in_conversation","ai_email_destination","ai_conversation_to_create","ai_other_conversation","publication_pending"],"description":"A canonical token, never a sentence, so a dashboard and an agentic executor can both branch on it. Absent on ordinary success. publication_pending means a Message was durably recorded and the token/PDF remain valid, while queue publication or a callback needs confirmation; do not send a new sequence with another key. The `ai_*` tokens appear only when the caller is the AI agent and mean a person must send the contract.","example":"no_destination"},"message_ids":{"type":"array","items":{"type":"integer"},"description":"Durable Message ids of a bot delivery, reused on a retry with the same idempotency key."},"publication_errors":{"type":"array","items":{"type":"object","properties":{"error_class":{"type":"string","description":"Sanitized exception class only; no exception message or provider payload."}}},"description":"Publication failures recorded after a durable Message; present on bot sends."},"channel":{"type":"string","enum":["conversation","email"],"description":"Where the request went. Absent when the entry failed.","example":"email"}}}}}}}}}},"example":{"payload":{"scope":"sample scope","messages":"sample messages","delivery":{"status":"partial","signers":[{"signer_id":4711,"name":"Maria Souza","role":"contractor","status":"failed","reason":"no_destination","message_ids":[1],"publication_errors":[{"error_class":"sample error class"}],"channel":"email"}]}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/contracts/theme_preview":{"post":{"tags":["Contracts"],"operationId":"auto_post_api_v1_accounts_account_id_contracts_theme_preview","summary":"Create theme preview","description":"Creates a new theme preview from the request payload. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"File download","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"company_id":{"type":["integer","null"],"description":"Preview a specific company's cascade.","example":4},"template_id":{"type":["integer","null"],"description":"Preview a specific template's cascade.","example":3},"theme":{"type":"object","description":"Unsaved theme override merged over the resolved cascade (Contracts::ThemeResolver::DEFAULT_THEME).","properties":{"header":{"type":"object","properties":{"logo_url":{"type":["string","null"],"example":"https://cdn.example.com/logo.png"},"logo_position":{"type":"string","enum":["left","center","right"],"example":"left"},"show_company_name":{"type":"boolean","example":true},"show_company_cnpj":{"type":"boolean","example":true},"show_company_address":{"type":"boolean","example":true}}},"branding":{"type":"object","properties":{"primary_color":{"type":"string","example":"#1F73B7"},"secondary_color":{"type":"string","example":"#6B7280"},"accent_color":{"type":"string","example":"#0E7C5A"},"heading_color":{"type":"string","example":"#1F2A37"},"text_color":{"type":"string","example":"#1F2A37"},"font_family":{"type":"string","enum":["Helvetica","Times","Courier"],"example":"Helvetica"},"font_size_body":{"type":"integer","example":10},"font_size_title":{"type":"integer","example":20}}},"page":{"type":"object","properties":{"size":{"type":"string","enum":["A4","LETTER"],"example":"A4"},"orientation":{"type":"string","enum":["portrait","landscape"],"example":"portrait"},"margins":{"type":"object","properties":{"top":{"type":"integer","example":54},"bottom":{"type":"integer","example":64},"left":{"type":"integer","example":54},"right":{"type":"integer","example":54}}},"border":{"type":"object","properties":{"show":{"type":"boolean","example":false},"color":{"type":"string","example":"#D1D5DB"},"width":{"type":"integer","example":1}}},"watermark":{"type":"object","properties":{"text":{"type":["string","null"],"example":null},"opacity":{"type":"number","example":0.08}}}}},"footer":{"type":"object","properties":{"show_page_number":{"type":"boolean","example":true},"page_number_position":{"type":"string","enum":["left","center","right"],"example":"right"},"page_number_format":{"type":"string","example":"%\u003cpage\u003es / %\u003ctotal\u003es"},"show_legal_disclaimer":{"type":"boolean","example":true},"legal_disclaimer_text":{"type":["string","null"],"example":null}}},"signatures":{"type":"object","properties":{"layout":{"type":"string","enum":["stacked","grid"],"example":"stacked"},"roles":{"type":"array","items":{"type":"string"},"example":[]},"show_witnesses":{"type":"boolean","example":true},"witness_count":{"type":"integer","example":0},"show_a1_badge":{"type":"boolean","example":true},"a1_badge_position":{"type":"string","example":"inline"},"block_width_percent":{"type":"integer","example":100}}}}}}},"example":{"company_id":4,"template_id":3,"theme":{"header":{"logo_url":"https://cdn.example.com/logo.png","logo_position":"left","show_company_name":true,"show_company_cnpj":true,"show_company_address":true},"branding":{"primary_color":"#1F73B7","secondary_color":"#6B7280","accent_color":"#0E7C5A","heading_color":"#1F2A37","text_color":"#1F2A37","font_family":"Helvetica","font_size_body":10,"font_size_title":20},"page":{"size":"A4","orientation":"portrait","margins":{"top":54,"bottom":64,"left":54,"right":54},"border":{"show":false,"color":"#D1D5DB","width":1},"watermark":{"text":null,"opacity":0.08}},"footer":{"show_page_number":true,"page_number_position":"right","page_number_format":"%\u003cpage\u003es / %\u003ctotal\u003es","show_legal_disclaimer":true,"legal_disclaimer_text":null},"signatures":{"layout":"stacked","roles":[],"show_witnesses":true,"witness_count":0,"show_a1_badge":true,"a1_badge_position":"inline","block_width_percent":100}}}}}}}},"/api/v1/accounts/{account_id}/contracts/demo":{"delete":{"tags":["Contracts"],"operationId":"auto_delete_api_v1_accounts_account_id_contracts_demo","summary":"Delete demo","description":"Deletes the demo identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"202":{"description":"Success (no content)"},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]},"post":{"tags":["Contracts"],"operationId":"auto_post_api_v1_accounts_account_id_contracts_demo","summary":"Seed contracts demo data","description":"Enqueues the creation of a complete set of demo data for the contracts module — the template library, an issuing company, demo contacts and several contracts in different signature states — so the module can be explored with realistic records. The work is heavy and runs in the background, so the request returns immediately with HTTP 202 and an EMPTY body before the data exists; poll the contract list to watch it land. Sending the matching delete request removes the demo data again.","security":[{"userApiKey":[]}],"responses":{"202":{"description":"The demo seed was accepted and will run in the background. Empty body — the demo records do not exist yet when this response is received."},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/contracts/{id}/duplicate":{"post":{"tags":["Contracts"],"operationId":"auto_post_api_v1_accounts_account_id_contracts_id_duplicate","summary":"Duplicate contracts","description":"Performs the duplicate operation on the targeted contract resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"title":{"type":"string"},"status":{"type":"string","enum":["draft","pending_signature","partially_signed","completed","rejected","expired","voided","canceled"]},"signature_tier":{"type":"string","enum":["simple","advanced","qualified"]},"region":{"type":"string"},"locale":{"type":"string"},"verification_code":{"type":"string"},"public_verification_url":{"type":"string"},"document_sha256":{"type":"string"},"sent_at":{"type":"string","format":"date-time"},"expires_at":{"type":"string","format":"date-time"},"completed_at":{"type":"string","format":"date-time"},"voided_at":{"type":"string","format":"date-time"},"archived":{"type":"boolean"},"legally_binding":{"type":"boolean"},"company_signature_pending":{"type":"boolean"},"created_by_id":{"type":"integer"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"template_id":{"type":"integer"},"company_id":{"type":"integer"},"company_name":{"type":["string","null"]},"contact_id":{"type":"integer"},"contact_name":{"type":"string"},"conversation_id":{"type":"integer"},"conversation_display_id":{"type":["integer","null"]},"crm_item_id":{"type":"integer"},"payments_charge_id":{"type":"integer"},"payments_subscription_id":{"type":"integer"},"calendar_booking_id":{"type":"integer"},"follow_up_enrollment_id":{"type":"integer"},"variables_snapshot":{"type":"object","additionalProperties":true,"description":"Merge variables captured at send-time, keyed by template variable name."},"metadata":{"type":"object","additionalProperties":true,"description":"Free-form metadata bag; the key set depends on the record and context."},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"signers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"role":{"type":"string","enum":["contractor","contracted","witness","guarantor"]},"name":{"type":"string"},"email":{"type":"string","format":"email"},"phone":{"type":"string"},"document":{"type":"string"},"status":{"type":"string","enum":["pending","viewed","signed","rejected"]},"auth_method":{"type":"string","enum":["none","email_otp","whatsapp_otp","icp_brasil"]},"auto_sign":{"type":"string"},"sign_order":{"type":"string"},"is_responsible":{"type":"boolean"},"signed_at":{"type":"string","format":"date-time"},"contact_id":{"type":"integer"},"company_id":{"type":"integer"},"has_signing_token":{"type":"boolean"}}}},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"kind":{"type":"string","enum":["product","service","fee","discount"],"description":"The kind of contract line item."},"name":{"type":"string"},"price":{"type":"number"},"quantity":{"type":"string"},"currency":{"type":"string"},"line_total":{"type":"number"},"catalog_product_id":{"type":"integer"},"clause":{"type":"string"}}}},"signers_count":{"type":"integer"},"signed_count":{"type":"integer"},"body_snapshot":{"type":"string"}}}}},"example":{"payload":{"id":1,"title":"Sample title","status":"draft","signature_tier":"simple","region":"sample region","locale":"en","verification_code":"sample verification code","public_verification_url":"https://example.com/resource","document_sha256":"sample document sha256","sent_at":"2026-01-15T10:30:00.000Z","expires_at":"2026-01-15T10:30:00.000Z","completed_at":"2026-01-15T10:30:00.000Z","voided_at":"2026-01-15T10:30:00.000Z","archived":true,"legally_binding":true,"company_signature_pending":true,"created_by_id":1,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","template_id":1,"company_id":1,"company_name":"sample company name","contact_id":1,"contact_name":"sample contact name","conversation_id":1,"conversation_display_id":1,"crm_item_id":1,"payments_charge_id":1,"payments_subscription_id":1,"calendar_booking_id":1,"follow_up_enrollment_id":1,"variables_snapshot":{},"metadata":{},"custom_attributes":{},"signers":[{"id":1,"role":"contractor","name":"Sample Name","email":"agent@example.com","phone":"+5511999998888","document":"sample document","status":"pending","auth_method":"none","auto_sign":"sample auto sign","sign_order":"sample sign order","is_responsible":true,"signed_at":"2026-01-15T10:30:00.000Z","contact_id":1,"company_id":1,"has_signing_token":true}],"items":[{"id":1,"kind":"product","name":"Sample Name","price":149.9,"quantity":"sample quantity","currency":"BRL","line_total":149.9,"catalog_product_id":1,"clause":"sample clause"}],"signers_count":5,"signed_count":5,"body_snapshot":"sample body snapshot"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/contracts/{id}/archive":{"post":{"tags":["Contracts"],"operationId":"auto_post_api_v1_accounts_account_id_contracts_id_archive","summary":"Archive a contract","description":"Soft-deletes a contract by stamping its archive timestamp. The contract leaves the default list and is reachable through the archived filter; signatures, documents and the forensic event timeline are preserved, and the contract can be restored. Archiving is also the required first step before a non-binding draft can be permanently deleted. On success the endpoint returns HTTP 200 with an EMPTY body.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The contract is archived. Empty body."},"401":{"description":"Unauthorized"},"404":{"description":"No contract with this id exists in the account."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/contracts/{id}/restore":{"post":{"tags":["Contracts"],"operationId":"auto_post_api_v1_accounts_account_id_contracts_id_restore","summary":"Restore contracts","description":"Performs the restore operation on the targeted contract resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"title":{"type":"string"},"status":{"type":"string","enum":["draft","pending_signature","partially_signed","completed","rejected","expired","voided","canceled"]},"signature_tier":{"type":"string","enum":["simple","advanced","qualified"]},"region":{"type":"string"},"locale":{"type":"string"},"verification_code":{"type":"string"},"public_verification_url":{"type":"string"},"document_sha256":{"type":"string"},"sent_at":{"type":"string","format":"date-time"},"expires_at":{"type":"string","format":"date-time"},"completed_at":{"type":"string","format":"date-time"},"voided_at":{"type":"string","format":"date-time"},"archived":{"type":"boolean"},"legally_binding":{"type":"boolean"},"company_signature_pending":{"type":"boolean"},"created_by_id":{"type":"integer"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"template_id":{"type":"integer"},"company_id":{"type":"integer"},"company_name":{"type":["string","null"]},"contact_id":{"type":"integer"},"contact_name":{"type":"string"},"conversation_id":{"type":"integer"},"conversation_display_id":{"type":["integer","null"]},"crm_item_id":{"type":"integer"},"payments_charge_id":{"type":"integer"},"payments_subscription_id":{"type":"integer"},"calendar_booking_id":{"type":"integer"},"follow_up_enrollment_id":{"type":"integer"},"variables_snapshot":{"type":"object","additionalProperties":true,"description":"Merge variables captured at send-time, keyed by template variable name."},"metadata":{"type":"object","additionalProperties":true,"description":"Free-form metadata bag; the key set depends on the record and context."},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"signers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"role":{"type":"string","enum":["contractor","contracted","witness","guarantor"]},"name":{"type":"string"},"email":{"type":"string","format":"email"},"phone":{"type":"string"},"document":{"type":"string"},"status":{"type":"string","enum":["pending","viewed","signed","rejected"]},"auth_method":{"type":"string","enum":["none","email_otp","whatsapp_otp","icp_brasil"]},"auto_sign":{"type":"string"},"sign_order":{"type":"string"},"is_responsible":{"type":"boolean"},"signed_at":{"type":"string","format":"date-time"},"contact_id":{"type":"integer"},"company_id":{"type":"integer"},"has_signing_token":{"type":"boolean"}}}},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"kind":{"type":"string","enum":["product","service","fee","discount"],"description":"The kind of contract line item."},"name":{"type":"string"},"price":{"type":"number"},"quantity":{"type":"string"},"currency":{"type":"string"},"line_total":{"type":"number"},"catalog_product_id":{"type":"integer"},"clause":{"type":"string"}}}},"signers_count":{"type":"integer"},"signed_count":{"type":"integer"},"body_snapshot":{"type":"string"}}}}},"example":{"payload":{"id":1,"title":"Sample title","status":"draft","signature_tier":"simple","region":"sample region","locale":"en","verification_code":"sample verification code","public_verification_url":"https://example.com/resource","document_sha256":"sample document sha256","sent_at":"2026-01-15T10:30:00.000Z","expires_at":"2026-01-15T10:30:00.000Z","completed_at":"2026-01-15T10:30:00.000Z","voided_at":"2026-01-15T10:30:00.000Z","archived":true,"legally_binding":true,"company_signature_pending":true,"created_by_id":1,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","template_id":1,"company_id":1,"company_name":"sample company name","contact_id":1,"contact_name":"sample contact name","conversation_id":1,"conversation_display_id":1,"crm_item_id":1,"payments_charge_id":1,"payments_subscription_id":1,"calendar_booking_id":1,"follow_up_enrollment_id":1,"variables_snapshot":{},"metadata":{},"custom_attributes":{},"signers":[{"id":1,"role":"contractor","name":"Sample Name","email":"agent@example.com","phone":"+5511999998888","document":"sample document","status":"pending","auth_method":"none","auto_sign":"sample auto sign","sign_order":"sample sign order","is_responsible":true,"signed_at":"2026-01-15T10:30:00.000Z","contact_id":1,"company_id":1,"has_signing_token":true}],"items":[{"id":1,"kind":"product","name":"Sample Name","price":149.9,"quantity":"sample quantity","currency":"BRL","line_total":149.9,"catalog_product_id":1,"clause":"sample clause"}],"signers_count":5,"signed_count":5,"body_snapshot":"sample body snapshot"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/contracts/{id}/send_for_signature":{"post":{"tags":["Contracts"],"operationId":"auto_post_api_v1_accounts_account_id_contracts_id_send_for_signature","summary":"Send a contract for signature","description":"Validates every pending signer has a reachable destination, renders the document, delivers the signing request to each party on their own channel, and only then flips the contract to `pending_signature`, stamps `sent_at` and applies the issuing company's automatic signature. Because the checks run BEFORE any state change, a 422 leaves the contract exactly as it was — no contact is created, no signature is applied. A 200 whose `delivery.status` is `partial` means the contract advanced but at least one party was not reached; `delivery.signers[].reason` says which and why. Human callers send as themselves; the bot authorization rules below apply only to bot callers. Bot callers must name a `conversation_id` and authenticate as the active bot bound to that conversation's inbox; the signing card is then authored by that bot, and any other bot, or a user credential asserting bot authorship, is refused with 401. A bot send is further limited by the account's contract settings: it is refused with 422 `contract_ai_send_disabled` unless `ai_can_send_for_signature` is on; it is refused with 422 `contract_send_requires_human` unless every pending signer is the contact of that same conversation (never by e-mail, never into another conversation or a conversation that would have to be created); and it does NOT apply the issuing company's signature unless `ai_can_auto_sign_company` is also on — otherwise the contract is delivered and stays `company_signature_pending` until a person signs for the company. A bot send that reached nobody is refused with 422 `contract_send_not_delivered` and the contract does not advance. This is the only contract action a bot may call. The current AI switches and signer/contact bindings are reread before delivery; the company-signature switch is reread under the settings lock at the actual signature boundary. A revocation before that boundary leaves the company side pending; a signature already applied is never undone. Once a signing-request Message is durably persisted, queue publication or callback failure does not roll the contract back or invalidate its token/PDF: the response remains successful with `delivery.signers[].reason = publication_pending`, Message ids and sanitized error classes. Retry with the SAME idempotency key reuses the authored Messages.","security":[{"agentBotApiKey":[]},{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"delivery":{"type":"object","description":"Who was actually reached. It exists so a 200 can never again mean only \"the request did not crash\": the send and remind endpoints used to answer with an empty body while delivery failures were swallowed, so an operator was told \"sent\" for a message that never left.","properties":{"status":{"type":"string","enum":["delivered","partial","failed","skipped","blocked"],"description":"delivered = every pending signer was reached · partial = some were, some were not · failed = none were (the contract may still have advanced — that is exactly what the caller must see) · skipped = there was nobody to deliver to · blocked = the pre-flight refused the send, so nothing changed at all.","example":"partial"},"signers":{"type":"array","description":"One entry per pending signer. Empty when status is `skipped`.","items":{"type":"object","properties":{"signer_id":{"type":"integer","description":"The signer this entry is about.","example":4711},"name":{"type":"string","description":"The signer's name","so the operator reads who instead of an id.":null,"example":"Maria Souza"},"role":{"type":"string","enum":["contractor","contracted","witness","guarantor"],"description":"The party's role in the contract.","example":"contractor"},"status":{"type":"string","enum":["delivered","failed","blocked"],"description":"Whether this specific party received the request.","example":"failed"},"reason":{"type":"string","enum":["no_destination","no_inbox","channel_unavailable","hsm_template_without_url_button","no_signing_link","delivery_error","ai_not_active_in_conversation","ai_email_destination","ai_conversation_to_create","ai_other_conversation","publication_pending"],"description":"A canonical token, never a sentence, so a dashboard and an agentic executor can both branch on it. Absent on ordinary success. publication_pending means a Message was durably recorded and the token/PDF remain valid, while queue publication or a callback needs confirmation; do not send a new sequence with another key. The `ai_*` tokens appear only when the caller is the AI agent and mean a person must send the contract.","example":"no_destination"},"message_ids":{"type":"array","items":{"type":"integer"},"description":"Durable Message ids of a bot delivery, reused on a retry with the same idempotency key."},"publication_errors":{"type":"array","items":{"type":"object","properties":{"error_class":{"type":"string","description":"Sanitized exception class only; no exception message or provider payload."}}},"description":"Publication failures recorded after a durable Message; present on bot sends."},"channel":{"type":"string","enum":["conversation","email"],"description":"Where the request went. Absent when the entry failed.","example":"email"}}}}}}}},"example":{"error":"sample error","code":"sample code","delivery":{"status":"partial","signers":[{"signer_id":4711,"name":"Maria Souza","role":"contractor","status":"failed","reason":"no_destination","message_ids":[1],"publication_errors":[{"error_class":"sample error class"}],"channel":"email"}]}}}}},"401":{"description":"A bot that is not the active bot of the named conversation's inbox, a bot that named no conversation, or a user credential asserting bot authorship."},"404":{"description":"No contract with this id exists in the account, or the named conversation does not exist."},"422":{"description":"The send was refused before anything changed — a signer with no destination, or the document could not be generated. `delivery.signers[]` names each blocking party.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"The contract was not sent: at least one signer has no way to receive it."},"code":{"type":"string","enum":["contract_ai_send_disabled","contract_send_requires_human","contract_send_not_delivered"],"description":"Present only when a bot caller was refused. contract_ai_send_disabled = the account does not allow the AI agent to send contracts · contract_send_requires_human = a pending signer is not reachable in the caller's own conversation · contract_send_not_delivered = the signing message could not be delivered there. In all three nothing changed and a person must send the contract.","example":"contract_send_requires_human"},"delivery":{"$ref":"#/components/schemas/contract_delivery_report"}}},"example":{"error":"The contract was not sent: at least one signer has no way to receive it.","code":"contract_send_requires_human","delivery":{"status":"partial","signers":[{"signer_id":4711,"name":"Maria Souza","role":"contractor","status":"failed","reason":"no_destination","channel":"email"}]}}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"X-Chatwoot-Message-Author","in":"header","required":false,"schema":{"type":"string","enum":["agent_bot"]},"description":"Optional assertion requiring authenticated AgentBot credentials. This header alone does not authenticate a caller."},{"name":"X-Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Stable key for retrying the signature-request sequence. Per-signer and per-message sub-keys prevent duplicate summary, document and native-button messages."}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"conversation_id":{"type":"integer","description":"Conversation the caller is acting in. The per-account display id is matched first and the internal record id is used as a fallback. Optional for a human caller (the conversation linked to the contract is used); required for a bot caller."}}},"example":{"conversation_id":128}}}}}},"/api/v1/accounts/{account_id}/contracts/{id}/sign_company":{"post":{"tags":["Contracts"],"operationId":"auto_post_api_v1_accounts_account_id_contracts_id_sign_company","summary":"Sign a sent contract for the issuing company","description":"Applies the issuing company's signature to a contract that is already out for signature and whose company side is still open (`company_signature_pending` is true) — the state left by a send the AI agent made without permission to sign for the company. It is the same server-side signature a human send applies, recorded in the forensic timeline with the user who decided it. When it is the last missing signature the contract is finalized. Human callers only: a bot credential is refused.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"title":{"type":"string"},"status":{"type":"string","enum":["draft","pending_signature","partially_signed","completed","rejected","expired","voided","canceled"]},"signature_tier":{"type":"string","enum":["simple","advanced","qualified"]},"region":{"type":"string"},"locale":{"type":"string"},"verification_code":{"type":"string"},"public_verification_url":{"type":"string"},"document_sha256":{"type":"string"},"sent_at":{"type":"string","format":"date-time"},"expires_at":{"type":"string","format":"date-time"},"completed_at":{"type":"string","format":"date-time"},"voided_at":{"type":"string","format":"date-time"},"archived":{"type":"boolean"},"legally_binding":{"type":"boolean"},"company_signature_pending":{"type":"boolean"},"created_by_id":{"type":"integer"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"template_id":{"type":"integer"},"company_id":{"type":"integer"},"company_name":{"type":["string","null"]},"contact_id":{"type":"integer"},"contact_name":{"type":"string"},"conversation_id":{"type":"integer"},"conversation_display_id":{"type":["integer","null"]},"crm_item_id":{"type":"integer"},"payments_charge_id":{"type":"integer"},"payments_subscription_id":{"type":"integer"},"calendar_booking_id":{"type":"integer"},"follow_up_enrollment_id":{"type":"integer"},"variables_snapshot":{"type":"object","additionalProperties":true,"description":"Merge variables captured at send-time, keyed by template variable name."},"metadata":{"type":"object","additionalProperties":true,"description":"Free-form metadata bag; the key set depends on the record and context."},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"signers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"role":{"type":"string","enum":["contractor","contracted","witness","guarantor"]},"name":{"type":"string"},"email":{"type":"string","format":"email"},"phone":{"type":"string"},"document":{"type":"string"},"status":{"type":"string","enum":["pending","viewed","signed","rejected"]},"auth_method":{"type":"string","enum":["none","email_otp","whatsapp_otp","icp_brasil"]},"auto_sign":{"type":"string"},"sign_order":{"type":"string"},"is_responsible":{"type":"boolean"},"signed_at":{"type":"string","format":"date-time"},"contact_id":{"type":"integer"},"company_id":{"type":"integer"},"has_signing_token":{"type":"boolean"}}}},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"kind":{"type":"string","enum":["product","service","fee","discount"],"description":"The kind of contract line item."},"name":{"type":"string"},"price":{"type":"number"},"quantity":{"type":"string"},"currency":{"type":"string"},"line_total":{"type":"number"},"catalog_product_id":{"type":"integer"},"clause":{"type":"string"}}}},"signers_count":{"type":"integer"},"signed_count":{"type":"integer"},"body_snapshot":{"type":"string"}}}}},"example":{"payload":{"id":1,"title":"Sample title","status":"draft","signature_tier":"simple","region":"sample region","locale":"en","verification_code":"sample verification code","public_verification_url":"https://example.com/resource","document_sha256":"sample document sha256","sent_at":"2026-01-15T10:30:00.000Z","expires_at":"2026-01-15T10:30:00.000Z","completed_at":"2026-01-15T10:30:00.000Z","voided_at":"2026-01-15T10:30:00.000Z","archived":true,"legally_binding":true,"company_signature_pending":true,"created_by_id":1,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","template_id":1,"company_id":1,"company_name":"sample company name","contact_id":1,"contact_name":"sample contact name","conversation_id":1,"conversation_display_id":1,"crm_item_id":1,"payments_charge_id":1,"payments_subscription_id":1,"calendar_booking_id":1,"follow_up_enrollment_id":1,"variables_snapshot":{},"metadata":{},"custom_attributes":{},"signers":[{"id":1,"role":"contractor","name":"Sample Name","email":"agent@example.com","phone":"+5511999998888","document":"sample document","status":"pending","auth_method":"none","auto_sign":"sample auto sign","sign_order":"sample sign order","is_responsible":true,"signed_at":"2026-01-15T10:30:00.000Z","contact_id":1,"company_id":1,"has_signing_token":true}],"items":[{"id":1,"kind":"product","name":"Sample Name","price":149.9,"quantity":"sample quantity","currency":"BRL","line_total":149.9,"catalog_product_id":1,"clause":"sample clause"}],"signers_count":5,"signed_count":5,"body_snapshot":"sample body snapshot"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"No contract with this id exists in the account."},"422":{"description":"The contract is not waiting for the company signature, or is no longer open for signature. Nothing changed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"This contract is not waiting for the company signature."}}},"example":{"error":"This contract is not waiting for the company signature."}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/contracts/{id}/remind":{"post":{"tags":["Contracts"],"operationId":"auto_post_api_v1_accounts_account_id_contracts_id_remind","summary":"Re-send the signing link to each pending signer","description":"Nudges every pending external signer by re-posting the signing card on THEIR own destination — not into a single shared conversation. No new document is rendered, no PDF is re-attached and no signature state changes. The response reports the outcome per signer: an empty 200 used to make \"nobody was reminded\" indistinguishable from success.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"At least one pending signer was reached.","content":{"application/json":{"schema":{"type":"object","properties":{"delivery":{"$ref":"#/components/schemas/contract_delivery_report"}}},"example":{"delivery":{"status":"partial","signers":[{"signer_id":4711,"name":"Maria Souza","role":"contractor","status":"failed","reason":"no_destination","channel":"email"}]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"No contract with this id exists in the account."},"422":{"description":"No pending signer could be reached. Nothing changed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"No pending party could be reached. Check each signer’s contact details."},"delivery":{"$ref":"#/components/schemas/contract_delivery_report"}}},"example":{"error":"No pending party could be reached. Check each signer’s contact details.","delivery":{"status":"partial","signers":[{"signer_id":4711,"name":"Maria Souza","role":"contractor","status":"failed","reason":"no_destination","channel":"email"}]}}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"X-Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Stable key for retrying this reminder sequence without duplicating signer messages."}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"conversation_id":{"type":"integer"}}},"example":{"conversation_id":1}}}}}},"/api/v1/accounts/{account_id}/contracts/{id}/void":{"post":{"tags":["Contracts"],"operationId":"auto_post_api_v1_accounts_account_id_contracts_id_void","summary":"Void contracts","description":"Performs the void operation on the targeted contract resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"title":{"type":"string"},"status":{"type":"string","enum":["draft","pending_signature","partially_signed","completed","rejected","expired","voided","canceled"]},"signature_tier":{"type":"string","enum":["simple","advanced","qualified"]},"region":{"type":"string"},"locale":{"type":"string"},"verification_code":{"type":"string"},"public_verification_url":{"type":"string"},"document_sha256":{"type":"string"},"sent_at":{"type":"string","format":"date-time"},"expires_at":{"type":"string","format":"date-time"},"completed_at":{"type":"string","format":"date-time"},"voided_at":{"type":"string","format":"date-time"},"archived":{"type":"boolean"},"legally_binding":{"type":"boolean"},"company_signature_pending":{"type":"boolean"},"created_by_id":{"type":"integer"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"template_id":{"type":"integer"},"company_id":{"type":"integer"},"company_name":{"type":["string","null"]},"contact_id":{"type":"integer"},"contact_name":{"type":"string"},"conversation_id":{"type":"integer"},"conversation_display_id":{"type":["integer","null"]},"crm_item_id":{"type":"integer"},"payments_charge_id":{"type":"integer"},"payments_subscription_id":{"type":"integer"},"calendar_booking_id":{"type":"integer"},"follow_up_enrollment_id":{"type":"integer"},"variables_snapshot":{"type":"object","additionalProperties":true,"description":"Merge variables captured at send-time, keyed by template variable name."},"metadata":{"type":"object","additionalProperties":true,"description":"Free-form metadata bag; the key set depends on the record and context."},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"signers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"role":{"type":"string","enum":["contractor","contracted","witness","guarantor"]},"name":{"type":"string"},"email":{"type":"string","format":"email"},"phone":{"type":"string"},"document":{"type":"string"},"status":{"type":"string","enum":["pending","viewed","signed","rejected"]},"auth_method":{"type":"string","enum":["none","email_otp","whatsapp_otp","icp_brasil"]},"auto_sign":{"type":"string"},"sign_order":{"type":"string"},"is_responsible":{"type":"boolean"},"signed_at":{"type":"string","format":"date-time"},"contact_id":{"type":"integer"},"company_id":{"type":"integer"},"has_signing_token":{"type":"boolean"}}}},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"kind":{"type":"string","enum":["product","service","fee","discount"],"description":"The kind of contract line item."},"name":{"type":"string"},"price":{"type":"number"},"quantity":{"type":"string"},"currency":{"type":"string"},"line_total":{"type":"number"},"catalog_product_id":{"type":"integer"},"clause":{"type":"string"}}}},"signers_count":{"type":"integer"},"signed_count":{"type":"integer"},"body_snapshot":{"type":"string"}}}}},"example":{"payload":{"id":1,"title":"Sample title","status":"draft","signature_tier":"simple","region":"sample region","locale":"en","verification_code":"sample verification code","public_verification_url":"https://example.com/resource","document_sha256":"sample document sha256","sent_at":"2026-01-15T10:30:00.000Z","expires_at":"2026-01-15T10:30:00.000Z","completed_at":"2026-01-15T10:30:00.000Z","voided_at":"2026-01-15T10:30:00.000Z","archived":true,"legally_binding":true,"company_signature_pending":true,"created_by_id":1,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","template_id":1,"company_id":1,"company_name":"sample company name","contact_id":1,"contact_name":"sample contact name","conversation_id":1,"conversation_display_id":1,"crm_item_id":1,"payments_charge_id":1,"payments_subscription_id":1,"calendar_booking_id":1,"follow_up_enrollment_id":1,"variables_snapshot":{},"metadata":{},"custom_attributes":{},"signers":[{"id":1,"role":"contractor","name":"Sample Name","email":"agent@example.com","phone":"+5511999998888","document":"sample document","status":"pending","auth_method":"none","auto_sign":"sample auto sign","sign_order":"sample sign order","is_responsible":true,"signed_at":"2026-01-15T10:30:00.000Z","contact_id":1,"company_id":1,"has_signing_token":true}],"items":[{"id":1,"kind":"product","name":"Sample Name","price":149.9,"quantity":"sample quantity","currency":"BRL","line_total":149.9,"catalog_product_id":1,"clause":"sample clause"}],"signers_count":5,"signed_count":5,"body_snapshot":"sample body snapshot"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/contracts/{id}/events":{"get":{"tags":["Contracts"],"operationId":"auto_get_api_v1_accounts_account_id_contracts_id_events","summary":"Events contracts","description":"Performs the events operation on the targeted contract resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"event_type":{"type":"string","enum":["created","sent","viewed","otp_sent","otp_verified","signed","rejected","expired","downloaded","voided"]},"signature_kind":{"type":"string","enum":["simple","drawn","uploaded","typed","icp_a1"]},"auth_method":{"type":"string","enum":["none","email_otp","whatsapp_otp","icp_brasil"]},"signer_id":{"type":"integer"},"ip":{"type":"string"},"user_agent":{"type":"string"},"geo":{"type":"string"},"document_sha256":{"type":"string"},"occurred_at":{"type":"string","format":"date-time"},"actor_type":{"type":["string","null"],"enum":["AgentBot","User",null]},"actor_id":{"type":["integer","null"]},"company_signature":{"type":["string","null"],"enum":["pending_human","auto_by_account_setting",null]}}}},"meta":{"type":"object","properties":{"count":{"type":"integer"},"current_page":{"type":"string"},"total_pages":{"type":"string"},"has_more":{"type":"boolean"}}}}},"example":{"payload":[{"id":1,"event_type":"created","signature_kind":"simple","auth_method":"none","signer_id":1,"ip":"203.0.113.10","user_agent":"Mozilla/5.0","geo":"sample geo","document_sha256":"sample document sha256","occurred_at":"2026-01-15T10:30:00.000Z","actor_type":"AgentBot","actor_id":1,"company_signature":"pending_human"}],"meta":{"count":5,"current_page":"sample current page","total_pages":"sample total pages","has_more":true}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page of signature events.","schema":{"type":"integer","default":1},"example":1}]}},"/api/v1/accounts/{account_id}/contracts/{id}/download":{"get":{"tags":["Contracts"],"operationId":"auto_get_api_v1_accounts_account_id_contracts_id_download","summary":"Download contracts","description":"Performs the download operation on the targeted contract resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string"},"filename":{"type":"string"},"sha256":{"type":"string"}}},"example":{"url":"https://example.com/resource","filename":"sample filename","sha256":"sample sha256"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/contracts/{id}/preview":{"get":{"tags":["Contracts"],"operationId":"auto_get_api_v1_accounts_account_id_contracts_id_preview","summary":"Preview a saved contract draft without sending or signing it","description":"Reads the account's saved draft using the native variable merge and document layout. JSON returns the complete merged body and missing-variable warnings. Request the PDF format for an inline draft document. Neither format persists rendered content, creates a document or blob, signs a party, or sends a message. A completed or sent contract is rejected: use its existing document download instead of regenerating evidence. Requires authenticated contract management access and the contracts feature. Responses are private and must not be cached.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Full transient draft text or native draft PDF.","headers":{"Cache-Control":{"description":"Private transient document data must not be cached.","schema":{"type":"string","example":"private, no-store"}}},"content":{"application/json":{"schema":{"type":"object","required":["payload"],"properties":{"payload":{"type":"object","required":["contract_id","kind","body","empty_body","missing_variables","updated_at"],"properties":{"contract_id":{"type":"integer","description":"Saved draft identifier.","example":27},"kind":{"type":"string","enum":["draft"],"description":"Informational unsent draft.","example":"draft"},"body":{"type":"string","description":"Entire native merged document body as inert text.","example":"The service is provided to Fixture Client."},"empty_body":{"type":"boolean","description":"Whether the merged body is blank.","example":false},"missing_variables":{"type":"array","description":"Distinct absent or blank merge keys in first-occurrence order; zero and false are present values.","items":{"type":"string"},"example":["contact.document"]},"updated_at":{"type":"string","format":"date-time","description":"Saved draft version time; preview does not update it.","example":"2026-10-08T12:00:00.000000Z"}}}}},"example":{"payload":{"contract_id":27,"kind":"draft","body":"The service is provided to Fixture Client.","empty_body":false,"missing_variables":["contact.document"],"updated_at":"2026-10-08T12:00:00.000000Z"}}},"application/pdf":{"schema":{"type":"string","format":"binary","description":"Inline PDF produced by the native draft layout."},"example":"%PDF-1.7 (binary draft document)"}}},"401":{"description":"Authentication or account membership is missing, expired or invalid, or the native policy rejects the caller.","content":{"application/json":{"schema":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"string"}},"error":{"type":"string","description":"Native authorization rejection when an authenticated account member lacks access."}}},"example":{"errors":["You need to sign in or sign up before continuing."],"error":"sample error"}}}},"404":{"description":"The contract does not exist in the caller's account.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}},"example":{"error":"Resource could not be found"}}}},"403":{"description":"Contract management is forbidden or the contracts feature is disabled.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}},"example":{"error":"feature_not_enabled"}}}},"422":{"description":"The saved contract is not a draft or native preview rendering is unavailable; no state is changed.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Safe localized explanation."}}},"example":{"error":"The complete contract preview could not be generated. Try again before sending."}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/contracts/{id}/signing_links":{"get":{"tags":["Contracts"],"operationId":"auto_get_api_v1_accounts_account_id_contracts_id_signing_links","summary":"Signing links contracts","description":"Performs the signing links operation on the targeted contract resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"string"}}},"example":{"payload":"sample payload"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/contracts/{id}/create_task":{"post":{"tags":["Contracts"],"operationId":"auto_post_api_v1_accounts_account_id_contracts_id_create_task","summary":"Create task contracts","description":"Performs the create task operation on the targeted contract resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"title":{"type":"string"}}}}},"example":{"payload":{"id":1,"title":"Sample title"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","description":"All optional — title/assignees default from the contract + current user; links are derived server-side.","properties":{"title":{"type":"string","example":"Revisar contrato antes do envio"},"description":{"type":["string","null"],"example":"Conferir cláusulas de pagamento."},"due_at":{"type":["string","null"],"format":"date-time","example":"2026-01-20T18:00:00.000Z"},"assignee_ids":{"type":"array","items":{"type":"integer"},"example":[7]}}},"example":{"title":"Revisar contrato antes do envio","description":"Conferir cláusulas de pagamento.","due_at":"2026-01-20T18:00:00.000Z","assignee_ids":[7]}}}}}},"/api/v1/accounts/{account_id}/contracts/{id}/enroll_follow_up":{"post":{"tags":["Contracts"],"operationId":"auto_post_api_v1_accounts_account_id_contracts_id_enroll_follow_up","summary":"Enroll follow up contracts","description":"Performs the enroll follow up operation on the targeted contract resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"sequence_id":{"type":"integer"}}}}},"example":{"payload":{"id":1,"sequence_id":1}}}}},"401":{"description":"Contract authorization denied, visibility of the source or effective enrollment conversation denied, or one of the inherited authentication and account checks of every account endpoint (invalid access token, suspended account, account not accessible to the caller). Nothing is enrolled and the contract is not linked.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Reason, by origin. \"You are not authorized to do this action\" for the contract policy and for a denied source or effective conversation; \"Invalid Access Token\" for an unknown api_access_token; \"Account is suspended\" for an inactive account; \"You are not authorized to access this account\" when the caller has no membership in it (translated to the account locale). Not a closed set: the inherited layers own these texts.","example":"You are not authorized to do this action"}},"required":["error"]},"examples":{"policy_or_conversation_denied":{"summary":"Contract policy, or a source or delivery conversation the caller cannot see","value":{"error":"You are not authorized to do this action"}},"invalid_access_token":{"summary":"api_access_token header that matches no token","value":{"error":"Invalid Access Token"}},"account_suspended":{"summary":"Account no longer active","value":{"error":"Account is suspended"}},"account_not_accessible":{"summary":"Caller has no membership in the account","value":{"error":"You are not authorized to access this account"}}}}}},"404":{"description":"Account or resource not found"},"422":{"description":"Follow-ups are disabled, the contract has no contact, the enrollment did not materialize (no published sequence version, or the effective conversation unavailable or changed before enrollment), a different sequence is already linked to this contract, or linking the contract to the enrollment failed validation. Enrollment and its contract link are atomic: a failed link rolls back the new enrollment and its creation events. A contract has one linked sequence; repeating that sequence reuses its pinned enrollment, even when it has ended. A conflicting sequence is rejected without creating an enrollment, emitting creation events or changing the link.","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"error":{"type":"string","description":"Human-readable enrollment failure in the request locale — the Follow-ups module disabled, the contract without a linked contact, or the single generic enroll failure returned for every builder reason (no published sequence version, conversation unavailable, missing contact). A different sequence conflicts with the contract's existing link; that error names the linked sequence and asks the caller to select it for reuse or manage its enrollment in Follow-up. Not a closed set: the shared request exception handler renders its own translated 422 texts.","example":"Could not enroll: the sequence has no published version."}},"required":["error"]},{"type":"object","description":"The global ActiveRecord::RecordInvalid shape when creating the enrollment or linking it to the contract fails validation. The new enrollment and its audit rows are rolled back with the failed contract link; no creation event is published.","required":["message","attributes"],"properties":{"message":{"type":"string","description":"Every validation message joined by ', '.","example":"Title can't be blank"},"attributes":{"type":"array","description":"The attribute names that carried a validation error, with base for the whole record.","items":{"type":"string"},"example":["title"]}}}]},"examples":{"follow_ups_disabled":{"summary":"Follow-ups module off for the account","value":{"error":"The Follow-ups module is not enabled for this account."}},"no_contact":{"summary":"Contract without a linked contact","value":{"error":"This contract has no linked contact to enroll."}},"enroll_failed":{"summary":"Builder returned no enrollment (any reason)","value":{"error":"Could not enroll: the sequence has no published version."}},"sequence_conflict":{"summary":"A different sequence is already linked to this contract","value":{"error":"This contract is already linked to sequence Signature reminders. Select that sequence to reuse the enrollment or manage it in Follow-up."}},"record_validation":{"summary":"Enrollment creation or contract-link update failed validation","value":{"message":"Title can't be blank","attributes":["title"]}}}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"sequence_id":{"type":"integer"}}},"example":{"sequence_id":1}}}}}},"/api/v1/accounts/{account_id}/contracts/{contract_id}/signers":{"post":{"tags":["Contracts"],"operationId":"auto_post_api_v1_accounts_account_id_contracts_contract_id_signers","summary":"Create signers","description":"Creates a new signer from the request payload. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The updated contract with its refreshed signer roster.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer","example":12},"title":{"type":"string","example":"Contrato de Prestação de Serviços"},"status":{"type":"string","enum":["draft","pending_signature","partially_signed","completed","rejected","expired","voided","canceled"],"example":"draft"},"signature_tier":{"type":"string","enum":["simple","advanced","qualified"],"example":"simple"},"region":{"type":"string","example":"BR"},"locale":{"type":"string","example":"pt_BR"},"verification_code":{"type":"string","example":"CW-7F3A9B2C"},"public_verification_url":{"type":["string","null"],"example":"https://app.example.com/contracts/verify/CW-7F3A9B2C"},"document_sha256":{"type":["string","null"],"example":"e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"},"sent_at":{"type":["string","null"],"format":"date-time","example":"2026-01-15T10:30:00.000Z"},"expires_at":{"type":["string","null"],"format":"date-time","example":"2026-02-15T10:30:00.000Z"},"completed_at":{"type":["string","null"],"format":"date-time","example":null},"voided_at":{"type":["string","null"],"format":"date-time","example":null},"archived":{"type":"boolean","example":false},"legally_binding":{"type":"boolean","example":false},"company_signature_pending":{"type":"boolean","description":"True while the contract is out for signature and the issuing company has not signed yet.","example":false},"created_by_id":{"type":["integer","null"],"example":7},"created_at":{"type":"string","format":"date-time","example":"2026-01-15T10:00:00.000Z"},"updated_at":{"type":"string","format":"date-time","example":"2026-01-15T10:30:00.000Z"},"template_id":{"type":["integer","null"],"example":3},"company_id":{"type":["integer","null"],"example":4},"company_name":{"type":["string","null"],"example":"ACME Serviços LTDA"},"contact_id":{"type":["integer","null"],"example":55},"contact_name":{"type":["string","null"],"example":"João da Silva"},"conversation_id":{"type":["integer","null"],"example":900},"conversation_display_id":{"type":["integer","null"],"example":42},"crm_item_id":{"type":["integer","null"],"example":null},"payments_charge_id":{"type":["integer","null"],"example":null},"payments_subscription_id":{"type":["integer","null"],"example":null},"calendar_booking_id":{"type":["integer","null"],"example":null},"follow_up_enrollment_id":{"type":["integer","null"],"example":null},"variables_snapshot":{"type":"object","additionalProperties":true,"description":"Merge variables captured at send-time."},"metadata":{"type":"object","additionalProperties":true,"description":"Free-form metadata bag; the key set depends on the record and context."},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"signers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","example":21},"role":{"type":"string","enum":["contractor","contracted","witness","guarantor"],"example":"contractor"},"name":{"type":"string","example":"João da Silva"},"email":{"type":["string","null"],"example":"joao@example.com"},"phone":{"type":["string","null"],"example":"+5521999998888"},"document":{"type":["string","null"],"example":"123.456.789-00"},"status":{"type":"string","enum":["pending","viewed","signed","rejected"],"example":"pending"},"auth_method":{"type":"string","enum":["none","email_otp","whatsapp_otp","icp_brasil"],"example":"none"},"auto_sign":{"type":"boolean","example":false},"sign_order":{"type":"integer","example":0},"is_responsible":{"type":"boolean","example":true},"signed_at":{"type":["string","null"],"format":"date-time","example":null},"contact_id":{"type":["integer","null"],"example":55},"company_id":{"type":["integer","null"],"example":null},"has_signing_token":{"type":"boolean","description":"Whether a per-signer link token exists (the token itself is never exposed).","example":false}}}},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","example":31},"kind":{"type":"string","example":"product","enum":["product","service","fee","discount"],"description":"The kind of contract line item."},"name":{"type":"string","example":"Plano Pro (anual)"},"price":{"type":"number","description":"MAJOR units.","example":1200.0},"quantity":{"type":"number","example":1},"currency":{"type":"string","example":"BRL"},"line_total":{"type":"number","example":1200.0},"catalog_product_id":{"type":["integer","null"],"example":88},"clause":{"type":["string","null"],"example":null}}}},"body_snapshot":{"type":["string","null"],"description":"Frozen rendered body (detail view only).","example":"# Contrato..."},"signers_count":{"type":"integer","example":1},"signed_count":{"type":"integer","example":0}}}}},"example":{"payload":{"id":12,"title":"Contrato de Prestação de Serviços","status":"draft","signature_tier":"simple","region":"BR","locale":"pt_BR","verification_code":"CW-7F3A9B2C","public_verification_url":"https://app.example.com/contracts/verify/CW-7F3A9B2C","document_sha256":"e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855","sent_at":"2026-01-15T10:30:00.000Z","expires_at":"2026-02-15T10:30:00.000Z","completed_at":null,"voided_at":null,"archived":false,"legally_binding":false,"company_signature_pending":false,"created_by_id":7,"created_at":"2026-01-15T10:00:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","template_id":3,"company_id":4,"company_name":"ACME Serviços LTDA","contact_id":55,"contact_name":"João da Silva","conversation_id":900,"conversation_display_id":42,"crm_item_id":null,"payments_charge_id":null,"payments_subscription_id":null,"calendar_booking_id":null,"follow_up_enrollment_id":null,"variables_snapshot":{},"metadata":{},"custom_attributes":{},"signers":[{"id":21,"role":"contractor","name":"João da Silva","email":"joao@example.com","phone":"+5521999998888","document":"123.456.789-00","status":"pending","auth_method":"none","auto_sign":false,"sign_order":0,"is_responsible":true,"signed_at":null,"contact_id":55,"company_id":null,"has_signing_token":false}],"items":[{"id":31,"kind":"product","name":"Plano Pro (anual)","price":1200.0,"quantity":1,"currency":"BRL","line_total":1200.0,"catalog_product_id":88,"clause":null}],"body_snapshot":"# Contrato...","signers_count":1,"signed_count":0}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"contract_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"signer":{"type":"object","properties":{"role":{"type":"string","enum":["contractor","contracted","witness","guarantor"]},"name":{"type":"string"},"email":{"type":"string","format":"email"},"phone":{"type":"string"},"document":{"type":"string"},"auth_method":{"type":"string","enum":["none","email_otp","whatsapp_otp","icp_brasil"]},"sign_order":{"type":"string"},"is_responsible":{"type":"boolean"},"contact_id":{"type":"integer"}}}},"required":["signer"]},"example":{"signer":{"role":"contractor","name":"Sample Name","email":"agent@example.com","phone":"+5511999998888","document":"sample document","auth_method":"none","sign_order":"sample sign order","is_responsible":true,"contact_id":1}}}}}}},"/api/v1/accounts/{account_id}/contracts/{contract_id}/signers/{id}":{"patch":{"tags":["Contracts"],"operationId":"auto_patch_api_v1_accounts_account_id_contracts_contract_id_signers_id","summary":"Update signers","description":"Updates the signer identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The updated contract with its refreshed signer roster.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer","example":12},"title":{"type":"string","example":"Contrato de Prestação de Serviços"},"status":{"type":"string","enum":["draft","pending_signature","partially_signed","completed","rejected","expired","voided","canceled"],"example":"draft"},"signature_tier":{"type":"string","enum":["simple","advanced","qualified"],"example":"simple"},"region":{"type":"string","example":"BR"},"locale":{"type":"string","example":"pt_BR"},"verification_code":{"type":"string","example":"CW-7F3A9B2C"},"public_verification_url":{"type":["string","null"],"example":"https://app.example.com/contracts/verify/CW-7F3A9B2C"},"document_sha256":{"type":["string","null"],"example":"e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"},"sent_at":{"type":["string","null"],"format":"date-time","example":null},"expires_at":{"type":["string","null"],"format":"date-time","example":null},"completed_at":{"type":["string","null"],"format":"date-time","example":null},"voided_at":{"type":["string","null"],"format":"date-time","example":null},"archived":{"type":"boolean","example":false},"legally_binding":{"type":"boolean","example":false},"company_signature_pending":{"type":"boolean","description":"True while the contract is out for signature and the issuing company has not signed yet.","example":false},"created_by_id":{"type":["integer","null"],"example":7},"created_at":{"type":"string","format":"date-time","example":"2026-01-15T10:00:00.000Z"},"updated_at":{"type":"string","format":"date-time","example":"2026-01-15T10:35:00.000Z"},"template_id":{"type":["integer","null"],"example":3},"company_id":{"type":["integer","null"],"example":4},"company_name":{"type":["string","null"],"example":"ACME Serviços LTDA"},"contact_id":{"type":["integer","null"],"example":55},"contact_name":{"type":["string","null"],"example":"João da Silva"},"conversation_id":{"type":["integer","null"],"example":900},"conversation_display_id":{"type":["integer","null"],"example":42},"crm_item_id":{"type":["integer","null"],"example":null},"payments_charge_id":{"type":["integer","null"],"example":null},"payments_subscription_id":{"type":["integer","null"],"example":null},"calendar_booking_id":{"type":["integer","null"],"example":null},"follow_up_enrollment_id":{"type":["integer","null"],"example":null},"variables_snapshot":{"type":"object","additionalProperties":true,"description":"Merge variables captured at send-time, keyed by template variable name."},"metadata":{"type":"object","additionalProperties":true,"description":"Free-form metadata bag; the key set depends on the record and context."},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"signers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","example":21},"role":{"type":"string","enum":["contractor","contracted","witness","guarantor"],"example":"contractor"},"name":{"type":"string","example":"João da Silva"},"email":{"type":["string","null"],"example":"joao@example.com"},"phone":{"type":["string","null"],"example":"+5521999998888"},"document":{"type":["string","null"],"example":"123.456.789-00"},"status":{"type":"string","enum":["pending","viewed","signed","rejected"],"example":"pending"},"auth_method":{"type":"string","enum":["none","email_otp","whatsapp_otp","icp_brasil"],"example":"email_otp"},"auto_sign":{"type":"boolean","example":false},"sign_order":{"type":"integer","example":0},"is_responsible":{"type":"boolean","example":true},"signed_at":{"type":["string","null"],"format":"date-time","example":null},"contact_id":{"type":["integer","null"],"example":55},"company_id":{"type":["integer","null"],"example":null},"has_signing_token":{"type":"boolean","example":false}}}},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","example":31},"kind":{"type":"string","example":"product","enum":["product","service","fee","discount"],"description":"The kind of contract line item."},"name":{"type":"string","example":"Plano Pro (anual)"},"price":{"type":"number","example":1200.0},"quantity":{"type":"number","example":1},"currency":{"type":"string","example":"BRL"},"line_total":{"type":"number","example":1200.0},"catalog_product_id":{"type":["integer","null"],"example":88},"clause":{"type":["string","null"],"example":null}}}},"body_snapshot":{"type":["string","null"],"example":null},"signers_count":{"type":"integer","example":2},"signed_count":{"type":"integer","example":0}}}}},"example":{"payload":{"id":12,"title":"Contrato de Prestação de Serviços","status":"draft","signature_tier":"simple","region":"BR","locale":"pt_BR","verification_code":"CW-7F3A9B2C","public_verification_url":"https://app.example.com/contracts/verify/CW-7F3A9B2C","document_sha256":"e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855","sent_at":null,"expires_at":null,"completed_at":null,"voided_at":null,"archived":false,"legally_binding":false,"company_signature_pending":false,"created_by_id":7,"created_at":"2026-01-15T10:00:00.000Z","updated_at":"2026-01-15T10:35:00.000Z","template_id":3,"company_id":4,"company_name":"ACME Serviços LTDA","contact_id":55,"contact_name":"João da Silva","conversation_id":900,"conversation_display_id":42,"crm_item_id":null,"payments_charge_id":null,"payments_subscription_id":null,"calendar_booking_id":null,"follow_up_enrollment_id":null,"variables_snapshot":{},"metadata":{},"custom_attributes":{},"signers":[{"id":21,"role":"contractor","name":"João da Silva","email":"joao@example.com","phone":"+5521999998888","document":"123.456.789-00","status":"pending","auth_method":"email_otp","auto_sign":false,"sign_order":0,"is_responsible":true,"signed_at":null,"contact_id":55,"company_id":null,"has_signing_token":false}],"items":[{"id":31,"kind":"product","name":"Plano Pro (anual)","price":1200.0,"quantity":1,"currency":"BRL","line_total":1200.0,"catalog_product_id":88,"clause":null}],"body_snapshot":null,"signers_count":2,"signed_count":0}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"contract_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"signer":{"type":"object","properties":{"role":{"type":"string","enum":["contractor","contracted","witness","guarantor"]},"name":{"type":"string"},"email":{"type":"string","format":"email"},"phone":{"type":"string"},"document":{"type":"string"},"auth_method":{"type":"string","enum":["none","email_otp","whatsapp_otp","icp_brasil"]},"sign_order":{"type":"string"},"is_responsible":{"type":"boolean"},"contact_id":{"type":"integer"}}}},"required":["signer"]},"example":{"signer":{"role":"contractor","name":"Sample Name","email":"agent@example.com","phone":"+5511999998888","document":"sample document","auth_method":"none","sign_order":"sample sign order","is_responsible":true,"contact_id":1}}}}}},"put":{"tags":["Contracts"],"operationId":"auto_put_api_v1_accounts_account_id_contracts_contract_id_signers_id","summary":"Update signers","description":"Updates the signer identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The updated contract with its refreshed signer roster.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer","example":12},"title":{"type":"string","example":"Contrato de Prestação de Serviços"},"status":{"type":"string","enum":["draft","pending_signature","partially_signed","completed","rejected","expired","voided","canceled"],"example":"draft"},"signature_tier":{"type":"string","enum":["simple","advanced","qualified"],"example":"simple"},"region":{"type":"string","example":"BR"},"locale":{"type":"string","example":"pt_BR"},"verification_code":{"type":"string","example":"CW-7F3A9B2C"},"public_verification_url":{"type":["string","null"],"example":"https://app.example.com/contracts/verify/CW-7F3A9B2C"},"document_sha256":{"type":["string","null"],"example":"e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"},"sent_at":{"type":["string","null"],"format":"date-time","example":null},"expires_at":{"type":["string","null"],"format":"date-time","example":null},"completed_at":{"type":["string","null"],"format":"date-time","example":null},"voided_at":{"type":["string","null"],"format":"date-time","example":null},"archived":{"type":"boolean","example":false},"legally_binding":{"type":"boolean","example":false},"company_signature_pending":{"type":"boolean","description":"True while the contract is out for signature and the issuing company has not signed yet.","example":false},"created_by_id":{"type":["integer","null"],"example":7},"created_at":{"type":"string","format":"date-time","example":"2026-01-15T10:00:00.000Z"},"updated_at":{"type":"string","format":"date-time","example":"2026-01-15T10:35:00.000Z"},"template_id":{"type":["integer","null"],"example":3},"company_id":{"type":["integer","null"],"example":4},"company_name":{"type":["string","null"],"example":"ACME Serviços LTDA"},"contact_id":{"type":["integer","null"],"example":55},"contact_name":{"type":["string","null"],"example":"João da Silva"},"conversation_id":{"type":["integer","null"],"example":900},"conversation_display_id":{"type":["integer","null"],"example":42},"crm_item_id":{"type":["integer","null"],"example":null},"payments_charge_id":{"type":["integer","null"],"example":null},"payments_subscription_id":{"type":["integer","null"],"example":null},"calendar_booking_id":{"type":["integer","null"],"example":null},"follow_up_enrollment_id":{"type":["integer","null"],"example":null},"variables_snapshot":{"type":"object","additionalProperties":true,"description":"Merge variables captured at send-time, keyed by template variable name."},"metadata":{"type":"object","additionalProperties":true,"description":"Free-form metadata bag; the key set depends on the record and context."},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"signers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","example":21},"role":{"type":"string","enum":["contractor","contracted","witness","guarantor"],"example":"contractor"},"name":{"type":"string","example":"João da Silva"},"email":{"type":["string","null"],"example":"joao@example.com"},"phone":{"type":["string","null"],"example":"+5521999998888"},"document":{"type":["string","null"],"example":"123.456.789-00"},"status":{"type":"string","enum":["pending","viewed","signed","rejected"],"example":"pending"},"auth_method":{"type":"string","enum":["none","email_otp","whatsapp_otp","icp_brasil"],"example":"email_otp"},"auto_sign":{"type":"boolean","example":false},"sign_order":{"type":"integer","example":0},"is_responsible":{"type":"boolean","example":true},"signed_at":{"type":["string","null"],"format":"date-time","example":null},"contact_id":{"type":["integer","null"],"example":55},"company_id":{"type":["integer","null"],"example":null},"has_signing_token":{"type":"boolean","example":false}}}},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","example":31},"kind":{"type":"string","example":"product","enum":["product","service","fee","discount"],"description":"The kind of contract line item."},"name":{"type":"string","example":"Plano Pro (anual)"},"price":{"type":"number","example":1200.0},"quantity":{"type":"number","example":1},"currency":{"type":"string","example":"BRL"},"line_total":{"type":"number","example":1200.0},"catalog_product_id":{"type":["integer","null"],"example":88},"clause":{"type":["string","null"],"example":null}}}},"body_snapshot":{"type":["string","null"],"example":null},"signers_count":{"type":"integer","example":2},"signed_count":{"type":"integer","example":0}}}}},"example":{"payload":{"id":12,"title":"Contrato de Prestação de Serviços","status":"draft","signature_tier":"simple","region":"BR","locale":"pt_BR","verification_code":"CW-7F3A9B2C","public_verification_url":"https://app.example.com/contracts/verify/CW-7F3A9B2C","document_sha256":"e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855","sent_at":null,"expires_at":null,"completed_at":null,"voided_at":null,"archived":false,"legally_binding":false,"company_signature_pending":false,"created_by_id":7,"created_at":"2026-01-15T10:00:00.000Z","updated_at":"2026-01-15T10:35:00.000Z","template_id":3,"company_id":4,"company_name":"ACME Serviços LTDA","contact_id":55,"contact_name":"João da Silva","conversation_id":900,"conversation_display_id":42,"crm_item_id":null,"payments_charge_id":null,"payments_subscription_id":null,"calendar_booking_id":null,"follow_up_enrollment_id":null,"variables_snapshot":{},"metadata":{},"custom_attributes":{},"signers":[{"id":21,"role":"contractor","name":"João da Silva","email":"joao@example.com","phone":"+5521999998888","document":"123.456.789-00","status":"pending","auth_method":"email_otp","auto_sign":false,"sign_order":0,"is_responsible":true,"signed_at":null,"contact_id":55,"company_id":null,"has_signing_token":false}],"items":[{"id":31,"kind":"product","name":"Plano Pro (anual)","price":1200.0,"quantity":1,"currency":"BRL","line_total":1200.0,"catalog_product_id":88,"clause":null}],"body_snapshot":null,"signers_count":2,"signed_count":0}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"contract_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"signer":{"type":"object","properties":{"role":{"type":"string","enum":["contractor","contracted","witness","guarantor"]},"name":{"type":"string"},"email":{"type":"string","format":"email"},"phone":{"type":"string"},"document":{"type":"string"},"auth_method":{"type":"string","enum":["none","email_otp","whatsapp_otp","icp_brasil"]},"sign_order":{"type":"string"},"is_responsible":{"type":"boolean"},"contact_id":{"type":"integer"}}}},"required":["signer"]},"example":{"signer":{"role":"contractor","name":"Sample Name","email":"agent@example.com","phone":"+5511999998888","document":"sample document","auth_method":"none","sign_order":"sample sign order","is_responsible":true,"contact_id":1}}}}}},"delete":{"tags":["Contracts"],"operationId":"auto_delete_api_v1_accounts_account_id_contracts_contract_id_signers_id","summary":"Delete signers","description":"Deletes the signer identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The updated contract with its refreshed signer roster.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer","example":12},"title":{"type":"string","example":"Contrato de Prestação de Serviços"},"status":{"type":"string","enum":["draft","pending_signature","partially_signed","completed","rejected","expired","voided","canceled"],"example":"draft"},"signature_tier":{"type":"string","enum":["simple","advanced","qualified"],"example":"simple"},"region":{"type":"string","example":"BR"},"locale":{"type":"string","example":"pt_BR"},"verification_code":{"type":"string","example":"CW-7F3A9B2C"},"public_verification_url":{"type":["string","null"],"example":"https://app.example.com/contracts/verify/CW-7F3A9B2C"},"document_sha256":{"type":["string","null"],"example":null},"sent_at":{"type":["string","null"],"format":"date-time","example":null},"expires_at":{"type":["string","null"],"format":"date-time","example":null},"completed_at":{"type":["string","null"],"format":"date-time","example":null},"voided_at":{"type":["string","null"],"format":"date-time","example":null},"archived":{"type":"boolean","example":false},"legally_binding":{"type":"boolean","example":false},"company_signature_pending":{"type":"boolean","description":"True while the contract is out for signature and the issuing company has not signed yet.","example":false},"created_by_id":{"type":["integer","null"],"example":7},"created_at":{"type":"string","format":"date-time","example":"2026-01-15T10:00:00.000Z"},"updated_at":{"type":"string","format":"date-time","example":"2026-01-15T10:40:00.000Z"},"template_id":{"type":["integer","null"],"example":3},"company_id":{"type":["integer","null"],"example":4},"company_name":{"type":["string","null"],"example":"ACME Serviços LTDA"},"contact_id":{"type":["integer","null"],"example":55},"contact_name":{"type":["string","null"],"example":"João da Silva"},"conversation_id":{"type":["integer","null"],"example":900},"conversation_display_id":{"type":["integer","null"],"example":42},"crm_item_id":{"type":["integer","null"],"example":null},"payments_charge_id":{"type":["integer","null"],"example":null},"payments_subscription_id":{"type":["integer","null"],"example":null},"calendar_booking_id":{"type":["integer","null"],"example":null},"follow_up_enrollment_id":{"type":["integer","null"],"example":null},"variables_snapshot":{"type":"object","additionalProperties":true,"description":"Merge variables captured at send-time, keyed by template variable name."},"metadata":{"type":"object","additionalProperties":true,"description":"Free-form metadata bag; the key set depends on the record and context."},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"signers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","example":21},"role":{"type":"string","enum":["contractor","contracted","witness","guarantor"],"example":"contractor"},"name":{"type":"string","example":"João da Silva"},"email":{"type":["string","null"],"example":"joao@example.com"},"phone":{"type":["string","null"],"example":"+5521999998888"},"document":{"type":["string","null"],"example":null},"status":{"type":"string","enum":["pending","viewed","signed","rejected"],"example":"pending"},"auth_method":{"type":"string","enum":["none","email_otp","whatsapp_otp","icp_brasil"],"example":"none"},"auto_sign":{"type":"boolean","example":false},"sign_order":{"type":"integer","example":0},"is_responsible":{"type":"boolean","example":true},"signed_at":{"type":["string","null"],"format":"date-time","example":null},"contact_id":{"type":["integer","null"],"example":55},"company_id":{"type":["integer","null"],"example":null},"has_signing_token":{"type":"boolean","example":false}}}},"items":{"type":"array","items":{"type":"object","additionalProperties":true}},"body_snapshot":{"type":["string","null"],"example":null},"signers_count":{"type":"integer","example":1},"signed_count":{"type":"integer","example":0}}}}},"example":{"payload":{"id":12,"title":"Contrato de Prestação de Serviços","status":"draft","signature_tier":"simple","region":"BR","locale":"pt_BR","verification_code":"CW-7F3A9B2C","public_verification_url":"https://app.example.com/contracts/verify/CW-7F3A9B2C","document_sha256":null,"sent_at":null,"expires_at":null,"completed_at":null,"voided_at":null,"archived":false,"legally_binding":false,"company_signature_pending":false,"created_by_id":7,"created_at":"2026-01-15T10:00:00.000Z","updated_at":"2026-01-15T10:40:00.000Z","template_id":3,"company_id":4,"company_name":"ACME Serviços LTDA","contact_id":55,"contact_name":"João da Silva","conversation_id":900,"conversation_display_id":42,"crm_item_id":null,"payments_charge_id":null,"payments_subscription_id":null,"calendar_booking_id":null,"follow_up_enrollment_id":null,"variables_snapshot":{},"metadata":{},"custom_attributes":{},"signers":[{"id":21,"role":"contractor","name":"João da Silva","email":"joao@example.com","phone":"+5521999998888","document":null,"status":"pending","auth_method":"none","auto_sign":false,"sign_order":0,"is_responsible":true,"signed_at":null,"contact_id":55,"company_id":null,"has_signing_token":false}],"items":[{}],"body_snapshot":null,"signers_count":1,"signed_count":0}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"contract_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/contracts":{"get":{"tags":["Contracts"],"operationId":"auto_get_api_v1_accounts_account_id_contracts","summary":"List contracts","description":"Returns the list of contracts visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"title":{"type":"string"},"status":{"type":"string","enum":["draft","pending_signature","partially_signed","completed","rejected","expired","voided","canceled"]},"signature_tier":{"type":"string","enum":["simple","advanced","qualified"]},"region":{"type":"string"},"locale":{"type":"string"},"verification_code":{"type":"string"},"public_verification_url":{"type":"string"},"document_sha256":{"type":"string"},"sent_at":{"type":"string","format":"date-time"},"expires_at":{"type":"string","format":"date-time"},"completed_at":{"type":"string","format":"date-time"},"voided_at":{"type":"string","format":"date-time"},"archived":{"type":"boolean"},"legally_binding":{"type":"boolean"},"company_signature_pending":{"type":"boolean"},"created_by_id":{"type":"integer"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"template_id":{"type":"integer"},"company_id":{"type":"integer"},"company_name":{"type":["string","null"]},"contact_id":{"type":"integer"},"contact_name":{"type":"string"},"conversation_id":{"type":"integer"},"conversation_display_id":{"type":["integer","null"]},"crm_item_id":{"type":"integer"},"payments_charge_id":{"type":"integer"},"payments_subscription_id":{"type":"integer"},"calendar_booking_id":{"type":"integer"},"follow_up_enrollment_id":{"type":"integer"},"variables_snapshot":{"type":"object","additionalProperties":true,"description":"Merge variables captured at send-time, keyed by template variable name."},"metadata":{"type":"object","additionalProperties":true,"description":"Free-form metadata bag; the key set depends on the record and context."},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"signers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"role":{"type":"string","enum":["contractor","contracted","witness","guarantor"]},"name":{"type":"string"},"email":{"type":"string","format":"email"},"phone":{"type":"string"},"document":{"type":"string"},"status":{"type":"string","enum":["pending","viewed","signed","rejected"]},"auth_method":{"type":"string","enum":["none","email_otp","whatsapp_otp","icp_brasil"]},"auto_sign":{"type":"string"},"sign_order":{"type":"string"},"is_responsible":{"type":"boolean"},"signed_at":{"type":"string","format":"date-time"},"contact_id":{"type":"integer"},"company_id":{"type":"integer"},"has_signing_token":{"type":"boolean"}}}},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"kind":{"type":"string","enum":["product","service","fee","discount"],"description":"The kind of contract line item."},"name":{"type":"string"},"price":{"type":"number"},"quantity":{"type":"string"},"currency":{"type":"string"},"line_total":{"type":"number"},"catalog_product_id":{"type":"integer"},"clause":{"type":"string"}}}},"signers_count":{"type":"integer"},"signed_count":{"type":"integer"}}}},"meta":{"type":"object","properties":{"count":{"type":"integer"},"current_page":{"type":"string"},"total_pages":{"type":"string"},"per_page":{"type":"string"},"has_more":{"type":"boolean"}}}}},"example":{"payload":[{"id":1,"title":"Sample title","status":"draft","signature_tier":"simple","region":"sample region","locale":"en","verification_code":"sample verification code","public_verification_url":"https://example.com/resource","document_sha256":"sample document sha256","sent_at":"2026-01-15T10:30:00.000Z","expires_at":"2026-01-15T10:30:00.000Z","completed_at":"2026-01-15T10:30:00.000Z","voided_at":"2026-01-15T10:30:00.000Z","archived":true,"legally_binding":true,"company_signature_pending":true,"created_by_id":1,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","template_id":1,"company_id":1,"company_name":"sample company name","contact_id":1,"contact_name":"sample contact name","conversation_id":1,"conversation_display_id":1,"crm_item_id":1,"payments_charge_id":1,"payments_subscription_id":1,"calendar_booking_id":1,"follow_up_enrollment_id":1,"variables_snapshot":{},"metadata":{},"custom_attributes":{},"signers":[{"id":1,"role":"contractor","name":"Sample Name","email":"agent@example.com","phone":"+5511999998888","document":"sample document","status":"pending","auth_method":"none","auto_sign":"sample auto sign","sign_order":"sample sign order","is_responsible":true,"signed_at":"2026-01-15T10:30:00.000Z","contact_id":1,"company_id":1,"has_signing_token":true}],"items":[{"id":1,"kind":"product","name":"Sample Name","price":149.9,"quantity":"sample quantity","currency":"BRL","line_total":149.9,"catalog_product_id":1,"clause":"sample clause"}],"signers_count":5,"signed_count":5}],"meta":{"count":5,"current_page":"sample current page","total_pages":"sample total pages","per_page":"sample per page","has_more":true}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."}]},"post":{"tags":["Contracts"],"operationId":"auto_post_api_v1_accounts_account_id_contracts","summary":"Create contracts","description":"Creates a new contract from the request payload. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"title":{"type":"string"},"status":{"type":"string","enum":["draft","pending_signature","partially_signed","completed","rejected","expired","voided","canceled"]},"signature_tier":{"type":"string","enum":["simple","advanced","qualified"]},"region":{"type":"string"},"locale":{"type":"string"},"verification_code":{"type":"string"},"public_verification_url":{"type":"string"},"document_sha256":{"type":"string"},"sent_at":{"type":"string","format":"date-time"},"expires_at":{"type":"string","format":"date-time"},"completed_at":{"type":"string","format":"date-time"},"voided_at":{"type":"string","format":"date-time"},"archived":{"type":"boolean"},"legally_binding":{"type":"boolean"},"company_signature_pending":{"type":"boolean"},"created_by_id":{"type":"integer"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"template_id":{"type":"integer"},"company_id":{"type":"integer"},"company_name":{"type":["string","null"]},"contact_id":{"type":"integer"},"contact_name":{"type":"string"},"conversation_id":{"type":"integer"},"conversation_display_id":{"type":["integer","null"]},"crm_item_id":{"type":"integer"},"payments_charge_id":{"type":"integer"},"payments_subscription_id":{"type":"integer"},"calendar_booking_id":{"type":"integer"},"follow_up_enrollment_id":{"type":"integer"},"variables_snapshot":{"type":"object","additionalProperties":true,"description":"Merge variables captured at send-time, keyed by template variable name."},"metadata":{"type":"object","additionalProperties":true,"description":"Free-form metadata bag; the key set depends on the record and context."},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"signers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"role":{"type":"string","enum":["contractor","contracted","witness","guarantor"]},"name":{"type":"string"},"email":{"type":"string","format":"email"},"phone":{"type":"string"},"document":{"type":"string"},"status":{"type":"string","enum":["pending","viewed","signed","rejected"]},"auth_method":{"type":"string","enum":["none","email_otp","whatsapp_otp","icp_brasil"]},"auto_sign":{"type":"string"},"sign_order":{"type":"string"},"is_responsible":{"type":"boolean"},"signed_at":{"type":"string","format":"date-time"},"contact_id":{"type":"integer"},"company_id":{"type":"integer"},"has_signing_token":{"type":"boolean"}}}},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"kind":{"type":"string","enum":["product","service","fee","discount"],"description":"The kind of contract line item."},"name":{"type":"string"},"price":{"type":"number"},"quantity":{"type":"string"},"currency":{"type":"string"},"line_total":{"type":"number"},"catalog_product_id":{"type":"integer"},"clause":{"type":"string"}}}},"signers_count":{"type":"integer"},"signed_count":{"type":"integer"},"body_snapshot":{"type":"string"}}}}},"example":{"payload":{"id":1,"title":"Sample title","status":"draft","signature_tier":"simple","region":"sample region","locale":"en","verification_code":"sample verification code","public_verification_url":"https://example.com/resource","document_sha256":"sample document sha256","sent_at":"2026-01-15T10:30:00.000Z","expires_at":"2026-01-15T10:30:00.000Z","completed_at":"2026-01-15T10:30:00.000Z","voided_at":"2026-01-15T10:30:00.000Z","archived":true,"legally_binding":true,"company_signature_pending":true,"created_by_id":1,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","template_id":1,"company_id":1,"company_name":"sample company name","contact_id":1,"contact_name":"sample contact name","conversation_id":1,"conversation_display_id":1,"crm_item_id":1,"payments_charge_id":1,"payments_subscription_id":1,"calendar_booking_id":1,"follow_up_enrollment_id":1,"variables_snapshot":{},"metadata":{},"custom_attributes":{},"signers":[{"id":1,"role":"contractor","name":"Sample Name","email":"agent@example.com","phone":"+5511999998888","document":"sample document","status":"pending","auth_method":"none","auto_sign":"sample auto sign","sign_order":"sample sign order","is_responsible":true,"signed_at":"2026-01-15T10:30:00.000Z","contact_id":1,"company_id":1,"has_signing_token":true}],"items":[{"id":1,"kind":"product","name":"Sample Name","price":149.9,"quantity":"sample quantity","currency":"BRL","line_total":149.9,"catalog_product_id":1,"clause":"sample clause"}],"signers_count":5,"signed_count":5,"body_snapshot":"sample body snapshot"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"contract":{"type":"object","properties":{"template_id":{"type":"integer"},"company_id":{"type":"integer"},"title":{"type":"string"},"signature_tier":{"type":"string","enum":["simple","advanced","qualified"]},"region":{"type":"string"},"locale":{"type":"string","enum":["en","pt_BR","es"]},"contact_id":{"type":"integer"},"organization_id":{"type":"integer"},"conversation_id":{"type":"integer"},"crm_item_id":{"type":"integer"},"payments_charge_id":{"type":"integer"},"calendar_booking_id":{"type":"integer"},"expires_at":{"type":"string","format":"date-time"},"variables":{"type":"object","additionalProperties":true,"description":"Free-form object."},"metadata":{"type":"object","additionalProperties":true,"description":"Free-form metadata bag; the key set depends on the record and context."},"signers":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Free-form object."}},"items":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Free-form object."}}},"required":["title"]}},"required":["contract"]},"example":{"contract":{"template_id":1,"company_id":1,"title":"Sample title","signature_tier":"simple","region":"sample region","locale":"en","contact_id":1,"organization_id":1,"conversation_id":1,"crm_item_id":1,"payments_charge_id":1,"calendar_booking_id":1,"expires_at":"2026-01-15T10:30:00.000Z","variables":{},"metadata":{},"signers":[{}],"items":[{}]}}}}}}},"/api/v1/accounts/{account_id}/contracts/{id}":{"get":{"tags":["Contracts"],"operationId":"auto_get_api_v1_accounts_account_id_contracts_id","summary":"Get contracts","description":"Returns the contract identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"title":{"type":"string"},"status":{"type":"string","enum":["draft","pending_signature","partially_signed","completed","rejected","expired","voided","canceled"]},"signature_tier":{"type":"string","enum":["simple","advanced","qualified"]},"region":{"type":"string"},"locale":{"type":"string"},"verification_code":{"type":"string"},"public_verification_url":{"type":"string"},"document_sha256":{"type":"string"},"sent_at":{"type":"string","format":"date-time"},"expires_at":{"type":"string","format":"date-time"},"completed_at":{"type":"string","format":"date-time"},"voided_at":{"type":"string","format":"date-time"},"archived":{"type":"boolean"},"legally_binding":{"type":"boolean"},"company_signature_pending":{"type":"boolean"},"created_by_id":{"type":"integer"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"template_id":{"type":"integer"},"company_id":{"type":"integer"},"company_name":{"type":["string","null"]},"contact_id":{"type":"integer"},"contact_name":{"type":"string"},"conversation_id":{"type":"integer"},"conversation_display_id":{"type":["integer","null"]},"crm_item_id":{"type":"integer"},"payments_charge_id":{"type":"integer"},"payments_subscription_id":{"type":"integer"},"calendar_booking_id":{"type":"integer"},"follow_up_enrollment_id":{"type":"integer"},"variables_snapshot":{"type":"object","additionalProperties":true,"description":"Merge variables captured at send-time, keyed by template variable name."},"metadata":{"type":"object","additionalProperties":true,"description":"Free-form metadata bag; the key set depends on the record and context."},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"signers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"role":{"type":"string","enum":["contractor","contracted","witness","guarantor"]},"name":{"type":"string"},"email":{"type":"string","format":"email"},"phone":{"type":"string"},"document":{"type":"string"},"status":{"type":"string","enum":["pending","viewed","signed","rejected"]},"auth_method":{"type":"string","enum":["none","email_otp","whatsapp_otp","icp_brasil"]},"auto_sign":{"type":"string"},"sign_order":{"type":"string"},"is_responsible":{"type":"boolean"},"signed_at":{"type":"string","format":"date-time"},"contact_id":{"type":"integer"},"company_id":{"type":"integer"},"has_signing_token":{"type":"boolean"}}}},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"kind":{"type":"string","enum":["product","service","fee","discount"],"description":"The kind of contract line item."},"name":{"type":"string"},"price":{"type":"number"},"quantity":{"type":"string"},"currency":{"type":"string"},"line_total":{"type":"number"},"catalog_product_id":{"type":"integer"},"clause":{"type":"string"}}}},"signers_count":{"type":"integer"},"signed_count":{"type":"integer"},"body_snapshot":{"type":"string"}}}}},"example":{"payload":{"id":1,"title":"Sample title","status":"draft","signature_tier":"simple","region":"sample region","locale":"en","verification_code":"sample verification code","public_verification_url":"https://example.com/resource","document_sha256":"sample document sha256","sent_at":"2026-01-15T10:30:00.000Z","expires_at":"2026-01-15T10:30:00.000Z","completed_at":"2026-01-15T10:30:00.000Z","voided_at":"2026-01-15T10:30:00.000Z","archived":true,"legally_binding":true,"company_signature_pending":true,"created_by_id":1,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","template_id":1,"company_id":1,"company_name":"sample company name","contact_id":1,"contact_name":"sample contact name","conversation_id":1,"conversation_display_id":1,"crm_item_id":1,"payments_charge_id":1,"payments_subscription_id":1,"calendar_booking_id":1,"follow_up_enrollment_id":1,"variables_snapshot":{},"metadata":{},"custom_attributes":{},"signers":[{"id":1,"role":"contractor","name":"Sample Name","email":"agent@example.com","phone":"+5511999998888","document":"sample document","status":"pending","auth_method":"none","auto_sign":"sample auto sign","sign_order":"sample sign order","is_responsible":true,"signed_at":"2026-01-15T10:30:00.000Z","contact_id":1,"company_id":1,"has_signing_token":true}],"items":[{"id":1,"kind":"product","name":"Sample Name","price":149.9,"quantity":"sample quantity","currency":"BRL","line_total":149.9,"catalog_product_id":1,"clause":"sample clause"}],"signers_count":5,"signed_count":5,"body_snapshot":"sample body snapshot"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]},"patch":{"tags":["Contracts"],"operationId":"auto_patch_api_v1_accounts_account_id_contracts_id","summary":"Update contracts","description":"Updates the contract identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"title":{"type":"string"},"status":{"type":"string","enum":["draft","pending_signature","partially_signed","completed","rejected","expired","voided","canceled"]},"signature_tier":{"type":"string","enum":["simple","advanced","qualified"]},"region":{"type":"string"},"locale":{"type":"string"},"verification_code":{"type":"string"},"public_verification_url":{"type":"string"},"document_sha256":{"type":"string"},"sent_at":{"type":"string","format":"date-time"},"expires_at":{"type":"string","format":"date-time"},"completed_at":{"type":"string","format":"date-time"},"voided_at":{"type":"string","format":"date-time"},"archived":{"type":"boolean"},"legally_binding":{"type":"boolean"},"company_signature_pending":{"type":"boolean"},"created_by_id":{"type":"integer"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"template_id":{"type":"integer"},"company_id":{"type":"integer"},"company_name":{"type":["string","null"]},"contact_id":{"type":"integer"},"contact_name":{"type":"string"},"conversation_id":{"type":"integer"},"conversation_display_id":{"type":["integer","null"]},"crm_item_id":{"type":"integer"},"payments_charge_id":{"type":"integer"},"payments_subscription_id":{"type":"integer"},"calendar_booking_id":{"type":"integer"},"follow_up_enrollment_id":{"type":"integer"},"variables_snapshot":{"type":"object","additionalProperties":true,"description":"Merge variables captured at send-time, keyed by template variable name."},"metadata":{"type":"object","additionalProperties":true,"description":"Free-form metadata bag; the key set depends on the record and context."},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"signers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"role":{"type":"string","enum":["contractor","contracted","witness","guarantor"]},"name":{"type":"string"},"email":{"type":"string","format":"email"},"phone":{"type":"string"},"document":{"type":"string"},"status":{"type":"string","enum":["pending","viewed","signed","rejected"]},"auth_method":{"type":"string","enum":["none","email_otp","whatsapp_otp","icp_brasil"]},"auto_sign":{"type":"string"},"sign_order":{"type":"string"},"is_responsible":{"type":"boolean"},"signed_at":{"type":"string","format":"date-time"},"contact_id":{"type":"integer"},"company_id":{"type":"integer"},"has_signing_token":{"type":"boolean"}}}},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"kind":{"type":"string","enum":["product","service","fee","discount"],"description":"The kind of contract line item."},"name":{"type":"string"},"price":{"type":"number"},"quantity":{"type":"string"},"currency":{"type":"string"},"line_total":{"type":"number"},"catalog_product_id":{"type":"integer"},"clause":{"type":"string"}}}},"signers_count":{"type":"integer"},"signed_count":{"type":"integer"},"body_snapshot":{"type":"string"}}}}},"example":{"payload":{"id":1,"title":"Sample title","status":"draft","signature_tier":"simple","region":"sample region","locale":"en","verification_code":"sample verification code","public_verification_url":"https://example.com/resource","document_sha256":"sample document sha256","sent_at":"2026-01-15T10:30:00.000Z","expires_at":"2026-01-15T10:30:00.000Z","completed_at":"2026-01-15T10:30:00.000Z","voided_at":"2026-01-15T10:30:00.000Z","archived":true,"legally_binding":true,"company_signature_pending":true,"created_by_id":1,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","template_id":1,"company_id":1,"company_name":"sample company name","contact_id":1,"contact_name":"sample contact name","conversation_id":1,"conversation_display_id":1,"crm_item_id":1,"payments_charge_id":1,"payments_subscription_id":1,"calendar_booking_id":1,"follow_up_enrollment_id":1,"variables_snapshot":{},"metadata":{},"custom_attributes":{},"signers":[{"id":1,"role":"contractor","name":"Sample Name","email":"agent@example.com","phone":"+5511999998888","document":"sample document","status":"pending","auth_method":"none","auto_sign":"sample auto sign","sign_order":"sample sign order","is_responsible":true,"signed_at":"2026-01-15T10:30:00.000Z","contact_id":1,"company_id":1,"has_signing_token":true}],"items":[{"id":1,"kind":"product","name":"Sample Name","price":149.9,"quantity":"sample quantity","currency":"BRL","line_total":149.9,"catalog_product_id":1,"clause":"sample clause"}],"signers_count":5,"signed_count":5,"body_snapshot":"sample body snapshot"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"contract":{"type":"object","properties":{"title":{"type":"string"},"signature_tier":{"type":"string","enum":["simple","advanced","qualified"]},"region":{"type":"string"},"locale":{"type":"string","enum":["en","pt_BR","es"]},"expires_at":{"type":"string","format":"date-time"},"body_snapshot":{"type":"string"},"variables_snapshot":{"type":"object","additionalProperties":true,"description":"Merge variables captured at send-time, keyed by template variable name."},"metadata":{"type":"object","additionalProperties":true,"description":"Free-form metadata bag; the key set depends on the record and context."}}}},"required":["contract"]},"example":{"contract":{"title":"Sample title","signature_tier":"simple","region":"sample region","locale":"en","expires_at":"2026-01-15T10:30:00.000Z","body_snapshot":"sample body snapshot","variables_snapshot":{},"metadata":{}}}}}}},"put":{"tags":["Contracts"],"operationId":"auto_put_api_v1_accounts_account_id_contracts_id","summary":"Update contracts","description":"Updates the contract identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"title":{"type":"string"},"status":{"type":"string","enum":["draft","pending_signature","partially_signed","completed","rejected","expired","voided","canceled"]},"signature_tier":{"type":"string","enum":["simple","advanced","qualified"]},"region":{"type":"string"},"locale":{"type":"string"},"verification_code":{"type":"string"},"public_verification_url":{"type":"string"},"document_sha256":{"type":"string"},"sent_at":{"type":"string","format":"date-time"},"expires_at":{"type":"string","format":"date-time"},"completed_at":{"type":"string","format":"date-time"},"voided_at":{"type":"string","format":"date-time"},"archived":{"type":"boolean"},"legally_binding":{"type":"boolean"},"company_signature_pending":{"type":"boolean"},"created_by_id":{"type":"integer"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"template_id":{"type":"integer"},"company_id":{"type":"integer"},"company_name":{"type":["string","null"]},"contact_id":{"type":"integer"},"contact_name":{"type":"string"},"conversation_id":{"type":"integer"},"conversation_display_id":{"type":["integer","null"]},"crm_item_id":{"type":"integer"},"payments_charge_id":{"type":"integer"},"payments_subscription_id":{"type":"integer"},"calendar_booking_id":{"type":"integer"},"follow_up_enrollment_id":{"type":"integer"},"variables_snapshot":{"type":"object","additionalProperties":true,"description":"Merge variables captured at send-time, keyed by template variable name."},"metadata":{"type":"object","additionalProperties":true,"description":"Free-form metadata bag; the key set depends on the record and context."},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"signers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"role":{"type":"string","enum":["contractor","contracted","witness","guarantor"]},"name":{"type":"string"},"email":{"type":"string","format":"email"},"phone":{"type":"string"},"document":{"type":"string"},"status":{"type":"string","enum":["pending","viewed","signed","rejected"]},"auth_method":{"type":"string","enum":["none","email_otp","whatsapp_otp","icp_brasil"]},"auto_sign":{"type":"string"},"sign_order":{"type":"string"},"is_responsible":{"type":"boolean"},"signed_at":{"type":"string","format":"date-time"},"contact_id":{"type":"integer"},"company_id":{"type":"integer"},"has_signing_token":{"type":"boolean"}}}},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"kind":{"type":"string","enum":["product","service","fee","discount"],"description":"The kind of contract line item."},"name":{"type":"string"},"price":{"type":"number"},"quantity":{"type":"string"},"currency":{"type":"string"},"line_total":{"type":"number"},"catalog_product_id":{"type":"integer"},"clause":{"type":"string"}}}},"signers_count":{"type":"integer"},"signed_count":{"type":"integer"},"body_snapshot":{"type":"string"}}}}},"example":{"payload":{"id":1,"title":"Sample title","status":"draft","signature_tier":"simple","region":"sample region","locale":"en","verification_code":"sample verification code","public_verification_url":"https://example.com/resource","document_sha256":"sample document sha256","sent_at":"2026-01-15T10:30:00.000Z","expires_at":"2026-01-15T10:30:00.000Z","completed_at":"2026-01-15T10:30:00.000Z","voided_at":"2026-01-15T10:30:00.000Z","archived":true,"legally_binding":true,"company_signature_pending":true,"created_by_id":1,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","template_id":1,"company_id":1,"company_name":"sample company name","contact_id":1,"contact_name":"sample contact name","conversation_id":1,"conversation_display_id":1,"crm_item_id":1,"payments_charge_id":1,"payments_subscription_id":1,"calendar_booking_id":1,"follow_up_enrollment_id":1,"variables_snapshot":{},"metadata":{},"custom_attributes":{},"signers":[{"id":1,"role":"contractor","name":"Sample Name","email":"agent@example.com","phone":"+5511999998888","document":"sample document","status":"pending","auth_method":"none","auto_sign":"sample auto sign","sign_order":"sample sign order","is_responsible":true,"signed_at":"2026-01-15T10:30:00.000Z","contact_id":1,"company_id":1,"has_signing_token":true}],"items":[{"id":1,"kind":"product","name":"Sample Name","price":149.9,"quantity":"sample quantity","currency":"BRL","line_total":149.9,"catalog_product_id":1,"clause":"sample clause"}],"signers_count":5,"signed_count":5,"body_snapshot":"sample body snapshot"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"contract":{"type":"object","properties":{"title":{"type":"string"},"signature_tier":{"type":"string","enum":["simple","advanced","qualified"]},"region":{"type":"string"},"locale":{"type":"string","enum":["en","pt_BR","es"]},"expires_at":{"type":"string","format":"date-time"},"body_snapshot":{"type":"string"},"variables_snapshot":{"type":"object","additionalProperties":true,"description":"Merge variables captured at send-time, keyed by template variable name."},"metadata":{"type":"object","additionalProperties":true,"description":"Free-form metadata bag; the key set depends on the record and context."}}}},"required":["contract"]},"example":{"contract":{"title":"Sample title","signature_tier":"simple","region":"sample region","locale":"en","expires_at":"2026-01-15T10:30:00.000Z","body_snapshot":"sample body snapshot","variables_snapshot":{},"metadata":{}}}}}}},"delete":{"tags":["Contracts"],"operationId":"auto_delete_api_v1_accounts_account_id_contracts_id","summary":"Delete contracts","description":"Deletes the contract identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Success (no content)"},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/sales/portfolio":{"get":{"tags":["Sales"],"operationId":"auto_get_api_v1_accounts_account_id_sales_portfolio","summary":"Get portfolio","description":"Returns the portfolio identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"owner_id":{"type":"integer"},"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"display_id":{"type":"integer"},"type":{"type":"string"},"name":{"type":"string"},"owner_id":{"type":"integer"},"value":{"type":"number"},"status":{"type":"string"}}}},"meta":{"type":"object","properties":{"count":{"type":"integer"},"current_page":{"type":"string"},"total_pages":{"type":"string"},"has_more":{"type":"boolean"}}}}},"example":{"owner_id":1,"payload":[{"id":1,"display_id":1,"type":"sample type","name":"Sample Name","owner_id":1,"value":149.9,"status":"active"}],"meta":{"count":5,"current_page":"sample current page","total_pages":"sample total pages","has_more":true}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/sales/transfers":{"get":{"tags":["Sales"],"operationId":"auto_get_api_v1_accounts_account_id_sales_transfers","summary":"List transfers","description":"Returns the list of transfers visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"from_owner_id":{"type":["integer","null"]},"from_owner_name":{"type":["string","null"]},"to_owner_id":{"type":["integer","null"]},"to_owner_name":{"type":["string","null"]},"scope":{"type":"string","enum":["all_open","conversations","deals","contacts"],"description":"Entity scope moved by the portfolio operation."},"carried_over":{"type":"object","additionalProperties":false,"description":"Counts of records moved by entity type; an individual assignment also carries its target record id.","properties":{"conversations":{"type":"integer","minimum":0},"deals":{"type":"integer","minimum":0},"contacts":{"type":"integer","minimum":0},"record_ids":{"type":"array","items":{"type":"integer","minimum":1}}}},"reason":{"type":"string"},"performed_by_id":{"type":["integer","null"]},"performed_by_name":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}},"meta":{"type":"object","properties":{"count":{"type":"integer"},"current_page":{"type":"integer","minimum":1},"total_pages":{"type":"integer","minimum":1},"per_page":{"type":"integer","minimum":1},"has_more":{"type":"boolean"}}}}},"example":{"payload":[{"id":1,"account_id":1,"from_owner_id":1,"from_owner_name":"sample from owner name","to_owner_id":1,"to_owner_name":"sample to owner name","scope":"all_open","carried_over":{"conversations":1,"deals":1,"contacts":1,"record_ids":[1]},"reason":"Sample reason.","performed_by_id":1,"performed_by_name":"sample performed by name","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}],"meta":{"count":5,"current_page":1,"total_pages":1,"per_page":1,"has_more":true}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."}]},"post":{"tags":["Sales"],"operationId":"auto_post_api_v1_accounts_account_id_sales_transfers","summary":"Create transfers","description":"Creates a new transfer from the request payload. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"201":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"from_owner_id":{"type":["integer","null"]},"from_owner_name":{"type":["string","null"]},"to_owner_id":{"type":["integer","null"]},"to_owner_name":{"type":["string","null"]},"scope":{"type":"string","enum":["all_open","conversations","deals","contacts"],"description":"Entity scope moved by the portfolio operation."},"carried_over":{"type":"object","additionalProperties":false,"description":"Counts of records moved by entity type; an individual assignment also carries its target record id.","properties":{"conversations":{"type":"integer","minimum":0},"deals":{"type":"integer","minimum":0},"contacts":{"type":"integer","minimum":0},"record_ids":{"type":"array","items":{"type":"integer","minimum":1}}}},"reason":{"type":"string"},"performed_by_id":{"type":["integer","null"]},"performed_by_name":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"example":{"id":1,"account_id":1,"from_owner_id":1,"from_owner_name":"sample from owner name","to_owner_id":1,"to_owner_name":"sample to owner name","scope":"all_open","carried_over":{"conversations":1,"deals":1,"contacts":1,"record_ids":[1]},"reason":"Sample reason.","performed_by_id":1,"performed_by_name":"sample performed by name","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"transfer":{"type":"object","properties":{"from_owner_id":{"type":["integer","null"]},"to_owner_id":{"type":["integer","null"]},"scope":{"type":"string","enum":["all_open","conversations","deals","contacts"],"description":"Entity scope moved by the portfolio operation."},"reason":{"type":"string","enum":["","client_revocation","refresh_token_reuse","subject_revoked","account_admin_security_review","account_admin_access_removed","account_admin_client_decommissioned","account_admin_incident_response","operator_security_review","operator_access_removed","operator_client_decommissioned","operator_incident_response","operator_credential_provisioning","operator_credential_rotation","operator_approval_required","operator_approval_approved","operator_approval_rejected","operator_approval_execution_failed","operator_approval_response_delivery_failed","operator_approval_execution_unknown","operator_approval_execution_started","operator_approval_execution_succeeded","operator_approval_execution_rejected","operator_approval_confirmed_succeeded","operator_approval_confirmed_not_applied","operator_delegation_profile_changed","operator_delegation_profile_revoked","mfa_disabled"]},"record_ids":{"type":"array","items":{"type":"integer"}}}}},"required":["transfer"]},"example":{"transfer":{"from_owner_id":1,"to_owner_id":1,"scope":"all_open","reason":"","record_ids":[1]}}}}}}},"/api/v1/accounts/{account_id}/sales/distribution_rules":{"get":{"tags":["Sales"],"operationId":"auto_get_api_v1_accounts_account_id_sales_distribution_rules","summary":"List distribution rules","description":"Returns the list of distribution rules visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"name":{"type":"string"},"position":{"type":"integer"},"conditions":{"type":"string"},"target_type":{"type":"string","enum":["user","team_round_robin","pool"]},"target_id":{"type":"integer"},"sla_minutes":{"type":"integer"},"fallback_target_id":{"type":"integer"},"active":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}}},"example":{"payload":[{"id":1,"account_id":1,"name":"Sample Name","position":1,"conditions":"sample conditions","target_type":"user","target_id":1,"sla_minutes":60,"fallback_target_id":1,"active":true,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."}]},"post":{"tags":["Sales"],"operationId":"auto_post_api_v1_accounts_account_id_sales_distribution_rules","summary":"Create distribution rules","description":"Creates a new distribution rule from the request payload. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"201":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"name":{"type":"string"},"position":{"type":"integer"},"conditions":{"type":"string"},"target_type":{"type":"string","enum":["user","team_round_robin","pool"]},"target_id":{"type":"integer"},"sla_minutes":{"type":"integer"},"fallback_target_id":{"type":"integer"},"active":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"example":{"id":1,"account_id":1,"name":"Sample Name","position":1,"conditions":"sample conditions","target_type":"user","target_id":1,"sla_minutes":60,"fallback_target_id":1,"active":true,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"distribution_rule":{"type":"object","properties":{"name":{"type":"string"},"position":{"type":"integer"},"target_type":{"type":"string","enum":["user","team_round_robin","pool"]},"target_id":{"type":"integer"},"sla_minutes":{"type":"integer"},"fallback_target_id":{"type":"integer"},"active":{"type":"boolean"}},"required":["name","target_type"]}},"required":["distribution_rule"]},"example":{"distribution_rule":{"name":"Sample Name","position":1,"target_type":"user","target_id":1,"sla_minutes":60,"fallback_target_id":1,"active":true}}}}}}},"/api/v1/accounts/{account_id}/sales/distribution_rules/{id}":{"get":{"tags":["Sales"],"operationId":"auto_get_api_v1_accounts_account_id_sales_distribution_rules_id","summary":"Get distribution rules","description":"Returns the distribution rule identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"name":{"type":"string"},"position":{"type":"integer"},"conditions":{"type":"string"},"target_type":{"type":"string","enum":["user","team_round_robin","pool"]},"target_id":{"type":"integer"},"sla_minutes":{"type":"integer"},"fallback_target_id":{"type":"integer"},"active":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"example":{"id":1,"account_id":1,"name":"Sample Name","position":1,"conditions":"sample conditions","target_type":"user","target_id":1,"sla_minutes":60,"fallback_target_id":1,"active":true,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]},"patch":{"tags":["Sales"],"operationId":"auto_patch_api_v1_accounts_account_id_sales_distribution_rules_id","summary":"Update distribution rules","description":"Updates the distribution rule identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"name":{"type":"string"},"position":{"type":"integer"},"conditions":{"type":"string"},"target_type":{"type":"string","enum":["user","team_round_robin","pool"]},"target_id":{"type":"integer"},"sla_minutes":{"type":"integer"},"fallback_target_id":{"type":"integer"},"active":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"example":{"id":1,"account_id":1,"name":"Sample Name","position":1,"conditions":"sample conditions","target_type":"user","target_id":1,"sla_minutes":60,"fallback_target_id":1,"active":true,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"distribution_rule":{"type":"object","properties":{"name":{"type":"string"},"position":{"type":"integer"},"target_type":{"type":"string","enum":["user","team_round_robin","pool"]},"target_id":{"type":"integer"},"sla_minutes":{"type":"integer"},"fallback_target_id":{"type":"integer"},"active":{"type":"boolean"}}}},"required":["distribution_rule"]},"example":{"distribution_rule":{"name":"Sample Name","position":1,"target_type":"user","target_id":1,"sla_minutes":60,"fallback_target_id":1,"active":true}}}}}},"put":{"tags":["Sales"],"operationId":"auto_put_api_v1_accounts_account_id_sales_distribution_rules_id","summary":"Update distribution rules","description":"Updates the distribution rule identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"name":{"type":"string"},"position":{"type":"integer"},"conditions":{"type":"string"},"target_type":{"type":"string","enum":["user","team_round_robin","pool"]},"target_id":{"type":"integer"},"sla_minutes":{"type":"integer"},"fallback_target_id":{"type":"integer"},"active":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"example":{"id":1,"account_id":1,"name":"Sample Name","position":1,"conditions":"sample conditions","target_type":"user","target_id":1,"sla_minutes":60,"fallback_target_id":1,"active":true,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"distribution_rule":{"type":"object","properties":{"name":{"type":"string"},"position":{"type":"integer"},"target_type":{"type":"string","enum":["user","team_round_robin","pool"]},"target_id":{"type":"integer"},"sla_minutes":{"type":"integer"},"fallback_target_id":{"type":"integer"},"active":{"type":"boolean"}}}},"required":["distribution_rule"]},"example":{"distribution_rule":{"name":"Sample Name","position":1,"target_type":"user","target_id":1,"sla_minutes":60,"fallback_target_id":1,"active":true}}}}}},"delete":{"tags":["Sales"],"operationId":"auto_delete_api_v1_accounts_account_id_sales_distribution_rules_id","summary":"Delete distribution rules","description":"Deletes the distribution rule identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"204":{"description":"Success (no content)"},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/sales/goals/{goal_id}/goal_tiers":{"get":{"tags":["Sales"],"operationId":"auto_get_api_v1_accounts_account_id_sales_goals_goal_id_goal_tiers","summary":"List goal tiers","description":"Returns the list of goal tiers visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"goal_id":{"type":"integer"},"position":{"type":"integer"},"label":{"type":"string"},"threshold_pct":{"type":"number"},"threshold_value":{"type":"number"},"reward_id":{"type":"integer"},"commission_multiplier":{"type":"string"},"medal_band":{"type":"string"},"points_bonus":{"type":"string"},"settings":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}}},"example":{"payload":[{"id":1,"account_id":1,"goal_id":1,"position":1,"label":"sample label","threshold_pct":12.5,"threshold_value":149.9,"reward_id":1,"commission_multiplier":"sample commission multiplier","medal_band":"sample medal band","points_bonus":"sample points bonus","settings":"sample settings","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"goal_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."}]},"post":{"tags":["Sales"],"operationId":"auto_post_api_v1_accounts_account_id_sales_goals_goal_id_goal_tiers","summary":"Create goal tiers","description":"Creates a new goal tier from the request payload. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"201":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"goal_id":{"type":"integer"},"position":{"type":"integer"},"label":{"type":"string"},"threshold_pct":{"type":"number"},"threshold_value":{"type":"number"},"reward_id":{"type":"integer"},"commission_multiplier":{"type":"string"},"medal_band":{"type":"string"},"points_bonus":{"type":"string"},"settings":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"example":{"id":1,"account_id":1,"goal_id":1,"position":1,"label":"sample label","threshold_pct":12.5,"threshold_value":149.9,"reward_id":1,"commission_multiplier":"sample commission multiplier","medal_band":"sample medal band","points_bonus":"sample points bonus","settings":"sample settings","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"goal_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"goal_tier":{"type":"object","properties":{"position":{"type":"integer"},"label":{"type":"string"},"threshold_pct":{"type":"number"},"threshold_value":{"type":"number"},"reward_id":{"type":"integer"},"commission_multiplier":{"type":"string"},"medal_band":{"type":"string"},"points_bonus":{"type":"string"}},"required":["position"]}},"required":["goal_tier"]},"example":{"goal_tier":{"position":1,"label":"sample label","threshold_pct":12.5,"threshold_value":149.9,"reward_id":1,"commission_multiplier":"sample commission multiplier","medal_band":"sample medal band","points_bonus":"sample points bonus"}}}}}}},"/api/v1/accounts/{account_id}/sales/goals/{goal_id}/goal_tiers/{id}":{"patch":{"tags":["Sales"],"operationId":"auto_patch_api_v1_accounts_account_id_sales_goals_goal_id_goal_tiers_id","summary":"Update goal tiers","description":"Updates the goal tier identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"goal_id":{"type":"integer"},"position":{"type":"integer"},"label":{"type":"string"},"threshold_pct":{"type":"number"},"threshold_value":{"type":"number"},"reward_id":{"type":"integer"},"commission_multiplier":{"type":"string"},"medal_band":{"type":"string"},"points_bonus":{"type":"string"},"settings":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"example":{"id":1,"account_id":1,"goal_id":1,"position":1,"label":"sample label","threshold_pct":12.5,"threshold_value":149.9,"reward_id":1,"commission_multiplier":"sample commission multiplier","medal_band":"sample medal band","points_bonus":"sample points bonus","settings":"sample settings","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"goal_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"goal_tier":{"type":"object","properties":{"position":{"type":"integer"},"label":{"type":"string"},"threshold_pct":{"type":"number"},"threshold_value":{"type":"number"},"reward_id":{"type":"integer"},"commission_multiplier":{"type":"string"},"medal_band":{"type":"string"},"points_bonus":{"type":"string"}}}},"required":["goal_tier"]},"example":{"goal_tier":{"position":1,"label":"sample label","threshold_pct":12.5,"threshold_value":149.9,"reward_id":1,"commission_multiplier":"sample commission multiplier","medal_band":"sample medal band","points_bonus":"sample points bonus"}}}}}},"put":{"tags":["Sales"],"operationId":"auto_put_api_v1_accounts_account_id_sales_goals_goal_id_goal_tiers_id","summary":"Update goal tiers","description":"Updates the goal tier identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"goal_id":{"type":"integer"},"position":{"type":"integer"},"label":{"type":"string"},"threshold_pct":{"type":"number"},"threshold_value":{"type":"number"},"reward_id":{"type":"integer"},"commission_multiplier":{"type":"string"},"medal_band":{"type":"string"},"points_bonus":{"type":"string"},"settings":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"example":{"id":1,"account_id":1,"goal_id":1,"position":1,"label":"sample label","threshold_pct":12.5,"threshold_value":149.9,"reward_id":1,"commission_multiplier":"sample commission multiplier","medal_band":"sample medal band","points_bonus":"sample points bonus","settings":"sample settings","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"goal_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"goal_tier":{"type":"object","properties":{"position":{"type":"integer"},"label":{"type":"string"},"threshold_pct":{"type":"number"},"threshold_value":{"type":"number"},"reward_id":{"type":"integer"},"commission_multiplier":{"type":"string"},"medal_band":{"type":"string"},"points_bonus":{"type":"string"}}}},"required":["goal_tier"]},"example":{"goal_tier":{"position":1,"label":"sample label","threshold_pct":12.5,"threshold_value":149.9,"reward_id":1,"commission_multiplier":"sample commission multiplier","medal_band":"sample medal band","points_bonus":"sample points bonus"}}}}}},"delete":{"tags":["Sales"],"operationId":"auto_delete_api_v1_accounts_account_id_sales_goals_goal_id_goal_tiers_id","summary":"Delete goal tiers","description":"Deletes the goal tier identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"204":{"description":"Success (no content)"},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"goal_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/sales/goals":{"get":{"tags":["Sales"],"operationId":"auto_get_api_v1_accounts_account_id_sales_goals","summary":"List goals","description":"Returns the list of goals visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"name":{"type":"string"},"scope_type":{"type":"string","enum":["user","team","account"]},"scope_id":{"type":"integer"},"period_type":{"type":"string","enum":["week","month","quarter","year"],"description":"The recurring period a sales goal or leaderboard is measured over."},"period_start":{"type":"string"},"period_end":{"type":"string"},"metric_type":{"type":"string","enum":["revenue_won","revenue_paid","deals","conversions","resolutions","bookings","combination","points"]},"target_amount":{"type":"number"},"target_count":{"type":"integer"},"weight":{"type":"string"},"ramp_schedule":{"type":"string"},"settings":{"type":"string"},"archived_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}},"meta":{"type":"object","properties":{"count":{"type":"integer"}}}}},"example":{"payload":[{"id":1,"account_id":1,"name":"Sample Name","scope_type":"user","scope_id":1,"period_type":"week","period_start":"sample period start","period_end":"sample period end","metric_type":"revenue_won","target_amount":149.9,"target_count":5,"weight":"sample weight","ramp_schedule":"sample ramp schedule","settings":"sample settings","archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}],"meta":{"count":5}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."}]},"post":{"tags":["Sales"],"operationId":"auto_post_api_v1_accounts_account_id_sales_goals","summary":"Create goals","description":"Creates a new goal from the request payload. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"201":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"name":{"type":"string"},"scope_type":{"type":"string","enum":["user","team","account"]},"scope_id":{"type":"integer"},"period_type":{"type":"string","enum":["week","month","quarter","year"],"description":"The recurring period a sales goal or leaderboard is measured over."},"period_start":{"type":"string"},"period_end":{"type":"string"},"metric_type":{"type":"string","enum":["revenue_won","revenue_paid","deals","conversions","resolutions","bookings","combination","points"]},"target_amount":{"type":"number"},"target_count":{"type":"integer"},"weight":{"type":"string"},"ramp_schedule":{"type":"string"},"settings":{"type":"string"},"archived_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"attainment":{"type":"string"},"tiers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"goal_id":{"type":"integer"},"position":{"type":"integer"},"label":{"type":"string"},"threshold_pct":{"type":"number"},"threshold_value":{"type":"number"},"reward_id":{"type":"integer"},"commission_multiplier":{"type":"string"},"medal_band":{"type":"string"},"points_bonus":{"type":"string"},"settings":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}}},"example":{"id":1,"account_id":1,"name":"Sample Name","scope_type":"user","scope_id":1,"period_type":"week","period_start":"sample period start","period_end":"sample period end","metric_type":"revenue_won","target_amount":149.9,"target_count":5,"weight":"sample weight","ramp_schedule":"sample ramp schedule","settings":"sample settings","archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","attainment":"sample attainment","tiers":[{"id":1,"account_id":1,"goal_id":1,"position":1,"label":"sample label","threshold_pct":12.5,"threshold_value":149.9,"reward_id":1,"commission_multiplier":"sample commission multiplier","medal_band":"sample medal band","points_bonus":"sample points bonus","settings":"sample settings","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"goal":{"type":"object","properties":{"name":{"type":"string"},"scope_type":{"type":"string","enum":["user","team","account"]},"scope_id":{"type":"integer"},"period_type":{"type":"string","enum":["week","month","quarter","year"],"description":"The recurring period a sales goal or leaderboard is measured over."},"period_start":{"type":"string"},"period_end":{"type":"string"},"metric_type":{"type":"string","enum":["revenue_won","revenue_paid","deals","conversions","resolutions","bookings","combination","points"]},"target_amount":{"type":"number"},"target_count":{"type":"integer"},"weight":{"type":"string"}},"required":["name","scope_type"]}},"required":["goal"]},"example":{"goal":{"name":"Sample Name","scope_type":"user","scope_id":1,"period_type":"week","period_start":"sample period start","period_end":"sample period end","metric_type":"revenue_won","target_amount":149.9,"target_count":5,"weight":"sample weight"}}}}}}},"/api/v1/accounts/{account_id}/sales/goals/{id}":{"get":{"tags":["Sales"],"operationId":"auto_get_api_v1_accounts_account_id_sales_goals_id","summary":"Get goals","description":"Returns the goal identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"name":{"type":"string"},"scope_type":{"type":"string","enum":["user","team","account"]},"scope_id":{"type":"integer"},"period_type":{"type":"string","enum":["week","month","quarter","year"],"description":"The recurring period a sales goal or leaderboard is measured over."},"period_start":{"type":"string"},"period_end":{"type":"string"},"metric_type":{"type":"string","enum":["revenue_won","revenue_paid","deals","conversions","resolutions","bookings","combination","points"]},"target_amount":{"type":"number"},"target_count":{"type":"integer"},"weight":{"type":"string"},"ramp_schedule":{"type":"string"},"settings":{"type":"string"},"archived_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"attainment":{"type":"string"},"tiers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"goal_id":{"type":"integer"},"position":{"type":"integer"},"label":{"type":"string"},"threshold_pct":{"type":"number"},"threshold_value":{"type":"number"},"reward_id":{"type":"integer"},"commission_multiplier":{"type":"string"},"medal_band":{"type":"string"},"points_bonus":{"type":"string"},"settings":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}}},"example":{"id":1,"account_id":1,"name":"Sample Name","scope_type":"user","scope_id":1,"period_type":"week","period_start":"sample period start","period_end":"sample period end","metric_type":"revenue_won","target_amount":149.9,"target_count":5,"weight":"sample weight","ramp_schedule":"sample ramp schedule","settings":"sample settings","archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","attainment":"sample attainment","tiers":[{"id":1,"account_id":1,"goal_id":1,"position":1,"label":"sample label","threshold_pct":12.5,"threshold_value":149.9,"reward_id":1,"commission_multiplier":"sample commission multiplier","medal_band":"sample medal band","points_bonus":"sample points bonus","settings":"sample settings","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]},"patch":{"tags":["Sales"],"operationId":"auto_patch_api_v1_accounts_account_id_sales_goals_id","summary":"Update goals","description":"Updates the goal identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"name":{"type":"string"},"scope_type":{"type":"string","enum":["user","team","account"]},"scope_id":{"type":"integer"},"period_type":{"type":"string","enum":["week","month","quarter","year"],"description":"The recurring period a sales goal or leaderboard is measured over."},"period_start":{"type":"string"},"period_end":{"type":"string"},"metric_type":{"type":"string","enum":["revenue_won","revenue_paid","deals","conversions","resolutions","bookings","combination","points"]},"target_amount":{"type":"number"},"target_count":{"type":"integer"},"weight":{"type":"string"},"ramp_schedule":{"type":"string"},"settings":{"type":"string"},"archived_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"attainment":{"type":"string"},"tiers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"goal_id":{"type":"integer"},"position":{"type":"integer"},"label":{"type":"string"},"threshold_pct":{"type":"number"},"threshold_value":{"type":"number"},"reward_id":{"type":"integer"},"commission_multiplier":{"type":"string"},"medal_band":{"type":"string"},"points_bonus":{"type":"string"},"settings":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}}},"example":{"id":1,"account_id":1,"name":"Sample Name","scope_type":"user","scope_id":1,"period_type":"week","period_start":"sample period start","period_end":"sample period end","metric_type":"revenue_won","target_amount":149.9,"target_count":5,"weight":"sample weight","ramp_schedule":"sample ramp schedule","settings":"sample settings","archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","attainment":"sample attainment","tiers":[{"id":1,"account_id":1,"goal_id":1,"position":1,"label":"sample label","threshold_pct":12.5,"threshold_value":149.9,"reward_id":1,"commission_multiplier":"sample commission multiplier","medal_band":"sample medal band","points_bonus":"sample points bonus","settings":"sample settings","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"goal":{"type":"object","properties":{"name":{"type":"string"},"scope_type":{"type":"string","enum":["user","team","account"]},"scope_id":{"type":"integer"},"period_type":{"type":"string","enum":["week","month","quarter","year"],"description":"The recurring period a sales goal or leaderboard is measured over."},"period_start":{"type":"string"},"period_end":{"type":"string"},"metric_type":{"type":"string","enum":["revenue_won","revenue_paid","deals","conversions","resolutions","bookings","combination","points"]},"target_amount":{"type":"number"},"target_count":{"type":"integer"},"weight":{"type":"string"}}}},"required":["goal"]},"example":{"goal":{"name":"Sample Name","scope_type":"user","scope_id":1,"period_type":"week","period_start":"sample period start","period_end":"sample period end","metric_type":"revenue_won","target_amount":149.9,"target_count":5,"weight":"sample weight"}}}}}},"put":{"tags":["Sales"],"operationId":"auto_put_api_v1_accounts_account_id_sales_goals_id","summary":"Update goals","description":"Updates the goal identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"name":{"type":"string"},"scope_type":{"type":"string","enum":["user","team","account"]},"scope_id":{"type":"integer"},"period_type":{"type":"string","enum":["week","month","quarter","year"],"description":"The recurring period a sales goal or leaderboard is measured over."},"period_start":{"type":"string"},"period_end":{"type":"string"},"metric_type":{"type":"string","enum":["revenue_won","revenue_paid","deals","conversions","resolutions","bookings","combination","points"]},"target_amount":{"type":"number"},"target_count":{"type":"integer"},"weight":{"type":"string"},"ramp_schedule":{"type":"string"},"settings":{"type":"string"},"archived_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"attainment":{"type":"string"},"tiers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"goal_id":{"type":"integer"},"position":{"type":"integer"},"label":{"type":"string"},"threshold_pct":{"type":"number"},"threshold_value":{"type":"number"},"reward_id":{"type":"integer"},"commission_multiplier":{"type":"string"},"medal_band":{"type":"string"},"points_bonus":{"type":"string"},"settings":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}}},"example":{"id":1,"account_id":1,"name":"Sample Name","scope_type":"user","scope_id":1,"period_type":"week","period_start":"sample period start","period_end":"sample period end","metric_type":"revenue_won","target_amount":149.9,"target_count":5,"weight":"sample weight","ramp_schedule":"sample ramp schedule","settings":"sample settings","archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","attainment":"sample attainment","tiers":[{"id":1,"account_id":1,"goal_id":1,"position":1,"label":"sample label","threshold_pct":12.5,"threshold_value":149.9,"reward_id":1,"commission_multiplier":"sample commission multiplier","medal_band":"sample medal band","points_bonus":"sample points bonus","settings":"sample settings","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"goal":{"type":"object","properties":{"name":{"type":"string"},"scope_type":{"type":"string","enum":["user","team","account"]},"scope_id":{"type":"integer"},"period_type":{"type":"string","enum":["week","month","quarter","year"],"description":"The recurring period a sales goal or leaderboard is measured over."},"period_start":{"type":"string"},"period_end":{"type":"string"},"metric_type":{"type":"string","enum":["revenue_won","revenue_paid","deals","conversions","resolutions","bookings","combination","points"]},"target_amount":{"type":"number"},"target_count":{"type":"integer"},"weight":{"type":"string"}}}},"required":["goal"]},"example":{"goal":{"name":"Sample Name","scope_type":"user","scope_id":1,"period_type":"week","period_start":"sample period start","period_end":"sample period end","metric_type":"revenue_won","target_amount":149.9,"target_count":5,"weight":"sample weight"}}}}}},"delete":{"tags":["Sales"],"operationId":"auto_delete_api_v1_accounts_account_id_sales_goals_id","summary":"Delete goals","description":"Deletes the goal identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"204":{"description":"Success (no content)"},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/sales/leaderboard":{"get":{"tags":["Sales"],"operationId":"auto_get_api_v1_accounts_account_id_sales_leaderboard","summary":"Read one sales points leaderboard","description":"Returns exactly one precomputed leaderboard slice. The slice defaults to individual points from deals won in the account's current business month; supplying filters selects another supported points slice. value/points are fractional points; revenue is independent money in row.currency. Invalid filters return 422 instead of widening the response to unrelated periods, metrics or scopes.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"One points-ranked slice with separately stored revenue and its currency. Null currency means unresolved historical money; do not relabel it using current settings.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"scope_type":{"type":"string","enum":["user","team"],"description":"Leaderboard slice scope — per-agent or per-team ranking."},"scope_id":{"type":["integer","null"]},"period_type":{"type":"string","enum":["week","month","quarter","year"],"description":"The recurring period a sales goal or leaderboard is measured over."},"period_start":{"type":"string","format":"date","example":"2026-09-01"},"metric":{"type":"string","example":"deal_won","description":"Point-event metric summed in this leaderboard slice: a platform default, an engine-written metric, or a key the account added to its own point_weights setting."},"user_id":{"type":["integer","null"]},"team_id":{"type":["integer","null"]},"name":{"type":["string","null"]},"avatar_url":{"type":["string","null"]},"rank":{"type":"integer","minimum":1},"value":{"oneOf":[{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},{"type":"number"}],"description":"Decimal serialized as a string or number; values are never currency-converted."},"points":{"oneOf":[{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},{"type":"number"}],"description":"Decimal serialized as a string or number; values are never currency-converted."},"revenue":{"oneOf":[{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},{"type":"number"}],"description":"Decimal serialized as a string or number; values are never currency-converted."},"currency":{"type":["string","null"],"minLength":3,"maxLength":3},"revenue_status":{"type":"string","enum":["resolved","currency_unresolved"]},"trend":{"oneOf":[{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},{"type":"number"}],"description":"Decimal serialized as a string or number; values are never currency-converted."},"created_at":{"type":"string","format":"date-time","example":"2026-09-01T12:00:00Z"},"updated_at":{"type":"string","format":"date-time","example":"2026-09-01T12:00:00Z"}}}},"meta":{"type":"object","properties":{"count":{"type":"integer"},"scope_type":{"type":"string","enum":["user","team"],"description":"Leaderboard slice scope — per-agent or per-team ranking."},"period_type":{"type":"string","enum":["week","month","quarter","year"],"description":"The recurring period a sales goal or leaderboard is measured over."},"period_start":{"type":"string","format":"date","example":"2026-09-01"},"metric":{"type":"string","example":"deal_won","description":"Point-event metric summed in this leaderboard slice: a platform default, an engine-written metric, or a key the account added to its own point_weights setting."},"value_unit":{"type":"string","enum":["points"],"description":"Unit of every leaderboard value in the selected slice."},"units":{"type":"object","properties":{"value":{"type":"string","enum":["points"]},"points":{"type":"string","enum":["points"]},"revenue":{"type":"string","enum":["currency"]}}}}}}},"example":{"payload":[{"id":1,"account_id":1,"scope_type":"user","scope_id":null,"period_type":"week","period_start":"2026-09-01","metric":"deal_won","user_id":null,"team_id":null,"name":null,"avatar_url":null,"rank":1,"value":"1.5","points":"1.5","revenue":null,"currency":null,"revenue_status":"currency_unresolved","trend":"1.5","created_at":"2026-09-01T12:00:00Z","updated_at":"2026-09-01T12:00:00Z"}],"meta":{"count":1,"scope_type":"user","period_type":"week","period_start":"2026-09-01","metric":"deal_won","value_unit":"points","units":{"value":"points","points":"points","revenue":"currency"}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"422":{"description":"A supplied scope, period, date or metric is invalid.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["invalid_leaderboard_slice"],"example":"invalid_leaderboard_slice"}}},"example":{"error":"invalid_leaderboard_slice"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"scope_type","in":"query","required":false,"schema":{"type":"string","enum":["user","team"],"default":"user"},"description":"Rank individual account users or teams."},{"name":"period_type","in":"query","required":false,"schema":{"type":"string","enum":["week","month","quarter","year"],"default":"month"},"description":"Calendar period interpreted in the account's canonical timezone."},{"name":"period_start","in":"query","required":false,"schema":{"type":"string","format":"date"},"description":"Start date of the requested calendar period; defaults to the current period."},{"name":"metric","in":"query","required":false,"schema":{"type":"string","default":"deal_won"},"description":"Point-event metric summed in this slice. The accepted set is closed but not fixed at build time: it is the union of the five platform defaults (deal_won, payment_paid, booking_completed, follow_up_converted, resolution), the metrics the engine itself writes (tier_bonus, contest_reward, team_goal_reward) and any additional key the account added to its own point_weights setting. Anything outside that union returns 422; no free-text metric ever reaches the query. Read the account's sales settings to enumerate its own keys."},{"name":"scope_id","in":"query","required":false,"schema":{"type":"integer","minimum":1},"description":"Optionally narrow the selected slice to one user or team id."}]}},"/api/v1/accounts/{account_id}/sales/badges/{id}/award":{"post":{"tags":["Sales"],"operationId":"auto_post_api_v1_accounts_account_id_sales_badges_id_award","summary":"Award badges","description":"Performs the award operation on the targeted badge resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"key":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"icon":{"type":"string"},"category":{"type":"string"},"manual":{"type":"boolean"},"criteria":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"example":{"id":1,"account_id":1,"key":"sample key","name":"Sample Name","description":"A short description.","icon":"sample icon","category":"sample category","manual":true,"criteria":"sample criteria","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"user_id":{"type":"integer"}}},"example":{"user_id":1}}}}}},"/api/v1/accounts/{account_id}/sales/badges":{"get":{"tags":["Sales"],"operationId":"auto_get_api_v1_accounts_account_id_sales_badges","summary":"List badges","description":"Returns the list of badges visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"key":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"icon":{"type":"string"},"category":{"type":"string"},"manual":{"type":"boolean"},"criteria":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}},"meta":{"type":"object","properties":{"count":{"type":"integer"}}}}},"example":{"payload":[{"id":1,"account_id":1,"key":"sample key","name":"Sample Name","description":"A short description.","icon":"sample icon","category":"sample category","manual":true,"criteria":"sample criteria","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}],"meta":{"count":5}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."}]},"post":{"tags":["Sales"],"operationId":"auto_post_api_v1_accounts_account_id_sales_badges","summary":"Create badges","description":"Creates a new badge from the request payload. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"201":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"key":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"icon":{"type":"string"},"category":{"type":"string"},"manual":{"type":"boolean"},"criteria":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"example":{"id":1,"account_id":1,"key":"sample key","name":"Sample Name","description":"A short description.","icon":"sample icon","category":"sample category","manual":true,"criteria":"sample criteria","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"badge":{"type":"object","properties":{"key":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"icon":{"type":"string"},"category":{"type":"string","enum":["MARKETING","UTILITY","AUTHENTICATION"]},"manual":{"type":"boolean"}}}},"required":["badge"]},"example":{"badge":{"key":"sample key","name":"Sample Name","description":"A short description.","icon":"sample icon","category":"MARKETING","manual":true}}}}}}},"/api/v1/accounts/{account_id}/sales/badges/{id}":{"get":{"tags":["Sales"],"operationId":"auto_get_api_v1_accounts_account_id_sales_badges_id","summary":"Get badges","description":"Returns the badge identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"key":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"icon":{"type":"string"},"category":{"type":"string"},"manual":{"type":"boolean"},"criteria":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"example":{"id":1,"account_id":1,"key":"sample key","name":"Sample Name","description":"A short description.","icon":"sample icon","category":"sample category","manual":true,"criteria":"sample criteria","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]},"patch":{"tags":["Sales"],"operationId":"auto_patch_api_v1_accounts_account_id_sales_badges_id","summary":"Update badges","description":"Updates the badge identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"key":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"icon":{"type":"string"},"category":{"type":"string"},"manual":{"type":"boolean"},"criteria":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"example":{"id":1,"account_id":1,"key":"sample key","name":"Sample Name","description":"A short description.","icon":"sample icon","category":"sample category","manual":true,"criteria":"sample criteria","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"badge":{"type":"object","properties":{"key":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"icon":{"type":"string"},"category":{"type":"string","enum":["MARKETING","UTILITY","AUTHENTICATION"]},"manual":{"type":"boolean"}}}},"required":["badge"]},"example":{"badge":{"key":"sample key","name":"Sample Name","description":"A short description.","icon":"sample icon","category":"MARKETING","manual":true}}}}}},"put":{"tags":["Sales"],"operationId":"auto_put_api_v1_accounts_account_id_sales_badges_id","summary":"Update badges","description":"Updates the badge identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"key":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"icon":{"type":"string"},"category":{"type":"string"},"manual":{"type":"boolean"},"criteria":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"example":{"id":1,"account_id":1,"key":"sample key","name":"Sample Name","description":"A short description.","icon":"sample icon","category":"sample category","manual":true,"criteria":"sample criteria","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"badge":{"type":"object","properties":{"key":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"icon":{"type":"string"},"category":{"type":"string","enum":["MARKETING","UTILITY","AUTHENTICATION"]},"manual":{"type":"boolean"}}}},"required":["badge"]},"example":{"badge":{"key":"sample key","name":"Sample Name","description":"A short description.","icon":"sample icon","category":"MARKETING","manual":true}}}}}},"delete":{"tags":["Sales"],"operationId":"auto_delete_api_v1_accounts_account_id_sales_badges_id","summary":"Delete badges","description":"Deletes the badge identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"204":{"description":"Success (no content)"},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/sales/levels":{"get":{"tags":["Sales"],"operationId":"auto_get_api_v1_accounts_account_id_sales_levels","summary":"List levels","description":"Returns the list of levels visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"name":{"type":"string"},"min_points":{"type":"string"},"max_points":{"type":"string"},"icon":{"type":"string"},"perks":{"type":"string"},"position":{"type":"integer"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}},"meta":{"type":"object","properties":{"count":{"type":"integer"}}}}},"example":{"payload":[{"id":1,"account_id":1,"name":"Sample Name","min_points":"sample min points","max_points":"sample max points","icon":"sample icon","perks":"sample perks","position":1,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}],"meta":{"count":5}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."}]}},"/api/v1/accounts/{account_id}/sales/contests/{contest_id}/entries":{"get":{"tags":["Sales"],"operationId":"auto_get_api_v1_accounts_account_id_sales_contests_contest_id_entries","summary":"List visible contest participants","description":"List visible contest participants. Requires sales_management and account membership; writes require sales_manage or administrator. Owner isolation applies to participant records.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"contest_id":{"type":"integer"},"user_id":{"type":["integer","null"]},"team_id":{"type":["integer","null"]},"rank":{"type":["integer","null"]},"score":{"type":"string","description":"Decimal value serialized without losing precision."},"revenue":{"type":"string","description":"Decimal value serialized without losing precision."},"currency":{"type":["string","null"],"example":"BRL"},"created_at":{"type":"string","format":"date-time"},"name":{"type":["string","null"],"description":"Visible user or team name; loaded only after participant policy scoping."},"rank_status":{"type":"string","enum":["ranked","indeterminate"]},"reached_at":{"type":["string","null"],"format":"date-time","description":"Verified cumulative reach for live scoring only; absent for frozen rows or incomplete history."},"temporal_diagnostics":{"type":"array","items":{"type":"string","enum":["missing_history","opening_balance_unknown","unknown_time","broken_chain","balance_mismatch","owner_reassigned","currency_mismatch","plan_mismatch"]}}}}},"meta":{"type":"object","properties":{"count":{"type":"integer"},"score_kind":{"type":"string","enum":["money","points"]},"currency":{"type":["string","null"]},"revenue_status":{"type":"string","enum":["available","currency_unresolved"]},"ranking_status":{"type":"string","enum":["ranked","indeterminate"]}}}}},"example":{"payload":[{"id":10,"contest_id":3,"user_id":7,"team_id":null,"rank":1,"score":"25.0","revenue":"0.0","currency":null,"created_at":"2026-09-07T12:00:00Z","name":"Example seller","rank_status":"ranked","reached_at":null,"temporal_diagnostics":[]}],"meta":{"count":1,"score_kind":"points","currency":null,"revenue_status":"currency_unresolved","ranking_status":"ranked"}}}}},"401":{"description":"Authentication required"},"404":{"description":"Contest or participant not visible in this account"},"403":{"description":"Feature, membership or permission denied"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"contest_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."}]},"post":{"tags":["Sales"],"operationId":"auto_post_api_v1_accounts_account_id_sales_contests_contest_id_entries","summary":"Enroll one account user or team idempotently","description":"Enroll one account user or team idempotently. Requires sales_management and account membership; writes require sales_manage or administrator. Owner isolation applies to participant records.","security":[{"userApiKey":[]}],"responses":{"201":{"description":"Participant enrolled; an existing identical enrollment is returned without duplication","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"contest_id":{"type":"integer"},"user_id":{"type":["integer","null"]},"team_id":{"type":["integer","null"]},"rank":{"type":["integer","null"]},"score":{"type":"string","description":"Decimal value serialized without losing precision."},"revenue":{"type":"string","description":"Decimal value serialized without losing precision."},"currency":{"type":["string","null"],"example":"BRL"},"created_at":{"type":"string","format":"date-time"},"name":{"type":["string","null"],"description":"Visible user or team name; loaded only after participant policy scoping."},"rank_status":{"type":"string","enum":["ranked","indeterminate"]},"reached_at":{"type":["string","null"],"format":"date-time","description":"Verified cumulative reach for live scoring only; absent for frozen rows or incomplete history."},"temporal_diagnostics":{"type":"array","items":{"type":"string","enum":["missing_history","opening_balance_unknown","unknown_time","broken_chain","balance_mismatch","owner_reassigned","currency_mismatch","plan_mismatch"]}}}},"example":{"id":10,"contest_id":3,"user_id":7,"team_id":null,"rank":1,"score":"25.0","revenue":"0.0","currency":null,"created_at":"2026-09-07T12:00:00Z","name":"Example seller","rank_status":"ranked","reached_at":null,"temporal_diagnostics":[]}}}},"401":{"description":"Authentication required"},"404":{"description":"Contest or participant not visible in this account"},"403":{"description":"Feature, membership or permission denied"},"422":{"description":"Invalid enrollment, closed contest or unavailable temporal scoring source","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["contest_entry"]},"message":{"type":"string"}}},"example":{"error":"contest_entry","message":"contest is closed"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"contest_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["entry"],"properties":{"entry":{"type":"object","description":"Exactly one of user_id or team_id is required. Audience must match the contest.","properties":{"user_id":{"type":["integer","null"]},"team_id":{"type":["integer","null"]}},"additionalProperties":false}}},"example":{"entry":{"user_id":7,"team_id":null}}}}}}},"/api/v1/accounts/{account_id}/sales/contests/{contest_id}/entries/{id}":{"delete":{"tags":["Sales"],"operationId":"auto_delete_api_v1_accounts_account_id_sales_contests_contest_id_entries_id","summary":"Remove a participant from a live contest","description":"Remove a participant from a live contest. Requires sales_management and account membership; writes require sales_manage or administrator. Owner isolation applies to participant records.","security":[{"userApiKey":[]}],"responses":{"204":{"description":"Participant removed"},"401":{"description":"Authentication required"},"404":{"description":"Contest or participant not visible in this account"},"403":{"description":"Feature, membership or permission denied"},"422":{"description":"Invalid enrollment, closed contest or unavailable temporal scoring source","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["contest_entry"]},"message":{"type":"string"}}},"example":{"error":"contest_entry","message":"contest is closed"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"contest_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/sales/contests/{id}/enroll_roster":{"post":{"tags":["Sales"],"operationId":"auto_post_api_v1_accounts_account_id_sales_contests_id_enroll_roster","summary":"Enroll eligible visible active sellers idempotently","description":"Enroll eligible visible active sellers idempotently. Requires sales_management and account membership; writes require sales_manage or administrator. Owner isolation applies to participant records.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"contest_id":{"type":"integer"},"user_id":{"type":["integer","null"]},"team_id":{"type":["integer","null"]},"rank":{"type":["integer","null"]},"score":{"type":"string","description":"Decimal value serialized without losing precision."},"revenue":{"type":"string","description":"Decimal value serialized without losing precision."},"currency":{"type":["string","null"],"example":"BRL"},"created_at":{"type":"string","format":"date-time"},"name":{"type":["string","null"],"description":"Visible user or team name; loaded only after participant policy scoping."},"rank_status":{"type":"string","enum":["ranked","indeterminate"]},"reached_at":{"type":["string","null"],"format":"date-time","description":"Verified cumulative reach for live scoring only; absent for frozen rows or incomplete history."},"temporal_diagnostics":{"type":"array","items":{"type":"string","enum":["missing_history","opening_balance_unknown","unknown_time","broken_chain","balance_mismatch","owner_reassigned","currency_mismatch","plan_mismatch"]}}}}},"meta":{"type":"object","properties":{"count":{"type":"integer"},"score_kind":{"type":"string","enum":["money","points"]},"currency":{"type":["string","null"]},"revenue_status":{"type":"string","enum":["available","currency_unresolved"]},"ranking_status":{"type":"string","enum":["ranked","indeterminate"]}}}}},"example":{"payload":[{"id":10,"contest_id":3,"user_id":7,"team_id":null,"rank":1,"score":"25.0","revenue":"0.0","currency":null,"created_at":"2026-09-07T12:00:00Z","name":"Example seller","rank_status":"ranked","reached_at":null,"temporal_diagnostics":[]}],"meta":{"count":1,"score_kind":"points","currency":null,"revenue_status":"currency_unresolved","ranking_status":"ranked"}}}}},"401":{"description":"Authentication required"},"404":{"description":"Contest or participant not visible in this account"},"403":{"description":"Feature, membership or permission denied"},"422":{"description":"Invalid enrollment, closed contest or unavailable temporal scoring source","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["contest"]},"message":{"type":"string"}}},"example":{"error":"contest","message":"contest is closed"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/sales/contests/{id}/standings":{"get":{"tags":["Sales"],"operationId":"auto_get_api_v1_accounts_account_id_sales_contests_id_standings","summary":"Read current or settled contest standings","description":"Read current or settled contest standings. Requires sales_management and account membership; writes require sales_manage or administrator. Owner isolation applies to participant records. With earliest_reach, incomplete installment recognition history returns 200 with canonical fallback score/revenue, rank null and ranking_status indeterminate. No winner is asserted. temporal_diagnostics explain missing authority without exposing order identities. A manager must explicitly select another criterion before settlement; complete histories use economic effective_at deltas, including refunds, not arrival timestamps. Non-plan legacy scoring remains unchanged.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"contest_id":{"type":"integer"},"user_id":{"type":["integer","null"]},"team_id":{"type":["integer","null"]},"rank":{"type":["integer","null"]},"score":{"type":"string","description":"Decimal value serialized without losing precision."},"revenue":{"type":"string","description":"Decimal value serialized without losing precision."},"currency":{"type":["string","null"],"example":"BRL"},"created_at":{"type":"string","format":"date-time"},"name":{"type":["string","null"],"description":"Visible user or team name; loaded only after participant policy scoping."},"rank_status":{"type":"string","enum":["ranked","indeterminate"]},"reached_at":{"type":["string","null"],"format":"date-time","description":"Verified cumulative reach for live scoring only; absent for frozen rows or incomplete history."},"temporal_diagnostics":{"type":"array","items":{"type":"string","enum":["missing_history","opening_balance_unknown","unknown_time","broken_chain","balance_mismatch","owner_reassigned","currency_mismatch","plan_mismatch"]}}}}},"meta":{"type":"object","properties":{"count":{"type":"integer"},"score_kind":{"type":"string","enum":["money","points"]},"currency":{"type":["string","null"]},"revenue_status":{"type":"string","enum":["available","currency_unresolved"]},"ranking_status":{"type":"string","enum":["ranked","indeterminate"]}}}}},"example":{"payload":[{"id":10,"contest_id":3,"user_id":7,"team_id":null,"rank":1,"score":"25.0","revenue":"0.0","currency":null,"created_at":"2026-09-07T12:00:00Z","name":"Example seller","rank_status":"ranked","reached_at":null,"temporal_diagnostics":[]}],"meta":{"count":1,"score_kind":"points","currency":null,"revenue_status":"currency_unresolved","ranking_status":"ranked"}}}}},"401":{"description":"Authentication required"},"404":{"description":"Contest or participant not visible in this account"},"403":{"description":"Feature, membership or permission denied"},"422":{"description":"Invalid enrollment, closed contest or unavailable temporal scoring source","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["contest"]},"message":{"type":"string"}}},"example":{"error":"contest","message":"contest is closed"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/sales/contests":{"get":{"tags":["Sales"],"operationId":"auto_get_api_v1_accounts_account_id_sales_contests","summary":"List contests","description":"Returns the list of contests visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"name":{"type":"string"},"format":{"type":"string","enum":["challenge","race","tournament"]},"audience":{"type":"string","enum":["individual","team"]},"metric":{"type":"string"},"starts_at":{"type":"string","format":"date-time"},"midpoint_at":{"type":"string","format":"date-time"},"ends_at":{"type":"string","format":"date-time"},"status":{"type":"string","enum":["scheduled","active","ended","cancelled"]},"reward":{"type":"string"},"scope":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}},"meta":{"type":"object","properties":{"count":{"type":"integer"}}}}},"example":{"payload":[{"id":1,"account_id":1,"name":"Sample Name","format":"challenge","audience":"individual","metric":"sample metric","starts_at":"2026-01-15T10:30:00.000Z","midpoint_at":"2026-01-15T10:30:00.000Z","ends_at":"2026-01-15T10:30:00.000Z","status":"scheduled","reward":"sample reward","scope":"sample scope","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}],"meta":{"count":5}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."}]},"post":{"tags":["Sales"],"operationId":"auto_post_api_v1_accounts_account_id_sales_contests","summary":"Create contests","description":"An ended contest using earliest_reach must have a complete, reconciled recognition timeline. Create/update validates scoring in the same transaction without creating rewards or payouts. Incomplete temporal authority returns 422 and rolls back status and scores; editing a previously ended contest cannot bypass this validation. Choosing a different criterion is an explicit manager action.","security":[{"userApiKey":[]}],"responses":{"201":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"name":{"type":"string"},"format":{"type":"string","enum":["challenge","race","tournament"]},"audience":{"type":"string","enum":["individual","team"]},"metric":{"type":"string"},"starts_at":{"type":"string","format":"date-time"},"midpoint_at":{"type":"string","format":"date-time"},"ends_at":{"type":"string","format":"date-time"},"status":{"type":"string","enum":["scheduled","active","ended","cancelled"]},"reward":{"type":"string"},"scope":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"example":{"id":1,"account_id":1,"name":"Sample Name","format":"challenge","audience":"individual","metric":"sample metric","starts_at":"2026-01-15T10:30:00.000Z","midpoint_at":"2026-01-15T10:30:00.000Z","ends_at":"2026-01-15T10:30:00.000Z","status":"scheduled","reward":"sample reward","scope":"sample scope","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"422":{"description":"Invalid contest, including unsupported temporal settlement. No partial status or score write.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["contest"]},"message":{"type":"string"}}},"example":{"error":"contest","message":"earliest_reach requires a complete verified recognition timeline"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"contest":{"type":"object","properties":{"name":{"type":"string"},"format":{"type":"string","enum":["challenge","race","tournament"]},"audience":{"type":"string","enum":["individual","team"]},"metric":{"type":"string"},"starts_at":{"type":"string","format":"date-time"},"midpoint_at":{"type":"string","format":"date-time"},"ends_at":{"type":"string","format":"date-time"},"status":{"type":"string","enum":["scheduled","active","ended","cancelled"]}}}},"required":["contest"]},"example":{"contest":{"name":"Sample Name","format":"challenge","audience":"individual","metric":"sample metric","starts_at":"2026-01-15T10:30:00.000Z","midpoint_at":"2026-01-15T10:30:00.000Z","ends_at":"2026-01-15T10:30:00.000Z","status":"scheduled"}}}}}}},"/api/v1/accounts/{account_id}/sales/contests/{id}":{"get":{"tags":["Sales"],"operationId":"auto_get_api_v1_accounts_account_id_sales_contests_id","summary":"Get contests","description":"Returns the contest identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"name":{"type":"string"},"format":{"type":"string","enum":["challenge","race","tournament"]},"audience":{"type":"string","enum":["individual","team"]},"metric":{"type":"string"},"starts_at":{"type":"string","format":"date-time"},"midpoint_at":{"type":"string","format":"date-time"},"ends_at":{"type":"string","format":"date-time"},"status":{"type":"string","enum":["scheduled","active","ended","cancelled"]},"reward":{"type":"string"},"scope":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"example":{"id":1,"account_id":1,"name":"Sample Name","format":"challenge","audience":"individual","metric":"sample metric","starts_at":"2026-01-15T10:30:00.000Z","midpoint_at":"2026-01-15T10:30:00.000Z","ends_at":"2026-01-15T10:30:00.000Z","status":"scheduled","reward":"sample reward","scope":"sample scope","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]},"patch":{"tags":["Sales"],"operationId":"auto_patch_api_v1_accounts_account_id_sales_contests_id","summary":"Update contests","description":"An ended contest using earliest_reach must have a complete, reconciled recognition timeline. Create/update validates scoring in the same transaction without creating rewards or payouts. Incomplete temporal authority returns 422 and rolls back status and scores; editing a previously ended contest cannot bypass this validation. Choosing a different criterion is an explicit manager action.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"name":{"type":"string"},"format":{"type":"string","enum":["challenge","race","tournament"]},"audience":{"type":"string","enum":["individual","team"]},"metric":{"type":"string"},"starts_at":{"type":"string","format":"date-time"},"midpoint_at":{"type":"string","format":"date-time"},"ends_at":{"type":"string","format":"date-time"},"status":{"type":"string","enum":["scheduled","active","ended","cancelled"]},"reward":{"type":"string"},"scope":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"example":{"id":1,"account_id":1,"name":"Sample Name","format":"challenge","audience":"individual","metric":"sample metric","starts_at":"2026-01-15T10:30:00.000Z","midpoint_at":"2026-01-15T10:30:00.000Z","ends_at":"2026-01-15T10:30:00.000Z","status":"scheduled","reward":"sample reward","scope":"sample scope","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"422":{"description":"Invalid contest, including unsupported temporal settlement. No partial status or score write.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["contest"]},"message":{"type":"string"}}},"example":{"error":"contest","message":"earliest_reach requires a complete verified recognition timeline"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"contest":{"type":"object","properties":{"name":{"type":"string"},"format":{"type":"string","enum":["challenge","race","tournament"]},"audience":{"type":"string","enum":["individual","team"]},"metric":{"type":"string"},"starts_at":{"type":"string","format":"date-time"},"midpoint_at":{"type":"string","format":"date-time"},"ends_at":{"type":"string","format":"date-time"},"status":{"type":"string","enum":["scheduled","active","ended","cancelled"]}}}},"required":["contest"]},"example":{"contest":{"name":"Sample Name","format":"challenge","audience":"individual","metric":"sample metric","starts_at":"2026-01-15T10:30:00.000Z","midpoint_at":"2026-01-15T10:30:00.000Z","ends_at":"2026-01-15T10:30:00.000Z","status":"scheduled"}}}}}},"put":{"tags":["Sales"],"operationId":"auto_put_api_v1_accounts_account_id_sales_contests_id","summary":"Update contests","description":"An ended contest using earliest_reach must have a complete, reconciled recognition timeline. Create/update validates scoring in the same transaction without creating rewards or payouts. Incomplete temporal authority returns 422 and rolls back status and scores; editing a previously ended contest cannot bypass this validation. Choosing a different criterion is an explicit manager action.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"name":{"type":"string"},"format":{"type":"string","enum":["challenge","race","tournament"]},"audience":{"type":"string","enum":["individual","team"]},"metric":{"type":"string"},"starts_at":{"type":"string","format":"date-time"},"midpoint_at":{"type":"string","format":"date-time"},"ends_at":{"type":"string","format":"date-time"},"status":{"type":"string","enum":["scheduled","active","ended","cancelled"]},"reward":{"type":"string"},"scope":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"example":{"id":1,"account_id":1,"name":"Sample Name","format":"challenge","audience":"individual","metric":"sample metric","starts_at":"2026-01-15T10:30:00.000Z","midpoint_at":"2026-01-15T10:30:00.000Z","ends_at":"2026-01-15T10:30:00.000Z","status":"scheduled","reward":"sample reward","scope":"sample scope","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"422":{"description":"Invalid contest, including unsupported temporal settlement. No partial status or score write.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["contest"]},"message":{"type":"string"}}},"example":{"error":"contest","message":"earliest_reach requires a complete verified recognition timeline"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"contest":{"type":"object","properties":{"name":{"type":"string"},"format":{"type":"string","enum":["challenge","race","tournament"]},"audience":{"type":"string","enum":["individual","team"]},"metric":{"type":"string"},"starts_at":{"type":"string","format":"date-time"},"midpoint_at":{"type":"string","format":"date-time"},"ends_at":{"type":"string","format":"date-time"},"status":{"type":"string","enum":["scheduled","active","ended","cancelled"]}}}},"required":["contest"]},"example":{"contest":{"name":"Sample Name","format":"challenge","audience":"individual","metric":"sample metric","starts_at":"2026-01-15T10:30:00.000Z","midpoint_at":"2026-01-15T10:30:00.000Z","ends_at":"2026-01-15T10:30:00.000Z","status":"scheduled"}}}}}},"delete":{"tags":["Sales"],"operationId":"auto_delete_api_v1_accounts_account_id_sales_contests_id","summary":"Delete contests","description":"Deletes the contest identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"204":{"description":"Success (no content)"},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/sales/certifications":{"get":{"tags":["Sales"],"operationId":"auto_get_api_v1_accounts_account_id_sales_certifications","summary":"List certifications","description":"Returns the list of certifications visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"key":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"icon":{"type":"string"},"criteria":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}},"meta":{"type":"object","properties":{"count":{"type":"integer"}}}}},"example":{"payload":[{"id":1,"account_id":1,"key":"sample key","name":"Sample Name","description":"A short description.","icon":"sample icon","criteria":"sample criteria","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}],"meta":{"count":5}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."}]},"post":{"tags":["Sales"],"operationId":"auto_post_api_v1_accounts_account_id_sales_certifications","summary":"Create certifications","description":"Creates a new certification from the request payload. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"201":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"key":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"icon":{"type":"string"},"criteria":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"example":{"id":1,"account_id":1,"key":"sample key","name":"Sample Name","description":"A short description.","icon":"sample icon","criteria":"sample criteria","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"certification":{"type":"object","properties":{"key":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"icon":{"type":"string"}}}},"required":["certification"]},"example":{"certification":{"key":"sample key","name":"Sample Name","description":"A short description.","icon":"sample icon"}}}}}}},"/api/v1/accounts/{account_id}/sales/certifications/{id}":{"get":{"tags":["Sales"],"operationId":"auto_get_api_v1_accounts_account_id_sales_certifications_id","summary":"Get certifications","description":"Returns the certification identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"key":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"icon":{"type":"string"},"criteria":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"example":{"id":1,"account_id":1,"key":"sample key","name":"Sample Name","description":"A short description.","icon":"sample icon","criteria":"sample criteria","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]},"patch":{"tags":["Sales"],"operationId":"auto_patch_api_v1_accounts_account_id_sales_certifications_id","summary":"Update certifications","description":"Updates the certification identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"key":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"icon":{"type":"string"},"criteria":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"example":{"id":1,"account_id":1,"key":"sample key","name":"Sample Name","description":"A short description.","icon":"sample icon","criteria":"sample criteria","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"certification":{"type":"object","properties":{"key":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"icon":{"type":"string"}}}},"required":["certification"]},"example":{"certification":{"key":"sample key","name":"Sample Name","description":"A short description.","icon":"sample icon"}}}}}},"put":{"tags":["Sales"],"operationId":"auto_put_api_v1_accounts_account_id_sales_certifications_id","summary":"Update certifications","description":"Updates the certification identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"key":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"icon":{"type":"string"},"criteria":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"example":{"id":1,"account_id":1,"key":"sample key","name":"Sample Name","description":"A short description.","icon":"sample icon","criteria":"sample criteria","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"certification":{"type":"object","properties":{"key":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"icon":{"type":"string"}}}},"required":["certification"]},"example":{"certification":{"key":"sample key","name":"Sample Name","description":"A short description.","icon":"sample icon"}}}}}},"delete":{"tags":["Sales"],"operationId":"auto_delete_api_v1_accounts_account_id_sales_certifications_id","summary":"Delete certifications","description":"Deletes the certification identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"204":{"description":"Success (no content)"},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/sales/rewards":{"get":{"tags":["Sales"],"operationId":"auto_get_api_v1_accounts_account_id_sales_rewards","summary":"List rewards","description":"Returns the list of rewards visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"image":{"type":"string"},"cost_coins":{"type":"string"},"stock":{"type":"string"},"category":{"type":"string"},"kind":{"type":"string","enum":["physical","voucher","pix","perk"]},"active":{"type":"boolean"},"settings":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}},"meta":{"type":"object","properties":{"count":{"type":"integer"}}}}},"example":{"payload":[{"id":1,"account_id":1,"name":"Sample Name","description":"A short description.","image":"sample image","cost_coins":"sample cost coins","stock":"sample stock","category":"sample category","kind":"physical","active":true,"settings":"sample settings","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}],"meta":{"count":5}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."}]},"post":{"tags":["Sales"],"operationId":"auto_post_api_v1_accounts_account_id_sales_rewards","summary":"Create rewards","description":"Creates a new reward from the request payload. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"201":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"image":{"type":"string"},"cost_coins":{"type":"string"},"stock":{"type":"string"},"category":{"type":"string"},"kind":{"type":"string","enum":["physical","voucher","pix","perk"]},"active":{"type":"boolean"},"settings":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"example":{"id":1,"account_id":1,"name":"Sample Name","description":"A short description.","image":"sample image","cost_coins":"sample cost coins","stock":"sample stock","category":"sample category","kind":"physical","active":true,"settings":"sample settings","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"reward":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"image":{"type":"string"},"cost_coins":{"type":"string"},"stock":{"type":"string"},"category":{"type":"string","enum":["MARKETING","UTILITY","AUTHENTICATION"]},"kind":{"type":"string","enum":["physical","voucher","pix","perk"]},"active":{"type":"boolean"}},"required":["name"]}},"required":["reward"]},"example":{"reward":{"name":"Sample Name","description":"A short description.","image":"sample image","cost_coins":"sample cost coins","stock":"sample stock","category":"MARKETING","kind":"physical","active":true}}}}}}},"/api/v1/accounts/{account_id}/sales/rewards/{id}":{"get":{"tags":["Sales"],"operationId":"auto_get_api_v1_accounts_account_id_sales_rewards_id","summary":"Get rewards","description":"Returns the reward identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"image":{"type":"string"},"cost_coins":{"type":"string"},"stock":{"type":"string"},"category":{"type":"string"},"kind":{"type":"string","enum":["physical","voucher","pix","perk"]},"active":{"type":"boolean"},"settings":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"example":{"id":1,"account_id":1,"name":"Sample Name","description":"A short description.","image":"sample image","cost_coins":"sample cost coins","stock":"sample stock","category":"sample category","kind":"physical","active":true,"settings":"sample settings","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]},"patch":{"tags":["Sales"],"operationId":"auto_patch_api_v1_accounts_account_id_sales_rewards_id","summary":"Update rewards","description":"Updates the reward identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"image":{"type":"string"},"cost_coins":{"type":"string"},"stock":{"type":"string"},"category":{"type":"string"},"kind":{"type":"string","enum":["physical","voucher","pix","perk"]},"active":{"type":"boolean"},"settings":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"example":{"id":1,"account_id":1,"name":"Sample Name","description":"A short description.","image":"sample image","cost_coins":"sample cost coins","stock":"sample stock","category":"sample category","kind":"physical","active":true,"settings":"sample settings","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"reward":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"image":{"type":"string"},"cost_coins":{"type":"string"},"stock":{"type":"string"},"category":{"type":"string","enum":["MARKETING","UTILITY","AUTHENTICATION"]},"kind":{"type":"string","enum":["physical","voucher","pix","perk"]},"active":{"type":"boolean"}}}},"required":["reward"]},"example":{"reward":{"name":"Sample Name","description":"A short description.","image":"sample image","cost_coins":"sample cost coins","stock":"sample stock","category":"MARKETING","kind":"physical","active":true}}}}}},"put":{"tags":["Sales"],"operationId":"auto_put_api_v1_accounts_account_id_sales_rewards_id","summary":"Update rewards","description":"Updates the reward identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"image":{"type":"string"},"cost_coins":{"type":"string"},"stock":{"type":"string"},"category":{"type":"string"},"kind":{"type":"string","enum":["physical","voucher","pix","perk"]},"active":{"type":"boolean"},"settings":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"example":{"id":1,"account_id":1,"name":"Sample Name","description":"A short description.","image":"sample image","cost_coins":"sample cost coins","stock":"sample stock","category":"sample category","kind":"physical","active":true,"settings":"sample settings","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"reward":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"image":{"type":"string"},"cost_coins":{"type":"string"},"stock":{"type":"string"},"category":{"type":"string","enum":["MARKETING","UTILITY","AUTHENTICATION"]},"kind":{"type":"string","enum":["physical","voucher","pix","perk"]},"active":{"type":"boolean"}}}},"required":["reward"]},"example":{"reward":{"name":"Sample Name","description":"A short description.","image":"sample image","cost_coins":"sample cost coins","stock":"sample stock","category":"MARKETING","kind":"physical","active":true}}}}}},"delete":{"tags":["Sales"],"operationId":"auto_delete_api_v1_accounts_account_id_sales_rewards_id","summary":"Delete rewards","description":"Deletes the reward identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"204":{"description":"Success (no content)"},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/sales/redemptions/{id}/approve":{"post":{"tags":["Sales"],"operationId":"auto_post_api_v1_accounts_account_id_sales_redemptions_id_approve","summary":"Approve redemptions","description":"Performs the approve operation on the targeted redemption resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"user_id":{"type":"integer"},"user_name":{"type":["string","null"]},"user_avatar_url":{"type":["string","null"]},"reward_id":{"type":"integer"},"reward_name":{"type":["string","null"]},"cost_coins":{"type":"string"},"status":{"type":"string","enum":["requested","approved","fulfilled","rejected"],"description":"The status of the reward redemption."},"approved_by_id":{"type":"integer"},"fulfilled_at":{"type":"string","format":"date-time"},"notes":{"type":"string"},"payout_ref":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"reward":{"type":"string"}}},"example":{"id":1,"account_id":1,"user_id":1,"user_name":"sample user name","user_avatar_url":"https://example.com/resource","reward_id":1,"reward_name":"sample reward name","cost_coins":"sample cost coins","status":"requested","approved_by_id":1,"fulfilled_at":"2026-01-15T10:30:00.000Z","notes":"sample notes","payout_ref":"sample payout ref","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","reward":"sample reward"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/sales/redemptions/{id}/reject":{"post":{"tags":["Sales"],"operationId":"auto_post_api_v1_accounts_account_id_sales_redemptions_id_reject","summary":"Reject redemptions","description":"Performs the reject operation on the targeted redemption resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"user_id":{"type":"integer"},"user_name":{"type":["string","null"]},"user_avatar_url":{"type":["string","null"]},"reward_id":{"type":"integer"},"reward_name":{"type":["string","null"]},"cost_coins":{"type":"string"},"status":{"type":"string","enum":["requested","approved","fulfilled","rejected"],"description":"The status of the reward redemption."},"approved_by_id":{"type":"integer"},"fulfilled_at":{"type":"string","format":"date-time"},"notes":{"type":"string"},"payout_ref":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"reward":{"type":"string"}}},"example":{"id":1,"account_id":1,"user_id":1,"user_name":"sample user name","user_avatar_url":"https://example.com/resource","reward_id":1,"reward_name":"sample reward name","cost_coins":"sample cost coins","status":"requested","approved_by_id":1,"fulfilled_at":"2026-01-15T10:30:00.000Z","notes":"sample notes","payout_ref":"sample payout ref","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","reward":"sample reward"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"notes":{"type":"string"}}},"example":{"notes":"sample notes"}}}}}},"/api/v1/accounts/{account_id}/sales/redemptions/{id}/fulfill":{"post":{"tags":["Sales"],"operationId":"auto_post_api_v1_accounts_account_id_sales_redemptions_id_fulfill","summary":"Fulfill redemptions","description":"Performs the fulfill operation on the targeted redemption resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"user_id":{"type":"integer"},"user_name":{"type":["string","null"]},"user_avatar_url":{"type":["string","null"]},"reward_id":{"type":"integer"},"reward_name":{"type":["string","null"]},"cost_coins":{"type":"string"},"status":{"type":"string","enum":["requested","approved","fulfilled","rejected"],"description":"The status of the reward redemption."},"approved_by_id":{"type":"integer"},"fulfilled_at":{"type":"string","format":"date-time"},"notes":{"type":"string"},"payout_ref":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"reward":{"type":"string"}}},"example":{"id":1,"account_id":1,"user_id":1,"user_name":"sample user name","user_avatar_url":"https://example.com/resource","reward_id":1,"reward_name":"sample reward name","cost_coins":"sample cost coins","status":"requested","approved_by_id":1,"fulfilled_at":"2026-01-15T10:30:00.000Z","notes":"sample notes","payout_ref":"sample payout ref","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","reward":"sample reward"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"payout_ref":{"type":"string"}}},"example":{"payout_ref":"sample payout ref"}}}}}},"/api/v1/accounts/{account_id}/sales/redemptions":{"get":{"tags":["Sales"],"operationId":"auto_get_api_v1_accounts_account_id_sales_redemptions","summary":"List redemptions","description":"Returns the list of redemptions visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"user_id":{"type":"integer"},"user_name":{"type":["string","null"]},"user_avatar_url":{"type":["string","null"]},"reward_id":{"type":"integer"},"reward_name":{"type":["string","null"]},"cost_coins":{"type":"string"},"status":{"type":"string","enum":["requested","approved","fulfilled","rejected"],"description":"The status of the reward redemption."},"approved_by_id":{"type":"integer"},"fulfilled_at":{"type":"string","format":"date-time"},"notes":{"type":"string"},"payout_ref":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"reward":{"type":"string"}}}},"meta":{"type":"object","properties":{"count":{"type":"integer"},"current_page":{"type":"string"},"total_pages":{"type":"string"},"per_page":{"type":"string"},"has_more":{"type":"boolean"}}}}},"example":{"payload":[{"id":1,"account_id":1,"user_id":1,"user_name":"sample user name","user_avatar_url":"https://example.com/resource","reward_id":1,"reward_name":"sample reward name","cost_coins":"sample cost coins","status":"requested","approved_by_id":1,"fulfilled_at":"2026-01-15T10:30:00.000Z","notes":"sample notes","payout_ref":"sample payout ref","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","reward":"sample reward"}],"meta":{"count":5,"current_page":"sample current page","total_pages":"sample total pages","per_page":"sample per page","has_more":true}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."}]},"post":{"tags":["Sales"],"operationId":"auto_post_api_v1_accounts_account_id_sales_redemptions","summary":"Create redemptions","description":"Creates a new redemption from the request payload. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"201":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"user_id":{"type":"integer"},"user_name":{"type":["string","null"]},"user_avatar_url":{"type":["string","null"]},"reward_id":{"type":"integer"},"reward_name":{"type":["string","null"]},"cost_coins":{"type":"string"},"status":{"type":"string","enum":["requested","approved","fulfilled","rejected"],"description":"The status of the reward redemption."},"approved_by_id":{"type":"integer"},"fulfilled_at":{"type":"string","format":"date-time"},"notes":{"type":"string"},"payout_ref":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"reward":{"type":"string"}}},"example":{"id":1,"account_id":1,"user_id":1,"user_name":"sample user name","user_avatar_url":"https://example.com/resource","reward_id":1,"reward_name":"sample reward name","cost_coins":"sample cost coins","status":"requested","approved_by_id":1,"fulfilled_at":"2026-01-15T10:30:00.000Z","notes":"sample notes","payout_ref":"sample payout ref","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","reward":"sample reward"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"reward_id":{"type":"integer"}}},"example":{"reward_id":1}}}}}},"/api/v1/accounts/{account_id}/sales/redemptions/{id}":{"get":{"tags":["Sales"],"operationId":"auto_get_api_v1_accounts_account_id_sales_redemptions_id","summary":"Get redemptions","description":"Returns the redemption identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"user_id":{"type":"integer"},"user_name":{"type":["string","null"]},"user_avatar_url":{"type":["string","null"]},"reward_id":{"type":"integer"},"reward_name":{"type":["string","null"]},"cost_coins":{"type":"string"},"status":{"type":"string","enum":["requested","approved","fulfilled","rejected"],"description":"The status of the reward redemption."},"approved_by_id":{"type":"integer"},"fulfilled_at":{"type":"string","format":"date-time"},"notes":{"type":"string"},"payout_ref":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"reward":{"type":"string"}}},"example":{"id":1,"account_id":1,"user_id":1,"user_name":"sample user name","user_avatar_url":"https://example.com/resource","reward_id":1,"reward_name":"sample reward name","cost_coins":"sample cost coins","status":"requested","approved_by_id":1,"fulfilled_at":"2026-01-15T10:30:00.000Z","notes":"sample notes","payout_ref":"sample payout ref","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","reward":"sample reward"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"reward_id","in":"query","required":true,"description":"Reward being redeemed — must be active and in stock.","schema":{"type":"integer"},"example":12}]}},"/api/v1/accounts/{account_id}/sales/coins":{"get":{"tags":["Sales"],"operationId":"auto_get_api_v1_accounts_account_id_sales_coins","summary":"List coins","description":"Returns the list of coins visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"balance":{"type":"string"},"user_id":{"type":"integer"},"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"user_id":{"type":"integer"},"delta":{"type":"string"},"reason":{"type":"string"},"source_type":{"type":"string"},"source_id":{"type":"integer"},"balance_after":{"type":"string"},"created_at":{"type":"string","format":"date-time"}}}},"meta":{"type":"object","properties":{"count":{"type":"integer"},"current_page":{"type":"string"},"total_pages":{"type":"string"},"per_page":{"type":"string"},"has_more":{"type":"boolean"}}}}},"example":{"balance":"sample balance","user_id":1,"payload":[{"id":1,"account_id":1,"user_id":1,"delta":"sample delta","reason":"Sample reason.","source_type":"sample source type","source_id":1,"balance_after":"sample balance after","created_at":"2026-01-15T10:30:00.000Z"}],"meta":{"count":5,"current_page":"sample current page","total_pages":"sample total pages","per_page":"sample per page","has_more":true}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."}]}},"/api/v1/accounts/{account_id}/sales/human_tools/execute":{"post":{"tags":["Sales"],"operationId":"auto_post_api_v1_accounts_account_id_sales_human_tools_execute","summary":"Execute a signed human Sales action","description":"Delegates four native Sales tools using a short-lived capability issued to an authenticated human for the account, action and canonical arguments. Application API authentication alone never authorizes the action. Current membership, resource policies and owner visibility are checked again when executing. Recognition and decision replay require the Maestro execution receipt.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Policy-checked native tool result.","content":{"application/json":{"schema":{"type":"object","required":["result"],"properties":{"result":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"deal_id":{"type":"integer"},"title":{"type":"string"},"status":{"type":"string","enum":["pending","approved","rejected","cancelled"]},"can_approve":{"type":"boolean"}}}},{"type":"object","properties":{"id":{"type":"integer"},"status":{"type":"string","enum":["approved","rejected"]}}}]}}},"example":{"result":"sample result"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Resource is absent or outside the human actor's visible scope."},"403":{"description":"Missing or invalid human capability, or insufficient current human permission."},"422":{"description":"Invalid arguments or business validation failure."},"409":{"description":"Human action is running or its previous outcome is unknown; do not retry the effect."},"503":{"description":"Human capability or execution receipt storage is unavailable; action is not confirmed."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"in":"header","name":"X-Maestro-Human-Capability","required":true,"schema":{"type":"string","writeOnly":true},"description":"Runtime-only signed capability; never supplied by a model or logged."},{"in":"header","name":"X-Maestro-Human-Request-Id","required":true,"schema":{"type":"string"}},{"in":"header","name":"X-Maestro-Human-Conversation-Id","required":false,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["tool","arguments"],"additionalProperties":false,"properties":{"tool":{"type":"string","enum":["sales_get_leaderboard","sales_recognize","sales_list_deal_approvals","sales_decide_deal_approval"]},"arguments":{"type":"object","description":"Only the selected action's arguments are accepted. Leaderboard accepts limit; approval listing accepts status; decision accepts approval_id, decision and note; recognition accepts message, kind, user_id, points and currency. Actor, capability, account and request identity are never accepted here.","properties":{"limit":{"oneOf":[{"type":"integer"},{"type":"string"}]},"status":{"type":"string","enum":["pending","approved","rejected","cancelled"]},"approval_id":{"oneOf":[{"type":"integer"},{"type":"string"}]},"decision":{"type":"string","enum":["approve","reject"]},"note":{"type":["string","null"],"description":"Nonblank justification is mandatory for rejection."},"message":{"type":"string"},"kind":{"type":"string","enum":["win","meta","super_meta","mega_meta"]},"user_id":{"oneOf":[{"type":"integer"},{"type":"string"}]},"points":{"type":["string","null"],"description":"Display-only decimal points; never awards ledger points."},"currency":{"type":["string","null"],"pattern":"^[A-Z]{3}$"}},"additionalProperties":false}}},"example":{"tool":"sales_list_deal_approvals","arguments":{"status":"pending","limit":1,"approval_id":1,"decision":"approve","note":"Sample note.","message":"Sample message text.","kind":"win","user_id":1,"points":"sample points","currency":"BRL"}}}}}}},"/api/v1/accounts/{account_id}/sales/deal_approvals/{id}/approve":{"post":{"tags":["Sales"],"operationId":"auto_post_api_v1_accounts_account_id_sales_deal_approvals_id_approve","summary":"Approve deal approvals","description":"Performs the approve operation on the targeted deal approval resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"deal_approval":{"type":"object","properties":{"extract":{"type":"string"},"item":{"type":"object","properties":{"extract":{"type":"string"}}},"requested_by":{"type":"object","properties":{"extract":{"type":"string"},"null":{"type":"string"}}},"current_close":{"type":"string"},"stale":{"type":"boolean"},"can_approve":{"type":"boolean"},"can_reject":{"type":"boolean"},"can_cancel":{"type":"boolean"}}}}},"example":{"deal_approval":{"extract":"sample extract","item":{"extract":"sample extract"},"requested_by":{"extract":"sample extract","null":"sample null"},"current_close":"sample current close","stale":true,"can_approve":true,"can_reject":true,"can_cancel":true}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"note":{"type":"string"}}},"example":{"note":"Sample note."}}}}}},"/api/v1/accounts/{account_id}/sales/deal_approvals/{id}/reject":{"post":{"tags":["Sales"],"operationId":"auto_post_api_v1_accounts_account_id_sales_deal_approvals_id_reject","summary":"Reject deal approvals","description":"Performs the reject operation on the targeted deal approval resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"deal_approval":{"type":"object","properties":{"extract":{"type":"string"},"item":{"type":"object","properties":{"extract":{"type":"string"}}},"requested_by":{"type":"object","properties":{"extract":{"type":"string"},"null":{"type":"string"}}},"current_close":{"type":"string"},"stale":{"type":"boolean"},"can_approve":{"type":"boolean"},"can_reject":{"type":"boolean"},"can_cancel":{"type":"boolean"}}}}},"example":{"deal_approval":{"extract":"sample extract","item":{"extract":"sample extract"},"requested_by":{"extract":"sample extract","null":"sample null"},"current_close":"sample current close","stale":true,"can_approve":true,"can_reject":true,"can_cancel":true}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"note":{"type":"string"}}},"example":{"note":"Sample note."}}}}}},"/api/v1/accounts/{account_id}/sales/deal_approvals/{id}/cancel":{"post":{"tags":["Sales"],"operationId":"auto_post_api_v1_accounts_account_id_sales_deal_approvals_id_cancel","summary":"Cancel deal approvals","description":"Performs the cancel operation on the targeted deal approval resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"deal_approval":{"type":"object","properties":{"extract":{"type":"string"},"item":{"type":"object","properties":{"extract":{"type":"string"}}},"requested_by":{"type":"object","properties":{"extract":{"type":"string"},"null":{"type":"string"}}},"current_close":{"type":"string"},"stale":{"type":"boolean"},"can_approve":{"type":"boolean"},"can_reject":{"type":"boolean"},"can_cancel":{"type":"boolean"}}}}},"example":{"deal_approval":{"extract":"sample extract","item":{"extract":"sample extract"},"requested_by":{"extract":"sample extract","null":"sample null"},"current_close":"sample current close","stale":true,"can_approve":true,"can_reject":true,"can_cancel":true}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"note":{"type":"string"}}},"example":{"note":"Sample note."}}}}}},"/api/v1/accounts/{account_id}/sales/deal_approvals":{"get":{"tags":["Sales"],"operationId":"auto_get_api_v1_accounts_account_id_sales_deal_approvals","summary":"List visible commercial approvals","description":"Returns the list of deal approvals visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Visibility-scoped queue. Review capability is independent of the active search and does not authorize every record.","content":{"application/json":{"schema":{"type":"object","properties":{"meta":{"type":"object","properties":{"can_review_deal_approvals":{"type":"boolean"},"total_count":{"type":"integer"},"current_page":{"type":"integer"},"total_pages":{"type":"integer"}}},"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"crm_item_id":{"type":"integer"},"status":{"type":"string","enum":["pending","approved","rejected","cancelled"]},"invalidated_reason":{"type":["string","null"],"enum":["expired","terms_changed","lost","archived","owner_changed",null]},"stale":{"type":"boolean"},"can_approve":{"type":"boolean"},"can_reject":{"type":"boolean"},"can_cancel":{"type":"boolean"},"justification":{"type":["string","null"]},"requested_close":{"type":"object","description":"Frozen requested commercial terms and ownership, including stage and closing time; decimal values use their JSON string representation.","additionalProperties":true},"evaluation":{"type":"object","description":"Versioned policy evaluation snapshot with breaches, observed state and any subsequent clearance or stale-state evidence.","additionalProperties":true},"current_close":{"type":"object","description":"Current commercial terms and ownership for comparison with the frozen requested close; decimal values use their JSON string representation.","additionalProperties":true}}}}}},"example":{"meta":{"can_review_deal_approvals":true,"total_count":5,"current_page":1,"total_pages":1},"payload":[{"id":1,"crm_item_id":1,"status":"pending","invalidated_reason":"expired","stale":true,"can_approve":true,"can_reject":true,"can_cancel":true,"justification":"sample justification","requested_close":{},"evaluation":{},"current_close":{}}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"422":{"description":"Invalid list filter.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["deal_approval"]},"code":{"type":"string","enum":["invalid_status","invalid_invalidated_reason","invalid_query","invalid_mine"]},"diff":{"type":["object","null"],"description":"Changed observed-state keys mapped to before and after values; empty when the error has no state comparison.","additionalProperties":true}}},"example":{"error":"deal_approval","code":"invalid_status","diff":{}}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"mine","in":"query","description":"Restrict to the authenticated requester before pagination.","schema":{"type":"boolean"}},{"name":"status","in":"query","schema":{"type":"string","enum":["pending","approved","rejected","cancelled"]}},{"name":"invalidated_reason","in":"query","schema":{"type":"string","enum":["expired","terms_changed","lost","archived","owner_changed"]}},{"name":"q","in":"query","description":"Case-insensitive literal search of deal title, requester name and justification.","schema":{"type":"string"}},{"name":"page","in":"query","schema":{"type":"integer","minimum":1}}]},"post":{"tags":["Sales"],"operationId":"auto_post_api_v1_accounts_account_id_sales_deal_approvals","summary":"Create deal approvals","description":"Creates a new deal approval from the request payload. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"deal_approval":{"type":"object","properties":{"extract":{"type":"string"},"item":{"type":"object","properties":{"extract":{"type":"string"}}},"requested_by":{"type":"object","properties":{"extract":{"type":"string"},"null":{"type":"string"}}},"current_close":{"type":"string"},"stale":{"type":"boolean"},"can_approve":{"type":"boolean"},"can_reject":{"type":"boolean"},"can_cancel":{"type":"boolean"}}}}},"example":{"deal_approval":{"extract":"sample extract","item":{"extract":"sample extract"},"requested_by":{"extract":"sample extract","null":"sample null"},"current_close":"sample current close","stale":true,"can_approve":true,"can_reject":true,"can_cancel":true}}}}},"202":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"deal_approval":{"type":"object","properties":{"extract":{"type":"string"},"item":{"type":"object","properties":{"extract":{"type":"string"}}},"requested_by":{"type":"object","properties":{"extract":{"type":"string"},"null":{"type":"string"}}},"current_close":{"type":"string"},"stale":{"type":"boolean"},"can_approve":{"type":"boolean"},"can_reject":{"type":"boolean"},"can_cancel":{"type":"boolean"}}}}},"example":{"deal_approval":{"extract":"sample extract","item":{"extract":"sample extract"},"requested_by":{"extract":"sample extract","null":"sample null"},"current_close":"sample current close","stale":true,"can_approve":true,"can_reject":true,"can_cancel":true}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"crm_item_id":{"type":"integer"},"closed_at":{"type":"string","format":"date-time"},"reason":{"type":"string","enum":["","client_revocation","refresh_token_reuse","subject_revoked","account_admin_security_review","account_admin_access_removed","account_admin_client_decommissioned","account_admin_incident_response","operator_security_review","operator_access_removed","operator_client_decommissioned","operator_incident_response","operator_credential_provisioning","operator_credential_rotation","operator_approval_required","operator_approval_approved","operator_approval_rejected","operator_approval_execution_failed","operator_approval_response_delivery_failed","operator_approval_execution_unknown","operator_approval_execution_started","operator_approval_execution_succeeded","operator_approval_execution_rejected","operator_approval_confirmed_succeeded","operator_approval_confirmed_not_applied","operator_delegation_profile_changed","operator_delegation_profile_revoked","mfa_disabled"]},"justification":{"type":"string"}}},"example":{"crm_item_id":1,"closed_at":"2026-01-15T10:30:00.000Z","reason":"","justification":"sample justification"}}}}}},"/api/v1/accounts/{account_id}/sales/deal_approvals/{id}":{"get":{"tags":["Sales"],"operationId":"auto_get_api_v1_accounts_account_id_sales_deal_approvals_id","summary":"Get deal approvals","description":"Returns the deal approval identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"deal_approval":{"type":"object","properties":{"extract":{"type":"string"},"item":{"type":"object","properties":{"extract":{"type":"string"}}},"requested_by":{"type":"object","properties":{"extract":{"type":"string"},"null":{"type":"string"}}},"current_close":{"type":"string"},"stale":{"type":"boolean"},"can_approve":{"type":"boolean"},"can_reject":{"type":"boolean"},"can_cancel":{"type":"boolean"}}}}},"example":{"deal_approval":{"extract":"sample extract","item":{"extract":"sample extract"},"requested_by":{"extract":"sample extract","null":"sample null"},"current_close":"sample current close","stale":true,"can_approve":true,"can_reject":true,"can_cancel":true}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/sales/commission_plans":{"get":{"tags":["Sales"],"operationId":"auto_get_api_v1_accounts_account_id_sales_commission_plans","summary":"List commission plans","description":"Returns the list of commission plans visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"name":{"type":"string"},"basis":{"type":"string","enum":["paid","won"]},"credit_mode":{"type":"string","enum":["single","split"]},"effective_from":{"type":"string"},"effective_to":{"type":"string"},"archived_at":{"type":"string","format":"date-time"},"settings":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"components":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"kind":{"type":"string","enum":["rate","tier","accelerator","spif","cap","floor"],"description":"The kind of commission-plan component."},"position":{"type":"integer"},"rate_table":{"type":"string"},"product_filter":{"type":"string"},"conditions":{"type":"string"},"basis":{"type":"string","enum":["paid","won"]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}},"assignments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"payee_id":{"type":"integer"},"period_start":{"type":"string"},"period_end":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}}}},"meta":{"type":"object","properties":{"count":{"type":"integer"}}}}},"example":{"payload":[{"id":1,"account_id":1,"name":"Sample Name","basis":"paid","credit_mode":"single","effective_from":"sample effective from","effective_to":"sample effective to","archived_at":"2026-01-15T10:30:00.000Z","settings":"sample settings","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","components":[{"id":1,"kind":"rate","position":1,"rate_table":"sample rate table","product_filter":"sample product filter","conditions":"sample conditions","basis":"paid","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}],"assignments":[{"id":1,"payee_id":1,"period_start":"sample period start","period_end":"sample period end","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}]}],"meta":{"count":5}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"archived","in":"query","required":false,"description":"Any non-empty value also returns archived plans. Managers only — for other roles the parameter is ignored and archived plans stay hidden.","schema":{"type":"string"},"example":"true"}]},"post":{"tags":["Sales"],"operationId":"auto_post_api_v1_accounts_account_id_sales_commission_plans","summary":"Create commission plans","description":"Creates a new commission plan from the request payload. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"201":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"name":{"type":"string"},"basis":{"type":"string","enum":["paid","won"]},"credit_mode":{"type":"string","enum":["single","split"]},"effective_from":{"type":"string"},"effective_to":{"type":"string"},"archived_at":{"type":"string","format":"date-time"},"settings":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"components":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"kind":{"type":"string","enum":["rate","tier","accelerator","spif","cap","floor"],"description":"The kind of commission-plan component."},"position":{"type":"integer"},"rate_table":{"type":"string"},"product_filter":{"type":"string"},"conditions":{"type":"string"},"basis":{"type":"string","enum":["paid","won"]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}},"assignments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"payee_id":{"type":"integer"},"period_start":{"type":"string"},"period_end":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}}},"example":{"id":1,"account_id":1,"name":"Sample Name","basis":"paid","credit_mode":"single","effective_from":"sample effective from","effective_to":"sample effective to","archived_at":"2026-01-15T10:30:00.000Z","settings":"sample settings","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","components":[{"id":1,"kind":"rate","position":1,"rate_table":"sample rate table","product_filter":"sample product filter","conditions":"sample conditions","basis":"paid","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}],"assignments":[{"id":1,"payee_id":1,"period_start":"sample period start","period_end":"sample period end","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"422":{"description":"Validation failed, or the request asked for a credit_mode this platform does not support.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["credit_mode/unsupported"],"description":"Present only on the credit_mode refusal. `credit_mode: \"split\"` is stored by legacy plans and remains readable, but no computation branch implements it: the accrual ledger credits exactly one payee per source, so a plan created as \"split\" would pay a single person while its name promised otherwise. Creating one is refused.","example":"credit_mode/unsupported"},"errors":{"type":"array","items":{"type":"string"},"description":"Human-readable messages, from the model validations or from the refusal.","example":["Name can't be blank"]}}},"example":{"error":"credit_mode/unsupported","errors":["Name can't be blank"]}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"commission_plan":{"type":"object","properties":{"name":{"type":"string"},"basis":{"type":"string","enum":["paid","won"]},"credit_mode":{"type":"string","enum":["single","split"]},"effective_from":{"type":"string"},"effective_to":{"type":"string"}},"required":["name"]}},"required":["commission_plan"]},"example":{"commission_plan":{"name":"Sample Name","basis":"paid","credit_mode":"single","effective_from":"sample effective from","effective_to":"sample effective to"}}}}}}},"/api/v1/accounts/{account_id}/sales/commission_plans/{id}":{"get":{"tags":["Sales"],"operationId":"auto_get_api_v1_accounts_account_id_sales_commission_plans_id","summary":"Get commission plans","description":"Returns the commission plan identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"name":{"type":"string"},"basis":{"type":"string","enum":["paid","won"]},"credit_mode":{"type":"string","enum":["single","split"]},"effective_from":{"type":"string"},"effective_to":{"type":"string"},"archived_at":{"type":"string","format":"date-time"},"settings":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"components":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"kind":{"type":"string","enum":["rate","tier","accelerator","spif","cap","floor"],"description":"The kind of commission-plan component."},"position":{"type":"integer"},"rate_table":{"type":"string"},"product_filter":{"type":"string"},"conditions":{"type":"string"},"basis":{"type":"string","enum":["paid","won"]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}},"assignments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"payee_id":{"type":"integer"},"period_start":{"type":"string"},"period_end":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}}},"example":{"id":1,"account_id":1,"name":"Sample Name","basis":"paid","credit_mode":"single","effective_from":"sample effective from","effective_to":"sample effective to","archived_at":"2026-01-15T10:30:00.000Z","settings":"sample settings","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","components":[{"id":1,"kind":"rate","position":1,"rate_table":"sample rate table","product_filter":"sample product filter","conditions":"sample conditions","basis":"paid","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}],"assignments":[{"id":1,"payee_id":1,"period_start":"sample period start","period_end":"sample period end","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]},"patch":{"tags":["Sales"],"operationId":"auto_patch_api_v1_accounts_account_id_sales_commission_plans_id","summary":"Update commission plans","description":"Updates the commission plan identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"name":{"type":"string"},"basis":{"type":"string","enum":["paid","won"]},"credit_mode":{"type":"string","enum":["single","split"]},"effective_from":{"type":"string"},"effective_to":{"type":"string"},"archived_at":{"type":"string","format":"date-time"},"settings":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"components":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"kind":{"type":"string","enum":["rate","tier","accelerator","spif","cap","floor"],"description":"The kind of commission-plan component."},"position":{"type":"integer"},"rate_table":{"type":"string"},"product_filter":{"type":"string"},"conditions":{"type":"string"},"basis":{"type":"string","enum":["paid","won"]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}},"assignments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"payee_id":{"type":"integer"},"period_start":{"type":"string"},"period_end":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}}},"example":{"id":1,"account_id":1,"name":"Sample Name","basis":"paid","credit_mode":"single","effective_from":"sample effective from","effective_to":"sample effective to","archived_at":"2026-01-15T10:30:00.000Z","settings":"sample settings","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","components":[{"id":1,"kind":"rate","position":1,"rate_table":"sample rate table","product_filter":"sample product filter","conditions":"sample conditions","basis":"paid","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}],"assignments":[{"id":1,"payee_id":1,"period_start":"sample period start","period_end":"sample period end","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"422":{"description":"Validation failed, or the request tried to switch the plan to an unsupported credit_mode.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["credit_mode/unsupported"],"description":"Only the TRANSITION to \"split\" is refused. A plan that already stores \"split\" stays fully editable — including re-asserting the same value — so an unrelated edit (a rename, an extra assignment) never fails on a field the manager did not change.","example":"credit_mode/unsupported"},"errors":{"type":"array","items":{"type":"string"},"description":"Human-readable messages, from the model validations or from the refusal.","example":["Name can't be blank"]}}},"example":{"error":"credit_mode/unsupported","errors":["Name can't be blank"]}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"commission_plan":{"type":"object","properties":{"name":{"type":"string"},"basis":{"type":"string","enum":["paid","won"]},"credit_mode":{"type":"string","enum":["single","split"]},"effective_from":{"type":"string"},"effective_to":{"type":"string"}}}},"required":["commission_plan"]},"example":{"commission_plan":{"name":"Sample Name","basis":"paid","credit_mode":"single","effective_from":"sample effective from","effective_to":"sample effective to"}}}}}},"put":{"tags":["Sales"],"operationId":"auto_put_api_v1_accounts_account_id_sales_commission_plans_id","summary":"Update commission plans","description":"Updates the commission plan identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"name":{"type":"string"},"basis":{"type":"string","enum":["paid","won"]},"credit_mode":{"type":"string","enum":["single","split"]},"effective_from":{"type":"string"},"effective_to":{"type":"string"},"archived_at":{"type":"string","format":"date-time"},"settings":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"components":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"kind":{"type":"string","enum":["rate","tier","accelerator","spif","cap","floor"],"description":"The kind of commission-plan component."},"position":{"type":"integer"},"rate_table":{"type":"string"},"product_filter":{"type":"string"},"conditions":{"type":"string"},"basis":{"type":"string","enum":["paid","won"]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}},"assignments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"payee_id":{"type":"integer"},"period_start":{"type":"string"},"period_end":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}}},"example":{"id":1,"account_id":1,"name":"Sample Name","basis":"paid","credit_mode":"single","effective_from":"sample effective from","effective_to":"sample effective to","archived_at":"2026-01-15T10:30:00.000Z","settings":"sample settings","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","components":[{"id":1,"kind":"rate","position":1,"rate_table":"sample rate table","product_filter":"sample product filter","conditions":"sample conditions","basis":"paid","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}],"assignments":[{"id":1,"payee_id":1,"period_start":"sample period start","period_end":"sample period end","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"422":{"description":"Validation failed, or the request tried to switch the plan to an unsupported credit_mode.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["credit_mode/unsupported"],"description":"Only the TRANSITION to \"split\" is refused. A plan that already stores \"split\" stays fully editable — including re-asserting the same value — so an unrelated edit (a rename, an extra assignment) never fails on a field the manager did not change.","example":"credit_mode/unsupported"},"errors":{"type":"array","items":{"type":"string"},"description":"Human-readable messages, from the model validations or from the refusal.","example":["Name can't be blank"]}}},"example":{"error":"credit_mode/unsupported","errors":["Name can't be blank"]}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"commission_plan":{"type":"object","properties":{"name":{"type":"string"},"basis":{"type":"string","enum":["paid","won"]},"credit_mode":{"type":"string","enum":["single","split"]},"effective_from":{"type":"string"},"effective_to":{"type":"string"}}}},"required":["commission_plan"]},"example":{"commission_plan":{"name":"Sample Name","basis":"paid","credit_mode":"single","effective_from":"sample effective from","effective_to":"sample effective to"}}}}}},"delete":{"tags":["Sales"],"operationId":"auto_delete_api_v1_accounts_account_id_sales_commission_plans_id","summary":"Delete commission plans","description":"Deletes the commission plan identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"204":{"description":"Success (no content)"},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/sales/commission_statements/{id}/approve":{"post":{"tags":["Sales"],"operationId":"auto_post_api_v1_accounts_account_id_sales_commission_statements_id_approve","summary":"Approve commission statements","description":"Performs the approve operation on the targeted commission statement resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/sales_commission_statement"},"example":{"id":77,"account_id":1,"payee_id":7,"payee_type":"User","payee_name":"Ana Vendedora","currency":"BRL","period_start":"2026-07-01","period_end":"2026-07-31","status":"open","total_accrued":1240.5,"total_approved":0.0,"total_paid":0.0,"approved_by_id":null,"approved_at":null,"created_at":"2026-07-31T23:00:00Z","updated_at":"2026-07-31T23:00:00Z","commission_lines":[{"key":"deal:44","kind":"deal","title":"Assinatura anual","crm_item_id":44,"contact_id":19,"organization_id":8,"order_ids":[101,102],"payments_charge_ids":[201,202],"payment_count":2,"event_count":2,"gross_amount":997.0,"commission_amount":99.7,"effective_rate":0.1,"accrued_at":"2026-09-05T12:00:00Z","has_adjustments":false,"accrual_ids":[501,502]}],"accruals":[{"id":501,"source_type":"Payments::Charge","source_label":"Cobrança","source_id":8,"gross_amount":500.0,"rate_applied":0.08,"commission_amount":40.0}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/sales/commission_statements/{id}/mark_paid":{"post":{"tags":["Sales"],"operationId":"auto_post_api_v1_accounts_account_id_sales_commission_statements_id_mark_paid","summary":"Mark paid commission statements","description":"Performs the mark paid operation on the targeted commission statement resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/sales_commission_statement"},"example":{"id":77,"account_id":1,"payee_id":7,"payee_type":"User","payee_name":"Ana Vendedora","currency":"BRL","period_start":"2026-07-01","period_end":"2026-07-31","status":"open","total_accrued":1240.5,"total_approved":0.0,"total_paid":0.0,"approved_by_id":null,"approved_at":null,"created_at":"2026-07-31T23:00:00Z","updated_at":"2026-07-31T23:00:00Z","commission_lines":[{"key":"deal:44","kind":"deal","title":"Assinatura anual","crm_item_id":44,"contact_id":19,"organization_id":8,"order_ids":[101,102],"payments_charge_ids":[201,202],"payment_count":2,"event_count":2,"gross_amount":997.0,"commission_amount":99.7,"effective_rate":0.1,"accrued_at":"2026-09-05T12:00:00Z","has_adjustments":false,"accrual_ids":[501,502]}],"accruals":[{"id":501,"source_type":"Payments::Charge","source_label":"Cobrança","source_id":8,"gross_amount":500.0,"rate_applied":0.08,"commission_amount":40.0}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/sales/commission_statements":{"get":{"tags":["Sales"],"operationId":"auto_get_api_v1_accounts_account_id_sales_commission_statements","summary":"List commission statements","description":"One page of period commission statements. Agents see only their own; managers (admin or the sales-management permission) see all and may narrow by payee_id, payee_type or status. meta.count and meta.totals (Σ accrued/approved/paid) are over the WHOLE filtered set, not the page. Spec-078 — a statement's identity includes its payee_type: agent #5 and affiliate #5 are DIFFERENT payees, so every scope carries the discriminator and the per-currency breakdown in meta.totals_by_currency is the honest figure for a multi-currency account (BRL + USD is not a payable number). The scalar meta.totals stays for back-compat with single-currency accounts.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"One page of statements with a whole-set count, pagination meta and commission Σ totals.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"$ref":"#/components/schemas/sales_commission_statement"}},"meta":{"type":"object","properties":{"count":{"type":"integer","description":"Total statements in the WHOLE filtered set (not the page).","example":42},"current_page":{"type":"integer","example":1},"total_pages":{"type":"integer","example":2},"per_page":{"type":"integer","description":"Effective page size (capped at 100).","example":25},"has_more":{"type":"boolean","description":"Whether another page exists after this one.","example":true},"totals":{"type":"object","description":"Σ over the WHOLE filtered set (not the page) — authoritative commission counters. Currency-blind; read totals_by_currency on a multi-currency account.","properties":{"accrued":{"type":"number","example":5280.0},"approved":{"type":"number","example":1200.0},"paid":{"type":"number","example":900.0}}},"totals_by_currency":{"type":"array","description":"The same sums split per currency — the only payable figures when an account bills in more than one. A statement predating the currency column reports under 'unspecified'.","items":{"type":"object","properties":{"currency":{"type":"string","example":"BRL"},"accrued":{"type":"number","example":5280.0},"approved":{"type":"number","example":1200.0},"paid":{"type":"number","example":900.0}}}}}}}},"example":{"payload":[{"id":77,"account_id":1,"payee_id":7,"payee_type":"User","payee_name":"Ana Vendedora","currency":"BRL","period_start":"2026-07-01","period_end":"2026-07-31","status":"open","total_accrued":1240.5,"total_approved":0.0,"total_paid":0.0,"approved_by_id":null,"approved_at":null,"created_at":"2026-07-31T23:00:00Z","updated_at":"2026-07-31T23:00:00Z","commission_lines":[{"key":"deal:44","kind":"deal","title":"Assinatura anual","crm_item_id":44,"contact_id":19,"organization_id":8,"order_ids":[101,102],"payments_charge_ids":[201,202],"payment_count":2,"event_count":2,"gross_amount":997.0,"commission_amount":99.7,"effective_rate":0.1,"accrued_at":"2026-09-05T12:00:00Z","has_adjustments":false,"accrual_ids":[501,502]}],"accruals":[{"id":501,"source_type":"Payments::Charge","source_label":"Cobrança","source_id":8,"gross_amount":500.0,"rate_applied":0.08,"commission_amount":40.0}]}],"meta":{"count":42,"current_page":1,"total_pages":2,"per_page":25,"has_more":true,"totals":{"accrued":5280.0,"approved":1200.0,"paid":900.0},"totals_by_currency":[{"currency":"BRL","accrued":5280.0,"approved":1200.0,"paid":900.0}]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer","default":1},"description":"1-based page number."},{"name":"per_page","in":"query","required":false,"schema":{"type":"integer","default":25,"maximum":100},"description":"Page size (default 25, capped at 100)."},{"name":"payee_id","in":"query","required":false,"schema":{"type":"integer"},"description":"Manager-only — filter to one payee's statements (an agent id is bounded to the manager's visible cascade). Interpreted against payee_type."},{"name":"payee_type","in":"query","required":false,"schema":{"type":"string","enum":["User","Sales::Affiliate"],"default":"User"},"description":"Which ledger to read — the agents' statements or the affiliates'. Defaults to 'User'. Without it an affiliate's statement and the agent who happens to share its id are the same row to the caller."},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["open","approved","paid"]},"description":"Narrow to a single statement status."}]}},"/api/v1/accounts/{account_id}/sales/commission_statements/{id}":{"get":{"tags":["Sales"],"operationId":"auto_get_api_v1_accounts_account_id_sales_commission_statements_id","summary":"Get commission statements","description":"Returns the commission statement identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/sales_commission_statement"},"example":{"id":77,"account_id":1,"payee_id":7,"payee_type":"User","payee_name":"Ana Vendedora","currency":"BRL","period_start":"2026-07-01","period_end":"2026-07-31","status":"open","total_accrued":1240.5,"total_approved":0.0,"total_paid":0.0,"approved_by_id":null,"approved_at":null,"created_at":"2026-07-31T23:00:00Z","updated_at":"2026-07-31T23:00:00Z","commission_lines":[{"key":"deal:44","kind":"deal","title":"Assinatura anual","crm_item_id":44,"contact_id":19,"organization_id":8,"order_ids":[101,102],"payments_charge_ids":[201,202],"payment_count":2,"event_count":2,"gross_amount":997.0,"commission_amount":99.7,"effective_rate":0.1,"accrued_at":"2026-09-05T12:00:00Z","has_adjustments":false,"accrual_ids":[501,502]}],"accruals":[{"id":501,"source_type":"Payments::Charge","source_label":"Cobrança","source_id":8,"gross_amount":500.0,"rate_applied":0.08,"commission_amount":40.0}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/sales/commission_reconciliation/preview":{"get":{"tags":["Sales"],"operationId":"auto_get_api_v1_accounts_account_id_sales_commission_reconciliation_preview","summary":"Preview historical commission reconciliation","description":"Read-only evaluation of an explicit account-scoped order selection. It considers only operational paid orders with an active seller, valid currency and exactly one effective commission assignment and plan on paid_at, falling back to ordered_at. A won-basis plan is eligible only when no deal is linked or every linked deal is won. Canonical gateway/external-id duplicates and legacy deal accruals are counted once. Installments and mixed payment methods linked to one deal receive a deterministic cumulative allocation under one frozen policy, so their sum equals the rounded plan commission on the logical sale total. Provider ids are scoped by payment connection and ambiguous unscoped identities fail closed. The fingerprint binds apply to the reviewed orders, policy and ledger snapshot. Requires an administrator or the sales-management permission.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Stable preview of eligible, already reconciled and skipped orders.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/sales_commission_reconciliation_preview"},"example":{"fingerprint":"8a79d86d6e264ce27e64c9f6f55e489de996f5492d0e5a7c98d63d483e4149a1","fingerprint_version":3,"selection":{"order_ids":[101,102],"count":2},"summary":{"selected":2,"logical_sales_count":1,"eligible":1,"already_reconciled":1,"skipped":0,"economic_gross_by_currency":[{"currency":"BRL","amount":"200.00"}],"economic_commission_by_currency":[{"currency":"BRL","amount":"200.00"}],"commission_to_apply_by_currency":[{"currency":"BRL","amount":"200.00"}],"existing_commission_by_currency":[{"currency":"BRL","amount":"200.00"}],"credits_to_create_by_currency":[{"currency":"BRL","amount":"200.00"}],"reversals_to_create_by_currency":[{"currency":"BRL","amount":"200.00"}],"payable_after_apply_by_currency":[{"currency":"BRL","amount":"200.00"}],"period_movements":[{"currency":"BRL","amount":"99.70","from_period_start":"2026-07-01","from_period_end":"2026-07-31","to_period_start":"2026-08-01","to_period_end":"2026-08-31"}]},"rules":{"paid_basis":"operational_paid_order","won_basis":"settled_order_without_deal_or_linked_to_won_deal","existing_history":"closed_history_never_reopened_open_legacy_realigned","statement_period":"existing_custom_period_or_account_timezone_calendar_month","logical_sale_allocation":"cumulative_by_deal_owner_currency_provenance_and_frozen_policy"},"items":[{"order_id":101,"status":"paid","owner_id":7,"currency":"BRL","economic_at":"2026-08-15T14:00:00.000000Z","gross_amount":"1000.0","recognized_amount":"1000.0","assignment_id":9,"plan":{"id":3,"name":"Standard commission","basis":"paid","credit_mode":"single"},"expected_commission_amount":"100.0","commission_allocation":{"scope":"crm_item","crm_item_id":44,"order_ids":[101,102],"position":2,"gross_before":"500.0","gross_through":"997.0","commission_before":"50.0","commission_through":"99.7","canonical_order_id":101},"net_commission_amount":"100.0","ledger_action":"create","existing_commission_amount":"100.0","existing_commission_currency":"BRL","existing_source_type":"Crm::Order","existing_source_id":101,"canonical_order_id":101,"source_order_id":100,"crm_item_id":44,"statement_id":18,"statement_status":"approved","outcome":"eligible","reason":null,"reason_label":null,"history_reason":null,"legacy_alignment":[{}],"period_movements":[{"currency":"BRL","amount":"99.70","from_period_start":"2026-07-01","from_period_end":"2026-07-31","to_period_start":"2026-08-01","to_period_end":"2026-08-31"}]}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"403":{"description":"Sales feature disabled or administrator/sales-management permission required.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["feature_not_enabled","forbidden"],"example":"forbidden"}}},"example":{"error":"forbidden"}}}},"422":{"description":"The explicit selection is missing, invalid or too large.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["selection_required","selection_invalid","selection_too_large","economic_identity_ambiguous","commission_statement_period_ambiguous"],"example":"selection_required"},"message":{"type":"string","example":"Select at least one order."}}},"example":{"error":"selection_required","message":"Select at least one order."}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"order_ids[]","in":"query","required":true,"description":"Explicit unique order identifiers; at most 500.","schema":{"type":"array","minItems":1,"maxItems":500,"uniqueItems":true,"items":{"type":"integer","minimum":1}}}]}},"/api/v1/accounts/{account_id}/sales/commission_reconciliation/apply":{"post":{"tags":["Sales"],"operationId":"auto_post_api_v1_accounts_account_id_sales_commission_reconciliation_apply","summary":"Apply historical commission reconciliation","description":"Re-evaluates the explicit order selection under the account commission lock and appends missing accruals only when the economic inputs still match the preview fingerprint. Closed commission history is never reopened. Eligible open legacy deal credits are compensated through the canonical commission service and replaced by order credits in their economic periods. Each selected order keeps its own audit row, while cumulative allocation prevents installment rounding from changing the logical sale commission. Apply persists the exact locked-preview calculation; it never recomputes money after verifying the fingerprint. No scoring, webhook, provider call or customer automation is dispatched. A replay is a successful no-op. Requires an administrator or the sales-management permission. This financial mutation remains excluded from account MCP until a durable server-owned human approval receipt is available.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Post-apply preview plus the append-only accrual receipts created by this attempt.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/sales_commission_reconciliation_result"},"example":{"fingerprint":"8a79d86d6e264ce27e64c9f6f55e489de996f5492d0e5a7c98d63d483e4149a1","fingerprint_version":3,"selection":{"order_ids":[101,102],"count":2},"summary":{"selected":2,"logical_sales_count":1,"eligible":1,"already_reconciled":1,"skipped":0,"economic_gross_by_currency":[{"currency":"BRL","amount":"200.00"}],"economic_commission_by_currency":[{"currency":"BRL","amount":"200.00"}],"commission_to_apply_by_currency":[{"currency":"BRL","amount":"200.00"}],"existing_commission_by_currency":[{"currency":"BRL","amount":"200.00"}],"credits_to_create_by_currency":[{"currency":"BRL","amount":"200.00"}],"reversals_to_create_by_currency":[{"currency":"BRL","amount":"200.00"}],"payable_after_apply_by_currency":[{"currency":"BRL","amount":"200.00"}],"period_movements":[{"currency":"BRL","amount":"99.70","from_period_start":"2026-07-01","from_period_end":"2026-07-31","to_period_start":"2026-08-01","to_period_end":"2026-08-31"}]},"rules":{"paid_basis":"operational_paid_order","won_basis":"settled_order_without_deal_or_linked_to_won_deal","existing_history":"closed_history_never_reopened_open_legacy_realigned","statement_period":"existing_custom_period_or_account_timezone_calendar_month","logical_sale_allocation":"cumulative_by_deal_owner_currency_provenance_and_frozen_policy"},"items":[{"order_id":101,"status":"paid","owner_id":7,"currency":"BRL","economic_at":"2026-08-15T14:00:00.000000Z","gross_amount":"1000.0","recognized_amount":"1000.0","assignment_id":9,"plan":{"id":3,"name":"Standard commission","basis":"paid","credit_mode":"single"},"expected_commission_amount":"100.0","commission_allocation":{"scope":"crm_item","crm_item_id":44,"order_ids":[101,102],"position":2,"gross_before":"500.0","gross_through":"997.0","commission_before":"50.0","commission_through":"99.7","canonical_order_id":101},"net_commission_amount":"100.0","ledger_action":"create","existing_commission_amount":"100.0","existing_commission_currency":"BRL","existing_source_type":"Crm::Order","existing_source_id":101,"canonical_order_id":101,"source_order_id":100,"crm_item_id":44,"statement_id":18,"statement_status":"approved","outcome":"eligible","reason":null,"reason_label":null,"history_reason":null,"legacy_alignment":[{}],"period_movements":[{"currency":"BRL","amount":"99.70","from_period_start":"2026-07-01","from_period_end":"2026-07-31","to_period_start":"2026-08-01","to_period_end":"2026-08-31"}]}],"applied":[{"order_id":101,"accrual_id":81,"ledger_action":"create","reversal_accrual_ids":[],"statement_period":["2026-08-01","2026-08-31"]}],"applied_count":1,"skipped_after_lock_order_ids":[],"replayed":false}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"403":{"description":"Sales feature disabled or administrator/sales-management permission required.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["feature_not_enabled","forbidden"],"example":"forbidden"}}},"example":{"error":"forbidden"}}}},"409":{"description":"Economic inputs changed after preview; no accrual was written.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["fingerprint_mismatch"],"example":"fingerprint_mismatch"},"message":{"type":"string","example":"The economic data changed after preview. Review a new preview before applying."}}},"example":{"error":"fingerprint_mismatch","message":"The economic data changed after preview. Review a new preview before applying."}}}},"422":{"description":"Selection or fingerprint validation failed; no accrual was written.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["selection_required","selection_invalid","selection_too_large","fingerprint_required","fingerprint_invalid","economic_identity_ambiguous","commission_statement_period_ambiguous"],"example":"fingerprint_required"},"message":{"type":"string","example":"Preview the selection and send its fingerprint before applying."}}},"example":{"error":"fingerprint_required","message":"Preview the selection and send its fingerprint before applying."}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["order_ids","fingerprint"],"properties":{"order_ids":{"type":"array","minItems":1,"maxItems":500,"uniqueItems":true,"items":{"type":"integer","minimum":1},"example":[101,102]},"fingerprint":{"type":"string","pattern":"^[0-9a-f]{64}$","example":"8a79d86d6e264ce27e64c9f6f55e489de996f5492d0e5a7c98d63d483e4149a1"}}},"example":{"order_ids":[101,102],"fingerprint":"8a79d86d6e264ce27e64c9f6f55e489de996f5492d0e5a7c98d63d483e4149a1"}}}}}},"/api/v1/accounts/{account_id}/sales/commission_simulator":{"get":{"tags":["Sales"],"operationId":"auto_get_api_v1_accounts_account_id_sales_commission_simulator","summary":"Get commission simulator","description":"Returns the commission simulator identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"plan_id":{"type":"integer"},"plan_name":{"type":"string"},"gross_amount":{"type":"number"},"attainment_pct":{"type":"number"},"commission_amount":{"type":"number"},"rate_applied":{"type":"string"},"breakdown":{"type":"string"},"currency":{"type":"string"},"error":{"type":"string"}}},"example":{"plan_id":1,"plan_name":"sample plan name","gross_amount":149.9,"attainment_pct":12.5,"commission_amount":149.9,"rate_applied":"sample rate applied","breakdown":"sample breakdown","currency":"BRL","error":"sample error"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"plan_id","in":"query","required":true,"description":"Commission plan to simulate against.","schema":{"type":"integer"},"example":4},{"name":"gross_amount","in":"query","required":true,"description":"Gross deal amount the commission is computed on, in the account currency.","schema":{"type":"number"},"example":15000.0},{"name":"attainment_pct","in":"query","required":false,"description":"Quota attainment to apply, as a percentage. Omitted, the plan's accelerators are evaluated with no attainment modifier.","schema":{"type":"number"},"example":87.5}]}},"/api/v1/accounts/{account_id}/sales/scoring_simulator":{"get":{"tags":["Sales"],"operationId":"auto_get_api_v1_accounts_account_id_sales_scoring_simulator","summary":"Scoring simulator","description":"Evaluates a HYPOTHETICAL sale against the account's scoring rules and returns the points AND the reason. Account configuration is read; the hypothetical sale and evaluation are never persisted. The `skipped_reason` is the product, not a detail: a bare \"0\" cannot distinguish \"the rule is like that\" from a suppressing trigger, unmatched conditions, a missing basis, an invalid divisor or a source that carries no money by nature — and each has a different fix. Requires the sales-management permission.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The simulated evaluation.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"metric":{"type":"string","example":"deal_won"},"points":{"type":"number","format":"float","description":"Points this sale would score. A NUMBER, never a string.","example":3.0},"skipped_reason":{"type":["string","null"],"enum":["trigger","disabled","conditions","basis_missing","no_divisor","zero_basis","no_amount",null],"description":"Why the evaluation did not score. Null when it did.","example":"trigger"},"clamped":{"type":["string","null"],"enum":["min","max",null],"description":"Which clamp bound was applied, if any. Never applied to a skipped evaluation."},"amount":{"type":["number","null"],"format":"float","description":"The basis amount actually used, in MAJOR units.","example":9000.0},"matched_clause":{"type":["object","null"],"additionalProperties":true,"description":"The first clause whose `when` matched, merged over the rule header. Null when none matched."},"rule":{"type":"object","additionalProperties":true,"description":"Snapshot of the effective rule (mode, basis, divisor, percent, rounding, legacy)."},"legacy":{"type":"boolean","description":"True when no rule is configured and the legacy per-event weight was used.","example":false},"context":{"type":"object","properties":{"payment_method":{"type":["string","null"],"example":"pix","description":"Meio de pagamento do negócio. O conjunto base é pix, boleto, credit_card, debit_card, bank_transfer, cash, hosted_link e other; uma conta pode acrescentar chaves próprias em Sales::Setting `payment_categories.custom_methods`, então o conjunto NÃO é fechado. `other` é escolha do usuário; valor desconhecido vindo de provider é sempre nulo."},"payment_category":{"type":["string","null"],"example":"a_vista","description":"Categoria de pagamento DERIVADA (não é coluna), resolvida pela primeira regra que casa em `payment_categories.rules` e, sem nenhuma, pelo `default` da conta. `uncategorized` é a chave reservada usada como degrau intermediário da cascata do piso. Texto livre por conta."},"installments":{"type":"integer","description":"Normalized — an absent or zero column counts as 1 (a single payment).","example":1},"currency":{"type":["string","null"],"example":"BRL"}}}}}}},"example":{"payload":{"metric":"deal_won","points":3.0,"skipped_reason":"trigger","clamped":"min","amount":9000.0,"matched_clause":{},"rule":{},"legacy":false,"context":{"payment_method":"pix","payment_category":"a_vista","installments":1,"currency":"BRL"}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"403":{"description":"The caller is not a sales manager, or the sales_management feature is off."},"422":{"description":"Invalid, oversized or disallowed scoring draft; no settings are written.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["invalid_scoring_draft"]},"message":{"type":"string"}}},"example":{"error":"invalid_scoring_draft","message":"draft contains unsupported settings"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"metric","in":"query","schema":{"type":"string"}},{"name":"payment_method","in":"query","schema":{"type":"string"}},{"name":"payment_category","in":"query","schema":{"type":"string"}},{"name":"currency","in":"query","schema":{"type":"string"}},{"name":"source_type","in":"query","schema":{"type":"string"}},{"name":"weight","in":"query","schema":{"type":"number"},"description":"Hypothetical decimal input; omitted amounts remain absent."},{"name":"gross_amount","in":"query","schema":{"type":"number"},"description":"Hypothetical decimal input; omitted amounts remain absent."},{"name":"net_amount","in":"query","schema":{"type":"number"},"description":"Hypothetical decimal input; omitted amounts remain absent."},{"name":"list_amount","in":"query","schema":{"type":"number"},"description":"Hypothetical decimal input; omitted amounts remain absent."},{"name":"down_payment","in":"query","schema":{"type":"number"},"description":"Hypothetical decimal input; omitted amounts remain absent."},{"name":"base_amount","in":"query","schema":{"type":"number"},"description":"Hypothetical decimal input; omitted amounts remain absent."},{"name":"first_charge_amount","in":"query","schema":{"type":"number"},"description":"Hypothetical decimal input; omitted amounts remain absent."},{"name":"line_item_total","in":"query","schema":{"type":"number"},"description":"Hypothetical decimal input; omitted amounts remain absent."},{"name":"quantity_total","in":"query","schema":{"type":"number"},"description":"Hypothetical decimal input; omitted amounts remain absent."},{"name":"installments","in":"query","schema":{"type":"integer"}},{"name":"first_charge","in":"query","schema":{"type":"boolean"}},{"name":"product_ids","in":"query","schema":{"type":"array","items":{"type":"integer"}},"style":"form","explode":true},{"name":"product_category_ids","in":"query","schema":{"type":"array","items":{"type":"integer"}},"style":"form","explode":true},{"name":"draft","in":"query","description":"Optional unsaved JSON object, at most 32768 bytes. Only scoring_rules, point_weights, point_weight_won/paid/booking/activity/resolution, scoring_trigger, basis_on_missing, points_unit_label and points_decimals are accepted. Omit to evaluate persisted settings. Invalid or secret/unknown keys return 422.","schema":{"type":"string","example":"{\"scoring_rules\":{\"deal_won\":{\"enabled\":true,\"mode\":\"fixed\",\"points\":2}}}"}}]}},"/api/v1/accounts/{account_id}/sales/rule_impact_preview":{"get":{"tags":["Sales"],"operationId":"auto_get_api_v1_accounts_account_id_sales_rule_impact_preview","summary":"Preview an unsaved commercial rule draft","description":"Manager-only hypothetical comparison over at most 25 recently updated open deals in the caller's visible owner scope. Does not write settings, points or commissions. No historical cash-flow projection or currency conversion. Mixed-currency commission totals are null.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Estimated comparison over a bounded sample; never an award or payout.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"sample_size":{"type":"integer","minimum":0,"maximum":25},"sample_limit":{"type":"integer","enum":[25]},"sample_selection":{"type":"string","enum":["recent_open_deals"]},"period_label":{"type":"string","description":"Localized update-date range of the selected deals in the account time zone; explicit empty-sample label when no deals qualify."},"estimated":{"type":"boolean","enum":[true]},"delta_points":{"oneOf":[{"type":"string","pattern":"^-?[0-9]+(\\.[0-9]+)?$"},{"type":"number"}]},"delta_commission":{"oneOf":[{"type":"string","pattern":"^-?[0-9]+(\\.[0-9]+)?$"},{"type":"number"}]},"currency":{"type":["string","null"]},"would_block_count":{"type":"integer"},"sample":{"type":"array","maxItems":25,"items":{"type":"object","properties":{"item_id":{"type":"integer"},"currency":{"type":["string","null"]},"before":{"oneOf":[{"type":"string","pattern":"^-?[0-9]+(\\.[0-9]+)?$"},{"type":"number"},{"type":"boolean"}]},"after":{"oneOf":[{"type":"string","pattern":"^-?[0-9]+(\\.[0-9]+)?$"},{"type":"number"},{"type":"boolean"}]}}}}}}}},"example":{"payload":{"sample_size":1,"sample_limit":25,"sample_selection":"recent_open_deals","period_label":"Deals updated from 2026-09-01 to 2026-09-07 (account time zone).","estimated":true,"delta_points":"1.5","delta_commission":null,"currency":"BRL","would_block_count":0,"sample":[{"item_id":42,"currency":"BRL","before":"1.5","after":"3.0"}]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Commission plan not found within the account."},"403":{"description":"Feature or manager permission unavailable."},"422":{"description":"Invalid scope, draft, or rule configuration.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["invalid_impact_draft"]},"message":{"type":"string"}}},"example":{"error":"invalid_impact_draft","message":"invalid impact scope"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"scope","in":"query","required":true,"schema":{"type":"string","enum":["scoring","commission","floor"]}},{"name":"draft","in":"query","required":true,"description":"JSON object encoded as a string, maximum 32768 bytes.","schema":{"type":"string"}},{"name":"metric","in":"query","schema":{"type":"string","default":"deal_won"}},{"name":"plan_id","in":"query","description":"Required for commission scope; existing account plan.","schema":{"type":"integer"}}]}},"/api/v1/accounts/{account_id}/sales/point_events":{"get":{"tags":["Sales"],"operationId":"auto_get_api_v1_accounts_account_id_sales_point_events","summary":"Explainable point ledger","description":"The rep's point statement, one row per ledger entry, each carrying the explanation derived from the snapshot the row itself holds — never recomputed with today's rule, so changing a divisor tomorrow does not rewrite history. Scoped by the module's existing visibility target: asking for another rep's user_id is resolved by existing owner visibility; unauthorized targets fall back to self.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"One page of the caller's point events.","content":{"application/json":{"schema":{"type":"object","properties":{"meta":{"type":"object","properties":{"user_id":{"type":"integer","example":7},"count":{"type":"integer","example":42},"total_points":{"type":"number","format":"float","description":"Sum over the whole filtered set (not just this page). A NUMBER.","example":1240.5},"per_page":{"type":"integer","example":25}}},"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","example":9912},"metric":{"type":"string","example":"deal_won"},"points":{"type":"number","format":"float","example":1.5},"awarded_at":{"type":"string","format":"date-time","example":"2026-09-01T13:22:10Z"},"reversal":{"type":"boolean","description":"True for a mirror reversal/reinstatement row.","example":false},"source_type":{"type":"string","example":"Crm::Item"},"source_id":{"type":"integer","example":4471},"explanation":{"type":"object","properties":{"engine":{"type":["string","null"],"example":"v2"},"mode":{"type":["string","null"],"example":"per_value","enum":["fixed","per_value","percent",null],"description":"Como a regra de pontuação transformou o valor em pontos. Trace: Sales::ScoringRuleResolver::MODES."},"basis":{"type":["string","null"],"example":"gross"},"divisor":{"type":["number","null"],"example":3000},"percent":{"type":["number","null"],"example":1.0},"rounding":{"type":["object","null"],"additionalProperties":true,"description":"The rounding frozen on this row (mode + decimals)."},"legacy":{"type":"boolean","example":false},"matched_clause":{"type":["object","null"],"additionalProperties":true,"description":"The clause that produced this row, as it was at award time."},"clamped":{"type":["string","null"],"example":"min"},"skipped_reason":{"type":["string","null"],"example":"zero_basis"},"amount":{"type":["string","null"],"example":"4500.0"},"currency":{"type":["string","null"],"example":"BRL"},"payment_category":{"type":["string","null"],"example":"a_vista","description":"Categoria de pagamento DERIVADA (não é coluna), resolvida pela primeira regra que casa em `payment_categories.rules` e, sem nenhuma, pelo `default` da conta. `uncategorized` é a chave reservada usada como degrau intermediário da cascata do piso. Texto livre por conta."},"payment_method":{"type":["string","null"],"example":"pix","description":"Meio de pagamento do negócio. O conjunto base é pix, boleto, credit_card, debit_card, bank_transfer, cash, hosted_link e other; uma conta pode acrescentar chaves próprias em Sales::Setting `payment_categories.custom_methods`, então o conjunto NÃO é fechado. `other` é escolha do usuário; valor desconhecido vindo de provider é sempre nulo."},"installments":{"type":["integer","null"],"example":1},"allocation":{"type":["object","null"],"additionalProperties":true,"description":"Present when the row was allocated per logical sale — carries the mode, the cohort size, the sale total and how much was already credited to the others."}}}}}}}},"example":{"meta":{"user_id":7,"count":42,"total_points":1240.5,"per_page":25},"payload":[{"id":9912,"metric":"deal_won","points":1.5,"awarded_at":"2026-09-01T13:22:10Z","reversal":false,"source_type":"Crm::Item","source_id":4471,"explanation":{"engine":"v2","mode":"per_value","basis":"gross","divisor":3000,"percent":1.0,"rounding":{},"legacy":false,"matched_clause":{},"clamped":"min","skipped_reason":"zero_basis","amount":"4500.0","currency":"BRL","payment_category":"a_vista","payment_method":"pix","installments":1,"allocation":{}}}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"user_id","in":"query","description":"Defaults to the authenticated user; existing visibility rules govern any other target.","schema":{"type":"integer"}},{"name":"metric","in":"query","description":"Exact metric filter; omitted means all metrics.","schema":{"type":"string"}},{"name":"from","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"to","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1}}]}},"/api/v1/accounts/{account_id}/sales/settings/rotate_wallboard_token":{"post":{"tags":["Sales"],"operationId":"auto_post_api_v1_accounts_account_id_sales_settings_rotate_wallboard_token","summary":"Rotate wallboard token settings","description":"Performs the rotate wallboard token operation on the targeted setting resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"settings_presets":{"type":"string"},"point_weight_won":{"type":"integer"},"point_weight_paid":{"type":"integer"},"point_weight_booking":{"type":"integer"},"point_weight_activity":{"type":"integer"},"point_weight_resolution":{"type":"integer"},"medal_bronze_pct":{"type":"integer"},"medal_silver_pct":{"type":"integer"},"medal_gold_pct":{"type":"integer"},"medal_platinum_pct":{"type":"integer"},"medal_diamond_pct":{"type":"integer"},"level_thresholds":{"type":"array","items":{"type":"integer"}},"isolation_mode":{"type":"string","enum":["inbox_team","per_owner"],"description":"Whether sales visibility is inbox/team-wide or isolated to each record owner."},"leaderboard_anonymized":{"type":"string"},"coin_conversion_rate":{"type":"number"},"celebration_win":{"type":"boolean"},"celebration_goal":{"type":"boolean"},"celebration_super_goal":{"type":"boolean"},"celebration_mega_goal":{"type":"boolean"},"commission_basis_default":{"type":"string"},"wallboard_display_token":{"type":"string"},"wallboard_phrases":{"type":"array","items":{"type":"string"}},"wallboard_ticker_speed":{"type":"string"},"wallboard_mask_names":{"type":"boolean"},"ingest_token_configured":{"type":"boolean"},"scoring_trigger":{"type":"string","enum":["both","won","paid"],"description":"Governa APENAS o par deal_won/payment_paid; as demais métricas seguem suas próprias regras. O mais restritivo vence, e uma avaliação suprimida NÃO grava linha no ledger."},"basis_on_missing":{"type":"string","enum":["skip","zero","gross"],"description":"O que fazer quando a base de cálculo não resolve. `skip` (default) não pontua nem grava linha; `zero` pontua zero; `gross` cai para o bruto. Trace: Sales::RuleBases::MISSING_POLICIES."},"celebration_follows":{"type":"string","enum":["business_event","scoring"],"description":"A que a celebração segue. `business_event` (default) celebra o evento de negócio mesmo quando o gatilho suprimiu o ponto; `scoring` mantém o acoplamento à criação da linha do ledger."},"credit_automation_closes":{"type":"boolean"},"credit_follows_owner_change":{"type":"string","enum":[false,"reverse_and_recredit","recredit_only"],"description":"O que acontece com o crédito quando o dono do negócio muda. `off` é o comportamento de hoje."},"points_unit_label":{"type":"string"},"points_decimals":{"type":"integer"},"reporting_currency":{"type":"string"},"allowed_payment_methods":{"type":"string"},"payment_method_labels":{"type":"string"},"wallboard_display_mode":{"type":"string","enum":["both","points","money"],"description":"O que o telão exibe em cada linha: `points` (só pontos), `money` (só moeda) ou `both` (os dois, default). Trace: Sales::SettingSchemas::Wallboard::DISPLAY_MODES."},"wallboard_scenes":{"type":"array","items":{"type":"string"}},"wallboard_rotate_seconds":{"type":"integer"},"wallboard_theme":{"type":"string","enum":["dark","light"],"description":"Tema do telão. Trace: Sales::SettingSchemas::Wallboard::THEMES."},"wallboard_mask_values":{"type":"boolean"},"settings":{"type":"string"},"resolved":{"type":"string"}}}}},"example":{"payload":{"settings_presets":"sample settings presets","point_weight_won":1,"point_weight_paid":1,"point_weight_booking":1,"point_weight_activity":1,"point_weight_resolution":1,"medal_bronze_pct":1,"medal_silver_pct":1,"medal_gold_pct":1,"medal_platinum_pct":1,"medal_diamond_pct":1,"level_thresholds":[1],"isolation_mode":"inbox_team","leaderboard_anonymized":"sample leaderboard anonymized","coin_conversion_rate":12.5,"celebration_win":true,"celebration_goal":true,"celebration_super_goal":true,"celebration_mega_goal":true,"commission_basis_default":"sample commission basis default","wallboard_display_token":"sample-token","wallboard_phrases":["sample wallboard phrase"],"wallboard_ticker_speed":"sample wallboard ticker speed","wallboard_mask_names":true,"ingest_token_configured":true,"scoring_trigger":"both","basis_on_missing":"skip","celebration_follows":"business_event","credit_automation_closes":true,"credit_follows_owner_change":false,"points_unit_label":"sample points unit label","points_decimals":1,"reporting_currency":"sample reporting currency","allowed_payment_methods":"sample allowed payment methods","payment_method_labels":"sample payment method labels","wallboard_display_mode":"both","wallboard_scenes":["sample wallboard scene"],"wallboard_rotate_seconds":60,"wallboard_theme":"dark","wallboard_mask_values":true,"settings":"sample settings","resolved":"sample resolved"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/sales/settings":{"get":{"tags":["Sales"],"operationId":"auto_get_api_v1_accounts_account_id_sales_settings","summary":"Read sales settings and safe draft presets","description":"Manager-only settings read. Returns existing settings fields plus generic unsaved preset mechanics. Monetary presets are omitted until a reporting currency is configured. Applying a preset in a form does not persist settings; saving remains an explicit write. Display masking is applied on wallboard payloads, not merely in CSS.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Settings and optional draft presets. Other established settings fields remain present.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"settings_presets":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","enum":["fixed_points","per_value","percentage"]},"title_key":{"type":"string"},"description_key":{"type":"string"},"settings":{"type":"object","properties":{"scoring_rules":{"type":"object","additionalProperties":{"type":"object","properties":{"enabled":{"type":"boolean"},"mode":{"type":"string","enum":["fixed","per_value","percent"]},"points":{"oneOf":[{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},{"type":"number"}],"description":"Decimal serialized as a string or number; values are never currency-converted."},"basis":{"type":["string","null"],"enum":["list","gross","net","down_payment","first_charge_amount","base_amount","line_item_total","quantity","fixed",null]},"divisor":{"oneOf":[{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},{"type":"number"}],"description":"Decimal serialized as a string or number; values are never currency-converted."},"percent":{"oneOf":[{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},{"type":"number"}],"description":"Decimal serialized as a string or number; values are never currency-converted."},"currency":{"type":["string","null"]},"rounding":{"type":"object","properties":{"mode":{"type":"string","enum":["round","floor","ceil"]},"decimals":{"type":"integer","minimum":0,"maximum":2}}}},"additionalProperties":true},"description":"Metric keys mapped to normalized, unsaved rules."}}}}}},"wallboard_display_mode":{"type":"string","enum":["points","money","both"],"description":"O que o telão exibe em cada linha: `points` (só pontos), `money` (só moeda) ou `both` (os dois, default). Trace: Sales::SettingSchemas::Wallboard::DISPLAY_MODES."},"wallboard_scenes":{"type":"array","items":{"type":"string","enum":["ranking","team_goal","recent_wins","top_movers","pareto"]}},"wallboard_rotate_seconds":{"type":"integer","minimum":5,"maximum":120},"wallboard_theme":{"type":"string","enum":["dark","light"],"description":"Tema do telão. Trace: Sales::SettingSchemas::Wallboard::THEMES."},"wallboard_mask_names":{"type":"boolean"},"wallboard_mask_values":{"type":"boolean"}},"additionalProperties":true}}},"example":{"payload":{"settings_presets":[{"id":"fixed_points","title_key":"SALES.SETTINGS.PRESETS.FIXED_POINTS.TITLE","description_key":"SALES.SETTINGS.PRESETS.FIXED_POINTS.DESCRIPTION","settings":{"scoring_rules":{"deal_won":{"mode":"fixed","points":1,"enabled":true,"rounding":{"mode":"round","decimals":2}}}}}],"wallboard_display_mode":"points","wallboard_scenes":["ranking"],"wallboard_rotate_seconds":13,"wallboard_theme":"dark","wallboard_mask_names":false,"wallboard_mask_values":false}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]},"patch":{"tags":["Sales"],"operationId":"auto_patch_api_v1_accounts_account_id_sales_settings","summary":"Update settings","description":"Updates the setting identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"sales_settings/invalid"},"code":{"type":"string"},"errors":{"type":"array","items":{"type":"string"}}}},"example":{"error":"sales_settings/invalid","code":"sample code","errors":["sample error"]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"Send the tunables under `settings` (or `data`). The form talks flat keys (whitelisted and coerced by the API) that map into the nested engine structure; pre-nested groups (point_weights, medal_bands, celebration_thresholds) are also accepted. Unknown keys are dropped.","properties":{"settings":{"type":"object","properties":{"point_weight_won":{"type":"integer","description":"-\u003e point_weights.deal_won","example":100},"point_weight_paid":{"type":"integer","description":"-\u003e point_weights.payment_paid","example":100},"point_weight_booking":{"type":"integer","description":"-\u003e point_weights.booking_completed","example":30},"point_weight_follow_up":{"type":"integer","description":"-\u003e point_weights.follow_up_converted","example":20},"point_weight_resolution":{"type":"integer","description":"-\u003e point_weights.resolution","example":10},"medal_bronze_pct":{"type":"integer","example":50},"medal_silver_pct":{"type":"integer","example":75},"medal_gold_pct":{"type":"integer","example":100},"medal_platinum_pct":{"type":"integer","example":125},"medal_diamond_pct":{"type":"integer","example":150},"celebration_win":{"type":"boolean","example":true},"celebration_goal":{"type":"boolean","example":true},"celebration_super_goal":{"type":"boolean","example":true},"celebration_mega_goal":{"type":"boolean","example":true},"isolation_mode":{"type":"string","enum":["inbox_team","per_owner"],"example":"inbox_team","description":"Whether sales visibility is inbox/team-wide or isolated to each record owner."},"external_attribution_mode":{"type":"string","enum":["off","last_conversation","distribution"],"description":"How an external/catalog sale is auto-attributed to a seller when the buyer has no owner. Manual attribution (sales/orders/:id/attribute) always overrides it.","example":"off"},"leaderboard_anonymized":{"type":"boolean","example":false},"coin_conversion_rate":{"type":"number","example":1.0},"commission_basis_default":{"type":"string","enum":["paid","won"],"example":"paid"},"level_thresholds":{"type":"array","items":{"type":"integer"},"example":[0,500,1500,3500,7500]},"wallboard_ticker_speed":{"type":"string","enum":["slow","normal","fast"],"example":"normal"},"wallboard_phrases":{"type":"array","items":{"type":"string"},"description":"Max 50 phrases, 200 chars each.","example":["Vamos fechar mais uma!","Meta é destino"]}}}}},"example":{"settings":{"point_weight_won":100,"point_weight_paid":100,"point_weight_booking":30,"point_weight_follow_up":20,"point_weight_resolution":10,"medal_bronze_pct":50,"medal_silver_pct":75,"medal_gold_pct":100,"medal_platinum_pct":125,"medal_diamond_pct":150,"celebration_win":true,"celebration_goal":true,"celebration_super_goal":true,"celebration_mega_goal":true,"isolation_mode":"inbox_team","external_attribution_mode":"off","leaderboard_anonymized":false,"coin_conversion_rate":1.0,"commission_basis_default":"paid","level_thresholds":[0,500,1500,3500,7500],"wallboard_ticker_speed":"normal","wallboard_phrases":["Vamos fechar mais uma!","Meta é destino"]}}}}}},"put":{"tags":["Sales"],"operationId":"auto_put_api_v1_accounts_account_id_sales_settings","summary":"Update settings","description":"Updates the setting identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"sales_settings/invalid"},"code":{"type":"string"},"errors":{"type":"array","items":{"type":"string"}}}},"example":{"error":"sales_settings/invalid","code":"sample code","errors":["sample error"]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"Send the tunables under `settings` (or `data`). The form talks flat keys (whitelisted and coerced by the API) that map into the nested engine structure; pre-nested groups (point_weights, medal_bands, celebration_thresholds) are also accepted. Unknown keys are dropped.","properties":{"settings":{"type":"object","properties":{"point_weight_won":{"type":"integer","description":"-\u003e point_weights.deal_won","example":100},"point_weight_paid":{"type":"integer","description":"-\u003e point_weights.payment_paid","example":100},"point_weight_booking":{"type":"integer","description":"-\u003e point_weights.booking_completed","example":30},"point_weight_follow_up":{"type":"integer","description":"-\u003e point_weights.follow_up_converted","example":20},"point_weight_resolution":{"type":"integer","description":"-\u003e point_weights.resolution","example":10},"medal_bronze_pct":{"type":"integer","example":50},"medal_silver_pct":{"type":"integer","example":75},"medal_gold_pct":{"type":"integer","example":100},"medal_platinum_pct":{"type":"integer","example":125},"medal_diamond_pct":{"type":"integer","example":150},"celebration_win":{"type":"boolean","example":true},"celebration_goal":{"type":"boolean","example":true},"celebration_super_goal":{"type":"boolean","example":true},"celebration_mega_goal":{"type":"boolean","example":true},"isolation_mode":{"type":"string","enum":["inbox_team","per_owner"],"example":"inbox_team","description":"Whether sales visibility is inbox/team-wide or isolated to each record owner."},"external_attribution_mode":{"type":"string","enum":["off","last_conversation","distribution"],"description":"How an external/catalog sale is auto-attributed to a seller when the buyer has no owner. Manual attribution (sales/orders/:id/attribute) always overrides it.","example":"off"},"leaderboard_anonymized":{"type":"boolean","example":false},"coin_conversion_rate":{"type":"number","example":1.0},"commission_basis_default":{"type":"string","enum":["paid","won"],"example":"paid"},"level_thresholds":{"type":"array","items":{"type":"integer"},"example":[0,500,1500,3500,7500]},"wallboard_ticker_speed":{"type":"string","enum":["slow","normal","fast"],"example":"normal"},"wallboard_phrases":{"type":"array","items":{"type":"string"},"description":"Max 50 phrases, 200 chars each.","example":["Vamos fechar mais uma!","Meta é destino"]}}}}},"example":{"settings":{"point_weight_won":100,"point_weight_paid":100,"point_weight_booking":30,"point_weight_follow_up":20,"point_weight_resolution":10,"medal_bronze_pct":50,"medal_silver_pct":75,"medal_gold_pct":100,"medal_platinum_pct":125,"medal_diamond_pct":150,"celebration_win":true,"celebration_goal":true,"celebration_super_goal":true,"celebration_mega_goal":true,"isolation_mode":"inbox_team","external_attribution_mode":"off","leaderboard_anonymized":false,"coin_conversion_rate":1.0,"commission_basis_default":"paid","level_thresholds":[0,500,1500,3500,7500],"wallboard_ticker_speed":"normal","wallboard_phrases":["Vamos fechar mais uma!","Meta é destino"]}}}}}}},"/api/v1/accounts/{account_id}/sales/wallboard":{"get":{"tags":["Sales"],"operationId":"auto_get_api_v1_accounts_account_id_sales_wallboard","summary":"Read sales wallboard scenes","description":"Read-only scene data with independent points and revenue. Display mode controls presentation, not the unit of stored numbers. Identity/value masking replaces the corresponding JSON values with null before serialization; private commercial terms and provider/ingest/display tokens are removed recursively. Revenue currency belongs to each row. Authenticated account variant.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Scene data after server-side presentation privacy.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"team_goal":{"type":["object","null"],"properties":{"id":{"type":["integer","null"]},"name":{"type":["string","null"]},"metric_type":{"type":"string","enum":["revenue_won","revenue_paid","deals","conversions","resolutions","bookings","combination","points"]},"score_kind":{"type":"string","enum":["money","points"]},"currency":{"type":["string","null"],"minLength":3,"maxLength":3},"target_amount":{"oneOf":[{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},{"type":"number"}],"description":"Decimal serialized as a string or number; values are never currency-converted."},"target_count":{"type":["integer","null"]},"actual_value":{"oneOf":[{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},{"type":"number"}],"description":"Decimal serialized as a string or number; values are never currency-converted."},"actual_count":{"type":["integer","null"]},"actual":{"oneOf":[{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},{"type":"number"}],"description":"Decimal serialized as a string or number; values are never currency-converted."},"target":{"oneOf":[{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},{"type":"number"}],"description":"Decimal serialized as a string or number; values are never currency-converted."},"attainment_pct":{"oneOf":[{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},{"type":"number"}],"description":"Decimal serialized as a string or number; values are never currency-converted."},"tiers":{"type":"array","items":{"type":"object","properties":{"id":{"type":["integer","null"]},"label":{"type":"string"},"medal_band":{"type":["string","null"]},"threshold":{"oneOf":[{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},{"type":"number"}],"description":"Decimal serialized as a string or number; values are never currency-converted."},"threshold_value":{"oneOf":[{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},{"type":"number"}],"description":"Decimal serialized as a string or number; values are never currency-converted."},"reached":{"type":"boolean"}}}}}},"goal_gauges":{"type":"array","items":{"type":"object","properties":{"id":{"type":["integer","null"]},"name":{"type":["string","null"]},"metric_type":{"type":"string","enum":["revenue_won","revenue_paid","deals","conversions","resolutions","bookings","combination","points"]},"score_kind":{"type":"string","enum":["money","points"]},"currency":{"type":["string","null"],"minLength":3,"maxLength":3},"target_amount":{"oneOf":[{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},{"type":"number"}],"description":"Decimal serialized as a string or number; values are never currency-converted."},"target_count":{"type":["integer","null"]},"actual_value":{"oneOf":[{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},{"type":"number"}],"description":"Decimal serialized as a string or number; values are never currency-converted."},"actual_count":{"type":["integer","null"]},"actual":{"oneOf":[{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},{"type":"number"}],"description":"Decimal serialized as a string or number; values are never currency-converted."},"target":{"oneOf":[{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},{"type":"number"}],"description":"Decimal serialized as a string or number; values are never currency-converted."},"attainment_pct":{"oneOf":[{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},{"type":"number"}],"description":"Decimal serialized as a string or number; values are never currency-converted."},"scope_type":{"type":"string","enum":["user","team","account"]}}}},"leaderboard":{"type":"array","items":{"type":"object","properties":{"id":{"type":["integer","null"]},"user_id":{"type":["integer","null"]},"rank":{"type":"integer"},"value":{"oneOf":[{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},{"type":"number"}],"description":"Decimal serialized as a string or number; values are never currency-converted."},"points":{"oneOf":[{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},{"type":"number"}],"description":"Decimal serialized as a string or number; values are never currency-converted."},"revenue":{"oneOf":[{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},{"type":"number"}],"description":"Decimal serialized as a string or number; values are never currency-converted."},"currency":{"type":["string","null"],"minLength":3,"maxLength":3},"trend":{"oneOf":[{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},{"type":"number"}],"description":"Decimal serialized as a string or number; values are never currency-converted."},"attainment_pct":{"oneOf":[{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},{"type":"number"}],"description":"Decimal serialized as a string or number; values are never currency-converted."},"name":{"type":["string","null"]},"avatar_url":{"type":["string","null"]}}}},"pareto":{"type":"array","items":{"type":"object","properties":{"user_id":{"type":["integer","null"]},"rank":{"type":"integer"},"value":{"oneOf":[{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},{"type":"number"}],"description":"Decimal serialized as a string or number; values are never currency-converted."},"points":{"oneOf":[{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},{"type":"number"}],"description":"Decimal serialized as a string or number; values are never currency-converted."},"revenue":{"oneOf":[{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},{"type":"number"}],"description":"Decimal serialized as a string or number; values are never currency-converted."},"currency":{"type":["string","null"],"minLength":3,"maxLength":3},"name":{"type":["string","null"]},"contribution_pct":{"oneOf":[{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},{"type":"number"}],"description":"Decimal serialized as a string or number; values are never currency-converted."}}}},"ticker":{"type":"object","properties":{"today":{"oneOf":[{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},{"type":"number"}],"description":"Decimal serialized as a string or number; values are never currency-converted."},"month":{"oneOf":[{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},{"type":"number"}],"description":"Decimal serialized as a string or number; values are never currency-converted."},"points_today":{"oneOf":[{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},{"type":"number"}],"description":"Decimal serialized as a string or number; values are never currency-converted."},"points_month":{"oneOf":[{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},{"type":"number"}],"description":"Decimal serialized as a string or number; values are never currency-converted."},"currency":{"type":["string","null"],"minLength":3,"maxLength":3}}},"recent_wins":{"type":"array","items":{"type":"object","properties":{"id":{"type":["integer","null"]},"title":{"type":["string","null"]},"value":{"oneOf":[{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},{"type":"number"}],"description":"Decimal serialized as a string or number; values are never currency-converted."},"points":{"oneOf":[{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},{"type":"number"}],"description":"Decimal serialized as a string or number; values are never currency-converted."},"revenue":{"oneOf":[{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},{"type":"number"}],"description":"Decimal serialized as a string or number; values are never currency-converted."},"currency":{"type":["string","null"],"minLength":3,"maxLength":3},"owner_id":{"type":["integer","null"]},"owner_name":{"type":["string","null"]},"owner_avatar_url":{"type":["string","null"]},"closed_at":{"type":"string","format":"date-time","example":"2026-09-01T12:00:00Z"}}}},"top_movers":{"type":"array","items":{"type":"object","properties":{"user_id":{"type":["integer","null"]},"rank":{"type":"integer"},"value":{"oneOf":[{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},{"type":"number"}],"description":"Decimal serialized as a string or number; values are never currency-converted."},"points":{"oneOf":[{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},{"type":"number"}],"description":"Decimal serialized as a string or number; values are never currency-converted."},"revenue":{"oneOf":[{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},{"type":"number"}],"description":"Decimal serialized as a string or number; values are never currency-converted."},"currency":{"type":["string","null"],"minLength":3,"maxLength":3},"trend":{"oneOf":[{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},{"type":"number"}],"description":"Decimal serialized as a string or number; values are never currency-converted."},"name":{"type":["string","null"]},"avatar_url":{"type":["string","null"]}}}},"phrases":{"type":"array","items":{"type":"string"}},"ticker_speed":{"type":"string","enum":["slow","normal","fast"]},"mask_names":{"type":"boolean"},"mask_values":{"type":"boolean"},"display_mode":{"type":"string","enum":["points","money","both"]},"currency":{"type":["string","null"],"minLength":3,"maxLength":3},"scenes":{"type":"array","items":{"type":"string","enum":["ranking","team_goal","recent_wins","top_movers","pareto"]}},"rotate_seconds":{"type":"integer","minimum":5,"maximum":120},"theme":{"type":"string","enum":["dark","light"]},"points_unit_label":{"type":["string","null"]},"points_decimals":{"type":"integer","minimum":0,"maximum":2}}}}},"example":{"payload":{"team_goal":null,"goal_gauges":[{"id":null,"name":null,"metric_type":"revenue_won","score_kind":"money","currency":null,"target_amount":null,"target_count":null,"actual_value":null,"actual_count":null,"actual":null,"target":null,"attainment_pct":null,"scope_type":"user"}],"leaderboard":[{"id":null,"user_id":null,"rank":1,"value":null,"points":null,"revenue":null,"currency":null,"trend":"1.5","attainment_pct":null,"name":null,"avatar_url":null}],"pareto":[{"user_id":null,"rank":1,"value":null,"points":null,"revenue":null,"currency":null,"name":null,"contribution_pct":null}],"ticker":{"today":null,"month":null,"points_today":null,"points_month":null,"currency":null},"recent_wins":[{"id":null,"title":null,"value":null,"points":null,"revenue":null,"currency":null,"owner_id":null,"owner_name":null,"owner_avatar_url":null,"closed_at":"2026-09-01T12:00:00Z"}],"top_movers":[{"user_id":null,"rank":1,"value":null,"points":null,"revenue":null,"currency":null,"trend":"1.5","name":null,"avatar_url":null}],"phrases":["example"],"ticker_speed":"slow","mask_names":true,"mask_values":true,"display_mode":"points","currency":null,"scenes":["ranking"],"rotate_seconds":13,"theme":"dark","points_unit_label":"points","points_decimals":2}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Token or account resource unavailable."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/sales/dashboard":{"get":{"tags":["Sales"],"operationId":"auto_get_api_v1_accounts_account_id_sales_dashboard","summary":"Seller dashboard aggregate","description":"The caller's OWN dashboard slice: coin balance, badge count, points earned in the current month, current level, active goals with attainment, accrued commission and the ids of every badge and certification already earned. Read-only and always self-scoped — a manager sees their own numbers here and uses the wallboard for the team view. Requires the sales_management feature.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The caller's dashboard slice.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","description":"The dashboard aggregate for the authenticated user.","properties":{"user_id":{"type":"integer","description":"Id of the user the payload belongs to (always the caller)."},"coin_balance":{"type":"integer","description":"Signed sum of the user's coin ledger (credits positive, debits negative)."},"badge_count":{"type":"integer","description":"How many badge awards the user holds."},"period_points":{"type":"integer","description":"Points earned in the current calendar month."},"commission_accrued":{"type":["number","null"],"description":"Sum of total_accrued over the user's own agent commission statements, in MAJOR units. Null when it could not be computed (the UI then renders a dash rather than a misleading zero)."},"earned_badges":{"type":"array","description":"Ids of the badges the user has earned.","items":{"type":"integer"}},"earned_certifications":{"type":"array","description":"Ids of the certifications the user has earned.","items":{"type":"integer"}},"level":{"type":["object","null"],"description":"Highest level reached for the user's cumulative points; null when the account has no levels.","properties":{"id":{"type":"integer"},"name":{"type":"string"},"threshold_points":{"type":"integer","description":"Minimum cumulative points required by this level."},"total_points":{"type":"integer","description":"The user's cumulative points across all time."}}},"active_goals":{"type":"array","description":"Up to five active goals scoped to the user, their teams, or the whole account.","items":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"metric_type":{"type":"string","description":"Which metric the goal measures.","enum":["revenue_won","revenue_paid","deals","conversions","resolutions","bookings","combination"]},"target_amount":{"type":"number","description":"The goal target, in MAJOR units when the metric is monetary."},"attainment_pct":{"type":"number","description":"Attainment percentage (0-100+) for this goal; 0 when not yet computed."}}}}}}}},"example":{"payload":{"user_id":1,"coin_balance":1,"badge_count":5,"period_points":1,"commission_accrued":12.5,"earned_badges":[1],"earned_certifications":[1],"level":{"id":1,"name":"Sample Name","threshold_points":1,"total_points":1},"active_goals":[{"id":1,"name":"Sample Name","metric_type":"revenue_won","target_amount":149.9,"attainment_pct":12.5}]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/sales/affiliates/{id}/archive":{"post":{"tags":["Sales"],"operationId":"auto_post_api_v1_accounts_account_id_sales_affiliates_id_archive","summary":"Archive an affiliate explicitly","description":"Idempotently archives the affiliate while preserving referrals, orders and financial history.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The archived affiliate."},"401":{"description":"Unauthorized"},"404":{"description":"No affiliate with that id in this account."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/sales/affiliates/{id}/restore":{"post":{"tags":["Sales"],"operationId":"auto_post_api_v1_accounts_account_id_sales_affiliates_id_restore","summary":"Restore an archived affiliate","description":"Idempotently returns the affiliate to active status so new attribution and commission may resume.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The active affiliate."},"401":{"description":"Unauthorized"},"404":{"description":"No affiliate with that id in this account."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/sales/affiliates/{id}/purge":{"delete":{"tags":["Sales"],"operationId":"auto_delete_api_v1_accounts_account_id_sales_affiliates_id_purge","summary":"Delete an affiliate permanently","description":"Permanently deletes only an already archived affiliate with no contact referrals, attributed orders, commission accruals/statements or reconciliation history. This operation is explicit and irreversible.","security":[{"userApiKey":[]}],"responses":{"204":{"description":"The unreferenced archived affiliate was permanently deleted."},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"409":{"description":"Historical references block permanent deletion; the body includes blocker counts."},"422":{"description":"The affiliate must be archived first."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/sales/affiliates/{id}/rotate_portal_token":{"post":{"tags":["Sales"],"operationId":"auto_post_api_v1_accounts_account_id_sales_affiliates_id_rotate_portal_token","summary":"Rotate an affiliate's report token","description":"Issues a NEW portal_token and invalidates every report link previously shared for this affiliate, immediately. The referral_code is untouched, so no referral link in circulation breaks — that separation is the whole reason the two values exist (spec-078 gap D2). Use it when a report link leaked, when a partnership ends, or to clear the migration backfill that seeded portal_token from the PUBLIC referral code (portal_token_shared: true). Requires the affiliate_program feature plus the sales-management permission.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The affiliate, carrying the freshly issued token.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer","example":42},"portal_token":{"type":"string","description":"The new credential. The previous one stops resolving the instant this returns.","example":"7Qa2Zx9Lm4Kd1Rf6Tp0Yb3Nc8Vh5Jw"},"portal_token_rotated_at":{"type":"string","format":"date-time","description":"When this rotation happened.","example":"2026-07-25T18:20:00Z"},"portal_token_shared":{"type":"boolean","description":"False after any rotation — the token is no longer the public referral code.","example":false},"referral_code":{"type":"string","description":"Unchanged by the rotation.","example":"AB12CD34"},"name":{"type":"string","example":"João Afiliado"},"status":{"type":"string","enum":["active","paused","archived"],"example":"active"}}},"example":{"id":42,"portal_token":"7Qa2Zx9Lm4Kd1Rf6Tp0Yb3Nc8Vh5Jw","portal_token_rotated_at":"2026-07-25T18:20:00Z","portal_token_shared":false,"referral_code":"AB12CD34","name":"João Afiliado","status":"active"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/sales/affiliates":{"get":{"tags":["Sales"],"operationId":"auto_get_api_v1_accounts_account_id_sales_affiliates","summary":"List affiliates","description":"A page of the affiliates configured for the account (internal Users or external partners), ordered by name. Server-paginated (default 25, capped at 100) with an optional server-side search (q) and status filter; meta.count is the WHOLE filtered set, not the page. Requires the affiliate_program feature plus the sales-management permission.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"One page of affiliates with a whole-set count + pagination meta.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","example":42},"account_id":{"type":"integer","example":1},"user_id":{"type":["integer","null"],"description":"The linked User for an INTERNAL affiliate; null for an external one.","example":null},"name":{"type":"string","example":"João Afiliado"},"email":{"type":["string","null"],"example":"joao@parceiro.com"},"external_ref":{"type":["string","null"],"description":"External id / Hotmart ucode for an external affiliate.","example":"HTM9x1ucode"},"referral_code":{"type":"string","description":"Auto-generated","account-unique":null,"human-shareable code. PUBLIC — it is printed on links and material":null,"and since spec-078 it is NOT the portal credential.":null,"example":"AB12CD34"},"portal_token":{"type":"string","description":"The PRIVATE credential for the affiliate's own report (GET /sales/affiliate/:portal_token). Separate from referral_code so it can be revoked without breaking a single referral link already in circulation. Manager-only field.","example":"7Qa2Zx9Lm4Kd1Rf6Tp0Yb3Nc8Vh5Jw"},"portal_token_rotated_at":{"type":["string","null"],"format":"date-time","description":"When the token was last rotated; null while it is still the value seeded at migration.","example":null},"portal_token_shared":{"type":"boolean","description":"True while portal_token still equals the PUBLIC referral_code (the migration backfill). Anyone who knows the code can open the report until the operator rotates.","example":false},"contact_id":{"type":["integer","null"],"description":"The Contact this affiliate IS","when the partner is someone already in the account. Mutually exclusive with user_id / organization_id.":null,"example":null},"organization_id":{"type":["integer","null"],"description":"The Organization (company) this affiliate IS. Mutually exclusive with user_id / contact_id.","example":null},"inherit_to_org_contacts":{"type":"boolean","description":"Opt-in — when the affiliate IS a company","credit it for orders from the contacts whose PRIMARY organization it is. Forward-only; off by default so nobody is credited in bulk by accident.":null,"example":false},"party_kind":{"type":"string","enum":["user","contact","organization","external"],"description":"Which of the four identities this affiliate has. 'external' means no link at all (e.g. a Hotmart partner known only by e-mail/ucode).","example":"external"},"linked_party":{"type":["object","null"],"description":"The linked record, when there is one. Deliberately only kind/id/name — an affiliate row must never become a side channel for the linked contact's e-mail, phone or address.","properties":{"kind":{"type":"string","enum":["user","contact","organization"],"example":"contact","description":"Which record type the affiliate is linked to."},"id":{"type":"integer","example":88},"name":{"type":"string","example":"Ana Souza"}},"example":null},"commission_percent":{"type":["number","null"],"description":"Flat commission percent (0–100); null when a plan drives it.","example":15.0},"commission_amount":{"type":["number","null"],"description":"Fixed (flat) commission per sale","in the order currency. Per-sale resolution":null,"most accurate first":"the SOURCE-reported value (the split Hotmart/Kiwify actually paid this affiliate) \u003e plan \u003e this fixed amount \u003e commission_percent.","example":25.0},"plan_id":{"type":["integer","null"],"description":"A commission plan that overrides commission_percent.","example":null},"status":{"type":"string","enum":["active","paused","archived"],"description":"Only an active affiliate accrues commission.","example":"active"},"metadata":{"type":"object","additionalProperties":true,"description":"Free jsonb (e.g. a preserved Hotmart affiliation payload).","example":{}},"created_at":{"type":"string","format":"date-time","example":"2026-07-10T12:00:00Z"},"updated_at":{"type":"string","format":"date-time","example":"2026-07-12T08:30:00Z"}}}},"meta":{"type":"object","properties":{"count":{"type":"integer","description":"Total affiliates in the WHOLE filtered set (not the page).","example":3},"current_page":{"type":"integer","description":"The 1-based page returned.","example":1},"total_pages":{"type":"integer","description":"Number of pages for the filtered set.","example":1},"per_page":{"type":"integer","description":"Effective page size (capped at 100).","example":25},"has_more":{"type":"boolean","description":"Whether another page exists after this one.","example":false}}}}},"example":{"payload":[{"id":42,"account_id":1,"user_id":null,"name":"João Afiliado","email":"joao@parceiro.com","external_ref":"HTM9x1ucode","referral_code":"AB12CD34","portal_token":"7Qa2Zx9Lm4Kd1Rf6Tp0Yb3Nc8Vh5Jw","portal_token_rotated_at":null,"portal_token_shared":false,"contact_id":null,"organization_id":null,"inherit_to_org_contacts":false,"party_kind":"external","linked_party":null,"commission_percent":15.0,"commission_amount":25.0,"plan_id":null,"status":"active","metadata":{},"created_at":"2026-07-10T12:00:00Z","updated_at":"2026-07-12T08:30:00Z"}],"meta":{"count":3,"current_page":1,"total_pages":1,"per_page":25,"has_more":false}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer","default":1},"description":"1-based page number."},{"name":"per_page","in":"query","required":false,"schema":{"type":"integer","default":25,"maximum":100},"description":"Page size (default 25, capped at 100)."},{"name":"q","in":"query","required":false,"schema":{"type":"string"},"description":"Case-insensitive search over name, email, referral_code and external_ref."},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["current","active","paused","archived","all"],"default":"current"},"description":"Current excludes archived rows; all lifts the status filter."}]},"post":{"tags":["Sales"],"operationId":"auto_post_api_v1_accounts_account_id_sales_affiliates","summary":"Create an affiliate","description":"Creates an internal (user_id) or external (email/external_ref) affiliate. referral_code auto-generates when blank. Requires the affiliate_program feature plus the sales-management permission.","security":[{"userApiKey":[]}],"responses":{"201":{"description":"The created affiliate.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer","example":42},"account_id":{"type":"integer","example":1},"user_id":{"type":["integer","null"],"description":"The linked User for an INTERNAL affiliate; null for an external one.","example":null},"name":{"type":"string","example":"João Afiliado"},"email":{"type":["string","null"],"example":"joao@parceiro.com"},"external_ref":{"type":["string","null"],"description":"External id / Hotmart ucode for an external affiliate.","example":"HTM9x1ucode"},"referral_code":{"type":"string","description":"Auto-generated","account-unique":null,"human-shareable code. PUBLIC — it is printed on links and material":null,"and since spec-078 it is NOT the portal credential.":null,"example":"AB12CD34"},"portal_token":{"type":"string","description":"The PRIVATE credential for the affiliate's own report (GET /sales/affiliate/:portal_token). Separate from referral_code so it can be revoked without breaking a single referral link already in circulation. Manager-only field.","example":"7Qa2Zx9Lm4Kd1Rf6Tp0Yb3Nc8Vh5Jw"},"portal_token_rotated_at":{"type":["string","null"],"format":"date-time","description":"When the token was last rotated; null while it is still the value seeded at migration.","example":null},"portal_token_shared":{"type":"boolean","description":"True while portal_token still equals the PUBLIC referral_code (the migration backfill). Anyone who knows the code can open the report until the operator rotates.","example":false},"contact_id":{"type":["integer","null"],"description":"The Contact this affiliate IS","when the partner is someone already in the account. Mutually exclusive with user_id / organization_id.":null,"example":null},"organization_id":{"type":["integer","null"],"description":"The Organization (company) this affiliate IS. Mutually exclusive with user_id / contact_id.","example":null},"inherit_to_org_contacts":{"type":"boolean","description":"Opt-in — when the affiliate IS a company","credit it for orders from the contacts whose PRIMARY organization it is. Forward-only; off by default so nobody is credited in bulk by accident.":null,"example":false},"party_kind":{"type":"string","enum":["user","contact","organization","external"],"description":"Which of the four identities this affiliate has. 'external' means no link at all (e.g. a Hotmart partner known only by e-mail/ucode).","example":"external"},"linked_party":{"type":["object","null"],"description":"The linked record, when there is one. Deliberately only kind/id/name — an affiliate row must never become a side channel for the linked contact's e-mail, phone or address.","properties":{"kind":{"type":"string","enum":["user","contact","organization"],"example":"contact","description":"Which record type the affiliate is linked to."},"id":{"type":"integer","example":88},"name":{"type":"string","example":"Ana Souza"}},"example":null},"commission_percent":{"type":["number","null"],"description":"Flat commission percent (0–100); null when a plan drives it.","example":15.0},"commission_amount":{"type":["number","null"],"description":"Fixed (flat) commission per sale","in the order currency. Per-sale resolution":null,"most accurate first":"the SOURCE-reported value (the split Hotmart/Kiwify actually paid this affiliate) \u003e plan \u003e this fixed amount \u003e commission_percent.","example":25.0},"plan_id":{"type":["integer","null"],"description":"A commission plan that overrides commission_percent.","example":null},"status":{"type":"string","enum":["active","paused","archived"],"description":"Only an active affiliate accrues commission.","example":"active"},"metadata":{"type":"object","additionalProperties":true,"description":"Free jsonb (e.g. a preserved Hotmart affiliation payload).","example":{}},"created_at":{"type":"string","format":"date-time","example":"2026-07-10T12:00:00Z"},"updated_at":{"type":"string","format":"date-time","example":"2026-07-10T12:00:00Z"}}},"example":{"id":42,"account_id":1,"user_id":null,"name":"João Afiliado","email":"joao@parceiro.com","external_ref":"HTM9x1ucode","referral_code":"AB12CD34","portal_token":"7Qa2Zx9Lm4Kd1Rf6Tp0Yb3Nc8Vh5Jw","portal_token_rotated_at":null,"portal_token_shared":false,"contact_id":null,"organization_id":null,"inherit_to_org_contacts":false,"party_kind":"external","linked_party":null,"commission_percent":15.0,"commission_amount":25.0,"plan_id":null,"status":"active","metadata":{},"created_at":"2026-07-10T12:00:00Z","updated_at":"2026-07-10T12:00:00Z"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"422":{"description":"Validation failed.","content":{"application/json":{"schema":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"string"},"description":"Human-readable validation messages.","example":["Name can't be blank"]}}},"example":{"errors":["Name can't be blank"]}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["affiliate"],"properties":{"affiliate":{"type":"object","required":["name"],"description":"The affiliate attributes to create.","properties":{"name":{"type":"string","example":"João Afiliado"},"email":{"type":["string","null"],"example":"joao@parceiro.com"},"external_ref":{"type":["string","null"],"description":"External id / Hotmart ucode.","example":"HTM9x1ucode"},"contact_id":{"type":["integer","null"],"description":"Link the affiliate to a Contact. Mutually exclusive with user_id / organization_id — sending more than one is a 422.","example":null},"organization_id":{"type":["integer","null"],"description":"Link the affiliate to an Organization (company). Mutually exclusive with user_id / contact_id.","example":null},"inherit_to_org_contacts":{"type":"boolean","description":"Opt-in — credit this company affiliate for orders from the contacts whose PRIMARY organization it is. Forward-only","off by default.":null,"example":false},"user_id":{"type":["integer","null"],"description":"Link to a User for an internal affiliate. Mutually exclusive with contact_id / organization_id.","example":null},"commission_percent":{"type":["number","null"],"description":"Flat percent 0–100 (ignored when plan_id is set).","example":15.0},"commission_amount":{"type":["number","null"],"description":"Fixed (flat) commission per sale","in the order currency. Per-sale resolution":null,"most accurate first":"the SOURCE-reported value (the split Hotmart/Kiwify actually paid this affiliate) \u003e plan \u003e this fixed amount \u003e commission_percent.","example":25.0},"plan_id":{"type":["integer","null"],"description":"A commission plan id.","example":null},"status":{"type":"string","enum":["active","paused","archived"],"default":"active","example":"active"},"referral_code":{"type":["string","null"],"description":"Optional custom code; auto-generated when blank.","example":"AB12CD34"}}}}},"example":{"affiliate":{"name":"João Afiliado","email":"joao@parceiro.com","external_ref":"HTM9x1ucode","contact_id":null,"organization_id":null,"inherit_to_org_contacts":false,"user_id":null,"commission_percent":15.0,"commission_amount":25.0,"plan_id":null,"status":"active","referral_code":"AB12CD34"}}}}}}},"/api/v1/accounts/{account_id}/sales/affiliates/{id}":{"get":{"tags":["Sales"],"operationId":"auto_get_api_v1_accounts_account_id_sales_affiliates_id","summary":"Get an affiliate","description":"A single affiliate by id. Requires the affiliate_program feature plus the sales-management permission.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The affiliate.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer","example":42},"account_id":{"type":"integer","example":1},"user_id":{"type":["integer","null"],"description":"The linked User for an INTERNAL affiliate; null for an external one.","example":null},"name":{"type":"string","example":"João Afiliado"},"email":{"type":["string","null"],"example":"joao@parceiro.com"},"external_ref":{"type":["string","null"],"description":"External id / Hotmart ucode for an external affiliate.","example":"HTM9x1ucode"},"referral_code":{"type":"string","description":"Auto-generated","account-unique":null,"human-shareable code. PUBLIC — it is printed on links and material":null,"and since spec-078 it is NOT the portal credential.":null,"example":"AB12CD34"},"portal_token":{"type":"string","description":"The PRIVATE credential for the affiliate's own report (GET /sales/affiliate/:portal_token). Separate from referral_code so it can be revoked without breaking a single referral link already in circulation. Manager-only field.","example":"7Qa2Zx9Lm4Kd1Rf6Tp0Yb3Nc8Vh5Jw"},"portal_token_rotated_at":{"type":["string","null"],"format":"date-time","description":"When the token was last rotated; null while it is still the value seeded at migration.","example":null},"portal_token_shared":{"type":"boolean","description":"True while portal_token still equals the PUBLIC referral_code (the migration backfill). Anyone who knows the code can open the report until the operator rotates.","example":false},"contact_id":{"type":["integer","null"],"description":"The Contact this affiliate IS","when the partner is someone already in the account. Mutually exclusive with user_id / organization_id.":null,"example":null},"organization_id":{"type":["integer","null"],"description":"The Organization (company) this affiliate IS. Mutually exclusive with user_id / contact_id.","example":null},"inherit_to_org_contacts":{"type":"boolean","description":"Opt-in — when the affiliate IS a company","credit it for orders from the contacts whose PRIMARY organization it is. Forward-only; off by default so nobody is credited in bulk by accident.":null,"example":false},"party_kind":{"type":"string","enum":["user","contact","organization","external"],"description":"Which of the four identities this affiliate has. 'external' means no link at all (e.g. a Hotmart partner known only by e-mail/ucode).","example":"external"},"linked_party":{"type":["object","null"],"description":"The linked record, when there is one. Deliberately only kind/id/name — an affiliate row must never become a side channel for the linked contact's e-mail, phone or address.","properties":{"kind":{"type":"string","enum":["user","contact","organization"],"example":"contact","description":"Which record type the affiliate is linked to."},"id":{"type":"integer","example":88},"name":{"type":"string","example":"Ana Souza"}},"example":null},"commission_percent":{"type":["number","null"],"description":"Flat commission percent (0–100); null when a plan drives it.","example":15.0},"commission_amount":{"type":["number","null"],"description":"Fixed (flat) commission per sale","in the order currency. Per-sale resolution":null,"most accurate first":"the SOURCE-reported value (the split Hotmart/Kiwify actually paid this affiliate) \u003e plan \u003e this fixed amount \u003e commission_percent.","example":25.0},"plan_id":{"type":["integer","null"],"description":"A commission plan that overrides commission_percent.","example":null},"status":{"type":"string","enum":["active","paused","archived"],"description":"Only an active affiliate accrues commission.","example":"active"},"metadata":{"type":"object","additionalProperties":true,"description":"Free jsonb (e.g. a preserved Hotmart affiliation payload).","example":{}},"created_at":{"type":"string","format":"date-time","example":"2026-07-10T12:00:00Z"},"updated_at":{"type":"string","format":"date-time","example":"2026-07-12T08:30:00Z"}}},"example":{"id":42,"account_id":1,"user_id":null,"name":"João Afiliado","email":"joao@parceiro.com","external_ref":"HTM9x1ucode","referral_code":"AB12CD34","portal_token":"7Qa2Zx9Lm4Kd1Rf6Tp0Yb3Nc8Vh5Jw","portal_token_rotated_at":null,"portal_token_shared":false,"contact_id":null,"organization_id":null,"inherit_to_org_contacts":false,"party_kind":"external","linked_party":null,"commission_percent":15.0,"commission_amount":25.0,"plan_id":null,"status":"active","metadata":{},"created_at":"2026-07-10T12:00:00Z","updated_at":"2026-07-12T08:30:00Z"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]},"patch":{"tags":["Sales"],"operationId":"auto_patch_api_v1_accounts_account_id_sales_affiliates_id","summary":"Update an affiliate","description":"Updates the mutable affiliate attributes (all optional). Requires the affiliate_program feature plus the sales-management permission.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The updated affiliate.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer","example":42},"account_id":{"type":"integer","example":1},"user_id":{"type":["integer","null"],"description":"The linked User for an INTERNAL affiliate; null for an external one.","example":null},"name":{"type":"string","example":"João Afiliado"},"email":{"type":["string","null"],"example":"joao@parceiro.com"},"external_ref":{"type":["string","null"],"description":"External id / Hotmart ucode for an external affiliate.","example":"HTM9x1ucode"},"referral_code":{"type":"string","description":"Auto-generated","account-unique":null,"human-shareable code. PUBLIC — it is printed on links and material":null,"and since spec-078 it is NOT the portal credential.":null,"example":"AB12CD34"},"portal_token":{"type":"string","description":"The PRIVATE credential for the affiliate's own report (GET /sales/affiliate/:portal_token). Separate from referral_code so it can be revoked without breaking a single referral link already in circulation. Manager-only field.","example":"7Qa2Zx9Lm4Kd1Rf6Tp0Yb3Nc8Vh5Jw"},"portal_token_rotated_at":{"type":["string","null"],"format":"date-time","description":"When the token was last rotated; null while it is still the value seeded at migration.","example":null},"portal_token_shared":{"type":"boolean","description":"True while portal_token still equals the PUBLIC referral_code (the migration backfill). Anyone who knows the code can open the report until the operator rotates.","example":false},"contact_id":{"type":["integer","null"],"description":"The Contact this affiliate IS","when the partner is someone already in the account. Mutually exclusive with user_id / organization_id.":null,"example":null},"organization_id":{"type":["integer","null"],"description":"The Organization (company) this affiliate IS. Mutually exclusive with user_id / contact_id.","example":null},"inherit_to_org_contacts":{"type":"boolean","description":"Opt-in — when the affiliate IS a company","credit it for orders from the contacts whose PRIMARY organization it is. Forward-only; off by default so nobody is credited in bulk by accident.":null,"example":false},"party_kind":{"type":"string","enum":["user","contact","organization","external"],"description":"Which of the four identities this affiliate has. 'external' means no link at all (e.g. a Hotmart partner known only by e-mail/ucode).","example":"external"},"linked_party":{"type":["object","null"],"description":"The linked record, when there is one. Deliberately only kind/id/name — an affiliate row must never become a side channel for the linked contact's e-mail, phone or address.","properties":{"kind":{"type":"string","enum":["user","contact","organization"],"example":"contact","description":"Which record type the affiliate is linked to."},"id":{"type":"integer","example":88},"name":{"type":"string","example":"Ana Souza"}},"example":null},"commission_percent":{"type":["number","null"],"description":"Flat commission percent (0–100); null when a plan drives it.","example":20.0},"commission_amount":{"type":["number","null"],"description":"Fixed (flat) commission per sale","in the order currency. Per-sale resolution":null,"most accurate first":"the SOURCE-reported value (the split Hotmart/Kiwify actually paid this affiliate) \u003e plan \u003e this fixed amount \u003e commission_percent.","example":25.0},"plan_id":{"type":["integer","null"],"description":"A commission plan that overrides commission_percent.","example":null},"status":{"type":"string","enum":["active","paused","archived"],"description":"Only an active affiliate accrues commission.","example":"paused"},"metadata":{"type":"object","additionalProperties":true,"description":"Free jsonb (e.g. a preserved Hotmart affiliation payload).","example":{}},"created_at":{"type":"string","format":"date-time","example":"2026-07-10T12:00:00Z"},"updated_at":{"type":"string","format":"date-time","example":"2026-07-12T08:30:00Z"}}},"example":{"id":42,"account_id":1,"user_id":null,"name":"João Afiliado","email":"joao@parceiro.com","external_ref":"HTM9x1ucode","referral_code":"AB12CD34","portal_token":"7Qa2Zx9Lm4Kd1Rf6Tp0Yb3Nc8Vh5Jw","portal_token_rotated_at":null,"portal_token_shared":false,"contact_id":null,"organization_id":null,"inherit_to_org_contacts":false,"party_kind":"external","linked_party":null,"commission_percent":20.0,"commission_amount":25.0,"plan_id":null,"status":"paused","metadata":{},"created_at":"2026-07-10T12:00:00Z","updated_at":"2026-07-12T08:30:00Z"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"422":{"description":"Validation failed.","content":{"application/json":{"schema":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"string"},"description":"Human-readable validation messages.","example":["Status is not included in the list"]}}},"example":{"errors":["Status is not included in the list"]}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["affiliate"],"properties":{"affiliate":{"type":"object","description":"The affiliate attributes to change (any subset).","properties":{"name":{"type":"string","example":"João Afiliado"},"email":{"type":["string","null"],"example":"joao@parceiro.com"},"external_ref":{"type":["string","null"],"description":"External id / Hotmart ucode.","example":"HTM9x1ucode"},"contact_id":{"type":["integer","null"],"description":"Link the affiliate to a Contact. Mutually exclusive with user_id / organization_id — sending more than one is a 422.","example":null},"organization_id":{"type":["integer","null"],"description":"Link the affiliate to an Organization (company). Mutually exclusive with user_id / contact_id.","example":null},"inherit_to_org_contacts":{"type":"boolean","description":"Opt-in — credit this company affiliate for orders from the contacts whose PRIMARY organization it is. Forward-only","off by default.":null,"example":false},"user_id":{"type":["integer","null"],"description":"Link to a User for an internal affiliate. Mutually exclusive with contact_id / organization_id.","example":null},"commission_percent":{"type":["number","null"],"description":"Flat percent 0–100 (ignored when plan_id is set).","example":20.0},"commission_amount":{"type":["number","null"],"description":"Fixed (flat) commission per sale","in the order currency. Per-sale resolution":null,"most accurate first":"the SOURCE-reported value (the split Hotmart/Kiwify actually paid this affiliate) \u003e plan \u003e this fixed amount \u003e commission_percent.","example":25.0},"plan_id":{"type":["integer","null"],"description":"A commission plan id.","example":null},"status":{"type":"string","enum":["active","paused","archived"],"example":"paused"},"referral_code":{"type":["string","null"],"description":"Optional custom code.","example":"AB12CD34"}}}}},"example":{"affiliate":{"name":"João Afiliado","email":"joao@parceiro.com","external_ref":"HTM9x1ucode","contact_id":null,"organization_id":null,"inherit_to_org_contacts":false,"user_id":null,"commission_percent":20.0,"commission_amount":25.0,"plan_id":null,"status":"paused","referral_code":"AB12CD34"}}}}}},"put":{"tags":["Sales"],"operationId":"auto_put_api_v1_accounts_account_id_sales_affiliates_id","summary":"Update an affiliate","description":"Updates the mutable affiliate attributes (all optional). Requires the affiliate_program feature plus the sales-management permission.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The updated affiliate.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer","example":42},"account_id":{"type":"integer","example":1},"user_id":{"type":["integer","null"],"description":"The linked User for an INTERNAL affiliate; null for an external one.","example":null},"name":{"type":"string","example":"João Afiliado"},"email":{"type":["string","null"],"example":"joao@parceiro.com"},"external_ref":{"type":["string","null"],"description":"External id / Hotmart ucode for an external affiliate.","example":"HTM9x1ucode"},"referral_code":{"type":"string","description":"Auto-generated","account-unique":null,"human-shareable code. PUBLIC — it is printed on links and material":null,"and since spec-078 it is NOT the portal credential.":null,"example":"AB12CD34"},"portal_token":{"type":"string","description":"The PRIVATE credential for the affiliate's own report (GET /sales/affiliate/:portal_token). Separate from referral_code so it can be revoked without breaking a single referral link already in circulation. Manager-only field.","example":"7Qa2Zx9Lm4Kd1Rf6Tp0Yb3Nc8Vh5Jw"},"portal_token_rotated_at":{"type":["string","null"],"format":"date-time","description":"When the token was last rotated; null while it is still the value seeded at migration.","example":null},"portal_token_shared":{"type":"boolean","description":"True while portal_token still equals the PUBLIC referral_code (the migration backfill). Anyone who knows the code can open the report until the operator rotates.","example":false},"contact_id":{"type":["integer","null"],"description":"The Contact this affiliate IS","when the partner is someone already in the account. Mutually exclusive with user_id / organization_id.":null,"example":null},"organization_id":{"type":["integer","null"],"description":"The Organization (company) this affiliate IS. Mutually exclusive with user_id / contact_id.","example":null},"inherit_to_org_contacts":{"type":"boolean","description":"Opt-in — when the affiliate IS a company","credit it for orders from the contacts whose PRIMARY organization it is. Forward-only; off by default so nobody is credited in bulk by accident.":null,"example":false},"party_kind":{"type":"string","enum":["user","contact","organization","external"],"description":"Which of the four identities this affiliate has. 'external' means no link at all (e.g. a Hotmart partner known only by e-mail/ucode).","example":"external"},"linked_party":{"type":["object","null"],"description":"The linked record, when there is one. Deliberately only kind/id/name — an affiliate row must never become a side channel for the linked contact's e-mail, phone or address.","properties":{"kind":{"type":"string","enum":["user","contact","organization"],"example":"contact","description":"Which record type the affiliate is linked to."},"id":{"type":"integer","example":88},"name":{"type":"string","example":"Ana Souza"}},"example":null},"commission_percent":{"type":["number","null"],"description":"Flat commission percent (0–100); null when a plan drives it.","example":20.0},"commission_amount":{"type":["number","null"],"description":"Fixed (flat) commission per sale","in the order currency. Per-sale resolution":null,"most accurate first":"the SOURCE-reported value (the split Hotmart/Kiwify actually paid this affiliate) \u003e plan \u003e this fixed amount \u003e commission_percent.","example":25.0},"plan_id":{"type":["integer","null"],"description":"A commission plan that overrides commission_percent.","example":null},"status":{"type":"string","enum":["active","paused","archived"],"description":"Only an active affiliate accrues commission.","example":"paused"},"metadata":{"type":"object","additionalProperties":true,"description":"Free jsonb (e.g. a preserved Hotmart affiliation payload).","example":{}},"created_at":{"type":"string","format":"date-time","example":"2026-07-10T12:00:00Z"},"updated_at":{"type":"string","format":"date-time","example":"2026-07-12T08:30:00Z"}}},"example":{"id":42,"account_id":1,"user_id":null,"name":"João Afiliado","email":"joao@parceiro.com","external_ref":"HTM9x1ucode","referral_code":"AB12CD34","portal_token":"7Qa2Zx9Lm4Kd1Rf6Tp0Yb3Nc8Vh5Jw","portal_token_rotated_at":null,"portal_token_shared":false,"contact_id":null,"organization_id":null,"inherit_to_org_contacts":false,"party_kind":"external","linked_party":null,"commission_percent":20.0,"commission_amount":25.0,"plan_id":null,"status":"paused","metadata":{},"created_at":"2026-07-10T12:00:00Z","updated_at":"2026-07-12T08:30:00Z"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"422":{"description":"Validation failed.","content":{"application/json":{"schema":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"string"},"description":"Human-readable validation messages.","example":["Status is not included in the list"]}}},"example":{"errors":["Status is not included in the list"]}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["affiliate"],"properties":{"affiliate":{"type":"object","description":"The affiliate attributes to change (any subset).","properties":{"name":{"type":"string","example":"João Afiliado"},"email":{"type":["string","null"],"example":"joao@parceiro.com"},"external_ref":{"type":["string","null"],"description":"External id / Hotmart ucode.","example":"HTM9x1ucode"},"contact_id":{"type":["integer","null"],"description":"Link the affiliate to a Contact. Mutually exclusive with user_id / organization_id — sending more than one is a 422.","example":null},"organization_id":{"type":["integer","null"],"description":"Link the affiliate to an Organization (company). Mutually exclusive with user_id / contact_id.","example":null},"inherit_to_org_contacts":{"type":"boolean","description":"Opt-in — credit this company affiliate for orders from the contacts whose PRIMARY organization it is. Forward-only","off by default.":null,"example":false},"user_id":{"type":["integer","null"],"description":"Link to a User for an internal affiliate. Mutually exclusive with contact_id / organization_id.","example":null},"commission_percent":{"type":["number","null"],"description":"Flat percent 0–100 (ignored when plan_id is set).","example":20.0},"commission_amount":{"type":["number","null"],"description":"Fixed (flat) commission per sale","in the order currency. Per-sale resolution":null,"most accurate first":"the SOURCE-reported value (the split Hotmart/Kiwify actually paid this affiliate) \u003e plan \u003e this fixed amount \u003e commission_percent.","example":25.0},"plan_id":{"type":["integer","null"],"description":"A commission plan id.","example":null},"status":{"type":"string","enum":["active","paused","archived"],"example":"paused"},"referral_code":{"type":["string","null"],"description":"Optional custom code.","example":"AB12CD34"}}}}},"example":{"affiliate":{"name":"João Afiliado","email":"joao@parceiro.com","external_ref":"HTM9x1ucode","contact_id":null,"organization_id":null,"inherit_to_org_contacts":false,"user_id":null,"commission_percent":20.0,"commission_amount":25.0,"plan_id":null,"status":"paused","referral_code":"AB12CD34"}}}}}},"delete":{"tags":["Sales"],"operationId":"auto_delete_api_v1_accounts_account_id_sales_affiliates_id","summary":"Archive an affiliate","description":"DELETE here is a SOFT archive, not a row deletion: the affiliate moves to status 'archived' and stops accruing, and nothing else changes. That is deliberate — an affiliate is a PAYEE, so destroying the row would strand the accruals and statements that reference it and leave contacts pointing at an id that no longer exists. An archived affiliate keeps its history, its statements stay readable, and its portal token stops resolving (the report is only served for an ACTIVE affiliate). Requires the affiliate_program feature plus the sales-management permission.","security":[{"userApiKey":[]}],"responses":{"204":{"description":"The affiliate was archived. No body."},"401":{"description":"Unauthorized"},"404":{"description":"No affiliate with that id in this account.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Resource could not be found"}}},"example":{"error":"Resource could not be found"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/sales/affiliate_orphan_splits/{id}/materialize":{"post":{"tags":["Sales"],"operationId":"auto_post_api_v1_accounts_account_id_sales_affiliate_orphan_splits_id_materialize","summary":"Register the affiliate behind an unmatched split","description":"Creates the affiliate the operator confirmed and closes the split against it, then attributes the split's order and books the commission. Deliberately a separate, explicit action (decision D-3): the queue NEVER creates a payee on its own, because auto-registering from an unverified webhook name is how an account ends up paying a stranger. Every field defaults from the split (name/e-mail/ucode) and every field is overridable — the operator is confirming an identity, not rubber-stamping a payload. The create and the resolution share one transaction, so a split is never marked resolved against an affiliate that failed to save. Requires the affiliate_program feature plus the sales-management permission.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"affiliate":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"user_id":{"type":"integer"},"contact_id":{"type":"integer"},"organization_id":{"type":"integer"},"inherit_to_org_contacts":{"type":"string"},"name":{"type":"string"},"email":{"type":"string","format":"email"},"external_ref":{"type":"string"},"referral_code":{"type":"string"},"portal_token":{"type":"string"},"portal_token_rotated_at":{"type":"string","format":"date-time"},"portal_token_shared":{"type":"boolean"},"commission_percent":{"type":"string"},"commission_amount":{"type":"number"},"plan_id":{"type":"integer"},"status":{"type":"string","enum":["active","paused","archived"]},"metadata":{"type":"object","additionalProperties":true,"description":"Free-form metadata bag; the key set depends on the record and context."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"party_kind":{"type":"string","enum":["user","contact","organization","external"]},"linked_party":{"type":"object","properties":{"null":{"type":"string"},"kind":{"type":"string","enum":["user","contact","organization"],"description":"Which record type the affiliate is linked to."},"id":{"type":"integer"},"name":{"type":"string"}}}}},"split":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"crm_order_id":{"type":"integer"},"affiliate_id":{"type":"integer"},"gateway":{"type":"string"},"name":{"type":"string"},"email":{"type":"string","format":"email"},"external_ref":{"type":"string"},"reported_amount":{"type":"number"},"currency":{"type":"string"},"status":{"type":"string","enum":["pending","materialized","dismissed"]},"resolved_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"},"order":{"type":"object","properties":{"null":{"type":"string"},"id":{"type":"integer"},"title":{"type":"string"},"amount":{"type":"number"},"currency":{"type":"string"},"paid_at":{"type":"string","format":"date-time"}}},"affiliate":{"type":"object","properties":{"null":{"type":"string"},"id":{"type":"integer"},"name":{"type":"string"}}}}}}},"example":{"affiliate":{"id":1,"account_id":1,"user_id":1,"contact_id":1,"organization_id":1,"inherit_to_org_contacts":"sample inherit to org contacts","name":"Sample Name","email":"agent@example.com","external_ref":"sample external ref","referral_code":"sample referral code","portal_token":"sample-token","portal_token_rotated_at":"2026-01-15T10:30:00.000Z","portal_token_shared":true,"commission_percent":"sample commission percent","commission_amount":149.9,"plan_id":1,"status":"active","metadata":{},"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","party_kind":"user","linked_party":{"null":"sample null","kind":"user","id":1,"name":"Sample Name"}},"split":{"id":1,"account_id":1,"crm_order_id":1,"affiliate_id":1,"gateway":"sample gateway","name":"Sample Name","email":"agent@example.com","external_ref":"sample external ref","reported_amount":149.9,"currency":"BRL","status":"pending","resolved_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","order":{"null":"sample null","id":1,"title":"Sample title","amount":149.9,"currency":"BRL","paid_at":"2026-01-15T10:30:00.000Z"},"affiliate":{"null":"sample null","id":1,"name":"Sample Name"}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"201":{"description":"The created affiliate and the closed split.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"affiliate":{"type":"object","description":"The new cadastro. Upsert it into the affiliates list — the page behind the dialog is already correct when it closes.","properties":{"id":{"type":"integer","example":42},"name":{"type":"string","example":"Ana Souza"},"email":{"type":["string","null"],"example":"ana@parceira.com"},"external_ref":{"type":["string","null"],"example":"HTM9x1ucode"},"referral_code":{"type":"string","example":"AB12CD34"},"status":{"type":"string","enum":["active","paused","archived"],"example":"active"}}},"split":{"type":"object","properties":{"id":{"type":"integer","example":17},"status":{"type":"string","enum":["pending","materialized","dismissed"],"example":"materialized"},"affiliate_id":{"type":"integer","example":42},"resolved_at":{"type":"string","format":"date-time","example":"2026-07-25T18:35:00Z"}}}}}}},"example":{"payload":{"affiliate":{"id":42,"name":"Ana Souza","email":"ana@parceira.com","external_ref":"HTM9x1ucode","referral_code":"AB12CD34","status":"active"},"split":{"id":17,"status":"materialized","affiliate_id":42,"resolved_at":"2026-07-25T18:35:00Z"}}}}}},"422":{"description":"The affiliate could not be created (e.g. an e-mail or external_ref already registered in this account).","content":{"application/json":{"schema":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"string"},"description":"Human-readable validation messages.","example":["Email has already been taken"]}}},"example":{"errors":["Email has already been taken"]}}}},"409":{"description":"The split was already resolved or its economic order was concurrently attributed elsewhere; no affiliate or commission was created.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","enum":["affiliate_orphan_split_resolution_conflict"],"example":"affiliate_orphan_split_resolution_conflict"}}},"example":{"error":"affiliate_orphan_split_resolution_conflict"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","description":"Overrides for the cadastro. Omit a field to accept the value the split carried.","properties":{"affiliate":{"type":"object","description":"The affiliate attributes to create.","properties":{"name":{"type":"string","description":"Defaults to the split's name","then its e-mail":null,"then a placeholder.":null,"example":"Ana Souza"},"email":{"type":["string","null"],"description":"Defaults to the split's e-mail.","example":"ana@parceira.com"},"external_ref":{"type":["string","null"],"description":"Defaults to the split's gateway id (ucode).","example":"HTM9x1ucode"},"user_id":{"type":["integer","null"],"description":"Link the new affiliate to a User. Mutually exclusive with contact_id / organization_id.","example":null},"contact_id":{"type":["integer","null"],"description":"Link the new affiliate to a Contact — the common case when a customer became a partner.","example":88},"organization_id":{"type":["integer","null"],"description":"Link the new affiliate to an Organization (company).","example":null},"inherit_to_org_contacts":{"type":"boolean","description":"Opt-in company inheritance (forward-only","off by default).":null,"example":false},"commission_percent":{"type":["number","null"],"example":15.0},"commission_amount":{"type":["number","null"],"example":null},"plan_id":{"type":["integer","null"],"example":null}}}}},"example":{"affiliate":{"name":"Ana Souza","email":"ana@parceira.com","external_ref":"HTM9x1ucode","user_id":null,"contact_id":88,"organization_id":null,"inherit_to_org_contacts":false,"commission_percent":15.0,"commission_amount":null,"plan_id":null}}}}}}},"/api/v1/accounts/{account_id}/sales/affiliate_orphan_splits":{"get":{"tags":["Sales"],"operationId":"auto_get_api_v1_accounts_account_id_sales_affiliate_orphan_splits","summary":"List unmatched external commission splits","description":"The reconciliation queue (spec-078 gap F1 / decision D-3): commission splits an external gateway (Hotmart/Kiwify) reported for someone this account has no registered affiliate for. Before this existed the reconciler simply returned nil and the split stayed buried in order.metadata with no screen and no counter, so the only symptom an operator ever saw was a commission that never appeared. Defaults to the pending rows (what still needs a decision); pass status=all or status=dismissed to review past calls. meta.count is the WHOLE filtered set, not the page. Requires the affiliate_program feature plus the sales-management permission.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"One page of unmatched splits with a whole-set count.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","example":17},"account_id":{"type":"integer","example":1},"crm_order_id":{"type":["integer","null"],"description":"The order the split rode on.","example":1001},"affiliate_id":{"type":["integer","null"],"description":"Set once an operator materialized this split into a cadastro.","example":null},"gateway":{"type":["string","null"],"example":"hotmart"},"name":{"type":["string","null"],"description":"The best label the gateway gave for the person; may be null when only an e-mail or ucode came through.","example":"Ana Souza"},"email":{"type":["string","null"],"example":"ana@parceira.com"},"external_ref":{"type":["string","null"],"description":"The gateway's own id for the person (Hotmart ucode).","example":"HTM9x1ucode"},"reported_amount":{"type":["number","null"],"description":"The commission the gateway says it paid this person (major units).","example":30.0},"currency":{"type":["string","null"],"example":"BRL"},"status":{"type":"string","enum":["pending","materialized","dismissed"],"example":"pending"},"resolved_at":{"type":["string","null"],"format":"date-time","example":null},"created_at":{"type":"string","format":"date-time","example":"2026-07-20T10:00:00Z"},"order":{"type":["object","null"],"description":"The sale the split rode on, so the candidate can be judged against a real order instead of a bare name. The untouched gateway payload is deliberately NOT exposed — it may carry buyer details that have no business on this screen.","properties":{"id":{"type":"integer","example":1001},"title":{"type":["string","null"],"example":"Curso Pro"},"amount":{"type":"number","example":300.0},"currency":{"type":["string","null"],"example":"BRL"},"paid_at":{"type":["string","null"],"format":"date-time","example":"2026-07-20T09:58:00Z"}},"example":null},"affiliate":{"type":["object","null"],"description":"Present once the split was materialized — the audit trail of which cadastro closed which gap.","properties":{"id":{"type":"integer","example":42},"name":{"type":"string","example":"Ana Souza"}},"example":null}}}},"meta":{"type":"object","properties":{"count":{"type":"integer","description":"Total splits in the WHOLE filtered set (not the page) — the queue badge must not lie about how much is left.","example":3},"current_page":{"type":"integer","example":1},"total_pages":{"type":"integer","example":1},"per_page":{"type":"integer","example":25},"has_more":{"type":"boolean","example":false}}}}},"example":{"payload":[{"id":17,"account_id":1,"crm_order_id":1001,"affiliate_id":null,"gateway":"hotmart","name":"Ana Souza","email":"ana@parceira.com","external_ref":"HTM9x1ucode","reported_amount":30.0,"currency":"BRL","status":"pending","resolved_at":null,"created_at":"2026-07-20T10:00:00Z","order":null,"affiliate":null}],"meta":{"count":3,"current_page":1,"total_pages":1,"per_page":25,"has_more":false}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["pending","materialized","dismissed","all"],"default":"pending"},"description":"Which rows to return. Omitted means pending only; 'all' lifts the filter."},{"name":"page","in":"query","required":false,"schema":{"type":"integer","default":1},"description":"1-based page number."},{"name":"per_page","in":"query","required":false,"schema":{"type":"integer","default":25,"maximum":100},"description":"Page size (default 25, capped at 100)."}]}},"/api/v1/accounts/{account_id}/sales/affiliate_orphan_splits/{id}":{"patch":{"tags":["Sales"],"operationId":"auto_patch_api_v1_accounts_account_id_sales_affiliate_orphan_splits_id","summary":"Dismiss or reopen an unmatched split","description":"The only two transitions this endpoint offers are 'dismissed' (this split needs no affiliate) and 'pending' (undo that — a wrong dismissal must not be a dead end). 'materialized' is NOT settable here: a cadastro is created through the materialize action, never by relabelling a row. Requires the affiliate_program feature plus the sales-management permission.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The updated split.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer","example":17},"status":{"type":"string","enum":["pending","materialized","dismissed"],"example":"dismissed"},"resolved_at":{"type":["string","null"],"format":"date-time","description":"Stamped on dismissal; cleared again on reopen.","example":"2026-07-25T18:30:00Z"}}}}},"example":{"payload":{"id":17,"status":"dismissed","resolved_at":"2026-07-25T18:30:00Z"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"422":{"description":"A status other than pending/dismissed was requested.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"invalid_status"}}},"example":{"error":"invalid_status"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"The transition to apply. `status` may be sent at the top level or nested under `affiliate_orphan_split`.","properties":{"status":{"type":"string","enum":["pending","dismissed"],"description":"The value dismissed closes the row with no affiliate; pending puts it back in the queue.","example":"dismissed"},"affiliate_orphan_split":{"type":"object","description":"Nested form of the same field.","properties":{"status":{"type":"string","enum":["pending","dismissed"],"example":"dismissed"}}}}},"example":{"status":"dismissed","affiliate_orphan_split":{"status":"dismissed"}}}}}},"put":{"tags":["Sales"],"operationId":"auto_put_api_v1_accounts_account_id_sales_affiliate_orphan_splits_id","summary":"Dismiss or reopen an unmatched split","description":"The only two transitions this endpoint offers are 'dismissed' (this split needs no affiliate) and 'pending' (undo that — a wrong dismissal must not be a dead end). 'materialized' is NOT settable here: a cadastro is created through the materialize action, never by relabelling a row. Requires the affiliate_program feature plus the sales-management permission.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The updated split.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer","example":17},"status":{"type":"string","enum":["pending","materialized","dismissed"],"example":"dismissed"},"resolved_at":{"type":["string","null"],"format":"date-time","description":"Stamped on dismissal; cleared again on reopen.","example":"2026-07-25T18:30:00Z"}}}}},"example":{"payload":{"id":17,"status":"dismissed","resolved_at":"2026-07-25T18:30:00Z"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"422":{"description":"A status other than pending/dismissed was requested.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"invalid_status"}}},"example":{"error":"invalid_status"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"The transition to apply. `status` may be sent at the top level or nested under `affiliate_orphan_split`.","properties":{"status":{"type":"string","enum":["pending","dismissed"],"description":"The value dismissed closes the row with no affiliate; pending puts it back in the queue.","example":"dismissed"},"affiliate_orphan_split":{"type":"object","description":"Nested form of the same field.","properties":{"status":{"type":"string","enum":["pending","dismissed"],"example":"dismissed"}}}}},"example":{"status":"dismissed","affiliate_orphan_split":{"status":"dismissed"}}}}}}},"/api/v1/accounts/{account_id}/sales/revenue/export":{"get":{"tags":["Sales"],"operationId":"auto_get_api_v1_accounts_account_id_sales_revenue_export","summary":"Export the revenue ledger as CSV","description":"Streams one row per paid order for the filtered scope and period as a CSV attachment (finance reconciliation). Same gate as the ledger read (unified_revenue_ledger + sales-management). Amounts are in MAJOR units.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"CSV attachment (text/csv) — a header row plus one line per paid order.","content":{"text/csv":{"schema":{"type":"string","format":"binary","description":"CSV whose header is order_id,paid_at,source,gateway,owner_id,affiliate_id,amount,currency followed by one line per paid order."},"example":"order_id,paid_at,source,gateway,owner_id,affiliate_id,amount,currency\n1001,2026-07-10T14:03:00Z,payments,asaas,7,42,4970.50,BRL\n1002,2026-07-11T09:20:00Z,commerce,native,7,,24.85,BRL\n"}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/sales/revenue":{"get":{"tags":["Sales"],"operationId":"auto_get_api_v1_accounts_account_id_sales_revenue","summary":"Unified revenue ledger","description":"Recognized revenue over the canonical paid orders for a period, grouped by source, by gateway, by seller (the order owner) and by affiliate. Currency-aware — one row per currency, never summed across currencies. Visibility-scoped: under sales isolation a manager sees only their cascade. Requires the unified_revenue_ledger feature plus the sales-management permission. Amounts are in MAJOR units.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The grouped revenue ledger for the requested period.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"period":{"type":"object","description":"The resolved window (defaults to the last 30 days when the params are omitted).","properties":{"start":{"type":"string","format":"date-time","example":"2026-06-13T00:00:00Z"},"end":{"type":"string","format":"date-time","example":"2026-07-13T23:59:59Z"}}},"totals":{"type":"array","description":"Total recognized revenue per currency (never summed across currencies).","items":{"type":"object","properties":{"currency":{"type":"string","description":"ISO currency code.","example":"BRL"},"amount":{"type":"number","description":"Sum of paid order amounts in major units.","example":24850.0}}}},"by_source":{"type":"array","description":"Revenue grouped by the canonical order source.","items":{"type":"object","properties":{"source":{"type":"string","enum":["manual","webhook","api","payments","commerce"],"description":"The order source that produced the sale.","example":"payments"},"currency":{"type":"string","example":"BRL"},"amount":{"type":"number","example":12010.0}}}},"by_gateway":{"type":"array","description":"Revenue grouped by the money gateway (open set — e.g. asaas, mercado_pago, hotmart, native, catalog).","items":{"type":"object","properties":{"gateway":{"type":["string","null"],"description":"Gateway identifier; null for orders without a gateway.","example":"asaas"},"currency":{"type":"string","example":"BRL"},"amount":{"type":"number","example":8300.0}}}},"by_seller":{"type":"array","description":"Revenue grouped by the crediting seller (the order owner).","items":{"type":"object","properties":{"owner_id":{"type":"integer","description":"The User who owns and was credited for the order.","example":7},"currency":{"type":"string","example":"BRL"},"amount":{"type":"number","example":15400.0}}}},"by_affiliate":{"type":"array","description":"Revenue grouped by the attributed affiliate (dual attribution — Phase 3).","items":{"type":"object","properties":{"affiliate_id":{"type":"integer","description":"The affiliate attributed to the order.","example":42},"currency":{"type":"string","example":"BRL"},"amount":{"type":"number","example":9850.0}}}}}}}},"example":{"data":{"period":{"start":"2026-06-13T00:00:00Z","end":"2026-07-13T23:59:59Z"},"totals":[{"currency":"BRL","amount":24850.0}],"by_source":[{"source":"payments","currency":"BRL","amount":12010.0}],"by_gateway":[{"gateway":"asaas","currency":"BRL","amount":8300.0}],"by_seller":[{"owner_id":7,"currency":"BRL","amount":15400.0}],"by_affiliate":[{"affiliate_id":42,"currency":"BRL","amount":9850.0}]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/sales/orders/{id}/attribute":{"post":{"tags":["Sales"],"operationId":"auto_post_api_v1_accounts_account_id_sales_orders_id_attribute","summary":"Attribute an order to a seller","description":"Manually links a canonical order to a seller (the order owner) or moves the credit between agents — the intended path for external/catalog sales (Hotmart, Kiwify, …) that reached a buyer outside any seller's portfolio. Reassigning REVERSES the previous owner's gamification points and commission and credits only the new seller through a payee-scoped event; stock, revenue, customer automations and affiliate credit are not replayed. A blank/null owner_id UNASSIGNS the order. Manager-only — requires the sales-management permission plus the unified_revenue_ledger feature. Every change is audited via the order_reattributed webhook.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The order's resolved seller after the (re)attribution.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"order_id":{"type":"integer","description":"The canonical order that was (re)attributed.","example":1001},"owner_id":{"type":["integer","null"],"description":"The crediting seller after the change; null when the order was unassigned.","example":7}}}}},"example":{"data":{"order_id":1001,"owner_id":7}}}}},"401":{"description":"The request is not authenticated.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Unauthorized"}}},"example":{"error":"Unauthorized"}}}},"404":{"description":"No order with that id exists on the account.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"not_found"}}},"example":{"error":"not_found"}}}},"403":{"description":"The user lacks the sales-management permission, or the unified_revenue_ledger feature is off.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["feature_not_enabled","forbidden"],"example":"forbidden"}}},"example":{"error":"forbidden"}}}},"422":{"description":"Validation failed (e.g. owner_id is not a User on this account).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["invalid_owner"],"example":"invalid_owner"}}},"example":{"error":"invalid_owner"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"The seller to credit for this order.","properties":{"owner_id":{"type":["integer","null"],"description":"The User id to credit as the order's seller. Blank or null unassigns the order (removes the current seller's credit).","example":7}}},"example":{"owner_id":7}}}}}},"/api/v1/accounts/{account_id}/sales/orders":{"get":{"tags":["Sales"],"operationId":"auto_get_api_v1_accounts_account_id_sales_orders","summary":"List paid orders for seller attribution","description":"Lists policy-visible paid operational orders. By default it returns only orders without a credited seller; attributed=true returns the complete paid set.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"One page of paid orders plus the total remaining attribution gap.","content":{"application/json":{"schema":{"type":"object","required":["payload","meta"],"properties":{"payload":{"type":"array","items":{"type":"object","required":["id","external_id","status","source","gateway","amount","currency","paid_at","owner_id","contact_id","contact_name","crm_item_id"],"properties":{"id":{"type":"integer","minimum":1},"external_id":{"type":["string","null"]},"status":{"type":"string","enum":["paid"]},"source":{"type":"string","enum":["manual","webhook","api","payments","commerce"]},"gateway":{"type":["string","null"]},"amount":{"type":"number","minimum":0},"currency":{"type":["string","null"],"example":"BRL"},"paid_at":{"type":["string","null"],"format":"date-time"},"owner_id":{"type":["integer","null"],"minimum":1},"contact_id":{"type":"integer","minimum":1},"contact_name":{"type":["string","null"]},"crm_item_id":{"type":["integer","null"],"minimum":1}}}},"meta":{"type":"object","required":["count","unattributed_count","current_page","total_pages","per_page"],"properties":{"count":{"type":"integer","minimum":0},"unattributed_count":{"type":"integer","minimum":0},"current_page":{"type":"integer","minimum":1},"total_pages":{"type":"integer","minimum":0},"per_page":{"type":"integer","minimum":1,"maximum":100}}}}},"example":{"payload":[{"id":1,"external_id":"sample external id","status":"paid","source":"manual","gateway":"sample gateway","amount":149.9,"currency":"BRL","paid_at":"2026-01-15T10:30:00.000Z","owner_id":1,"contact_id":1,"contact_name":"sample contact name","crm_item_id":1}],"meta":{"count":5,"unattributed_count":5,"current_page":1,"total_pages":1,"per_page":1}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"attributed","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"true includes already-attributed paid orders; false or omitted returns only the attribution gap."},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1}},{"name":"per_page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":25}}]}},"/api/v1/accounts/{account_id}/sales/sellers/overview":{"get":{"tags":["Sales"],"operationId":"auto_get_api_v1_accounts_account_id_sales_sellers_overview","summary":"Overview sellers","description":"Performs the overview operation on the targeted seller resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","properties":{"owner_id":{"type":"integer"},"name":{"type":"string"},"available_name":{"type":"string"},"thumbnail":{"type":"string"},"on_roster":{"type":"string"},"active":{"type":"boolean"},"contacts":{"type":"string"},"conversations":{"type":"string"},"deals":{"type":"string"},"revenue":{"type":"string"}}}}}},"example":{"payload":[{"owner_id":1,"name":"Sample Name","available_name":"sample available name","thumbnail":"sample thumbnail","on_roster":"sample on roster","active":true,"contacts":"sample contacts","conversations":"sample conversations","deals":"sample deals","revenue":"sample revenue"}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/sales/sellers/{id}/deactivate":{"post":{"tags":["Sales"],"operationId":"auto_post_api_v1_accounts_account_id_sales_sellers_id_deactivate","summary":"Remove a seller from the active roster","description":"Idempotently deactivates the roster entry while preserving portfolio and financial history.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The inactive seller roster entry."},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/sales/sellers/{id}/reactivate":{"post":{"tags":["Sales"],"operationId":"auto_post_api_v1_accounts_account_id_sales_sellers_id_reactivate","summary":"Restore a seller to the active roster","description":"Idempotently reactivates the roster entry so it can receive new work again.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The active seller roster entry."},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/sales/sellers/{id}/purge":{"delete":{"tags":["Sales"],"operationId":"auto_delete_api_v1_accounts_account_id_sales_sellers_id_purge","summary":"Delete a seller roster entry permanently","description":"Permanently deletes only an inactive roster entry whose user has no portfolio, goals, transfers or financial history in this account. The user's account membership is never deleted.","security":[{"userApiKey":[]}],"responses":{"204":{"description":"The unused inactive roster entry was permanently deleted."},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"409":{"description":"Historical references block permanent deletion; the body includes blocker counts."},"422":{"description":"The seller must be inactive first."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/sales/sellers":{"get":{"tags":["Sales"],"operationId":"auto_get_api_v1_accounts_account_id_sales_sellers","summary":"List the seller roster","description":"Lists account members explicitly registered as sellers, with optional status and text filters.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The filtered seller roster.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","example":12},"user_id":{"type":"integer","example":7},"name":{"type":"string","example":"Ana Vendedora"},"active":{"type":"boolean","example":true},"joined_at":{"type":["string","null"],"format":"date-time"},"left_at":{"type":["string","null"],"format":"date-time"}}}},"meta":{"type":"object","properties":{"roster_configured":{"type":"boolean","example":true}}}}},"example":{"payload":[{"id":12,"user_id":7,"name":"Ana Vendedora","active":true,"joined_at":"2026-08-01T12:00:00Z","left_at":null}],"meta":{"roster_configured":true}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["all","active","inactive"],"default":"all"}},{"name":"q","in":"query","required":false,"schema":{"type":"string"},"description":"Case-insensitive search over the seller name or email."}]},"post":{"tags":["Sales"],"operationId":"auto_post_api_v1_accounts_account_id_sales_sellers","summary":"Create sellers","description":"Creates a new seller from the request payload. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"user_id":{"type":"integer"},"active":{"type":"boolean"},"joined_at":{"type":"string","format":"date-time"},"left_at":{"type":"string","format":"date-time"},"commission_plan_id":{"type":"integer"},"metadata":{"type":"object","additionalProperties":true,"description":"Free-form metadata bag; the key set depends on the record and context."},"name":{"type":["string","null"]},"available_name":{"type":["string","null"]},"thumbnail":{"type":["string","null"]},"email":{"type":["string","null"],"format":"email"}}}}},"example":{"payload":{"id":1,"user_id":1,"active":true,"joined_at":"2026-01-15T10:30:00.000Z","left_at":"2026-01-15T10:30:00.000Z","commission_plan_id":1,"metadata":{},"name":"Sample Name","available_name":"sample available name","thumbnail":"sample thumbnail","email":"agent@example.com"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"seller":{"type":"object","properties":{"user_id":{"type":"integer"},"active":{"type":"boolean"},"commission_plan_id":{"type":"integer"},"metadata":{"type":"object","additionalProperties":true,"description":"Free-form metadata bag; the key set depends on the record and context."}}}},"required":["seller"]},"example":{"seller":{"user_id":1,"active":true,"commission_plan_id":1,"metadata":{}}}}}}}},"/api/v1/accounts/{account_id}/sales/sellers/{id}":{"patch":{"tags":["Sales"],"operationId":"auto_patch_api_v1_accounts_account_id_sales_sellers_id","summary":"Update sellers","description":"Updates the seller identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"user_id":{"type":"integer"},"active":{"type":"boolean"},"joined_at":{"type":"string","format":"date-time"},"left_at":{"type":"string","format":"date-time"},"commission_plan_id":{"type":"integer"},"metadata":{"type":"object","additionalProperties":true,"description":"Free-form metadata bag; the key set depends on the record and context."},"name":{"type":["string","null"]},"available_name":{"type":["string","null"]},"thumbnail":{"type":["string","null"]},"email":{"type":["string","null"],"format":"email"}}}}},"example":{"payload":{"id":1,"user_id":1,"active":true,"joined_at":"2026-01-15T10:30:00.000Z","left_at":"2026-01-15T10:30:00.000Z","commission_plan_id":1,"metadata":{},"name":"Sample Name","available_name":"sample available name","thumbnail":"sample thumbnail","email":"agent@example.com"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"seller":{"type":"object","properties":{"user_id":{"type":"integer"},"active":{"type":"boolean"},"commission_plan_id":{"type":"integer"},"metadata":{"type":"object","additionalProperties":true,"description":"Free-form metadata bag; the key set depends on the record and context."}}}},"required":["seller"]},"example":{"seller":{"user_id":1,"active":true,"commission_plan_id":1,"metadata":{}}}}}}},"put":{"tags":["Sales"],"operationId":"auto_put_api_v1_accounts_account_id_sales_sellers_id","summary":"Update sellers","description":"Updates the seller identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"user_id":{"type":"integer"},"active":{"type":"boolean"},"joined_at":{"type":"string","format":"date-time"},"left_at":{"type":"string","format":"date-time"},"commission_plan_id":{"type":"integer"},"metadata":{"type":"object","additionalProperties":true,"description":"Free-form metadata bag; the key set depends on the record and context."},"name":{"type":["string","null"]},"available_name":{"type":["string","null"]},"thumbnail":{"type":["string","null"]},"email":{"type":["string","null"],"format":"email"}}}}},"example":{"payload":{"id":1,"user_id":1,"active":true,"joined_at":"2026-01-15T10:30:00.000Z","left_at":"2026-01-15T10:30:00.000Z","commission_plan_id":1,"metadata":{},"name":"Sample Name","available_name":"sample available name","thumbnail":"sample thumbnail","email":"agent@example.com"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"seller":{"type":"object","properties":{"user_id":{"type":"integer"},"active":{"type":"boolean"},"commission_plan_id":{"type":"integer"},"metadata":{"type":"object","additionalProperties":true,"description":"Free-form metadata bag; the key set depends on the record and context."}}}},"required":["seller"]},"example":{"seller":{"user_id":1,"active":true,"commission_plan_id":1,"metadata":{}}}}}}},"delete":{"tags":["Sales"],"operationId":"auto_delete_api_v1_accounts_account_id_sales_sellers_id","summary":"Delete sellers","description":"Deletes the seller identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Success (no content)"},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/sales/demo":{"delete":{"tags":["Sales"],"operationId":"auto_delete_api_v1_accounts_account_id_sales_demo","summary":"Delete demo","description":"Deletes the demo identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"202":{"description":"Success (no content)"},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]},"post":{"tags":["Sales"],"operationId":"auto_post_api_v1_accounts_account_id_sales_demo","summary":"Seed Sales demo data","description":"Enqueues the Sales Management demo seed for the account and returns immediately. The background job creates a full sample program — goals with their tiers, rewards, badges, a contest, a commission plan and the point events behind them — and then recomputes the leaderboard, so the surfaces have realistic data to render. The endpoint takes no request body and returns no response body: it answers 202 as soon as the job is enqueued, and the client refetches the Sales surfaces to observe the result. The DELETE sibling on the same path tears the demo data down again. Requires the sales_management feature to be enabled for the account and a caller who is an administrator or holds the sales_manage permission.","security":[{"userApiKey":[]}],"responses":{"202":{"description":"Accepted — the demo seed job was enqueued. No response body is returned; poll the Sales surfaces until the demo records appear."},"401":{"description":"Unauthorized"},"403":{"description":"The sales_management feature is disabled for the account, or the caller is neither an administrator nor a holder of the sales_manage permission.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable reason. feature_not_enabled means the account does not have the Sales Management feature turned on; forbidden means the caller lacks the required permission.","enum":["feature_not_enabled","forbidden"],"example":"forbidden"}}},"example":{"error":"forbidden"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/sales/program_pack_templates":{"get":{"tags":["Sales"],"operationId":"auto_get_api_v1_accounts_account_id_sales_program_pack_templates","summary":"List program pack templates","description":"Returns the list of program pack templates visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"string"}}},"example":{"data":"sample data"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."}]},"post":{"tags":["Sales"],"operationId":"auto_post_api_v1_accounts_account_id_sales_program_pack_templates","summary":"Create program pack templates","description":"Creates a new program pack template from the request payload. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"201":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"string"}}},"example":{"data":"sample data"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"niche":{"type":"string"}}},"example":{"niche":"sample niche"}}}}}},"/api/v1/accounts/{account_id}/sales/reports/export":{"get":{"tags":["Sales"],"operationId":"auto_get_api_v1_accounts_account_id_sales_reports_export","summary":"Export sales commissions or leaderboard history","description":"Manager-only CSV. Ranking columns value/value_unit mean points; revenue/revenue_unit preserve historical money and its currency, with unresolved for missing currency. Commission totals retain separate currency buckets.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"CSV attachment. Leaderboard header: rank,user_id,team_id,scope_type,period_type,period_start,metric,value,value_unit,revenue,revenue_unit,trend. Commission header: payee_id,payee_type,currency,period_start,period_end,status,total_accrued,total_approved,total_paid.","content":{"text/csv":{"schema":{"type":"string"},"example":"rank,user_id,team_id,scope_type,period_type,period_start,metric,value,value_unit,revenue,revenue_unit,trend\n1,7,,user,month,2026-09-01,deal_won,12.5,points,1250,BRL,0\n"}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"403":{"description":"Manager permission or feature unavailable."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"period_start","in":"query","schema":{"type":"string","format":"date"}},{"name":"payee_id","in":"query","schema":{"type":"integer"}},{"name":"metric","in":"query","schema":{"type":"string"}},{"name":"scope_type","in":"query","schema":{"type":"string","enum":["user","team"]}},{"name":"kind","in":"query","required":false,"description":"Which CSV to export. Omitted or any other value exports the commissions report.","example":"leaderboard","schema":{"type":"string","enum":["commissions","leaderboard"],"default":"commissions"}}]}},"/api/v1/accounts/{account_id}/sales/reports":{"get":{"tags":["Sales"],"operationId":"auto_get_api_v1_accounts_account_id_sales_reports","summary":"Read sales attainment, payouts and ranking history","description":"Manager-only report. Ranking value remains points; revenue is independent money in the persisted row currency. A null currency must be presented as unresolved. Filters operate on stored date periods, not a new timezone conversion. Attainment rows currently carry score_kind but no currency; do not infer one.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Report sections under data (not payload).","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"attainment":{"type":"array","items":{"type":"object","properties":{"goal":{"type":"string"},"scope_id":{"type":["integer","null"]},"attainment_pct":{"type":"number"},"actual_value":{"type":"number"},"computed_at":{"type":["string","null"],"format":"date-time"},"metric":{"type":"string"},"score_kind":{"type":"string","enum":["money","points"]}}}},"payout_history":{"type":"array","items":{"type":"object","properties":{"period_start":{"type":"string","format":"date"},"currency":{"type":["string","null"],"minLength":3,"maxLength":3},"total_accrued":{"type":"number"},"total_approved":{"type":"number"},"total_paid":{"type":"number"}}}},"leaderboard_history":{"type":"array","items":{"type":"object","properties":{"period_start":{"type":"string","format":"date"},"metric":{"type":"string"},"user_id":{"type":["integer","null"]},"name":{"type":["string","null"]},"value":{"type":"number"},"value_unit":{"type":"string","enum":["points"]},"revenue":{"type":"number"},"currency":{"type":["string","null"],"minLength":3,"maxLength":3},"score_kind":{"type":"string","enum":["money","points"]}}}}}}}},"example":{"data":{"attainment":[{"goal":"sample goal","scope_id":1,"attainment_pct":12.5,"actual_value":149.9,"computed_at":"2026-01-15T10:30:00.000Z","metric":"sample metric","score_kind":"money"}],"payout_history":[{"period_start":"2026-01-15","currency":"BRL","total_accrued":12.5,"total_approved":12.5,"total_paid":12.5}],"leaderboard_history":[{"period_start":"2026-09-01","metric":"deal_won","user_id":7,"name":"Example seller","value":12.5,"value_unit":"points","revenue":1250.0,"currency":"BRL","score_kind":"points"}]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"403":{"description":"Manager permission or feature unavailable."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"period_start","in":"query","schema":{"type":"string","format":"date"}},{"name":"payee_id","in":"query","schema":{"type":"integer"}},{"name":"metric","in":"query","schema":{"type":"string"}},{"name":"scope_type","in":"query","schema":{"type":"string","enum":["user","team"]}}]}},"/api/v1/accounts/{account_id}/growth/distributions/defaults":{"get":{"tags":["Growth Distribution"],"operationId":"auto_get_api_v1_accounts_account_id_growth_distributions_defaults","summary":"Read launch distribution defaults","description":"Returns server defaults for creating a distribution, before any distribution exists. The same defaults are exposed on saved distributions. Access uses the distribution-list permission and the same feature flag. The response is a direct object with no payload wrapper. The entry-trigger catalog is a separate top-level field, not part of account_settings. Its labels and descriptions are localized for the request. Capacity defaults reflect the resolved account per-unit setting, hard cap and explicit headroom; absent overrides use 256 seats and zero headroom. configuration_options lists recognized routing sources and template identifiers beside the entry catalog. The two template selectors currently have no send consumer; these identifiers authorize neither a send nor a promise of delivery.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Current setup capabilities, setup pacing, capacity and WhatsApp Web outbound defaults.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["setup_capabilities","setup_pause_defaults","capacity_defaults","throttle_defaults","account_settings","entry_trigger_catalog","configuration_options"],"properties":{"setup_capabilities":{"type":"object","description":"Birth-setting support by step. Only live capabilities support the listed destination types; partial_contract is unavailable.","additionalProperties":{"type":"object","additionalProperties":false,"required":["tier","target_types"],"properties":{"tier":{"type":"string","enum":["live","partial_contract"]},"target_types":{"type":"array","items":{"type":"string","enum":["group","community"]}}}},"example":{"join_approval":{"tier":"partial_contract","target_types":["group","community"]},"locked":{"tier":"live","target_types":["group","community"]},"member_add_mode":{"tier":"partial_contract","target_types":["group","community"]},"ephemeral":{"tier":"live","target_types":["group","community"]}}},"entry_trigger_catalog":{"type":"array","description":"Complete list of selectable entry keys, shared with server validation. Text is localized for the request. Translation keys belong to the server translation catalog. Availability of a key does not guarantee an event producer, an eligible contact or an enrollment effect.","items":{"type":"object","additionalProperties":false,"required":["key","label_key","description_key","label","description"],"properties":{"key":{"type":"string","description":"A selectable launch distribution entry key backed by an enrollment consumer. Payment confirmed emissions use payment_charge.paid.","enum":["payment_charge.paid","payment_charge.overdue","crm_item.stage_changed","crm_item.stale","crm_item.won","task.overdue","task.due_soon","calendar_event.created","calendar_event.no_show","commerce.cart_abandoned","commerce.order_placed","commerce.payment_pending","commerce.payment_confirmed","commerce.payment_declined","commerce.overdue","commerce.due_soon","commerce.refunded","commerce.chargeback","commerce.subscription_late","commerce.subscription_canceled","ads.lead_captured","social.comment_captured"],"example":"payment_charge.paid"},"label_key":{"type":"string","description":"Server translation key for the label.","example":"growth.distribution.entry_triggers.events.payment_charge_paid.label"},"description_key":{"type":"string","description":"Server translation key for the description.","example":"growth.distribution.entry_triggers.events.payment_charge_paid.description"},"label":{"type":"string","description":"Localized label.","example":"Charge paid"},"description":{"type":"string","description":"Localized explanation of the entry signal.","example":"A confirmed or paid charge payment, admitted through the payment_charge.paid key."}}},"example":[{"key":"payment_charge.paid","label_key":"growth.distribution.entry_triggers.events.payment_charge_paid.label","description_key":"growth.distribution.entry_triggers.events.payment_charge_paid.description","label":"Charge paid","description":"A confirmed or paid charge payment, admitted through the payment_charge.paid key."}]},"configuration_options":{"type":"object","additionalProperties":false,"required":["routing_sources","template_keys"],"description":"Recognized routing sources and stored template identifiers from the same server sets used by validation. Template membership does not imply a send: the join-template and overdue-warning selectors currently have no operational send consumer and must be presented as unavailable.","properties":{"routing_sources":{"type":"array","items":{"type":"string","enum":["link","automation","event","manual","api","follow_up"]}},"template_keys":{"type":"array","items":{"type":"string","enum":["welcome","reminder","countdown","unit_opened","waitlist_ack","removed_notice","graduated_notice"]}}},"example":{"routing_sources":["link","automation","event","manual","api","follow_up"],"template_keys":["welcome","reminder","countdown","unit_opened","waitlist_ack","removed_notice","graduated_notice"]}},"setup_pause_defaults":{"type":"object","additionalProperties":false,"required":["default_seconds","jitter_seconds","max_seconds"],"description":"Server defaults and operator bounds for setup pacing. Jitter is added only to positive pauses.","properties":{"default_seconds":{"type":"integer","minimum":0,"description":"Base pause inherited when no override is set.","example":3},"jitter_seconds":{"type":"integer","minimum":0,"description":"Maximum random delay added to a positive base pause.","example":2},"max_seconds":{"type":"integer","minimum":0,"description":"Maximum configurable base pause before jitter.","example":60}},"example":{"default_seconds":3,"jitter_seconds":2,"max_seconds":60}},"capacity_defaults":{"type":"object","additionalProperties":false,"required":["default","maximum","effective_maximum","hard_cap","headroom"],"description":"Resolved capacity limits. On defaults, default is the account per-unit setting; on distribution resources it is the product default of 256. Effective maximum is min(1023, hard_cap minus headroom). An existing explicit per-unit setting is preserved when the account defaults change.","properties":{"default":{"type":"integer","minimum":1,"maximum":1023,"example":256},"maximum":{"type":"integer","description":"Maximum accepted capacity per launch group.","example":1023},"effective_maximum":{"type":"integer","minimum":0,"maximum":1023,"description":"Maximum after applying the resolved hard cap and explicit headroom.","example":1023},"hard_cap":{"type":"integer","minimum":1,"maximum":1024,"description":"Hard cap resolved from the account and distribution settings.","example":1024},"headroom":{"type":"integer","minimum":0,"maximum":1023,"description":"Explicit seat margin; absent overrides use the product margin of zero.","example":0}}},"throttle_defaults":{"type":"object","additionalProperties":false,"required":["second","hour"],"description":"Default outbound limits for WhatsApp Web; operator overrides are kept in settings.","properties":{"second":{"type":"integer","example":1},"hour":{"type":"integer","example":240}}},"account_settings":{"type":"object","additionalProperties":false,"required":["capacity","algorithm","rotation","fallback","schedule","reentry","post_purchase","sellers","dm_on_join","templates","branding","attribution","api","join_approval","setup"],"properties":{"capacity":{"type":"object","additionalProperties":{"type":"object","additionalProperties":false,"required":["value","layer","default","inherited"],"properties":{"value":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."},"layer":{"type":"string","enum":["default","account","distribution","unit"],"example":"distribution"},"default":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."},"inherited":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."}}},"description":"All current capacity configuration keys with their effective and inherited values."},"algorithm":{"type":"object","additionalProperties":{"type":"object","additionalProperties":false,"required":["value","layer","default","inherited"],"properties":{"value":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."},"layer":{"type":"string","enum":["default","account","distribution","unit"],"example":"distribution"},"default":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."},"inherited":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."}}},"description":"All current algorithm configuration keys with their effective and inherited values."},"rotation":{"type":"object","additionalProperties":{"type":"object","additionalProperties":false,"required":["value","layer","default","inherited"],"properties":{"value":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."},"layer":{"type":"string","enum":["default","account","distribution","unit"],"example":"distribution"},"default":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."},"inherited":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."}}},"description":"All current rotation configuration keys with their effective and inherited values."},"fallback":{"type":"object","additionalProperties":{"type":"object","additionalProperties":false,"required":["value","layer","default","inherited"],"properties":{"value":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."},"layer":{"type":"string","enum":["default","account","distribution","unit"],"example":"distribution"},"default":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."},"inherited":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."}}},"description":"All current fallback configuration keys with their effective and inherited values."},"schedule":{"type":"object","additionalProperties":{"type":"object","additionalProperties":false,"required":["value","layer","default","inherited"],"properties":{"value":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."},"layer":{"type":"string","enum":["default","account","distribution","unit"],"example":"distribution"},"default":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."},"inherited":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."}}},"description":"All current schedule configuration keys with their effective and inherited values."},"reentry":{"type":"object","additionalProperties":{"type":"object","additionalProperties":false,"required":["value","layer","default","inherited"],"properties":{"value":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."},"layer":{"type":"string","enum":["default","account","distribution","unit"],"example":"distribution"},"default":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."},"inherited":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."}}},"description":"All current reentry configuration keys with their effective and inherited values."},"post_purchase":{"type":"object","additionalProperties":{"type":"object","additionalProperties":false,"required":["value","layer","default","inherited"],"properties":{"value":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."},"layer":{"type":"string","enum":["default","account","distribution","unit"],"example":"distribution"},"default":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."},"inherited":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."}}},"description":"All current post_purchase configuration keys with their effective and inherited values."},"sellers":{"type":"object","additionalProperties":{"type":"object","additionalProperties":false,"required":["value","layer","default","inherited"],"properties":{"value":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."},"layer":{"type":"string","enum":["default","account","distribution","unit"],"example":"distribution"},"default":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."},"inherited":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."}}},"description":"All current sellers configuration keys with their effective and inherited values."},"dm_on_join":{"type":"object","additionalProperties":{"type":"object","additionalProperties":false,"required":["value","layer","default","inherited"],"properties":{"value":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."},"layer":{"type":"string","enum":["default","account","distribution","unit"],"example":"distribution"},"default":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."},"inherited":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."}}},"description":"All current dm_on_join configuration keys with their effective and inherited values."},"templates":{"type":"object","additionalProperties":{"type":"object","additionalProperties":false,"required":["value","layer","default","inherited"],"properties":{"value":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."},"layer":{"type":"string","enum":["default","account","distribution","unit"],"example":"distribution"},"default":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."},"inherited":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."}}},"description":"All current templates configuration keys with their effective and inherited values."},"branding":{"type":"object","additionalProperties":{"type":"object","additionalProperties":false,"required":["value","layer","default","inherited"],"properties":{"value":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."},"layer":{"type":"string","enum":["default","account","distribution","unit"],"example":"distribution"},"default":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."},"inherited":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."}}},"description":"All current branding configuration keys with their effective and inherited values."},"attribution":{"type":"object","additionalProperties":{"type":"object","additionalProperties":false,"required":["value","layer","default","inherited"],"properties":{"value":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."},"layer":{"type":"string","enum":["default","account","distribution","unit"],"example":"distribution"},"default":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."},"inherited":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."}}},"description":"All current attribution configuration keys with their effective and inherited values."},"api":{"type":"object","additionalProperties":{"type":"object","additionalProperties":false,"required":["value","layer","default","inherited"],"properties":{"value":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."},"layer":{"type":"string","enum":["default","account","distribution","unit"],"example":"distribution"},"default":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."},"inherited":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."}}},"description":"All current api configuration keys with their effective and inherited values."},"join_approval":{"type":"object","additionalProperties":{"type":"object","additionalProperties":false,"required":["value","layer","default","inherited"],"properties":{"value":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."},"layer":{"type":"string","enum":["default","account","distribution","unit"],"example":"distribution"},"default":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."},"inherited":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."}}},"description":"All current join_approval configuration keys with their effective and inherited values."},"setup":{"type":"object","additionalProperties":{"type":"object","additionalProperties":false,"required":["value","layer","default","inherited"],"properties":{"value":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."},"layer":{"type":"string","enum":["default","account","distribution","unit"],"example":"distribution"},"default":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."},"inherited":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."}}},"description":"All current setup configuration keys with their effective and inherited values."}},"description":"The account layer every distribution and unit inherits, with each key's value, origin (default or account), shipped default and inherited value. schedule.opens_at, schedule.closes_at and fallback.distribution_id always show the default layer, and post_purchase.on_paid never carries an account move_to_distribution_id: those belong to each distribution."}}},"example":{"setup_capabilities":{"join_approval":{"tier":"partial_contract","target_types":["group","community"]},"locked":{"tier":"live","target_types":["group","community"]},"member_add_mode":{"tier":"partial_contract","target_types":["group","community"]},"ephemeral":{"tier":"live","target_types":["group","community"]}},"setup_pause_defaults":{"default_seconds":3,"jitter_seconds":2,"max_seconds":60},"entry_trigger_catalog":[{"key":"payment_charge.paid","label_key":"growth.distribution.entry_triggers.events.payment_charge_paid.label","description_key":"growth.distribution.entry_triggers.events.payment_charge_paid.description","label":"Charge paid","description":"A confirmed or paid charge payment, admitted through the payment_charge.paid key."}],"configuration_options":{"routing_sources":["link","automation","event","manual","api","follow_up"],"template_keys":["welcome","reminder","countdown","unit_opened","waitlist_ack","removed_notice","graduated_notice"]},"capacity_defaults":{"default":256,"maximum":1023,"effective_maximum":1023,"hard_cap":1024,"headroom":0},"throttle_defaults":{"second":1,"hour":240},"account_settings":{"capacity":{"hard_cap":{"value":1024,"layer":"default","default":1024,"inherited":1024},"headroom":{"value":0,"layer":"default","default":0,"inherited":0},"per_unit":{"value":256,"layer":"default","default":256,"inherited":256},"by_inbox":{"value":{},"layer":"default","default":{},"inherited":{}},"reserve_for_waitlist":{"value":0,"layer":"default","default":0,"inherited":0}},"algorithm":{"strategy":{"value":"fill_first","layer":"default","default":"fill_first","inherited":"fill_first"},"weight":{"value":1,"layer":"default","default":1,"inherited":1},"sticky_by_contact":{"value":true,"layer":"default","default":true,"inherited":true},"routing_rules":{"value":[],"layer":"default","default":[],"inherited":[]}},"rotation":{"batch_size":{"value":10,"layer":"default","default":10,"inherited":10},"warmup_ramp":{"value":[],"layer":"default","default":[],"inherited":[]},"defer_base_seconds":{"value":30,"layer":"default","default":30,"inherited":30},"max_backoff_shift":{"value":6,"layer":"default","default":6,"inherited":6},"max_defer_attempts":{"value":8,"layer":"default","default":8,"inherited":8},"throttle":{"value":{"second":null,"hour":null},"layer":"default","default":{"second":null,"hour":null},"inherited":{"second":null,"hour":null}},"sync_interval_minutes":{"value":2,"layer":"default","default":2,"inherited":2},"scheduler_batch_size":{"value":500,"layer":"default","default":500,"inherited":500},"full_unit_reconcile_minutes":{"value":15,"layer":"account","default":10,"inherited":10}},"fallback":{"mode":{"value":"url","layer":"default","default":"url","inherited":"url"},"url":{"value":null,"layer":"default","default":null,"inherited":null},"message":{"value":"growth_distribution.public.unavailable.default_message","layer":"default","default":"growth_distribution.public.unavailable.default_message","inherited":"growth_distribution.public.unavailable.default_message"},"distribution_id":{"value":null,"layer":"default","default":null,"inherited":null},"waitlist_max":{"value":1000,"layer":"default","default":1000,"inherited":1000},"waitlist_ttl_hours":{"value":168,"layer":"default","default":168,"inherited":168},"waitlist_drain_batch":{"value":25,"layer":"default","default":25,"inherited":25}},"schedule":{"opens_at":{"value":null,"layer":"default","default":null,"inherited":null},"closes_at":{"value":null,"layer":"default","default":null,"inherited":null},"cascade_minutes":{"value":0,"layer":"default","default":0,"inherited":0},"announce_when_closed":{"value":true,"layer":"default","default":true,"inherited":true},"lock_when_closed":{"value":false,"layer":"default","default":false,"inherited":false},"warmup_window_minutes":{"value":0,"layer":"default","default":0,"inherited":0},"timezone":{"value":"America/Sao_Paulo","layer":"default","default":null,"inherited":null}},"reentry":{"allow_reentry":{"value":false,"layer":"default","default":false,"inherited":false},"cooldown_hours":{"value":24,"layer":"default","default":24,"inherited":24},"dedupe_across_units":{"value":true,"layer":"default","default":true,"inherited":true},"use_hub_blocklist":{"value":false,"layer":"default","default":false,"inherited":false},"blacklist":{"value":[],"layer":"default","default":[],"inherited":[]},"whitelist":{"value":[],"layer":"default","default":[],"inherited":[]},"reopen_on_leave":{"value":true,"layer":"default","default":true,"inherited":true}},"post_purchase":{"on_paid":{"value":{"remove":false,"move_to_distribution_id":null,"delay_minutes":0},"layer":"default","default":{"remove":false,"move_to_distribution_id":null,"delay_minutes":0},"inherited":{"remove":false,"move_to_distribution_id":null,"delay_minutes":0}},"on_overdue":{"value":{"remove":false,"after_days":3,"warn_template":"removed_notice"},"layer":"default","default":{"remove":false,"after_days":3,"warn_template":"removed_notice"},"inherited":{"remove":false,"after_days":3,"warn_template":"removed_notice"}},"on_refund":{"value":{"remove":true},"layer":"default","default":{"remove":true},"inherited":{"remove":true}},"on_chargeback":{"value":{"remove":true},"layer":"default","default":{"remove":true},"inherited":{"remove":true}},"remove_batch_size":{"value":20,"layer":"default","default":20,"inherited":20},"remove_throttle":{"value":{"second":null,"hour":null},"layer":"default","default":{"second":null,"hour":null},"inherited":{"second":null,"hour":null}}},"sellers":{"strategy":{"value":"round_robin","layer":"default","default":"round_robin","inherited":"round_robin"},"list":{"value":[],"layer":"default","default":[],"inherited":[]},"prefill_template":{"value":"growth_distribution.sellers.prefill_default","layer":"default","default":"growth_distribution.sellers.prefill_default","inherited":"growth_distribution.sellers.prefill_default"},"daily_cap_per_seller":{"value":0,"layer":"default","default":0,"inherited":0},"pause_when_offline":{"value":false,"layer":"default","default":false,"inherited":false}},"dm_on_join":{"enabled":{"value":false,"layer":"default","default":false,"inherited":false},"template":{"value":"welcome","layer":"default","default":"welcome","inherited":"welcome"},"spintax":{"value":[],"layer":"default","default":[],"inherited":[]},"delay_seconds":{"value":{"min":5,"max":45},"layer":"default","default":{"min":5,"max":45},"inherited":{"min":5,"max":45}},"per_hour_limit":{"value":60,"layer":"default","default":60,"inherited":60},"inbox_id":{"value":null,"layer":"default","default":null,"inherited":null},"fallback_inbox_id":{"value":null,"layer":"default","default":null,"inherited":null},"mode":{"value":"fixed","layer":"default","default":"fixed","inherited":"fixed"},"brief":{"value":"","layer":"default","default":"","inherited":""},"skip_if_conversation_open":{"value":true,"layer":"default","default":true,"inherited":true}},"templates":{"welcome":{"value":{"text":null,"spintax":[],"media_url":null},"layer":"default","default":{"text":null,"spintax":[],"media_url":null},"inherited":{"text":null,"spintax":[],"media_url":null}},"reminder":{"value":{"i18n_key":"growth_distribution.templates.reminder","text":null,"spintax":[],"media_url":null},"layer":"default","default":{"i18n_key":"growth_distribution.templates.reminder","text":null,"spintax":[],"media_url":null},"inherited":{"i18n_key":"growth_distribution.templates.reminder","text":null,"spintax":[],"media_url":null}},"countdown":{"value":{"i18n_key":"growth_distribution.templates.countdown","text":null,"spintax":[],"media_url":null},"layer":"default","default":{"i18n_key":"growth_distribution.templates.countdown","text":null,"spintax":[],"media_url":null},"inherited":{"i18n_key":"growth_distribution.templates.countdown","text":null,"spintax":[],"media_url":null}},"unit_opened":{"value":{"i18n_key":"growth_distribution.templates.unit_opened","text":null,"spintax":[],"media_url":null},"layer":"default","default":{"i18n_key":"growth_distribution.templates.unit_opened","text":null,"spintax":[],"media_url":null},"inherited":{"i18n_key":"growth_distribution.templates.unit_opened","text":null,"spintax":[],"media_url":null}},"waitlist_ack":{"value":{"i18n_key":"growth_distribution.templates.waitlist_ack","text":null,"spintax":[],"media_url":null},"layer":"default","default":{"i18n_key":"growth_distribution.templates.waitlist_ack","text":null,"spintax":[],"media_url":null},"inherited":{"i18n_key":"growth_distribution.templates.waitlist_ack","text":null,"spintax":[],"media_url":null}},"removed_notice":{"value":{"i18n_key":"growth_distribution.templates.removed_notice","text":null,"spintax":[],"media_url":null},"layer":"default","default":{"i18n_key":"growth_distribution.templates.removed_notice","text":null,"spintax":[],"media_url":null},"inherited":{"i18n_key":"growth_distribution.templates.removed_notice","text":null,"spintax":[],"media_url":null}},"graduated_notice":{"value":{"i18n_key":"growth_distribution.templates.graduated_notice","text":null,"spintax":[],"media_url":null},"layer":"default","default":{"i18n_key":"growth_distribution.templates.graduated_notice","text":null,"spintax":[],"media_url":null},"inherited":{"i18n_key":"growth_distribution.templates.graduated_notice","text":null,"spintax":[],"media_url":null}}},"branding":{"naming_template":{"value":"Turma {n}","layer":"default","default":"Turma {n}","inherited":"Turma {n}"},"photo_url":{"value":null,"layer":"default","default":null,"inherited":null},"description":{"value":null,"layer":"default","default":null,"inherited":null},"admins":{"value":[],"layer":"default","default":[],"inherited":[]},"announcement_group":{"value":false,"layer":"default","default":false,"inherited":false},"auto_create_channel":{"value":false,"layer":"default","default":false,"inherited":false},"auto_create_channel_live":{"value":false,"layer":"default","default":false,"inherited":false},"channel_invite_url":{"value":null,"layer":"default","default":null,"inherited":null}},"attribution":{"utm_capture":{"value":true,"layer":"default","default":true,"inherited":true},"store_referrer_host":{"value":true,"layer":"default","default":true,"inherited":true},"store_ip_hash":{"value":true,"layer":"default","default":true,"inherited":true},"capi":{"value":{"on_click":null,"on_join":null,"on_purchase":null},"layer":"default","default":{"on_click":null,"on_join":null,"on_purchase":null},"inherited":{"on_click":null,"on_join":null,"on_purchase":null}},"contact_attribute_key":{"value":"distribution_attributions","layer":"default","default":"distribution_attributions","inherited":"distribution_attributions"}},"api":{"bulk_enroll_max":{"value":500,"layer":"account","default":1000,"inherited":1000},"index_page_size":{"value":25,"layer":"default","default":25,"inherited":25},"approvals_timeout_seconds":{"value":3,"layer":"default","default":3,"inherited":3},"public_link_rate_per_minute":{"value":30,"layer":"default","default":30,"inherited":30},"export_row_limit":{"value":50000,"layer":"default","default":50000,"inherited":50000}},"join_approval":{"batch":{"value":20,"layer":"default","default":20,"inherited":20},"policy":{"value":"all_while_seats","layer":"default","default":"all_while_seats","inherited":"all_while_seats"}},"setup":{"pause_seconds":{"value":3,"layer":"default","default":3,"inherited":3},"pause_jitter_seconds":{"value":2,"layer":"default","default":2,"inherited":2},"pause_max_seconds":{"value":60,"layer":"default","default":60,"inherited":60}}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]},"patch":{"tags":["Growth Distribution"],"operationId":"auto_patch_api_v1_accounts_account_id_growth_distributions_defaults","summary":"Patch the account-wide launch distribution defaults","description":"Writes the account layer that every distribution and unit inherits unless it overrides the key. Validates the whole partial document before saving; null removes the account override. Returns the account layer with each key's value, origin (default or account), shipped default and inherited value. Absent capacity overrides use per_unit 256 and headroom zero; saved explicit margins are retained. The resolved headroom must remain smaller than hard_cap. An invalid capacity combination returns invalid_settings with keys containing capacity.headroom and does not persist the draft. Routing source and template choices use the same configuration_options sets. Only identical saved invalid values may be retained; changed invalid values are rejected and null removes an override. Canonical membership failures keep invalid_settings and submitted section.key paths, without a configuration_validation field in that error response.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Account layer of the settings with origins and inheritance.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["payload"],"properties":{"payload":{"type":"object","additionalProperties":false,"required":["capacity","algorithm","rotation","fallback","schedule","reentry","post_purchase","sellers","dm_on_join","templates","branding","attribution","api","join_approval","setup"],"properties":{"capacity":{"type":"object","additionalProperties":{"type":"object","additionalProperties":false,"required":["value","layer","default","inherited"],"properties":{"value":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."},"layer":{"type":"string","enum":["default","account","distribution","unit"],"example":"distribution"},"default":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."},"inherited":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."}}},"description":"All current capacity configuration keys with their effective and inherited values."},"algorithm":{"type":"object","additionalProperties":{"type":"object","additionalProperties":false,"required":["value","layer","default","inherited"],"properties":{"value":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."},"layer":{"type":"string","enum":["default","account","distribution","unit"],"example":"distribution"},"default":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."},"inherited":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."}}},"description":"All current algorithm configuration keys with their effective and inherited values."},"rotation":{"type":"object","additionalProperties":{"type":"object","additionalProperties":false,"required":["value","layer","default","inherited"],"properties":{"value":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."},"layer":{"type":"string","enum":["default","account","distribution","unit"],"example":"distribution"},"default":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."},"inherited":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."}}},"description":"All current rotation configuration keys with their effective and inherited values."},"fallback":{"type":"object","additionalProperties":{"type":"object","additionalProperties":false,"required":["value","layer","default","inherited"],"properties":{"value":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."},"layer":{"type":"string","enum":["default","account","distribution","unit"],"example":"distribution"},"default":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."},"inherited":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."}}},"description":"All current fallback configuration keys with their effective and inherited values."},"schedule":{"type":"object","additionalProperties":{"type":"object","additionalProperties":false,"required":["value","layer","default","inherited"],"properties":{"value":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."},"layer":{"type":"string","enum":["default","account","distribution","unit"],"example":"distribution"},"default":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."},"inherited":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."}}},"description":"All current schedule configuration keys with their effective and inherited values."},"reentry":{"type":"object","additionalProperties":{"type":"object","additionalProperties":false,"required":["value","layer","default","inherited"],"properties":{"value":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."},"layer":{"type":"string","enum":["default","account","distribution","unit"],"example":"distribution"},"default":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."},"inherited":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."}}},"description":"All current reentry configuration keys with their effective and inherited values."},"post_purchase":{"type":"object","additionalProperties":{"type":"object","additionalProperties":false,"required":["value","layer","default","inherited"],"properties":{"value":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."},"layer":{"type":"string","enum":["default","account","distribution","unit"],"example":"distribution"},"default":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."},"inherited":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."}}},"description":"All current post_purchase configuration keys with their effective and inherited values."},"sellers":{"type":"object","additionalProperties":{"type":"object","additionalProperties":false,"required":["value","layer","default","inherited"],"properties":{"value":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."},"layer":{"type":"string","enum":["default","account","distribution","unit"],"example":"distribution"},"default":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."},"inherited":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."}}},"description":"All current sellers configuration keys with their effective and inherited values."},"dm_on_join":{"type":"object","additionalProperties":{"type":"object","additionalProperties":false,"required":["value","layer","default","inherited"],"properties":{"value":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."},"layer":{"type":"string","enum":["default","account","distribution","unit"],"example":"distribution"},"default":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."},"inherited":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."}}},"description":"All current dm_on_join configuration keys with their effective and inherited values."},"templates":{"type":"object","additionalProperties":{"type":"object","additionalProperties":false,"required":["value","layer","default","inherited"],"properties":{"value":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."},"layer":{"type":"string","enum":["default","account","distribution","unit"],"example":"distribution"},"default":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."},"inherited":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."}}},"description":"All current templates configuration keys with their effective and inherited values."},"branding":{"type":"object","additionalProperties":{"type":"object","additionalProperties":false,"required":["value","layer","default","inherited"],"properties":{"value":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."},"layer":{"type":"string","enum":["default","account","distribution","unit"],"example":"distribution"},"default":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."},"inherited":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."}}},"description":"All current branding configuration keys with their effective and inherited values."},"attribution":{"type":"object","additionalProperties":{"type":"object","additionalProperties":false,"required":["value","layer","default","inherited"],"properties":{"value":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."},"layer":{"type":"string","enum":["default","account","distribution","unit"],"example":"distribution"},"default":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."},"inherited":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."}}},"description":"All current attribution configuration keys with their effective and inherited values."},"api":{"type":"object","additionalProperties":{"type":"object","additionalProperties":false,"required":["value","layer","default","inherited"],"properties":{"value":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."},"layer":{"type":"string","enum":["default","account","distribution","unit"],"example":"distribution"},"default":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."},"inherited":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."}}},"description":"All current api configuration keys with their effective and inherited values."},"join_approval":{"type":"object","additionalProperties":{"type":"object","additionalProperties":false,"required":["value","layer","default","inherited"],"properties":{"value":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."},"layer":{"type":"string","enum":["default","account","distribution","unit"],"example":"distribution"},"default":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."},"inherited":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."}}},"description":"All current join_approval configuration keys with their effective and inherited values."},"setup":{"type":"object","additionalProperties":{"type":"object","additionalProperties":false,"required":["value","layer","default","inherited"],"properties":{"value":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."},"layer":{"type":"string","enum":["default","account","distribution","unit"],"example":"distribution"},"default":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."},"inherited":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."}}},"description":"All current setup configuration keys with their effective and inherited values."}}}}},"example":{"payload":{"capacity":{"hard_cap":{"value":1024,"layer":"account","default":1024,"inherited":1024},"headroom":{"value":24,"layer":"account","default":0,"inherited":0},"per_unit":{"value":1000,"layer":"account","default":256,"inherited":256},"by_inbox":{"value":{},"layer":"account","default":{},"inherited":{}},"reserve_for_waitlist":{"value":0,"layer":"account","default":0,"inherited":0}},"algorithm":{"strategy":{"value":"fill_first","layer":"default","default":"fill_first","inherited":"fill_first"},"weight":{"value":1,"layer":"default","default":1,"inherited":1},"sticky_by_contact":{"value":true,"layer":"default","default":true,"inherited":true},"routing_rules":{"value":[],"layer":"default","default":[],"inherited":[]}},"rotation":{"batch_size":{"value":10,"layer":"default","default":10,"inherited":10},"warmup_ramp":{"value":[],"layer":"default","default":[],"inherited":[]},"defer_base_seconds":{"value":30,"layer":"default","default":30,"inherited":30},"max_backoff_shift":{"value":6,"layer":"default","default":6,"inherited":6},"max_defer_attempts":{"value":8,"layer":"default","default":8,"inherited":8},"throttle":{"value":{"second":null,"hour":null},"layer":"default","default":{"second":null,"hour":null},"inherited":{"second":null,"hour":null}},"sync_interval_minutes":{"value":2,"layer":"default","default":2,"inherited":2},"scheduler_batch_size":{"value":500,"layer":"default","default":500,"inherited":500},"full_unit_reconcile_minutes":{"value":15,"layer":"account","default":10,"inherited":10}},"fallback":{"mode":{"value":"url","layer":"default","default":"url","inherited":"url"},"url":{"value":null,"layer":"default","default":null,"inherited":null},"message":{"value":"growth_distribution.public.unavailable.default_message","layer":"default","default":"growth_distribution.public.unavailable.default_message","inherited":"growth_distribution.public.unavailable.default_message"},"distribution_id":{"value":null,"layer":"default","default":null,"inherited":null},"waitlist_max":{"value":1000,"layer":"default","default":1000,"inherited":1000},"waitlist_ttl_hours":{"value":168,"layer":"default","default":168,"inherited":168},"waitlist_drain_batch":{"value":25,"layer":"default","default":25,"inherited":25}},"schedule":{"opens_at":{"value":null,"layer":"default","default":null,"inherited":null},"closes_at":{"value":null,"layer":"default","default":null,"inherited":null},"cascade_minutes":{"value":0,"layer":"default","default":0,"inherited":0},"announce_when_closed":{"value":true,"layer":"default","default":true,"inherited":true},"lock_when_closed":{"value":false,"layer":"default","default":false,"inherited":false},"warmup_window_minutes":{"value":0,"layer":"default","default":0,"inherited":0},"timezone":{"value":"America/Sao_Paulo","layer":"default","default":null,"inherited":null}},"reentry":{"allow_reentry":{"value":false,"layer":"default","default":false,"inherited":false},"cooldown_hours":{"value":24,"layer":"default","default":24,"inherited":24},"dedupe_across_units":{"value":true,"layer":"default","default":true,"inherited":true},"use_hub_blocklist":{"value":false,"layer":"default","default":false,"inherited":false},"blacklist":{"value":[],"layer":"default","default":[],"inherited":[]},"whitelist":{"value":[],"layer":"default","default":[],"inherited":[]},"reopen_on_leave":{"value":true,"layer":"default","default":true,"inherited":true}},"post_purchase":{"on_paid":{"value":{"remove":false,"move_to_distribution_id":null,"delay_minutes":0},"layer":"default","default":{"remove":false,"move_to_distribution_id":null,"delay_minutes":0},"inherited":{"remove":false,"move_to_distribution_id":null,"delay_minutes":0}},"on_overdue":{"value":{"remove":false,"after_days":3,"warn_template":"removed_notice"},"layer":"default","default":{"remove":false,"after_days":3,"warn_template":"removed_notice"},"inherited":{"remove":false,"after_days":3,"warn_template":"removed_notice"}},"on_refund":{"value":{"remove":true},"layer":"default","default":{"remove":true},"inherited":{"remove":true}},"on_chargeback":{"value":{"remove":true},"layer":"default","default":{"remove":true},"inherited":{"remove":true}},"remove_batch_size":{"value":20,"layer":"default","default":20,"inherited":20},"remove_throttle":{"value":{"second":null,"hour":null},"layer":"default","default":{"second":null,"hour":null},"inherited":{"second":null,"hour":null}}},"sellers":{"strategy":{"value":"round_robin","layer":"default","default":"round_robin","inherited":"round_robin"},"list":{"value":[],"layer":"default","default":[],"inherited":[]},"prefill_template":{"value":"growth_distribution.sellers.prefill_default","layer":"default","default":"growth_distribution.sellers.prefill_default","inherited":"growth_distribution.sellers.prefill_default"},"daily_cap_per_seller":{"value":0,"layer":"default","default":0,"inherited":0},"pause_when_offline":{"value":false,"layer":"default","default":false,"inherited":false}},"dm_on_join":{"enabled":{"value":false,"layer":"default","default":false,"inherited":false},"template":{"value":"welcome","layer":"default","default":"welcome","inherited":"welcome"},"spintax":{"value":[],"layer":"default","default":[],"inherited":[]},"delay_seconds":{"value":{"min":5,"max":45},"layer":"default","default":{"min":5,"max":45},"inherited":{"min":5,"max":45}},"per_hour_limit":{"value":60,"layer":"default","default":60,"inherited":60},"inbox_id":{"value":null,"layer":"default","default":null,"inherited":null},"fallback_inbox_id":{"value":null,"layer":"default","default":null,"inherited":null},"mode":{"value":"fixed","layer":"default","default":"fixed","inherited":"fixed"},"brief":{"value":"","layer":"default","default":"","inherited":""},"skip_if_conversation_open":{"value":true,"layer":"default","default":true,"inherited":true}},"templates":{"welcome":{"value":{"text":null,"spintax":[],"media_url":null},"layer":"default","default":{"text":null,"spintax":[],"media_url":null},"inherited":{"text":null,"spintax":[],"media_url":null}},"reminder":{"value":{"i18n_key":"growth_distribution.templates.reminder","text":null,"spintax":[],"media_url":null},"layer":"default","default":{"i18n_key":"growth_distribution.templates.reminder","text":null,"spintax":[],"media_url":null},"inherited":{"i18n_key":"growth_distribution.templates.reminder","text":null,"spintax":[],"media_url":null}},"countdown":{"value":{"i18n_key":"growth_distribution.templates.countdown","text":null,"spintax":[],"media_url":null},"layer":"default","default":{"i18n_key":"growth_distribution.templates.countdown","text":null,"spintax":[],"media_url":null},"inherited":{"i18n_key":"growth_distribution.templates.countdown","text":null,"spintax":[],"media_url":null}},"unit_opened":{"value":{"i18n_key":"growth_distribution.templates.unit_opened","text":null,"spintax":[],"media_url":null},"layer":"default","default":{"i18n_key":"growth_distribution.templates.unit_opened","text":null,"spintax":[],"media_url":null},"inherited":{"i18n_key":"growth_distribution.templates.unit_opened","text":null,"spintax":[],"media_url":null}},"waitlist_ack":{"value":{"i18n_key":"growth_distribution.templates.waitlist_ack","text":null,"spintax":[],"media_url":null},"layer":"default","default":{"i18n_key":"growth_distribution.templates.waitlist_ack","text":null,"spintax":[],"media_url":null},"inherited":{"i18n_key":"growth_distribution.templates.waitlist_ack","text":null,"spintax":[],"media_url":null}},"removed_notice":{"value":{"i18n_key":"growth_distribution.templates.removed_notice","text":null,"spintax":[],"media_url":null},"layer":"default","default":{"i18n_key":"growth_distribution.templates.removed_notice","text":null,"spintax":[],"media_url":null},"inherited":{"i18n_key":"growth_distribution.templates.removed_notice","text":null,"spintax":[],"media_url":null}},"graduated_notice":{"value":{"i18n_key":"growth_distribution.templates.graduated_notice","text":null,"spintax":[],"media_url":null},"layer":"default","default":{"i18n_key":"growth_distribution.templates.graduated_notice","text":null,"spintax":[],"media_url":null},"inherited":{"i18n_key":"growth_distribution.templates.graduated_notice","text":null,"spintax":[],"media_url":null}}},"branding":{"naming_template":{"value":"Turma {n}","layer":"default","default":"Turma {n}","inherited":"Turma {n}"},"photo_url":{"value":null,"layer":"default","default":null,"inherited":null},"description":{"value":null,"layer":"default","default":null,"inherited":null},"admins":{"value":[],"layer":"default","default":[],"inherited":[]},"announcement_group":{"value":false,"layer":"default","default":false,"inherited":false},"auto_create_channel":{"value":false,"layer":"default","default":false,"inherited":false},"auto_create_channel_live":{"value":false,"layer":"default","default":false,"inherited":false},"channel_invite_url":{"value":null,"layer":"default","default":null,"inherited":null}},"attribution":{"utm_capture":{"value":true,"layer":"default","default":true,"inherited":true},"store_referrer_host":{"value":true,"layer":"default","default":true,"inherited":true},"store_ip_hash":{"value":true,"layer":"default","default":true,"inherited":true},"capi":{"value":{"on_click":null,"on_join":null,"on_purchase":null},"layer":"default","default":{"on_click":null,"on_join":null,"on_purchase":null},"inherited":{"on_click":null,"on_join":null,"on_purchase":null}},"contact_attribute_key":{"value":"distribution_attributions","layer":"default","default":"distribution_attributions","inherited":"distribution_attributions"}},"api":{"bulk_enroll_max":{"value":500,"layer":"account","default":1000,"inherited":1000},"index_page_size":{"value":25,"layer":"default","default":25,"inherited":25},"approvals_timeout_seconds":{"value":3,"layer":"default","default":3,"inherited":3},"public_link_rate_per_minute":{"value":30,"layer":"default","default":30,"inherited":30},"export_row_limit":{"value":50000,"layer":"default","default":50000,"inherited":50000}},"join_approval":{"batch":{"value":20,"layer":"default","default":20,"inherited":20},"policy":{"value":"all_while_seats","layer":"default","default":"all_while_seats","inherited":"all_while_seats"}},"setup":{"pause_seconds":{"value":3,"layer":"default","default":3,"inherited":3},"pause_jitter_seconds":{"value":2,"layer":"default","default":2,"inherited":2},"pause_max_seconds":{"value":60,"layer":"default","default":60,"inherited":60}}}}}}},"401":{"description":"Administrator access is required."},"404":{"description":"Account or resource not found"},"403":{"description":"The launch distribution feature is not enabled."},"422":{"description":"Invalid overrides; no changes are persisted. Distribution-only keys are checked first: a non-null value for any of them answers class_scoped_settings before the document is validated, and a null for them is accepted. Otherwise an invalid document answers invalid_settings.","content":{"application/json":{"schema":{"oneOf":[{"type":"object","additionalProperties":false,"required":["error","keys","message"],"properties":{"error":{"type":"string","enum":["class_scoped_settings"],"example":"class_scoped_settings"},"keys":{"type":"array","description":"The distribution-only keys that carried a value, in this fixed order and without duplicates.","items":{"type":"string","enum":["schedule.opens_at","schedule.closes_at","fallback.distribution_id","post_purchase.on_paid.move_to_distribution_id"]},"example":["schedule.opens_at","fallback.distribution_id"]},"message":{"type":"string","description":"Translated explanation of where these keys are set."}}},{"type":"object","additionalProperties":false,"required":["error","keys"],"properties":{"error":{"type":"string","enum":["invalid_settings"],"example":"invalid_settings"},"keys":{"type":"array","description":"Rejected section or section.key paths, in submission order without duplicates.","items":{"type":"string"},"example":["api.bulk_enroll_max"]}}}]},"examples":{"class_scoped":{"value":{"error":"class_scoped_settings","keys":["schedule.opens_at","fallback.distribution_id"],"message":"The opening and closing times, the other launch group that takes leads when there is no seat, and the students' group after a purchase are set on each launch group, not in the account defaults."}},"invalid":{"value":{"error":"invalid_settings","keys":["api.bulk_enroll_max"],"message":"Sample message text."}}}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["settings"],"properties":{"settings":{"type":"object","additionalProperties":false,"description":"Partial override document for the account layer, inherited by every distribution and unit that does not override the key. Same sections, keys and value types as the distribution settings document; null removes the account override. The account-scoped full_unit_reconcile_minutes is writable only here. The distribution-only keys schedule.opens_at, schedule.closes_at, fallback.distribution_id and post_purchase.on_paid.move_to_distribution_id accept only null here.","properties":{"capacity":{"type":"object","additionalProperties":false,"properties":{"hard_cap":{"type":["integer","null"],"minimum":1,"maximum":1024},"headroom":{"type":["integer","null"],"minimum":0,"maximum":1023,"description":"Seat margin below hard_cap; the resolved margin must remain smaller than the resolved hard cap. Null inherits."},"per_unit":{"type":["integer","null"],"minimum":1,"maximum":1023},"by_inbox":{"type":["object","null"],"additionalProperties":false},"reserve_for_waitlist":{"type":["integer","null"],"minimum":0}}},"algorithm":{"type":"object","additionalProperties":false,"properties":{"strategy":{"type":["string","null"],"enum":["fill_first","round_robin","random","weighted",null]},"weight":{"type":["integer","null"],"minimum":0},"sticky_by_contact":{"type":["boolean","null"],"enum":[true,false,null]},"routing_rules":{"anyOf":[{"type":["array","null"],"description":"Ordered rules, evaluated with equality and all conditions together. New or changed lists must use recognized condition keys and member sources; an identical legacy list may remain during an unrelated update. Null removes the override. UTM values and account labels are open values.","items":{"type":"object","required":["match"],"properties":{"match":{"type":"object","additionalProperties":false,"properties":{"utm_source":{"type":"string","description":"Compared with lead attribution, ignoring case and surrounding spaces."},"utm_campaign":{"type":"string","description":"Compared with lead attribution, ignoring case and surrounding spaces."},"tag":{"type":"string","description":"Literal label from the account label catalog."},"source":{"type":"string","enum":["link","automation","event","manual","api","follow_up"],"description":"Member entry source; null and empty values are not choices."}}},"distribution_id":{"type":"integer","minimum":1,"description":"Target distribution; skipped unless it is active and not archived in the same account."}}}},{"$ref":"#/components/schemas/json_value","description":"A previously stored JSON value may be retained only when it is exactly identical to this field or complete list in the same persisted record. Equality with persisted state is enforced at runtime and cannot be expressed by this static schema alone. A new or changed invalid value is rejected; no conversion, filtering or implicit repair is performed."}]}}},"rotation":{"type":"object","additionalProperties":false,"properties":{"batch_size":{"type":["integer","null"],"minimum":0},"warmup_ramp":{"type":["array","null"],"description":"Rotation batch steps; the latest step whose after_minutes has elapsed since creation sets the batch size.","items":{"type":"object","properties":{"after_minutes":{"type":"integer","minimum":0,"description":"Minutes after the distribution was created when the step starts."},"batch":{"type":"integer","minimum":1,"description":"Rotation batch size while the step applies; a missing or zero batch keeps the flat batch_size."}}}},"defer_base_seconds":{"type":["integer","null"],"minimum":0},"max_backoff_shift":{"type":["integer","null"],"minimum":0},"max_defer_attempts":{"type":["integer","null"],"minimum":0},"throttle":{"type":["object","null"],"additionalProperties":false,"properties":{"second":{"type":["integer","null"],"minimum":0},"hour":{"type":["integer","null"],"minimum":0}}},"sync_interval_minutes":{"type":["integer","null"],"minimum":0},"scheduler_batch_size":{"type":["integer","null"],"minimum":0},"full_unit_reconcile_minutes":{"type":["integer","null"],"minimum":0}}},"fallback":{"type":"object","additionalProperties":false,"properties":{"mode":{"type":["string","null"],"enum":["url","distribution","message","waitlist",null]},"url":{"type":["string","null"],"format":"uri"},"message":{"type":["string","null"]},"distribution_id":{"type":["integer","null"],"minimum":0},"waitlist_max":{"type":["integer","null"],"minimum":0},"waitlist_ttl_hours":{"type":["integer","null"],"minimum":0},"waitlist_drain_batch":{"type":["integer","null"],"minimum":0}}},"schedule":{"type":"object","additionalProperties":false,"properties":{"opens_at":{"type":["string","null"],"format":"date-time"},"closes_at":{"type":["string","null"],"format":"date-time"},"cascade_minutes":{"type":["integer","null"],"minimum":0},"announce_when_closed":{"type":["boolean","null"],"enum":[true,false,null]},"lock_when_closed":{"type":["boolean","null"],"enum":[true,false,null]},"warmup_window_minutes":{"type":["integer","null"],"minimum":0},"timezone":{"type":"string","description":"IANA timezone identifier (e.g. \"America/Sao_Paulo\", \"UTC\"). Rails timezone names are also accepted on input; an unrecognized value is ignored in favor of the next fallback.","example":"America/Sao_Paulo"}}},"reentry":{"type":"object","additionalProperties":false,"properties":{"allow_reentry":{"type":["boolean","null"],"enum":[true,false,null]},"cooldown_hours":{"type":["integer","null"],"minimum":0},"dedupe_across_units":{"type":["boolean","null"],"enum":[true,false,null]},"use_hub_blocklist":{"type":["boolean","null"],"enum":[true,false,null]},"blacklist":{"type":["array","null"],"description":"Phone numbers refused on entry; non-digit characters are ignored.","items":{"type":["string","integer"]}},"whitelist":{"type":["array","null"],"description":"Phone numbers allowed on entry; non-digit characters are ignored.","items":{"type":["string","integer"]}},"reopen_on_leave":{"type":["boolean","null"],"enum":[true,false,null]}}},"post_purchase":{"type":"object","additionalProperties":false,"properties":{"on_paid":{"type":["object","null"],"additionalProperties":false,"properties":{"remove":{"type":["boolean","null"],"enum":[true,false,null]},"move_to_distribution_id":{"type":["integer","null"],"minimum":0},"delay_minutes":{"type":["integer","null"],"minimum":0}}},"on_overdue":{"type":["object","null"],"additionalProperties":false,"properties":{"remove":{"type":["boolean","null"],"enum":[true,false,null]},"after_days":{"type":["integer","null"],"minimum":0},"warn_template":{"anyOf":[{"type":["string","null"],"enum":["welcome","reminder","countdown","unit_opened","waitlist_ack","removed_notice","graduated_notice",null],"description":"Recognized stored template identifier. Null removes the override; an empty string is invalid. An unchanged legacy identifier may be retained on an unrelated update. This selector currently has no operational send consumer; accepting an identifier does not schedule or send a message."},{"$ref":"#/components/schemas/json_value","description":"A previously stored JSON value may be retained only when it is exactly identical to this field or complete list in the same persisted record. Equality with persisted state is enforced at runtime and cannot be expressed by this static schema alone. A new or changed invalid value is rejected; no conversion, filtering or implicit repair is performed."}]}}},"on_refund":{"type":["object","null"],"additionalProperties":false,"properties":{"remove":{"type":["boolean","null"],"enum":[true,false,null]}}},"on_chargeback":{"type":["object","null"],"additionalProperties":false,"properties":{"remove":{"type":["boolean","null"],"enum":[true,false,null]}}},"remove_batch_size":{"type":["integer","null"],"minimum":0},"remove_throttle":{"type":["object","null"],"additionalProperties":false,"properties":{"second":{"type":["integer","null"],"minimum":0},"hour":{"type":["integer","null"],"minimum":0}}}}},"sellers":{"type":"object","additionalProperties":false,"properties":{"strategy":{"type":["string","null"],"enum":["round_robin","random","weighted",null]},"list":{"type":["array","null"],"description":"Sellers rotated 1:1; each entry is read with exactly these fields.","items":{"type":"object","properties":{"phone":{"type":"string","pattern":"^[0-9]{8,15}$","description":"Seller WhatsApp number, digits only."},"name":{"type":"string","minLength":1},"weight":{"type":"integer","minimum":1},"paused":{"type":"boolean"},"user_id":{"type":["integer","null"],"description":"Agent of this account linked to the seller."},"inbox_id":{"type":["integer","null"],"description":"WhatsApp inbox of this account used for the seller."}}}},"prefill_template":{"type":["string","null"]},"daily_cap_per_seller":{"type":["integer","null"],"minimum":0},"pause_when_offline":{"type":["boolean","null"],"enum":[true,false,null]}}},"dm_on_join":{"type":"object","additionalProperties":false,"properties":{"enabled":{"type":["boolean","null"],"enum":[true,false,null]},"template":{"anyOf":[{"type":["string","null"],"enum":["welcome","reminder","countdown","unit_opened","waitlist_ack","removed_notice","graduated_notice",null],"description":"Recognized stored template identifier. Null removes the override; an empty string is invalid. An unchanged legacy identifier may be retained on an unrelated update. This selector currently has no operational send consumer; accepting an identifier does not schedule or send a message."},{"$ref":"#/components/schemas/json_value","description":"A previously stored JSON value may be retained only when it is exactly identical to this field or complete list in the same persisted record. Equality with persisted state is enforced at runtime and cannot be expressed by this static schema alone. A new or changed invalid value is rejected; no conversion, filtering or implicit repair is performed."}]},"spintax":{"type":["array","null"],"description":"Message variants; one is picked at random per send and blank entries are dropped.","items":{"type":"string"}},"delay_seconds":{"type":["object","null"],"additionalProperties":false,"properties":{"min":{"type":["integer","null"],"minimum":0},"max":{"type":["integer","null"],"minimum":0}}},"per_hour_limit":{"type":["integer","null"],"minimum":0},"inbox_id":{"type":["integer","null"],"minimum":0},"fallback_inbox_id":{"type":["integer","null"],"minimum":0},"mode":{"type":["string","null"],"enum":["fixed","generative",null]},"brief":{"type":["string","null"]},"skip_if_conversation_open":{"type":["boolean","null"],"enum":[true,false,null]}}},"templates":{"type":"object","additionalProperties":false,"properties":{"welcome":{"type":["object","null"],"additionalProperties":false,"properties":{"text":{"type":["string","null"]},"spintax":{"type":["array","null"],"description":"Message variants; one is picked at random per send and blank entries are dropped.","items":{"type":"string"}},"media_url":{"type":["string","null"],"format":"uri"}}},"reminder":{"type":["object","null"],"additionalProperties":false,"properties":{"i18n_key":{"type":["string","null"]},"text":{"type":["string","null"]},"spintax":{"type":["array","null"],"description":"Message variants; one is picked at random per send and blank entries are dropped.","items":{"type":"string"}},"media_url":{"type":["string","null"],"format":"uri"}}},"countdown":{"type":["object","null"],"additionalProperties":false,"properties":{"i18n_key":{"type":["string","null"]},"text":{"type":["string","null"]},"spintax":{"type":["array","null"],"description":"Message variants; one is picked at random per send and blank entries are dropped.","items":{"type":"string"}},"media_url":{"type":["string","null"],"format":"uri"}}},"unit_opened":{"type":["object","null"],"additionalProperties":false,"properties":{"i18n_key":{"type":["string","null"]},"text":{"type":["string","null"]},"spintax":{"type":["array","null"],"description":"Message variants; one is picked at random per send and blank entries are dropped.","items":{"type":"string"}},"media_url":{"type":["string","null"],"format":"uri"}}},"waitlist_ack":{"type":["object","null"],"additionalProperties":false,"properties":{"i18n_key":{"type":["string","null"]},"text":{"type":["string","null"]},"spintax":{"type":["array","null"],"description":"Message variants; one is picked at random per send and blank entries are dropped.","items":{"type":"string"}},"media_url":{"type":["string","null"],"format":"uri"}}},"removed_notice":{"type":["object","null"],"additionalProperties":false,"properties":{"i18n_key":{"type":["string","null"]},"text":{"type":["string","null"]},"spintax":{"type":["array","null"],"description":"Message variants; one is picked at random per send and blank entries are dropped.","items":{"type":"string"}},"media_url":{"type":["string","null"],"format":"uri"}}},"graduated_notice":{"type":["object","null"],"additionalProperties":false,"properties":{"i18n_key":{"type":["string","null"]},"text":{"type":["string","null"]},"spintax":{"type":["array","null"],"description":"Message variants; one is picked at random per send and blank entries are dropped.","items":{"type":"string"}},"media_url":{"type":["string","null"],"format":"uri"}}}}},"branding":{"type":"object","additionalProperties":false,"properties":{"naming_template":{"type":["string","null"]},"photo_url":{"type":["string","null"],"format":"uri","description":"Null removes the override. An explicit unit photo overrides distribution identity, then identity overrides the inherited URL. External URLs require HTTPS. HTTP is accepted only for an authorized account-owned image blob on the canonical application origin with a valid signed blob URL and no credentials, query or fragment."},"description":{"type":["string","null"]},"admins":{"type":["array","null"],"description":"Group admins promoted on provisioning; a value with @ is a WhatsApp JID, otherwise a phone whose non-digits are ignored.","items":{"type":"string"}},"announcement_group":{"type":["boolean","null"],"enum":[true,false,null]},"auto_create_channel":{"type":["boolean","null"],"enum":[true,false,null]},"auto_create_channel_live":{"type":["boolean","null"],"enum":[true,false,null]},"channel_invite_url":{"type":["string","null"],"format":"uri"}}},"attribution":{"type":"object","additionalProperties":false,"properties":{"utm_capture":{"type":["boolean","null"],"enum":[true,false,null]},"store_referrer_host":{"type":["boolean","null"],"enum":[true,false,null]},"store_ip_hash":{"type":["boolean","null"],"enum":[true,false,null]},"capi":{"type":["object","null"],"additionalProperties":false,"properties":{"on_click":{"type":["string","null"]},"on_join":{"type":["string","null"]},"on_purchase":{"type":["string","null"]}}},"contact_attribute_key":{"type":["string","null"]}}},"api":{"type":"object","additionalProperties":false,"properties":{"bulk_enroll_max":{"type":["integer","null"],"minimum":0},"index_page_size":{"type":["integer","null"],"minimum":0},"approvals_timeout_seconds":{"type":["integer","null"],"minimum":0},"public_link_rate_per_minute":{"type":["integer","null"],"minimum":0},"export_row_limit":{"type":["integer","null"],"minimum":0}}},"join_approval":{"type":"object","additionalProperties":false,"properties":{"batch":{"type":["integer","null"],"minimum":0},"policy":{"type":["string","null"]}}},"setup":{"type":"object","additionalProperties":false,"properties":{"pause_seconds":{"type":["integer","null"],"minimum":0,"maximum":60},"pause_jitter_seconds":{"type":["integer","null"],"minimum":0},"pause_max_seconds":{"type":["integer","null"],"minimum":0}}}}}}},"examples":{"account":{"summary":"Every account key, with a bulk ceiling and the account-only reconciliation interval set.","value":{"settings":{"capacity":{"hard_cap":1024,"headroom":24,"per_unit":1000,"by_inbox":{},"reserve_for_waitlist":0},"algorithm":{"strategy":"fill_first","weight":1,"sticky_by_contact":true,"routing_rules":[{"match":{"utm_source":"sample utm source","utm_campaign":"sample utm campaign","tag":"sample tag","source":"link"},"distribution_id":1}]},"rotation":{"batch_size":10,"warmup_ramp":[{"after_minutes":60,"batch":1}],"defer_base_seconds":30,"max_backoff_shift":6,"max_defer_attempts":8,"throttle":{"second":null,"hour":null},"sync_interval_minutes":2,"scheduler_batch_size":500,"full_unit_reconcile_minutes":15},"fallback":{"mode":"url","url":null,"message":"growth_distribution.public.unavailable.default_message","distribution_id":null,"waitlist_max":1000,"waitlist_ttl_hours":168,"waitlist_drain_batch":25},"schedule":{"opens_at":null,"closes_at":null,"cascade_minutes":0,"announce_when_closed":true,"lock_when_closed":false,"warmup_window_minutes":0,"timezone":null},"reentry":{"allow_reentry":false,"cooldown_hours":24,"dedupe_across_units":true,"use_hub_blocklist":false,"blacklist":[],"whitelist":[],"reopen_on_leave":true},"post_purchase":{"on_paid":{"remove":false,"move_to_distribution_id":null,"delay_minutes":0},"on_overdue":{"remove":false,"after_days":3,"warn_template":"removed_notice"},"on_refund":{"remove":true},"on_chargeback":{"remove":true},"remove_batch_size":20,"remove_throttle":{"second":null,"hour":null}},"sellers":{"strategy":"round_robin","list":[{"phone":"+5511999998888","name":"Sample Name","weight":1,"paused":true,"user_id":1,"inbox_id":1}],"prefill_template":"growth_distribution.sellers.prefill_default","daily_cap_per_seller":0,"pause_when_offline":false},"dm_on_join":{"enabled":false,"template":"welcome","spintax":[],"delay_seconds":{"min":5,"max":45},"per_hour_limit":60,"inbox_id":null,"fallback_inbox_id":null,"mode":"fixed","brief":"","skip_if_conversation_open":true},"templates":{"welcome":{"text":null,"spintax":[],"media_url":null},"reminder":{"i18n_key":"growth_distribution.templates.reminder","text":null,"spintax":[],"media_url":null},"countdown":{"i18n_key":"growth_distribution.templates.countdown","text":null,"spintax":[],"media_url":null},"unit_opened":{"i18n_key":"growth_distribution.templates.unit_opened","text":null,"spintax":[],"media_url":null},"waitlist_ack":{"i18n_key":"growth_distribution.templates.waitlist_ack","text":null,"spintax":[],"media_url":null},"removed_notice":{"i18n_key":"growth_distribution.templates.removed_notice","text":null,"spintax":[],"media_url":null},"graduated_notice":{"i18n_key":"growth_distribution.templates.graduated_notice","text":null,"spintax":[],"media_url":null}},"branding":{"naming_template":"Turma {n}","photo_url":null,"description":null,"admins":[],"announcement_group":false,"auto_create_channel":false,"auto_create_channel_live":false,"channel_invite_url":null},"attribution":{"utm_capture":true,"store_referrer_host":true,"store_ip_hash":true,"capi":{"on_click":null,"on_join":null,"on_purchase":null},"contact_attribute_key":"distribution_attributions"},"api":{"bulk_enroll_max":500,"index_page_size":25,"approvals_timeout_seconds":3,"public_link_rate_per_minute":30,"export_row_limit":50000},"join_approval":{"batch":20,"policy":"all_while_seats"},"setup":{"pause_seconds":3,"pause_jitter_seconds":2,"pause_max_seconds":60}}}}}}}}}},"/api/v1/accounts/{account_id}/growth/distributions/pending_approvals":{"get":{"tags":["Growth Distribution"],"operationId":"auto_get_api_v1_accounts_account_id_growth_distributions_pending_approvals","summary":"Read pending Maestro approvals for visible distributions","description":"Always answers 200 after authorization. An unavailable or invalid upstream answer is represented by available false with no rows, never a partial result. Foreign or unresolved resource ids are combined under a null distribution_id; account-owned ids outside the caller scope are omitted. Conversation ids are display ids. No message text or phone is returned.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Complete available result or explicit degraded result.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["payload"],"properties":{"payload":{"type":"object","additionalProperties":false,"required":["available","rows"],"properties":{"available":{"type":"boolean","example":true},"rows":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["distribution_id","count","conversation_ids"],"properties":{"distribution_id":{"type":["integer","null"],"example":22},"count":{"type":"integer","minimum":0,"example":2},"conversation_ids":{"type":"array","items":{"type":"integer"},"example":[101,103]}}}}}}}},"examples":{"available":{"value":{"payload":{"available":true,"rows":[{"distribution_id":22,"count":2,"conversation_ids":[101,103]}]}}},"unavailable":{"value":{"payload":{"available":false,"rows":[{"distribution_id":22,"count":2,"conversation_ids":[101,103]}]}}}}}}},"401":{"description":"Authentication and permission to read launch distributions are required."},"404":{"description":"Account or resource not found"},"403":{"description":"The launch distribution feature is not enabled."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/growth/distributions/{id}/activate":{"post":{"tags":["Growth Distribution"],"operationId":"auto_post_api_v1_accounts_account_id_growth_distributions_id_activate","summary":"Activate distributions","description":"Performs the activate operation on the targeted distribution resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Launch distribution with stored configuration and the current identity projection.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["payload"],"properties":{"payload":{"type":"object","additionalProperties":false,"required":["id","account_id","name","slug","public_path","inbox_id","launch_id","target_type","join_mode","capacity_per_unit","algorithm","opens_at","fallback_distribution_id","graduate_distribution_id","advanced_enabled","capacity_defaults","community_member_limit","community_provisioning","setup_capabilities","setup_pause_defaults","next_sequence","effective_capacity","throttle_defaults","identity","community_jid","channel_jid","naming_template","welcome_message","status","settings","entry_trigger_catalog","entry_trigger_validation","configuration_options","configuration_validation","units_count","members_count","open_unit_sequence","closes_at","archived_at","created_at","updated_at","slug_collision","slug_retired_from"],"properties":{"algorithm":{"type":"string","enum":["fill_first","round_robin","random","weighted"],"example":"fill_first"},"opens_at":{"type":["string","null"],"format":"date-time","description":"Distribution opening time, when configured.","example":null},"fallback_distribution_id":{"type":["integer","null"],"example":null},"graduate_distribution_id":{"type":["integer","null"],"example":null},"advanced_enabled":{"type":"boolean","description":"Whether advanced launch distribution features are enabled for this account.","example":false},"capacity_defaults":{"type":"object","additionalProperties":false,"required":["default","maximum","effective_maximum","hard_cap","headroom"],"description":"Resolved capacity limits. On defaults, default is the account per-unit setting; on distribution resources it is the product default of 256. Effective maximum is min(1023, hard_cap minus headroom). An existing explicit per-unit setting is preserved when the account defaults change.","properties":{"default":{"type":"integer","minimum":1,"maximum":1023,"example":256},"maximum":{"type":"integer","description":"Maximum accepted capacity per launch group.","example":1023},"effective_maximum":{"type":"integer","minimum":0,"maximum":1023,"description":"Maximum after applying the resolved hard cap and explicit headroom.","example":1023},"hard_cap":{"type":"integer","minimum":1,"maximum":1024,"description":"Hard cap resolved from the account and distribution settings.","example":1024},"headroom":{"type":"integer","minimum":0,"maximum":1023,"description":"Explicit seat margin; absent overrides use the product margin of zero.","example":0}}},"community_member_limit":{"type":"integer","example":2000},"community_provisioning":{"type":"object","additionalProperties":false,"required":["state","error_code","failed_at"],"properties":{"state":{"type":"string","enum":["not_requested","pending","created","failed"],"example":"not_requested","description":"Distribution member progress state."},"error_code":{"type":["string","null"],"enum":["missing_initial_participant","outcome_uncertain","feature_not_supported","gateway_rejected","gateway_unavailable","rate_limited","setup_step_failed","setup_step_refused","setup_incomplete","creator_inbox_unavailable","group_not_admin","group_not_found",null],"example":null},"failed_at":{"type":["string","null"],"format":"date-time","example":null}}},"next_sequence":{"type":"integer","minimum":1,"example":1},"effective_capacity":{"type":"integer","minimum":0,"maximum":1023,"description":"Minimum of the configured per-unit capacity and the effective maximum after the resolved hard cap and headroom.","example":256},"throttle_defaults":{"type":"object","additionalProperties":false,"required":["second","hour"],"description":"Default outbound limits for WhatsApp Web; operator overrides are kept in settings.","properties":{"second":{"type":"integer","example":1},"hour":{"type":"integer","example":240}}},"identity":{"type":"object","additionalProperties":false,"required":["mode","items","fallback","remaining_positions","exhausts_at_sequence","limits"],"properties":{"mode":{"type":"string","enum":["none","single","sequence"],"example":"sequence"},"items":{"type":"array","maxItems":100,"items":{"type":"object","additionalProperties":false,"required":["key","source","thumb_url","available","check"],"properties":{"key":{"type":"string","minLength":1,"example":"4711"},"source":{"type":"string","enum":["upload","library","url"],"example":"upload"},"media_asset_id":{"type":"integer","minimum":1,"example":44},"thumb_url":{"type":"string","description":"Center-cropped 160 by 160 representation URL, present only after the full image check succeeded; empty while the check is pending or invalid, when the file is unavailable, or when the representation fails.","example":""},"available":{"type":"boolean","description":"Whether the blob is still attached to this distribution.","example":true},"check":{"type":"object","additionalProperties":false,"required":["state","reason","checked_at","overdue"],"properties":{"state":{"type":"string","enum":["pending","ok","invalid"],"example":"pending","description":"Distribution member progress state."},"reason":{"type":["string","null"],"enum":["type","size","dimensions","unreadable","unavailable",null],"example":null},"checked_at":{"type":["string","null"],"format":"date-time","example":null},"overdue":{"type":"boolean","description":"Pending without a check time for at least 15 minutes since attachment creation; false without the check column or attachment.","example":false}}}}}},"fallback":{"oneOf":[{"type":"object","additionalProperties":false,"required":["key","source","thumb_url","available","check"],"properties":{"key":{"type":"string","minLength":1,"example":"4711"},"source":{"type":"string","enum":["upload","library","url"],"example":"upload"},"media_asset_id":{"type":"integer","minimum":1,"example":44},"thumb_url":{"type":"string","description":"Center-cropped 160 by 160 representation URL, present only after the full image check succeeded; empty while the check is pending or invalid, when the file is unavailable, or when the representation fails.","example":""},"available":{"type":"boolean","description":"Whether the blob is still attached to this distribution.","example":true},"check":{"type":"object","additionalProperties":false,"required":["state","reason","checked_at","overdue"],"properties":{"state":{"type":"string","enum":["pending","ok","invalid"],"example":"pending","description":"Distribution member progress state."},"reason":{"type":["string","null"],"enum":["type","size","dimensions","unreadable","unavailable",null],"example":null},"checked_at":{"type":["string","null"],"format":"date-time","example":null},"overdue":{"type":"boolean","description":"Pending without a check time for at least 15 minutes since attachment creation; false without the check column or attachment.","example":false}}}}},{"type":"null"}]},"limits":{"type":"object","additionalProperties":false,"required":["max_bytes","max_side","max_items","content_types","check_overdue_after_seconds"],"properties":{"max_bytes":{"type":"integer","example":8388608},"max_side":{"type":"integer","example":4096},"max_items":{"type":"integer","example":100},"check_overdue_after_seconds":{"type":"integer","example":900},"content_types":{"type":"array","items":{"type":"string","enum":["image/jpeg","image/png"]},"example":["image/jpeg","image/png"]}}},"remaining_positions":{"type":["integer","null"],"minimum":0,"description":"Remaining own-image positions from next_sequence; null outside sequence mode.","example":2},"exhausts_at_sequence":{"type":["integer","null"],"minimum":0,"description":"Number of own-image positions; null outside sequence mode.","example":2}}},"setup_capabilities":{"type":"object","description":"Birth-setting support by step. Only live capabilities support the listed destination types; partial_contract is unavailable.","additionalProperties":{"type":"object","additionalProperties":false,"required":["tier","target_types"],"properties":{"tier":{"type":"string","enum":["live","partial_contract"]},"target_types":{"type":"array","items":{"type":"string","enum":["group","community"]}}}},"example":{"join_approval":{"tier":"partial_contract","target_types":["group","community"]},"locked":{"tier":"live","target_types":["group","community"]},"member_add_mode":{"tier":"partial_contract","target_types":["group","community"]},"ephemeral":{"tier":"live","target_types":["group","community"]}}},"setup_pause_defaults":{"type":"object","additionalProperties":false,"required":["default_seconds","jitter_seconds","max_seconds"],"description":"Server defaults and operator bounds for setup pacing. Jitter is added only to positive pauses.","properties":{"default_seconds":{"type":"integer","minimum":0,"description":"Base pause inherited when no override is set.","example":3},"jitter_seconds":{"type":"integer","minimum":0,"description":"Maximum random delay added to a positive base pause.","example":2},"max_seconds":{"type":"integer","minimum":0,"description":"Maximum configurable base pause before jitter.","example":60}},"example":{"default_seconds":3,"jitter_seconds":2,"max_seconds":60}},"id":{"type":"integer","example":22},"account_id":{"type":"integer","example":1},"name":{"type":"string","example":"October launch"},"slug":{"type":"string","example":"october-launch"},"public_path":{"type":"string","example":"/g/october-launch"},"inbox_id":{"type":"integer","example":6},"logical_inbox_id":{"type":"integer","description":"Present when the visible logical inbox differs from the transport inbox.","example":15},"launch_id":{"type":["integer","null"],"example":null},"target_type":{"type":"string","enum":["community","group","channel"],"example":"group"},"join_mode":{"type":"string","enum":["invite_link","direct_add","both"],"example":"invite_link"},"capacity_per_unit":{"type":"integer","minimum":1,"maximum":1023,"example":256},"community_jid":{"type":["string","null"],"example":null},"channel_jid":{"type":["string","null"],"example":null},"naming_template":{"type":"string","example":"Launch group {n}"},"welcome_message":{"type":["string","null"],"example":null},"status":{"type":"string","enum":["draft","active","paused","completed"],"example":"draft"},"settings":{"type":"object","additionalProperties":true,"description":"Operator configuration excluding system-owned diagnostics; other configuration keys are preserved.","properties":{"join_approval":{"type":["boolean","null"],"enum":[true,false,null],"description":"Require administrator approval to join. Null inherits WhatsApp. New or changed non-null values require a live capability tier for the destination. An unchanged saved value is accepted on update when the destination stays the same.","example":null},"join_approval_policy":{"type":["string","null"],"enum":["manual","all_while_seats",null],"description":"Null defaults effectively to all_while_seats when join_approval is true. A new or changed non-null policy requires a live join_approval capability tier for the destination. An unchanged saved policy is accepted on update when the destination stays the same. Manual only counts pending requests.","example":null},"locked":{"type":["boolean","null"],"enum":[true,false,null],"description":"Restrict group information edits to administrators. Explicit null keeps WhatsApp's existing setting. Omission follows the rules described for each operation.","example":true},"member_add_mode":{"type":["string","null"],"enum":["admin_add","all_member_add",null],"description":"Who may add members. Null inherits WhatsApp. New or changed non-null values require a live capability tier for the destination. An unchanged saved value is accepted on update when the destination stays the same.","example":null},"ephemeral_seconds":{"type":["integer","null"],"enum":[0,86400,604800,7776000,null],"description":"Disappearing-message duration in seconds; zero disables the timer and null inherits WhatsApp.","example":86400},"setup_pause_seconds":{"type":["integer","null"],"minimum":0,"maximum":60,"default":3,"description":"Base delay between setup delegations, plus zero to two seconds of jitter. Zero disables pauses; null uses three seconds.","example":3},"identity":{"type":"object","additionalProperties":false,"required":["photo"],"properties":{"photo":{"type":"object","additionalProperties":false,"required":["mode","items","fallback"],"properties":{"mode":{"type":"string","enum":["none","single","sequence"],"example":"sequence"},"items":{"type":"array","maxItems":100,"description":"Ordered blob references. Single requires one item; none requires an empty list.","items":{"type":"object","additionalProperties":false,"required":["key","source"],"properties":{"key":{"type":"string","minLength":1,"description":"Blob id attached to this distribution.","example":"4711"},"source":{"type":"string","enum":["upload","library","url"],"example":"upload"},"media_asset_id":{"type":"integer","minimum":1,"description":"Original Library asset, when selected from the Library.","example":44}}}},"fallback":{"description":"Image used after the sequence ends or when a selected image is unavailable.","oneOf":[{"type":"object","additionalProperties":false,"required":["key","source"],"properties":{"key":{"type":"string","minLength":1,"description":"Blob id attached to this distribution.","example":"4711"},"source":{"type":"string","enum":["upload","library","url"],"example":"upload"},"media_asset_id":{"type":"integer","minimum":1,"description":"Original Library asset, when selected from the Library.","example":44}}},{"type":"null"}]}}}}},"photo_url":{"type":["string","null"],"description":"Inherited group photo link. An explicit unit photo overrides the distribution identity; without a unit override the distribution identity wins, then the inherited URL. HTTP is accepted only for an authorized image blob of this account on the canonical application origin, with a valid signed blob URL and no credentials, query or fragment. External URLs require HTTPS.","example":"https://images.example.test/legacy-cover.jpg"},"description":{"type":["string","null"],"description":"Group description; each occurrence of {n} is replaced with the unit sequence.","example":"Welcome to launch group {n}."}}},"entry_trigger_catalog":{"type":"array","description":"Complete list of selectable entry keys, shared with server validation. Text is localized for the request. Translation keys belong to the server translation catalog. Availability of a key does not guarantee an event producer, an eligible contact or an enrollment effect.","items":{"type":"object","additionalProperties":false,"required":["key","label_key","description_key","label","description"],"properties":{"key":{"type":"string","description":"A selectable launch distribution entry key backed by an enrollment consumer. Payment confirmed emissions use payment_charge.paid.","enum":["payment_charge.paid","payment_charge.overdue","crm_item.stage_changed","crm_item.stale","crm_item.won","task.overdue","task.due_soon","calendar_event.created","calendar_event.no_show","commerce.cart_abandoned","commerce.order_placed","commerce.payment_pending","commerce.payment_confirmed","commerce.payment_declined","commerce.overdue","commerce.due_soon","commerce.refunded","commerce.chargeback","commerce.subscription_late","commerce.subscription_canceled","ads.lead_captured","social.comment_captured"],"example":"payment_charge.paid"},"label_key":{"type":"string","description":"Server translation key for the label.","example":"growth.distribution.entry_triggers.events.payment_charge_paid.label"},"description_key":{"type":"string","description":"Server translation key for the description.","example":"growth.distribution.entry_triggers.events.payment_charge_paid.description"},"label":{"type":"string","description":"Localized label.","example":"Charge paid"},"description":{"type":"string","description":"Localized explanation of the entry signal.","example":"A confirmed or paid charge payment, admitted through the payment_charge.paid key."}}},"example":[{"key":"payment_charge.paid","label_key":"growth.distribution.entry_triggers.events.payment_charge_paid.label","description_key":"growth.distribution.entry_triggers.events.payment_charge_paid.description","label":"Charge paid","description":"A confirmed or paid charge payment, admitted through the payment_charge.paid key."}]},"entry_trigger_validation":{"type":"object","additionalProperties":false,"required":["valid","invalid_type","invalid_indexes"],"description":"Advisory validation of the stored entry list, without changing it. Read invalid values from settings.entry_triggers at the reported positions. A malformed non-array value has invalid_type true and no positions. An absent list is valid and equivalent to an empty list.","properties":{"valid":{"type":"boolean","example":false},"invalid_type":{"type":"boolean","example":false},"invalid_indexes":{"type":"array","description":"Zero-based positions of unknown keys or elements that are not strings.","items":{"type":"integer","minimum":0},"example":[0]}},"example":{"valid":false,"invalid_type":false,"invalid_indexes":[0]}},"configuration_options":{"type":"object","additionalProperties":false,"required":["routing_sources","template_keys"],"description":"Recognized routing sources and stored template identifiers from the same server sets used by validation. Template membership does not imply a send: the join-template and overdue-warning selectors currently have no operational send consumer and must be presented as unavailable.","properties":{"routing_sources":{"type":"array","items":{"type":"string","enum":["link","automation","event","manual","api","follow_up"]}},"template_keys":{"type":"array","items":{"type":"string","enum":["welcome","reminder","countdown","unit_opened","waitlist_ack","removed_notice","graduated_notice"]}}},"example":{"routing_sources":["link","automation","event","manual","api","follow_up"],"template_keys":["welcome","reminder","countdown","unit_opened","waitlist_ack","removed_notice","graduated_notice"]}},"configuration_validation":{"type":"object","additionalProperties":false,"required":["valid","issues"],"description":"Diagnostics for saved and resolved choices without removing or rewriting them. Paths are relative to the settings document; inherited values also remain available in settings explanations.","properties":{"valid":{"type":"boolean","example":true},"issues":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["path","code"],"properties":{"path":{"type":"string","example":"algorithm.routing_rules[0].match.source"},"code":{"type":"string","enum":["invalid_type","unknown_choice","unknown_key"],"example":"unknown_choice"}}}}},"example":{"valid":true,"issues":[]}},"units_count":{"type":"integer","minimum":0,"example":0},"members_count":{"type":"integer","minimum":0,"example":0},"capacity_total":{"type":"integer","minimum":0,"description":"Sum of current effective capacities across all units, including explicit unit overrides.","example":0},"occupancy_total":{"type":"integer","minimum":0,"description":"Sum of the synced member count of every unit.","example":0},"awaiting_count":{"type":"integer","minimum":0,"description":"Members still pending, queued or waitlisted.","example":0},"open_unit_sequence":{"type":["integer","null"],"example":null},"closes_at":{"type":["string","null"],"format":"date-time","description":"Configured distribution closing time; null means no closing time is set.","example":null},"archived_at":{"type":["string","null"],"format":"date-time","example":null},"created_at":{"type":"string","format":"date-time","example":"2026-10-13T22:00:00Z"},"updated_at":{"type":"string","format":"date-time","example":"2026-10-13T22:00:00Z"},"slug_collision":{"type":"boolean","description":"Whether the current public slug is shared with another distribution.","example":false},"slug_retired_from":{"type":["string","null"],"description":"Former public slug retired after a collision, or null.","example":null}}}}},"example":{"payload":{"algorithm":"fill_first","opens_at":null,"fallback_distribution_id":null,"graduate_distribution_id":null,"advanced_enabled":false,"capacity_defaults":{"default":256,"maximum":1023,"effective_maximum":1023,"hard_cap":1024,"headroom":0},"community_member_limit":2000,"community_provisioning":{"state":"not_requested","error_code":null,"failed_at":null},"next_sequence":1,"effective_capacity":256,"throttle_defaults":{"second":1,"hour":240},"identity":{"mode":"sequence","items":[{"key":"4711","source":"upload","thumb_url":"https://app.example.test/rails/active_storage/representations/redirect/cover-1.jpg","available":true,"check":{"state":"ok","reason":null,"checked_at":"2026-10-14T01:00:00Z","overdue":false},"media_asset_id":44},{"key":"4712","source":"library","media_asset_id":44,"thumb_url":"","available":true,"check":{"state":"pending","reason":null,"checked_at":null,"overdue":false}}],"fallback":{"key":"4720","source":"url","thumb_url":"https://app.example.test/rails/active_storage/representations/redirect/default-cover.jpg","available":true,"check":{"state":"ok","reason":null,"checked_at":"2026-10-14T01:00:00Z","overdue":false},"media_asset_id":44},"limits":{"max_bytes":8388608,"max_side":4096,"max_items":100,"check_overdue_after_seconds":900,"content_types":["image/jpeg","image/png"]},"remaining_positions":2,"exhausts_at_sequence":2},"entry_trigger_catalog":[{"key":"payment_charge.paid","label_key":"growth.distribution.entry_triggers.events.payment_charge_paid.label","description_key":"growth.distribution.entry_triggers.events.payment_charge_paid.description","label":"Charge paid","description":"A confirmed or paid charge payment, admitted through the payment_charge.paid key."}],"entry_trigger_validation":{"valid":true,"invalid_type":false,"invalid_indexes":[]},"configuration_options":{"routing_sources":["link","automation","event","manual","api","follow_up"],"template_keys":["welcome","reminder","countdown","unit_opened","waitlist_ack","removed_notice","graduated_notice"]},"configuration_validation":{"valid":true,"issues":[{"path":"algorithm.routing_rules[0].match.source","code":"unknown_choice"}]},"setup_capabilities":{"join_approval":{"tier":"partial_contract","target_types":["group","community"]},"locked":{"tier":"live","target_types":["group","community"]},"member_add_mode":{"tier":"partial_contract","target_types":["group","community"]},"ephemeral":{"tier":"live","target_types":["group","community"]}},"setup_pause_defaults":{"default_seconds":3,"jitter_seconds":2,"max_seconds":60},"id":22,"account_id":1,"name":"October launch","slug":"october-launch","public_path":"/g/october-launch","inbox_id":6,"logical_inbox_id":15,"launch_id":null,"target_type":"group","join_mode":"invite_link","capacity_per_unit":256,"community_jid":null,"channel_jid":null,"naming_template":"Launch group {n}","welcome_message":null,"status":"active","settings":{"locked":true,"ephemeral_seconds":86400,"setup_pause_seconds":3,"description":"Welcome to launch group {n}.","photo_url":"https://images.example.test/legacy-cover.jpg","identity":{"photo":{"mode":"sequence","items":[{"key":"4711","source":"upload","media_asset_id":44},{"key":"4712","source":"library","media_asset_id":44}],"fallback":{"key":"4720","source":"url","media_asset_id":44}}},"join_approval":null,"join_approval_policy":null,"member_add_mode":null},"units_count":0,"members_count":0,"capacity_total":0,"occupancy_total":0,"awaiting_count":0,"open_unit_sequence":null,"closes_at":null,"archived_at":null,"created_at":"2026-10-13T22:00:00Z","updated_at":"2026-10-13T22:00:00Z","slug_collision":false,"slug_retired_from":null}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"422":{"description":"Activation requires a bound channel and invite URL, and reconciliation of any uncertain group creation.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","enum":["provisioning_reconciliation_required","channel_binding_required"]},"message":{"type":"string","description":"Translated explanation when the channel binding is incomplete."}}},"examples":{"reconciliation":{"value":{"error":"provisioning_reconciliation_required","message":"Sample message text."}},"channel_binding":{"value":{"error":"channel_binding_required","message":"Bind an existing WhatsApp channel and its invite URL before activating this launch group."}}}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"unit_id":{"type":"integer"}}},"example":{"unit_id":1}}}}}},"/api/v1/accounts/{account_id}/growth/distributions/{id}/pause":{"post":{"tags":["Growth Distribution"],"operationId":"auto_post_api_v1_accounts_account_id_growth_distributions_id_pause","summary":"Pause distributions","description":"Performs the pause operation on the targeted distribution resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Launch distribution with stored configuration and the current identity projection.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["payload"],"properties":{"payload":{"type":"object","additionalProperties":false,"required":["id","account_id","name","slug","public_path","inbox_id","launch_id","target_type","join_mode","capacity_per_unit","algorithm","opens_at","fallback_distribution_id","graduate_distribution_id","advanced_enabled","capacity_defaults","community_member_limit","community_provisioning","setup_capabilities","setup_pause_defaults","next_sequence","effective_capacity","throttle_defaults","identity","community_jid","channel_jid","naming_template","welcome_message","status","settings","entry_trigger_catalog","entry_trigger_validation","configuration_options","configuration_validation","units_count","members_count","open_unit_sequence","closes_at","archived_at","created_at","updated_at","slug_collision","slug_retired_from"],"properties":{"algorithm":{"type":"string","enum":["fill_first","round_robin","random","weighted"],"example":"fill_first"},"opens_at":{"type":["string","null"],"format":"date-time","description":"Distribution opening time, when configured.","example":null},"fallback_distribution_id":{"type":["integer","null"],"example":null},"graduate_distribution_id":{"type":["integer","null"],"example":null},"advanced_enabled":{"type":"boolean","description":"Whether advanced launch distribution features are enabled for this account.","example":false},"capacity_defaults":{"type":"object","additionalProperties":false,"required":["default","maximum","effective_maximum","hard_cap","headroom"],"description":"Resolved capacity limits. On defaults, default is the account per-unit setting; on distribution resources it is the product default of 256. Effective maximum is min(1023, hard_cap minus headroom). An existing explicit per-unit setting is preserved when the account defaults change.","properties":{"default":{"type":"integer","minimum":1,"maximum":1023,"example":256},"maximum":{"type":"integer","description":"Maximum accepted capacity per launch group.","example":1023},"effective_maximum":{"type":"integer","minimum":0,"maximum":1023,"description":"Maximum after applying the resolved hard cap and explicit headroom.","example":1023},"hard_cap":{"type":"integer","minimum":1,"maximum":1024,"description":"Hard cap resolved from the account and distribution settings.","example":1024},"headroom":{"type":"integer","minimum":0,"maximum":1023,"description":"Explicit seat margin; absent overrides use the product margin of zero.","example":0}}},"community_member_limit":{"type":"integer","example":2000},"community_provisioning":{"type":"object","additionalProperties":false,"required":["state","error_code","failed_at"],"properties":{"state":{"type":"string","enum":["not_requested","pending","created","failed"],"example":"not_requested","description":"Distribution member progress state."},"error_code":{"type":["string","null"],"enum":["missing_initial_participant","outcome_uncertain","feature_not_supported","gateway_rejected","gateway_unavailable","rate_limited","setup_step_failed","setup_step_refused","setup_incomplete","creator_inbox_unavailable","group_not_admin","group_not_found",null],"example":null},"failed_at":{"type":["string","null"],"format":"date-time","example":null}}},"next_sequence":{"type":"integer","minimum":1,"example":1},"effective_capacity":{"type":"integer","minimum":0,"maximum":1023,"description":"Minimum of the configured per-unit capacity and the effective maximum after the resolved hard cap and headroom.","example":256},"throttle_defaults":{"type":"object","additionalProperties":false,"required":["second","hour"],"description":"Default outbound limits for WhatsApp Web; operator overrides are kept in settings.","properties":{"second":{"type":"integer","example":1},"hour":{"type":"integer","example":240}}},"identity":{"type":"object","additionalProperties":false,"required":["mode","items","fallback","remaining_positions","exhausts_at_sequence","limits"],"properties":{"mode":{"type":"string","enum":["none","single","sequence"],"example":"sequence"},"items":{"type":"array","maxItems":100,"items":{"type":"object","additionalProperties":false,"required":["key","source","thumb_url","available","check"],"properties":{"key":{"type":"string","minLength":1,"example":"4711"},"source":{"type":"string","enum":["upload","library","url"],"example":"upload"},"media_asset_id":{"type":"integer","minimum":1,"example":44},"thumb_url":{"type":"string","description":"Center-cropped 160 by 160 representation URL, present only after the full image check succeeded; empty while the check is pending or invalid, when the file is unavailable, or when the representation fails.","example":""},"available":{"type":"boolean","description":"Whether the blob is still attached to this distribution.","example":true},"check":{"type":"object","additionalProperties":false,"required":["state","reason","checked_at","overdue"],"properties":{"state":{"type":"string","enum":["pending","ok","invalid"],"example":"pending","description":"Distribution member progress state."},"reason":{"type":["string","null"],"enum":["type","size","dimensions","unreadable","unavailable",null],"example":null},"checked_at":{"type":["string","null"],"format":"date-time","example":null},"overdue":{"type":"boolean","description":"Pending without a check time for at least 15 minutes since attachment creation; false without the check column or attachment.","example":false}}}}}},"fallback":{"oneOf":[{"type":"object","additionalProperties":false,"required":["key","source","thumb_url","available","check"],"properties":{"key":{"type":"string","minLength":1,"example":"4711"},"source":{"type":"string","enum":["upload","library","url"],"example":"upload"},"media_asset_id":{"type":"integer","minimum":1,"example":44},"thumb_url":{"type":"string","description":"Center-cropped 160 by 160 representation URL, present only after the full image check succeeded; empty while the check is pending or invalid, when the file is unavailable, or when the representation fails.","example":""},"available":{"type":"boolean","description":"Whether the blob is still attached to this distribution.","example":true},"check":{"type":"object","additionalProperties":false,"required":["state","reason","checked_at","overdue"],"properties":{"state":{"type":"string","enum":["pending","ok","invalid"],"example":"pending","description":"Distribution member progress state."},"reason":{"type":["string","null"],"enum":["type","size","dimensions","unreadable","unavailable",null],"example":null},"checked_at":{"type":["string","null"],"format":"date-time","example":null},"overdue":{"type":"boolean","description":"Pending without a check time for at least 15 minutes since attachment creation; false without the check column or attachment.","example":false}}}}},{"type":"null"}]},"limits":{"type":"object","additionalProperties":false,"required":["max_bytes","max_side","max_items","content_types","check_overdue_after_seconds"],"properties":{"max_bytes":{"type":"integer","example":8388608},"max_side":{"type":"integer","example":4096},"max_items":{"type":"integer","example":100},"check_overdue_after_seconds":{"type":"integer","example":900},"content_types":{"type":"array","items":{"type":"string","enum":["image/jpeg","image/png"]},"example":["image/jpeg","image/png"]}}},"remaining_positions":{"type":["integer","null"],"minimum":0,"description":"Remaining own-image positions from next_sequence; null outside sequence mode.","example":2},"exhausts_at_sequence":{"type":["integer","null"],"minimum":0,"description":"Number of own-image positions; null outside sequence mode.","example":2}}},"setup_capabilities":{"type":"object","description":"Birth-setting support by step. Only live capabilities support the listed destination types; partial_contract is unavailable.","additionalProperties":{"type":"object","additionalProperties":false,"required":["tier","target_types"],"properties":{"tier":{"type":"string","enum":["live","partial_contract"]},"target_types":{"type":"array","items":{"type":"string","enum":["group","community"]}}}},"example":{"join_approval":{"tier":"partial_contract","target_types":["group","community"]},"locked":{"tier":"live","target_types":["group","community"]},"member_add_mode":{"tier":"partial_contract","target_types":["group","community"]},"ephemeral":{"tier":"live","target_types":["group","community"]}}},"setup_pause_defaults":{"type":"object","additionalProperties":false,"required":["default_seconds","jitter_seconds","max_seconds"],"description":"Server defaults and operator bounds for setup pacing. Jitter is added only to positive pauses.","properties":{"default_seconds":{"type":"integer","minimum":0,"description":"Base pause inherited when no override is set.","example":3},"jitter_seconds":{"type":"integer","minimum":0,"description":"Maximum random delay added to a positive base pause.","example":2},"max_seconds":{"type":"integer","minimum":0,"description":"Maximum configurable base pause before jitter.","example":60}},"example":{"default_seconds":3,"jitter_seconds":2,"max_seconds":60}},"id":{"type":"integer","example":22},"account_id":{"type":"integer","example":1},"name":{"type":"string","example":"October launch"},"slug":{"type":"string","example":"october-launch"},"public_path":{"type":"string","example":"/g/october-launch"},"inbox_id":{"type":"integer","example":6},"logical_inbox_id":{"type":"integer","description":"Present when the visible logical inbox differs from the transport inbox.","example":15},"launch_id":{"type":["integer","null"],"example":null},"target_type":{"type":"string","enum":["community","group","channel"],"example":"group"},"join_mode":{"type":"string","enum":["invite_link","direct_add","both"],"example":"invite_link"},"capacity_per_unit":{"type":"integer","minimum":1,"maximum":1023,"example":256},"community_jid":{"type":["string","null"],"example":null},"channel_jid":{"type":["string","null"],"example":null},"naming_template":{"type":"string","example":"Launch group {n}"},"welcome_message":{"type":["string","null"],"example":null},"status":{"type":"string","enum":["draft","active","paused","completed"],"example":"draft"},"settings":{"type":"object","additionalProperties":true,"description":"Operator configuration excluding system-owned diagnostics; other configuration keys are preserved.","properties":{"join_approval":{"type":["boolean","null"],"enum":[true,false,null],"description":"Require administrator approval to join. Null inherits WhatsApp. New or changed non-null values require a live capability tier for the destination. An unchanged saved value is accepted on update when the destination stays the same.","example":null},"join_approval_policy":{"type":["string","null"],"enum":["manual","all_while_seats",null],"description":"Null defaults effectively to all_while_seats when join_approval is true. A new or changed non-null policy requires a live join_approval capability tier for the destination. An unchanged saved policy is accepted on update when the destination stays the same. Manual only counts pending requests.","example":null},"locked":{"type":["boolean","null"],"enum":[true,false,null],"description":"Restrict group information edits to administrators. Explicit null keeps WhatsApp's existing setting. Omission follows the rules described for each operation.","example":true},"member_add_mode":{"type":["string","null"],"enum":["admin_add","all_member_add",null],"description":"Who may add members. Null inherits WhatsApp. New or changed non-null values require a live capability tier for the destination. An unchanged saved value is accepted on update when the destination stays the same.","example":null},"ephemeral_seconds":{"type":["integer","null"],"enum":[0,86400,604800,7776000,null],"description":"Disappearing-message duration in seconds; zero disables the timer and null inherits WhatsApp.","example":86400},"setup_pause_seconds":{"type":["integer","null"],"minimum":0,"maximum":60,"default":3,"description":"Base delay between setup delegations, plus zero to two seconds of jitter. Zero disables pauses; null uses three seconds.","example":3},"identity":{"type":"object","additionalProperties":false,"required":["photo"],"properties":{"photo":{"type":"object","additionalProperties":false,"required":["mode","items","fallback"],"properties":{"mode":{"type":"string","enum":["none","single","sequence"],"example":"sequence"},"items":{"type":"array","maxItems":100,"description":"Ordered blob references. Single requires one item; none requires an empty list.","items":{"type":"object","additionalProperties":false,"required":["key","source"],"properties":{"key":{"type":"string","minLength":1,"description":"Blob id attached to this distribution.","example":"4711"},"source":{"type":"string","enum":["upload","library","url"],"example":"upload"},"media_asset_id":{"type":"integer","minimum":1,"description":"Original Library asset, when selected from the Library.","example":44}}}},"fallback":{"description":"Image used after the sequence ends or when a selected image is unavailable.","oneOf":[{"type":"object","additionalProperties":false,"required":["key","source"],"properties":{"key":{"type":"string","minLength":1,"description":"Blob id attached to this distribution.","example":"4711"},"source":{"type":"string","enum":["upload","library","url"],"example":"upload"},"media_asset_id":{"type":"integer","minimum":1,"description":"Original Library asset, when selected from the Library.","example":44}}},{"type":"null"}]}}}}},"photo_url":{"type":["string","null"],"description":"Inherited group photo link. An explicit unit photo overrides the distribution identity; without a unit override the distribution identity wins, then the inherited URL. HTTP is accepted only for an authorized image blob of this account on the canonical application origin, with a valid signed blob URL and no credentials, query or fragment. External URLs require HTTPS.","example":"https://images.example.test/legacy-cover.jpg"},"description":{"type":["string","null"],"description":"Group description; each occurrence of {n} is replaced with the unit sequence.","example":"Welcome to launch group {n}."}}},"entry_trigger_catalog":{"type":"array","description":"Complete list of selectable entry keys, shared with server validation. Text is localized for the request. Translation keys belong to the server translation catalog. Availability of a key does not guarantee an event producer, an eligible contact or an enrollment effect.","items":{"type":"object","additionalProperties":false,"required":["key","label_key","description_key","label","description"],"properties":{"key":{"type":"string","description":"A selectable launch distribution entry key backed by an enrollment consumer. Payment confirmed emissions use payment_charge.paid.","enum":["payment_charge.paid","payment_charge.overdue","crm_item.stage_changed","crm_item.stale","crm_item.won","task.overdue","task.due_soon","calendar_event.created","calendar_event.no_show","commerce.cart_abandoned","commerce.order_placed","commerce.payment_pending","commerce.payment_confirmed","commerce.payment_declined","commerce.overdue","commerce.due_soon","commerce.refunded","commerce.chargeback","commerce.subscription_late","commerce.subscription_canceled","ads.lead_captured","social.comment_captured"],"example":"payment_charge.paid"},"label_key":{"type":"string","description":"Server translation key for the label.","example":"growth.distribution.entry_triggers.events.payment_charge_paid.label"},"description_key":{"type":"string","description":"Server translation key for the description.","example":"growth.distribution.entry_triggers.events.payment_charge_paid.description"},"label":{"type":"string","description":"Localized label.","example":"Charge paid"},"description":{"type":"string","description":"Localized explanation of the entry signal.","example":"A confirmed or paid charge payment, admitted through the payment_charge.paid key."}}},"example":[{"key":"payment_charge.paid","label_key":"growth.distribution.entry_triggers.events.payment_charge_paid.label","description_key":"growth.distribution.entry_triggers.events.payment_charge_paid.description","label":"Charge paid","description":"A confirmed or paid charge payment, admitted through the payment_charge.paid key."}]},"entry_trigger_validation":{"type":"object","additionalProperties":false,"required":["valid","invalid_type","invalid_indexes"],"description":"Advisory validation of the stored entry list, without changing it. Read invalid values from settings.entry_triggers at the reported positions. A malformed non-array value has invalid_type true and no positions. An absent list is valid and equivalent to an empty list.","properties":{"valid":{"type":"boolean","example":false},"invalid_type":{"type":"boolean","example":false},"invalid_indexes":{"type":"array","description":"Zero-based positions of unknown keys or elements that are not strings.","items":{"type":"integer","minimum":0},"example":[0]}},"example":{"valid":false,"invalid_type":false,"invalid_indexes":[0]}},"configuration_options":{"type":"object","additionalProperties":false,"required":["routing_sources","template_keys"],"description":"Recognized routing sources and stored template identifiers from the same server sets used by validation. Template membership does not imply a send: the join-template and overdue-warning selectors currently have no operational send consumer and must be presented as unavailable.","properties":{"routing_sources":{"type":"array","items":{"type":"string","enum":["link","automation","event","manual","api","follow_up"]}},"template_keys":{"type":"array","items":{"type":"string","enum":["welcome","reminder","countdown","unit_opened","waitlist_ack","removed_notice","graduated_notice"]}}},"example":{"routing_sources":["link","automation","event","manual","api","follow_up"],"template_keys":["welcome","reminder","countdown","unit_opened","waitlist_ack","removed_notice","graduated_notice"]}},"configuration_validation":{"type":"object","additionalProperties":false,"required":["valid","issues"],"description":"Diagnostics for saved and resolved choices without removing or rewriting them. Paths are relative to the settings document; inherited values also remain available in settings explanations.","properties":{"valid":{"type":"boolean","example":true},"issues":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["path","code"],"properties":{"path":{"type":"string","example":"algorithm.routing_rules[0].match.source"},"code":{"type":"string","enum":["invalid_type","unknown_choice","unknown_key"],"example":"unknown_choice"}}}}},"example":{"valid":true,"issues":[]}},"units_count":{"type":"integer","minimum":0,"example":0},"members_count":{"type":"integer","minimum":0,"example":0},"capacity_total":{"type":"integer","minimum":0,"description":"Sum of current effective capacities across all units, including explicit unit overrides.","example":0},"occupancy_total":{"type":"integer","minimum":0,"description":"Sum of the synced member count of every unit.","example":0},"awaiting_count":{"type":"integer","minimum":0,"description":"Members still pending, queued or waitlisted.","example":0},"open_unit_sequence":{"type":["integer","null"],"example":null},"closes_at":{"type":["string","null"],"format":"date-time","description":"Configured distribution closing time; null means no closing time is set.","example":null},"archived_at":{"type":["string","null"],"format":"date-time","example":null},"created_at":{"type":"string","format":"date-time","example":"2026-10-13T22:00:00Z"},"updated_at":{"type":"string","format":"date-time","example":"2026-10-13T22:00:00Z"},"slug_collision":{"type":"boolean","description":"Whether the current public slug is shared with another distribution.","example":false},"slug_retired_from":{"type":["string","null"],"description":"Former public slug retired after a collision, or null.","example":null}}}}},"example":{"payload":{"algorithm":"fill_first","opens_at":null,"fallback_distribution_id":null,"graduate_distribution_id":null,"advanced_enabled":false,"capacity_defaults":{"default":256,"maximum":1023,"effective_maximum":1023,"hard_cap":1024,"headroom":0},"community_member_limit":2000,"community_provisioning":{"state":"not_requested","error_code":null,"failed_at":null},"next_sequence":1,"effective_capacity":256,"throttle_defaults":{"second":1,"hour":240},"identity":{"mode":"sequence","items":[{"key":"4711","source":"upload","thumb_url":"https://app.example.test/rails/active_storage/representations/redirect/cover-1.jpg","available":true,"check":{"state":"ok","reason":null,"checked_at":"2026-10-14T01:00:00Z","overdue":false},"media_asset_id":44},{"key":"4712","source":"library","media_asset_id":44,"thumb_url":"","available":true,"check":{"state":"pending","reason":null,"checked_at":null,"overdue":false}}],"fallback":{"key":"4720","source":"url","thumb_url":"https://app.example.test/rails/active_storage/representations/redirect/default-cover.jpg","available":true,"check":{"state":"ok","reason":null,"checked_at":"2026-10-14T01:00:00Z","overdue":false},"media_asset_id":44},"limits":{"max_bytes":8388608,"max_side":4096,"max_items":100,"check_overdue_after_seconds":900,"content_types":["image/jpeg","image/png"]},"remaining_positions":2,"exhausts_at_sequence":2},"entry_trigger_catalog":[{"key":"payment_charge.paid","label_key":"growth.distribution.entry_triggers.events.payment_charge_paid.label","description_key":"growth.distribution.entry_triggers.events.payment_charge_paid.description","label":"Charge paid","description":"A confirmed or paid charge payment, admitted through the payment_charge.paid key."}],"entry_trigger_validation":{"valid":true,"invalid_type":false,"invalid_indexes":[]},"configuration_options":{"routing_sources":["link","automation","event","manual","api","follow_up"],"template_keys":["welcome","reminder","countdown","unit_opened","waitlist_ack","removed_notice","graduated_notice"]},"configuration_validation":{"valid":true,"issues":[{"path":"algorithm.routing_rules[0].match.source","code":"unknown_choice"}]},"setup_capabilities":{"join_approval":{"tier":"partial_contract","target_types":["group","community"]},"locked":{"tier":"live","target_types":["group","community"]},"member_add_mode":{"tier":"partial_contract","target_types":["group","community"]},"ephemeral":{"tier":"live","target_types":["group","community"]}},"setup_pause_defaults":{"default_seconds":3,"jitter_seconds":2,"max_seconds":60},"id":22,"account_id":1,"name":"October launch","slug":"october-launch","public_path":"/g/october-launch","inbox_id":6,"logical_inbox_id":15,"launch_id":null,"target_type":"group","join_mode":"invite_link","capacity_per_unit":256,"community_jid":null,"channel_jid":null,"naming_template":"Launch group {n}","welcome_message":null,"status":"paused","settings":{"locked":true,"ephemeral_seconds":86400,"setup_pause_seconds":3,"description":"Welcome to launch group {n}.","photo_url":"https://images.example.test/legacy-cover.jpg","identity":{"photo":{"mode":"sequence","items":[{"key":"4711","source":"upload","media_asset_id":44},{"key":"4712","source":"library","media_asset_id":44}],"fallback":{"key":"4720","source":"url","media_asset_id":44}}},"join_approval":null,"join_approval_policy":null,"member_add_mode":null},"units_count":0,"members_count":0,"capacity_total":0,"occupancy_total":0,"awaiting_count":0,"open_unit_sequence":null,"closes_at":null,"archived_at":null,"created_at":"2026-10-13T22:00:00Z","updated_at":"2026-10-13T22:00:00Z","slug_collision":false,"slug_retired_from":null}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/growth/distributions/{id}/archive":{"post":{"tags":["Growth Distribution"],"operationId":"auto_post_api_v1_accounts_account_id_growth_distributions_id_archive","summary":"Archive distributions","description":"Performs the archive operation on the targeted distribution resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Launch distribution with stored configuration and the current identity projection.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["payload"],"properties":{"payload":{"type":"object","additionalProperties":false,"required":["id","account_id","name","slug","public_path","inbox_id","launch_id","target_type","join_mode","capacity_per_unit","algorithm","opens_at","fallback_distribution_id","graduate_distribution_id","advanced_enabled","capacity_defaults","community_member_limit","community_provisioning","setup_capabilities","setup_pause_defaults","next_sequence","effective_capacity","throttle_defaults","identity","community_jid","channel_jid","naming_template","welcome_message","status","settings","entry_trigger_catalog","entry_trigger_validation","configuration_options","configuration_validation","units_count","members_count","open_unit_sequence","closes_at","archived_at","created_at","updated_at","slug_collision","slug_retired_from"],"properties":{"algorithm":{"type":"string","enum":["fill_first","round_robin","random","weighted"],"example":"fill_first"},"opens_at":{"type":["string","null"],"format":"date-time","description":"Distribution opening time, when configured.","example":null},"fallback_distribution_id":{"type":["integer","null"],"example":null},"graduate_distribution_id":{"type":["integer","null"],"example":null},"advanced_enabled":{"type":"boolean","description":"Whether advanced launch distribution features are enabled for this account.","example":false},"capacity_defaults":{"type":"object","additionalProperties":false,"required":["default","maximum","effective_maximum","hard_cap","headroom"],"description":"Resolved capacity limits. On defaults, default is the account per-unit setting; on distribution resources it is the product default of 256. Effective maximum is min(1023, hard_cap minus headroom). An existing explicit per-unit setting is preserved when the account defaults change.","properties":{"default":{"type":"integer","minimum":1,"maximum":1023,"example":256},"maximum":{"type":"integer","description":"Maximum accepted capacity per launch group.","example":1023},"effective_maximum":{"type":"integer","minimum":0,"maximum":1023,"description":"Maximum after applying the resolved hard cap and explicit headroom.","example":1023},"hard_cap":{"type":"integer","minimum":1,"maximum":1024,"description":"Hard cap resolved from the account and distribution settings.","example":1024},"headroom":{"type":"integer","minimum":0,"maximum":1023,"description":"Explicit seat margin; absent overrides use the product margin of zero.","example":0}}},"community_member_limit":{"type":"integer","example":2000},"community_provisioning":{"type":"object","additionalProperties":false,"required":["state","error_code","failed_at"],"properties":{"state":{"type":"string","enum":["not_requested","pending","created","failed"],"example":"not_requested","description":"Distribution member progress state."},"error_code":{"type":["string","null"],"enum":["missing_initial_participant","outcome_uncertain","feature_not_supported","gateway_rejected","gateway_unavailable","rate_limited","setup_step_failed","setup_step_refused","setup_incomplete","creator_inbox_unavailable","group_not_admin","group_not_found",null],"example":null},"failed_at":{"type":["string","null"],"format":"date-time","example":null}}},"next_sequence":{"type":"integer","minimum":1,"example":1},"effective_capacity":{"type":"integer","minimum":0,"maximum":1023,"description":"Minimum of the configured per-unit capacity and the effective maximum after the resolved hard cap and headroom.","example":256},"throttle_defaults":{"type":"object","additionalProperties":false,"required":["second","hour"],"description":"Default outbound limits for WhatsApp Web; operator overrides are kept in settings.","properties":{"second":{"type":"integer","example":1},"hour":{"type":"integer","example":240}}},"identity":{"type":"object","additionalProperties":false,"required":["mode","items","fallback","remaining_positions","exhausts_at_sequence","limits"],"properties":{"mode":{"type":"string","enum":["none","single","sequence"],"example":"sequence"},"items":{"type":"array","maxItems":100,"items":{"type":"object","additionalProperties":false,"required":["key","source","thumb_url","available","check"],"properties":{"key":{"type":"string","minLength":1,"example":"4711"},"source":{"type":"string","enum":["upload","library","url"],"example":"upload"},"media_asset_id":{"type":"integer","minimum":1,"example":44},"thumb_url":{"type":"string","description":"Center-cropped 160 by 160 representation URL, present only after the full image check succeeded; empty while the check is pending or invalid, when the file is unavailable, or when the representation fails.","example":""},"available":{"type":"boolean","description":"Whether the blob is still attached to this distribution.","example":true},"check":{"type":"object","additionalProperties":false,"required":["state","reason","checked_at","overdue"],"properties":{"state":{"type":"string","enum":["pending","ok","invalid"],"example":"pending","description":"Distribution member progress state."},"reason":{"type":["string","null"],"enum":["type","size","dimensions","unreadable","unavailable",null],"example":null},"checked_at":{"type":["string","null"],"format":"date-time","example":null},"overdue":{"type":"boolean","description":"Pending without a check time for at least 15 minutes since attachment creation; false without the check column or attachment.","example":false}}}}}},"fallback":{"oneOf":[{"type":"object","additionalProperties":false,"required":["key","source","thumb_url","available","check"],"properties":{"key":{"type":"string","minLength":1,"example":"4711"},"source":{"type":"string","enum":["upload","library","url"],"example":"upload"},"media_asset_id":{"type":"integer","minimum":1,"example":44},"thumb_url":{"type":"string","description":"Center-cropped 160 by 160 representation URL, present only after the full image check succeeded; empty while the check is pending or invalid, when the file is unavailable, or when the representation fails.","example":""},"available":{"type":"boolean","description":"Whether the blob is still attached to this distribution.","example":true},"check":{"type":"object","additionalProperties":false,"required":["state","reason","checked_at","overdue"],"properties":{"state":{"type":"string","enum":["pending","ok","invalid"],"example":"pending","description":"Distribution member progress state."},"reason":{"type":["string","null"],"enum":["type","size","dimensions","unreadable","unavailable",null],"example":null},"checked_at":{"type":["string","null"],"format":"date-time","example":null},"overdue":{"type":"boolean","description":"Pending without a check time for at least 15 minutes since attachment creation; false without the check column or attachment.","example":false}}}}},{"type":"null"}]},"limits":{"type":"object","additionalProperties":false,"required":["max_bytes","max_side","max_items","content_types","check_overdue_after_seconds"],"properties":{"max_bytes":{"type":"integer","example":8388608},"max_side":{"type":"integer","example":4096},"max_items":{"type":"integer","example":100},"check_overdue_after_seconds":{"type":"integer","example":900},"content_types":{"type":"array","items":{"type":"string","enum":["image/jpeg","image/png"]},"example":["image/jpeg","image/png"]}}},"remaining_positions":{"type":["integer","null"],"minimum":0,"description":"Remaining own-image positions from next_sequence; null outside sequence mode.","example":2},"exhausts_at_sequence":{"type":["integer","null"],"minimum":0,"description":"Number of own-image positions; null outside sequence mode.","example":2}}},"setup_capabilities":{"type":"object","description":"Birth-setting support by step. Only live capabilities support the listed destination types; partial_contract is unavailable.","additionalProperties":{"type":"object","additionalProperties":false,"required":["tier","target_types"],"properties":{"tier":{"type":"string","enum":["live","partial_contract"]},"target_types":{"type":"array","items":{"type":"string","enum":["group","community"]}}}},"example":{"join_approval":{"tier":"partial_contract","target_types":["group","community"]},"locked":{"tier":"live","target_types":["group","community"]},"member_add_mode":{"tier":"partial_contract","target_types":["group","community"]},"ephemeral":{"tier":"live","target_types":["group","community"]}}},"setup_pause_defaults":{"type":"object","additionalProperties":false,"required":["default_seconds","jitter_seconds","max_seconds"],"description":"Server defaults and operator bounds for setup pacing. Jitter is added only to positive pauses.","properties":{"default_seconds":{"type":"integer","minimum":0,"description":"Base pause inherited when no override is set.","example":3},"jitter_seconds":{"type":"integer","minimum":0,"description":"Maximum random delay added to a positive base pause.","example":2},"max_seconds":{"type":"integer","minimum":0,"description":"Maximum configurable base pause before jitter.","example":60}},"example":{"default_seconds":3,"jitter_seconds":2,"max_seconds":60}},"id":{"type":"integer","example":22},"account_id":{"type":"integer","example":1},"name":{"type":"string","example":"October launch"},"slug":{"type":"string","example":"october-launch"},"public_path":{"type":"string","example":"/g/october-launch"},"inbox_id":{"type":"integer","example":6},"logical_inbox_id":{"type":"integer","description":"Present when the visible logical inbox differs from the transport inbox.","example":15},"launch_id":{"type":["integer","null"],"example":null},"target_type":{"type":"string","enum":["community","group","channel"],"example":"group"},"join_mode":{"type":"string","enum":["invite_link","direct_add","both"],"example":"invite_link"},"capacity_per_unit":{"type":"integer","minimum":1,"maximum":1023,"example":256},"community_jid":{"type":["string","null"],"example":null},"channel_jid":{"type":["string","null"],"example":null},"naming_template":{"type":"string","example":"Launch group {n}"},"welcome_message":{"type":["string","null"],"example":null},"status":{"type":"string","enum":["draft","active","paused","completed"],"example":"draft"},"settings":{"type":"object","additionalProperties":true,"description":"Operator configuration excluding system-owned diagnostics; other configuration keys are preserved.","properties":{"join_approval":{"type":["boolean","null"],"enum":[true,false,null],"description":"Require administrator approval to join. Null inherits WhatsApp. New or changed non-null values require a live capability tier for the destination. An unchanged saved value is accepted on update when the destination stays the same.","example":null},"join_approval_policy":{"type":["string","null"],"enum":["manual","all_while_seats",null],"description":"Null defaults effectively to all_while_seats when join_approval is true. A new or changed non-null policy requires a live join_approval capability tier for the destination. An unchanged saved policy is accepted on update when the destination stays the same. Manual only counts pending requests.","example":null},"locked":{"type":["boolean","null"],"enum":[true,false,null],"description":"Restrict group information edits to administrators. Explicit null keeps WhatsApp's existing setting. Omission follows the rules described for each operation.","example":true},"member_add_mode":{"type":["string","null"],"enum":["admin_add","all_member_add",null],"description":"Who may add members. Null inherits WhatsApp. New or changed non-null values require a live capability tier for the destination. An unchanged saved value is accepted on update when the destination stays the same.","example":null},"ephemeral_seconds":{"type":["integer","null"],"enum":[0,86400,604800,7776000,null],"description":"Disappearing-message duration in seconds; zero disables the timer and null inherits WhatsApp.","example":86400},"setup_pause_seconds":{"type":["integer","null"],"minimum":0,"maximum":60,"default":3,"description":"Base delay between setup delegations, plus zero to two seconds of jitter. Zero disables pauses; null uses three seconds.","example":3},"identity":{"type":"object","additionalProperties":false,"required":["photo"],"properties":{"photo":{"type":"object","additionalProperties":false,"required":["mode","items","fallback"],"properties":{"mode":{"type":"string","enum":["none","single","sequence"],"example":"sequence"},"items":{"type":"array","maxItems":100,"description":"Ordered blob references. Single requires one item; none requires an empty list.","items":{"type":"object","additionalProperties":false,"required":["key","source"],"properties":{"key":{"type":"string","minLength":1,"description":"Blob id attached to this distribution.","example":"4711"},"source":{"type":"string","enum":["upload","library","url"],"example":"upload"},"media_asset_id":{"type":"integer","minimum":1,"description":"Original Library asset, when selected from the Library.","example":44}}}},"fallback":{"description":"Image used after the sequence ends or when a selected image is unavailable.","oneOf":[{"type":"object","additionalProperties":false,"required":["key","source"],"properties":{"key":{"type":"string","minLength":1,"description":"Blob id attached to this distribution.","example":"4711"},"source":{"type":"string","enum":["upload","library","url"],"example":"upload"},"media_asset_id":{"type":"integer","minimum":1,"description":"Original Library asset, when selected from the Library.","example":44}}},{"type":"null"}]}}}}},"photo_url":{"type":["string","null"],"description":"Inherited group photo link. An explicit unit photo overrides the distribution identity; without a unit override the distribution identity wins, then the inherited URL. HTTP is accepted only for an authorized image blob of this account on the canonical application origin, with a valid signed blob URL and no credentials, query or fragment. External URLs require HTTPS.","example":"https://images.example.test/legacy-cover.jpg"},"description":{"type":["string","null"],"description":"Group description; each occurrence of {n} is replaced with the unit sequence.","example":"Welcome to launch group {n}."}}},"entry_trigger_catalog":{"type":"array","description":"Complete list of selectable entry keys, shared with server validation. Text is localized for the request. Translation keys belong to the server translation catalog. Availability of a key does not guarantee an event producer, an eligible contact or an enrollment effect.","items":{"type":"object","additionalProperties":false,"required":["key","label_key","description_key","label","description"],"properties":{"key":{"type":"string","description":"A selectable launch distribution entry key backed by an enrollment consumer. Payment confirmed emissions use payment_charge.paid.","enum":["payment_charge.paid","payment_charge.overdue","crm_item.stage_changed","crm_item.stale","crm_item.won","task.overdue","task.due_soon","calendar_event.created","calendar_event.no_show","commerce.cart_abandoned","commerce.order_placed","commerce.payment_pending","commerce.payment_confirmed","commerce.payment_declined","commerce.overdue","commerce.due_soon","commerce.refunded","commerce.chargeback","commerce.subscription_late","commerce.subscription_canceled","ads.lead_captured","social.comment_captured"],"example":"payment_charge.paid"},"label_key":{"type":"string","description":"Server translation key for the label.","example":"growth.distribution.entry_triggers.events.payment_charge_paid.label"},"description_key":{"type":"string","description":"Server translation key for the description.","example":"growth.distribution.entry_triggers.events.payment_charge_paid.description"},"label":{"type":"string","description":"Localized label.","example":"Charge paid"},"description":{"type":"string","description":"Localized explanation of the entry signal.","example":"A confirmed or paid charge payment, admitted through the payment_charge.paid key."}}},"example":[{"key":"payment_charge.paid","label_key":"growth.distribution.entry_triggers.events.payment_charge_paid.label","description_key":"growth.distribution.entry_triggers.events.payment_charge_paid.description","label":"Charge paid","description":"A confirmed or paid charge payment, admitted through the payment_charge.paid key."}]},"entry_trigger_validation":{"type":"object","additionalProperties":false,"required":["valid","invalid_type","invalid_indexes"],"description":"Advisory validation of the stored entry list, without changing it. Read invalid values from settings.entry_triggers at the reported positions. A malformed non-array value has invalid_type true and no positions. An absent list is valid and equivalent to an empty list.","properties":{"valid":{"type":"boolean","example":false},"invalid_type":{"type":"boolean","example":false},"invalid_indexes":{"type":"array","description":"Zero-based positions of unknown keys or elements that are not strings.","items":{"type":"integer","minimum":0},"example":[0]}},"example":{"valid":false,"invalid_type":false,"invalid_indexes":[0]}},"configuration_options":{"type":"object","additionalProperties":false,"required":["routing_sources","template_keys"],"description":"Recognized routing sources and stored template identifiers from the same server sets used by validation. Template membership does not imply a send: the join-template and overdue-warning selectors currently have no operational send consumer and must be presented as unavailable.","properties":{"routing_sources":{"type":"array","items":{"type":"string","enum":["link","automation","event","manual","api","follow_up"]}},"template_keys":{"type":"array","items":{"type":"string","enum":["welcome","reminder","countdown","unit_opened","waitlist_ack","removed_notice","graduated_notice"]}}},"example":{"routing_sources":["link","automation","event","manual","api","follow_up"],"template_keys":["welcome","reminder","countdown","unit_opened","waitlist_ack","removed_notice","graduated_notice"]}},"configuration_validation":{"type":"object","additionalProperties":false,"required":["valid","issues"],"description":"Diagnostics for saved and resolved choices without removing or rewriting them. Paths are relative to the settings document; inherited values also remain available in settings explanations.","properties":{"valid":{"type":"boolean","example":true},"issues":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["path","code"],"properties":{"path":{"type":"string","example":"algorithm.routing_rules[0].match.source"},"code":{"type":"string","enum":["invalid_type","unknown_choice","unknown_key"],"example":"unknown_choice"}}}}},"example":{"valid":true,"issues":[]}},"units_count":{"type":"integer","minimum":0,"example":0},"members_count":{"type":"integer","minimum":0,"example":0},"capacity_total":{"type":"integer","minimum":0,"description":"Sum of current effective capacities across all units, including explicit unit overrides.","example":0},"occupancy_total":{"type":"integer","minimum":0,"description":"Sum of the synced member count of every unit.","example":0},"awaiting_count":{"type":"integer","minimum":0,"description":"Members still pending, queued or waitlisted.","example":0},"open_unit_sequence":{"type":["integer","null"],"example":null},"closes_at":{"type":["string","null"],"format":"date-time","description":"Configured distribution closing time; null means no closing time is set.","example":null},"archived_at":{"type":["string","null"],"format":"date-time","example":null},"created_at":{"type":"string","format":"date-time","example":"2026-10-13T22:00:00Z"},"updated_at":{"type":"string","format":"date-time","example":"2026-10-13T22:00:00Z"},"slug_collision":{"type":"boolean","description":"Whether the current public slug is shared with another distribution.","example":false},"slug_retired_from":{"type":["string","null"],"description":"Former public slug retired after a collision, or null.","example":null}}}}},"example":{"payload":{"algorithm":"fill_first","opens_at":null,"fallback_distribution_id":null,"graduate_distribution_id":null,"advanced_enabled":false,"capacity_defaults":{"default":256,"maximum":1023,"effective_maximum":1023,"hard_cap":1024,"headroom":0},"community_member_limit":2000,"community_provisioning":{"state":"not_requested","error_code":null,"failed_at":null},"next_sequence":1,"effective_capacity":256,"throttle_defaults":{"second":1,"hour":240},"identity":{"mode":"sequence","items":[{"key":"4711","source":"upload","thumb_url":"https://app.example.test/rails/active_storage/representations/redirect/cover-1.jpg","available":true,"check":{"state":"ok","reason":null,"checked_at":"2026-10-14T01:00:00Z","overdue":false},"media_asset_id":44},{"key":"4712","source":"library","media_asset_id":44,"thumb_url":"","available":true,"check":{"state":"pending","reason":null,"checked_at":null,"overdue":false}}],"fallback":{"key":"4720","source":"url","thumb_url":"https://app.example.test/rails/active_storage/representations/redirect/default-cover.jpg","available":true,"check":{"state":"ok","reason":null,"checked_at":"2026-10-14T01:00:00Z","overdue":false},"media_asset_id":44},"limits":{"max_bytes":8388608,"max_side":4096,"max_items":100,"check_overdue_after_seconds":900,"content_types":["image/jpeg","image/png"]},"remaining_positions":2,"exhausts_at_sequence":2},"entry_trigger_catalog":[{"key":"payment_charge.paid","label_key":"growth.distribution.entry_triggers.events.payment_charge_paid.label","description_key":"growth.distribution.entry_triggers.events.payment_charge_paid.description","label":"Charge paid","description":"A confirmed or paid charge payment, admitted through the payment_charge.paid key."}],"entry_trigger_validation":{"valid":true,"invalid_type":false,"invalid_indexes":[]},"configuration_options":{"routing_sources":["link","automation","event","manual","api","follow_up"],"template_keys":["welcome","reminder","countdown","unit_opened","waitlist_ack","removed_notice","graduated_notice"]},"configuration_validation":{"valid":true,"issues":[{"path":"algorithm.routing_rules[0].match.source","code":"unknown_choice"}]},"setup_capabilities":{"join_approval":{"tier":"partial_contract","target_types":["group","community"]},"locked":{"tier":"live","target_types":["group","community"]},"member_add_mode":{"tier":"partial_contract","target_types":["group","community"]},"ephemeral":{"tier":"live","target_types":["group","community"]}},"setup_pause_defaults":{"default_seconds":3,"jitter_seconds":2,"max_seconds":60},"id":22,"account_id":1,"name":"October launch","slug":"october-launch","public_path":"/g/october-launch","inbox_id":6,"logical_inbox_id":15,"launch_id":null,"target_type":"group","join_mode":"invite_link","capacity_per_unit":256,"community_jid":null,"channel_jid":null,"naming_template":"Launch group {n}","welcome_message":null,"status":"paused","settings":{"locked":true,"ephemeral_seconds":86400,"setup_pause_seconds":3,"description":"Welcome to launch group {n}.","photo_url":"https://images.example.test/legacy-cover.jpg","identity":{"photo":{"mode":"sequence","items":[{"key":"4711","source":"upload","media_asset_id":44},{"key":"4712","source":"library","media_asset_id":44}],"fallback":{"key":"4720","source":"url","media_asset_id":44}}},"join_approval":null,"join_approval_policy":null,"member_add_mode":null},"units_count":0,"members_count":0,"capacity_total":0,"occupancy_total":0,"awaiting_count":0,"open_unit_sequence":null,"closes_at":null,"archived_at":"2026-10-14T01:00:00Z","created_at":"2026-10-13T22:00:00Z","updated_at":"2026-10-13T22:00:00Z","slug_collision":false,"slug_retired_from":null}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/growth/distributions/{id}/restore":{"post":{"tags":["Growth Distribution"],"operationId":"auto_post_api_v1_accounts_account_id_growth_distributions_id_restore","summary":"Restore distributions","description":"Performs the restore operation on the targeted distribution resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Launch distribution with stored configuration and the current identity projection.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["payload"],"properties":{"payload":{"type":"object","additionalProperties":false,"required":["id","account_id","name","slug","public_path","inbox_id","launch_id","target_type","join_mode","capacity_per_unit","algorithm","opens_at","fallback_distribution_id","graduate_distribution_id","advanced_enabled","capacity_defaults","community_member_limit","community_provisioning","setup_capabilities","setup_pause_defaults","next_sequence","effective_capacity","throttle_defaults","identity","community_jid","channel_jid","naming_template","welcome_message","status","settings","entry_trigger_catalog","entry_trigger_validation","configuration_options","configuration_validation","units_count","members_count","open_unit_sequence","closes_at","archived_at","created_at","updated_at","slug_collision","slug_retired_from"],"properties":{"algorithm":{"type":"string","enum":["fill_first","round_robin","random","weighted"],"example":"fill_first"},"opens_at":{"type":["string","null"],"format":"date-time","description":"Distribution opening time, when configured.","example":null},"fallback_distribution_id":{"type":["integer","null"],"example":null},"graduate_distribution_id":{"type":["integer","null"],"example":null},"advanced_enabled":{"type":"boolean","description":"Whether advanced launch distribution features are enabled for this account.","example":false},"capacity_defaults":{"type":"object","additionalProperties":false,"required":["default","maximum","effective_maximum","hard_cap","headroom"],"description":"Resolved capacity limits. On defaults, default is the account per-unit setting; on distribution resources it is the product default of 256. Effective maximum is min(1023, hard_cap minus headroom). An existing explicit per-unit setting is preserved when the account defaults change.","properties":{"default":{"type":"integer","minimum":1,"maximum":1023,"example":256},"maximum":{"type":"integer","description":"Maximum accepted capacity per launch group.","example":1023},"effective_maximum":{"type":"integer","minimum":0,"maximum":1023,"description":"Maximum after applying the resolved hard cap and explicit headroom.","example":1023},"hard_cap":{"type":"integer","minimum":1,"maximum":1024,"description":"Hard cap resolved from the account and distribution settings.","example":1024},"headroom":{"type":"integer","minimum":0,"maximum":1023,"description":"Explicit seat margin; absent overrides use the product margin of zero.","example":0}}},"community_member_limit":{"type":"integer","example":2000},"community_provisioning":{"type":"object","additionalProperties":false,"required":["state","error_code","failed_at"],"properties":{"state":{"type":"string","enum":["not_requested","pending","created","failed"],"example":"not_requested","description":"Distribution member progress state."},"error_code":{"type":["string","null"],"enum":["missing_initial_participant","outcome_uncertain","feature_not_supported","gateway_rejected","gateway_unavailable","rate_limited","setup_step_failed","setup_step_refused","setup_incomplete","creator_inbox_unavailable","group_not_admin","group_not_found",null],"example":null},"failed_at":{"type":["string","null"],"format":"date-time","example":null}}},"next_sequence":{"type":"integer","minimum":1,"example":1},"effective_capacity":{"type":"integer","minimum":0,"maximum":1023,"description":"Minimum of the configured per-unit capacity and the effective maximum after the resolved hard cap and headroom.","example":256},"throttle_defaults":{"type":"object","additionalProperties":false,"required":["second","hour"],"description":"Default outbound limits for WhatsApp Web; operator overrides are kept in settings.","properties":{"second":{"type":"integer","example":1},"hour":{"type":"integer","example":240}}},"identity":{"type":"object","additionalProperties":false,"required":["mode","items","fallback","remaining_positions","exhausts_at_sequence","limits"],"properties":{"mode":{"type":"string","enum":["none","single","sequence"],"example":"sequence"},"items":{"type":"array","maxItems":100,"items":{"type":"object","additionalProperties":false,"required":["key","source","thumb_url","available","check"],"properties":{"key":{"type":"string","minLength":1,"example":"4711"},"source":{"type":"string","enum":["upload","library","url"],"example":"upload"},"media_asset_id":{"type":"integer","minimum":1,"example":44},"thumb_url":{"type":"string","description":"Center-cropped 160 by 160 representation URL, present only after the full image check succeeded; empty while the check is pending or invalid, when the file is unavailable, or when the representation fails.","example":""},"available":{"type":"boolean","description":"Whether the blob is still attached to this distribution.","example":true},"check":{"type":"object","additionalProperties":false,"required":["state","reason","checked_at","overdue"],"properties":{"state":{"type":"string","enum":["pending","ok","invalid"],"example":"pending","description":"Distribution member progress state."},"reason":{"type":["string","null"],"enum":["type","size","dimensions","unreadable","unavailable",null],"example":null},"checked_at":{"type":["string","null"],"format":"date-time","example":null},"overdue":{"type":"boolean","description":"Pending without a check time for at least 15 minutes since attachment creation; false without the check column or attachment.","example":false}}}}}},"fallback":{"oneOf":[{"type":"object","additionalProperties":false,"required":["key","source","thumb_url","available","check"],"properties":{"key":{"type":"string","minLength":1,"example":"4711"},"source":{"type":"string","enum":["upload","library","url"],"example":"upload"},"media_asset_id":{"type":"integer","minimum":1,"example":44},"thumb_url":{"type":"string","description":"Center-cropped 160 by 160 representation URL, present only after the full image check succeeded; empty while the check is pending or invalid, when the file is unavailable, or when the representation fails.","example":""},"available":{"type":"boolean","description":"Whether the blob is still attached to this distribution.","example":true},"check":{"type":"object","additionalProperties":false,"required":["state","reason","checked_at","overdue"],"properties":{"state":{"type":"string","enum":["pending","ok","invalid"],"example":"pending","description":"Distribution member progress state."},"reason":{"type":["string","null"],"enum":["type","size","dimensions","unreadable","unavailable",null],"example":null},"checked_at":{"type":["string","null"],"format":"date-time","example":null},"overdue":{"type":"boolean","description":"Pending without a check time for at least 15 minutes since attachment creation; false without the check column or attachment.","example":false}}}}},{"type":"null"}]},"limits":{"type":"object","additionalProperties":false,"required":["max_bytes","max_side","max_items","content_types","check_overdue_after_seconds"],"properties":{"max_bytes":{"type":"integer","example":8388608},"max_side":{"type":"integer","example":4096},"max_items":{"type":"integer","example":100},"check_overdue_after_seconds":{"type":"integer","example":900},"content_types":{"type":"array","items":{"type":"string","enum":["image/jpeg","image/png"]},"example":["image/jpeg","image/png"]}}},"remaining_positions":{"type":["integer","null"],"minimum":0,"description":"Remaining own-image positions from next_sequence; null outside sequence mode.","example":2},"exhausts_at_sequence":{"type":["integer","null"],"minimum":0,"description":"Number of own-image positions; null outside sequence mode.","example":2}}},"setup_capabilities":{"type":"object","description":"Birth-setting support by step. Only live capabilities support the listed destination types; partial_contract is unavailable.","additionalProperties":{"type":"object","additionalProperties":false,"required":["tier","target_types"],"properties":{"tier":{"type":"string","enum":["live","partial_contract"]},"target_types":{"type":"array","items":{"type":"string","enum":["group","community"]}}}},"example":{"join_approval":{"tier":"partial_contract","target_types":["group","community"]},"locked":{"tier":"live","target_types":["group","community"]},"member_add_mode":{"tier":"partial_contract","target_types":["group","community"]},"ephemeral":{"tier":"live","target_types":["group","community"]}}},"setup_pause_defaults":{"type":"object","additionalProperties":false,"required":["default_seconds","jitter_seconds","max_seconds"],"description":"Server defaults and operator bounds for setup pacing. Jitter is added only to positive pauses.","properties":{"default_seconds":{"type":"integer","minimum":0,"description":"Base pause inherited when no override is set.","example":3},"jitter_seconds":{"type":"integer","minimum":0,"description":"Maximum random delay added to a positive base pause.","example":2},"max_seconds":{"type":"integer","minimum":0,"description":"Maximum configurable base pause before jitter.","example":60}},"example":{"default_seconds":3,"jitter_seconds":2,"max_seconds":60}},"id":{"type":"integer","example":22},"account_id":{"type":"integer","example":1},"name":{"type":"string","example":"October launch"},"slug":{"type":"string","example":"october-launch"},"public_path":{"type":"string","example":"/g/october-launch"},"inbox_id":{"type":"integer","example":6},"logical_inbox_id":{"type":"integer","description":"Present when the visible logical inbox differs from the transport inbox.","example":15},"launch_id":{"type":["integer","null"],"example":null},"target_type":{"type":"string","enum":["community","group","channel"],"example":"group"},"join_mode":{"type":"string","enum":["invite_link","direct_add","both"],"example":"invite_link"},"capacity_per_unit":{"type":"integer","minimum":1,"maximum":1023,"example":256},"community_jid":{"type":["string","null"],"example":null},"channel_jid":{"type":["string","null"],"example":null},"naming_template":{"type":"string","example":"Launch group {n}"},"welcome_message":{"type":["string","null"],"example":null},"status":{"type":"string","enum":["draft","active","paused","completed"],"example":"draft"},"settings":{"type":"object","additionalProperties":true,"description":"Operator configuration excluding system-owned diagnostics; other configuration keys are preserved.","properties":{"join_approval":{"type":["boolean","null"],"enum":[true,false,null],"description":"Require administrator approval to join. Null inherits WhatsApp. New or changed non-null values require a live capability tier for the destination. An unchanged saved value is accepted on update when the destination stays the same.","example":null},"join_approval_policy":{"type":["string","null"],"enum":["manual","all_while_seats",null],"description":"Null defaults effectively to all_while_seats when join_approval is true. A new or changed non-null policy requires a live join_approval capability tier for the destination. An unchanged saved policy is accepted on update when the destination stays the same. Manual only counts pending requests.","example":null},"locked":{"type":["boolean","null"],"enum":[true,false,null],"description":"Restrict group information edits to administrators. Explicit null keeps WhatsApp's existing setting. Omission follows the rules described for each operation.","example":true},"member_add_mode":{"type":["string","null"],"enum":["admin_add","all_member_add",null],"description":"Who may add members. Null inherits WhatsApp. New or changed non-null values require a live capability tier for the destination. An unchanged saved value is accepted on update when the destination stays the same.","example":null},"ephemeral_seconds":{"type":["integer","null"],"enum":[0,86400,604800,7776000,null],"description":"Disappearing-message duration in seconds; zero disables the timer and null inherits WhatsApp.","example":86400},"setup_pause_seconds":{"type":["integer","null"],"minimum":0,"maximum":60,"default":3,"description":"Base delay between setup delegations, plus zero to two seconds of jitter. Zero disables pauses; null uses three seconds.","example":3},"identity":{"type":"object","additionalProperties":false,"required":["photo"],"properties":{"photo":{"type":"object","additionalProperties":false,"required":["mode","items","fallback"],"properties":{"mode":{"type":"string","enum":["none","single","sequence"],"example":"sequence"},"items":{"type":"array","maxItems":100,"description":"Ordered blob references. Single requires one item; none requires an empty list.","items":{"type":"object","additionalProperties":false,"required":["key","source"],"properties":{"key":{"type":"string","minLength":1,"description":"Blob id attached to this distribution.","example":"4711"},"source":{"type":"string","enum":["upload","library","url"],"example":"upload"},"media_asset_id":{"type":"integer","minimum":1,"description":"Original Library asset, when selected from the Library.","example":44}}}},"fallback":{"description":"Image used after the sequence ends or when a selected image is unavailable.","oneOf":[{"type":"object","additionalProperties":false,"required":["key","source"],"properties":{"key":{"type":"string","minLength":1,"description":"Blob id attached to this distribution.","example":"4711"},"source":{"type":"string","enum":["upload","library","url"],"example":"upload"},"media_asset_id":{"type":"integer","minimum":1,"description":"Original Library asset, when selected from the Library.","example":44}}},{"type":"null"}]}}}}},"photo_url":{"type":["string","null"],"description":"Inherited group photo link. An explicit unit photo overrides the distribution identity; without a unit override the distribution identity wins, then the inherited URL. HTTP is accepted only for an authorized image blob of this account on the canonical application origin, with a valid signed blob URL and no credentials, query or fragment. External URLs require HTTPS.","example":"https://images.example.test/legacy-cover.jpg"},"description":{"type":["string","null"],"description":"Group description; each occurrence of {n} is replaced with the unit sequence.","example":"Welcome to launch group {n}."}}},"entry_trigger_catalog":{"type":"array","description":"Complete list of selectable entry keys, shared with server validation. Text is localized for the request. Translation keys belong to the server translation catalog. Availability of a key does not guarantee an event producer, an eligible contact or an enrollment effect.","items":{"type":"object","additionalProperties":false,"required":["key","label_key","description_key","label","description"],"properties":{"key":{"type":"string","description":"A selectable launch distribution entry key backed by an enrollment consumer. Payment confirmed emissions use payment_charge.paid.","enum":["payment_charge.paid","payment_charge.overdue","crm_item.stage_changed","crm_item.stale","crm_item.won","task.overdue","task.due_soon","calendar_event.created","calendar_event.no_show","commerce.cart_abandoned","commerce.order_placed","commerce.payment_pending","commerce.payment_confirmed","commerce.payment_declined","commerce.overdue","commerce.due_soon","commerce.refunded","commerce.chargeback","commerce.subscription_late","commerce.subscription_canceled","ads.lead_captured","social.comment_captured"],"example":"payment_charge.paid"},"label_key":{"type":"string","description":"Server translation key for the label.","example":"growth.distribution.entry_triggers.events.payment_charge_paid.label"},"description_key":{"type":"string","description":"Server translation key for the description.","example":"growth.distribution.entry_triggers.events.payment_charge_paid.description"},"label":{"type":"string","description":"Localized label.","example":"Charge paid"},"description":{"type":"string","description":"Localized explanation of the entry signal.","example":"A confirmed or paid charge payment, admitted through the payment_charge.paid key."}}},"example":[{"key":"payment_charge.paid","label_key":"growth.distribution.entry_triggers.events.payment_charge_paid.label","description_key":"growth.distribution.entry_triggers.events.payment_charge_paid.description","label":"Charge paid","description":"A confirmed or paid charge payment, admitted through the payment_charge.paid key."}]},"entry_trigger_validation":{"type":"object","additionalProperties":false,"required":["valid","invalid_type","invalid_indexes"],"description":"Advisory validation of the stored entry list, without changing it. Read invalid values from settings.entry_triggers at the reported positions. A malformed non-array value has invalid_type true and no positions. An absent list is valid and equivalent to an empty list.","properties":{"valid":{"type":"boolean","example":false},"invalid_type":{"type":"boolean","example":false},"invalid_indexes":{"type":"array","description":"Zero-based positions of unknown keys or elements that are not strings.","items":{"type":"integer","minimum":0},"example":[0]}},"example":{"valid":false,"invalid_type":false,"invalid_indexes":[0]}},"configuration_options":{"type":"object","additionalProperties":false,"required":["routing_sources","template_keys"],"description":"Recognized routing sources and stored template identifiers from the same server sets used by validation. Template membership does not imply a send: the join-template and overdue-warning selectors currently have no operational send consumer and must be presented as unavailable.","properties":{"routing_sources":{"type":"array","items":{"type":"string","enum":["link","automation","event","manual","api","follow_up"]}},"template_keys":{"type":"array","items":{"type":"string","enum":["welcome","reminder","countdown","unit_opened","waitlist_ack","removed_notice","graduated_notice"]}}},"example":{"routing_sources":["link","automation","event","manual","api","follow_up"],"template_keys":["welcome","reminder","countdown","unit_opened","waitlist_ack","removed_notice","graduated_notice"]}},"configuration_validation":{"type":"object","additionalProperties":false,"required":["valid","issues"],"description":"Diagnostics for saved and resolved choices without removing or rewriting them. Paths are relative to the settings document; inherited values also remain available in settings explanations.","properties":{"valid":{"type":"boolean","example":true},"issues":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["path","code"],"properties":{"path":{"type":"string","example":"algorithm.routing_rules[0].match.source"},"code":{"type":"string","enum":["invalid_type","unknown_choice","unknown_key"],"example":"unknown_choice"}}}}},"example":{"valid":true,"issues":[]}},"units_count":{"type":"integer","minimum":0,"example":0},"members_count":{"type":"integer","minimum":0,"example":0},"capacity_total":{"type":"integer","minimum":0,"description":"Sum of current effective capacities across all units, including explicit unit overrides.","example":0},"occupancy_total":{"type":"integer","minimum":0,"description":"Sum of the synced member count of every unit.","example":0},"awaiting_count":{"type":"integer","minimum":0,"description":"Members still pending, queued or waitlisted.","example":0},"open_unit_sequence":{"type":["integer","null"],"example":null},"closes_at":{"type":["string","null"],"format":"date-time","description":"Configured distribution closing time; null means no closing time is set.","example":null},"archived_at":{"type":["string","null"],"format":"date-time","example":null},"created_at":{"type":"string","format":"date-time","example":"2026-10-13T22:00:00Z"},"updated_at":{"type":"string","format":"date-time","example":"2026-10-13T22:00:00Z"},"slug_collision":{"type":"boolean","description":"Whether the current public slug is shared with another distribution.","example":false},"slug_retired_from":{"type":["string","null"],"description":"Former public slug retired after a collision, or null.","example":null}}}}},"example":{"payload":{"algorithm":"fill_first","opens_at":null,"fallback_distribution_id":null,"graduate_distribution_id":null,"advanced_enabled":false,"capacity_defaults":{"default":256,"maximum":1023,"effective_maximum":1023,"hard_cap":1024,"headroom":0},"community_member_limit":2000,"community_provisioning":{"state":"not_requested","error_code":null,"failed_at":null},"next_sequence":1,"effective_capacity":256,"throttle_defaults":{"second":1,"hour":240},"identity":{"mode":"sequence","items":[{"key":"4711","source":"upload","thumb_url":"https://app.example.test/rails/active_storage/representations/redirect/cover-1.jpg","available":true,"check":{"state":"ok","reason":null,"checked_at":"2026-10-14T01:00:00Z","overdue":false},"media_asset_id":44},{"key":"4712","source":"library","media_asset_id":44,"thumb_url":"","available":true,"check":{"state":"pending","reason":null,"checked_at":null,"overdue":false}}],"fallback":{"key":"4720","source":"url","thumb_url":"https://app.example.test/rails/active_storage/representations/redirect/default-cover.jpg","available":true,"check":{"state":"ok","reason":null,"checked_at":"2026-10-14T01:00:00Z","overdue":false},"media_asset_id":44},"limits":{"max_bytes":8388608,"max_side":4096,"max_items":100,"check_overdue_after_seconds":900,"content_types":["image/jpeg","image/png"]},"remaining_positions":2,"exhausts_at_sequence":2},"entry_trigger_catalog":[{"key":"payment_charge.paid","label_key":"growth.distribution.entry_triggers.events.payment_charge_paid.label","description_key":"growth.distribution.entry_triggers.events.payment_charge_paid.description","label":"Charge paid","description":"A confirmed or paid charge payment, admitted through the payment_charge.paid key."}],"entry_trigger_validation":{"valid":true,"invalid_type":false,"invalid_indexes":[]},"configuration_options":{"routing_sources":["link","automation","event","manual","api","follow_up"],"template_keys":["welcome","reminder","countdown","unit_opened","waitlist_ack","removed_notice","graduated_notice"]},"configuration_validation":{"valid":true,"issues":[{"path":"algorithm.routing_rules[0].match.source","code":"unknown_choice"}]},"setup_capabilities":{"join_approval":{"tier":"partial_contract","target_types":["group","community"]},"locked":{"tier":"live","target_types":["group","community"]},"member_add_mode":{"tier":"partial_contract","target_types":["group","community"]},"ephemeral":{"tier":"live","target_types":["group","community"]}},"setup_pause_defaults":{"default_seconds":3,"jitter_seconds":2,"max_seconds":60},"id":22,"account_id":1,"name":"October launch","slug":"october-launch","public_path":"/g/october-launch","inbox_id":6,"logical_inbox_id":15,"launch_id":null,"target_type":"group","join_mode":"invite_link","capacity_per_unit":256,"community_jid":null,"channel_jid":null,"naming_template":"Launch group {n}","welcome_message":null,"status":"draft","settings":{"locked":true,"ephemeral_seconds":86400,"setup_pause_seconds":3,"description":"Welcome to launch group {n}.","photo_url":"https://images.example.test/legacy-cover.jpg","identity":{"photo":{"mode":"sequence","items":[{"key":"4711","source":"upload","media_asset_id":44},{"key":"4712","source":"library","media_asset_id":44}],"fallback":{"key":"4720","source":"url","media_asset_id":44}}},"join_approval":null,"join_approval_policy":null,"member_add_mode":null},"units_count":0,"members_count":0,"capacity_total":0,"occupancy_total":0,"awaiting_count":0,"open_unit_sequence":null,"closes_at":null,"archived_at":null,"created_at":"2026-10-13T22:00:00Z","updated_at":"2026-10-13T22:00:00Z","slug_collision":false,"slug_retired_from":null}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/growth/distributions/{id}/duplicate":{"post":{"tags":["Growth Distribution"],"operationId":"auto_post_api_v1_accounts_account_id_growth_distributions_id_duplicate","summary":"Duplicate distributions","description":"Creates a draft with a fresh public address and no units or members. The fields, the placement algorithm and the settings are copied; the fallback and graduation targets are copied only while they are still another active, unarchived distribution of the account, otherwise the copy starts without them. The opening and closing times are not copied, as columns or in the schedule settings, because a copy starts another round. Identity and attachments are not copied, since the new distribution owns no image references. A legacy photo_url is copied. No create-only locked default is applied: the source's stored true, false, null or omitted key is copied unchanged. Channel copies receive no injected locked key. Copied entry triggers must be catalog keys. Repair invalid legacy triggers on the source before duplicating it; invalid keys are not silently removed from the copied configuration.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Launch distribution with stored configuration and the current identity projection.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["payload"],"properties":{"payload":{"type":"object","additionalProperties":false,"required":["id","account_id","name","slug","public_path","inbox_id","launch_id","target_type","join_mode","capacity_per_unit","algorithm","opens_at","fallback_distribution_id","graduate_distribution_id","advanced_enabled","capacity_defaults","community_member_limit","community_provisioning","setup_capabilities","setup_pause_defaults","next_sequence","effective_capacity","throttle_defaults","identity","community_jid","channel_jid","naming_template","welcome_message","status","settings","entry_trigger_catalog","entry_trigger_validation","configuration_options","configuration_validation","units_count","members_count","open_unit_sequence","closes_at","archived_at","created_at","updated_at","slug_collision","slug_retired_from"],"properties":{"algorithm":{"type":"string","enum":["fill_first","round_robin","random","weighted"],"example":"fill_first"},"opens_at":{"type":["string","null"],"format":"date-time","description":"Distribution opening time, when configured.","example":null},"fallback_distribution_id":{"type":["integer","null"],"example":null},"graduate_distribution_id":{"type":["integer","null"],"example":null},"advanced_enabled":{"type":"boolean","description":"Whether advanced launch distribution features are enabled for this account.","example":false},"capacity_defaults":{"type":"object","additionalProperties":false,"required":["default","maximum","effective_maximum","hard_cap","headroom"],"description":"Resolved capacity limits. On defaults, default is the account per-unit setting; on distribution resources it is the product default of 256. Effective maximum is min(1023, hard_cap minus headroom). An existing explicit per-unit setting is preserved when the account defaults change.","properties":{"default":{"type":"integer","minimum":1,"maximum":1023,"example":256},"maximum":{"type":"integer","description":"Maximum accepted capacity per launch group.","example":1023},"effective_maximum":{"type":"integer","minimum":0,"maximum":1023,"description":"Maximum after applying the resolved hard cap and explicit headroom.","example":1023},"hard_cap":{"type":"integer","minimum":1,"maximum":1024,"description":"Hard cap resolved from the account and distribution settings.","example":1024},"headroom":{"type":"integer","minimum":0,"maximum":1023,"description":"Explicit seat margin; absent overrides use the product margin of zero.","example":0}}},"community_member_limit":{"type":"integer","example":2000},"community_provisioning":{"type":"object","additionalProperties":false,"required":["state","error_code","failed_at"],"properties":{"state":{"type":"string","enum":["not_requested","pending","created","failed"],"example":"not_requested","description":"Distribution member progress state."},"error_code":{"type":["string","null"],"enum":["missing_initial_participant","outcome_uncertain","feature_not_supported","gateway_rejected","gateway_unavailable","rate_limited","setup_step_failed","setup_step_refused","setup_incomplete","creator_inbox_unavailable","group_not_admin","group_not_found",null],"example":null},"failed_at":{"type":["string","null"],"format":"date-time","example":null}}},"next_sequence":{"type":"integer","minimum":1,"example":1},"effective_capacity":{"type":"integer","minimum":0,"maximum":1023,"description":"Minimum of the configured per-unit capacity and the effective maximum after the resolved hard cap and headroom.","example":256},"throttle_defaults":{"type":"object","additionalProperties":false,"required":["second","hour"],"description":"Default outbound limits for WhatsApp Web; operator overrides are kept in settings.","properties":{"second":{"type":"integer","example":1},"hour":{"type":"integer","example":240}}},"identity":{"type":"object","additionalProperties":false,"required":["mode","items","fallback","remaining_positions","exhausts_at_sequence","limits"],"properties":{"mode":{"type":"string","enum":["none","single","sequence"],"example":"sequence"},"items":{"type":"array","maxItems":100,"items":{"type":"object","additionalProperties":false,"required":["key","source","thumb_url","available","check"],"properties":{"key":{"type":"string","minLength":1,"example":"4711"},"source":{"type":"string","enum":["upload","library","url"],"example":"upload"},"media_asset_id":{"type":"integer","minimum":1,"example":44},"thumb_url":{"type":"string","description":"Center-cropped 160 by 160 representation URL, present only after the full image check succeeded; empty while the check is pending or invalid, when the file is unavailable, or when the representation fails.","example":""},"available":{"type":"boolean","description":"Whether the blob is still attached to this distribution.","example":true},"check":{"type":"object","additionalProperties":false,"required":["state","reason","checked_at","overdue"],"properties":{"state":{"type":"string","enum":["pending","ok","invalid"],"example":"pending","description":"Distribution member progress state."},"reason":{"type":["string","null"],"enum":["type","size","dimensions","unreadable","unavailable",null],"example":null},"checked_at":{"type":["string","null"],"format":"date-time","example":null},"overdue":{"type":"boolean","description":"Pending without a check time for at least 15 minutes since attachment creation; false without the check column or attachment.","example":false}}}}}},"fallback":{"oneOf":[{"type":"object","additionalProperties":false,"required":["key","source","thumb_url","available","check"],"properties":{"key":{"type":"string","minLength":1,"example":"4711"},"source":{"type":"string","enum":["upload","library","url"],"example":"upload"},"media_asset_id":{"type":"integer","minimum":1,"example":44},"thumb_url":{"type":"string","description":"Center-cropped 160 by 160 representation URL, present only after the full image check succeeded; empty while the check is pending or invalid, when the file is unavailable, or when the representation fails.","example":""},"available":{"type":"boolean","description":"Whether the blob is still attached to this distribution.","example":true},"check":{"type":"object","additionalProperties":false,"required":["state","reason","checked_at","overdue"],"properties":{"state":{"type":"string","enum":["pending","ok","invalid"],"example":"pending","description":"Distribution member progress state."},"reason":{"type":["string","null"],"enum":["type","size","dimensions","unreadable","unavailable",null],"example":null},"checked_at":{"type":["string","null"],"format":"date-time","example":null},"overdue":{"type":"boolean","description":"Pending without a check time for at least 15 minutes since attachment creation; false without the check column or attachment.","example":false}}}}},{"type":"null"}]},"limits":{"type":"object","additionalProperties":false,"required":["max_bytes","max_side","max_items","content_types","check_overdue_after_seconds"],"properties":{"max_bytes":{"type":"integer","example":8388608},"max_side":{"type":"integer","example":4096},"max_items":{"type":"integer","example":100},"check_overdue_after_seconds":{"type":"integer","example":900},"content_types":{"type":"array","items":{"type":"string","enum":["image/jpeg","image/png"]},"example":["image/jpeg","image/png"]}}},"remaining_positions":{"type":["integer","null"],"minimum":0,"description":"Remaining own-image positions from next_sequence; null outside sequence mode.","example":2},"exhausts_at_sequence":{"type":["integer","null"],"minimum":0,"description":"Number of own-image positions; null outside sequence mode.","example":2}}},"setup_capabilities":{"type":"object","description":"Birth-setting support by step. Only live capabilities support the listed destination types; partial_contract is unavailable.","additionalProperties":{"type":"object","additionalProperties":false,"required":["tier","target_types"],"properties":{"tier":{"type":"string","enum":["live","partial_contract"]},"target_types":{"type":"array","items":{"type":"string","enum":["group","community"]}}}},"example":{"join_approval":{"tier":"partial_contract","target_types":["group","community"]},"locked":{"tier":"live","target_types":["group","community"]},"member_add_mode":{"tier":"partial_contract","target_types":["group","community"]},"ephemeral":{"tier":"live","target_types":["group","community"]}}},"setup_pause_defaults":{"type":"object","additionalProperties":false,"required":["default_seconds","jitter_seconds","max_seconds"],"description":"Server defaults and operator bounds for setup pacing. Jitter is added only to positive pauses.","properties":{"default_seconds":{"type":"integer","minimum":0,"description":"Base pause inherited when no override is set.","example":3},"jitter_seconds":{"type":"integer","minimum":0,"description":"Maximum random delay added to a positive base pause.","example":2},"max_seconds":{"type":"integer","minimum":0,"description":"Maximum configurable base pause before jitter.","example":60}},"example":{"default_seconds":3,"jitter_seconds":2,"max_seconds":60}},"id":{"type":"integer","example":22},"account_id":{"type":"integer","example":1},"name":{"type":"string","example":"October launch"},"slug":{"type":"string","example":"october-launch"},"public_path":{"type":"string","example":"/g/october-launch"},"inbox_id":{"type":"integer","example":6},"logical_inbox_id":{"type":"integer","description":"Present when the visible logical inbox differs from the transport inbox.","example":15},"launch_id":{"type":["integer","null"],"example":null},"target_type":{"type":"string","enum":["community","group","channel"],"example":"group"},"join_mode":{"type":"string","enum":["invite_link","direct_add","both"],"example":"invite_link"},"capacity_per_unit":{"type":"integer","minimum":1,"maximum":1023,"example":256},"community_jid":{"type":["string","null"],"example":null},"channel_jid":{"type":["string","null"],"example":null},"naming_template":{"type":"string","example":"Launch group {n}"},"welcome_message":{"type":["string","null"],"example":null},"status":{"type":"string","enum":["draft","active","paused","completed"],"example":"draft"},"settings":{"type":"object","additionalProperties":true,"description":"Operator configuration excluding system-owned diagnostics; other configuration keys are preserved.","properties":{"join_approval":{"type":["boolean","null"],"enum":[true,false,null],"description":"Require administrator approval to join. Null inherits WhatsApp. New or changed non-null values require a live capability tier for the destination. An unchanged saved value is accepted on update when the destination stays the same.","example":null},"join_approval_policy":{"type":["string","null"],"enum":["manual","all_while_seats",null],"description":"Null defaults effectively to all_while_seats when join_approval is true. A new or changed non-null policy requires a live join_approval capability tier for the destination. An unchanged saved policy is accepted on update when the destination stays the same. Manual only counts pending requests.","example":null},"locked":{"type":["boolean","null"],"enum":[true,false,null],"description":"Restrict group information edits to administrators. Explicit null keeps WhatsApp's existing setting. Omission follows the rules described for each operation.","example":true},"member_add_mode":{"type":["string","null"],"enum":["admin_add","all_member_add",null],"description":"Who may add members. Null inherits WhatsApp. New or changed non-null values require a live capability tier for the destination. An unchanged saved value is accepted on update when the destination stays the same.","example":null},"ephemeral_seconds":{"type":["integer","null"],"enum":[0,86400,604800,7776000,null],"description":"Disappearing-message duration in seconds; zero disables the timer and null inherits WhatsApp.","example":86400},"setup_pause_seconds":{"type":["integer","null"],"minimum":0,"maximum":60,"default":3,"description":"Base delay between setup delegations, plus zero to two seconds of jitter. Zero disables pauses; null uses three seconds.","example":3},"identity":{"type":"object","additionalProperties":false,"required":["photo"],"properties":{"photo":{"type":"object","additionalProperties":false,"required":["mode","items","fallback"],"properties":{"mode":{"type":"string","enum":["none","single","sequence"],"example":"sequence"},"items":{"type":"array","maxItems":100,"description":"Ordered blob references. Single requires one item; none requires an empty list.","items":{"type":"object","additionalProperties":false,"required":["key","source"],"properties":{"key":{"type":"string","minLength":1,"description":"Blob id attached to this distribution.","example":"4711"},"source":{"type":"string","enum":["upload","library","url"],"example":"upload"},"media_asset_id":{"type":"integer","minimum":1,"description":"Original Library asset, when selected from the Library.","example":44}}}},"fallback":{"description":"Image used after the sequence ends or when a selected image is unavailable.","oneOf":[{"type":"object","additionalProperties":false,"required":["key","source"],"properties":{"key":{"type":"string","minLength":1,"description":"Blob id attached to this distribution.","example":"4711"},"source":{"type":"string","enum":["upload","library","url"],"example":"upload"},"media_asset_id":{"type":"integer","minimum":1,"description":"Original Library asset, when selected from the Library.","example":44}}},{"type":"null"}]}}}}},"photo_url":{"type":["string","null"],"description":"Inherited group photo link. An explicit unit photo overrides the distribution identity; without a unit override the distribution identity wins, then the inherited URL. HTTP is accepted only for an authorized image blob of this account on the canonical application origin, with a valid signed blob URL and no credentials, query or fragment. External URLs require HTTPS.","example":"https://images.example.test/legacy-cover.jpg"},"description":{"type":["string","null"],"description":"Group description; each occurrence of {n} is replaced with the unit sequence.","example":"Welcome to launch group {n}."}}},"entry_trigger_catalog":{"type":"array","description":"Complete list of selectable entry keys, shared with server validation. Text is localized for the request. Translation keys belong to the server translation catalog. Availability of a key does not guarantee an event producer, an eligible contact or an enrollment effect.","items":{"type":"object","additionalProperties":false,"required":["key","label_key","description_key","label","description"],"properties":{"key":{"type":"string","description":"A selectable launch distribution entry key backed by an enrollment consumer. Payment confirmed emissions use payment_charge.paid.","enum":["payment_charge.paid","payment_charge.overdue","crm_item.stage_changed","crm_item.stale","crm_item.won","task.overdue","task.due_soon","calendar_event.created","calendar_event.no_show","commerce.cart_abandoned","commerce.order_placed","commerce.payment_pending","commerce.payment_confirmed","commerce.payment_declined","commerce.overdue","commerce.due_soon","commerce.refunded","commerce.chargeback","commerce.subscription_late","commerce.subscription_canceled","ads.lead_captured","social.comment_captured"],"example":"payment_charge.paid"},"label_key":{"type":"string","description":"Server translation key for the label.","example":"growth.distribution.entry_triggers.events.payment_charge_paid.label"},"description_key":{"type":"string","description":"Server translation key for the description.","example":"growth.distribution.entry_triggers.events.payment_charge_paid.description"},"label":{"type":"string","description":"Localized label.","example":"Charge paid"},"description":{"type":"string","description":"Localized explanation of the entry signal.","example":"A confirmed or paid charge payment, admitted through the payment_charge.paid key."}}},"example":[{"key":"payment_charge.paid","label_key":"growth.distribution.entry_triggers.events.payment_charge_paid.label","description_key":"growth.distribution.entry_triggers.events.payment_charge_paid.description","label":"Charge paid","description":"A confirmed or paid charge payment, admitted through the payment_charge.paid key."}]},"entry_trigger_validation":{"type":"object","additionalProperties":false,"required":["valid","invalid_type","invalid_indexes"],"description":"Advisory validation of the stored entry list, without changing it. Read invalid values from settings.entry_triggers at the reported positions. A malformed non-array value has invalid_type true and no positions. An absent list is valid and equivalent to an empty list.","properties":{"valid":{"type":"boolean","example":false},"invalid_type":{"type":"boolean","example":false},"invalid_indexes":{"type":"array","description":"Zero-based positions of unknown keys or elements that are not strings.","items":{"type":"integer","minimum":0},"example":[0]}},"example":{"valid":false,"invalid_type":false,"invalid_indexes":[0]}},"configuration_options":{"type":"object","additionalProperties":false,"required":["routing_sources","template_keys"],"description":"Recognized routing sources and stored template identifiers from the same server sets used by validation. Template membership does not imply a send: the join-template and overdue-warning selectors currently have no operational send consumer and must be presented as unavailable.","properties":{"routing_sources":{"type":"array","items":{"type":"string","enum":["link","automation","event","manual","api","follow_up"]}},"template_keys":{"type":"array","items":{"type":"string","enum":["welcome","reminder","countdown","unit_opened","waitlist_ack","removed_notice","graduated_notice"]}}},"example":{"routing_sources":["link","automation","event","manual","api","follow_up"],"template_keys":["welcome","reminder","countdown","unit_opened","waitlist_ack","removed_notice","graduated_notice"]}},"configuration_validation":{"type":"object","additionalProperties":false,"required":["valid","issues"],"description":"Diagnostics for saved and resolved choices without removing or rewriting them. Paths are relative to the settings document; inherited values also remain available in settings explanations.","properties":{"valid":{"type":"boolean","example":true},"issues":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["path","code"],"properties":{"path":{"type":"string","example":"algorithm.routing_rules[0].match.source"},"code":{"type":"string","enum":["invalid_type","unknown_choice","unknown_key"],"example":"unknown_choice"}}}}},"example":{"valid":true,"issues":[]}},"units_count":{"type":"integer","minimum":0,"example":0},"members_count":{"type":"integer","minimum":0,"example":0},"capacity_total":{"type":"integer","minimum":0,"description":"Sum of current effective capacities across all units, including explicit unit overrides.","example":0},"occupancy_total":{"type":"integer","minimum":0,"description":"Sum of the synced member count of every unit.","example":0},"awaiting_count":{"type":"integer","minimum":0,"description":"Members still pending, queued or waitlisted.","example":0},"open_unit_sequence":{"type":["integer","null"],"example":null},"closes_at":{"type":["string","null"],"format":"date-time","description":"Configured distribution closing time; null means no closing time is set.","example":null},"archived_at":{"type":["string","null"],"format":"date-time","example":null},"created_at":{"type":"string","format":"date-time","example":"2026-10-13T22:00:00Z"},"updated_at":{"type":"string","format":"date-time","example":"2026-10-13T22:00:00Z"},"slug_collision":{"type":"boolean","description":"Whether the current public slug is shared with another distribution.","example":false},"slug_retired_from":{"type":["string","null"],"description":"Former public slug retired after a collision, or null.","example":null}}}}},"example":{"payload":{"algorithm":"fill_first","opens_at":null,"fallback_distribution_id":null,"graduate_distribution_id":null,"advanced_enabled":false,"capacity_defaults":{"default":256,"maximum":1023,"effective_maximum":1023,"hard_cap":1024,"headroom":0},"community_member_limit":2000,"community_provisioning":{"state":"not_requested","error_code":null,"failed_at":null},"next_sequence":1,"effective_capacity":256,"throttle_defaults":{"second":1,"hour":240},"identity":{"mode":"none","items":[{"key":"4711","source":"upload","media_asset_id":44,"thumb_url":"","available":true,"check":{"state":"pending","reason":null,"checked_at":null,"overdue":false}}],"fallback":null,"limits":{"max_bytes":8388608,"max_side":4096,"max_items":100,"check_overdue_after_seconds":900,"content_types":["image/jpeg","image/png"]},"remaining_positions":null,"exhausts_at_sequence":null},"entry_trigger_catalog":[{"key":"payment_charge.paid","label_key":"growth.distribution.entry_triggers.events.payment_charge_paid.label","description_key":"growth.distribution.entry_triggers.events.payment_charge_paid.description","label":"Charge paid","description":"A confirmed or paid charge payment, admitted through the payment_charge.paid key."}],"entry_trigger_validation":{"valid":true,"invalid_type":false,"invalid_indexes":[]},"configuration_options":{"routing_sources":["link","automation","event","manual","api","follow_up"],"template_keys":["welcome","reminder","countdown","unit_opened","waitlist_ack","removed_notice","graduated_notice"]},"configuration_validation":{"valid":true,"issues":[{"path":"algorithm.routing_rules[0].match.source","code":"unknown_choice"}]},"setup_capabilities":{"join_approval":{"tier":"partial_contract","target_types":["group","community"]},"locked":{"tier":"live","target_types":["group","community"]},"member_add_mode":{"tier":"partial_contract","target_types":["group","community"]},"ephemeral":{"tier":"live","target_types":["group","community"]}},"setup_pause_defaults":{"default_seconds":3,"jitter_seconds":2,"max_seconds":60},"id":23,"account_id":1,"name":"October launch (copy)","slug":"october-launch-copy-a1b2c3","public_path":"/g/october-launch-copy-a1b2c3","inbox_id":6,"logical_inbox_id":15,"launch_id":null,"target_type":"group","join_mode":"invite_link","capacity_per_unit":256,"community_jid":null,"channel_jid":null,"naming_template":"Launch group {n}","welcome_message":null,"status":"draft","settings":{"locked":true,"description":"Welcome to launch group {n}.","photo_url":"https://images.example.test/legacy-cover.jpg","join_approval":null,"join_approval_policy":null,"member_add_mode":null,"ephemeral_seconds":86400,"setup_pause_seconds":3,"identity":{"photo":{"mode":"sequence","items":[{"key":"4711","source":"upload","media_asset_id":44}],"fallback":{"key":"4711","source":"upload","media_asset_id":44}}}},"units_count":0,"members_count":0,"capacity_total":0,"occupancy_total":0,"awaiting_count":0,"open_unit_sequence":null,"closes_at":null,"archived_at":null,"created_at":"2026-10-13T22:00:00Z","updated_at":"2026-10-13T22:00:00Z","slug_collision":false,"slug_retired_from":null}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"422":{"description":"Invalid identity or distribution configuration; nothing is saved.","content":{"application/json":{"schema":{"oneOf":[{"type":"object","additionalProperties":false,"required":["error","keys","message","entry_trigger_validation"],"properties":{"error":{"type":"string","enum":["invalid_entry_triggers"],"example":"invalid_entry_triggers"},"keys":{"type":"array","items":{"type":"string","enum":["settings.entry_triggers"]},"example":["settings.entry_triggers"]},"message":{"type":"string","description":"Localized correction instructions.","example":"Choose entry triggers from the available list. Correct or remove unknown keys before changing that list."},"entry_trigger_validation":{"type":"object","additionalProperties":false,"required":["valid","invalid_type","invalid_indexes"],"description":"Advisory validation of the stored entry list, without changing it. Read invalid values from settings.entry_triggers at the reported positions. A malformed non-array value has invalid_type true and no positions. An absent list is valid and equivalent to an empty list.","properties":{"valid":{"type":"boolean","example":false},"invalid_type":{"type":"boolean","example":false},"invalid_indexes":{"type":"array","description":"Zero-based positions of unknown keys or elements that are not strings.","items":{"type":"integer","minimum":0},"example":[0]}},"example":{"valid":false,"invalid_type":false,"invalid_indexes":[0]}}},"example":{"error":"invalid_entry_triggers","keys":["settings.entry_triggers"],"message":"Choose entry triggers from the available list. Correct or remove unknown keys before changing that list.","entry_trigger_validation":{"valid":false,"invalid_type":false,"invalid_indexes":[0]}}},{"type":"object","additionalProperties":false,"required":["error","keys","message","configuration_validation"],"properties":{"error":{"type":"string","enum":["invalid_configuration_choices"],"example":"invalid_configuration_choices"},"keys":{"type":"array","items":{"type":"string","enum":["algorithm.routing_rules","dm_on_join.template","post_purchase.on_overdue.warn_template"]},"example":["dm_on_join.template"]},"message":{"type":"string","example":"Choose a source or template from the available list. Correct or remove unknown values before changing these fields."},"configuration_validation":{"type":"object","additionalProperties":false,"required":["valid","issues"],"description":"Diagnostics for saved and resolved choices without removing or rewriting them. Paths are relative to the settings document; inherited values also remain available in settings explanations.","properties":{"valid":{"type":"boolean","example":true},"issues":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["path","code"],"properties":{"path":{"type":"string","example":"algorithm.routing_rules[0].match.source"},"code":{"type":"string","enum":["invalid_type","unknown_choice","unknown_key"],"example":"unknown_choice"}}}}},"example":{"valid":true,"issues":[]}}}},{"type":"object","additionalProperties":false,"required":["error","setting","message"],"properties":{"error":{"type":"string","enum":["setup_capability_unavailable"],"example":"setup_capability_unavailable"},"setting":{"type":"string","enum":["join_approval","locked","member_add_mode","ephemeral_seconds"],"example":"join_approval"},"message":{"type":"string","example":"This setting cannot be used on this distribution yet."}}},{"type":"object","additionalProperties":false,"required":["error","message"],"properties":{"error":{"type":"string","enum":["identity_invalid"],"example":"identity_invalid"},"message":{"type":"string","example":"The launch group image configuration is invalid. Review the mode and selected items."}}},{"type":"object","additionalProperties":false,"required":["error","message","items"],"properties":{"error":{"type":"string","enum":["identity_image_invalid"],"example":"identity_image_invalid"},"message":{"type":"string","example":"One or more launch group images are invalid or unavailable. Review the indicated items."},"items":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["index","reason","message"],"properties":{"index":{"description":"Zero-based item position, or fallback for the fallback image.","oneOf":[{"type":"integer","minimum":0},{"type":"string","enum":["fallback"]}],"example":1},"reason":{"type":"string","enum":["type","size","dimensions","unreadable","unavailable"],"example":"size"},"message":{"type":"string","description":"Localized explanation with the applicable limit.","example":"The image must be no larger than 8 MB."}}}}}},{"type":"object","additionalProperties":false,"required":["error","keys"],"properties":{"error":{"type":"string","enum":["invalid_settings"],"example":"invalid_settings"},"keys":{"type":"array","description":"Rejected section or section.key paths of settings_overrides, in submission order without duplicates.","items":{"type":"string"},"example":["sellers.strategy"]}}},{"type":"object","additionalProperties":false,"required":["message","attributes"],"properties":{"message":{"type":"string","example":"Name cannot be blank"},"attributes":{"type":"array","description":"Distribution attributes rejected by model validation.","items":{"type":"string"},"example":["name"]}}},{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","description":"Framework message for an invalid enum value or other invalid request parameter.","example":"'unsupported' is not a valid target_type"}}}]},"examples":{"invalid_configuration_choices":{"value":{"error":"invalid_configuration_choices","keys":["dm_on_join.template"],"message":"Choose a source or template from the available list. Correct or remove unknown values before changing these fields.","configuration_validation":{"valid":false,"issues":[{"path":"dm_on_join.template","code":"unknown_choice"}]}}},"invalid_entry_triggers":{"value":{"error":"invalid_entry_triggers","keys":["settings.entry_triggers"],"message":"Choose entry triggers from the available list. Correct or remove unknown keys before changing that list.","entry_trigger_validation":{"valid":false,"invalid_type":false,"invalid_indexes":[0]}}},"setup_capability":{"value":{"error":"setup_capability_unavailable","setting":"join_approval","message":"This setting cannot be used on this distribution yet."}},"structure":{"value":{"error":"identity_invalid","message":"The launch group image configuration is invalid. Review the mode and selected items.","keys":["settings.entry_triggers"],"entry_trigger_validation":{"valid":false,"invalid_type":false,"invalid_indexes":[0]}}},"image":{"value":{"error":"identity_image_invalid","message":"One or more launch group images are invalid or unavailable. Review the indicated items.","items":[{"index":1,"reason":"size","message":"The image must be no larger than 8 MB."},{"index":"fallback","reason":"unavailable","message":"The image is unavailable. Upload another image."}]}},"invalid_settings":{"value":{"error":"invalid_settings","keys":["sellers.strategy"],"message":"Choose entry triggers from the available list. Correct or remove unknown keys before changing that list.","entry_trigger_validation":{"valid":false,"invalid_type":false,"invalid_indexes":[0]}}},"model_validation":{"value":{"message":"Name cannot be blank","attributes":["name"]}},"enum_validation":{"value":{"error":"'unsupported' is not a valid target_type","keys":["settings.entry_triggers"],"message":"Choose entry triggers from the available list. Correct or remove unknown keys before changing that list.","entry_trigger_validation":{"valid":false,"invalid_type":false,"invalid_indexes":[0]}}}}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"unit_id":{"type":"integer"}}},"example":{"unit_id":1}}}}}},"/api/v1/accounts/{account_id}/growth/distributions/{id}/retry_provision":{"post":{"tags":["Growth Distribution"],"operationId":"auto_post_api_v1_accounts_account_id_growth_distributions_id_retry_provision","summary":"Retry one reconciled launch-unit provision","description":"Administrator-only recovery for a launch unit whose WhatsApp group creation has an uncertain outcome. The caller must have verified that the group does not exist and submit the JSON boolean `confirmed_absent: true`; strings and other truthy values are refused. The operation only releases the existing failed unit and queues the normal advance job, preserving its sequence. It never creates a new unit directly and it is refused unless the stored diagnostic requires reconciliation. A unit that already has a WhatsApp group is always refused (`unit_already_provisioned`): the rotation resumes that group by itself and never creates it again. The unit diagnostic field `retry_allowed` tells a client when this operation is valid.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The existing distribution is active and its normal provision advance was queued.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["payload"],"properties":{"payload":{"type":"object","additionalProperties":false,"required":["id","account_id","name","slug","slug_collision","slug_retired_from","public_path","inbox_id","target_type","join_mode","capacity_per_unit","algorithm","opens_at","fallback_distribution_id","graduate_distribution_id","advanced_enabled","capacity_defaults","community_member_limit","community_provisioning","naming_template","status","settings","entry_trigger_catalog","entry_trigger_validation","configuration_options","configuration_validation","units_count","members_count","created_at","updated_at","next_sequence","effective_capacity","throttle_defaults","identity"],"properties":{"algorithm":{"type":"string","enum":["fill_first","round_robin","random","weighted"],"example":"fill_first"},"opens_at":{"type":["string","null"],"format":"date-time","description":"Distribution opening time, when configured.","example":null},"fallback_distribution_id":{"type":["integer","null"],"example":null},"graduate_distribution_id":{"type":["integer","null"],"example":null},"advanced_enabled":{"type":"boolean","description":"Whether advanced launch distribution features are enabled for this account.","example":false},"capacity_defaults":{"type":"object","additionalProperties":false,"required":["default","maximum","effective_maximum","hard_cap","headroom"],"description":"Resolved capacity limits. On defaults, default is the account per-unit setting; on distribution resources it is the product default of 256. Effective maximum is min(1023, hard_cap minus headroom). An existing explicit per-unit setting is preserved when the account defaults change.","properties":{"default":{"type":"integer","minimum":1,"maximum":1023,"example":256},"maximum":{"type":"integer","description":"Maximum accepted capacity per launch group.","example":1023},"effective_maximum":{"type":"integer","minimum":0,"maximum":1023,"description":"Maximum after applying the resolved hard cap and explicit headroom.","example":1023},"hard_cap":{"type":"integer","minimum":1,"maximum":1024,"description":"Hard cap resolved from the account and distribution settings.","example":1024},"headroom":{"type":"integer","minimum":0,"maximum":1023,"description":"Explicit seat margin; absent overrides use the product margin of zero.","example":0}}},"community_member_limit":{"type":"integer","example":2000},"community_provisioning":{"type":"object","additionalProperties":false,"required":["state","error_code","failed_at"],"properties":{"state":{"type":"string","enum":["not_requested","pending","created","failed"],"example":"not_requested","description":"Distribution member progress state."},"error_code":{"type":["string","null"],"enum":["missing_initial_participant","outcome_uncertain","feature_not_supported","gateway_rejected","gateway_unavailable","rate_limited","setup_step_failed","setup_step_refused","setup_incomplete","creator_inbox_unavailable","group_not_admin","group_not_found",null],"example":null},"failed_at":{"type":["string","null"],"format":"date-time","example":null}}},"next_sequence":{"type":"integer","minimum":1,"example":1},"effective_capacity":{"type":"integer","minimum":0,"maximum":1023,"description":"Minimum of the configured per-unit capacity and the effective maximum after the resolved hard cap and headroom.","example":256},"throttle_defaults":{"type":"object","additionalProperties":false,"required":["second","hour"],"description":"Default outbound limits for WhatsApp Web; operator overrides are kept in settings.","properties":{"second":{"type":"integer","example":1},"hour":{"type":"integer","example":240}}},"identity":{"type":"object","additionalProperties":false,"required":["mode","items","fallback","remaining_positions","exhausts_at_sequence","limits"],"properties":{"mode":{"type":"string","enum":["none","single","sequence"],"example":"sequence"},"items":{"type":"array","maxItems":100,"items":{"type":"object","additionalProperties":false,"required":["key","source","thumb_url","available","check"],"properties":{"key":{"type":"string","minLength":1,"example":"4711"},"source":{"type":"string","enum":["upload","library","url"],"example":"upload"},"media_asset_id":{"type":"integer","minimum":1,"example":44},"thumb_url":{"type":"string","description":"Center-cropped 160 by 160 representation URL, present only after the full image check succeeded; empty while the check is pending or invalid, when the file is unavailable, or when the representation fails.","example":""},"available":{"type":"boolean","description":"Whether the blob is still attached to this distribution.","example":true},"check":{"type":"object","additionalProperties":false,"required":["state","reason","checked_at","overdue"],"properties":{"state":{"type":"string","enum":["pending","ok","invalid"],"example":"pending","description":"Distribution member progress state."},"reason":{"type":["string","null"],"enum":["type","size","dimensions","unreadable","unavailable",null],"example":null},"checked_at":{"type":["string","null"],"format":"date-time","example":null},"overdue":{"type":"boolean","description":"Pending without a check time for at least 15 minutes since attachment creation; false without the check column or attachment.","example":false}}}}}},"fallback":{"oneOf":[{"type":"object","additionalProperties":false,"required":["key","source","thumb_url","available","check"],"properties":{"key":{"type":"string","minLength":1,"example":"4711"},"source":{"type":"string","enum":["upload","library","url"],"example":"upload"},"media_asset_id":{"type":"integer","minimum":1,"example":44},"thumb_url":{"type":"string","description":"Center-cropped 160 by 160 representation URL, present only after the full image check succeeded; empty while the check is pending or invalid, when the file is unavailable, or when the representation fails.","example":""},"available":{"type":"boolean","description":"Whether the blob is still attached to this distribution.","example":true},"check":{"type":"object","additionalProperties":false,"required":["state","reason","checked_at","overdue"],"properties":{"state":{"type":"string","enum":["pending","ok","invalid"],"example":"pending","description":"Distribution member progress state."},"reason":{"type":["string","null"],"enum":["type","size","dimensions","unreadable","unavailable",null],"example":null},"checked_at":{"type":["string","null"],"format":"date-time","example":null},"overdue":{"type":"boolean","description":"Pending without a check time for at least 15 minutes since attachment creation; false without the check column or attachment.","example":false}}}}},{"type":"null"}]},"limits":{"type":"object","additionalProperties":false,"required":["max_bytes","max_side","max_items","content_types","check_overdue_after_seconds"],"properties":{"max_bytes":{"type":"integer","example":8388608},"max_side":{"type":"integer","example":4096},"max_items":{"type":"integer","example":100},"check_overdue_after_seconds":{"type":"integer","example":900},"content_types":{"type":"array","items":{"type":"string","enum":["image/jpeg","image/png"]},"example":["image/jpeg","image/png"]}}},"remaining_positions":{"type":["integer","null"],"minimum":0,"description":"Remaining own-image positions from next_sequence; null outside sequence mode.","example":2},"exhausts_at_sequence":{"type":["integer","null"],"minimum":0,"description":"Number of own-image positions; null outside sequence mode.","example":2}}},"id":{"type":"integer","example":22},"account_id":{"type":"integer","example":1},"name":{"type":"string","example":"Lista de espera — setembro"},"slug":{"type":"string","example":"lista-de-espera-setembro"},"slug_collision":{"type":"boolean","description":"Whether the current public slug is shared by another persisted distribution. A provisioned slug may be changed only while this is true.","example":false},"slug_retired_from":{"type":["string","null"],"description":"Former public slug of this distribution. Set when that slug was shared with another distribution and retired for good; the distribution then received its current slug and the old links stopped working. Null when the slug was never retired.","example":null},"public_path":{"type":"string","example":"/g/lista-de-espera-setembro"},"inbox_id":{"type":"integer","example":6},"logical_inbox_id":{"type":"integer","example":15},"launch_id":{"type":["integer","null"],"example":null},"target_type":{"type":"string","enum":["community","group","channel"],"example":"group"},"join_mode":{"type":"string","enum":["invite_link","direct_add","both"],"example":"invite_link"},"capacity_per_unit":{"type":"integer","example":900},"community_jid":{"type":["string","null"],"example":null},"channel_jid":{"type":["string","null"],"example":null},"naming_template":{"type":"string","example":"Turma {n}"},"welcome_message":{"type":["string","null"],"example":null},"status":{"type":"string","enum":["draft","active","paused","completed"],"example":"active"},"entry_trigger_catalog":{"type":"array","description":"Complete list of selectable entry keys, shared with server validation. Text is localized for the request. Translation keys belong to the server translation catalog. Availability of a key does not guarantee an event producer, an eligible contact or an enrollment effect.","items":{"type":"object","additionalProperties":false,"required":["key","label_key","description_key","label","description"],"properties":{"key":{"type":"string","description":"A selectable launch distribution entry key backed by an enrollment consumer. Payment confirmed emissions use payment_charge.paid.","enum":["payment_charge.paid","payment_charge.overdue","crm_item.stage_changed","crm_item.stale","crm_item.won","task.overdue","task.due_soon","calendar_event.created","calendar_event.no_show","commerce.cart_abandoned","commerce.order_placed","commerce.payment_pending","commerce.payment_confirmed","commerce.payment_declined","commerce.overdue","commerce.due_soon","commerce.refunded","commerce.chargeback","commerce.subscription_late","commerce.subscription_canceled","ads.lead_captured","social.comment_captured"],"example":"payment_charge.paid"},"label_key":{"type":"string","description":"Server translation key for the label.","example":"growth.distribution.entry_triggers.events.payment_charge_paid.label"},"description_key":{"type":"string","description":"Server translation key for the description.","example":"growth.distribution.entry_triggers.events.payment_charge_paid.description"},"label":{"type":"string","description":"Localized label.","example":"Charge paid"},"description":{"type":"string","description":"Localized explanation of the entry signal.","example":"A confirmed or paid charge payment, admitted through the payment_charge.paid key."}}},"example":[{"key":"payment_charge.paid","label_key":"growth.distribution.entry_triggers.events.payment_charge_paid.label","description_key":"growth.distribution.entry_triggers.events.payment_charge_paid.description","label":"Charge paid","description":"A confirmed or paid charge payment, admitted through the payment_charge.paid key."}]},"entry_trigger_validation":{"type":"object","additionalProperties":false,"required":["valid","invalid_type","invalid_indexes"],"description":"Advisory validation of the stored entry list, without changing it. Read invalid values from settings.entry_triggers at the reported positions. A malformed non-array value has invalid_type true and no positions. An absent list is valid and equivalent to an empty list.","properties":{"valid":{"type":"boolean","example":false},"invalid_type":{"type":"boolean","example":false},"invalid_indexes":{"type":"array","description":"Zero-based positions of unknown keys or elements that are not strings.","items":{"type":"integer","minimum":0},"example":[0]}},"example":{"valid":false,"invalid_type":false,"invalid_indexes":[0]}},"configuration_options":{"type":"object","additionalProperties":false,"required":["routing_sources","template_keys"],"description":"Recognized routing sources and stored template identifiers from the same server sets used by validation. Template membership does not imply a send: the join-template and overdue-warning selectors currently have no operational send consumer and must be presented as unavailable.","properties":{"routing_sources":{"type":"array","items":{"type":"string","enum":["link","automation","event","manual","api","follow_up"]}},"template_keys":{"type":"array","items":{"type":"string","enum":["welcome","reminder","countdown","unit_opened","waitlist_ack","removed_notice","graduated_notice"]}}},"example":{"routing_sources":["link","automation","event","manual","api","follow_up"],"template_keys":["welcome","reminder","countdown","unit_opened","waitlist_ack","removed_notice","graduated_notice"]}},"configuration_validation":{"type":"object","additionalProperties":false,"required":["valid","issues"],"description":"Diagnostics for saved and resolved choices without removing or rewriting them. Paths are relative to the settings document; inherited values also remain available in settings explanations.","properties":{"valid":{"type":"boolean","example":true},"issues":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["path","code"],"properties":{"path":{"type":"string","example":"algorithm.routing_rules[0].match.source"},"code":{"type":"string","enum":["invalid_type","unknown_choice","unknown_key"],"example":"unknown_choice"}}}}},"example":{"valid":true,"issues":[]}},"settings":{"type":"object","additionalProperties":true,"description":"Operator configuration excluding system-owned provisioning diagnostics.","properties":{"join_approval":{"type":["boolean","null"],"enum":[true,false,null],"description":"Require administrator approval to join. Null inherits WhatsApp. New or changed non-null values require a live capability tier for the destination. An unchanged saved value is accepted on update when the destination stays the same.","example":null},"join_approval_policy":{"type":["string","null"],"enum":["manual","all_while_seats",null],"description":"Null defaults effectively to all_while_seats when join_approval is true. A new or changed non-null policy requires a live join_approval capability tier for the destination. An unchanged saved policy is accepted on update when the destination stays the same. Manual only counts pending requests.","example":null},"locked":{"type":["boolean","null"],"enum":[true,false,null],"description":"Restrict group information edits to administrators. Explicit null keeps WhatsApp's existing setting. Omission follows the rules described for each operation.","example":true},"member_add_mode":{"type":["string","null"],"enum":["admin_add","all_member_add",null],"description":"Who may add members. Null inherits WhatsApp. New or changed non-null values require a live capability tier for the destination. An unchanged saved value is accepted on update when the destination stays the same.","example":null},"ephemeral_seconds":{"type":["integer","null"],"enum":[0,86400,604800,7776000,null],"description":"Disappearing-message duration in seconds; zero disables the timer and null inherits WhatsApp.","example":86400},"setup_pause_seconds":{"type":["integer","null"],"minimum":0,"maximum":60,"default":3,"description":"Base delay between setup delegations, plus zero to two seconds of jitter. Zero disables pauses; null uses three seconds.","example":3},"identity":{"type":"object","additionalProperties":false,"required":["photo"],"properties":{"photo":{"type":"object","additionalProperties":false,"required":["mode","items","fallback"],"properties":{"mode":{"type":"string","enum":["none","single","sequence"],"example":"sequence"},"items":{"type":"array","maxItems":100,"description":"Ordered blob references. Single requires one item; none requires an empty list.","items":{"type":"object","additionalProperties":false,"required":["key","source"],"properties":{"key":{"type":"string","minLength":1,"description":"Blob id attached to this distribution.","example":"4711"},"source":{"type":"string","enum":["upload","library","url"],"example":"upload"},"media_asset_id":{"type":"integer","minimum":1,"description":"Original Library asset, when selected from the Library.","example":44}}}},"fallback":{"description":"Image used after the sequence ends or when a selected image is unavailable.","oneOf":[{"type":"object","additionalProperties":false,"required":["key","source"],"properties":{"key":{"type":"string","minLength":1,"description":"Blob id attached to this distribution.","example":"4711"},"source":{"type":"string","enum":["upload","library","url"],"example":"upload"},"media_asset_id":{"type":"integer","minimum":1,"description":"Original Library asset, when selected from the Library.","example":44}}},{"type":"null"}]}}}}},"photo_url":{"type":["string","null"],"description":"Inherited group photo link. An explicit unit photo overrides the distribution identity; without a unit override the distribution identity wins, then the inherited URL. HTTP is accepted only for an authorized image blob of this account on the canonical application origin, with a valid signed blob URL and no credentials, query or fragment. External URLs require HTTPS.","example":"https://images.example.test/legacy-cover.jpg"},"description":{"type":["string","null"],"description":"Group description; each occurrence of {n} is replaced with the unit sequence.","example":"Welcome to launch group {n}."}},"example":{"admins":["5511987654321"],"description":"Aquecimento de lançamento"}},"units_count":{"type":"integer","example":1},"members_count":{"type":"integer","example":0},"capacity_total":{"type":"integer","minimum":0,"description":"Sum of current effective capacities across all units, including explicit unit overrides.","example":0},"occupancy_total":{"type":"integer","minimum":0,"description":"Sum of the synced member count of every unit.","example":0},"awaiting_count":{"type":"integer","minimum":0,"description":"Members still pending, queued or waitlisted.","example":0},"open_unit_sequence":{"type":["integer","null"],"example":null},"archived_at":{"type":["string","null"],"format":"date-time","example":null},"created_at":{"type":"string","format":"date-time","example":"2026-09-28T13:15:00Z"},"updated_at":{"type":"string","format":"date-time","example":"2026-09-28T13:20:00Z"}}}}},"example":{"payload":{"algorithm":"fill_first","opens_at":null,"fallback_distribution_id":null,"graduate_distribution_id":null,"advanced_enabled":false,"capacity_defaults":{"default":256,"maximum":1023,"effective_maximum":1023,"hard_cap":1024,"headroom":0},"community_member_limit":2000,"community_provisioning":{"state":"not_requested","error_code":null,"failed_at":null},"next_sequence":2,"effective_capacity":900,"throttle_defaults":{"second":1,"hour":240},"identity":{"mode":"sequence","items":[{"key":"4711","source":"upload","thumb_url":"https://app.example.test/rails/active_storage/representations/redirect/cover-1.jpg","available":true,"check":{"state":"ok","reason":null,"checked_at":"2026-10-14T01:00:00Z","overdue":false},"media_asset_id":44},{"key":"4712","source":"library","media_asset_id":44,"thumb_url":"","available":true,"check":{"state":"pending","reason":null,"checked_at":null,"overdue":false}}],"fallback":{"key":"4720","source":"url","thumb_url":"https://app.example.test/rails/active_storage/representations/redirect/default-cover.jpg","available":true,"check":{"state":"ok","reason":null,"checked_at":"2026-10-14T01:00:00Z","overdue":false},"media_asset_id":44},"limits":{"max_bytes":8388608,"max_side":4096,"max_items":100,"check_overdue_after_seconds":900,"content_types":["image/jpeg","image/png"]},"remaining_positions":1,"exhausts_at_sequence":2},"entry_trigger_catalog":[{"key":"payment_charge.paid","label_key":"growth.distribution.entry_triggers.events.payment_charge_paid.label","description_key":"growth.distribution.entry_triggers.events.payment_charge_paid.description","label":"Charge paid","description":"A confirmed or paid charge payment, admitted through the payment_charge.paid key."}],"entry_trigger_validation":{"valid":true,"invalid_type":false,"invalid_indexes":[]},"configuration_options":{"routing_sources":["link","automation","event","manual","api","follow_up"],"template_keys":["welcome","reminder","countdown","unit_opened","waitlist_ack","removed_notice","graduated_notice"]},"configuration_validation":{"valid":true,"issues":[{"path":"algorithm.routing_rules[0].match.source","code":"unknown_choice"}]},"id":22,"account_id":1,"name":"Lista de espera — setembro","slug":"lista-de-espera-setembro","slug_collision":false,"slug_retired_from":null,"public_path":"/g/lista-de-espera-setembro","inbox_id":6,"logical_inbox_id":15,"launch_id":null,"target_type":"group","join_mode":"invite_link","capacity_per_unit":900,"community_jid":null,"channel_jid":null,"naming_template":"Turma {n}","welcome_message":null,"status":"active","settings":{"admins":["5511987654321"],"description":"Aquecimento de lançamento","identity":{"photo":{"mode":"sequence","items":[{"key":"4711","source":"upload","media_asset_id":44},{"key":"4712","source":"library","media_asset_id":44}],"fallback":{"key":"4720","source":"url","media_asset_id":44}}},"join_approval":null,"join_approval_policy":null,"locked":true,"member_add_mode":null,"ephemeral_seconds":86400,"setup_pause_seconds":3,"photo_url":"https://images.example.test/legacy-cover.jpg"},"units_count":1,"members_count":0,"capacity_total":0,"occupancy_total":0,"awaiting_count":0,"open_unit_sequence":null,"archived_at":null,"created_at":"2026-09-28T13:15:00Z","updated_at":"2026-09-28T13:20:00Z"}}}}},"401":{"description":"Authentication is required."},"404":{"description":"The account, distribution or failed unit does not exist in the caller scope."},"403":{"description":"Only an account administrator may authorize this recovery."},"400":{"description":"The required unit_id field was not supplied.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","description":"Framework message identifying the missing required parameter.","example":"param is missing or the value is empty: unit_id"}},"description":"Framework parameter-missing response."},"example":{"error":"param is missing or the value is empty: unit_id"}}}},"422":{"description":"The confirmation was not strict JSON boolean true, the failed unit is not awaiting reconciliation, or the unit already has a WhatsApp group.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error","message"],"properties":{"error":{"type":"string","enum":["confirmation_required","provisioning_reconciliation_required","unit_already_provisioned"],"example":"confirmation_required"},"message":{"type":"string","description":"Human-readable explanation in the caller's language.","example":"Confirm that the group does not exist on WhatsApp before retrying."}}},"examples":{"confirmation_required":{"value":{"error":"confirmation_required","message":"Confirm that the group does not exist on WhatsApp before retrying."}},"not_reconciling":{"value":{"error":"provisioning_reconciliation_required","message":"This unit is not waiting for a reconciliation."}},"already_provisioned":{"value":{"error":"unit_already_provisioned","message":"This unit already has a WhatsApp group. It is resumed automatically and is never created again."}}}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["unit_id","confirmed_absent"],"properties":{"unit_id":{"type":"integer","minimum":1,"description":"Failed launch unit that belongs to the distribution in the path.","example":81},"confirmed_absent":{"type":"boolean","enum":[true],"description":"Must be the JSON boolean true after the administrator verified that WhatsApp did not create the group.","example":true}}},"example":{"unit_id":81,"confirmed_absent":true}}}}}},"/api/v1/accounts/{account_id}/growth/distributions/{id}/retry_members":{"post":{"tags":["Growth Distribution"],"operationId":"auto_post_api_v1_accounts_account_id_growth_distributions_id_retry_members","summary":"Re-queue failed members of a launch distribution","description":"Administrator-only. Moves members in the `failed` state back to `pending` so the rotation tries to place them again, and clears their error code and attempt counter. Without `member_ids` every failed member of the distribution is re-queued; with it only the listed members that are currently failed. Members in any other state, including `skipped`, are never touched. When the distribution is active the normal advance job is queued.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Number of members moved back to the placement queue.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["payload"],"properties":{"payload":{"type":"object","additionalProperties":false,"required":["requeued"],"properties":{"requeued":{"type":"integer","minimum":0,"example":2}}}}},"example":{"payload":{"requeued":2}}}}},"401":{"description":"Authentication is required, or the caller is not an administrator."},"404":{"description":"The account or distribution does not exist in the caller scope."},"403":{"description":"The launch distribution feature is not enabled for the account."},"422":{"description":"More than 1000 member ids were submitted.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error","max"],"properties":{"error":{"type":"string","enum":["bulk_limit_exceeded"],"example":"bulk_limit_exceeded"},"max":{"type":"integer","example":1000}}},"example":{"error":"bulk_limit_exceeded","max":1000}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"member_ids":{"type":"array","maxItems":1000,"description":"Members to re-queue. Omit to re-queue every failed member.","items":{"type":"integer","minimum":1},"example":[9041,9042]}}},"example":{"member_ids":[9041,9042]}}}}}},"/api/v1/accounts/{account_id}/growth/distributions/{id}/refresh_invite_link":{"post":{"tags":["Growth Distribution"],"operationId":"auto_post_api_v1_accounts_account_id_growth_distributions_id_refresh_invite_link","summary":"Refresh the invite link of one launch unit","description":"Administrator-only. Reads the current invite link of the unit's WhatsApp group again and stores it — the recovery for a unit that opened without a link or whose stored link is stale. With the JSON boolean `regenerate: true` the current link is revoked on WhatsApp and a new one is created; every copy of the old link already shared stops working. Strings and other truthy values do not regenerate. Channel units and units without a WhatsApp group are refused.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The unit with its stored invite link.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["payload"],"properties":{"payload":{"type":"object","additionalProperties":false,"required":["id","distribution_id","sequence","name","jid","whatsapp_group_id","invite_link","capacity","member_count","pending_requests_count","pending_requests_synced_at","pending_requests_stale_since","pending_requests_error","fill_rate","status","next_run_at","provisioning_diagnostic","setup","created_at","updated_at"],"properties":{"weight":{"type":"integer","minimum":0,"example":1},"announce_only":{"type":"boolean","example":false},"opens_at":{"type":["string","null"],"format":"date-time","example":null},"closes_at":{"type":["string","null"],"format":"date-time","example":null},"invite_refreshed_at":{"type":["string","null"],"format":"date-time","example":null},"left_count":{"type":"integer","minimum":0,"example":0},"filled_at":{"type":["string","null"],"format":"date-time","example":null},"filled_at_tracked":{"type":"boolean","description":"Whether filled_at was recorded by the real fill tracking rather than left unknown.","example":true},"synced_at":{"type":["string","null"],"format":"date-time","example":null},"pending_requests_count":{"type":"integer","minimum":0,"example":0},"pending_requests_synced_at":{"type":["string","null"],"format":"date-time","example":null},"pending_requests_stale_since":{"type":["string","null"],"format":"date-time","example":null},"pending_requests_error":{"type":["string","null"],"enum":["refused","rate_limited","connection",null],"example":null},"id":{"type":"integer","example":81},"distribution_id":{"type":"integer","example":22},"sequence":{"type":"integer","minimum":1,"example":1},"name":{"type":"string","example":"Turma 1"},"jid":{"type":["string","null"],"example":"120363025246125486@g.us"},"whatsapp_group_id":{"type":["integer","null"],"example":412},"invite_link":{"type":["string","null"],"format":"uri","example":"https://chat.whatsapp.com/EXAMPLEinvite0000000000"},"capacity":{"type":"integer","minimum":0,"maximum":1023,"description":"Current effective capacity including explicit unit overrides.","example":256},"member_count":{"type":"integer","minimum":0,"example":12},"fill_rate":{"type":"number","minimum":0,"example":0.0469},"status":{"type":"string","enum":["provisioning","open","full","closed","failed"],"example":"open"},"next_run_at":{"type":["string","null"],"format":"date-time","example":null},"provisioning_diagnostic":{"type":"object","additionalProperties":true,"description":"Sanitized provisioning diagnostic of the unit, as returned by the units listing; empty when nothing is recorded.","example":{}},"setup":{"type":"array","description":"Recorded step results in execution order; empty for units without recorded setup. Internal fingerprints are excluded.","items":{"type":"object","additionalProperties":false,"required":["step","state","reason","attempted_at","applied_at","retryable"],"properties":{"step":{"type":"string","enum":["mirror","community_link","announce","join_approval","locked","member_add_mode","ephemeral","photo","description","admins","invite_link"],"example":"photo"},"state":{"type":"string","enum":["applied","failed","skipped","not_applied","not_applicable","inherited"],"example":"skipped","description":"Distribution member progress state."},"reason":{"type":["string","null"],"enum":["refused","connection","attempts_exhausted","deferrals_exhausted","sequence_exhausted","image_unavailable","community_unavailable","target_type",null],"example":"attempts_exhausted"},"attempted_at":{"type":["string","null"],"format":"date-time","example":"2026-10-14T01:00:00Z"},"applied_at":{"type":["string","null"],"format":"date-time","example":null},"retryable":{"type":"boolean","description":"Whether this optional step is eligible for an administrator retry.","example":true}}}},"created_at":{"type":"string","format":"date-time","example":"2026-09-29T08:00:00Z"},"updated_at":{"type":"string","format":"date-time","example":"2026-09-29T08:05:00Z"}}}}},"example":{"payload":{"id":81,"distribution_id":22,"sequence":1,"name":"Turma 1","jid":"120363025246125486@g.us","whatsapp_group_id":412,"invite_link":"https://chat.whatsapp.com/EXAMPLEinvite0000000000","capacity":256,"weight":1,"announce_only":false,"opens_at":null,"closes_at":null,"invite_refreshed_at":null,"left_count":0,"filled_at":null,"filled_at_tracked":true,"synced_at":null,"pending_requests_count":0,"pending_requests_synced_at":null,"pending_requests_stale_since":null,"pending_requests_error":null,"member_count":12,"fill_rate":0.0469,"status":"open","next_run_at":null,"provisioning_diagnostic":{},"setup":[{"step":"photo","state":"skipped","reason":"attempts_exhausted","attempted_at":"2026-10-14T01:00:00Z","applied_at":null,"retryable":true}],"created_at":"2026-09-29T08:00:00Z","updated_at":"2026-09-29T08:05:00Z"}}}}},"401":{"description":"Authentication is required, or the caller is not an administrator."},"404":{"description":"The account, distribution or unit does not exist in the caller scope."},"400":{"description":"The required unit_id field was not supplied.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","description":"Framework message identifying the missing required parameter.","example":"param is missing or the value is empty: unit_id"}},"description":"Framework parameter-missing response."},"example":{"error":"param is missing or the value is empty: unit_id"}}}},"403":{"description":"The launch distribution feature is not enabled for the account."},"409":{"description":"Another provision or invite-link operation already owns this distribution; no gateway call is made.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error","message"],"properties":{"error":{"type":"string","enum":["invite_refresh_busy"],"example":"invite_refresh_busy"},"message":{"type":"string","description":"Human-readable explanation in the caller's language.","example":"An operation is already in progress. Try again after it finishes."}}},"example":{"error":"invite_refresh_busy","message":"An operation is already in progress. Try again after it finishes."}}}},"422":{"description":"The unit has no WhatsApp group, its original creator connection is unavailable, or WhatsApp returned no link.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error","message"],"properties":{"error":{"type":"string","enum":["invite_refresh_not_supported","invite_link_unavailable","creator_inbox_unavailable"],"example":"invite_link_unavailable"},"message":{"type":"string","description":"Human-readable explanation in the caller's language.","example":"WhatsApp did not return an invite link. Check the connection and try again."}}},"examples":{"unavailable":{"value":{"error":"invite_link_unavailable","message":"WhatsApp did not return an invite link. Check the connection and try again."}},"not_supported":{"value":{"error":"invite_refresh_not_supported","message":"This unit has no WhatsApp group whose invite link can be refreshed."}}}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["unit_id"],"properties":{"unit_id":{"type":"integer","minimum":1,"description":"Unit that belongs to the distribution in the path.","example":81},"regenerate":{"type":"boolean","description":"JSON boolean true revokes the current link and mints a new one. Defaults to false.","example":false}}},"example":{"unit_id":81,"regenerate":false}}}}}},"/api/v1/accounts/{account_id}/growth/distributions/{id}/retry_setup_step":{"post":{"tags":["Growth Distribution"],"operationId":"auto_post_api_v1_accounts_account_id_growth_distributions_id_retry_setup_step","summary":"Retry one optional setup step of an existing launch group","description":"Administrator-only, also available with distribution_manage permission. Reapplies the current configuration for this unit under the same exclusive authority as the rotation, without consuming its automatic attempt budget. Essential steps, steps already applied or inherited, steps that do not apply to the destination, and units without a WhatsApp group are refused. When the current configuration no longer requests the step, records its true inherited or not_applied result and clears that step's diagnostic without calling WhatsApp.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The unit with the current result of the requested setup step.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["payload"],"properties":{"payload":{"type":"object","additionalProperties":false,"required":["id","distribution_id","sequence","name","jid","whatsapp_group_id","invite_link","capacity","member_count","weight","announce_only","opens_at","closes_at","invite_refreshed_at","left_count","filled_at","synced_at","pending_requests_count","pending_requests_synced_at","pending_requests_stale_since","pending_requests_error","fill_rate","status","next_run_at","provisioning_diagnostic","setup","created_at","updated_at"],"properties":{"weight":{"type":"integer","minimum":0,"example":1},"announce_only":{"type":"boolean","example":false},"opens_at":{"type":["string","null"],"format":"date-time","example":null},"closes_at":{"type":["string","null"],"format":"date-time","example":null},"invite_refreshed_at":{"type":["string","null"],"format":"date-time","example":null},"left_count":{"type":"integer","minimum":0,"example":0},"filled_at":{"type":["string","null"],"format":"date-time","example":null},"filled_at_tracked":{"type":"boolean","description":"Whether filled_at was recorded by the real fill tracking rather than left unknown.","example":true},"synced_at":{"type":["string","null"],"format":"date-time","example":null},"pending_requests_count":{"type":"integer","minimum":0,"example":0},"pending_requests_synced_at":{"type":["string","null"],"format":"date-time","example":null},"pending_requests_stale_since":{"type":["string","null"],"format":"date-time","example":null},"pending_requests_error":{"type":["string","null"],"enum":["refused","rate_limited","connection",null],"example":null},"id":{"type":"integer","example":81},"distribution_id":{"type":"integer","example":22},"sequence":{"type":"integer","minimum":1,"example":1},"name":{"type":"string","example":"Turma 1"},"jid":{"type":["string","null"],"example":null},"whatsapp_group_id":{"type":["integer","null"],"example":null},"invite_link":{"type":["string","null"],"format":"uri","example":null},"capacity":{"type":"integer","minimum":0,"maximum":1023,"description":"Current effective capacity including explicit unit overrides; the stored snapshot is not an implicit override.","example":256},"member_count":{"type":"integer","minimum":0,"example":0},"fill_rate":{"type":"number","minimum":0,"example":0.0},"status":{"type":"string","enum":["provisioning","open","full","closed","failed"],"example":"failed"},"next_run_at":{"type":["string","null"],"format":"date-time","example":null},"provisioning_diagnostic":{"oneOf":[{"type":"object","additionalProperties":true,"maxProperties":0,"description":"No provisioning diagnostic has been recorded for this unit.","example":{}},{"type":"object","additionalProperties":false,"required":["error_code","error_message","failed_at","retry_count","confirmed_rejection_count","last_retry_at","resolution","step","skipped_steps","retry_allowed","next_attempt_at"],"properties":{"error_code":{"type":"string","enum":["missing_initial_participant","outcome_uncertain","feature_not_supported","gateway_rejected","gateway_unavailable","rate_limited","setup_step_failed","setup_step_refused","setup_incomplete","creator_inbox_unavailable","group_not_admin","group_not_found"],"example":"outcome_uncertain"},"error_message":{"type":"string","description":"Fixed safe message derived from the error code, in the caller's language.","example":"The provisioning outcome must be reconciled before retrying."},"failed_at":{"type":["string","null"],"format":"date-time","example":"2026-09-29T08:00:00Z"},"retry_count":{"type":"integer","minimum":0,"example":1},"confirmed_rejection_count":{"type":"integer","minimum":0,"example":0},"last_retry_at":{"type":["string","null"],"format":"date-time","example":null},"resolution":{"type":"string","enum":["retryable","reconciliation_required","retry_authorized","retry_limit_reached","configuration_required","degraded"],"description":"What happens next. `retryable` is retried automatically; `reconciliation_required` waits for an administrator; `retry_authorized` was released by one; `retry_limit_reached` and `configuration_required` paused the distribution; `degraded` is an open unit missing optional setup steps.","example":"reconciliation_required"},"step":{"type":["string","null"],"enum":["mirror","community_link","announce","join_approval","locked","member_add_mode","ephemeral","photo","description","admins","invite_link",null],"description":"Post-create setup step that last failed or was given up; null for a failure before the group existed.","example":null},"skipped_steps":{"type":"array","description":"Optional setup steps given up after the configured attempts.","items":{"type":"string","enum":["mirror","community_link","announce","join_approval","locked","member_add_mode","ephemeral","photo","description","admins","invite_link"]},"example":[]},"retry_allowed":{"type":"boolean","description":"True only when the confirmed-absent retry operation is valid for this unit.","example":true},"next_attempt_at":{"type":["string","null"],"format":"date-time","description":"Earliest time of the next automatic attempt; null when none is scheduled.","example":null}}}]},"setup":{"type":"array","description":"Recorded step results in execution order; empty for units without recorded setup. Internal fingerprints are excluded.","items":{"type":"object","additionalProperties":false,"required":["step","state","reason","attempted_at","applied_at","retryable"],"properties":{"step":{"type":"string","enum":["mirror","community_link","announce","join_approval","locked","member_add_mode","ephemeral","photo","description","admins","invite_link"],"example":"photo"},"state":{"type":"string","enum":["applied","failed","skipped","not_applied","not_applicable","inherited"],"example":"skipped","description":"Distribution member progress state."},"reason":{"type":["string","null"],"enum":["refused","connection","attempts_exhausted","deferrals_exhausted","sequence_exhausted","image_unavailable","community_unavailable","target_type",null],"example":"attempts_exhausted"},"attempted_at":{"type":["string","null"],"format":"date-time","example":"2026-10-14T01:00:00Z"},"applied_at":{"type":["string","null"],"format":"date-time","example":null},"retryable":{"type":"boolean","description":"Whether this optional step is eligible for an administrator retry.","example":true}}}},"created_at":{"type":"string","format":"date-time","example":"2026-09-29T08:00:00Z"},"updated_at":{"type":"string","format":"date-time","example":"2026-09-29T08:00:00Z"}}}}},"example":{"payload":{"id":81,"distribution_id":22,"sequence":1,"name":"Turma 1","jid":"120363025246125486@g.us","whatsapp_group_id":412,"invite_link":"https://chat.whatsapp.com/EXAMPLEinvite0000000000","capacity":256,"weight":1,"announce_only":false,"opens_at":null,"closes_at":null,"invite_refreshed_at":null,"left_count":0,"filled_at":null,"filled_at_tracked":true,"synced_at":null,"pending_requests_count":0,"pending_requests_synced_at":null,"pending_requests_stale_since":null,"pending_requests_error":null,"member_count":12,"fill_rate":0.0469,"status":"open","next_run_at":null,"provisioning_diagnostic":{},"setup":[{"step":"photo","state":"applied","reason":null,"attempted_at":"2026-10-14T01:00:00Z","applied_at":"2026-10-14T01:00:00Z","retryable":false}],"created_at":"2026-09-29T08:00:00Z","updated_at":"2026-10-14T01:00:00Z"}}}}},"401":{"description":"Authentication and permission to manage launch distributions are required."},"404":{"description":"The account, distribution or unit does not exist in the caller scope."},"400":{"description":"A required unit_id or step parameter was not supplied.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","example":"param is missing or the value is empty: step"}}},"example":{"error":"param is missing or the value is empty: step"}}}},"403":{"description":"The launch distribution feature is not enabled for the account."},"409":{"description":"Another rotation or recovery operation owns this distribution.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error","message"],"properties":{"error":{"type":"string","enum":["setup_retry_busy"],"example":"setup_retry_busy"},"message":{"type":"string","example":"Another operation is running for this launch group. Wait for it to finish and try again."}}},"example":{"error":"setup_retry_busy","message":"Another operation is running for this launch group. Wait for it to finish and try again."}}}},"422":{"description":"The step is ineligible, the physical creator is unavailable, or the attempted setup failed.","content":{"application/json":{"schema":{"oneOf":[{"type":"object","additionalProperties":false,"required":["error","message"],"properties":{"error":{"type":"string","enum":["setup_step_not_retryable","creator_inbox_unavailable"],"example":"setup_step_not_retryable"},"message":{"type":"string","example":"This setup step cannot be retried for this group."}}},{"type":"object","additionalProperties":false,"required":["error","message","reason"],"properties":{"error":{"type":"string","enum":["setup_step_retry_failed"],"example":"setup_step_retry_failed"},"reason":{"type":"string","enum":["refused","connection"],"example":"refused"},"message":{"type":"string","example":"The setup step could not be applied. Check the connection and group permissions, then try again."}}}]},"examples":{"not_retryable":{"value":{"error":"setup_step_not_retryable","message":"This setup step cannot be retried for this group."}},"creator_unavailable":{"value":{"error":"creator_inbox_unavailable","message":"The inbox that created this group is unavailable. Review the creator connection before trying again."}},"failed":{"value":{"error":"setup_step_retry_failed","reason":"refused","message":"The setup step could not be applied. Check the connection and group permissions, then try again."}}}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["unit_id","step"],"properties":{"unit_id":{"type":"integer","minimum":1,"example":81},"step":{"type":"string","enum":["mirror","community_link","announce","join_approval","locked","member_add_mode","ephemeral","photo","description","admins","invite_link"],"example":"photo"}}},"example":{"unit_id":81,"step":"photo"}}}}}},"/api/v1/accounts/{account_id}/growth/distributions/{id}/join_requests":{"get":{"tags":["Growth Distribution"],"operationId":"auto_get_api_v1_accounts_account_id_growth_distributions_id_join_requests","summary":"Read pending requests for one launch unit","description":"Uses the same administrator/custom distribution_manage authorization as retry_setup_step. Dormant until join_approval is live and enabled. Reads strictly from the physical creator's gateway, stores the observed count and sync time, and paginates in gateway order. Unresolved LIDs have a null phone. A read failure preserves the last count and records stale/error metadata. Request identities are only returned here, never in the units listing.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"A fresh page of pending requests; fifty requests per page.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["payload"],"properties":{"payload":{"type":"object","additionalProperties":false,"required":["unit_id","requests","count","page","per_page","seats","synced_at"],"properties":{"unit_id":{"type":"integer","example":81},"requests":{"type":"array","maxItems":50,"items":{"type":"object","additionalProperties":false,"required":["jid","phone"],"properties":{"jid":{"type":"string","example":"700000000000001@lid"},"phone":{"type":["string","null"],"example":null}}}},"count":{"type":"integer","minimum":0,"example":1},"page":{"type":"integer","minimum":1,"example":1},"per_page":{"type":"integer","enum":[50],"example":50},"seats":{"type":"integer","minimum":0,"example":2},"synced_at":{"type":"string","format":"date-time","example":"2026-10-14T12:00:00Z"}}}}},"example":{"payload":{"unit_id":81,"requests":[{"jid":"700000000000001@lid","phone":null}],"count":1,"page":1,"per_page":50,"seats":2,"synced_at":"2026-10-14T12:00:00Z"}}}}},"401":{"description":"Authentication and permission to manage launch distributions are required."},"404":{"description":"The account, distribution or unit does not exist in the caller scope."},"400":{"description":"The required unit_id parameter was not supplied."},"403":{"description":"The launch distribution feature is not enabled for the account."},"422":{"description":"Capability unavailable, approval disabled, gateway read/update failed, or no seats for approval.","content":{"application/json":{"schema":{"oneOf":[{"type":"object","additionalProperties":false,"required":["error","setting","message"],"properties":{"error":{"type":"string","enum":["setup_capability_unavailable"]},"setting":{"type":"string","enum":["join_approval"]},"message":{"type":"string","example":"This setting cannot be used on this distribution yet."}}},{"type":"object","additionalProperties":false,"required":["error","message"],"properties":{"error":{"type":"string","enum":["join_requests_unavailable","join_requests_read_failed","join_requests_update_failed","no_seats_available"]},"message":{"type":"string","example":"Join approval is not enabled for this class."}}}]},"examples":{"dormant":{"value":{"error":"setup_capability_unavailable","setting":"join_approval","message":"This setting cannot be used on this distribution yet."}},"unavailable":{"value":{"error":"join_requests_unavailable","message":"Join approval is not enabled for this class.","setting":"join_approval"}},"read_failed":{"value":{"error":"join_requests_read_failed","message":"The join requests could not be read right now. Try again in a moment.","setting":"join_approval"}},"update_failed":{"value":{"error":"join_requests_update_failed","message":"WhatsApp did not accept the decision right now. The requests are still pending.","setting":"join_approval"}},"no_seats":{"value":{"error":"no_seats_available","message":"The class has no open seats. Approving now would exceed its capacity.","setting":"join_approval"}}}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"unit_id","in":"query","required":true,"schema":{"type":"integer","minimum":1},"example":81},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1},"example":1}]}},"/api/v1/accounts/{account_id}/growth/distributions/{id}/update_join_requests":{"post":{"tags":["Growth Distribution"],"operationId":"auto_post_api_v1_accounts_account_id_growth_distributions_id_update_join_requests","summary":"Approve or reject pending requests for one launch unit","description":"Uses the same administrator/custom distribution_manage authorization as retry_setup_step. Dormant until join_approval is live and enabled. Acquires AdvanceAuthority before its strict initial member-count refresh and pending read, then intersects the requested identities with the current list. Bulk selects the first max pending requests; approval is additionally capped by capacity minus member_count. An empty selection answers requested zero without an update, even with zero seats. A nonempty approval with zero seats is refused. Reject does not depend on seats. Calls the update once and reads again: approved/rejected is min(requested, max(before minus after, zero)), not the gateway's status code. A failed update or reread preserves the last count and records stale/error metadata.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Outcome verified by a second strict read, or an empty selection with no gateway update.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["payload"],"properties":{"payload":{"oneOf":[{"type":"object","additionalProperties":false,"required":["decision","requested","approved","remaining","seats"],"properties":{"decision":{"type":"string","enum":["approve"]},"requested":{"type":"integer","minimum":0,"example":2},"approved":{"type":"integer","minimum":0,"example":1},"remaining":{"type":"integer","minimum":0,"example":2},"seats":{"type":"integer","minimum":0,"example":2}}},{"type":"object","additionalProperties":false,"required":["decision","requested","rejected","remaining","seats"],"properties":{"decision":{"type":"string","enum":["reject"]},"requested":{"type":"integer","minimum":0,"example":2},"rejected":{"type":"integer","minimum":0,"example":1},"remaining":{"type":"integer","minimum":0,"example":2},"seats":{"type":"integer","minimum":0,"example":2}}}]}}},"examples":{"approved":{"value":{"payload":{"decision":"approve","requested":2,"approved":1,"remaining":2,"seats":2}}},"rejected":{"value":{"payload":{"decision":"reject","requested":2,"rejected":1,"remaining":2,"seats":2}}},"no_longer_pending":{"value":{"payload":{"decision":"approve","requested":0,"approved":0,"remaining":0,"seats":0}}}}}}},"401":{"description":"Authentication and permission to manage launch distributions are required."},"404":{"description":"The account, distribution or unit does not exist in the caller scope."},"400":{"description":"The unit_id is missing or decision, max, bulk or requests is invalid."},"403":{"description":"The launch distribution feature is not enabled for the account."},"409":{"description":"Another rotation or recovery operation owns AdvanceAuthority; the gateway was not called.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error","message"],"properties":{"error":{"type":"string","enum":["join_requests_busy"],"example":"join_requests_busy"},"message":{"type":"string","example":"This class's requests are being updated. Try again in a moment."}}},"example":{"error":"join_requests_busy","message":"This class's requests are being updated. Try again in a moment."}}}},"422":{"description":"Capability unavailable, approval disabled, gateway read/update failed, or no seats for approval.","content":{"application/json":{"schema":{"oneOf":[{"type":"object","additionalProperties":false,"required":["error","setting","message"],"properties":{"error":{"type":"string","enum":["setup_capability_unavailable"]},"setting":{"type":"string","enum":["join_approval"]},"message":{"type":"string","example":"This setting cannot be used on this distribution yet."}}},{"type":"object","additionalProperties":false,"required":["error","message"],"properties":{"error":{"type":"string","enum":["join_requests_unavailable","join_requests_read_failed","join_requests_update_failed","no_seats_available"]},"message":{"type":"string","example":"Join approval is not enabled for this class."}}}]},"examples":{"dormant":{"value":{"error":"setup_capability_unavailable","setting":"join_approval","message":"This setting cannot be used on this distribution yet."}},"unavailable":{"value":{"error":"join_requests_unavailable","message":"Join approval is not enabled for this class.","setting":"join_approval"}},"read_failed":{"value":{"error":"join_requests_read_failed","message":"The join requests could not be read right now. Try again in a moment.","setting":"join_approval"}},"update_failed":{"value":{"error":"join_requests_update_failed","message":"WhatsApp did not accept the decision right now. The requests are still pending.","setting":"join_approval"}},"no_seats":{"value":{"error":"no_seats_available","message":"The class has no open seats. Approving now would exceed its capacity.","setting":"join_approval"}}}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"type":"object","additionalProperties":false,"required":["unit_id","decision","requests"],"properties":{"unit_id":{"type":"integer","minimum":1,"example":81},"decision":{"type":"string","enum":["approve","reject"],"example":"approve"},"bulk":{"type":"boolean","enum":[false],"example":false},"requests":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"string","example":"700000000000001@lid"}}}},{"type":"object","additionalProperties":false,"required":["unit_id","decision","bulk","max"],"properties":{"unit_id":{"type":"integer","minimum":1,"example":81},"decision":{"type":"string","enum":["approve","reject"],"example":"approve"},"bulk":{"type":"boolean","enum":[true],"example":true},"max":{"type":"integer","minimum":1,"example":20}}}]},"examples":{"single":{"value":{"unit_id":81,"decision":"approve","requests":["700000000000001@lid"],"bulk":false}},"batch":{"value":{"unit_id":81,"decision":"approve","bulk":true,"max":20}}}}}}}},"/api/v1/accounts/{account_id}/growth/distributions/{id}/units":{"get":{"tags":["Growth Distribution"],"operationId":"auto_get_api_v1_accounts_account_id_growth_distributions_id_units","summary":"List launch units with sanitized provisioning diagnostics","description":"Lists the ordered units of one launch distribution. Each unit includes an empty diagnostic object when it has no recorded provision failure, or a fixed sanitized diagnostic when a local failure, confirmed rejection, deferred attempt, incomplete setup step, or uncertain remote result was recorded. Raw gateway responses are excluded. A unit in `provisioning` that already has a `jid` is an existing group whose setup is being finished automatically; a unit in `open` with resolution `degraded` is usable but one or more optional setup steps were given up.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Ordered units for the requested distribution.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["payload"],"properties":{"payload":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["id","distribution_id","sequence","name","jid","whatsapp_group_id","invite_link","capacity","member_count","weight","announce_only","opens_at","closes_at","invite_refreshed_at","left_count","filled_at","synced_at","pending_requests_count","pending_requests_synced_at","pending_requests_stale_since","pending_requests_error","fill_rate","status","next_run_at","provisioning_diagnostic","setup","created_at","updated_at"],"properties":{"weight":{"type":"integer","minimum":0,"example":1},"announce_only":{"type":"boolean","example":false},"opens_at":{"type":["string","null"],"format":"date-time","example":null},"closes_at":{"type":["string","null"],"format":"date-time","example":null},"invite_refreshed_at":{"type":["string","null"],"format":"date-time","example":null},"left_count":{"type":"integer","minimum":0,"example":0},"filled_at":{"type":["string","null"],"format":"date-time","example":null},"filled_at_tracked":{"type":"boolean","description":"Whether filled_at was recorded by the real fill tracking rather than left unknown.","example":true},"synced_at":{"type":["string","null"],"format":"date-time","example":null},"pending_requests_count":{"type":"integer","minimum":0,"example":0},"pending_requests_synced_at":{"type":["string","null"],"format":"date-time","example":null},"pending_requests_stale_since":{"type":["string","null"],"format":"date-time","example":null},"pending_requests_error":{"type":["string","null"],"enum":["refused","rate_limited","connection",null],"example":null},"id":{"type":"integer","example":81},"distribution_id":{"type":"integer","example":22},"sequence":{"type":"integer","minimum":1,"example":1},"name":{"type":"string","example":"Turma 1"},"jid":{"type":["string","null"],"example":null},"whatsapp_group_id":{"type":["integer","null"],"example":null},"invite_link":{"type":["string","null"],"format":"uri","example":null},"capacity":{"type":"integer","minimum":0,"maximum":1023,"description":"Current effective capacity including explicit unit overrides; the stored snapshot is not an implicit override.","example":256},"member_count":{"type":"integer","minimum":0,"example":0},"fill_rate":{"type":"number","minimum":0,"example":0.0},"status":{"type":"string","enum":["provisioning","open","full","closed","failed"],"example":"failed"},"next_run_at":{"type":["string","null"],"format":"date-time","example":null},"provisioning_diagnostic":{"oneOf":[{"type":"object","additionalProperties":true,"maxProperties":0,"description":"No provisioning diagnostic has been recorded for this unit.","example":{}},{"type":"object","additionalProperties":false,"required":["error_code","error_message","failed_at","retry_count","confirmed_rejection_count","last_retry_at","resolution","step","skipped_steps","retry_allowed","next_attempt_at"],"properties":{"error_code":{"type":"string","enum":["missing_initial_participant","outcome_uncertain","feature_not_supported","gateway_rejected","gateway_unavailable","rate_limited","setup_step_failed","setup_step_refused","setup_incomplete","creator_inbox_unavailable","group_not_admin","group_not_found"],"example":"outcome_uncertain"},"error_message":{"type":"string","description":"Fixed safe message derived from the error code, in the caller's language.","example":"The provisioning outcome must be reconciled before retrying."},"failed_at":{"type":["string","null"],"format":"date-time","example":"2026-09-29T08:00:00Z"},"retry_count":{"type":"integer","minimum":0,"example":1},"confirmed_rejection_count":{"type":"integer","minimum":0,"example":0},"last_retry_at":{"type":["string","null"],"format":"date-time","example":null},"resolution":{"type":"string","enum":["retryable","reconciliation_required","retry_authorized","retry_limit_reached","configuration_required","degraded"],"description":"What happens next. `retryable` is retried automatically; `reconciliation_required` waits for an administrator; `retry_authorized` was released by one; `retry_limit_reached` and `configuration_required` paused the distribution; `degraded` is an open unit missing optional setup steps.","example":"reconciliation_required"},"step":{"type":["string","null"],"enum":["mirror","community_link","announce","join_approval","locked","member_add_mode","ephemeral","photo","description","admins","invite_link",null],"description":"Post-create setup step that last failed or was given up; null for a failure before the group existed.","example":null},"skipped_steps":{"type":"array","description":"Optional setup steps given up after the configured attempts.","items":{"type":"string","enum":["mirror","community_link","announce","join_approval","locked","member_add_mode","ephemeral","photo","description","admins","invite_link"]},"example":[]},"retry_allowed":{"type":"boolean","description":"True only when the confirmed-absent retry operation is valid for this unit.","example":true},"next_attempt_at":{"type":["string","null"],"format":"date-time","description":"Earliest time of the next automatic attempt; null when none is scheduled.","example":null}}}]},"setup":{"type":"array","description":"Recorded step results in execution order; empty for units without recorded setup. Internal fingerprints are excluded.","items":{"type":"object","additionalProperties":false,"required":["step","state","reason","attempted_at","applied_at","retryable"],"properties":{"step":{"type":"string","enum":["mirror","community_link","announce","join_approval","locked","member_add_mode","ephemeral","photo","description","admins","invite_link"],"example":"photo"},"state":{"type":"string","enum":["applied","failed","skipped","not_applied","not_applicable","inherited"],"example":"skipped","description":"Distribution member progress state."},"reason":{"type":["string","null"],"enum":["refused","connection","attempts_exhausted","deferrals_exhausted","sequence_exhausted","image_unavailable","community_unavailable","target_type",null],"example":"attempts_exhausted"},"attempted_at":{"type":["string","null"],"format":"date-time","example":"2026-10-14T01:00:00Z"},"applied_at":{"type":["string","null"],"format":"date-time","example":null},"retryable":{"type":"boolean","description":"Whether this optional step is eligible for an administrator retry.","example":true}}}},"created_at":{"type":"string","format":"date-time","example":"2026-09-29T08:00:00Z"},"updated_at":{"type":"string","format":"date-time","example":"2026-09-29T08:00:00Z"}}}}}},"example":{"payload":[{"weight":1,"announce_only":false,"opens_at":null,"closes_at":null,"invite_refreshed_at":null,"left_count":0,"filled_at":null,"filled_at_tracked":true,"synced_at":null,"pending_requests_count":0,"pending_requests_synced_at":null,"pending_requests_stale_since":null,"pending_requests_error":null,"id":81,"distribution_id":22,"sequence":1,"name":"Turma 1","jid":null,"whatsapp_group_id":null,"invite_link":null,"capacity":256,"member_count":0,"fill_rate":0.0,"status":"failed","next_run_at":null,"provisioning_diagnostic":{"error_code":"outcome_uncertain","error_message":"The provisioning outcome must be reconciled before retrying.","failed_at":"2026-09-29T08:00:00Z","retry_count":1,"confirmed_rejection_count":0,"last_retry_at":null,"resolution":"reconciliation_required","step":null,"skipped_steps":[],"retry_allowed":true,"next_attempt_at":null},"setup":[{"step":"photo","state":"skipped","reason":"attempts_exhausted","attempted_at":"2026-10-14T01:00:00Z","applied_at":null,"retryable":true}],"created_at":"2026-09-29T08:00:00Z","updated_at":"2026-09-29T08:00:00Z"}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/growth/distributions/{id}/members":{"get":{"tags":["Growth Distribution"],"operationId":"auto_get_api_v1_accounts_account_id_growth_distributions_id_members","summary":"List distribution members with normalized attribution","description":"Filtered member page with field visibility rules and normalized attribution excluding IP hashes. Member attribution may include seller_phone after a seller-link selection. This optional operational value is preserved only as a String of 8 to 15 E.164 digits without a plus sign and with a nonzero first digit; it does not depend on UTM capture.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Member records and pagination metadata.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["payload","meta"],"properties":{"payload":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["id","distribution_id","unit_id","contact_id","state","join_mode","source","error_code","added_at","joined_at","left_at","removed_at","attribution","created_at","updated_at"],"properties":{"id":{"type":"integer","example":101},"distribution_id":{"type":"integer","example":22},"unit_id":{"type":["integer","null"],"example":81},"contact_id":{"type":["integer","null"],"example":301},"phone":{"type":["string","null"],"description":"Omitted when hidden; otherwise rendered according to field visibility.","example":"+••••1234"},"state":{"type":"string","enum":["pending","queued","invited","added","joined","failed","skipped","waitlisted","left","removed","graduated"],"example":"joined","description":"Distribution member progress state."},"join_mode":{"type":"string","enum":["invite_link","direct_add","both"],"example":"invite_link"},"source":{"type":"string","enum":["link","automation","event","manual","api","follow_up"],"example":"manual"},"error_code":{"type":["string","null"],"description":"Placement error code when one was recorded.","example":null},"added_at":{"type":["string","null"],"format":"date-time","example":null},"joined_at":{"type":["string","null"],"format":"date-time","example":"2026-10-15T12:00:00Z"},"left_at":{"type":["string","null"],"format":"date-time","example":null},"removed_at":{"type":["string","null"],"format":"date-time","example":null},"attribution":{"type":"object","additionalProperties":true,"description":"Normalized utm fields, referrer_host and user_agent_family; ip_hash is excluded.","example":{"utm_source":"newsletter","utm_medium":"email","utm_campaign":"october","referrer_host":"example.test","user_agent_family":"chrome"}},"created_at":{"type":"string","format":"date-time","example":"2026-10-15T11:00:00Z"},"updated_at":{"type":"string","format":"date-time","example":"2026-10-15T12:00:00Z"}}}},"meta":{"type":"object","additionalProperties":false,"required":["count","current_page","total_pages","per_page","has_more"],"properties":{"count":{"type":"integer","minimum":0,"example":1},"current_page":{"type":"integer","minimum":1,"example":1},"total_pages":{"type":"integer","minimum":0,"example":1},"per_page":{"type":"integer","minimum":1,"example":50},"has_more":{"type":"boolean","example":false}}}}},"example":{"payload":[{"id":101,"distribution_id":22,"unit_id":81,"contact_id":301,"phone":"+••••1234","state":"joined","join_mode":"invite_link","source":"manual","error_code":null,"added_at":null,"joined_at":"2026-10-15T12:00:00Z","left_at":null,"removed_at":null,"attribution":{"utm_source":"newsletter","utm_medium":"email","utm_campaign":"october","referrer_host":"example.test","user_agent_family":"chrome"},"created_at":"2026-10-15T11:00:00Z","updated_at":"2026-10-15T12:00:00Z"}],"meta":{"count":1,"current_page":1,"total_pages":1,"per_page":50,"has_more":false}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"state","in":"query","required":false,"description":"Restrict to members in one distribution state.","schema":{"type":"string","enum":["pending","queued","invited","added","joined","failed","skipped","waitlisted","left","removed","graduated"]},"example":"joined"},{"name":"source","in":"query","required":false,"description":"Restrict to members that entered through one origin.","schema":{"type":"string","enum":["link","automation","event","manual","api","follow_up"]},"example":"link"},{"name":"page","in":"query","required":false,"description":"Page of members.","schema":{"type":"integer","default":1},"example":1},{"name":"per_page","in":"query","required":false,"description":"Members per page (default 50).","schema":{"type":"integer","default":50},"example":50}]}},"/api/v1/accounts/{account_id}/growth/distributions/{id}/report":{"get":{"tags":["Growth Distribution"],"operationId":"auto_get_api_v1_accounts_account_id_growth_distributions_id_report","summary":"Funnel report and number health for one launch distribution","description":"Preserves placement, state, source and unit counters. Independent funnel stages count distinct members: clicked is every member; invited includes invited, added, joined, left, removed and graduated; joined includes a recorded join time or joined, left and graduated states; stayed includes joined and graduated. Purchased means graduated or a paid CRM order, a confirmed, paid or partially refunded charge, or a payment_confirmed commerce event. UTM groups use normalized source and campaign. Fill duration uses filled_at minus opens_at or creation, never updated_at. Number capacity is unknown when disconnected.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Funnel counters, UTM groups, fill durations and health of rotation inboxes.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["payload"],"properties":{"payload":{"type":"object","additionalProperties":false,"required":["totals","members_by_state","members_by_source","units","funnel","funnel_degraded","by_utm","time_to_fill","inboxes"],"properties":{"totals":{"type":"object","additionalProperties":false,"required":["members","awaiting","placed","invited","added","joined","failed","skipped","left","units","open_units","full_units","exits","join_conversion"],"properties":{"members":{"type":"integer","minimum":0,"example":140},"awaiting":{"type":"integer","minimum":0,"example":20},"placed":{"type":"integer","minimum":0,"example":110},"invited":{"type":"integer","minimum":0,"example":80},"added":{"type":"integer","minimum":0,"example":25},"joined":{"type":"integer","minimum":0,"example":5},"failed":{"type":"integer","minimum":0,"example":6},"skipped":{"type":"integer","minimum":0,"example":4},"left":{"type":"integer","minimum":0,"example":0},"units":{"type":"integer","minimum":0,"example":2},"open_units":{"type":"integer","minimum":0,"example":1},"full_units":{"type":"integer","minimum":0,"example":1},"exits":{"type":"integer","minimum":0,"example":0},"join_conversion":{"type":"number","minimum":0,"example":0.0455}}},"members_by_state":{"type":"object","additionalProperties":{"type":"integer"},"description":"Counts keyed by any of the eleven distribution member states."},"members_by_source":{"type":"object","additionalProperties":{"type":"integer"},"description":"Counts keyed by link, automation, event, manual, api or follow_up."},"funnel":{"type":"object","additionalProperties":false,"required":["clicked","invited","joined","stayed","purchased"],"properties":{"clicked":{"type":"integer","minimum":0,"example":140},"invited":{"type":"integer","minimum":0,"example":5},"joined":{"type":"integer","minimum":0,"example":5},"stayed":{"type":"integer","minimum":0,"example":5},"purchased":{"type":"integer","minimum":0,"example":2}}},"funnel_degraded":{"type":"array","description":"Funnel stages with no data source in this distribution; show them as unavailable instead of a count, in funnel and in by_utm. Today only purchased can be listed: it has no source when no paid-entry trigger is configured and no member is tied to a sale or graduated. Empty when none.","items":{"type":"string","enum":["purchased"]},"example":[]},"by_utm":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["utm_source","utm_campaign","clicked","invited","joined","stayed","purchased"],"properties":{"clicked":{"type":"integer","minimum":0,"example":140},"invited":{"type":"integer","minimum":0,"example":5},"joined":{"type":"integer","minimum":0,"example":5},"stayed":{"type":"integer","minimum":0,"example":5},"purchased":{"type":"integer","minimum":0,"example":2},"utm_source":{"type":["string","null"],"example":"newsletter"},"utm_campaign":{"type":["string","null"],"example":"october"}}}},"time_to_fill":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["unit_id","sequence","filled_at","seconds","tracked"],"properties":{"unit_id":{"type":"integer","example":81},"sequence":{"type":"integer","minimum":1,"example":1},"filled_at":{"type":["string","null"],"format":"date-time","example":"2026-10-15T10:00:00Z"},"seconds":{"type":["integer","null"],"description":"Elapsed whole seconds from opening or creation; null when never filled.","example":3600},"tracked":{"type":"boolean","description":"Whether fill tracking was active for this unit.","example":true}}}},"inboxes":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["inbox_id","name","state","available_capacity","ramp_batch","cap"],"properties":{"inbox_id":{"type":"integer","example":6},"name":{"type":"string","example":"Launch number"},"state":{"type":"string","enum":["unsupported","disconnected","unlimited","ok","unknown"],"example":"ok","description":"Distribution member progress state."},"available_capacity":{"type":["integer","null"],"minimum":0,"example":4},"ramp_batch":{"type":"integer","minimum":0,"example":10},"cap":{"type":["object","null"],"additionalProperties":false,"description":"Resolved throttle override; null bounds defer to the provider default, not the effective provider ceiling.","properties":{"second":{"type":["integer","null"],"minimum":0,"example":4},"hour":{"type":["integer","null"],"minimum":0,"example":500}}}}}},"units":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["id","sequence","name","status","member_count","capacity","left_count","fill_rate","retention_rate"],"properties":{"id":{"type":"integer","example":81},"sequence":{"type":"integer","minimum":1,"example":1},"name":{"type":"string","example":"Turma 1"},"status":{"type":"string","enum":["provisioning","open","full","closed","failed"],"example":"full"},"member_count":{"type":"integer","minimum":0,"example":256},"capacity":{"type":"integer","minimum":0,"maximum":1023,"description":"Current effective capacity including explicit unit overrides.","example":256},"left_count":{"type":"integer","minimum":0,"example":0},"fill_rate":{"type":"number","minimum":0,"example":1.0},"retention_rate":{"type":"number","minimum":0,"description":"Stayed divided by joined, rounded to four places; zero without joins.","example":1.0}}}}}}}},"example":{"payload":{"totals":{"members":140,"awaiting":20,"placed":110,"invited":80,"added":25,"joined":5,"failed":6,"skipped":4,"left":0,"units":2,"open_units":1,"full_units":1,"exits":0,"join_conversion":0.0455},"members_by_state":{"pending":20,"invited":80,"added":25,"joined":5,"failed":6,"skipped":4},"members_by_source":{"link":90,"manual":30,"event":20},"funnel":{"clicked":140,"invited":110,"joined":5,"stayed":5,"purchased":2},"funnel_degraded":[],"by_utm":[{"utm_source":"newsletter","utm_campaign":"october","clicked":140,"invited":110,"joined":5,"stayed":5,"purchased":2}],"time_to_fill":[{"unit_id":81,"sequence":1,"filled_at":"2026-10-15T10:00:00Z","seconds":3600,"tracked":true}],"inboxes":[{"inbox_id":6,"name":"Launch number","state":"ok","available_capacity":4,"ramp_batch":10,"cap":{"second":4,"hour":500}}],"units":[{"id":81,"sequence":1,"name":"Turma 1","status":"full","member_count":256,"capacity":256,"left_count":0,"fill_rate":1.0,"retention_rate":1.0},{"id":82,"sequence":2,"name":"Turma 2","status":"open","member_count":12,"capacity":256,"left_count":0,"fill_rate":0.0469,"retention_rate":0.0}]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/growth/distributions/{id}/settings":{"get":{"tags":["Growth Distribution"],"operationId":"auto_get_api_v1_accounts_account_id_growth_distributions_id_settings","summary":"Read effective distribution or unit settings","description":"Returns every resolver section and top-level key with value, origin layer, shipped default and the value inherited without the writable layer. Unit ids are scoped to this distribution. The account-scoped reconciliation interval always inherits its own effective value.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Effective settings with origins and inheritance.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["payload"],"properties":{"payload":{"type":"object","additionalProperties":false,"required":["capacity","algorithm","rotation","fallback","schedule","reentry","post_purchase","sellers","dm_on_join","templates","branding","attribution","api","join_approval","setup"],"properties":{"capacity":{"type":"object","additionalProperties":{"type":"object","additionalProperties":false,"required":["value","layer","default","inherited"],"properties":{"value":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."},"layer":{"type":"string","enum":["default","account","distribution","unit"],"example":"distribution"},"default":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."},"inherited":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."}}},"description":"All current capacity configuration keys with their effective and inherited values."},"algorithm":{"type":"object","additionalProperties":{"type":"object","additionalProperties":false,"required":["value","layer","default","inherited"],"properties":{"value":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."},"layer":{"type":"string","enum":["default","account","distribution","unit"],"example":"distribution"},"default":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."},"inherited":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."}}},"description":"All current algorithm configuration keys with their effective and inherited values."},"rotation":{"type":"object","additionalProperties":{"type":"object","additionalProperties":false,"required":["value","layer","default","inherited"],"properties":{"value":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."},"layer":{"type":"string","enum":["default","account","distribution","unit"],"example":"distribution"},"default":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."},"inherited":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."}}},"description":"All current rotation configuration keys with their effective and inherited values."},"fallback":{"type":"object","additionalProperties":{"type":"object","additionalProperties":false,"required":["value","layer","default","inherited"],"properties":{"value":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."},"layer":{"type":"string","enum":["default","account","distribution","unit"],"example":"distribution"},"default":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."},"inherited":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."}}},"description":"All current fallback configuration keys with their effective and inherited values."},"schedule":{"type":"object","additionalProperties":{"type":"object","additionalProperties":false,"required":["value","layer","default","inherited"],"properties":{"value":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."},"layer":{"type":"string","enum":["default","account","distribution","unit"],"example":"distribution"},"default":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."},"inherited":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."}}},"description":"All current schedule configuration keys with their effective and inherited values."},"reentry":{"type":"object","additionalProperties":{"type":"object","additionalProperties":false,"required":["value","layer","default","inherited"],"properties":{"value":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."},"layer":{"type":"string","enum":["default","account","distribution","unit"],"example":"distribution"},"default":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."},"inherited":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."}}},"description":"All current reentry configuration keys with their effective and inherited values."},"post_purchase":{"type":"object","additionalProperties":{"type":"object","additionalProperties":false,"required":["value","layer","default","inherited"],"properties":{"value":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."},"layer":{"type":"string","enum":["default","account","distribution","unit"],"example":"distribution"},"default":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."},"inherited":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."}}},"description":"All current post_purchase configuration keys with their effective and inherited values."},"sellers":{"type":"object","additionalProperties":{"type":"object","additionalProperties":false,"required":["value","layer","default","inherited"],"properties":{"value":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."},"layer":{"type":"string","enum":["default","account","distribution","unit"],"example":"distribution"},"default":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."},"inherited":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."}}},"description":"All current sellers configuration keys with their effective and inherited values."},"dm_on_join":{"type":"object","additionalProperties":{"type":"object","additionalProperties":false,"required":["value","layer","default","inherited"],"properties":{"value":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."},"layer":{"type":"string","enum":["default","account","distribution","unit"],"example":"distribution"},"default":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."},"inherited":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."}}},"description":"All current dm_on_join configuration keys with their effective and inherited values."},"templates":{"type":"object","additionalProperties":{"type":"object","additionalProperties":false,"required":["value","layer","default","inherited"],"properties":{"value":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."},"layer":{"type":"string","enum":["default","account","distribution","unit"],"example":"distribution"},"default":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."},"inherited":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."}}},"description":"All current templates configuration keys with their effective and inherited values."},"branding":{"type":"object","additionalProperties":{"type":"object","additionalProperties":false,"required":["value","layer","default","inherited"],"properties":{"value":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."},"layer":{"type":"string","enum":["default","account","distribution","unit"],"example":"distribution"},"default":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."},"inherited":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."}}},"description":"All current branding configuration keys with their effective and inherited values."},"attribution":{"type":"object","additionalProperties":{"type":"object","additionalProperties":false,"required":["value","layer","default","inherited"],"properties":{"value":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."},"layer":{"type":"string","enum":["default","account","distribution","unit"],"example":"distribution"},"default":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."},"inherited":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."}}},"description":"All current attribution configuration keys with their effective and inherited values."},"api":{"type":"object","additionalProperties":{"type":"object","additionalProperties":false,"required":["value","layer","default","inherited"],"properties":{"value":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."},"layer":{"type":"string","enum":["default","account","distribution","unit"],"example":"distribution"},"default":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."},"inherited":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."}}},"description":"All current api configuration keys with their effective and inherited values."},"join_approval":{"type":"object","additionalProperties":{"type":"object","additionalProperties":false,"required":["value","layer","default","inherited"],"properties":{"value":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."},"layer":{"type":"string","enum":["default","account","distribution","unit"],"example":"distribution"},"default":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."},"inherited":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."}}},"description":"All current join_approval configuration keys with their effective and inherited values."},"setup":{"type":"object","additionalProperties":{"type":"object","additionalProperties":false,"required":["value","layer","default","inherited"],"properties":{"value":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."},"layer":{"type":"string","enum":["default","account","distribution","unit"],"example":"distribution"},"default":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."},"inherited":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."}}},"description":"All current setup configuration keys with their effective and inherited values."}}}}},"example":{"payload":{"capacity":{"hard_cap":{"value":1024,"layer":"default","default":1024,"inherited":1024},"headroom":{"value":0,"layer":"default","default":0,"inherited":0},"per_unit":{"value":256,"layer":"distribution","default":256,"inherited":256},"by_inbox":{"value":{},"layer":"default","default":{},"inherited":{}},"reserve_for_waitlist":{"value":0,"layer":"default","default":0,"inherited":0}},"algorithm":{"strategy":{"value":"fill_first","layer":"distribution","default":"fill_first","inherited":"fill_first"},"weight":{"value":1,"layer":"default","default":1,"inherited":1},"sticky_by_contact":{"value":true,"layer":"default","default":true,"inherited":true},"routing_rules":{"value":[],"layer":"default","default":[],"inherited":[]}},"rotation":{"batch_size":{"value":10,"layer":"default","default":10,"inherited":10},"warmup_ramp":{"value":[],"layer":"default","default":[],"inherited":[]},"defer_base_seconds":{"value":30,"layer":"default","default":30,"inherited":30},"max_backoff_shift":{"value":6,"layer":"default","default":6,"inherited":6},"max_defer_attempts":{"value":8,"layer":"default","default":8,"inherited":8},"throttle":{"value":{"second":null,"hour":null},"layer":"default","default":{"second":null,"hour":null},"inherited":{"second":null,"hour":null}},"sync_interval_minutes":{"value":2,"layer":"default","default":2,"inherited":2},"scheduler_batch_size":{"value":500,"layer":"default","default":500,"inherited":500},"full_unit_reconcile_minutes":{"value":10,"layer":"default","default":10,"inherited":10}},"fallback":{"mode":{"value":"url","layer":"default","default":"url","inherited":"url"},"url":{"value":null,"layer":"default","default":null,"inherited":null},"message":{"value":"growth_distribution.public.unavailable.default_message","layer":"default","default":"growth_distribution.public.unavailable.default_message","inherited":"growth_distribution.public.unavailable.default_message"},"distribution_id":{"value":null,"layer":"default","default":null,"inherited":null},"waitlist_max":{"value":1000,"layer":"default","default":1000,"inherited":1000},"waitlist_ttl_hours":{"value":168,"layer":"default","default":168,"inherited":168},"waitlist_drain_batch":{"value":25,"layer":"default","default":25,"inherited":25}},"schedule":{"opens_at":{"value":null,"layer":"default","default":null,"inherited":null},"closes_at":{"value":null,"layer":"default","default":null,"inherited":null},"cascade_minutes":{"value":0,"layer":"default","default":0,"inherited":0},"announce_when_closed":{"value":true,"layer":"default","default":true,"inherited":true},"lock_when_closed":{"value":false,"layer":"default","default":false,"inherited":false},"warmup_window_minutes":{"value":0,"layer":"default","default":0,"inherited":0},"timezone":{"value":"America/Sao_Paulo","layer":"default","default":null,"inherited":"America/Sao_Paulo"}},"reentry":{"allow_reentry":{"value":false,"layer":"default","default":false,"inherited":false},"cooldown_hours":{"value":24,"layer":"default","default":24,"inherited":24},"dedupe_across_units":{"value":true,"layer":"default","default":true,"inherited":true},"use_hub_blocklist":{"value":false,"layer":"default","default":false,"inherited":false},"blacklist":{"value":[],"layer":"default","default":[],"inherited":[]},"whitelist":{"value":[],"layer":"default","default":[],"inherited":[]},"reopen_on_leave":{"value":true,"layer":"default","default":true,"inherited":true}},"post_purchase":{"on_paid":{"value":{"remove":false,"move_to_distribution_id":null,"delay_minutes":0},"layer":"default","default":{"remove":false,"move_to_distribution_id":null,"delay_minutes":0},"inherited":{"remove":false,"move_to_distribution_id":null,"delay_minutes":0}},"on_overdue":{"value":{"remove":false,"after_days":3,"warn_template":"removed_notice"},"layer":"default","default":{"remove":false,"after_days":3,"warn_template":"removed_notice"},"inherited":{"remove":false,"after_days":3,"warn_template":"removed_notice"}},"on_refund":{"value":{"remove":true},"layer":"default","default":{"remove":true},"inherited":{"remove":true}},"on_chargeback":{"value":{"remove":true},"layer":"default","default":{"remove":true},"inherited":{"remove":true}},"remove_batch_size":{"value":20,"layer":"default","default":20,"inherited":20},"remove_throttle":{"value":{"second":null,"hour":null},"layer":"default","default":{"second":null,"hour":null},"inherited":{"second":null,"hour":null}}},"sellers":{"strategy":{"value":"round_robin","layer":"default","default":"round_robin","inherited":"round_robin"},"list":{"value":[],"layer":"default","default":[],"inherited":[]},"prefill_template":{"value":"growth_distribution.sellers.prefill_default","layer":"default","default":"growth_distribution.sellers.prefill_default","inherited":"growth_distribution.sellers.prefill_default"},"daily_cap_per_seller":{"value":0,"layer":"default","default":0,"inherited":0},"pause_when_offline":{"value":false,"layer":"default","default":false,"inherited":false}},"dm_on_join":{"enabled":{"value":false,"layer":"default","default":false,"inherited":false},"template":{"value":"welcome","layer":"default","default":"welcome","inherited":"welcome"},"spintax":{"value":[],"layer":"default","default":[],"inherited":[]},"delay_seconds":{"value":{"min":5,"max":45},"layer":"default","default":{"min":5,"max":45},"inherited":{"min":5,"max":45}},"per_hour_limit":{"value":60,"layer":"default","default":60,"inherited":60},"inbox_id":{"value":null,"layer":"default","default":null,"inherited":null},"fallback_inbox_id":{"value":null,"layer":"default","default":null,"inherited":null},"mode":{"value":"fixed","layer":"default","default":"fixed","inherited":"fixed"},"brief":{"value":"","layer":"default","default":"","inherited":""},"skip_if_conversation_open":{"value":true,"layer":"default","default":true,"inherited":true}},"templates":{"welcome":{"value":{"text":null,"spintax":[],"media_url":null},"layer":"default","default":{"text":null,"spintax":[],"media_url":null},"inherited":{"text":null,"spintax":[],"media_url":null}},"reminder":{"value":{"i18n_key":"growth_distribution.templates.reminder","text":null,"spintax":[],"media_url":null},"layer":"default","default":{"i18n_key":"growth_distribution.templates.reminder","text":null,"spintax":[],"media_url":null},"inherited":{"i18n_key":"growth_distribution.templates.reminder","text":null,"spintax":[],"media_url":null}},"countdown":{"value":{"i18n_key":"growth_distribution.templates.countdown","text":null,"spintax":[],"media_url":null},"layer":"default","default":{"i18n_key":"growth_distribution.templates.countdown","text":null,"spintax":[],"media_url":null},"inherited":{"i18n_key":"growth_distribution.templates.countdown","text":null,"spintax":[],"media_url":null}},"unit_opened":{"value":{"i18n_key":"growth_distribution.templates.unit_opened","text":null,"spintax":[],"media_url":null},"layer":"default","default":{"i18n_key":"growth_distribution.templates.unit_opened","text":null,"spintax":[],"media_url":null},"inherited":{"i18n_key":"growth_distribution.templates.unit_opened","text":null,"spintax":[],"media_url":null}},"waitlist_ack":{"value":{"i18n_key":"growth_distribution.templates.waitlist_ack","text":null,"spintax":[],"media_url":null},"layer":"default","default":{"i18n_key":"growth_distribution.templates.waitlist_ack","text":null,"spintax":[],"media_url":null},"inherited":{"i18n_key":"growth_distribution.templates.waitlist_ack","text":null,"spintax":[],"media_url":null}},"removed_notice":{"value":{"i18n_key":"growth_distribution.templates.removed_notice","text":null,"spintax":[],"media_url":null},"layer":"default","default":{"i18n_key":"growth_distribution.templates.removed_notice","text":null,"spintax":[],"media_url":null},"inherited":{"i18n_key":"growth_distribution.templates.removed_notice","text":null,"spintax":[],"media_url":null}},"graduated_notice":{"value":{"i18n_key":"growth_distribution.templates.graduated_notice","text":null,"spintax":[],"media_url":null},"layer":"default","default":{"i18n_key":"growth_distribution.templates.graduated_notice","text":null,"spintax":[],"media_url":null},"inherited":{"i18n_key":"growth_distribution.templates.graduated_notice","text":null,"spintax":[],"media_url":null}}},"branding":{"naming_template":{"value":"Turma {n}","layer":"default","default":"Turma {n}","inherited":"Turma {n}"},"photo_url":{"value":null,"layer":"default","default":null,"inherited":null},"description":{"value":null,"layer":"default","default":null,"inherited":null},"admins":{"value":[],"layer":"default","default":[],"inherited":[]},"announcement_group":{"value":false,"layer":"default","default":false,"inherited":false},"auto_create_channel":{"value":false,"layer":"default","default":false,"inherited":false},"auto_create_channel_live":{"value":false,"layer":"default","default":false,"inherited":false},"channel_invite_url":{"value":null,"layer":"default","default":null,"inherited":null}},"attribution":{"utm_capture":{"value":true,"layer":"default","default":true,"inherited":true},"store_referrer_host":{"value":true,"layer":"default","default":true,"inherited":true},"store_ip_hash":{"value":true,"layer":"default","default":true,"inherited":true},"capi":{"value":{"on_click":null,"on_join":null,"on_purchase":null},"layer":"default","default":{"on_click":null,"on_join":null,"on_purchase":null},"inherited":{"on_click":null,"on_join":null,"on_purchase":null}},"contact_attribute_key":{"value":"distribution_attributions","layer":"default","default":"distribution_attributions","inherited":"distribution_attributions"}},"api":{"bulk_enroll_max":{"value":1000,"layer":"default","default":1000,"inherited":1000},"index_page_size":{"value":25,"layer":"default","default":25,"inherited":25},"approvals_timeout_seconds":{"value":3,"layer":"default","default":3,"inherited":3},"public_link_rate_per_minute":{"value":30,"layer":"default","default":30,"inherited":30},"export_row_limit":{"value":50000,"layer":"default","default":50000,"inherited":50000}},"join_approval":{"batch":{"value":20,"layer":"default","default":20,"inherited":20},"policy":{"value":"all_while_seats","layer":"default","default":"all_while_seats","inherited":"all_while_seats"}},"setup":{"pause_seconds":{"value":3,"layer":"default","default":3,"inherited":3},"pause_jitter_seconds":{"value":2,"layer":"default","default":2,"inherited":2},"pause_max_seconds":{"value":60,"layer":"default","default":60,"inherited":60}}}}}}},"401":{"description":"Authentication and permission to read launch distributions are required."},"404":{"description":"Distribution or unit is outside the caller scope."},"403":{"description":"The launch distribution feature is not enabled."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"unit_id","in":"query","required":false,"description":"Unit belonging to this distribution.","schema":{"type":"integer","minimum":1},"example":81}]},"patch":{"tags":["Growth Distribution"],"operationId":"auto_patch_api_v1_accounts_account_id_growth_distributions_id_settings","summary":"Patch distribution or unit configuration overrides","description":"Validates the whole partial document before saving once under the selected row lock. Null removes an override. Existing identity, diagnostic and retired-address data is preserved. Values use the existing column or legacy writer where one exists. Canonical writes cannot replace a saved boolean join_approval document. The account-only reconciliation interval is rejected in both layers. Unit capacity, weight and opening/closing times update their consumer columns as well as the unit settings document. Null clears unit dates and restores inherited capacity or weight. Effective closing time must be later than opening time. No events or jobs are emitted. Capacity reads use current resolved limits, including explicit unit overrides, rather than treating old capacity snapshots as overrides. A capacity combination without a seat is refused atomically with invalid_settings and keys containing capacity.headroom. Routing source and template membership use configuration_options. Invalid identical legacy values may be retained; a changed invalid list or identifier is rejected. Null restores inheritance. The 422 keys identify submitted section.key paths: a rejected overdue warning identifier reports post_purchase.on_overdue. This canonical error keeps the existing error and keys envelope.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Effective settings with origins and inheritance.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["payload"],"properties":{"payload":{"type":"object","additionalProperties":false,"required":["capacity","algorithm","rotation","fallback","schedule","reentry","post_purchase","sellers","dm_on_join","templates","branding","attribution","api","join_approval","setup"],"properties":{"capacity":{"type":"object","additionalProperties":{"type":"object","additionalProperties":false,"required":["value","layer","default","inherited"],"properties":{"value":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."},"layer":{"type":"string","enum":["default","account","distribution","unit"],"example":"distribution"},"default":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."},"inherited":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."}}},"description":"All current capacity configuration keys with their effective and inherited values."},"algorithm":{"type":"object","additionalProperties":{"type":"object","additionalProperties":false,"required":["value","layer","default","inherited"],"properties":{"value":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."},"layer":{"type":"string","enum":["default","account","distribution","unit"],"example":"distribution"},"default":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."},"inherited":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."}}},"description":"All current algorithm configuration keys with their effective and inherited values."},"rotation":{"type":"object","additionalProperties":{"type":"object","additionalProperties":false,"required":["value","layer","default","inherited"],"properties":{"value":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."},"layer":{"type":"string","enum":["default","account","distribution","unit"],"example":"distribution"},"default":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."},"inherited":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."}}},"description":"All current rotation configuration keys with their effective and inherited values."},"fallback":{"type":"object","additionalProperties":{"type":"object","additionalProperties":false,"required":["value","layer","default","inherited"],"properties":{"value":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."},"layer":{"type":"string","enum":["default","account","distribution","unit"],"example":"distribution"},"default":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."},"inherited":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."}}},"description":"All current fallback configuration keys with their effective and inherited values."},"schedule":{"type":"object","additionalProperties":{"type":"object","additionalProperties":false,"required":["value","layer","default","inherited"],"properties":{"value":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."},"layer":{"type":"string","enum":["default","account","distribution","unit"],"example":"distribution"},"default":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."},"inherited":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."}}},"description":"All current schedule configuration keys with their effective and inherited values."},"reentry":{"type":"object","additionalProperties":{"type":"object","additionalProperties":false,"required":["value","layer","default","inherited"],"properties":{"value":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."},"layer":{"type":"string","enum":["default","account","distribution","unit"],"example":"distribution"},"default":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."},"inherited":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."}}},"description":"All current reentry configuration keys with their effective and inherited values."},"post_purchase":{"type":"object","additionalProperties":{"type":"object","additionalProperties":false,"required":["value","layer","default","inherited"],"properties":{"value":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."},"layer":{"type":"string","enum":["default","account","distribution","unit"],"example":"distribution"},"default":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."},"inherited":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."}}},"description":"All current post_purchase configuration keys with their effective and inherited values."},"sellers":{"type":"object","additionalProperties":{"type":"object","additionalProperties":false,"required":["value","layer","default","inherited"],"properties":{"value":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."},"layer":{"type":"string","enum":["default","account","distribution","unit"],"example":"distribution"},"default":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."},"inherited":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."}}},"description":"All current sellers configuration keys with their effective and inherited values."},"dm_on_join":{"type":"object","additionalProperties":{"type":"object","additionalProperties":false,"required":["value","layer","default","inherited"],"properties":{"value":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."},"layer":{"type":"string","enum":["default","account","distribution","unit"],"example":"distribution"},"default":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."},"inherited":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."}}},"description":"All current dm_on_join configuration keys with their effective and inherited values."},"templates":{"type":"object","additionalProperties":{"type":"object","additionalProperties":false,"required":["value","layer","default","inherited"],"properties":{"value":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."},"layer":{"type":"string","enum":["default","account","distribution","unit"],"example":"distribution"},"default":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."},"inherited":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."}}},"description":"All current templates configuration keys with their effective and inherited values."},"branding":{"type":"object","additionalProperties":{"type":"object","additionalProperties":false,"required":["value","layer","default","inherited"],"properties":{"value":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."},"layer":{"type":"string","enum":["default","account","distribution","unit"],"example":"distribution"},"default":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."},"inherited":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."}}},"description":"All current branding configuration keys with their effective and inherited values."},"attribution":{"type":"object","additionalProperties":{"type":"object","additionalProperties":false,"required":["value","layer","default","inherited"],"properties":{"value":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."},"layer":{"type":"string","enum":["default","account","distribution","unit"],"example":"distribution"},"default":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."},"inherited":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."}}},"description":"All current attribution configuration keys with their effective and inherited values."},"api":{"type":"object","additionalProperties":{"type":"object","additionalProperties":false,"required":["value","layer","default","inherited"],"properties":{"value":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."},"layer":{"type":"string","enum":["default","account","distribution","unit"],"example":"distribution"},"default":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."},"inherited":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."}}},"description":"All current api configuration keys with their effective and inherited values."},"join_approval":{"type":"object","additionalProperties":{"type":"object","additionalProperties":false,"required":["value","layer","default","inherited"],"properties":{"value":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."},"layer":{"type":"string","enum":["default","account","distribution","unit"],"example":"distribution"},"default":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."},"inherited":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."}}},"description":"All current join_approval configuration keys with their effective and inherited values."},"setup":{"type":"object","additionalProperties":{"type":"object","additionalProperties":false,"required":["value","layer","default","inherited"],"properties":{"value":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."},"layer":{"type":"string","enum":["default","account","distribution","unit"],"example":"distribution"},"default":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."},"inherited":{"type":["string","integer","number","boolean","array","object","null"],"additionalProperties":true,"items":{"type":["string","integer","number","boolean","object","null"],"additionalProperties":true,"description":"One element of a list-valued setting, in the shape the distribution settings document gives that key: a text variant, a phone or JID, a warm-up step, a routing rule or a seller."},"description":"Resolved JSON scalar, ordered list or structured configuration; null means no configured value."}}},"description":"All current setup configuration keys with their effective and inherited values."}}}}},"example":{"payload":{"capacity":{"hard_cap":{"value":1024,"layer":"default","default":1024,"inherited":1024},"headroom":{"value":0,"layer":"default","default":0,"inherited":0},"per_unit":{"value":256,"layer":"distribution","default":256,"inherited":256},"by_inbox":{"value":{},"layer":"default","default":{},"inherited":{}},"reserve_for_waitlist":{"value":0,"layer":"default","default":0,"inherited":0}},"algorithm":{"strategy":{"value":"fill_first","layer":"distribution","default":"fill_first","inherited":"fill_first"},"weight":{"value":1,"layer":"default","default":1,"inherited":1},"sticky_by_contact":{"value":true,"layer":"default","default":true,"inherited":true},"routing_rules":{"value":[],"layer":"default","default":[],"inherited":[]}},"rotation":{"batch_size":{"value":10,"layer":"default","default":10,"inherited":10},"warmup_ramp":{"value":[],"layer":"default","default":[],"inherited":[]},"defer_base_seconds":{"value":30,"layer":"default","default":30,"inherited":30},"max_backoff_shift":{"value":6,"layer":"default","default":6,"inherited":6},"max_defer_attempts":{"value":8,"layer":"default","default":8,"inherited":8},"throttle":{"value":{"second":null,"hour":null},"layer":"default","default":{"second":null,"hour":null},"inherited":{"second":null,"hour":null}},"sync_interval_minutes":{"value":2,"layer":"default","default":2,"inherited":2},"scheduler_batch_size":{"value":500,"layer":"default","default":500,"inherited":500},"full_unit_reconcile_minutes":{"value":10,"layer":"default","default":10,"inherited":10}},"fallback":{"mode":{"value":"url","layer":"default","default":"url","inherited":"url"},"url":{"value":null,"layer":"default","default":null,"inherited":null},"message":{"value":"growth_distribution.public.unavailable.default_message","layer":"default","default":"growth_distribution.public.unavailable.default_message","inherited":"growth_distribution.public.unavailable.default_message"},"distribution_id":{"value":null,"layer":"default","default":null,"inherited":null},"waitlist_max":{"value":1000,"layer":"default","default":1000,"inherited":1000},"waitlist_ttl_hours":{"value":168,"layer":"default","default":168,"inherited":168},"waitlist_drain_batch":{"value":25,"layer":"default","default":25,"inherited":25}},"schedule":{"opens_at":{"value":null,"layer":"default","default":null,"inherited":null},"closes_at":{"value":null,"layer":"default","default":null,"inherited":null},"cascade_minutes":{"value":0,"layer":"default","default":0,"inherited":0},"announce_when_closed":{"value":true,"layer":"default","default":true,"inherited":true},"lock_when_closed":{"value":false,"layer":"default","default":false,"inherited":false},"warmup_window_minutes":{"value":0,"layer":"default","default":0,"inherited":0},"timezone":{"value":"America/Sao_Paulo","layer":"default","default":null,"inherited":"America/Sao_Paulo"}},"reentry":{"allow_reentry":{"value":false,"layer":"default","default":false,"inherited":false},"cooldown_hours":{"value":24,"layer":"default","default":24,"inherited":24},"dedupe_across_units":{"value":true,"layer":"default","default":true,"inherited":true},"use_hub_blocklist":{"value":false,"layer":"default","default":false,"inherited":false},"blacklist":{"value":[],"layer":"default","default":[],"inherited":[]},"whitelist":{"value":[],"layer":"default","default":[],"inherited":[]},"reopen_on_leave":{"value":true,"layer":"default","default":true,"inherited":true}},"post_purchase":{"on_paid":{"value":{"remove":false,"move_to_distribution_id":null,"delay_minutes":0},"layer":"default","default":{"remove":false,"move_to_distribution_id":null,"delay_minutes":0},"inherited":{"remove":false,"move_to_distribution_id":null,"delay_minutes":0}},"on_overdue":{"value":{"remove":false,"after_days":3,"warn_template":"removed_notice"},"layer":"default","default":{"remove":false,"after_days":3,"warn_template":"removed_notice"},"inherited":{"remove":false,"after_days":3,"warn_template":"removed_notice"}},"on_refund":{"value":{"remove":true},"layer":"default","default":{"remove":true},"inherited":{"remove":true}},"on_chargeback":{"value":{"remove":true},"layer":"default","default":{"remove":true},"inherited":{"remove":true}},"remove_batch_size":{"value":20,"layer":"default","default":20,"inherited":20},"remove_throttle":{"value":{"second":null,"hour":null},"layer":"default","default":{"second":null,"hour":null},"inherited":{"second":null,"hour":null}}},"sellers":{"strategy":{"value":"round_robin","layer":"default","default":"round_robin","inherited":"round_robin"},"list":{"value":[],"layer":"default","default":[],"inherited":[]},"prefill_template":{"value":"growth_distribution.sellers.prefill_default","layer":"default","default":"growth_distribution.sellers.prefill_default","inherited":"growth_distribution.sellers.prefill_default"},"daily_cap_per_seller":{"value":0,"layer":"default","default":0,"inherited":0},"pause_when_offline":{"value":false,"layer":"default","default":false,"inherited":false}},"dm_on_join":{"enabled":{"value":false,"layer":"default","default":false,"inherited":false},"template":{"value":"welcome","layer":"default","default":"welcome","inherited":"welcome"},"spintax":{"value":[],"layer":"default","default":[],"inherited":[]},"delay_seconds":{"value":{"min":5,"max":45},"layer":"default","default":{"min":5,"max":45},"inherited":{"min":5,"max":45}},"per_hour_limit":{"value":60,"layer":"default","default":60,"inherited":60},"inbox_id":{"value":null,"layer":"default","default":null,"inherited":null},"fallback_inbox_id":{"value":null,"layer":"default","default":null,"inherited":null},"mode":{"value":"fixed","layer":"default","default":"fixed","inherited":"fixed"},"brief":{"value":"","layer":"default","default":"","inherited":""},"skip_if_conversation_open":{"value":true,"layer":"default","default":true,"inherited":true}},"templates":{"welcome":{"value":{"text":null,"spintax":[],"media_url":null},"layer":"default","default":{"text":null,"spintax":[],"media_url":null},"inherited":{"text":null,"spintax":[],"media_url":null}},"reminder":{"value":{"i18n_key":"growth_distribution.templates.reminder","text":null,"spintax":[],"media_url":null},"layer":"default","default":{"i18n_key":"growth_distribution.templates.reminder","text":null,"spintax":[],"media_url":null},"inherited":{"i18n_key":"growth_distribution.templates.reminder","text":null,"spintax":[],"media_url":null}},"countdown":{"value":{"i18n_key":"growth_distribution.templates.countdown","text":null,"spintax":[],"media_url":null},"layer":"default","default":{"i18n_key":"growth_distribution.templates.countdown","text":null,"spintax":[],"media_url":null},"inherited":{"i18n_key":"growth_distribution.templates.countdown","text":null,"spintax":[],"media_url":null}},"unit_opened":{"value":{"i18n_key":"growth_distribution.templates.unit_opened","text":null,"spintax":[],"media_url":null},"layer":"default","default":{"i18n_key":"growth_distribution.templates.unit_opened","text":null,"spintax":[],"media_url":null},"inherited":{"i18n_key":"growth_distribution.templates.unit_opened","text":null,"spintax":[],"media_url":null}},"waitlist_ack":{"value":{"i18n_key":"growth_distribution.templates.waitlist_ack","text":null,"spintax":[],"media_url":null},"layer":"default","default":{"i18n_key":"growth_distribution.templates.waitlist_ack","text":null,"spintax":[],"media_url":null},"inherited":{"i18n_key":"growth_distribution.templates.waitlist_ack","text":null,"spintax":[],"media_url":null}},"removed_notice":{"value":{"i18n_key":"growth_distribution.templates.removed_notice","text":null,"spintax":[],"media_url":null},"layer":"default","default":{"i18n_key":"growth_distribution.templates.removed_notice","text":null,"spintax":[],"media_url":null},"inherited":{"i18n_key":"growth_distribution.templates.removed_notice","text":null,"spintax":[],"media_url":null}},"graduated_notice":{"value":{"i18n_key":"growth_distribution.templates.graduated_notice","text":null,"spintax":[],"media_url":null},"layer":"default","default":{"i18n_key":"growth_distribution.templates.graduated_notice","text":null,"spintax":[],"media_url":null},"inherited":{"i18n_key":"growth_distribution.templates.graduated_notice","text":null,"spintax":[],"media_url":null}}},"branding":{"naming_template":{"value":"Turma {n}","layer":"default","default":"Turma {n}","inherited":"Turma {n}"},"photo_url":{"value":null,"layer":"default","default":null,"inherited":null},"description":{"value":null,"layer":"default","default":null,"inherited":null},"admins":{"value":[],"layer":"default","default":[],"inherited":[]},"announcement_group":{"value":false,"layer":"default","default":false,"inherited":false},"auto_create_channel":{"value":false,"layer":"default","default":false,"inherited":false},"auto_create_channel_live":{"value":false,"layer":"default","default":false,"inherited":false},"channel_invite_url":{"value":null,"layer":"default","default":null,"inherited":null}},"attribution":{"utm_capture":{"value":true,"layer":"default","default":true,"inherited":true},"store_referrer_host":{"value":true,"layer":"default","default":true,"inherited":true},"store_ip_hash":{"value":true,"layer":"default","default":true,"inherited":true},"capi":{"value":{"on_click":null,"on_join":null,"on_purchase":null},"layer":"default","default":{"on_click":null,"on_join":null,"on_purchase":null},"inherited":{"on_click":null,"on_join":null,"on_purchase":null}},"contact_attribute_key":{"value":"distribution_attributions","layer":"default","default":"distribution_attributions","inherited":"distribution_attributions"}},"api":{"bulk_enroll_max":{"value":1000,"layer":"default","default":1000,"inherited":1000},"index_page_size":{"value":25,"layer":"default","default":25,"inherited":25},"approvals_timeout_seconds":{"value":3,"layer":"default","default":3,"inherited":3},"public_link_rate_per_minute":{"value":30,"layer":"default","default":30,"inherited":30},"export_row_limit":{"value":50000,"layer":"default","default":50000,"inherited":50000}},"join_approval":{"batch":{"value":20,"layer":"default","default":20,"inherited":20},"policy":{"value":"all_while_seats","layer":"default","default":"all_while_seats","inherited":"all_while_seats"}},"setup":{"pause_seconds":{"value":3,"layer":"default","default":3,"inherited":3},"pause_jitter_seconds":{"value":2,"layer":"default","default":2,"inherited":2},"pause_max_seconds":{"value":60,"layer":"default","default":60,"inherited":60}}}}}}},"401":{"description":"An administrator or custom role with distribution management permission is required."},"404":{"description":"Distribution or unit is outside the caller scope."},"403":{"description":"The launch distribution feature is not enabled."},"422":{"description":"Invalid overrides; no changes are persisted.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error","keys"],"properties":{"error":{"type":"string","enum":["invalid_settings"],"example":"invalid_settings"},"keys":{"type":"array","description":"Rejected section or section.key paths, in submission order without duplicates.","items":{"type":"string"},"example":["capacity.per_unit"]}}},"example":{"error":"invalid_settings","keys":["capacity.per_unit"]}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["settings"],"properties":{"unit_id":{"type":"integer","minimum":1,"description":"Unit belonging to this distribution; omission selects the distribution layer.","example":81},"settings":{"type":"object","additionalProperties":false,"description":"Partial override document. Null removes an override. Account-scoped full_unit_reconcile_minutes is rejected in either writable layer. Distribution per_unit and strategy columns cannot be null. Unit writes allow only capacity hard_cap, headroom, per_unit and reserve_for_waitlist; algorithm weight; reentry reopen_on_leave; schedule opens_at, closes_at, announce_when_closed and lock_when_closed; branding naming_template, photo_url and description. Unit capacity columns record the effective limit as a snapshot; only explicit settings override inheritance. Unit weight and opening/closing times are mirrored into their consumer columns. Null restores inherited unit capacity and weight and clears unit opening/closing columns. The resolved headroom must remain smaller than hard_cap; an invalid capacity combination is rejected atomically with capacity.headroom.","properties":{"capacity":{"type":"object","additionalProperties":false,"properties":{"hard_cap":{"type":["integer","null"],"minimum":1,"maximum":1024},"headroom":{"type":["integer","null"],"minimum":0,"maximum":1023,"description":"Seat margin below hard_cap; the resolved margin must remain smaller than the resolved hard cap. Null inherits."},"per_unit":{"type":["integer","null"],"minimum":1,"maximum":1023},"by_inbox":{"type":["object","null"],"additionalProperties":false},"reserve_for_waitlist":{"type":["integer","null"],"minimum":0}}},"algorithm":{"type":"object","additionalProperties":false,"properties":{"strategy":{"type":["string","null"],"enum":["fill_first","round_robin","random","weighted",null]},"weight":{"type":["integer","null"],"minimum":0},"sticky_by_contact":{"type":["boolean","null"],"enum":[true,false,null]},"routing_rules":{"anyOf":[{"type":["array","null"],"description":"Ordered rules, evaluated with equality and all conditions together. New or changed lists must use recognized condition keys and member sources; an identical legacy list may remain during an unrelated update. Null removes the override. UTM values and account labels are open values.","items":{"type":"object","required":["match"],"properties":{"match":{"type":"object","additionalProperties":false,"properties":{"utm_source":{"type":"string","description":"Compared with lead attribution, ignoring case and surrounding spaces."},"utm_campaign":{"type":"string","description":"Compared with lead attribution, ignoring case and surrounding spaces."},"tag":{"type":"string","description":"Literal label from the account label catalog."},"source":{"type":"string","enum":["link","automation","event","manual","api","follow_up"],"description":"Member entry source; null and empty values are not choices."}}},"distribution_id":{"type":"integer","minimum":1,"description":"Target distribution; skipped unless it is active and not archived in the same account."}}}},{"$ref":"#/components/schemas/json_value","description":"A previously stored JSON value may be retained only when it is exactly identical to this field or complete list in the same persisted record. Equality with persisted state is enforced at runtime and cannot be expressed by this static schema alone. A new or changed invalid value is rejected; no conversion, filtering or implicit repair is performed."}]}}},"rotation":{"type":"object","additionalProperties":false,"properties":{"batch_size":{"type":["integer","null"],"minimum":0},"warmup_ramp":{"type":["array","null"],"description":"Rotation batch steps; the latest step whose after_minutes has elapsed since creation sets the batch size.","items":{"type":"object","properties":{"after_minutes":{"type":"integer","minimum":0,"description":"Minutes after the distribution was created when the step starts."},"batch":{"type":"integer","minimum":1,"description":"Rotation batch size while the step applies; a missing or zero batch keeps the flat batch_size."}}}},"defer_base_seconds":{"type":["integer","null"],"minimum":0},"max_backoff_shift":{"type":["integer","null"],"minimum":0},"max_defer_attempts":{"type":["integer","null"],"minimum":0},"throttle":{"type":["object","null"],"additionalProperties":false,"properties":{"second":{"type":["integer","null"],"minimum":0},"hour":{"type":["integer","null"],"minimum":0}}},"sync_interval_minutes":{"type":["integer","null"],"minimum":0},"scheduler_batch_size":{"type":["integer","null"],"minimum":0}}},"fallback":{"type":"object","additionalProperties":false,"properties":{"mode":{"type":["string","null"],"enum":["url","distribution","message","waitlist",null]},"url":{"type":["string","null"],"format":"uri"},"message":{"type":["string","null"]},"distribution_id":{"type":["integer","null"],"minimum":0},"waitlist_max":{"type":["integer","null"],"minimum":0},"waitlist_ttl_hours":{"type":["integer","null"],"minimum":0},"waitlist_drain_batch":{"type":["integer","null"],"minimum":0}}},"schedule":{"type":"object","additionalProperties":false,"properties":{"opens_at":{"type":["string","null"],"format":"date-time"},"closes_at":{"type":["string","null"],"format":"date-time"},"cascade_minutes":{"type":["integer","null"],"minimum":0},"announce_when_closed":{"type":["boolean","null"],"enum":[true,false,null]},"lock_when_closed":{"type":["boolean","null"],"enum":[true,false,null]},"warmup_window_minutes":{"type":["integer","null"],"minimum":0},"timezone":{"type":"string","description":"IANA timezone identifier (e.g. \"America/Sao_Paulo\", \"UTC\"). Rails timezone names are also accepted on input; an unrecognized value is ignored in favor of the next fallback.","example":"America/Sao_Paulo"}}},"reentry":{"type":"object","additionalProperties":false,"properties":{"allow_reentry":{"type":["boolean","null"],"enum":[true,false,null]},"cooldown_hours":{"type":["integer","null"],"minimum":0},"dedupe_across_units":{"type":["boolean","null"],"enum":[true,false,null]},"use_hub_blocklist":{"type":["boolean","null"],"enum":[true,false,null]},"blacklist":{"type":["array","null"],"description":"Phone numbers refused on entry; non-digit characters are ignored.","items":{"type":["string","integer"]}},"whitelist":{"type":["array","null"],"description":"Phone numbers allowed on entry; non-digit characters are ignored.","items":{"type":["string","integer"]}},"reopen_on_leave":{"type":["boolean","null"],"enum":[true,false,null]}}},"post_purchase":{"type":"object","additionalProperties":false,"properties":{"on_paid":{"type":["object","null"],"additionalProperties":false,"properties":{"remove":{"type":["boolean","null"],"enum":[true,false,null]},"move_to_distribution_id":{"type":["integer","null"],"minimum":0},"delay_minutes":{"type":["integer","null"],"minimum":0}}},"on_overdue":{"type":["object","null"],"additionalProperties":false,"properties":{"remove":{"type":["boolean","null"],"enum":[true,false,null]},"after_days":{"type":["integer","null"],"minimum":0},"warn_template":{"anyOf":[{"type":["string","null"],"enum":["welcome","reminder","countdown","unit_opened","waitlist_ack","removed_notice","graduated_notice",null],"description":"Recognized stored template identifier. Null removes the override; an empty string is invalid. An unchanged legacy identifier may be retained on an unrelated update. This selector currently has no operational send consumer; accepting an identifier does not schedule or send a message."},{"$ref":"#/components/schemas/json_value","description":"A previously stored JSON value may be retained only when it is exactly identical to this field or complete list in the same persisted record. Equality with persisted state is enforced at runtime and cannot be expressed by this static schema alone. A new or changed invalid value is rejected; no conversion, filtering or implicit repair is performed."}]}}},"on_refund":{"type":["object","null"],"additionalProperties":false,"properties":{"remove":{"type":["boolean","null"],"enum":[true,false,null]}}},"on_chargeback":{"type":["object","null"],"additionalProperties":false,"properties":{"remove":{"type":["boolean","null"],"enum":[true,false,null]}}},"remove_batch_size":{"type":["integer","null"],"minimum":0},"remove_throttle":{"type":["object","null"],"additionalProperties":false,"properties":{"second":{"type":["integer","null"],"minimum":0},"hour":{"type":["integer","null"],"minimum":0}}}}},"sellers":{"type":"object","additionalProperties":false,"properties":{"strategy":{"type":["string","null"],"enum":["round_robin","random","weighted",null]},"list":{"type":["array","null"],"description":"Sellers rotated 1:1; each entry is read with exactly these fields.","items":{"type":"object","properties":{"phone":{"type":"string","pattern":"^[0-9]{8,15}$","description":"Seller WhatsApp number, digits only."},"name":{"type":"string","minLength":1},"weight":{"type":"integer","minimum":1},"paused":{"type":"boolean"},"user_id":{"type":["integer","null"],"description":"Agent of this account linked to the seller."},"inbox_id":{"type":["integer","null"],"description":"WhatsApp inbox of this account used for the seller."}}}},"prefill_template":{"type":["string","null"]},"daily_cap_per_seller":{"type":["integer","null"],"minimum":0},"pause_when_offline":{"type":["boolean","null"],"enum":[true,false,null]}}},"dm_on_join":{"type":"object","additionalProperties":false,"properties":{"enabled":{"type":["boolean","null"],"enum":[true,false,null]},"template":{"anyOf":[{"type":["string","null"],"enum":["welcome","reminder","countdown","unit_opened","waitlist_ack","removed_notice","graduated_notice",null],"description":"Recognized stored template identifier. Null removes the override; an empty string is invalid. An unchanged legacy identifier may be retained on an unrelated update. This selector currently has no operational send consumer; accepting an identifier does not schedule or send a message."},{"$ref":"#/components/schemas/json_value","description":"A previously stored JSON value may be retained only when it is exactly identical to this field or complete list in the same persisted record. Equality with persisted state is enforced at runtime and cannot be expressed by this static schema alone. A new or changed invalid value is rejected; no conversion, filtering or implicit repair is performed."}]},"spintax":{"type":["array","null"],"description":"Message variants; one is picked at random per send and blank entries are dropped.","items":{"type":"string"}},"delay_seconds":{"type":["object","null"],"additionalProperties":false,"properties":{"min":{"type":["integer","null"],"minimum":0},"max":{"type":["integer","null"],"minimum":0}}},"per_hour_limit":{"type":["integer","null"],"minimum":0},"inbox_id":{"type":["integer","null"],"minimum":0},"fallback_inbox_id":{"type":["integer","null"],"minimum":0},"mode":{"type":["string","null"],"enum":["fixed","generative",null]},"brief":{"type":["string","null"]},"skip_if_conversation_open":{"type":["boolean","null"],"enum":[true,false,null]}}},"templates":{"type":"object","additionalProperties":false,"properties":{"welcome":{"type":["object","null"],"additionalProperties":false,"properties":{"text":{"type":["string","null"]},"spintax":{"type":["array","null"],"description":"Message variants; one is picked at random per send and blank entries are dropped.","items":{"type":"string"}},"media_url":{"type":["string","null"],"format":"uri"}}},"reminder":{"type":["object","null"],"additionalProperties":false,"properties":{"i18n_key":{"type":["string","null"]},"text":{"type":["string","null"]},"spintax":{"type":["array","null"],"description":"Message variants; one is picked at random per send and blank entries are dropped.","items":{"type":"string"}},"media_url":{"type":["string","null"],"format":"uri"}}},"countdown":{"type":["object","null"],"additionalProperties":false,"properties":{"i18n_key":{"type":["string","null"]},"text":{"type":["string","null"]},"spintax":{"type":["array","null"],"description":"Message variants; one is picked at random per send and blank entries are dropped.","items":{"type":"string"}},"media_url":{"type":["string","null"],"format":"uri"}}},"unit_opened":{"type":["object","null"],"additionalProperties":false,"properties":{"i18n_key":{"type":["string","null"]},"text":{"type":["string","null"]},"spintax":{"type":["array","null"],"description":"Message variants; one is picked at random per send and blank entries are dropped.","items":{"type":"string"}},"media_url":{"type":["string","null"],"format":"uri"}}},"waitlist_ack":{"type":["object","null"],"additionalProperties":false,"properties":{"i18n_key":{"type":["string","null"]},"text":{"type":["string","null"]},"spintax":{"type":["array","null"],"description":"Message variants; one is picked at random per send and blank entries are dropped.","items":{"type":"string"}},"media_url":{"type":["string","null"],"format":"uri"}}},"removed_notice":{"type":["object","null"],"additionalProperties":false,"properties":{"i18n_key":{"type":["string","null"]},"text":{"type":["string","null"]},"spintax":{"type":["array","null"],"description":"Message variants; one is picked at random per send and blank entries are dropped.","items":{"type":"string"}},"media_url":{"type":["string","null"],"format":"uri"}}},"graduated_notice":{"type":["object","null"],"additionalProperties":false,"properties":{"i18n_key":{"type":["string","null"]},"text":{"type":["string","null"]},"spintax":{"type":["array","null"],"description":"Message variants; one is picked at random per send and blank entries are dropped.","items":{"type":"string"}},"media_url":{"type":["string","null"],"format":"uri"}}}}},"branding":{"type":"object","additionalProperties":false,"properties":{"naming_template":{"type":["string","null"]},"photo_url":{"type":["string","null"],"format":"uri","description":"Null removes the override. An explicit unit photo overrides distribution identity, then identity overrides the inherited URL. External URLs require HTTPS. HTTP is accepted only for an authorized account-owned image blob on the canonical application origin with a valid signed blob URL and no credentials, query or fragment."},"description":{"type":["string","null"]},"admins":{"type":["array","null"],"description":"Group admins promoted on provisioning; a value with @ is a WhatsApp JID, otherwise a phone whose non-digits are ignored.","items":{"type":"string"}},"announcement_group":{"type":["boolean","null"],"enum":[true,false,null]},"auto_create_channel":{"type":["boolean","null"],"enum":[true,false,null]},"auto_create_channel_live":{"type":["boolean","null"],"enum":[true,false,null]},"channel_invite_url":{"type":["string","null"],"format":"uri"}}},"attribution":{"type":"object","additionalProperties":false,"properties":{"utm_capture":{"type":["boolean","null"],"enum":[true,false,null]},"store_referrer_host":{"type":["boolean","null"],"enum":[true,false,null]},"store_ip_hash":{"type":["boolean","null"],"enum":[true,false,null]},"capi":{"type":["object","null"],"additionalProperties":false,"properties":{"on_click":{"type":["string","null"]},"on_join":{"type":["string","null"]},"on_purchase":{"type":["string","null"]}}},"contact_attribute_key":{"type":["string","null"]}}},"api":{"type":"object","additionalProperties":false,"properties":{"bulk_enroll_max":{"type":["integer","null"],"minimum":0},"index_page_size":{"type":["integer","null"],"minimum":0},"approvals_timeout_seconds":{"type":["integer","null"],"minimum":0},"public_link_rate_per_minute":{"type":["integer","null"],"minimum":0},"export_row_limit":{"type":["integer","null"],"minimum":0}}},"join_approval":{"type":"object","additionalProperties":false,"properties":{"batch":{"type":["integer","null"],"minimum":0},"policy":{"type":["string","null"]}}},"setup":{"type":"object","additionalProperties":false,"properties":{"pause_seconds":{"type":["integer","null"],"minimum":0,"maximum":60},"pause_jitter_seconds":{"type":["integer","null"],"minimum":0},"pause_max_seconds":{"type":["integer","null"],"minimum":0}}}}}}},"examples":{"distribution":{"summary":"Distribution overrides, using shipped values and explicit null removals.","value":{"settings":{"capacity":{"hard_cap":1024,"headroom":24,"per_unit":1000,"by_inbox":{},"reserve_for_waitlist":0},"algorithm":{"strategy":"fill_first","weight":1,"sticky_by_contact":true,"routing_rules":[{"match":{"utm_source":"sample utm source","utm_campaign":"sample utm campaign","tag":"sample tag","source":"link"},"distribution_id":1}]},"rotation":{"batch_size":10,"warmup_ramp":[{"after_minutes":60,"batch":1}],"defer_base_seconds":30,"max_backoff_shift":6,"max_defer_attempts":8,"throttle":{"second":null,"hour":null},"sync_interval_minutes":2,"scheduler_batch_size":500},"fallback":{"mode":"url","url":null,"message":"growth_distribution.public.unavailable.default_message","distribution_id":null,"waitlist_max":1000,"waitlist_ttl_hours":168,"waitlist_drain_batch":25},"schedule":{"opens_at":null,"closes_at":null,"cascade_minutes":0,"announce_when_closed":true,"lock_when_closed":false,"warmup_window_minutes":0,"timezone":null},"reentry":{"allow_reentry":false,"cooldown_hours":24,"dedupe_across_units":true,"use_hub_blocklist":false,"blacklist":[],"whitelist":[],"reopen_on_leave":true},"post_purchase":{"on_paid":{"remove":false,"move_to_distribution_id":null,"delay_minutes":0},"on_overdue":{"remove":false,"after_days":3,"warn_template":"removed_notice"},"on_refund":{"remove":true},"on_chargeback":{"remove":true},"remove_batch_size":20,"remove_throttle":{"second":null,"hour":null}},"sellers":{"strategy":"round_robin","list":[{"phone":"+5511999998888","name":"Sample Name","weight":1,"paused":true,"user_id":1,"inbox_id":1}],"prefill_template":"growth_distribution.sellers.prefill_default","daily_cap_per_seller":0,"pause_when_offline":false},"dm_on_join":{"enabled":false,"template":"welcome","spintax":[],"delay_seconds":{"min":5,"max":45},"per_hour_limit":60,"inbox_id":null,"fallback_inbox_id":null,"mode":"fixed","brief":"","skip_if_conversation_open":true},"templates":{"welcome":{"text":null,"spintax":[],"media_url":null},"reminder":{"i18n_key":"growth_distribution.templates.reminder","text":null,"spintax":[],"media_url":null},"countdown":{"i18n_key":"growth_distribution.templates.countdown","text":null,"spintax":[],"media_url":null},"unit_opened":{"i18n_key":"growth_distribution.templates.unit_opened","text":null,"spintax":[],"media_url":null},"waitlist_ack":{"i18n_key":"growth_distribution.templates.waitlist_ack","text":null,"spintax":[],"media_url":null},"removed_notice":{"i18n_key":"growth_distribution.templates.removed_notice","text":null,"spintax":[],"media_url":null},"graduated_notice":{"i18n_key":"growth_distribution.templates.graduated_notice","text":null,"spintax":[],"media_url":null}},"branding":{"naming_template":"Turma {n}","photo_url":null,"description":null,"admins":[],"announcement_group":false,"auto_create_channel":false,"auto_create_channel_live":false,"channel_invite_url":null},"attribution":{"utm_capture":true,"store_referrer_host":true,"store_ip_hash":true,"capi":{"on_click":null,"on_join":null,"on_purchase":null},"contact_attribute_key":"distribution_attributions"},"api":{"bulk_enroll_max":1000,"index_page_size":25,"approvals_timeout_seconds":3,"public_link_rate_per_minute":30,"export_row_limit":50000},"join_approval":{"batch":20,"policy":"all_while_seats"},"setup":{"pause_seconds":3,"pause_jitter_seconds":2,"pause_max_seconds":60}},"unit_id":81}},"unit":{"summary":"Unit capacity and schedule overrides with column mirroring.","value":{"unit_id":81,"settings":{"capacity":{"per_unit":200,"hard_cap":1,"headroom":1,"by_inbox":{},"reserve_for_waitlist":1},"algorithm":{"weight":2,"strategy":"fill_first","sticky_by_contact":true,"routing_rules":[{"match":{"utm_source":"sample utm source","utm_campaign":"sample utm campaign","tag":"sample tag","source":"link"},"distribution_id":1}]},"schedule":{"opens_at":"2026-10-15T10:00:00Z","closes_at":"2026-10-16T10:00:00Z","cascade_minutes":60,"announce_when_closed":true,"lock_when_closed":true,"warmup_window_minutes":60,"timezone":"America/Sao_Paulo"},"rotation":{"batch_size":1,"warmup_ramp":[{"after_minutes":60,"batch":1}],"defer_base_seconds":60,"max_backoff_shift":1,"max_defer_attempts":1,"throttle":{"second":1,"hour":1},"sync_interval_minutes":60,"scheduler_batch_size":1},"fallback":{"mode":"url","url":"https://example.com/resource","message":"Sample message text.","distribution_id":1,"waitlist_max":1,"waitlist_ttl_hours":1,"waitlist_drain_batch":1},"reentry":{"allow_reentry":true,"cooldown_hours":1,"dedupe_across_units":true,"use_hub_blocklist":true,"blacklist":["sample blacklist"],"whitelist":["sample whitelist"],"reopen_on_leave":true},"post_purchase":{"on_paid":{"remove":true,"move_to_distribution_id":1,"delay_minutes":60},"on_overdue":{"remove":true,"after_days":7,"warn_template":"welcome"},"on_refund":{"remove":true},"on_chargeback":{"remove":true},"remove_batch_size":1,"remove_throttle":{"second":1,"hour":1}},"sellers":{"strategy":"round_robin","list":[{"phone":"+5511999998888","name":"Sample Name","weight":1,"paused":true,"user_id":1,"inbox_id":1}],"prefill_template":"sample prefill template","daily_cap_per_seller":1,"pause_when_offline":true},"dm_on_join":{"enabled":true,"template":"welcome","spintax":["sample spintax"],"delay_seconds":{"min":1,"max":1},"per_hour_limit":1,"inbox_id":1,"fallback_inbox_id":1,"mode":"fixed","brief":"sample brief","skip_if_conversation_open":true},"templates":{"welcome":{"text":"sample text","spintax":["sample spintax"],"media_url":"https://example.com/resource"},"reminder":{"i18n_key":"sample-token","text":"sample text","spintax":["sample spintax"],"media_url":"https://example.com/resource"},"countdown":{"i18n_key":"sample-token","text":"sample text","spintax":["sample spintax"],"media_url":"https://example.com/resource"},"unit_opened":{"i18n_key":"sample-token","text":"sample text","spintax":["sample spintax"],"media_url":"https://example.com/resource"},"waitlist_ack":{"i18n_key":"sample-token","text":"sample text","spintax":["sample spintax"],"media_url":"https://example.com/resource"},"removed_notice":{"i18n_key":"sample-token","text":"sample text","spintax":["sample spintax"],"media_url":"https://example.com/resource"},"graduated_notice":{"i18n_key":"sample-token","text":"sample text","spintax":["sample spintax"],"media_url":"https://example.com/resource"}},"branding":{"naming_template":"sample naming template","photo_url":"https://example.com/resource","description":"A short description.","admins":["sample admin"],"announcement_group":true,"auto_create_channel":true,"auto_create_channel_live":true,"channel_invite_url":"https://example.com/resource"},"attribution":{"utm_capture":true,"store_referrer_host":true,"store_ip_hash":true,"capi":{"on_click":"sample on click","on_join":"sample on join","on_purchase":"sample on purchase"},"contact_attribute_key":"sample-token"},"api":{"bulk_enroll_max":1,"index_page_size":1,"approvals_timeout_seconds":60,"public_link_rate_per_minute":1,"export_row_limit":1},"join_approval":{"batch":1,"policy":"sample policy"},"setup":{"pause_seconds":60,"pause_jitter_seconds":60,"pause_max_seconds":60}}}}}}}}}},"/api/v1/accounts/{account_id}/growth/distributions/{id}/export":{"get":{"tags":["Growth Distribution"],"operationId":"auto_get_api_v1_accounts_account_id_growth_distributions_id_export","summary":"Stream a masked distribution member CSV","description":"Administrator-only CSV with one row per member up to the resolved export limit. The phone is always masked, or empty for a hidden phone field. Spreadsheet formulas are escaped in every cell. Dates and the filename date use the account timezone. Truncation is declared before streaming. No names, emails, contact ids, IP hashes or referrers are exported.","security":[{"userApiKey":[]}],"responses":{"204":{"description":"Success (no content)"},"401":{"description":"An administrator or custom role with distribution management permission is required."},"404":{"description":"The distribution is outside the caller scope."},"200":{"description":"CSV stream, optionally truncated at the configured row limit.","headers":{"Content-Disposition":{"description":"Attachment filename containing the distribution slug and account-local date.","schema":{"type":"string"},"example":"attachment; filename=\"turma-october-launch-2026-10-15.csv\""},"Cache-Control":{"description":"Member data must not be cached.","schema":{"type":"string","enum":["no-store"]},"example":"no-store"},"X-Export-Truncated":{"description":"Present only when matching members exceed the exported row limit.","schema":{"type":"string","enum":["true"]},"example":"true"},"X-Export-Row-Limit":{"description":"Effective row limit, present only with X-Export-Truncated.","schema":{"type":"integer","minimum":0},"example":50000}},"content":{"text/csv":{"schema":{"type":"string","description":"UTF-8 CSV with the fixed nine-column header."},"example":"phone_masked,state,source,unit_sequence,joined_at,left_at,utm_source,utm_medium,utm_campaign\n••••1234,joined,manual,1,2026-10-15T09:00:00-03:00,,newsletter,email,october\n"}}},"403":{"description":"The launch distribution feature is not enabled."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/growth/distributions/{id}/sellers":{"get":{"tags":["Growth Distribution"],"operationId":"auto_get_api_v1_accounts_account_id_growth_distributions_id_sellers","summary":"Read the effective seller list","description":"Reads account defaults with distribution overrides, preserving rotation order and projecting only phone, name, weight, paused, user_id and inbox_id. Missing fields are null; legacy malformed field values are returned unchanged and non-object items are omitted. A non-array list is empty. Phone digits are unmasked for authorized readers. Administrator or agent access is required, with the existing custom-role permission rules. The advanced flag is not required for this read. Available for every distribution target type.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Ordered seller rows with exactly six fields per row; no counters or assignment occurs.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["payload"],"properties":{"payload":{"type":"array","description":"Effective list in rotation order; non-object stored items are omitted.","items":{"anyOf":[{"type":"object","additionalProperties":false,"required":["phone","name","weight","paused","user_id","inbox_id"],"properties":{"phone":{"type":"string","pattern":"^[1-9][0-9]{7,14}$","description":"E.164 phone digits without a plus sign; unique within this ordered list.","example":"15555550101"},"name":{"type":"string","minLength":1,"pattern":"\\S","description":"Seller display name. Leading and trailing whitespace is removed on replacement.","example":"Seller One"},"weight":{"type":"integer","minimum":1,"description":"Positive integer weight. A paused seller retains its weight.","example":1},"paused":{"type":"boolean","description":"Whether the seller is paused.","example":false},"user_id":{"type":["integer","null"],"description":"Optional user belonging to the current account.","example":null},"inbox_id":{"type":["integer","null"],"description":"Optional WhatsApp inbox belonging to the current account.","example":null}}},{"type":"object","additionalProperties":false,"description":"Six-key projection of a stored row that has not passed current replacement validation.","required":["phone","name","weight","paused","user_id","inbox_id"],"properties":{"phone":{"description":"Stored JSON value, returned unchanged for a legacy or malformed row. A missing field becomes null. This compatibility reader does not coerce strings, numbers, booleans, arrays, objects or null.","additionalProperties":true},"name":{"description":"Stored JSON value, returned unchanged for a legacy or malformed row. A missing field becomes null. This compatibility reader does not coerce strings, numbers, booleans, arrays, objects or null.","additionalProperties":true},"weight":{"description":"Stored JSON value, returned unchanged for a legacy or malformed row. A missing field becomes null. This compatibility reader does not coerce strings, numbers, booleans, arrays, objects or null.","additionalProperties":true},"paused":{"description":"Stored JSON value, returned unchanged for a legacy or malformed row. A missing field becomes null. This compatibility reader does not coerce strings, numbers, booleans, arrays, objects or null.","additionalProperties":true},"user_id":{"description":"Stored JSON value, returned unchanged for a legacy or malformed row. A missing field becomes null. This compatibility reader does not coerce strings, numbers, booleans, arrays, objects or null.","additionalProperties":true},"inbox_id":{"description":"Stored JSON value, returned unchanged for a legacy or malformed row. A missing field becomes null. This compatibility reader does not coerce strings, numbers, booleans, arrays, objects or null.","additionalProperties":true}}}]}}}},"example":{"payload":[{"phone":"15555550101","name":"Seller One","weight":1,"paused":false,"user_id":null,"inbox_id":null},{"phone":"15555550102","name":"Seller Two","weight":2,"paused":true,"user_id":null,"inbox_id":null}]}}}},"401":{"description":"Authentication or permission to read launch distributions is required."},"404":{"description":"The distribution is outside the caller scope or does not exist."},"403":{"description":"feature_not_enabled means the base launch distribution feature is disabled. forbidden means the inherited native access-role gate denied distribution management permission.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","enum":["feature_not_enabled","forbidden"],"example":"feature_not_enabled"}}},"examples":{"feature_disabled":{"summary":"Base launch distribution feature is disabled.","value":{"error":"feature_not_enabled"}},"permission_denied":{"summary":"Native access-role gate denies distribution management permission.","value":{"error":"forbidden"}}}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]},"patch":{"tags":["Growth Distribution"],"operationId":"auto_patch_api_v1_accounts_account_id_growth_distributions_id_sellers","summary":"Replace a distribution seller list","description":"Replaces the whole list in the distribution layer, including an empty list. Validates every row before writing, checks optional user and WhatsApp inbox ids against the current account, trims names, supplies null optional ids and drops unrecognized row fields. Other configuration remains unchanged. Requires administrator access or the existing distribution-management custom-role permission, plus the advanced launch distribution feature. Last committed replacement wins under the existing settings lock. No event, job, picker or assignment is triggered by this action.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Ordered seller rows with exactly six fields per row; no counters or assignment occurs.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["payload"],"properties":{"payload":{"type":"array","description":"Effective list in rotation order; non-object stored items are omitted.","items":{"anyOf":[{"type":"object","additionalProperties":false,"required":["phone","name","weight","paused","user_id","inbox_id"],"properties":{"phone":{"type":"string","pattern":"^[1-9][0-9]{7,14}$","description":"E.164 phone digits without a plus sign; unique within this ordered list.","example":"15555550101"},"name":{"type":"string","minLength":1,"pattern":"\\S","description":"Seller display name. Leading and trailing whitespace is removed on replacement.","example":"Seller One"},"weight":{"type":"integer","minimum":1,"description":"Positive integer weight. A paused seller retains its weight.","example":1},"paused":{"type":"boolean","description":"Whether the seller is paused.","example":false},"user_id":{"type":["integer","null"],"description":"Optional user belonging to the current account.","example":null},"inbox_id":{"type":["integer","null"],"description":"Optional WhatsApp inbox belonging to the current account.","example":null}}},{"type":"object","additionalProperties":false,"description":"Six-key projection of a stored row that has not passed current replacement validation.","required":["phone","name","weight","paused","user_id","inbox_id"],"properties":{"phone":{"description":"Stored JSON value, returned unchanged for a legacy or malformed row. A missing field becomes null. This compatibility reader does not coerce strings, numbers, booleans, arrays, objects or null.","additionalProperties":true},"name":{"description":"Stored JSON value, returned unchanged for a legacy or malformed row. A missing field becomes null. This compatibility reader does not coerce strings, numbers, booleans, arrays, objects or null.","additionalProperties":true},"weight":{"description":"Stored JSON value, returned unchanged for a legacy or malformed row. A missing field becomes null. This compatibility reader does not coerce strings, numbers, booleans, arrays, objects or null.","additionalProperties":true},"paused":{"description":"Stored JSON value, returned unchanged for a legacy or malformed row. A missing field becomes null. This compatibility reader does not coerce strings, numbers, booleans, arrays, objects or null.","additionalProperties":true},"user_id":{"description":"Stored JSON value, returned unchanged for a legacy or malformed row. A missing field becomes null. This compatibility reader does not coerce strings, numbers, booleans, arrays, objects or null.","additionalProperties":true},"inbox_id":{"description":"Stored JSON value, returned unchanged for a legacy or malformed row. A missing field becomes null. This compatibility reader does not coerce strings, numbers, booleans, arrays, objects or null.","additionalProperties":true}}}]}}}},"example":{"payload":[{"phone":"15555550101","name":"Seller One","weight":1,"paused":false,"user_id":null,"inbox_id":null},{"phone":"15555550102","name":"Seller Two","weight":2,"paused":true,"user_id":null,"inbox_id":null}]}}}},"401":{"description":"Authentication and administrator or distribution-management custom-role permission are required."},"404":{"description":"The distribution is outside the caller scope or does not exist."},"403":{"description":"feature_not_enabled means the base launch distribution feature or its advanced flag is disabled. forbidden means the inherited native access-role gate denied distribution management permission.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","enum":["feature_not_enabled","forbidden"],"example":"feature_not_enabled"}}},"examples":{"feature_disabled":{"summary":"Base launch distribution feature or advanced flag is disabled.","value":{"error":"feature_not_enabled"}},"permission_denied":{"summary":"Native access-role gate denies distribution management permission.","value":{"error":"forbidden"}}}}}},"422":{"description":"Invalid replacement; no list or unrelated setting is persisted.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error","keys"],"properties":{"error":{"type":"string","enum":["invalid_sellers"],"example":"invalid_sellers"},"keys":{"type":"array","uniqueItems":true,"minItems":1,"description":"Rejected keys in input order, then phone, name, weight, paused, user_id, inbox_id within each row. The later duplicate phone is rejected. A non-array list or settings writer refusal is sellers; a non-object row is sellers.\u003cindex\u003e.","items":{"type":"string","pattern":"^sellers(\\.[0-9]+(\\.(phone|name|weight|paused|user_id|inbox_id))?)?$"},"example":["sellers.0.phone","sellers.0.weight"]}}},"example":{"error":"invalid_sellers","keys":["sellers.0.phone","sellers.0.weight"]}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["sellers"],"properties":{"sellers":{"type":"array","description":"Whole ordered replacement. Empty removes every distribution-level seller row.","items":{"type":"object","additionalProperties":true,"description":"A complete replacement row. The two optional ids default to null when absent. Unrecognized fields are ignored rather than stored.","required":["phone","name","weight","paused"],"properties":{"phone":{"type":"string","pattern":"^[1-9][0-9]{7,14}$","description":"E.164 phone digits without a plus sign; unique within this ordered list.","example":"15555550101"},"name":{"type":"string","minLength":1,"pattern":"\\S","description":"Seller display name. Leading and trailing whitespace is removed on replacement.","example":"Seller One"},"weight":{"type":"integer","minimum":1,"description":"Positive integer weight. A paused seller retains its weight.","example":1},"paused":{"type":"boolean","description":"Whether the seller is paused.","example":false},"user_id":{"type":["integer","null"],"description":"Optional user belonging to the current account.","example":null},"inbox_id":{"type":["integer","null"],"description":"Optional WhatsApp inbox belonging to the current account.","example":null}}}}}},"example":{"sellers":[{"phone":"15555550101","name":"Seller One","weight":1,"paused":false,"user_id":null,"inbox_id":null},{"phone":"15555550102","name":"Seller Two","weight":2,"paused":true,"user_id":null,"inbox_id":null}]}}}}}},"/api/v1/accounts/{account_id}/growth/distributions/{id}/broadcast":{"post":{"tags":["Growth Distribution"],"operationId":"auto_post_api_v1_accounts_account_id_growth_distributions_id_broadcast","summary":"Broadcast a text to the groups of chosen distribution units","description":"Creates one WhatsApp Hub broadcast per WhatsApp inbox that owns the groups of the chosen units, so a multi-number distribution yields several broadcasts. Groups come from the Hub distribution scope; delivery, pacing and the pause, cancel and recipient screens are the Hub's. Units without a WhatsApp group are not targeted and are returned as skipped. Requires the WhatsApp Hub feature as well.","security":[{"userApiKey":[]}],"responses":{"401":{"description":"An administrator or custom role with distribution management permission is required."},"404":{"description":"The account, distribution or a listed unit does not exist in the caller scope."},"201":{"description":"The created broadcasts, one per WhatsApp inbox, and the units that had no WhatsApp group.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["payload"],"properties":{"payload":{"type":"object","additionalProperties":false,"required":["broadcasts","skipped_unit_ids"],"properties":{"broadcasts":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["id","display_id","status","inbox_id","targets"],"properties":{"id":{"type":"integer","example":77},"display_id":{"type":"integer","description":"Per-account broadcast number shown in the Hub.","example":12},"status":{"type":"string","enum":["draft","scheduled","sending","completed","paused","failed","cancelled"],"description":"Broadcast status right after creation; sending or scheduled in the usual case."},"inbox_id":{"type":"integer","description":"WhatsApp inbox that owns the targeted groups.","example":6},"targets":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["jid","kind","whatsapp_group_id"],"properties":{"jid":{"type":"string","example":"120363000000000001@g.us"},"kind":{"type":"string","enum":["group","channel"],"example":"group"},"whatsapp_group_id":{"type":"integer","example":501}}}}}}},"skipped_unit_ids":{"type":"array","description":"Chosen units with no WhatsApp group; nothing was sent to them.","items":{"type":"integer"}}}}}},"example":{"payload":{"broadcasts":[{"id":77,"display_id":12,"status":"scheduled","inbox_id":6,"targets":[{"jid":"120363000000000001@g.us","kind":"group","whatsapp_group_id":501}]}],"skipped_unit_ids":[82]}}}}},"400":{"description":"A unit id is not an integer, or schedule_type is neither immediate nor scheduled."},"403":{"description":"The launch distribution feature or the WhatsApp Hub feature is not enabled for the account.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","enum":["feature_not_enabled"]}}},"example":{"error":"feature_not_enabled"}}}},"422":{"description":"Nothing was created. Either a coded refusal (no units, no unit with a WhatsApp group, a scheduled broadcast without a readable time, or more units than the bulk limit) or a missing title or message.","content":{"application/json":{"schema":{"anyOf":[{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","enum":["broadcast_units_required","broadcast_no_targetable_units","broadcast_schedule_required","bulk_limit_exceeded"]},"message":{"type":"string","description":"Translated explanation of the coded refusal."},"max":{"type":"integer","description":"The account bulk limit; present only with bulk_limit_exceeded."}}},{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","description":"Sanitized message naming the missing title or message parameter."}}}]},"example":{"error":"broadcast_no_targetable_units","message":"None of the chosen units has a WhatsApp group yet, so nothing was sent.","max":1}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["unit_ids","title","message"],"properties":{"unit_ids":{"type":"array","minItems":1,"description":"Units of this distribution to target, at most the account bulk limit. Duplicates are ignored.","items":{"type":"integer","minimum":1}},"title":{"type":"string","minLength":1,"description":"Broadcast title shown in the Hub."},"message":{"type":"string","minLength":1,"description":"Text sent to every targeted group or channel."},"schedule_type":{"type":"string","enum":["immediate","scheduled"],"default":"immediate","description":"Immediate broadcasts start fanning out at once; scheduled ones wait for scheduled_at."},"scheduled_at":{"type":"string","format":"date-time","description":"Required when schedule_type is scheduled and ignored otherwise. A time without offset is read in the account time zone."}}},"example":{"unit_ids":[81,82],"title":"Cart open","message":"Last seats in this class.","schedule_type":"scheduled","scheduled_at":"2026-10-20T13:00:00-03:00"}}}}}},"/api/v1/accounts/{account_id}/growth/distributions/{id}/enroll":{"post":{"tags":["Growth Distribution"],"operationId":"auto_post_api_v1_accounts_account_id_growth_distributions_id_enroll","summary":"Enroll distributions","description":"Performs the enroll operation on the targeted distribution resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"enrolled":{"type":"integer"},"skipped":{"type":"integer"},"skipped_reasons":{"type":"string"},"member_ids":{"type":"array","items":{"type":"integer"}}}}}},"example":{"payload":{"enrolled":1,"skipped":1,"skipped_reasons":"sample skipped reasons","member_ids":[1]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"contact_ids":{"type":"array","items":{"type":"integer"}},"contact_id":{"type":"array","items":{"type":"integer"}},"phones":{"type":"array","items":{"type":"string"}},"state":{"type":"string","enum":["pending","queued","invited","added","joined","failed","skipped"],"description":"Distribution member progress state."},"source":{"type":"string"},"page":{"type":"string"},"per_page":{"type":"string"}}},"example":{"contact_ids":[1],"contact_id":[1],"phones":["+5511999998888"],"state":"pending","source":"sample source","page":"sample page","per_page":"sample per page"}}}}}},"/api/v1/accounts/{account_id}/growth/distributions":{"get":{"tags":["Growth Distribution"],"operationId":"auto_get_api_v1_accounts_account_id_growth_distributions","summary":"List launch distributions","description":"Returns account-scoped distributions in descending creation order. Filters are applied before counting and pagination. When neither page nor per_page is supplied, all matching distributions are returned and meta contains only count. Supplying either pagination parameter returns one page and adds the effective page and per_page, plus current_page, total_pages and has_more, to meta. A non-blank unknown status returns 400. Every resource includes the complete localized entry-trigger catalog and diagnostics for its stored list; invalid legacy values remain literal in settings. Capacity metadata and totals use current effective limits, with explicit account, distribution and unit settings rather than old unit snapshots.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Matching launch distributions and their total count, with pagination metadata only when requested.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["payload","meta"],"properties":{"payload":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["id","account_id","name","slug","public_path","inbox_id","launch_id","target_type","join_mode","capacity_per_unit","algorithm","opens_at","fallback_distribution_id","graduate_distribution_id","advanced_enabled","capacity_defaults","community_member_limit","community_provisioning","setup_capabilities","setup_pause_defaults","next_sequence","effective_capacity","throttle_defaults","identity","community_jid","channel_jid","naming_template","welcome_message","status","settings","entry_trigger_catalog","entry_trigger_validation","configuration_options","configuration_validation","units_count","members_count","capacity_total","occupancy_total","awaiting_count","open_unit_sequence","closes_at","archived_at","created_at","updated_at"],"properties":{"algorithm":{"type":"string","enum":["fill_first","round_robin","random","weighted"],"example":"fill_first"},"opens_at":{"type":["string","null"],"format":"date-time","description":"Distribution opening time, when configured.","example":null},"fallback_distribution_id":{"type":["integer","null"],"example":null},"graduate_distribution_id":{"type":["integer","null"],"example":null},"advanced_enabled":{"type":"boolean","description":"Whether advanced launch distribution features are enabled for this account.","example":false},"capacity_defaults":{"type":"object","additionalProperties":false,"required":["default","maximum","effective_maximum","hard_cap","headroom"],"description":"Product default and limits resolved from account and distribution settings. Effective maximum is min(1023, hard_cap minus headroom); absent overrides use hard_cap 1024 and headroom zero.","properties":{"default":{"type":"integer","minimum":1,"maximum":1023,"description":"Product per-unit default; existing explicit capacities are retained.","example":256},"maximum":{"type":"integer","description":"Maximum accepted capacity per launch group.","example":1023},"effective_maximum":{"type":"integer","minimum":0,"maximum":1023,"description":"Maximum after applying the resolved hard cap and explicit headroom.","example":1023},"hard_cap":{"type":"integer","minimum":1,"maximum":1024,"description":"Hard cap resolved from the account and distribution settings.","example":1024},"headroom":{"type":"integer","minimum":0,"maximum":1023,"description":"Explicit seat margin; absent overrides use zero.","example":0}}},"community_member_limit":{"type":"integer","example":2000},"community_provisioning":{"type":"object","additionalProperties":false,"required":["state","error_code","failed_at"],"properties":{"state":{"type":"string","enum":["not_requested","pending","created","failed"],"example":"not_requested","description":"Distribution member progress state."},"error_code":{"type":["string","null"],"enum":["missing_initial_participant","outcome_uncertain","feature_not_supported","gateway_rejected","gateway_unavailable","rate_limited","setup_step_failed","setup_step_refused","setup_incomplete","creator_inbox_unavailable","group_not_admin","group_not_found",null],"example":null},"failed_at":{"type":["string","null"],"format":"date-time","example":null}}},"next_sequence":{"type":"integer","minimum":1,"example":1},"effective_capacity":{"type":"integer","minimum":0,"maximum":1023,"description":"Minimum of the configured per-unit capacity and the resolved effective maximum.","example":256},"throttle_defaults":{"type":"object","additionalProperties":false,"required":["second","hour"],"description":"Default outbound limits for WhatsApp Web; operator overrides are kept in settings.","properties":{"second":{"type":"integer","example":1},"hour":{"type":"integer","example":240}}},"identity":{"type":"object","additionalProperties":false,"required":["mode","items","fallback","remaining_positions","exhausts_at_sequence","limits"],"properties":{"mode":{"type":"string","enum":["none","single","sequence"],"example":"sequence"},"items":{"type":"array","maxItems":100,"items":{"type":"object","additionalProperties":false,"required":["key","source","thumb_url","available","check"],"properties":{"key":{"type":"string","minLength":1,"example":"4711"},"source":{"type":"string","enum":["upload","library","url"],"example":"upload"},"media_asset_id":{"type":"integer","minimum":1,"example":44},"thumb_url":{"type":"string","description":"Center-cropped 160 by 160 representation URL, present only after the full image check succeeded; empty while the check is pending or invalid, when the file is unavailable, or when the representation fails.","example":""},"available":{"type":"boolean","description":"Whether the blob is still attached to this distribution.","example":true},"check":{"type":"object","additionalProperties":false,"required":["state","reason","checked_at","overdue"],"properties":{"state":{"type":"string","enum":["pending","ok","invalid"],"example":"pending","description":"Distribution member progress state."},"reason":{"type":["string","null"],"enum":["type","size","dimensions","unreadable","unavailable",null],"example":null},"checked_at":{"type":["string","null"],"format":"date-time","example":null},"overdue":{"type":"boolean","description":"Pending without a check time for at least 15 minutes since attachment creation; false without the check column or attachment.","example":false}}}}}},"fallback":{"oneOf":[{"type":"object","additionalProperties":false,"required":["key","source","thumb_url","available","check"],"properties":{"key":{"type":"string","minLength":1,"example":"4711"},"source":{"type":"string","enum":["upload","library","url"],"example":"upload"},"media_asset_id":{"type":"integer","minimum":1,"example":44},"thumb_url":{"type":"string","description":"Center-cropped 160 by 160 representation URL, present only after the full image check succeeded; empty while the check is pending or invalid, when the file is unavailable, or when the representation fails.","example":""},"available":{"type":"boolean","description":"Whether the blob is still attached to this distribution.","example":true},"check":{"type":"object","additionalProperties":false,"required":["state","reason","checked_at","overdue"],"properties":{"state":{"type":"string","enum":["pending","ok","invalid"],"example":"pending","description":"Distribution member progress state."},"reason":{"type":["string","null"],"enum":["type","size","dimensions","unreadable","unavailable",null],"example":null},"checked_at":{"type":["string","null"],"format":"date-time","example":null},"overdue":{"type":"boolean","description":"Pending without a check time for at least 15 minutes since attachment creation; false without the check column or attachment.","example":false}}}}},{"type":"null"}]},"limits":{"type":"object","additionalProperties":false,"required":["max_bytes","max_side","max_items","content_types","check_overdue_after_seconds"],"properties":{"max_bytes":{"type":"integer","example":8388608},"max_side":{"type":"integer","example":4096},"max_items":{"type":"integer","example":100},"check_overdue_after_seconds":{"type":"integer","example":900},"content_types":{"type":"array","items":{"type":"string","enum":["image/jpeg","image/png"]},"example":["image/jpeg","image/png"]}}},"remaining_positions":{"type":["integer","null"],"minimum":0,"description":"Remaining own-image positions from next_sequence; null outside sequence mode.","example":2},"exhausts_at_sequence":{"type":["integer","null"],"minimum":0,"description":"Number of own-image positions; null outside sequence mode.","example":2}}},"setup_capabilities":{"type":"object","description":"Birth-setting support by step. Only live capabilities support the listed destination types; partial_contract is unavailable.","additionalProperties":{"type":"object","additionalProperties":false,"required":["tier","target_types"],"properties":{"tier":{"type":"string","enum":["live","partial_contract"]},"target_types":{"type":"array","items":{"type":"string","enum":["group","community"]}}}},"example":{"join_approval":{"tier":"partial_contract","target_types":["group","community"]},"locked":{"tier":"live","target_types":["group","community"]},"member_add_mode":{"tier":"partial_contract","target_types":["group","community"]},"ephemeral":{"tier":"live","target_types":["group","community"]}}},"setup_pause_defaults":{"type":"object","additionalProperties":false,"required":["default_seconds","jitter_seconds","max_seconds"],"description":"Server defaults and operator bounds for setup pacing. Jitter is added only to positive pauses.","properties":{"default_seconds":{"type":"integer","minimum":0,"description":"Base pause inherited when no override is set.","example":3},"jitter_seconds":{"type":"integer","minimum":0,"description":"Maximum random delay added to a positive base pause.","example":2},"max_seconds":{"type":"integer","minimum":0,"description":"Maximum configurable base pause before jitter.","example":60}},"example":{"default_seconds":3,"jitter_seconds":2,"max_seconds":60}},"id":{"type":"integer","example":22},"account_id":{"type":"integer","example":1},"name":{"type":"string","example":"October launch"},"slug":{"type":"string","example":"october-launch"},"public_path":{"type":"string","example":"/g/october-launch"},"inbox_id":{"type":"integer","example":6},"logical_inbox_id":{"type":"integer","description":"Present when the visible logical inbox differs from the transport inbox.","example":15},"launch_id":{"type":["integer","null"],"example":null},"target_type":{"type":"string","enum":["community","group","channel"],"example":"group"},"join_mode":{"type":"string","enum":["invite_link","direct_add","both"],"example":"invite_link"},"capacity_per_unit":{"type":"integer","minimum":1,"maximum":1023,"example":256},"community_jid":{"type":["string","null"],"example":null},"channel_jid":{"type":["string","null"],"example":null},"naming_template":{"type":"string","example":"Launch group {n}"},"welcome_message":{"type":["string","null"],"example":null},"status":{"type":"string","enum":["draft","active","paused","completed"],"example":"draft"},"settings":{"type":"object","additionalProperties":true,"description":"Operator configuration excluding system-owned diagnostics; other configuration keys are preserved.","properties":{"join_approval":{"type":["boolean","null"],"enum":[true,false,null],"description":"Require administrator approval to join. Null inherits WhatsApp. New or changed non-null values require a live capability tier for the destination. An unchanged saved value is accepted on update when the destination stays the same.","example":null},"join_approval_policy":{"type":["string","null"],"enum":["manual","all_while_seats",null],"description":"Null defaults effectively to all_while_seats when join_approval is true. A new or changed non-null policy requires a live join_approval capability tier for the destination. An unchanged saved policy is accepted on update when the destination stays the same. Manual only counts pending requests.","example":null},"locked":{"type":["boolean","null"],"enum":[true,false,null],"description":"Restrict group information edits to administrators. Explicit null keeps WhatsApp's existing setting. Omission follows the rules described for each operation.","example":true},"member_add_mode":{"type":["string","null"],"enum":["admin_add","all_member_add",null],"description":"Who may add members. Null inherits WhatsApp. New or changed non-null values require a live capability tier for the destination. An unchanged saved value is accepted on update when the destination stays the same.","example":null},"ephemeral_seconds":{"type":["integer","null"],"enum":[0,86400,604800,7776000,null],"description":"Disappearing-message duration in seconds; zero disables the timer and null inherits WhatsApp.","example":86400},"setup_pause_seconds":{"type":["integer","null"],"minimum":0,"maximum":60,"default":3,"description":"Base delay between setup delegations, plus zero to two seconds of jitter. Zero disables pauses; null uses three seconds.","example":3},"identity":{"type":"object","additionalProperties":false,"required":["photo"],"properties":{"photo":{"type":"object","additionalProperties":false,"required":["mode","items","fallback"],"properties":{"mode":{"type":"string","enum":["none","single","sequence"],"example":"sequence"},"items":{"type":"array","maxItems":100,"description":"Ordered blob references. Single requires one item; none requires an empty list.","items":{"type":"object","additionalProperties":false,"required":["key","source"],"properties":{"key":{"type":"string","minLength":1,"description":"Blob id attached to this distribution.","example":"4711"},"source":{"type":"string","enum":["upload","library","url"],"example":"upload"},"media_asset_id":{"type":"integer","minimum":1,"description":"Original Library asset, when selected from the Library.","example":44}}}},"fallback":{"description":"Image used after the sequence ends or when a selected image is unavailable.","oneOf":[{"type":"object","additionalProperties":false,"required":["key","source"],"properties":{"key":{"type":"string","minLength":1,"description":"Blob id attached to this distribution.","example":"4711"},"source":{"type":"string","enum":["upload","library","url"],"example":"upload"},"media_asset_id":{"type":"integer","minimum":1,"description":"Original Library asset, when selected from the Library.","example":44}}},{"type":"null"}]}}}}},"photo_url":{"type":["string","null"],"description":"Inherited group photo link. An explicit unit photo overrides distribution identity, then identity overrides the inherited URL. External URLs require HTTPS; HTTP is accepted only for an authorized account-owned image blob on the canonical application origin with a valid signed blob URL and no credentials, query or fragment. Null removes the override.","example":"https://images.example.test/legacy-cover.jpg"},"description":{"type":["string","null"],"description":"Group description; each occurrence of {n} is replaced with the unit sequence.","example":"Welcome to launch group {n}."}}},"entry_trigger_catalog":{"type":"array","description":"Complete list of selectable entry keys, shared with server validation. Text is localized for the request. Translation keys belong to the server translation catalog. Availability of a key does not guarantee an event producer, an eligible contact or an enrollment effect.","items":{"type":"object","additionalProperties":false,"required":["key","label_key","description_key","label","description"],"properties":{"key":{"type":"string","description":"A selectable launch distribution entry key backed by an enrollment consumer. Payment confirmed emissions use payment_charge.paid.","enum":["payment_charge.paid","payment_charge.overdue","crm_item.stage_changed","crm_item.stale","crm_item.won","task.overdue","task.due_soon","calendar_event.created","calendar_event.no_show","commerce.cart_abandoned","commerce.order_placed","commerce.payment_pending","commerce.payment_confirmed","commerce.payment_declined","commerce.overdue","commerce.due_soon","commerce.refunded","commerce.chargeback","commerce.subscription_late","commerce.subscription_canceled","ads.lead_captured","social.comment_captured"],"example":"payment_charge.paid"},"label_key":{"type":"string","description":"Server translation key for the label.","example":"growth.distribution.entry_triggers.events.payment_charge_paid.label"},"description_key":{"type":"string","description":"Server translation key for the description.","example":"growth.distribution.entry_triggers.events.payment_charge_paid.description"},"label":{"type":"string","description":"Localized label.","example":"Charge paid"},"description":{"type":"string","description":"Localized explanation of the entry signal.","example":"A confirmed or paid charge payment, admitted through the payment_charge.paid key."}}},"example":[{"key":"payment_charge.paid","label_key":"growth.distribution.entry_triggers.events.payment_charge_paid.label","description_key":"growth.distribution.entry_triggers.events.payment_charge_paid.description","label":"Charge paid","description":"A confirmed or paid charge payment, admitted through the payment_charge.paid key."}]},"entry_trigger_validation":{"type":"object","additionalProperties":false,"required":["valid","invalid_type","invalid_indexes"],"description":"Advisory validation of the stored entry list, without changing it. Read invalid values from settings.entry_triggers at the reported positions. A malformed non-array value has invalid_type true and no positions. An absent list is valid and equivalent to an empty list.","properties":{"valid":{"type":"boolean","example":false},"invalid_type":{"type":"boolean","example":false},"invalid_indexes":{"type":"array","description":"Zero-based positions of unknown keys or elements that are not strings.","items":{"type":"integer","minimum":0},"example":[0]}},"example":{"valid":false,"invalid_type":false,"invalid_indexes":[0]}},"configuration_options":{"type":"object","additionalProperties":false,"required":["routing_sources","template_keys"],"description":"Recognized routing sources and stored template identifiers from the same server sets used by validation. Template membership does not imply a send: the join-template and overdue-warning selectors currently have no operational send consumer and must be presented as unavailable.","properties":{"routing_sources":{"type":"array","items":{"type":"string","enum":["link","automation","event","manual","api","follow_up"]}},"template_keys":{"type":"array","items":{"type":"string","enum":["welcome","reminder","countdown","unit_opened","waitlist_ack","removed_notice","graduated_notice"]}}},"example":{"routing_sources":["link","automation","event","manual","api","follow_up"],"template_keys":["welcome","reminder","countdown","unit_opened","waitlist_ack","removed_notice","graduated_notice"]}},"configuration_validation":{"type":"object","additionalProperties":false,"required":["valid","issues"],"description":"Diagnostics for saved and resolved choices without removing or rewriting them. Paths are relative to the settings document; inherited values also remain available in settings explanations.","properties":{"valid":{"type":"boolean","example":true},"issues":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["path","code"],"properties":{"path":{"type":"string","example":"algorithm.routing_rules[0].match.source"},"code":{"type":"string","enum":["invalid_type","unknown_choice","unknown_key"],"example":"unknown_choice"}}}}},"example":{"valid":true,"issues":[]}},"units_count":{"type":"integer","minimum":0,"example":0},"members_count":{"type":"integer","minimum":0,"example":0},"capacity_total":{"type":"integer","minimum":0,"description":"Sum of current effective capacities across all units, including explicit unit overrides.","example":0},"occupancy_total":{"type":"integer","minimum":0,"description":"Sum of the synced member counts across all units.","example":0},"awaiting_count":{"type":"integer","minimum":0,"description":"Members still pending or queued or waitlisted.","example":0},"open_unit_sequence":{"type":["integer","null"],"example":null},"closes_at":{"type":["string","null"],"format":"date-time","description":"Configured distribution closing time; null means no closing time is set.","example":null},"archived_at":{"type":["string","null"],"format":"date-time","example":null},"created_at":{"type":"string","format":"date-time","example":"2026-10-13T22:00:00Z"},"updated_at":{"type":"string","format":"date-time","example":"2026-10-13T22:00:00Z"}}}},"meta":{"type":"object","additionalProperties":false,"required":["count"],"properties":{"count":{"type":"integer","minimum":0,"description":"Total matching distributions before pagination."},"current_page":{"type":"integer","minimum":1,"description":"Alias of effective page; present only in paginated mode.","example":1},"total_pages":{"type":"integer","minimum":0,"description":"Matching count divided by effective page size, rounded up; only in paginated mode.","example":1},"has_more":{"type":"boolean","description":"Whether current_page is below total_pages; only in paginated mode.","example":false},"page":{"type":"integer","minimum":1,"description":"Effective page after adjustment; present only when the request supplies page or per_page."},"per_page":{"type":"integer","minimum":1,"maximum":100,"description":"Effective page size after truncation; present only when the request supplies page or per_page."}}}}},"example":{"payload":[{"algorithm":"fill_first","opens_at":null,"fallback_distribution_id":null,"graduate_distribution_id":null,"advanced_enabled":false,"capacity_defaults":{"default":256,"maximum":1023,"effective_maximum":1023,"hard_cap":1024,"headroom":0},"community_member_limit":2000,"community_provisioning":{"state":"not_requested","error_code":null,"failed_at":null},"next_sequence":1,"effective_capacity":256,"throttle_defaults":{"second":1,"hour":240},"identity":{"mode":"sequence","items":[{"key":"4711","source":"upload","thumb_url":"https://app.example.test/rails/active_storage/representations/redirect/cover-1.jpg","available":true,"check":{"state":"ok","reason":null,"checked_at":"2026-10-14T01:00:00Z","overdue":false},"media_asset_id":44},{"key":"4712","source":"library","media_asset_id":44,"thumb_url":"","available":true,"check":{"state":"pending","reason":null,"checked_at":null,"overdue":false}}],"fallback":{"key":"4720","source":"url","thumb_url":"https://app.example.test/rails/active_storage/representations/redirect/default-cover.jpg","available":true,"check":{"state":"ok","reason":null,"checked_at":"2026-10-14T01:00:00Z","overdue":false},"media_asset_id":44},"limits":{"max_bytes":8388608,"max_side":4096,"max_items":100,"check_overdue_after_seconds":900,"content_types":["image/jpeg","image/png"]},"remaining_positions":2,"exhausts_at_sequence":2},"entry_trigger_catalog":[{"key":"payment_charge.paid","label_key":"growth.distribution.entry_triggers.events.payment_charge_paid.label","description_key":"growth.distribution.entry_triggers.events.payment_charge_paid.description","label":"Charge paid","description":"A confirmed or paid charge payment, admitted through the payment_charge.paid key."}],"entry_trigger_validation":{"valid":true,"invalid_type":false,"invalid_indexes":[]},"configuration_options":{"routing_sources":["link","automation","event","manual","api","follow_up"],"template_keys":["welcome","reminder","countdown","unit_opened","waitlist_ack","removed_notice","graduated_notice"]},"configuration_validation":{"valid":true,"issues":[{"path":"algorithm.routing_rules[0].match.source","code":"unknown_choice"}]},"setup_capabilities":{"join_approval":{"tier":"partial_contract","target_types":["group","community"]},"locked":{"tier":"live","target_types":["group","community"]},"member_add_mode":{"tier":"partial_contract","target_types":["group","community"]},"ephemeral":{"tier":"live","target_types":["group","community"]}},"setup_pause_defaults":{"default_seconds":3,"jitter_seconds":2,"max_seconds":60},"id":22,"account_id":1,"name":"October launch","slug":"october-launch","public_path":"/g/october-launch","inbox_id":6,"logical_inbox_id":15,"launch_id":null,"target_type":"group","join_mode":"invite_link","capacity_per_unit":256,"community_jid":null,"channel_jid":null,"naming_template":"Launch group {n}","welcome_message":null,"status":"draft","settings":{"locked":true,"ephemeral_seconds":86400,"setup_pause_seconds":3,"description":"Welcome to launch group {n}.","photo_url":"https://images.example.test/legacy-cover.jpg","identity":{"photo":{"mode":"sequence","items":[{"key":"4711","source":"upload","media_asset_id":44},{"key":"4712","source":"library","media_asset_id":44}],"fallback":{"key":"4720","source":"url","media_asset_id":44}}},"join_approval":null,"join_approval_policy":null,"member_add_mode":null},"units_count":0,"members_count":0,"capacity_total":0,"occupancy_total":0,"awaiting_count":0,"open_unit_sequence":null,"closes_at":null,"archived_at":null,"created_at":"2026-10-13T22:00:00Z","updated_at":"2026-10-13T22:00:00Z"}],"meta":{"count":1,"page":1,"per_page":25,"current_page":1,"total_pages":1,"has_more":false}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"400":{"description":"The non-blank requested status is outside the distribution status enum.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","enum":["invalid_status"]}}},"example":{"error":"invalid_status"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"status","in":"query","required":false,"description":"Restrict to distributions in one state. Omitted or blank means no status filter.","schema":{"type":"string","enum":["draft","active","paused","completed"]},"example":"active"},{"name":"archived","in":"query","required":false,"description":"True returns only archived distributions; false returns only non-archived distributions. Omitted or any other value returns both.","schema":{"type":"string","enum":["true","false"]},"example":"false"},{"name":"q","in":"query","required":false,"description":"Case-insensitive text matched anywhere in the distribution name or smart-link slug. Surrounding spaces are ignored, a blank value applies no filter, and % or _ are matched literally. Combines with status and archived.","schema":{"type":"string"},"example":"october"},{"name":"page","in":"query","required":false,"description":"Enables pagination when supplied. The effective page is at least one; omitted, non-numeric, zero or negative values use page one whenever pagination is enabled. Omit both page and per_page to return all matching distributions.","schema":{"type":"integer","minimum":1},"example":1},{"name":"per_page","in":"query","required":false,"description":"Enables pagination when supplied. Values above 100 are truncated to 100. Omitted, non-numeric, zero or negative values use the account page size (api.index_page_size, 25 as shipped; a zero or invalid account value also falls back to 25) when pagination is enabled. Omit both page and per_page to return all matching distributions.","schema":{"type":"integer","minimum":1,"maximum":100},"example":25}]},"post":{"tags":["Growth Distribution"],"operationId":"auto_post_api_v1_accounts_account_id_growth_distributions","summary":"Create a launch distribution","description":"Creates a draft configuration. Identity images are attached atomically with the distribution; files and links must first be uploaded through the existing account upload endpoint. No WhatsApp group is created by this action. Without identity, the legacy photo_url remains the photo source. Only this create operation adds settings.locked: true for group or community destinations when the locked key is omitted, including when settings is absent or null. Explicit locked true, false or null is preserved; null keeps WhatsApp's existing setting without applying this restriction. Channel destinations receive no injected locked key; non-null birth settings still require a live capability for the destination. Update and duplicate do not apply this creation default. The group request example omits locked and therefore saves locked as true. Entry triggers must be an array of selectable catalog keys; an empty array disables automatic entry. A payment_charge.confirmed emission is handled through payment_charge.paid and is not a selectable key. Omitted capacity_per_unit inherits the account per-unit default; an explicit value is retained.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Launch distribution with stored configuration and the current identity projection.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["payload"],"properties":{"payload":{"type":"object","additionalProperties":false,"required":["id","account_id","name","slug","public_path","inbox_id","launch_id","target_type","join_mode","capacity_per_unit","algorithm","opens_at","fallback_distribution_id","graduate_distribution_id","advanced_enabled","capacity_defaults","community_member_limit","community_provisioning","setup_capabilities","setup_pause_defaults","next_sequence","effective_capacity","throttle_defaults","identity","community_jid","channel_jid","naming_template","welcome_message","status","settings","entry_trigger_catalog","entry_trigger_validation","configuration_options","configuration_validation","units_count","members_count","open_unit_sequence","closes_at","archived_at","created_at","updated_at","slug_collision","slug_retired_from"],"properties":{"algorithm":{"type":"string","enum":["fill_first","round_robin","random","weighted"],"example":"fill_first"},"opens_at":{"type":["string","null"],"format":"date-time","description":"Distribution opening time, when configured.","example":null},"fallback_distribution_id":{"type":["integer","null"],"example":null},"graduate_distribution_id":{"type":["integer","null"],"example":null},"advanced_enabled":{"type":"boolean","description":"Whether advanced launch distribution features are enabled for this account.","example":false},"capacity_defaults":{"type":"object","additionalProperties":false,"required":["default","maximum","effective_maximum","hard_cap","headroom"],"description":"Resolved capacity limits. On defaults, default is the account per-unit setting; on distribution resources it is the product default of 256. Effective maximum is min(1023, hard_cap minus headroom). An existing explicit per-unit setting is preserved when the account defaults change.","properties":{"default":{"type":"integer","minimum":1,"maximum":1023,"example":256},"maximum":{"type":"integer","description":"Maximum accepted capacity per launch group.","example":1023},"effective_maximum":{"type":"integer","minimum":0,"maximum":1023,"description":"Maximum after applying the resolved hard cap and explicit headroom.","example":1023},"hard_cap":{"type":"integer","minimum":1,"maximum":1024,"description":"Hard cap resolved from the account and distribution settings.","example":1024},"headroom":{"type":"integer","minimum":0,"maximum":1023,"description":"Explicit seat margin; absent overrides use the product margin of zero.","example":0}}},"community_member_limit":{"type":"integer","example":2000},"community_provisioning":{"type":"object","additionalProperties":false,"required":["state","error_code","failed_at"],"properties":{"state":{"type":"string","enum":["not_requested","pending","created","failed"],"example":"not_requested","description":"Distribution member progress state."},"error_code":{"type":["string","null"],"enum":["missing_initial_participant","outcome_uncertain","feature_not_supported","gateway_rejected","gateway_unavailable","rate_limited","setup_step_failed","setup_step_refused","setup_incomplete","creator_inbox_unavailable","group_not_admin","group_not_found",null],"example":null},"failed_at":{"type":["string","null"],"format":"date-time","example":null}}},"next_sequence":{"type":"integer","minimum":1,"example":1},"effective_capacity":{"type":"integer","minimum":0,"maximum":1023,"description":"Minimum of the configured per-unit capacity and the effective maximum after the resolved hard cap and headroom.","example":256},"throttle_defaults":{"type":"object","additionalProperties":false,"required":["second","hour"],"description":"Default outbound limits for WhatsApp Web; operator overrides are kept in settings.","properties":{"second":{"type":"integer","example":1},"hour":{"type":"integer","example":240}}},"identity":{"type":"object","additionalProperties":false,"required":["mode","items","fallback","remaining_positions","exhausts_at_sequence","limits"],"properties":{"mode":{"type":"string","enum":["none","single","sequence"],"example":"sequence"},"items":{"type":"array","maxItems":100,"items":{"type":"object","additionalProperties":false,"required":["key","source","thumb_url","available","check"],"properties":{"key":{"type":"string","minLength":1,"example":"4711"},"source":{"type":"string","enum":["upload","library","url"],"example":"upload"},"media_asset_id":{"type":"integer","minimum":1,"example":44},"thumb_url":{"type":"string","description":"Center-cropped 160 by 160 representation URL, present only after the full image check succeeded; empty while the check is pending or invalid, when the file is unavailable, or when the representation fails.","example":""},"available":{"type":"boolean","description":"Whether the blob is still attached to this distribution.","example":true},"check":{"type":"object","additionalProperties":false,"required":["state","reason","checked_at","overdue"],"properties":{"state":{"type":"string","enum":["pending","ok","invalid"],"example":"pending","description":"Distribution member progress state."},"reason":{"type":["string","null"],"enum":["type","size","dimensions","unreadable","unavailable",null],"example":null},"checked_at":{"type":["string","null"],"format":"date-time","example":null},"overdue":{"type":"boolean","description":"Pending without a check time for at least 15 minutes since attachment creation; false without the check column or attachment.","example":false}}}}}},"fallback":{"oneOf":[{"type":"object","additionalProperties":false,"required":["key","source","thumb_url","available","check"],"properties":{"key":{"type":"string","minLength":1,"example":"4711"},"source":{"type":"string","enum":["upload","library","url"],"example":"upload"},"media_asset_id":{"type":"integer","minimum":1,"example":44},"thumb_url":{"type":"string","description":"Center-cropped 160 by 160 representation URL, present only after the full image check succeeded; empty while the check is pending or invalid, when the file is unavailable, or when the representation fails.","example":""},"available":{"type":"boolean","description":"Whether the blob is still attached to this distribution.","example":true},"check":{"type":"object","additionalProperties":false,"required":["state","reason","checked_at","overdue"],"properties":{"state":{"type":"string","enum":["pending","ok","invalid"],"example":"pending","description":"Distribution member progress state."},"reason":{"type":["string","null"],"enum":["type","size","dimensions","unreadable","unavailable",null],"example":null},"checked_at":{"type":["string","null"],"format":"date-time","example":null},"overdue":{"type":"boolean","description":"Pending without a check time for at least 15 minutes since attachment creation; false without the check column or attachment.","example":false}}}}},{"type":"null"}]},"limits":{"type":"object","additionalProperties":false,"required":["max_bytes","max_side","max_items","content_types","check_overdue_after_seconds"],"properties":{"max_bytes":{"type":"integer","example":8388608},"max_side":{"type":"integer","example":4096},"max_items":{"type":"integer","example":100},"check_overdue_after_seconds":{"type":"integer","example":900},"content_types":{"type":"array","items":{"type":"string","enum":["image/jpeg","image/png"]},"example":["image/jpeg","image/png"]}}},"remaining_positions":{"type":["integer","null"],"minimum":0,"description":"Remaining own-image positions from next_sequence; null outside sequence mode.","example":2},"exhausts_at_sequence":{"type":["integer","null"],"minimum":0,"description":"Number of own-image positions; null outside sequence mode.","example":2}}},"setup_capabilities":{"type":"object","description":"Birth-setting support by step. Only live capabilities support the listed destination types; partial_contract is unavailable.","additionalProperties":{"type":"object","additionalProperties":false,"required":["tier","target_types"],"properties":{"tier":{"type":"string","enum":["live","partial_contract"]},"target_types":{"type":"array","items":{"type":"string","enum":["group","community"]}}}},"example":{"join_approval":{"tier":"partial_contract","target_types":["group","community"]},"locked":{"tier":"live","target_types":["group","community"]},"member_add_mode":{"tier":"partial_contract","target_types":["group","community"]},"ephemeral":{"tier":"live","target_types":["group","community"]}}},"setup_pause_defaults":{"type":"object","additionalProperties":false,"required":["default_seconds","jitter_seconds","max_seconds"],"description":"Server defaults and operator bounds for setup pacing. Jitter is added only to positive pauses.","properties":{"default_seconds":{"type":"integer","minimum":0,"description":"Base pause inherited when no override is set.","example":3},"jitter_seconds":{"type":"integer","minimum":0,"description":"Maximum random delay added to a positive base pause.","example":2},"max_seconds":{"type":"integer","minimum":0,"description":"Maximum configurable base pause before jitter.","example":60}},"example":{"default_seconds":3,"jitter_seconds":2,"max_seconds":60}},"id":{"type":"integer","example":22},"account_id":{"type":"integer","example":1},"name":{"type":"string","example":"October launch"},"slug":{"type":"string","example":"october-launch"},"public_path":{"type":"string","example":"/g/october-launch"},"inbox_id":{"type":"integer","example":6},"logical_inbox_id":{"type":"integer","description":"Present when the visible logical inbox differs from the transport inbox.","example":15},"launch_id":{"type":["integer","null"],"example":null},"target_type":{"type":"string","enum":["community","group","channel"],"example":"group"},"join_mode":{"type":"string","enum":["invite_link","direct_add","both"],"example":"invite_link"},"capacity_per_unit":{"type":"integer","minimum":1,"maximum":1023,"example":256},"community_jid":{"type":["string","null"],"example":null},"channel_jid":{"type":["string","null"],"example":null},"naming_template":{"type":"string","example":"Launch group {n}"},"welcome_message":{"type":["string","null"],"example":null},"status":{"type":"string","enum":["draft","active","paused","completed"],"example":"draft"},"settings":{"type":"object","additionalProperties":true,"description":"Operator configuration excluding system-owned diagnostics; other configuration keys are preserved.","properties":{"join_approval":{"type":["boolean","null"],"enum":[true,false,null],"description":"Require administrator approval to join. Null inherits WhatsApp. New or changed non-null values require a live capability tier for the destination. An unchanged saved value is accepted on update when the destination stays the same.","example":null},"join_approval_policy":{"type":["string","null"],"enum":["manual","all_while_seats",null],"description":"Null defaults effectively to all_while_seats when join_approval is true. A new or changed non-null policy requires a live join_approval capability tier for the destination. An unchanged saved policy is accepted on update when the destination stays the same. Manual only counts pending requests.","example":null},"locked":{"type":["boolean","null"],"enum":[true,false,null],"description":"Restrict group information edits to administrators. Explicit null keeps WhatsApp's existing setting. Omission follows the rules described for each operation.","example":true},"member_add_mode":{"type":["string","null"],"enum":["admin_add","all_member_add",null],"description":"Who may add members. Null inherits WhatsApp. New or changed non-null values require a live capability tier for the destination. An unchanged saved value is accepted on update when the destination stays the same.","example":null},"ephemeral_seconds":{"type":["integer","null"],"enum":[0,86400,604800,7776000,null],"description":"Disappearing-message duration in seconds; zero disables the timer and null inherits WhatsApp.","example":86400},"setup_pause_seconds":{"type":["integer","null"],"minimum":0,"maximum":60,"default":3,"description":"Base delay between setup delegations, plus zero to two seconds of jitter. Zero disables pauses; null uses three seconds.","example":3},"identity":{"type":"object","additionalProperties":false,"required":["photo"],"properties":{"photo":{"type":"object","additionalProperties":false,"required":["mode","items","fallback"],"properties":{"mode":{"type":"string","enum":["none","single","sequence"],"example":"sequence"},"items":{"type":"array","maxItems":100,"description":"Ordered blob references. Single requires one item; none requires an empty list.","items":{"type":"object","additionalProperties":false,"required":["key","source"],"properties":{"key":{"type":"string","minLength":1,"description":"Blob id attached to this distribution.","example":"4711"},"source":{"type":"string","enum":["upload","library","url"],"example":"upload"},"media_asset_id":{"type":"integer","minimum":1,"description":"Original Library asset, when selected from the Library.","example":44}}}},"fallback":{"description":"Image used after the sequence ends or when a selected image is unavailable.","oneOf":[{"type":"object","additionalProperties":false,"required":["key","source"],"properties":{"key":{"type":"string","minLength":1,"description":"Blob id attached to this distribution.","example":"4711"},"source":{"type":"string","enum":["upload","library","url"],"example":"upload"},"media_asset_id":{"type":"integer","minimum":1,"description":"Original Library asset, when selected from the Library.","example":44}}},{"type":"null"}]}}}}},"photo_url":{"type":["string","null"],"description":"Inherited group photo link. An explicit unit photo overrides the distribution identity; without a unit override the distribution identity wins, then the inherited URL. HTTP is accepted only for an authorized image blob of this account on the canonical application origin, with a valid signed blob URL and no credentials, query or fragment. External URLs require HTTPS.","example":"https://images.example.test/legacy-cover.jpg"},"description":{"type":["string","null"],"description":"Group description; each occurrence of {n} is replaced with the unit sequence.","example":"Welcome to launch group {n}."}}},"entry_trigger_catalog":{"type":"array","description":"Complete list of selectable entry keys, shared with server validation. Text is localized for the request. Translation keys belong to the server translation catalog. Availability of a key does not guarantee an event producer, an eligible contact or an enrollment effect.","items":{"type":"object","additionalProperties":false,"required":["key","label_key","description_key","label","description"],"properties":{"key":{"type":"string","description":"A selectable launch distribution entry key backed by an enrollment consumer. Payment confirmed emissions use payment_charge.paid.","enum":["payment_charge.paid","payment_charge.overdue","crm_item.stage_changed","crm_item.stale","crm_item.won","task.overdue","task.due_soon","calendar_event.created","calendar_event.no_show","commerce.cart_abandoned","commerce.order_placed","commerce.payment_pending","commerce.payment_confirmed","commerce.payment_declined","commerce.overdue","commerce.due_soon","commerce.refunded","commerce.chargeback","commerce.subscription_late","commerce.subscription_canceled","ads.lead_captured","social.comment_captured"],"example":"payment_charge.paid"},"label_key":{"type":"string","description":"Server translation key for the label.","example":"growth.distribution.entry_triggers.events.payment_charge_paid.label"},"description_key":{"type":"string","description":"Server translation key for the description.","example":"growth.distribution.entry_triggers.events.payment_charge_paid.description"},"label":{"type":"string","description":"Localized label.","example":"Charge paid"},"description":{"type":"string","description":"Localized explanation of the entry signal.","example":"A confirmed or paid charge payment, admitted through the payment_charge.paid key."}}},"example":[{"key":"payment_charge.paid","label_key":"growth.distribution.entry_triggers.events.payment_charge_paid.label","description_key":"growth.distribution.entry_triggers.events.payment_charge_paid.description","label":"Charge paid","description":"A confirmed or paid charge payment, admitted through the payment_charge.paid key."}]},"entry_trigger_validation":{"type":"object","additionalProperties":false,"required":["valid","invalid_type","invalid_indexes"],"description":"Advisory validation of the stored entry list, without changing it. Read invalid values from settings.entry_triggers at the reported positions. A malformed non-array value has invalid_type true and no positions. An absent list is valid and equivalent to an empty list.","properties":{"valid":{"type":"boolean","example":false},"invalid_type":{"type":"boolean","example":false},"invalid_indexes":{"type":"array","description":"Zero-based positions of unknown keys or elements that are not strings.","items":{"type":"integer","minimum":0},"example":[0]}},"example":{"valid":false,"invalid_type":false,"invalid_indexes":[0]}},"configuration_options":{"type":"object","additionalProperties":false,"required":["routing_sources","template_keys"],"description":"Recognized routing sources and stored template identifiers from the same server sets used by validation. Template membership does not imply a send: the join-template and overdue-warning selectors currently have no operational send consumer and must be presented as unavailable.","properties":{"routing_sources":{"type":"array","items":{"type":"string","enum":["link","automation","event","manual","api","follow_up"]}},"template_keys":{"type":"array","items":{"type":"string","enum":["welcome","reminder","countdown","unit_opened","waitlist_ack","removed_notice","graduated_notice"]}}},"example":{"routing_sources":["link","automation","event","manual","api","follow_up"],"template_keys":["welcome","reminder","countdown","unit_opened","waitlist_ack","removed_notice","graduated_notice"]}},"configuration_validation":{"type":"object","additionalProperties":false,"required":["valid","issues"],"description":"Diagnostics for saved and resolved choices without removing or rewriting them. Paths are relative to the settings document; inherited values also remain available in settings explanations.","properties":{"valid":{"type":"boolean","example":true},"issues":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["path","code"],"properties":{"path":{"type":"string","example":"algorithm.routing_rules[0].match.source"},"code":{"type":"string","enum":["invalid_type","unknown_choice","unknown_key"],"example":"unknown_choice"}}}}},"example":{"valid":true,"issues":[]}},"units_count":{"type":"integer","minimum":0,"example":0},"members_count":{"type":"integer","minimum":0,"example":0},"capacity_total":{"type":"integer","minimum":0,"description":"Sum of current effective capacities across all units, including explicit unit overrides.","example":0},"occupancy_total":{"type":"integer","minimum":0,"description":"Sum of the synced member count of every unit.","example":0},"awaiting_count":{"type":"integer","minimum":0,"description":"Members still pending, queued or waitlisted.","example":0},"open_unit_sequence":{"type":["integer","null"],"example":null},"closes_at":{"type":["string","null"],"format":"date-time","description":"Configured distribution closing time; null means no closing time is set.","example":null},"archived_at":{"type":["string","null"],"format":"date-time","example":null},"created_at":{"type":"string","format":"date-time","example":"2026-10-13T22:00:00Z"},"updated_at":{"type":"string","format":"date-time","example":"2026-10-13T22:00:00Z"},"slug_collision":{"type":"boolean","description":"Whether the current public slug is shared with another distribution.","example":false},"slug_retired_from":{"type":["string","null"],"description":"Former public slug retired after a collision, or null.","example":null}}}}},"example":{"payload":{"algorithm":"fill_first","opens_at":null,"fallback_distribution_id":null,"graduate_distribution_id":null,"advanced_enabled":false,"capacity_defaults":{"default":256,"maximum":1023,"effective_maximum":1023,"hard_cap":1024,"headroom":0},"community_member_limit":2000,"community_provisioning":{"state":"not_requested","error_code":null,"failed_at":null},"next_sequence":1,"effective_capacity":256,"throttle_defaults":{"second":1,"hour":240},"identity":{"mode":"sequence","items":[{"key":"4711","source":"upload","thumb_url":"https://app.example.test/rails/active_storage/representations/redirect/cover-1.jpg","available":true,"check":{"state":"ok","reason":null,"checked_at":"2026-10-14T01:00:00Z","overdue":false},"media_asset_id":44},{"key":"4712","source":"library","media_asset_id":44,"thumb_url":"","available":true,"check":{"state":"pending","reason":null,"checked_at":null,"overdue":false}}],"fallback":{"key":"4720","source":"url","thumb_url":"https://app.example.test/rails/active_storage/representations/redirect/default-cover.jpg","available":true,"check":{"state":"ok","reason":null,"checked_at":"2026-10-14T01:00:00Z","overdue":false},"media_asset_id":44},"limits":{"max_bytes":8388608,"max_side":4096,"max_items":100,"check_overdue_after_seconds":900,"content_types":["image/jpeg","image/png"]},"remaining_positions":2,"exhausts_at_sequence":2},"entry_trigger_catalog":[{"key":"payment_charge.paid","label_key":"growth.distribution.entry_triggers.events.payment_charge_paid.label","description_key":"growth.distribution.entry_triggers.events.payment_charge_paid.description","label":"Charge paid","description":"A confirmed or paid charge payment, admitted through the payment_charge.paid key."}],"entry_trigger_validation":{"valid":true,"invalid_type":false,"invalid_indexes":[]},"configuration_options":{"routing_sources":["link","automation","event","manual","api","follow_up"],"template_keys":["welcome","reminder","countdown","unit_opened","waitlist_ack","removed_notice","graduated_notice"]},"configuration_validation":{"valid":true,"issues":[{"path":"algorithm.routing_rules[0].match.source","code":"unknown_choice"}]},"setup_capabilities":{"join_approval":{"tier":"partial_contract","target_types":["group","community"]},"locked":{"tier":"live","target_types":["group","community"]},"member_add_mode":{"tier":"partial_contract","target_types":["group","community"]},"ephemeral":{"tier":"live","target_types":["group","community"]}},"setup_pause_defaults":{"default_seconds":3,"jitter_seconds":2,"max_seconds":60},"id":22,"account_id":1,"name":"October launch","slug":"october-launch","public_path":"/g/october-launch","inbox_id":6,"logical_inbox_id":15,"launch_id":null,"target_type":"group","join_mode":"invite_link","capacity_per_unit":256,"community_jid":null,"channel_jid":null,"naming_template":"Launch group {n}","welcome_message":null,"status":"draft","settings":{"locked":true,"ephemeral_seconds":86400,"setup_pause_seconds":3,"description":"Welcome to launch group {n}.","photo_url":"https://images.example.test/legacy-cover.jpg","identity":{"photo":{"mode":"sequence","items":[{"key":"4711","source":"upload","media_asset_id":44},{"key":"4712","source":"library","media_asset_id":44}],"fallback":{"key":"4720","source":"url","media_asset_id":44}}},"join_approval":null,"join_approval_policy":null,"member_add_mode":null},"units_count":0,"members_count":0,"capacity_total":0,"occupancy_total":0,"awaiting_count":0,"open_unit_sequence":null,"closes_at":null,"archived_at":null,"created_at":"2026-10-13T22:00:00Z","updated_at":"2026-10-13T22:00:00Z","slug_collision":false,"slug_retired_from":null}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"422":{"description":"Invalid identity or distribution configuration; nothing is saved.","content":{"application/json":{"schema":{"oneOf":[{"type":"object","additionalProperties":false,"required":["error","keys","message","entry_trigger_validation"],"properties":{"error":{"type":"string","enum":["invalid_entry_triggers"],"example":"invalid_entry_triggers"},"keys":{"type":"array","items":{"type":"string","enum":["settings.entry_triggers"]},"example":["settings.entry_triggers"]},"message":{"type":"string","description":"Localized correction instructions.","example":"Choose entry triggers from the available list. Correct or remove unknown keys before changing that list."},"entry_trigger_validation":{"type":"object","additionalProperties":false,"required":["valid","invalid_type","invalid_indexes"],"description":"Advisory validation of the stored entry list, without changing it. Read invalid values from settings.entry_triggers at the reported positions. A malformed non-array value has invalid_type true and no positions. An absent list is valid and equivalent to an empty list.","properties":{"valid":{"type":"boolean","example":false},"invalid_type":{"type":"boolean","example":false},"invalid_indexes":{"type":"array","description":"Zero-based positions of unknown keys or elements that are not strings.","items":{"type":"integer","minimum":0},"example":[0]}},"example":{"valid":false,"invalid_type":false,"invalid_indexes":[0]}}},"example":{"error":"invalid_entry_triggers","keys":["settings.entry_triggers"],"message":"Choose entry triggers from the available list. Correct or remove unknown keys before changing that list.","entry_trigger_validation":{"valid":false,"invalid_type":false,"invalid_indexes":[0]}}},{"type":"object","additionalProperties":false,"required":["error","keys","message","configuration_validation"],"properties":{"error":{"type":"string","enum":["invalid_configuration_choices"],"example":"invalid_configuration_choices"},"keys":{"type":"array","items":{"type":"string","enum":["algorithm.routing_rules","dm_on_join.template","post_purchase.on_overdue.warn_template"]},"example":["dm_on_join.template"]},"message":{"type":"string","example":"Choose a source or template from the available list. Correct or remove unknown values before changing these fields."},"configuration_validation":{"type":"object","additionalProperties":false,"required":["valid","issues"],"description":"Diagnostics for saved and resolved choices without removing or rewriting them. Paths are relative to the settings document; inherited values also remain available in settings explanations.","properties":{"valid":{"type":"boolean","example":true},"issues":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["path","code"],"properties":{"path":{"type":"string","example":"algorithm.routing_rules[0].match.source"},"code":{"type":"string","enum":["invalid_type","unknown_choice","unknown_key"],"example":"unknown_choice"}}}}},"example":{"valid":true,"issues":[]}}}},{"type":"object","additionalProperties":false,"required":["error","setting","message"],"properties":{"error":{"type":"string","enum":["setup_capability_unavailable"],"example":"setup_capability_unavailable"},"setting":{"type":"string","enum":["join_approval","locked","member_add_mode","ephemeral_seconds"],"example":"join_approval"},"message":{"type":"string","example":"This setting cannot be used on this distribution yet."}}},{"type":"object","additionalProperties":false,"required":["error","message"],"properties":{"error":{"type":"string","enum":["identity_invalid"],"example":"identity_invalid"},"message":{"type":"string","example":"The launch group image configuration is invalid. Review the mode and selected items."}}},{"type":"object","additionalProperties":false,"required":["error","message","items"],"properties":{"error":{"type":"string","enum":["identity_image_invalid"],"example":"identity_image_invalid"},"message":{"type":"string","example":"One or more launch group images are invalid or unavailable. Review the indicated items."},"items":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["index","reason","message"],"properties":{"index":{"description":"Zero-based item position, or fallback for the fallback image.","oneOf":[{"type":"integer","minimum":0},{"type":"string","enum":["fallback"]}],"example":1},"reason":{"type":"string","enum":["type","size","dimensions","unreadable","unavailable"],"example":"size"},"message":{"type":"string","description":"Localized explanation with the applicable limit.","example":"The image must be no larger than 8 MB."}}}}}},{"type":"object","additionalProperties":false,"required":["error","keys"],"properties":{"error":{"type":"string","enum":["invalid_settings"],"example":"invalid_settings"},"keys":{"type":"array","description":"Rejected section or section.key paths of settings_overrides, in submission order without duplicates.","items":{"type":"string"},"example":["sellers.strategy"]}}},{"type":"object","additionalProperties":false,"required":["message","attributes"],"properties":{"message":{"type":"string","example":"Name cannot be blank"},"attributes":{"type":"array","description":"Distribution attributes rejected by model validation.","items":{"type":"string"},"example":["name"]}}},{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","description":"Framework message for an invalid enum value or other invalid request parameter.","example":"'unsupported' is not a valid target_type"}}}]},"examples":{"invalid_configuration_choices":{"value":{"error":"invalid_configuration_choices","keys":["dm_on_join.template"],"message":"Choose a source or template from the available list. Correct or remove unknown values before changing these fields.","configuration_validation":{"valid":false,"issues":[{"path":"dm_on_join.template","code":"unknown_choice"}]}}},"invalid_entry_triggers":{"value":{"error":"invalid_entry_triggers","keys":["settings.entry_triggers"],"message":"Choose entry triggers from the available list. Correct or remove unknown keys before changing that list.","entry_trigger_validation":{"valid":false,"invalid_type":false,"invalid_indexes":[0]}}},"setup_capability":{"value":{"error":"setup_capability_unavailable","setting":"join_approval","message":"This setting cannot be used on this distribution yet."}},"structure":{"value":{"error":"identity_invalid","message":"The launch group image configuration is invalid. Review the mode and selected items.","keys":["settings.entry_triggers"],"entry_trigger_validation":{"valid":false,"invalid_type":false,"invalid_indexes":[0]}}},"image":{"value":{"error":"identity_image_invalid","message":"One or more launch group images are invalid or unavailable. Review the indicated items.","items":[{"index":1,"reason":"size","message":"The image must be no larger than 8 MB."},{"index":"fallback","reason":"unavailable","message":"The image is unavailable. Upload another image."}]}},"invalid_settings":{"value":{"error":"invalid_settings","keys":["sellers.strategy"],"message":"Choose entry triggers from the available list. Correct or remove unknown keys before changing that list.","entry_trigger_validation":{"valid":false,"invalid_type":false,"invalid_indexes":[0]}}},"model_validation":{"value":{"message":"Name cannot be blank","attributes":["name"]}},"enum_validation":{"value":{"error":"'unsupported' is not a valid target_type","keys":["settings.entry_triggers"],"message":"Choose entry triggers from the available list. Correct or remove unknown keys before changing that list.","entry_trigger_validation":{"valid":false,"invalid_type":false,"invalid_indexes":[0]}}}}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["name","inbox_id"],"properties":{"name":{"type":"string","example":"October launch"},"slug":{"type":"string","example":"october-launch"},"inbox_id":{"type":"integer","example":15},"launch_id":{"type":["integer","null"],"example":null},"target_type":{"type":"string","enum":["community","group","channel"],"example":"group"},"join_mode":{"type":"string","enum":["invite_link","direct_add","both"],"example":"invite_link"},"capacity_per_unit":{"type":"integer","minimum":1,"maximum":1023,"example":256},"algorithm":{"type":"string","enum":["fill_first","round_robin","random","weighted"],"description":"Distribution placement strategy.","example":"fill_first"},"opens_at":{"type":["string","null"],"format":"date-time","description":"Opening time persisted by create and update; when both are set, closes_at must be later.","example":null},"closes_at":{"type":["string","null"],"format":"date-time","description":"Closing time persisted by create and update.","example":null},"fallback_distribution_id":{"type":["integer","null"],"minimum":1,"description":"Another active, unarchived distribution of the same account used as fallback; null clears it.","example":null},"graduate_distribution_id":{"type":["integer","null"],"minimum":1,"description":"Another active, unarchived distribution of the same account that receives graduated members; null clears it.","example":null},"settings_overrides":{"type":"object","additionalProperties":false,"description":"Canonical distribution overrides, validated and written like the distribution settings document in the same transaction as the save. Null removes an override so the key inherits again; one invalid key refuses the whole save with invalid_settings.","properties":{"capacity":{"type":"object","additionalProperties":false,"properties":{"hard_cap":{"type":["integer","null"],"minimum":1,"maximum":1024},"headroom":{"type":["integer","null"],"minimum":0,"maximum":1023,"description":"Seat margin below hard_cap; the resolved margin must remain smaller than the resolved hard cap. Null inherits."},"per_unit":{"type":["integer","null"],"minimum":1,"maximum":1023},"by_inbox":{"type":["object","null"],"additionalProperties":false},"reserve_for_waitlist":{"type":["integer","null"],"minimum":0}}},"algorithm":{"type":"object","additionalProperties":false,"properties":{"strategy":{"type":["string","null"],"enum":["fill_first","round_robin","random","weighted",null]},"weight":{"type":["integer","null"],"minimum":0},"sticky_by_contact":{"type":["boolean","null"],"enum":[true,false,null]},"routing_rules":{"type":["array","null"],"description":"Ordered rules, evaluated with equality and all conditions together. New or changed lists must use recognized condition keys and member sources; an identical legacy list may remain during an unrelated update. Null removes the override. UTM values and account labels are open values.","items":{"type":"object","required":["match"],"properties":{"match":{"type":"object","additionalProperties":false,"properties":{"utm_source":{"type":"string","description":"Compared with lead attribution, ignoring case and surrounding spaces."},"utm_campaign":{"type":"string","description":"Compared with lead attribution, ignoring case and surrounding spaces."},"tag":{"type":"string","description":"Literal label from the account label catalog."},"source":{"type":"string","enum":["link","automation","event","manual","api","follow_up"],"description":"Member entry source; null and empty values are not choices."}}},"distribution_id":{"type":"integer","minimum":1,"description":"Target distribution; skipped unless it is active and not archived in the same account."}}}}}},"rotation":{"type":"object","additionalProperties":false,"properties":{"batch_size":{"type":["integer","null"],"minimum":0},"warmup_ramp":{"type":["array","null"],"description":"Rotation batch steps; the latest step whose after_minutes has elapsed since creation sets the batch size.","items":{"type":"object","properties":{"after_minutes":{"type":"integer","minimum":0,"description":"Minutes after the distribution was created when the step starts."},"batch":{"type":"integer","minimum":1,"description":"Rotation batch size while the step applies; a missing or zero batch keeps the flat batch_size."}}}},"defer_base_seconds":{"type":["integer","null"],"minimum":0},"max_backoff_shift":{"type":["integer","null"],"minimum":0},"max_defer_attempts":{"type":["integer","null"],"minimum":0},"throttle":{"type":["object","null"],"additionalProperties":false,"properties":{"second":{"type":["integer","null"],"minimum":0},"hour":{"type":["integer","null"],"minimum":0}}},"sync_interval_minutes":{"type":["integer","null"],"minimum":0},"scheduler_batch_size":{"type":["integer","null"],"minimum":0}}},"fallback":{"type":"object","additionalProperties":false,"properties":{"mode":{"type":["string","null"],"enum":["url","distribution","message","waitlist",null]},"url":{"type":["string","null"],"format":"uri"},"message":{"type":["string","null"]},"distribution_id":{"type":["integer","null"],"minimum":0},"waitlist_max":{"type":["integer","null"],"minimum":0},"waitlist_ttl_hours":{"type":["integer","null"],"minimum":0},"waitlist_drain_batch":{"type":["integer","null"],"minimum":0}}},"schedule":{"type":"object","additionalProperties":false,"properties":{"opens_at":{"type":["string","null"],"format":"date-time"},"closes_at":{"type":["string","null"],"format":"date-time"},"cascade_minutes":{"type":["integer","null"],"minimum":0},"announce_when_closed":{"type":["boolean","null"],"enum":[true,false,null]},"lock_when_closed":{"type":["boolean","null"],"enum":[true,false,null]},"warmup_window_minutes":{"type":["integer","null"],"minimum":0},"timezone":{"type":"string","description":"IANA timezone identifier (e.g. \"America/Sao_Paulo\", \"UTC\"). Rails timezone names are also accepted on input; an unrecognized value is ignored in favor of the next fallback.","example":"America/Sao_Paulo"}}},"reentry":{"type":"object","additionalProperties":false,"properties":{"allow_reentry":{"type":["boolean","null"],"enum":[true,false,null]},"cooldown_hours":{"type":["integer","null"],"minimum":0},"dedupe_across_units":{"type":["boolean","null"],"enum":[true,false,null]},"use_hub_blocklist":{"type":["boolean","null"],"enum":[true,false,null]},"blacklist":{"type":["array","null"],"description":"Phone numbers refused on entry; non-digit characters are ignored.","items":{"type":["string","integer"]}},"whitelist":{"type":["array","null"],"description":"Phone numbers allowed on entry; non-digit characters are ignored.","items":{"type":["string","integer"]}},"reopen_on_leave":{"type":["boolean","null"],"enum":[true,false,null]}}},"post_purchase":{"type":"object","additionalProperties":false,"properties":{"on_paid":{"type":["object","null"],"additionalProperties":false,"properties":{"remove":{"type":["boolean","null"],"enum":[true,false,null]},"move_to_distribution_id":{"type":["integer","null"],"minimum":0},"delay_minutes":{"type":["integer","null"],"minimum":0}}},"on_overdue":{"type":["object","null"],"additionalProperties":false,"properties":{"remove":{"type":["boolean","null"],"enum":[true,false,null]},"after_days":{"type":["integer","null"],"minimum":0},"warn_template":{"type":["string","null"],"enum":["welcome","reminder","countdown","unit_opened","waitlist_ack","removed_notice","graduated_notice",null],"description":"Recognized stored template identifier. Null removes the override; an empty string is invalid. An unchanged legacy identifier may be retained on an unrelated update. This selector currently has no operational send consumer; accepting an identifier does not schedule or send a message."}}},"on_refund":{"type":["object","null"],"additionalProperties":false,"properties":{"remove":{"type":["boolean","null"],"enum":[true,false,null]}}},"on_chargeback":{"type":["object","null"],"additionalProperties":false,"properties":{"remove":{"type":["boolean","null"],"enum":[true,false,null]}}},"remove_batch_size":{"type":["integer","null"],"minimum":0},"remove_throttle":{"type":["object","null"],"additionalProperties":false,"properties":{"second":{"type":["integer","null"],"minimum":0},"hour":{"type":["integer","null"],"minimum":0}}}}},"sellers":{"type":"object","additionalProperties":false,"properties":{"strategy":{"type":["string","null"],"enum":["round_robin","random","weighted",null]},"list":{"type":["array","null"],"description":"Sellers rotated 1:1; each entry is read with exactly these fields.","items":{"type":"object","properties":{"phone":{"type":"string","pattern":"^[0-9]{8,15}$","description":"Seller WhatsApp number, digits only."},"name":{"type":"string","minLength":1},"weight":{"type":"integer","minimum":1},"paused":{"type":"boolean"},"user_id":{"type":["integer","null"],"description":"Agent of this account linked to the seller."},"inbox_id":{"type":["integer","null"],"description":"WhatsApp inbox of this account used for the seller."}}}},"prefill_template":{"type":["string","null"]},"daily_cap_per_seller":{"type":["integer","null"],"minimum":0},"pause_when_offline":{"type":["boolean","null"],"enum":[true,false,null]}}},"dm_on_join":{"type":"object","additionalProperties":false,"properties":{"enabled":{"type":["boolean","null"],"enum":[true,false,null]},"template":{"type":["string","null"],"enum":["welcome","reminder","countdown","unit_opened","waitlist_ack","removed_notice","graduated_notice",null],"description":"Recognized stored template identifier. Null removes the override; an empty string is invalid. An unchanged legacy identifier may be retained on an unrelated update. This selector currently has no operational send consumer; accepting an identifier does not schedule or send a message."},"spintax":{"type":["array","null"],"description":"Message variants; one is picked at random per send and blank entries are dropped.","items":{"type":"string"}},"delay_seconds":{"type":["object","null"],"additionalProperties":false,"properties":{"min":{"type":["integer","null"],"minimum":0},"max":{"type":["integer","null"],"minimum":0}}},"per_hour_limit":{"type":["integer","null"],"minimum":0},"inbox_id":{"type":["integer","null"],"minimum":0},"fallback_inbox_id":{"type":["integer","null"],"minimum":0},"mode":{"type":["string","null"],"enum":["fixed","generative",null]},"brief":{"type":["string","null"]},"skip_if_conversation_open":{"type":["boolean","null"],"enum":[true,false,null]}}},"templates":{"type":"object","additionalProperties":false,"properties":{"welcome":{"type":["object","null"],"additionalProperties":false,"properties":{"text":{"type":["string","null"]},"spintax":{"type":["array","null"],"description":"Message variants; one is picked at random per send and blank entries are dropped.","items":{"type":"string"}},"media_url":{"type":["string","null"],"format":"uri"}}},"reminder":{"type":["object","null"],"additionalProperties":false,"properties":{"i18n_key":{"type":["string","null"]},"text":{"type":["string","null"]},"spintax":{"type":["array","null"],"description":"Message variants; one is picked at random per send and blank entries are dropped.","items":{"type":"string"}},"media_url":{"type":["string","null"],"format":"uri"}}},"countdown":{"type":["object","null"],"additionalProperties":false,"properties":{"i18n_key":{"type":["string","null"]},"text":{"type":["string","null"]},"spintax":{"type":["array","null"],"description":"Message variants; one is picked at random per send and blank entries are dropped.","items":{"type":"string"}},"media_url":{"type":["string","null"],"format":"uri"}}},"unit_opened":{"type":["object","null"],"additionalProperties":false,"properties":{"i18n_key":{"type":["string","null"]},"text":{"type":["string","null"]},"spintax":{"type":["array","null"],"description":"Message variants; one is picked at random per send and blank entries are dropped.","items":{"type":"string"}},"media_url":{"type":["string","null"],"format":"uri"}}},"waitlist_ack":{"type":["object","null"],"additionalProperties":false,"properties":{"i18n_key":{"type":["string","null"]},"text":{"type":["string","null"]},"spintax":{"type":["array","null"],"description":"Message variants; one is picked at random per send and blank entries are dropped.","items":{"type":"string"}},"media_url":{"type":["string","null"],"format":"uri"}}},"removed_notice":{"type":["object","null"],"additionalProperties":false,"properties":{"i18n_key":{"type":["string","null"]},"text":{"type":["string","null"]},"spintax":{"type":["array","null"],"description":"Message variants; one is picked at random per send and blank entries are dropped.","items":{"type":"string"}},"media_url":{"type":["string","null"],"format":"uri"}}},"graduated_notice":{"type":["object","null"],"additionalProperties":false,"properties":{"i18n_key":{"type":["string","null"]},"text":{"type":["string","null"]},"spintax":{"type":["array","null"],"description":"Message variants; one is picked at random per send and blank entries are dropped.","items":{"type":"string"}},"media_url":{"type":["string","null"],"format":"uri"}}}}},"branding":{"type":"object","additionalProperties":false,"properties":{"naming_template":{"type":["string","null"]},"photo_url":{"type":["string","null"],"format":"uri","description":"Null removes the override. An explicit unit photo overrides distribution identity, then identity overrides the inherited URL. External URLs require HTTPS. HTTP is accepted only for an authorized account-owned image blob on the canonical application origin with a valid signed blob URL and no credentials, query or fragment."},"description":{"type":["string","null"]},"admins":{"type":["array","null"],"description":"Group admins promoted on provisioning; a value with @ is a WhatsApp JID, otherwise a phone whose non-digits are ignored.","items":{"type":"string"}},"announcement_group":{"type":["boolean","null"],"enum":[true,false,null]},"auto_create_channel":{"type":["boolean","null"],"enum":[true,false,null]},"auto_create_channel_live":{"type":["boolean","null"],"enum":[true,false,null]},"channel_invite_url":{"type":["string","null"],"format":"uri"}}},"attribution":{"type":"object","additionalProperties":false,"properties":{"utm_capture":{"type":["boolean","null"],"enum":[true,false,null]},"store_referrer_host":{"type":["boolean","null"],"enum":[true,false,null]},"store_ip_hash":{"type":["boolean","null"],"enum":[true,false,null]},"capi":{"type":["object","null"],"additionalProperties":false,"properties":{"on_click":{"type":["string","null"]},"on_join":{"type":["string","null"]},"on_purchase":{"type":["string","null"]}}},"contact_attribute_key":{"type":["string","null"]}}},"api":{"type":"object","additionalProperties":false,"properties":{"bulk_enroll_max":{"type":["integer","null"],"minimum":0},"index_page_size":{"type":["integer","null"],"minimum":0},"approvals_timeout_seconds":{"type":["integer","null"],"minimum":0},"public_link_rate_per_minute":{"type":["integer","null"],"minimum":0},"export_row_limit":{"type":["integer","null"],"minimum":0}}},"join_approval":{"type":"object","additionalProperties":false,"properties":{"batch":{"type":["integer","null"],"minimum":0},"policy":{"type":["string","null"]}}},"setup":{"type":"object","additionalProperties":false,"properties":{"pause_seconds":{"type":["integer","null"],"minimum":0,"maximum":60},"pause_jitter_seconds":{"type":["integer","null"],"minimum":0},"pause_max_seconds":{"type":["integer","null"],"minimum":0}}}}},"naming_template":{"type":"string","example":"Launch group {n}"},"welcome_message":{"type":["string","null"],"example":null},"community_jid":{"type":["string","null"],"example":null},"channel_jid":{"type":["string","null"],"example":null},"settings":{"type":"object","additionalProperties":true,"description":"Operator configuration. See each operation for settings.locked omission rules. Omit identity to retain legacy photo_url behavior. Identity overrides photo_url without removing that link. New images must have JPEG or PNG signatures, be at most 8 MB, and have no side over 4096 pixels when dimensions are found in the initial 256 KiB. Accepted images start pending full verification. Existing keys must belong to this distribution. Non-null birth settings require a live capability for the destination. Other configuration keys are accepted.","properties":{"join_approval":{"type":["boolean","null"],"enum":[true,false,null],"description":"Require administrator approval to join. Null inherits WhatsApp. New or changed non-null values require a live capability tier for the destination. An unchanged saved value is accepted on update when the destination stays the same.","example":null},"join_approval_policy":{"type":["string","null"],"enum":["manual","all_while_seats",null],"description":"Null defaults effectively to all_while_seats when join_approval is true. A new or changed non-null policy requires a live join_approval capability tier for the destination. An unchanged saved policy is accepted on update when the destination stays the same. Manual only counts pending requests.","example":null},"locked":{"type":["boolean","null"],"enum":[true,false,null],"description":"Restrict group information edits to administrators. Explicit null keeps WhatsApp's existing setting. Omission follows the rules described for each operation.","example":true},"member_add_mode":{"type":["string","null"],"enum":["admin_add","all_member_add",null],"description":"Who may add members. Null inherits WhatsApp. New or changed non-null values require a live capability tier for the destination. An unchanged saved value is accepted on update when the destination stays the same.","example":null},"ephemeral_seconds":{"type":["integer","null"],"enum":[0,86400,604800,7776000,null],"description":"Disappearing-message duration in seconds; zero disables the timer and null inherits WhatsApp.","example":86400},"setup_pause_seconds":{"type":["integer","null"],"minimum":0,"maximum":60,"default":3,"description":"Base delay between setup delegations, plus zero to two seconds of jitter. Zero disables pauses; null uses three seconds.","example":3},"identity":{"type":"object","additionalProperties":false,"required":["photo"],"properties":{"photo":{"type":"object","additionalProperties":false,"required":["mode","items"],"properties":{"mode":{"type":"string","enum":["none","single","sequence"],"example":"sequence"},"items":{"type":"array","maxItems":100,"description":"Position n belongs to unit sequence n. Single requires one item; none requires an empty list.","items":{"oneOf":[{"type":"object","additionalProperties":false,"required":["key"],"properties":{"key":{"type":"string","minLength":1,"description":"Blob id already attached to this distribution.","example":"4711"},"source":{"type":"string","enum":["upload","library","url"],"example":"upload"},"media_asset_id":{"type":"integer","minimum":1,"example":44}}},{"type":"object","additionalProperties":false,"required":["signed_id","source"],"properties":{"signed_id":{"type":"string","minLength":1,"description":"Account-owned signed blob_id returned by the existing upload endpoint.","example":"eyJfcmFpbHMiOnsibWVzc2FnZSI6Ik5EY3hNUT09In19--signed-blob-reference"},"source":{"type":"string","enum":["upload","url"],"example":"upload"}}},{"type":"object","additionalProperties":false,"required":["media_asset_id"],"properties":{"media_asset_id":{"description":"Available, unarchived Library asset belonging to the current account.","oneOf":[{"type":"integer","minimum":1},{"type":"string","pattern":"^[1-9][0-9]*$"}],"example":44},"source":{"type":"string","enum":["library"],"example":"library"}}}]}},"fallback":{"description":"Optional fallback image. Null means no fallback.","oneOf":[{"oneOf":[{"type":"object","additionalProperties":false,"required":["key"],"properties":{"key":{"type":"string","minLength":1,"description":"Blob id already attached to this distribution.","example":"4711"},"source":{"type":"string","enum":["upload","library","url"],"example":"upload"},"media_asset_id":{"type":"integer","minimum":1,"example":44}}},{"type":"object","additionalProperties":false,"required":["signed_id","source"],"properties":{"signed_id":{"type":"string","minLength":1,"description":"Account-owned signed blob_id returned by the existing upload endpoint.","example":"eyJfcmFpbHMiOnsibWVzc2FnZSI6Ik5EY3hNUT09In19--signed-blob-reference"},"source":{"type":"string","enum":["upload","url"],"example":"upload"}}},{"type":"object","additionalProperties":false,"required":["media_asset_id"],"properties":{"media_asset_id":{"description":"Available, unarchived Library asset belonging to the current account.","oneOf":[{"type":"integer","minimum":1},{"type":"string","pattern":"^[1-9][0-9]*$"}],"example":44},"source":{"type":"string","enum":["library"],"example":"library"}}}]},{"type":"null"}]}}}}},"entry_triggers":{"type":"array","description":"Selected entry keys. An empty list disables automatic entry. New configurations and changed lists accept only catalog keys. An unchanged legacy value can be retained during an unrelated update; repair or remove invalid values explicitly before changing that list.","items":{"type":"string","description":"A selectable launch distribution entry key backed by an enrollment consumer. Payment confirmed emissions use payment_charge.paid.","enum":["payment_charge.paid","payment_charge.overdue","crm_item.stage_changed","crm_item.stale","crm_item.won","task.overdue","task.due_soon","calendar_event.created","calendar_event.no_show","commerce.cart_abandoned","commerce.order_placed","commerce.payment_pending","commerce.payment_confirmed","commerce.payment_declined","commerce.overdue","commerce.due_soon","commerce.refunded","commerce.chargeback","commerce.subscription_late","commerce.subscription_canceled","ads.lead_captured","social.comment_captured"],"example":"payment_charge.paid"},"example":["payment_charge.paid","commerce.payment_confirmed"]},"algorithm":{"type":["object","null"],"additionalProperties":true,"description":"Raw placement configuration; unrelated existing keys are preserved.","properties":{"routing_rules":{"type":["array","null"],"description":"Ordered rules, evaluated with equality and all conditions together. New or changed lists must use recognized condition keys and member sources; an identical legacy list may remain during an unrelated update. Null removes the override. UTM values and account labels are open values.","items":{"type":"object","required":["match"],"properties":{"match":{"type":"object","additionalProperties":false,"properties":{"utm_source":{"type":"string","description":"Compared with lead attribution, ignoring case and surrounding spaces."},"utm_campaign":{"type":"string","description":"Compared with lead attribution, ignoring case and surrounding spaces."},"tag":{"type":"string","description":"Literal label from the account label catalog."},"source":{"type":"string","enum":["link","automation","event","manual","api","follow_up"],"description":"Member entry source; null and empty values are not choices."}}},"distribution_id":{"type":"integer","minimum":1,"description":"Target distribution; skipped unless it is active and not archived in the same account."}}}}}},"dm_on_join":{"type":["object","null"],"additionalProperties":true,"description":"Raw join-message configuration; these template selectors have no operational send consumer.","properties":{"template":{"type":["string","null"],"enum":["welcome","reminder","countdown","unit_opened","waitlist_ack","removed_notice","graduated_notice",null],"description":"Recognized stored template identifier. Null removes the override; an empty string is invalid. An unchanged legacy identifier may be retained on an unrelated update. This selector currently has no operational send consumer; accepting an identifier does not schedule or send a message."}}},"post_purchase":{"type":["object","null"],"additionalProperties":true,"description":"Raw post-purchase configuration; unrelated existing keys are preserved.","properties":{"on_overdue":{"type":["object","null"],"additionalProperties":true,"description":"Overdue configuration; selecting a warning template does not currently send a warning.","properties":{"warn_template":{"type":["string","null"],"enum":["welcome","reminder","countdown","unit_opened","waitlist_ack","removed_notice","graduated_notice",null],"description":"Recognized stored template identifier. Null removes the override; an empty string is invalid. An unchanged legacy identifier may be retained on an unrelated update. This selector currently has no operational send consumer; accepting an identifier does not schedule or send a message."}}}}},"photo_url":{"type":["string","null"],"description":"Inherited photo URL. An explicit unit photo overrides distribution identity, then identity overrides the inherited URL. External URLs require HTTPS; HTTP is accepted only for an authorized image blob of this account on the canonical application origin with a valid signed blob URL and no credentials, query or fragment. Null removes the override.","example":"https://images.example.test/legacy-cover.jpg"},"description":{"type":["string","null"],"example":"Welcome to launch group {n}."}}}}},"example":{"name":"October launch","slug":"october-launch","inbox_id":15,"target_type":"group","join_mode":"invite_link","capacity_per_unit":256,"algorithm":"fill_first","opens_at":"2026-10-20T12:00:00Z","closes_at":null,"fallback_distribution_id":null,"graduate_distribution_id":null,"settings_overrides":{"capacity":{"headroom":30,"hard_cap":1,"per_unit":1,"by_inbox":{},"reserve_for_waitlist":1},"sellers":{"strategy":"weighted","list":[{"phone":"+5511999998888","name":"Sample Name","weight":1,"paused":true,"user_id":1,"inbox_id":1}],"prefill_template":"sample prefill template","daily_cap_per_seller":1,"pause_when_offline":true},"algorithm":{"strategy":"fill_first","weight":1,"sticky_by_contact":true,"routing_rules":[{"match":{"utm_source":"sample utm source","utm_campaign":"sample utm campaign","tag":"sample tag","source":"link"},"distribution_id":1}]},"rotation":{"batch_size":1,"warmup_ramp":[{"after_minutes":60,"batch":1}],"defer_base_seconds":60,"max_backoff_shift":1,"max_defer_attempts":1,"throttle":{"second":1,"hour":1},"sync_interval_minutes":60,"scheduler_batch_size":1},"fallback":{"mode":"url","url":"https://example.com/resource","message":"Sample message text.","distribution_id":1,"waitlist_max":1,"waitlist_ttl_hours":1,"waitlist_drain_batch":1},"schedule":{"opens_at":"2026-01-15T10:30:00.000Z","closes_at":"2026-01-15T10:30:00.000Z","cascade_minutes":60,"announce_when_closed":true,"lock_when_closed":true,"warmup_window_minutes":60,"timezone":"America/Sao_Paulo"},"reentry":{"allow_reentry":true,"cooldown_hours":1,"dedupe_across_units":true,"use_hub_blocklist":true,"blacklist":["sample blacklist"],"whitelist":["sample whitelist"],"reopen_on_leave":true},"post_purchase":{"on_paid":{"remove":true,"move_to_distribution_id":1,"delay_minutes":60},"on_overdue":{"remove":true,"after_days":7,"warn_template":"welcome"},"on_refund":{"remove":true},"on_chargeback":{"remove":true},"remove_batch_size":1,"remove_throttle":{"second":1,"hour":1}},"dm_on_join":{"enabled":true,"template":"welcome","spintax":["sample spintax"],"delay_seconds":{"min":1,"max":1},"per_hour_limit":1,"inbox_id":1,"fallback_inbox_id":1,"mode":"fixed","brief":"sample brief","skip_if_conversation_open":true},"templates":{"welcome":{"text":"sample text","spintax":["sample spintax"],"media_url":"https://example.com/resource"},"reminder":{"i18n_key":"sample-token","text":"sample text","spintax":["sample spintax"],"media_url":"https://example.com/resource"},"countdown":{"i18n_key":"sample-token","text":"sample text","spintax":["sample spintax"],"media_url":"https://example.com/resource"},"unit_opened":{"i18n_key":"sample-token","text":"sample text","spintax":["sample spintax"],"media_url":"https://example.com/resource"},"waitlist_ack":{"i18n_key":"sample-token","text":"sample text","spintax":["sample spintax"],"media_url":"https://example.com/resource"},"removed_notice":{"i18n_key":"sample-token","text":"sample text","spintax":["sample spintax"],"media_url":"https://example.com/resource"},"graduated_notice":{"i18n_key":"sample-token","text":"sample text","spintax":["sample spintax"],"media_url":"https://example.com/resource"}},"branding":{"naming_template":"sample naming template","photo_url":"https://example.com/resource","description":"A short description.","admins":["sample admin"],"announcement_group":true,"auto_create_channel":true,"auto_create_channel_live":true,"channel_invite_url":"https://example.com/resource"},"attribution":{"utm_capture":true,"store_referrer_host":true,"store_ip_hash":true,"capi":{"on_click":"sample on click","on_join":"sample on join","on_purchase":"sample on purchase"},"contact_attribute_key":"sample-token"},"api":{"bulk_enroll_max":1,"index_page_size":1,"approvals_timeout_seconds":60,"public_link_rate_per_minute":1,"export_row_limit":1},"join_approval":{"batch":1,"policy":"sample policy"},"setup":{"pause_seconds":60,"pause_jitter_seconds":60,"pause_max_seconds":60}},"naming_template":"Launch group {n}","settings":{"entry_triggers":[],"description":"Welcome to launch group {n}.","identity":{"photo":{"mode":"sequence","items":[{"signed_id":"eyJfcmFpbHMiOnsibWVzc2FnZSI6Ik5EY3hNUT09In19--signed-blob-reference","source":"upload"},{"media_asset_id":44,"key":"4711","source":"upload"}],"fallback":{"signed_id":"eyJfcmFpbHMiOnsibWVzc2FnZSI6Ik5EY3lNQT09In19--signed-blob-reference","source":"url"}}},"join_approval":null,"join_approval_policy":null,"locked":true,"member_add_mode":null,"ephemeral_seconds":86400,"setup_pause_seconds":3,"algorithm":{"routing_rules":[{"match":{"utm_source":"sample utm source","utm_campaign":"sample utm campaign","tag":"sample tag","source":"link"},"distribution_id":1}]},"dm_on_join":{"template":"welcome"},"post_purchase":{"on_overdue":{"warn_template":"welcome"}},"photo_url":"https://images.example.test/legacy-cover.jpg"},"launch_id":null,"welcome_message":null,"community_jid":null,"channel_jid":null}}}}}},"/api/v1/accounts/{account_id}/growth/distributions/{id}":{"get":{"tags":["Growth Distribution"],"operationId":"auto_get_api_v1_accounts_account_id_growth_distributions_id","summary":"Get distributions","description":"Returns the distribution identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Launch distribution with stored configuration and the current identity projection.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["payload"],"properties":{"payload":{"type":"object","additionalProperties":false,"required":["id","account_id","name","slug","public_path","inbox_id","launch_id","target_type","join_mode","capacity_per_unit","algorithm","opens_at","fallback_distribution_id","graduate_distribution_id","advanced_enabled","capacity_defaults","community_member_limit","community_provisioning","setup_capabilities","setup_pause_defaults","next_sequence","effective_capacity","throttle_defaults","identity","community_jid","channel_jid","naming_template","welcome_message","status","settings","entry_trigger_catalog","entry_trigger_validation","configuration_options","configuration_validation","units_count","members_count","open_unit_sequence","closes_at","archived_at","created_at","updated_at","slug_collision","slug_retired_from"],"properties":{"algorithm":{"type":"string","enum":["fill_first","round_robin","random","weighted"],"example":"fill_first"},"opens_at":{"type":["string","null"],"format":"date-time","description":"Distribution opening time, when configured.","example":null},"fallback_distribution_id":{"type":["integer","null"],"example":null},"graduate_distribution_id":{"type":["integer","null"],"example":null},"advanced_enabled":{"type":"boolean","description":"Whether advanced launch distribution features are enabled for this account.","example":false},"capacity_defaults":{"type":"object","additionalProperties":false,"required":["default","maximum","effective_maximum","hard_cap","headroom"],"description":"Resolved capacity limits. On defaults, default is the account per-unit setting; on distribution resources it is the product default of 256. Effective maximum is min(1023, hard_cap minus headroom). An existing explicit per-unit setting is preserved when the account defaults change.","properties":{"default":{"type":"integer","minimum":1,"maximum":1023,"example":256},"maximum":{"type":"integer","description":"Maximum accepted capacity per launch group.","example":1023},"effective_maximum":{"type":"integer","minimum":0,"maximum":1023,"description":"Maximum after applying the resolved hard cap and explicit headroom.","example":1023},"hard_cap":{"type":"integer","minimum":1,"maximum":1024,"description":"Hard cap resolved from the account and distribution settings.","example":1024},"headroom":{"type":"integer","minimum":0,"maximum":1023,"description":"Explicit seat margin; absent overrides use the product margin of zero.","example":0}}},"community_member_limit":{"type":"integer","example":2000},"community_provisioning":{"type":"object","additionalProperties":false,"required":["state","error_code","failed_at"],"properties":{"state":{"type":"string","enum":["not_requested","pending","created","failed"],"example":"not_requested","description":"Distribution member progress state."},"error_code":{"type":["string","null"],"enum":["missing_initial_participant","outcome_uncertain","feature_not_supported","gateway_rejected","gateway_unavailable","rate_limited","setup_step_failed","setup_step_refused","setup_incomplete","creator_inbox_unavailable","group_not_admin","group_not_found",null],"example":null},"failed_at":{"type":["string","null"],"format":"date-time","example":null}}},"next_sequence":{"type":"integer","minimum":1,"example":1},"effective_capacity":{"type":"integer","minimum":0,"maximum":1023,"description":"Minimum of the configured per-unit capacity and the effective maximum after the resolved hard cap and headroom.","example":256},"throttle_defaults":{"type":"object","additionalProperties":false,"required":["second","hour"],"description":"Default outbound limits for WhatsApp Web; operator overrides are kept in settings.","properties":{"second":{"type":"integer","example":1},"hour":{"type":"integer","example":240}}},"identity":{"type":"object","additionalProperties":false,"required":["mode","items","fallback","remaining_positions","exhausts_at_sequence","limits"],"properties":{"mode":{"type":"string","enum":["none","single","sequence"],"example":"sequence"},"items":{"type":"array","maxItems":100,"items":{"type":"object","additionalProperties":false,"required":["key","source","thumb_url","available","check"],"properties":{"key":{"type":"string","minLength":1,"example":"4711"},"source":{"type":"string","enum":["upload","library","url"],"example":"upload"},"media_asset_id":{"type":"integer","minimum":1,"example":44},"thumb_url":{"type":"string","description":"Center-cropped 160 by 160 representation URL, present only after the full image check succeeded; empty while the check is pending or invalid, when the file is unavailable, or when the representation fails.","example":""},"available":{"type":"boolean","description":"Whether the blob is still attached to this distribution.","example":true},"check":{"type":"object","additionalProperties":false,"required":["state","reason","checked_at","overdue"],"properties":{"state":{"type":"string","enum":["pending","ok","invalid"],"example":"pending","description":"Distribution member progress state."},"reason":{"type":["string","null"],"enum":["type","size","dimensions","unreadable","unavailable",null],"example":null},"checked_at":{"type":["string","null"],"format":"date-time","example":null},"overdue":{"type":"boolean","description":"Pending without a check time for at least 15 minutes since attachment creation; false without the check column or attachment.","example":false}}}}}},"fallback":{"oneOf":[{"type":"object","additionalProperties":false,"required":["key","source","thumb_url","available","check"],"properties":{"key":{"type":"string","minLength":1,"example":"4711"},"source":{"type":"string","enum":["upload","library","url"],"example":"upload"},"media_asset_id":{"type":"integer","minimum":1,"example":44},"thumb_url":{"type":"string","description":"Center-cropped 160 by 160 representation URL, present only after the full image check succeeded; empty while the check is pending or invalid, when the file is unavailable, or when the representation fails.","example":""},"available":{"type":"boolean","description":"Whether the blob is still attached to this distribution.","example":true},"check":{"type":"object","additionalProperties":false,"required":["state","reason","checked_at","overdue"],"properties":{"state":{"type":"string","enum":["pending","ok","invalid"],"example":"pending","description":"Distribution member progress state."},"reason":{"type":["string","null"],"enum":["type","size","dimensions","unreadable","unavailable",null],"example":null},"checked_at":{"type":["string","null"],"format":"date-time","example":null},"overdue":{"type":"boolean","description":"Pending without a check time for at least 15 minutes since attachment creation; false without the check column or attachment.","example":false}}}}},{"type":"null"}]},"limits":{"type":"object","additionalProperties":false,"required":["max_bytes","max_side","max_items","content_types","check_overdue_after_seconds"],"properties":{"max_bytes":{"type":"integer","example":8388608},"max_side":{"type":"integer","example":4096},"max_items":{"type":"integer","example":100},"check_overdue_after_seconds":{"type":"integer","example":900},"content_types":{"type":"array","items":{"type":"string","enum":["image/jpeg","image/png"]},"example":["image/jpeg","image/png"]}}},"remaining_positions":{"type":["integer","null"],"minimum":0,"description":"Remaining own-image positions from next_sequence; null outside sequence mode.","example":2},"exhausts_at_sequence":{"type":["integer","null"],"minimum":0,"description":"Number of own-image positions; null outside sequence mode.","example":2}}},"setup_capabilities":{"type":"object","description":"Birth-setting support by step. Only live capabilities support the listed destination types; partial_contract is unavailable.","additionalProperties":{"type":"object","additionalProperties":false,"required":["tier","target_types"],"properties":{"tier":{"type":"string","enum":["live","partial_contract"]},"target_types":{"type":"array","items":{"type":"string","enum":["group","community"]}}}},"example":{"join_approval":{"tier":"partial_contract","target_types":["group","community"]},"locked":{"tier":"live","target_types":["group","community"]},"member_add_mode":{"tier":"partial_contract","target_types":["group","community"]},"ephemeral":{"tier":"live","target_types":["group","community"]}}},"setup_pause_defaults":{"type":"object","additionalProperties":false,"required":["default_seconds","jitter_seconds","max_seconds"],"description":"Server defaults and operator bounds for setup pacing. Jitter is added only to positive pauses.","properties":{"default_seconds":{"type":"integer","minimum":0,"description":"Base pause inherited when no override is set.","example":3},"jitter_seconds":{"type":"integer","minimum":0,"description":"Maximum random delay added to a positive base pause.","example":2},"max_seconds":{"type":"integer","minimum":0,"description":"Maximum configurable base pause before jitter.","example":60}},"example":{"default_seconds":3,"jitter_seconds":2,"max_seconds":60}},"id":{"type":"integer","example":22},"account_id":{"type":"integer","example":1},"name":{"type":"string","example":"October launch"},"slug":{"type":"string","example":"october-launch"},"public_path":{"type":"string","example":"/g/october-launch"},"inbox_id":{"type":"integer","example":6},"logical_inbox_id":{"type":"integer","description":"Present when the visible logical inbox differs from the transport inbox.","example":15},"launch_id":{"type":["integer","null"],"example":null},"target_type":{"type":"string","enum":["community","group","channel"],"example":"group"},"join_mode":{"type":"string","enum":["invite_link","direct_add","both"],"example":"invite_link"},"capacity_per_unit":{"type":"integer","minimum":1,"maximum":1023,"example":256},"community_jid":{"type":["string","null"],"example":null},"channel_jid":{"type":["string","null"],"example":null},"naming_template":{"type":"string","example":"Launch group {n}"},"welcome_message":{"type":["string","null"],"example":null},"status":{"type":"string","enum":["draft","active","paused","completed"],"example":"draft"},"settings":{"type":"object","additionalProperties":true,"description":"Operator configuration excluding system-owned diagnostics; other configuration keys are preserved.","properties":{"join_approval":{"type":["boolean","null"],"enum":[true,false,null],"description":"Require administrator approval to join. Null inherits WhatsApp. New or changed non-null values require a live capability tier for the destination. An unchanged saved value is accepted on update when the destination stays the same.","example":null},"join_approval_policy":{"type":["string","null"],"enum":["manual","all_while_seats",null],"description":"Null defaults effectively to all_while_seats when join_approval is true. A new or changed non-null policy requires a live join_approval capability tier for the destination. An unchanged saved policy is accepted on update when the destination stays the same. Manual only counts pending requests.","example":null},"locked":{"type":["boolean","null"],"enum":[true,false,null],"description":"Restrict group information edits to administrators. Explicit null keeps WhatsApp's existing setting. Omission follows the rules described for each operation.","example":true},"member_add_mode":{"type":["string","null"],"enum":["admin_add","all_member_add",null],"description":"Who may add members. Null inherits WhatsApp. New or changed non-null values require a live capability tier for the destination. An unchanged saved value is accepted on update when the destination stays the same.","example":null},"ephemeral_seconds":{"type":["integer","null"],"enum":[0,86400,604800,7776000,null],"description":"Disappearing-message duration in seconds; zero disables the timer and null inherits WhatsApp.","example":86400},"setup_pause_seconds":{"type":["integer","null"],"minimum":0,"maximum":60,"default":3,"description":"Base delay between setup delegations, plus zero to two seconds of jitter. Zero disables pauses; null uses three seconds.","example":3},"identity":{"type":"object","additionalProperties":false,"required":["photo"],"properties":{"photo":{"type":"object","additionalProperties":false,"required":["mode","items","fallback"],"properties":{"mode":{"type":"string","enum":["none","single","sequence"],"example":"sequence"},"items":{"type":"array","maxItems":100,"description":"Ordered blob references. Single requires one item; none requires an empty list.","items":{"type":"object","additionalProperties":false,"required":["key","source"],"properties":{"key":{"type":"string","minLength":1,"description":"Blob id attached to this distribution.","example":"4711"},"source":{"type":"string","enum":["upload","library","url"],"example":"upload"},"media_asset_id":{"type":"integer","minimum":1,"description":"Original Library asset, when selected from the Library.","example":44}}}},"fallback":{"description":"Image used after the sequence ends or when a selected image is unavailable.","oneOf":[{"type":"object","additionalProperties":false,"required":["key","source"],"properties":{"key":{"type":"string","minLength":1,"description":"Blob id attached to this distribution.","example":"4711"},"source":{"type":"string","enum":["upload","library","url"],"example":"upload"},"media_asset_id":{"type":"integer","minimum":1,"description":"Original Library asset, when selected from the Library.","example":44}}},{"type":"null"}]}}}}},"photo_url":{"type":["string","null"],"description":"Inherited group photo link. An explicit unit photo overrides the distribution identity; without a unit override the distribution identity wins, then the inherited URL. HTTP is accepted only for an authorized image blob of this account on the canonical application origin, with a valid signed blob URL and no credentials, query or fragment. External URLs require HTTPS.","example":"https://images.example.test/legacy-cover.jpg"},"description":{"type":["string","null"],"description":"Group description; each occurrence of {n} is replaced with the unit sequence.","example":"Welcome to launch group {n}."}}},"entry_trigger_catalog":{"type":"array","description":"Complete list of selectable entry keys, shared with server validation. Text is localized for the request. Translation keys belong to the server translation catalog. Availability of a key does not guarantee an event producer, an eligible contact or an enrollment effect.","items":{"type":"object","additionalProperties":false,"required":["key","label_key","description_key","label","description"],"properties":{"key":{"type":"string","description":"A selectable launch distribution entry key backed by an enrollment consumer. Payment confirmed emissions use payment_charge.paid.","enum":["payment_charge.paid","payment_charge.overdue","crm_item.stage_changed","crm_item.stale","crm_item.won","task.overdue","task.due_soon","calendar_event.created","calendar_event.no_show","commerce.cart_abandoned","commerce.order_placed","commerce.payment_pending","commerce.payment_confirmed","commerce.payment_declined","commerce.overdue","commerce.due_soon","commerce.refunded","commerce.chargeback","commerce.subscription_late","commerce.subscription_canceled","ads.lead_captured","social.comment_captured"],"example":"payment_charge.paid"},"label_key":{"type":"string","description":"Server translation key for the label.","example":"growth.distribution.entry_triggers.events.payment_charge_paid.label"},"description_key":{"type":"string","description":"Server translation key for the description.","example":"growth.distribution.entry_triggers.events.payment_charge_paid.description"},"label":{"type":"string","description":"Localized label.","example":"Charge paid"},"description":{"type":"string","description":"Localized explanation of the entry signal.","example":"A confirmed or paid charge payment, admitted through the payment_charge.paid key."}}},"example":[{"key":"payment_charge.paid","label_key":"growth.distribution.entry_triggers.events.payment_charge_paid.label","description_key":"growth.distribution.entry_triggers.events.payment_charge_paid.description","label":"Charge paid","description":"A confirmed or paid charge payment, admitted through the payment_charge.paid key."}]},"entry_trigger_validation":{"type":"object","additionalProperties":false,"required":["valid","invalid_type","invalid_indexes"],"description":"Advisory validation of the stored entry list, without changing it. Read invalid values from settings.entry_triggers at the reported positions. A malformed non-array value has invalid_type true and no positions. An absent list is valid and equivalent to an empty list.","properties":{"valid":{"type":"boolean","example":false},"invalid_type":{"type":"boolean","example":false},"invalid_indexes":{"type":"array","description":"Zero-based positions of unknown keys or elements that are not strings.","items":{"type":"integer","minimum":0},"example":[0]}},"example":{"valid":false,"invalid_type":false,"invalid_indexes":[0]}},"configuration_options":{"type":"object","additionalProperties":false,"required":["routing_sources","template_keys"],"description":"Recognized routing sources and stored template identifiers from the same server sets used by validation. Template membership does not imply a send: the join-template and overdue-warning selectors currently have no operational send consumer and must be presented as unavailable.","properties":{"routing_sources":{"type":"array","items":{"type":"string","enum":["link","automation","event","manual","api","follow_up"]}},"template_keys":{"type":"array","items":{"type":"string","enum":["welcome","reminder","countdown","unit_opened","waitlist_ack","removed_notice","graduated_notice"]}}},"example":{"routing_sources":["link","automation","event","manual","api","follow_up"],"template_keys":["welcome","reminder","countdown","unit_opened","waitlist_ack","removed_notice","graduated_notice"]}},"configuration_validation":{"type":"object","additionalProperties":false,"required":["valid","issues"],"description":"Diagnostics for saved and resolved choices without removing or rewriting them. Paths are relative to the settings document; inherited values also remain available in settings explanations.","properties":{"valid":{"type":"boolean","example":true},"issues":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["path","code"],"properties":{"path":{"type":"string","example":"algorithm.routing_rules[0].match.source"},"code":{"type":"string","enum":["invalid_type","unknown_choice","unknown_key"],"example":"unknown_choice"}}}}},"example":{"valid":true,"issues":[]}},"units_count":{"type":"integer","minimum":0,"example":0},"members_count":{"type":"integer","minimum":0,"example":0},"capacity_total":{"type":"integer","minimum":0,"description":"Sum of current effective capacities across all units, including explicit unit overrides.","example":0},"occupancy_total":{"type":"integer","minimum":0,"description":"Sum of the synced member count of every unit.","example":0},"awaiting_count":{"type":"integer","minimum":0,"description":"Members still pending, queued or waitlisted.","example":0},"open_unit_sequence":{"type":["integer","null"],"example":null},"closes_at":{"type":["string","null"],"format":"date-time","description":"Configured distribution closing time; null means no closing time is set.","example":null},"archived_at":{"type":["string","null"],"format":"date-time","example":null},"created_at":{"type":"string","format":"date-time","example":"2026-10-13T22:00:00Z"},"updated_at":{"type":"string","format":"date-time","example":"2026-10-13T22:00:00Z"},"slug_collision":{"type":"boolean","description":"Whether the current public slug is shared with another distribution.","example":false},"slug_retired_from":{"type":["string","null"],"description":"Former public slug retired after a collision, or null.","example":null}}}}},"example":{"payload":{"algorithm":"fill_first","opens_at":null,"fallback_distribution_id":null,"graduate_distribution_id":null,"advanced_enabled":false,"capacity_defaults":{"default":256,"maximum":1023,"effective_maximum":1023,"hard_cap":1024,"headroom":0},"community_member_limit":2000,"community_provisioning":{"state":"not_requested","error_code":null,"failed_at":null},"next_sequence":1,"effective_capacity":256,"throttle_defaults":{"second":1,"hour":240},"identity":{"mode":"sequence","items":[{"key":"4711","source":"upload","thumb_url":"https://app.example.test/rails/active_storage/representations/redirect/cover-1.jpg","available":true,"check":{"state":"ok","reason":null,"checked_at":"2026-10-14T01:00:00Z","overdue":false},"media_asset_id":44},{"key":"4712","source":"library","media_asset_id":44,"thumb_url":"","available":true,"check":{"state":"pending","reason":null,"checked_at":null,"overdue":false}}],"fallback":{"key":"4720","source":"url","thumb_url":"https://app.example.test/rails/active_storage/representations/redirect/default-cover.jpg","available":true,"check":{"state":"ok","reason":null,"checked_at":"2026-10-14T01:00:00Z","overdue":false},"media_asset_id":44},"limits":{"max_bytes":8388608,"max_side":4096,"max_items":100,"check_overdue_after_seconds":900,"content_types":["image/jpeg","image/png"]},"remaining_positions":2,"exhausts_at_sequence":2},"entry_trigger_catalog":[{"key":"payment_charge.paid","label_key":"growth.distribution.entry_triggers.events.payment_charge_paid.label","description_key":"growth.distribution.entry_triggers.events.payment_charge_paid.description","label":"Charge paid","description":"A confirmed or paid charge payment, admitted through the payment_charge.paid key."}],"entry_trigger_validation":{"valid":true,"invalid_type":false,"invalid_indexes":[]},"configuration_options":{"routing_sources":["link","automation","event","manual","api","follow_up"],"template_keys":["welcome","reminder","countdown","unit_opened","waitlist_ack","removed_notice","graduated_notice"]},"configuration_validation":{"valid":true,"issues":[{"path":"algorithm.routing_rules[0].match.source","code":"unknown_choice"}]},"setup_capabilities":{"join_approval":{"tier":"partial_contract","target_types":["group","community"]},"locked":{"tier":"live","target_types":["group","community"]},"member_add_mode":{"tier":"partial_contract","target_types":["group","community"]},"ephemeral":{"tier":"live","target_types":["group","community"]}},"setup_pause_defaults":{"default_seconds":3,"jitter_seconds":2,"max_seconds":60},"id":22,"account_id":1,"name":"October launch","slug":"october-launch","public_path":"/g/october-launch","inbox_id":6,"logical_inbox_id":15,"launch_id":null,"target_type":"group","join_mode":"invite_link","capacity_per_unit":256,"community_jid":null,"channel_jid":null,"naming_template":"Launch group {n}","welcome_message":null,"status":"draft","settings":{"locked":true,"ephemeral_seconds":86400,"setup_pause_seconds":3,"description":"Welcome to launch group {n}.","photo_url":"https://images.example.test/legacy-cover.jpg","identity":{"photo":{"mode":"sequence","items":[{"key":"4711","source":"upload","media_asset_id":44},{"key":"4712","source":"library","media_asset_id":44}],"fallback":{"key":"4720","source":"url","media_asset_id":44}}},"join_approval":null,"join_approval_policy":null,"member_add_mode":null},"units_count":0,"members_count":0,"capacity_total":0,"occupancy_total":0,"awaiting_count":0,"open_unit_sequence":null,"closes_at":null,"archived_at":null,"created_at":"2026-10-13T22:00:00Z","updated_at":"2026-10-13T22:00:00Z","slug_collision":false,"slug_retired_from":null}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]},"patch":{"tags":["Growth Distribution"],"operationId":"auto_patch_api_v1_accounts_account_id_growth_distributions_id","summary":"Update a launch distribution","description":"Resolves and validates identity under the distribution row lock, preserving system diagnostics, rotation inboxes and retired-address metadata. All image errors are returned together. A refused save persists neither settings nor attachments. Unreferenced attachments are detached only after a successful save; a shared Library blob survives. Existing image keys can be repeated or reordered. No settings.locked default is injected by update, for any destination. When settings is omitted or null, the saved configuration is retained; a non-null document replaces the operator configuration. Explicit locked true, false or null is preserved; null keeps WhatsApp's existing setting. A switch to channel validates the effective configuration against its available capabilities. With the same destination, only changed birth settings are checked for live support; an unchanged saved legacy value may be resubmitted. When the destination changes, all non-null birth settings in the effective configuration require a live capability for the new destination. A changed entry-trigger list must use catalog keys. An unchanged legacy list can be retained during an unrelated edit; the response diagnoses invalid saved positions without removing them.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Launch distribution with stored configuration and the current identity projection.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["payload"],"properties":{"payload":{"type":"object","additionalProperties":false,"required":["id","account_id","name","slug","public_path","inbox_id","launch_id","target_type","join_mode","capacity_per_unit","algorithm","opens_at","fallback_distribution_id","graduate_distribution_id","advanced_enabled","capacity_defaults","community_member_limit","community_provisioning","setup_capabilities","setup_pause_defaults","next_sequence","effective_capacity","throttle_defaults","identity","community_jid","channel_jid","naming_template","welcome_message","status","settings","entry_trigger_catalog","entry_trigger_validation","configuration_options","configuration_validation","units_count","members_count","open_unit_sequence","closes_at","archived_at","created_at","updated_at","slug_collision","slug_retired_from"],"properties":{"algorithm":{"type":"string","enum":["fill_first","round_robin","random","weighted"],"example":"fill_first"},"opens_at":{"type":["string","null"],"format":"date-time","description":"Distribution opening time, when configured.","example":null},"fallback_distribution_id":{"type":["integer","null"],"example":null},"graduate_distribution_id":{"type":["integer","null"],"example":null},"advanced_enabled":{"type":"boolean","description":"Whether advanced launch distribution features are enabled for this account.","example":false},"capacity_defaults":{"type":"object","additionalProperties":false,"required":["default","maximum","effective_maximum","hard_cap","headroom"],"description":"Resolved capacity limits. On defaults, default is the account per-unit setting; on distribution resources it is the product default of 256. Effective maximum is min(1023, hard_cap minus headroom). An existing explicit per-unit setting is preserved when the account defaults change.","properties":{"default":{"type":"integer","minimum":1,"maximum":1023,"example":256},"maximum":{"type":"integer","description":"Maximum accepted capacity per launch group.","example":1023},"effective_maximum":{"type":"integer","minimum":0,"maximum":1023,"description":"Maximum after applying the resolved hard cap and explicit headroom.","example":1023},"hard_cap":{"type":"integer","minimum":1,"maximum":1024,"description":"Hard cap resolved from the account and distribution settings.","example":1024},"headroom":{"type":"integer","minimum":0,"maximum":1023,"description":"Explicit seat margin; absent overrides use the product margin of zero.","example":0}}},"community_member_limit":{"type":"integer","example":2000},"community_provisioning":{"type":"object","additionalProperties":false,"required":["state","error_code","failed_at"],"properties":{"state":{"type":"string","enum":["not_requested","pending","created","failed"],"example":"not_requested","description":"Distribution member progress state."},"error_code":{"type":["string","null"],"enum":["missing_initial_participant","outcome_uncertain","feature_not_supported","gateway_rejected","gateway_unavailable","rate_limited","setup_step_failed","setup_step_refused","setup_incomplete","creator_inbox_unavailable","group_not_admin","group_not_found",null],"example":null},"failed_at":{"type":["string","null"],"format":"date-time","example":null}}},"next_sequence":{"type":"integer","minimum":1,"example":1},"effective_capacity":{"type":"integer","minimum":0,"maximum":1023,"description":"Minimum of the configured per-unit capacity and the effective maximum after the resolved hard cap and headroom.","example":256},"throttle_defaults":{"type":"object","additionalProperties":false,"required":["second","hour"],"description":"Default outbound limits for WhatsApp Web; operator overrides are kept in settings.","properties":{"second":{"type":"integer","example":1},"hour":{"type":"integer","example":240}}},"identity":{"type":"object","additionalProperties":false,"required":["mode","items","fallback","remaining_positions","exhausts_at_sequence","limits"],"properties":{"mode":{"type":"string","enum":["none","single","sequence"],"example":"sequence"},"items":{"type":"array","maxItems":100,"items":{"type":"object","additionalProperties":false,"required":["key","source","thumb_url","available","check"],"properties":{"key":{"type":"string","minLength":1,"example":"4711"},"source":{"type":"string","enum":["upload","library","url"],"example":"upload"},"media_asset_id":{"type":"integer","minimum":1,"example":44},"thumb_url":{"type":"string","description":"Center-cropped 160 by 160 representation URL, present only after the full image check succeeded; empty while the check is pending or invalid, when the file is unavailable, or when the representation fails.","example":""},"available":{"type":"boolean","description":"Whether the blob is still attached to this distribution.","example":true},"check":{"type":"object","additionalProperties":false,"required":["state","reason","checked_at","overdue"],"properties":{"state":{"type":"string","enum":["pending","ok","invalid"],"example":"pending","description":"Distribution member progress state."},"reason":{"type":["string","null"],"enum":["type","size","dimensions","unreadable","unavailable",null],"example":null},"checked_at":{"type":["string","null"],"format":"date-time","example":null},"overdue":{"type":"boolean","description":"Pending without a check time for at least 15 minutes since attachment creation; false without the check column or attachment.","example":false}}}}}},"fallback":{"oneOf":[{"type":"object","additionalProperties":false,"required":["key","source","thumb_url","available","check"],"properties":{"key":{"type":"string","minLength":1,"example":"4711"},"source":{"type":"string","enum":["upload","library","url"],"example":"upload"},"media_asset_id":{"type":"integer","minimum":1,"example":44},"thumb_url":{"type":"string","description":"Center-cropped 160 by 160 representation URL, present only after the full image check succeeded; empty while the check is pending or invalid, when the file is unavailable, or when the representation fails.","example":""},"available":{"type":"boolean","description":"Whether the blob is still attached to this distribution.","example":true},"check":{"type":"object","additionalProperties":false,"required":["state","reason","checked_at","overdue"],"properties":{"state":{"type":"string","enum":["pending","ok","invalid"],"example":"pending","description":"Distribution member progress state."},"reason":{"type":["string","null"],"enum":["type","size","dimensions","unreadable","unavailable",null],"example":null},"checked_at":{"type":["string","null"],"format":"date-time","example":null},"overdue":{"type":"boolean","description":"Pending without a check time for at least 15 minutes since attachment creation; false without the check column or attachment.","example":false}}}}},{"type":"null"}]},"limits":{"type":"object","additionalProperties":false,"required":["max_bytes","max_side","max_items","content_types","check_overdue_after_seconds"],"properties":{"max_bytes":{"type":"integer","example":8388608},"max_side":{"type":"integer","example":4096},"max_items":{"type":"integer","example":100},"check_overdue_after_seconds":{"type":"integer","example":900},"content_types":{"type":"array","items":{"type":"string","enum":["image/jpeg","image/png"]},"example":["image/jpeg","image/png"]}}},"remaining_positions":{"type":["integer","null"],"minimum":0,"description":"Remaining own-image positions from next_sequence; null outside sequence mode.","example":2},"exhausts_at_sequence":{"type":["integer","null"],"minimum":0,"description":"Number of own-image positions; null outside sequence mode.","example":2}}},"setup_capabilities":{"type":"object","description":"Birth-setting support by step. Only live capabilities support the listed destination types; partial_contract is unavailable.","additionalProperties":{"type":"object","additionalProperties":false,"required":["tier","target_types"],"properties":{"tier":{"type":"string","enum":["live","partial_contract"]},"target_types":{"type":"array","items":{"type":"string","enum":["group","community"]}}}},"example":{"join_approval":{"tier":"partial_contract","target_types":["group","community"]},"locked":{"tier":"live","target_types":["group","community"]},"member_add_mode":{"tier":"partial_contract","target_types":["group","community"]},"ephemeral":{"tier":"live","target_types":["group","community"]}}},"setup_pause_defaults":{"type":"object","additionalProperties":false,"required":["default_seconds","jitter_seconds","max_seconds"],"description":"Server defaults and operator bounds for setup pacing. Jitter is added only to positive pauses.","properties":{"default_seconds":{"type":"integer","minimum":0,"description":"Base pause inherited when no override is set.","example":3},"jitter_seconds":{"type":"integer","minimum":0,"description":"Maximum random delay added to a positive base pause.","example":2},"max_seconds":{"type":"integer","minimum":0,"description":"Maximum configurable base pause before jitter.","example":60}},"example":{"default_seconds":3,"jitter_seconds":2,"max_seconds":60}},"id":{"type":"integer","example":22},"account_id":{"type":"integer","example":1},"name":{"type":"string","example":"October launch"},"slug":{"type":"string","example":"october-launch"},"public_path":{"type":"string","example":"/g/october-launch"},"inbox_id":{"type":"integer","example":6},"logical_inbox_id":{"type":"integer","description":"Present when the visible logical inbox differs from the transport inbox.","example":15},"launch_id":{"type":["integer","null"],"example":null},"target_type":{"type":"string","enum":["community","group","channel"],"example":"group"},"join_mode":{"type":"string","enum":["invite_link","direct_add","both"],"example":"invite_link"},"capacity_per_unit":{"type":"integer","minimum":1,"maximum":1023,"example":256},"community_jid":{"type":["string","null"],"example":null},"channel_jid":{"type":["string","null"],"example":null},"naming_template":{"type":"string","example":"Launch group {n}"},"welcome_message":{"type":["string","null"],"example":null},"status":{"type":"string","enum":["draft","active","paused","completed"],"example":"draft"},"settings":{"type":"object","additionalProperties":true,"description":"Operator configuration excluding system-owned diagnostics; other configuration keys are preserved.","properties":{"join_approval":{"type":["boolean","null"],"enum":[true,false,null],"description":"Require administrator approval to join. Null inherits WhatsApp. New or changed non-null values require a live capability tier for the destination. An unchanged saved value is accepted on update when the destination stays the same.","example":null},"join_approval_policy":{"type":["string","null"],"enum":["manual","all_while_seats",null],"description":"Null defaults effectively to all_while_seats when join_approval is true. A new or changed non-null policy requires a live join_approval capability tier for the destination. An unchanged saved policy is accepted on update when the destination stays the same. Manual only counts pending requests.","example":null},"locked":{"type":["boolean","null"],"enum":[true,false,null],"description":"Restrict group information edits to administrators. Explicit null keeps WhatsApp's existing setting. Omission follows the rules described for each operation.","example":true},"member_add_mode":{"type":["string","null"],"enum":["admin_add","all_member_add",null],"description":"Who may add members. Null inherits WhatsApp. New or changed non-null values require a live capability tier for the destination. An unchanged saved value is accepted on update when the destination stays the same.","example":null},"ephemeral_seconds":{"type":["integer","null"],"enum":[0,86400,604800,7776000,null],"description":"Disappearing-message duration in seconds; zero disables the timer and null inherits WhatsApp.","example":86400},"setup_pause_seconds":{"type":["integer","null"],"minimum":0,"maximum":60,"default":3,"description":"Base delay between setup delegations, plus zero to two seconds of jitter. Zero disables pauses; null uses three seconds.","example":3},"identity":{"type":"object","additionalProperties":false,"required":["photo"],"properties":{"photo":{"type":"object","additionalProperties":false,"required":["mode","items","fallback"],"properties":{"mode":{"type":"string","enum":["none","single","sequence"],"example":"sequence"},"items":{"type":"array","maxItems":100,"description":"Ordered blob references. Single requires one item; none requires an empty list.","items":{"type":"object","additionalProperties":false,"required":["key","source"],"properties":{"key":{"type":"string","minLength":1,"description":"Blob id attached to this distribution.","example":"4711"},"source":{"type":"string","enum":["upload","library","url"],"example":"upload"},"media_asset_id":{"type":"integer","minimum":1,"description":"Original Library asset, when selected from the Library.","example":44}}}},"fallback":{"description":"Image used after the sequence ends or when a selected image is unavailable.","oneOf":[{"type":"object","additionalProperties":false,"required":["key","source"],"properties":{"key":{"type":"string","minLength":1,"description":"Blob id attached to this distribution.","example":"4711"},"source":{"type":"string","enum":["upload","library","url"],"example":"upload"},"media_asset_id":{"type":"integer","minimum":1,"description":"Original Library asset, when selected from the Library.","example":44}}},{"type":"null"}]}}}}},"photo_url":{"type":["string","null"],"description":"Inherited group photo link. An explicit unit photo overrides the distribution identity; without a unit override the distribution identity wins, then the inherited URL. HTTP is accepted only for an authorized image blob of this account on the canonical application origin, with a valid signed blob URL and no credentials, query or fragment. External URLs require HTTPS.","example":"https://images.example.test/legacy-cover.jpg"},"description":{"type":["string","null"],"description":"Group description; each occurrence of {n} is replaced with the unit sequence.","example":"Welcome to launch group {n}."}}},"entry_trigger_catalog":{"type":"array","description":"Complete list of selectable entry keys, shared with server validation. Text is localized for the request. Translation keys belong to the server translation catalog. Availability of a key does not guarantee an event producer, an eligible contact or an enrollment effect.","items":{"type":"object","additionalProperties":false,"required":["key","label_key","description_key","label","description"],"properties":{"key":{"type":"string","description":"A selectable launch distribution entry key backed by an enrollment consumer. Payment confirmed emissions use payment_charge.paid.","enum":["payment_charge.paid","payment_charge.overdue","crm_item.stage_changed","crm_item.stale","crm_item.won","task.overdue","task.due_soon","calendar_event.created","calendar_event.no_show","commerce.cart_abandoned","commerce.order_placed","commerce.payment_pending","commerce.payment_confirmed","commerce.payment_declined","commerce.overdue","commerce.due_soon","commerce.refunded","commerce.chargeback","commerce.subscription_late","commerce.subscription_canceled","ads.lead_captured","social.comment_captured"],"example":"payment_charge.paid"},"label_key":{"type":"string","description":"Server translation key for the label.","example":"growth.distribution.entry_triggers.events.payment_charge_paid.label"},"description_key":{"type":"string","description":"Server translation key for the description.","example":"growth.distribution.entry_triggers.events.payment_charge_paid.description"},"label":{"type":"string","description":"Localized label.","example":"Charge paid"},"description":{"type":"string","description":"Localized explanation of the entry signal.","example":"A confirmed or paid charge payment, admitted through the payment_charge.paid key."}}},"example":[{"key":"payment_charge.paid","label_key":"growth.distribution.entry_triggers.events.payment_charge_paid.label","description_key":"growth.distribution.entry_triggers.events.payment_charge_paid.description","label":"Charge paid","description":"A confirmed or paid charge payment, admitted through the payment_charge.paid key."}]},"entry_trigger_validation":{"type":"object","additionalProperties":false,"required":["valid","invalid_type","invalid_indexes"],"description":"Advisory validation of the stored entry list, without changing it. Read invalid values from settings.entry_triggers at the reported positions. A malformed non-array value has invalid_type true and no positions. An absent list is valid and equivalent to an empty list.","properties":{"valid":{"type":"boolean","example":false},"invalid_type":{"type":"boolean","example":false},"invalid_indexes":{"type":"array","description":"Zero-based positions of unknown keys or elements that are not strings.","items":{"type":"integer","minimum":0},"example":[0]}},"example":{"valid":false,"invalid_type":false,"invalid_indexes":[0]}},"configuration_options":{"type":"object","additionalProperties":false,"required":["routing_sources","template_keys"],"description":"Recognized routing sources and stored template identifiers from the same server sets used by validation. Template membership does not imply a send: the join-template and overdue-warning selectors currently have no operational send consumer and must be presented as unavailable.","properties":{"routing_sources":{"type":"array","items":{"type":"string","enum":["link","automation","event","manual","api","follow_up"]}},"template_keys":{"type":"array","items":{"type":"string","enum":["welcome","reminder","countdown","unit_opened","waitlist_ack","removed_notice","graduated_notice"]}}},"example":{"routing_sources":["link","automation","event","manual","api","follow_up"],"template_keys":["welcome","reminder","countdown","unit_opened","waitlist_ack","removed_notice","graduated_notice"]}},"configuration_validation":{"type":"object","additionalProperties":false,"required":["valid","issues"],"description":"Diagnostics for saved and resolved choices without removing or rewriting them. Paths are relative to the settings document; inherited values also remain available in settings explanations.","properties":{"valid":{"type":"boolean","example":true},"issues":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["path","code"],"properties":{"path":{"type":"string","example":"algorithm.routing_rules[0].match.source"},"code":{"type":"string","enum":["invalid_type","unknown_choice","unknown_key"],"example":"unknown_choice"}}}}},"example":{"valid":true,"issues":[]}},"units_count":{"type":"integer","minimum":0,"example":0},"members_count":{"type":"integer","minimum":0,"example":0},"capacity_total":{"type":"integer","minimum":0,"description":"Sum of current effective capacities across all units, including explicit unit overrides.","example":0},"occupancy_total":{"type":"integer","minimum":0,"description":"Sum of the synced member count of every unit.","example":0},"awaiting_count":{"type":"integer","minimum":0,"description":"Members still pending, queued or waitlisted.","example":0},"open_unit_sequence":{"type":["integer","null"],"example":null},"closes_at":{"type":["string","null"],"format":"date-time","description":"Configured distribution closing time; null means no closing time is set.","example":null},"archived_at":{"type":["string","null"],"format":"date-time","example":null},"created_at":{"type":"string","format":"date-time","example":"2026-10-13T22:00:00Z"},"updated_at":{"type":"string","format":"date-time","example":"2026-10-13T22:00:00Z"},"slug_collision":{"type":"boolean","description":"Whether the current public slug is shared with another distribution.","example":false},"slug_retired_from":{"type":["string","null"],"description":"Former public slug retired after a collision, or null.","example":null}}}}},"example":{"payload":{"algorithm":"fill_first","opens_at":null,"fallback_distribution_id":null,"graduate_distribution_id":null,"advanced_enabled":false,"capacity_defaults":{"default":256,"maximum":1023,"effective_maximum":1023,"hard_cap":1024,"headroom":0},"community_member_limit":2000,"community_provisioning":{"state":"not_requested","error_code":null,"failed_at":null},"next_sequence":1,"effective_capacity":256,"throttle_defaults":{"second":1,"hour":240},"identity":{"mode":"sequence","items":[{"key":"4711","source":"upload","thumb_url":"https://app.example.test/rails/active_storage/representations/redirect/cover-1.jpg","available":true,"check":{"state":"ok","reason":null,"checked_at":"2026-10-14T01:00:00Z","overdue":false},"media_asset_id":44},{"key":"4712","source":"library","media_asset_id":44,"thumb_url":"","available":true,"check":{"state":"pending","reason":null,"checked_at":null,"overdue":false}}],"fallback":{"key":"4720","source":"url","thumb_url":"https://app.example.test/rails/active_storage/representations/redirect/default-cover.jpg","available":true,"check":{"state":"ok","reason":null,"checked_at":"2026-10-14T01:00:00Z","overdue":false},"media_asset_id":44},"limits":{"max_bytes":8388608,"max_side":4096,"max_items":100,"check_overdue_after_seconds":900,"content_types":["image/jpeg","image/png"]},"remaining_positions":2,"exhausts_at_sequence":2},"entry_trigger_catalog":[{"key":"payment_charge.paid","label_key":"growth.distribution.entry_triggers.events.payment_charge_paid.label","description_key":"growth.distribution.entry_triggers.events.payment_charge_paid.description","label":"Charge paid","description":"A confirmed or paid charge payment, admitted through the payment_charge.paid key."}],"entry_trigger_validation":{"valid":true,"invalid_type":false,"invalid_indexes":[]},"configuration_options":{"routing_sources":["link","automation","event","manual","api","follow_up"],"template_keys":["welcome","reminder","countdown","unit_opened","waitlist_ack","removed_notice","graduated_notice"]},"configuration_validation":{"valid":true,"issues":[{"path":"algorithm.routing_rules[0].match.source","code":"unknown_choice"}]},"setup_capabilities":{"join_approval":{"tier":"partial_contract","target_types":["group","community"]},"locked":{"tier":"live","target_types":["group","community"]},"member_add_mode":{"tier":"partial_contract","target_types":["group","community"]},"ephemeral":{"tier":"live","target_types":["group","community"]}},"setup_pause_defaults":{"default_seconds":3,"jitter_seconds":2,"max_seconds":60},"id":22,"account_id":1,"name":"October launch","slug":"october-launch","public_path":"/g/october-launch","inbox_id":6,"logical_inbox_id":15,"launch_id":null,"target_type":"group","join_mode":"invite_link","capacity_per_unit":256,"community_jid":null,"channel_jid":null,"naming_template":"Launch group {n}","welcome_message":null,"status":"draft","settings":{"locked":true,"ephemeral_seconds":86400,"setup_pause_seconds":3,"description":"Welcome to launch group {n}.","photo_url":"https://images.example.test/legacy-cover.jpg","identity":{"photo":{"mode":"sequence","items":[{"key":"4711","source":"upload","media_asset_id":44},{"key":"4712","source":"library","media_asset_id":44}],"fallback":{"key":"4720","source":"url","media_asset_id":44}}},"join_approval":null,"join_approval_policy":null,"member_add_mode":null},"units_count":0,"members_count":0,"capacity_total":0,"occupancy_total":0,"awaiting_count":0,"open_unit_sequence":null,"closes_at":null,"archived_at":null,"created_at":"2026-10-13T22:00:00Z","updated_at":"2026-10-13T22:00:00Z","slug_collision":false,"slug_retired_from":null}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"422":{"description":"Invalid identity or distribution configuration; nothing is saved.","content":{"application/json":{"schema":{"oneOf":[{"type":"object","additionalProperties":false,"required":["error","keys","message","entry_trigger_validation"],"properties":{"error":{"type":"string","enum":["invalid_entry_triggers"],"example":"invalid_entry_triggers"},"keys":{"type":"array","items":{"type":"string","enum":["settings.entry_triggers"]},"example":["settings.entry_triggers"]},"message":{"type":"string","description":"Localized correction instructions.","example":"Choose entry triggers from the available list. Correct or remove unknown keys before changing that list."},"entry_trigger_validation":{"type":"object","additionalProperties":false,"required":["valid","invalid_type","invalid_indexes"],"description":"Advisory validation of the stored entry list, without changing it. Read invalid values from settings.entry_triggers at the reported positions. A malformed non-array value has invalid_type true and no positions. An absent list is valid and equivalent to an empty list.","properties":{"valid":{"type":"boolean","example":false},"invalid_type":{"type":"boolean","example":false},"invalid_indexes":{"type":"array","description":"Zero-based positions of unknown keys or elements that are not strings.","items":{"type":"integer","minimum":0},"example":[0]}},"example":{"valid":false,"invalid_type":false,"invalid_indexes":[0]}}},"example":{"error":"invalid_entry_triggers","keys":["settings.entry_triggers"],"message":"Choose entry triggers from the available list. Correct or remove unknown keys before changing that list.","entry_trigger_validation":{"valid":false,"invalid_type":false,"invalid_indexes":[0]}}},{"type":"object","additionalProperties":false,"required":["error","keys","message","configuration_validation"],"properties":{"error":{"type":"string","enum":["invalid_configuration_choices"],"example":"invalid_configuration_choices"},"keys":{"type":"array","items":{"type":"string","enum":["algorithm.routing_rules","dm_on_join.template","post_purchase.on_overdue.warn_template"]},"example":["dm_on_join.template"]},"message":{"type":"string","example":"Choose a source or template from the available list. Correct or remove unknown values before changing these fields."},"configuration_validation":{"type":"object","additionalProperties":false,"required":["valid","issues"],"description":"Diagnostics for saved and resolved choices without removing or rewriting them. Paths are relative to the settings document; inherited values also remain available in settings explanations.","properties":{"valid":{"type":"boolean","example":true},"issues":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["path","code"],"properties":{"path":{"type":"string","example":"algorithm.routing_rules[0].match.source"},"code":{"type":"string","enum":["invalid_type","unknown_choice","unknown_key"],"example":"unknown_choice"}}}}},"example":{"valid":true,"issues":[]}}}},{"type":"object","additionalProperties":false,"required":["error","setting","message"],"properties":{"error":{"type":"string","enum":["setup_capability_unavailable"],"example":"setup_capability_unavailable"},"setting":{"type":"string","enum":["join_approval","locked","member_add_mode","ephemeral_seconds"],"example":"join_approval"},"message":{"type":"string","example":"This setting cannot be used on this distribution yet."}}},{"type":"object","additionalProperties":false,"required":["error","message"],"properties":{"error":{"type":"string","enum":["identity_invalid"],"example":"identity_invalid"},"message":{"type":"string","example":"The launch group image configuration is invalid. Review the mode and selected items."}}},{"type":"object","additionalProperties":false,"required":["error","message","items"],"properties":{"error":{"type":"string","enum":["identity_image_invalid"],"example":"identity_image_invalid"},"message":{"type":"string","example":"One or more launch group images are invalid or unavailable. Review the indicated items."},"items":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["index","reason","message"],"properties":{"index":{"description":"Zero-based item position, or fallback for the fallback image.","oneOf":[{"type":"integer","minimum":0},{"type":"string","enum":["fallback"]}],"example":1},"reason":{"type":"string","enum":["type","size","dimensions","unreadable","unavailable"],"example":"size"},"message":{"type":"string","description":"Localized explanation with the applicable limit.","example":"The image must be no larger than 8 MB."}}}}}},{"type":"object","additionalProperties":false,"required":["error","keys"],"properties":{"error":{"type":"string","enum":["invalid_settings"],"example":"invalid_settings"},"keys":{"type":"array","description":"Rejected section or section.key paths of settings_overrides, in submission order without duplicates.","items":{"type":"string"},"example":["sellers.strategy"]}}},{"type":"object","additionalProperties":false,"required":["message","attributes"],"properties":{"message":{"type":"string","example":"Name cannot be blank"},"attributes":{"type":"array","description":"Distribution attributes rejected by model validation.","items":{"type":"string"},"example":["name"]}}},{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","description":"Framework message for an invalid enum value or other invalid request parameter.","example":"'unsupported' is not a valid target_type"}}}]},"examples":{"invalid_configuration_choices":{"value":{"error":"invalid_configuration_choices","keys":["dm_on_join.template"],"message":"Choose a source or template from the available list. Correct or remove unknown values before changing these fields.","configuration_validation":{"valid":false,"issues":[{"path":"dm_on_join.template","code":"unknown_choice"}]}}},"invalid_entry_triggers":{"value":{"error":"invalid_entry_triggers","keys":["settings.entry_triggers"],"message":"Choose entry triggers from the available list. Correct or remove unknown keys before changing that list.","entry_trigger_validation":{"valid":false,"invalid_type":false,"invalid_indexes":[0]}}},"setup_capability":{"value":{"error":"setup_capability_unavailable","setting":"join_approval","message":"This setting cannot be used on this distribution yet."}},"structure":{"value":{"error":"identity_invalid","message":"The launch group image configuration is invalid. Review the mode and selected items.","keys":["settings.entry_triggers"],"entry_trigger_validation":{"valid":false,"invalid_type":false,"invalid_indexes":[0]}}},"image":{"value":{"error":"identity_image_invalid","message":"One or more launch group images are invalid or unavailable. Review the indicated items.","items":[{"index":1,"reason":"size","message":"The image must be no larger than 8 MB."},{"index":"fallback","reason":"unavailable","message":"The image is unavailable. Upload another image."}]}},"invalid_settings":{"value":{"error":"invalid_settings","keys":["sellers.strategy"],"message":"Choose entry triggers from the available list. Correct or remove unknown keys before changing that list.","entry_trigger_validation":{"valid":false,"invalid_type":false,"invalid_indexes":[0]}}},"model_validation":{"value":{"message":"Name cannot be blank","attributes":["name"]}},"enum_validation":{"value":{"error":"'unsupported' is not a valid target_type","keys":["settings.entry_triggers"],"message":"Choose entry triggers from the available list. Correct or remove unknown keys before changing that list.","entry_trigger_validation":{"valid":false,"invalid_type":false,"invalid_indexes":[0]}}}}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"name":{"type":"string","example":"October launch"},"slug":{"type":"string","example":"october-launch"},"inbox_id":{"type":"integer","example":15},"launch_id":{"type":["integer","null"],"example":null},"target_type":{"type":"string","enum":["community","group","channel"],"example":"group"},"join_mode":{"type":"string","enum":["invite_link","direct_add","both"],"example":"invite_link"},"capacity_per_unit":{"type":"integer","minimum":1,"maximum":1023,"example":256},"algorithm":{"type":"string","enum":["fill_first","round_robin","random","weighted"],"description":"Distribution placement strategy.","example":"fill_first"},"opens_at":{"type":["string","null"],"format":"date-time","description":"Opening time persisted by create and update; when both are set, closes_at must be later.","example":null},"closes_at":{"type":["string","null"],"format":"date-time","description":"Closing time persisted by create and update.","example":null},"fallback_distribution_id":{"type":["integer","null"],"minimum":1,"description":"Another active, unarchived distribution of the same account used as fallback; null clears it.","example":null},"graduate_distribution_id":{"type":["integer","null"],"minimum":1,"description":"Another active, unarchived distribution of the same account that receives graduated members; null clears it.","example":null},"settings_overrides":{"type":"object","additionalProperties":false,"properties":{"capacity":{"type":"object","additionalProperties":false,"properties":{"hard_cap":{"type":["integer","null"],"minimum":1,"maximum":1024},"headroom":{"type":["integer","null"],"minimum":0,"maximum":1023,"description":"Seat margin below hard_cap; the resolved margin must remain smaller than the resolved hard cap. Null inherits."},"per_unit":{"type":["integer","null"],"minimum":1,"maximum":1023},"by_inbox":{"type":["object","null"],"additionalProperties":false},"reserve_for_waitlist":{"type":["integer","null"],"minimum":0}}},"algorithm":{"type":"object","additionalProperties":false,"properties":{"strategy":{"type":["string","null"],"enum":["fill_first","round_robin","random","weighted",null]},"weight":{"type":["integer","null"],"minimum":0},"sticky_by_contact":{"type":["boolean","null"],"enum":[true,false,null]},"routing_rules":{"anyOf":[{"type":["array","null"],"description":"Ordered rules, evaluated with equality and all conditions together. New or changed lists must use recognized condition keys and member sources; an identical legacy list may remain during an unrelated update. Null removes the override. UTM values and account labels are open values.","items":{"type":"object","required":["match"],"properties":{"match":{"type":"object","additionalProperties":false,"properties":{"utm_source":{"type":"string","description":"Compared with lead attribution, ignoring case and surrounding spaces."},"utm_campaign":{"type":"string","description":"Compared with lead attribution, ignoring case and surrounding spaces."},"tag":{"type":"string","description":"Literal label from the account label catalog."},"source":{"type":"string","enum":["link","automation","event","manual","api","follow_up"],"description":"Member entry source; null and empty values are not choices."}}},"distribution_id":{"type":"integer","minimum":1,"description":"Target distribution; skipped unless it is active and not archived in the same account."}}}},{"$ref":"#/components/schemas/json_value","description":"A previously stored JSON value may be retained only when it is exactly identical to this field or complete list in the same persisted record. Equality with persisted state is enforced at runtime and cannot be expressed by this static schema alone. A new or changed invalid value is rejected; no conversion, filtering or implicit repair is performed."}]}}},"rotation":{"type":"object","additionalProperties":false,"properties":{"batch_size":{"type":["integer","null"],"minimum":0},"warmup_ramp":{"type":["array","null"],"description":"Rotation batch steps; the latest step whose after_minutes has elapsed since creation sets the batch size.","items":{"type":"object","properties":{"after_minutes":{"type":"integer","minimum":0,"description":"Minutes after the distribution was created when the step starts."},"batch":{"type":"integer","minimum":1,"description":"Rotation batch size while the step applies; a missing or zero batch keeps the flat batch_size."}}}},"defer_base_seconds":{"type":["integer","null"],"minimum":0},"max_backoff_shift":{"type":["integer","null"],"minimum":0},"max_defer_attempts":{"type":["integer","null"],"minimum":0},"throttle":{"type":["object","null"],"additionalProperties":false,"properties":{"second":{"type":["integer","null"],"minimum":0},"hour":{"type":["integer","null"],"minimum":0}}},"sync_interval_minutes":{"type":["integer","null"],"minimum":0},"scheduler_batch_size":{"type":["integer","null"],"minimum":0}}},"fallback":{"type":"object","additionalProperties":false,"properties":{"mode":{"type":["string","null"],"enum":["url","distribution","message","waitlist",null]},"url":{"type":["string","null"],"format":"uri"},"message":{"type":["string","null"]},"distribution_id":{"type":["integer","null"],"minimum":0},"waitlist_max":{"type":["integer","null"],"minimum":0},"waitlist_ttl_hours":{"type":["integer","null"],"minimum":0},"waitlist_drain_batch":{"type":["integer","null"],"minimum":0}}},"schedule":{"type":"object","additionalProperties":false,"properties":{"opens_at":{"type":["string","null"],"format":"date-time"},"closes_at":{"type":["string","null"],"format":"date-time"},"cascade_minutes":{"type":["integer","null"],"minimum":0},"announce_when_closed":{"type":["boolean","null"],"enum":[true,false,null]},"lock_when_closed":{"type":["boolean","null"],"enum":[true,false,null]},"warmup_window_minutes":{"type":["integer","null"],"minimum":0},"timezone":{"type":"string","description":"IANA timezone identifier (e.g. \"America/Sao_Paulo\", \"UTC\"). Rails timezone names are also accepted on input; an unrecognized value is ignored in favor of the next fallback.","example":"America/Sao_Paulo"}}},"reentry":{"type":"object","additionalProperties":false,"properties":{"allow_reentry":{"type":["boolean","null"],"enum":[true,false,null]},"cooldown_hours":{"type":["integer","null"],"minimum":0},"dedupe_across_units":{"type":["boolean","null"],"enum":[true,false,null]},"use_hub_blocklist":{"type":["boolean","null"],"enum":[true,false,null]},"blacklist":{"type":["array","null"],"description":"Phone numbers refused on entry; non-digit characters are ignored.","items":{"type":["string","integer"]}},"whitelist":{"type":["array","null"],"description":"Phone numbers allowed on entry; non-digit characters are ignored.","items":{"type":["string","integer"]}},"reopen_on_leave":{"type":["boolean","null"],"enum":[true,false,null]}}},"post_purchase":{"type":"object","additionalProperties":false,"properties":{"on_paid":{"type":["object","null"],"additionalProperties":false,"properties":{"remove":{"type":["boolean","null"],"enum":[true,false,null]},"move_to_distribution_id":{"type":["integer","null"],"minimum":0},"delay_minutes":{"type":["integer","null"],"minimum":0}}},"on_overdue":{"type":["object","null"],"additionalProperties":false,"properties":{"remove":{"type":["boolean","null"],"enum":[true,false,null]},"after_days":{"type":["integer","null"],"minimum":0},"warn_template":{"anyOf":[{"type":["string","null"],"enum":["welcome","reminder","countdown","unit_opened","waitlist_ack","removed_notice","graduated_notice",null],"description":"Recognized stored template identifier. Null removes the override; an empty string is invalid. An unchanged legacy identifier may be retained on an unrelated update. This selector currently has no operational send consumer; accepting an identifier does not schedule or send a message."},{"$ref":"#/components/schemas/json_value","description":"A previously stored JSON value may be retained only when it is exactly identical to this field or complete list in the same persisted record. Equality with persisted state is enforced at runtime and cannot be expressed by this static schema alone. A new or changed invalid value is rejected; no conversion, filtering or implicit repair is performed."}]}}},"on_refund":{"type":["object","null"],"additionalProperties":false,"properties":{"remove":{"type":["boolean","null"],"enum":[true,false,null]}}},"on_chargeback":{"type":["object","null"],"additionalProperties":false,"properties":{"remove":{"type":["boolean","null"],"enum":[true,false,null]}}},"remove_batch_size":{"type":["integer","null"],"minimum":0},"remove_throttle":{"type":["object","null"],"additionalProperties":false,"properties":{"second":{"type":["integer","null"],"minimum":0},"hour":{"type":["integer","null"],"minimum":0}}}}},"sellers":{"type":"object","additionalProperties":false,"properties":{"strategy":{"type":["string","null"],"enum":["round_robin","random","weighted",null]},"list":{"type":["array","null"],"description":"Sellers rotated 1:1; each entry is read with exactly these fields.","items":{"type":"object","properties":{"phone":{"type":"string","pattern":"^[0-9]{8,15}$","description":"Seller WhatsApp number, digits only."},"name":{"type":"string","minLength":1},"weight":{"type":"integer","minimum":1},"paused":{"type":"boolean"},"user_id":{"type":["integer","null"],"description":"Agent of this account linked to the seller."},"inbox_id":{"type":["integer","null"],"description":"WhatsApp inbox of this account used for the seller."}}}},"prefill_template":{"type":["string","null"]},"daily_cap_per_seller":{"type":["integer","null"],"minimum":0},"pause_when_offline":{"type":["boolean","null"],"enum":[true,false,null]}}},"dm_on_join":{"type":"object","additionalProperties":false,"properties":{"enabled":{"type":["boolean","null"],"enum":[true,false,null]},"template":{"anyOf":[{"type":["string","null"],"enum":["welcome","reminder","countdown","unit_opened","waitlist_ack","removed_notice","graduated_notice",null],"description":"Recognized stored template identifier. Null removes the override; an empty string is invalid. An unchanged legacy identifier may be retained on an unrelated update. This selector currently has no operational send consumer; accepting an identifier does not schedule or send a message."},{"$ref":"#/components/schemas/json_value","description":"A previously stored JSON value may be retained only when it is exactly identical to this field or complete list in the same persisted record. Equality with persisted state is enforced at runtime and cannot be expressed by this static schema alone. A new or changed invalid value is rejected; no conversion, filtering or implicit repair is performed."}]},"spintax":{"type":["array","null"],"description":"Message variants; one is picked at random per send and blank entries are dropped.","items":{"type":"string"}},"delay_seconds":{"type":["object","null"],"additionalProperties":false,"properties":{"min":{"type":["integer","null"],"minimum":0},"max":{"type":["integer","null"],"minimum":0}}},"per_hour_limit":{"type":["integer","null"],"minimum":0},"inbox_id":{"type":["integer","null"],"minimum":0},"fallback_inbox_id":{"type":["integer","null"],"minimum":0},"mode":{"type":["string","null"],"enum":["fixed","generative",null]},"brief":{"type":["string","null"]},"skip_if_conversation_open":{"type":["boolean","null"],"enum":[true,false,null]}}},"templates":{"type":"object","additionalProperties":false,"properties":{"welcome":{"type":["object","null"],"additionalProperties":false,"properties":{"text":{"type":["string","null"]},"spintax":{"type":["array","null"],"description":"Message variants; one is picked at random per send and blank entries are dropped.","items":{"type":"string"}},"media_url":{"type":["string","null"],"format":"uri"}}},"reminder":{"type":["object","null"],"additionalProperties":false,"properties":{"i18n_key":{"type":["string","null"]},"text":{"type":["string","null"]},"spintax":{"type":["array","null"],"description":"Message variants; one is picked at random per send and blank entries are dropped.","items":{"type":"string"}},"media_url":{"type":["string","null"],"format":"uri"}}},"countdown":{"type":["object","null"],"additionalProperties":false,"properties":{"i18n_key":{"type":["string","null"]},"text":{"type":["string","null"]},"spintax":{"type":["array","null"],"description":"Message variants; one is picked at random per send and blank entries are dropped.","items":{"type":"string"}},"media_url":{"type":["string","null"],"format":"uri"}}},"unit_opened":{"type":["object","null"],"additionalProperties":false,"properties":{"i18n_key":{"type":["string","null"]},"text":{"type":["string","null"]},"spintax":{"type":["array","null"],"description":"Message variants; one is picked at random per send and blank entries are dropped.","items":{"type":"string"}},"media_url":{"type":["string","null"],"format":"uri"}}},"waitlist_ack":{"type":["object","null"],"additionalProperties":false,"properties":{"i18n_key":{"type":["string","null"]},"text":{"type":["string","null"]},"spintax":{"type":["array","null"],"description":"Message variants; one is picked at random per send and blank entries are dropped.","items":{"type":"string"}},"media_url":{"type":["string","null"],"format":"uri"}}},"removed_notice":{"type":["object","null"],"additionalProperties":false,"properties":{"i18n_key":{"type":["string","null"]},"text":{"type":["string","null"]},"spintax":{"type":["array","null"],"description":"Message variants; one is picked at random per send and blank entries are dropped.","items":{"type":"string"}},"media_url":{"type":["string","null"],"format":"uri"}}},"graduated_notice":{"type":["object","null"],"additionalProperties":false,"properties":{"i18n_key":{"type":["string","null"]},"text":{"type":["string","null"]},"spintax":{"type":["array","null"],"description":"Message variants; one is picked at random per send and blank entries are dropped.","items":{"type":"string"}},"media_url":{"type":["string","null"],"format":"uri"}}}}},"branding":{"type":"object","additionalProperties":false,"properties":{"naming_template":{"type":["string","null"]},"photo_url":{"type":["string","null"],"format":"uri","description":"Null removes the override. An explicit unit photo overrides distribution identity, then identity overrides the inherited URL. External URLs require HTTPS. HTTP is accepted only for an authorized account-owned image blob on the canonical application origin with a valid signed blob URL and no credentials, query or fragment."},"description":{"type":["string","null"]},"admins":{"type":["array","null"],"description":"Group admins promoted on provisioning; a value with @ is a WhatsApp JID, otherwise a phone whose non-digits are ignored.","items":{"type":"string"}},"announcement_group":{"type":["boolean","null"],"enum":[true,false,null]},"auto_create_channel":{"type":["boolean","null"],"enum":[true,false,null]},"auto_create_channel_live":{"type":["boolean","null"],"enum":[true,false,null]},"channel_invite_url":{"type":["string","null"],"format":"uri"}}},"attribution":{"type":"object","additionalProperties":false,"properties":{"utm_capture":{"type":["boolean","null"],"enum":[true,false,null]},"store_referrer_host":{"type":["boolean","null"],"enum":[true,false,null]},"store_ip_hash":{"type":["boolean","null"],"enum":[true,false,null]},"capi":{"type":["object","null"],"additionalProperties":false,"properties":{"on_click":{"type":["string","null"]},"on_join":{"type":["string","null"]},"on_purchase":{"type":["string","null"]}}},"contact_attribute_key":{"type":["string","null"]}}},"api":{"type":"object","additionalProperties":false,"properties":{"bulk_enroll_max":{"type":["integer","null"],"minimum":0},"index_page_size":{"type":["integer","null"],"minimum":0},"approvals_timeout_seconds":{"type":["integer","null"],"minimum":0},"public_link_rate_per_minute":{"type":["integer","null"],"minimum":0},"export_row_limit":{"type":["integer","null"],"minimum":0}}},"join_approval":{"type":"object","additionalProperties":false,"properties":{"batch":{"type":["integer","null"],"minimum":0},"policy":{"type":["string","null"]}}},"setup":{"type":"object","additionalProperties":false,"properties":{"pause_seconds":{"type":["integer","null"],"minimum":0,"maximum":60},"pause_jitter_seconds":{"type":["integer","null"],"minimum":0},"pause_max_seconds":{"type":["integer","null"],"minimum":0}}}}},"naming_template":{"type":"string","example":"Launch group {n}"},"welcome_message":{"type":["string","null"],"example":null},"community_jid":{"type":["string","null"],"example":null},"channel_jid":{"type":["string","null"],"example":null},"settings":{"type":"object","additionalProperties":true,"description":"Operator configuration. No settings.locked default is injected by update. Omit identity to retain legacy photo_url behavior. Identity overrides photo_url without removing that link. New images must have JPEG or PNG signatures, be at most 8 MB, and have no side over 4096 pixels when dimensions are found in the initial 256 KiB. Accepted images start pending full verification. Existing keys must belong to this distribution. With the same destination, only birth settings whose values differ from the saved configuration require a live capability tier; unchanged saved legacy values are accepted. When the destination changes, all non-null birth settings in the effective configuration require a live capability for the new destination. Omitted or null settings retain the saved configuration; a non-null document replaces it. Other configuration keys are accepted. The legacy JSON alternatives are conditional on exact equality with saved values. This runtime guard permits an unchanged null, string, object or malformed list; it never permits a new or changed invalid entry-trigger list or configuration choice.","properties":{"join_approval":{"type":["boolean","null"],"enum":[true,false,null],"description":"Require administrator approval to join. Null inherits WhatsApp. New or changed non-null values require a live capability tier for the destination. An unchanged saved value is accepted on update when the destination stays the same.","example":null},"join_approval_policy":{"type":["string","null"],"enum":["manual","all_while_seats",null],"description":"Null defaults effectively to all_while_seats when join_approval is true. A new or changed non-null policy requires a live join_approval capability tier for the destination. An unchanged saved policy is accepted on update when the destination stays the same. Manual only counts pending requests.","example":null},"locked":{"type":["boolean","null"],"enum":[true,false,null],"description":"Restrict group information edits to administrators. Explicit null keeps WhatsApp's existing setting. Omission follows the rules described for each operation.","example":true},"member_add_mode":{"type":["string","null"],"enum":["admin_add","all_member_add",null],"description":"Who may add members. Null inherits WhatsApp. New or changed non-null values require a live capability tier for the destination. An unchanged saved value is accepted on update when the destination stays the same.","example":null},"ephemeral_seconds":{"type":["integer","null"],"enum":[0,86400,604800,7776000,null],"description":"Disappearing-message duration in seconds; zero disables the timer and null inherits WhatsApp.","example":86400},"setup_pause_seconds":{"type":["integer","null"],"minimum":0,"maximum":60,"default":3,"description":"Base delay between setup delegations, plus zero to two seconds of jitter. Zero disables pauses; null uses three seconds.","example":3},"identity":{"type":"object","additionalProperties":false,"required":["photo"],"properties":{"photo":{"type":"object","additionalProperties":false,"required":["mode","items"],"properties":{"mode":{"type":"string","enum":["none","single","sequence"],"example":"sequence"},"items":{"type":"array","maxItems":100,"description":"Position n belongs to unit sequence n. Single requires one item; none requires an empty list.","items":{"oneOf":[{"type":"object","additionalProperties":false,"required":["key"],"properties":{"key":{"type":"string","minLength":1,"description":"Blob id already attached to this distribution.","example":"4711"},"source":{"type":"string","enum":["upload","library","url"],"example":"upload"},"media_asset_id":{"type":"integer","minimum":1,"example":44}}},{"type":"object","additionalProperties":false,"required":["signed_id","source"],"properties":{"signed_id":{"type":"string","minLength":1,"description":"Account-owned signed blob_id returned by the existing upload endpoint.","example":"eyJfcmFpbHMiOnsibWVzc2FnZSI6Ik5EY3hNUT09In19--signed-blob-reference"},"source":{"type":"string","enum":["upload","url"],"example":"upload"}}},{"type":"object","additionalProperties":false,"required":["media_asset_id"],"properties":{"media_asset_id":{"description":"Available, unarchived Library asset belonging to the current account.","oneOf":[{"type":"integer","minimum":1},{"type":"string","pattern":"^[1-9][0-9]*$"}],"example":44},"source":{"type":"string","enum":["library"],"example":"library"}}}]}},"fallback":{"description":"Optional fallback image. Null means no fallback.","oneOf":[{"oneOf":[{"type":"object","additionalProperties":false,"required":["key"],"properties":{"key":{"type":"string","minLength":1,"description":"Blob id already attached to this distribution.","example":"4711"},"source":{"type":"string","enum":["upload","library","url"],"example":"upload"},"media_asset_id":{"type":"integer","minimum":1,"example":44}}},{"type":"object","additionalProperties":false,"required":["signed_id","source"],"properties":{"signed_id":{"type":"string","minLength":1,"description":"Account-owned signed blob_id returned by the existing upload endpoint.","example":"eyJfcmFpbHMiOnsibWVzc2FnZSI6Ik5EY3hNUT09In19--signed-blob-reference"},"source":{"type":"string","enum":["upload","url"],"example":"upload"}}},{"type":"object","additionalProperties":false,"required":["media_asset_id"],"properties":{"media_asset_id":{"description":"Available, unarchived Library asset belonging to the current account.","oneOf":[{"type":"integer","minimum":1},{"type":"string","pattern":"^[1-9][0-9]*$"}],"example":44},"source":{"type":"string","enum":["library"],"example":"library"}}}]},{"type":"null"}]}}}}},"entry_triggers":{"description":"Catalog keys for new lists, or the exact unchanged legacy value already saved on this distribution.","examples":[null,"legacy.payment",{"legacy":true},["legacy.payment"]],"anyOf":[{"type":"array","description":"Selected entry keys. An empty list disables automatic entry. New configurations and changed lists accept only catalog keys. An unchanged legacy value can be retained during an unrelated update; repair or remove invalid values explicitly before changing that list.","items":{"type":"string","description":"A selectable launch distribution entry key backed by an enrollment consumer. Payment confirmed emissions use payment_charge.paid.","enum":["payment_charge.paid","payment_charge.overdue","crm_item.stage_changed","crm_item.stale","crm_item.won","task.overdue","task.due_soon","calendar_event.created","calendar_event.no_show","commerce.cart_abandoned","commerce.order_placed","commerce.payment_pending","commerce.payment_confirmed","commerce.payment_declined","commerce.overdue","commerce.due_soon","commerce.refunded","commerce.chargeback","commerce.subscription_late","commerce.subscription_canceled","ads.lead_captured","social.comment_captured"],"example":"payment_charge.paid"},"example":["payment_charge.paid","commerce.payment_confirmed"]},{"$ref":"#/components/schemas/json_value","description":"A previously stored JSON value may be retained only when it is exactly identical to this field or complete list in the same persisted record. Equality with persisted state is enforced at runtime and cannot be expressed by this static schema alone. A new or changed invalid value is rejected; no conversion, filtering or implicit repair is performed."}]},"algorithm":{"anyOf":[{"type":["object","null"],"additionalProperties":true,"description":"Raw placement configuration; unrelated keys remain unchanged.","properties":{"routing_rules":{"anyOf":[{"type":["array","null"],"description":"Ordered rules, evaluated with equality and all conditions together. New or changed lists must use recognized condition keys and member sources; an identical legacy list may remain during an unrelated update. Null removes the override. UTM values and account labels are open values.","items":{"type":"object","required":["match"],"properties":{"match":{"type":"object","additionalProperties":false,"properties":{"utm_source":{"type":"string","description":"Compared with lead attribution, ignoring case and surrounding spaces."},"utm_campaign":{"type":"string","description":"Compared with lead attribution, ignoring case and surrounding spaces."},"tag":{"type":"string","description":"Literal label from the account label catalog."},"source":{"type":"string","enum":["link","automation","event","manual","api","follow_up"],"description":"Member entry source; null and empty values are not choices."}}},"distribution_id":{"type":"integer","minimum":1,"description":"Target distribution; skipped unless it is active and not archived in the same account."}}}},{"$ref":"#/components/schemas/json_value","description":"A previously stored JSON value may be retained only when it is exactly identical to this field or complete list in the same persisted record. Equality with persisted state is enforced at runtime and cannot be expressed by this static schema alone. A new or changed invalid value is rejected; no conversion, filtering or implicit repair is performed."}]}}},{"$ref":"#/components/schemas/json_value","description":"A previously stored JSON value may be retained only when it is exactly identical to this field or complete list in the same persisted record. Equality with persisted state is enforced at runtime and cannot be expressed by this static schema alone. A new or changed invalid value is rejected; no conversion, filtering or implicit repair is performed."}]},"dm_on_join":{"anyOf":[{"type":["object","null"],"additionalProperties":true,"description":"Raw join-message configuration; membership does not imply a send.","properties":{"template":{"anyOf":[{"type":["string","null"],"enum":["welcome","reminder","countdown","unit_opened","waitlist_ack","removed_notice","graduated_notice",null],"description":"Recognized stored template identifier. Null removes the override; an empty string is invalid. An unchanged legacy identifier may be retained on an unrelated update. This selector currently has no operational send consumer; accepting an identifier does not schedule or send a message."},{"$ref":"#/components/schemas/json_value","description":"A previously stored JSON value may be retained only when it is exactly identical to this field or complete list in the same persisted record. Equality with persisted state is enforced at runtime and cannot be expressed by this static schema alone. A new or changed invalid value is rejected; no conversion, filtering or implicit repair is performed."}]}}},{"$ref":"#/components/schemas/json_value","description":"A previously stored JSON value may be retained only when it is exactly identical to this field or complete list in the same persisted record. Equality with persisted state is enforced at runtime and cannot be expressed by this static schema alone. A new or changed invalid value is rejected; no conversion, filtering or implicit repair is performed."}]},"post_purchase":{"anyOf":[{"type":["object","null"],"additionalProperties":true,"description":"Raw post-purchase configuration with preserved unrelated keys.","properties":{"on_overdue":{"anyOf":[{"type":["object","null"],"additionalProperties":true,"description":"Overdue settings; the warning-template selector has no send consumer.","properties":{"warn_template":{"anyOf":[{"type":["string","null"],"enum":["welcome","reminder","countdown","unit_opened","waitlist_ack","removed_notice","graduated_notice",null],"description":"Recognized stored template identifier. Null removes the override; an empty string is invalid. An unchanged legacy identifier may be retained on an unrelated update. This selector currently has no operational send consumer; accepting an identifier does not schedule or send a message."},{"$ref":"#/components/schemas/json_value","description":"A previously stored JSON value may be retained only when it is exactly identical to this field or complete list in the same persisted record. Equality with persisted state is enforced at runtime and cannot be expressed by this static schema alone. A new or changed invalid value is rejected; no conversion, filtering or implicit repair is performed."}]}}},{"$ref":"#/components/schemas/json_value","description":"A previously stored JSON value may be retained only when it is exactly identical to this field or complete list in the same persisted record. Equality with persisted state is enforced at runtime and cannot be expressed by this static schema alone. A new or changed invalid value is rejected; no conversion, filtering or implicit repair is performed."}]}}},{"$ref":"#/components/schemas/json_value","description":"A previously stored JSON value may be retained only when it is exactly identical to this field or complete list in the same persisted record. Equality with persisted state is enforced at runtime and cannot be expressed by this static schema alone. A new or changed invalid value is rejected; no conversion, filtering or implicit repair is performed."}]},"photo_url":{"type":["string","null"],"description":"Inherited photo URL. An explicit unit photo overrides distribution identity, then identity overrides the inherited URL. External URLs require HTTPS; HTTP is accepted only for an authorized image blob of this account on the canonical application origin with a valid signed blob URL and no credentials, query or fragment. Null removes the override.","example":"https://images.example.test/legacy-cover.jpg"},"description":{"type":["string","null"],"example":"Welcome to launch group {n}."}}}}},"example":{"algorithm":"round_robin","opens_at":"2026-10-20T12:00:00Z","closes_at":"2026-10-31T23:59:00Z","fallback_distribution_id":42,"graduate_distribution_id":null,"settings_overrides":{"algorithm":{"routing_rules":null,"strategy":"fill_first","weight":1,"sticky_by_contact":true},"dm_on_join":{"mode":"generative","enabled":true,"template":"welcome","spintax":["sample spintax"],"delay_seconds":{"min":1,"max":1},"per_hour_limit":1,"inbox_id":1,"fallback_inbox_id":1,"brief":"sample brief","skip_if_conversation_open":true},"capacity":{"hard_cap":1,"headroom":1,"per_unit":1,"by_inbox":{},"reserve_for_waitlist":1},"rotation":{"batch_size":1,"warmup_ramp":[{"after_minutes":60,"batch":1}],"defer_base_seconds":60,"max_backoff_shift":1,"max_defer_attempts":1,"throttle":{"second":1,"hour":1},"sync_interval_minutes":60,"scheduler_batch_size":1},"fallback":{"mode":"url","url":"https://example.com/resource","message":"Sample message text.","distribution_id":1,"waitlist_max":1,"waitlist_ttl_hours":1,"waitlist_drain_batch":1},"schedule":{"opens_at":"2026-01-15T10:30:00.000Z","closes_at":"2026-01-15T10:30:00.000Z","cascade_minutes":60,"announce_when_closed":true,"lock_when_closed":true,"warmup_window_minutes":60,"timezone":"America/Sao_Paulo"},"reentry":{"allow_reentry":true,"cooldown_hours":1,"dedupe_across_units":true,"use_hub_blocklist":true,"blacklist":["sample blacklist"],"whitelist":["sample whitelist"],"reopen_on_leave":true},"post_purchase":{"on_paid":{"remove":true,"move_to_distribution_id":1,"delay_minutes":60},"on_overdue":{"remove":true,"after_days":7,"warn_template":"welcome"},"on_refund":{"remove":true},"on_chargeback":{"remove":true},"remove_batch_size":1,"remove_throttle":{"second":1,"hour":1}},"sellers":{"strategy":"round_robin","list":[{"phone":"+5511999998888","name":"Sample Name","weight":1,"paused":true,"user_id":1,"inbox_id":1}],"prefill_template":"sample prefill template","daily_cap_per_seller":1,"pause_when_offline":true},"templates":{"welcome":{"text":"sample text","spintax":["sample spintax"],"media_url":"https://example.com/resource"},"reminder":{"i18n_key":"sample-token","text":"sample text","spintax":["sample spintax"],"media_url":"https://example.com/resource"},"countdown":{"i18n_key":"sample-token","text":"sample text","spintax":["sample spintax"],"media_url":"https://example.com/resource"},"unit_opened":{"i18n_key":"sample-token","text":"sample text","spintax":["sample spintax"],"media_url":"https://example.com/resource"},"waitlist_ack":{"i18n_key":"sample-token","text":"sample text","spintax":["sample spintax"],"media_url":"https://example.com/resource"},"removed_notice":{"i18n_key":"sample-token","text":"sample text","spintax":["sample spintax"],"media_url":"https://example.com/resource"},"graduated_notice":{"i18n_key":"sample-token","text":"sample text","spintax":["sample spintax"],"media_url":"https://example.com/resource"}},"branding":{"naming_template":"sample naming template","photo_url":"https://example.com/resource","description":"A short description.","admins":["sample admin"],"announcement_group":true,"auto_create_channel":true,"auto_create_channel_live":true,"channel_invite_url":"https://example.com/resource"},"attribution":{"utm_capture":true,"store_referrer_host":true,"store_ip_hash":true,"capi":{"on_click":"sample on click","on_join":"sample on join","on_purchase":"sample on purchase"},"contact_attribute_key":"sample-token"},"api":{"bulk_enroll_max":1,"index_page_size":1,"approvals_timeout_seconds":60,"public_link_rate_per_minute":1,"export_row_limit":1},"join_approval":{"batch":1,"policy":"sample policy"},"setup":{"pause_seconds":60,"pause_jitter_seconds":60,"pause_max_seconds":60}},"settings":{"entry_triggers":[],"description":"Welcome to launch group {n}.","identity":{"photo":{"mode":"sequence","items":[{"key":"4712","source":"upload","media_asset_id":44},{"key":"4711","source":"upload","media_asset_id":44}],"fallback":{"key":"4720","source":"upload","media_asset_id":44}}},"join_approval":null,"join_approval_policy":null,"locked":true,"member_add_mode":null,"ephemeral_seconds":86400,"setup_pause_seconds":3,"algorithm":{"routing_rules":[{"match":{"utm_source":"sample utm source","utm_campaign":"sample utm campaign","tag":"sample tag","source":"link"},"distribution_id":1}]},"dm_on_join":{"template":"welcome"},"post_purchase":{"on_overdue":{"warn_template":"welcome"}},"photo_url":"https://images.example.test/legacy-cover.jpg"},"name":"October launch","slug":"october-launch","inbox_id":15,"launch_id":null,"target_type":"group","join_mode":"invite_link","capacity_per_unit":256,"naming_template":"Launch group {n}","welcome_message":null,"community_jid":null,"channel_jid":null}}}}},"put":{"tags":["Growth Distribution"],"operationId":"auto_put_api_v1_accounts_account_id_growth_distributions_id","summary":"Update a launch distribution","description":"Resolves and validates identity under the distribution row lock, preserving system diagnostics, rotation inboxes and retired-address metadata. All image errors are returned together. A refused save persists neither settings nor attachments. Unreferenced attachments are detached only after a successful save; a shared Library blob survives. Existing image keys can be repeated or reordered. No settings.locked default is injected by update, for any destination. When settings is omitted or null, the saved configuration is retained; a non-null document replaces the operator configuration. Explicit locked true, false or null is preserved; null keeps WhatsApp's existing setting. A switch to channel validates the effective configuration against its available capabilities. With the same destination, only changed birth settings are checked for live support; an unchanged saved legacy value may be resubmitted. When the destination changes, all non-null birth settings in the effective configuration require a live capability for the new destination. A changed entry-trigger list must use catalog keys. An unchanged legacy list can be retained during an unrelated edit; the response diagnoses invalid saved positions without removing them.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Launch distribution with stored configuration and the current identity projection.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["payload"],"properties":{"payload":{"type":"object","additionalProperties":false,"required":["id","account_id","name","slug","public_path","inbox_id","launch_id","target_type","join_mode","capacity_per_unit","algorithm","opens_at","fallback_distribution_id","graduate_distribution_id","advanced_enabled","capacity_defaults","community_member_limit","community_provisioning","setup_capabilities","setup_pause_defaults","next_sequence","effective_capacity","throttle_defaults","identity","community_jid","channel_jid","naming_template","welcome_message","status","settings","entry_trigger_catalog","entry_trigger_validation","configuration_options","configuration_validation","units_count","members_count","open_unit_sequence","closes_at","archived_at","created_at","updated_at","slug_collision","slug_retired_from"],"properties":{"algorithm":{"type":"string","enum":["fill_first","round_robin","random","weighted"],"example":"fill_first"},"opens_at":{"type":["string","null"],"format":"date-time","description":"Distribution opening time, when configured.","example":null},"fallback_distribution_id":{"type":["integer","null"],"example":null},"graduate_distribution_id":{"type":["integer","null"],"example":null},"advanced_enabled":{"type":"boolean","description":"Whether advanced launch distribution features are enabled for this account.","example":false},"capacity_defaults":{"type":"object","additionalProperties":false,"required":["default","maximum","effective_maximum","hard_cap","headroom"],"description":"Resolved capacity limits. On defaults, default is the account per-unit setting; on distribution resources it is the product default of 256. Effective maximum is min(1023, hard_cap minus headroom). An existing explicit per-unit setting is preserved when the account defaults change.","properties":{"default":{"type":"integer","minimum":1,"maximum":1023,"example":256},"maximum":{"type":"integer","description":"Maximum accepted capacity per launch group.","example":1023},"effective_maximum":{"type":"integer","minimum":0,"maximum":1023,"description":"Maximum after applying the resolved hard cap and explicit headroom.","example":1023},"hard_cap":{"type":"integer","minimum":1,"maximum":1024,"description":"Hard cap resolved from the account and distribution settings.","example":1024},"headroom":{"type":"integer","minimum":0,"maximum":1023,"description":"Explicit seat margin; absent overrides use the product margin of zero.","example":0}}},"community_member_limit":{"type":"integer","example":2000},"community_provisioning":{"type":"object","additionalProperties":false,"required":["state","error_code","failed_at"],"properties":{"state":{"type":"string","enum":["not_requested","pending","created","failed"],"example":"not_requested","description":"Distribution member progress state."},"error_code":{"type":["string","null"],"enum":["missing_initial_participant","outcome_uncertain","feature_not_supported","gateway_rejected","gateway_unavailable","rate_limited","setup_step_failed","setup_step_refused","setup_incomplete","creator_inbox_unavailable","group_not_admin","group_not_found",null],"example":null},"failed_at":{"type":["string","null"],"format":"date-time","example":null}}},"next_sequence":{"type":"integer","minimum":1,"example":1},"effective_capacity":{"type":"integer","minimum":0,"maximum":1023,"description":"Minimum of the configured per-unit capacity and the effective maximum after the resolved hard cap and headroom.","example":256},"throttle_defaults":{"type":"object","additionalProperties":false,"required":["second","hour"],"description":"Default outbound limits for WhatsApp Web; operator overrides are kept in settings.","properties":{"second":{"type":"integer","example":1},"hour":{"type":"integer","example":240}}},"identity":{"type":"object","additionalProperties":false,"required":["mode","items","fallback","remaining_positions","exhausts_at_sequence","limits"],"properties":{"mode":{"type":"string","enum":["none","single","sequence"],"example":"sequence"},"items":{"type":"array","maxItems":100,"items":{"type":"object","additionalProperties":false,"required":["key","source","thumb_url","available","check"],"properties":{"key":{"type":"string","minLength":1,"example":"4711"},"source":{"type":"string","enum":["upload","library","url"],"example":"upload"},"media_asset_id":{"type":"integer","minimum":1,"example":44},"thumb_url":{"type":"string","description":"Center-cropped 160 by 160 representation URL, present only after the full image check succeeded; empty while the check is pending or invalid, when the file is unavailable, or when the representation fails.","example":""},"available":{"type":"boolean","description":"Whether the blob is still attached to this distribution.","example":true},"check":{"type":"object","additionalProperties":false,"required":["state","reason","checked_at","overdue"],"properties":{"state":{"type":"string","enum":["pending","ok","invalid"],"example":"pending","description":"Distribution member progress state."},"reason":{"type":["string","null"],"enum":["type","size","dimensions","unreadable","unavailable",null],"example":null},"checked_at":{"type":["string","null"],"format":"date-time","example":null},"overdue":{"type":"boolean","description":"Pending without a check time for at least 15 minutes since attachment creation; false without the check column or attachment.","example":false}}}}}},"fallback":{"oneOf":[{"type":"object","additionalProperties":false,"required":["key","source","thumb_url","available","check"],"properties":{"key":{"type":"string","minLength":1,"example":"4711"},"source":{"type":"string","enum":["upload","library","url"],"example":"upload"},"media_asset_id":{"type":"integer","minimum":1,"example":44},"thumb_url":{"type":"string","description":"Center-cropped 160 by 160 representation URL, present only after the full image check succeeded; empty while the check is pending or invalid, when the file is unavailable, or when the representation fails.","example":""},"available":{"type":"boolean","description":"Whether the blob is still attached to this distribution.","example":true},"check":{"type":"object","additionalProperties":false,"required":["state","reason","checked_at","overdue"],"properties":{"state":{"type":"string","enum":["pending","ok","invalid"],"example":"pending","description":"Distribution member progress state."},"reason":{"type":["string","null"],"enum":["type","size","dimensions","unreadable","unavailable",null],"example":null},"checked_at":{"type":["string","null"],"format":"date-time","example":null},"overdue":{"type":"boolean","description":"Pending without a check time for at least 15 minutes since attachment creation; false without the check column or attachment.","example":false}}}}},{"type":"null"}]},"limits":{"type":"object","additionalProperties":false,"required":["max_bytes","max_side","max_items","content_types","check_overdue_after_seconds"],"properties":{"max_bytes":{"type":"integer","example":8388608},"max_side":{"type":"integer","example":4096},"max_items":{"type":"integer","example":100},"check_overdue_after_seconds":{"type":"integer","example":900},"content_types":{"type":"array","items":{"type":"string","enum":["image/jpeg","image/png"]},"example":["image/jpeg","image/png"]}}},"remaining_positions":{"type":["integer","null"],"minimum":0,"description":"Remaining own-image positions from next_sequence; null outside sequence mode.","example":2},"exhausts_at_sequence":{"type":["integer","null"],"minimum":0,"description":"Number of own-image positions; null outside sequence mode.","example":2}}},"setup_capabilities":{"type":"object","description":"Birth-setting support by step. Only live capabilities support the listed destination types; partial_contract is unavailable.","additionalProperties":{"type":"object","additionalProperties":false,"required":["tier","target_types"],"properties":{"tier":{"type":"string","enum":["live","partial_contract"]},"target_types":{"type":"array","items":{"type":"string","enum":["group","community"]}}}},"example":{"join_approval":{"tier":"partial_contract","target_types":["group","community"]},"locked":{"tier":"live","target_types":["group","community"]},"member_add_mode":{"tier":"partial_contract","target_types":["group","community"]},"ephemeral":{"tier":"live","target_types":["group","community"]}}},"setup_pause_defaults":{"type":"object","additionalProperties":false,"required":["default_seconds","jitter_seconds","max_seconds"],"description":"Server defaults and operator bounds for setup pacing. Jitter is added only to positive pauses.","properties":{"default_seconds":{"type":"integer","minimum":0,"description":"Base pause inherited when no override is set.","example":3},"jitter_seconds":{"type":"integer","minimum":0,"description":"Maximum random delay added to a positive base pause.","example":2},"max_seconds":{"type":"integer","minimum":0,"description":"Maximum configurable base pause before jitter.","example":60}},"example":{"default_seconds":3,"jitter_seconds":2,"max_seconds":60}},"id":{"type":"integer","example":22},"account_id":{"type":"integer","example":1},"name":{"type":"string","example":"October launch"},"slug":{"type":"string","example":"october-launch"},"public_path":{"type":"string","example":"/g/october-launch"},"inbox_id":{"type":"integer","example":6},"logical_inbox_id":{"type":"integer","description":"Present when the visible logical inbox differs from the transport inbox.","example":15},"launch_id":{"type":["integer","null"],"example":null},"target_type":{"type":"string","enum":["community","group","channel"],"example":"group"},"join_mode":{"type":"string","enum":["invite_link","direct_add","both"],"example":"invite_link"},"capacity_per_unit":{"type":"integer","minimum":1,"maximum":1023,"example":256},"community_jid":{"type":["string","null"],"example":null},"channel_jid":{"type":["string","null"],"example":null},"naming_template":{"type":"string","example":"Launch group {n}"},"welcome_message":{"type":["string","null"],"example":null},"status":{"type":"string","enum":["draft","active","paused","completed"],"example":"draft"},"settings":{"type":"object","additionalProperties":true,"description":"Operator configuration excluding system-owned diagnostics; other configuration keys are preserved.","properties":{"join_approval":{"type":["boolean","null"],"enum":[true,false,null],"description":"Require administrator approval to join. Null inherits WhatsApp. New or changed non-null values require a live capability tier for the destination. An unchanged saved value is accepted on update when the destination stays the same.","example":null},"join_approval_policy":{"type":["string","null"],"enum":["manual","all_while_seats",null],"description":"Null defaults effectively to all_while_seats when join_approval is true. A new or changed non-null policy requires a live join_approval capability tier for the destination. An unchanged saved policy is accepted on update when the destination stays the same. Manual only counts pending requests.","example":null},"locked":{"type":["boolean","null"],"enum":[true,false,null],"description":"Restrict group information edits to administrators. Explicit null keeps WhatsApp's existing setting. Omission follows the rules described for each operation.","example":true},"member_add_mode":{"type":["string","null"],"enum":["admin_add","all_member_add",null],"description":"Who may add members. Null inherits WhatsApp. New or changed non-null values require a live capability tier for the destination. An unchanged saved value is accepted on update when the destination stays the same.","example":null},"ephemeral_seconds":{"type":["integer","null"],"enum":[0,86400,604800,7776000,null],"description":"Disappearing-message duration in seconds; zero disables the timer and null inherits WhatsApp.","example":86400},"setup_pause_seconds":{"type":["integer","null"],"minimum":0,"maximum":60,"default":3,"description":"Base delay between setup delegations, plus zero to two seconds of jitter. Zero disables pauses; null uses three seconds.","example":3},"identity":{"type":"object","additionalProperties":false,"required":["photo"],"properties":{"photo":{"type":"object","additionalProperties":false,"required":["mode","items","fallback"],"properties":{"mode":{"type":"string","enum":["none","single","sequence"],"example":"sequence"},"items":{"type":"array","maxItems":100,"description":"Ordered blob references. Single requires one item; none requires an empty list.","items":{"type":"object","additionalProperties":false,"required":["key","source"],"properties":{"key":{"type":"string","minLength":1,"description":"Blob id attached to this distribution.","example":"4711"},"source":{"type":"string","enum":["upload","library","url"],"example":"upload"},"media_asset_id":{"type":"integer","minimum":1,"description":"Original Library asset, when selected from the Library.","example":44}}}},"fallback":{"description":"Image used after the sequence ends or when a selected image is unavailable.","oneOf":[{"type":"object","additionalProperties":false,"required":["key","source"],"properties":{"key":{"type":"string","minLength":1,"description":"Blob id attached to this distribution.","example":"4711"},"source":{"type":"string","enum":["upload","library","url"],"example":"upload"},"media_asset_id":{"type":"integer","minimum":1,"description":"Original Library asset, when selected from the Library.","example":44}}},{"type":"null"}]}}}}},"photo_url":{"type":["string","null"],"description":"Inherited group photo link. An explicit unit photo overrides the distribution identity; without a unit override the distribution identity wins, then the inherited URL. HTTP is accepted only for an authorized image blob of this account on the canonical application origin, with a valid signed blob URL and no credentials, query or fragment. External URLs require HTTPS.","example":"https://images.example.test/legacy-cover.jpg"},"description":{"type":["string","null"],"description":"Group description; each occurrence of {n} is replaced with the unit sequence.","example":"Welcome to launch group {n}."}}},"entry_trigger_catalog":{"type":"array","description":"Complete list of selectable entry keys, shared with server validation. Text is localized for the request. Translation keys belong to the server translation catalog. Availability of a key does not guarantee an event producer, an eligible contact or an enrollment effect.","items":{"type":"object","additionalProperties":false,"required":["key","label_key","description_key","label","description"],"properties":{"key":{"type":"string","description":"A selectable launch distribution entry key backed by an enrollment consumer. Payment confirmed emissions use payment_charge.paid.","enum":["payment_charge.paid","payment_charge.overdue","crm_item.stage_changed","crm_item.stale","crm_item.won","task.overdue","task.due_soon","calendar_event.created","calendar_event.no_show","commerce.cart_abandoned","commerce.order_placed","commerce.payment_pending","commerce.payment_confirmed","commerce.payment_declined","commerce.overdue","commerce.due_soon","commerce.refunded","commerce.chargeback","commerce.subscription_late","commerce.subscription_canceled","ads.lead_captured","social.comment_captured"],"example":"payment_charge.paid"},"label_key":{"type":"string","description":"Server translation key for the label.","example":"growth.distribution.entry_triggers.events.payment_charge_paid.label"},"description_key":{"type":"string","description":"Server translation key for the description.","example":"growth.distribution.entry_triggers.events.payment_charge_paid.description"},"label":{"type":"string","description":"Localized label.","example":"Charge paid"},"description":{"type":"string","description":"Localized explanation of the entry signal.","example":"A confirmed or paid charge payment, admitted through the payment_charge.paid key."}}},"example":[{"key":"payment_charge.paid","label_key":"growth.distribution.entry_triggers.events.payment_charge_paid.label","description_key":"growth.distribution.entry_triggers.events.payment_charge_paid.description","label":"Charge paid","description":"A confirmed or paid charge payment, admitted through the payment_charge.paid key."}]},"entry_trigger_validation":{"type":"object","additionalProperties":false,"required":["valid","invalid_type","invalid_indexes"],"description":"Advisory validation of the stored entry list, without changing it. Read invalid values from settings.entry_triggers at the reported positions. A malformed non-array value has invalid_type true and no positions. An absent list is valid and equivalent to an empty list.","properties":{"valid":{"type":"boolean","example":false},"invalid_type":{"type":"boolean","example":false},"invalid_indexes":{"type":"array","description":"Zero-based positions of unknown keys or elements that are not strings.","items":{"type":"integer","minimum":0},"example":[0]}},"example":{"valid":false,"invalid_type":false,"invalid_indexes":[0]}},"configuration_options":{"type":"object","additionalProperties":false,"required":["routing_sources","template_keys"],"description":"Recognized routing sources and stored template identifiers from the same server sets used by validation. Template membership does not imply a send: the join-template and overdue-warning selectors currently have no operational send consumer and must be presented as unavailable.","properties":{"routing_sources":{"type":"array","items":{"type":"string","enum":["link","automation","event","manual","api","follow_up"]}},"template_keys":{"type":"array","items":{"type":"string","enum":["welcome","reminder","countdown","unit_opened","waitlist_ack","removed_notice","graduated_notice"]}}},"example":{"routing_sources":["link","automation","event","manual","api","follow_up"],"template_keys":["welcome","reminder","countdown","unit_opened","waitlist_ack","removed_notice","graduated_notice"]}},"configuration_validation":{"type":"object","additionalProperties":false,"required":["valid","issues"],"description":"Diagnostics for saved and resolved choices without removing or rewriting them. Paths are relative to the settings document; inherited values also remain available in settings explanations.","properties":{"valid":{"type":"boolean","example":true},"issues":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["path","code"],"properties":{"path":{"type":"string","example":"algorithm.routing_rules[0].match.source"},"code":{"type":"string","enum":["invalid_type","unknown_choice","unknown_key"],"example":"unknown_choice"}}}}},"example":{"valid":true,"issues":[]}},"units_count":{"type":"integer","minimum":0,"example":0},"members_count":{"type":"integer","minimum":0,"example":0},"capacity_total":{"type":"integer","minimum":0,"description":"Sum of current effective capacities across all units, including explicit unit overrides.","example":0},"occupancy_total":{"type":"integer","minimum":0,"description":"Sum of the synced member count of every unit.","example":0},"awaiting_count":{"type":"integer","minimum":0,"description":"Members still pending, queued or waitlisted.","example":0},"open_unit_sequence":{"type":["integer","null"],"example":null},"closes_at":{"type":["string","null"],"format":"date-time","description":"Configured distribution closing time; null means no closing time is set.","example":null},"archived_at":{"type":["string","null"],"format":"date-time","example":null},"created_at":{"type":"string","format":"date-time","example":"2026-10-13T22:00:00Z"},"updated_at":{"type":"string","format":"date-time","example":"2026-10-13T22:00:00Z"},"slug_collision":{"type":"boolean","description":"Whether the current public slug is shared with another distribution.","example":false},"slug_retired_from":{"type":["string","null"],"description":"Former public slug retired after a collision, or null.","example":null}}}}},"example":{"payload":{"algorithm":"fill_first","opens_at":null,"fallback_distribution_id":null,"graduate_distribution_id":null,"advanced_enabled":false,"capacity_defaults":{"default":256,"maximum":1023,"effective_maximum":1023,"hard_cap":1024,"headroom":0},"community_member_limit":2000,"community_provisioning":{"state":"not_requested","error_code":null,"failed_at":null},"next_sequence":1,"effective_capacity":256,"throttle_defaults":{"second":1,"hour":240},"identity":{"mode":"sequence","items":[{"key":"4711","source":"upload","thumb_url":"https://app.example.test/rails/active_storage/representations/redirect/cover-1.jpg","available":true,"check":{"state":"ok","reason":null,"checked_at":"2026-10-14T01:00:00Z","overdue":false},"media_asset_id":44},{"key":"4712","source":"library","media_asset_id":44,"thumb_url":"","available":true,"check":{"state":"pending","reason":null,"checked_at":null,"overdue":false}}],"fallback":{"key":"4720","source":"url","thumb_url":"https://app.example.test/rails/active_storage/representations/redirect/default-cover.jpg","available":true,"check":{"state":"ok","reason":null,"checked_at":"2026-10-14T01:00:00Z","overdue":false},"media_asset_id":44},"limits":{"max_bytes":8388608,"max_side":4096,"max_items":100,"check_overdue_after_seconds":900,"content_types":["image/jpeg","image/png"]},"remaining_positions":2,"exhausts_at_sequence":2},"entry_trigger_catalog":[{"key":"payment_charge.paid","label_key":"growth.distribution.entry_triggers.events.payment_charge_paid.label","description_key":"growth.distribution.entry_triggers.events.payment_charge_paid.description","label":"Charge paid","description":"A confirmed or paid charge payment, admitted through the payment_charge.paid key."}],"entry_trigger_validation":{"valid":true,"invalid_type":false,"invalid_indexes":[]},"configuration_options":{"routing_sources":["link","automation","event","manual","api","follow_up"],"template_keys":["welcome","reminder","countdown","unit_opened","waitlist_ack","removed_notice","graduated_notice"]},"configuration_validation":{"valid":true,"issues":[{"path":"algorithm.routing_rules[0].match.source","code":"unknown_choice"}]},"setup_capabilities":{"join_approval":{"tier":"partial_contract","target_types":["group","community"]},"locked":{"tier":"live","target_types":["group","community"]},"member_add_mode":{"tier":"partial_contract","target_types":["group","community"]},"ephemeral":{"tier":"live","target_types":["group","community"]}},"setup_pause_defaults":{"default_seconds":3,"jitter_seconds":2,"max_seconds":60},"id":22,"account_id":1,"name":"October launch","slug":"october-launch","public_path":"/g/october-launch","inbox_id":6,"logical_inbox_id":15,"launch_id":null,"target_type":"group","join_mode":"invite_link","capacity_per_unit":256,"community_jid":null,"channel_jid":null,"naming_template":"Launch group {n}","welcome_message":null,"status":"draft","settings":{"locked":true,"ephemeral_seconds":86400,"setup_pause_seconds":3,"description":"Welcome to launch group {n}.","photo_url":"https://images.example.test/legacy-cover.jpg","identity":{"photo":{"mode":"sequence","items":[{"key":"4711","source":"upload","media_asset_id":44},{"key":"4712","source":"library","media_asset_id":44}],"fallback":{"key":"4720","source":"url","media_asset_id":44}}},"join_approval":null,"join_approval_policy":null,"member_add_mode":null},"units_count":0,"members_count":0,"capacity_total":0,"occupancy_total":0,"awaiting_count":0,"open_unit_sequence":null,"closes_at":null,"archived_at":null,"created_at":"2026-10-13T22:00:00Z","updated_at":"2026-10-13T22:00:00Z","slug_collision":false,"slug_retired_from":null}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"422":{"description":"Invalid identity or distribution configuration; nothing is saved.","content":{"application/json":{"schema":{"oneOf":[{"type":"object","additionalProperties":false,"required":["error","keys","message","entry_trigger_validation"],"properties":{"error":{"type":"string","enum":["invalid_entry_triggers"],"example":"invalid_entry_triggers"},"keys":{"type":"array","items":{"type":"string","enum":["settings.entry_triggers"]},"example":["settings.entry_triggers"]},"message":{"type":"string","description":"Localized correction instructions.","example":"Choose entry triggers from the available list. Correct or remove unknown keys before changing that list."},"entry_trigger_validation":{"type":"object","additionalProperties":false,"required":["valid","invalid_type","invalid_indexes"],"description":"Advisory validation of the stored entry list, without changing it. Read invalid values from settings.entry_triggers at the reported positions. A malformed non-array value has invalid_type true and no positions. An absent list is valid and equivalent to an empty list.","properties":{"valid":{"type":"boolean","example":false},"invalid_type":{"type":"boolean","example":false},"invalid_indexes":{"type":"array","description":"Zero-based positions of unknown keys or elements that are not strings.","items":{"type":"integer","minimum":0},"example":[0]}},"example":{"valid":false,"invalid_type":false,"invalid_indexes":[0]}}},"example":{"error":"invalid_entry_triggers","keys":["settings.entry_triggers"],"message":"Choose entry triggers from the available list. Correct or remove unknown keys before changing that list.","entry_trigger_validation":{"valid":false,"invalid_type":false,"invalid_indexes":[0]}}},{"type":"object","additionalProperties":false,"required":["error","keys","message","configuration_validation"],"properties":{"error":{"type":"string","enum":["invalid_configuration_choices"],"example":"invalid_configuration_choices"},"keys":{"type":"array","items":{"type":"string","enum":["algorithm.routing_rules","dm_on_join.template","post_purchase.on_overdue.warn_template"]},"example":["dm_on_join.template"]},"message":{"type":"string","example":"Choose a source or template from the available list. Correct or remove unknown values before changing these fields."},"configuration_validation":{"type":"object","additionalProperties":false,"required":["valid","issues"],"description":"Diagnostics for saved and resolved choices without removing or rewriting them. Paths are relative to the settings document; inherited values also remain available in settings explanations.","properties":{"valid":{"type":"boolean","example":true},"issues":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["path","code"],"properties":{"path":{"type":"string","example":"algorithm.routing_rules[0].match.source"},"code":{"type":"string","enum":["invalid_type","unknown_choice","unknown_key"],"example":"unknown_choice"}}}}},"example":{"valid":true,"issues":[]}}}},{"type":"object","additionalProperties":false,"required":["error","setting","message"],"properties":{"error":{"type":"string","enum":["setup_capability_unavailable"],"example":"setup_capability_unavailable"},"setting":{"type":"string","enum":["join_approval","locked","member_add_mode","ephemeral_seconds"],"example":"join_approval"},"message":{"type":"string","example":"This setting cannot be used on this distribution yet."}}},{"type":"object","additionalProperties":false,"required":["error","message"],"properties":{"error":{"type":"string","enum":["identity_invalid"],"example":"identity_invalid"},"message":{"type":"string","example":"The launch group image configuration is invalid. Review the mode and selected items."}}},{"type":"object","additionalProperties":false,"required":["error","message","items"],"properties":{"error":{"type":"string","enum":["identity_image_invalid"],"example":"identity_image_invalid"},"message":{"type":"string","example":"One or more launch group images are invalid or unavailable. Review the indicated items."},"items":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["index","reason","message"],"properties":{"index":{"description":"Zero-based item position, or fallback for the fallback image.","oneOf":[{"type":"integer","minimum":0},{"type":"string","enum":["fallback"]}],"example":1},"reason":{"type":"string","enum":["type","size","dimensions","unreadable","unavailable"],"example":"size"},"message":{"type":"string","description":"Localized explanation with the applicable limit.","example":"The image must be no larger than 8 MB."}}}}}},{"type":"object","additionalProperties":false,"required":["error","keys"],"properties":{"error":{"type":"string","enum":["invalid_settings"],"example":"invalid_settings"},"keys":{"type":"array","description":"Rejected section or section.key paths of settings_overrides, in submission order without duplicates.","items":{"type":"string"},"example":["sellers.strategy"]}}},{"type":"object","additionalProperties":false,"required":["message","attributes"],"properties":{"message":{"type":"string","example":"Name cannot be blank"},"attributes":{"type":"array","description":"Distribution attributes rejected by model validation.","items":{"type":"string"},"example":["name"]}}},{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","description":"Framework message for an invalid enum value or other invalid request parameter.","example":"'unsupported' is not a valid target_type"}}}]},"examples":{"invalid_configuration_choices":{"value":{"error":"invalid_configuration_choices","keys":["dm_on_join.template"],"message":"Choose a source or template from the available list. Correct or remove unknown values before changing these fields.","configuration_validation":{"valid":false,"issues":[{"path":"dm_on_join.template","code":"unknown_choice"}]}}},"invalid_entry_triggers":{"value":{"error":"invalid_entry_triggers","keys":["settings.entry_triggers"],"message":"Choose entry triggers from the available list. Correct or remove unknown keys before changing that list.","entry_trigger_validation":{"valid":false,"invalid_type":false,"invalid_indexes":[0]}}},"setup_capability":{"value":{"error":"setup_capability_unavailable","setting":"join_approval","message":"This setting cannot be used on this distribution yet."}},"structure":{"value":{"error":"identity_invalid","message":"The launch group image configuration is invalid. Review the mode and selected items.","keys":["settings.entry_triggers"],"entry_trigger_validation":{"valid":false,"invalid_type":false,"invalid_indexes":[0]}}},"image":{"value":{"error":"identity_image_invalid","message":"One or more launch group images are invalid or unavailable. Review the indicated items.","items":[{"index":1,"reason":"size","message":"The image must be no larger than 8 MB."},{"index":"fallback","reason":"unavailable","message":"The image is unavailable. Upload another image."}]}},"invalid_settings":{"value":{"error":"invalid_settings","keys":["sellers.strategy"],"message":"Choose entry triggers from the available list. Correct or remove unknown keys before changing that list.","entry_trigger_validation":{"valid":false,"invalid_type":false,"invalid_indexes":[0]}}},"model_validation":{"value":{"message":"Name cannot be blank","attributes":["name"]}},"enum_validation":{"value":{"error":"'unsupported' is not a valid target_type","keys":["settings.entry_triggers"],"message":"Choose entry triggers from the available list. Correct or remove unknown keys before changing that list.","entry_trigger_validation":{"valid":false,"invalid_type":false,"invalid_indexes":[0]}}}}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"name":{"type":"string","example":"October launch"},"slug":{"type":"string","example":"october-launch"},"inbox_id":{"type":"integer","example":15},"launch_id":{"type":["integer","null"],"example":null},"target_type":{"type":"string","enum":["community","group","channel"],"example":"group"},"join_mode":{"type":"string","enum":["invite_link","direct_add","both"],"example":"invite_link"},"capacity_per_unit":{"type":"integer","minimum":1,"maximum":1023,"example":256},"algorithm":{"type":"string","enum":["fill_first","round_robin","random","weighted"],"description":"Distribution placement strategy.","example":"fill_first"},"opens_at":{"type":["string","null"],"format":"date-time","description":"Opening time persisted by create and update; when both are set, closes_at must be later.","example":null},"closes_at":{"type":["string","null"],"format":"date-time","description":"Closing time persisted by create and update.","example":null},"fallback_distribution_id":{"type":["integer","null"],"minimum":1,"description":"Another active, unarchived distribution of the same account used as fallback; null clears it.","example":null},"graduate_distribution_id":{"type":["integer","null"],"minimum":1,"description":"Another active, unarchived distribution of the same account that receives graduated members; null clears it.","example":null},"settings_overrides":{"type":"object","additionalProperties":false,"properties":{"capacity":{"type":"object","additionalProperties":false,"properties":{"hard_cap":{"type":["integer","null"],"minimum":1,"maximum":1024},"headroom":{"type":["integer","null"],"minimum":0,"maximum":1023,"description":"Seat margin below hard_cap; the resolved margin must remain smaller than the resolved hard cap. Null inherits."},"per_unit":{"type":["integer","null"],"minimum":1,"maximum":1023},"by_inbox":{"type":["object","null"],"additionalProperties":false},"reserve_for_waitlist":{"type":["integer","null"],"minimum":0}}},"algorithm":{"type":"object","additionalProperties":false,"properties":{"strategy":{"type":["string","null"],"enum":["fill_first","round_robin","random","weighted",null]},"weight":{"type":["integer","null"],"minimum":0},"sticky_by_contact":{"type":["boolean","null"],"enum":[true,false,null]},"routing_rules":{"anyOf":[{"type":["array","null"],"description":"Ordered rules, evaluated with equality and all conditions together. New or changed lists must use recognized condition keys and member sources; an identical legacy list may remain during an unrelated update. Null removes the override. UTM values and account labels are open values.","items":{"type":"object","required":["match"],"properties":{"match":{"type":"object","additionalProperties":false,"properties":{"utm_source":{"type":"string","description":"Compared with lead attribution, ignoring case and surrounding spaces."},"utm_campaign":{"type":"string","description":"Compared with lead attribution, ignoring case and surrounding spaces."},"tag":{"type":"string","description":"Literal label from the account label catalog."},"source":{"type":"string","enum":["link","automation","event","manual","api","follow_up"],"description":"Member entry source; null and empty values are not choices."}}},"distribution_id":{"type":"integer","minimum":1,"description":"Target distribution; skipped unless it is active and not archived in the same account."}}}},{"$ref":"#/components/schemas/json_value","description":"A previously stored JSON value may be retained only when it is exactly identical to this field or complete list in the same persisted record. Equality with persisted state is enforced at runtime and cannot be expressed by this static schema alone. A new or changed invalid value is rejected; no conversion, filtering or implicit repair is performed."}]}}},"rotation":{"type":"object","additionalProperties":false,"properties":{"batch_size":{"type":["integer","null"],"minimum":0},"warmup_ramp":{"type":["array","null"],"description":"Rotation batch steps; the latest step whose after_minutes has elapsed since creation sets the batch size.","items":{"type":"object","properties":{"after_minutes":{"type":"integer","minimum":0,"description":"Minutes after the distribution was created when the step starts."},"batch":{"type":"integer","minimum":1,"description":"Rotation batch size while the step applies; a missing or zero batch keeps the flat batch_size."}}}},"defer_base_seconds":{"type":["integer","null"],"minimum":0},"max_backoff_shift":{"type":["integer","null"],"minimum":0},"max_defer_attempts":{"type":["integer","null"],"minimum":0},"throttle":{"type":["object","null"],"additionalProperties":false,"properties":{"second":{"type":["integer","null"],"minimum":0},"hour":{"type":["integer","null"],"minimum":0}}},"sync_interval_minutes":{"type":["integer","null"],"minimum":0},"scheduler_batch_size":{"type":["integer","null"],"minimum":0}}},"fallback":{"type":"object","additionalProperties":false,"properties":{"mode":{"type":["string","null"],"enum":["url","distribution","message","waitlist",null]},"url":{"type":["string","null"],"format":"uri"},"message":{"type":["string","null"]},"distribution_id":{"type":["integer","null"],"minimum":0},"waitlist_max":{"type":["integer","null"],"minimum":0},"waitlist_ttl_hours":{"type":["integer","null"],"minimum":0},"waitlist_drain_batch":{"type":["integer","null"],"minimum":0}}},"schedule":{"type":"object","additionalProperties":false,"properties":{"opens_at":{"type":["string","null"],"format":"date-time"},"closes_at":{"type":["string","null"],"format":"date-time"},"cascade_minutes":{"type":["integer","null"],"minimum":0},"announce_when_closed":{"type":["boolean","null"],"enum":[true,false,null]},"lock_when_closed":{"type":["boolean","null"],"enum":[true,false,null]},"warmup_window_minutes":{"type":["integer","null"],"minimum":0},"timezone":{"type":"string","description":"IANA timezone identifier (e.g. \"America/Sao_Paulo\", \"UTC\"). Rails timezone names are also accepted on input; an unrecognized value is ignored in favor of the next fallback.","example":"America/Sao_Paulo"}}},"reentry":{"type":"object","additionalProperties":false,"properties":{"allow_reentry":{"type":["boolean","null"],"enum":[true,false,null]},"cooldown_hours":{"type":["integer","null"],"minimum":0},"dedupe_across_units":{"type":["boolean","null"],"enum":[true,false,null]},"use_hub_blocklist":{"type":["boolean","null"],"enum":[true,false,null]},"blacklist":{"type":["array","null"],"description":"Phone numbers refused on entry; non-digit characters are ignored.","items":{"type":["string","integer"]}},"whitelist":{"type":["array","null"],"description":"Phone numbers allowed on entry; non-digit characters are ignored.","items":{"type":["string","integer"]}},"reopen_on_leave":{"type":["boolean","null"],"enum":[true,false,null]}}},"post_purchase":{"type":"object","additionalProperties":false,"properties":{"on_paid":{"type":["object","null"],"additionalProperties":false,"properties":{"remove":{"type":["boolean","null"],"enum":[true,false,null]},"move_to_distribution_id":{"type":["integer","null"],"minimum":0},"delay_minutes":{"type":["integer","null"],"minimum":0}}},"on_overdue":{"type":["object","null"],"additionalProperties":false,"properties":{"remove":{"type":["boolean","null"],"enum":[true,false,null]},"after_days":{"type":["integer","null"],"minimum":0},"warn_template":{"anyOf":[{"type":["string","null"],"enum":["welcome","reminder","countdown","unit_opened","waitlist_ack","removed_notice","graduated_notice",null],"description":"Recognized stored template identifier. Null removes the override; an empty string is invalid. An unchanged legacy identifier may be retained on an unrelated update. This selector currently has no operational send consumer; accepting an identifier does not schedule or send a message."},{"$ref":"#/components/schemas/json_value","description":"A previously stored JSON value may be retained only when it is exactly identical to this field or complete list in the same persisted record. Equality with persisted state is enforced at runtime and cannot be expressed by this static schema alone. A new or changed invalid value is rejected; no conversion, filtering or implicit repair is performed."}]}}},"on_refund":{"type":["object","null"],"additionalProperties":false,"properties":{"remove":{"type":["boolean","null"],"enum":[true,false,null]}}},"on_chargeback":{"type":["object","null"],"additionalProperties":false,"properties":{"remove":{"type":["boolean","null"],"enum":[true,false,null]}}},"remove_batch_size":{"type":["integer","null"],"minimum":0},"remove_throttle":{"type":["object","null"],"additionalProperties":false,"properties":{"second":{"type":["integer","null"],"minimum":0},"hour":{"type":["integer","null"],"minimum":0}}}}},"sellers":{"type":"object","additionalProperties":false,"properties":{"strategy":{"type":["string","null"],"enum":["round_robin","random","weighted",null]},"list":{"type":["array","null"],"description":"Sellers rotated 1:1; each entry is read with exactly these fields.","items":{"type":"object","properties":{"phone":{"type":"string","pattern":"^[0-9]{8,15}$","description":"Seller WhatsApp number, digits only."},"name":{"type":"string","minLength":1},"weight":{"type":"integer","minimum":1},"paused":{"type":"boolean"},"user_id":{"type":["integer","null"],"description":"Agent of this account linked to the seller."},"inbox_id":{"type":["integer","null"],"description":"WhatsApp inbox of this account used for the seller."}}}},"prefill_template":{"type":["string","null"]},"daily_cap_per_seller":{"type":["integer","null"],"minimum":0},"pause_when_offline":{"type":["boolean","null"],"enum":[true,false,null]}}},"dm_on_join":{"type":"object","additionalProperties":false,"properties":{"enabled":{"type":["boolean","null"],"enum":[true,false,null]},"template":{"anyOf":[{"type":["string","null"],"enum":["welcome","reminder","countdown","unit_opened","waitlist_ack","removed_notice","graduated_notice",null],"description":"Recognized stored template identifier. Null removes the override; an empty string is invalid. An unchanged legacy identifier may be retained on an unrelated update. This selector currently has no operational send consumer; accepting an identifier does not schedule or send a message."},{"$ref":"#/components/schemas/json_value","description":"A previously stored JSON value may be retained only when it is exactly identical to this field or complete list in the same persisted record. Equality with persisted state is enforced at runtime and cannot be expressed by this static schema alone. A new or changed invalid value is rejected; no conversion, filtering or implicit repair is performed."}]},"spintax":{"type":["array","null"],"description":"Message variants; one is picked at random per send and blank entries are dropped.","items":{"type":"string"}},"delay_seconds":{"type":["object","null"],"additionalProperties":false,"properties":{"min":{"type":["integer","null"],"minimum":0},"max":{"type":["integer","null"],"minimum":0}}},"per_hour_limit":{"type":["integer","null"],"minimum":0},"inbox_id":{"type":["integer","null"],"minimum":0},"fallback_inbox_id":{"type":["integer","null"],"minimum":0},"mode":{"type":["string","null"],"enum":["fixed","generative",null]},"brief":{"type":["string","null"]},"skip_if_conversation_open":{"type":["boolean","null"],"enum":[true,false,null]}}},"templates":{"type":"object","additionalProperties":false,"properties":{"welcome":{"type":["object","null"],"additionalProperties":false,"properties":{"text":{"type":["string","null"]},"spintax":{"type":["array","null"],"description":"Message variants; one is picked at random per send and blank entries are dropped.","items":{"type":"string"}},"media_url":{"type":["string","null"],"format":"uri"}}},"reminder":{"type":["object","null"],"additionalProperties":false,"properties":{"i18n_key":{"type":["string","null"]},"text":{"type":["string","null"]},"spintax":{"type":["array","null"],"description":"Message variants; one is picked at random per send and blank entries are dropped.","items":{"type":"string"}},"media_url":{"type":["string","null"],"format":"uri"}}},"countdown":{"type":["object","null"],"additionalProperties":false,"properties":{"i18n_key":{"type":["string","null"]},"text":{"type":["string","null"]},"spintax":{"type":["array","null"],"description":"Message variants; one is picked at random per send and blank entries are dropped.","items":{"type":"string"}},"media_url":{"type":["string","null"],"format":"uri"}}},"unit_opened":{"type":["object","null"],"additionalProperties":false,"properties":{"i18n_key":{"type":["string","null"]},"text":{"type":["string","null"]},"spintax":{"type":["array","null"],"description":"Message variants; one is picked at random per send and blank entries are dropped.","items":{"type":"string"}},"media_url":{"type":["string","null"],"format":"uri"}}},"waitlist_ack":{"type":["object","null"],"additionalProperties":false,"properties":{"i18n_key":{"type":["string","null"]},"text":{"type":["string","null"]},"spintax":{"type":["array","null"],"description":"Message variants; one is picked at random per send and blank entries are dropped.","items":{"type":"string"}},"media_url":{"type":["string","null"],"format":"uri"}}},"removed_notice":{"type":["object","null"],"additionalProperties":false,"properties":{"i18n_key":{"type":["string","null"]},"text":{"type":["string","null"]},"spintax":{"type":["array","null"],"description":"Message variants; one is picked at random per send and blank entries are dropped.","items":{"type":"string"}},"media_url":{"type":["string","null"],"format":"uri"}}},"graduated_notice":{"type":["object","null"],"additionalProperties":false,"properties":{"i18n_key":{"type":["string","null"]},"text":{"type":["string","null"]},"spintax":{"type":["array","null"],"description":"Message variants; one is picked at random per send and blank entries are dropped.","items":{"type":"string"}},"media_url":{"type":["string","null"],"format":"uri"}}}}},"branding":{"type":"object","additionalProperties":false,"properties":{"naming_template":{"type":["string","null"]},"photo_url":{"type":["string","null"],"format":"uri","description":"Null removes the override. An explicit unit photo overrides distribution identity, then identity overrides the inherited URL. External URLs require HTTPS. HTTP is accepted only for an authorized account-owned image blob on the canonical application origin with a valid signed blob URL and no credentials, query or fragment."},"description":{"type":["string","null"]},"admins":{"type":["array","null"],"description":"Group admins promoted on provisioning; a value with @ is a WhatsApp JID, otherwise a phone whose non-digits are ignored.","items":{"type":"string"}},"announcement_group":{"type":["boolean","null"],"enum":[true,false,null]},"auto_create_channel":{"type":["boolean","null"],"enum":[true,false,null]},"auto_create_channel_live":{"type":["boolean","null"],"enum":[true,false,null]},"channel_invite_url":{"type":["string","null"],"format":"uri"}}},"attribution":{"type":"object","additionalProperties":false,"properties":{"utm_capture":{"type":["boolean","null"],"enum":[true,false,null]},"store_referrer_host":{"type":["boolean","null"],"enum":[true,false,null]},"store_ip_hash":{"type":["boolean","null"],"enum":[true,false,null]},"capi":{"type":["object","null"],"additionalProperties":false,"properties":{"on_click":{"type":["string","null"]},"on_join":{"type":["string","null"]},"on_purchase":{"type":["string","null"]}}},"contact_attribute_key":{"type":["string","null"]}}},"api":{"type":"object","additionalProperties":false,"properties":{"bulk_enroll_max":{"type":["integer","null"],"minimum":0},"index_page_size":{"type":["integer","null"],"minimum":0},"approvals_timeout_seconds":{"type":["integer","null"],"minimum":0},"public_link_rate_per_minute":{"type":["integer","null"],"minimum":0},"export_row_limit":{"type":["integer","null"],"minimum":0}}},"join_approval":{"type":"object","additionalProperties":false,"properties":{"batch":{"type":["integer","null"],"minimum":0},"policy":{"type":["string","null"]}}},"setup":{"type":"object","additionalProperties":false,"properties":{"pause_seconds":{"type":["integer","null"],"minimum":0,"maximum":60},"pause_jitter_seconds":{"type":["integer","null"],"minimum":0},"pause_max_seconds":{"type":["integer","null"],"minimum":0}}}}},"naming_template":{"type":"string","example":"Launch group {n}"},"welcome_message":{"type":["string","null"],"example":null},"community_jid":{"type":["string","null"],"example":null},"channel_jid":{"type":["string","null"],"example":null},"settings":{"type":"object","additionalProperties":true,"description":"Operator configuration. No settings.locked default is injected by update. Omit identity to retain legacy photo_url behavior. Identity overrides photo_url without removing that link. New images must have JPEG or PNG signatures, be at most 8 MB, and have no side over 4096 pixels when dimensions are found in the initial 256 KiB. Accepted images start pending full verification. Existing keys must belong to this distribution. With the same destination, only birth settings whose values differ from the saved configuration require a live capability tier; unchanged saved legacy values are accepted. When the destination changes, all non-null birth settings in the effective configuration require a live capability for the new destination. Omitted or null settings retain the saved configuration; a non-null document replaces it. Other configuration keys are accepted. The legacy JSON alternatives are conditional on exact equality with saved values. This runtime guard permits an unchanged null, string, object or malformed list; it never permits a new or changed invalid entry-trigger list or configuration choice.","properties":{"join_approval":{"type":["boolean","null"],"enum":[true,false,null],"description":"Require administrator approval to join. Null inherits WhatsApp. New or changed non-null values require a live capability tier for the destination. An unchanged saved value is accepted on update when the destination stays the same.","example":null},"join_approval_policy":{"type":["string","null"],"enum":["manual","all_while_seats",null],"description":"Null defaults effectively to all_while_seats when join_approval is true. A new or changed non-null policy requires a live join_approval capability tier for the destination. An unchanged saved policy is accepted on update when the destination stays the same. Manual only counts pending requests.","example":null},"locked":{"type":["boolean","null"],"enum":[true,false,null],"description":"Restrict group information edits to administrators. Explicit null keeps WhatsApp's existing setting. Omission follows the rules described for each operation.","example":true},"member_add_mode":{"type":["string","null"],"enum":["admin_add","all_member_add",null],"description":"Who may add members. Null inherits WhatsApp. New or changed non-null values require a live capability tier for the destination. An unchanged saved value is accepted on update when the destination stays the same.","example":null},"ephemeral_seconds":{"type":["integer","null"],"enum":[0,86400,604800,7776000,null],"description":"Disappearing-message duration in seconds; zero disables the timer and null inherits WhatsApp.","example":86400},"setup_pause_seconds":{"type":["integer","null"],"minimum":0,"maximum":60,"default":3,"description":"Base delay between setup delegations, plus zero to two seconds of jitter. Zero disables pauses; null uses three seconds.","example":3},"identity":{"type":"object","additionalProperties":false,"required":["photo"],"properties":{"photo":{"type":"object","additionalProperties":false,"required":["mode","items"],"properties":{"mode":{"type":"string","enum":["none","single","sequence"],"example":"sequence"},"items":{"type":"array","maxItems":100,"description":"Position n belongs to unit sequence n. Single requires one item; none requires an empty list.","items":{"oneOf":[{"type":"object","additionalProperties":false,"required":["key"],"properties":{"key":{"type":"string","minLength":1,"description":"Blob id already attached to this distribution.","example":"4711"},"source":{"type":"string","enum":["upload","library","url"],"example":"upload"},"media_asset_id":{"type":"integer","minimum":1,"example":44}}},{"type":"object","additionalProperties":false,"required":["signed_id","source"],"properties":{"signed_id":{"type":"string","minLength":1,"description":"Account-owned signed blob_id returned by the existing upload endpoint.","example":"eyJfcmFpbHMiOnsibWVzc2FnZSI6Ik5EY3hNUT09In19--signed-blob-reference"},"source":{"type":"string","enum":["upload","url"],"example":"upload"}}},{"type":"object","additionalProperties":false,"required":["media_asset_id"],"properties":{"media_asset_id":{"description":"Available, unarchived Library asset belonging to the current account.","oneOf":[{"type":"integer","minimum":1},{"type":"string","pattern":"^[1-9][0-9]*$"}],"example":44},"source":{"type":"string","enum":["library"],"example":"library"}}}]}},"fallback":{"description":"Optional fallback image. Null means no fallback.","oneOf":[{"oneOf":[{"type":"object","additionalProperties":false,"required":["key"],"properties":{"key":{"type":"string","minLength":1,"description":"Blob id already attached to this distribution.","example":"4711"},"source":{"type":"string","enum":["upload","library","url"],"example":"upload"},"media_asset_id":{"type":"integer","minimum":1,"example":44}}},{"type":"object","additionalProperties":false,"required":["signed_id","source"],"properties":{"signed_id":{"type":"string","minLength":1,"description":"Account-owned signed blob_id returned by the existing upload endpoint.","example":"eyJfcmFpbHMiOnsibWVzc2FnZSI6Ik5EY3hNUT09In19--signed-blob-reference"},"source":{"type":"string","enum":["upload","url"],"example":"upload"}}},{"type":"object","additionalProperties":false,"required":["media_asset_id"],"properties":{"media_asset_id":{"description":"Available, unarchived Library asset belonging to the current account.","oneOf":[{"type":"integer","minimum":1},{"type":"string","pattern":"^[1-9][0-9]*$"}],"example":44},"source":{"type":"string","enum":["library"],"example":"library"}}}]},{"type":"null"}]}}}}},"entry_triggers":{"description":"Catalog keys for new lists, or the exact unchanged legacy value already saved on this distribution.","examples":[null,"legacy.payment",{"legacy":true},["legacy.payment"]],"anyOf":[{"type":"array","description":"Selected entry keys. An empty list disables automatic entry. New configurations and changed lists accept only catalog keys. An unchanged legacy value can be retained during an unrelated update; repair or remove invalid values explicitly before changing that list.","items":{"type":"string","description":"A selectable launch distribution entry key backed by an enrollment consumer. Payment confirmed emissions use payment_charge.paid.","enum":["payment_charge.paid","payment_charge.overdue","crm_item.stage_changed","crm_item.stale","crm_item.won","task.overdue","task.due_soon","calendar_event.created","calendar_event.no_show","commerce.cart_abandoned","commerce.order_placed","commerce.payment_pending","commerce.payment_confirmed","commerce.payment_declined","commerce.overdue","commerce.due_soon","commerce.refunded","commerce.chargeback","commerce.subscription_late","commerce.subscription_canceled","ads.lead_captured","social.comment_captured"],"example":"payment_charge.paid"},"example":["payment_charge.paid","commerce.payment_confirmed"]},{"$ref":"#/components/schemas/json_value","description":"A previously stored JSON value may be retained only when it is exactly identical to this field or complete list in the same persisted record. Equality with persisted state is enforced at runtime and cannot be expressed by this static schema alone. A new or changed invalid value is rejected; no conversion, filtering or implicit repair is performed."}]},"algorithm":{"anyOf":[{"type":["object","null"],"additionalProperties":true,"description":"Raw placement configuration; unrelated keys remain unchanged.","properties":{"routing_rules":{"anyOf":[{"type":["array","null"],"description":"Ordered rules, evaluated with equality and all conditions together. New or changed lists must use recognized condition keys and member sources; an identical legacy list may remain during an unrelated update. Null removes the override. UTM values and account labels are open values.","items":{"type":"object","required":["match"],"properties":{"match":{"type":"object","additionalProperties":false,"properties":{"utm_source":{"type":"string","description":"Compared with lead attribution, ignoring case and surrounding spaces."},"utm_campaign":{"type":"string","description":"Compared with lead attribution, ignoring case and surrounding spaces."},"tag":{"type":"string","description":"Literal label from the account label catalog."},"source":{"type":"string","enum":["link","automation","event","manual","api","follow_up"],"description":"Member entry source; null and empty values are not choices."}}},"distribution_id":{"type":"integer","minimum":1,"description":"Target distribution; skipped unless it is active and not archived in the same account."}}}},{"$ref":"#/components/schemas/json_value","description":"A previously stored JSON value may be retained only when it is exactly identical to this field or complete list in the same persisted record. Equality with persisted state is enforced at runtime and cannot be expressed by this static schema alone. A new or changed invalid value is rejected; no conversion, filtering or implicit repair is performed."}]}}},{"$ref":"#/components/schemas/json_value","description":"A previously stored JSON value may be retained only when it is exactly identical to this field or complete list in the same persisted record. Equality with persisted state is enforced at runtime and cannot be expressed by this static schema alone. A new or changed invalid value is rejected; no conversion, filtering or implicit repair is performed."}]},"dm_on_join":{"anyOf":[{"type":["object","null"],"additionalProperties":true,"description":"Raw join-message configuration; membership does not imply a send.","properties":{"template":{"anyOf":[{"type":["string","null"],"enum":["welcome","reminder","countdown","unit_opened","waitlist_ack","removed_notice","graduated_notice",null],"description":"Recognized stored template identifier. Null removes the override; an empty string is invalid. An unchanged legacy identifier may be retained on an unrelated update. This selector currently has no operational send consumer; accepting an identifier does not schedule or send a message."},{"$ref":"#/components/schemas/json_value","description":"A previously stored JSON value may be retained only when it is exactly identical to this field or complete list in the same persisted record. Equality with persisted state is enforced at runtime and cannot be expressed by this static schema alone. A new or changed invalid value is rejected; no conversion, filtering or implicit repair is performed."}]}}},{"$ref":"#/components/schemas/json_value","description":"A previously stored JSON value may be retained only when it is exactly identical to this field or complete list in the same persisted record. Equality with persisted state is enforced at runtime and cannot be expressed by this static schema alone. A new or changed invalid value is rejected; no conversion, filtering or implicit repair is performed."}]},"post_purchase":{"anyOf":[{"type":["object","null"],"additionalProperties":true,"description":"Raw post-purchase configuration with preserved unrelated keys.","properties":{"on_overdue":{"anyOf":[{"type":["object","null"],"additionalProperties":true,"description":"Overdue settings; the warning-template selector has no send consumer.","properties":{"warn_template":{"anyOf":[{"type":["string","null"],"enum":["welcome","reminder","countdown","unit_opened","waitlist_ack","removed_notice","graduated_notice",null],"description":"Recognized stored template identifier. Null removes the override; an empty string is invalid. An unchanged legacy identifier may be retained on an unrelated update. This selector currently has no operational send consumer; accepting an identifier does not schedule or send a message."},{"$ref":"#/components/schemas/json_value","description":"A previously stored JSON value may be retained only when it is exactly identical to this field or complete list in the same persisted record. Equality with persisted state is enforced at runtime and cannot be expressed by this static schema alone. A new or changed invalid value is rejected; no conversion, filtering or implicit repair is performed."}]}}},{"$ref":"#/components/schemas/json_value","description":"A previously stored JSON value may be retained only when it is exactly identical to this field or complete list in the same persisted record. Equality with persisted state is enforced at runtime and cannot be expressed by this static schema alone. A new or changed invalid value is rejected; no conversion, filtering or implicit repair is performed."}]}}},{"$ref":"#/components/schemas/json_value","description":"A previously stored JSON value may be retained only when it is exactly identical to this field or complete list in the same persisted record. Equality with persisted state is enforced at runtime and cannot be expressed by this static schema alone. A new or changed invalid value is rejected; no conversion, filtering or implicit repair is performed."}]},"photo_url":{"type":["string","null"],"description":"Inherited photo URL. An explicit unit photo overrides distribution identity, then identity overrides the inherited URL. External URLs require HTTPS; HTTP is accepted only for an authorized image blob of this account on the canonical application origin with a valid signed blob URL and no credentials, query or fragment. Null removes the override.","example":"https://images.example.test/legacy-cover.jpg"},"description":{"type":["string","null"],"example":"Welcome to launch group {n}."}}}}},"example":{"algorithm":"round_robin","opens_at":"2026-10-20T12:00:00Z","closes_at":"2026-10-31T23:59:00Z","fallback_distribution_id":42,"graduate_distribution_id":null,"settings_overrides":{"algorithm":{"routing_rules":null,"strategy":"fill_first","weight":1,"sticky_by_contact":true},"dm_on_join":{"mode":"generative","enabled":true,"template":"welcome","spintax":["sample spintax"],"delay_seconds":{"min":1,"max":1},"per_hour_limit":1,"inbox_id":1,"fallback_inbox_id":1,"brief":"sample brief","skip_if_conversation_open":true},"capacity":{"hard_cap":1,"headroom":1,"per_unit":1,"by_inbox":{},"reserve_for_waitlist":1},"rotation":{"batch_size":1,"warmup_ramp":[{"after_minutes":60,"batch":1}],"defer_base_seconds":60,"max_backoff_shift":1,"max_defer_attempts":1,"throttle":{"second":1,"hour":1},"sync_interval_minutes":60,"scheduler_batch_size":1},"fallback":{"mode":"url","url":"https://example.com/resource","message":"Sample message text.","distribution_id":1,"waitlist_max":1,"waitlist_ttl_hours":1,"waitlist_drain_batch":1},"schedule":{"opens_at":"2026-01-15T10:30:00.000Z","closes_at":"2026-01-15T10:30:00.000Z","cascade_minutes":60,"announce_when_closed":true,"lock_when_closed":true,"warmup_window_minutes":60,"timezone":"America/Sao_Paulo"},"reentry":{"allow_reentry":true,"cooldown_hours":1,"dedupe_across_units":true,"use_hub_blocklist":true,"blacklist":["sample blacklist"],"whitelist":["sample whitelist"],"reopen_on_leave":true},"post_purchase":{"on_paid":{"remove":true,"move_to_distribution_id":1,"delay_minutes":60},"on_overdue":{"remove":true,"after_days":7,"warn_template":"welcome"},"on_refund":{"remove":true},"on_chargeback":{"remove":true},"remove_batch_size":1,"remove_throttle":{"second":1,"hour":1}},"sellers":{"strategy":"round_robin","list":[{"phone":"+5511999998888","name":"Sample Name","weight":1,"paused":true,"user_id":1,"inbox_id":1}],"prefill_template":"sample prefill template","daily_cap_per_seller":1,"pause_when_offline":true},"templates":{"welcome":{"text":"sample text","spintax":["sample spintax"],"media_url":"https://example.com/resource"},"reminder":{"i18n_key":"sample-token","text":"sample text","spintax":["sample spintax"],"media_url":"https://example.com/resource"},"countdown":{"i18n_key":"sample-token","text":"sample text","spintax":["sample spintax"],"media_url":"https://example.com/resource"},"unit_opened":{"i18n_key":"sample-token","text":"sample text","spintax":["sample spintax"],"media_url":"https://example.com/resource"},"waitlist_ack":{"i18n_key":"sample-token","text":"sample text","spintax":["sample spintax"],"media_url":"https://example.com/resource"},"removed_notice":{"i18n_key":"sample-token","text":"sample text","spintax":["sample spintax"],"media_url":"https://example.com/resource"},"graduated_notice":{"i18n_key":"sample-token","text":"sample text","spintax":["sample spintax"],"media_url":"https://example.com/resource"}},"branding":{"naming_template":"sample naming template","photo_url":"https://example.com/resource","description":"A short description.","admins":["sample admin"],"announcement_group":true,"auto_create_channel":true,"auto_create_channel_live":true,"channel_invite_url":"https://example.com/resource"},"attribution":{"utm_capture":true,"store_referrer_host":true,"store_ip_hash":true,"capi":{"on_click":"sample on click","on_join":"sample on join","on_purchase":"sample on purchase"},"contact_attribute_key":"sample-token"},"api":{"bulk_enroll_max":1,"index_page_size":1,"approvals_timeout_seconds":60,"public_link_rate_per_minute":1,"export_row_limit":1},"join_approval":{"batch":1,"policy":"sample policy"},"setup":{"pause_seconds":60,"pause_jitter_seconds":60,"pause_max_seconds":60}},"settings":{"entry_triggers":[],"description":"Welcome to launch group {n}.","identity":{"photo":{"mode":"sequence","items":[{"key":"4712","source":"upload","media_asset_id":44},{"key":"4711","source":"upload","media_asset_id":44}],"fallback":{"key":"4720","source":"upload","media_asset_id":44}}},"join_approval":null,"join_approval_policy":null,"locked":true,"member_add_mode":null,"ephemeral_seconds":86400,"setup_pause_seconds":3,"algorithm":{"routing_rules":[{"match":{"utm_source":"sample utm source","utm_campaign":"sample utm campaign","tag":"sample tag","source":"link"},"distribution_id":1}]},"dm_on_join":{"template":"welcome"},"post_purchase":{"on_overdue":{"warn_template":"welcome"}},"photo_url":"https://images.example.test/legacy-cover.jpg"},"name":"October launch","slug":"october-launch","inbox_id":15,"launch_id":null,"target_type":"group","join_mode":"invite_link","capacity_per_unit":256,"naming_template":"Launch group {n}","welcome_message":null,"community_jid":null,"channel_jid":null}}}}},"delete":{"tags":["Growth Distribution"],"operationId":"auto_delete_api_v1_accounts_account_id_growth_distributions_id","summary":"Delete distributions","description":"Deletes the distribution identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Success (no content)"},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/growth_social/comment_rules/{id}/toggle":{"post":{"tags":["Growth Social"],"operationId":"auto_post_api_v1_accounts_account_id_growth_social_comment_rules_id_toggle","summary":"Toggle comment rules","description":"Performs the toggle operation on the targeted comment rule resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"name":{"type":"string"},"inbox_id":{"type":"integer"},"distribution_id":{"type":"integer"},"post_id":{"type":"integer"},"post":{"type":"string"},"keyword":{"type":"string"},"keywords":{"type":"string"},"all_keywords":{"type":"string"},"trigger_type":{"type":"string","enum":["keyword","any"]},"platform":{"type":"string","enum":["any_platform","instagram","facebook"]},"match_type":{"type":"string","enum":["contains","exact","starts_with"]},"dm_template":{"type":"string"},"public_reply":{"type":"string"},"enabled":{"type":"boolean"},"settings":{"type":"object","additionalProperties":true,"description":"Rule options. The native_comment_recovery subtree is read-only; rule writes ignore it and preserve the server checkpoint.","properties":{"native_comment_recovery":{"$ref":"#/components/schemas/native_comment_recovery","readOnly":true}}},"dm_logs_count":{"type":"integer"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"example":{"id":1,"account_id":1,"name":"Sample Name","inbox_id":1,"distribution_id":1,"post_id":1,"post":"sample post","keyword":"sample keyword","keywords":"sample keywords","all_keywords":"sample all keywords","trigger_type":"keyword","platform":"any_platform","match_type":"contains","dm_template":"sample dm template","public_reply":"sample public reply","enabled":true,"settings":{"native_comment_recovery":{"actor_id":"sample actor id","inbox_id":1,"post_id":"sample post id","platform":"instagram","status":"scheduled","since":"2026-01-15T10:30:00.000Z","initial_since":"2026-01-15T10:30:00.000Z","cutoff":"2026-01-15T10:30:00.000Z","cursor":"sample cursor","pages":1,"attempts":1,"processed":1,"next_run_at":"2026-01-15T10:30:00.000Z","lease_until":"2026-01-15T10:30:00.000Z","diagnostic":{"stage":"sample stage","code":"sample code","provider_code":1,"provider_subcode":1,"provider_type":"sample provider type","request_id":"sample request id","http_status":1,"retryable":true,"uncertain":true}}},"dm_logs_count":5,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/growth_social/comment_rules/{id}/logs":{"get":{"tags":["Growth Social"],"operationId":"auto_get_api_v1_accounts_account_id_growth_social_comment_rules_id_logs","summary":"Logs comment rules","description":"Performs the logs operation on the targeted comment rule resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"comment_id":{"type":"string"},"commenter_id":{"type":"string"},"commenter_name":{"type":["string","null"]},"comment_text":{"type":["string","null"]},"comment_rule_id":{"type":"integer"},"contact_id":{"type":["integer","null"]},"status":{"type":"string","enum":["sent","failed","skipped","processing","uncertain"],"description":"Outcome of the comment-to-DM delivery attempt."},"error_code":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"},"message_id":{"type":["integer","null"]},"conversation_id":{"type":["integer","null"]},"outcomes":{"type":"object","properties":{"private_reply":{"type":"object","properties":{"success":{"type":"boolean"},"uncertain":{"type":"boolean"},"error":{"type":"string","maxLength":255},"diagnostic":{"$ref":"#/components/schemas/social_graph_diagnostic"}}},"public_reply":{"type":"object","properties":{"success":{"type":"boolean"},"uncertain":{"type":"boolean"},"error":{"type":"string","maxLength":255},"diagnostic":{"$ref":"#/components/schemas/social_graph_diagnostic"}}},"like_comment":{"type":"object","properties":{"success":{"type":"boolean"},"uncertain":{"type":"boolean"},"error":{"type":"string","maxLength":255},"diagnostic":{"$ref":"#/components/schemas/social_graph_diagnostic"}}},"inbox_recording":{"type":"object","properties":{"success":{"type":"boolean"},"uncertain":{"type":"boolean"},"error":{"type":"string","maxLength":255},"diagnostic":{"$ref":"#/components/schemas/social_graph_diagnostic"}}}}}}}},"meta":{"type":"object","properties":{"count":{"type":"integer"}}}}},"example":{"payload":[{"id":1,"comment_id":"sample comment id","commenter_id":"sample commenter id","commenter_name":"sample commenter name","comment_text":"sample comment text","comment_rule_id":1,"contact_id":1,"status":"sent","error_code":"sample error code","created_at":"2026-01-15T10:30:00.000Z","message_id":1,"conversation_id":1,"outcomes":{"private_reply":{"success":true,"uncertain":true,"error":"sample error","diagnostic":{"stage":"sample stage","code":"sample code","provider_code":1,"provider_subcode":1,"provider_type":"sample provider type","request_id":"sample request id","http_status":1,"retryable":true,"uncertain":true}},"public_reply":{"success":true,"uncertain":true,"error":"sample error","diagnostic":{"stage":"sample stage","code":"sample code","provider_code":1,"provider_subcode":1,"provider_type":"sample provider type","request_id":"sample request id","http_status":1,"retryable":true,"uncertain":true}},"like_comment":{"success":true,"uncertain":true,"error":"sample error","diagnostic":{"stage":"sample stage","code":"sample code","provider_code":1,"provider_subcode":1,"provider_type":"sample provider type","request_id":"sample request id","http_status":1,"retryable":true,"uncertain":true}},"inbox_recording":{"success":true,"uncertain":true,"error":"sample error","diagnostic":{"stage":"sample stage","code":"sample code","provider_code":1,"provider_subcode":1,"provider_type":"sample provider type","request_id":"sample request id","http_status":1,"retryable":true,"uncertain":true}}}}],"meta":{"count":5}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page of delivery logs.","schema":{"type":"integer","minimum":1,"default":1}},{"name":"per_page","in":"query","required":false,"description":"Logs per page.","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}}]}},"/api/v1/accounts/{account_id}/growth_social/comment_rules/report":{"get":{"tags":["Growth Social"],"operationId":"auto_get_api_v1_accounts_account_id_growth_social_comment_rules_report","summary":"Report comment rules","description":"Performs the report operation on the targeted comment rule resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"total":{"type":"number"},"active":{"type":"boolean"},"dm_sent":{"type":"string"},"dm_failed":{"type":"string"},"dm_skipped":{"type":"string"}}},"example":{"total":149.9,"active":true,"dm_sent":"sample dm sent","dm_failed":"sample dm failed","dm_skipped":"sample dm skipped"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/growth_social/comment_rules":{"get":{"tags":["Growth Social"],"operationId":"auto_get_api_v1_accounts_account_id_growth_social_comment_rules","summary":"List comment rules","description":"Returns the list of comment rules visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"name":{"type":"string"},"inbox_id":{"type":"integer"},"distribution_id":{"type":"integer"},"post_id":{"type":"integer"},"post":{"type":"string"},"keyword":{"type":"string"},"keywords":{"type":"string"},"all_keywords":{"type":"string"},"trigger_type":{"type":"string","enum":["keyword","any"]},"platform":{"type":"string","enum":["any_platform","instagram","facebook"]},"match_type":{"type":"string","enum":["contains","exact","starts_with"]},"dm_template":{"type":"string"},"public_reply":{"type":"string"},"enabled":{"type":"boolean"},"settings":{"type":"object","additionalProperties":true,"description":"Rule options. The native_comment_recovery subtree is read-only; rule writes ignore it and preserve the server checkpoint.","properties":{"native_comment_recovery":{"$ref":"#/components/schemas/native_comment_recovery","readOnly":true}}},"dm_logs_count":{"type":"integer"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}},"meta":{"type":"object","properties":{"count":{"type":"integer"}}}}},"example":{"payload":[{"id":1,"account_id":1,"name":"Sample Name","inbox_id":1,"distribution_id":1,"post_id":1,"post":"sample post","keyword":"sample keyword","keywords":"sample keywords","all_keywords":"sample all keywords","trigger_type":"keyword","platform":"any_platform","match_type":"contains","dm_template":"sample dm template","public_reply":"sample public reply","enabled":true,"settings":{"native_comment_recovery":{"actor_id":"sample actor id","inbox_id":1,"post_id":"sample post id","platform":"instagram","status":"scheduled","since":"2026-01-15T10:30:00.000Z","initial_since":"2026-01-15T10:30:00.000Z","cutoff":"2026-01-15T10:30:00.000Z","cursor":"sample cursor","pages":1,"attempts":1,"processed":1,"next_run_at":"2026-01-15T10:30:00.000Z","lease_until":"2026-01-15T10:30:00.000Z","diagnostic":{"stage":"sample stage","code":"sample code","provider_code":1,"provider_subcode":1,"provider_type":"sample provider type","request_id":"sample request id","http_status":1,"retryable":true,"uncertain":true}}},"dm_logs_count":5,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}],"meta":{"count":5}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"inbox_id","in":"query","required":false,"description":"Restrict to rules bound to one inbox.","schema":{"type":"integer"},"example":42},{"name":"enabled","in":"query","required":false,"description":"Restrict to enabled or disabled rules. Sending the key at all applies the filter.","schema":{"type":"boolean"},"example":true}]},"post":{"tags":["Growth Social"],"operationId":"auto_post_api_v1_accounts_account_id_growth_social_comment_rules","summary":"Create comment rules","description":"Creates a new comment rule from the request payload. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"name":{"type":"string"},"inbox_id":{"type":"integer"},"distribution_id":{"type":"integer"},"post_id":{"type":"integer"},"post":{"type":"string"},"keyword":{"type":"string"},"keywords":{"type":"string"},"all_keywords":{"type":"string"},"trigger_type":{"type":"string","enum":["keyword","any"]},"platform":{"type":"string","enum":["any_platform","instagram","facebook"]},"match_type":{"type":"string","enum":["contains","exact","starts_with"]},"dm_template":{"type":"string"},"public_reply":{"type":"string"},"enabled":{"type":"boolean"},"settings":{"type":"object","additionalProperties":true,"description":"Rule options. The native_comment_recovery subtree is read-only; rule writes ignore it and preserve the server checkpoint.","properties":{"native_comment_recovery":{"$ref":"#/components/schemas/native_comment_recovery","readOnly":true}}},"dm_logs_count":{"type":"integer"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"example":{"id":1,"account_id":1,"name":"Sample Name","inbox_id":1,"distribution_id":1,"post_id":1,"post":"sample post","keyword":"sample keyword","keywords":"sample keywords","all_keywords":"sample all keywords","trigger_type":"keyword","platform":"any_platform","match_type":"contains","dm_template":"sample dm template","public_reply":"sample public reply","enabled":true,"settings":{"native_comment_recovery":{"actor_id":"sample actor id","inbox_id":1,"post_id":"sample post id","platform":"instagram","status":"scheduled","since":"2026-01-15T10:30:00.000Z","initial_since":"2026-01-15T10:30:00.000Z","cutoff":"2026-01-15T10:30:00.000Z","cursor":"sample cursor","pages":1,"attempts":1,"processed":1,"next_run_at":"2026-01-15T10:30:00.000Z","lease_until":"2026-01-15T10:30:00.000Z","diagnostic":{"stage":"sample stage","code":"sample code","provider_code":1,"provider_subcode":1,"provider_type":"sample provider type","request_id":"sample request id","http_status":1,"retryable":true,"uncertain":true}}},"dm_logs_count":5,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":["string","null"]},"inbox_id":{"type":["integer","null"]},"distribution_id":{"type":["integer","null"]},"post_id":{"type":["string","null"]},"keyword":{"type":["string","null"]},"keywords":{"type":"array","items":{"type":"string"}},"match_type":{"type":"string","enum":["contains","exact","starts_with"]},"trigger_type":{"type":"string","enum":["keyword","any"]},"platform":{"type":"string","enum":["any_platform","instagram","facebook"]},"dm_template":{"type":["string","null"]},"public_reply":{"type":["string","null"]},"enabled":{"type":"boolean"},"settings":{"type":"object","additionalProperties":true,"description":"Rule options. The native_comment_recovery subtree is server-owned; submitted values are ignored and the stored checkpoint is preserved.","properties":{"native_comment_recovery":{"$ref":"#/components/schemas/native_comment_recovery","readOnly":true}}}}},"example":{"name":"Comment follow-up","trigger_type":"any","platform":"instagram","dm_template":"Thanks for your comment.","enabled":true,"settings":{"once_per_user":true,"native_comment_recovery":{"actor_id":"sample actor id","inbox_id":1,"post_id":"sample post id","platform":"instagram","status":"scheduled","since":"2026-01-15T10:30:00.000Z","initial_since":"2026-01-15T10:30:00.000Z","cutoff":"2026-01-15T10:30:00.000Z","cursor":"sample cursor","pages":1,"attempts":1,"processed":1,"next_run_at":"2026-01-15T10:30:00.000Z","lease_until":"2026-01-15T10:30:00.000Z","diagnostic":{"stage":"sample stage","code":"sample code","provider_code":1,"provider_subcode":1,"provider_type":"sample provider type","request_id":"sample request id","http_status":1,"retryable":true,"uncertain":true}}},"inbox_id":1,"distribution_id":1,"post_id":"sample post id","keyword":"sample keyword","keywords":["sample keyword"],"match_type":"contains","public_reply":"sample public reply"}}}}}},"/api/v1/accounts/{account_id}/growth_social/comment_rules/{id}":{"get":{"tags":["Growth Social"],"operationId":"auto_get_api_v1_accounts_account_id_growth_social_comment_rules_id","summary":"Get comment rules","description":"Returns the comment rule identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"name":{"type":"string"},"inbox_id":{"type":"integer"},"distribution_id":{"type":"integer"},"post_id":{"type":"integer"},"post":{"type":"string"},"keyword":{"type":"string"},"keywords":{"type":"string"},"all_keywords":{"type":"string"},"trigger_type":{"type":"string","enum":["keyword","any"]},"platform":{"type":"string","enum":["any_platform","instagram","facebook"]},"match_type":{"type":"string","enum":["contains","exact","starts_with"]},"dm_template":{"type":"string"},"public_reply":{"type":"string"},"enabled":{"type":"boolean"},"settings":{"type":"object","additionalProperties":true,"description":"Rule options. The native_comment_recovery subtree is read-only; rule writes ignore it and preserve the server checkpoint.","properties":{"native_comment_recovery":{"$ref":"#/components/schemas/native_comment_recovery","readOnly":true}}},"dm_logs_count":{"type":"integer"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"example":{"id":1,"account_id":1,"name":"Sample Name","inbox_id":1,"distribution_id":1,"post_id":1,"post":"sample post","keyword":"sample keyword","keywords":"sample keywords","all_keywords":"sample all keywords","trigger_type":"keyword","platform":"any_platform","match_type":"contains","dm_template":"sample dm template","public_reply":"sample public reply","enabled":true,"settings":{"native_comment_recovery":{"actor_id":"sample actor id","inbox_id":1,"post_id":"sample post id","platform":"instagram","status":"scheduled","since":"2026-01-15T10:30:00.000Z","initial_since":"2026-01-15T10:30:00.000Z","cutoff":"2026-01-15T10:30:00.000Z","cursor":"sample cursor","pages":1,"attempts":1,"processed":1,"next_run_at":"2026-01-15T10:30:00.000Z","lease_until":"2026-01-15T10:30:00.000Z","diagnostic":{"stage":"sample stage","code":"sample code","provider_code":1,"provider_subcode":1,"provider_type":"sample provider type","request_id":"sample request id","http_status":1,"retryable":true,"uncertain":true}}},"dm_logs_count":5,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]},"patch":{"tags":["Growth Social"],"operationId":"auto_patch_api_v1_accounts_account_id_growth_social_comment_rules_id","summary":"Update comment rules","description":"Updates the comment rule identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"name":{"type":"string"},"inbox_id":{"type":"integer"},"distribution_id":{"type":"integer"},"post_id":{"type":"integer"},"post":{"type":"string"},"keyword":{"type":"string"},"keywords":{"type":"string"},"all_keywords":{"type":"string"},"trigger_type":{"type":"string","enum":["keyword","any"]},"platform":{"type":"string","enum":["any_platform","instagram","facebook"]},"match_type":{"type":"string","enum":["contains","exact","starts_with"]},"dm_template":{"type":"string"},"public_reply":{"type":"string"},"enabled":{"type":"boolean"},"settings":{"type":"object","additionalProperties":true,"description":"Rule options. The native_comment_recovery subtree is read-only; rule writes ignore it and preserve the server checkpoint.","properties":{"native_comment_recovery":{"$ref":"#/components/schemas/native_comment_recovery","readOnly":true}}},"dm_logs_count":{"type":"integer"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"example":{"id":1,"account_id":1,"name":"Sample Name","inbox_id":1,"distribution_id":1,"post_id":1,"post":"sample post","keyword":"sample keyword","keywords":"sample keywords","all_keywords":"sample all keywords","trigger_type":"keyword","platform":"any_platform","match_type":"contains","dm_template":"sample dm template","public_reply":"sample public reply","enabled":true,"settings":{"native_comment_recovery":{"actor_id":"sample actor id","inbox_id":1,"post_id":"sample post id","platform":"instagram","status":"scheduled","since":"2026-01-15T10:30:00.000Z","initial_since":"2026-01-15T10:30:00.000Z","cutoff":"2026-01-15T10:30:00.000Z","cursor":"sample cursor","pages":1,"attempts":1,"processed":1,"next_run_at":"2026-01-15T10:30:00.000Z","lease_until":"2026-01-15T10:30:00.000Z","diagnostic":{"stage":"sample stage","code":"sample code","provider_code":1,"provider_subcode":1,"provider_type":"sample provider type","request_id":"sample request id","http_status":1,"retryable":true,"uncertain":true}}},"dm_logs_count":5,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":["string","null"]},"inbox_id":{"type":["integer","null"]},"distribution_id":{"type":["integer","null"]},"post_id":{"type":["string","null"]},"keyword":{"type":["string","null"]},"keywords":{"type":"array","items":{"type":"string"}},"match_type":{"type":"string","enum":["contains","exact","starts_with"]},"trigger_type":{"type":"string","enum":["keyword","any"]},"platform":{"type":"string","enum":["any_platform","instagram","facebook"]},"dm_template":{"type":["string","null"]},"public_reply":{"type":["string","null"]},"enabled":{"type":"boolean"},"settings":{"type":"object","additionalProperties":true,"description":"Rule options. The native_comment_recovery subtree is server-owned; submitted values are ignored and the stored checkpoint is preserved.","properties":{"native_comment_recovery":{"$ref":"#/components/schemas/native_comment_recovery","readOnly":true}}}}},"example":{"name":"Comment follow-up","trigger_type":"any","platform":"instagram","dm_template":"Thanks for your comment.","enabled":true,"settings":{"once_per_user":true,"native_comment_recovery":{"actor_id":"sample actor id","inbox_id":1,"post_id":"sample post id","platform":"instagram","status":"scheduled","since":"2026-01-15T10:30:00.000Z","initial_since":"2026-01-15T10:30:00.000Z","cutoff":"2026-01-15T10:30:00.000Z","cursor":"sample cursor","pages":1,"attempts":1,"processed":1,"next_run_at":"2026-01-15T10:30:00.000Z","lease_until":"2026-01-15T10:30:00.000Z","diagnostic":{"stage":"sample stage","code":"sample code","provider_code":1,"provider_subcode":1,"provider_type":"sample provider type","request_id":"sample request id","http_status":1,"retryable":true,"uncertain":true}}},"inbox_id":1,"distribution_id":1,"post_id":"sample post id","keyword":"sample keyword","keywords":["sample keyword"],"match_type":"contains","public_reply":"sample public reply"}}}}},"put":{"tags":["Growth Social"],"operationId":"auto_put_api_v1_accounts_account_id_growth_social_comment_rules_id","summary":"Update comment rules","description":"Updates the comment rule identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"name":{"type":"string"},"inbox_id":{"type":"integer"},"distribution_id":{"type":"integer"},"post_id":{"type":"integer"},"post":{"type":"string"},"keyword":{"type":"string"},"keywords":{"type":"string"},"all_keywords":{"type":"string"},"trigger_type":{"type":"string","enum":["keyword","any"]},"platform":{"type":"string","enum":["any_platform","instagram","facebook"]},"match_type":{"type":"string","enum":["contains","exact","starts_with"]},"dm_template":{"type":"string"},"public_reply":{"type":"string"},"enabled":{"type":"boolean"},"settings":{"type":"object","additionalProperties":true,"description":"Rule options. The native_comment_recovery subtree is read-only; rule writes ignore it and preserve the server checkpoint.","properties":{"native_comment_recovery":{"$ref":"#/components/schemas/native_comment_recovery","readOnly":true}}},"dm_logs_count":{"type":"integer"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"example":{"id":1,"account_id":1,"name":"Sample Name","inbox_id":1,"distribution_id":1,"post_id":1,"post":"sample post","keyword":"sample keyword","keywords":"sample keywords","all_keywords":"sample all keywords","trigger_type":"keyword","platform":"any_platform","match_type":"contains","dm_template":"sample dm template","public_reply":"sample public reply","enabled":true,"settings":{"native_comment_recovery":{"actor_id":"sample actor id","inbox_id":1,"post_id":"sample post id","platform":"instagram","status":"scheduled","since":"2026-01-15T10:30:00.000Z","initial_since":"2026-01-15T10:30:00.000Z","cutoff":"2026-01-15T10:30:00.000Z","cursor":"sample cursor","pages":1,"attempts":1,"processed":1,"next_run_at":"2026-01-15T10:30:00.000Z","lease_until":"2026-01-15T10:30:00.000Z","diagnostic":{"stage":"sample stage","code":"sample code","provider_code":1,"provider_subcode":1,"provider_type":"sample provider type","request_id":"sample request id","http_status":1,"retryable":true,"uncertain":true}}},"dm_logs_count":5,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":["string","null"]},"inbox_id":{"type":["integer","null"]},"distribution_id":{"type":["integer","null"]},"post_id":{"type":["string","null"]},"keyword":{"type":["string","null"]},"keywords":{"type":"array","items":{"type":"string"}},"match_type":{"type":"string","enum":["contains","exact","starts_with"]},"trigger_type":{"type":"string","enum":["keyword","any"]},"platform":{"type":"string","enum":["any_platform","instagram","facebook"]},"dm_template":{"type":["string","null"]},"public_reply":{"type":["string","null"]},"enabled":{"type":"boolean"},"settings":{"type":"object","additionalProperties":true,"description":"Rule options. The native_comment_recovery subtree is server-owned; submitted values are ignored and the stored checkpoint is preserved.","properties":{"native_comment_recovery":{"$ref":"#/components/schemas/native_comment_recovery","readOnly":true}}}}},"example":{"name":"Comment follow-up","trigger_type":"any","platform":"instagram","dm_template":"Thanks for your comment.","enabled":true,"settings":{"once_per_user":true,"native_comment_recovery":{"actor_id":"sample actor id","inbox_id":1,"post_id":"sample post id","platform":"instagram","status":"scheduled","since":"2026-01-15T10:30:00.000Z","initial_since":"2026-01-15T10:30:00.000Z","cutoff":"2026-01-15T10:30:00.000Z","cursor":"sample cursor","pages":1,"attempts":1,"processed":1,"next_run_at":"2026-01-15T10:30:00.000Z","lease_until":"2026-01-15T10:30:00.000Z","diagnostic":{"stage":"sample stage","code":"sample code","provider_code":1,"provider_subcode":1,"provider_type":"sample provider type","request_id":"sample request id","http_status":1,"retryable":true,"uncertain":true}}},"inbox_id":1,"distribution_id":1,"post_id":"sample post id","keyword":"sample keyword","keywords":["sample keyword"],"match_type":"contains","public_reply":"sample public reply"}}}}},"delete":{"tags":["Growth Social"],"operationId":"auto_delete_api_v1_accounts_account_id_growth_social_comment_rules_id","summary":"Delete comment rules","description":"Deletes the comment rule identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Success (no content)"},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/growth_social/moderation_rules/{id}/toggle":{"post":{"tags":["Growth Social"],"operationId":"auto_post_api_v1_accounts_account_id_growth_social_moderation_rules_id_toggle","summary":"Toggle moderation rules","description":"Performs the toggle operation on the targeted moderation rule resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"name":{"type":"string"},"inbox_id":{"type":"integer"},"post_id":{"type":"integer"},"post":{"type":"string"},"keywords":{"type":"string"},"all_keywords":{"type":"string"},"match_type":{"type":"string","enum":["contains","exact","starts_with"]},"platform":{"type":"string","enum":["any_platform","instagram","facebook"]},"action":{"type":"string","enum":["hide","delete","maestro"]},"action_label":{"type":"string"},"enabled":{"type":"boolean"},"settings":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"example":{"id":1,"account_id":1,"name":"Sample Name","inbox_id":1,"post_id":1,"post":"sample post","keywords":"sample keywords","all_keywords":"sample all keywords","match_type":"contains","platform":"any_platform","action":"hide","action_label":"sample action label","enabled":true,"settings":"sample settings","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/growth_social/moderation_rules":{"get":{"tags":["Growth Social"],"operationId":"auto_get_api_v1_accounts_account_id_growth_social_moderation_rules","summary":"List moderation rules","description":"Returns the list of moderation rules visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"name":{"type":"string"},"inbox_id":{"type":"integer"},"post_id":{"type":"integer"},"post":{"type":"string"},"keywords":{"type":"string"},"all_keywords":{"type":"string"},"match_type":{"type":"string","enum":["contains","exact","starts_with"]},"platform":{"type":"string","enum":["any_platform","instagram","facebook"]},"action":{"type":"string","enum":["hide","delete","maestro"]},"action_label":{"type":"string"},"enabled":{"type":"boolean"},"settings":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}},"meta":{"type":"object","properties":{"count":{"type":"integer"}}}}},"example":{"payload":[{"id":1,"account_id":1,"name":"Sample Name","inbox_id":1,"post_id":1,"post":"sample post","keywords":"sample keywords","all_keywords":"sample all keywords","match_type":"contains","platform":"any_platform","action":"hide","action_label":"sample action label","enabled":true,"settings":"sample settings","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}],"meta":{"count":5}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"inbox_id","in":"query","required":false,"description":"Restrict to rules bound to one inbox.","schema":{"type":"integer"},"example":42}]},"post":{"tags":["Growth Social"],"operationId":"auto_post_api_v1_accounts_account_id_growth_social_moderation_rules","summary":"Create moderation rules","description":"Creates a new moderation rule from the request payload. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"name":{"type":"string"},"inbox_id":{"type":"integer"},"post_id":{"type":"integer"},"post":{"type":"string"},"keywords":{"type":"string"},"all_keywords":{"type":"string"},"match_type":{"type":"string","enum":["contains","exact","starts_with"]},"platform":{"type":"string","enum":["any_platform","instagram","facebook"]},"action":{"type":"string","enum":["hide","delete","maestro"]},"action_label":{"type":"string"},"enabled":{"type":"boolean"},"settings":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"example":{"id":1,"account_id":1,"name":"Sample Name","inbox_id":1,"post_id":1,"post":"sample post","keywords":"sample keywords","all_keywords":"sample all keywords","match_type":"contains","platform":"any_platform","action":"hide","action_label":"sample action label","enabled":true,"settings":"sample settings","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"inbox_id":{"type":"integer"},"post_id":{"type":"integer"},"match_type":{"type":"string","enum":["contains","exact","starts_with"]},"platform":{"type":"string","enum":["any_platform","instagram","facebook"]},"action":{"type":"string","enum":["hide","delete","maestro"]},"enabled":{"type":"boolean"},"keywords":{"type":"array","items":{"type":"string"}}}},"example":{"name":"Sample Name","inbox_id":1,"post_id":1,"match_type":"contains","platform":"any_platform","action":"hide","enabled":true,"keywords":["sample keyword"]}}}}}},"/api/v1/accounts/{account_id}/growth_social/moderation_rules/{id}":{"get":{"tags":["Growth Social"],"operationId":"auto_get_api_v1_accounts_account_id_growth_social_moderation_rules_id","summary":"Get moderation rules","description":"Returns the moderation rule identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"name":{"type":"string"},"inbox_id":{"type":"integer"},"post_id":{"type":"integer"},"post":{"type":"string"},"keywords":{"type":"string"},"all_keywords":{"type":"string"},"match_type":{"type":"string","enum":["contains","exact","starts_with"]},"platform":{"type":"string","enum":["any_platform","instagram","facebook"]},"action":{"type":"string","enum":["hide","delete","maestro"]},"action_label":{"type":"string"},"enabled":{"type":"boolean"},"settings":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"example":{"id":1,"account_id":1,"name":"Sample Name","inbox_id":1,"post_id":1,"post":"sample post","keywords":"sample keywords","all_keywords":"sample all keywords","match_type":"contains","platform":"any_platform","action":"hide","action_label":"sample action label","enabled":true,"settings":"sample settings","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]},"patch":{"tags":["Growth Social"],"operationId":"auto_patch_api_v1_accounts_account_id_growth_social_moderation_rules_id","summary":"Update moderation rules","description":"Updates the moderation rule identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"name":{"type":"string"},"inbox_id":{"type":"integer"},"post_id":{"type":"integer"},"post":{"type":"string"},"keywords":{"type":"string"},"all_keywords":{"type":"string"},"match_type":{"type":"string","enum":["contains","exact","starts_with"]},"platform":{"type":"string","enum":["any_platform","instagram","facebook"]},"action":{"type":"string","enum":["hide","delete","maestro"]},"action_label":{"type":"string"},"enabled":{"type":"boolean"},"settings":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"example":{"id":1,"account_id":1,"name":"Sample Name","inbox_id":1,"post_id":1,"post":"sample post","keywords":"sample keywords","all_keywords":"sample all keywords","match_type":"contains","platform":"any_platform","action":"hide","action_label":"sample action label","enabled":true,"settings":"sample settings","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"inbox_id":{"type":"integer"},"post_id":{"type":"integer"},"match_type":{"type":"string","enum":["contains","exact","starts_with"]},"platform":{"type":"string","enum":["any_platform","instagram","facebook"]},"action":{"type":"string","enum":["hide","delete","maestro"]},"enabled":{"type":"boolean"},"keywords":{"type":"array","items":{"type":"string"}}}},"example":{"name":"Sample Name","inbox_id":1,"post_id":1,"match_type":"contains","platform":"any_platform","action":"hide","enabled":true,"keywords":["sample keyword"]}}}}},"put":{"tags":["Growth Social"],"operationId":"auto_put_api_v1_accounts_account_id_growth_social_moderation_rules_id","summary":"Update moderation rules","description":"Updates the moderation rule identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"name":{"type":"string"},"inbox_id":{"type":"integer"},"post_id":{"type":"integer"},"post":{"type":"string"},"keywords":{"type":"string"},"all_keywords":{"type":"string"},"match_type":{"type":"string","enum":["contains","exact","starts_with"]},"platform":{"type":"string","enum":["any_platform","instagram","facebook"]},"action":{"type":"string","enum":["hide","delete","maestro"]},"action_label":{"type":"string"},"enabled":{"type":"boolean"},"settings":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"example":{"id":1,"account_id":1,"name":"Sample Name","inbox_id":1,"post_id":1,"post":"sample post","keywords":"sample keywords","all_keywords":"sample all keywords","match_type":"contains","platform":"any_platform","action":"hide","action_label":"sample action label","enabled":true,"settings":"sample settings","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"inbox_id":{"type":"integer"},"post_id":{"type":"integer"},"match_type":{"type":"string","enum":["contains","exact","starts_with"]},"platform":{"type":"string","enum":["any_platform","instagram","facebook"]},"action":{"type":"string","enum":["hide","delete","maestro"]},"enabled":{"type":"boolean"},"keywords":{"type":"array","items":{"type":"string"}}}},"example":{"name":"Sample Name","inbox_id":1,"post_id":1,"match_type":"contains","platform":"any_platform","action":"hide","enabled":true,"keywords":["sample keyword"]}}}}},"delete":{"tags":["Growth Social"],"operationId":"auto_delete_api_v1_accounts_account_id_growth_social_moderation_rules_id","summary":"Delete moderation rules","description":"Deletes the moderation rule identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Success (no content)"},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/growth_social/posts":{"get":{"tags":["Growth Social"],"operationId":"auto_get_api_v1_accounts_account_id_growth_social_posts","summary":"List posts","description":"Returns the list of posts visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"caption":{"type":["string","null"]},"thumbnail":{"type":["string","null"]},"permalink":{"type":["string","null"]},"timestamp":{"type":["string","null"],"format":"date-time"}}}},"meta":{"type":"object","properties":{"next_cursor":{"type":["string","null"]},"capabilities":{"type":"object","properties":{"platform":{"type":"string","enum":["instagram","facebook"]},"transport":{"type":"string","enum":["instagram_login","facebook_login"]},"private_reply":{"type":"boolean"},"reply_comment":{"type":"boolean"},"hide_comment":{"type":"boolean"},"unhide_comment":{"type":"boolean"},"delete_comment":{"type":"boolean"},"like_comment":{"type":"boolean"},"unlike_comment":{"type":"boolean"},"delete_post":{"type":"boolean"}}}}}}},"example":{"payload":[{"id":"17895695668004550","caption":"Ask about our product","thumbnail":"https://example.com/post.jpg","permalink":"https://www.instagram.com/p/example/","timestamp":"2026-09-07T12:00:00Z"}],"meta":{"next_cursor":null,"capabilities":{"platform":"instagram","transport":"facebook_login","private_reply":true,"reply_comment":true,"hide_comment":true,"unhide_comment":true,"delete_comment":true,"like_comment":false,"unlike_comment":false,"delete_post":false}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"502":{"description":"Provider request failed; no empty successful page is substituted.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"error_code":{"type":"string"},"retryable":{"type":"boolean"}}},"example":{"error":"provider_connection_failed","error_code":"provider_connection_failed","retryable":true}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"inbox_id","in":"query","required":true,"description":"Native Instagram or Facebook Page inbox.","schema":{"type":"integer"}},{"name":"platform","in":"query","required":false,"description":"Explicit network. A Facebook-linked inbox can address Instagram or the Page; defaults to Instagram when linked.","schema":{"type":"string","enum":["instagram","facebook"]}},{"name":"cursor","in":"query","required":false,"description":"Opaque next_cursor from the previous page.","schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/growth_social/moderation/comments":{"get":{"tags":["Growth Social"],"operationId":"auto_get_api_v1_accounts_account_id_growth_social_moderation_comments","summary":"Comments moderation","description":"Performs the comments operation on the targeted moderation resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"text":{"type":"string"},"username":{"type":["string","null"]},"timestamp":{"type":["string","null"],"format":"date-time"},"hidden":{"type":"boolean"},"like_count":{"type":"integer"},"reply_receipt":{"type":["object","null"],"properties":{"id":{"type":"integer"},"status":{"type":"string","enum":["success","failed","processing","uncertain"]},"external_id":{"type":["string","null"]},"can_reconcile":{"type":"boolean"}}}}}},"meta":{"type":"object","properties":{"next_cursor":{"type":["string","null"]},"capabilities":{"type":"object","properties":{"platform":{"type":"string","enum":["instagram","facebook"]},"transport":{"type":"string","enum":["instagram_login","facebook_login"]},"private_reply":{"type":"boolean"},"reply_comment":{"type":"boolean"},"hide_comment":{"type":"boolean"},"unhide_comment":{"type":"boolean"},"delete_comment":{"type":"boolean"},"like_comment":{"type":"boolean"},"unlike_comment":{"type":"boolean"},"delete_post":{"type":"boolean"}}}}}}},"example":{"payload":[{"id":"17900000000000001","text":"What is the price?","username":"example_customer","timestamp":"2026-09-07T12:05:00Z","hidden":false,"like_count":0,"reply_receipt":{"id":17,"status":"uncertain","external_id":null,"can_reconcile":true}}],"meta":{"next_cursor":null,"capabilities":{"platform":"instagram","transport":"facebook_login","private_reply":true,"reply_comment":true,"hide_comment":true,"unhide_comment":true,"delete_comment":true,"like_comment":false,"unlike_comment":false,"delete_post":false}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"502":{"description":"Provider request failed; no empty successful page is substituted.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"error_code":{"type":"string"},"retryable":{"type":"boolean"}}},"example":{"error":"provider_connection_failed","error_code":"provider_connection_failed","retryable":true}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"inbox_id","in":"query","required":true,"description":"Native Instagram or Facebook Page inbox.","schema":{"type":"integer"}},{"name":"platform","in":"query","required":false,"description":"Explicit network. A Facebook-linked inbox can address Instagram or the Page; defaults to Instagram when linked.","schema":{"type":"string","enum":["instagram","facebook"]}},{"name":"cursor","in":"query","required":false,"description":"Opaque next_cursor from the previous page.","schema":{"type":"string"}},{"name":"post_id","in":"query","required":true,"description":"Post whose comments are read live.","schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/growth_social/moderation/hide_comment":{"post":{"tags":["Growth Social"],"operationId":"auto_post_api_v1_accounts_account_id_growth_social_moderation_hide_comment","summary":"Hide comment moderation","description":"Apply the operation to the selected native network. Instagram post deletion is unsupported. Comment likes require a linked Facebook user connection and engagement permissions; consult capabilities before enabling an operation.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}}},"example":{"success":true}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"422":{"description":"Operation unsupported or rejected by the provider.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"string"}}},"example":{"success":true,"error":"sample error"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"inbox_id":{"type":"integer"},"platform":{"type":"string","enum":["instagram","facebook"]},"comment_id":{"type":"string"}},"required":["inbox_id","comment_id"]},"example":{"inbox_id":1,"platform":"instagram","comment_id":"sample comment id"}}}}}},"/api/v1/accounts/{account_id}/growth_social/moderation/unhide_comment":{"post":{"tags":["Growth Social"],"operationId":"auto_post_api_v1_accounts_account_id_growth_social_moderation_unhide_comment","summary":"Unhide comment moderation","description":"Apply the operation to the selected native network. Instagram post deletion is unsupported. Comment likes require a linked Facebook user connection and engagement permissions; consult capabilities before enabling an operation.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}}},"example":{"success":true}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"422":{"description":"Operation unsupported or rejected by the provider.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"string"}}},"example":{"success":true,"error":"sample error"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"inbox_id":{"type":"integer"},"platform":{"type":"string","enum":["instagram","facebook"]},"comment_id":{"type":"string"}},"required":["inbox_id","comment_id"]},"example":{"inbox_id":1,"platform":"instagram","comment_id":"sample comment id"}}}}}},"/api/v1/accounts/{account_id}/growth_social/moderation/delete_comment":{"post":{"tags":["Growth Social"],"operationId":"auto_post_api_v1_accounts_account_id_growth_social_moderation_delete_comment","summary":"Delete comment moderation","description":"Apply the operation to the selected native network. Instagram post deletion is unsupported. Comment likes require a linked Facebook user connection and engagement permissions; consult capabilities before enabling an operation.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}}},"example":{"success":true}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"422":{"description":"Operation unsupported or rejected by the provider.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"string"}}},"example":{"success":true,"error":"sample error"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"inbox_id":{"type":"integer"},"platform":{"type":"string","enum":["instagram","facebook"]},"comment_id":{"type":"string"}},"required":["inbox_id","comment_id"]},"example":{"inbox_id":1,"platform":"instagram","comment_id":"sample comment id"}}}}}},"/api/v1/accounts/{account_id}/growth_social/moderation/reply_comment":{"post":{"tags":["Growth Social"],"operationId":"auto_post_api_v1_accounts_account_id_growth_social_moderation_reply_comment","summary":"Reply comment moderation","description":"Reply with a durable per-account/network/actor/comment claim. Confirmed identical text replays without another send. Processing or ambiguous delivery blocks new replies until verified reconciliation.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"uncertain":{"type":"boolean"},"receipt":{"type":["object","null"],"properties":{"id":{"type":"integer"},"status":{"type":"string","enum":["success","failed","processing","uncertain"]},"external_id":{"type":["string","null"]},"can_reconcile":{"type":"boolean"}}}}},"example":{"success":true,"uncertain":true,"receipt":{"id":1,"status":"success","external_id":"sample external id","can_reconcile":true}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"422":{"description":"Definite failure or unresolved delivery. Preserve receipt and never automatically resend an uncertain reply.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":["string","null"]},"uncertain":{"type":"boolean"},"receipt":{"type":["object","null"],"properties":{"id":{"type":"integer"},"status":{"type":"string","enum":["success","failed","processing","uncertain"]},"external_id":{"type":["string","null"]},"can_reconcile":{"type":"boolean"}}}}},"example":{"success":true,"error":"sample error","uncertain":true,"receipt":{"id":1,"status":"success","external_id":"sample external id","can_reconcile":true}}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"inbox_id":{"type":"integer"},"platform":{"type":"string","enum":["instagram","facebook"]},"comment_id":{"type":"string"},"message":{"type":"string","minLength":1},"post_id":{"type":"string"}},"required":["inbox_id","comment_id","message"]},"example":{"inbox_id":1,"platform":"instagram","comment_id":"sample comment id","message":"Sample message text.","post_id":"sample post id"}}}}}},"/api/v1/accounts/{account_id}/growth_social/moderation/reconcile_reply":{"post":{"tags":["Growth Social"],"operationId":"auto_post_api_v1_accounts_account_id_growth_social_moderation_reconcile_reply","summary":"Reconcile a native manual comment reply","description":"Record verified provider delivery without sending. Delivered requires external_id. A verified failed outcome permits a later explicit reply. Processing receipts must be at least 15 minutes old. Repeating identical reconciliation evidence is idempotent.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"uncertain":{"type":"boolean"},"receipt":{"type":["object","null"],"properties":{"id":{"type":"integer"},"status":{"type":"string","enum":["success","failed","processing","uncertain"]},"external_id":{"type":["string","null"]},"can_reconcile":{"type":"boolean"}}}}},"example":{"success":true,"uncertain":true,"receipt":{"id":1,"status":"success","external_id":"sample external id","can_reconcile":true}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"422":{"description":"Definite failure or unresolved delivery. Preserve receipt and never automatically resend an uncertain reply.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":["string","null"]},"uncertain":{"type":"boolean"},"receipt":{"type":["object","null"],"properties":{"id":{"type":"integer"},"status":{"type":"string","enum":["success","failed","processing","uncertain"]},"external_id":{"type":["string","null"]},"can_reconcile":{"type":"boolean"}}}}},"example":{"success":true,"error":"sample error","uncertain":true,"receipt":{"id":1,"status":"success","external_id":"sample external id","can_reconcile":true}}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"inbox_id":{"type":"integer"},"platform":{"type":"string","enum":["instagram","facebook"]},"comment_id":{"type":"string"},"receipt_id":{"type":"integer"},"outcome":{"type":"string","enum":["delivered","failed"]},"note":{"type":"string","minLength":1,"maxLength":1000},"external_id":{"type":["string","null"]}},"required":["inbox_id","comment_id","receipt_id","outcome","note"]},"example":{"inbox_id":1,"platform":"instagram","comment_id":"sample comment id","receipt_id":1,"outcome":"delivered","note":"Sample note.","external_id":"sample external id"}}}}}},"/api/v1/accounts/{account_id}/growth_social/moderation/like_comment":{"post":{"tags":["Growth Social"],"operationId":"auto_post_api_v1_accounts_account_id_growth_social_moderation_like_comment","summary":"Like comment moderation","description":"Apply the operation to the selected native network. Instagram requires a linked Facebook user connection and granted engagement permissions. A timeout may have applied the operation; never automatically retry an uncertain result.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}}},"example":{"success":true}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"422":{"description":"Operation unavailable, rejected or of uncertain outcome. Inspect uncertain before retrying.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"string"},"uncertain":{"type":"boolean","description":"The provider may have applied the operation despite the error."},"retryable":{"type":"boolean","description":"Transient failure indicator, not permission to retry an uncertain mutation."},"diagnostic":{"$ref":"#/components/schemas/social_graph_diagnostic"}}},"example":{"success":true,"error":"sample error","uncertain":true,"retryable":true,"diagnostic":{"stage":"sample stage","code":"sample code","provider_code":1,"provider_subcode":1,"provider_type":"sample provider type","request_id":"sample request id","http_status":1,"retryable":true,"uncertain":true}}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"inbox_id":{"type":"integer"},"platform":{"type":"string","enum":["instagram","facebook"]},"comment_id":{"type":"string"}},"required":["inbox_id","comment_id"]},"example":{"inbox_id":1,"platform":"instagram","comment_id":"sample comment id"}}}}}},"/api/v1/accounts/{account_id}/growth_social/moderation/unlike_comment":{"post":{"tags":["Growth Social"],"operationId":"auto_post_api_v1_accounts_account_id_growth_social_moderation_unlike_comment","summary":"Unlike comment moderation","description":"Apply the operation to the selected native network. Instagram requires a linked Facebook user connection and granted engagement permissions. A timeout may have applied the operation; never automatically retry an uncertain result.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}}},"example":{"success":true}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"422":{"description":"Operation unavailable, rejected or of uncertain outcome. Inspect uncertain before retrying.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"string"},"uncertain":{"type":"boolean","description":"The provider may have applied the operation despite the error."},"retryable":{"type":"boolean","description":"Transient failure indicator, not permission to retry an uncertain mutation."},"diagnostic":{"$ref":"#/components/schemas/social_graph_diagnostic"}}},"example":{"success":true,"error":"sample error","uncertain":true,"retryable":true,"diagnostic":{"stage":"sample stage","code":"sample code","provider_code":1,"provider_subcode":1,"provider_type":"sample provider type","request_id":"sample request id","http_status":1,"retryable":true,"uncertain":true}}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"inbox_id":{"type":"integer"},"platform":{"type":"string","enum":["instagram","facebook"]},"comment_id":{"type":"string"}},"required":["inbox_id","comment_id"]},"example":{"inbox_id":1,"platform":"instagram","comment_id":"sample comment id"}}}}}},"/api/v1/accounts/{account_id}/growth_social/moderation/delete_post":{"post":{"tags":["Growth Social"],"operationId":"auto_post_api_v1_accounts_account_id_growth_social_moderation_delete_post","summary":"Delete post moderation","description":"Apply the operation to the selected native network. Instagram post deletion is unsupported. Comment likes require a linked Facebook user connection and engagement permissions; consult capabilities before enabling an operation.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}}},"example":{"success":true}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"422":{"description":"Operation unsupported or rejected by the provider.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"string"}}},"example":{"success":true,"error":"sample error"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"inbox_id":{"type":"integer"},"platform":{"type":"string","enum":["instagram","facebook"]},"post_id":{"type":"string"}},"required":["inbox_id","post_id"]},"example":{"inbox_id":1,"platform":"instagram","post_id":"sample post id"}}}}}},"/api/v1/accounts/{account_id}/growth_social/accounts/{id}/reconnect":{"post":{"tags":["Growth Social"],"operationId":"auto_post_api_v1_accounts_account_id_growth_social_accounts_id_reconnect","summary":"Reconnect accounts","description":"Performs the reconnect operation on the targeted account resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"social_gateway_instance_id":{"type":["integer","null"]},"inbox_id":{"type":["integer","null"]},"platform":{"type":"string","enum":["instagram","tiktok","youtube"]},"external_user_id":{"type":["string","null"]},"username":{"type":["string","null"]},"display_name":{"type":["string","null"]},"auth_mode":{"type":"string","enum":["oauth","session_or_password"]},"access_token":{"type":["string","null"],"description":"Masked token only; never the usable access token."},"status":{"type":"string","enum":["connecting","awaiting_challenge","connected","disconnected","blocked","logged_out"],"description":"Connection state of the social account."},"capabilities":{"type":"object","description":"Application configuration or provider-specific attributes.","additionalProperties":true},"settings":{"type":"object","description":"Account configuration. Legacy proxy_url is excluded; proxy secrets are encrypted separately.","additionalProperties":true},"last_health_at":{"type":["string","null"],"format":"date-time"},"last_error":{"type":["string","null"]},"stats":{"type":"object","description":"Application configuration or provider-specific attributes.","additionalProperties":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"member_id":{"type":["integer","null"]},"has_credentials":{"type":"boolean"},"proxy_route":{"type":["object","null"],"properties":{"mode":{"type":"string","enum":["direct","custom","managed"]},"fallback_policy":{"type":"string","enum":["hold","reassign","direct_allowed"]},"status":{"type":"string","enum":["pending","active","paused","direct_fallback"],"description":"Connection state of the social account."},"route_version":{"type":"integer","minimum":1},"requested_region":{"type":["string","null"]},"region":{"type":["string","null"]},"health":{"type":"object","description":"Sanitized health check outcome. Contains no proxy URL or credentials.","additionalProperties":true},"endpoint_health":{"type":["string","null"],"enum":["unknown","healthy","degraded","unhealthy","exhausted",null]},"fallback":{"type":"boolean"},"reason":{"type":["string","null"]},"effective_mode":{"type":["string","null"],"enum":["direct","custom","managed",null]}}},"stealth_health":{"type":"object","description":"Derived warmup, risk, cooldown and connection health indicators.","additionalProperties":true}}},"example":{"id":1,"account_id":1,"social_gateway_instance_id":1,"inbox_id":1,"platform":"instagram","external_user_id":"sample external user id","username":"sample username","display_name":"sample display name","auth_mode":"oauth","access_token":"sample-token","status":"connecting","capabilities":{},"settings":{},"last_health_at":"2026-01-15T10:30:00.000Z","last_error":"sample last error","stats":{},"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","member_id":1,"has_credentials":true,"proxy_route":{"mode":"direct","fallback_policy":"hold","status":"pending","route_version":1,"requested_region":"sample requested region","region":"sample region","health":{},"endpoint_health":"unknown","fallback":true,"reason":"Sample reason.","effective_mode":"direct"},"stealth_health":{}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/growth_social/accounts/{id}/connect":{"post":{"tags":["Growth Social"],"operationId":"auto_post_api_v1_accounts_account_id_growth_social_accounts_id_connect","summary":"Connect accounts","description":"Performs the connect operation on the targeted account resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"social_gateway_instance_id":{"type":["integer","null"]},"inbox_id":{"type":["integer","null"]},"platform":{"type":"string","enum":["instagram","tiktok","youtube"]},"external_user_id":{"type":["string","null"]},"username":{"type":["string","null"]},"display_name":{"type":["string","null"]},"auth_mode":{"type":"string","enum":["oauth","session_or_password"]},"access_token":{"type":["string","null"],"description":"Masked token only; never the usable access token."},"status":{"type":"string","enum":["connecting","awaiting_challenge","connected","disconnected","blocked","logged_out"],"description":"Connection state of the social account."},"capabilities":{"type":"object","description":"Application configuration or provider-specific attributes.","additionalProperties":true},"settings":{"type":"object","description":"Account configuration. Legacy proxy_url is excluded; proxy secrets are encrypted separately.","additionalProperties":true},"last_health_at":{"type":["string","null"],"format":"date-time"},"last_error":{"type":["string","null"]},"stats":{"type":"object","description":"Application configuration or provider-specific attributes.","additionalProperties":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"member_id":{"type":["integer","null"]},"has_credentials":{"type":"boolean"},"proxy_route":{"type":["object","null"],"properties":{"mode":{"type":"string","enum":["direct","custom","managed"]},"fallback_policy":{"type":"string","enum":["hold","reassign","direct_allowed"]},"status":{"type":"string","enum":["pending","active","paused","direct_fallback"],"description":"Connection state of the social account."},"route_version":{"type":"integer","minimum":1},"requested_region":{"type":["string","null"]},"region":{"type":["string","null"]},"health":{"type":"object","description":"Sanitized health check outcome. Contains no proxy URL or credentials.","additionalProperties":true},"endpoint_health":{"type":["string","null"],"enum":["unknown","healthy","degraded","unhealthy","exhausted",null]},"fallback":{"type":"boolean"},"reason":{"type":["string","null"]},"effective_mode":{"type":["string","null"],"enum":["direct","custom","managed",null]}}},"stealth_health":{"type":"object","description":"Derived warmup, risk, cooldown and connection health indicators.","additionalProperties":true},"result":{"type":"object","properties":{"ok":{"type":"boolean"},"status":{"type":["string","null"],"description":"Connection state returned by the gateway.","enum":["connected","connecting","awaiting_challenge","disconnected","blocked","logged_out","challenge","error",null]},"error":{"type":["string","null"]},"error_category":{"type":["string","null"],"enum":["FATAL","TRANSIENT","RATE_LIMITED","SESSION_INVALID","CHALLENGE","ACTION_BLOCKED","NOT_FOUND",null]}}}}},"example":{"id":1,"account_id":1,"social_gateway_instance_id":1,"inbox_id":1,"platform":"instagram","external_user_id":"sample external user id","username":"sample username","display_name":"sample display name","auth_mode":"oauth","access_token":"sample-token","status":"connecting","capabilities":{},"settings":{},"last_health_at":"2026-01-15T10:30:00.000Z","last_error":"sample last error","stats":{},"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","member_id":1,"has_credentials":true,"proxy_route":{"mode":"direct","fallback_policy":"hold","status":"pending","route_version":1,"requested_region":"sample requested region","region":"sample region","health":{},"endpoint_health":"unknown","fallback":true,"reason":"Sample reason.","effective_mode":"direct"},"stealth_health":{},"result":{"ok":true,"status":"connected","error":"sample error","error_category":"FATAL"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"username":{"type":"string"},"password":{"type":"string"},"verification_code":{"type":"string"}}},"example":{"username":"sample username","password":"sample-password","verification_code":"sample verification code"}}}}}},"/api/v1/accounts/{account_id}/growth_social/accounts/{id}/resolve_challenge":{"post":{"tags":["Growth Social"],"operationId":"auto_post_api_v1_accounts_account_id_growth_social_accounts_id_resolve_challenge","summary":"Resolve challenge accounts","description":"Performs the resolve challenge operation on the targeted account resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"social_gateway_instance_id":{"type":["integer","null"]},"inbox_id":{"type":["integer","null"]},"platform":{"type":"string","enum":["instagram","tiktok","youtube"]},"external_user_id":{"type":["string","null"]},"username":{"type":["string","null"]},"display_name":{"type":["string","null"]},"auth_mode":{"type":"string","enum":["oauth","session_or_password"]},"access_token":{"type":["string","null"],"description":"Masked token only; never the usable access token."},"status":{"type":"string","enum":["connecting","awaiting_challenge","connected","disconnected","blocked","logged_out"],"description":"Connection state of the social account."},"capabilities":{"type":"object","description":"Application configuration or provider-specific attributes.","additionalProperties":true},"settings":{"type":"object","description":"Account configuration. Legacy proxy_url is excluded; proxy secrets are encrypted separately.","additionalProperties":true},"last_health_at":{"type":["string","null"],"format":"date-time"},"last_error":{"type":["string","null"]},"stats":{"type":"object","description":"Application configuration or provider-specific attributes.","additionalProperties":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"member_id":{"type":["integer","null"]},"has_credentials":{"type":"boolean"},"proxy_route":{"type":["object","null"],"properties":{"mode":{"type":"string","enum":["direct","custom","managed"]},"fallback_policy":{"type":"string","enum":["hold","reassign","direct_allowed"]},"status":{"type":"string","enum":["pending","active","paused","direct_fallback"],"description":"Connection state of the social account."},"route_version":{"type":"integer","minimum":1},"requested_region":{"type":["string","null"]},"region":{"type":["string","null"]},"health":{"type":"object","description":"Sanitized health check outcome. Contains no proxy URL or credentials.","additionalProperties":true},"endpoint_health":{"type":["string","null"],"enum":["unknown","healthy","degraded","unhealthy","exhausted",null]},"fallback":{"type":"boolean"},"reason":{"type":["string","null"]},"effective_mode":{"type":["string","null"],"enum":["direct","custom","managed",null]}}},"stealth_health":{"type":"object","description":"Derived warmup, risk, cooldown and connection health indicators.","additionalProperties":true},"result":{"type":"object","properties":{"ok":{"type":"boolean"},"status":{"type":["string","null"],"description":"Connection state returned by the gateway.","enum":["connected","connecting","awaiting_challenge","disconnected","blocked","logged_out","challenge","error",null]},"error":{"type":["string","null"]},"error_category":{"type":["string","null"],"enum":["FATAL","TRANSIENT","RATE_LIMITED","SESSION_INVALID","CHALLENGE","ACTION_BLOCKED","NOT_FOUND",null]}}}}},"example":{"id":1,"account_id":1,"social_gateway_instance_id":1,"inbox_id":1,"platform":"instagram","external_user_id":"sample external user id","username":"sample username","display_name":"sample display name","auth_mode":"oauth","access_token":"sample-token","status":"connecting","capabilities":{},"settings":{},"last_health_at":"2026-01-15T10:30:00.000Z","last_error":"sample last error","stats":{},"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","member_id":1,"has_credentials":true,"proxy_route":{"mode":"direct","fallback_policy":"hold","status":"pending","route_version":1,"requested_region":"sample requested region","region":"sample region","health":{},"endpoint_health":"unknown","fallback":true,"reason":"Sample reason.","effective_mode":"direct"},"stealth_health":{},"result":{"ok":true,"status":"connected","error":"sample error","error_category":"FATAL"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"username":{"type":"string"},"password":{"type":"string"},"verification_code":{"type":"string"}}},"example":{"code":"sample code","username":"sample username","password":"sample-password","verification_code":"sample verification code"}}}}}},"/api/v1/accounts/{account_id}/growth_social/accounts/{id}/set_proxy":{"post":{"tags":["Growth Social"],"operationId":"auto_post_api_v1_accounts_account_id_growth_social_accounts_id_set_proxy","summary":"Set proxy accounts","description":"Apply a versioned proxy route to a provisioned Instagram gateway account. Managed mode reserves the shared Super Admin inventory. Hold pauses on failure; direct fallback requires direct_allowed. A response is confirmed only when the gateway acknowledges the requested route version.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"social_gateway_instance_id":{"type":["integer","null"]},"inbox_id":{"type":["integer","null"]},"platform":{"type":"string","enum":["instagram","tiktok","youtube"]},"external_user_id":{"type":["string","null"]},"username":{"type":["string","null"]},"display_name":{"type":["string","null"]},"auth_mode":{"type":"string","enum":["oauth","session_or_password"]},"access_token":{"type":["string","null"],"description":"Masked token only; never the usable access token."},"status":{"type":"string","enum":["connecting","awaiting_challenge","connected","disconnected","blocked","logged_out"],"description":"Connection state of the social account."},"capabilities":{"type":"object","description":"Application configuration or provider-specific attributes.","additionalProperties":true},"settings":{"type":"object","description":"Account configuration. Legacy proxy_url is excluded; proxy secrets are encrypted separately.","additionalProperties":true},"last_health_at":{"type":["string","null"],"format":"date-time"},"last_error":{"type":["string","null"]},"stats":{"type":"object","description":"Application configuration or provider-specific attributes.","additionalProperties":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"member_id":{"type":["integer","null"]},"has_credentials":{"type":"boolean"},"proxy_route":{"type":["object","null"],"properties":{"mode":{"type":"string","enum":["direct","custom","managed"]},"fallback_policy":{"type":"string","enum":["hold","reassign","direct_allowed"]},"status":{"type":"string","enum":["pending","active","paused","direct_fallback"],"description":"Connection state of the social account."},"route_version":{"type":"integer","minimum":1},"requested_region":{"type":["string","null"]},"region":{"type":["string","null"]},"health":{"type":"object","description":"Sanitized health check outcome. Contains no proxy URL or credentials.","additionalProperties":true},"endpoint_health":{"type":["string","null"],"enum":["unknown","healthy","degraded","unhealthy","exhausted",null]},"fallback":{"type":"boolean"},"reason":{"type":["string","null"]},"effective_mode":{"type":["string","null"],"enum":["direct","custom","managed",null]}}},"stealth_health":{"type":"object","description":"Derived warmup, risk, cooldown and connection health indicators.","additionalProperties":true},"result":{"type":"object","properties":{"ok":{"type":"boolean"},"status":{"type":["string","null"],"description":"Connection state returned by the gateway.","enum":["connected","connecting","awaiting_challenge","disconnected","blocked","logged_out","challenge","error",null]},"error":{"type":["string","null"]},"error_category":{"type":["string","null"],"enum":["FATAL","TRANSIENT","RATE_LIMITED","SESSION_INVALID","CHALLENGE","ACTION_BLOCKED","NOT_FOUND",null]}}}}},"example":{"id":1,"account_id":1,"social_gateway_instance_id":1,"inbox_id":1,"platform":"instagram","external_user_id":"sample external user id","username":"sample username","display_name":"sample display name","auth_mode":"oauth","access_token":"sample-token","status":"connecting","capabilities":{},"settings":{},"last_health_at":"2026-01-15T10:30:00.000Z","last_error":"sample last error","stats":{},"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","member_id":1,"has_credentials":true,"proxy_route":{"mode":"direct","fallback_policy":"hold","status":"pending","route_version":1,"requested_region":"sample requested region","region":"sample region","health":{},"endpoint_health":"unknown","fallback":true,"reason":"Sample reason.","effective_mode":"direct"},"stealth_health":{},"result":{"ok":true,"status":"connected","error":"sample error","error_category":"FATAL"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"422":{"description":"Invalid proxy configuration or no eligible managed endpoint.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}},"example":{"error":"sample error"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"mode":{"type":"string","enum":["direct","custom","managed"]},"proxy_url":{"type":"string","writeOnly":true,"description":"Required for custom mode. HTTP, HTTPS or SOCKS5 URL; stored encrypted and never returned."},"fallback_policy":{"type":"string","enum":["hold","reassign","direct_allowed"]},"requested_region":{"type":"string","description":"AUTO or an ISO country code.","example":"BR"}}},"example":{"mode":"custom","proxy_url":"https://proxy.example.com:8080","fallback_policy":"hold","requested_region":"BR"}}}}}},"/api/v1/accounts/{account_id}/growth_social/accounts/{id}/insights":{"get":{"tags":["Growth Social"],"operationId":"auto_get_api_v1_accounts_account_id_growth_social_accounts_id_insights","summary":"Insights accounts","description":"Performs the insights operation on the targeted account resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Normalized native Instagram insights (never raises — degrades when the Graph scope is missing)","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","example":true},"data":{"type":["object","null"],"description":"Flat map of metric name → latest value (nil on failure)","additionalProperties":true,"example":{"reach":1240,"follower_count":5678,"profile_views":91}},"error":{"type":["string","null"],"example":null},"error_category":{"type":["string","null"],"description":"Set on failure (e.g. NOT_FOUND, SESSION_INVALID, FATAL)","example":null}}},"example":{"ok":true,"data":{"reach":1240,"follower_count":5678,"profile_views":91},"error":null,"error_category":null}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"period","in":"query","required":false,"description":"Window the native insights are read for, forwarded to the network.","schema":{"type":"string"},"example":"day"}]}},"/api/v1/accounts/{account_id}/growth_social/accounts":{"get":{"tags":["Growth Social"],"operationId":"auto_get_api_v1_accounts_account_id_growth_social_accounts","summary":"List accounts","description":"Returns the list of accounts visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"social_gateway_instance_id":{"type":["integer","null"]},"inbox_id":{"type":["integer","null"]},"platform":{"type":"string","enum":["instagram","tiktok","youtube"]},"external_user_id":{"type":["string","null"]},"username":{"type":["string","null"]},"display_name":{"type":["string","null"]},"auth_mode":{"type":"string","enum":["oauth","session_or_password"]},"access_token":{"type":["string","null"],"description":"Masked token only; never the usable access token."},"status":{"type":"string","enum":["connecting","awaiting_challenge","connected","disconnected","blocked","logged_out"],"description":"Connection state of the social account."},"capabilities":{"type":"object","description":"Application configuration or provider-specific attributes.","additionalProperties":true},"settings":{"type":"object","description":"Account configuration. Legacy proxy_url is excluded; proxy secrets are encrypted separately.","additionalProperties":true},"last_health_at":{"type":["string","null"],"format":"date-time"},"last_error":{"type":["string","null"]},"stats":{"type":"object","description":"Application configuration or provider-specific attributes.","additionalProperties":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"member_id":{"type":["integer","null"]},"has_credentials":{"type":"boolean"},"proxy_route":{"type":["object","null"],"properties":{"mode":{"type":"string","enum":["direct","custom","managed"]},"fallback_policy":{"type":"string","enum":["hold","reassign","direct_allowed"]},"status":{"type":"string","enum":["pending","active","paused","direct_fallback"],"description":"Connection state of the social account."},"route_version":{"type":"integer","minimum":1},"requested_region":{"type":["string","null"]},"region":{"type":["string","null"]},"health":{"type":"object","description":"Sanitized health check outcome. Contains no proxy URL or credentials.","additionalProperties":true},"endpoint_health":{"type":["string","null"],"enum":["unknown","healthy","degraded","unhealthy","exhausted",null]},"fallback":{"type":"boolean"},"reason":{"type":["string","null"]},"effective_mode":{"type":["string","null"],"enum":["direct","custom","managed",null]}}},"stealth_health":{"type":"object","description":"Derived warmup, risk, cooldown and connection health indicators.","additionalProperties":true}}}},"meta":{"type":"object","properties":{"count":{"type":"integer"}}}}},"example":{"payload":[{"id":1,"account_id":1,"social_gateway_instance_id":1,"inbox_id":1,"platform":"instagram","external_user_id":"sample external user id","username":"sample username","display_name":"sample display name","auth_mode":"oauth","access_token":"sample-token","status":"connecting","capabilities":{},"settings":{},"last_health_at":"2026-01-15T10:30:00.000Z","last_error":"sample last error","stats":{},"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","member_id":1,"has_credentials":true,"proxy_route":{"mode":"direct","fallback_policy":"hold","status":"pending","route_version":1,"requested_region":"sample requested region","region":"sample region","health":{},"endpoint_health":"unknown","fallback":true,"reason":"Sample reason.","effective_mode":"direct"},"stealth_health":{}}],"meta":{"count":5}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"platform","in":"query","required":false,"description":"Restrict to connected accounts of one network.","schema":{"type":"string","enum":["instagram","tiktok","youtube"]},"example":"instagram"},{"name":"status","in":"query","required":false,"description":"Restrict to connections in one state.","schema":{"type":"string","enum":["connecting","awaiting_challenge","connected","disconnected","blocked","logged_out"]},"example":"connected"}]},"post":{"tags":["Growth Social"],"operationId":"auto_post_api_v1_accounts_account_id_growth_social_accounts","summary":"Create accounts","description":"Creates a new account from the request payload. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"social_gateway_instance_id":{"type":["integer","null"]},"inbox_id":{"type":["integer","null"]},"platform":{"type":"string","enum":["instagram","tiktok","youtube"]},"external_user_id":{"type":["string","null"]},"username":{"type":["string","null"]},"display_name":{"type":["string","null"]},"auth_mode":{"type":"string","enum":["oauth","session_or_password"]},"access_token":{"type":["string","null"],"description":"Masked token only; never the usable access token."},"status":{"type":"string","enum":["connecting","awaiting_challenge","connected","disconnected","blocked","logged_out"],"description":"Connection state of the social account."},"capabilities":{"type":"object","description":"Application configuration or provider-specific attributes.","additionalProperties":true},"settings":{"type":"object","description":"Account configuration. Legacy proxy_url is excluded; proxy secrets are encrypted separately.","additionalProperties":true},"last_health_at":{"type":["string","null"],"format":"date-time"},"last_error":{"type":["string","null"]},"stats":{"type":"object","description":"Application configuration or provider-specific attributes.","additionalProperties":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"member_id":{"type":["integer","null"]},"has_credentials":{"type":"boolean"},"proxy_route":{"type":["object","null"],"properties":{"mode":{"type":"string","enum":["direct","custom","managed"]},"fallback_policy":{"type":"string","enum":["hold","reassign","direct_allowed"]},"status":{"type":"string","enum":["pending","active","paused","direct_fallback"],"description":"Connection state of the social account."},"route_version":{"type":"integer","minimum":1},"requested_region":{"type":["string","null"]},"region":{"type":["string","null"]},"health":{"type":"object","description":"Sanitized health check outcome. Contains no proxy URL or credentials.","additionalProperties":true},"endpoint_health":{"type":["string","null"],"enum":["unknown","healthy","degraded","unhealthy","exhausted",null]},"fallback":{"type":"boolean"},"reason":{"type":["string","null"]},"effective_mode":{"type":["string","null"],"enum":["direct","custom","managed",null]}}},"stealth_health":{"type":"object","description":"Derived warmup, risk, cooldown and connection health indicators.","additionalProperties":true}}},"example":{"id":1,"account_id":1,"social_gateway_instance_id":1,"inbox_id":1,"platform":"instagram","external_user_id":"sample external user id","username":"sample username","display_name":"sample display name","auth_mode":"oauth","access_token":"sample-token","status":"connecting","capabilities":{},"settings":{},"last_health_at":"2026-01-15T10:30:00.000Z","last_error":"sample last error","stats":{},"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","member_id":1,"has_credentials":true,"proxy_route":{"mode":"direct","fallback_policy":"hold","status":"pending","route_version":1,"requested_region":"sample requested region","region":"sample region","health":{},"endpoint_health":"unknown","fallback":true,"reason":"Sample reason.","effective_mode":"direct"},"stealth_health":{}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"platform":{"type":"string","enum":["instagram","tiktok","youtube"]},"auth_mode":{"type":"string","enum":["oauth","session_or_password"]},"inbox_id":{"type":"integer"},"social_gateway_instance_id":{"type":"integer"},"username":{"type":"string"},"display_name":{"type":"string"}},"required":["platform"]},"example":{"platform":"instagram","auth_mode":"oauth","inbox_id":1,"social_gateway_instance_id":1,"username":"sample username","display_name":"sample display name"}}}}}},"/api/v1/accounts/{account_id}/growth_social/accounts/{id}":{"get":{"tags":["Growth Social"],"operationId":"auto_get_api_v1_accounts_account_id_growth_social_accounts_id","summary":"Get accounts","description":"Returns the account identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"social_gateway_instance_id":{"type":["integer","null"]},"inbox_id":{"type":["integer","null"]},"platform":{"type":"string","enum":["instagram","tiktok","youtube"]},"external_user_id":{"type":["string","null"]},"username":{"type":["string","null"]},"display_name":{"type":["string","null"]},"auth_mode":{"type":"string","enum":["oauth","session_or_password"]},"access_token":{"type":["string","null"],"description":"Masked token only; never the usable access token."},"status":{"type":"string","enum":["connecting","awaiting_challenge","connected","disconnected","blocked","logged_out"],"description":"Connection state of the social account."},"capabilities":{"type":"object","description":"Application configuration or provider-specific attributes.","additionalProperties":true},"settings":{"type":"object","description":"Account configuration. Legacy proxy_url is excluded; proxy secrets are encrypted separately.","additionalProperties":true},"last_health_at":{"type":["string","null"],"format":"date-time"},"last_error":{"type":["string","null"]},"stats":{"type":"object","description":"Application configuration or provider-specific attributes.","additionalProperties":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"member_id":{"type":["integer","null"]},"has_credentials":{"type":"boolean"},"proxy_route":{"type":["object","null"],"properties":{"mode":{"type":"string","enum":["direct","custom","managed"]},"fallback_policy":{"type":"string","enum":["hold","reassign","direct_allowed"]},"status":{"type":"string","enum":["pending","active","paused","direct_fallback"],"description":"Connection state of the social account."},"route_version":{"type":"integer","minimum":1},"requested_region":{"type":["string","null"]},"region":{"type":["string","null"]},"health":{"type":"object","description":"Sanitized health check outcome. Contains no proxy URL or credentials.","additionalProperties":true},"endpoint_health":{"type":["string","null"],"enum":["unknown","healthy","degraded","unhealthy","exhausted",null]},"fallback":{"type":"boolean"},"reason":{"type":["string","null"]},"effective_mode":{"type":["string","null"],"enum":["direct","custom","managed",null]}}},"stealth_health":{"type":"object","description":"Derived warmup, risk, cooldown and connection health indicators.","additionalProperties":true}}},"example":{"id":1,"account_id":1,"social_gateway_instance_id":1,"inbox_id":1,"platform":"instagram","external_user_id":"sample external user id","username":"sample username","display_name":"sample display name","auth_mode":"oauth","access_token":"sample-token","status":"connecting","capabilities":{},"settings":{},"last_health_at":"2026-01-15T10:30:00.000Z","last_error":"sample last error","stats":{},"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","member_id":1,"has_credentials":true,"proxy_route":{"mode":"direct","fallback_policy":"hold","status":"pending","route_version":1,"requested_region":"sample requested region","region":"sample region","health":{},"endpoint_health":"unknown","fallback":true,"reason":"Sample reason.","effective_mode":"direct"},"stealth_health":{}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]},"patch":{"tags":["Growth Social"],"operationId":"auto_patch_api_v1_accounts_account_id_growth_social_accounts_id","summary":"Update accounts","description":"Updates the account identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"social_gateway_instance_id":{"type":["integer","null"]},"inbox_id":{"type":["integer","null"]},"platform":{"type":"string","enum":["instagram","tiktok","youtube"]},"external_user_id":{"type":["string","null"]},"username":{"type":["string","null"]},"display_name":{"type":["string","null"]},"auth_mode":{"type":"string","enum":["oauth","session_or_password"]},"access_token":{"type":["string","null"],"description":"Masked token only; never the usable access token."},"status":{"type":"string","enum":["connecting","awaiting_challenge","connected","disconnected","blocked","logged_out"],"description":"Connection state of the social account."},"capabilities":{"type":"object","description":"Application configuration or provider-specific attributes.","additionalProperties":true},"settings":{"type":"object","description":"Account configuration. Legacy proxy_url is excluded; proxy secrets are encrypted separately.","additionalProperties":true},"last_health_at":{"type":["string","null"],"format":"date-time"},"last_error":{"type":["string","null"]},"stats":{"type":"object","description":"Application configuration or provider-specific attributes.","additionalProperties":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"member_id":{"type":["integer","null"]},"has_credentials":{"type":"boolean"},"proxy_route":{"type":["object","null"],"properties":{"mode":{"type":"string","enum":["direct","custom","managed"]},"fallback_policy":{"type":"string","enum":["hold","reassign","direct_allowed"]},"status":{"type":"string","enum":["pending","active","paused","direct_fallback"],"description":"Connection state of the social account."},"route_version":{"type":"integer","minimum":1},"requested_region":{"type":["string","null"]},"region":{"type":["string","null"]},"health":{"type":"object","description":"Sanitized health check outcome. Contains no proxy URL or credentials.","additionalProperties":true},"endpoint_health":{"type":["string","null"],"enum":["unknown","healthy","degraded","unhealthy","exhausted",null]},"fallback":{"type":"boolean"},"reason":{"type":["string","null"]},"effective_mode":{"type":["string","null"],"enum":["direct","custom","managed",null]}}},"stealth_health":{"type":"object","description":"Derived warmup, risk, cooldown and connection health indicators.","additionalProperties":true}}},"example":{"id":1,"account_id":1,"social_gateway_instance_id":1,"inbox_id":1,"platform":"instagram","external_user_id":"sample external user id","username":"sample username","display_name":"sample display name","auth_mode":"oauth","access_token":"sample-token","status":"connecting","capabilities":{},"settings":{},"last_health_at":"2026-01-15T10:30:00.000Z","last_error":"sample last error","stats":{},"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","member_id":1,"has_credentials":true,"proxy_route":{"mode":"direct","fallback_policy":"hold","status":"pending","route_version":1,"requested_region":"sample requested region","region":"sample region","health":{},"endpoint_health":"unknown","fallback":true,"reason":"Sample reason.","effective_mode":"direct"},"stealth_health":{}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"platform":{"type":"string","enum":["instagram","tiktok","youtube"]},"auth_mode":{"type":"string","enum":["oauth","session_or_password"]},"inbox_id":{"type":"integer"},"social_gateway_instance_id":{"type":"integer"},"username":{"type":"string"},"display_name":{"type":"string"}}},"example":{"platform":"instagram","auth_mode":"oauth","inbox_id":1,"social_gateway_instance_id":1,"username":"sample username","display_name":"sample display name"}}}}},"put":{"tags":["Growth Social"],"operationId":"auto_put_api_v1_accounts_account_id_growth_social_accounts_id","summary":"Update accounts","description":"Updates the account identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"social_gateway_instance_id":{"type":["integer","null"]},"inbox_id":{"type":["integer","null"]},"platform":{"type":"string","enum":["instagram","tiktok","youtube"]},"external_user_id":{"type":["string","null"]},"username":{"type":["string","null"]},"display_name":{"type":["string","null"]},"auth_mode":{"type":"string","enum":["oauth","session_or_password"]},"access_token":{"type":["string","null"],"description":"Masked token only; never the usable access token."},"status":{"type":"string","enum":["connecting","awaiting_challenge","connected","disconnected","blocked","logged_out"],"description":"Connection state of the social account."},"capabilities":{"type":"object","description":"Application configuration or provider-specific attributes.","additionalProperties":true},"settings":{"type":"object","description":"Account configuration. Legacy proxy_url is excluded; proxy secrets are encrypted separately.","additionalProperties":true},"last_health_at":{"type":["string","null"],"format":"date-time"},"last_error":{"type":["string","null"]},"stats":{"type":"object","description":"Application configuration or provider-specific attributes.","additionalProperties":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"member_id":{"type":["integer","null"]},"has_credentials":{"type":"boolean"},"proxy_route":{"type":["object","null"],"properties":{"mode":{"type":"string","enum":["direct","custom","managed"]},"fallback_policy":{"type":"string","enum":["hold","reassign","direct_allowed"]},"status":{"type":"string","enum":["pending","active","paused","direct_fallback"],"description":"Connection state of the social account."},"route_version":{"type":"integer","minimum":1},"requested_region":{"type":["string","null"]},"region":{"type":["string","null"]},"health":{"type":"object","description":"Sanitized health check outcome. Contains no proxy URL or credentials.","additionalProperties":true},"endpoint_health":{"type":["string","null"],"enum":["unknown","healthy","degraded","unhealthy","exhausted",null]},"fallback":{"type":"boolean"},"reason":{"type":["string","null"]},"effective_mode":{"type":["string","null"],"enum":["direct","custom","managed",null]}}},"stealth_health":{"type":"object","description":"Derived warmup, risk, cooldown and connection health indicators.","additionalProperties":true}}},"example":{"id":1,"account_id":1,"social_gateway_instance_id":1,"inbox_id":1,"platform":"instagram","external_user_id":"sample external user id","username":"sample username","display_name":"sample display name","auth_mode":"oauth","access_token":"sample-token","status":"connecting","capabilities":{},"settings":{},"last_health_at":"2026-01-15T10:30:00.000Z","last_error":"sample last error","stats":{},"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","member_id":1,"has_credentials":true,"proxy_route":{"mode":"direct","fallback_policy":"hold","status":"pending","route_version":1,"requested_region":"sample requested region","region":"sample region","health":{},"endpoint_health":"unknown","fallback":true,"reason":"Sample reason.","effective_mode":"direct"},"stealth_health":{}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"platform":{"type":"string","enum":["instagram","tiktok","youtube"]},"auth_mode":{"type":"string","enum":["oauth","session_or_password"]},"inbox_id":{"type":"integer"},"social_gateway_instance_id":{"type":"integer"},"username":{"type":"string"},"display_name":{"type":"string"}}},"example":{"platform":"instagram","auth_mode":"oauth","inbox_id":1,"social_gateway_instance_id":1,"username":"sample username","display_name":"sample display name"}}}}},"delete":{"tags":["Growth Social"],"operationId":"auto_delete_api_v1_accounts_account_id_growth_social_accounts_id","summary":"Delete accounts","description":"Deletes the account identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Success (no content)"},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/growth_social/monitors":{"get":{"tags":["Growth Social"],"operationId":"auto_get_api_v1_accounts_account_id_growth_social_monitors","summary":"List monitors","description":"Returns the list of monitors visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"growth_social_account_id":{"type":"integer"},"kind":{"type":"string","enum":["account_stats","post_stats","comments","followers","hashtag","competitor_profile","following","post_likers","post_commenters","location_audience"]},"target":{"type":["string","null"]},"schedule_minutes":{"type":"integer"},"last_run_at":{"type":["string","null"],"format":"date-time"},"last_cursor":{"type":["string","null"]},"active":{"type":"boolean"},"settings":{"type":"object","properties":{"collection":{"type":"object","properties":{"status":{"type":"string","enum":["ok","retrying","failed"]},"last_error_category":{"type":"string","enum":["FATAL","TRANSIENT","RATE_LIMITED","SESSION_INVALID","CHALLENGE","ACTION_BLOCKED","NOT_FOUND"]},"last_error_at":{"type":"string","format":"date-time"},"next_retry_at":{"type":["string","null"],"format":"date-time"},"consecutive_failures":{"type":"integer","minimum":0}}}},"description":"Collection state. PATCH collection:{} to clear a retry/failure hold for an explicit retry.","additionalProperties":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}},"meta":{"type":"object","properties":{"count":{"type":"integer"}}}}},"example":{"payload":[{"id":1,"growth_social_account_id":1,"kind":"account_stats","target":"sample target","schedule_minutes":60,"last_run_at":"2026-01-15T10:30:00.000Z","last_cursor":"sample last cursor","active":true,"settings":{"collection":{"status":"ok","last_error_category":"FATAL","last_error_at":"2026-01-15T10:30:00.000Z","next_retry_at":"2026-01-15T10:30:00.000Z","consecutive_failures":1}},"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}],"meta":{"count":5}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"social_account_id","in":"query","required":false,"description":"Restrict to monitors of one connected account.","schema":{"type":"integer"},"example":8},{"name":"kind","in":"query","required":false,"description":"Restrict to one monitor kind.","schema":{"type":"string","enum":["account_stats","post_stats","comments","followers","hashtag","competitor_profile","following","post_likers","post_commenters","location_audience"]},"example":"comments"}]},"post":{"tags":["Growth Social"],"operationId":"auto_post_api_v1_accounts_account_id_growth_social_monitors","summary":"Create monitors","description":"Creates a new monitor from the request payload. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"growth_social_account_id":{"type":"integer"},"kind":{"type":"string","enum":["account_stats","post_stats","comments","followers","hashtag","competitor_profile","following","post_likers","post_commenters","location_audience"]},"target":{"type":["string","null"]},"schedule_minutes":{"type":"integer"},"last_run_at":{"type":["string","null"],"format":"date-time"},"last_cursor":{"type":["string","null"]},"active":{"type":"boolean"},"settings":{"type":"object","properties":{"collection":{"type":"object","properties":{"status":{"type":"string","enum":["ok","retrying","failed"]},"last_error_category":{"type":"string","enum":["FATAL","TRANSIENT","RATE_LIMITED","SESSION_INVALID","CHALLENGE","ACTION_BLOCKED","NOT_FOUND"]},"last_error_at":{"type":"string","format":"date-time"},"next_retry_at":{"type":["string","null"],"format":"date-time"},"consecutive_failures":{"type":"integer","minimum":0}}}},"description":"Collection state. PATCH collection:{} to clear a retry/failure hold for an explicit retry.","additionalProperties":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"example":{"id":1,"growth_social_account_id":1,"kind":"account_stats","target":"sample target","schedule_minutes":60,"last_run_at":"2026-01-15T10:30:00.000Z","last_cursor":"sample last cursor","active":true,"settings":{"collection":{"status":"ok","last_error_category":"FATAL","last_error_at":"2026-01-15T10:30:00.000Z","next_retry_at":"2026-01-15T10:30:00.000Z","consecutive_failures":1}},"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"growth_social_account_id":{"type":"integer"},"kind":{"type":"string","enum":["account_stats","post_stats","comments","followers","hashtag","competitor_profile","following","post_likers","post_commenters","location_audience"]},"target":{"type":["string","null"]},"schedule_minutes":{"type":"integer","minimum":5},"active":{"type":"boolean"},"settings":{"type":"object","properties":{"collection":{"type":"object","properties":{"status":{"type":"string","enum":["ok","retrying","failed"]},"last_error_category":{"type":"string","enum":["FATAL","TRANSIENT","RATE_LIMITED","SESSION_INVALID","CHALLENGE","ACTION_BLOCKED","NOT_FOUND"]},"last_error_at":{"type":"string","format":"date-time"},"next_retry_at":{"type":["string","null"],"format":"date-time"},"consecutive_failures":{"type":"integer","minimum":0}}}},"description":"Collection state. PATCH collection:{} to clear a retry/failure hold for an explicit retry.","additionalProperties":true}}},"example":{"growth_social_account_id":1,"kind":"account_stats","target":"sample target","schedule_minutes":60,"active":true,"settings":{"collection":{"status":"ok","last_error_category":"FATAL","last_error_at":"2026-01-15T10:30:00.000Z","next_retry_at":"2026-01-15T10:30:00.000Z","consecutive_failures":1}}}}}}}},"/api/v1/accounts/{account_id}/growth_social/monitors/{id}":{"get":{"tags":["Growth Social"],"operationId":"auto_get_api_v1_accounts_account_id_growth_social_monitors_id","summary":"Get monitors","description":"Returns the monitor identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"growth_social_account_id":{"type":"integer"},"kind":{"type":"string","enum":["account_stats","post_stats","comments","followers","hashtag","competitor_profile","following","post_likers","post_commenters","location_audience"]},"target":{"type":["string","null"]},"schedule_minutes":{"type":"integer"},"last_run_at":{"type":["string","null"],"format":"date-time"},"last_cursor":{"type":["string","null"]},"active":{"type":"boolean"},"settings":{"type":"object","properties":{"collection":{"type":"object","properties":{"status":{"type":"string","enum":["ok","retrying","failed"]},"last_error_category":{"type":"string","enum":["FATAL","TRANSIENT","RATE_LIMITED","SESSION_INVALID","CHALLENGE","ACTION_BLOCKED","NOT_FOUND"]},"last_error_at":{"type":"string","format":"date-time"},"next_retry_at":{"type":["string","null"],"format":"date-time"},"consecutive_failures":{"type":"integer","minimum":0}}}},"description":"Collection state. PATCH collection:{} to clear a retry/failure hold for an explicit retry.","additionalProperties":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"example":{"id":1,"growth_social_account_id":1,"kind":"account_stats","target":"sample target","schedule_minutes":60,"last_run_at":"2026-01-15T10:30:00.000Z","last_cursor":"sample last cursor","active":true,"settings":{"collection":{"status":"ok","last_error_category":"FATAL","last_error_at":"2026-01-15T10:30:00.000Z","next_retry_at":"2026-01-15T10:30:00.000Z","consecutive_failures":1}},"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]},"patch":{"tags":["Growth Social"],"operationId":"auto_patch_api_v1_accounts_account_id_growth_social_monitors_id","summary":"Update monitors","description":"Updates the monitor identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"growth_social_account_id":{"type":"integer"},"kind":{"type":"string","enum":["account_stats","post_stats","comments","followers","hashtag","competitor_profile","following","post_likers","post_commenters","location_audience"]},"target":{"type":["string","null"]},"schedule_minutes":{"type":"integer"},"last_run_at":{"type":["string","null"],"format":"date-time"},"last_cursor":{"type":["string","null"]},"active":{"type":"boolean"},"settings":{"type":"object","properties":{"collection":{"type":"object","properties":{"status":{"type":"string","enum":["ok","retrying","failed"]},"last_error_category":{"type":"string","enum":["FATAL","TRANSIENT","RATE_LIMITED","SESSION_INVALID","CHALLENGE","ACTION_BLOCKED","NOT_FOUND"]},"last_error_at":{"type":"string","format":"date-time"},"next_retry_at":{"type":["string","null"],"format":"date-time"},"consecutive_failures":{"type":"integer","minimum":0}}}},"description":"Collection state. PATCH collection:{} to clear a retry/failure hold for an explicit retry.","additionalProperties":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"example":{"id":1,"growth_social_account_id":1,"kind":"account_stats","target":"sample target","schedule_minutes":60,"last_run_at":"2026-01-15T10:30:00.000Z","last_cursor":"sample last cursor","active":true,"settings":{"collection":{"status":"ok","last_error_category":"FATAL","last_error_at":"2026-01-15T10:30:00.000Z","next_retry_at":"2026-01-15T10:30:00.000Z","consecutive_failures":1}},"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"growth_social_account_id":{"type":"integer"},"kind":{"type":"string","enum":["account_stats","post_stats","comments","followers","hashtag","competitor_profile","following","post_likers","post_commenters","location_audience"]},"target":{"type":["string","null"]},"schedule_minutes":{"type":"integer","minimum":5},"active":{"type":"boolean"},"settings":{"type":"object","properties":{"collection":{"type":"object","properties":{"status":{"type":"string","enum":["ok","retrying","failed"]},"last_error_category":{"type":"string","enum":["FATAL","TRANSIENT","RATE_LIMITED","SESSION_INVALID","CHALLENGE","ACTION_BLOCKED","NOT_FOUND"]},"last_error_at":{"type":"string","format":"date-time"},"next_retry_at":{"type":["string","null"],"format":"date-time"},"consecutive_failures":{"type":"integer","minimum":0}}}},"description":"Collection state. PATCH collection:{} to clear a retry/failure hold for an explicit retry.","additionalProperties":true}}},"example":{"growth_social_account_id":1,"kind":"account_stats","target":"sample target","schedule_minutes":60,"active":true,"settings":{"collection":{"status":"ok","last_error_category":"FATAL","last_error_at":"2026-01-15T10:30:00.000Z","next_retry_at":"2026-01-15T10:30:00.000Z","consecutive_failures":1}}}}}}},"put":{"tags":["Growth Social"],"operationId":"auto_put_api_v1_accounts_account_id_growth_social_monitors_id","summary":"Update monitors","description":"Updates the monitor identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"growth_social_account_id":{"type":"integer"},"kind":{"type":"string","enum":["account_stats","post_stats","comments","followers","hashtag","competitor_profile","following","post_likers","post_commenters","location_audience"]},"target":{"type":["string","null"]},"schedule_minutes":{"type":"integer"},"last_run_at":{"type":["string","null"],"format":"date-time"},"last_cursor":{"type":["string","null"]},"active":{"type":"boolean"},"settings":{"type":"object","properties":{"collection":{"type":"object","properties":{"status":{"type":"string","enum":["ok","retrying","failed"]},"last_error_category":{"type":"string","enum":["FATAL","TRANSIENT","RATE_LIMITED","SESSION_INVALID","CHALLENGE","ACTION_BLOCKED","NOT_FOUND"]},"last_error_at":{"type":"string","format":"date-time"},"next_retry_at":{"type":["string","null"],"format":"date-time"},"consecutive_failures":{"type":"integer","minimum":0}}}},"description":"Collection state. PATCH collection:{} to clear a retry/failure hold for an explicit retry.","additionalProperties":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"example":{"id":1,"growth_social_account_id":1,"kind":"account_stats","target":"sample target","schedule_minutes":60,"last_run_at":"2026-01-15T10:30:00.000Z","last_cursor":"sample last cursor","active":true,"settings":{"collection":{"status":"ok","last_error_category":"FATAL","last_error_at":"2026-01-15T10:30:00.000Z","next_retry_at":"2026-01-15T10:30:00.000Z","consecutive_failures":1}},"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"growth_social_account_id":{"type":"integer"},"kind":{"type":"string","enum":["account_stats","post_stats","comments","followers","hashtag","competitor_profile","following","post_likers","post_commenters","location_audience"]},"target":{"type":["string","null"]},"schedule_minutes":{"type":"integer","minimum":5},"active":{"type":"boolean"},"settings":{"type":"object","properties":{"collection":{"type":"object","properties":{"status":{"type":"string","enum":["ok","retrying","failed"]},"last_error_category":{"type":"string","enum":["FATAL","TRANSIENT","RATE_LIMITED","SESSION_INVALID","CHALLENGE","ACTION_BLOCKED","NOT_FOUND"]},"last_error_at":{"type":"string","format":"date-time"},"next_retry_at":{"type":["string","null"],"format":"date-time"},"consecutive_failures":{"type":"integer","minimum":0}}}},"description":"Collection state. PATCH collection:{} to clear a retry/failure hold for an explicit retry.","additionalProperties":true}}},"example":{"growth_social_account_id":1,"kind":"account_stats","target":"sample target","schedule_minutes":60,"active":true,"settings":{"collection":{"status":"ok","last_error_category":"FATAL","last_error_at":"2026-01-15T10:30:00.000Z","next_retry_at":"2026-01-15T10:30:00.000Z","consecutive_failures":1}}}}}}},"delete":{"tags":["Growth Social"],"operationId":"auto_delete_api_v1_accounts_account_id_growth_social_monitors_id","summary":"Delete monitors","description":"Deletes the monitor identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Success (no content)"},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/growth_social/metrics/report":{"get":{"tags":["Growth Social"],"operationId":"auto_get_api_v1_accounts_account_id_growth_social_metrics_report","summary":"Report metrics","description":"Performs the report operation on the targeted metric resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"string"}}},"example":{"payload":"sample payload"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"since","in":"query","required":false,"description":"Only aggregate activity at or after this instant. Omitted, the service window applies.","schema":{"type":"string","format":"date-time"},"example":"2026-07-01T00:00:00Z"},{"name":"social_account_id","in":"query","required":false,"description":"Restrict metrics and report aggregates to a connected social account.","schema":{"type":"integer"}}]}},"/api/v1/accounts/{account_id}/growth_social/metrics":{"get":{"tags":["Growth Social"],"operationId":"auto_get_api_v1_accounts_account_id_growth_social_metrics","summary":"List metrics","description":"Returns the list of metrics visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Free-form object."}},"meta":{"type":"object","properties":{"count":{"type":"integer"}}}}},"example":{"payload":[{}],"meta":{"count":5}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."}]}},"/api/v1/accounts/{account_id}/growth_social/actions/{id}/reconcile":{"post":{"tags":["Growth Social"],"operationId":"auto_post_api_v1_accounts_account_id_growth_social_actions_id_reconcile","summary":"Reconcile actions","description":"Resolve a sent or uncertain action using operator evidence. Delivered requires external_id. Updates the gateway ledger and the application audit with the acting user; never resends the operation.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"growth_social_account_id":{"type":"integer"},"action":{"type":"string","enum":["like_post","comment","reply","follow","unfollow","like_comment","direct_message","like_recent_posts","view_story","save_post"]},"target_id":{"type":["string","null"]},"idempotency_key":{"type":"string"},"status":{"type":"string","enum":["queued","throttled","sent","succeeded","failed","blocked","uncertain"]},"params":{"type":"object","properties":{"text":{"type":"string","description":"Fixed or composed outgoing message."},"brief":{"type":"string","description":"Maestro generation instruction."},"n":{"type":"integer","minimum":1},"replied_to_comment_id":{"type":"string"}},"description":"Action-specific parameters; additional provider options may be preserved.","additionalProperties":true},"result":{"type":"object","properties":{"reconciliation":{"type":"object","properties":{"outcome":{"type":"string","enum":["delivered","failed"]},"note":{"type":"string"},"external_id":{"type":"string"},"user_id":{"type":"integer"}}}},"description":"Provider execution outcome and optional operator reconciliation audit.","additionalProperties":true},"error":{"type":["string","null"]},"error_category":{"type":["string","null"]},"retryable":{"type":"boolean"},"attempts":{"type":"integer"},"scheduled_at":{"type":["string","null"],"format":"date-time"},"executed_at":{"type":["string","null"],"format":"date-time"},"triggered_by":{"type":"string","enum":["rule","maestro","manual"]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"example":{"id":1,"growth_social_account_id":1,"action":"like_post","target_id":"sample target id","idempotency_key":"sample-token","status":"queued","params":{"text":"sample text","brief":"sample brief","n":1,"replied_to_comment_id":"sample replied to comment id"},"result":{"reconciliation":{"outcome":"delivered","note":"Sample note.","external_id":"sample external id","user_id":1}},"error":"sample error","error_category":"sample error category","retryable":true,"attempts":1,"scheduled_at":"2026-01-15T10:30:00.000Z","executed_at":"2026-01-15T10:30:00.000Z","triggered_by":"rule","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"422":{"description":"Invalid evidence, action not reconcilable or gateway reconciliation rejected.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}},"example":{"error":"sample error"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"outcome":{"type":"string","enum":["delivered","failed"]},"note":{"type":"string","minLength":1},"external_id":{"type":"string","description":"Required when outcome is delivered; provider evidence for the completed operation."}},"required":["outcome","note"],"allOf":[{"if":{"properties":{"outcome":{"const":"delivered"}},"required":["outcome"]},"then":{"required":["external_id"]}}]},"example":{"outcome":"delivered","note":"Verified the completed operation in the provider ledger.","external_id":"provider-message-123"}}}}}},"/api/v1/accounts/{account_id}/growth_social/actions":{"get":{"tags":["Growth Social"],"operationId":"auto_get_api_v1_accounts_account_id_growth_social_actions","summary":"List actions","description":"Returns the list of actions visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"growth_social_account_id":{"type":"integer"},"action":{"type":"string","enum":["like_post","comment","reply","follow","unfollow","like_comment","direct_message","like_recent_posts","view_story","save_post"]},"target_id":{"type":["string","null"]},"idempotency_key":{"type":"string"},"status":{"type":"string","enum":["queued","throttled","sent","succeeded","failed","blocked","uncertain"]},"params":{"type":"object","properties":{"text":{"type":"string","description":"Fixed or composed outgoing message."},"brief":{"type":"string","description":"Maestro generation instruction."},"n":{"type":"integer","minimum":1},"replied_to_comment_id":{"type":"string"}},"description":"Action-specific parameters; additional provider options may be preserved.","additionalProperties":true},"result":{"type":"object","properties":{"reconciliation":{"type":"object","properties":{"outcome":{"type":"string","enum":["delivered","failed"]},"note":{"type":"string"},"external_id":{"type":"string"},"user_id":{"type":"integer"}}}},"description":"Provider execution outcome and optional operator reconciliation audit.","additionalProperties":true},"error":{"type":["string","null"]},"error_category":{"type":["string","null"]},"retryable":{"type":"boolean"},"attempts":{"type":"integer"},"scheduled_at":{"type":["string","null"],"format":"date-time"},"executed_at":{"type":["string","null"],"format":"date-time"},"triggered_by":{"type":"string","enum":["rule","maestro","manual"]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}},"meta":{"type":"object","properties":{"count":{"type":"integer"}}}}},"example":{"payload":[{"id":1,"growth_social_account_id":1,"action":"like_post","target_id":"sample target id","idempotency_key":"sample-token","status":"queued","params":{"text":"sample text","brief":"sample brief","n":1,"replied_to_comment_id":"sample replied to comment id"},"result":{"reconciliation":{"outcome":"delivered","note":"Sample note.","external_id":"sample external id","user_id":1}},"error":"sample error","error_category":"sample error category","retryable":true,"attempts":1,"scheduled_at":"2026-01-15T10:30:00.000Z","executed_at":"2026-01-15T10:30:00.000Z","triggered_by":"rule","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}],"meta":{"count":5}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"social_account_id","in":"query","required":false,"description":"Filter by connected social account.","schema":{"type":"integer"}},{"name":"action_type","in":"query","required":false,"description":"Filter by operation.","schema":{"type":"string","enum":["like_post","comment","reply","follow","unfollow","like_comment","direct_message","like_recent_posts","view_story","save_post"]}},{"name":"status","in":"query","required":false,"description":"Filter by ledger status, including uncertain delivery.","schema":{"type":"string","enum":["queued","throttled","sent","succeeded","failed","blocked","uncertain"]}},{"name":"page","in":"query","required":false,"description":"Page number.","schema":{"type":"integer","minimum":1,"default":1}},{"name":"per_page","in":"query","required":false,"description":"Page size.","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}}]},"post":{"tags":["Growth Social"],"operationId":"auto_post_api_v1_accounts_account_id_growth_social_actions","summary":"Create actions","description":"Creates a new action from the request payload. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"growth_social_account_id":{"type":"integer"},"action":{"type":"string","enum":["like_post","comment","reply","follow","unfollow","like_comment","direct_message","like_recent_posts","view_story","save_post"]},"target_id":{"type":["string","null"]},"idempotency_key":{"type":"string"},"status":{"type":"string","enum":["queued","throttled","sent","succeeded","failed","blocked","uncertain"]},"params":{"type":"object","properties":{"text":{"type":"string","description":"Fixed or composed outgoing message."},"brief":{"type":"string","description":"Maestro generation instruction."},"n":{"type":"integer","minimum":1},"replied_to_comment_id":{"type":"string"}},"description":"Action-specific parameters; additional provider options may be preserved.","additionalProperties":true},"result":{"type":"object","properties":{"reconciliation":{"type":"object","properties":{"outcome":{"type":"string","enum":["delivered","failed"]},"note":{"type":"string"},"external_id":{"type":"string"},"user_id":{"type":"integer"}}}},"description":"Provider execution outcome and optional operator reconciliation audit.","additionalProperties":true},"error":{"type":["string","null"]},"error_category":{"type":["string","null"]},"retryable":{"type":"boolean"},"attempts":{"type":"integer"},"scheduled_at":{"type":["string","null"],"format":"date-time"},"executed_at":{"type":["string","null"],"format":"date-time"},"triggered_by":{"type":"string","enum":["rule","maestro","manual"]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"example":{"id":1,"growth_social_account_id":1,"action":"like_post","target_id":"sample target id","idempotency_key":"sample-token","status":"queued","params":{"text":"sample text","brief":"sample brief","n":1,"replied_to_comment_id":"sample replied to comment id"},"result":{"reconciliation":{"outcome":"delivered","note":"Sample note.","external_id":"sample external id","user_id":1}},"error":"sample error","error_category":"sample error category","retryable":true,"attempts":1,"scheduled_at":"2026-01-15T10:30:00.000Z","executed_at":"2026-01-15T10:30:00.000Z","triggered_by":"rule","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"growth_social_account_id":{"type":"integer"},"action_type":{"type":"string","enum":["like_post","comment","reply","follow","unfollow","like_comment","direct_message","like_recent_posts","view_story","save_post"]},"target_id":{"type":"string"},"params":{"type":"object","properties":{"text":{"type":"string","description":"Fixed or composed outgoing message."},"brief":{"type":"string","description":"Maestro generation instruction."},"n":{"type":"integer","minimum":1},"replied_to_comment_id":{"type":"string"}},"description":"Action-specific parameters; additional provider options may be preserved.","additionalProperties":true}}},"example":{"growth_social_account_id":1,"action_type":"like_post","target_id":"sample target id","params":{"text":"sample text","brief":"sample brief","n":1,"replied_to_comment_id":"sample replied to comment id"}}}}}}},"/api/v1/accounts/{account_id}/growth_social/actions/{id}":{"get":{"tags":["Growth Social"],"operationId":"auto_get_api_v1_accounts_account_id_growth_social_actions_id","summary":"Get actions","description":"Returns the action identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"growth_social_account_id":{"type":"integer"},"action":{"type":"string","enum":["like_post","comment","reply","follow","unfollow","like_comment","direct_message","like_recent_posts","view_story","save_post"]},"target_id":{"type":["string","null"]},"idempotency_key":{"type":"string"},"status":{"type":"string","enum":["queued","throttled","sent","succeeded","failed","blocked","uncertain"]},"params":{"type":"object","properties":{"text":{"type":"string","description":"Fixed or composed outgoing message."},"brief":{"type":"string","description":"Maestro generation instruction."},"n":{"type":"integer","minimum":1},"replied_to_comment_id":{"type":"string"}},"description":"Action-specific parameters; additional provider options may be preserved.","additionalProperties":true},"result":{"type":"object","properties":{"reconciliation":{"type":"object","properties":{"outcome":{"type":"string","enum":["delivered","failed"]},"note":{"type":"string"},"external_id":{"type":"string"},"user_id":{"type":"integer"}}}},"description":"Provider execution outcome and optional operator reconciliation audit.","additionalProperties":true},"error":{"type":["string","null"]},"error_category":{"type":["string","null"]},"retryable":{"type":"boolean"},"attempts":{"type":"integer"},"scheduled_at":{"type":["string","null"],"format":"date-time"},"executed_at":{"type":["string","null"],"format":"date-time"},"triggered_by":{"type":"string","enum":["rule","maestro","manual"]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"example":{"id":1,"growth_social_account_id":1,"action":"like_post","target_id":"sample target id","idempotency_key":"sample-token","status":"queued","params":{"text":"sample text","brief":"sample brief","n":1,"replied_to_comment_id":"sample replied to comment id"},"result":{"reconciliation":{"outcome":"delivered","note":"Sample note.","external_id":"sample external id","user_id":1}},"error":"sample error","error_category":"sample error category","retryable":true,"attempts":1,"scheduled_at":"2026-01-15T10:30:00.000Z","executed_at":"2026-01-15T10:30:00.000Z","triggered_by":"rule","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/growth_social/automation_rules":{"get":{"tags":["Growth Social"],"operationId":"auto_get_api_v1_accounts_account_id_growth_social_automation_rules","summary":"List automation rules","description":"Returns the list of automation rules visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"growth_social_account_id":{"type":["integer","null"]},"name":{"type":["string","null"]},"trigger_event":{"type":"string","enum":["new_follower","new_comment","mention","follower_milestone","scheduled"]},"conditions":{"type":"object","properties":{"keywords":{"type":"array","items":{"type":"string"}},"followers_at_least":{"type":"integer","minimum":1}},"description":"Keywords match comment or mention text by case-insensitive contains. Milestones require a positive follower threshold and run once per rule, connected account and threshold.","additionalProperties":true},"actions":{"type":"array","items":{"type":"object","properties":{"action":{"type":"string","enum":["like_post","comment","reply","follow","unfollow","like_comment","direct_message","like_recent_posts","view_story","save_post"]},"target_id":{"type":"string","description":"Required for every scheduled or follower milestone action; event-based rules may infer a target."},"params":{"type":"object","properties":{"text":{"type":"string","description":"Fixed or composed outgoing message."},"brief":{"type":"string","description":"Maestro generation instruction."},"n":{"type":"integer","minimum":1},"replied_to_comment_id":{"type":"string"}},"description":"Action-specific parameters; additional provider options may be preserved.","additionalProperties":true},"brief":{"type":"string","description":"Legacy Maestro brief; params.brief is also accepted."}}}},"platform":{"type":"string","enum":["any_platform","instagram","tiktok","youtube"]},"active":{"type":"boolean"},"mode":{"type":"string","enum":["rule","maestro_assisted"]},"settings":{"type":"object","properties":{"interval_minutes":{"type":"integer","minimum":1,"default":60}},"description":"Scheduled rule cadence in minutes.","additionalProperties":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}},"meta":{"type":"object","properties":{"count":{"type":"integer"}}}}},"example":{"payload":[{"id":1,"account_id":1,"growth_social_account_id":1,"name":"Sample Name","trigger_event":"new_follower","conditions":{"keywords":["sample keyword"],"followers_at_least":1},"actions":[{"action":"like_post","target_id":"sample target id","params":{"text":"sample text","brief":"sample brief","n":1,"replied_to_comment_id":"sample replied to comment id"},"brief":"sample brief"}],"platform":"any_platform","active":true,"mode":"rule","settings":{"interval_minutes":60},"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}],"meta":{"count":5}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"social_account_id","in":"query","required":false,"description":"Filter by connected social account.","schema":{"type":"integer"}},{"name":"trigger_event","in":"query","required":false,"description":"Filter by event.","schema":{"type":"string","enum":["new_follower","new_comment","mention","follower_milestone","scheduled"]}},{"name":"platform","in":"query","required":false,"description":"Filter by network.","schema":{"type":"string","enum":["any_platform","instagram","tiktok","youtube"]}}]},"post":{"tags":["Growth Social"],"operationId":"auto_post_api_v1_accounts_account_id_growth_social_automation_rules","summary":"Create automation rules","description":"Creates a new automation rule from the request payload. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"growth_social_account_id":{"type":["integer","null"]},"name":{"type":["string","null"]},"trigger_event":{"type":"string","enum":["new_follower","new_comment","mention","follower_milestone","scheduled"]},"conditions":{"type":"object","properties":{"keywords":{"type":"array","items":{"type":"string"}},"followers_at_least":{"type":"integer","minimum":1}},"description":"Keywords match comment or mention text by case-insensitive contains. Milestones require a positive follower threshold and run once per rule, connected account and threshold.","additionalProperties":true},"actions":{"type":"array","items":{"type":"object","properties":{"action":{"type":"string","enum":["like_post","comment","reply","follow","unfollow","like_comment","direct_message","like_recent_posts","view_story","save_post"]},"target_id":{"type":"string","description":"Required for every scheduled or follower milestone action; event-based rules may infer a target."},"params":{"type":"object","properties":{"text":{"type":"string","description":"Fixed or composed outgoing message."},"brief":{"type":"string","description":"Maestro generation instruction."},"n":{"type":"integer","minimum":1},"replied_to_comment_id":{"type":"string"}},"description":"Action-specific parameters; additional provider options may be preserved.","additionalProperties":true},"brief":{"type":"string","description":"Legacy Maestro brief; params.brief is also accepted."}}}},"platform":{"type":"string","enum":["any_platform","instagram","tiktok","youtube"]},"active":{"type":"boolean"},"mode":{"type":"string","enum":["rule","maestro_assisted"]},"settings":{"type":"object","properties":{"interval_minutes":{"type":"integer","minimum":1,"default":60}},"description":"Scheduled rule cadence in minutes.","additionalProperties":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"example":{"id":1,"account_id":1,"growth_social_account_id":1,"name":"Sample Name","trigger_event":"new_follower","conditions":{"keywords":["sample keyword"],"followers_at_least":1},"actions":[{"action":"like_post","target_id":"sample target id","params":{"text":"sample text","brief":"sample brief","n":1,"replied_to_comment_id":"sample replied to comment id"},"brief":"sample brief"}],"platform":"any_platform","active":true,"mode":"rule","settings":{"interval_minutes":60},"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":["string","null"]},"growth_social_account_id":{"type":["integer","null"]},"trigger_event":{"type":"string","enum":["new_follower","new_comment","mention","follower_milestone","scheduled"]},"platform":{"type":"string","enum":["any_platform","instagram","tiktok","youtube"]},"mode":{"type":"string","enum":["rule","maestro_assisted"]},"active":{"type":"boolean"},"conditions":{"type":"object","properties":{"keywords":{"type":"array","items":{"type":"string"}},"followers_at_least":{"type":"integer","minimum":1}},"description":"Keywords match comment or mention text by case-insensitive contains. Milestones require a positive follower threshold and run once per rule, connected account and threshold.","additionalProperties":true},"settings":{"type":"object","properties":{"interval_minutes":{"type":"integer","minimum":1,"default":60}},"description":"Scheduled rule cadence in minutes.","additionalProperties":true},"actions":{"type":"array","items":{"type":"object","properties":{"action":{"type":"string","enum":["like_post","comment","reply","follow","unfollow","like_comment","direct_message","like_recent_posts","view_story","save_post"]},"target_id":{"type":"string","description":"Required for every scheduled or follower milestone action; event-based rules may infer a target."},"params":{"type":"object","properties":{"text":{"type":"string","description":"Fixed or composed outgoing message."},"brief":{"type":"string","description":"Maestro generation instruction."},"n":{"type":"integer","minimum":1},"replied_to_comment_id":{"type":"string"}},"description":"Action-specific parameters; additional provider options may be preserved.","additionalProperties":true},"brief":{"type":"string","description":"Legacy Maestro brief; params.brief is also accepted."}},"required":["action"]},"minItems":1}},"allOf":[{"if":{"properties":{"trigger_event":{"enum":["scheduled","follower_milestone"]}},"required":["trigger_event"]},"then":{"properties":{"actions":{"items":{"required":["target_id"]}}}}}]},"example":{}}}}}},"/api/v1/accounts/{account_id}/growth_social/automation_rules/{id}":{"get":{"tags":["Growth Social"],"operationId":"auto_get_api_v1_accounts_account_id_growth_social_automation_rules_id","summary":"Get automation rules","description":"Returns the automation rule identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"growth_social_account_id":{"type":["integer","null"]},"name":{"type":["string","null"]},"trigger_event":{"type":"string","enum":["new_follower","new_comment","mention","follower_milestone","scheduled"]},"conditions":{"type":"object","properties":{"keywords":{"type":"array","items":{"type":"string"}},"followers_at_least":{"type":"integer","minimum":1}},"description":"Keywords match comment or mention text by case-insensitive contains. Milestones require a positive follower threshold and run once per rule, connected account and threshold.","additionalProperties":true},"actions":{"type":"array","items":{"type":"object","properties":{"action":{"type":"string","enum":["like_post","comment","reply","follow","unfollow","like_comment","direct_message","like_recent_posts","view_story","save_post"]},"target_id":{"type":"string","description":"Required for every scheduled or follower milestone action; event-based rules may infer a target."},"params":{"type":"object","properties":{"text":{"type":"string","description":"Fixed or composed outgoing message."},"brief":{"type":"string","description":"Maestro generation instruction."},"n":{"type":"integer","minimum":1},"replied_to_comment_id":{"type":"string"}},"description":"Action-specific parameters; additional provider options may be preserved.","additionalProperties":true},"brief":{"type":"string","description":"Legacy Maestro brief; params.brief is also accepted."}}}},"platform":{"type":"string","enum":["any_platform","instagram","tiktok","youtube"]},"active":{"type":"boolean"},"mode":{"type":"string","enum":["rule","maestro_assisted"]},"settings":{"type":"object","properties":{"interval_minutes":{"type":"integer","minimum":1,"default":60}},"description":"Scheduled rule cadence in minutes.","additionalProperties":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"example":{"id":1,"account_id":1,"growth_social_account_id":1,"name":"Sample Name","trigger_event":"new_follower","conditions":{"keywords":["sample keyword"],"followers_at_least":1},"actions":[{"action":"like_post","target_id":"sample target id","params":{"text":"sample text","brief":"sample brief","n":1,"replied_to_comment_id":"sample replied to comment id"},"brief":"sample brief"}],"platform":"any_platform","active":true,"mode":"rule","settings":{"interval_minutes":60},"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]},"patch":{"tags":["Growth Social"],"operationId":"auto_patch_api_v1_accounts_account_id_growth_social_automation_rules_id","summary":"Update automation rules","description":"Updates the automation rule identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"growth_social_account_id":{"type":["integer","null"]},"name":{"type":["string","null"]},"trigger_event":{"type":"string","enum":["new_follower","new_comment","mention","follower_milestone","scheduled"]},"conditions":{"type":"object","properties":{"keywords":{"type":"array","items":{"type":"string"}},"followers_at_least":{"type":"integer","minimum":1}},"description":"Keywords match comment or mention text by case-insensitive contains. Milestones require a positive follower threshold and run once per rule, connected account and threshold.","additionalProperties":true},"actions":{"type":"array","items":{"type":"object","properties":{"action":{"type":"string","enum":["like_post","comment","reply","follow","unfollow","like_comment","direct_message","like_recent_posts","view_story","save_post"]},"target_id":{"type":"string","description":"Required for every scheduled or follower milestone action; event-based rules may infer a target."},"params":{"type":"object","properties":{"text":{"type":"string","description":"Fixed or composed outgoing message."},"brief":{"type":"string","description":"Maestro generation instruction."},"n":{"type":"integer","minimum":1},"replied_to_comment_id":{"type":"string"}},"description":"Action-specific parameters; additional provider options may be preserved.","additionalProperties":true},"brief":{"type":"string","description":"Legacy Maestro brief; params.brief is also accepted."}}}},"platform":{"type":"string","enum":["any_platform","instagram","tiktok","youtube"]},"active":{"type":"boolean"},"mode":{"type":"string","enum":["rule","maestro_assisted"]},"settings":{"type":"object","properties":{"interval_minutes":{"type":"integer","minimum":1,"default":60}},"description":"Scheduled rule cadence in minutes.","additionalProperties":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"example":{"id":1,"account_id":1,"growth_social_account_id":1,"name":"Sample Name","trigger_event":"new_follower","conditions":{"keywords":["sample keyword"],"followers_at_least":1},"actions":[{"action":"like_post","target_id":"sample target id","params":{"text":"sample text","brief":"sample brief","n":1,"replied_to_comment_id":"sample replied to comment id"},"brief":"sample brief"}],"platform":"any_platform","active":true,"mode":"rule","settings":{"interval_minutes":60},"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":["string","null"]},"growth_social_account_id":{"type":["integer","null"]},"trigger_event":{"type":"string","enum":["new_follower","new_comment","mention","follower_milestone","scheduled"]},"platform":{"type":"string","enum":["any_platform","instagram","tiktok","youtube"]},"mode":{"type":"string","enum":["rule","maestro_assisted"]},"active":{"type":"boolean"},"conditions":{"type":"object","properties":{"keywords":{"type":"array","items":{"type":"string"}},"followers_at_least":{"type":"integer","minimum":1}},"description":"Keywords match comment or mention text by case-insensitive contains. Milestones require a positive follower threshold and run once per rule, connected account and threshold.","additionalProperties":true},"settings":{"type":"object","properties":{"interval_minutes":{"type":"integer","minimum":1,"default":60}},"description":"Scheduled rule cadence in minutes.","additionalProperties":true},"actions":{"type":"array","items":{"type":"object","properties":{"action":{"type":"string","enum":["like_post","comment","reply","follow","unfollow","like_comment","direct_message","like_recent_posts","view_story","save_post"]},"target_id":{"type":"string","description":"Required for every scheduled or follower milestone action; event-based rules may infer a target."},"params":{"type":"object","properties":{"text":{"type":"string","description":"Fixed or composed outgoing message."},"brief":{"type":"string","description":"Maestro generation instruction."},"n":{"type":"integer","minimum":1},"replied_to_comment_id":{"type":"string"}},"description":"Action-specific parameters; additional provider options may be preserved.","additionalProperties":true},"brief":{"type":"string","description":"Legacy Maestro brief; params.brief is also accepted."}},"required":["action"]},"minItems":1}},"allOf":[{"if":{"properties":{"trigger_event":{"enum":["scheduled","follower_milestone"]}},"required":["trigger_event"]},"then":{"properties":{"actions":{"items":{"required":["target_id"]}}}}}]},"example":{}}}}},"put":{"tags":["Growth Social"],"operationId":"auto_put_api_v1_accounts_account_id_growth_social_automation_rules_id","summary":"Update automation rules","description":"Updates the automation rule identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"growth_social_account_id":{"type":["integer","null"]},"name":{"type":["string","null"]},"trigger_event":{"type":"string","enum":["new_follower","new_comment","mention","follower_milestone","scheduled"]},"conditions":{"type":"object","properties":{"keywords":{"type":"array","items":{"type":"string"}},"followers_at_least":{"type":"integer","minimum":1}},"description":"Keywords match comment or mention text by case-insensitive contains. Milestones require a positive follower threshold and run once per rule, connected account and threshold.","additionalProperties":true},"actions":{"type":"array","items":{"type":"object","properties":{"action":{"type":"string","enum":["like_post","comment","reply","follow","unfollow","like_comment","direct_message","like_recent_posts","view_story","save_post"]},"target_id":{"type":"string","description":"Required for every scheduled or follower milestone action; event-based rules may infer a target."},"params":{"type":"object","properties":{"text":{"type":"string","description":"Fixed or composed outgoing message."},"brief":{"type":"string","description":"Maestro generation instruction."},"n":{"type":"integer","minimum":1},"replied_to_comment_id":{"type":"string"}},"description":"Action-specific parameters; additional provider options may be preserved.","additionalProperties":true},"brief":{"type":"string","description":"Legacy Maestro brief; params.brief is also accepted."}}}},"platform":{"type":"string","enum":["any_platform","instagram","tiktok","youtube"]},"active":{"type":"boolean"},"mode":{"type":"string","enum":["rule","maestro_assisted"]},"settings":{"type":"object","properties":{"interval_minutes":{"type":"integer","minimum":1,"default":60}},"description":"Scheduled rule cadence in minutes.","additionalProperties":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"example":{"id":1,"account_id":1,"growth_social_account_id":1,"name":"Sample Name","trigger_event":"new_follower","conditions":{"keywords":["sample keyword"],"followers_at_least":1},"actions":[{"action":"like_post","target_id":"sample target id","params":{"text":"sample text","brief":"sample brief","n":1,"replied_to_comment_id":"sample replied to comment id"},"brief":"sample brief"}],"platform":"any_platform","active":true,"mode":"rule","settings":{"interval_minutes":60},"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":["string","null"]},"growth_social_account_id":{"type":["integer","null"]},"trigger_event":{"type":"string","enum":["new_follower","new_comment","mention","follower_milestone","scheduled"]},"platform":{"type":"string","enum":["any_platform","instagram","tiktok","youtube"]},"mode":{"type":"string","enum":["rule","maestro_assisted"]},"active":{"type":"boolean"},"conditions":{"type":"object","properties":{"keywords":{"type":"array","items":{"type":"string"}},"followers_at_least":{"type":"integer","minimum":1}},"description":"Keywords match comment or mention text by case-insensitive contains. Milestones require a positive follower threshold and run once per rule, connected account and threshold.","additionalProperties":true},"settings":{"type":"object","properties":{"interval_minutes":{"type":"integer","minimum":1,"default":60}},"description":"Scheduled rule cadence in minutes.","additionalProperties":true},"actions":{"type":"array","items":{"type":"object","properties":{"action":{"type":"string","enum":["like_post","comment","reply","follow","unfollow","like_comment","direct_message","like_recent_posts","view_story","save_post"]},"target_id":{"type":"string","description":"Required for every scheduled or follower milestone action; event-based rules may infer a target."},"params":{"type":"object","properties":{"text":{"type":"string","description":"Fixed or composed outgoing message."},"brief":{"type":"string","description":"Maestro generation instruction."},"n":{"type":"integer","minimum":1},"replied_to_comment_id":{"type":"string"}},"description":"Action-specific parameters; additional provider options may be preserved.","additionalProperties":true},"brief":{"type":"string","description":"Legacy Maestro brief; params.brief is also accepted."}},"required":["action"]},"minItems":1}},"allOf":[{"if":{"properties":{"trigger_event":{"enum":["scheduled","follower_milestone"]}},"required":["trigger_event"]},"then":{"properties":{"actions":{"items":{"required":["target_id"]}}}}}]},"example":{}}}}},"delete":{"tags":["Growth Social"],"operationId":"auto_delete_api_v1_accounts_account_id_growth_social_automation_rules_id","summary":"Delete automation rules","description":"Deletes the automation rule identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Success (no content)"},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/growth_social/scrape_runs/{id}/cancel":{"post":{"tags":["Growth Social"],"operationId":"auto_post_api_v1_accounts_account_id_growth_social_scrape_runs_id_cancel","summary":"Cancel scrape runs","description":"Performs the cancel operation on the targeted scrape run resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"merge":{"type":"string"}}},"example":{"merge":"sample merge"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/growth_social/scrape_runs":{"get":{"tags":["Growth Social"],"operationId":"auto_get_api_v1_accounts_account_id_growth_social_scrape_runs","summary":"List scrape runs","description":"Returns the list of scrape runs visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Free-form object."}},"meta":{"type":"object","properties":{"count":{"type":"integer"}}}}},"example":{"payload":[{}],"meta":{"count":5}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"growth_social_account_id","in":"query","required":false,"description":"Restrict to runs of one connected account.","schema":{"type":"integer"},"example":8},{"name":"status","in":"query","required":false,"description":"Restrict to runs in one state.","schema":{"type":"string","enum":["queued","running","paused","done","failed"]},"example":"running"}]},"post":{"tags":["Growth Social"],"operationId":"auto_post_api_v1_accounts_account_id_growth_social_scrape_runs","summary":"Create scrape runs","description":"Creates a new scrape run from the request payload. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"merge":{"type":"string"}}},"example":{"merge":"sample merge"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"growth_social_account_id":{"type":"integer"},"source":{"type":"string","enum":["followers_of","following_of","post_likers","post_commenters","hashtag","location","competitor"]},"target":{"type":"string"},"requested_count":{"type":"integer"},"triggered_by":{"type":"string","enum":["manual","monitor","maestro"]}},"required":["target"]},"example":{"growth_social_account_id":1,"source":"followers_of","target":"sample target","requested_count":5,"triggered_by":"manual"}}}}}},"/api/v1/accounts/{account_id}/growth_social/scrape_runs/{id}":{"get":{"tags":["Growth Social"],"operationId":"auto_get_api_v1_accounts_account_id_growth_social_scrape_runs_id","summary":"Get scrape runs","description":"Returns the scrape run identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"merge":{"type":"string"}}},"example":{"merge":"sample merge"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/growth_social/prospects/{id}/promote":{"post":{"tags":["Growth Social"],"operationId":"auto_post_api_v1_accounts_account_id_growth_social_prospects_id_promote","summary":"Promote prospects","description":"Performs the promote operation on the targeted prospect resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"merge":{"type":"string"},"promoted":{"type":"boolean"}}},"example":{"merge":"sample merge","promoted":true}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/growth_social/prospects/bulk":{"post":{"tags":["Growth Social"],"operationId":"auto_post_api_v1_accounts_account_id_growth_social_prospects_bulk","summary":"Apply a bulk operation to selected prospects","description":"Runs one operation over the selected prospect ids — `promote` converts each prospect into a native contact attached to the social inbox (idempotent), `skip` marks them skipped, and `add_to_campaign` enrolls them into the campaign given by `campaign_id`, silently ignoring prospects already enrolled. On success the answer is `200 OK` with an EMPTY body, so re-read the prospect list to observe the new statuses; only the failure paths carry JSON.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Bulk operation applied. Empty body — re-read the prospects for the new statuses."},"401":{"description":"Unauthorized"},"404":{"description":"The campaign given for an enrollment does not exist in this account.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Why the enrollment target could not be resolved."}}},"example":{"error":"campaign not found"}}}},"422":{"description":"The requested operation is not one of the supported bulk operations.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Why the bulk request was rejected."}}},"example":{"error":"unsupported bulk op"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"ids":{"type":"array","items":{"type":"string"}},"op":{"type":"string"},"campaign_id":{"type":"integer"}}},"example":{"ids":["sample id"],"op":"sample op","campaign_id":1}}}}}},"/api/v1/accounts/{account_id}/growth_social/prospects":{"get":{"tags":["Growth Social"],"operationId":"auto_get_api_v1_accounts_account_id_growth_social_prospects","summary":"List prospects","description":"Returns the list of prospects visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Free-form object."}},"meta":{"type":"object","properties":{"count":{"type":"integer"}}}}},"example":{"payload":[{}],"meta":{"count":5}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."}]}},"/api/v1/accounts/{account_id}/growth_social/prospects/{id}":{"get":{"tags":["Growth Social"],"operationId":"auto_get_api_v1_accounts_account_id_growth_social_prospects_id","summary":"Get prospects","description":"Returns the prospect identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"merge":{"type":"string"},"promoted":{"type":"boolean"}}},"example":{"merge":"sample merge","promoted":true}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]},"patch":{"tags":["Growth Social"],"operationId":"auto_patch_api_v1_accounts_account_id_growth_social_prospects_id","summary":"Update prospects","description":"Updates the prospect identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"merge":{"type":"string"},"promoted":{"type":"boolean"}}},"example":{"merge":"sample merge","promoted":true}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["discovered","enriched","contacted","converted","skipped","blocked"]}}},"example":{"status":"discovered"}}}}},"put":{"tags":["Growth Social"],"operationId":"auto_put_api_v1_accounts_account_id_growth_social_prospects_id","summary":"Update prospects","description":"Updates the prospect identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"merge":{"type":"string"},"promoted":{"type":"boolean"}}},"example":{"merge":"sample merge","promoted":true}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["discovered","enriched","contacted","converted","skipped","blocked"]}}},"example":{"status":"discovered"}}}}},"delete":{"tags":["Growth Social"],"operationId":"auto_delete_api_v1_accounts_account_id_growth_social_prospects_id","summary":"Delete prospects","description":"Deletes the prospect identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Success (no content)"},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/growth_social/campaigns/{id}/activate":{"post":{"tags":["Growth Social"],"operationId":"auto_post_api_v1_accounts_account_id_growth_social_campaigns_id_activate","summary":"Activate campaigns","description":"Performs the activate operation on the targeted campaign resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"merge":{"type":"string"},"targets_summary":{"type":"integer"}}},"example":{"merge":"sample merge","targets_summary":1}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/growth_social/campaigns/{id}/pause":{"post":{"tags":["Growth Social"],"operationId":"auto_post_api_v1_accounts_account_id_growth_social_campaigns_id_pause","summary":"Pause campaigns","description":"Performs the pause operation on the targeted campaign resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"merge":{"type":"string"},"targets_summary":{"type":"integer"}}},"example":{"merge":"sample merge","targets_summary":1}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/growth_social/campaigns/{id}/resume":{"post":{"tags":["Growth Social"],"operationId":"auto_post_api_v1_accounts_account_id_growth_social_campaigns_id_resume","summary":"Resume campaigns","description":"Performs the resume operation on the targeted campaign resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"merge":{"type":"string"},"targets_summary":{"type":"integer"}}},"example":{"merge":"sample merge","targets_summary":1}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/growth_social/campaigns/{id}/archive":{"post":{"tags":["Growth Social"],"operationId":"auto_post_api_v1_accounts_account_id_growth_social_campaigns_id_archive","summary":"Archive campaigns","description":"Performs the archive operation on the targeted campaign resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"merge":{"type":"string"},"targets_summary":{"type":"integer"}}},"example":{"merge":"sample merge","targets_summary":1}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/growth_social/campaigns":{"get":{"tags":["Growth Social"],"operationId":"auto_get_api_v1_accounts_account_id_growth_social_campaigns","summary":"List campaigns","description":"Returns the list of campaigns visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Free-form object."}},"meta":{"type":"object","properties":{"count":{"type":"integer"}}}}},"example":{"payload":[{}],"meta":{"count":5}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"growth_social_account_id","in":"query","required":false,"description":"Restrict to campaigns of one connected account.","schema":{"type":"integer"},"example":8},{"name":"status","in":"query","required":false,"description":"Restrict to campaigns in one state.","schema":{"type":"string","enum":["draft","active","paused","completed","archived"]},"example":"active"}]},"post":{"tags":["Growth Social"],"operationId":"auto_post_api_v1_accounts_account_id_growth_social_campaigns","summary":"Create campaigns","description":"Creates a new campaign from the request payload. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"merge":{"type":"string"},"targets_summary":{"type":"integer"}}},"example":{"merge":"sample merge","targets_summary":1}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"growth_social_account_id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"}},"required":["name"]},"example":{"growth_social_account_id":1,"name":"Sample Name","description":"A short description."}}}}}},"/api/v1/accounts/{account_id}/growth_social/campaigns/{id}":{"get":{"tags":["Growth Social"],"operationId":"auto_get_api_v1_accounts_account_id_growth_social_campaigns_id","summary":"Get campaigns","description":"Returns the campaign identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"merge":{"type":"string"},"targets_summary":{"type":"integer"}}},"example":{"merge":"sample merge","targets_summary":1}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]},"patch":{"tags":["Growth Social"],"operationId":"auto_patch_api_v1_accounts_account_id_growth_social_campaigns_id","summary":"Update campaigns","description":"Updates the campaign identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"merge":{"type":"string"},"targets_summary":{"type":"integer"}}},"example":{"merge":"sample merge","targets_summary":1}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"growth_social_account_id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"}}},"example":{"growth_social_account_id":1,"name":"Sample Name","description":"A short description."}}}}},"put":{"tags":["Growth Social"],"operationId":"auto_put_api_v1_accounts_account_id_growth_social_campaigns_id","summary":"Update campaigns","description":"Updates the campaign identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"merge":{"type":"string"},"targets_summary":{"type":"integer"}}},"example":{"merge":"sample merge","targets_summary":1}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"growth_social_account_id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"}}},"example":{"growth_social_account_id":1,"name":"Sample Name","description":"A short description."}}}}},"delete":{"tags":["Growth Social"],"operationId":"auto_delete_api_v1_accounts_account_id_growth_social_campaigns_id","summary":"Delete campaigns","description":"Deletes the campaign identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Success (no content)"},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/growth_social/dm_templates":{"get":{"tags":["Growth Social"],"operationId":"auto_get_api_v1_accounts_account_id_growth_social_dm_templates","summary":"List dm templates","description":"Returns the list of dm templates visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Free-form object."}}}},"example":{"payload":[{}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"growth_social_account_id","in":"query","required":false,"description":"Restrict to templates of one connected account.","schema":{"type":"integer"},"example":8},{"name":"kind","in":"query","required":false,"description":"Restrict to one template kind.","schema":{"type":"string","enum":["dm","comment"]},"example":"dm"}]},"post":{"tags":["Growth Social"],"operationId":"auto_post_api_v1_accounts_account_id_growth_social_dm_templates","summary":"Create dm templates","description":"Creates a new dm template from the request payload. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"merge":{"type":"string"}}},"example":{"merge":"sample merge"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"kind":{"type":"string","enum":["dm","comment"]},"body":{"type":"string"},"growth_social_account_id":{"type":"integer"}},"required":["body","name"]},"example":{"name":"Sample Name","kind":"dm","body":"Sample body text.","growth_social_account_id":1}}}}}},"/api/v1/accounts/{account_id}/growth_social/dm_templates/{id}":{"get":{"tags":["Growth Social"],"operationId":"auto_get_api_v1_accounts_account_id_growth_social_dm_templates_id","summary":"Get dm templates","description":"Returns the dm template identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"merge":{"type":"string"}}},"example":{"merge":"sample merge"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]},"patch":{"tags":["Growth Social"],"operationId":"auto_patch_api_v1_accounts_account_id_growth_social_dm_templates_id","summary":"Update dm templates","description":"Updates the dm template identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"merge":{"type":"string"}}},"example":{"merge":"sample merge"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"kind":{"type":"string","enum":["dm","comment"]},"body":{"type":"string"},"growth_social_account_id":{"type":"integer"}}},"example":{"name":"Sample Name","kind":"dm","body":"Sample body text.","growth_social_account_id":1}}}}},"put":{"tags":["Growth Social"],"operationId":"auto_put_api_v1_accounts_account_id_growth_social_dm_templates_id","summary":"Update dm templates","description":"Updates the dm template identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"merge":{"type":"string"}}},"example":{"merge":"sample merge"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"kind":{"type":"string","enum":["dm","comment"]},"body":{"type":"string"},"growth_social_account_id":{"type":"integer"}}},"example":{"name":"Sample Name","kind":"dm","body":"Sample body text.","growth_social_account_id":1}}}}},"delete":{"tags":["Growth Social"],"operationId":"auto_delete_api_v1_accounts_account_id_growth_social_dm_templates_id","summary":"Delete dm templates","description":"Deletes the dm template identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Success (no content)"},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/growth_social/central":{"get":{"tags":["Growth Social"],"operationId":"auto_get_api_v1_accounts_account_id_growth_social_central","summary":"Get central","description":"Returns the central identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Instagram Growth \"Central\" dashboard rollup","content":{"application/json":{"schema":{"type":"object","properties":{"summary":{"type":"object","properties":{"followers":{"type":"number","format":"float","example":5678},"followers_delta":{"type":"number","format":"float","example":124},"prospects_total":{"type":"integer","example":940},"prospects_new":{"type":"integer","example":63},"prospects_converted":{"type":"integer","example":21},"actions_succeeded":{"type":"integer","example":410},"dms_sent":{"type":"integer","example":88}}},"growth_over_time":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","example":"2026-01-14"},"value":{"type":"number","format":"float","example":5654}}}},"top_posts":{"type":"array","items":{"type":"object","properties":{"target_id":{"type":"string","example":"17895..."},"metric_type":{"type":"string","example":"likes","enum":["followers","following","posts","likes","views","comments","shares","saves","engagement_rate","reach","impressions"],"description":"The social metric captured for the post."},"total":{"type":"number","format":"float","example":320}}}},"audience_breakdown":{"type":"object","properties":{"by_source":{"type":"object","additionalProperties":{"type":"integer"},"example":{"hashtag":300,"competitor":120},"description":"Prospect counts keyed by acquisition source (followers_of, following_of, post_likers, post_commenters, hashtag, location, competitor)."},"verified":{"type":"integer","example":34},"private":{"type":"integer","example":210},"public":{"type":"integer","example":730}}},"action_funnel":{"type":"object","properties":{"by_status":{"type":"object","additionalProperties":{"type":"integer"},"example":{"succeeded":410,"failed":12},"description":"Action counts keyed by status (queued, throttled, sent, succeeded, failed, blocked)."},"by_action":{"type":"object","additionalProperties":{"type":"integer"},"example":{"direct_message":88,"follow":140},"description":"Action counts keyed by action (like_post, comment, reply, follow, unfollow, like_comment, direct_message, like_recent_posts, view_story, save_post)."}}},"prospect_funnel":{"type":"object","additionalProperties":{"type":"integer"},"example":{"new":63,"contacted":200,"converted":21},"description":"Prospect counts keyed by funnel status (discovered, enriched, contacted, converted, skipped, blocked)."},"account_health":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","example":4},"username":{"type":"string","example":"@brandhandle"},"platform":{"type":"string","enum":["instagram","tiktok","youtube"],"example":"instagram"},"status":{"type":"string","example":"connected","enum":["connecting","awaiting_challenge","connected","disconnected","blocked","logged_out"],"description":"Connection state of the social account."},"last_health_at":{"type":["string","null"],"format":"date-time","example":"2026-01-15T10:00:00.000Z"},"last_error":{"type":["string","null"],"example":null},"followers":{"type":"number","format":"float","example":5678}}}}}},"example":{"summary":{"followers":5678,"followers_delta":124,"prospects_total":940,"prospects_new":63,"prospects_converted":21,"actions_succeeded":410,"dms_sent":88},"growth_over_time":[{"date":"2026-01-14","value":5654}],"top_posts":[{"target_id":"17895...","metric_type":"likes","total":320}],"audience_breakdown":{"by_source":{"hashtag":300,"competitor":120},"verified":34,"private":210,"public":730},"action_funnel":{"by_status":{"succeeded":410,"failed":12},"by_action":{"direct_message":88,"follow":140}},"prospect_funnel":{"new":63,"contacted":200,"converted":21},"account_health":[{"id":4,"username":"@brandhandle","platform":"instagram","status":"connected","last_health_at":"2026-01-15T10:00:00.000Z","last_error":null,"followers":5678}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"growth_social_account_id","in":"query","required":false,"description":"Restrict the central panel to one connected account. Omitted, every connected account is aggregated.","schema":{"type":"integer"},"example":8}]}},"/api/v1/accounts/{account_id}/growth_social/communities/{id}/archive":{"post":{"tags":["Growth Social"],"operationId":"auto_post_api_v1_accounts_account_id_growth_social_communities_id_archive","summary":"Archive communities","description":"Performs the archive operation on the targeted community resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"slug":{"type":"string"},"invite_token":{"type":"string"},"status":{"type":"string","enum":["draft","active","archived"]},"branding":{"type":"string"},"reward_rule":{"type":"string"},"default_caps":{"type":"string"},"archived_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"},"invite_url":{"type":"string"},"members_count":{"type":"integer"}},"required":["id","name","description","slug","invite_token","status","branding","reward_rule","default_caps","archived_at","created_at","invite_url"],"additionalProperties":false},"example":{"id":1,"name":"Sample Name","description":"A short description.","slug":"sample-slug","invite_token":"sample-token","status":"draft","branding":"sample branding","reward_rule":"sample reward rule","default_caps":"sample default caps","archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","invite_url":"https://example.com/resource","members_count":5}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/growth_social/communities/{id}/restore":{"post":{"tags":["Growth Social"],"operationId":"auto_post_api_v1_accounts_account_id_growth_social_communities_id_restore","summary":"Restore communities","description":"Performs the restore operation on the targeted community resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"slug":{"type":"string"},"invite_token":{"type":"string"},"status":{"type":"string","enum":["draft","active","archived"]},"branding":{"type":"string"},"reward_rule":{"type":"string"},"default_caps":{"type":"string"},"archived_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"},"invite_url":{"type":"string"},"members_count":{"type":"integer"}},"required":["id","name","description","slug","invite_token","status","branding","reward_rule","default_caps","archived_at","created_at","invite_url"],"additionalProperties":false},"example":{"id":1,"name":"Sample Name","description":"A short description.","slug":"sample-slug","invite_token":"sample-token","status":"draft","branding":"sample branding","reward_rule":"sample reward rule","default_caps":"sample default caps","archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","invite_url":"https://example.com/resource","members_count":5}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/growth_social/communities/report":{"get":{"tags":["Growth Social"],"operationId":"auto_get_api_v1_accounts_account_id_growth_social_communities_report","summary":"Report communities","description":"Performs the report operation on the targeted community resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Account-wide collaboration rollup (matrix header)","content":{"application/json":{"schema":{"type":"object","properties":{"communities":{"type":"integer","example":3},"members":{"type":"integer","description":"Distinct members across communities","example":42},"active_collaborations":{"type":"integer","example":5},"rounds":{"type":"object","description":"Engagement-round counts keyed by status (building/dispatching/completed/failed)","additionalProperties":{"type":"integer"},"example":{"completed":18,"dispatching":2,"failed":1}},"points_distributed":{"type":"number","format":"float","example":12400}}},"example":{"communities":3,"members":42,"active_collaborations":5,"rounds":{"completed":18,"dispatching":2,"failed":1},"points_distributed":12400}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/growth_social/communities":{"get":{"tags":["Growth Social"],"operationId":"auto_get_api_v1_accounts_account_id_growth_social_communities","summary":"List communities","description":"Returns the list of communities visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"slug":{"type":"string"},"invite_token":{"type":"string"},"status":{"type":"string","enum":["draft","active","archived"]},"branding":{"type":"string"},"reward_rule":{"type":"string"},"default_caps":{"type":"string"},"archived_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"},"invite_url":{"type":"string"},"members_count":{"type":"integer"}},"required":["id","name","description","slug","invite_token","status","branding","reward_rule","default_caps","archived_at","created_at","invite_url"],"additionalProperties":false}}}},"example":{"payload":[{"id":1,"name":"Sample Name","description":"A short description.","slug":"sample-slug","invite_token":"sample-token","status":"draft","branding":"sample branding","reward_rule":"sample reward rule","default_caps":"sample default caps","archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","invite_url":"https://example.com/resource","members_count":5}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."}]},"post":{"tags":["Growth Social"],"operationId":"auto_post_api_v1_accounts_account_id_growth_social_communities","summary":"Create communities","description":"Creates a new community from the request payload. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"201":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"slug":{"type":"string"},"invite_token":{"type":"string"},"status":{"type":"string","enum":["draft","active","archived"]},"branding":{"type":"string"},"reward_rule":{"type":"string"},"default_caps":{"type":"string"},"archived_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"},"invite_url":{"type":"string"},"members_count":{"type":"integer"}},"required":["id","name","description","slug","invite_token","status","branding","reward_rule","default_caps","archived_at","created_at","invite_url"],"additionalProperties":false},"example":{"id":1,"name":"Sample Name","description":"A short description.","slug":"sample-slug","invite_token":"sample-token","status":"draft","branding":"sample branding","reward_rule":"sample reward rule","default_caps":"sample default caps","archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","invite_url":"https://example.com/resource","members_count":5}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"slug":{"type":"string"},"status":{"type":"string","enum":["draft","active","archived"]}},"required":["name","slug"]},"example":{"name":"Sample Name","description":"A short description.","slug":"sample-slug","status":"draft"}}}}}},"/api/v1/accounts/{account_id}/growth_social/communities/{id}":{"get":{"tags":["Growth Social"],"operationId":"auto_get_api_v1_accounts_account_id_growth_social_communities_id","summary":"Get communities","description":"Returns the community identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"slug":{"type":"string"},"invite_token":{"type":"string"},"status":{"type":"string","enum":["draft","active","archived"]},"branding":{"type":"string"},"reward_rule":{"type":"string"},"default_caps":{"type":"string"},"archived_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"},"invite_url":{"type":"string"},"members_count":{"type":"integer"}},"required":["id","name","description","slug","invite_token","status","branding","reward_rule","default_caps","archived_at","created_at","invite_url"],"additionalProperties":false},"example":{"id":1,"name":"Sample Name","description":"A short description.","slug":"sample-slug","invite_token":"sample-token","status":"draft","branding":"sample branding","reward_rule":"sample reward rule","default_caps":"sample default caps","archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","invite_url":"https://example.com/resource","members_count":5}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]},"patch":{"tags":["Growth Social"],"operationId":"auto_patch_api_v1_accounts_account_id_growth_social_communities_id","summary":"Update communities","description":"Updates the community identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"slug":{"type":"string"},"invite_token":{"type":"string"},"status":{"type":"string","enum":["draft","active","archived"]},"branding":{"type":"string"},"reward_rule":{"type":"string"},"default_caps":{"type":"string"},"archived_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"},"invite_url":{"type":"string"},"members_count":{"type":"integer"}},"required":["id","name","description","slug","invite_token","status","branding","reward_rule","default_caps","archived_at","created_at","invite_url"],"additionalProperties":false},"example":{"id":1,"name":"Sample Name","description":"A short description.","slug":"sample-slug","invite_token":"sample-token","status":"draft","branding":"sample branding","reward_rule":"sample reward rule","default_caps":"sample default caps","archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","invite_url":"https://example.com/resource","members_count":5}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"slug":{"type":"string"},"status":{"type":"string","enum":["draft","active","archived"]}}},"example":{"name":"Sample Name","description":"A short description.","slug":"sample-slug","status":"draft"}}}}},"put":{"tags":["Growth Social"],"operationId":"auto_put_api_v1_accounts_account_id_growth_social_communities_id","summary":"Update communities","description":"Updates the community identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"slug":{"type":"string"},"invite_token":{"type":"string"},"status":{"type":"string","enum":["draft","active","archived"]},"branding":{"type":"string"},"reward_rule":{"type":"string"},"default_caps":{"type":"string"},"archived_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"},"invite_url":{"type":"string"},"members_count":{"type":"integer"}},"required":["id","name","description","slug","invite_token","status","branding","reward_rule","default_caps","archived_at","created_at","invite_url"],"additionalProperties":false},"example":{"id":1,"name":"Sample Name","description":"A short description.","slug":"sample-slug","invite_token":"sample-token","status":"draft","branding":"sample branding","reward_rule":"sample reward rule","default_caps":"sample default caps","archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","invite_url":"https://example.com/resource","members_count":5}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"slug":{"type":"string"},"status":{"type":"string","enum":["draft","active","archived"]}}},"example":{"name":"Sample Name","description":"A short description.","slug":"sample-slug","status":"draft"}}}}},"delete":{"tags":["Growth Social"],"operationId":"auto_delete_api_v1_accounts_account_id_growth_social_communities_id","summary":"Delete communities","description":"Deletes the community identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Success (no content)"},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/growth_social/collaborations/{id}/activate":{"post":{"tags":["Growth Social"],"operationId":"auto_post_api_v1_accounts_account_id_growth_social_collaborations_id_activate","summary":"Activate collaborations","description":"Performs the activate operation on the targeted collaboration resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"community_id":{"type":"integer"},"name":{"type":"string"},"mode":{"type":"string","enum":["boost_target","mutual_pod"]},"status":{"type":"string","enum":["draft","active","paused","archived"]},"target_spec":{"type":"string"},"action_spec":{"type":"string"},"eligibility":{"type":"string"},"throttle":{"type":"string"},"schedule":{"type":"string"},"archived_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"},"rounds_count":{"type":"integer"}},"required":["id","community_id","name","mode","status","target_spec","action_spec","eligibility","throttle","schedule","archived_at","created_at"],"additionalProperties":false},"example":{"id":1,"community_id":1,"name":"Sample Name","mode":"boost_target","status":"draft","target_spec":"sample target spec","action_spec":"sample action spec","eligibility":"sample eligibility","throttle":"sample throttle","schedule":"sample schedule","archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","rounds_count":5}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"community_id":{"type":"integer"}}},"example":{"community_id":1}}}}}},"/api/v1/accounts/{account_id}/growth_social/collaborations/{id}/pause":{"post":{"tags":["Growth Social"],"operationId":"auto_post_api_v1_accounts_account_id_growth_social_collaborations_id_pause","summary":"Pause collaborations","description":"Performs the pause operation on the targeted collaboration resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"community_id":{"type":"integer"},"name":{"type":"string"},"mode":{"type":"string","enum":["boost_target","mutual_pod"]},"status":{"type":"string","enum":["draft","active","paused","archived"]},"target_spec":{"type":"string"},"action_spec":{"type":"string"},"eligibility":{"type":"string"},"throttle":{"type":"string"},"schedule":{"type":"string"},"archived_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"},"rounds_count":{"type":"integer"}},"required":["id","community_id","name","mode","status","target_spec","action_spec","eligibility","throttle","schedule","archived_at","created_at"],"additionalProperties":false},"example":{"id":1,"community_id":1,"name":"Sample Name","mode":"boost_target","status":"draft","target_spec":"sample target spec","action_spec":"sample action spec","eligibility":"sample eligibility","throttle":"sample throttle","schedule":"sample schedule","archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","rounds_count":5}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"community_id":{"type":"integer"}}},"example":{"community_id":1}}}}}},"/api/v1/accounts/{account_id}/growth_social/collaborations/{id}/resume":{"post":{"tags":["Growth Social"],"operationId":"auto_post_api_v1_accounts_account_id_growth_social_collaborations_id_resume","summary":"Resume collaborations","description":"Performs the resume operation on the targeted collaboration resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"community_id":{"type":"integer"},"name":{"type":"string"},"mode":{"type":"string","enum":["boost_target","mutual_pod"]},"status":{"type":"string","enum":["draft","active","paused","archived"]},"target_spec":{"type":"string"},"action_spec":{"type":"string"},"eligibility":{"type":"string"},"throttle":{"type":"string"},"schedule":{"type":"string"},"archived_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"},"rounds_count":{"type":"integer"}},"required":["id","community_id","name","mode","status","target_spec","action_spec","eligibility","throttle","schedule","archived_at","created_at"],"additionalProperties":false},"example":{"id":1,"community_id":1,"name":"Sample Name","mode":"boost_target","status":"draft","target_spec":"sample target spec","action_spec":"sample action spec","eligibility":"sample eligibility","throttle":"sample throttle","schedule":"sample schedule","archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","rounds_count":5}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"community_id":{"type":"integer"}}},"example":{"community_id":1}}}}}},"/api/v1/accounts/{account_id}/growth_social/collaborations/{id}/archive":{"post":{"tags":["Growth Social"],"operationId":"auto_post_api_v1_accounts_account_id_growth_social_collaborations_id_archive","summary":"Archive collaborations","description":"Performs the archive operation on the targeted collaboration resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"community_id":{"type":"integer"},"name":{"type":"string"},"mode":{"type":"string","enum":["boost_target","mutual_pod"]},"status":{"type":"string","enum":["draft","active","paused","archived"]},"target_spec":{"type":"string"},"action_spec":{"type":"string"},"eligibility":{"type":"string"},"throttle":{"type":"string"},"schedule":{"type":"string"},"archived_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"},"rounds_count":{"type":"integer"}},"required":["id","community_id","name","mode","status","target_spec","action_spec","eligibility","throttle","schedule","archived_at","created_at"],"additionalProperties":false},"example":{"id":1,"community_id":1,"name":"Sample Name","mode":"boost_target","status":"draft","target_spec":"sample target spec","action_spec":"sample action spec","eligibility":"sample eligibility","throttle":"sample throttle","schedule":"sample schedule","archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","rounds_count":5}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"community_id":{"type":"integer"}}},"example":{"community_id":1}}}}}},"/api/v1/accounts/{account_id}/growth_social/collaborations/{id}/trigger":{"post":{"tags":["Growth Social"],"operationId":"auto_post_api_v1_accounts_account_id_growth_social_collaborations_id_trigger","summary":"Trigger a collaboration round on an explicit media item","description":"Fans out an engagement round for this collaboration against the media item the operator names, using the same enqueue path the automatic detection uses but marked as manually triggered. Returns `202 Accepted` with an EMPTY body — the round rows are created by the job, so re-read the collaboration detail (which carries `rounds_count`) to observe the result.","security":[{"userApiKey":[]}],"responses":{"202":{"description":"Round enqueued. Empty body — the round is created asynchronously."},"401":{"description":"Unauthorized"},"404":{"description":"No such collaboration under this account's communities."},"422":{"description":"The target media item was not supplied.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Why the trigger was rejected."}}},"example":{"error":"media_id required"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"media_id":{"type":"integer"},"owner":{"type":"string"}}},"example":{"media_id":1,"owner":"sample owner"}}}}}},"/api/v1/accounts/{account_id}/growth_social/collaborations":{"get":{"tags":["Growth Social"],"operationId":"auto_get_api_v1_accounts_account_id_growth_social_collaborations","summary":"List collaborations","description":"Returns the list of collaborations visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"community_id":{"type":"integer"},"name":{"type":"string"},"mode":{"type":"string","enum":["boost_target","mutual_pod"]},"status":{"type":"string","enum":["draft","active","paused","archived"]},"target_spec":{"type":"string"},"action_spec":{"type":"string"},"eligibility":{"type":"string"},"throttle":{"type":"string"},"schedule":{"type":"string"},"archived_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"},"rounds_count":{"type":"integer"}},"required":["id","community_id","name","mode","status","target_spec","action_spec","eligibility","throttle","schedule","archived_at","created_at"],"additionalProperties":false}}}},"example":{"payload":[{"id":1,"community_id":1,"name":"Sample Name","mode":"boost_target","status":"draft","target_spec":"sample target spec","action_spec":"sample action spec","eligibility":"sample eligibility","throttle":"sample throttle","schedule":"sample schedule","archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","rounds_count":5}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"community_id","in":"query","required":false,"description":"Restrict to collaborations of one community.","schema":{"type":"integer"},"example":3}]},"post":{"tags":["Growth Social"],"operationId":"auto_post_api_v1_accounts_account_id_growth_social_collaborations","summary":"Create collaborations","description":"Creates a new collaboration from the request payload. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"201":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"community_id":{"type":"integer"},"name":{"type":"string"},"mode":{"type":"string","enum":["boost_target","mutual_pod"]},"status":{"type":"string","enum":["draft","active","paused","archived"]},"target_spec":{"type":"string"},"action_spec":{"type":"string"},"eligibility":{"type":"string"},"throttle":{"type":"string"},"schedule":{"type":"string"},"archived_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"},"rounds_count":{"type":"integer"}},"required":["id","community_id","name","mode","status","target_spec","action_spec","eligibility","throttle","schedule","archived_at","created_at"],"additionalProperties":false},"example":{"id":1,"community_id":1,"name":"Sample Name","mode":"boost_target","status":"draft","target_spec":"sample target spec","action_spec":"sample action spec","eligibility":"sample eligibility","throttle":"sample throttle","schedule":"sample schedule","archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","rounds_count":5}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"mode":{"type":"string","enum":["boost_target","mutual_pod"]},"status":{"type":"string","enum":["draft","active","paused","archived"]}},"required":["name"]},"example":{"name":"Sample Name","mode":"boost_target","status":"draft"}}}}}},"/api/v1/accounts/{account_id}/growth_social/collaborations/{id}":{"get":{"tags":["Growth Social"],"operationId":"auto_get_api_v1_accounts_account_id_growth_social_collaborations_id","summary":"Get collaborations","description":"Returns the collaboration identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"community_id":{"type":"integer"},"name":{"type":"string"},"mode":{"type":"string","enum":["boost_target","mutual_pod"]},"status":{"type":"string","enum":["draft","active","paused","archived"]},"target_spec":{"type":"string"},"action_spec":{"type":"string"},"eligibility":{"type":"string"},"throttle":{"type":"string"},"schedule":{"type":"string"},"archived_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"},"rounds_count":{"type":"integer"}},"required":["id","community_id","name","mode","status","target_spec","action_spec","eligibility","throttle","schedule","archived_at","created_at"],"additionalProperties":false},"example":{"id":1,"community_id":1,"name":"Sample Name","mode":"boost_target","status":"draft","target_spec":"sample target spec","action_spec":"sample action spec","eligibility":"sample eligibility","throttle":"sample throttle","schedule":"sample schedule","archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","rounds_count":5}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]},"patch":{"tags":["Growth Social"],"operationId":"auto_patch_api_v1_accounts_account_id_growth_social_collaborations_id","summary":"Update collaborations","description":"Updates the collaboration identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"community_id":{"type":"integer"},"name":{"type":"string"},"mode":{"type":"string","enum":["boost_target","mutual_pod"]},"status":{"type":"string","enum":["draft","active","paused","archived"]},"target_spec":{"type":"string"},"action_spec":{"type":"string"},"eligibility":{"type":"string"},"throttle":{"type":"string"},"schedule":{"type":"string"},"archived_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"},"rounds_count":{"type":"integer"}},"required":["id","community_id","name","mode","status","target_spec","action_spec","eligibility","throttle","schedule","archived_at","created_at"],"additionalProperties":false},"example":{"id":1,"community_id":1,"name":"Sample Name","mode":"boost_target","status":"draft","target_spec":"sample target spec","action_spec":"sample action spec","eligibility":"sample eligibility","throttle":"sample throttle","schedule":"sample schedule","archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","rounds_count":5}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"mode":{"type":"string","enum":["boost_target","mutual_pod"]},"status":{"type":"string","enum":["draft","active","paused","archived"]}}},"example":{"name":"Sample Name","mode":"boost_target","status":"draft"}}}}},"put":{"tags":["Growth Social"],"operationId":"auto_put_api_v1_accounts_account_id_growth_social_collaborations_id","summary":"Update collaborations","description":"Updates the collaboration identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"community_id":{"type":"integer"},"name":{"type":"string"},"mode":{"type":"string","enum":["boost_target","mutual_pod"]},"status":{"type":"string","enum":["draft","active","paused","archived"]},"target_spec":{"type":"string"},"action_spec":{"type":"string"},"eligibility":{"type":"string"},"throttle":{"type":"string"},"schedule":{"type":"string"},"archived_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"},"rounds_count":{"type":"integer"}},"required":["id","community_id","name","mode","status","target_spec","action_spec","eligibility","throttle","schedule","archived_at","created_at"],"additionalProperties":false},"example":{"id":1,"community_id":1,"name":"Sample Name","mode":"boost_target","status":"draft","target_spec":"sample target spec","action_spec":"sample action spec","eligibility":"sample eligibility","throttle":"sample throttle","schedule":"sample schedule","archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","rounds_count":5}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"mode":{"type":"string","enum":["boost_target","mutual_pod"]},"status":{"type":"string","enum":["draft","active","paused","archived"]}}},"example":{"name":"Sample Name","mode":"boost_target","status":"draft"}}}}},"delete":{"tags":["Growth Social"],"operationId":"auto_delete_api_v1_accounts_account_id_growth_social_collaborations_id","summary":"Delete collaborations","description":"Deletes the collaboration identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Success (no content)"},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/growth_social/memberships":{"get":{"tags":["Growth Social"],"operationId":"auto_get_api_v1_accounts_account_id_growth_social_memberships","summary":"List memberships","description":"Returns the list of memberships visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"community_id":{"type":"integer"},"member_id":{"type":"integer"},"member":{"type":["string","null"]},"role":{"type":"string","enum":["member","captain","admin"],"description":"The member's role in the community."},"status":{"type":"string","enum":["pending","active","paused","left"],"description":"Membership state of the public community member."},"reputation_score":{"type":"string"},"tier":{"type":"string","enum":["champion","active","at_risk","dormant"],"description":"Community engagement/retention tier derived from the reputation score."},"points_balance":{"type":"string"},"give_count":{"type":"integer"},"receive_count":{"type":"integer"},"joined_at":{"type":"string","format":"date-time"}},"required":["id","community_id","member_id","member","role","status","reputation_score","tier","points_balance","give_count","receive_count","joined_at"],"additionalProperties":false}}}},"example":{"payload":[{"id":1,"community_id":1,"member_id":1,"member":"sample member","role":"member","status":"pending","reputation_score":"sample reputation score","tier":"champion","points_balance":"sample points balance","give_count":5,"receive_count":5,"joined_at":"2026-01-15T10:30:00.000Z"}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"community_id","in":"query","required":false,"description":"Restrict to memberships of one community.","schema":{"type":"integer"},"example":3},{"name":"status","in":"query","required":false,"description":"Restrict to memberships in one state.","schema":{"type":"string","enum":["pending","active","paused","left"]},"example":"active"}]}},"/api/v1/accounts/{account_id}/growth_social/memberships/{id}":{"get":{"tags":["Growth Social"],"operationId":"auto_get_api_v1_accounts_account_id_growth_social_memberships_id","summary":"Get memberships","description":"Returns the membership identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"community_id":{"type":"integer"},"member_id":{"type":"integer"},"member":{"type":["string","null"]},"role":{"type":"string","enum":["member","captain","admin"],"description":"The member's role in the community."},"status":{"type":"string","enum":["pending","active","paused","left"],"description":"Membership state of the public community member."},"reputation_score":{"type":"string"},"tier":{"type":"string","enum":["champion","active","at_risk","dormant"],"description":"Community engagement/retention tier derived from the reputation score."},"points_balance":{"type":"string"},"give_count":{"type":"integer"},"receive_count":{"type":"integer"},"joined_at":{"type":"string","format":"date-time"}},"required":["id","community_id","member_id","member","role","status","reputation_score","tier","points_balance","give_count","receive_count","joined_at"],"additionalProperties":false},"example":{"id":1,"community_id":1,"member_id":1,"member":"sample member","role":"member","status":"pending","reputation_score":"sample reputation score","tier":"champion","points_balance":"sample points balance","give_count":5,"receive_count":5,"joined_at":"2026-01-15T10:30:00.000Z"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]},"patch":{"tags":["Growth Social"],"operationId":"auto_patch_api_v1_accounts_account_id_growth_social_memberships_id","summary":"Update memberships","description":"Updates the membership identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"community_id":{"type":"integer"},"member_id":{"type":"integer"},"member":{"type":["string","null"]},"role":{"type":"string","enum":["member","captain","admin"],"description":"The member's role in the community."},"status":{"type":"string","enum":["pending","active","paused","left"],"description":"Membership state of the public community member."},"reputation_score":{"type":"string"},"tier":{"type":"string","enum":["champion","active","at_risk","dormant"],"description":"Community engagement/retention tier derived from the reputation score."},"points_balance":{"type":"string"},"give_count":{"type":"integer"},"receive_count":{"type":"integer"},"joined_at":{"type":"string","format":"date-time"}},"required":["id","community_id","member_id","member","role","status","reputation_score","tier","points_balance","give_count","receive_count","joined_at"],"additionalProperties":false},"example":{"id":1,"community_id":1,"member_id":1,"member":"sample member","role":"member","status":"pending","reputation_score":"sample reputation score","tier":"champion","points_balance":"sample points balance","give_count":5,"receive_count":5,"joined_at":"2026-01-15T10:30:00.000Z"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["pending","active","paused","left"],"description":"Membership state of the public community member."},"role":{"type":"string","enum":["member","captain","admin"],"description":"The member's role in the community."}}},"example":{"status":"pending","role":"member"}}}}},"put":{"tags":["Growth Social"],"operationId":"auto_put_api_v1_accounts_account_id_growth_social_memberships_id","summary":"Update memberships","description":"Updates the membership identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"community_id":{"type":"integer"},"member_id":{"type":"integer"},"member":{"type":["string","null"]},"role":{"type":"string","enum":["member","captain","admin"],"description":"The member's role in the community."},"status":{"type":"string","enum":["pending","active","paused","left"],"description":"Membership state of the public community member."},"reputation_score":{"type":"string"},"tier":{"type":"string","enum":["champion","active","at_risk","dormant"],"description":"Community engagement/retention tier derived from the reputation score."},"points_balance":{"type":"string"},"give_count":{"type":"integer"},"receive_count":{"type":"integer"},"joined_at":{"type":"string","format":"date-time"}},"required":["id","community_id","member_id","member","role","status","reputation_score","tier","points_balance","give_count","receive_count","joined_at"],"additionalProperties":false},"example":{"id":1,"community_id":1,"member_id":1,"member":"sample member","role":"member","status":"pending","reputation_score":"sample reputation score","tier":"champion","points_balance":"sample points balance","give_count":5,"receive_count":5,"joined_at":"2026-01-15T10:30:00.000Z"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["pending","active","paused","left"],"description":"Membership state of the public community member."},"role":{"type":"string","enum":["member","captain","admin"],"description":"The member's role in the community."}}},"example":{"status":"pending","role":"member"}}}}}},"/api/v1/accounts/{account_id}/growth_social/members":{"get":{"tags":["Growth Social"],"operationId":"auto_get_api_v1_accounts_account_id_growth_social_members","summary":"List members","description":"Returns the list of members visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"email":{"type":"string","format":"email"},"name":{"type":"string"},"avatar_url":{"type":"string"},"status":{"type":"string","enum":["invited","active","suspended"],"description":"Membership state of the public community member."},"locale":{"type":"string"},"last_login_at":{"type":"string","format":"date-time"},"memberships_count":{"type":"integer"},"accounts_count":{"type":"integer"},"memberships":{"type":"array","items":{"type":"object","properties":{"community_id":{"type":"integer"},"status":{"type":"string","enum":["invited","active","suspended"],"description":"Membership state of the public community member."},"points":{"type":"string"},"tier":{"type":"string","enum":["champion","active","at_risk","dormant"],"description":"Community engagement/retention tier derived from the reputation score."}}}},"accounts":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Free-form object."}}}}}}},"example":{"payload":[{"id":1,"email":"agent@example.com","name":"Sample Name","avatar_url":"https://example.com/resource","status":"invited","locale":"en","last_login_at":"2026-01-15T10:30:00.000Z","memberships_count":5,"accounts_count":5,"memberships":[{"community_id":1,"status":"invited","points":"sample points","tier":"champion"}],"accounts":[{}]}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"status","in":"query","required":false,"description":"Restrict to members in one state.","schema":{"type":"string","enum":["invited","active","suspended"]},"example":"active"}]}},"/api/v1/accounts/{account_id}/growth_social/members/{id}":{"get":{"tags":["Growth Social"],"operationId":"auto_get_api_v1_accounts_account_id_growth_social_members_id","summary":"Get members","description":"Returns the member identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"email":{"type":"string","format":"email"},"name":{"type":"string"},"avatar_url":{"type":"string"},"status":{"type":"string","enum":["invited","active","suspended"],"description":"Membership state of the public community member."},"locale":{"type":"string"},"last_login_at":{"type":"string","format":"date-time"},"memberships_count":{"type":"integer"},"accounts_count":{"type":"integer"},"memberships":{"type":"array","items":{"type":"object","properties":{"community_id":{"type":"integer"},"status":{"type":"string","enum":["invited","active","suspended"],"description":"Membership state of the public community member."},"points":{"type":"string"},"tier":{"type":"string","enum":["champion","active","at_risk","dormant"],"description":"Community engagement/retention tier derived from the reputation score."}}}},"accounts":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Free-form object."}}}},"example":{"id":1,"email":"agent@example.com","name":"Sample Name","avatar_url":"https://example.com/resource","status":"invited","locale":"en","last_login_at":"2026-01-15T10:30:00.000Z","memberships_count":5,"accounts_count":5,"memberships":[{"community_id":1,"status":"invited","points":"sample points","tier":"champion"}],"accounts":[{}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]},"patch":{"tags":["Growth Social"],"operationId":"auto_patch_api_v1_accounts_account_id_growth_social_members_id","summary":"Update members","description":"Updates the member identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"email":{"type":"string","format":"email"},"name":{"type":"string"},"avatar_url":{"type":"string"},"status":{"type":"string","enum":["invited","active","suspended"],"description":"Membership state of the public community member."},"locale":{"type":"string"},"last_login_at":{"type":"string","format":"date-time"},"memberships_count":{"type":"integer"},"accounts_count":{"type":"integer"},"memberships":{"type":"array","items":{"type":"object","properties":{"community_id":{"type":"integer"},"status":{"type":"string","enum":["invited","active","suspended"],"description":"Membership state of the public community member."},"points":{"type":"string"},"tier":{"type":"string","enum":["champion","active","at_risk","dormant"],"description":"Community engagement/retention tier derived from the reputation score."}}}},"accounts":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Free-form object."}}}},"example":{"id":1,"email":"agent@example.com","name":"Sample Name","avatar_url":"https://example.com/resource","status":"invited","locale":"en","last_login_at":"2026-01-15T10:30:00.000Z","memberships_count":5,"accounts_count":5,"memberships":[{"community_id":1,"status":"invited","points":"sample points","tier":"champion"}],"accounts":[{}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["invited","active","suspended"],"description":"Membership state of the public community member."}}},"example":{"status":"invited"}}}}},"put":{"tags":["Growth Social"],"operationId":"auto_put_api_v1_accounts_account_id_growth_social_members_id","summary":"Update members","description":"Updates the member identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"email":{"type":"string","format":"email"},"name":{"type":"string"},"avatar_url":{"type":"string"},"status":{"type":"string","enum":["invited","active","suspended"],"description":"Membership state of the public community member."},"locale":{"type":"string"},"last_login_at":{"type":"string","format":"date-time"},"memberships_count":{"type":"integer"},"accounts_count":{"type":"integer"},"memberships":{"type":"array","items":{"type":"object","properties":{"community_id":{"type":"integer"},"status":{"type":"string","enum":["invited","active","suspended"],"description":"Membership state of the public community member."},"points":{"type":"string"},"tier":{"type":"string","enum":["champion","active","at_risk","dormant"],"description":"Community engagement/retention tier derived from the reputation score."}}}},"accounts":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Free-form object."}}}},"example":{"id":1,"email":"agent@example.com","name":"Sample Name","avatar_url":"https://example.com/resource","status":"invited","locale":"en","last_login_at":"2026-01-15T10:30:00.000Z","memberships_count":5,"accounts_count":5,"memberships":[{"community_id":1,"status":"invited","points":"sample points","tier":"champion"}],"accounts":[{}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["invited","active","suspended"],"description":"Membership state of the public community member."}}},"example":{"status":"invited"}}}}}},"/api/v1/accounts/{account_id}/growth_social/engagement_rounds":{"get":{"tags":["Growth Social"],"operationId":"auto_get_api_v1_accounts_account_id_growth_social_engagement_rounds","summary":"List engagement rounds","description":"Returns the list of engagement rounds visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"collaboration_id":{"type":"integer"},"target_ref":{"type":"string"},"trigger":{"type":"string"},"status":{"type":"string","enum":["building","dispatching","completed","failed"]},"planned_count":{"type":"integer"},"dispatched_count":{"type":"integer"},"succeeded_count":{"type":"integer"},"started_at":{"type":"string","format":"date-time"},"finished_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"},"tasks_by_status":{"type":"object","description":"Engagement-task counts keyed by task status. Returned only on the round detail; a status with no task is omitted.","properties":{"queued":{"type":"integer","description":"Tasks not yet dispatched."},"dispatched":{"type":"integer","description":"Tasks whose engagement action was created and queued for execution."},"succeeded":{"type":"integer","description":"Tasks whose engagement action succeeded."},"failed":{"type":"integer","description":"Tasks whose engagement action failed."},"skipped":{"type":"integer","description":"Tasks skipped because no engagement action could be created for them."}},"additionalProperties":false}}}}}},"example":{"payload":[{"id":1,"collaboration_id":1,"target_ref":"sample target ref","trigger":"sample trigger","status":"building","planned_count":5,"dispatched_count":5,"succeeded_count":5,"started_at":"2026-01-15T10:30:00.000Z","finished_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","tasks_by_status":{"queued":1,"dispatched":1,"succeeded":1,"failed":1,"skipped":1}}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"collaboration_id","in":"query","required":false,"description":"Restrict to rounds of one collaboration.","schema":{"type":"integer"},"example":5},{"name":"status","in":"query","required":false,"description":"Restrict to rounds in one state.","schema":{"type":"string","enum":["building","dispatching","completed","failed"]},"example":"completed"}]}},"/api/v1/accounts/{account_id}/growth_social/engagement_rounds/{id}":{"get":{"tags":["Growth Social"],"operationId":"auto_get_api_v1_accounts_account_id_growth_social_engagement_rounds_id","summary":"Get engagement rounds","description":"Returns the engagement round identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"collaboration_id":{"type":"integer"},"target_ref":{"type":"string"},"trigger":{"type":"string"},"status":{"type":"string","enum":["building","dispatching","completed","failed"]},"planned_count":{"type":"integer"},"dispatched_count":{"type":"integer"},"succeeded_count":{"type":"integer"},"started_at":{"type":"string","format":"date-time"},"finished_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"},"tasks_by_status":{"type":"object","description":"Engagement-task counts keyed by task status. Returned only on the round detail; a status with no task is omitted.","properties":{"queued":{"type":"integer","description":"Tasks not yet dispatched."},"dispatched":{"type":"integer","description":"Tasks whose engagement action was created and queued for execution."},"succeeded":{"type":"integer","description":"Tasks whose engagement action succeeded."},"failed":{"type":"integer","description":"Tasks whose engagement action failed."},"skipped":{"type":"integer","description":"Tasks skipped because no engagement action could be created for them."}},"additionalProperties":false}}},"example":{"id":1,"collaboration_id":1,"target_ref":"sample target ref","trigger":"sample trigger","status":"building","planned_count":5,"dispatched_count":5,"succeeded_count":5,"started_at":"2026-01-15T10:30:00.000Z","finished_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","tasks_by_status":{"queued":1,"dispatched":1,"succeeded":1,"failed":1,"skipped":1}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/growth_social/rewards/leaderboard":{"get":{"tags":["Growth Social"],"operationId":"auto_get_api_v1_accounts_account_id_growth_social_rewards_leaderboard","summary":"Leaderboard rewards","description":"Performs the leaderboard operation on the targeted reward resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"string"}}},"example":{"payload":"sample payload"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"community_id","in":"query","required":false,"description":"Community to rank. Omitted, every community the account owns is ranked together.","schema":{"type":"integer"},"example":3}]}},"/api/v1/accounts/{account_id}/growth_social/rewards/overview":{"get":{"tags":["Growth Social"],"operationId":"auto_get_api_v1_accounts_account_id_growth_social_rewards_overview","summary":"Overview rewards","description":"Performs the overview operation on the targeted reward resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Account-wide collaboration rollup (rewards overview)","content":{"application/json":{"schema":{"type":"object","properties":{"communities":{"type":"integer","example":3},"members":{"type":"integer","example":42},"active_collaborations":{"type":"integer","example":5},"rounds":{"type":"object","additionalProperties":{"type":"integer"},"example":{"completed":18,"dispatching":2,"failed":1},"description":"Engagement-round counts keyed by round status (building, dispatching, completed, failed)."},"points_distributed":{"type":"number","format":"float","example":12400}}},"example":{"communities":3,"members":42,"active_collaborations":5,"rounds":{"completed":18,"dispatching":2,"failed":1},"points_distributed":12400}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/growth_social/rewards/matrix":{"get":{"tags":["Growth Social"],"operationId":"auto_get_api_v1_accounts_account_id_growth_social_rewards_matrix","summary":"Matrix rewards","description":"Performs the matrix operation on the targeted reward resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Insights matrix rollup for one community (shared-insight snapshots)","content":{"application/json":{"schema":{"type":"object","properties":{"members":{"type":"integer","description":"Memberships in the community","example":15},"snapshots":{"type":"integer","description":"Shared-insight snapshots considered (max 500)","example":120},"followers_total":{"type":"number","format":"float","description":"Sum of followers across snapshots","example":84300},"by_source":{"type":"object","description":"Snapshot counts grouped by source","additionalProperties":{"type":"integer"},"example":{"manual":40,"auto":80}}}},"example":{"members":15,"snapshots":120,"followers_total":84300,"by_source":{"manual":40,"auto":80}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"community_id","in":"query","required":false,"description":"Community the matrix is computed for. Omitted, every community the account owns is included.","schema":{"type":"integer"},"example":3}]}},"/api/v1/accounts/{account_id}/growth_social/rewards":{"get":{"tags":["Growth Social"],"operationId":"auto_get_api_v1_accounts_account_id_growth_social_rewards","summary":"List rewards","description":"Returns the list of rewards visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"amount":{"type":"number"},"kind":{"type":"string","enum":["physical","voucher","pix","perk"]},"balance_after":{"type":"string"},"source":{"type":"string"},"created_at":{"type":"string","format":"date-time"}},"required":["id","amount","kind","balance_after","source","created_at"],"additionalProperties":false}},"balance":{"type":"string"}}},"example":{"payload":[{"id":1,"amount":149.9,"kind":"physical","balance_after":"sample balance after","source":"sample source","created_at":"2026-01-15T10:30:00.000Z"}],"balance":"sample balance"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"membership_id","in":"query","required":true,"description":"Membership whose reward ledger is returned. A membership outside the account returns 404.","schema":{"type":"integer"},"example":77}]}},"/api/v1/accounts/{account_id}/ads/leads/{id}/conversions":{"get":{"tags":["Ads"],"operationId":"auto_get_api_v1_accounts_account_id_ads_leads_id_conversions","summary":"List the conversion ledger for an ad lead","description":"Returns the bounded, newest-first ledger of conversion attempts associated with one ad lead, including delivery status, optional value and the PII-free request and provider response used for diagnostics.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The ad lead's conversion ledger.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["payload"],"properties":{"payload":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["id","provider","event_name","event_id","action_source","status","http_status","value_amount","currency","test","error","error_code","sent_at","created_at","request_payload","response_body"],"properties":{"id":{"type":"integer"},"provider":{"type":"string","enum":["meta","google_ads","tiktok"],"description":"Conversion provider recorded in the ledger. Meta is live; Google Ads and TikTok are reserved scaffold providers and do not perform a real send yet."},"event_name":{"type":"string"},"event_id":{"type":"string"},"action_source":{"type":["string","null"],"enum":["business_messaging","system_generated",null]},"status":{"type":"string","enum":["pending","sent","failed","skipped"]},"http_status":{"type":["integer","null"],"description":"HTTP status returned by the provider; null before a response exists."},"value_amount":{"type":["number","null"]},"currency":{"type":["string","null"],"minLength":3,"maxLength":3},"test":{"type":"boolean"},"error":{"type":["string","null"],"description":"Raw failure or skip reason as recorded, kept for diagnosis."},"error_code":{"type":["string","null"],"enum":["no_attribution","no_provider_ready","unsupported_event_name","missing_messenger_identity","missing_instagram_identity","no_dataset","no_conversions_dataset","no_token","no_permission","token_invalid","invalid_event_name","invalid_parameter","rate_limited","meta_unavailable","connection_failed","read_timeout_not_retried","transport_error_not_retried","unknown",null],"description":"Stable code of a failed or skipped attempt, null otherwise. read_timeout_not_retried and transport_error_not_retried are never retried automatically because Meta does not deduplicate business-messaging events; connection_failed, rate_limited and meta_unavailable are retried with the same event_id."},"sent_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"},"request_payload":{"type":"object","additionalProperties":true,"description":"PII-free event body sent to the conversion provider."},"response_body":{"type":"object","additionalProperties":true,"description":"Parsed response returned by the conversion provider."}}}}}},"example":{"payload":[{"id":82,"provider":"meta","event_name":"Purchase","event_id":"manual:purchase:ads_lead:42","action_source":"business_messaging","status":"sent","http_status":200,"value_amount":6080.0,"currency":"BRL","test":false,"error":null,"error_code":null,"sent_at":"2026-08-02T23:44:38.000Z","created_at":"2026-08-02T23:44:38.000Z","request_payload":{"event_name":"Purchase","event_time":1785714278,"event_id":"manual:purchase:ads_lead:42","action_source":"business_messaging","messaging_channel":"whatsapp","user_data":{"whatsapp_business_account_id":"102938475610293","ctwa_clid":"ARB3118xyz"},"custom_data":{"value":6080.0,"currency":"BRL"}},"response_body":{"events_received":1,"fbtrace_id":"AXExampleTrace"}}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/ads/leads/{id}/trigger_conversion":{"post":{"tags":["Ads"],"operationId":"auto_post_api_v1_accounts_account_id_ads_leads_id_trigger_conversion","summary":"Send a Meta conversion event for an ad lead","description":"Sends one supported business-messaging conversion event for the selected ad lead and returns its refreshed conversion ledger. Lead and Contact remain accepted as compatibility aliases and are normalized to LeadSubmitted and ViewContent. Repeating the same event for the same lead is idempotent.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The refreshed conversion ledger after the manual attempt.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["payload"],"properties":{"payload":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["id","provider","event_name","event_id","action_source","status","http_status","value_amount","currency","test","error","error_code","sent_at","created_at","request_payload","response_body"],"properties":{"id":{"type":"integer"},"provider":{"type":"string","enum":["meta","google_ads","tiktok"],"description":"Conversion provider recorded in the ledger. Meta is live; Google Ads and TikTok are reserved scaffold providers and do not perform a real send yet."},"event_name":{"type":"string"},"event_id":{"type":"string"},"action_source":{"type":["string","null"],"enum":["business_messaging","system_generated",null]},"status":{"type":"string","enum":["pending","sent","failed","skipped"]},"http_status":{"type":["integer","null"],"description":"HTTP status returned by the provider; null before a response exists."},"value_amount":{"type":["number","null"]},"currency":{"type":["string","null"],"minLength":3,"maxLength":3},"test":{"type":"boolean"},"error":{"type":["string","null"],"description":"Raw failure or skip reason as recorded, kept for diagnosis."},"error_code":{"type":["string","null"],"enum":["no_attribution","no_provider_ready","unsupported_event_name","missing_messenger_identity","missing_instagram_identity","no_dataset","no_conversions_dataset","no_token","no_permission","token_invalid","invalid_event_name","invalid_parameter","rate_limited","meta_unavailable","connection_failed","read_timeout_not_retried","transport_error_not_retried","unknown",null],"description":"Stable code of a failed or skipped attempt, null otherwise. read_timeout_not_retried and transport_error_not_retried are never retried automatically because Meta does not deduplicate business-messaging events; connection_failed, rate_limited and meta_unavailable are retried with the same event_id."},"sent_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"},"request_payload":{"type":"object","additionalProperties":true,"description":"PII-free event body sent to the conversion provider."},"response_body":{"type":"object","additionalProperties":true,"description":"Parsed response returned by the conversion provider."}}}}}},"example":{"payload":[{"id":82,"provider":"meta","event_name":"Purchase","event_id":"manual:purchase:ads_lead:42","action_source":"business_messaging","status":"sent","http_status":200,"value_amount":6080.0,"currency":"BRL","test":false,"error":null,"error_code":null,"sent_at":"2026-08-02T23:44:38.000Z","created_at":"2026-08-02T23:44:38.000Z","request_payload":{"event_name":"Purchase","event_time":1785714278,"event_id":"manual:purchase:ads_lead:42","action_source":"business_messaging","messaging_channel":"whatsapp","user_data":{"whatsapp_business_account_id":"102938475610293","ctwa_clid":"ARB3118xyz"},"custom_data":{"value":6080.0,"currency":"BRL"}},"response_body":{"events_received":1,"fbtrace_id":"AXExampleTrace"}}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"422":{"description":"Conversion tracking is disabled for the inbox or the event is unsupported.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","enum":["conversions_not_enabled","invalid_conversion_event"]}}},"example":{"error":"invalid_conversion_event"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["event_name"],"properties":{"event_name":{"type":"string","enum":["LeadSubmitted","QualifiedLead","ViewContent","AddToCart","InitiateCheckout","Purchase","Lead","Contact"],"description":"Meta business-messaging event; Lead and Contact are legacy compatibility aliases."},"value":{"type":"number","minimum":0,"description":"Optional monetary value, normally supplied for Purchase."},"currency":{"type":"string","minLength":3,"maxLength":3,"description":"ISO 4217 currency code for value, such as BRL."}}},"example":{"event_name":"Purchase","value":6080.0,"currency":"BRL"}}}}}},"/api/v1/accounts/{account_id}/ads/leads/{id}/set_ownership":{"patch":{"tags":["Ads"],"operationId":"auto_patch_api_v1_accounts_account_id_ads_leads_id_set_ownership","summary":"Set ownership leads","description":"Performs the set ownership operation on the targeted lead resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"source":{"type":"string","enum":["ctwa","leadgen","ctm","ctd"]},"status":{"type":"string","enum":["captured","enriched","failed","converted"]},"ctwa_clid":{"type":"string"},"source_id":{"type":"integer"},"ad_id":{"type":"integer"},"headline":{"type":"string"},"leadgen_id":{"type":"integer"},"form_id":{"type":"integer"},"page_id":{"type":"integer"},"campaign_id":{"type":"integer"},"adset_id":{"type":"integer"},"owned":{"type":"string"},"attribution_reason":{"type":"boolean"},"contact_id":{"type":"integer"},"contact_name":{"type":"string"},"conversation_id":{"type":"integer"},"inbox_id":{"type":"integer"},"logical_inbox_id":{"type":"integer"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"crm_item_id":{"type":"integer"},"converted_at":{"type":"string","format":"date-time"},"conversion_value_amount":{"type":"number"},"conversion_currency":{"type":"string"},"preview":{"type":"object","properties":{"thumbnail_url":{"type":"string"},"source_app":{"type":"string"},"source_type":{"type":"string"},"media_type":{"type":"string"},"title":{"type":"string"}}},"conversation_display_id":{"type":["integer","null"]},"raw":{"type":"string"},"field_data":{"type":"array","description":"Normalized lead-form answers (empty for CTWA leads).","items":{"type":"object","properties":{"name":{"type":"string"},"value":{"type":"string"}}}}}},"example":{"id":1,"account_id":1,"source":"ctwa","status":"captured","ctwa_clid":"sample ctwa clid","source_id":1,"ad_id":1,"headline":"sample headline","leadgen_id":1,"form_id":1,"page_id":1,"campaign_id":1,"adset_id":1,"owned":"sample owned","attribution_reason":true,"contact_id":1,"contact_name":"sample contact name","conversation_id":1,"inbox_id":1,"logical_inbox_id":1,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","crm_item_id":1,"converted_at":"2026-01-15T10:30:00.000Z","conversion_value_amount":149.9,"conversion_currency":"sample conversion currency","preview":{"thumbnail_url":"https://example.com/resource","source_app":"sample source app","source_type":"sample source type","media_type":"sample media type","title":"Sample title"},"conversation_display_id":1,"raw":"sample raw","field_data":[{"name":"Sample Name","value":"sample value"}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"owned":{"type":"string"},"apply_to_ad":{"type":"string"}}},"example":{"owned":"sample owned","apply_to_ad":"sample apply to ad"}}}}}},"/api/v1/accounts/{account_id}/ads/leads/report":{"get":{"tags":["Ads"],"operationId":"auto_get_api_v1_accounts_account_id_ads_leads_report","summary":"Report leads","description":"Performs the report operation on the targeted lead resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"total":{"type":"number"},"owned_total":{"type":"number"},"external_total":{"type":"number"},"by_source":{"type":"string"},"by_status":{"type":"object","additionalProperties":{"type":"integer"},"description":"Lead counts keyed by lead status (captured, enriched, failed, converted)."},"by_owned":{"type":"string"},"conversions":{"type":"string"}}},"example":{"total":149.9,"owned_total":149.9,"external_total":149.9,"by_source":"sample by source","by_status":{},"by_owned":"sample by owned","conversions":"sample conversions"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/ads/leads":{"get":{"tags":["Ads"],"operationId":"auto_get_api_v1_accounts_account_id_ads_leads","summary":"List leads","description":"Returns the list of leads visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"source":{"type":"string","enum":["ctwa","leadgen","ctm","ctd"]},"status":{"type":"string","enum":["captured","enriched","failed","converted"]},"ctwa_clid":{"type":"string"},"source_id":{"type":"integer"},"ad_id":{"type":"integer"},"headline":{"type":"string"},"leadgen_id":{"type":"integer"},"form_id":{"type":"integer"},"page_id":{"type":"integer"},"campaign_id":{"type":"integer"},"adset_id":{"type":"integer"},"owned":{"type":"string"},"attribution_reason":{"type":"boolean"},"contact_id":{"type":"integer"},"contact_name":{"type":"string"},"conversation_id":{"type":"integer"},"inbox_id":{"type":"integer"},"logical_inbox_id":{"type":"integer"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"crm_item_id":{"type":"integer"},"converted_at":{"type":"string","format":"date-time"},"conversion_value_amount":{"type":"number"},"conversion_currency":{"type":"string"},"preview":{"type":"object","properties":{"thumbnail_url":{"type":"string"},"source_app":{"type":"string"},"source_type":{"type":"string"},"media_type":{"type":"string"},"title":{"type":"string"}}}}}},"meta":{"type":"object","properties":{"count":{"type":"integer"}}}}},"example":{"payload":[{"id":1,"account_id":1,"source":"ctwa","status":"captured","ctwa_clid":"sample ctwa clid","source_id":1,"ad_id":1,"headline":"sample headline","leadgen_id":1,"form_id":1,"page_id":1,"campaign_id":1,"adset_id":1,"owned":"sample owned","attribution_reason":true,"contact_id":1,"contact_name":"sample contact name","conversation_id":1,"inbox_id":1,"logical_inbox_id":1,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","crm_item_id":1,"converted_at":"2026-01-15T10:30:00.000Z","conversion_value_amount":149.9,"conversion_currency":"sample conversion currency","preview":{"thumbnail_url":"https://example.com/resource","source_app":"sample source app","source_type":"sample source type","media_type":"sample media type","title":"Sample title"}}],"meta":{"count":5}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."}]}},"/api/v1/accounts/{account_id}/ads/leads/{id}":{"get":{"tags":["Ads"],"operationId":"auto_get_api_v1_accounts_account_id_ads_leads_id","summary":"Get leads","description":"Returns the lead identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"source":{"type":"string","enum":["ctwa","leadgen","ctm","ctd"]},"status":{"type":"string","enum":["captured","enriched","failed","converted"]},"ctwa_clid":{"type":"string"},"source_id":{"type":"integer"},"ad_id":{"type":"integer"},"headline":{"type":"string"},"leadgen_id":{"type":"integer"},"form_id":{"type":"integer"},"page_id":{"type":"integer"},"campaign_id":{"type":"integer"},"adset_id":{"type":"integer"},"owned":{"type":"string"},"attribution_reason":{"type":"boolean"},"contact_id":{"type":"integer"},"contact_name":{"type":"string"},"conversation_id":{"type":"integer"},"inbox_id":{"type":"integer"},"logical_inbox_id":{"type":"integer"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"crm_item_id":{"type":"integer"},"converted_at":{"type":"string","format":"date-time"},"conversion_value_amount":{"type":"number"},"conversion_currency":{"type":"string"},"preview":{"type":"object","properties":{"thumbnail_url":{"type":"string"},"source_app":{"type":"string"},"source_type":{"type":"string"},"media_type":{"type":"string"},"title":{"type":"string"}}},"conversation_display_id":{"type":["integer","null"]},"raw":{"type":"string"},"field_data":{"type":"array","description":"Normalized lead-form answers (empty for CTWA leads).","items":{"type":"object","properties":{"name":{"type":"string"},"value":{"type":"string"}}}}}},"example":{"id":1,"account_id":1,"source":"ctwa","status":"captured","ctwa_clid":"sample ctwa clid","source_id":1,"ad_id":1,"headline":"sample headline","leadgen_id":1,"form_id":1,"page_id":1,"campaign_id":1,"adset_id":1,"owned":"sample owned","attribution_reason":true,"contact_id":1,"contact_name":"sample contact name","conversation_id":1,"inbox_id":1,"logical_inbox_id":1,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","crm_item_id":1,"converted_at":"2026-01-15T10:30:00.000Z","conversion_value_amount":149.9,"conversion_currency":"sample conversion currency","preview":{"thumbnail_url":"https://example.com/resource","source_app":"sample source app","source_type":"sample source type","media_type":"sample media type","title":"Sample title"},"conversation_display_id":1,"raw":"sample raw","field_data":[{"name":"Sample Name","value":"sample value"}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]},"delete":{"tags":["Ads"],"operationId":"auto_delete_api_v1_accounts_account_id_ads_leads_id","summary":"Delete leads","description":"Deletes the lead identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Success (no content)"},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/ads/conversion_settings/{inbox_id}/test_event":{"post":{"tags":["Ads"],"operationId":"auto_post_api_v1_accounts_account_id_ads_conversion_settings_inbox_id_test_event","summary":"Send test conversion events for an inbox","description":"Sends a LeadSubmitted and a Purchase event to Meta with a test event code, so the operator can confirm the wiring in Events Manager → Test Events before turning the inbox on. Test events never reach Meta's ad optimization and are not written to the conversion ledger. The values on screen are applied in memory (nothing is saved). The event shape follows the inbox's channel: WhatsApp (WhatsApp Business Account plus a synthetic click id), Messenger (Page id plus a synthetic Page-scoped id) or Instagram (professional account id plus a synthetic Instagram-scoped id).","security":[{"userApiKey":[]}],"responses":{"200":{"description":"One result per test event, or a single result when the test could not start.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["results"],"properties":{"results":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["ok","error"],"properties":{"event_name":{"type":"string","enum":["LeadSubmitted","Purchase"]},"ok":{"type":"boolean"},"http_status":{"type":["integer","null"],"description":"HTTP status returned by Meta."},"response":{"type":"object","additionalProperties":true,"description":"Meta's parsed response."},"error":{"type":["string","null"],"description":"Raw failure reason","kept for diagnosis.":null},"error_code":{"type":["string","null"],"enum":["meta_not_credentialed","test_event_code_required","unsupported_event_name","missing_messenger_identity","missing_instagram_identity","no_dataset","no_conversions_dataset","no_token","no_permission","token_invalid","invalid_event_name","invalid_parameter","rate_limited","meta_unavailable","connection_failed","read_timeout_not_retried","transport_error_not_retried","unknown",null],"description":"Stable code of a failed test event, null when it succeeded."},"request":{"type":"object","additionalProperties":true,"description":"The PII-free event body that was sent."},"dataset_id":{"type":["string","null"],"description":"Dataset the event went to."}}}}}},"example":{"results":[{"event_name":"LeadSubmitted","ok":true,"http_status":200,"response":{"events_received":1,"fbtrace_id":"AXExampleTrace"},"error":null,"error_code":null,"request":{"event_name":"LeadSubmitted","event_time":1790889600,"event_id":"test-leadsubmitted-a1b2c3d4e5f6","action_source":"business_messaging","messaging_channel":"messenger","user_data":{"page_id":"109876543210987","page_scoped_user_id":"4820193847561029"},"test_event_code":"TEST48213"},"dataset_id":"1209384756473829"}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"422":{"description":"The test did not run because `meta_api_version` is not one of the supported versions. Nothing was sent to Meta.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["message","attributes"],"properties":{"message":{"type":"string","description":"Validation messages","comma-separated.":null},"attributes":{"type":"array","items":{"type":"string"},"description":"Attributes that failed validation."}}},"example":{"message":"API version v24.0 is not supported for the Conversions API. Use one of: v26.0, v25.0.","attributes":["base"]}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"inbox_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"test_event_code":{"type":"string","description":"Code from Events Manager → Test Events. Falls back to the saved one; required by one of the two."},"use_channel_token":{"type":"boolean","description":"Use the inbox channel's own token for this test."},"meta_waba_id":{"type":"string","description":"WhatsApp Business Account to test with (WhatsApp inboxes)."},"meta_dataset_id":{"type":"string","description":"Dataset to send to."},"meta_api_version":{"type":"string","enum":["v26.0","v25.0"],"deprecated":true,"description":"Ignored; the platform sets the Marketing API version. A value outside the supported list is refused with 422, as on the settings update."},"meta_access_token":{"type":"string","description":"Token to test with (never echoed back)."}}},"example":{"test_event_code":"TEST48213","use_channel_token":true,"meta_waba_id":"104857392018475","meta_dataset_id":"1209384756473829","meta_api_version":"v26.0","meta_access_token":"sample-token"}}}}}},"/api/v1/accounts/{account_id}/ads/conversion_settings/{inbox_id}/discover_dataset":{"post":{"tags":["Ads"],"operationId":"auto_post_api_v1_accounts_account_id_ads_conversion_settings_inbox_id_discover_dataset","summary":"Discover the Meta CAPI dataset id for an inbox","description":"Asks Meta's Dataset API for the Conversions API dataset of the inbox's own asset: the WhatsApp Business Account, the Facebook Page (Messenger) or the Instagram professional account. The call is idempotent on Meta's side: it returns the existing dataset or provisions one. The saved setting can be overridden in memory by the channel token, meta_waba_id or meta_access_token in the body (nothing is saved except a dataset that was found, plus the Meta Ads Manager token when only that token could read it). The token needs the channel's events permission: whatsapp_business_manage_events, page_events or instagram_manage_events.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The resolved dataset id, or an error reason.","content":{"application/json":{"schema":{"type":"object","properties":{"dataset_id":{"type":"string","description":"Present on success.","example":"1234567890"},"via":{"type":"string","enum":["inbox_token","ads_manager_token"],"description":"Which token resolved the dataset; present on success.","example":"inbox_token"},"error":{"type":"string","description":"Present on failure: no_waba, no_messenger_asset or no_instagram_asset (the inbox has no asset to look up), no_token, no_permission (the token lacks the channel's events permission), no_conversions_dataset, dataset_discovery_unreachable or dataset_discovery_failed, or Meta's own message for any other Graph error.","example":"no_permission"}}},"example":{"dataset_id":"1234567890","via":"inbox_token","error":"no_permission"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"inbox_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"use_channel_token":{"type":"boolean","description":"Apply the linked channel's credentials to the setting before discovery.","example":true},"meta_waba_id":{"type":"string","description":"WhatsApp Business Account to look up (WhatsApp inboxes only).","example":"102290129340398"},"meta_access_token":{"type":"string","description":"Override access token (never echoed back).","example":"EAAG..."}}},"example":{"use_channel_token":true,"meta_waba_id":"102290129340398","meta_access_token":"EAAG..."}}}}}},"/api/v1/accounts/{account_id}/ads/conversion_settings/{inbox_id}":{"get":{"tags":["Ads"],"operationId":"auto_get_api_v1_accounts_account_id_ads_conversion_settings_inbox_id","summary":"Show the inbox's ad conversion-tracking settings","description":"Returns the Conversions API settings of the inbox, prefilled from the inbox channel when nothing was saved yet. The access token is never returned. The Marketing API version is set by the platform for every inbox: `effective_meta_api_version` is the one called, and the legacy `meta_api_version` is only the stored value.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The inbox's conversion-tracking settings, with secrets masked.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["inbox_id","logical_inbox_id","enabled","meta_enabled","meta_dataset_id","meta_waba_id","meta_test_event_code","meta_partner_agent","meta_api_version","effective_meta_api_version","advanced_matching","lead_on_capture","contact_on_first_message","purchase_on_won","custom_on_lost","purchase_on_payment","lost_event_name","stage_event_map","has_meta_access_token","meta_access_token_masked","meta_ready","meta_credentialed","persisted","suggestions"],"properties":{"inbox_id":{"type":"integer","description":"Inbox the settings belong to."},"logical_inbox_id":{"type":"integer","description":"Inbox id the dashboard shows for this number (the paired inbox on a hybrid number)."},"enabled":{"type":"boolean","description":"Master switch for sending conversions."},"meta_enabled":{"type":"boolean","description":"Whether the Meta Conversions API provider is on."},"meta_dataset_id":{"type":["string","null"],"description":"Meta dataset that receives the events."},"meta_waba_id":{"type":["string","null"],"description":"WhatsApp Business account used to discover the dataset."},"meta_test_event_code":{"type":["string","null"],"description":"Test event code sent with test events."},"meta_partner_agent":{"type":"string","description":"Partner agent string sent with every event."},"meta_api_version":{"type":"string","deprecated":true,"description":"Legacy per-inbox value, as stored (an older row may hold, for example, v25.0 or v24.0). The version is set by the platform for every inbox and this field is ignored when sending; read `effective_meta_api_version`."},"effective_meta_api_version":{"type":"string","enum":["v26.0","v25.0"],"description":"Marketing API version the Conversions API client calls — the installation-wide version, the same for every inbox."},"advanced_matching":{"type":"boolean","description":"Send hashed contact identifiers for advanced matching."},"lead_on_capture":{"type":"boolean","description":"Send a lead event when an ad lead is captured."},"contact_on_first_message":{"type":"boolean","description":"Send an event on the contact's first message."},"purchase_on_won":{"type":"boolean","description":"Send a purchase event when a deal is won."},"custom_on_lost":{"type":"boolean","description":"Send the lost event when a deal is lost."},"purchase_on_payment":{"type":"boolean","description":"Send a purchase event when a charge is paid."},"lost_event_name":{"type":"string","description":"Event name sent when a deal is lost."},"stage_event_map":{"type":"object","additionalProperties":{"type":"string"},"description":"Pipeline stage id mapped to the event name sent when a deal enters that stage."},"has_meta_access_token":{"type":"boolean","description":"Whether an access token is stored (never returned)."},"meta_access_token_masked":{"type":["string","null"],"description":"Masked tail of the stored access token."},"meta_ready":{"type":"boolean","description":"Enabled and able to send."},"meta_credentialed":{"type":"boolean","description":"Has a token plus a dataset, or an asset to discover one from (a WABA, a Facebook Page or an Instagram professional account)."},"persisted":{"type":"boolean","description":"Whether the settings have been saved at least once."},"suggestions":{"type":"object","additionalProperties":false,"required":["channel_kind","supports_meta","suggested_waba_id","has_channel_token","manual_dataset","messaging_channel","asset_id","required_scope","optimization_supported"],"description":"Values suggested from the inbox channel.","properties":{"channel_kind":{"type":"string","enum":["default","whatsapp_cloud","whatsapp_web","api","email","facebook_page","instagram","line","sms","telegram","tiktok","twilio_sms","twitter_profile","web_widget"],"description":"WhatsApp provider of the inbox, or its channel type for other channels."},"supports_meta":{"type":"boolean","description":"Whether the channel can send Meta conversions."},"suggested_waba_id":{"type":["string","null"],"description":"WABA id read from the channel."},"has_channel_token":{"type":"boolean","description":"Whether the channel has its own Graph token."},"manual_dataset":{"type":"boolean","description":"Whether the dataset id must be entered manually. False for WhatsApp Cloud, Facebook Page and Instagram inboxes, whose dataset is discovered from the WABA, the Page or the Instagram account."},"messaging_channel":{"type":["string","null"],"enum":["whatsapp","messenger","instagram",null],"description":"Meta messaging channel of the inbox; null when the inbox is not a Meta channel."},"asset_id":{"type":["string","null"],"description":"Facebook Page (Messenger) or Instagram professional account the dataset is discovered from; null for WhatsApp, which uses `suggested_waba_id`."},"required_scope":{"type":["string","null"],"enum":["whatsapp_business_manage_events","page_events","instagram_manage_events",null],"description":"Permission the access token needs for the Dataset and Conversions API on this channel."},"optimization_supported":{"type":"boolean","description":"Whether Meta optimizes ads with these events on this channel. False for Instagram: the events are accepted but not used to optimize Instagram ads."}}}}},"example":{"inbox_id":12,"logical_inbox_id":12,"enabled":true,"meta_enabled":true,"meta_dataset_id":"1209384756473829","meta_waba_id":"104857392018475","meta_test_event_code":"TEST48213","meta_partner_agent":"ConversaLabs","meta_api_version":"v24.0","effective_meta_api_version":"v26.0","advanced_matching":false,"lead_on_capture":true,"contact_on_first_message":false,"purchase_on_won":true,"custom_on_lost":true,"purchase_on_payment":true,"lost_event_name":"Lead_Lost","stage_event_map":{"7":"QualifiedLead"},"has_meta_access_token":true,"meta_access_token_masked":"••••••••9f3a","meta_ready":true,"meta_credentialed":true,"persisted":true,"suggestions":{"channel_kind":"whatsapp_cloud","supports_meta":true,"suggested_waba_id":"104857392018475","has_channel_token":true,"manual_dataset":false,"messaging_channel":"whatsapp","asset_id":null,"required_scope":"whatsapp_business_manage_events","optimization_supported":true}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"inbox_id","in":"path","required":true,"schema":{"type":"string"}}]},"patch":{"tags":["Ads"],"operationId":"auto_patch_api_v1_accounts_account_id_ads_conversion_settings_inbox_id","summary":"Update the inbox's ad conversion-tracking settings","description":"Saves the Conversions API settings of the inbox. Fields left out keep their stored value. A blank `meta_access_token` keeps the stored token. The Marketing API version is set by the platform: the deprecated `meta_api_version`, when sent, must still be one of the supported versions (any other value is refused with 422) and is then ignored when sending.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The inbox's conversion-tracking settings, with secrets masked.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["inbox_id","logical_inbox_id","enabled","meta_enabled","meta_dataset_id","meta_waba_id","meta_test_event_code","meta_partner_agent","meta_api_version","effective_meta_api_version","advanced_matching","lead_on_capture","contact_on_first_message","purchase_on_won","custom_on_lost","purchase_on_payment","lost_event_name","stage_event_map","has_meta_access_token","meta_access_token_masked","meta_ready","meta_credentialed","persisted","suggestions"],"properties":{"inbox_id":{"type":"integer","description":"Inbox the settings belong to."},"logical_inbox_id":{"type":"integer","description":"Inbox id the dashboard shows for this number (the paired inbox on a hybrid number)."},"enabled":{"type":"boolean","description":"Master switch for sending conversions."},"meta_enabled":{"type":"boolean","description":"Whether the Meta Conversions API provider is on."},"meta_dataset_id":{"type":["string","null"],"description":"Meta dataset that receives the events."},"meta_waba_id":{"type":["string","null"],"description":"WhatsApp Business account used to discover the dataset."},"meta_test_event_code":{"type":["string","null"],"description":"Test event code sent with test events."},"meta_partner_agent":{"type":"string","description":"Partner agent string sent with every event."},"meta_api_version":{"type":"string","deprecated":true,"description":"Legacy per-inbox value, as stored (an older row may hold, for example, v25.0 or v24.0). The version is set by the platform for every inbox and this field is ignored when sending; read `effective_meta_api_version`."},"effective_meta_api_version":{"type":"string","enum":["v26.0","v25.0"],"description":"Marketing API version the Conversions API client calls — the installation-wide version, the same for every inbox."},"advanced_matching":{"type":"boolean","description":"Send hashed contact identifiers for advanced matching."},"lead_on_capture":{"type":"boolean","description":"Send a lead event when an ad lead is captured."},"contact_on_first_message":{"type":"boolean","description":"Send an event on the contact's first message."},"purchase_on_won":{"type":"boolean","description":"Send a purchase event when a deal is won."},"custom_on_lost":{"type":"boolean","description":"Send the lost event when a deal is lost."},"purchase_on_payment":{"type":"boolean","description":"Send a purchase event when a charge is paid."},"lost_event_name":{"type":"string","description":"Event name sent when a deal is lost."},"stage_event_map":{"type":"object","additionalProperties":{"type":"string"},"description":"Pipeline stage id mapped to the event name sent when a deal enters that stage."},"has_meta_access_token":{"type":"boolean","description":"Whether an access token is stored (never returned)."},"meta_access_token_masked":{"type":["string","null"],"description":"Masked tail of the stored access token."},"meta_ready":{"type":"boolean","description":"Enabled and able to send."},"meta_credentialed":{"type":"boolean","description":"Has a token plus a dataset, or an asset to discover one from (a WABA, a Facebook Page or an Instagram professional account)."},"persisted":{"type":"boolean","description":"Whether the settings have been saved at least once."},"suggestions":{"type":"object","additionalProperties":false,"required":["channel_kind","supports_meta","suggested_waba_id","has_channel_token","manual_dataset","messaging_channel","asset_id","required_scope","optimization_supported"],"description":"Values suggested from the inbox channel.","properties":{"channel_kind":{"type":"string","enum":["default","whatsapp_cloud","whatsapp_web","api","email","facebook_page","instagram","line","sms","telegram","tiktok","twilio_sms","twitter_profile","web_widget"],"description":"WhatsApp provider of the inbox, or its channel type for other channels."},"supports_meta":{"type":"boolean","description":"Whether the channel can send Meta conversions."},"suggested_waba_id":{"type":["string","null"],"description":"WABA id read from the channel."},"has_channel_token":{"type":"boolean","description":"Whether the channel has its own Graph token."},"manual_dataset":{"type":"boolean","description":"Whether the dataset id must be entered manually. False for WhatsApp Cloud, Facebook Page and Instagram inboxes, whose dataset is discovered from the WABA, the Page or the Instagram account."},"messaging_channel":{"type":["string","null"],"enum":["whatsapp","messenger","instagram",null],"description":"Meta messaging channel of the inbox; null when the inbox is not a Meta channel."},"asset_id":{"type":["string","null"],"description":"Facebook Page (Messenger) or Instagram professional account the dataset is discovered from; null for WhatsApp, which uses `suggested_waba_id`."},"required_scope":{"type":["string","null"],"enum":["whatsapp_business_manage_events","page_events","instagram_manage_events",null],"description":"Permission the access token needs for the Dataset and Conversions API on this channel."},"optimization_supported":{"type":"boolean","description":"Whether Meta optimizes ads with these events on this channel. False for Instagram: the events are accepted but not used to optimize Instagram ads."}}}}},"example":{"inbox_id":12,"logical_inbox_id":12,"enabled":true,"meta_enabled":true,"meta_dataset_id":"1209384756473829","meta_waba_id":"104857392018475","meta_test_event_code":"TEST48213","meta_partner_agent":"ConversaLabs","meta_api_version":"v24.0","effective_meta_api_version":"v26.0","advanced_matching":false,"lead_on_capture":true,"contact_on_first_message":false,"purchase_on_won":true,"custom_on_lost":true,"purchase_on_payment":true,"lost_event_name":"Lead_Lost","stage_event_map":{"7":"QualifiedLead"},"has_meta_access_token":true,"meta_access_token_masked":"••••••••9f3a","meta_ready":true,"meta_credentialed":true,"persisted":true,"suggestions":{"channel_kind":"whatsapp_cloud","supports_meta":true,"suggested_waba_id":"104857392018475","has_channel_token":true,"manual_dataset":false,"messaging_channel":"whatsapp","asset_id":null,"required_scope":"whatsapp_business_manage_events","optimization_supported":true}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"422":{"description":"The settings could not be saved, for example because `meta_api_version` is not one of the versions the Conversions API client calls.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["message","attributes"],"properties":{"message":{"type":"string","description":"Validation messages","comma-separated.":null},"attributes":{"type":"array","items":{"type":"string"},"description":"Attributes that failed validation."}}},"example":{"message":"API version v24.0 is not supported for the Conversions API. Use one of: v26.0, v25.0.","attributes":["base"]}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"inbox_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"enabled":{"type":"boolean","description":"Master switch for sending conversions."},"meta_enabled":{"type":"boolean","description":"Turn the Meta Conversions API provider on or off."},"meta_dataset_id":{"type":"string","description":"Meta dataset that receives the events."},"meta_waba_id":{"type":"string","description":"WhatsApp Business account used to discover the dataset."},"meta_test_event_code":{"type":"string","description":"Test event code sent with test events."},"meta_partner_agent":{"type":"string","description":"Partner agent string sent with every event."},"meta_api_version":{"type":"string","enum":["v26.0","v25.0"],"deprecated":true,"description":"The version is set by the platform; this field is ignored when sending. Any value outside the supported list is refused with 422."},"meta_access_token":{"type":"string","description":"Access token to store (write-only; blank keeps the stored one)."},"clear_meta_access_token":{"type":"boolean","description":"Remove the stored access token so the inbox channel's own token is used."},"use_channel_token":{"type":"boolean","description":"Bind the settings to the inbox channel's WABA and live token."},"advanced_matching":{"type":"boolean","description":"Send hashed contact identifiers for advanced matching."},"lead_on_capture":{"type":"boolean","description":"Send a lead event when an ad lead is captured."},"contact_on_first_message":{"type":"boolean","description":"Send an event on the contact's first message."},"purchase_on_won":{"type":"boolean","description":"Send a purchase event when a deal is won."},"custom_on_lost":{"type":"boolean","description":"Send the lost event when a deal is lost."},"purchase_on_payment":{"type":"boolean","description":"Send a purchase event when a charge is paid."},"lost_event_name":{"type":"string","description":"Event name sent when a deal is lost."},"stage_event_map":{"type":"object","additionalProperties":{"type":"string"},"description":"Pipeline stage id mapped to the event name sent when a deal enters that stage."},"provider_settings":{"type":"object","additionalProperties":true,"description":"Settings of the additional conversion providers, stored as sent."}}},"example":{"enabled":true,"meta_enabled":true,"meta_dataset_id":"1209384756473829","meta_waba_id":"104857392018475","meta_test_event_code":"TEST48213","meta_partner_agent":"ConversaLabs","meta_api_version":"v26.0","meta_access_token":"sample-token","clear_meta_access_token":false,"use_channel_token":false,"advanced_matching":false,"lead_on_capture":true,"contact_on_first_message":false,"purchase_on_won":true,"custom_on_lost":true,"purchase_on_payment":true,"lost_event_name":"Lead_Lost","stage_event_map":{"7":"QualifiedLead"},"provider_settings":{"google_ads":{"enabled":false}}}}}}},"put":{"tags":["Ads"],"operationId":"auto_put_api_v1_accounts_account_id_ads_conversion_settings_inbox_id","summary":"Update the inbox's ad conversion-tracking settings","description":"Saves the Conversions API settings of the inbox. Fields left out keep their stored value. A blank `meta_access_token` keeps the stored token. The Marketing API version is set by the platform: the deprecated `meta_api_version`, when sent, must still be one of the supported versions (any other value is refused with 422) and is then ignored when sending.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The inbox's conversion-tracking settings, with secrets masked.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["inbox_id","logical_inbox_id","enabled","meta_enabled","meta_dataset_id","meta_waba_id","meta_test_event_code","meta_partner_agent","meta_api_version","effective_meta_api_version","advanced_matching","lead_on_capture","contact_on_first_message","purchase_on_won","custom_on_lost","purchase_on_payment","lost_event_name","stage_event_map","has_meta_access_token","meta_access_token_masked","meta_ready","meta_credentialed","persisted","suggestions"],"properties":{"inbox_id":{"type":"integer","description":"Inbox the settings belong to."},"logical_inbox_id":{"type":"integer","description":"Inbox id the dashboard shows for this number (the paired inbox on a hybrid number)."},"enabled":{"type":"boolean","description":"Master switch for sending conversions."},"meta_enabled":{"type":"boolean","description":"Whether the Meta Conversions API provider is on."},"meta_dataset_id":{"type":["string","null"],"description":"Meta dataset that receives the events."},"meta_waba_id":{"type":["string","null"],"description":"WhatsApp Business account used to discover the dataset."},"meta_test_event_code":{"type":["string","null"],"description":"Test event code sent with test events."},"meta_partner_agent":{"type":"string","description":"Partner agent string sent with every event."},"meta_api_version":{"type":"string","deprecated":true,"description":"Legacy per-inbox value, as stored (an older row may hold, for example, v25.0 or v24.0). The version is set by the platform for every inbox and this field is ignored when sending; read `effective_meta_api_version`."},"effective_meta_api_version":{"type":"string","enum":["v26.0","v25.0"],"description":"Marketing API version the Conversions API client calls — the installation-wide version, the same for every inbox."},"advanced_matching":{"type":"boolean","description":"Send hashed contact identifiers for advanced matching."},"lead_on_capture":{"type":"boolean","description":"Send a lead event when an ad lead is captured."},"contact_on_first_message":{"type":"boolean","description":"Send an event on the contact's first message."},"purchase_on_won":{"type":"boolean","description":"Send a purchase event when a deal is won."},"custom_on_lost":{"type":"boolean","description":"Send the lost event when a deal is lost."},"purchase_on_payment":{"type":"boolean","description":"Send a purchase event when a charge is paid."},"lost_event_name":{"type":"string","description":"Event name sent when a deal is lost."},"stage_event_map":{"type":"object","additionalProperties":{"type":"string"},"description":"Pipeline stage id mapped to the event name sent when a deal enters that stage."},"has_meta_access_token":{"type":"boolean","description":"Whether an access token is stored (never returned)."},"meta_access_token_masked":{"type":["string","null"],"description":"Masked tail of the stored access token."},"meta_ready":{"type":"boolean","description":"Enabled and able to send."},"meta_credentialed":{"type":"boolean","description":"Has a token plus a dataset, or an asset to discover one from (a WABA, a Facebook Page or an Instagram professional account)."},"persisted":{"type":"boolean","description":"Whether the settings have been saved at least once."},"suggestions":{"type":"object","additionalProperties":false,"required":["channel_kind","supports_meta","suggested_waba_id","has_channel_token","manual_dataset","messaging_channel","asset_id","required_scope","optimization_supported"],"description":"Values suggested from the inbox channel.","properties":{"channel_kind":{"type":"string","enum":["default","whatsapp_cloud","whatsapp_web","api","email","facebook_page","instagram","line","sms","telegram","tiktok","twilio_sms","twitter_profile","web_widget"],"description":"WhatsApp provider of the inbox, or its channel type for other channels."},"supports_meta":{"type":"boolean","description":"Whether the channel can send Meta conversions."},"suggested_waba_id":{"type":["string","null"],"description":"WABA id read from the channel."},"has_channel_token":{"type":"boolean","description":"Whether the channel has its own Graph token."},"manual_dataset":{"type":"boolean","description":"Whether the dataset id must be entered manually. False for WhatsApp Cloud, Facebook Page and Instagram inboxes, whose dataset is discovered from the WABA, the Page or the Instagram account."},"messaging_channel":{"type":["string","null"],"enum":["whatsapp","messenger","instagram",null],"description":"Meta messaging channel of the inbox; null when the inbox is not a Meta channel."},"asset_id":{"type":["string","null"],"description":"Facebook Page (Messenger) or Instagram professional account the dataset is discovered from; null for WhatsApp, which uses `suggested_waba_id`."},"required_scope":{"type":["string","null"],"enum":["whatsapp_business_manage_events","page_events","instagram_manage_events",null],"description":"Permission the access token needs for the Dataset and Conversions API on this channel."},"optimization_supported":{"type":"boolean","description":"Whether Meta optimizes ads with these events on this channel. False for Instagram: the events are accepted but not used to optimize Instagram ads."}}}}},"example":{"inbox_id":12,"logical_inbox_id":12,"enabled":true,"meta_enabled":true,"meta_dataset_id":"1209384756473829","meta_waba_id":"104857392018475","meta_test_event_code":"TEST48213","meta_partner_agent":"ConversaLabs","meta_api_version":"v24.0","effective_meta_api_version":"v26.0","advanced_matching":false,"lead_on_capture":true,"contact_on_first_message":false,"purchase_on_won":true,"custom_on_lost":true,"purchase_on_payment":true,"lost_event_name":"Lead_Lost","stage_event_map":{"7":"QualifiedLead"},"has_meta_access_token":true,"meta_access_token_masked":"••••••••9f3a","meta_ready":true,"meta_credentialed":true,"persisted":true,"suggestions":{"channel_kind":"whatsapp_cloud","supports_meta":true,"suggested_waba_id":"104857392018475","has_channel_token":true,"manual_dataset":false,"messaging_channel":"whatsapp","asset_id":null,"required_scope":"whatsapp_business_manage_events","optimization_supported":true}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"422":{"description":"The settings could not be saved, for example because `meta_api_version` is not one of the versions the Conversions API client calls.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["message","attributes"],"properties":{"message":{"type":"string","description":"Validation messages","comma-separated.":null},"attributes":{"type":"array","items":{"type":"string"},"description":"Attributes that failed validation."}}},"example":{"message":"API version v24.0 is not supported for the Conversions API. Use one of: v26.0, v25.0.","attributes":["base"]}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"inbox_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"enabled":{"type":"boolean","description":"Master switch for sending conversions."},"meta_enabled":{"type":"boolean","description":"Turn the Meta Conversions API provider on or off."},"meta_dataset_id":{"type":"string","description":"Meta dataset that receives the events."},"meta_waba_id":{"type":"string","description":"WhatsApp Business account used to discover the dataset."},"meta_test_event_code":{"type":"string","description":"Test event code sent with test events."},"meta_partner_agent":{"type":"string","description":"Partner agent string sent with every event."},"meta_api_version":{"type":"string","enum":["v26.0","v25.0"],"deprecated":true,"description":"The version is set by the platform; this field is ignored when sending. Any value outside the supported list is refused with 422."},"meta_access_token":{"type":"string","description":"Access token to store (write-only; blank keeps the stored one)."},"clear_meta_access_token":{"type":"boolean","description":"Remove the stored access token so the inbox channel's own token is used."},"use_channel_token":{"type":"boolean","description":"Bind the settings to the inbox channel's WABA and live token."},"advanced_matching":{"type":"boolean","description":"Send hashed contact identifiers for advanced matching."},"lead_on_capture":{"type":"boolean","description":"Send a lead event when an ad lead is captured."},"contact_on_first_message":{"type":"boolean","description":"Send an event on the contact's first message."},"purchase_on_won":{"type":"boolean","description":"Send a purchase event when a deal is won."},"custom_on_lost":{"type":"boolean","description":"Send the lost event when a deal is lost."},"purchase_on_payment":{"type":"boolean","description":"Send a purchase event when a charge is paid."},"lost_event_name":{"type":"string","description":"Event name sent when a deal is lost."},"stage_event_map":{"type":"object","additionalProperties":{"type":"string"},"description":"Pipeline stage id mapped to the event name sent when a deal enters that stage."},"provider_settings":{"type":"object","additionalProperties":true,"description":"Settings of the additional conversion providers, stored as sent."}}},"example":{"enabled":true,"meta_enabled":true,"meta_dataset_id":"1209384756473829","meta_waba_id":"104857392018475","meta_test_event_code":"TEST48213","meta_partner_agent":"ConversaLabs","meta_api_version":"v26.0","meta_access_token":"sample-token","clear_meta_access_token":false,"use_channel_token":false,"advanced_matching":false,"lead_on_capture":true,"contact_on_first_message":false,"purchase_on_won":true,"custom_on_lost":true,"purchase_on_payment":true,"lost_event_name":"Lead_Lost","stage_event_map":{"7":"QualifiedLead"},"provider_settings":{"google_ads":{"enabled":false}}}}}}}},"/api/v1/accounts/{account_id}/ads/ad_accounts/{id}/refresh":{"post":{"tags":["Ads"],"operationId":"auto_post_api_v1_accounts_account_id_ads_ad_accounts_id_refresh","summary":"Re-validate the stored Meta token of an ad account","description":"Enqueues the token refresh job, which re-validates the stored system-user token against the advertising platform and reconciles a revocation. Returns `202 Accepted` with an EMPTY body so no external call happens inside the request — re-read the ad account afterwards to observe the refreshed credential state. The token itself is never rendered.","security":[{"userApiKey":[]}],"responses":{"202":{"description":"Refresh job enqueued. Empty body — the credential state updates asynchronously."},"401":{"description":"Unauthorized"},"404":{"description":"No such ad account in this account."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/ads/ad_accounts/{id}/readiness":{"get":{"tags":["Ads"],"operationId":"auto_get_api_v1_accounts_account_id_ads_ad_accounts_id_readiness","summary":"Readiness ad accounts","description":"Performs the readiness operation on the targeted ad account resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"checks":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"ok":{"type":"string"},"severity":{"type":"string","enum":["blocker","warning","info"],"description":"Severity of the readiness check."},"scope":{"type":"string"},"detail":{"type":"string"},"help_url":{"type":"string"}}}},"ready_for":{"type":"object","properties":{"ctwa":{"type":"string"},"lead_form":{"type":"string"}}}}}}},"example":{"payload":{"checks":[{"key":"sample key","ok":"sample ok","severity":"blocker","scope":"sample scope","detail":"sample detail","help_url":"https://example.com/resource"}],"ready_for":{"ctwa":"sample ctwa","lead_form":"sample lead form"}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/ads/ad_accounts/{id}/pages":{"get":{"tags":["Ads"],"operationId":"auto_get_api_v1_accounts_account_id_ads_ad_accounts_id_pages","summary":"List the Pages reachable with the connected account's stored token","description":"GET /me/accounts with the stored (encrypted) Marketing API token — used to re-bind the Page/Instagram identity after connect. Page access tokens are fetched on demand only and never rendered.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The Pages with their Instagram identity.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"118631077994251"},"name":{"type":"string","example":"Setup Automatizado"},"instagram_user_id":{"type":["string","null"],"example":"17841401185010968"},"instagram_username":{"type":["string","null"],"example":"setpar"}}}}}},"example":{"payload":[{"id":"118631077994251","name":"Setup Automatizado","instagram_user_id":null,"instagram_username":null}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"422":{"description":"The connection has no usable token (not_credentialed) or Meta refused the read.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"not_credentialed"}}},"example":{"error":"not_credentialed"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/ads/ad_accounts/discover":{"post":{"tags":["Ads"],"operationId":"auto_post_api_v1_accounts_account_id_ads_ad_accounts_discover","summary":"Discover the Meta ad accounts and Pages reachable with a token","description":"Reuses the WhatsApp Cloud inbox's own Meta token (zero-config) or a pasted Business Manager system-user token to list the ad accounts (GET /me/adaccounts) and the Pages with their Instagram identity (GET /me/accounts) for the connect wizard pickers. On a Graph failure the real reason rides in `error` (invalid_token / missing_permission / gateway_unreachable / gateway_error) instead of a silent empty list. No token or Page access token is ever rendered.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The discovery result for the connect wizard.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"token_available":{"type":"boolean","example":true},"business_id":{"type":["string","null"],"example":"659808524521631"},"whatsapp_number_id":{"type":["string","null"],"example":"890499750814967"},"page_id":{"type":["string","null"],"example":"118631077994251"},"error":{"type":["object","null"],"description":"Present when the Graph read failed — the wizard shows the real reason.","properties":{"kind":{"type":"string","enum":["invalid_token","missing_permission","gateway_unreachable","gateway_error"],"example":"invalid_token"},"meta_code":{"type":["integer","null"],"example":190},"http_status":{"type":["integer","null"],"example":400}}},"ad_accounts":{"type":"array","items":{"type":"object","properties":{"act_id":{"type":"string","example":"act_1421045155905475"},"account_id":{"type":"string","example":"1421045155905475"},"name":{"type":"string","example":"TESTE (Read-Only)"},"currency":{"type":"string","example":"BRL"},"status":{"type":"integer","description":"Meta account_status (1 = ACTIVE).","example":1}}}},"pages":{"type":"array","description":"The Pages the same token manages (Page access tokens are stripped).","items":{"type":"object","properties":{"id":{"type":"string","example":"118631077994251"},"name":{"type":"string","example":"Setup Automatizado"},"instagram_user_id":{"type":["string","null"],"example":"17841401185010968"},"instagram_username":{"type":["string","null"],"example":"setpar"}}}}}}}},"example":{"payload":{"token_available":true,"business_id":"659808524521631","whatsapp_number_id":"890499750814967","page_id":"118631077994251","error":null,"ad_accounts":[{"act_id":"act_1421045155905475","account_id":"1421045155905475","name":"TESTE (Read-Only)","currency":"BRL","status":1}],"pages":[{"id":"118631077994251","name":"Setup Automatizado","instagram_user_id":null,"instagram_username":null}]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["inbox_id"],"properties":{"inbox_id":{"type":"integer","example":137},"access_token":{"type":"string","description":"Optional system-user token (manual path). Never echoed back.","example":"sample-access-token"}}},"example":{"inbox_id":137,"access_token":"sample-access-token"}}}}}},"/api/v1/accounts/{account_id}/ads/ad_accounts":{"get":{"tags":["Ads"],"operationId":"auto_get_api_v1_accounts_account_id_ads_ad_accounts","summary":"List ad accounts","description":"Returns the list of ad accounts visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"inbox_id":{"type":"integer"},"logical_inbox_id":{"type":["integer","null"]},"provider":{"type":"string","enum":["meta","tiktok","google","linkedin"]},"act_id":{"type":"integer"},"name":{"type":"string"},"page_id":{"type":"integer"},"page_name":{"type":"string"},"instagram_user_id":{"type":"integer"},"instagram_username":{"type":"string"},"whatsapp_number_id":{"type":"integer"},"business_id":{"type":"integer"},"status":{"type":"string","enum":["pending","connected","error","revoked"]},"token_type":{"type":"string","enum":["system_user","user"]},"scopes":{"type":"string"},"poll_interval_minutes":{"type":"integer"},"last_synced_at":{"type":"string","format":"date-time"},"last_error":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"access_token_present":{"type":"boolean"},"access_token_masked":{"type":"string"}}}},"meta":{"type":"object","properties":{"count":{"type":"integer"}}}}},"example":{"payload":[{"id":1,"account_id":1,"inbox_id":1,"logical_inbox_id":1,"provider":"meta","act_id":1,"name":"Sample Name","page_id":1,"page_name":"sample page name","instagram_user_id":1,"instagram_username":"sample instagram username","whatsapp_number_id":1,"business_id":1,"status":"pending","token_type":"system_user","scopes":"sample scopes","poll_interval_minutes":60,"last_synced_at":"2026-01-15T10:30:00.000Z","last_error":"sample last error","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","access_token_present":true,"access_token_masked":"sample access token masked"}],"meta":{"count":5}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."}]},"post":{"tags":["Ads"],"operationId":"auto_post_api_v1_accounts_account_id_ads_ad_accounts","summary":"Create ad accounts","description":"Creates a new ad account from the request payload. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"201":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"inbox_id":{"type":"integer"},"logical_inbox_id":{"type":["integer","null"]},"provider":{"type":"string","enum":["meta","tiktok","google","linkedin"]},"act_id":{"type":"integer"},"name":{"type":"string"},"page_id":{"type":"integer"},"page_name":{"type":"string"},"instagram_user_id":{"type":"integer"},"instagram_username":{"type":"string"},"whatsapp_number_id":{"type":"integer"},"business_id":{"type":"integer"},"status":{"type":"string","enum":["pending","connected","error","revoked"]},"token_type":{"type":"string","enum":["system_user","user"]},"scopes":{"type":"string"},"poll_interval_minutes":{"type":"integer"},"last_synced_at":{"type":"string","format":"date-time"},"last_error":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"access_token_present":{"type":"boolean"},"access_token_masked":{"type":"string"}}},"example":{"id":1,"account_id":1,"inbox_id":1,"logical_inbox_id":1,"provider":"meta","act_id":1,"name":"Sample Name","page_id":1,"page_name":"sample page name","instagram_user_id":1,"instagram_username":"sample instagram username","whatsapp_number_id":1,"business_id":1,"status":"pending","token_type":"system_user","scopes":"sample scopes","poll_interval_minutes":60,"last_synced_at":"2026-01-15T10:30:00.000Z","last_error":"sample last error","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","access_token_present":true,"access_token_masked":"sample access token masked"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ad_account":{"type":"object","properties":{"inbox_id":{"type":"integer"},"act_id":{"type":"integer"},"name":{"type":"string"},"code":{"type":"string","enum":["","dependency_unavailable","invalid_reference","not_authorized","binding_conflict","execution_inactive","non_local_exit","projection_unsealed","projection_conflict"]},"access_token":{"type":"string"},"redirect_uri":{"type":"string"},"page_id":{"type":"integer"},"page_name":{"type":"string"},"instagram_user_id":{"type":"integer"},"instagram_username":{"type":"string"},"whatsapp_number_id":{"type":"integer"},"business_id":{"type":"integer"},"scopes":{"type":"array","items":{"type":"string"}}},"required":["act_id"]}},"required":["ad_account"]},"example":{"ad_account":{"inbox_id":1,"act_id":1,"name":"Sample Name","code":"","access_token":"sample-token","redirect_uri":"sample redirect uri","page_id":1,"page_name":"sample page name","instagram_user_id":1,"instagram_username":"sample instagram username","whatsapp_number_id":1,"business_id":1,"scopes":["sample scope"]}}}}}}},"/api/v1/accounts/{account_id}/ads/ad_accounts/{id}":{"get":{"tags":["Ads"],"operationId":"auto_get_api_v1_accounts_account_id_ads_ad_accounts_id","summary":"Get ad accounts","description":"Returns the ad account identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"inbox_id":{"type":"integer"},"logical_inbox_id":{"type":["integer","null"]},"provider":{"type":"string","enum":["meta","tiktok","google","linkedin"]},"act_id":{"type":"integer"},"name":{"type":"string"},"page_id":{"type":"integer"},"page_name":{"type":"string"},"instagram_user_id":{"type":"integer"},"instagram_username":{"type":"string"},"whatsapp_number_id":{"type":"integer"},"business_id":{"type":"integer"},"status":{"type":"string","enum":["pending","connected","error","revoked"]},"token_type":{"type":"string","enum":["system_user","user"]},"scopes":{"type":"string"},"poll_interval_minutes":{"type":"integer"},"last_synced_at":{"type":"string","format":"date-time"},"last_error":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"access_token_present":{"type":"boolean"},"access_token_masked":{"type":"string"}}},"example":{"id":1,"account_id":1,"inbox_id":1,"logical_inbox_id":1,"provider":"meta","act_id":1,"name":"Sample Name","page_id":1,"page_name":"sample page name","instagram_user_id":1,"instagram_username":"sample instagram username","whatsapp_number_id":1,"business_id":1,"status":"pending","token_type":"system_user","scopes":"sample scopes","poll_interval_minutes":60,"last_synced_at":"2026-01-15T10:30:00.000Z","last_error":"sample last error","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","access_token_present":true,"access_token_masked":"sample access token masked"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]},"patch":{"tags":["Ads"],"operationId":"auto_patch_api_v1_accounts_account_id_ads_ad_accounts_id","summary":"Update ad accounts","description":"Updates the ad account identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"inbox_id":{"type":"integer"},"logical_inbox_id":{"type":["integer","null"]},"provider":{"type":"string","enum":["meta","tiktok","google","linkedin"]},"act_id":{"type":"integer"},"name":{"type":"string"},"page_id":{"type":"integer"},"page_name":{"type":"string"},"instagram_user_id":{"type":"integer"},"instagram_username":{"type":"string"},"whatsapp_number_id":{"type":"integer"},"business_id":{"type":"integer"},"status":{"type":"string","enum":["pending","connected","error","revoked"]},"token_type":{"type":"string","enum":["system_user","user"]},"scopes":{"type":"string"},"poll_interval_minutes":{"type":"integer"},"last_synced_at":{"type":"string","format":"date-time"},"last_error":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"access_token_present":{"type":"boolean"},"access_token_masked":{"type":"string"}}},"example":{"id":1,"account_id":1,"inbox_id":1,"logical_inbox_id":1,"provider":"meta","act_id":1,"name":"Sample Name","page_id":1,"page_name":"sample page name","instagram_user_id":1,"instagram_username":"sample instagram username","whatsapp_number_id":1,"business_id":1,"status":"pending","token_type":"system_user","scopes":"sample scopes","poll_interval_minutes":60,"last_synced_at":"2026-01-15T10:30:00.000Z","last_error":"sample last error","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","access_token_present":true,"access_token_masked":"sample access token masked"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ad_account":{"type":"object","properties":{"page_id":{"type":"integer"},"page_name":{"type":"string"},"instagram_user_id":{"type":"integer"},"instagram_username":{"type":"string"},"whatsapp_number_id":{"type":"integer"},"poll_interval_minutes":{"type":"integer"}}}},"required":["ad_account"]},"example":{"ad_account":{"page_id":1,"page_name":"sample page name","instagram_user_id":1,"instagram_username":"sample instagram username","whatsapp_number_id":1,"poll_interval_minutes":60}}}}}},"put":{"tags":["Ads"],"operationId":"auto_put_api_v1_accounts_account_id_ads_ad_accounts_id","summary":"Update ad accounts","description":"Updates the ad account identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"inbox_id":{"type":"integer"},"logical_inbox_id":{"type":["integer","null"]},"provider":{"type":"string","enum":["meta","tiktok","google","linkedin"]},"act_id":{"type":"integer"},"name":{"type":"string"},"page_id":{"type":"integer"},"page_name":{"type":"string"},"instagram_user_id":{"type":"integer"},"instagram_username":{"type":"string"},"whatsapp_number_id":{"type":"integer"},"business_id":{"type":"integer"},"status":{"type":"string","enum":["pending","connected","error","revoked"]},"token_type":{"type":"string","enum":["system_user","user"]},"scopes":{"type":"string"},"poll_interval_minutes":{"type":"integer"},"last_synced_at":{"type":"string","format":"date-time"},"last_error":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"access_token_present":{"type":"boolean"},"access_token_masked":{"type":"string"}}},"example":{"id":1,"account_id":1,"inbox_id":1,"logical_inbox_id":1,"provider":"meta","act_id":1,"name":"Sample Name","page_id":1,"page_name":"sample page name","instagram_user_id":1,"instagram_username":"sample instagram username","whatsapp_number_id":1,"business_id":1,"status":"pending","token_type":"system_user","scopes":"sample scopes","poll_interval_minutes":60,"last_synced_at":"2026-01-15T10:30:00.000Z","last_error":"sample last error","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","access_token_present":true,"access_token_masked":"sample access token masked"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ad_account":{"type":"object","properties":{"page_id":{"type":"integer"},"page_name":{"type":"string"},"instagram_user_id":{"type":"integer"},"instagram_username":{"type":"string"},"whatsapp_number_id":{"type":"integer"},"poll_interval_minutes":{"type":"integer"}}}},"required":["ad_account"]},"example":{"ad_account":{"page_id":1,"page_name":"sample page name","instagram_user_id":1,"instagram_username":"sample instagram username","whatsapp_number_id":1,"poll_interval_minutes":60}}}}}},"delete":{"tags":["Ads"],"operationId":"auto_delete_api_v1_accounts_account_id_ads_ad_accounts_id","summary":"Delete ad accounts","description":"Deletes the ad account identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Success (no content)"},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/ads/campaigns/{id}/pause":{"post":{"tags":["Ads"],"operationId":"auto_post_api_v1_accounts_account_id_ads_campaigns_id_pause","summary":"Publish a pause for an advertising campaign","description":"Enqueues the publish job that flips the campaign to paused on the advertising platform. Going live or off-air is deliberately an out-of-request action, so the response is `202 Accepted` with an EMPTY body; the mirrored `status` only changes after the job runs and the account re-syncs.","security":[{"userApiKey":[]}],"responses":{"202":{"description":"Pause publish enqueued. Empty body — the mirrored status changes after the sync."},"401":{"description":"Unauthorized"},"404":{"description":"No such campaign in this account."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/ads/campaigns/{id}/activate":{"post":{"tags":["Ads"],"operationId":"auto_post_api_v1_accounts_account_id_ads_campaigns_id_activate","summary":"Publish an activation for an advertising campaign","description":"Enqueues the publish job that flips the campaign to active on the advertising platform. Going live is deliberately an out-of-request action, so the response is `202 Accepted` with an EMPTY body; the mirrored `status` only changes after the job runs and the account re-syncs.","security":[{"userApiKey":[]}],"responses":{"202":{"description":"Activation publish enqueued. Empty body — the mirrored status changes after the sync."},"401":{"description":"Unauthorized"},"404":{"description":"No such campaign in this account."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/ads/campaigns":{"get":{"tags":["Ads"],"operationId":"auto_get_api_v1_accounts_account_id_ads_campaigns","summary":"List campaigns","description":"Returns the list of campaigns visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"ad_account_id":{"type":"integer"},"remote_id":{"type":"integer"},"name":{"type":"string"},"objective":{"type":"string"},"status":{"type":"string","enum":["active","paused","deleted","archived","draft"]},"effective_status":{"type":"string"},"daily_budget":{"type":"string"},"lifetime_budget":{"type":"string"},"budget_remaining":{"type":"string"},"special_ad_categories":{"type":"string"},"last_synced_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}},"meta":{"type":"object","properties":{"count":{"type":"integer"}}}}},"example":{"payload":[{"id":1,"account_id":1,"ad_account_id":1,"remote_id":1,"name":"Sample Name","objective":"sample objective","status":"active","effective_status":"sample effective status","daily_budget":"sample daily budget","lifetime_budget":"sample lifetime budget","budget_remaining":"sample budget remaining","special_ad_categories":"sample special ad categories","last_synced_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}],"meta":{"count":5}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"ad_account_id","in":"query","required":false,"description":"Restrict to campaigns of one connected ad account.","schema":{"type":"integer"},"example":2},{"name":"status","in":"query","required":false,"description":"Restrict to campaigns in one state.","schema":{"type":"string","enum":["active","paused","deleted","archived","draft"]},"example":"active"}]},"post":{"tags":["Ads"],"operationId":"auto_post_api_v1_accounts_account_id_ads_campaigns","summary":"Create campaigns","description":"Creates a new campaign from the request payload. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"201":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"ad_account_id":{"type":"integer"},"remote_id":{"type":"integer"},"name":{"type":"string"},"objective":{"type":"string"},"status":{"type":"string","enum":["active","paused","deleted","archived","draft"]},"effective_status":{"type":"string"},"daily_budget":{"type":"string"},"lifetime_budget":{"type":"string"},"budget_remaining":{"type":"string"},"special_ad_categories":{"type":"string"},"last_synced_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"raw":{"type":"string"},"ad_account":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"act_id":{"type":"integer"},"page_id":{"type":"integer"},"page_name":{"type":"string"},"instagram_username":{"type":"string"},"whatsapp_number":{"type":["string","null"]}}},"ad_sets":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"ad_account_id":{"type":"integer"},"campaign_id":{"type":"integer"},"remote_id":{"type":"integer"},"name":{"type":"string"},"status":{"type":"string","enum":["active","paused","deleted","archived","draft"]},"effective_status":{"type":"string"},"optimization_goal":{"type":"string"},"destination_type":{"type":"string","enum":["WHATSAPP","MESSENGER","INSTAGRAM_DIRECT","MESSAGING_MESSENGER_WHATSAPP","MESSAGING_INSTAGRAM_DIRECT_WHATSAPP","MESSAGING_INSTAGRAM_DIRECT_MESSENGER","MESSAGING_INSTAGRAM_DIRECT_MESSENGER_WHATSAPP","ON_AD"],"description":"Meta ad-set destination — one messaging app (WHATSAPP / MESSENGER / INSTAGRAM_DIRECT), a combined MESSAGING_* value (automatic destination across 2+ apps), or ON_AD for lead-form campaigns."},"promoted_object":{"type":"string"},"daily_budget":{"type":"string"},"lifetime_budget":{"type":"string"},"bid_amount":{"type":"number"},"targeting":{"type":"string"},"last_synced_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"ads":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"ad_account_id":{"type":"integer"},"ad_set_id":{"type":"integer"},"creative_id":{"type":"integer"},"remote_id":{"type":"integer"},"name":{"type":"string"},"status":{"type":"string","enum":["active","paused","deleted","archived","draft"]},"effective_status":{"type":"string"},"last_synced_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"creative":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"ad_account_id":{"type":"integer"},"remote_id":{"type":"integer"},"name":{"type":"string"},"call_to_action_type":{"type":"string","enum":["WHATSAPP_MESSAGE"],"description":"Meta creative call-to-action type."},"message_text":{"type":"string"},"object_story_spec":{"type":"string"},"image_hash":{"type":"string"},"image_url":{"type":"string"},"page_id":{"type":"integer"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}}}}}}}},"example":{"id":1,"account_id":1,"ad_account_id":1,"remote_id":1,"name":"Sample Name","objective":"sample objective","status":"active","effective_status":"sample effective status","daily_budget":"sample daily budget","lifetime_budget":"sample lifetime budget","budget_remaining":"sample budget remaining","special_ad_categories":"sample special ad categories","last_synced_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","raw":"sample raw","ad_account":{"id":1,"name":"Sample Name","act_id":1,"page_id":1,"page_name":"sample page name","instagram_username":"sample instagram username","whatsapp_number":"sample whatsapp number"},"ad_sets":[{"id":1,"account_id":1,"ad_account_id":1,"campaign_id":1,"remote_id":1,"name":"Sample Name","status":"active","effective_status":"sample effective status","optimization_goal":"sample optimization goal","destination_type":"WHATSAPP","promoted_object":"sample promoted object","daily_budget":"sample daily budget","lifetime_budget":"sample lifetime budget","bid_amount":149.9,"targeting":"sample targeting","last_synced_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","ads":[{"id":1,"account_id":1,"ad_account_id":1,"ad_set_id":1,"creative_id":1,"remote_id":1,"name":"Sample Name","status":"active","effective_status":"sample effective status","last_synced_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","creative":{"id":1,"account_id":1,"ad_account_id":1,"remote_id":1,"name":"Sample Name","call_to_action_type":"WHATSAPP_MESSAGE","message_text":"sample message text","object_story_spec":"sample object story spec","image_hash":"sample image hash","image_url":"https://example.com/resource","page_id":1,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}]}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"422":{"description":"The campaign was not created. Configuration problems are refused before any call to Meta — for example a placement the current Marketing API retired (Instagram Explore, Messenger Stories) that would leave a chosen platform with no position. Errors Meta returns while creating the chain are reported the same way.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","description":"Reason in the account's language."}}},"example":{"error":"The chosen placements (Instagram Explore) no longer exist in the current Meta Marketing API. Choose other placements for that platform, or use automatic placements."}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"campaign":{"type":"object","properties":{"ad_account_id":{"type":"integer"},"kind":{"type":"string","enum":["ctwa","lead_form"],"description":"Ad objective — Click-to-WhatsApp or Lead Form."},"name":{"type":"string"},"objective":{"type":"string"},"daily_budget":{"type":"string"},"lifetime_budget":{"type":"string"},"start_time":{"type":"string","format":"date-time"},"end_time":{"type":"string","format":"date-time"},"optimization_goal":{"type":"string"},"message_text":{"type":"string"},"body":{"type":"string"},"headline":{"type":"string"},"description":{"type":"string"},"image_hash":{"type":"string"},"video_id":{"type":"integer"},"video_thumbnail_url":{"type":"string"},"lead_form_id":{"type":"integer"},"advantage_audience":{"type":"string"},"greeting_text":{"type":"string"},"prefill_text":{"type":"string"},"wa_cta_type":{"type":"string","enum":["call","catalog","url"],"description":"Optional WhatsApp welcome-screen CTA type for a CTWA creative — call, catalog or url (url requires wa_cta_url). Absent/blank sends no welcome CTA."},"wa_cta_url":{"type":"string"},"wa_flow_id":{"type":"integer"},"wa_flow_cta":{"type":"string"},"bid_amount":{"type":"number"},"special_ad_categories":{"type":"array","items":{"type":"string"}},"destinations":{"type":"array","description":"Messaging destinations the campaign opens — where the conversation lands when someone taps the ad. Two or more selections become Meta's automatic destination (each person is routed to the app where they are most likely to reply). Defaults to whatsapp when omitted.","items":{"type":"string","enum":["whatsapp","messenger","instagram"]}},"targeting":{"type":"object","additionalProperties":true,"description":"Free-form object."},"placements":{"type":"object","additionalProperties":true,"description":"Free-form object."},"ice_breakers":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Free-form object."}}}}},"required":["campaign"]},"example":{"campaign":{"ad_account_id":1,"kind":"ctwa","name":"Sample Name","objective":"sample objective","daily_budget":"sample daily budget","lifetime_budget":"sample lifetime budget","start_time":"2026-01-15T10:30:00.000Z","end_time":"2026-01-15T10:30:00.000Z","optimization_goal":"sample optimization goal","message_text":"sample message text","body":"Sample body text.","headline":"sample headline","description":"A short description.","image_hash":"sample image hash","video_id":1,"video_thumbnail_url":"https://example.com/resource","lead_form_id":1,"advantage_audience":"sample advantage audience","greeting_text":"sample greeting text","prefill_text":"sample prefill text","wa_cta_type":"call","wa_cta_url":"https://example.com/resource","wa_flow_id":1,"wa_flow_cta":"sample wa flow cta","bid_amount":149.9,"special_ad_categories":["sample special ad categorie"],"destinations":["whatsapp"],"targeting":{},"placements":{},"ice_breakers":[{}]}}}}}}},"/api/v1/accounts/{account_id}/ads/campaigns/{id}":{"get":{"tags":["Ads"],"operationId":"auto_get_api_v1_accounts_account_id_ads_campaigns_id","summary":"Get campaigns","description":"Returns the campaign identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"ad_account_id":{"type":"integer"},"remote_id":{"type":"integer"},"name":{"type":"string"},"objective":{"type":"string"},"status":{"type":"string","enum":["active","paused","deleted","archived","draft"]},"effective_status":{"type":"string"},"daily_budget":{"type":"string"},"lifetime_budget":{"type":"string"},"budget_remaining":{"type":"string"},"special_ad_categories":{"type":"string"},"last_synced_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"raw":{"type":"string"},"ad_account":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"act_id":{"type":"integer"},"page_id":{"type":"integer"},"page_name":{"type":"string"},"instagram_username":{"type":"string"},"whatsapp_number":{"type":["string","null"]}}},"ad_sets":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"ad_account_id":{"type":"integer"},"campaign_id":{"type":"integer"},"remote_id":{"type":"integer"},"name":{"type":"string"},"status":{"type":"string","enum":["active","paused","deleted","archived","draft"]},"effective_status":{"type":"string"},"optimization_goal":{"type":"string"},"destination_type":{"type":"string","enum":["WHATSAPP","MESSENGER","INSTAGRAM_DIRECT","MESSAGING_MESSENGER_WHATSAPP","MESSAGING_INSTAGRAM_DIRECT_WHATSAPP","MESSAGING_INSTAGRAM_DIRECT_MESSENGER","MESSAGING_INSTAGRAM_DIRECT_MESSENGER_WHATSAPP","ON_AD"],"description":"Meta ad-set destination — one messaging app (WHATSAPP / MESSENGER / INSTAGRAM_DIRECT), a combined MESSAGING_* value (automatic destination across 2+ apps), or ON_AD for lead-form campaigns."},"promoted_object":{"type":"string"},"daily_budget":{"type":"string"},"lifetime_budget":{"type":"string"},"bid_amount":{"type":"number"},"targeting":{"type":"string"},"last_synced_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"ads":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"ad_account_id":{"type":"integer"},"ad_set_id":{"type":"integer"},"creative_id":{"type":"integer"},"remote_id":{"type":"integer"},"name":{"type":"string"},"status":{"type":"string","enum":["active","paused","deleted","archived","draft"]},"effective_status":{"type":"string"},"last_synced_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"creative":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"ad_account_id":{"type":"integer"},"remote_id":{"type":"integer"},"name":{"type":"string"},"call_to_action_type":{"type":"string","enum":["WHATSAPP_MESSAGE"],"description":"Meta creative call-to-action type."},"message_text":{"type":"string"},"object_story_spec":{"type":"string"},"image_hash":{"type":"string"},"image_url":{"type":"string"},"page_id":{"type":"integer"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}}}}}}}},"example":{"id":1,"account_id":1,"ad_account_id":1,"remote_id":1,"name":"Sample Name","objective":"sample objective","status":"active","effective_status":"sample effective status","daily_budget":"sample daily budget","lifetime_budget":"sample lifetime budget","budget_remaining":"sample budget remaining","special_ad_categories":"sample special ad categories","last_synced_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","raw":"sample raw","ad_account":{"id":1,"name":"Sample Name","act_id":1,"page_id":1,"page_name":"sample page name","instagram_username":"sample instagram username","whatsapp_number":"sample whatsapp number"},"ad_sets":[{"id":1,"account_id":1,"ad_account_id":1,"campaign_id":1,"remote_id":1,"name":"Sample Name","status":"active","effective_status":"sample effective status","optimization_goal":"sample optimization goal","destination_type":"WHATSAPP","promoted_object":"sample promoted object","daily_budget":"sample daily budget","lifetime_budget":"sample lifetime budget","bid_amount":149.9,"targeting":"sample targeting","last_synced_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","ads":[{"id":1,"account_id":1,"ad_account_id":1,"ad_set_id":1,"creative_id":1,"remote_id":1,"name":"Sample Name","status":"active","effective_status":"sample effective status","last_synced_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","creative":{"id":1,"account_id":1,"ad_account_id":1,"remote_id":1,"name":"Sample Name","call_to_action_type":"WHATSAPP_MESSAGE","message_text":"sample message text","object_story_spec":"sample object story spec","image_hash":"sample image hash","image_url":"https://example.com/resource","page_id":1,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}]}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]},"patch":{"tags":["Ads"],"operationId":"auto_patch_api_v1_accounts_account_id_ads_campaigns_id","summary":"Change the budget of an advertising campaign","description":"Applies the submitted daily or lifetime budget on the advertising platform. Chains authored by the wizard hold the budget on the ad set rather than on the campaign, so the change targets the campaign's first ad set unless the campaign carries a budget of its own. The call succeeds with `202 Accepted` and an EMPTY body — the mirrored budget columns are refreshed by the next sync, so re-read the campaign instead of parsing this response.","security":[{"userApiKey":[]}],"responses":{"202":{"description":"Budget applied upstream. Empty body — mirrored values refresh on the next sync."},"401":{"description":"Unauthorized"},"404":{"description":"No such campaign in this account."},"422":{"description":"The submitted budget was rejected.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Why the budget could not be applied."}}},"example":{"error":"at least one of daily_budget or lifetime_budget is required"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"campaign":{"type":"object","properties":{"daily_budget":{"type":"string"},"lifetime_budget":{"type":"string"}}}},"required":["campaign"]},"example":{"campaign":{"daily_budget":"sample daily budget","lifetime_budget":"sample lifetime budget"}}}}}},"put":{"tags":["Ads"],"operationId":"auto_put_api_v1_accounts_account_id_ads_campaigns_id","summary":"Change the budget of an advertising campaign","description":"Applies the submitted daily or lifetime budget on the advertising platform. Chains authored by the wizard hold the budget on the ad set rather than on the campaign, so the change targets the campaign's first ad set unless the campaign carries a budget of its own. The call succeeds with `202 Accepted` and an EMPTY body — the mirrored budget columns are refreshed by the next sync, so re-read the campaign instead of parsing this response.","security":[{"userApiKey":[]}],"responses":{"202":{"description":"Budget applied upstream. Empty body — mirrored values refresh on the next sync."},"401":{"description":"Unauthorized"},"404":{"description":"No such campaign in this account."},"422":{"description":"The submitted budget was rejected.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Why the budget could not be applied."}}},"example":{"error":"at least one of daily_budget or lifetime_budget is required"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"campaign":{"type":"object","properties":{"daily_budget":{"type":"string"},"lifetime_budget":{"type":"string"}}}},"required":["campaign"]},"example":{"campaign":{"daily_budget":"sample daily budget","lifetime_budget":"sample lifetime budget"}}}}}},"delete":{"tags":["Ads"],"operationId":"auto_delete_api_v1_accounts_account_id_ads_campaigns_id","summary":"Delete campaigns","description":"Deletes the campaign identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Success (no content)"},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/ads/ad_sets":{"get":{"tags":["Ads"],"operationId":"auto_get_api_v1_accounts_account_id_ads_ad_sets","summary":"List ad sets","description":"Returns the list of ad sets visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"ad_account_id":{"type":"integer"},"campaign_id":{"type":"integer"},"remote_id":{"type":"integer"},"name":{"type":"string"},"status":{"type":"string","enum":["active","paused","deleted","archived","draft"]},"effective_status":{"type":"string"},"optimization_goal":{"type":"string"},"destination_type":{"type":"string","enum":["WHATSAPP","MESSENGER","INSTAGRAM_DIRECT","MESSAGING_MESSENGER_WHATSAPP","MESSAGING_INSTAGRAM_DIRECT_WHATSAPP","MESSAGING_INSTAGRAM_DIRECT_MESSENGER","MESSAGING_INSTAGRAM_DIRECT_MESSENGER_WHATSAPP","ON_AD"],"description":"Meta ad-set destination — one messaging app (WHATSAPP / MESSENGER / INSTAGRAM_DIRECT), a combined MESSAGING_* value (automatic destination across 2+ apps), or ON_AD for lead-form campaigns."},"promoted_object":{"type":"string"},"daily_budget":{"type":"string"},"lifetime_budget":{"type":"string"},"bid_amount":{"type":"number"},"targeting":{"type":"string"},"last_synced_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}},"meta":{"type":"object","properties":{"count":{"type":"integer"}}}}},"example":{"payload":[{"id":1,"account_id":1,"ad_account_id":1,"campaign_id":1,"remote_id":1,"name":"Sample Name","status":"active","effective_status":"sample effective status","optimization_goal":"sample optimization goal","destination_type":"WHATSAPP","promoted_object":"sample promoted object","daily_budget":"sample daily budget","lifetime_budget":"sample lifetime budget","bid_amount":149.9,"targeting":"sample targeting","last_synced_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}],"meta":{"count":5}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"campaign_id","in":"query","required":false,"description":"Restrict to ad sets of one campaign.","schema":{"type":"integer"},"example":9}]}},"/api/v1/accounts/{account_id}/ads/ad_sets/{id}":{"get":{"tags":["Ads"],"operationId":"auto_get_api_v1_accounts_account_id_ads_ad_sets_id","summary":"Get ad sets","description":"Returns the ad set identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"ad_account_id":{"type":"integer"},"campaign_id":{"type":"integer"},"remote_id":{"type":"integer"},"name":{"type":"string"},"status":{"type":"string","enum":["active","paused","deleted","archived","draft"]},"effective_status":{"type":"string"},"optimization_goal":{"type":"string"},"destination_type":{"type":"string","enum":["WHATSAPP","MESSENGER","INSTAGRAM_DIRECT","MESSAGING_MESSENGER_WHATSAPP","MESSAGING_INSTAGRAM_DIRECT_WHATSAPP","MESSAGING_INSTAGRAM_DIRECT_MESSENGER","MESSAGING_INSTAGRAM_DIRECT_MESSENGER_WHATSAPP","ON_AD"],"description":"Meta ad-set destination — one messaging app (WHATSAPP / MESSENGER / INSTAGRAM_DIRECT), a combined MESSAGING_* value (automatic destination across 2+ apps), or ON_AD for lead-form campaigns."},"promoted_object":{"type":"string"},"daily_budget":{"type":"string"},"lifetime_budget":{"type":"string"},"bid_amount":{"type":"number"},"targeting":{"type":"string"},"last_synced_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"raw":{"type":"string"}}},"example":{"id":1,"account_id":1,"ad_account_id":1,"campaign_id":1,"remote_id":1,"name":"Sample Name","status":"active","effective_status":"sample effective status","optimization_goal":"sample optimization goal","destination_type":"WHATSAPP","promoted_object":"sample promoted object","daily_budget":"sample daily budget","lifetime_budget":"sample lifetime budget","bid_amount":149.9,"targeting":"sample targeting","last_synced_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","raw":"sample raw"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/ads/ads":{"get":{"tags":["Ads"],"operationId":"auto_get_api_v1_accounts_account_id_ads_ads","summary":"List ads","description":"Returns the list of ads visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"ad_account_id":{"type":"integer"},"ad_set_id":{"type":"integer"},"creative_id":{"type":"integer"},"remote_id":{"type":"integer"},"name":{"type":"string"},"status":{"type":"string","enum":["active","paused","deleted","archived","draft"]},"effective_status":{"type":"string"},"last_synced_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}},"meta":{"type":"object","properties":{"count":{"type":"integer"}}}}},"example":{"payload":[{"id":1,"account_id":1,"ad_account_id":1,"ad_set_id":1,"creative_id":1,"remote_id":1,"name":"Sample Name","status":"active","effective_status":"sample effective status","last_synced_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}],"meta":{"count":5}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"ad_set_id","in":"query","required":false,"description":"Restrict to ads of one ad set.","schema":{"type":"integer"},"example":14}]}},"/api/v1/accounts/{account_id}/ads/ads/{id}":{"get":{"tags":["Ads"],"operationId":"auto_get_api_v1_accounts_account_id_ads_ads_id","summary":"Get ads","description":"Returns the ad identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"ad_account_id":{"type":"integer"},"ad_set_id":{"type":"integer"},"creative_id":{"type":"integer"},"remote_id":{"type":"integer"},"name":{"type":"string"},"status":{"type":"string","enum":["active","paused","deleted","archived","draft"]},"effective_status":{"type":"string"},"last_synced_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"raw":{"type":"string"}}},"example":{"id":1,"account_id":1,"ad_account_id":1,"ad_set_id":1,"creative_id":1,"remote_id":1,"name":"Sample Name","status":"active","effective_status":"sample effective status","last_synced_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","raw":"sample raw"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/ads/creatives":{"get":{"tags":["Ads"],"operationId":"auto_get_api_v1_accounts_account_id_ads_creatives","summary":"List creatives","description":"Returns the list of creatives visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"ad_account_id":{"type":"integer"},"remote_id":{"type":"integer"},"name":{"type":"string"},"call_to_action_type":{"type":"string","enum":["WHATSAPP_MESSAGE"],"description":"Meta creative call-to-action type."},"message_text":{"type":"string"},"object_story_spec":{"type":"string"},"image_hash":{"type":"string"},"image_url":{"type":"string"},"page_id":{"type":"integer"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}},"meta":{"type":"object","properties":{"count":{"type":"integer"}}}}},"example":{"payload":[{"id":1,"account_id":1,"ad_account_id":1,"remote_id":1,"name":"Sample Name","call_to_action_type":"WHATSAPP_MESSAGE","message_text":"sample message text","object_story_spec":"sample object story spec","image_hash":"sample image hash","image_url":"https://example.com/resource","page_id":1,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}],"meta":{"count":5}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."}]}},"/api/v1/accounts/{account_id}/ads/creatives/{id}":{"get":{"tags":["Ads"],"operationId":"auto_get_api_v1_accounts_account_id_ads_creatives_id","summary":"Get creatives","description":"Returns the creative identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"ad_account_id":{"type":"integer"},"remote_id":{"type":"integer"},"name":{"type":"string"},"call_to_action_type":{"type":"string","enum":["WHATSAPP_MESSAGE"],"description":"Meta creative call-to-action type."},"message_text":{"type":"string"},"object_story_spec":{"type":"string"},"image_hash":{"type":"string"},"image_url":{"type":"string"},"page_id":{"type":"integer"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"raw":{"type":"string"}}},"example":{"id":1,"account_id":1,"ad_account_id":1,"remote_id":1,"name":"Sample Name","call_to_action_type":"WHATSAPP_MESSAGE","message_text":"sample message text","object_story_spec":"sample object story spec","image_hash":"sample image hash","image_url":"https://example.com/resource","page_id":1,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","raw":"sample raw"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/ads/audiences":{"get":{"tags":["Ads"],"operationId":"auto_get_api_v1_accounts_account_id_ads_audiences","summary":"List audiences","description":"Returns the list of audiences visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"ad_account_id":{"type":"integer"},"remote_id":{"type":"integer"},"name":{"type":"string"},"subtype":{"type":"string"},"approximate_count":{"type":"integer"},"delivery_code":{"type":["string","null"]},"operation_code":{"type":["string","null"]},"rule":{"type":"string"},"last_synced_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}},"meta":{"type":"object","properties":{"count":{"type":"integer"}}}}},"example":{"payload":[{"id":1,"account_id":1,"ad_account_id":1,"remote_id":1,"name":"Sample Name","subtype":"sample subtype","approximate_count":5,"delivery_code":"sample delivery code","operation_code":"sample operation code","rule":"sample rule","last_synced_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}],"meta":{"count":5}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."}]},"post":{"tags":["Ads"],"operationId":"auto_post_api_v1_accounts_account_id_ads_audiences","summary":"Create audiences","description":"Creates a new audience from the request payload. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"201":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"ad_account_id":{"type":"integer"},"remote_id":{"type":"integer"},"name":{"type":"string"},"subtype":{"type":"string"},"approximate_count":{"type":"integer"},"delivery_code":{"type":["string","null"]},"operation_code":{"type":["string","null"]},"rule":{"type":"string"},"last_synced_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"example":{"id":1,"account_id":1,"ad_account_id":1,"remote_id":1,"name":"Sample Name","subtype":"sample subtype","approximate_count":5,"delivery_code":"sample delivery code","operation_code":"sample operation code","rule":"sample rule","last_synced_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"audience":{"type":"object","properties":{"name":{"type":"string"},"subtype":{"type":"string"},"origin_audience_id":{"type":"integer"},"ratio":{"type":"string"},"country":{"type":"string"},"source":{"type":"string"},"leads_scope":{"type":"string"},"rule":{"type":"object","additionalProperties":true,"description":"Free-form object."}}}},"required":["audience"]},"example":{"audience":{"name":"Sample Name","subtype":"sample subtype","origin_audience_id":1,"ratio":"sample ratio","country":"BR","source":"sample source","leads_scope":"sample leads scope","rule":{}}}}}}}},"/api/v1/accounts/{account_id}/ads/audiences/{id}":{"delete":{"tags":["Ads"],"operationId":"auto_delete_api_v1_accounts_account_id_ads_audiences_id","summary":"Delete audiences","description":"Deletes the audience identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Success (no content)"},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/ads/previews":{"post":{"tags":["Ads"],"operationId":"auto_post_api_v1_accounts_account_id_ads_previews","summary":"Create previews","description":"Creates a new preview from the request payload. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"string"}}},"example":{"payload":"sample payload"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"preview":{"type":"object","properties":{"ad_account_id":{"type":"integer"},"kind":{"type":"string","enum":["ctwa","lead_form"],"description":"Ad objective — Click-to-WhatsApp or Lead Form."},"message_text":{"type":"string"},"body":{"type":"string"},"headline":{"type":"string"},"description":{"type":"string"},"image_hash":{"type":"string"},"video_id":{"type":"integer"},"video_thumbnail_url":{"type":"string"},"lead_form_id":{"type":"integer"},"destinations":{"type":"array","description":"Messaging destinations the campaign opens — where the conversation lands when someone taps the ad. Two or more selections become Meta's automatic destination (each person is routed to the app where they are most likely to reply). Defaults to whatsapp when omitted.","items":{"type":"string","enum":["whatsapp","messenger","instagram"]}},"formats":{"type":"array","items":{"type":"string"}}}}},"required":["preview"]},"example":{"preview":{"ad_account_id":1,"kind":"ctwa","message_text":"sample message text","body":"Sample body text.","headline":"sample headline","description":"A short description.","image_hash":"sample image hash","video_id":1,"video_thumbnail_url":"https://example.com/resource","lead_form_id":1,"destinations":["whatsapp"],"formats":["sample format"]}}}}}}},"/api/v1/accounts/{account_id}/ads/images":{"post":{"tags":["Ads"],"operationId":"auto_post_api_v1_accounts_account_id_ads_images","summary":"Create images","description":"Creates a new image from the request payload. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"string"}}},"example":{"payload":"sample payload"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"image":{"type":"object","properties":{"ad_account_id":{"type":"integer"},"file":{"type":"string"},"media_asset_id":{"type":"integer"},"name":{"type":"string"}}}},"required":["image"]},"example":{"image":{"ad_account_id":1,"file":"sample file","media_asset_id":1,"name":"Sample Name"}}}}}}},"/api/v1/accounts/{account_id}/ads/videos":{"post":{"tags":["Ads"],"operationId":"auto_post_api_v1_accounts_account_id_ads_videos","summary":"Upload a creative video to the connected Meta ad account","description":"Uploads a video (multipart file up to 50MB, or an existing Media Library asset by id) to the connected ad account's advideos edge and returns the `video_id` the campaign creative references. Meta processes the video asynchronously — poll the show endpoint until `status` is `ready` before creating the campaign. Uploaded files are also filed in the Media Library under the Ads folder.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The advideo handle — Meta is still processing it.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"video_id":{"type":"string","example":"1206798107412941"},"status":{"type":"string","enum":["processing","ready","error"],"example":"processing"},"name":{"type":"string","example":"promo-julho.mp4"}}}}},"example":{"payload":{"video_id":"1206798107412941","status":"processing","name":"promo-julho.mp4"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"422":{"description":"No video source, file over 50MB, non-video asset or a Meta gateway rejection.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"video exceeds the 50MB limit"}}},"example":{"error":"video exceeds the 50MB limit"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["video"],"properties":{"video":{"type":"object","required":["ad_account_id"],"properties":{"ad_account_id":{"type":"integer","example":3},"file":{"type":"string","format":"binary","description":"The video file (MP4/MOV, up to 50MB). Either `file` or `media_asset_id`."},"media_asset_id":{"type":["integer","null"],"description":"Reuse a Media Library video asset instead of uploading a file.","example":91},"name":{"type":["string","null"],"example":"promo-julho.mp4"}}}}},"example":{"video":{"ad_account_id":3,"media_asset_id":91,"name":"promo-julho.mp4"}}}}}}},"/api/v1/accounts/{account_id}/ads/videos/{id}":{"get":{"tags":["Ads"],"operationId":"auto_get_api_v1_accounts_account_id_ads_videos_id","summary":"Poll a creative video's Meta processing status","description":"Reads the advideo's processing state (`processing` → `ready`/`error`) and Meta's auto-generated preferred thumbnail. The campaign wizard keeps the create disabled until `ready`; the thumbnail feeds the creative's video_data when the operator did not pick a cover image.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The processing state with the preferred thumbnail once available.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"video_id":{"type":"string","example":"1206798107412941"},"status":{"type":"string","enum":["processing","ready","error"],"example":"ready"},"thumbnail_url":{"type":["string","null"],"description":"Meta's preferred auto-generated thumbnail (fbcdn signed URL).","example":"https://scontent.xx.fbcdn.net/v/t15.5256-10/thumb.jpg"}}}}},"example":{"payload":{"video_id":"1206798107412941","status":"ready","thumbnail_url":"https://scontent.xx.fbcdn.net/v/t15.5256-10/thumb.jpg"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"422":{"description":"The connection has no usable token or Meta refused the read.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"meta get failed: HTTP 400 (Invalid parameter)"}}},"example":{"error":"meta get failed: HTTP 400 (Invalid parameter)"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"ad_account_id","in":"query","required":true,"schema":{"type":"integer"},"description":"The connected ad account that owns the video."}]}},"/api/v1/accounts/{account_id}/ads/targeting/search":{"get":{"tags":["Ads"],"operationId":"auto_get_api_v1_accounts_account_id_ads_targeting_search","summary":"Search targeting","description":"Performs the search operation on the targeted targeting resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"string"}}}},"example":{"payload":["sample payload"]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"q","in":"query","required":true,"description":"Term to autocomplete. An empty term returns no suggestions.","schema":{"type":"string"},"example":"são paulo"},{"name":"kind","in":"query","required":false,"description":"Which catalogue to search. Defaults to geo locations.","schema":{"type":"string","enum":["geo","interest"]},"example":"geo"}]}},"/api/v1/accounts/{account_id}/ads/targeting/estimate":{"get":{"tags":["Ads"],"operationId":"auto_get_api_v1_accounts_account_id_ads_targeting_estimate","summary":"Estimate targeting","description":"Performs the estimate operation on the targeted targeting resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"string"}}}},"example":{"payload":["sample payload"]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"optimization_goal","in":"query","required":false,"description":"Optimization goal the estimate is computed for. Defaults to CONVERSATIONS.","schema":{"type":"string"},"example":"CONVERSATIONS"}]}},"/api/v1/accounts/{account_id}/ads/lead_forms":{"get":{"tags":["Ads"],"operationId":"auto_get_api_v1_accounts_account_id_ads_lead_forms","summary":"List lead forms","description":"Returns the list of lead forms visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"ad_account_id":{"type":"integer"},"page_id":{"type":"integer"},"remote_id":{"type":"integer"},"name":{"type":"string"},"status":{"type":"string"},"questions":{"type":"string"},"privacy_url":{"type":"string"},"follow_up_url":{"type":"string"},"leads_count":{"type":"integer"},"last_synced_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}},"meta":{"type":"object","properties":{"count":{"type":"integer"}}}}},"example":{"payload":[{"id":1,"account_id":1,"ad_account_id":1,"page_id":1,"remote_id":1,"name":"Sample Name","status":"active","questions":"sample questions","privacy_url":"https://example.com/resource","follow_up_url":"https://example.com/resource","leads_count":5,"last_synced_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}],"meta":{"count":5}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"sync","in":"query","required":false,"description":"Any non-empty value forces a live re-read of the lead forms from the network before answering. A first call on an ad account with no stored forms syncs anyway.","schema":{"type":"string"},"example":"1"}]},"post":{"tags":["Ads"],"operationId":"auto_post_api_v1_accounts_account_id_ads_lead_forms","summary":"Create lead forms","description":"Creates a new lead form from the request payload. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"201":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"ad_account_id":{"type":"integer"},"page_id":{"type":"integer"},"remote_id":{"type":"integer"},"name":{"type":"string"},"status":{"type":"string"},"questions":{"type":"string"},"privacy_url":{"type":"string"},"follow_up_url":{"type":"string"},"leads_count":{"type":"integer"},"last_synced_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"example":{"id":1,"account_id":1,"ad_account_id":1,"page_id":1,"remote_id":1,"name":"Sample Name","status":"active","questions":"sample questions","privacy_url":"https://example.com/resource","follow_up_url":"https://example.com/resource","leads_count":5,"last_synced_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"lead_form":{"type":"object","properties":{"ad_account_id":{"type":"integer"},"name":{"type":"string"},"privacy_url":{"type":"string"},"privacy_link_text":{"type":"string"},"follow_up_url":{"type":"string"},"questions":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Free-form object."}},"thank_you_page":{"type":"object","additionalProperties":true,"description":"Free-form object."}}}},"required":["lead_form"]},"example":{"lead_form":{"ad_account_id":1,"name":"Sample Name","privacy_url":"https://example.com/resource","privacy_link_text":"sample privacy link text","follow_up_url":"https://example.com/resource","questions":[{}],"thank_you_page":{}}}}}}}},"/api/v1/accounts/{account_id}/ads/lead_forms/{id}":{"get":{"tags":["Ads"],"operationId":"auto_get_api_v1_accounts_account_id_ads_lead_forms_id","summary":"Get lead forms","description":"Returns the lead form identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"ad_account_id":{"type":"integer"},"page_id":{"type":"integer"},"remote_id":{"type":"integer"},"name":{"type":"string"},"status":{"type":"string"},"questions":{"type":"string"},"privacy_url":{"type":"string"},"follow_up_url":{"type":"string"},"leads_count":{"type":"integer"},"last_synced_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"example":{"id":1,"account_id":1,"ad_account_id":1,"page_id":1,"remote_id":1,"name":"Sample Name","status":"active","questions":"sample questions","privacy_url":"https://example.com/resource","follow_up_url":"https://example.com/resource","leads_count":5,"last_synced_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/ads/insights":{"get":{"tags":["Ads"],"operationId":"auto_get_api_v1_accounts_account_id_ads_insights","summary":"List insights","description":"Returns the list of insights visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"dimension_type":{"type":"string","enum":["account","agent","inbox","team"],"description":"Which dimension the rollup row aggregates by."},"from":{"type":"string"},"to":{"type":"string"},"series":{"type":"array","items":{"type":"object","properties":{"metric":{"type":"string"},"points":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","format":"date"},"value":{"type":"number"}}}}}}}}}}},"example":{"payload":{"dimension_type":"account","from":"sample from","to":"sample to","series":[{"metric":"sample metric","points":[{"date":"2026-01-15","value":149.9}]}]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"dimension_id","in":"query","required":false,"description":"Restrict to one entity of the requested dimension (campaign, ad set or ad id).","schema":{"type":"integer"},"example":9}]}},"/api/v1/accounts/{account_id}/ads/reports/summary":{"get":{"tags":["Ads"],"operationId":"auto_get_api_v1_accounts_account_id_ads_reports_summary","summary":"Summary reports","description":"Performs the summary operation on the targeted report resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"},"metrics":{"type":"object","properties":{"merge":{"type":"string"}}}}}}},"example":{"payload":{"from":"sample from","to":"sample to","metrics":{"merge":"sample merge"}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/ads/reports/breakdown":{"get":{"tags":["Ads"],"operationId":"auto_get_api_v1_accounts_account_id_ads_reports_breakdown","summary":"Breakdown reports","description":"Performs the breakdown operation on the targeted report resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"},"platforms":{"type":"object","properties":{"merge":{"type":"string"}}}}}}},"example":{"payload":{"from":"sample from","to":"sample to","platforms":{"merge":"sample merge"}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/ads/conversation_context":{"get":{"tags":["Ads"],"operationId":"auto_get_api_v1_accounts_account_id_ads_conversation_context","summary":"Get the ad context of a conversation","description":"Read-only context for a conversation opened from a Click-to-WhatsApp, Click-to-Messenger or Click-to-Instagram Direct ad: the stored ad referral, the free entry point window, the attributed lead and the mirrored campaign, each null when absent. CTM/CTD creative fields remain verbatim under `ad_referral.ads_context_data`; `lead.source` identifies their proven channel for the dashboard preview. The window follows Meta's rule: it waits for the business's first response inside the customer service window (`awaiting_response`, `expires_at` = 24 hours after the customer's last message), opens on the first Cloud API response for up to 7 days, or Meta's exact end when a status reports it (`open`, then `expiring` in the last hours), and is `expired` afterwards — including when the first response never came or Meta charged a reply. Requires the `ads_manager` or `growth_ads` feature and permission to see the conversation.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The ad context of the conversation.","content":{"application/json":{"schema":{"type":"object","required":["payload"],"properties":{"payload":{"type":"object","required":["ad_referral","window","lead","campaign"],"properties":{"ad_referral":{"type":["object","null"],"additionalProperties":true,"description":"The referral Meta delivered with the customer's first message from the ad (for example `source_url`, `source_id`, `source_type`, `headline`, `body`, `media_type`, `image_url` and `ctwa_clid`), as stored on the conversation; the keys present depend on the ad and the channel. CTM/CTD referrals may additionally include the server-captured `origin` envelope (`inbox_id`, `contact_inbox_id`, `messaging_channel`, `asset_id`), which keeps a merged contact's Messenger and Instagram identities bound to their originating conversation."},"window":{"type":["object","null"],"required":["state","phase","expires_at","remaining_seconds"],"description":"The free entry point window of the conversation; null when there is none.","properties":{"state":{"type":"string","enum":["open","expiring","expired","awaiting_response"],"description":"Derived on every read: `awaiting_response` until the first response, `open` while free, `expiring` near the end, `expired` once over."},"phase":{"type":["string","null"],"enum":["awaiting_response","open",null],"description":"Stored phase: `awaiting_response` before the first Cloud API response, `open` after it; null for a window recorded before the first-response rule."},"expires_at":{"type":"string","format":"date-time","description":"First-response deadline while awaiting, else the end of the free window."},"remaining_seconds":{"type":"integer","minimum":0,"description":"Seconds until `expires_at`; 0 once expired."}}},"lead":{"type":["object","null"],"description":"The attributed lead; null when there is none.","properties":{"id":{"type":"integer"},"source":{"type":"string","enum":["ctwa","leadgen","ctm","ctd"]},"status":{"type":"string","enum":["captured","enriched","failed","converted"]},"headline":{"type":["string","null"]},"campaign_id":{"type":["string","null"]},"adset_id":{"type":["string","null"]},"ad_id":{"type":["string","null"]},"converted_at":{"type":["string","null"],"format":"date-time"},"conversion_value_amount":{"type":["string","null"],"description":"Conversion value as a decimal string."},"conversion_currency":{"type":["string","null"]}}},"campaign":{"type":["object","null"],"description":"The mirrored campaign of the ad; null when it is not mirrored.","properties":{"id":{"type":"integer"},"name":{"type":"string"},"remote_id":{"type":"string"},"effective_status":{"type":"string","description":"Meta's computed delivery status (an open set owned by Meta), else the configured status."}}}}}}},"example":{"payload":{"ad_referral":{"source_url":"https://fb.me/2ZtGgSDE1","source_id":"120210000000000000","source_type":"ad","headline":"Fale conosco pelo WhatsApp","body":"Atendimento em minutos.","media_type":"image","image_url":"https://scontent.xx.fbcdn.net/v/t45.1600-4/ad.jpg","ctwa_clid":"ARAkLkA8rmlFeiCktEJQ-QTwRiyYHAFDLMNDBH0CD3qpjd0HR4irJ6LEkR7JwFF4XvnO2E4Nx0-eM-GABDLOPaOdRMv-_zfUQ2a"},"window":{"state":"awaiting_response","phase":"awaiting_response","expires_at":"2026-10-02T15:30:00Z","remaining_seconds":86400},"lead":{"id":7,"source":"ctwa","status":"captured","headline":"Fale conosco pelo WhatsApp","campaign_id":"120210000000000001","adset_id":"120210000000000002","ad_id":"120210000000000000","converted_at":null,"conversion_value_amount":null,"conversion_currency":null},"campaign":{"id":3,"name":"Campanha WhatsApp — Outubro","remote_id":"120210000000000001","effective_status":"ACTIVE"}}}}}},"401":{"description":"The caller cannot see the conversation.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}},"example":{"error":"You are not authorized to do this action"}}}},"404":{"description":"No conversation with this display ID in the account.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["conversation_not_found"]}}},"example":{"error":"conversation_not_found"}}}},"403":{"description":"Neither `ads_manager` nor `growth_ads` is enabled on the account.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["feature_not_enabled"]}}},"example":{"error":"feature_not_enabled"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"conversation_id","in":"query","required":true,"description":"Display ID of the conversation.","schema":{"type":"integer"},"example":42}]}},"/api/v1/accounts/{account_id}/internal_chat/channels/{id}/join":{"post":{"tags":["Internal Chat"],"operationId":"auto_post_api_v1_accounts_account_id_internal_chat_channels_id_join","summary":"Join channels","description":"Performs the join operation on the targeted channel resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Fully rendered channel with viewer state, latest-message preview and current members.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/internal_chat_channel_response"},"example":{"payload":{"id":30,"kind":"direct","name":null,"slug":null,"description":null,"topic":null,"visibility":"private_channel","posting_policy":"all_members","team_id":null,"created_by_id":7,"allowed_poster_ids":[],"avatar_url":null,"avatar_icon":null,"avatar_color":null,"archived":false,"last_message_at":"2026-08-24T17:46:00Z","messages_count":1284,"members_count":2,"unread_count":4,"created_at":1778734800,"current_member":{"id":61,"role":"owner","notification_level":"all","muted_until":null,"muted":false,"pinned":true,"archived":false},"last_message":{"id":9007,"content":"Deploy is green, shipping now.","content_type":"text","attachments_count":1,"sender_id":12,"sender_name":"John Agent","is_own":false,"created_at":1778735160},"direct_partner":{"id":12,"name":"John Agent","thumbnail":"https://cdn.example.com/avatars/12.png"},"members":[{"id":61,"channel_id":30,"user_id":7,"role":"owner","notification_level":"all","muted_until":null,"muted":false,"pinned":true,"archived":false,"last_read_at":"2026-08-24T17:45:00Z","user":{"id":7,"name":"Jane Agent","thumbnail":"https://cdn.example.com/avatars/7.png","availability_status":"online"}}]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/internal_chat/channels/{id}/leave":{"post":{"tags":["Internal Chat"],"operationId":"auto_post_api_v1_accounts_account_id_internal_chat_channels_id_leave","summary":"Leave an internal chat channel","description":"Removes the authenticated user's own membership from an internal chat channel. Only the caller's membership is affected; the channel and its message history are kept. A user who is the channel's only owner cannot leave, so ownership must be transferred to somebody else first. On success the endpoint returns HTTP 200 with an EMPTY body. Calling it when the user is not a member succeeds as a no-op.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The caller no longer belongs to the channel, or was already not a member. Empty body in both cases."},"401":{"description":"Unauthorized"},"404":{"description":"No internal chat channel with this id is visible to the caller."},"422":{"description":"The caller is the only owner of the channel. Promote another member to owner before leaving.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable reason the membership could not be removed.","enum":["sole_owner_must_transfer"]}},"required":["error"]},"example":{"error":"sole_owner_must_transfer"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/internal_chat/channels/{id}/read":{"post":{"tags":["Internal Chat"],"operationId":"auto_post_api_v1_accounts_account_id_internal_chat_channels_id_read","summary":"Mark an internal chat channel as read","description":"Advances the authenticated user's read marker on an internal chat channel, which is what clears the channel's unread badge and lowers the total unread count. Unread is derived from this marker, so no per-message state is written. When no message is given the marker jumps to the newest message in the channel. On success the endpoint returns HTTP 200 with an EMPTY body; calling it when the user is not a member of the channel succeeds as a no-op.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The read marker was advanced, or the caller is not a member. Empty body in both cases."},"401":{"description":"Unauthorized"},"404":{"description":"No internal chat channel with this id is visible to the caller."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"message_id":{"type":"integer","description":"Message to read up to. When omitted, the marker advances to the newest message currently in the channel."}}},"example":{"message_id":5120}}}}}},"/api/v1/accounts/{account_id}/internal_chat/channels/{id}/mark_unread":{"post":{"tags":["Internal Chat"],"operationId":"auto_post_api_v1_accounts_account_id_internal_chat_channels_id_mark_unread","summary":"Mark unread channels","description":"Performs the mark unread operation on the targeted channel resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Fully rendered channel with viewer state, latest-message preview and current members.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/internal_chat_channel_response"},"example":{"payload":{"id":30,"kind":"direct","name":null,"slug":null,"description":null,"topic":null,"visibility":"private_channel","posting_policy":"all_members","team_id":null,"created_by_id":7,"allowed_poster_ids":[],"avatar_url":null,"avatar_icon":null,"avatar_color":null,"archived":false,"last_message_at":"2026-08-24T17:46:00Z","messages_count":1284,"members_count":2,"unread_count":4,"created_at":1778734800,"current_member":{"id":61,"role":"owner","notification_level":"all","muted_until":null,"muted":false,"pinned":true,"archived":false},"last_message":{"id":9007,"content":"Deploy is green, shipping now.","content_type":"text","attachments_count":1,"sender_id":12,"sender_name":"John Agent","is_own":false,"created_at":1778735160},"direct_partner":{"id":12,"name":"John Agent","thumbnail":"https://cdn.example.com/avatars/12.png"},"members":[{"id":61,"channel_id":30,"user_id":7,"role":"owner","notification_level":"all","muted_until":null,"muted":false,"pinned":true,"archived":false,"last_read_at":"2026-08-24T17:45:00Z","user":{"id":7,"name":"Jane Agent","thumbnail":"https://cdn.example.com/avatars/7.png","availability_status":"online"}}]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/internal_chat/channels/{id}/archive":{"post":{"tags":["Internal Chat"],"operationId":"auto_post_api_v1_accounts_account_id_internal_chat_channels_id_archive","summary":"Archive channels","description":"Performs the archive operation on the targeted channel resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Fully rendered channel with viewer state, latest-message preview and current members.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/internal_chat_channel_response"},"example":{"payload":{"id":30,"kind":"direct","name":null,"slug":null,"description":null,"topic":null,"visibility":"private_channel","posting_policy":"all_members","team_id":null,"created_by_id":7,"allowed_poster_ids":[],"avatar_url":null,"avatar_icon":null,"avatar_color":null,"archived":false,"last_message_at":"2026-08-24T17:46:00Z","messages_count":1284,"members_count":2,"unread_count":4,"created_at":1778734800,"current_member":{"id":61,"role":"owner","notification_level":"all","muted_until":null,"muted":false,"pinned":true,"archived":false},"last_message":{"id":9007,"content":"Deploy is green, shipping now.","content_type":"text","attachments_count":1,"sender_id":12,"sender_name":"John Agent","is_own":false,"created_at":1778735160},"direct_partner":{"id":12,"name":"John Agent","thumbnail":"https://cdn.example.com/avatars/12.png"},"members":[{"id":61,"channel_id":30,"user_id":7,"role":"owner","notification_level":"all","muted_until":null,"muted":false,"pinned":true,"archived":false,"last_read_at":"2026-08-24T17:45:00Z","user":{"id":7,"name":"Jane Agent","thumbnail":"https://cdn.example.com/avatars/7.png","availability_status":"online"}}]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/internal_chat/channels/{id}/unarchive":{"post":{"tags":["Internal Chat"],"operationId":"auto_post_api_v1_accounts_account_id_internal_chat_channels_id_unarchive","summary":"Unarchive channels","description":"Performs the unarchive operation on the targeted channel resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Fully rendered channel with viewer state, latest-message preview and current members.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/internal_chat_channel_response"},"example":{"payload":{"id":30,"kind":"direct","name":null,"slug":null,"description":null,"topic":null,"visibility":"private_channel","posting_policy":"all_members","team_id":null,"created_by_id":7,"allowed_poster_ids":[],"avatar_url":null,"avatar_icon":null,"avatar_color":null,"archived":false,"last_message_at":"2026-08-24T17:46:00Z","messages_count":1284,"members_count":2,"unread_count":4,"created_at":1778734800,"current_member":{"id":61,"role":"owner","notification_level":"all","muted_until":null,"muted":false,"pinned":true,"archived":false},"last_message":{"id":9007,"content":"Deploy is green, shipping now.","content_type":"text","attachments_count":1,"sender_id":12,"sender_name":"John Agent","is_own":false,"created_at":1778735160},"direct_partner":{"id":12,"name":"John Agent","thumbnail":"https://cdn.example.com/avatars/12.png"},"members":[{"id":61,"channel_id":30,"user_id":7,"role":"owner","notification_level":"all","muted_until":null,"muted":false,"pinned":true,"archived":false,"last_read_at":"2026-08-24T17:45:00Z","user":{"id":7,"name":"Jane Agent","thumbnail":"https://cdn.example.com/avatars/7.png","availability_status":"online"}}]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/internal_chat/channels/{channel_id}/members":{"get":{"tags":["Internal Chat"],"operationId":"auto_get_api_v1_accounts_account_id_internal_chat_channels_channel_id_members","summary":"List members","description":"Returns the list of members visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Complete current membership list for the channel.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/internal_chat_member_list_response"},"example":{"payload":[{"id":61,"channel_id":30,"user_id":7,"role":"owner","notification_level":"all","muted_until":null,"muted":false,"pinned":true,"archived":false,"last_read_at":"2026-08-24T17:45:00Z","user":{"id":7,"name":"Jane Agent","thumbnail":"https://cdn.example.com/avatars/7.png","availability_status":"online"}}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"channel_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."}]},"post":{"tags":["Internal Chat"],"operationId":"auto_post_api_v1_accounts_account_id_internal_chat_channels_channel_id_members","summary":"Create members","description":"Creates a new member from the request payload. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Complete current membership list for the channel.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/internal_chat_member_list_response"},"example":{"payload":[{"id":61,"channel_id":30,"user_id":7,"role":"owner","notification_level":"all","muted_until":null,"muted":false,"pinned":true,"archived":false,"last_read_at":"2026-08-24T17:45:00Z","user":{"id":7,"name":"Jane Agent","thumbnail":"https://cdn.example.com/avatars/7.png","availability_status":"online"}}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"channel_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"user_ids":{"type":"array","items":{"type":"integer"}},"user_id":{"type":"integer"}}},"example":{"user_ids":[1],"user_id":1}}}}}},"/api/v1/accounts/{account_id}/internal_chat/channels/{channel_id}/members/{id}":{"patch":{"tags":["Internal Chat"],"operationId":"auto_patch_api_v1_accounts_account_id_internal_chat_channels_channel_id_members_id","summary":"Update members","description":"Updates the member identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Complete current membership list for the channel.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/internal_chat_member_list_response"},"example":{"payload":[{"id":61,"channel_id":30,"user_id":7,"role":"owner","notification_level":"all","muted_until":null,"muted":false,"pinned":true,"archived":false,"last_read_at":"2026-08-24T17:45:00Z","user":{"id":7,"name":"Jane Agent","thumbnail":"https://cdn.example.com/avatars/7.png","availability_status":"online"}}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"channel_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/internal_chat_member_update_payload"},"example":{"member":{"role":"owner","notification_level":"mentions","muted_until":"2026-08-25T18:00:00Z","pinned":true,"archived":false}}}}}},"put":{"tags":["Internal Chat"],"operationId":"auto_put_api_v1_accounts_account_id_internal_chat_channels_channel_id_members_id","summary":"Update members","description":"Updates the member identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Complete current membership list for the channel.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/internal_chat_member_list_response"},"example":{"payload":[{"id":61,"channel_id":30,"user_id":7,"role":"owner","notification_level":"all","muted_until":null,"muted":false,"pinned":true,"archived":false,"last_read_at":"2026-08-24T17:45:00Z","user":{"id":7,"name":"Jane Agent","thumbnail":"https://cdn.example.com/avatars/7.png","availability_status":"online"}}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"channel_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/internal_chat_member_update_payload"},"example":{"member":{"role":"owner","notification_level":"mentions","muted_until":"2026-08-25T18:00:00Z","pinned":true,"archived":false}}}}}},"delete":{"tags":["Internal Chat"],"operationId":"auto_delete_api_v1_accounts_account_id_internal_chat_channels_channel_id_members_id","summary":"Delete members","description":"Deletes the member identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Success (no content)"},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"channel_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/internal_chat/channels/{channel_id}/messages/{message_id}/reactions":{"post":{"tags":["Internal Chat"],"operationId":"auto_post_api_v1_accounts_account_id_internal_chat_channels_channel_id_messages_message_id_reactions","summary":"Create reactions","description":"Creates a new reaction from the request payload. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Reaction toggled — returns the updated message","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer","example":9001},"channel_id":{"type":"integer","example":12},"content":{"type":["string","null"],"example":"Deploy is live 🎉"},"message_type":{"type":"integer","description":"0=message, 1=activity","example":0},"content_type":{"type":"string","enum":["text","shared_entity","system"],"example":"text"},"content_attributes":{"type":"object","additionalProperties":true,"example":{"reactions":{"👍":[7,12]}},"description":"Structured metadata accompanying the message content; the key set depends on content_type (e.g. select items, CSAT submission values, deletion flags, external delivery errors)."},"created_at":{"type":"integer","description":"Unix epoch seconds","example":1737024600},"sender":{"type":["object","null"],"properties":{"id":{"type":"integer","example":7},"name":{"type":"string","example":"Jane Agent"},"thumbnail":{"type":"string","example":"https://cdn.example.com/avatars/7.png"},"type":{"type":"string","example":"user"}}},"sender_id":{"type":["integer","null"],"example":7},"attachments":{"type":"array","description":"Files attached to the internal-chat message.","items":{"type":"object","properties":{"id":{"type":"integer","description":"Attachment id.","example":91},"message_id":{"type":"integer","description":"Message this file belongs to.","example":4210},"account_id":{"type":"integer","description":"Owning account.","example":7},"file_type":{"type":"string","description":"Coarse kind derived from the content type, for choosing how to render it.","enum":["image","audio","video","file"],"example":"image"},"extension":{"type":"string","description":"File extension without the dot.","example":"png"},"content_type":{"type":"string","description":"MIME type as stored.","example":"image/png"},"data_url":{"type":"string","description":"URL the file is served from.","example":"https://app.example.com/rails/active_storage/blobs/redirect/ey/diagrama.png"},"thumb_url":{"type":"string","description":"Thumbnail URL. Empty when no thumbnail exists.","example":""},"file_size":{"type":"integer","description":"Size in bytes.","example":20481}}}}}}}},"example":{"payload":{"id":9001,"channel_id":12,"content":"Deploy is live 🎉","message_type":0,"content_type":"text","content_attributes":{"reactions":{"👍":[7,12]}},"created_at":1737024600,"sender":{"id":7,"name":"Jane Agent","thumbnail":"https://cdn.example.com/avatars/7.png","type":"user"},"sender_id":7,"attachments":[{"id":91,"message_id":4210,"account_id":7,"file_type":"image","extension":"png","content_type":"image/png","data_url":"https://app.example.com/rails/active_storage/blobs/redirect/ey/diagrama.png","thumb_url":"","file_size":20481}]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"channel_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"message_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["emoji"],"properties":{"emoji":{"type":"string","description":"Emoji to toggle on the message","example":"👍"}}},"example":{"emoji":"👍"}}}}}},"/api/v1/accounts/{account_id}/internal_chat/channels/{channel_id}/messages":{"get":{"tags":["Internal Chat"],"operationId":"auto_get_api_v1_accounts_account_id_internal_chat_channels_channel_id_messages","summary":"List the messages of an internal-chat channel (cursor-paginated)","description":"Returns one page of messages for a channel, newest last. The thread scrolls UP: pass `before` (a message id) to load the page of older messages before it, and `limit` to size the page (default 30, capped at 50). Every message the current user may see is returned except other members' private notes (\"Nota Privada\"), which are visible only to their author. `meta.has_more` signals that older pages exist; `meta.count` is the size of the loaded page, while `meta.total_count` is the authoritative count of the WHOLE visible channel scope (not just the page). Before the client advances read state, `meta.unread_count` and `meta.first_unread_message_id` capture the unread boundary inside the returned page. When `message_id` is supplied, `meta.target_visible` reports whether that target is in this viewer's scoped channel history; deleted, missing, cross-channel and unauthorized targets all return false. Requires read access to the channel (membership or a public named channel).","security":[{"userApiKey":[]}],"responses":{"200":{"description":"One page of messages plus pagination meta.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","description":"The page of messages, oldest first.","items":{"type":"object","properties":{"id":{"type":"integer","description":"Message id.","example":9007},"channel_id":{"type":"integer","description":"Id of the channel the message belongs to.","example":42},"content":{"type":["string","null"],"description":"The message text (empty for a soft-deleted or shared-entity message).","example":"Deploy is green, shipping now."},"message_type":{"type":"integer","enum":[0,1],"description":"0 = message, 1 = activity (system/activity row).","example":0},"content_type":{"type":"string","enum":["text","shared_entity","system"],"description":"Payload kind — plain text, a shared entity card, or a system line.","example":"text"},"content_attributes":{"type":"object","additionalProperties":true,"description":"Free-form jsonb metadata — may carry in_reply_to, reactions, shared_entity, edited_at, deleted and private flags.","example":{"reactions":{"👍":[7]},"edited_at":"2026-01-15T10:31:00Z"}},"created_at":{"type":"integer","description":"Creation time as a Unix epoch (seconds).","example":1778735498},"sender_id":{"type":["integer","null"],"description":"Id of the sending user (null for a system/activity row).","example":7},"sender":{"type":["object","null"],"description":"The sending user (null for a system/activity row).","properties":{"id":{"type":"integer","example":7},"name":{"type":"string","example":"Ada Lovelace"},"thumbnail":{"type":"string","description":"Avatar URL (empty string when the user has no avatar).","example":"https://cdn.example.com/avatars/7.png"},"type":{"type":"string","enum":["user"],"description":"Always \"user\" for internal chat.","example":"user"}}},"attachments":{"type":"array","description":"Active Storage attachments on the message.","items":{"type":"object","properties":{"id":{"type":"integer","example":331},"message_id":{"type":"integer","example":9007},"account_id":{"type":"integer","example":1},"file_type":{"type":"string","enum":["image","audio","video","file"],"description":"Coarse media class derived from the content type.","example":"image"},"extension":{"type":"string","description":"File extension without the dot.","example":"png"},"content_type":{"type":"string","example":"image/png"},"data_url":{"type":"string","description":"Relative blob-redirect path (resolves against the dashboard origin).","example":"/rails/active_storage/blobs/redirect/abc123/screenshot.png"},"thumb_url":{"type":"string","example":""},"file_size":{"type":"integer","description":"Byte size of the blob.","example":20482}}}}}}},"meta":{"type":"object","properties":{"has_more":{"type":"boolean","description":"Whether older pages of messages exist before this one.","example":true},"count":{"type":"integer","description":"Size of the loaded page (not the whole thread).","example":30},"total_count":{"type":"integer","description":"Authoritative count of the whole visible channel scope (not just the page).","example":1284},"unread_count":{"type":"integer","description":"Incoming messages unread by the current user before this response was rendered.","example":4},"first_unread_message_id":{"type":["integer","null"],"description":"First row in this page after the current user's read marker, or null when the page has no unread boundary.","example":9007},"target_visible":{"type":"boolean","description":"Present only when message_id was supplied. True when the target belongs to this channel and is visible to the current user; false for deleted, missing, cross-channel or viewer-invisible targets.","example":true}}}}},"example":{"payload":[{"id":9007,"channel_id":42,"content":"Deploy is green, shipping now.","message_type":0,"content_type":"text","content_attributes":{"reactions":{"👍":[7]},"edited_at":"2026-01-15T10:31:00Z"},"created_at":1778735498,"sender_id":7,"sender":{"id":7,"name":"Ada Lovelace","thumbnail":"https://cdn.example.com/avatars/7.png","type":"user"},"attachments":[{"id":331,"message_id":9007,"account_id":1,"file_type":"image","extension":"png","content_type":"image/png","data_url":"/rails/active_storage/blobs/redirect/abc123/screenshot.png","thumb_url":"","file_size":20482}]}],"meta":{"has_more":true,"count":30,"total_count":1284,"unread_count":4,"first_unread_message_id":9007,"target_visible":true}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"channel_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"before","in":"query","required":false,"description":"Cursor for older history: only messages with an id lower than this one are returned. Omitted, the most recent page is returned.","schema":{"type":"integer"},"example":48213},{"name":"message_id","in":"query","required":false,"description":"Optional notification deep-link target. It does not change the returned page; meta.target_visible reports whether the non-deleted message belongs to this channel and is visible to the current user, after applying private-note visibility. The client then follows the existing before cursor until the target is loaded.","schema":{"type":"integer"},"example":47190}]},"post":{"tags":["Internal Chat"],"operationId":"auto_post_api_v1_accounts_account_id_internal_chat_channels_channel_id_messages","summary":"Create messages","description":"Creates a new message from the request payload. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Message created","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer","example":9003},"channel_id":{"type":"integer","example":12},"content":{"type":["string","null"],"example":"Deploy is live 🎉"},"message_type":{"type":"integer","description":"0=message, 1=activity","example":0},"content_type":{"type":"string","enum":["text","shared_entity","system"],"example":"text"},"content_attributes":{"type":"object","additionalProperties":true,"description":"Structured metadata accompanying the message content; the key set depends on content_type (e.g. select items, CSAT submission values, deletion flags, external delivery errors)."},"created_at":{"type":"integer","description":"Unix epoch seconds","example":1737024600},"sender":{"type":["object","null"],"properties":{"id":{"type":"integer","example":7},"name":{"type":"string","example":"Jane Agent"},"thumbnail":{"type":"string","example":"https://cdn.example.com/avatars/7.png"},"type":{"type":"string","example":"user"}}},"sender_id":{"type":["integer","null"],"example":7},"attachments":{"type":"array","description":"Files attached to the internal-chat message.","items":{"type":"object","properties":{"id":{"type":"integer","description":"Attachment id.","example":91},"message_id":{"type":"integer","description":"Message this file belongs to.","example":4210},"account_id":{"type":"integer","description":"Owning account.","example":7},"file_type":{"type":"string","description":"Coarse kind derived from the content type, for choosing how to render it.","enum":["image","audio","video","file"],"example":"image"},"extension":{"type":"string","description":"File extension without the dot.","example":"png"},"content_type":{"type":"string","description":"MIME type as stored.","example":"image/png"},"data_url":{"type":"string","description":"URL the file is served from.","example":"https://app.example.com/rails/active_storage/blobs/redirect/ey/diagrama.png"},"thumb_url":{"type":"string","description":"Thumbnail URL. Empty when no thumbnail exists.","example":""},"file_size":{"type":"integer","description":"Size in bytes.","example":20481}}}}}}}},"example":{"payload":{"id":9003,"channel_id":12,"content":"Deploy is live 🎉","message_type":0,"content_type":"text","content_attributes":{},"created_at":1737024600,"sender":{"id":7,"name":"Jane Agent","thumbnail":"https://cdn.example.com/avatars/7.png","type":"user"},"sender_id":7,"attachments":[{"id":91,"message_id":4210,"account_id":7,"file_type":"image","extension":"png","content_type":"image/png","data_url":"https://app.example.com/rails/active_storage/blobs/redirect/ey/diagrama.png","thumb_url":"","file_size":20481}]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"channel_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"content":{"type":["string","null"],"example":"Deploy is live 🎉"},"in_reply_to":{"type":["integer","null"],"description":"Message id being replied to","example":8999},"private":{"type":"boolean","description":"Private note (visible only to its author)","example":false},"mentioned_user_ids":{"type":"array","items":{"type":"integer"},"example":[12]},"attachments":{"type":"array","description":"ActiveStorage blob signed ids (from direct upload)","items":{"type":"string"},"example":[]},"library_asset_ids":{"type":"array","description":"Media Library asset ids to attach without re-upload","items":{"type":"integer"},"example":[]}}},"example":{"content":"Deploy is live 🎉","in_reply_to":8999,"private":false,"mentioned_user_ids":[12],"attachments":[],"library_asset_ids":[]}}}}}},"/api/v1/accounts/{account_id}/internal_chat/channels/{channel_id}/messages/{id}":{"patch":{"tags":["Internal Chat"],"operationId":"auto_patch_api_v1_accounts_account_id_internal_chat_channels_channel_id_messages_id","summary":"Update messages","description":"Updates the message identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"merge":{"type":"string"}}}}},"example":{"payload":{"merge":"sample merge"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"channel_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"content":{"type":"string"}}},"example":{"content":"Sample content text."}}}}},"put":{"tags":["Internal Chat"],"operationId":"auto_put_api_v1_accounts_account_id_internal_chat_channels_channel_id_messages_id","summary":"Update messages","description":"Updates the message identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"merge":{"type":"string"}}}}},"example":{"payload":{"merge":"sample merge"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"channel_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"content":{"type":"string"}}},"example":{"content":"Sample content text."}}}}},"delete":{"tags":["Internal Chat"],"operationId":"auto_delete_api_v1_accounts_account_id_internal_chat_channels_channel_id_messages_id","summary":"Delete messages","description":"Deletes the message identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Success (no content)"},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"channel_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/internal_chat/channels/{channel_id}/share":{"post":{"tags":["Internal Chat"],"operationId":"auto_post_api_v1_accounts_account_id_internal_chat_channels_channel_id_share","summary":"Create shares","description":"Creates a new share from the request payload. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Entity shared into the channel — returns the created message","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer","example":9002},"channel_id":{"type":"integer","example":12},"content":{"type":["string","null"],"example":"Look at this one"},"message_type":{"type":"integer","description":"0=message, 1=activity","example":0},"content_type":{"type":"string","enum":["text","shared_entity","system"],"example":"shared_entity"},"content_attributes":{"type":"object","additionalProperties":true,"example":{"shared_entity":{"type":"Conversation","id":8817}},"description":"Structured metadata accompanying the message content; the key set depends on content_type (e.g. select items, CSAT submission values, deletion flags, external delivery errors)."},"created_at":{"type":"integer","example":1737024600},"sender":{"type":["object","null"],"properties":{"id":{"type":"integer","example":7},"name":{"type":"string","example":"Jane Agent"},"thumbnail":{"type":"string","example":"https://cdn.example.com/avatars/7.png"},"type":{"type":"string","example":"user"}}},"sender_id":{"type":["integer","null"],"example":7},"attachments":{"type":"array","description":"Files attached to the internal-chat message.","items":{"type":"object","properties":{"id":{"type":"integer","description":"Attachment id.","example":91},"message_id":{"type":"integer","description":"Message this file belongs to.","example":4210},"account_id":{"type":"integer","description":"Owning account.","example":7},"file_type":{"type":"string","description":"Coarse kind derived from the content type, for choosing how to render it.","enum":["image","audio","video","file"],"example":"image"},"extension":{"type":"string","description":"File extension without the dot.","example":"png"},"content_type":{"type":"string","description":"MIME type as stored.","example":"image/png"},"data_url":{"type":"string","description":"URL the file is served from.","example":"https://app.example.com/rails/active_storage/blobs/redirect/ey/diagrama.png"},"thumb_url":{"type":"string","description":"Thumbnail URL. Empty when no thumbnail exists.","example":""},"file_size":{"type":"integer","description":"Size in bytes.","example":20481}}}}}}}},"example":{"payload":{"id":9002,"channel_id":12,"content":"Look at this one","message_type":0,"content_type":"shared_entity","content_attributes":{"shared_entity":{"type":"Conversation","id":8817}},"created_at":1737024600,"sender":{"id":7,"name":"Jane Agent","thumbnail":"https://cdn.example.com/avatars/7.png","type":"user"},"sender_id":7,"attachments":[{"id":91,"message_id":4210,"account_id":7,"file_type":"image","extension":"png","content_type":"image/png","data_url":"https://app.example.com/rails/active_storage/blobs/redirect/ey/diagrama.png","thumb_url":"","file_size":20481}]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Entity not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"entity_not_found"}}},"example":{"error":"entity_not_found"}}}},"422":{"description":"Unsupported entity type","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"unsupported_entity"}}},"example":{"error":"unsupported_entity"}}}},"403":{"description":"Not authorized to share this entity","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"not_authorized"}}},"example":{"error":"not_authorized"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"channel_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["entity_type","entity_id"],"properties":{"entity_type":{"type":"string","enum":["conversation","crm_item","task","payments_charge","calendar_event","contact","catalog_product","whatsapp_hub_broadcast","campaign"],"description":"Source entity type to share into the channel","example":"conversation"},"entity_id":{"type":"integer","example":8817},"message":{"type":["string","null"],"description":"Optional note to accompany the shared entity","example":"Look at this one"}}},"example":{"entity_type":"conversation","entity_id":8817,"message":"Look at this one"}}}}}},"/api/v1/accounts/{account_id}/internal_chat/channels":{"get":{"tags":["Internal Chat"],"operationId":"auto_get_api_v1_accounts_account_id_internal_chat_channels","summary":"List channels","description":"Returns the list of channels visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Channels visible to the viewer under the requested active, archived and kind filters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/internal_chat_channel_list_response"},"example":{"payload":[{"id":30,"kind":"direct","name":null,"slug":null,"description":null,"topic":null,"visibility":"private_channel","posting_policy":"all_members","team_id":null,"created_by_id":7,"allowed_poster_ids":[],"avatar_url":null,"avatar_icon":null,"avatar_color":null,"archived":false,"last_message_at":null,"messages_count":0,"members_count":2,"unread_count":0,"created_at":1778734800,"current_member":{"id":61,"role":"owner","notification_level":"all","muted_until":null,"muted":false,"pinned":true,"archived":false},"last_message":{"id":9007,"content":"Deploy is green, shipping now.","content_type":"text","attachments_count":1,"sender_id":12,"sender_name":"John Agent","is_own":false,"created_at":1778735160},"direct_partner":{"id":12,"name":"John Agent","thumbnail":"https://cdn.example.com/avatars/12.png"}}],"meta":{"count":1}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"archived","in":"query","required":false,"description":"Any non-empty value lists archived channels instead of the active ones.","schema":{"type":"string"},"example":"true"},{"name":"kind","in":"query","required":false,"description":"Restrict to one channel kind.","schema":{"type":"string","enum":["channel","direct","announcement"]},"example":"channel"}]},"post":{"tags":["Internal Chat"],"operationId":"auto_post_api_v1_accounts_account_id_internal_chat_channels","summary":"Create channels","description":"Creates a new channel from the request payload. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Fully rendered channel with viewer state, latest-message preview and current members.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/internal_chat_channel_response"},"example":{"payload":{"id":30,"kind":"direct","name":null,"slug":null,"description":null,"topic":null,"visibility":"private_channel","posting_policy":"all_members","team_id":null,"created_by_id":7,"allowed_poster_ids":[],"avatar_url":null,"avatar_icon":null,"avatar_color":null,"archived":false,"last_message_at":"2026-08-24T17:46:00Z","messages_count":1284,"members_count":2,"unread_count":4,"created_at":1778734800,"current_member":{"id":61,"role":"owner","notification_level":"all","muted_until":null,"muted":false,"pinned":true,"archived":false},"last_message":{"id":9007,"content":"Deploy is green, shipping now.","content_type":"text","attachments_count":1,"sender_id":12,"sender_name":"John Agent","is_own":false,"created_at":1778735160},"direct_partner":{"id":12,"name":"John Agent","thumbnail":"https://cdn.example.com/avatars/12.png"},"members":[{"id":61,"channel_id":30,"user_id":7,"role":"owner","notification_level":"all","muted_until":null,"muted":false,"pinned":true,"archived":false,"last_read_at":"2026-08-24T17:45:00Z","user":{"id":7,"name":"Jane Agent","thumbnail":"https://cdn.example.com/avatars/7.png","availability_status":"online"}}]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"channel":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"topic":{"type":"string"},"kind":{"type":"string","enum":["channel","direct","announcement"]},"visibility":{"type":"string","enum":["public_channel","private_channel"]},"posting_policy":{"type":"string","enum":["all_members","admins_only","allowed_list"]},"team_id":{"type":"integer"}}}},"required":["channel"]},"example":{"channel":{"name":"Sample Name","description":"A short description.","topic":"sample topic","kind":"channel","visibility":"public_channel","posting_policy":"all_members","team_id":1}}}}}}},"/api/v1/accounts/{account_id}/internal_chat/channels/{id}":{"get":{"tags":["Internal Chat"],"operationId":"auto_get_api_v1_accounts_account_id_internal_chat_channels_id","summary":"Get channels","description":"Returns the channel identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Fully rendered channel with viewer state, latest-message preview and current members.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/internal_chat_channel_response"},"example":{"payload":{"id":30,"kind":"direct","name":null,"slug":null,"description":null,"topic":null,"visibility":"private_channel","posting_policy":"all_members","team_id":null,"created_by_id":7,"allowed_poster_ids":[],"avatar_url":null,"avatar_icon":null,"avatar_color":null,"archived":false,"last_message_at":"2026-08-24T17:46:00Z","messages_count":1284,"members_count":2,"unread_count":4,"created_at":1778734800,"current_member":{"id":61,"role":"owner","notification_level":"all","muted_until":null,"muted":false,"pinned":true,"archived":false},"last_message":{"id":9007,"content":"Deploy is green, shipping now.","content_type":"text","attachments_count":1,"sender_id":12,"sender_name":"John Agent","is_own":false,"created_at":1778735160},"direct_partner":{"id":12,"name":"John Agent","thumbnail":"https://cdn.example.com/avatars/12.png"},"members":[{"id":61,"channel_id":30,"user_id":7,"role":"owner","notification_level":"all","muted_until":null,"muted":false,"pinned":true,"archived":false,"last_read_at":"2026-08-24T17:45:00Z","user":{"id":7,"name":"Jane Agent","thumbnail":"https://cdn.example.com/avatars/7.png","availability_status":"online"}}]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]},"patch":{"tags":["Internal Chat"],"operationId":"auto_patch_api_v1_accounts_account_id_internal_chat_channels_id","summary":"Update channels","description":"Updates the channel identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Fully rendered channel with viewer state, latest-message preview and current members.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/internal_chat_channel_response"},"example":{"payload":{"id":30,"kind":"direct","name":null,"slug":null,"description":null,"topic":null,"visibility":"private_channel","posting_policy":"all_members","team_id":null,"created_by_id":7,"allowed_poster_ids":[],"avatar_url":null,"avatar_icon":null,"avatar_color":null,"archived":false,"last_message_at":"2026-08-24T17:46:00Z","messages_count":1284,"members_count":2,"unread_count":4,"created_at":1778734800,"current_member":{"id":61,"role":"owner","notification_level":"all","muted_until":null,"muted":false,"pinned":true,"archived":false},"last_message":{"id":9007,"content":"Deploy is green, shipping now.","content_type":"text","attachments_count":1,"sender_id":12,"sender_name":"John Agent","is_own":false,"created_at":1778735160},"direct_partner":{"id":12,"name":"John Agent","thumbnail":"https://cdn.example.com/avatars/12.png"},"members":[{"id":61,"channel_id":30,"user_id":7,"role":"owner","notification_level":"all","muted_until":null,"muted":false,"pinned":true,"archived":false,"last_read_at":"2026-08-24T17:45:00Z","user":{"id":7,"name":"Jane Agent","thumbnail":"https://cdn.example.com/avatars/7.png","availability_status":"online"}}]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"channel":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"topic":{"type":"string"},"kind":{"type":"string","enum":["channel","direct","announcement"]},"visibility":{"type":"string","enum":["public_channel","private_channel"]},"posting_policy":{"type":"string","enum":["all_members","admins_only","allowed_list"]},"team_id":{"type":"integer"}}}},"required":["channel"]},"example":{"channel":{"name":"Sample Name","description":"A short description.","topic":"sample topic","kind":"channel","visibility":"public_channel","posting_policy":"all_members","team_id":1}}}}}},"put":{"tags":["Internal Chat"],"operationId":"auto_put_api_v1_accounts_account_id_internal_chat_channels_id","summary":"Update channels","description":"Updates the channel identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Fully rendered channel with viewer state, latest-message preview and current members.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/internal_chat_channel_response"},"example":{"payload":{"id":30,"kind":"direct","name":null,"slug":null,"description":null,"topic":null,"visibility":"private_channel","posting_policy":"all_members","team_id":null,"created_by_id":7,"allowed_poster_ids":[],"avatar_url":null,"avatar_icon":null,"avatar_color":null,"archived":false,"last_message_at":"2026-08-24T17:46:00Z","messages_count":1284,"members_count":2,"unread_count":4,"created_at":1778734800,"current_member":{"id":61,"role":"owner","notification_level":"all","muted_until":null,"muted":false,"pinned":true,"archived":false},"last_message":{"id":9007,"content":"Deploy is green, shipping now.","content_type":"text","attachments_count":1,"sender_id":12,"sender_name":"John Agent","is_own":false,"created_at":1778735160},"direct_partner":{"id":12,"name":"John Agent","thumbnail":"https://cdn.example.com/avatars/12.png"},"members":[{"id":61,"channel_id":30,"user_id":7,"role":"owner","notification_level":"all","muted_until":null,"muted":false,"pinned":true,"archived":false,"last_read_at":"2026-08-24T17:45:00Z","user":{"id":7,"name":"Jane Agent","thumbnail":"https://cdn.example.com/avatars/7.png","availability_status":"online"}}]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"channel":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"topic":{"type":"string"},"kind":{"type":"string","enum":["channel","direct","announcement"]},"visibility":{"type":"string","enum":["public_channel","private_channel"]},"posting_policy":{"type":"string","enum":["all_members","admins_only","allowed_list"]},"team_id":{"type":"integer"}}}},"required":["channel"]},"example":{"channel":{"name":"Sample Name","description":"A short description.","topic":"sample topic","kind":"channel","visibility":"public_channel","posting_policy":"all_members","team_id":1}}}}}},"delete":{"tags":["Internal Chat"],"operationId":"auto_delete_api_v1_accounts_account_id_internal_chat_channels_id","summary":"Delete channels","description":"Deletes the channel identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Success (no content)"},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/internal_chat/directs":{"post":{"tags":["Internal Chat"],"operationId":"auto_post_api_v1_accounts_account_id_internal_chat_directs","summary":"Create directs","description":"Creates a new direct from the request payload. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Direct channel found-or-created — returns the channel with members","content":{"application/json":{"schema":{"$ref":"#/components/schemas/internal_chat_channel_response"},"example":{"payload":{"id":30,"kind":"direct","name":null,"slug":null,"description":null,"topic":null,"visibility":"private_channel","posting_policy":"all_members","team_id":null,"created_by_id":7,"allowed_poster_ids":[],"avatar_url":null,"avatar_icon":null,"avatar_color":null,"archived":false,"last_message_at":"2026-08-24T17:46:00Z","messages_count":1284,"members_count":2,"unread_count":4,"created_at":1778734800,"current_member":{"id":61,"role":"owner","notification_level":"all","muted_until":null,"muted":false,"pinned":true,"archived":false},"last_message":{"id":9007,"content":"Deploy is green, shipping now.","content_type":"text","attachments_count":1,"sender_id":12,"sender_name":"John Agent","is_own":false,"created_at":1778735160},"direct_partner":{"id":12,"name":"John Agent","thumbnail":"https://cdn.example.com/avatars/12.png"},"members":[{"id":61,"channel_id":30,"user_id":7,"role":"owner","notification_level":"all","muted_until":null,"muted":false,"pinned":true,"archived":false,"last_read_at":"2026-08-24T17:45:00Z","user":{"id":7,"name":"Jane Agent","thumbnail":"https://cdn.example.com/avatars/7.png","availability_status":"online"}}]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["user_id"],"properties":{"user_id":{"type":"integer","description":"Target account user to open a DM with","example":12}}},"example":{"user_id":12}}}}}},"/api/v1/accounts/{account_id}/internal_chat/search":{"get":{"tags":["Internal Chat"],"operationId":"auto_get_api_v1_accounts_account_id_internal_chat_search","summary":"List search","description":"Returns the list of search visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"messages":{"type":"string"},"channels":{"type":"string"}}},"example":{"messages":"sample messages","channels":"sample channels"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"q","in":"query","required":true,"description":"Search term. A blank term returns empty message and channel lists.","schema":{"type":"string"},"example":"deploy"}]}},"/api/v1/accounts/{account_id}/internal_chat/unread":{"get":{"tags":["Internal Chat"],"operationId":"auto_get_api_v1_accounts_account_id_internal_chat_unread","summary":"Get unread","description":"Returns the unread identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Per-channel and total unread counts for the current user","content":{"application/json":{"schema":{"type":"object","properties":{"per_channel":{"type":"object","description":"Map of channel_id → unread message count","additionalProperties":{"type":"integer"},"example":{"12":3,"30":0}},"total":{"type":"integer","example":3}}},"example":{"per_channel":{"12":3,"30":0},"total":3}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/whatsapp_hub/groups/{id}/sync":{"post":{"tags":["WhatsApp Hub"],"operationId":"auto_post_api_v1_accounts_account_id_whatsapp_hub_groups_id_sync","summary":"Sync groups","description":"Performs the sync operation on the targeted group resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"inbox_id":{"type":"integer"},"logical_inbox_id":{"type":"integer"},"jid":{"type":"string"},"kind":{"type":"string","enum":["group","community","channel"],"description":"Container type of the WhatsApp entity."},"name":{"type":"string"},"topic":{"type":"string"},"role":{"type":"string","enum":["owner","admin","member","subscriber"],"description":"Operator/participant role within the group."},"is_parent":{"type":"boolean"},"is_default_sub":{"type":"boolean"},"community_jid":{"type":"string"},"photo_url":{"type":"string"},"invite_code":{"type":"string"},"participant_count":{"type":"integer"},"maestro_enabled":{"type":"boolean"},"settings":{"type":"string"},"greeting":{"type":"string"},"engagement":{"type":"string"},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"synced_at":{"type":"string","format":"date-time"},"archived_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"distribution":{"type":"object","properties":{"unit_id":{"type":"integer"},"unit_sequence":{"type":"string"},"unit_name":{"type":"string"},"distribution_id":{"type":"integer"},"distribution_name":{"type":["string","null"]}}},"participants":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"jid":{"type":"string"},"phone":{"type":"string"},"name":{"type":"string"},"display_name":{"type":"string"},"role":{"type":"string","enum":["agent","administrator"],"description":"Operator/participant role within the group."},"status":{"type":"string","enum":["active","left","removed","pending"],"description":"Membership status of the group participant."},"contact_id":{"type":"integer"},"messages_count":{"type":"integer"},"replies_count":{"type":"integer"},"reactions_given_count":{"type":"integer"},"reactions_received_count":{"type":"integer"},"poll_votes_count":{"type":"integer"},"button_clicks_count":{"type":"integer"},"media_count":{"type":"integer"},"engagement_score":{"type":"string"},"last_active_at":{"type":"string","format":"date-time"},"joined_at":{"type":"string","format":"date-time"}}}}}}}},"example":{"payload":{"id":1,"account_id":1,"inbox_id":1,"logical_inbox_id":1,"jid":"sample jid","kind":"group","name":"Sample Name","topic":"sample topic","role":"owner","is_parent":true,"is_default_sub":true,"community_jid":"sample community jid","photo_url":"https://example.com/resource","invite_code":"sample invite code","participant_count":5,"maestro_enabled":true,"settings":"sample settings","greeting":"sample greeting","engagement":"sample engagement","custom_attributes":{},"synced_at":"2026-01-15T10:30:00.000Z","archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","distribution":{"unit_id":1,"unit_sequence":"sample unit sequence","unit_name":"sample unit name","distribution_id":1,"distribution_name":"sample distribution name"},"participants":[{"id":1,"jid":"sample jid","phone":"+5511999998888","name":"Sample Name","display_name":"sample display name","role":"agent","status":"active","contact_id":1,"messages_count":5,"replies_count":5,"reactions_given_count":5,"reactions_received_count":5,"poll_votes_count":5,"button_clicks_count":5,"media_count":5,"engagement_score":"sample engagement score","last_active_at":"2026-01-15T10:30:00.000Z","joined_at":"2026-01-15T10:30:00.000Z"}]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/whatsapp_hub/groups/{id}/leave":{"post":{"tags":["WhatsApp Hub"],"operationId":"auto_post_api_v1_accounts_account_id_whatsapp_hub_groups_id_leave","summary":"Leave groups","description":"Performs the leave operation on the targeted group resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"inbox_id":{"type":"integer"},"logical_inbox_id":{"type":"integer"},"jid":{"type":"string"},"kind":{"type":"string","enum":["group","community","channel"],"description":"Container type of the WhatsApp entity."},"name":{"type":"string"},"topic":{"type":"string"},"role":{"type":"string","enum":["owner","admin","member","subscriber"],"description":"Operator/participant role within the group."},"is_parent":{"type":"boolean"},"is_default_sub":{"type":"boolean"},"community_jid":{"type":"string"},"photo_url":{"type":"string"},"invite_code":{"type":"string"},"participant_count":{"type":"integer"},"maestro_enabled":{"type":"boolean"},"settings":{"type":"string"},"greeting":{"type":"string"},"engagement":{"type":"string"},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"synced_at":{"type":"string","format":"date-time"},"archived_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"distribution":{"type":"object","properties":{"unit_id":{"type":"integer"},"unit_sequence":{"type":"string"},"unit_name":{"type":"string"},"distribution_id":{"type":"integer"},"distribution_name":{"type":["string","null"]}}},"participants":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"jid":{"type":"string"},"phone":{"type":"string"},"name":{"type":"string"},"display_name":{"type":"string"},"role":{"type":"string","enum":["agent","administrator"],"description":"Operator/participant role within the group."},"status":{"type":"string","enum":["active","left","removed","pending"],"description":"Membership status of the group participant."},"contact_id":{"type":"integer"},"messages_count":{"type":"integer"},"replies_count":{"type":"integer"},"reactions_given_count":{"type":"integer"},"reactions_received_count":{"type":"integer"},"poll_votes_count":{"type":"integer"},"button_clicks_count":{"type":"integer"},"media_count":{"type":"integer"},"engagement_score":{"type":"string"},"last_active_at":{"type":"string","format":"date-time"},"joined_at":{"type":"string","format":"date-time"}}}}}}}},"example":{"payload":{"id":1,"account_id":1,"inbox_id":1,"logical_inbox_id":1,"jid":"sample jid","kind":"group","name":"Sample Name","topic":"sample topic","role":"owner","is_parent":true,"is_default_sub":true,"community_jid":"sample community jid","photo_url":"https://example.com/resource","invite_code":"sample invite code","participant_count":5,"maestro_enabled":true,"settings":"sample settings","greeting":"sample greeting","engagement":"sample engagement","custom_attributes":{},"synced_at":"2026-01-15T10:30:00.000Z","archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","distribution":{"unit_id":1,"unit_sequence":"sample unit sequence","unit_name":"sample unit name","distribution_id":1,"distribution_name":"sample distribution name"},"participants":[{"id":1,"jid":"sample jid","phone":"+5511999998888","name":"Sample Name","display_name":"sample display name","role":"agent","status":"active","contact_id":1,"messages_count":5,"replies_count":5,"reactions_given_count":5,"reactions_received_count":5,"poll_votes_count":5,"button_clicks_count":5,"media_count":5,"engagement_score":"sample engagement score","last_active_at":"2026-01-15T10:30:00.000Z","joined_at":"2026-01-15T10:30:00.000Z"}]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/whatsapp_hub/groups/{id}/participants":{"post":{"tags":["WhatsApp Hub"],"operationId":"auto_post_api_v1_accounts_account_id_whatsapp_hub_groups_id_participants","summary":"Participants groups","description":"Performs the participants operation on the targeted group resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"string"}}},"example":{"payload":"sample payload"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"participant_action":{"type":"string"},"phones":{"type":"array","items":{"type":"string"}}}},"example":{"participant_action":"sample participant action","phones":["+5511999998888"]}}}}}},"/api/v1/accounts/{account_id}/whatsapp_hub/groups/{id}/invite":{"get":{"tags":["WhatsApp Hub"],"operationId":"auto_get_api_v1_accounts_account_id_whatsapp_hub_groups_id_invite","summary":"Invite groups","description":"Performs the invite operation on the targeted group resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"string"}}},"example":{"payload":"sample payload"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/whatsapp_hub/groups/{id}/regenerate_invite":{"post":{"tags":["WhatsApp Hub"],"operationId":"auto_post_api_v1_accounts_account_id_whatsapp_hub_groups_id_regenerate_invite","summary":"Regenerate invite groups","description":"Performs the regenerate invite operation on the targeted group resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"string"}}},"example":{"payload":"sample payload"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/whatsapp_hub/groups/{id}/photo":{"post":{"tags":["WhatsApp Hub"],"operationId":"auto_post_api_v1_accounts_account_id_whatsapp_hub_groups_id_photo","summary":"Photo groups","description":"Performs the photo operation on the targeted group resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"string"}}},"example":{"payload":"sample payload"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"image":{"type":"string"}}},"example":{"image":"sample image"}}}}}},"/api/v1/accounts/{account_id}/whatsapp_hub/groups/{id}/remove_photo":{"post":{"tags":["WhatsApp Hub"],"operationId":"auto_post_api_v1_accounts_account_id_whatsapp_hub_groups_id_remove_photo","summary":"Remove photo groups","description":"Performs the remove photo operation on the targeted group resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"string"}}},"example":{"payload":"sample payload"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/whatsapp_hub/groups/{id}/archive":{"post":{"tags":["WhatsApp Hub"],"operationId":"auto_post_api_v1_accounts_account_id_whatsapp_hub_groups_id_archive","summary":"Archive groups","description":"Performs the archive operation on the targeted group resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"inbox_id":{"type":"integer"},"logical_inbox_id":{"type":"integer"},"jid":{"type":"string"},"kind":{"type":"string","enum":["group","community","channel"],"description":"Container type of the WhatsApp entity."},"name":{"type":"string"},"topic":{"type":"string"},"role":{"type":"string","enum":["owner","admin","member","subscriber"],"description":"Operator/participant role within the group."},"is_parent":{"type":"boolean"},"is_default_sub":{"type":"boolean"},"community_jid":{"type":"string"},"photo_url":{"type":"string"},"invite_code":{"type":"string"},"participant_count":{"type":"integer"},"maestro_enabled":{"type":"boolean"},"settings":{"type":"string"},"greeting":{"type":"string"},"engagement":{"type":"string"},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"synced_at":{"type":"string","format":"date-time"},"archived_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"distribution":{"type":"object","properties":{"unit_id":{"type":"integer"},"unit_sequence":{"type":"string"},"unit_name":{"type":"string"},"distribution_id":{"type":"integer"},"distribution_name":{"type":["string","null"]}}},"participants":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"jid":{"type":"string"},"phone":{"type":"string"},"name":{"type":"string"},"display_name":{"type":"string"},"role":{"type":"string","enum":["agent","administrator"],"description":"Operator/participant role within the group."},"status":{"type":"string","enum":["active","left","removed","pending"],"description":"Membership status of the group participant."},"contact_id":{"type":"integer"},"messages_count":{"type":"integer"},"replies_count":{"type":"integer"},"reactions_given_count":{"type":"integer"},"reactions_received_count":{"type":"integer"},"poll_votes_count":{"type":"integer"},"button_clicks_count":{"type":"integer"},"media_count":{"type":"integer"},"engagement_score":{"type":"string"},"last_active_at":{"type":"string","format":"date-time"},"joined_at":{"type":"string","format":"date-time"}}}}}}}},"example":{"payload":{"id":1,"account_id":1,"inbox_id":1,"logical_inbox_id":1,"jid":"sample jid","kind":"group","name":"Sample Name","topic":"sample topic","role":"owner","is_parent":true,"is_default_sub":true,"community_jid":"sample community jid","photo_url":"https://example.com/resource","invite_code":"sample invite code","participant_count":5,"maestro_enabled":true,"settings":"sample settings","greeting":"sample greeting","engagement":"sample engagement","custom_attributes":{},"synced_at":"2026-01-15T10:30:00.000Z","archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","distribution":{"unit_id":1,"unit_sequence":"sample unit sequence","unit_name":"sample unit name","distribution_id":1,"distribution_name":"sample distribution name"},"participants":[{"id":1,"jid":"sample jid","phone":"+5511999998888","name":"Sample Name","display_name":"sample display name","role":"agent","status":"active","contact_id":1,"messages_count":5,"replies_count":5,"reactions_given_count":5,"reactions_received_count":5,"poll_votes_count":5,"button_clicks_count":5,"media_count":5,"engagement_score":"sample engagement score","last_active_at":"2026-01-15T10:30:00.000Z","joined_at":"2026-01-15T10:30:00.000Z"}]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/whatsapp_hub/groups/{id}/restore":{"post":{"tags":["WhatsApp Hub"],"operationId":"auto_post_api_v1_accounts_account_id_whatsapp_hub_groups_id_restore","summary":"Restore groups","description":"Performs the restore operation on the targeted group resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"inbox_id":{"type":"integer"},"logical_inbox_id":{"type":"integer"},"jid":{"type":"string"},"kind":{"type":"string","enum":["group","community","channel"],"description":"Container type of the WhatsApp entity."},"name":{"type":"string"},"topic":{"type":"string"},"role":{"type":"string","enum":["owner","admin","member","subscriber"],"description":"Operator/participant role within the group."},"is_parent":{"type":"boolean"},"is_default_sub":{"type":"boolean"},"community_jid":{"type":"string"},"photo_url":{"type":"string"},"invite_code":{"type":"string"},"participant_count":{"type":"integer"},"maestro_enabled":{"type":"boolean"},"settings":{"type":"string"},"greeting":{"type":"string"},"engagement":{"type":"string"},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"synced_at":{"type":"string","format":"date-time"},"archived_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"distribution":{"type":"object","properties":{"unit_id":{"type":"integer"},"unit_sequence":{"type":"string"},"unit_name":{"type":"string"},"distribution_id":{"type":"integer"},"distribution_name":{"type":["string","null"]}}},"participants":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"jid":{"type":"string"},"phone":{"type":"string"},"name":{"type":"string"},"display_name":{"type":"string"},"role":{"type":"string","enum":["agent","administrator"],"description":"Operator/participant role within the group."},"status":{"type":"string","enum":["active","left","removed","pending"],"description":"Membership status of the group participant."},"contact_id":{"type":"integer"},"messages_count":{"type":"integer"},"replies_count":{"type":"integer"},"reactions_given_count":{"type":"integer"},"reactions_received_count":{"type":"integer"},"poll_votes_count":{"type":"integer"},"button_clicks_count":{"type":"integer"},"media_count":{"type":"integer"},"engagement_score":{"type":"string"},"last_active_at":{"type":"string","format":"date-time"},"joined_at":{"type":"string","format":"date-time"}}}}}}}},"example":{"payload":{"id":1,"account_id":1,"inbox_id":1,"logical_inbox_id":1,"jid":"sample jid","kind":"group","name":"Sample Name","topic":"sample topic","role":"owner","is_parent":true,"is_default_sub":true,"community_jid":"sample community jid","photo_url":"https://example.com/resource","invite_code":"sample invite code","participant_count":5,"maestro_enabled":true,"settings":"sample settings","greeting":"sample greeting","engagement":"sample engagement","custom_attributes":{},"synced_at":"2026-01-15T10:30:00.000Z","archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","distribution":{"unit_id":1,"unit_sequence":"sample unit sequence","unit_name":"sample unit name","distribution_id":1,"distribution_name":"sample distribution name"},"participants":[{"id":1,"jid":"sample jid","phone":"+5511999998888","name":"Sample Name","display_name":"sample display name","role":"agent","status":"active","contact_id":1,"messages_count":5,"replies_count":5,"reactions_given_count":5,"reactions_received_count":5,"poll_votes_count":5,"button_clicks_count":5,"media_count":5,"engagement_score":"sample engagement score","last_active_at":"2026-01-15T10:30:00.000Z","joined_at":"2026-01-15T10:30:00.000Z"}]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/whatsapp_hub/groups/{id}/recompute_engagement":{"post":{"tags":["WhatsApp Hub"],"operationId":"auto_post_api_v1_accounts_account_id_whatsapp_hub_groups_id_recompute_engagement","summary":"Recompute engagement groups","description":"Performs the recompute engagement operation on the targeted group resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"202":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"status":{"type":"string","example":"queued","enum":["queued"],"description":"Acknowledges the async engagement recompute was enqueued."}}}}},"example":{"payload":{"status":"queued"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/whatsapp_hub/groups/{id}/open_conversation":{"post":{"tags":["WhatsApp Hub"],"operationId":"auto_post_api_v1_accounts_account_id_whatsapp_hub_groups_id_open_conversation","summary":"Open conversation groups","description":"Performs the open conversation operation on the targeted group resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"string"}}},"example":{"payload":"sample payload"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/whatsapp_hub/groups/{id}/member_activity":{"get":{"tags":["WhatsApp Hub"],"operationId":"auto_get_api_v1_accounts_account_id_whatsapp_hub_groups_id_member_activity","summary":"Member activity groups","description":"Performs the member activity operation on the targeted group resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"events":{"type":"string"}}}}},"example":{"payload":{"events":"sample events"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/whatsapp_hub/groups/{id}/participant_operation_scope":{"get":{"tags":["WhatsApp Hub"],"operationId":"auto_get_api_v1_accounts_account_id_whatsapp_hub_groups_id_participant_operation_scope","summary":"Read the group's participant-operation scope","description":"Requires the WhatsApp Hub feature, the existing group-read policy and operational inbox access. Reads local WazMeow authority for this account's connection and group, including conflicting operations from another principal. No online WhatsApp Client, roster refresh, reservation, submit or release is requested. A resolvable local physical binding and a valid authority database read are still required. Unavailable or malformed upstream responses return 503, never an idle or null scope. This observation is not permission to mutate participants; writes must reserve authority independently. A confirmation_pending operation has no guaranteed completion deadline. Other groups, messages and unrelated group settings remain available.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Credential-free local scope. idle means no active authority was found by a successful bound read; it does not confirm a remote participant effect. Clients retain their last known scope when a later read fails and discard responses for a previous account, inbox or group.","headers":{"Cache-Control":{"description":"The observation is never cached.","schema":{"type":"string","enum":["no-store"]},"example":"no-store"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["payload"],"properties":{"payload":{"type":"object","additionalProperties":false,"required":["contract_version","scope_ref","group_jid","scope_revision","blocked","active_state","operation_visible_to_caller"],"properties":{"contract_version":{"type":"string","enum":["group-participant-operation.v1"]},"scope_ref":{"type":"string","description":"Opaque physical scope reference; contains no account identifier or credential."},"group_jid":{"type":"string","description":"The literal requested group JID."},"scope_revision":{"type":"integer","description":"Revision supplied by the local gateway authority."},"blocked":{"type":"boolean","description":"True while the group authority is held or fenced."},"active_state":{"type":"string","enum":["idle","reserved","in_flight","confirmation_pending","fenced"],"description":"reserved and in_flight describe work in progress. confirmation_pending requires waiting for evidence, without automatic resending or age-based release. fenced denotes unavailable admission, not a confirmed remote effect."},"operation_ref":{"type":"string","description":"Optional opaque operation identifier. It is not a caller key or permission to retrieve another principal's operation."},"operation_visible_to_caller":{"type":"boolean","description":"Whether the held operation belongs to the authenticated gateway principal."}}}}},"example":{"payload":{"contract_version":"group-participant-operation.v1","scope_ref":"fixture-scope-ref","group_jid":"120363000000001@g.us","scope_revision":1,"blocked":true,"active_state":"confirmation_pending","operation_ref":"fixture-operation-ref","operation_visible_to_caller":true}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"503":{"description":"The scope cannot be read safely: binding, storage, authority or transport is unavailable, or the upstream response does not match the contract. No absence or remote success is inferred. Local authentication and account/inbox authorization failures retain their existing responses.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","enum":["participant_operation_scope_unavailable"]}}},"example":{"error":"participant_operation_scope_unavailable"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"description":"Authenticated Chatwoot account.","schema":{"type":"integer"}},{"name":"id","in":"path","required":true,"description":"Account-scoped mirrored group identifier. Its stored inbox selects the connection.","schema":{"type":"integer"}}]}},"/api/v1/accounts/{account_id}/whatsapp_hub/groups/{id}/history/originals":{"get":{"tags":["WhatsApp Hub"],"operationId":"auto_get_api_v1_accounts_account_id_whatsapp_hub_groups_id_history_originals","summary":"Read a page of locally observed group originals","description":"Reads only the authenticated account's authorized group and its stored physical WhatsApp Web connection. Requires the WhatsApp Hub feature, native whatsapp_hub_manage permission when an effective custom role exists, operational inbox access, the group read policy and the inbox read policy. Hybrid equivalent access does not select another physical connection. AgentBot access is not granted. Only limit, cursor, from_me and preview are accepted in the query; no request body is accepted. An entirely empty query uses the defaults. The raw query is limited to 16384 bytes; duplicate or unknown keys, empty segments in a nonempty query and nonscalar values are rejected. Client identity inputs cannot choose an inbox, principal, provider or token. Returns a closed browser projection without credentials, personal author data or a raw gateway envelope. Preview is opt-in and never synthesized. AVAILABLE describes a local observation, not remote retention, delivery or permission to send. This read does not sync, enqueue a job, submit messages or grant company authorship. Every response uses Cache-Control no-store.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"A validated local page containing only AVAILABLE originals. A real empty page may retain has_more and its producer cursor; upstream failure is never represented as that empty page.","headers":{"Cache-Control":{"description":"History responses are never cached, including refusals and errors.","schema":{"type":"string","enum":["no-store"]},"example":"no-store"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["payload"],"properties":{"payload":{"type":"object","additionalProperties":false,"required":["group_id","items","remote_retention_verified","scanned_count","has_more"],"properties":{"group_id":{"type":"integer","description":"Authorized account-scoped group row identifier."},"items":{"type":"array","maxItems":100,"description":"Distinct AVAILABLE originals, at most the requested limit, in producer key order. Key order is not chronological order and does not select the company's latest messages.","items":{"type":"object","additionalProperties":false,"required":["message_id","availability","message_timestamp","from_me","kind"],"properties":{"message_id":{"type":"string","minLength":1,"maxLength":128,"not":{"pattern":"[\\u0000-\\u001F\\u007F-\\u009F]"},"description":"Literal UTF-8 message identifier, 1 through 128 bytes, without Unicode control characters. The server enforces the byte limit in addition to this character bound; identifiers are not trimmed or normalized."},"availability":{"type":"string","enum":["AVAILABLE"],"description":"A local original was observed; this is not proof of remote retention, delivery or permission to send."},"message_timestamp":{"type":"integer","minimum":1,"maximum":18446744073709551615,"description":"Positive unsigned 64-bit timestamp supplied by the producer."},"from_me":{"type":"boolean","description":"Whether the stored original belongs to the paired account; this does not prove historical company authorship."},"kind":{"type":"string","enum":["text","image","video","document","audio","sticker","view_once","other"],"description":"Container type of the WhatsApp entity."},"preview":{"type":"object","additionalProperties":false,"required":["text","truncated"],"properties":{"text":{"type":"string","minLength":1,"maxLength":256,"description":"UTF-8 producer preview, bounded in characters rather than bytes."},"truncated":{"type":"boolean","description":"Whether the producer truncated the preview."}},"description":"Present only after preview opt-in and only for text, image, video or document when supplied by the producer."}},"if":{"properties":{"kind":{"enum":["audio","sticker","view_once","other"],"description":"Container type of the WhatsApp entity."}}},"then":{"not":{"required":["preview"]}}}},"remote_retention_verified":{"type":"boolean","enum":[false],"description":"The local read does not verify remote retention, including any 90-day retention promise."},"scanned_count":{"type":"integer","minimum":0,"maximum":200,"description":"Number scanned by the producer, at least the returned item count."},"has_more":{"type":"boolean","description":"Whether the producer supplied a continuation; an empty items page may still have a continuation."},"next_cursor":{"type":"string","minLength":1,"maxLength":4096,"description":"Literal UTF-8 producer cursor, at most 4096 bytes. Required exactly when has_more is true, with a positive scanned_count, and different from the requested cursor. Never synthesized or normalized."}},"if":{"properties":{"has_more":{"const":true}}},"then":{"required":["next_cursor"],"properties":{"scanned_count":{"minimum":1}}},"else":{"not":{"required":["next_cursor"]}}}}},"example":{"payload":{"group_id":42,"items":[{"message_id":"example-text-001","availability":"AVAILABLE","message_timestamp":1788696000,"from_me":true,"kind":"text","preview":{"text":"Example preview","truncated":false}}],"remote_retention_verified":false,"scanned_count":3,"has_more":true,"next_cursor":"cursor-page-2"}}}}},"401":{"description":"Native user/token/account or Pundit authorization denial retains its existing envelope and error text, including suspended accounts and AgentBot refusal. A typed WazMeow 401 is projected as unauthorized. An inbox or group policy denial remains 401 rather than being rewritten as a reader availability error.","headers":{"Cache-Control":{"description":"History responses are never cached, including refusals and errors.","schema":{"type":"string","enum":["no-store"]},"example":"no-store"}},"content":{"application/json":{"schema":{"oneOf":[{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","description":"Native authorization message, localized where applicable, or the literal gateway code unauthorized."}}},{"type":"object","additionalProperties":false,"required":["errors"],"properties":{"errors":{"type":"array","minItems":1,"maxItems":1,"description":"Existing native user-authentication refusal when no current user is authenticated.","items":{"type":"string"}}}}]},"examples":{"unauthenticated":{"value":{"errors":["You need to sign in or sign up before continuing."]}},"policy_denied":{"value":{"error":"You are not authorized to do this action"}},"gateway_denied":{"value":{"error":"unauthorized"}},"bot_denied":{"value":{"error":"Access to this endpoint is not authorized for bots"}}}}}},"404":{"description":"The group is missing or belongs to another account, or its physical inbox is outside the actor's operational scope. The native operational guard runs before the group predicate and inbox policy.","headers":{"Cache-Control":{"description":"History responses are never cached, including refusals and errors.","schema":{"type":"string","enum":["no-store"]},"example":"no-store"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","enum":["Resource could not be found"]}}},"example":{"error":"Resource could not be found"}}}},"400":{"description":"Invalid history input, including unknown or duplicate query keys, empty segments in a nonempty query, wrong scalar types, bounds violations, a nonempty GET body or invalid check JSON. The raw query limit is 16384 bytes and the check body limit is 32768 bytes. All 400 responses for these operations, including malformed raw queries rejected before controller callbacks, are normalized to this closed JSON envelope with Content-Type application/json; charset=utf-8 and Cache-Control no-store.","headers":{"Cache-Control":{"description":"History responses are never cached, including refusals and errors.","schema":{"type":"string","enum":["no-store"]},"example":"no-store"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","enum":["invalid_history_read_request"]}}},"example":{"error":"invalid_history_read_request"}}}},"403":{"description":"Missing effective native whatsapp_hub_manage permission, disabled Hub feature or disabled account token API access retains its native 403. An authorized physical channel that is not WhatsApp Web, or an unavailable reader binding, returns history_read_scope_unavailable.","headers":{"Cache-Control":{"description":"History responses are never cached, including refusals and errors.","schema":{"type":"string","enum":["no-store"]},"example":"no-store"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","enum":["forbidden","feature_not_enabled","API access is not enabled for this account","history_read_scope_unavailable"]}}},"examples":{"role_denied":{"value":{"error":"forbidden"}},"feature_disabled":{"value":{"error":"feature_not_enabled"}},"api_disabled":{"value":{"error":"API access is not enabled for this account"}},"scope_unavailable":{"value":{"error":"history_read_scope_unavailable"}}}}}},"500":{"description":"The producer returned the typed list serialization failure. No raw error detail is exposed.","headers":{"Cache-Control":{"description":"History responses are never cached, including refusals and errors.","schema":{"type":"string","enum":["no-store"]},"example":"no-store"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","enum":["history_read_serialization_failed"]}}},"example":{"error":"history_read_serialization_failed"}}}},"503":{"description":"Transport, configuration, database or local-store unavailability, or an invalid upstream JSON/envelope/DTO/status. Errors are sanitized and never returned as a successful empty result.","headers":{"Cache-Control":{"description":"History responses are never cached, including refusals and errors.","schema":{"type":"string","enum":["no-store"]},"example":"no-store"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","enum":["history_read_unavailable","history_read_contract_invalid"]}}},"examples":{"unavailable":{"value":{"error":"history_read_unavailable"}},"invalid_contract":{"value":{"error":"history_read_contract_invalid"}}}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"description":"Account to which the authenticated user must belong, with API access enabled for token requests.","schema":{"type":"integer"},"example":1},{"name":"id","in":"path","required":true,"description":"Group row in this account. Its stored physical inbox and Web connection determine the read scope.","schema":{"type":"integer"},"example":42},{"name":"limit","in":"query","required":false,"description":"Canonical decimal string from 1 through 100. Leading zeros, signs and whitespace are rejected.","schema":{"type":"string","pattern":"^([1-9]|[1-9][0-9]|100)$","not":{"pattern":"[^0-9]"},"default":"25"},"example":"25"},{"name":"cursor","in":"query","required":false,"allowEmptyValue":true,"description":"Optional literal UTF-8 cursor, including an empty value, with a server-enforced maximum of 4096 bytes.","schema":{"type":"string","maxLength":4096},"example":"cursor-page-1"},{"name":"from_me","in":"query","required":false,"description":"Literal case-sensitive filter for the paired account's stored originals; does not establish company authorship.","schema":{"type":"string","enum":["true","false"]},"example":"true"},{"name":"preview","in":"query","required":false,"description":"Literal case-sensitive query string. Opts into a bounded preview only when the producer supplies one.","schema":{"type":"string","enum":["true","false"],"default":"false"},"example":"true"}]}},"/api/v1/accounts/{account_id}/whatsapp_hub/groups/{id}/history/originals/check":{"post":{"tags":["WhatsApp Hub"],"operationId":"auto_post_api_v1_accounts_account_id_whatsapp_hub_groups_id_history_originals_check","summary":"Check specific group original identifiers without sending","description":"Applies the same native account, Hub, custom-role, operational, group and inbox read authority as the page read, using only the group's stored physical Web connection. AgentBot access is not granted. Accepts application/json with no wrapper and no query parameters. The closed body is limited to 32768 bytes and contains 1 through 100 distinct literal message identifiers, plus an optional strict JSON boolean preview. Unknown keys and wrong types are rejected, including client-supplied identity, principal, proof or provider fields. Results preserve the requested ID order. NOT_DEMONSTRATED contains only the identifier and availability. This check does not submit, release or send an identifier, prove historical company authorship, verify delivery or promise remote retention. No pagination metadata or raw gateway envelope is returned. Every response uses Cache-Control no-store.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Ordered local evidence for exactly the requested identifiers, without pagination fields.","headers":{"Cache-Control":{"description":"History responses are never cached, including refusals and errors.","schema":{"type":"string","enum":["no-store"]},"example":"no-store"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["payload"],"properties":{"payload":{"type":"object","additionalProperties":false,"required":["group_id","items","remote_retention_verified"],"properties":{"group_id":{"type":"integer","description":"Authorized account-scoped group row identifier."},"items":{"type":"array","minItems":1,"maxItems":100,"description":"Exactly one result per requested identifier, preserving the requested order, including NOT_DEMONSTRATED results.","items":{"oneOf":[{"type":"object","additionalProperties":false,"required":["message_id","availability","message_timestamp","from_me","kind"],"properties":{"message_id":{"type":"string","minLength":1,"maxLength":128,"not":{"pattern":"[\\u0000-\\u001F\\u007F-\\u009F]"},"description":"Literal UTF-8 message identifier, 1 through 128 bytes, without Unicode control characters. The server enforces the byte limit in addition to this character bound; identifiers are not trimmed or normalized."},"availability":{"type":"string","enum":["AVAILABLE"],"description":"A local original was observed; this is not proof of remote retention, delivery or permission to send."},"message_timestamp":{"type":"integer","minimum":1,"maximum":18446744073709551615,"description":"Positive unsigned 64-bit timestamp supplied by the producer."},"from_me":{"type":"boolean","description":"Whether the stored original belongs to the paired account; this does not prove historical company authorship."},"kind":{"type":"string","enum":["text","image","video","document","audio","sticker","view_once","other"],"description":"Container type of the WhatsApp entity."},"preview":{"type":"object","additionalProperties":false,"required":["text","truncated"],"properties":{"text":{"type":"string","minLength":1,"maxLength":256,"description":"UTF-8 producer preview, bounded in characters rather than bytes."},"truncated":{"type":"boolean","description":"Whether the producer truncated the preview."}},"description":"Present only after preview opt-in and only for text, image, video or document when supplied by the producer."}},"if":{"properties":{"kind":{"enum":["audio","sticker","view_once","other"],"description":"Container type of the WhatsApp entity."}}},"then":{"not":{"required":["preview"]}}},{"type":"object","additionalProperties":false,"required":["message_id","availability"],"properties":{"message_id":{"type":"string","minLength":1,"maxLength":128,"not":{"pattern":"[\\u0000-\\u001F\\u007F-\\u009F]"},"description":"Literal UTF-8 message identifier, 1 through 128 bytes, without Unicode control characters. The server enforces the byte limit in addition to this character bound; identifiers are not trimmed or normalized."},"availability":{"type":"string","enum":["NOT_DEMONSTRATED"],"description":"The local read did not demonstrate an original for this requested identifier."}}}]}},"remote_retention_verified":{"type":"boolean","enum":[false],"description":"The local read does not verify remote retention or delivery."}}}}},"example":{"payload":{"group_id":42,"items":[{"message_id":"example-text-001","availability":"AVAILABLE","message_timestamp":1788696000,"from_me":true,"kind":"text","preview":{"text":"Example preview","truncated":false}},{"message_id":"example-missing-002","availability":"NOT_DEMONSTRATED","message_timestamp":1,"from_me":true,"kind":"text","preview":{"text":"sample text","truncated":true}}],"remote_retention_verified":false}}}}},"401":{"description":"Native user/token/account or Pundit authorization denial retains its existing envelope and error text, including suspended accounts and AgentBot refusal. A typed WazMeow 401 is projected as unauthorized. An inbox or group policy denial remains 401 rather than being rewritten as a reader availability error.","headers":{"Cache-Control":{"description":"History responses are never cached, including refusals and errors.","schema":{"type":"string","enum":["no-store"]},"example":"no-store"}},"content":{"application/json":{"schema":{"oneOf":[{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","description":"Native authorization message, localized where applicable, or the literal gateway code unauthorized."}}},{"type":"object","additionalProperties":false,"required":["errors"],"properties":{"errors":{"type":"array","minItems":1,"maxItems":1,"description":"Existing native user-authentication refusal when no current user is authenticated.","items":{"type":"string"}}}}]},"examples":{"unauthenticated":{"value":{"errors":["You need to sign in or sign up before continuing."]}},"policy_denied":{"value":{"error":"You are not authorized to do this action"}},"gateway_denied":{"value":{"error":"unauthorized"}},"bot_denied":{"value":{"error":"Access to this endpoint is not authorized for bots"}}}}}},"404":{"description":"The group is missing or belongs to another account, or its physical inbox is outside the actor's operational scope. The native operational guard runs before the group predicate and inbox policy.","headers":{"Cache-Control":{"description":"History responses are never cached, including refusals and errors.","schema":{"type":"string","enum":["no-store"]},"example":"no-store"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","enum":["Resource could not be found"]}}},"example":{"error":"Resource could not be found"}}}},"400":{"description":"Invalid history input, including unknown or duplicate query keys, empty segments in a nonempty query, wrong scalar types, bounds violations, a nonempty GET body or invalid check JSON. The raw query limit is 16384 bytes and the check body limit is 32768 bytes. All 400 responses for these operations, including malformed raw queries rejected before controller callbacks, are normalized to this closed JSON envelope with Content-Type application/json; charset=utf-8 and Cache-Control no-store.","headers":{"Cache-Control":{"description":"History responses are never cached, including refusals and errors.","schema":{"type":"string","enum":["no-store"]},"example":"no-store"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","enum":["invalid_history_read_request"]}}},"example":{"error":"invalid_history_read_request"}}}},"403":{"description":"Missing effective native whatsapp_hub_manage permission, disabled Hub feature or disabled account token API access retains its native 403. An authorized physical channel that is not WhatsApp Web, or an unavailable reader binding, returns history_read_scope_unavailable.","headers":{"Cache-Control":{"description":"History responses are never cached, including refusals and errors.","schema":{"type":"string","enum":["no-store"]},"example":"no-store"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","enum":["forbidden","feature_not_enabled","API access is not enabled for this account","history_read_scope_unavailable"]}}},"examples":{"role_denied":{"value":{"error":"forbidden"}},"feature_disabled":{"value":{"error":"feature_not_enabled"}},"api_disabled":{"value":{"error":"API access is not enabled for this account"}},"scope_unavailable":{"value":{"error":"history_read_scope_unavailable"}}}}}},"503":{"description":"Transport, configuration, database or local-store unavailability, or an invalid upstream JSON/envelope/DTO/status. Errors are sanitized and never returned as a successful empty result.","headers":{"Cache-Control":{"description":"History responses are never cached, including refusals and errors.","schema":{"type":"string","enum":["no-store"]},"example":"no-store"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","enum":["history_read_unavailable","history_read_contract_invalid"]}}},"examples":{"unavailable":{"value":{"error":"history_read_unavailable"}},"invalid_contract":{"value":{"error":"history_read_contract_invalid"}}}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"description":"Account to which the authenticated user must belong, with API access enabled for token requests.","schema":{"type":"integer"},"example":1},{"name":"id","in":"path","required":true,"description":"Group row in this account. Its stored physical inbox and Web connection determine the read scope.","schema":{"type":"integer"},"example":42}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["message_ids"],"properties":{"message_ids":{"type":"array","minItems":1,"maxItems":100,"uniqueItems":true,"items":{"type":"string","minLength":1,"maxLength":128,"not":{"pattern":"[\\u0000-\\u001F\\u007F-\\u009F]"},"description":"Literal UTF-8 message identifier, 1 through 128 bytes, without Unicode control characters. The server enforces the byte limit in addition to this character bound; identifiers are not trimmed or normalized."}},"preview":{"type":"boolean","default":false,"description":"Strict JSON boolean opting into a producer preview for eligible available originals."}}},"example":{"message_ids":["example-text-001","example-missing-002"],"preview":true}}}}}},"/api/v1/accounts/{account_id}/whatsapp_hub/groups/{id}/history/originals/automatic":{"get":{"tags":["WhatsApp Hub"],"operationId":"auto_get_api_v1_accounts_account_id_whatsapp_hub_groups_id_history_originals_automatic","summary":"Select the latest proven originals from the current prospective company capture","description":"Runs the native account, Hub, custom-role, operational, group and inbox read guards, validates limit and preview, and uses the group's stored physical Web connection. Only these two query keys are accepted; no body, cursor, from_me, selection, proof or identity inputs are accepted. An entirely empty query uses the defaults. Raw query input is limited to 16384 bytes; duplicate keys, empty segments in a nonempty query and nonscalar values are rejected. Requires the entire explicitly activated prospective capture, at most 200 admissions and 4 MiB of evidence, with its Account continuity, native admissions, current originals and ACK proofs intact. Pending, missing, changed or excessive evidence refuses the entire selection instead of choosing only surviving Messages. Local cuts bracket remote reads; preview additionally rechecks all proofs. This proves only the stated prospective window, never older company history. With no active capture, the typed history_company_proof_unavailable refusal remains. Native denials, input failures and transport/contract failures retain their own responses. This read does not construct a successful empty selection, submit, send, sync or enqueue anything. It does not grant AgentBot access. Every response uses Cache-Control no-store.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Complete current prospective window was checked and the latest requested originals selected. No send is performed.","headers":{"Cache-Control":{"description":"History responses are never cached, including refusals and errors.","schema":{"type":"string","enum":["no-store"]},"example":"no-store"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["payload"],"properties":{"payload":{"type":"object","additionalProperties":false,"required":["group_id","items","remote_retention_verified","coverage"],"properties":{"group_id":{"type":"integer","description":"Authorized account-scoped group row identifier."},"items":{"type":"array","minItems":1,"maxItems":100,"description":"The latest requested originals from the complete proven prospective capture, ordered by server ACK descending then literal ID ascending.","items":{"type":"object","additionalProperties":false,"required":["message_id","availability","message_timestamp","from_me","kind"],"properties":{"message_id":{"type":"string","minLength":1,"maxLength":128,"not":{"pattern":"[\\u0000-\\u001F\\u007F-\\u009F]"},"description":"Literal UTF-8 message identifier, 1 through 128 bytes, without Unicode control characters. The server enforces the byte limit in addition to this character bound; identifiers are not trimmed or normalized."},"availability":{"type":"string","enum":["AVAILABLE"],"description":"A local original was observed; this is not proof of remote retention, delivery or permission to send."},"message_timestamp":{"type":"integer","minimum":1,"maximum":18446744073709551615,"description":"Positive unsigned 64-bit timestamp supplied by the producer."},"from_me":{"type":"boolean","description":"Whether the stored original belongs to the paired account; this does not prove historical company authorship."},"kind":{"type":"string","enum":["text","image","video","document","audio","sticker","view_once","other"],"description":"Container type of the WhatsApp entity."},"preview":{"type":"object","additionalProperties":false,"required":["text","truncated"],"properties":{"text":{"type":"string","minLength":1,"maxLength":256,"description":"UTF-8 producer preview, bounded in characters rather than bytes."},"truncated":{"type":"boolean","description":"Whether the producer truncated the preview."}},"description":"Present only after preview opt-in and only for text, image, video or document when supplied by the producer."}},"if":{"properties":{"kind":{"enum":["audio","sticker","view_once","other"],"description":"Container type of the WhatsApp entity."}}},"then":{"not":{"required":["preview"]}}}},"remote_retention_verified":{"type":"boolean","enum":[false],"description":"Local availability does not establish WhatsApp retention or recipient delivery."},"coverage":{"type":"object","additionalProperties":false,"required":["version","scope","capture_started_at","admission_count","selection_timestamp_source","order","older_messages_included"],"properties":{"version":{"type":"integer","enum":[1]},"scope":{"type":"string","enum":["prospective_chatwoot_capture"]},"capture_started_at":{"type":"string","format":"date-time","description":"Start of the explicitly activated current capture. Earlier company messages are outside its coverage."},"admission_count":{"type":"integer","minimum":1,"maximum":200},"selection_timestamp_source":{"type":"string","enum":["server_ack_t"]},"order":{"type":"string","enum":["ack_desc_id_asc"]},"older_messages_included":{"type":"boolean","enum":[false]}}}}}}},"example":{"payload":{"group_id":42,"items":[{"message_id":"captured-original","availability":"AVAILABLE","message_timestamp":1792324800,"from_me":true,"kind":"text","preview":{"text":"sample text","truncated":true}}],"remote_retention_verified":false,"coverage":{"version":1,"scope":"prospective_chatwoot_capture","capture_started_at":"2026-10-18T12:00:00.000000Z","admission_count":1,"selection_timestamp_source":"server_ack_t","order":"ack_desc_id_asc","older_messages_included":false}}}}}},"401":{"description":"Native user/token/account or Pundit authorization denial retains its existing envelope and error text, including suspended accounts and AgentBot refusal. A typed WazMeow 401 is projected as unauthorized. An inbox or group policy denial remains 401 rather than being rewritten as a reader availability error.","headers":{"Cache-Control":{"description":"History responses are never cached, including refusals and errors.","schema":{"type":"string","enum":["no-store"]},"example":"no-store"}},"content":{"application/json":{"schema":{"oneOf":[{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","description":"Native authorization message, localized where applicable, or the literal gateway code unauthorized."}}},{"type":"object","additionalProperties":false,"required":["errors"],"properties":{"errors":{"type":"array","minItems":1,"maxItems":1,"description":"Existing native user-authentication refusal when no current user is authenticated.","items":{"type":"string"}}}}]},"examples":{"unauthenticated":{"value":{"errors":["You need to sign in or sign up before continuing."]}},"policy_denied":{"value":{"error":"You are not authorized to do this action"}},"gateway_denied":{"value":{"error":"unauthorized"}},"bot_denied":{"value":{"error":"Access to this endpoint is not authorized for bots"}}}}}},"404":{"description":"The group is missing or belongs to another account, or its physical inbox is outside the actor's operational scope. The native operational guard runs before the group predicate and inbox policy.","headers":{"Cache-Control":{"description":"History responses are never cached, including refusals and errors.","schema":{"type":"string","enum":["no-store"]},"example":"no-store"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","enum":["Resource could not be found"]}}},"example":{"error":"Resource could not be found"}}}},"400":{"description":"Invalid history input, including unknown or duplicate query keys, empty segments in a nonempty query, wrong scalar types, bounds violations, a nonempty GET body or invalid check JSON. The raw query limit is 16384 bytes and the check body limit is 32768 bytes. All 400 responses for these operations, including malformed raw queries rejected before controller callbacks, are normalized to this closed JSON envelope with Content-Type application/json; charset=utf-8 and Cache-Control no-store.","headers":{"Cache-Control":{"description":"History responses are never cached, including refusals and errors.","schema":{"type":"string","enum":["no-store"]},"example":"no-store"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","enum":["invalid_history_read_request"]}}},"example":{"error":"invalid_history_read_request"}}}},"403":{"description":"Missing effective native whatsapp_hub_manage permission, disabled Hub feature or disabled account token API access retains its native 403. An authorized physical channel that is not WhatsApp Web, or an unavailable reader binding, returns history_read_scope_unavailable.","headers":{"Cache-Control":{"description":"History responses are never cached, including refusals and errors.","schema":{"type":"string","enum":["no-store"]},"example":"no-store"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","enum":["forbidden","feature_not_enabled","API access is not enabled for this account","history_read_scope_unavailable"]}}},"examples":{"role_denied":{"value":{"error":"forbidden"}},"feature_disabled":{"value":{"error":"feature_not_enabled"}},"api_disabled":{"value":{"error":"API access is not enabled for this account"}},"scope_unavailable":{"value":{"error":"history_read_scope_unavailable"}}}}}},"503":{"description":"Automatic selection is refused without a complete current prospective capture, or the read is unavailable/invalid. An unqualified upstream automatic 200 is never accepted as proof.","headers":{"Cache-Control":{"description":"History responses are never cached, including refusals and errors.","schema":{"type":"string","enum":["no-store"]},"example":"no-store"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","enum":["history_company_proof_unavailable","history_read_unavailable","history_read_contract_invalid"]}}},"examples":{"proof_unavailable":{"value":{"error":"history_company_proof_unavailable"}},"unavailable":{"value":{"error":"history_read_unavailable"}},"invalid_contract":{"value":{"error":"history_read_contract_invalid"}}}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"description":"Account to which the authenticated user must belong, with API access enabled for token requests.","schema":{"type":"integer"},"example":1},{"name":"id","in":"path","required":true,"description":"Group row in this account. Its stored physical inbox and Web connection determine the read scope.","schema":{"type":"integer"},"example":42},{"name":"limit","in":"query","required":false,"description":"Canonical decimal string from 1 through 100. Leading zeros, signs and whitespace are rejected.","schema":{"type":"string","pattern":"^([1-9]|[1-9][0-9]|100)$","not":{"pattern":"[^0-9]"},"default":"25"},"example":"25"},{"name":"preview","in":"query","required":false,"description":"Literal case-sensitive query string. Opts into a bounded preview only when the producer supplies one.","schema":{"type":"string","enum":["true","false"],"default":"false"},"example":"true"}]}},"/api/v1/accounts/{account_id}/whatsapp_hub/groups/{id}/history/capture":{"get":{"tags":["WhatsApp Hub"],"operationId":"auto_get_api_v1_accounts_account_id_whatsapp_hub_groups_id_history_capture","summary":"Read prospective company-history capture status","description":"Uses the native user, account, Hub, Custom show permission and operational physical inbox guards. Accepts no query keys or body. Reads freshly locked Account and Group evidence in its own short transaction, with no provider HTTP, synchronization or job. A never-configured group is disabled; missing or inconsistent existing evidence is unavailable, never reconstructed. Every response is no-store.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Current prospective window status, with no private identity, digest or authorization fields.","headers":{"Cache-Control":{"description":"History responses are never cached, including refusals and errors.","schema":{"type":"string","enum":["no-store"]},"example":"no-store"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["payload"],"properties":{"payload":{"type":"object","additionalProperties":false,"required":["group_id","enabled","state","capture_started_at","admission_count","automatic_admission_limit","message_limit","scope","older_messages_included"],"properties":{"group_id":{"type":"integer"},"enabled":{"type":"boolean","description":"Whether the current prospective capture is active. This is not an automatic selection or send grant."},"state":{"type":"string","enum":["disabled","capturing","closed"]},"capture_started_at":{"type":["string","null"],"format":"date-time","description":"Start of the current capture, or null before first activation."},"admission_count":{"type":"integer","minimum":0,"maximum":4096,"description":"All admitted sends in the current capture, including pending or incomplete proofs. Count alone does not imply readiness."},"automatic_admission_limit":{"type":"integer","enum":[200]},"message_limit":{"type":"integer","enum":[100]},"scope":{"type":"string","enum":["prospective_chatwoot_capture"]},"older_messages_included":{"type":"boolean","enum":[false]}}}}},"example":{"payload":{"group_id":42,"enabled":false,"state":"disabled","capture_started_at":null,"admission_count":0,"automatic_admission_limit":200,"message_limit":100,"scope":"prospective_chatwoot_capture","older_messages_included":false}}}}},"401":{"description":"Native user/token/account or Pundit authorization denial retains its existing envelope and error text, including suspended accounts and AgentBot refusal. A typed WazMeow 401 is projected as unauthorized. An inbox or group policy denial remains 401 rather than being rewritten as a reader availability error.","headers":{"Cache-Control":{"description":"History responses are never cached, including refusals and errors.","schema":{"type":"string","enum":["no-store"]},"example":"no-store"}},"content":{"application/json":{"schema":{"oneOf":[{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","description":"Native authorization message, localized where applicable, or the literal gateway code unauthorized."}}},{"type":"object","additionalProperties":false,"required":["errors"],"properties":{"errors":{"type":"array","minItems":1,"maxItems":1,"description":"Existing native user-authentication refusal when no current user is authenticated.","items":{"type":"string"}}}}]},"examples":{"unauthenticated":{"value":{"errors":["You need to sign in or sign up before continuing."]}},"policy_denied":{"value":{"error":"You are not authorized to do this action"}},"gateway_denied":{"value":{"error":"unauthorized"}},"bot_denied":{"value":{"error":"Access to this endpoint is not authorized for bots"}}}}}},"404":{"description":"The group is missing or belongs to another account, or its physical inbox is outside the actor's operational scope. The native operational guard runs before the group predicate and inbox policy.","headers":{"Cache-Control":{"description":"History responses are never cached, including refusals and errors.","schema":{"type":"string","enum":["no-store"]},"example":"no-store"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","enum":["Resource could not be found"]}}},"example":{"error":"Resource could not be found"}}}},"400":{"description":"Invalid history input, including unknown or duplicate query keys, empty segments in a nonempty query, wrong scalar types, bounds violations, a nonempty GET body or invalid check JSON. The raw query limit is 16384 bytes and the check body limit is 32768 bytes. All 400 responses for these operations, including malformed raw queries rejected before controller callbacks, are normalized to this closed JSON envelope with Content-Type application/json; charset=utf-8 and Cache-Control no-store.","headers":{"Cache-Control":{"description":"History responses are never cached, including refusals and errors.","schema":{"type":"string","enum":["no-store"]},"example":"no-store"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","enum":["invalid_history_read_request"]}}},"example":{"error":"invalid_history_read_request"}}}},"403":{"description":"Missing effective native whatsapp_hub_manage permission, disabled Hub feature or disabled account token API access retains its native 403. An authorized physical channel that is not WhatsApp Web, or an unavailable reader binding, returns history_read_scope_unavailable.","headers":{"Cache-Control":{"description":"History responses are never cached, including refusals and errors.","schema":{"type":"string","enum":["no-store"]},"example":"no-store"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","enum":["forbidden","feature_not_enabled","API access is not enabled for this account","history_read_scope_unavailable"]}}},"examples":{"role_denied":{"value":{"error":"forbidden"}},"feature_disabled":{"value":{"error":"feature_not_enabled"}},"api_disabled":{"value":{"error":"API access is not enabled for this account"}},"scope_unavailable":{"value":{"error":"history_read_scope_unavailable"}}}}}},"503":{"description":"The current Account cut or tenant DSR denies access, the physical binding/evidence changed, a NOWAIT lock is busy, or storage is unavailable. No evidence is rebuilt from survivors.","headers":{"Cache-Control":{"description":"History responses are never cached, including refusals and errors.","schema":{"type":"string","enum":["no-store"]},"example":"no-store"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","enum":["history_company_proof_unavailable"]}}},"example":{"error":"history_company_proof_unavailable"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"description":"Account to which the authenticated user must belong, with API access enabled for token requests.","schema":{"type":"integer"},"example":1},{"name":"id","in":"path","required":true,"description":"Group row in this account. Its stored physical inbox and Web connection determine the read scope.","schema":{"type":"integer"},"example":42}]},"put":{"tags":["WhatsApp Hub"],"operationId":"auto_put_api_v1_accounts_account_id_whatsapp_hub_groups_id_history_capture","summary":"Activate or close a prospective company-history capture","description":"Uses the native user, account, Hub, Custom update permission and operational physical inbox guards. Accepts no query input, private proof or caller-selected inbox. The JSON body contains only a strict enabled boolean, at most 32768 bytes. Activation co-commits the current Group cut and its independent Account anchor before responding; it never enrolls earlier Messages. Repeated activation of the same current binding is idempotent. Disabling before first activation is a no-op. Closing retains evidence; reactivation archives the closed window and begins a new one within native bounds. Status is freshly read after the mutation, so it may reflect a concurrent later close. No provider HTTP, message send, sync or job is performed, and no authority to send is created. Every response is no-store.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Current prospective window status, with no private identity, digest or authorization fields.","headers":{"Cache-Control":{"description":"History responses are never cached, including refusals and errors.","schema":{"type":"string","enum":["no-store"]},"example":"no-store"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["payload"],"properties":{"payload":{"type":"object","additionalProperties":false,"required":["group_id","enabled","state","capture_started_at","admission_count","automatic_admission_limit","message_limit","scope","older_messages_included"],"properties":{"group_id":{"type":"integer"},"enabled":{"type":"boolean","description":"Whether the current prospective capture is active. This is not an automatic selection or send grant."},"state":{"type":"string","enum":["disabled","capturing","closed"]},"capture_started_at":{"type":["string","null"],"format":"date-time","description":"Start of the current capture, or null before first activation."},"admission_count":{"type":"integer","minimum":0,"maximum":4096,"description":"All admitted sends in the current capture, including pending or incomplete proofs. Count alone does not imply readiness."},"automatic_admission_limit":{"type":"integer","enum":[200]},"message_limit":{"type":"integer","enum":[100]},"scope":{"type":"string","enum":["prospective_chatwoot_capture"]},"older_messages_included":{"type":"boolean","enum":[false]}}}}},"example":{"payload":{"group_id":42,"enabled":false,"state":"disabled","capture_started_at":null,"admission_count":0,"automatic_admission_limit":200,"message_limit":100,"scope":"prospective_chatwoot_capture","older_messages_included":false}}}}},"401":{"description":"Native user/token/account or Pundit authorization denial retains its existing envelope and error text, including suspended accounts and AgentBot refusal. A typed WazMeow 401 is projected as unauthorized. An inbox or group policy denial remains 401 rather than being rewritten as a reader availability error.","headers":{"Cache-Control":{"description":"History responses are never cached, including refusals and errors.","schema":{"type":"string","enum":["no-store"]},"example":"no-store"}},"content":{"application/json":{"schema":{"oneOf":[{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","description":"Native authorization message, localized where applicable, or the literal gateway code unauthorized."}}},{"type":"object","additionalProperties":false,"required":["errors"],"properties":{"errors":{"type":"array","minItems":1,"maxItems":1,"description":"Existing native user-authentication refusal when no current user is authenticated.","items":{"type":"string"}}}}]},"examples":{"unauthenticated":{"value":{"errors":["You need to sign in or sign up before continuing."]}},"policy_denied":{"value":{"error":"You are not authorized to do this action"}},"gateway_denied":{"value":{"error":"unauthorized"}},"bot_denied":{"value":{"error":"Access to this endpoint is not authorized for bots"}}}}}},"404":{"description":"The group is missing or belongs to another account, or its physical inbox is outside the actor's operational scope. The native operational guard runs before the group predicate and inbox policy.","headers":{"Cache-Control":{"description":"History responses are never cached, including refusals and errors.","schema":{"type":"string","enum":["no-store"]},"example":"no-store"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","enum":["Resource could not be found"]}}},"example":{"error":"Resource could not be found"}}}},"400":{"description":"Invalid history input, including unknown or duplicate query keys, empty segments in a nonempty query, wrong scalar types, bounds violations, a nonempty GET body or invalid check JSON. The raw query limit is 16384 bytes and the check body limit is 32768 bytes. All 400 responses for these operations, including malformed raw queries rejected before controller callbacks, are normalized to this closed JSON envelope with Content-Type application/json; charset=utf-8 and Cache-Control no-store.","headers":{"Cache-Control":{"description":"History responses are never cached, including refusals and errors.","schema":{"type":"string","enum":["no-store"]},"example":"no-store"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","enum":["invalid_history_read_request"]}}},"example":{"error":"invalid_history_read_request"}}}},"403":{"description":"Missing effective native whatsapp_hub_manage permission, disabled Hub feature or disabled account token API access retains its native 403. An authorized physical channel that is not WhatsApp Web, or an unavailable reader binding, returns history_read_scope_unavailable.","headers":{"Cache-Control":{"description":"History responses are never cached, including refusals and errors.","schema":{"type":"string","enum":["no-store"]},"example":"no-store"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","enum":["forbidden","feature_not_enabled","API access is not enabled for this account","history_read_scope_unavailable"]}}},"examples":{"role_denied":{"value":{"error":"forbidden"}},"feature_disabled":{"value":{"error":"feature_not_enabled"}},"api_disabled":{"value":{"error":"API access is not enabled for this account"}},"scope_unavailable":{"value":{"error":"history_read_scope_unavailable"}}}}}},"503":{"description":"The current Account cut or tenant DSR denies access, the physical binding/evidence changed, a NOWAIT lock is busy, or storage is unavailable. No evidence is rebuilt from survivors.","headers":{"Cache-Control":{"description":"History responses are never cached, including refusals and errors.","schema":{"type":"string","enum":["no-store"]},"example":"no-store"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","enum":["history_company_proof_unavailable"]}}},"example":{"error":"history_company_proof_unavailable"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"description":"Account to which the authenticated user must belong, with API access enabled for token requests.","schema":{"type":"integer"},"example":1},{"name":"id","in":"path","required":true,"description":"Group row in this account. Its stored physical inbox and Web connection determine the read scope.","schema":{"type":"integer"},"example":42}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["enabled"],"properties":{"enabled":{"type":"boolean"}}},"example":{"enabled":true}}}}}},"/api/v1/accounts/{account_id}/whatsapp_hub/groups/{group_id}/maestro":{"patch":{"tags":["WhatsApp Hub"],"operationId":"auto_patch_api_v1_accounts_account_id_whatsapp_hub_groups_group_id_maestro","summary":"Update maestro","description":"Updates the maestro identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Group/channel with the updated Maestro gate applied.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer","example":42},"account_id":{"type":"integer","example":1},"inbox_id":{"type":"integer","example":7},"jid":{"type":"string","example":"120363021234567890@g.us","description":"WhatsApp JID. Groups/communities end in @g.us; channels (newsletters) end in @newsletter."},"kind":{"type":"string","example":"group","enum":["group","community","channel"],"description":"Container type."},"name":{"type":["string","null"],"example":"Lancamento Turma 12"},"topic":{"type":["string","null"],"example":"Avisos e materiais da turma"},"role":{"type":"string","example":"admin","enum":["owner","admin","member","subscriber"],"description":"The connected account's role in this container."},"is_parent":{"type":"boolean","example":false,"description":"True for a community parent row."},"is_default_sub":{"type":"boolean","example":false,"description":"True for a community's default/announcement sub-group."},"community_jid":{"type":["string","null"],"example":"120363039876543210@g.us","description":"Parent community JID when this group is linked to one."},"photo_url":{"type":["string","null"],"example":"https://pps.whatsapp.net/v/t61.24694-24/group-avatar.jpg"},"invite_code":{"type":["string","null"],"example":"Hkq0dEXAMPLEabcdef"},"participant_count":{"type":"integer","example":128},"maestro_enabled":{"type":"string","example":"inherit","enum":["inherit","on","off"],"description":"Per-group Maestro AI gate. inherit resolves to the inbox group_ai_policy."},"settings":{"type":"object","description":"Mirrored WhatsApp group settings.","properties":{"announce":{"type":"boolean","example":false,"description":"Only admins can post."},"locked":{"type":"boolean","example":false,"description":"Only admins can edit group info."},"ephemeral":{"type":["integer","null"],"example":0,"description":"Disappearing-message timer in seconds (0 = off)."}},"example":{"announce":false,"locked":false,"ephemeral":0}},"greeting":{"type":"object","description":"Per-group welcome/farewell override merged over the inbox default. Empty object = inherit.","properties":{"welcome":{"type":"object","properties":{"enabled":{"type":"boolean","example":true},"in_group":{"type":"boolean","example":true},"dm":{"type":"boolean","example":false},"template":{"type":"string","example":"Bem-vindo(a), {{name}}!"}}},"farewell":{"type":"object","properties":{"enabled":{"type":"boolean","example":false},"in_group":{"type":"boolean","example":false},"dm":{"type":"boolean","example":false},"template":{"type":"string","example":""}}}},"example":{"welcome":{"enabled":true,"in_group":true,"dm":false,"template":"Bem-vindo(a), {{name}}!"},"farewell":{"enabled":false,"in_group":false,"dm":false,"template":""}}},"engagement":{"type":"object","additionalProperties":true,"description":"Group-level engagement rollup (empty until computed).","example":{}},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Account-defined whatsapp_group custom attributes.","example":{}},"synced_at":{"type":["string","null"],"format":"date-time","example":"2026-01-15T10:30:00.000Z"},"archived_at":{"type":["string","null"],"format":"date-time","example":"2026-01-15T10:30:00.000Z"},"created_at":{"type":"string","format":"date-time","example":"2026-01-10T08:00:00.000Z"},"updated_at":{"type":"string","format":"date-time","example":"2026-01-15T10:30:00.000Z"},"distribution":{"type":["object","null"],"description":"Cross-link to the distribution unit (Turma) this group backs. Present on detail only when eager-loaded.","properties":{"unit_id":{"type":"integer","example":5},"unit_sequence":{"type":"integer","example":3},"unit_name":{"type":"string","example":"Turma 12 - Grupo 3"},"distribution_id":{"type":"integer","example":2},"distribution_name":{"type":["string","null"],"example":"Lancamento Janeiro"}},"example":{"unit_id":5,"unit_sequence":3,"unit_name":"Turma 12 - Grupo 3","distribution_id":2,"distribution_name":"Lancamento Janeiro"}},"participants":{"type":"array","description":"Active members ranked by engagement_score desc.","items":{"type":"object","properties":{"id":{"type":"integer","example":501},"jid":{"type":"string","example":"5521999998888@s.whatsapp.net"},"phone":{"type":["string","null"],"example":"+5521999998888"},"name":{"type":["string","null"],"example":"Maria Silva"},"display_name":{"type":["string","null"],"example":"Maria Silva","description":"Best real (non-phone, non-placeholder) name; null when only a phone/placeholder is known."},"role":{"type":"string","example":"member","enum":["owner","admin","member","subscriber"],"description":"Operator/participant role within the group."},"status":{"type":"string","example":"active","enum":["active","left","removed","pending"],"description":"Membership status of the group participant."},"contact_id":{"type":["integer","null"],"example":3021},"messages_count":{"type":"integer","example":42},"replies_count":{"type":"integer","example":12},"reactions_given_count":{"type":"integer","example":8},"reactions_received_count":{"type":"integer","example":15},"poll_votes_count":{"type":"integer","example":3},"button_clicks_count":{"type":"integer","example":1},"media_count":{"type":"integer","example":5},"engagement_score":{"type":"number","example":57.5},"last_active_at":{"type":["string","null"],"format":"date-time","example":"2026-01-15T09:45:00.000Z"},"joined_at":{"type":["string","null"],"format":"date-time","example":"2026-01-10T08:05:00.000Z"}}}}}}}},"example":{"payload":{"id":42,"account_id":1,"inbox_id":7,"jid":"120363021234567890@g.us","kind":"group","name":"Lancamento Turma 12","topic":"Avisos e materiais da turma","role":"admin","is_parent":false,"is_default_sub":false,"community_jid":"120363039876543210@g.us","photo_url":"https://pps.whatsapp.net/v/t61.24694-24/group-avatar.jpg","invite_code":"Hkq0dEXAMPLEabcdef","participant_count":128,"maestro_enabled":"inherit","settings":{"announce":false,"locked":false,"ephemeral":0},"greeting":{"welcome":{"enabled":true,"in_group":true,"dm":false,"template":"Bem-vindo(a), {{name}}!"},"farewell":{"enabled":false,"in_group":false,"dm":false,"template":""}},"engagement":{},"custom_attributes":{},"synced_at":"2026-01-15T10:30:00.000Z","archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-10T08:00:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","distribution":{"unit_id":5,"unit_sequence":3,"unit_name":"Turma 12 - Grupo 3","distribution_id":2,"distribution_name":"Lancamento Janeiro"},"participants":[{"id":501,"jid":"5521999998888@s.whatsapp.net","phone":"+5521999998888","name":"Maria Silva","display_name":"Maria Silva","role":"member","status":"active","contact_id":3021,"messages_count":42,"replies_count":12,"reactions_given_count":8,"reactions_received_count":15,"poll_votes_count":3,"button_clicks_count":1,"media_count":5,"engagement_score":57.5,"last_active_at":"2026-01-15T09:45:00.000Z","joined_at":"2026-01-10T08:05:00.000Z"}]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"group_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"maestro_enabled":{"type":"boolean"},"channel_id":{"type":"integer"}}},"example":{"maestro_enabled":true,"channel_id":1}}}}},"put":{"tags":["WhatsApp Hub"],"operationId":"auto_put_api_v1_accounts_account_id_whatsapp_hub_groups_group_id_maestro","summary":"Update maestro","description":"Updates the maestro identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Group/channel with the updated Maestro gate applied.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer","example":42},"account_id":{"type":"integer","example":1},"inbox_id":{"type":"integer","example":7},"jid":{"type":"string","example":"120363021234567890@g.us","description":"WhatsApp JID. Groups/communities end in @g.us; channels (newsletters) end in @newsletter."},"kind":{"type":"string","example":"group","enum":["group","community","channel"],"description":"Container type."},"name":{"type":["string","null"],"example":"Lancamento Turma 12"},"topic":{"type":["string","null"],"example":"Avisos e materiais da turma"},"role":{"type":"string","example":"admin","enum":["owner","admin","member","subscriber"],"description":"The connected account's role in this container."},"is_parent":{"type":"boolean","example":false,"description":"True for a community parent row."},"is_default_sub":{"type":"boolean","example":false,"description":"True for a community's default/announcement sub-group."},"community_jid":{"type":["string","null"],"example":"120363039876543210@g.us","description":"Parent community JID when this group is linked to one."},"photo_url":{"type":["string","null"],"example":"https://pps.whatsapp.net/v/t61.24694-24/group-avatar.jpg"},"invite_code":{"type":["string","null"],"example":"Hkq0dEXAMPLEabcdef"},"participant_count":{"type":"integer","example":128},"maestro_enabled":{"type":"string","example":"inherit","enum":["inherit","on","off"],"description":"Per-group Maestro AI gate. inherit resolves to the inbox group_ai_policy."},"settings":{"type":"object","description":"Mirrored WhatsApp group settings.","properties":{"announce":{"type":"boolean","example":false,"description":"Only admins can post."},"locked":{"type":"boolean","example":false,"description":"Only admins can edit group info."},"ephemeral":{"type":["integer","null"],"example":0,"description":"Disappearing-message timer in seconds (0 = off)."}},"example":{"announce":false,"locked":false,"ephemeral":0}},"greeting":{"type":"object","description":"Per-group welcome/farewell override merged over the inbox default. Empty object = inherit.","properties":{"welcome":{"type":"object","properties":{"enabled":{"type":"boolean","example":true},"in_group":{"type":"boolean","example":true},"dm":{"type":"boolean","example":false},"template":{"type":"string","example":"Bem-vindo(a), {{name}}!"}}},"farewell":{"type":"object","properties":{"enabled":{"type":"boolean","example":false},"in_group":{"type":"boolean","example":false},"dm":{"type":"boolean","example":false},"template":{"type":"string","example":""}}}},"example":{"welcome":{"enabled":true,"in_group":true,"dm":false,"template":"Bem-vindo(a), {{name}}!"},"farewell":{"enabled":false,"in_group":false,"dm":false,"template":""}}},"engagement":{"type":"object","additionalProperties":true,"description":"Group-level engagement rollup (empty until computed).","example":{}},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Account-defined whatsapp_group custom attributes.","example":{}},"synced_at":{"type":["string","null"],"format":"date-time","example":"2026-01-15T10:30:00.000Z"},"archived_at":{"type":["string","null"],"format":"date-time","example":"2026-01-15T10:30:00.000Z"},"created_at":{"type":"string","format":"date-time","example":"2026-01-10T08:00:00.000Z"},"updated_at":{"type":"string","format":"date-time","example":"2026-01-15T10:30:00.000Z"},"distribution":{"type":["object","null"],"description":"Cross-link to the distribution unit (Turma) this group backs. Present on detail only when eager-loaded.","properties":{"unit_id":{"type":"integer","example":5},"unit_sequence":{"type":"integer","example":3},"unit_name":{"type":"string","example":"Turma 12 - Grupo 3"},"distribution_id":{"type":"integer","example":2},"distribution_name":{"type":["string","null"],"example":"Lancamento Janeiro"}},"example":{"unit_id":5,"unit_sequence":3,"unit_name":"Turma 12 - Grupo 3","distribution_id":2,"distribution_name":"Lancamento Janeiro"}},"participants":{"type":"array","description":"Active members ranked by engagement_score desc.","items":{"type":"object","properties":{"id":{"type":"integer","example":501},"jid":{"type":"string","example":"5521999998888@s.whatsapp.net"},"phone":{"type":["string","null"],"example":"+5521999998888"},"name":{"type":["string","null"],"example":"Maria Silva"},"display_name":{"type":["string","null"],"example":"Maria Silva","description":"Best real (non-phone, non-placeholder) name; null when only a phone/placeholder is known."},"role":{"type":"string","example":"member","enum":["owner","admin","member","subscriber"],"description":"Operator/participant role within the group."},"status":{"type":"string","example":"active","enum":["active","left","removed","pending"],"description":"Membership status of the group participant."},"contact_id":{"type":["integer","null"],"example":3021},"messages_count":{"type":"integer","example":42},"replies_count":{"type":"integer","example":12},"reactions_given_count":{"type":"integer","example":8},"reactions_received_count":{"type":"integer","example":15},"poll_votes_count":{"type":"integer","example":3},"button_clicks_count":{"type":"integer","example":1},"media_count":{"type":"integer","example":5},"engagement_score":{"type":"number","example":57.5},"last_active_at":{"type":["string","null"],"format":"date-time","example":"2026-01-15T09:45:00.000Z"},"joined_at":{"type":["string","null"],"format":"date-time","example":"2026-01-10T08:05:00.000Z"}}}}}}}},"example":{"payload":{"id":42,"account_id":1,"inbox_id":7,"jid":"120363021234567890@g.us","kind":"group","name":"Lancamento Turma 12","topic":"Avisos e materiais da turma","role":"admin","is_parent":false,"is_default_sub":false,"community_jid":"120363039876543210@g.us","photo_url":"https://pps.whatsapp.net/v/t61.24694-24/group-avatar.jpg","invite_code":"Hkq0dEXAMPLEabcdef","participant_count":128,"maestro_enabled":"inherit","settings":{"announce":false,"locked":false,"ephemeral":0},"greeting":{"welcome":{"enabled":true,"in_group":true,"dm":false,"template":"Bem-vindo(a), {{name}}!"},"farewell":{"enabled":false,"in_group":false,"dm":false,"template":""}},"engagement":{},"custom_attributes":{},"synced_at":"2026-01-15T10:30:00.000Z","archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-10T08:00:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","distribution":{"unit_id":5,"unit_sequence":3,"unit_name":"Turma 12 - Grupo 3","distribution_id":2,"distribution_name":"Lancamento Janeiro"},"participants":[{"id":501,"jid":"5521999998888@s.whatsapp.net","phone":"+5521999998888","name":"Maria Silva","display_name":"Maria Silva","role":"member","status":"active","contact_id":3021,"messages_count":42,"replies_count":12,"reactions_given_count":8,"reactions_received_count":15,"poll_votes_count":3,"button_clicks_count":1,"media_count":5,"engagement_score":57.5,"last_active_at":"2026-01-15T09:45:00.000Z","joined_at":"2026-01-10T08:05:00.000Z"}]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"group_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"maestro_enabled":{"type":"boolean"},"channel_id":{"type":"integer"}}},"example":{"maestro_enabled":true,"channel_id":1}}}}}},"/api/v1/accounts/{account_id}/whatsapp_hub/groups/{group_id}/greeting":{"patch":{"tags":["WhatsApp Hub"],"operationId":"auto_patch_api_v1_accounts_account_id_whatsapp_hub_groups_group_id_greeting","summary":"Update greeting","description":"Updates the greeting identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Group with the updated greeting override.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer","example":42},"account_id":{"type":"integer","example":1},"inbox_id":{"type":"integer","example":7},"jid":{"type":"string","example":"120363021234567890@g.us","description":"WhatsApp JID. Groups/communities end in @g.us; channels (newsletters) end in @newsletter."},"kind":{"type":"string","example":"group","enum":["group","community","channel"],"description":"Container type."},"name":{"type":["string","null"],"example":"Lancamento Turma 12"},"topic":{"type":["string","null"],"example":"Avisos e materiais da turma"},"role":{"type":"string","example":"admin","enum":["owner","admin","member","subscriber"],"description":"The connected account's role in this container."},"is_parent":{"type":"boolean","example":false,"description":"True for a community parent row."},"is_default_sub":{"type":"boolean","example":false,"description":"True for a community's default/announcement sub-group."},"community_jid":{"type":["string","null"],"example":"120363039876543210@g.us","description":"Parent community JID when this group is linked to one."},"photo_url":{"type":["string","null"],"example":"https://pps.whatsapp.net/v/t61.24694-24/group-avatar.jpg"},"invite_code":{"type":["string","null"],"example":"Hkq0dEXAMPLEabcdef"},"participant_count":{"type":"integer","example":128},"maestro_enabled":{"type":"string","example":"inherit","enum":["inherit","on","off"],"description":"Per-group Maestro AI gate. inherit resolves to the inbox group_ai_policy."},"settings":{"type":"object","description":"Mirrored WhatsApp group settings.","properties":{"announce":{"type":"boolean","example":false,"description":"Only admins can post."},"locked":{"type":"boolean","example":false,"description":"Only admins can edit group info."},"ephemeral":{"type":["integer","null"],"example":0,"description":"Disappearing-message timer in seconds (0 = off)."}},"example":{"announce":false,"locked":false,"ephemeral":0}},"greeting":{"type":"object","description":"Per-group welcome/farewell override merged over the inbox default. Empty object = inherit.","properties":{"welcome":{"type":"object","properties":{"enabled":{"type":"boolean","example":true},"in_group":{"type":"boolean","example":true},"dm":{"type":"boolean","example":false},"template":{"type":"string","example":"Bem-vindo(a), {{name}}!"}}},"farewell":{"type":"object","properties":{"enabled":{"type":"boolean","example":false},"in_group":{"type":"boolean","example":false},"dm":{"type":"boolean","example":false},"template":{"type":"string","example":""}}}},"example":{"welcome":{"enabled":true,"in_group":true,"dm":false,"template":"Bem-vindo(a), {{name}}!"},"farewell":{"enabled":false,"in_group":false,"dm":false,"template":""}}},"engagement":{"type":"object","additionalProperties":true,"description":"Group-level engagement rollup (empty until computed).","example":{}},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Account-defined whatsapp_group custom attributes.","example":{}},"synced_at":{"type":["string","null"],"format":"date-time","example":"2026-01-15T10:30:00.000Z"},"archived_at":{"type":["string","null"],"format":"date-time","example":"2026-01-15T10:30:00.000Z"},"created_at":{"type":"string","format":"date-time","example":"2026-01-10T08:00:00.000Z"},"updated_at":{"type":"string","format":"date-time","example":"2026-01-15T10:30:00.000Z"},"distribution":{"type":["object","null"],"description":"Cross-link to the distribution unit (Turma) this group backs. Present on detail only when eager-loaded.","properties":{"unit_id":{"type":"integer","example":5},"unit_sequence":{"type":"integer","example":3},"unit_name":{"type":"string","example":"Turma 12 - Grupo 3"},"distribution_id":{"type":"integer","example":2},"distribution_name":{"type":["string","null"],"example":"Lancamento Janeiro"}},"example":{"unit_id":5,"unit_sequence":3,"unit_name":"Turma 12 - Grupo 3","distribution_id":2,"distribution_name":"Lancamento Janeiro"}},"participants":{"type":"array","description":"Active members ranked by engagement_score desc.","items":{"type":"object","properties":{"id":{"type":"integer","example":501},"jid":{"type":"string","example":"5521999998888@s.whatsapp.net"},"phone":{"type":["string","null"],"example":"+5521999998888"},"name":{"type":["string","null"],"example":"Maria Silva"},"display_name":{"type":["string","null"],"example":"Maria Silva","description":"Best real (non-phone, non-placeholder) name; null when only a phone/placeholder is known."},"role":{"type":"string","example":"member","enum":["owner","admin","member","subscriber"],"description":"Operator/participant role within the group."},"status":{"type":"string","example":"active","enum":["active","left","removed","pending"],"description":"Membership status of the group participant."},"contact_id":{"type":["integer","null"],"example":3021},"messages_count":{"type":"integer","example":42},"replies_count":{"type":"integer","example":12},"reactions_given_count":{"type":"integer","example":8},"reactions_received_count":{"type":"integer","example":15},"poll_votes_count":{"type":"integer","example":3},"button_clicks_count":{"type":"integer","example":1},"media_count":{"type":"integer","example":5},"engagement_score":{"type":"number","example":57.5},"last_active_at":{"type":["string","null"],"format":"date-time","example":"2026-01-15T09:45:00.000Z"},"joined_at":{"type":["string","null"],"format":"date-time","example":"2026-01-10T08:05:00.000Z"}}}}}}}},"example":{"payload":{"id":42,"account_id":1,"inbox_id":7,"jid":"120363021234567890@g.us","kind":"group","name":"Lancamento Turma 12","topic":"Avisos e materiais da turma","role":"admin","is_parent":false,"is_default_sub":false,"community_jid":"120363039876543210@g.us","photo_url":"https://pps.whatsapp.net/v/t61.24694-24/group-avatar.jpg","invite_code":"Hkq0dEXAMPLEabcdef","participant_count":128,"maestro_enabled":"inherit","settings":{"announce":false,"locked":false,"ephemeral":0},"greeting":{"welcome":{"enabled":true,"in_group":true,"dm":false,"template":"Bem-vindo(a), {{name}}!"},"farewell":{"enabled":false,"in_group":false,"dm":false,"template":""}},"engagement":{},"custom_attributes":{},"synced_at":"2026-01-15T10:30:00.000Z","archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-10T08:00:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","distribution":{"unit_id":5,"unit_sequence":3,"unit_name":"Turma 12 - Grupo 3","distribution_id":2,"distribution_name":"Lancamento Janeiro"},"participants":[{"id":501,"jid":"5521999998888@s.whatsapp.net","phone":"+5521999998888","name":"Maria Silva","display_name":"Maria Silva","role":"member","status":"active","contact_id":3021,"messages_count":42,"replies_count":12,"reactions_given_count":8,"reactions_received_count":15,"poll_votes_count":3,"button_clicks_count":1,"media_count":5,"engagement_score":57.5,"last_active_at":"2026-01-15T09:45:00.000Z","joined_at":"2026-01-10T08:05:00.000Z"}]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"group_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"greeting":{"type":"object","properties":{"welcome":{"type":"object","additionalProperties":true,"description":"Free-form object."},"farewell":{"type":"object","additionalProperties":true,"description":"Free-form object."}}}}},"example":{"greeting":{"welcome":{},"farewell":{}}}}}}},"put":{"tags":["WhatsApp Hub"],"operationId":"auto_put_api_v1_accounts_account_id_whatsapp_hub_groups_group_id_greeting","summary":"Update greeting","description":"Updates the greeting identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Group with the updated greeting override.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer","example":42},"account_id":{"type":"integer","example":1},"inbox_id":{"type":"integer","example":7},"jid":{"type":"string","example":"120363021234567890@g.us","description":"WhatsApp JID. Groups/communities end in @g.us; channels (newsletters) end in @newsletter."},"kind":{"type":"string","example":"group","enum":["group","community","channel"],"description":"Container type."},"name":{"type":["string","null"],"example":"Lancamento Turma 12"},"topic":{"type":["string","null"],"example":"Avisos e materiais da turma"},"role":{"type":"string","example":"admin","enum":["owner","admin","member","subscriber"],"description":"The connected account's role in this container."},"is_parent":{"type":"boolean","example":false,"description":"True for a community parent row."},"is_default_sub":{"type":"boolean","example":false,"description":"True for a community's default/announcement sub-group."},"community_jid":{"type":["string","null"],"example":"120363039876543210@g.us","description":"Parent community JID when this group is linked to one."},"photo_url":{"type":["string","null"],"example":"https://pps.whatsapp.net/v/t61.24694-24/group-avatar.jpg"},"invite_code":{"type":["string","null"],"example":"Hkq0dEXAMPLEabcdef"},"participant_count":{"type":"integer","example":128},"maestro_enabled":{"type":"string","example":"inherit","enum":["inherit","on","off"],"description":"Per-group Maestro AI gate. inherit resolves to the inbox group_ai_policy."},"settings":{"type":"object","description":"Mirrored WhatsApp group settings.","properties":{"announce":{"type":"boolean","example":false,"description":"Only admins can post."},"locked":{"type":"boolean","example":false,"description":"Only admins can edit group info."},"ephemeral":{"type":["integer","null"],"example":0,"description":"Disappearing-message timer in seconds (0 = off)."}},"example":{"announce":false,"locked":false,"ephemeral":0}},"greeting":{"type":"object","description":"Per-group welcome/farewell override merged over the inbox default. Empty object = inherit.","properties":{"welcome":{"type":"object","properties":{"enabled":{"type":"boolean","example":true},"in_group":{"type":"boolean","example":true},"dm":{"type":"boolean","example":false},"template":{"type":"string","example":"Bem-vindo(a), {{name}}!"}}},"farewell":{"type":"object","properties":{"enabled":{"type":"boolean","example":false},"in_group":{"type":"boolean","example":false},"dm":{"type":"boolean","example":false},"template":{"type":"string","example":""}}}},"example":{"welcome":{"enabled":true,"in_group":true,"dm":false,"template":"Bem-vindo(a), {{name}}!"},"farewell":{"enabled":false,"in_group":false,"dm":false,"template":""}}},"engagement":{"type":"object","additionalProperties":true,"description":"Group-level engagement rollup (empty until computed).","example":{}},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Account-defined whatsapp_group custom attributes.","example":{}},"synced_at":{"type":["string","null"],"format":"date-time","example":"2026-01-15T10:30:00.000Z"},"archived_at":{"type":["string","null"],"format":"date-time","example":"2026-01-15T10:30:00.000Z"},"created_at":{"type":"string","format":"date-time","example":"2026-01-10T08:00:00.000Z"},"updated_at":{"type":"string","format":"date-time","example":"2026-01-15T10:30:00.000Z"},"distribution":{"type":["object","null"],"description":"Cross-link to the distribution unit (Turma) this group backs. Present on detail only when eager-loaded.","properties":{"unit_id":{"type":"integer","example":5},"unit_sequence":{"type":"integer","example":3},"unit_name":{"type":"string","example":"Turma 12 - Grupo 3"},"distribution_id":{"type":"integer","example":2},"distribution_name":{"type":["string","null"],"example":"Lancamento Janeiro"}},"example":{"unit_id":5,"unit_sequence":3,"unit_name":"Turma 12 - Grupo 3","distribution_id":2,"distribution_name":"Lancamento Janeiro"}},"participants":{"type":"array","description":"Active members ranked by engagement_score desc.","items":{"type":"object","properties":{"id":{"type":"integer","example":501},"jid":{"type":"string","example":"5521999998888@s.whatsapp.net"},"phone":{"type":["string","null"],"example":"+5521999998888"},"name":{"type":["string","null"],"example":"Maria Silva"},"display_name":{"type":["string","null"],"example":"Maria Silva","description":"Best real (non-phone, non-placeholder) name; null when only a phone/placeholder is known."},"role":{"type":"string","example":"member","enum":["owner","admin","member","subscriber"],"description":"Operator/participant role within the group."},"status":{"type":"string","example":"active","enum":["active","left","removed","pending"],"description":"Membership status of the group participant."},"contact_id":{"type":["integer","null"],"example":3021},"messages_count":{"type":"integer","example":42},"replies_count":{"type":"integer","example":12},"reactions_given_count":{"type":"integer","example":8},"reactions_received_count":{"type":"integer","example":15},"poll_votes_count":{"type":"integer","example":3},"button_clicks_count":{"type":"integer","example":1},"media_count":{"type":"integer","example":5},"engagement_score":{"type":"number","example":57.5},"last_active_at":{"type":["string","null"],"format":"date-time","example":"2026-01-15T09:45:00.000Z"},"joined_at":{"type":["string","null"],"format":"date-time","example":"2026-01-10T08:05:00.000Z"}}}}}}}},"example":{"payload":{"id":42,"account_id":1,"inbox_id":7,"jid":"120363021234567890@g.us","kind":"group","name":"Lancamento Turma 12","topic":"Avisos e materiais da turma","role":"admin","is_parent":false,"is_default_sub":false,"community_jid":"120363039876543210@g.us","photo_url":"https://pps.whatsapp.net/v/t61.24694-24/group-avatar.jpg","invite_code":"Hkq0dEXAMPLEabcdef","participant_count":128,"maestro_enabled":"inherit","settings":{"announce":false,"locked":false,"ephemeral":0},"greeting":{"welcome":{"enabled":true,"in_group":true,"dm":false,"template":"Bem-vindo(a), {{name}}!"},"farewell":{"enabled":false,"in_group":false,"dm":false,"template":""}},"engagement":{},"custom_attributes":{},"synced_at":"2026-01-15T10:30:00.000Z","archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-10T08:00:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","distribution":{"unit_id":5,"unit_sequence":3,"unit_name":"Turma 12 - Grupo 3","distribution_id":2,"distribution_name":"Lancamento Janeiro"},"participants":[{"id":501,"jid":"5521999998888@s.whatsapp.net","phone":"+5521999998888","name":"Maria Silva","display_name":"Maria Silva","role":"member","status":"active","contact_id":3021,"messages_count":42,"replies_count":12,"reactions_given_count":8,"reactions_received_count":15,"poll_votes_count":3,"button_clicks_count":1,"media_count":5,"engagement_score":57.5,"last_active_at":"2026-01-15T09:45:00.000Z","joined_at":"2026-01-10T08:05:00.000Z"}]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"group_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"greeting":{"type":"object","properties":{"welcome":{"type":"object","additionalProperties":true,"description":"Free-form object."},"farewell":{"type":"object","additionalProperties":true,"description":"Free-form object."}}}}},"example":{"greeting":{"welcome":{},"farewell":{}}}}}}}},"/api/v1/accounts/{account_id}/whatsapp_hub/groups":{"get":{"tags":["WhatsApp Hub"],"operationId":"auto_get_api_v1_accounts_account_id_whatsapp_hub_groups","summary":"List WhatsApp Hub groups, or resolve the whole selectable target set","description":"Lists mirrored WhatsApp containers for an inbox. By default returns a bounded page of full group cards with an authoritative whole-set meta.count. With targets=true (or mode=targets) returns the compact whole selectable set (no pagination) for \"select all\". Filter with kind, q (name/JID typeahead), community_jid (a community's sub-groups), standalone (groups outside any community), min_participants (near-capacity), and archived (the soft-deleted bin). Requires group read authorization (administrator or agent).","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Either a bounded page of full group cards + a whole-set meta.count (default), or the compact whole selectable set + meta.count when targets=true / mode=targets.","content":{"application/json":{"schema":{"oneOf":[{"type":"object","description":"Default — a bounded page of full group cards with an authoritative whole-set count.","properties":{"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","example":42},"account_id":{"type":"integer","example":1},"inbox_id":{"type":"integer","example":7},"jid":{"type":"string","example":"120363021234567890@g.us","description":"WhatsApp JID. Groups/communities end in @g.us; channels (newsletters) end in @newsletter."},"kind":{"type":"string","example":"group","enum":["group","community","channel"],"description":"Container type."},"name":{"type":["string","null"],"example":"Lancamento Turma 12"},"topic":{"type":["string","null"],"example":"Avisos e materiais da turma"},"role":{"type":"string","example":"admin","enum":["owner","admin","member","subscriber"],"description":"The connected account's role in this container."},"is_parent":{"type":"boolean","example":false,"description":"True for a community parent row."},"is_default_sub":{"type":"boolean","example":false,"description":"True for a community's default/announcement sub-group."},"community_jid":{"type":["string","null"],"example":"120363039876543210@g.us","description":"Parent community JID when this group is linked to one."},"photo_url":{"type":["string","null"],"example":"https://pps.whatsapp.net/v/t61.24694-24/group-avatar.jpg"},"invite_code":{"type":["string","null"],"example":"Hkq0dEXAMPLEabcdef"},"participant_count":{"type":"integer","example":128},"maestro_enabled":{"type":"string","example":"inherit","enum":["inherit","on","off"],"description":"Per-group Maestro AI gate. inherit resolves to the inbox group_ai_policy."},"settings":{"type":"object","description":"Mirrored WhatsApp group settings.","properties":{"announce":{"type":"boolean","example":false,"description":"Only admins can post."},"locked":{"type":"boolean","example":false,"description":"Only admins can edit group info."},"ephemeral":{"type":["integer","null"],"example":0,"description":"Disappearing-message timer in seconds (0 = off)."}},"example":{"announce":false,"locked":false,"ephemeral":0}},"greeting":{"type":"object","description":"Per-group welcome/farewell override merged over the inbox default. Empty object = inherit.","properties":{"welcome":{"type":"object","properties":{"enabled":{"type":"boolean","example":true},"in_group":{"type":"boolean","example":true},"dm":{"type":"boolean","example":false},"template":{"type":"string","example":"Bem-vindo(a), {{name}}!"}}},"farewell":{"type":"object","properties":{"enabled":{"type":"boolean","example":false},"in_group":{"type":"boolean","example":false},"dm":{"type":"boolean","example":false},"template":{"type":"string","example":""}}}},"example":{"welcome":{"enabled":true,"in_group":true,"dm":false,"template":"Bem-vindo(a), {{name}}!"},"farewell":{"enabled":false,"in_group":false,"dm":false,"template":""}}},"engagement":{"type":"object","additionalProperties":true,"description":"Group-level engagement rollup (empty until computed).","example":{}},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Account-defined whatsapp_group custom attributes.","example":{}},"synced_at":{"type":["string","null"],"format":"date-time","example":"2026-01-15T10:30:00.000Z"},"archived_at":{"type":["string","null"],"format":"date-time","example":"2026-01-15T10:30:00.000Z"},"created_at":{"type":"string","format":"date-time","example":"2026-01-10T08:00:00.000Z"},"updated_at":{"type":"string","format":"date-time","example":"2026-01-15T10:30:00.000Z"}}}},"meta":{"type":"object","description":"Whole-set pagination — count is a total over the entire filtered scope, not the loaded page.","properties":{"count":{"type":"integer","example":137},"current_page":{"type":"integer","example":1},"total_pages":{"type":"integer","example":6},"per_page":{"type":"integer","example":25},"has_more":{"type":"boolean","example":true}}}}},{"type":"object","description":"targets mode — the compact whole selectable set (no pagination) for \"select all\".","properties":{"payload":{"type":"array","items":{"type":"object","description":"Compact broadcast-target descriptor (a light projection, no engagement/settings/avatars).","properties":{"id":{"type":"integer","example":42},"inbox_id":{"type":"integer","example":7},"jid":{"type":"string","example":"120363021234567890@g.us","description":"WhatsApp JID. Groups/communities end in @g.us; channels (newsletters) end in @newsletter."},"kind":{"type":"string","example":"group","enum":["group","community","channel"],"description":"Container type."},"name":{"type":["string","null"],"example":"Lancamento Turma 12"},"participant_count":{"type":"integer","example":128},"is_default_sub":{"type":"boolean","example":false,"description":"True for a community's default/announcement sub-group (dropped by \"select all\")."},"photo_url":{"type":["string","null"],"example":"https://pps.whatsapp.net/v/t61.24694-24/group-avatar.jpg"},"whatsapp_group_id":{"type":"integer","example":42,"description":"Mirrors id — the descriptor the composer sends as targets[{ jid, kind, whatsapp_group_id }]."}}}},"meta":{"type":"object","description":"Whole-set count for the compact selectable set.","properties":{"count":{"type":"integer","example":137},"mode":{"type":"string","enum":["targets"],"example":"targets"}}}}}]},"example":{"payload":[{"id":42,"account_id":1,"inbox_id":7,"jid":"120363021234567890@g.us","kind":"group","name":"Lancamento Turma 12","topic":"Avisos e materiais da turma","role":"admin","is_parent":false,"is_default_sub":false,"community_jid":"120363039876543210@g.us","photo_url":"https://pps.whatsapp.net/v/t61.24694-24/group-avatar.jpg","invite_code":"Hkq0dEXAMPLEabcdef","participant_count":128,"maestro_enabled":"inherit","settings":{"announce":false,"locked":false,"ephemeral":0},"greeting":{"welcome":{"enabled":true,"in_group":true,"dm":false,"template":"Bem-vindo(a), {{name}}!"},"farewell":{"enabled":false,"in_group":false,"dm":false,"template":""}},"engagement":{},"custom_attributes":{},"synced_at":"2026-01-15T10:30:00.000Z","archived_at":null,"created_at":"2026-01-10T08:00:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}],"meta":{"count":137,"current_page":1,"total_pages":6,"per_page":25,"has_more":true}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"inbox_id","in":"query","required":false,"description":"Scope to a single whatsapp_web inbox's containers.","schema":{"type":"integer","example":7}},{"name":"kind","in":"query","required":false,"description":"Container type filter. Omit to include every kind (mixed).","schema":{"type":"string","enum":["group","community","channel"],"example":"group"}},{"name":"q","in":"query","required":false,"description":"Case-insensitive typeahead over group name OR JID (canonical; the legacy `search` alias is also accepted).","schema":{"type":"string","example":"Turma 12"}},{"name":"min_participants","in":"query","required":false,"description":"Only groups whose participant_count is at or above this threshold (powers the near-capacity whole-set count).","schema":{"type":"integer","example":1000}},{"name":"community_jid","in":"query","required":false,"description":"Return that community's linked sub-groups (the community-detail view), including its default/announcement group.","schema":{"type":"string","example":"120363039876543210@g.us"}},{"name":"standalone","in":"query","required":false,"description":"When true (with kind=group), only groups outside any community (the link-picker set).","schema":{"type":"boolean","example":true}},{"name":"archived","in":"query","required":false,"description":"When true, list the archived (soft-deleted) bin instead of the kept rows.","schema":{"type":"boolean","example":false}},{"name":"page","in":"query","required":false,"description":"1-based page for the bounded browse (ignored in targets mode, which is unpaginated).","schema":{"type":"integer","example":1}},{"name":"per_page","in":"query","required":false,"description":"Page size for the bounded browse (default 25, capped at 100 for safety).","schema":{"type":"integer","example":25}},{"name":"targets","in":"query","required":false,"description":"When true, return the compact whole selectable set (every matching row, no pagination) for \"select all\".","schema":{"type":"boolean","example":true}},{"name":"mode","in":"query","required":false,"description":"Alias for targets — set to `targets` to return the compact whole selectable set.","schema":{"type":"string","enum":["targets"],"example":"targets"}}]},"post":{"tags":["WhatsApp Hub"],"operationId":"auto_post_api_v1_accounts_account_id_whatsapp_hub_groups","summary":"Create groups","description":"Creates a new group from the request payload. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"201":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"inbox_id":{"type":"integer"},"logical_inbox_id":{"type":"integer"},"jid":{"type":"string"},"kind":{"type":"string","enum":["group","community","channel"],"description":"Container type of the WhatsApp entity."},"name":{"type":"string"},"topic":{"type":"string"},"role":{"type":"string","enum":["owner","admin","member","subscriber"],"description":"Operator/participant role within the group."},"is_parent":{"type":"boolean"},"is_default_sub":{"type":"boolean"},"community_jid":{"type":"string"},"photo_url":{"type":"string"},"invite_code":{"type":"string"},"participant_count":{"type":"integer"},"maestro_enabled":{"type":"boolean"},"settings":{"type":"string"},"greeting":{"type":"string"},"engagement":{"type":"string"},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"synced_at":{"type":"string","format":"date-time"},"archived_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"distribution":{"type":"object","properties":{"unit_id":{"type":"integer"},"unit_sequence":{"type":"string"},"unit_name":{"type":"string"},"distribution_id":{"type":"integer"},"distribution_name":{"type":["string","null"]}}},"participants":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"jid":{"type":"string"},"phone":{"type":"string"},"name":{"type":"string"},"display_name":{"type":"string"},"role":{"type":"string","enum":["agent","administrator"],"description":"Operator/participant role within the group."},"status":{"type":"string","enum":["active","left","removed","pending"],"description":"Membership status of the group participant."},"contact_id":{"type":"integer"},"messages_count":{"type":"integer"},"replies_count":{"type":"integer"},"reactions_given_count":{"type":"integer"},"reactions_received_count":{"type":"integer"},"poll_votes_count":{"type":"integer"},"button_clicks_count":{"type":"integer"},"media_count":{"type":"integer"},"engagement_score":{"type":"string"},"last_active_at":{"type":"string","format":"date-time"},"joined_at":{"type":"string","format":"date-time"}}}}}}}},"example":{"payload":{"id":1,"account_id":1,"inbox_id":1,"logical_inbox_id":1,"jid":"sample jid","kind":"group","name":"Sample Name","topic":"sample topic","role":"owner","is_parent":true,"is_default_sub":true,"community_jid":"sample community jid","photo_url":"https://example.com/resource","invite_code":"sample invite code","participant_count":5,"maestro_enabled":true,"settings":"sample settings","greeting":"sample greeting","engagement":"sample engagement","custom_attributes":{},"synced_at":"2026-01-15T10:30:00.000Z","archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","distribution":{"unit_id":1,"unit_sequence":"sample unit sequence","unit_name":"sample unit name","distribution_id":1,"distribution_name":"sample distribution name"},"participants":[{"id":1,"jid":"sample jid","phone":"+5511999998888","name":"Sample Name","display_name":"sample display name","role":"agent","status":"active","contact_id":1,"messages_count":5,"replies_count":5,"reactions_given_count":5,"reactions_received_count":5,"poll_votes_count":5,"button_clicks_count":5,"media_count":5,"engagement_score":"sample engagement score","last_active_at":"2026-01-15T10:30:00.000Z","joined_at":"2026-01-15T10:30:00.000Z"}]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"topic":{"type":"string"},"announce":{"type":"boolean"},"locked":{"type":"boolean"},"ephemeral_seconds":{"type":"integer"},"participants":{"type":"array","items":{"type":"string"}}}},"example":{"name":"Sample Name","topic":"sample topic","announce":true,"locked":true,"ephemeral_seconds":60,"participants":["sample participant"]}}}}}},"/api/v1/accounts/{account_id}/whatsapp_hub/groups/{id}":{"get":{"tags":["WhatsApp Hub"],"operationId":"auto_get_api_v1_accounts_account_id_whatsapp_hub_groups_id","summary":"Get groups","description":"Returns the group identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"inbox_id":{"type":"integer"},"logical_inbox_id":{"type":"integer"},"jid":{"type":"string"},"kind":{"type":"string","enum":["group","community","channel"],"description":"Container type of the WhatsApp entity."},"name":{"type":"string"},"topic":{"type":"string"},"role":{"type":"string","enum":["owner","admin","member","subscriber"],"description":"Operator/participant role within the group."},"is_parent":{"type":"boolean"},"is_default_sub":{"type":"boolean"},"community_jid":{"type":"string"},"photo_url":{"type":"string"},"invite_code":{"type":"string"},"participant_count":{"type":"integer"},"maestro_enabled":{"type":"boolean"},"settings":{"type":"string"},"greeting":{"type":"string"},"engagement":{"type":"string"},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"synced_at":{"type":"string","format":"date-time"},"archived_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"distribution":{"type":"object","properties":{"unit_id":{"type":"integer"},"unit_sequence":{"type":"string"},"unit_name":{"type":"string"},"distribution_id":{"type":"integer"},"distribution_name":{"type":["string","null"]}}},"participants":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"jid":{"type":"string"},"phone":{"type":"string"},"name":{"type":"string"},"display_name":{"type":"string"},"role":{"type":"string","enum":["agent","administrator"],"description":"Operator/participant role within the group."},"status":{"type":"string","enum":["active","left","removed","pending"],"description":"Membership status of the group participant."},"contact_id":{"type":"integer"},"messages_count":{"type":"integer"},"replies_count":{"type":"integer"},"reactions_given_count":{"type":"integer"},"reactions_received_count":{"type":"integer"},"poll_votes_count":{"type":"integer"},"button_clicks_count":{"type":"integer"},"media_count":{"type":"integer"},"engagement_score":{"type":"string"},"last_active_at":{"type":"string","format":"date-time"},"joined_at":{"type":"string","format":"date-time"}}}}}}}},"example":{"payload":{"id":1,"account_id":1,"inbox_id":1,"logical_inbox_id":1,"jid":"sample jid","kind":"group","name":"Sample Name","topic":"sample topic","role":"owner","is_parent":true,"is_default_sub":true,"community_jid":"sample community jid","photo_url":"https://example.com/resource","invite_code":"sample invite code","participant_count":5,"maestro_enabled":true,"settings":"sample settings","greeting":"sample greeting","engagement":"sample engagement","custom_attributes":{},"synced_at":"2026-01-15T10:30:00.000Z","archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","distribution":{"unit_id":1,"unit_sequence":"sample unit sequence","unit_name":"sample unit name","distribution_id":1,"distribution_name":"sample distribution name"},"participants":[{"id":1,"jid":"sample jid","phone":"+5511999998888","name":"Sample Name","display_name":"sample display name","role":"agent","status":"active","contact_id":1,"messages_count":5,"replies_count":5,"reactions_given_count":5,"reactions_received_count":5,"poll_votes_count":5,"button_clicks_count":5,"media_count":5,"engagement_score":"sample engagement score","last_active_at":"2026-01-15T10:30:00.000Z","joined_at":"2026-01-15T10:30:00.000Z"}]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]},"patch":{"tags":["WhatsApp Hub"],"operationId":"auto_patch_api_v1_accounts_account_id_whatsapp_hub_groups_id","summary":"Update groups","description":"Updates the group identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"inbox_id":{"type":"integer"},"logical_inbox_id":{"type":"integer"},"jid":{"type":"string"},"kind":{"type":"string","enum":["group","community","channel"],"description":"Container type of the WhatsApp entity."},"name":{"type":"string"},"topic":{"type":"string"},"role":{"type":"string","enum":["owner","admin","member","subscriber"],"description":"Operator/participant role within the group."},"is_parent":{"type":"boolean"},"is_default_sub":{"type":"boolean"},"community_jid":{"type":"string"},"photo_url":{"type":"string"},"invite_code":{"type":"string"},"participant_count":{"type":"integer"},"maestro_enabled":{"type":"boolean"},"settings":{"type":"string"},"greeting":{"type":"string"},"engagement":{"type":"string"},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"synced_at":{"type":"string","format":"date-time"},"archived_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"distribution":{"type":"object","properties":{"unit_id":{"type":"integer"},"unit_sequence":{"type":"string"},"unit_name":{"type":"string"},"distribution_id":{"type":"integer"},"distribution_name":{"type":["string","null"]}}},"participants":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"jid":{"type":"string"},"phone":{"type":"string"},"name":{"type":"string"},"display_name":{"type":"string"},"role":{"type":"string","enum":["agent","administrator"],"description":"Operator/participant role within the group."},"status":{"type":"string","enum":["active","left","removed","pending"],"description":"Membership status of the group participant."},"contact_id":{"type":"integer"},"messages_count":{"type":"integer"},"replies_count":{"type":"integer"},"reactions_given_count":{"type":"integer"},"reactions_received_count":{"type":"integer"},"poll_votes_count":{"type":"integer"},"button_clicks_count":{"type":"integer"},"media_count":{"type":"integer"},"engagement_score":{"type":"string"},"last_active_at":{"type":"string","format":"date-time"},"joined_at":{"type":"string","format":"date-time"}}}}}}}},"example":{"payload":{"id":1,"account_id":1,"inbox_id":1,"logical_inbox_id":1,"jid":"sample jid","kind":"group","name":"Sample Name","topic":"sample topic","role":"owner","is_parent":true,"is_default_sub":true,"community_jid":"sample community jid","photo_url":"https://example.com/resource","invite_code":"sample invite code","participant_count":5,"maestro_enabled":true,"settings":"sample settings","greeting":"sample greeting","engagement":"sample engagement","custom_attributes":{},"synced_at":"2026-01-15T10:30:00.000Z","archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","distribution":{"unit_id":1,"unit_sequence":"sample unit sequence","unit_name":"sample unit name","distribution_id":1,"distribution_name":"sample distribution name"},"participants":[{"id":1,"jid":"sample jid","phone":"+5511999998888","name":"Sample Name","display_name":"sample display name","role":"agent","status":"active","contact_id":1,"messages_count":5,"replies_count":5,"reactions_given_count":5,"reactions_received_count":5,"poll_votes_count":5,"button_clicks_count":5,"media_count":5,"engagement_score":"sample engagement score","last_active_at":"2026-01-15T10:30:00.000Z","joined_at":"2026-01-15T10:30:00.000Z"}]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"topic":{"type":"string"},"announce":{"type":"boolean"},"locked":{"type":"boolean"},"ephemeral_seconds":{"type":"integer"},"participants":{"type":"array","items":{"type":"string"}}}},"example":{"name":"Sample Name","topic":"sample topic","announce":true,"locked":true,"ephemeral_seconds":60,"participants":["sample participant"]}}}}},"put":{"tags":["WhatsApp Hub"],"operationId":"auto_put_api_v1_accounts_account_id_whatsapp_hub_groups_id","summary":"Update groups","description":"Updates the group identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"inbox_id":{"type":"integer"},"logical_inbox_id":{"type":"integer"},"jid":{"type":"string"},"kind":{"type":"string","enum":["group","community","channel"],"description":"Container type of the WhatsApp entity."},"name":{"type":"string"},"topic":{"type":"string"},"role":{"type":"string","enum":["owner","admin","member","subscriber"],"description":"Operator/participant role within the group."},"is_parent":{"type":"boolean"},"is_default_sub":{"type":"boolean"},"community_jid":{"type":"string"},"photo_url":{"type":"string"},"invite_code":{"type":"string"},"participant_count":{"type":"integer"},"maestro_enabled":{"type":"boolean"},"settings":{"type":"string"},"greeting":{"type":"string"},"engagement":{"type":"string"},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"synced_at":{"type":"string","format":"date-time"},"archived_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"distribution":{"type":"object","properties":{"unit_id":{"type":"integer"},"unit_sequence":{"type":"string"},"unit_name":{"type":"string"},"distribution_id":{"type":"integer"},"distribution_name":{"type":["string","null"]}}},"participants":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"jid":{"type":"string"},"phone":{"type":"string"},"name":{"type":"string"},"display_name":{"type":"string"},"role":{"type":"string","enum":["agent","administrator"],"description":"Operator/participant role within the group."},"status":{"type":"string","enum":["active","left","removed","pending"],"description":"Membership status of the group participant."},"contact_id":{"type":"integer"},"messages_count":{"type":"integer"},"replies_count":{"type":"integer"},"reactions_given_count":{"type":"integer"},"reactions_received_count":{"type":"integer"},"poll_votes_count":{"type":"integer"},"button_clicks_count":{"type":"integer"},"media_count":{"type":"integer"},"engagement_score":{"type":"string"},"last_active_at":{"type":"string","format":"date-time"},"joined_at":{"type":"string","format":"date-time"}}}}}}}},"example":{"payload":{"id":1,"account_id":1,"inbox_id":1,"logical_inbox_id":1,"jid":"sample jid","kind":"group","name":"Sample Name","topic":"sample topic","role":"owner","is_parent":true,"is_default_sub":true,"community_jid":"sample community jid","photo_url":"https://example.com/resource","invite_code":"sample invite code","participant_count":5,"maestro_enabled":true,"settings":"sample settings","greeting":"sample greeting","engagement":"sample engagement","custom_attributes":{},"synced_at":"2026-01-15T10:30:00.000Z","archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","distribution":{"unit_id":1,"unit_sequence":"sample unit sequence","unit_name":"sample unit name","distribution_id":1,"distribution_name":"sample distribution name"},"participants":[{"id":1,"jid":"sample jid","phone":"+5511999998888","name":"Sample Name","display_name":"sample display name","role":"agent","status":"active","contact_id":1,"messages_count":5,"replies_count":5,"reactions_given_count":5,"reactions_received_count":5,"poll_votes_count":5,"button_clicks_count":5,"media_count":5,"engagement_score":"sample engagement score","last_active_at":"2026-01-15T10:30:00.000Z","joined_at":"2026-01-15T10:30:00.000Z"}]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"topic":{"type":"string"},"announce":{"type":"boolean"},"locked":{"type":"boolean"},"ephemeral_seconds":{"type":"integer"},"participants":{"type":"array","items":{"type":"string"}}}},"example":{"name":"Sample Name","topic":"sample topic","announce":true,"locked":true,"ephemeral_seconds":60,"participants":["sample participant"]}}}}}},"/api/v1/accounts/{account_id}/whatsapp_hub/channels/{id}/archive":{"post":{"tags":["WhatsApp Hub"],"operationId":"auto_post_api_v1_accounts_account_id_whatsapp_hub_channels_id_archive","summary":"Archive channels","description":"Performs the archive operation on the targeted channel resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Channel archived (archived_at set).","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer","example":42},"account_id":{"type":"integer","example":1},"inbox_id":{"type":"integer","example":7},"jid":{"type":"string","example":"120363021234567890@g.us","description":"WhatsApp JID. Groups/communities end in @g.us; channels (newsletters) end in @newsletter."},"kind":{"type":"string","example":"group","enum":["group","community","channel"],"description":"Container type."},"name":{"type":["string","null"],"example":"Lancamento Turma 12"},"topic":{"type":["string","null"],"example":"Avisos e materiais da turma"},"role":{"type":"string","example":"admin","enum":["owner","admin","member","subscriber"],"description":"The connected account's role in this container."},"is_parent":{"type":"boolean","example":false,"description":"True for a community parent row."},"is_default_sub":{"type":"boolean","example":false,"description":"True for a community's default/announcement sub-group."},"community_jid":{"type":["string","null"],"example":"120363039876543210@g.us","description":"Parent community JID when this group is linked to one."},"photo_url":{"type":["string","null"],"example":"https://pps.whatsapp.net/v/t61.24694-24/group-avatar.jpg"},"invite_code":{"type":["string","null"],"example":"Hkq0dEXAMPLEabcdef"},"participant_count":{"type":"integer","example":128},"maestro_enabled":{"type":"string","example":"inherit","enum":["inherit","on","off"],"description":"Per-group Maestro AI gate. inherit resolves to the inbox group_ai_policy."},"settings":{"type":"object","description":"Mirrored WhatsApp group settings.","properties":{"announce":{"type":"boolean","example":false,"description":"Only admins can post."},"locked":{"type":"boolean","example":false,"description":"Only admins can edit group info."},"ephemeral":{"type":["integer","null"],"example":0,"description":"Disappearing-message timer in seconds (0 = off)."}},"example":{"announce":false,"locked":false,"ephemeral":0}},"greeting":{"type":"object","description":"Per-group welcome/farewell override merged over the inbox default. Empty object = inherit.","properties":{"welcome":{"type":"object","properties":{"enabled":{"type":"boolean","example":true},"in_group":{"type":"boolean","example":true},"dm":{"type":"boolean","example":false},"template":{"type":"string","example":"Bem-vindo(a), {{name}}!"}}},"farewell":{"type":"object","properties":{"enabled":{"type":"boolean","example":false},"in_group":{"type":"boolean","example":false},"dm":{"type":"boolean","example":false},"template":{"type":"string","example":""}}}},"example":{"welcome":{"enabled":true,"in_group":true,"dm":false,"template":"Bem-vindo(a), {{name}}!"},"farewell":{"enabled":false,"in_group":false,"dm":false,"template":""}}},"engagement":{"type":"object","additionalProperties":true,"description":"Group-level engagement rollup (empty until computed).","example":{}},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Account-defined whatsapp_group custom attributes.","example":{}},"synced_at":{"type":["string","null"],"format":"date-time","example":"2026-01-15T10:30:00.000Z"},"archived_at":{"type":["string","null"],"format":"date-time","example":"2026-01-15T10:30:00.000Z"},"created_at":{"type":"string","format":"date-time","example":"2026-01-10T08:00:00.000Z"},"updated_at":{"type":"string","format":"date-time","example":"2026-01-15T10:30:00.000Z"},"distribution":{"type":["object","null"],"description":"Cross-link to the distribution unit (Turma) this group backs. Present on detail only when eager-loaded.","properties":{"unit_id":{"type":"integer","example":5},"unit_sequence":{"type":"integer","example":3},"unit_name":{"type":"string","example":"Turma 12 - Grupo 3"},"distribution_id":{"type":"integer","example":2},"distribution_name":{"type":["string","null"],"example":"Lancamento Janeiro"}},"example":{"unit_id":5,"unit_sequence":3,"unit_name":"Turma 12 - Grupo 3","distribution_id":2,"distribution_name":"Lancamento Janeiro"}},"participants":{"type":"array","description":"Active members ranked by engagement_score desc.","items":{"type":"object","properties":{"id":{"type":"integer","example":501},"jid":{"type":"string","example":"5521999998888@s.whatsapp.net"},"phone":{"type":["string","null"],"example":"+5521999998888"},"name":{"type":["string","null"],"example":"Maria Silva"},"display_name":{"type":["string","null"],"example":"Maria Silva","description":"Best real (non-phone, non-placeholder) name; null when only a phone/placeholder is known."},"role":{"type":"string","example":"member","enum":["owner","admin","member","subscriber"]},"status":{"type":"string","example":"active","enum":["active","left","removed","pending"]},"contact_id":{"type":["integer","null"],"example":3021},"messages_count":{"type":"integer","example":42},"replies_count":{"type":"integer","example":12},"reactions_given_count":{"type":"integer","example":8},"reactions_received_count":{"type":"integer","example":15},"poll_votes_count":{"type":"integer","example":3},"button_clicks_count":{"type":"integer","example":1},"media_count":{"type":"integer","example":5},"engagement_score":{"type":"number","example":57.5},"last_active_at":{"type":["string","null"],"format":"date-time","example":"2026-01-15T09:45:00.000Z"},"joined_at":{"type":["string","null"],"format":"date-time","example":"2026-01-10T08:05:00.000Z"}}}}}}}},"example":{"payload":{"id":42,"account_id":1,"inbox_id":7,"jid":"120363021234567890@g.us","kind":"group","name":"Lancamento Turma 12","topic":"Avisos e materiais da turma","role":"admin","is_parent":false,"is_default_sub":false,"community_jid":"120363039876543210@g.us","photo_url":"https://pps.whatsapp.net/v/t61.24694-24/group-avatar.jpg","invite_code":"Hkq0dEXAMPLEabcdef","participant_count":128,"maestro_enabled":"inherit","settings":{"announce":false,"locked":false,"ephemeral":0},"greeting":{"welcome":{"enabled":true,"in_group":true,"dm":false,"template":"Bem-vindo(a), {{name}}!"},"farewell":{"enabled":false,"in_group":false,"dm":false,"template":""}},"engagement":{},"custom_attributes":{},"synced_at":"2026-01-15T10:30:00.000Z","archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-10T08:00:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","distribution":{"unit_id":5,"unit_sequence":3,"unit_name":"Turma 12 - Grupo 3","distribution_id":2,"distribution_name":"Lancamento Janeiro"},"participants":[{"id":501,"jid":"5521999998888@s.whatsapp.net","phone":"+5521999998888","name":"Maria Silva","display_name":"Maria Silva","role":"member","status":"active","contact_id":3021,"messages_count":42,"replies_count":12,"reactions_given_count":8,"reactions_received_count":15,"poll_votes_count":3,"button_clicks_count":1,"media_count":5,"engagement_score":57.5,"last_active_at":"2026-01-15T09:45:00.000Z","joined_at":"2026-01-10T08:05:00.000Z"}]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/whatsapp_hub/channels/{id}/restore":{"post":{"tags":["WhatsApp Hub"],"operationId":"auto_post_api_v1_accounts_account_id_whatsapp_hub_channels_id_restore","summary":"Restore channels","description":"Performs the restore operation on the targeted channel resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Channel restored (archived_at cleared).","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer","example":42},"account_id":{"type":"integer","example":1},"inbox_id":{"type":"integer","example":7},"jid":{"type":"string","example":"120363021234567890@g.us","description":"WhatsApp JID. Groups/communities end in @g.us; channels (newsletters) end in @newsletter."},"kind":{"type":"string","example":"group","enum":["group","community","channel"],"description":"Container type."},"name":{"type":["string","null"],"example":"Lancamento Turma 12"},"topic":{"type":["string","null"],"example":"Avisos e materiais da turma"},"role":{"type":"string","example":"admin","enum":["owner","admin","member","subscriber"],"description":"The connected account's role in this container."},"is_parent":{"type":"boolean","example":false,"description":"True for a community parent row."},"is_default_sub":{"type":"boolean","example":false,"description":"True for a community's default/announcement sub-group."},"community_jid":{"type":["string","null"],"example":"120363039876543210@g.us","description":"Parent community JID when this group is linked to one."},"photo_url":{"type":["string","null"],"example":"https://pps.whatsapp.net/v/t61.24694-24/group-avatar.jpg"},"invite_code":{"type":["string","null"],"example":"Hkq0dEXAMPLEabcdef"},"participant_count":{"type":"integer","example":128},"maestro_enabled":{"type":"string","example":"inherit","enum":["inherit","on","off"],"description":"Per-group Maestro AI gate. inherit resolves to the inbox group_ai_policy."},"settings":{"type":"object","description":"Mirrored WhatsApp group settings.","properties":{"announce":{"type":"boolean","example":false,"description":"Only admins can post."},"locked":{"type":"boolean","example":false,"description":"Only admins can edit group info."},"ephemeral":{"type":["integer","null"],"example":0,"description":"Disappearing-message timer in seconds (0 = off)."}},"example":{"announce":false,"locked":false,"ephemeral":0}},"greeting":{"type":"object","description":"Per-group welcome/farewell override merged over the inbox default. Empty object = inherit.","properties":{"welcome":{"type":"object","properties":{"enabled":{"type":"boolean","example":true},"in_group":{"type":"boolean","example":true},"dm":{"type":"boolean","example":false},"template":{"type":"string","example":"Bem-vindo(a), {{name}}!"}}},"farewell":{"type":"object","properties":{"enabled":{"type":"boolean","example":false},"in_group":{"type":"boolean","example":false},"dm":{"type":"boolean","example":false},"template":{"type":"string","example":""}}}},"example":{"welcome":{"enabled":true,"in_group":true,"dm":false,"template":"Bem-vindo(a), {{name}}!"},"farewell":{"enabled":false,"in_group":false,"dm":false,"template":""}}},"engagement":{"type":"object","additionalProperties":true,"description":"Group-level engagement rollup (empty until computed).","example":{}},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Account-defined whatsapp_group custom attributes.","example":{}},"synced_at":{"type":["string","null"],"format":"date-time","example":"2026-01-15T10:30:00.000Z"},"archived_at":{"type":["string","null"],"format":"date-time","example":"2026-01-15T10:30:00.000Z"},"created_at":{"type":"string","format":"date-time","example":"2026-01-10T08:00:00.000Z"},"updated_at":{"type":"string","format":"date-time","example":"2026-01-15T10:30:00.000Z"},"distribution":{"type":["object","null"],"description":"Cross-link to the distribution unit (Turma) this group backs. Present on detail only when eager-loaded.","properties":{"unit_id":{"type":"integer","example":5},"unit_sequence":{"type":"integer","example":3},"unit_name":{"type":"string","example":"Turma 12 - Grupo 3"},"distribution_id":{"type":"integer","example":2},"distribution_name":{"type":["string","null"],"example":"Lancamento Janeiro"}},"example":{"unit_id":5,"unit_sequence":3,"unit_name":"Turma 12 - Grupo 3","distribution_id":2,"distribution_name":"Lancamento Janeiro"}},"participants":{"type":"array","description":"Active members ranked by engagement_score desc.","items":{"type":"object","properties":{"id":{"type":"integer","example":501},"jid":{"type":"string","example":"5521999998888@s.whatsapp.net"},"phone":{"type":["string","null"],"example":"+5521999998888"},"name":{"type":["string","null"],"example":"Maria Silva"},"display_name":{"type":["string","null"],"example":"Maria Silva","description":"Best real (non-phone, non-placeholder) name; null when only a phone/placeholder is known."},"role":{"type":"string","example":"member","enum":["owner","admin","member","subscriber"]},"status":{"type":"string","example":"active","enum":["active","left","removed","pending"]},"contact_id":{"type":["integer","null"],"example":3021},"messages_count":{"type":"integer","example":42},"replies_count":{"type":"integer","example":12},"reactions_given_count":{"type":"integer","example":8},"reactions_received_count":{"type":"integer","example":15},"poll_votes_count":{"type":"integer","example":3},"button_clicks_count":{"type":"integer","example":1},"media_count":{"type":"integer","example":5},"engagement_score":{"type":"number","example":57.5},"last_active_at":{"type":["string","null"],"format":"date-time","example":"2026-01-15T09:45:00.000Z"},"joined_at":{"type":["string","null"],"format":"date-time","example":"2026-01-10T08:05:00.000Z"}}}}}}}},"example":{"payload":{"id":42,"account_id":1,"inbox_id":7,"jid":"120363021234567890@g.us","kind":"group","name":"Lancamento Turma 12","topic":"Avisos e materiais da turma","role":"admin","is_parent":false,"is_default_sub":false,"community_jid":"120363039876543210@g.us","photo_url":"https://pps.whatsapp.net/v/t61.24694-24/group-avatar.jpg","invite_code":"Hkq0dEXAMPLEabcdef","participant_count":128,"maestro_enabled":"inherit","settings":{"announce":false,"locked":false,"ephemeral":0},"greeting":{"welcome":{"enabled":true,"in_group":true,"dm":false,"template":"Bem-vindo(a), {{name}}!"},"farewell":{"enabled":false,"in_group":false,"dm":false,"template":""}},"engagement":{},"custom_attributes":{},"synced_at":"2026-01-15T10:30:00.000Z","archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-10T08:00:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","distribution":{"unit_id":5,"unit_sequence":3,"unit_name":"Turma 12 - Grupo 3","distribution_id":2,"distribution_name":"Lancamento Janeiro"},"participants":[{"id":501,"jid":"5521999998888@s.whatsapp.net","phone":"+5521999998888","name":"Maria Silva","display_name":"Maria Silva","role":"member","status":"active","contact_id":3021,"messages_count":42,"replies_count":12,"reactions_given_count":8,"reactions_received_count":15,"poll_votes_count":3,"button_clicks_count":1,"media_count":5,"engagement_score":57.5,"last_active_at":"2026-01-15T09:45:00.000Z","joined_at":"2026-01-10T08:05:00.000Z"}]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/whatsapp_hub/channels/{id}/leave":{"post":{"tags":["WhatsApp Hub"],"operationId":"auto_post_api_v1_accounts_account_id_whatsapp_hub_channels_id_leave","summary":"Leave channels","description":"Performs the leave operation on the targeted channel resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Channel unfollowed on WhatsApp and archived locally.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer","example":42},"account_id":{"type":"integer","example":1},"inbox_id":{"type":"integer","example":7},"jid":{"type":"string","example":"120363021234567890@g.us","description":"WhatsApp JID. Groups/communities end in @g.us; channels (newsletters) end in @newsletter."},"kind":{"type":"string","example":"group","enum":["group","community","channel"],"description":"Container type."},"name":{"type":["string","null"],"example":"Lancamento Turma 12"},"topic":{"type":["string","null"],"example":"Avisos e materiais da turma"},"role":{"type":"string","example":"admin","enum":["owner","admin","member","subscriber"],"description":"The connected account's role in this container."},"is_parent":{"type":"boolean","example":false,"description":"True for a community parent row."},"is_default_sub":{"type":"boolean","example":false,"description":"True for a community's default/announcement sub-group."},"community_jid":{"type":["string","null"],"example":"120363039876543210@g.us","description":"Parent community JID when this group is linked to one."},"photo_url":{"type":["string","null"],"example":"https://pps.whatsapp.net/v/t61.24694-24/group-avatar.jpg"},"invite_code":{"type":["string","null"],"example":"Hkq0dEXAMPLEabcdef"},"participant_count":{"type":"integer","example":128},"maestro_enabled":{"type":"string","example":"inherit","enum":["inherit","on","off"],"description":"Per-group Maestro AI gate. inherit resolves to the inbox group_ai_policy."},"settings":{"type":"object","description":"Mirrored WhatsApp group settings.","properties":{"announce":{"type":"boolean","example":false,"description":"Only admins can post."},"locked":{"type":"boolean","example":false,"description":"Only admins can edit group info."},"ephemeral":{"type":["integer","null"],"example":0,"description":"Disappearing-message timer in seconds (0 = off)."}},"example":{"announce":false,"locked":false,"ephemeral":0}},"greeting":{"type":"object","description":"Per-group welcome/farewell override merged over the inbox default. Empty object = inherit.","properties":{"welcome":{"type":"object","properties":{"enabled":{"type":"boolean","example":true},"in_group":{"type":"boolean","example":true},"dm":{"type":"boolean","example":false},"template":{"type":"string","example":"Bem-vindo(a), {{name}}!"}}},"farewell":{"type":"object","properties":{"enabled":{"type":"boolean","example":false},"in_group":{"type":"boolean","example":false},"dm":{"type":"boolean","example":false},"template":{"type":"string","example":""}}}},"example":{"welcome":{"enabled":true,"in_group":true,"dm":false,"template":"Bem-vindo(a), {{name}}!"},"farewell":{"enabled":false,"in_group":false,"dm":false,"template":""}}},"engagement":{"type":"object","additionalProperties":true,"description":"Group-level engagement rollup (empty until computed).","example":{}},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Account-defined whatsapp_group custom attributes.","example":{}},"synced_at":{"type":["string","null"],"format":"date-time","example":"2026-01-15T10:30:00.000Z"},"archived_at":{"type":["string","null"],"format":"date-time","example":"2026-01-15T10:30:00.000Z"},"created_at":{"type":"string","format":"date-time","example":"2026-01-10T08:00:00.000Z"},"updated_at":{"type":"string","format":"date-time","example":"2026-01-15T10:30:00.000Z"},"distribution":{"type":["object","null"],"description":"Cross-link to the distribution unit (Turma) this group backs. Present on detail only when eager-loaded.","properties":{"unit_id":{"type":"integer","example":5},"unit_sequence":{"type":"integer","example":3},"unit_name":{"type":"string","example":"Turma 12 - Grupo 3"},"distribution_id":{"type":"integer","example":2},"distribution_name":{"type":["string","null"],"example":"Lancamento Janeiro"}},"example":{"unit_id":5,"unit_sequence":3,"unit_name":"Turma 12 - Grupo 3","distribution_id":2,"distribution_name":"Lancamento Janeiro"}},"participants":{"type":"array","description":"Active members ranked by engagement_score desc.","items":{"type":"object","properties":{"id":{"type":"integer","example":501},"jid":{"type":"string","example":"5521999998888@s.whatsapp.net"},"phone":{"type":["string","null"],"example":"+5521999998888"},"name":{"type":["string","null"],"example":"Maria Silva"},"display_name":{"type":["string","null"],"example":"Maria Silva","description":"Best real (non-phone, non-placeholder) name; null when only a phone/placeholder is known."},"role":{"type":"string","example":"member","enum":["owner","admin","member","subscriber"]},"status":{"type":"string","example":"active","enum":["active","left","removed","pending"]},"contact_id":{"type":["integer","null"],"example":3021},"messages_count":{"type":"integer","example":42},"replies_count":{"type":"integer","example":12},"reactions_given_count":{"type":"integer","example":8},"reactions_received_count":{"type":"integer","example":15},"poll_votes_count":{"type":"integer","example":3},"button_clicks_count":{"type":"integer","example":1},"media_count":{"type":"integer","example":5},"engagement_score":{"type":"number","example":57.5},"last_active_at":{"type":["string","null"],"format":"date-time","example":"2026-01-15T09:45:00.000Z"},"joined_at":{"type":["string","null"],"format":"date-time","example":"2026-01-10T08:05:00.000Z"}}}}}}}},"example":{"payload":{"id":42,"account_id":1,"inbox_id":7,"jid":"120363021234567890@g.us","kind":"group","name":"Lancamento Turma 12","topic":"Avisos e materiais da turma","role":"admin","is_parent":false,"is_default_sub":false,"community_jid":"120363039876543210@g.us","photo_url":"https://pps.whatsapp.net/v/t61.24694-24/group-avatar.jpg","invite_code":"Hkq0dEXAMPLEabcdef","participant_count":128,"maestro_enabled":"inherit","settings":{"announce":false,"locked":false,"ephemeral":0},"greeting":{"welcome":{"enabled":true,"in_group":true,"dm":false,"template":"Bem-vindo(a), {{name}}!"},"farewell":{"enabled":false,"in_group":false,"dm":false,"template":""}},"engagement":{},"custom_attributes":{},"synced_at":"2026-01-15T10:30:00.000Z","archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-10T08:00:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","distribution":{"unit_id":5,"unit_sequence":3,"unit_name":"Turma 12 - Grupo 3","distribution_id":2,"distribution_name":"Lancamento Janeiro"},"participants":[{"id":501,"jid":"5521999998888@s.whatsapp.net","phone":"+5521999998888","name":"Maria Silva","display_name":"Maria Silva","role":"member","status":"active","contact_id":3021,"messages_count":42,"replies_count":12,"reactions_given_count":8,"reactions_received_count":15,"poll_votes_count":3,"button_clicks_count":1,"media_count":5,"engagement_score":57.5,"last_active_at":"2026-01-15T09:45:00.000Z","joined_at":"2026-01-10T08:05:00.000Z"}]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/whatsapp_hub/channels/{id}/open_conversation":{"post":{"tags":["WhatsApp Hub"],"operationId":"auto_post_api_v1_accounts_account_id_whatsapp_hub_channels_id_open_conversation","summary":"Open conversation channels","description":"Performs the open conversation operation on the targeted channel resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"string"}}},"example":{"payload":"sample payload"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/whatsapp_hub/channels/{channel_id}/maestro":{"patch":{"tags":["WhatsApp Hub"],"operationId":"auto_patch_api_v1_accounts_account_id_whatsapp_hub_channels_channel_id_maestro","summary":"Update maestro","description":"Updates the maestro identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Group/channel with the updated Maestro gate applied.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer","example":42},"account_id":{"type":"integer","example":1},"inbox_id":{"type":"integer","example":7},"jid":{"type":"string","example":"120363021234567890@g.us","description":"WhatsApp JID. Groups/communities end in @g.us; channels (newsletters) end in @newsletter."},"kind":{"type":"string","example":"group","enum":["group","community","channel"],"description":"Container type."},"name":{"type":["string","null"],"example":"Lancamento Turma 12"},"topic":{"type":["string","null"],"example":"Avisos e materiais da turma"},"role":{"type":"string","example":"admin","enum":["owner","admin","member","subscriber"],"description":"The connected account's role in this container."},"is_parent":{"type":"boolean","example":false,"description":"True for a community parent row."},"is_default_sub":{"type":"boolean","example":false,"description":"True for a community's default/announcement sub-group."},"community_jid":{"type":["string","null"],"example":"120363039876543210@g.us","description":"Parent community JID when this group is linked to one."},"photo_url":{"type":["string","null"],"example":"https://pps.whatsapp.net/v/t61.24694-24/group-avatar.jpg"},"invite_code":{"type":["string","null"],"example":"Hkq0dEXAMPLEabcdef"},"participant_count":{"type":"integer","example":128},"maestro_enabled":{"type":"string","example":"inherit","enum":["inherit","on","off"],"description":"Per-group Maestro AI gate. inherit resolves to the inbox group_ai_policy."},"settings":{"type":"object","description":"Mirrored WhatsApp group settings.","properties":{"announce":{"type":"boolean","example":false,"description":"Only admins can post."},"locked":{"type":"boolean","example":false,"description":"Only admins can edit group info."},"ephemeral":{"type":["integer","null"],"example":0,"description":"Disappearing-message timer in seconds (0 = off)."}},"example":{"announce":false,"locked":false,"ephemeral":0}},"greeting":{"type":"object","description":"Per-group welcome/farewell override merged over the inbox default. Empty object = inherit.","properties":{"welcome":{"type":"object","properties":{"enabled":{"type":"boolean","example":true},"in_group":{"type":"boolean","example":true},"dm":{"type":"boolean","example":false},"template":{"type":"string","example":"Bem-vindo(a), {{name}}!"}}},"farewell":{"type":"object","properties":{"enabled":{"type":"boolean","example":false},"in_group":{"type":"boolean","example":false},"dm":{"type":"boolean","example":false},"template":{"type":"string","example":""}}}},"example":{"welcome":{"enabled":true,"in_group":true,"dm":false,"template":"Bem-vindo(a), {{name}}!"},"farewell":{"enabled":false,"in_group":false,"dm":false,"template":""}}},"engagement":{"type":"object","additionalProperties":true,"description":"Group-level engagement rollup (empty until computed).","example":{}},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Account-defined whatsapp_group custom attributes.","example":{}},"synced_at":{"type":["string","null"],"format":"date-time","example":"2026-01-15T10:30:00.000Z"},"archived_at":{"type":["string","null"],"format":"date-time","example":"2026-01-15T10:30:00.000Z"},"created_at":{"type":"string","format":"date-time","example":"2026-01-10T08:00:00.000Z"},"updated_at":{"type":"string","format":"date-time","example":"2026-01-15T10:30:00.000Z"},"distribution":{"type":["object","null"],"description":"Cross-link to the distribution unit (Turma) this group backs. Present on detail only when eager-loaded.","properties":{"unit_id":{"type":"integer","example":5},"unit_sequence":{"type":"integer","example":3},"unit_name":{"type":"string","example":"Turma 12 - Grupo 3"},"distribution_id":{"type":"integer","example":2},"distribution_name":{"type":["string","null"],"example":"Lancamento Janeiro"}},"example":{"unit_id":5,"unit_sequence":3,"unit_name":"Turma 12 - Grupo 3","distribution_id":2,"distribution_name":"Lancamento Janeiro"}},"participants":{"type":"array","description":"Active members ranked by engagement_score desc.","items":{"type":"object","properties":{"id":{"type":"integer","example":501},"jid":{"type":"string","example":"5521999998888@s.whatsapp.net"},"phone":{"type":["string","null"],"example":"+5521999998888"},"name":{"type":["string","null"],"example":"Maria Silva"},"display_name":{"type":["string","null"],"example":"Maria Silva","description":"Best real (non-phone, non-placeholder) name; null when only a phone/placeholder is known."},"role":{"type":"string","example":"member","enum":["owner","admin","member","subscriber"],"description":"Operator/participant role within the group."},"status":{"type":"string","example":"active","enum":["active","left","removed","pending"],"description":"Membership status of the group participant."},"contact_id":{"type":["integer","null"],"example":3021},"messages_count":{"type":"integer","example":42},"replies_count":{"type":"integer","example":12},"reactions_given_count":{"type":"integer","example":8},"reactions_received_count":{"type":"integer","example":15},"poll_votes_count":{"type":"integer","example":3},"button_clicks_count":{"type":"integer","example":1},"media_count":{"type":"integer","example":5},"engagement_score":{"type":"number","example":57.5},"last_active_at":{"type":["string","null"],"format":"date-time","example":"2026-01-15T09:45:00.000Z"},"joined_at":{"type":["string","null"],"format":"date-time","example":"2026-01-10T08:05:00.000Z"}}}}}}}},"example":{"payload":{"id":42,"account_id":1,"inbox_id":7,"jid":"120363021234567890@g.us","kind":"group","name":"Lancamento Turma 12","topic":"Avisos e materiais da turma","role":"admin","is_parent":false,"is_default_sub":false,"community_jid":"120363039876543210@g.us","photo_url":"https://pps.whatsapp.net/v/t61.24694-24/group-avatar.jpg","invite_code":"Hkq0dEXAMPLEabcdef","participant_count":128,"maestro_enabled":"inherit","settings":{"announce":false,"locked":false,"ephemeral":0},"greeting":{"welcome":{"enabled":true,"in_group":true,"dm":false,"template":"Bem-vindo(a), {{name}}!"},"farewell":{"enabled":false,"in_group":false,"dm":false,"template":""}},"engagement":{},"custom_attributes":{},"synced_at":"2026-01-15T10:30:00.000Z","archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-10T08:00:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","distribution":{"unit_id":5,"unit_sequence":3,"unit_name":"Turma 12 - Grupo 3","distribution_id":2,"distribution_name":"Lancamento Janeiro"},"participants":[{"id":501,"jid":"5521999998888@s.whatsapp.net","phone":"+5521999998888","name":"Maria Silva","display_name":"Maria Silva","role":"member","status":"active","contact_id":3021,"messages_count":42,"replies_count":12,"reactions_given_count":8,"reactions_received_count":15,"poll_votes_count":3,"button_clicks_count":1,"media_count":5,"engagement_score":57.5,"last_active_at":"2026-01-15T09:45:00.000Z","joined_at":"2026-01-10T08:05:00.000Z"}]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"channel_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"maestro_enabled":{"type":"boolean"},"group_id":{"type":"integer"}}},"example":{"maestro_enabled":true,"group_id":1}}}}},"put":{"tags":["WhatsApp Hub"],"operationId":"auto_put_api_v1_accounts_account_id_whatsapp_hub_channels_channel_id_maestro","summary":"Update maestro","description":"Updates the maestro identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Group/channel with the updated Maestro gate applied.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer","example":42},"account_id":{"type":"integer","example":1},"inbox_id":{"type":"integer","example":7},"jid":{"type":"string","example":"120363021234567890@g.us","description":"WhatsApp JID. Groups/communities end in @g.us; channels (newsletters) end in @newsletter."},"kind":{"type":"string","example":"group","enum":["group","community","channel"],"description":"Container type."},"name":{"type":["string","null"],"example":"Lancamento Turma 12"},"topic":{"type":["string","null"],"example":"Avisos e materiais da turma"},"role":{"type":"string","example":"admin","enum":["owner","admin","member","subscriber"],"description":"The connected account's role in this container."},"is_parent":{"type":"boolean","example":false,"description":"True for a community parent row."},"is_default_sub":{"type":"boolean","example":false,"description":"True for a community's default/announcement sub-group."},"community_jid":{"type":["string","null"],"example":"120363039876543210@g.us","description":"Parent community JID when this group is linked to one."},"photo_url":{"type":["string","null"],"example":"https://pps.whatsapp.net/v/t61.24694-24/group-avatar.jpg"},"invite_code":{"type":["string","null"],"example":"Hkq0dEXAMPLEabcdef"},"participant_count":{"type":"integer","example":128},"maestro_enabled":{"type":"string","example":"inherit","enum":["inherit","on","off"],"description":"Per-group Maestro AI gate. inherit resolves to the inbox group_ai_policy."},"settings":{"type":"object","description":"Mirrored WhatsApp group settings.","properties":{"announce":{"type":"boolean","example":false,"description":"Only admins can post."},"locked":{"type":"boolean","example":false,"description":"Only admins can edit group info."},"ephemeral":{"type":["integer","null"],"example":0,"description":"Disappearing-message timer in seconds (0 = off)."}},"example":{"announce":false,"locked":false,"ephemeral":0}},"greeting":{"type":"object","description":"Per-group welcome/farewell override merged over the inbox default. Empty object = inherit.","properties":{"welcome":{"type":"object","properties":{"enabled":{"type":"boolean","example":true},"in_group":{"type":"boolean","example":true},"dm":{"type":"boolean","example":false},"template":{"type":"string","example":"Bem-vindo(a), {{name}}!"}}},"farewell":{"type":"object","properties":{"enabled":{"type":"boolean","example":false},"in_group":{"type":"boolean","example":false},"dm":{"type":"boolean","example":false},"template":{"type":"string","example":""}}}},"example":{"welcome":{"enabled":true,"in_group":true,"dm":false,"template":"Bem-vindo(a), {{name}}!"},"farewell":{"enabled":false,"in_group":false,"dm":false,"template":""}}},"engagement":{"type":"object","additionalProperties":true,"description":"Group-level engagement rollup (empty until computed).","example":{}},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Account-defined whatsapp_group custom attributes.","example":{}},"synced_at":{"type":["string","null"],"format":"date-time","example":"2026-01-15T10:30:00.000Z"},"archived_at":{"type":["string","null"],"format":"date-time","example":"2026-01-15T10:30:00.000Z"},"created_at":{"type":"string","format":"date-time","example":"2026-01-10T08:00:00.000Z"},"updated_at":{"type":"string","format":"date-time","example":"2026-01-15T10:30:00.000Z"},"distribution":{"type":["object","null"],"description":"Cross-link to the distribution unit (Turma) this group backs. Present on detail only when eager-loaded.","properties":{"unit_id":{"type":"integer","example":5},"unit_sequence":{"type":"integer","example":3},"unit_name":{"type":"string","example":"Turma 12 - Grupo 3"},"distribution_id":{"type":"integer","example":2},"distribution_name":{"type":["string","null"],"example":"Lancamento Janeiro"}},"example":{"unit_id":5,"unit_sequence":3,"unit_name":"Turma 12 - Grupo 3","distribution_id":2,"distribution_name":"Lancamento Janeiro"}},"participants":{"type":"array","description":"Active members ranked by engagement_score desc.","items":{"type":"object","properties":{"id":{"type":"integer","example":501},"jid":{"type":"string","example":"5521999998888@s.whatsapp.net"},"phone":{"type":["string","null"],"example":"+5521999998888"},"name":{"type":["string","null"],"example":"Maria Silva"},"display_name":{"type":["string","null"],"example":"Maria Silva","description":"Best real (non-phone, non-placeholder) name; null when only a phone/placeholder is known."},"role":{"type":"string","example":"member","enum":["owner","admin","member","subscriber"],"description":"Operator/participant role within the group."},"status":{"type":"string","example":"active","enum":["active","left","removed","pending"],"description":"Membership status of the group participant."},"contact_id":{"type":["integer","null"],"example":3021},"messages_count":{"type":"integer","example":42},"replies_count":{"type":"integer","example":12},"reactions_given_count":{"type":"integer","example":8},"reactions_received_count":{"type":"integer","example":15},"poll_votes_count":{"type":"integer","example":3},"button_clicks_count":{"type":"integer","example":1},"media_count":{"type":"integer","example":5},"engagement_score":{"type":"number","example":57.5},"last_active_at":{"type":["string","null"],"format":"date-time","example":"2026-01-15T09:45:00.000Z"},"joined_at":{"type":["string","null"],"format":"date-time","example":"2026-01-10T08:05:00.000Z"}}}}}}}},"example":{"payload":{"id":42,"account_id":1,"inbox_id":7,"jid":"120363021234567890@g.us","kind":"group","name":"Lancamento Turma 12","topic":"Avisos e materiais da turma","role":"admin","is_parent":false,"is_default_sub":false,"community_jid":"120363039876543210@g.us","photo_url":"https://pps.whatsapp.net/v/t61.24694-24/group-avatar.jpg","invite_code":"Hkq0dEXAMPLEabcdef","participant_count":128,"maestro_enabled":"inherit","settings":{"announce":false,"locked":false,"ephemeral":0},"greeting":{"welcome":{"enabled":true,"in_group":true,"dm":false,"template":"Bem-vindo(a), {{name}}!"},"farewell":{"enabled":false,"in_group":false,"dm":false,"template":""}},"engagement":{},"custom_attributes":{},"synced_at":"2026-01-15T10:30:00.000Z","archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-10T08:00:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","distribution":{"unit_id":5,"unit_sequence":3,"unit_name":"Turma 12 - Grupo 3","distribution_id":2,"distribution_name":"Lancamento Janeiro"},"participants":[{"id":501,"jid":"5521999998888@s.whatsapp.net","phone":"+5521999998888","name":"Maria Silva","display_name":"Maria Silva","role":"member","status":"active","contact_id":3021,"messages_count":42,"replies_count":12,"reactions_given_count":8,"reactions_received_count":15,"poll_votes_count":3,"button_clicks_count":1,"media_count":5,"engagement_score":57.5,"last_active_at":"2026-01-15T09:45:00.000Z","joined_at":"2026-01-10T08:05:00.000Z"}]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"channel_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"maestro_enabled":{"type":"boolean"},"group_id":{"type":"integer"}}},"example":{"maestro_enabled":true,"group_id":1}}}}}},"/api/v1/accounts/{account_id}/whatsapp_hub/channels":{"get":{"tags":["WhatsApp Hub"],"operationId":"auto_get_api_v1_accounts_account_id_whatsapp_hub_channels","summary":"List channels","description":"Returns the list of channels visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"List of mirrored WhatsApp channels (newsletters).","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","example":42},"account_id":{"type":"integer","example":1},"inbox_id":{"type":"integer","example":7},"jid":{"type":"string","example":"120363021234567890@g.us","description":"WhatsApp JID. Groups/communities end in @g.us; channels (newsletters) end in @newsletter."},"kind":{"type":"string","example":"group","enum":["group","community","channel"],"description":"Container type."},"name":{"type":["string","null"],"example":"Lancamento Turma 12"},"topic":{"type":["string","null"],"example":"Avisos e materiais da turma"},"role":{"type":"string","example":"admin","enum":["owner","admin","member","subscriber"],"description":"The connected account's role in this container."},"is_parent":{"type":"boolean","example":false,"description":"True for a community parent row."},"is_default_sub":{"type":"boolean","example":false,"description":"True for a community's default/announcement sub-group."},"community_jid":{"type":["string","null"],"example":"120363039876543210@g.us","description":"Parent community JID when this group is linked to one."},"photo_url":{"type":["string","null"],"example":"https://pps.whatsapp.net/v/t61.24694-24/group-avatar.jpg"},"invite_code":{"type":["string","null"],"example":"Hkq0dEXAMPLEabcdef"},"participant_count":{"type":"integer","example":128},"maestro_enabled":{"type":"string","example":"inherit","enum":["inherit","on","off"],"description":"Per-group Maestro AI gate. inherit resolves to the inbox group_ai_policy."},"settings":{"type":"object","description":"Mirrored WhatsApp group settings.","properties":{"announce":{"type":"boolean","example":false,"description":"Only admins can post."},"locked":{"type":"boolean","example":false,"description":"Only admins can edit group info."},"ephemeral":{"type":["integer","null"],"example":0,"description":"Disappearing-message timer in seconds (0 = off)."}},"example":{"announce":false,"locked":false,"ephemeral":0}},"greeting":{"type":"object","description":"Per-group welcome/farewell override merged over the inbox default. Empty object = inherit.","properties":{"welcome":{"type":"object","properties":{"enabled":{"type":"boolean","example":true},"in_group":{"type":"boolean","example":true},"dm":{"type":"boolean","example":false},"template":{"type":"string","example":"Bem-vindo(a), {{name}}!"}}},"farewell":{"type":"object","properties":{"enabled":{"type":"boolean","example":false},"in_group":{"type":"boolean","example":false},"dm":{"type":"boolean","example":false},"template":{"type":"string","example":""}}}},"example":{"welcome":{"enabled":true,"in_group":true,"dm":false,"template":"Bem-vindo(a), {{name}}!"},"farewell":{"enabled":false,"in_group":false,"dm":false,"template":""}}},"engagement":{"type":"object","additionalProperties":true,"description":"Group-level engagement rollup (empty until computed).","example":{}},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Account-defined whatsapp_group custom attributes.","example":{}},"synced_at":{"type":["string","null"],"format":"date-time","example":"2026-01-15T10:30:00.000Z"},"archived_at":{"type":["string","null"],"format":"date-time","example":"2026-01-15T10:30:00.000Z"},"created_at":{"type":"string","format":"date-time","example":"2026-01-10T08:00:00.000Z"},"updated_at":{"type":"string","format":"date-time","example":"2026-01-15T10:30:00.000Z"}}}},"meta":{"type":"object","properties":{"count":{"type":"integer","example":37},"current_page":{"type":"integer","example":1},"total_pages":{"type":"integer","example":2},"per_page":{"type":"integer","example":25},"has_more":{"type":"boolean","example":true}}}}},"example":{"payload":[{"id":42,"account_id":1,"inbox_id":7,"jid":"120363021234567890@g.us","kind":"group","name":"Lancamento Turma 12","topic":"Avisos e materiais da turma","role":"admin","is_parent":false,"is_default_sub":false,"community_jid":"120363039876543210@g.us","photo_url":"https://pps.whatsapp.net/v/t61.24694-24/group-avatar.jpg","invite_code":"Hkq0dEXAMPLEabcdef","participant_count":128,"maestro_enabled":"inherit","settings":{"announce":false,"locked":false,"ephemeral":0},"greeting":{"welcome":{"enabled":true,"in_group":true,"dm":false,"template":"Bem-vindo(a), {{name}}!"},"farewell":{"enabled":false,"in_group":false,"dm":false,"template":""}},"engagement":{},"custom_attributes":{},"synced_at":"2026-01-15T10:30:00.000Z","archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-10T08:00:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}],"meta":{"count":37,"current_page":1,"total_pages":2,"per_page":25,"has_more":true}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."},{"name":"inbox_id","in":"query","required":false,"schema":{"type":"integer"}},{"name":"search","in":"query","required":false,"schema":{"type":"string"}},{"name":"archived","in":"query","required":false,"schema":{"type":"boolean"}}]},"post":{"tags":["WhatsApp Hub"],"operationId":"auto_post_api_v1_accounts_account_id_whatsapp_hub_channels","summary":"Create channels","description":"Creates a new channel from the request payload. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"201":{"description":"Newly created/synced channel.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer","example":42},"account_id":{"type":"integer","example":1},"inbox_id":{"type":"integer","example":7},"jid":{"type":"string","example":"120363021234567890@g.us","description":"WhatsApp JID. Groups/communities end in @g.us; channels (newsletters) end in @newsletter."},"kind":{"type":"string","example":"group","enum":["group","community","channel"],"description":"Container type."},"name":{"type":["string","null"],"example":"Lancamento Turma 12"},"topic":{"type":["string","null"],"example":"Avisos e materiais da turma"},"role":{"type":"string","example":"admin","enum":["owner","admin","member","subscriber"],"description":"The connected account's role in this container."},"is_parent":{"type":"boolean","example":false,"description":"True for a community parent row."},"is_default_sub":{"type":"boolean","example":false,"description":"True for a community's default/announcement sub-group."},"community_jid":{"type":["string","null"],"example":"120363039876543210@g.us","description":"Parent community JID when this group is linked to one."},"photo_url":{"type":["string","null"],"example":"https://pps.whatsapp.net/v/t61.24694-24/group-avatar.jpg"},"invite_code":{"type":["string","null"],"example":"Hkq0dEXAMPLEabcdef"},"participant_count":{"type":"integer","example":128},"maestro_enabled":{"type":"string","example":"inherit","enum":["inherit","on","off"],"description":"Per-group Maestro AI gate. inherit resolves to the inbox group_ai_policy."},"settings":{"type":"object","description":"Mirrored WhatsApp group settings.","properties":{"announce":{"type":"boolean","example":false,"description":"Only admins can post."},"locked":{"type":"boolean","example":false,"description":"Only admins can edit group info."},"ephemeral":{"type":["integer","null"],"example":0,"description":"Disappearing-message timer in seconds (0 = off)."}},"example":{"announce":false,"locked":false,"ephemeral":0}},"greeting":{"type":"object","description":"Per-group welcome/farewell override merged over the inbox default. Empty object = inherit.","properties":{"welcome":{"type":"object","properties":{"enabled":{"type":"boolean","example":true},"in_group":{"type":"boolean","example":true},"dm":{"type":"boolean","example":false},"template":{"type":"string","example":"Bem-vindo(a), {{name}}!"}}},"farewell":{"type":"object","properties":{"enabled":{"type":"boolean","example":false},"in_group":{"type":"boolean","example":false},"dm":{"type":"boolean","example":false},"template":{"type":"string","example":""}}}},"example":{"welcome":{"enabled":true,"in_group":true,"dm":false,"template":"Bem-vindo(a), {{name}}!"},"farewell":{"enabled":false,"in_group":false,"dm":false,"template":""}}},"engagement":{"type":"object","additionalProperties":true,"description":"Group-level engagement rollup (empty until computed).","example":{}},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Account-defined whatsapp_group custom attributes.","example":{}},"synced_at":{"type":["string","null"],"format":"date-time","example":"2026-01-15T10:30:00.000Z"},"archived_at":{"type":["string","null"],"format":"date-time","example":"2026-01-15T10:30:00.000Z"},"created_at":{"type":"string","format":"date-time","example":"2026-01-10T08:00:00.000Z"},"updated_at":{"type":"string","format":"date-time","example":"2026-01-15T10:30:00.000Z"},"distribution":{"type":["object","null"],"description":"Cross-link to the distribution unit (Turma) this group backs. Present on detail only when eager-loaded.","properties":{"unit_id":{"type":"integer","example":5},"unit_sequence":{"type":"integer","example":3},"unit_name":{"type":"string","example":"Turma 12 - Grupo 3"},"distribution_id":{"type":"integer","example":2},"distribution_name":{"type":["string","null"],"example":"Lancamento Janeiro"}},"example":{"unit_id":5,"unit_sequence":3,"unit_name":"Turma 12 - Grupo 3","distribution_id":2,"distribution_name":"Lancamento Janeiro"}},"participants":{"type":"array","description":"Active members ranked by engagement_score desc.","items":{"type":"object","properties":{"id":{"type":"integer","example":501},"jid":{"type":"string","example":"5521999998888@s.whatsapp.net"},"phone":{"type":["string","null"],"example":"+5521999998888"},"name":{"type":["string","null"],"example":"Maria Silva"},"display_name":{"type":["string","null"],"example":"Maria Silva","description":"Best real (non-phone, non-placeholder) name; null when only a phone/placeholder is known."},"role":{"type":"string","example":"member","enum":["owner","admin","member","subscriber"]},"status":{"type":"string","example":"active","enum":["active","left","removed","pending"]},"contact_id":{"type":["integer","null"],"example":3021},"messages_count":{"type":"integer","example":42},"replies_count":{"type":"integer","example":12},"reactions_given_count":{"type":"integer","example":8},"reactions_received_count":{"type":"integer","example":15},"poll_votes_count":{"type":"integer","example":3},"button_clicks_count":{"type":"integer","example":1},"media_count":{"type":"integer","example":5},"engagement_score":{"type":"number","example":57.5},"last_active_at":{"type":["string","null"],"format":"date-time","example":"2026-01-15T09:45:00.000Z"},"joined_at":{"type":["string","null"],"format":"date-time","example":"2026-01-10T08:05:00.000Z"}}}}}}}},"example":{"payload":{"id":42,"account_id":1,"inbox_id":7,"jid":"120363021234567890@g.us","kind":"group","name":"Lancamento Turma 12","topic":"Avisos e materiais da turma","role":"admin","is_parent":false,"is_default_sub":false,"community_jid":"120363039876543210@g.us","photo_url":"https://pps.whatsapp.net/v/t61.24694-24/group-avatar.jpg","invite_code":"Hkq0dEXAMPLEabcdef","participant_count":128,"maestro_enabled":"inherit","settings":{"announce":false,"locked":false,"ephemeral":0},"greeting":{"welcome":{"enabled":true,"in_group":true,"dm":false,"template":"Bem-vindo(a), {{name}}!"},"farewell":{"enabled":false,"in_group":false,"dm":false,"template":""}},"engagement":{},"custom_attributes":{},"synced_at":"2026-01-15T10:30:00.000Z","archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-10T08:00:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","distribution":{"unit_id":5,"unit_sequence":3,"unit_name":"Turma 12 - Grupo 3","distribution_id":2,"distribution_name":"Lancamento Janeiro"},"participants":[{"id":501,"jid":"5521999998888@s.whatsapp.net","phone":"+5521999998888","name":"Maria Silva","display_name":"Maria Silva","role":"member","status":"active","contact_id":3021,"messages_count":42,"replies_count":12,"reactions_given_count":8,"reactions_received_count":15,"poll_votes_count":3,"button_clicks_count":1,"media_count":5,"engagement_score":57.5,"last_active_at":"2026-01-15T09:45:00.000Z","joined_at":"2026-01-10T08:05:00.000Z"}]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"202":{"description":"The channel was created on WhatsApp, but the local mirror is still synchronizing. Do not repeat the creation request.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["payload"],"properties":{"payload":{"type":"object","additionalProperties":false,"required":["jid","kind","sync_pending"],"properties":{"jid":{"type":["string","null"],"example":"120363000000000000@newsletter"},"kind":{"type":"string","enum":["channel"],"example":"channel"},"sync_pending":{"type":"boolean","enum":[true],"example":true}}}}},"example":{"payload":{"jid":"120363000000000000@newsletter","kind":"channel","sync_pending":true}}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"picture":{"type":"string"}}},"example":{"name":"Sample Name","description":"A short description.","picture":"sample picture"}}}}}},"/api/v1/accounts/{account_id}/whatsapp_hub/channels/{id}":{"get":{"tags":["WhatsApp Hub"],"operationId":"auto_get_api_v1_accounts_account_id_whatsapp_hub_channels_id","summary":"Get channels","description":"Returns the channel identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Channel detail with participants.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer","example":42},"account_id":{"type":"integer","example":1},"inbox_id":{"type":"integer","example":7},"jid":{"type":"string","example":"120363021234567890@g.us","description":"WhatsApp JID. Groups/communities end in @g.us; channels (newsletters) end in @newsletter."},"kind":{"type":"string","example":"group","enum":["group","community","channel"],"description":"Container type."},"name":{"type":["string","null"],"example":"Lancamento Turma 12"},"topic":{"type":["string","null"],"example":"Avisos e materiais da turma"},"role":{"type":"string","example":"admin","enum":["owner","admin","member","subscriber"],"description":"The connected account's role in this container."},"is_parent":{"type":"boolean","example":false,"description":"True for a community parent row."},"is_default_sub":{"type":"boolean","example":false,"description":"True for a community's default/announcement sub-group."},"community_jid":{"type":["string","null"],"example":"120363039876543210@g.us","description":"Parent community JID when this group is linked to one."},"photo_url":{"type":["string","null"],"example":"https://pps.whatsapp.net/v/t61.24694-24/group-avatar.jpg"},"invite_code":{"type":["string","null"],"example":"Hkq0dEXAMPLEabcdef"},"participant_count":{"type":"integer","example":128},"maestro_enabled":{"type":"string","example":"inherit","enum":["inherit","on","off"],"description":"Per-group Maestro AI gate. inherit resolves to the inbox group_ai_policy."},"settings":{"type":"object","description":"Mirrored WhatsApp group settings.","properties":{"announce":{"type":"boolean","example":false,"description":"Only admins can post."},"locked":{"type":"boolean","example":false,"description":"Only admins can edit group info."},"ephemeral":{"type":["integer","null"],"example":0,"description":"Disappearing-message timer in seconds (0 = off)."}},"example":{"announce":false,"locked":false,"ephemeral":0}},"greeting":{"type":"object","description":"Per-group welcome/farewell override merged over the inbox default. Empty object = inherit.","properties":{"welcome":{"type":"object","properties":{"enabled":{"type":"boolean","example":true},"in_group":{"type":"boolean","example":true},"dm":{"type":"boolean","example":false},"template":{"type":"string","example":"Bem-vindo(a), {{name}}!"}}},"farewell":{"type":"object","properties":{"enabled":{"type":"boolean","example":false},"in_group":{"type":"boolean","example":false},"dm":{"type":"boolean","example":false},"template":{"type":"string","example":""}}}},"example":{"welcome":{"enabled":true,"in_group":true,"dm":false,"template":"Bem-vindo(a), {{name}}!"},"farewell":{"enabled":false,"in_group":false,"dm":false,"template":""}}},"engagement":{"type":"object","additionalProperties":true,"description":"Group-level engagement rollup (empty until computed).","example":{}},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Account-defined whatsapp_group custom attributes.","example":{}},"synced_at":{"type":["string","null"],"format":"date-time","example":"2026-01-15T10:30:00.000Z"},"archived_at":{"type":["string","null"],"format":"date-time","example":"2026-01-15T10:30:00.000Z"},"created_at":{"type":"string","format":"date-time","example":"2026-01-10T08:00:00.000Z"},"updated_at":{"type":"string","format":"date-time","example":"2026-01-15T10:30:00.000Z"},"distribution":{"type":["object","null"],"description":"Cross-link to the distribution unit (Turma) this group backs. Present on detail only when eager-loaded.","properties":{"unit_id":{"type":"integer","example":5},"unit_sequence":{"type":"integer","example":3},"unit_name":{"type":"string","example":"Turma 12 - Grupo 3"},"distribution_id":{"type":"integer","example":2},"distribution_name":{"type":["string","null"],"example":"Lancamento Janeiro"}},"example":{"unit_id":5,"unit_sequence":3,"unit_name":"Turma 12 - Grupo 3","distribution_id":2,"distribution_name":"Lancamento Janeiro"}},"participants":{"type":"array","description":"Active members ranked by engagement_score desc.","items":{"type":"object","properties":{"id":{"type":"integer","example":501},"jid":{"type":"string","example":"5521999998888@s.whatsapp.net"},"phone":{"type":["string","null"],"example":"+5521999998888"},"name":{"type":["string","null"],"example":"Maria Silva"},"display_name":{"type":["string","null"],"example":"Maria Silva","description":"Best real (non-phone, non-placeholder) name; null when only a phone/placeholder is known."},"role":{"type":"string","example":"member","enum":["owner","admin","member","subscriber"]},"status":{"type":"string","example":"active","enum":["active","left","removed","pending"]},"contact_id":{"type":["integer","null"],"example":3021},"messages_count":{"type":"integer","example":42},"replies_count":{"type":"integer","example":12},"reactions_given_count":{"type":"integer","example":8},"reactions_received_count":{"type":"integer","example":15},"poll_votes_count":{"type":"integer","example":3},"button_clicks_count":{"type":"integer","example":1},"media_count":{"type":"integer","example":5},"engagement_score":{"type":"number","example":57.5},"last_active_at":{"type":["string","null"],"format":"date-time","example":"2026-01-15T09:45:00.000Z"},"joined_at":{"type":["string","null"],"format":"date-time","example":"2026-01-10T08:05:00.000Z"}}}}}}}},"example":{"payload":{"id":42,"account_id":1,"inbox_id":7,"jid":"120363021234567890@g.us","kind":"group","name":"Lancamento Turma 12","topic":"Avisos e materiais da turma","role":"admin","is_parent":false,"is_default_sub":false,"community_jid":"120363039876543210@g.us","photo_url":"https://pps.whatsapp.net/v/t61.24694-24/group-avatar.jpg","invite_code":"Hkq0dEXAMPLEabcdef","participant_count":128,"maestro_enabled":"inherit","settings":{"announce":false,"locked":false,"ephemeral":0},"greeting":{"welcome":{"enabled":true,"in_group":true,"dm":false,"template":"Bem-vindo(a), {{name}}!"},"farewell":{"enabled":false,"in_group":false,"dm":false,"template":""}},"engagement":{},"custom_attributes":{},"synced_at":"2026-01-15T10:30:00.000Z","archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-10T08:00:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","distribution":{"unit_id":5,"unit_sequence":3,"unit_name":"Turma 12 - Grupo 3","distribution_id":2,"distribution_name":"Lancamento Janeiro"},"participants":[{"id":501,"jid":"5521999998888@s.whatsapp.net","phone":"+5521999998888","name":"Maria Silva","display_name":"Maria Silva","role":"member","status":"active","contact_id":3021,"messages_count":42,"replies_count":12,"reactions_given_count":8,"reactions_received_count":15,"poll_votes_count":3,"button_clicks_count":1,"media_count":5,"engagement_score":57.5,"last_active_at":"2026-01-15T09:45:00.000Z","joined_at":"2026-01-10T08:05:00.000Z"}]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]},"patch":{"tags":["WhatsApp Hub"],"operationId":"auto_patch_api_v1_accounts_account_id_whatsapp_hub_channels_id","summary":"Update channels","description":"Updates the channel identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Updated channel (mute toggle).","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer","example":42},"account_id":{"type":"integer","example":1},"inbox_id":{"type":"integer","example":7},"jid":{"type":"string","example":"120363021234567890@g.us","description":"WhatsApp JID. Groups/communities end in @g.us; channels (newsletters) end in @newsletter."},"kind":{"type":"string","example":"group","enum":["group","community","channel"],"description":"Container type."},"name":{"type":["string","null"],"example":"Lancamento Turma 12"},"topic":{"type":["string","null"],"example":"Avisos e materiais da turma"},"role":{"type":"string","example":"admin","enum":["owner","admin","member","subscriber"],"description":"The connected account's role in this container."},"is_parent":{"type":"boolean","example":false,"description":"True for a community parent row."},"is_default_sub":{"type":"boolean","example":false,"description":"True for a community's default/announcement sub-group."},"community_jid":{"type":["string","null"],"example":"120363039876543210@g.us","description":"Parent community JID when this group is linked to one."},"photo_url":{"type":["string","null"],"example":"https://pps.whatsapp.net/v/t61.24694-24/group-avatar.jpg"},"invite_code":{"type":["string","null"],"example":"Hkq0dEXAMPLEabcdef"},"participant_count":{"type":"integer","example":128},"maestro_enabled":{"type":"string","example":"inherit","enum":["inherit","on","off"],"description":"Per-group Maestro AI gate. inherit resolves to the inbox group_ai_policy."},"settings":{"type":"object","description":"Mirrored WhatsApp group settings.","properties":{"announce":{"type":"boolean","example":false,"description":"Only admins can post."},"locked":{"type":"boolean","example":false,"description":"Only admins can edit group info."},"ephemeral":{"type":["integer","null"],"example":0,"description":"Disappearing-message timer in seconds (0 = off)."}},"example":{"announce":false,"locked":false,"ephemeral":0}},"greeting":{"type":"object","description":"Per-group welcome/farewell override merged over the inbox default. Empty object = inherit.","properties":{"welcome":{"type":"object","properties":{"enabled":{"type":"boolean","example":true},"in_group":{"type":"boolean","example":true},"dm":{"type":"boolean","example":false},"template":{"type":"string","example":"Bem-vindo(a), {{name}}!"}}},"farewell":{"type":"object","properties":{"enabled":{"type":"boolean","example":false},"in_group":{"type":"boolean","example":false},"dm":{"type":"boolean","example":false},"template":{"type":"string","example":""}}}},"example":{"welcome":{"enabled":true,"in_group":true,"dm":false,"template":"Bem-vindo(a), {{name}}!"},"farewell":{"enabled":false,"in_group":false,"dm":false,"template":""}}},"engagement":{"type":"object","additionalProperties":true,"description":"Group-level engagement rollup (empty until computed).","example":{}},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Account-defined whatsapp_group custom attributes.","example":{}},"synced_at":{"type":["string","null"],"format":"date-time","example":"2026-01-15T10:30:00.000Z"},"archived_at":{"type":["string","null"],"format":"date-time","example":"2026-01-15T10:30:00.000Z"},"created_at":{"type":"string","format":"date-time","example":"2026-01-10T08:00:00.000Z"},"updated_at":{"type":"string","format":"date-time","example":"2026-01-15T10:30:00.000Z"},"distribution":{"type":["object","null"],"description":"Cross-link to the distribution unit (Turma) this group backs. Present on detail only when eager-loaded.","properties":{"unit_id":{"type":"integer","example":5},"unit_sequence":{"type":"integer","example":3},"unit_name":{"type":"string","example":"Turma 12 - Grupo 3"},"distribution_id":{"type":"integer","example":2},"distribution_name":{"type":["string","null"],"example":"Lancamento Janeiro"}},"example":{"unit_id":5,"unit_sequence":3,"unit_name":"Turma 12 - Grupo 3","distribution_id":2,"distribution_name":"Lancamento Janeiro"}},"participants":{"type":"array","description":"Active members ranked by engagement_score desc.","items":{"type":"object","properties":{"id":{"type":"integer","example":501},"jid":{"type":"string","example":"5521999998888@s.whatsapp.net"},"phone":{"type":["string","null"],"example":"+5521999998888"},"name":{"type":["string","null"],"example":"Maria Silva"},"display_name":{"type":["string","null"],"example":"Maria Silva","description":"Best real (non-phone, non-placeholder) name; null when only a phone/placeholder is known."},"role":{"type":"string","example":"member","enum":["owner","admin","member","subscriber"]},"status":{"type":"string","example":"active","enum":["active","left","removed","pending"]},"contact_id":{"type":["integer","null"],"example":3021},"messages_count":{"type":"integer","example":42},"replies_count":{"type":"integer","example":12},"reactions_given_count":{"type":"integer","example":8},"reactions_received_count":{"type":"integer","example":15},"poll_votes_count":{"type":"integer","example":3},"button_clicks_count":{"type":"integer","example":1},"media_count":{"type":"integer","example":5},"engagement_score":{"type":"number","example":57.5},"last_active_at":{"type":["string","null"],"format":"date-time","example":"2026-01-15T09:45:00.000Z"},"joined_at":{"type":["string","null"],"format":"date-time","example":"2026-01-10T08:05:00.000Z"}}}}}}}},"example":{"payload":{"id":42,"account_id":1,"inbox_id":7,"jid":"120363021234567890@g.us","kind":"group","name":"Lancamento Turma 12","topic":"Avisos e materiais da turma","role":"admin","is_parent":false,"is_default_sub":false,"community_jid":"120363039876543210@g.us","photo_url":"https://pps.whatsapp.net/v/t61.24694-24/group-avatar.jpg","invite_code":"Hkq0dEXAMPLEabcdef","participant_count":128,"maestro_enabled":"inherit","settings":{"announce":false,"locked":false,"ephemeral":0},"greeting":{"welcome":{"enabled":true,"in_group":true,"dm":false,"template":"Bem-vindo(a), {{name}}!"},"farewell":{"enabled":false,"in_group":false,"dm":false,"template":""}},"engagement":{},"custom_attributes":{},"synced_at":"2026-01-15T10:30:00.000Z","archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-10T08:00:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","distribution":{"unit_id":5,"unit_sequence":3,"unit_name":"Turma 12 - Grupo 3","distribution_id":2,"distribution_name":"Lancamento Janeiro"},"participants":[{"id":501,"jid":"5521999998888@s.whatsapp.net","phone":"+5521999998888","name":"Maria Silva","display_name":"Maria Silva","role":"member","status":"active","contact_id":3021,"messages_count":42,"replies_count":12,"reactions_given_count":8,"reactions_received_count":15,"poll_votes_count":3,"button_clicks_count":1,"media_count":5,"engagement_score":57.5,"last_active_at":"2026-01-15T09:45:00.000Z","joined_at":"2026-01-10T08:05:00.000Z"}]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"muted":{"type":"boolean"}}},"example":{"muted":true}}}}},"put":{"tags":["WhatsApp Hub"],"operationId":"auto_put_api_v1_accounts_account_id_whatsapp_hub_channels_id","summary":"Update channels","description":"Updates the channel identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Updated channel (mute toggle).","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer","example":42},"account_id":{"type":"integer","example":1},"inbox_id":{"type":"integer","example":7},"jid":{"type":"string","example":"120363021234567890@g.us","description":"WhatsApp JID. Groups/communities end in @g.us; channels (newsletters) end in @newsletter."},"kind":{"type":"string","example":"group","enum":["group","community","channel"],"description":"Container type."},"name":{"type":["string","null"],"example":"Lancamento Turma 12"},"topic":{"type":["string","null"],"example":"Avisos e materiais da turma"},"role":{"type":"string","example":"admin","enum":["owner","admin","member","subscriber"],"description":"The connected account's role in this container."},"is_parent":{"type":"boolean","example":false,"description":"True for a community parent row."},"is_default_sub":{"type":"boolean","example":false,"description":"True for a community's default/announcement sub-group."},"community_jid":{"type":["string","null"],"example":"120363039876543210@g.us","description":"Parent community JID when this group is linked to one."},"photo_url":{"type":["string","null"],"example":"https://pps.whatsapp.net/v/t61.24694-24/group-avatar.jpg"},"invite_code":{"type":["string","null"],"example":"Hkq0dEXAMPLEabcdef"},"participant_count":{"type":"integer","example":128},"maestro_enabled":{"type":"string","example":"inherit","enum":["inherit","on","off"],"description":"Per-group Maestro AI gate. inherit resolves to the inbox group_ai_policy."},"settings":{"type":"object","description":"Mirrored WhatsApp group settings.","properties":{"announce":{"type":"boolean","example":false,"description":"Only admins can post."},"locked":{"type":"boolean","example":false,"description":"Only admins can edit group info."},"ephemeral":{"type":["integer","null"],"example":0,"description":"Disappearing-message timer in seconds (0 = off)."}},"example":{"announce":false,"locked":false,"ephemeral":0}},"greeting":{"type":"object","description":"Per-group welcome/farewell override merged over the inbox default. Empty object = inherit.","properties":{"welcome":{"type":"object","properties":{"enabled":{"type":"boolean","example":true},"in_group":{"type":"boolean","example":true},"dm":{"type":"boolean","example":false},"template":{"type":"string","example":"Bem-vindo(a), {{name}}!"}}},"farewell":{"type":"object","properties":{"enabled":{"type":"boolean","example":false},"in_group":{"type":"boolean","example":false},"dm":{"type":"boolean","example":false},"template":{"type":"string","example":""}}}},"example":{"welcome":{"enabled":true,"in_group":true,"dm":false,"template":"Bem-vindo(a), {{name}}!"},"farewell":{"enabled":false,"in_group":false,"dm":false,"template":""}}},"engagement":{"type":"object","additionalProperties":true,"description":"Group-level engagement rollup (empty until computed).","example":{}},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Account-defined whatsapp_group custom attributes.","example":{}},"synced_at":{"type":["string","null"],"format":"date-time","example":"2026-01-15T10:30:00.000Z"},"archived_at":{"type":["string","null"],"format":"date-time","example":"2026-01-15T10:30:00.000Z"},"created_at":{"type":"string","format":"date-time","example":"2026-01-10T08:00:00.000Z"},"updated_at":{"type":"string","format":"date-time","example":"2026-01-15T10:30:00.000Z"},"distribution":{"type":["object","null"],"description":"Cross-link to the distribution unit (Turma) this group backs. Present on detail only when eager-loaded.","properties":{"unit_id":{"type":"integer","example":5},"unit_sequence":{"type":"integer","example":3},"unit_name":{"type":"string","example":"Turma 12 - Grupo 3"},"distribution_id":{"type":"integer","example":2},"distribution_name":{"type":["string","null"],"example":"Lancamento Janeiro"}},"example":{"unit_id":5,"unit_sequence":3,"unit_name":"Turma 12 - Grupo 3","distribution_id":2,"distribution_name":"Lancamento Janeiro"}},"participants":{"type":"array","description":"Active members ranked by engagement_score desc.","items":{"type":"object","properties":{"id":{"type":"integer","example":501},"jid":{"type":"string","example":"5521999998888@s.whatsapp.net"},"phone":{"type":["string","null"],"example":"+5521999998888"},"name":{"type":["string","null"],"example":"Maria Silva"},"display_name":{"type":["string","null"],"example":"Maria Silva","description":"Best real (non-phone, non-placeholder) name; null when only a phone/placeholder is known."},"role":{"type":"string","example":"member","enum":["owner","admin","member","subscriber"]},"status":{"type":"string","example":"active","enum":["active","left","removed","pending"]},"contact_id":{"type":["integer","null"],"example":3021},"messages_count":{"type":"integer","example":42},"replies_count":{"type":"integer","example":12},"reactions_given_count":{"type":"integer","example":8},"reactions_received_count":{"type":"integer","example":15},"poll_votes_count":{"type":"integer","example":3},"button_clicks_count":{"type":"integer","example":1},"media_count":{"type":"integer","example":5},"engagement_score":{"type":"number","example":57.5},"last_active_at":{"type":["string","null"],"format":"date-time","example":"2026-01-15T09:45:00.000Z"},"joined_at":{"type":["string","null"],"format":"date-time","example":"2026-01-10T08:05:00.000Z"}}}}}}}},"example":{"payload":{"id":42,"account_id":1,"inbox_id":7,"jid":"120363021234567890@g.us","kind":"group","name":"Lancamento Turma 12","topic":"Avisos e materiais da turma","role":"admin","is_parent":false,"is_default_sub":false,"community_jid":"120363039876543210@g.us","photo_url":"https://pps.whatsapp.net/v/t61.24694-24/group-avatar.jpg","invite_code":"Hkq0dEXAMPLEabcdef","participant_count":128,"maestro_enabled":"inherit","settings":{"announce":false,"locked":false,"ephemeral":0},"greeting":{"welcome":{"enabled":true,"in_group":true,"dm":false,"template":"Bem-vindo(a), {{name}}!"},"farewell":{"enabled":false,"in_group":false,"dm":false,"template":""}},"engagement":{},"custom_attributes":{},"synced_at":"2026-01-15T10:30:00.000Z","archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-10T08:00:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","distribution":{"unit_id":5,"unit_sequence":3,"unit_name":"Turma 12 - Grupo 3","distribution_id":2,"distribution_name":"Lancamento Janeiro"},"participants":[{"id":501,"jid":"5521999998888@s.whatsapp.net","phone":"+5521999998888","name":"Maria Silva","display_name":"Maria Silva","role":"member","status":"active","contact_id":3021,"messages_count":42,"replies_count":12,"reactions_given_count":8,"reactions_received_count":15,"poll_votes_count":3,"button_clicks_count":1,"media_count":5,"engagement_score":57.5,"last_active_at":"2026-01-15T09:45:00.000Z","joined_at":"2026-01-10T08:05:00.000Z"}]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"muted":{"type":"boolean"}}},"example":{"muted":true}}}}}},"/api/v1/accounts/{account_id}/whatsapp_hub/communities/{id}/archive":{"post":{"tags":["WhatsApp Hub"],"operationId":"auto_post_api_v1_accounts_account_id_whatsapp_hub_communities_id_archive","summary":"Archive communities","description":"Performs the archive operation on the targeted community resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Community archived.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer","example":42},"account_id":{"type":"integer","example":1},"inbox_id":{"type":"integer","example":7},"jid":{"type":"string","example":"120363021234567890@g.us","description":"WhatsApp JID. Groups/communities end in @g.us; channels (newsletters) end in @newsletter."},"kind":{"type":"string","example":"group","enum":["group","community","channel"],"description":"Container type."},"name":{"type":["string","null"],"example":"Lancamento Turma 12"},"topic":{"type":["string","null"],"example":"Avisos e materiais da turma"},"role":{"type":"string","example":"admin","enum":["owner","admin","member","subscriber"],"description":"The connected account's role in this container."},"is_parent":{"type":"boolean","example":false,"description":"True for a community parent row."},"is_default_sub":{"type":"boolean","example":false,"description":"True for a community's default/announcement sub-group."},"community_jid":{"type":["string","null"],"example":"120363039876543210@g.us","description":"Parent community JID when this group is linked to one."},"photo_url":{"type":["string","null"],"example":"https://pps.whatsapp.net/v/t61.24694-24/group-avatar.jpg"},"invite_code":{"type":["string","null"],"example":"Hkq0dEXAMPLEabcdef"},"participant_count":{"type":"integer","example":128},"maestro_enabled":{"type":"string","example":"inherit","enum":["inherit","on","off"],"description":"Per-group Maestro AI gate. inherit resolves to the inbox group_ai_policy."},"settings":{"type":"object","description":"Mirrored WhatsApp group settings.","properties":{"announce":{"type":"boolean","example":false,"description":"Only admins can post."},"locked":{"type":"boolean","example":false,"description":"Only admins can edit group info."},"ephemeral":{"type":["integer","null"],"example":0,"description":"Disappearing-message timer in seconds (0 = off)."}},"example":{"announce":false,"locked":false,"ephemeral":0}},"greeting":{"type":"object","description":"Per-group welcome/farewell override merged over the inbox default. Empty object = inherit.","properties":{"welcome":{"type":"object","properties":{"enabled":{"type":"boolean","example":true},"in_group":{"type":"boolean","example":true},"dm":{"type":"boolean","example":false},"template":{"type":"string","example":"Bem-vindo(a), {{name}}!"}}},"farewell":{"type":"object","properties":{"enabled":{"type":"boolean","example":false},"in_group":{"type":"boolean","example":false},"dm":{"type":"boolean","example":false},"template":{"type":"string","example":""}}}},"example":{"welcome":{"enabled":true,"in_group":true,"dm":false,"template":"Bem-vindo(a), {{name}}!"},"farewell":{"enabled":false,"in_group":false,"dm":false,"template":""}}},"engagement":{"type":"object","additionalProperties":true,"description":"Group-level engagement rollup (empty until computed).","example":{}},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Account-defined whatsapp_group custom attributes.","example":{}},"synced_at":{"type":["string","null"],"format":"date-time","example":"2026-01-15T10:30:00.000Z"},"archived_at":{"type":["string","null"],"format":"date-time","example":"2026-01-15T10:30:00.000Z"},"created_at":{"type":"string","format":"date-time","example":"2026-01-10T08:00:00.000Z"},"updated_at":{"type":"string","format":"date-time","example":"2026-01-15T10:30:00.000Z"},"distribution":{"type":["object","null"],"description":"Cross-link to the distribution unit (Turma) this group backs. Present on detail only when eager-loaded.","properties":{"unit_id":{"type":"integer","example":5},"unit_sequence":{"type":"integer","example":3},"unit_name":{"type":"string","example":"Turma 12 - Grupo 3"},"distribution_id":{"type":"integer","example":2},"distribution_name":{"type":["string","null"],"example":"Lancamento Janeiro"}},"example":{"unit_id":5,"unit_sequence":3,"unit_name":"Turma 12 - Grupo 3","distribution_id":2,"distribution_name":"Lancamento Janeiro"}},"participants":{"type":"array","description":"Active members ranked by engagement_score desc.","items":{"type":"object","properties":{"id":{"type":"integer","example":501},"jid":{"type":"string","example":"5521999998888@s.whatsapp.net"},"phone":{"type":["string","null"],"example":"+5521999998888"},"name":{"type":["string","null"],"example":"Maria Silva"},"display_name":{"type":["string","null"],"example":"Maria Silva","description":"Best real (non-phone, non-placeholder) name; null when only a phone/placeholder is known."},"role":{"type":"string","example":"member","enum":["owner","admin","member","subscriber"]},"status":{"type":"string","example":"active","enum":["active","left","removed","pending"]},"contact_id":{"type":["integer","null"],"example":3021},"messages_count":{"type":"integer","example":42},"replies_count":{"type":"integer","example":12},"reactions_given_count":{"type":"integer","example":8},"reactions_received_count":{"type":"integer","example":15},"poll_votes_count":{"type":"integer","example":3},"button_clicks_count":{"type":"integer","example":1},"media_count":{"type":"integer","example":5},"engagement_score":{"type":"number","example":57.5},"last_active_at":{"type":["string","null"],"format":"date-time","example":"2026-01-15T09:45:00.000Z"},"joined_at":{"type":["string","null"],"format":"date-time","example":"2026-01-10T08:05:00.000Z"}}}}}}}},"example":{"payload":{"id":42,"account_id":1,"inbox_id":7,"jid":"120363021234567890@g.us","kind":"group","name":"Lancamento Turma 12","topic":"Avisos e materiais da turma","role":"admin","is_parent":false,"is_default_sub":false,"community_jid":"120363039876543210@g.us","photo_url":"https://pps.whatsapp.net/v/t61.24694-24/group-avatar.jpg","invite_code":"Hkq0dEXAMPLEabcdef","participant_count":128,"maestro_enabled":"inherit","settings":{"announce":false,"locked":false,"ephemeral":0},"greeting":{"welcome":{"enabled":true,"in_group":true,"dm":false,"template":"Bem-vindo(a), {{name}}!"},"farewell":{"enabled":false,"in_group":false,"dm":false,"template":""}},"engagement":{},"custom_attributes":{},"synced_at":"2026-01-15T10:30:00.000Z","archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-10T08:00:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","distribution":{"unit_id":5,"unit_sequence":3,"unit_name":"Turma 12 - Grupo 3","distribution_id":2,"distribution_name":"Lancamento Janeiro"},"participants":[{"id":501,"jid":"5521999998888@s.whatsapp.net","phone":"+5521999998888","name":"Maria Silva","display_name":"Maria Silva","role":"member","status":"active","contact_id":3021,"messages_count":42,"replies_count":12,"reactions_given_count":8,"reactions_received_count":15,"poll_votes_count":3,"button_clicks_count":1,"media_count":5,"engagement_score":57.5,"last_active_at":"2026-01-15T09:45:00.000Z","joined_at":"2026-01-10T08:05:00.000Z"}]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/whatsapp_hub/communities/{id}/restore":{"post":{"tags":["WhatsApp Hub"],"operationId":"auto_post_api_v1_accounts_account_id_whatsapp_hub_communities_id_restore","summary":"Restore communities","description":"Performs the restore operation on the targeted community resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Community restored.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer","example":42},"account_id":{"type":"integer","example":1},"inbox_id":{"type":"integer","example":7},"jid":{"type":"string","example":"120363021234567890@g.us","description":"WhatsApp JID. Groups/communities end in @g.us; channels (newsletters) end in @newsletter."},"kind":{"type":"string","example":"group","enum":["group","community","channel"],"description":"Container type."},"name":{"type":["string","null"],"example":"Lancamento Turma 12"},"topic":{"type":["string","null"],"example":"Avisos e materiais da turma"},"role":{"type":"string","example":"admin","enum":["owner","admin","member","subscriber"],"description":"The connected account's role in this container."},"is_parent":{"type":"boolean","example":false,"description":"True for a community parent row."},"is_default_sub":{"type":"boolean","example":false,"description":"True for a community's default/announcement sub-group."},"community_jid":{"type":["string","null"],"example":"120363039876543210@g.us","description":"Parent community JID when this group is linked to one."},"photo_url":{"type":["string","null"],"example":"https://pps.whatsapp.net/v/t61.24694-24/group-avatar.jpg"},"invite_code":{"type":["string","null"],"example":"Hkq0dEXAMPLEabcdef"},"participant_count":{"type":"integer","example":128},"maestro_enabled":{"type":"string","example":"inherit","enum":["inherit","on","off"],"description":"Per-group Maestro AI gate. inherit resolves to the inbox group_ai_policy."},"settings":{"type":"object","description":"Mirrored WhatsApp group settings.","properties":{"announce":{"type":"boolean","example":false,"description":"Only admins can post."},"locked":{"type":"boolean","example":false,"description":"Only admins can edit group info."},"ephemeral":{"type":["integer","null"],"example":0,"description":"Disappearing-message timer in seconds (0 = off)."}},"example":{"announce":false,"locked":false,"ephemeral":0}},"greeting":{"type":"object","description":"Per-group welcome/farewell override merged over the inbox default. Empty object = inherit.","properties":{"welcome":{"type":"object","properties":{"enabled":{"type":"boolean","example":true},"in_group":{"type":"boolean","example":true},"dm":{"type":"boolean","example":false},"template":{"type":"string","example":"Bem-vindo(a), {{name}}!"}}},"farewell":{"type":"object","properties":{"enabled":{"type":"boolean","example":false},"in_group":{"type":"boolean","example":false},"dm":{"type":"boolean","example":false},"template":{"type":"string","example":""}}}},"example":{"welcome":{"enabled":true,"in_group":true,"dm":false,"template":"Bem-vindo(a), {{name}}!"},"farewell":{"enabled":false,"in_group":false,"dm":false,"template":""}}},"engagement":{"type":"object","additionalProperties":true,"description":"Group-level engagement rollup (empty until computed).","example":{}},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Account-defined whatsapp_group custom attributes.","example":{}},"synced_at":{"type":["string","null"],"format":"date-time","example":"2026-01-15T10:30:00.000Z"},"archived_at":{"type":["string","null"],"format":"date-time","example":"2026-01-15T10:30:00.000Z"},"created_at":{"type":"string","format":"date-time","example":"2026-01-10T08:00:00.000Z"},"updated_at":{"type":"string","format":"date-time","example":"2026-01-15T10:30:00.000Z"},"distribution":{"type":["object","null"],"description":"Cross-link to the distribution unit (Turma) this group backs. Present on detail only when eager-loaded.","properties":{"unit_id":{"type":"integer","example":5},"unit_sequence":{"type":"integer","example":3},"unit_name":{"type":"string","example":"Turma 12 - Grupo 3"},"distribution_id":{"type":"integer","example":2},"distribution_name":{"type":["string","null"],"example":"Lancamento Janeiro"}},"example":{"unit_id":5,"unit_sequence":3,"unit_name":"Turma 12 - Grupo 3","distribution_id":2,"distribution_name":"Lancamento Janeiro"}},"participants":{"type":"array","description":"Active members ranked by engagement_score desc.","items":{"type":"object","properties":{"id":{"type":"integer","example":501},"jid":{"type":"string","example":"5521999998888@s.whatsapp.net"},"phone":{"type":["string","null"],"example":"+5521999998888"},"name":{"type":["string","null"],"example":"Maria Silva"},"display_name":{"type":["string","null"],"example":"Maria Silva","description":"Best real (non-phone, non-placeholder) name; null when only a phone/placeholder is known."},"role":{"type":"string","example":"member","enum":["owner","admin","member","subscriber"]},"status":{"type":"string","example":"active","enum":["active","left","removed","pending"]},"contact_id":{"type":["integer","null"],"example":3021},"messages_count":{"type":"integer","example":42},"replies_count":{"type":"integer","example":12},"reactions_given_count":{"type":"integer","example":8},"reactions_received_count":{"type":"integer","example":15},"poll_votes_count":{"type":"integer","example":3},"button_clicks_count":{"type":"integer","example":1},"media_count":{"type":"integer","example":5},"engagement_score":{"type":"number","example":57.5},"last_active_at":{"type":["string","null"],"format":"date-time","example":"2026-01-15T09:45:00.000Z"},"joined_at":{"type":["string","null"],"format":"date-time","example":"2026-01-10T08:05:00.000Z"}}}}}}}},"example":{"payload":{"id":42,"account_id":1,"inbox_id":7,"jid":"120363021234567890@g.us","kind":"group","name":"Lancamento Turma 12","topic":"Avisos e materiais da turma","role":"admin","is_parent":false,"is_default_sub":false,"community_jid":"120363039876543210@g.us","photo_url":"https://pps.whatsapp.net/v/t61.24694-24/group-avatar.jpg","invite_code":"Hkq0dEXAMPLEabcdef","participant_count":128,"maestro_enabled":"inherit","settings":{"announce":false,"locked":false,"ephemeral":0},"greeting":{"welcome":{"enabled":true,"in_group":true,"dm":false,"template":"Bem-vindo(a), {{name}}!"},"farewell":{"enabled":false,"in_group":false,"dm":false,"template":""}},"engagement":{},"custom_attributes":{},"synced_at":"2026-01-15T10:30:00.000Z","archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-10T08:00:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","distribution":{"unit_id":5,"unit_sequence":3,"unit_name":"Turma 12 - Grupo 3","distribution_id":2,"distribution_name":"Lancamento Janeiro"},"participants":[{"id":501,"jid":"5521999998888@s.whatsapp.net","phone":"+5521999998888","name":"Maria Silva","display_name":"Maria Silva","role":"member","status":"active","contact_id":3021,"messages_count":42,"replies_count":12,"reactions_given_count":8,"reactions_received_count":15,"poll_votes_count":3,"button_clicks_count":1,"media_count":5,"engagement_score":57.5,"last_active_at":"2026-01-15T09:45:00.000Z","joined_at":"2026-01-10T08:05:00.000Z"}]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/whatsapp_hub/communities/{id}/leave":{"post":{"tags":["WhatsApp Hub"],"operationId":"auto_post_api_v1_accounts_account_id_whatsapp_hub_communities_id_leave","summary":"Leave communities","description":"Performs the leave operation on the targeted community resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Left the community parent group and archived locally.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer","example":42},"account_id":{"type":"integer","example":1},"inbox_id":{"type":"integer","example":7},"jid":{"type":"string","example":"120363021234567890@g.us","description":"WhatsApp JID. Groups/communities end in @g.us; channels (newsletters) end in @newsletter."},"kind":{"type":"string","example":"group","enum":["group","community","channel"],"description":"Container type."},"name":{"type":["string","null"],"example":"Lancamento Turma 12"},"topic":{"type":["string","null"],"example":"Avisos e materiais da turma"},"role":{"type":"string","example":"admin","enum":["owner","admin","member","subscriber"],"description":"The connected account's role in this container."},"is_parent":{"type":"boolean","example":false,"description":"True for a community parent row."},"is_default_sub":{"type":"boolean","example":false,"description":"True for a community's default/announcement sub-group."},"community_jid":{"type":["string","null"],"example":"120363039876543210@g.us","description":"Parent community JID when this group is linked to one."},"photo_url":{"type":["string","null"],"example":"https://pps.whatsapp.net/v/t61.24694-24/group-avatar.jpg"},"invite_code":{"type":["string","null"],"example":"Hkq0dEXAMPLEabcdef"},"participant_count":{"type":"integer","example":128},"maestro_enabled":{"type":"string","example":"inherit","enum":["inherit","on","off"],"description":"Per-group Maestro AI gate. inherit resolves to the inbox group_ai_policy."},"settings":{"type":"object","description":"Mirrored WhatsApp group settings.","properties":{"announce":{"type":"boolean","example":false,"description":"Only admins can post."},"locked":{"type":"boolean","example":false,"description":"Only admins can edit group info."},"ephemeral":{"type":["integer","null"],"example":0,"description":"Disappearing-message timer in seconds (0 = off)."}},"example":{"announce":false,"locked":false,"ephemeral":0}},"greeting":{"type":"object","description":"Per-group welcome/farewell override merged over the inbox default. Empty object = inherit.","properties":{"welcome":{"type":"object","properties":{"enabled":{"type":"boolean","example":true},"in_group":{"type":"boolean","example":true},"dm":{"type":"boolean","example":false},"template":{"type":"string","example":"Bem-vindo(a), {{name}}!"}}},"farewell":{"type":"object","properties":{"enabled":{"type":"boolean","example":false},"in_group":{"type":"boolean","example":false},"dm":{"type":"boolean","example":false},"template":{"type":"string","example":""}}}},"example":{"welcome":{"enabled":true,"in_group":true,"dm":false,"template":"Bem-vindo(a), {{name}}!"},"farewell":{"enabled":false,"in_group":false,"dm":false,"template":""}}},"engagement":{"type":"object","additionalProperties":true,"description":"Group-level engagement rollup (empty until computed).","example":{}},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Account-defined whatsapp_group custom attributes.","example":{}},"synced_at":{"type":["string","null"],"format":"date-time","example":"2026-01-15T10:30:00.000Z"},"archived_at":{"type":["string","null"],"format":"date-time","example":"2026-01-15T10:30:00.000Z"},"created_at":{"type":"string","format":"date-time","example":"2026-01-10T08:00:00.000Z"},"updated_at":{"type":"string","format":"date-time","example":"2026-01-15T10:30:00.000Z"},"distribution":{"type":["object","null"],"description":"Cross-link to the distribution unit (Turma) this group backs. Present on detail only when eager-loaded.","properties":{"unit_id":{"type":"integer","example":5},"unit_sequence":{"type":"integer","example":3},"unit_name":{"type":"string","example":"Turma 12 - Grupo 3"},"distribution_id":{"type":"integer","example":2},"distribution_name":{"type":["string","null"],"example":"Lancamento Janeiro"}},"example":{"unit_id":5,"unit_sequence":3,"unit_name":"Turma 12 - Grupo 3","distribution_id":2,"distribution_name":"Lancamento Janeiro"}},"participants":{"type":"array","description":"Active members ranked by engagement_score desc.","items":{"type":"object","properties":{"id":{"type":"integer","example":501},"jid":{"type":"string","example":"5521999998888@s.whatsapp.net"},"phone":{"type":["string","null"],"example":"+5521999998888"},"name":{"type":["string","null"],"example":"Maria Silva"},"display_name":{"type":["string","null"],"example":"Maria Silva","description":"Best real (non-phone, non-placeholder) name; null when only a phone/placeholder is known."},"role":{"type":"string","example":"member","enum":["owner","admin","member","subscriber"]},"status":{"type":"string","example":"active","enum":["active","left","removed","pending"]},"contact_id":{"type":["integer","null"],"example":3021},"messages_count":{"type":"integer","example":42},"replies_count":{"type":"integer","example":12},"reactions_given_count":{"type":"integer","example":8},"reactions_received_count":{"type":"integer","example":15},"poll_votes_count":{"type":"integer","example":3},"button_clicks_count":{"type":"integer","example":1},"media_count":{"type":"integer","example":5},"engagement_score":{"type":"number","example":57.5},"last_active_at":{"type":["string","null"],"format":"date-time","example":"2026-01-15T09:45:00.000Z"},"joined_at":{"type":["string","null"],"format":"date-time","example":"2026-01-10T08:05:00.000Z"}}}}}}}},"example":{"payload":{"id":42,"account_id":1,"inbox_id":7,"jid":"120363021234567890@g.us","kind":"group","name":"Lancamento Turma 12","topic":"Avisos e materiais da turma","role":"admin","is_parent":false,"is_default_sub":false,"community_jid":"120363039876543210@g.us","photo_url":"https://pps.whatsapp.net/v/t61.24694-24/group-avatar.jpg","invite_code":"Hkq0dEXAMPLEabcdef","participant_count":128,"maestro_enabled":"inherit","settings":{"announce":false,"locked":false,"ephemeral":0},"greeting":{"welcome":{"enabled":true,"in_group":true,"dm":false,"template":"Bem-vindo(a), {{name}}!"},"farewell":{"enabled":false,"in_group":false,"dm":false,"template":""}},"engagement":{},"custom_attributes":{},"synced_at":"2026-01-15T10:30:00.000Z","archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-10T08:00:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","distribution":{"unit_id":5,"unit_sequence":3,"unit_name":"Turma 12 - Grupo 3","distribution_id":2,"distribution_name":"Lancamento Janeiro"},"participants":[{"id":501,"jid":"5521999998888@s.whatsapp.net","phone":"+5521999998888","name":"Maria Silva","display_name":"Maria Silva","role":"member","status":"active","contact_id":3021,"messages_count":42,"replies_count":12,"reactions_given_count":8,"reactions_received_count":15,"poll_votes_count":3,"button_clicks_count":1,"media_count":5,"engagement_score":57.5,"last_active_at":"2026-01-15T09:45:00.000Z","joined_at":"2026-01-10T08:05:00.000Z"}]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/whatsapp_hub/communities/{id}/open_conversation":{"post":{"tags":["WhatsApp Hub"],"operationId":"auto_post_api_v1_accounts_account_id_whatsapp_hub_communities_id_open_conversation","summary":"Open conversation communities","description":"Performs the open conversation operation on the targeted community resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"string"}}},"example":{"payload":"sample payload"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}},"example":{"message":"Sample message text."}}}}}},"/api/v1/accounts/{account_id}/whatsapp_hub/communities/{id}/join_requests":{"get":{"tags":["WhatsApp Hub"],"operationId":"auto_get_api_v1_accounts_account_id_whatsapp_hub_communities_id_join_requests","summary":"Join requests communities","description":"Performs the join requests operation on the targeted community resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"string"}}},"example":{"payload":"sample payload"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"group_jid","in":"query","required":false,"description":"Read the pending join requests of one group of the community instead of the community announcement group.","schema":{"type":"string"},"example":"120363000000000000@g.us"}]}},"/api/v1/accounts/{account_id}/whatsapp_hub/communities/{id}/update_join_requests":{"post":{"tags":["WhatsApp Hub"],"operationId":"auto_post_api_v1_accounts_account_id_whatsapp_hub_communities_id_update_join_requests","summary":"Update join requests communities","description":"Performs the update join requests operation on the targeted community resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"string"}}},"example":{"payload":"sample payload"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"requests":{"type":"array","items":{"type":"string"}},"group_jid":{"type":"string"},"join_action":{"type":"string"},"link_code":{"type":"string"}}},"example":{"requests":["sample request"],"group_jid":"sample group jid","join_action":"sample join action","link_code":"sample link code"}}}}}},"/api/v1/accounts/{account_id}/whatsapp_hub/communities/{id}/link":{"post":{"tags":["WhatsApp Hub"],"operationId":"auto_post_api_v1_accounts_account_id_whatsapp_hub_communities_id_link","summary":"Link communities","description":"Performs the link operation on the targeted community resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"payload":{"type":"string"}}},{"type":"object","properties":{"payload":{"type":"object","properties":{"status":{"type":"string","example":"already_linked","enum":["already_linked"],"description":"Returned when the group was already linked to the community."}}}}}]},"example":{"payload":"sample payload"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"group_jid":{"type":"string"}}},"example":{"group_jid":"sample group jid"}}}}}},"/api/v1/accounts/{account_id}/whatsapp_hub/communities/{id}/unlink":{"post":{"tags":["WhatsApp Hub"],"operationId":"auto_post_api_v1_accounts_account_id_whatsapp_hub_communities_id_unlink","summary":"Unlink communities","description":"Performs the unlink operation on the targeted community resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"string"}}},"example":{"payload":"sample payload"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"group_jid":{"type":"string"}}},"example":{"group_jid":"sample group jid"}}}}}},"/api/v1/accounts/{account_id}/whatsapp_hub/communities/{id}/announcement":{"post":{"tags":["WhatsApp Hub"],"operationId":"auto_post_api_v1_accounts_account_id_whatsapp_hub_communities_id_announcement","summary":"Announcement communities","description":"Performs the announcement operation on the targeted community resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"string"}}},"example":{"payload":"sample payload"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}},"example":{"message":"Sample message text."}}}}}},"/api/v1/accounts/{account_id}/whatsapp_hub/communities":{"get":{"tags":["WhatsApp Hub"],"operationId":"auto_get_api_v1_accounts_account_id_whatsapp_hub_communities","summary":"List communities","description":"Returns the list of communities visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"List of mirrored WhatsApp communities.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","example":42},"account_id":{"type":"integer","example":1},"inbox_id":{"type":"integer","example":7},"jid":{"type":"string","example":"120363021234567890@g.us","description":"WhatsApp JID. Groups/communities end in @g.us; channels (newsletters) end in @newsletter."},"kind":{"type":"string","example":"group","enum":["group","community","channel"],"description":"Container type."},"name":{"type":["string","null"],"example":"Lancamento Turma 12"},"topic":{"type":["string","null"],"example":"Avisos e materiais da turma"},"role":{"type":"string","example":"admin","enum":["owner","admin","member","subscriber"],"description":"The connected account's role in this container."},"is_parent":{"type":"boolean","example":false,"description":"True for a community parent row."},"is_default_sub":{"type":"boolean","example":false,"description":"True for a community's default/announcement sub-group."},"community_jid":{"type":["string","null"],"example":"120363039876543210@g.us","description":"Parent community JID when this group is linked to one."},"photo_url":{"type":["string","null"],"example":"https://pps.whatsapp.net/v/t61.24694-24/group-avatar.jpg"},"invite_code":{"type":["string","null"],"example":"Hkq0dEXAMPLEabcdef"},"participant_count":{"type":"integer","example":128},"maestro_enabled":{"type":"string","example":"inherit","enum":["inherit","on","off"],"description":"Per-group Maestro AI gate. inherit resolves to the inbox group_ai_policy."},"settings":{"type":"object","description":"Mirrored WhatsApp group settings.","properties":{"announce":{"type":"boolean","example":false,"description":"Only admins can post."},"locked":{"type":"boolean","example":false,"description":"Only admins can edit group info."},"ephemeral":{"type":["integer","null"],"example":0,"description":"Disappearing-message timer in seconds (0 = off)."}},"example":{"announce":false,"locked":false,"ephemeral":0}},"greeting":{"type":"object","description":"Per-group welcome/farewell override merged over the inbox default. Empty object = inherit.","properties":{"welcome":{"type":"object","properties":{"enabled":{"type":"boolean","example":true},"in_group":{"type":"boolean","example":true},"dm":{"type":"boolean","example":false},"template":{"type":"string","example":"Bem-vindo(a), {{name}}!"}}},"farewell":{"type":"object","properties":{"enabled":{"type":"boolean","example":false},"in_group":{"type":"boolean","example":false},"dm":{"type":"boolean","example":false},"template":{"type":"string","example":""}}}},"example":{"welcome":{"enabled":true,"in_group":true,"dm":false,"template":"Bem-vindo(a), {{name}}!"},"farewell":{"enabled":false,"in_group":false,"dm":false,"template":""}}},"engagement":{"type":"object","additionalProperties":true,"description":"Group-level engagement rollup (empty until computed).","example":{}},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Account-defined whatsapp_group custom attributes.","example":{}},"synced_at":{"type":["string","null"],"format":"date-time","example":"2026-01-15T10:30:00.000Z"},"archived_at":{"type":["string","null"],"format":"date-time","example":"2026-01-15T10:30:00.000Z"},"created_at":{"type":"string","format":"date-time","example":"2026-01-10T08:00:00.000Z"},"updated_at":{"type":"string","format":"date-time","example":"2026-01-15T10:30:00.000Z"}}}},"meta":{"type":"object","properties":{"count":{"type":"integer","example":37},"current_page":{"type":"integer","example":1},"total_pages":{"type":"integer","example":2},"per_page":{"type":"integer","example":25},"has_more":{"type":"boolean","example":true}}}}},"example":{"payload":[{"id":42,"account_id":1,"inbox_id":7,"jid":"120363021234567890@g.us","kind":"group","name":"Lancamento Turma 12","topic":"Avisos e materiais da turma","role":"admin","is_parent":false,"is_default_sub":false,"community_jid":"120363039876543210@g.us","photo_url":"https://pps.whatsapp.net/v/t61.24694-24/group-avatar.jpg","invite_code":"Hkq0dEXAMPLEabcdef","participant_count":128,"maestro_enabled":"inherit","settings":{"announce":false,"locked":false,"ephemeral":0},"greeting":{"welcome":{"enabled":true,"in_group":true,"dm":false,"template":"Bem-vindo(a), {{name}}!"},"farewell":{"enabled":false,"in_group":false,"dm":false,"template":""}},"engagement":{},"custom_attributes":{},"synced_at":"2026-01-15T10:30:00.000Z","archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-10T08:00:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}],"meta":{"count":37,"current_page":1,"total_pages":2,"per_page":25,"has_more":true}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."},{"name":"inbox_id","in":"query","required":false,"schema":{"type":"integer"}},{"name":"search","in":"query","required":false,"schema":{"type":"string"}},{"name":"archived","in":"query","required":false,"schema":{"type":"boolean"}}]},"post":{"tags":["WhatsApp Hub"],"operationId":"auto_post_api_v1_accounts_account_id_whatsapp_hub_communities","summary":"Create communities","description":"Creates a new community from the request payload. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"201":{"description":"Newly created community.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer","example":42},"account_id":{"type":"integer","example":1},"inbox_id":{"type":"integer","example":7},"jid":{"type":"string","example":"120363021234567890@g.us","description":"WhatsApp JID. Groups/communities end in @g.us; channels (newsletters) end in @newsletter."},"kind":{"type":"string","example":"group","enum":["group","community","channel"],"description":"Container type."},"name":{"type":["string","null"],"example":"Lancamento Turma 12"},"topic":{"type":["string","null"],"example":"Avisos e materiais da turma"},"role":{"type":"string","example":"admin","enum":["owner","admin","member","subscriber"],"description":"The connected account's role in this container."},"is_parent":{"type":"boolean","example":false,"description":"True for a community parent row."},"is_default_sub":{"type":"boolean","example":false,"description":"True for a community's default/announcement sub-group."},"community_jid":{"type":["string","null"],"example":"120363039876543210@g.us","description":"Parent community JID when this group is linked to one."},"photo_url":{"type":["string","null"],"example":"https://pps.whatsapp.net/v/t61.24694-24/group-avatar.jpg"},"invite_code":{"type":["string","null"],"example":"Hkq0dEXAMPLEabcdef"},"participant_count":{"type":"integer","example":128},"maestro_enabled":{"type":"string","example":"inherit","enum":["inherit","on","off"],"description":"Per-group Maestro AI gate. inherit resolves to the inbox group_ai_policy."},"settings":{"type":"object","description":"Mirrored WhatsApp group settings.","properties":{"announce":{"type":"boolean","example":false,"description":"Only admins can post."},"locked":{"type":"boolean","example":false,"description":"Only admins can edit group info."},"ephemeral":{"type":["integer","null"],"example":0,"description":"Disappearing-message timer in seconds (0 = off)."}},"example":{"announce":false,"locked":false,"ephemeral":0}},"greeting":{"type":"object","description":"Per-group welcome/farewell override merged over the inbox default. Empty object = inherit.","properties":{"welcome":{"type":"object","properties":{"enabled":{"type":"boolean","example":true},"in_group":{"type":"boolean","example":true},"dm":{"type":"boolean","example":false},"template":{"type":"string","example":"Bem-vindo(a), {{name}}!"}}},"farewell":{"type":"object","properties":{"enabled":{"type":"boolean","example":false},"in_group":{"type":"boolean","example":false},"dm":{"type":"boolean","example":false},"template":{"type":"string","example":""}}}},"example":{"welcome":{"enabled":true,"in_group":true,"dm":false,"template":"Bem-vindo(a), {{name}}!"},"farewell":{"enabled":false,"in_group":false,"dm":false,"template":""}}},"engagement":{"type":"object","additionalProperties":true,"description":"Group-level engagement rollup (empty until computed).","example":{}},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Account-defined whatsapp_group custom attributes.","example":{}},"synced_at":{"type":["string","null"],"format":"date-time","example":"2026-01-15T10:30:00.000Z"},"archived_at":{"type":["string","null"],"format":"date-time","example":"2026-01-15T10:30:00.000Z"},"created_at":{"type":"string","format":"date-time","example":"2026-01-10T08:00:00.000Z"},"updated_at":{"type":"string","format":"date-time","example":"2026-01-15T10:30:00.000Z"},"distribution":{"type":["object","null"],"description":"Cross-link to the distribution unit (Turma) this group backs. Present on detail only when eager-loaded.","properties":{"unit_id":{"type":"integer","example":5},"unit_sequence":{"type":"integer","example":3},"unit_name":{"type":"string","example":"Turma 12 - Grupo 3"},"distribution_id":{"type":"integer","example":2},"distribution_name":{"type":["string","null"],"example":"Lancamento Janeiro"}},"example":{"unit_id":5,"unit_sequence":3,"unit_name":"Turma 12 - Grupo 3","distribution_id":2,"distribution_name":"Lancamento Janeiro"}},"participants":{"type":"array","description":"Active members ranked by engagement_score desc.","items":{"type":"object","properties":{"id":{"type":"integer","example":501},"jid":{"type":"string","example":"5521999998888@s.whatsapp.net"},"phone":{"type":["string","null"],"example":"+5521999998888"},"name":{"type":["string","null"],"example":"Maria Silva"},"display_name":{"type":["string","null"],"example":"Maria Silva","description":"Best real (non-phone, non-placeholder) name; null when only a phone/placeholder is known."},"role":{"type":"string","example":"member","enum":["owner","admin","member","subscriber"]},"status":{"type":"string","example":"active","enum":["active","left","removed","pending"]},"contact_id":{"type":["integer","null"],"example":3021},"messages_count":{"type":"integer","example":42},"replies_count":{"type":"integer","example":12},"reactions_given_count":{"type":"integer","example":8},"reactions_received_count":{"type":"integer","example":15},"poll_votes_count":{"type":"integer","example":3},"button_clicks_count":{"type":"integer","example":1},"media_count":{"type":"integer","example":5},"engagement_score":{"type":"number","example":57.5},"last_active_at":{"type":["string","null"],"format":"date-time","example":"2026-01-15T09:45:00.000Z"},"joined_at":{"type":["string","null"],"format":"date-time","example":"2026-01-10T08:05:00.000Z"}}}}}}}},"example":{"payload":{"id":42,"account_id":1,"inbox_id":7,"jid":"120363021234567890@g.us","kind":"group","name":"Lancamento Turma 12","topic":"Avisos e materiais da turma","role":"admin","is_parent":false,"is_default_sub":false,"community_jid":"120363039876543210@g.us","photo_url":"https://pps.whatsapp.net/v/t61.24694-24/group-avatar.jpg","invite_code":"Hkq0dEXAMPLEabcdef","participant_count":128,"maestro_enabled":"inherit","settings":{"announce":false,"locked":false,"ephemeral":0},"greeting":{"welcome":{"enabled":true,"in_group":true,"dm":false,"template":"Bem-vindo(a), {{name}}!"},"farewell":{"enabled":false,"in_group":false,"dm":false,"template":""}},"engagement":{},"custom_attributes":{},"synced_at":"2026-01-15T10:30:00.000Z","archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-10T08:00:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","distribution":{"unit_id":5,"unit_sequence":3,"unit_name":"Turma 12 - Grupo 3","distribution_id":2,"distribution_name":"Lancamento Janeiro"},"participants":[{"id":501,"jid":"5521999998888@s.whatsapp.net","phone":"+5521999998888","name":"Maria Silva","display_name":"Maria Silva","role":"member","status":"active","contact_id":3021,"messages_count":42,"replies_count":12,"reactions_given_count":8,"reactions_received_count":15,"poll_votes_count":3,"button_clicks_count":1,"media_count":5,"engagement_score":57.5,"last_active_at":"2026-01-15T09:45:00.000Z","joined_at":"2026-01-10T08:05:00.000Z"}]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"groups":{"type":"array","items":{"type":"string"}}}},"example":{"name":"Sample Name","description":"A short description.","groups":["sample group"]}}}}}},"/api/v1/accounts/{account_id}/whatsapp_hub/communities/{id}":{"get":{"tags":["WhatsApp Hub"],"operationId":"auto_get_api_v1_accounts_account_id_whatsapp_hub_communities_id","summary":"Get communities","description":"Returns the community identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Community detail with participants.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer","example":42},"account_id":{"type":"integer","example":1},"inbox_id":{"type":"integer","example":7},"jid":{"type":"string","example":"120363021234567890@g.us","description":"WhatsApp JID. Groups/communities end in @g.us; channels (newsletters) end in @newsletter."},"kind":{"type":"string","example":"group","enum":["group","community","channel"],"description":"Container type."},"name":{"type":["string","null"],"example":"Lancamento Turma 12"},"topic":{"type":["string","null"],"example":"Avisos e materiais da turma"},"role":{"type":"string","example":"admin","enum":["owner","admin","member","subscriber"],"description":"The connected account's role in this container."},"is_parent":{"type":"boolean","example":false,"description":"True for a community parent row."},"is_default_sub":{"type":"boolean","example":false,"description":"True for a community's default/announcement sub-group."},"community_jid":{"type":["string","null"],"example":"120363039876543210@g.us","description":"Parent community JID when this group is linked to one."},"photo_url":{"type":["string","null"],"example":"https://pps.whatsapp.net/v/t61.24694-24/group-avatar.jpg"},"invite_code":{"type":["string","null"],"example":"Hkq0dEXAMPLEabcdef"},"participant_count":{"type":"integer","example":128},"maestro_enabled":{"type":"string","example":"inherit","enum":["inherit","on","off"],"description":"Per-group Maestro AI gate. inherit resolves to the inbox group_ai_policy."},"settings":{"type":"object","description":"Mirrored WhatsApp group settings.","properties":{"announce":{"type":"boolean","example":false,"description":"Only admins can post."},"locked":{"type":"boolean","example":false,"description":"Only admins can edit group info."},"ephemeral":{"type":["integer","null"],"example":0,"description":"Disappearing-message timer in seconds (0 = off)."}},"example":{"announce":false,"locked":false,"ephemeral":0}},"greeting":{"type":"object","description":"Per-group welcome/farewell override merged over the inbox default. Empty object = inherit.","properties":{"welcome":{"type":"object","properties":{"enabled":{"type":"boolean","example":true},"in_group":{"type":"boolean","example":true},"dm":{"type":"boolean","example":false},"template":{"type":"string","example":"Bem-vindo(a), {{name}}!"}}},"farewell":{"type":"object","properties":{"enabled":{"type":"boolean","example":false},"in_group":{"type":"boolean","example":false},"dm":{"type":"boolean","example":false},"template":{"type":"string","example":""}}}},"example":{"welcome":{"enabled":true,"in_group":true,"dm":false,"template":"Bem-vindo(a), {{name}}!"},"farewell":{"enabled":false,"in_group":false,"dm":false,"template":""}}},"engagement":{"type":"object","additionalProperties":true,"description":"Group-level engagement rollup (empty until computed).","example":{}},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Account-defined whatsapp_group custom attributes.","example":{}},"synced_at":{"type":["string","null"],"format":"date-time","example":"2026-01-15T10:30:00.000Z"},"archived_at":{"type":["string","null"],"format":"date-time","example":"2026-01-15T10:30:00.000Z"},"created_at":{"type":"string","format":"date-time","example":"2026-01-10T08:00:00.000Z"},"updated_at":{"type":"string","format":"date-time","example":"2026-01-15T10:30:00.000Z"},"distribution":{"type":["object","null"],"description":"Cross-link to the distribution unit (Turma) this group backs. Present on detail only when eager-loaded.","properties":{"unit_id":{"type":"integer","example":5},"unit_sequence":{"type":"integer","example":3},"unit_name":{"type":"string","example":"Turma 12 - Grupo 3"},"distribution_id":{"type":"integer","example":2},"distribution_name":{"type":["string","null"],"example":"Lancamento Janeiro"}},"example":{"unit_id":5,"unit_sequence":3,"unit_name":"Turma 12 - Grupo 3","distribution_id":2,"distribution_name":"Lancamento Janeiro"}},"participants":{"type":"array","description":"Active members ranked by engagement_score desc.","items":{"type":"object","properties":{"id":{"type":"integer","example":501},"jid":{"type":"string","example":"5521999998888@s.whatsapp.net"},"phone":{"type":["string","null"],"example":"+5521999998888"},"name":{"type":["string","null"],"example":"Maria Silva"},"display_name":{"type":["string","null"],"example":"Maria Silva","description":"Best real (non-phone, non-placeholder) name; null when only a phone/placeholder is known."},"role":{"type":"string","example":"member","enum":["owner","admin","member","subscriber"]},"status":{"type":"string","example":"active","enum":["active","left","removed","pending"]},"contact_id":{"type":["integer","null"],"example":3021},"messages_count":{"type":"integer","example":42},"replies_count":{"type":"integer","example":12},"reactions_given_count":{"type":"integer","example":8},"reactions_received_count":{"type":"integer","example":15},"poll_votes_count":{"type":"integer","example":3},"button_clicks_count":{"type":"integer","example":1},"media_count":{"type":"integer","example":5},"engagement_score":{"type":"number","example":57.5},"last_active_at":{"type":["string","null"],"format":"date-time","example":"2026-01-15T09:45:00.000Z"},"joined_at":{"type":["string","null"],"format":"date-time","example":"2026-01-10T08:05:00.000Z"}}}}}}}},"example":{"payload":{"id":42,"account_id":1,"inbox_id":7,"jid":"120363021234567890@g.us","kind":"group","name":"Lancamento Turma 12","topic":"Avisos e materiais da turma","role":"admin","is_parent":false,"is_default_sub":false,"community_jid":"120363039876543210@g.us","photo_url":"https://pps.whatsapp.net/v/t61.24694-24/group-avatar.jpg","invite_code":"Hkq0dEXAMPLEabcdef","participant_count":128,"maestro_enabled":"inherit","settings":{"announce":false,"locked":false,"ephemeral":0},"greeting":{"welcome":{"enabled":true,"in_group":true,"dm":false,"template":"Bem-vindo(a), {{name}}!"},"farewell":{"enabled":false,"in_group":false,"dm":false,"template":""}},"engagement":{},"custom_attributes":{},"synced_at":"2026-01-15T10:30:00.000Z","archived_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-10T08:00:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","distribution":{"unit_id":5,"unit_sequence":3,"unit_name":"Turma 12 - Grupo 3","distribution_id":2,"distribution_name":"Lancamento Janeiro"},"participants":[{"id":501,"jid":"5521999998888@s.whatsapp.net","phone":"+5521999998888","name":"Maria Silva","display_name":"Maria Silva","role":"member","status":"active","contact_id":3021,"messages_count":42,"replies_count":12,"reactions_given_count":8,"reactions_received_count":15,"poll_votes_count":3,"button_clicks_count":1,"media_count":5,"engagement_score":57.5,"last_active_at":"2026-01-15T09:45:00.000Z","joined_at":"2026-01-10T08:05:00.000Z"}]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/whatsapp_hub/broadcasts/{id}/pause":{"post":{"tags":["WhatsApp Hub"],"operationId":"auto_post_api_v1_accounts_account_id_whatsapp_hub_broadcasts_id_pause","summary":"Pause broadcasts","description":"Performs the pause operation on the targeted broadcast resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"inbox_id":{"type":"integer"},"logical_inbox_id":{"type":"integer"},"display_id":{"type":"integer"},"title":{"type":"string"},"message":{"type":"string"},"content_type":{"type":"string","enum":["text","image","video","audio","document","poll","interactive"],"description":"Content type of the broadcast message."},"content_attributes":{"type":"object","additionalProperties":true,"description":"Structured metadata accompanying the message content; the key set depends on content_type (e.g. select items, CSAT submission values, deletion flags, external delivery errors)."},"target_type":{"type":"string","enum":["groups","channels","communities","status","mixed"],"description":"Audience target type of the broadcast."},"targets":{"type":"string"},"schedule_type":{"type":"string","enum":["immediate","scheduled","recurring"],"description":"When the broadcast sends."},"scheduled_at":{"type":"string","format":"date-time"},"recurrence":{"type":"object","additionalProperties":true,"description":"JSONB recurrence rule: frequency (daily|weekly|monthly|yearly), interval, until, count, days."},"recurrence_parent_id":{"type":"integer"},"send_settings":{"type":"string"},"status":{"type":"string","enum":["draft","scheduled","sending","completed","paused","failed","cancelled"],"description":"Lifecycle status of the broadcast."},"sender_id":{"type":"integer"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"stats":{"type":"object","properties":{"total":{"type":"integer"},"set":{"type":"integer"}}},"errors":{"type":"array","description":"Grouped delivery failures/skips: each entry carries the recipient status, the failure/skip reason, and the count.","items":{"type":"object","additionalProperties":true,"description":"One (status, reason) group with its recipient count."}},"engagement":{"type":"object","properties":{"by_type":{"type":"object","additionalProperties":{"type":"integer"},"description":"Engagement counts keyed by activity type (poll_voted, button_clicked, reply_sent, reaction_given, media_shared, ...)."},"engaged_participants":{"type":"string"},"reach":{"type":"string"},"audience":{"type":"string"},"engagement_rate":{"type":"number"}}}}}}},"example":{"payload":{"id":1,"account_id":1,"inbox_id":1,"logical_inbox_id":1,"display_id":1,"title":"Sample title","message":"Sample message text.","content_type":"text","content_attributes":{},"target_type":"groups","targets":"sample targets","schedule_type":"immediate","scheduled_at":"2026-01-15T10:30:00.000Z","recurrence":{},"recurrence_parent_id":1,"send_settings":"sample send settings","status":"draft","sender_id":1,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","stats":{"total":1,"set":1},"errors":[{}],"engagement":{"by_type":{},"engaged_participants":"sample engaged participants","reach":"sample reach","audience":"sample audience","engagement_rate":12.5}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/whatsapp_hub/broadcasts/{id}/resume":{"post":{"tags":["WhatsApp Hub"],"operationId":"auto_post_api_v1_accounts_account_id_whatsapp_hub_broadcasts_id_resume","summary":"Resume broadcasts","description":"Performs the resume operation on the targeted broadcast resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"inbox_id":{"type":"integer"},"logical_inbox_id":{"type":"integer"},"display_id":{"type":"integer"},"title":{"type":"string"},"message":{"type":"string"},"content_type":{"type":"string","enum":["text","image","video","audio","document","poll","interactive"],"description":"Content type of the broadcast message."},"content_attributes":{"type":"object","additionalProperties":true,"description":"Structured metadata accompanying the message content; the key set depends on content_type (e.g. select items, CSAT submission values, deletion flags, external delivery errors)."},"target_type":{"type":"string","enum":["groups","channels","communities","status","mixed"],"description":"Audience target type of the broadcast."},"targets":{"type":"string"},"schedule_type":{"type":"string","enum":["immediate","scheduled","recurring"],"description":"When the broadcast sends."},"scheduled_at":{"type":"string","format":"date-time"},"recurrence":{"type":"object","additionalProperties":true,"description":"JSONB recurrence rule: frequency (daily|weekly|monthly|yearly), interval, until, count, days."},"recurrence_parent_id":{"type":"integer"},"send_settings":{"type":"string"},"status":{"type":"string","enum":["draft","scheduled","sending","completed","paused","failed","cancelled"],"description":"Lifecycle status of the broadcast."},"sender_id":{"type":"integer"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"stats":{"type":"object","properties":{"total":{"type":"integer"},"set":{"type":"integer"}}},"errors":{"type":"array","description":"Grouped delivery failures/skips: each entry carries the recipient status, the failure/skip reason, and the count.","items":{"type":"object","additionalProperties":true,"description":"One (status, reason) group with its recipient count."}},"engagement":{"type":"object","properties":{"by_type":{"type":"object","additionalProperties":{"type":"integer"},"description":"Engagement counts keyed by activity type (poll_voted, button_clicked, reply_sent, reaction_given, media_shared, ...)."},"engaged_participants":{"type":"string"},"reach":{"type":"string"},"audience":{"type":"string"},"engagement_rate":{"type":"number"}}}}}}},"example":{"payload":{"id":1,"account_id":1,"inbox_id":1,"logical_inbox_id":1,"display_id":1,"title":"Sample title","message":"Sample message text.","content_type":"text","content_attributes":{},"target_type":"groups","targets":"sample targets","schedule_type":"immediate","scheduled_at":"2026-01-15T10:30:00.000Z","recurrence":{},"recurrence_parent_id":1,"send_settings":"sample send settings","status":"draft","sender_id":1,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","stats":{"total":1,"set":1},"errors":[{}],"engagement":{"by_type":{},"engaged_participants":"sample engaged participants","reach":"sample reach","audience":"sample audience","engagement_rate":12.5}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/whatsapp_hub/broadcasts/{id}/cancel":{"post":{"tags":["WhatsApp Hub"],"operationId":"auto_post_api_v1_accounts_account_id_whatsapp_hub_broadcasts_id_cancel","summary":"Cancel broadcasts","description":"Performs the cancel operation on the targeted broadcast resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"inbox_id":{"type":"integer"},"logical_inbox_id":{"type":"integer"},"display_id":{"type":"integer"},"title":{"type":"string"},"message":{"type":"string"},"content_type":{"type":"string","enum":["text","image","video","audio","document","poll","interactive"],"description":"Content type of the broadcast message."},"content_attributes":{"type":"object","additionalProperties":true,"description":"Structured metadata accompanying the message content; the key set depends on content_type (e.g. select items, CSAT submission values, deletion flags, external delivery errors)."},"target_type":{"type":"string","enum":["groups","channels","communities","status","mixed"],"description":"Audience target type of the broadcast."},"targets":{"type":"string"},"schedule_type":{"type":"string","enum":["immediate","scheduled","recurring"],"description":"When the broadcast sends."},"scheduled_at":{"type":"string","format":"date-time"},"recurrence":{"type":"object","additionalProperties":true,"description":"JSONB recurrence rule: frequency (daily|weekly|monthly|yearly), interval, until, count, days."},"recurrence_parent_id":{"type":"integer"},"send_settings":{"type":"string"},"status":{"type":"string","enum":["draft","scheduled","sending","completed","paused","failed","cancelled"],"description":"Lifecycle status of the broadcast."},"sender_id":{"type":"integer"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"stats":{"type":"object","properties":{"total":{"type":"integer"},"set":{"type":"integer"}}},"errors":{"type":"array","description":"Grouped delivery failures/skips: each entry carries the recipient status, the failure/skip reason, and the count.","items":{"type":"object","additionalProperties":true,"description":"One (status, reason) group with its recipient count."}},"engagement":{"type":"object","properties":{"by_type":{"type":"object","additionalProperties":{"type":"integer"},"description":"Engagement counts keyed by activity type (poll_voted, button_clicked, reply_sent, reaction_given, media_shared, ...)."},"engaged_participants":{"type":"string"},"reach":{"type":"string"},"audience":{"type":"string"},"engagement_rate":{"type":"number"}}}}}}},"example":{"payload":{"id":1,"account_id":1,"inbox_id":1,"logical_inbox_id":1,"display_id":1,"title":"Sample title","message":"Sample message text.","content_type":"text","content_attributes":{},"target_type":"groups","targets":"sample targets","schedule_type":"immediate","scheduled_at":"2026-01-15T10:30:00.000Z","recurrence":{},"recurrence_parent_id":1,"send_settings":"sample send settings","status":"draft","sender_id":1,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","stats":{"total":1,"set":1},"errors":[{}],"engagement":{"by_type":{},"engaged_participants":"sample engaged participants","reach":"sample reach","audience":"sample audience","engagement_rate":12.5}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["pending","processing","sent","delivered","read","failed","skipped"],"description":"Optional recipient-status filter applied to the operation."},"q":{"type":"string"},"page":{"type":"string"}}},"example":{"status":"pending","q":"sample q","page":"sample page"}}}}}},"/api/v1/accounts/{account_id}/whatsapp_hub/broadcasts/{id}/retry_failures":{"post":{"tags":["WhatsApp Hub"],"operationId":"auto_post_api_v1_accounts_account_id_whatsapp_hub_broadcasts_id_retry_failures","summary":"Retry failures broadcasts","description":"Performs the retry failures operation on the targeted broadcast resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"inbox_id":{"type":"integer"},"logical_inbox_id":{"type":"integer"},"display_id":{"type":"integer"},"title":{"type":"string"},"message":{"type":"string"},"content_type":{"type":"string","enum":["text","image","video","audio","document","poll","interactive"],"description":"Content type of the broadcast message."},"content_attributes":{"type":"object","additionalProperties":true,"description":"Structured metadata accompanying the message content; the key set depends on content_type (e.g. select items, CSAT submission values, deletion flags, external delivery errors)."},"target_type":{"type":"string","enum":["groups","channels","communities","status","mixed"],"description":"Audience target type of the broadcast."},"targets":{"type":"string"},"schedule_type":{"type":"string","enum":["immediate","scheduled","recurring"],"description":"When the broadcast sends."},"scheduled_at":{"type":"string","format":"date-time"},"recurrence":{"type":"object","additionalProperties":true,"description":"JSONB recurrence rule: frequency (daily|weekly|monthly|yearly), interval, until, count, days."},"recurrence_parent_id":{"type":"integer"},"send_settings":{"type":"string"},"status":{"type":"string","enum":["draft","scheduled","sending","completed","paused","failed","cancelled"],"description":"Lifecycle status of the broadcast."},"sender_id":{"type":"integer"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"stats":{"type":"object","properties":{"total":{"type":"integer"},"set":{"type":"integer"}}},"errors":{"type":"array","description":"Grouped delivery failures/skips: each entry carries the recipient status, the failure/skip reason, and the count.","items":{"type":"object","additionalProperties":true,"description":"One (status, reason) group with its recipient count."}},"engagement":{"type":"object","properties":{"by_type":{"type":"object","additionalProperties":{"type":"integer"},"description":"Engagement counts keyed by activity type (poll_voted, button_clicked, reply_sent, reaction_given, media_shared, ...)."},"engaged_participants":{"type":"string"},"reach":{"type":"string"},"audience":{"type":"string"},"engagement_rate":{"type":"number"}}}}}}},"example":{"payload":{"id":1,"account_id":1,"inbox_id":1,"logical_inbox_id":1,"display_id":1,"title":"Sample title","message":"Sample message text.","content_type":"text","content_attributes":{},"target_type":"groups","targets":"sample targets","schedule_type":"immediate","scheduled_at":"2026-01-15T10:30:00.000Z","recurrence":{},"recurrence_parent_id":1,"send_settings":"sample send settings","status":"draft","sender_id":1,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","stats":{"total":1,"set":1},"errors":[{}],"engagement":{"by_type":{},"engaged_participants":"sample engaged participants","reach":"sample reach","audience":"sample audience","engagement_rate":12.5}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["pending","processing","sent","delivered","read","failed","skipped"],"description":"Optional recipient-status filter applied to the operation."},"q":{"type":"string"},"page":{"type":"string"}}},"example":{"status":"pending","q":"sample q","page":"sample page"}}}}}},"/api/v1/accounts/{account_id}/whatsapp_hub/broadcasts/{id}/recipients":{"get":{"tags":["WhatsApp Hub"],"operationId":"auto_get_api_v1_accounts_account_id_whatsapp_hub_broadcasts_id_recipients","summary":"Recipients broadcasts","description":"Performs the recipients operation on the targeted broadcast resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"target_kind":{"type":"string","enum":["group","channel","status"],"description":"What kind of destination this recipient row points at."},"target_jid":{"type":"string"},"target_name":{"type":"string"},"status":{"type":"string","enum":["pending","processing","sent","delivered","read","failed","skipped"],"description":"Per-recipient delivery funnel status for the broadcast."},"error_reason":{"type":"string"},"retryable":{"type":"string"},"conversation_id":{"type":"integer"},"message_id":{"type":"integer"},"timeline":{"type":"object","properties":{"queued_at":{"type":"string","format":"date-time"},"scheduled_at":{"type":"string","format":"date-time"},"sent_at":{"type":"string","format":"date-time"},"delivered_at":{"type":"string","format":"date-time"},"read_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}}},"meta":{"type":"object","properties":{"count":{"type":"integer"},"current_page":{"type":"string"},"total_pages":{"type":"string"},"per_page":{"type":"string"},"has_more":{"type":"boolean"}}}}},"example":{"payload":[{"id":1,"target_kind":"group","target_jid":"sample target jid","target_name":"sample target name","status":"pending","error_reason":"sample error reason","retryable":"sample retryable","conversation_id":1,"message_id":1,"timeline":{"queued_at":"2026-01-15T10:30:00.000Z","scheduled_at":"2026-01-15T10:30:00.000Z","sent_at":"2026-01-15T10:30:00.000Z","delivered_at":"2026-01-15T10:30:00.000Z","read_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}],"meta":{"count":5,"current_page":"sample current page","total_pages":"sample total pages","per_page":"sample per page","has_more":true}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"status","in":"query","required":false,"description":"Restrict to recipients in one delivery state.","schema":{"type":"string","enum":["pending","processing","sent","delivered","read","failed","skipped"]},"example":"failed"},{"name":"q","in":"query","required":false,"description":"Filter recipients by name or destination.","schema":{"type":"string"},"example":"maria"},{"name":"page","in":"query","required":false,"description":"Page of recipients.","schema":{"type":"integer","default":1},"example":1}]}},"/api/v1/accounts/{account_id}/whatsapp_hub/broadcasts":{"get":{"tags":["WhatsApp Hub"],"operationId":"auto_get_api_v1_accounts_account_id_whatsapp_hub_broadcasts","summary":"List broadcasts","description":"Returns the list of broadcasts visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"inbox_id":{"type":"integer"},"logical_inbox_id":{"type":"integer"},"display_id":{"type":"integer"},"title":{"type":"string"},"message":{"type":"string"},"content_type":{"type":"string","enum":["text","image","video","audio","document","poll","interactive"],"description":"Content type of the broadcast message."},"content_attributes":{"type":"object","additionalProperties":true,"description":"Structured metadata accompanying the message content; the key set depends on content_type (e.g. select items, CSAT submission values, deletion flags, external delivery errors)."},"target_type":{"type":"string","enum":["groups","channels","communities","status","mixed"],"description":"Audience target type of the broadcast."},"targets":{"type":"string"},"schedule_type":{"type":"string","enum":["immediate","scheduled","recurring"],"description":"When the broadcast sends."},"scheduled_at":{"type":"string","format":"date-time"},"recurrence":{"type":"object","additionalProperties":true,"description":"JSONB recurrence rule: frequency (daily|weekly|monthly|yearly), interval, until, count, days."},"recurrence_parent_id":{"type":"integer"},"send_settings":{"type":"string"},"status":{"type":"string","enum":["draft","scheduled","sending","completed","paused","failed","cancelled"],"description":"Lifecycle status of the broadcast."},"sender_id":{"type":"integer"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"stats":{"type":"object","properties":{"total":{"type":"integer"},"set":{"type":"integer"}}},"errors":{"type":"array","description":"Grouped delivery failures/skips: each entry carries the recipient status, the failure/skip reason, and the count.","items":{"type":"object","additionalProperties":true,"description":"One (status, reason) group with its recipient count."}}}}},"meta":{"type":"object","properties":{"count":{"type":"integer"},"current_page":{"type":"string"},"total_pages":{"type":"string"},"per_page":{"type":"string"},"has_more":{"type":"boolean"}}}}},"example":{"payload":[{"id":1,"account_id":1,"inbox_id":1,"logical_inbox_id":1,"display_id":1,"title":"Sample title","message":"Sample message text.","content_type":"text","content_attributes":{},"target_type":"groups","targets":"sample targets","schedule_type":"immediate","scheduled_at":"2026-01-15T10:30:00.000Z","recurrence":{},"recurrence_parent_id":1,"send_settings":"sample send settings","status":"draft","sender_id":1,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","stats":{"total":1,"set":1},"errors":[{}]}],"meta":{"count":5,"current_page":"sample current page","total_pages":"sample total pages","per_page":"sample per page","has_more":true}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"inbox_id","in":"query","required":false,"description":"Restrict to broadcasts of one inbox.","schema":{"type":"integer"},"example":42},{"name":"status","in":"query","required":false,"description":"Restrict to broadcasts in one state.","schema":{"type":"string","enum":["draft","scheduled","sending","completed","paused","failed","cancelled"]},"example":"sending"}]},"post":{"tags":["WhatsApp Hub"],"operationId":"auto_post_api_v1_accounts_account_id_whatsapp_hub_broadcasts","summary":"Create broadcasts","description":"Creates a broadcast and, for schedule_type=immediate, fans it out at once. Content is validated against the destination BEFORE creating: the Status target (target_type=status) only accepts text, image, video or audio — document media, polls and interactive payloads answer 422 status_content_unsupported. A Status broadcast needs no targets: an empty list synthesizes the implicit `{ kind: \"status\" }` recipient (the account's own Status). Text statuses may carry `content_attributes.status_style` — `{ background_color: \"#075E54\", text_color: \"#FFFFFF\", font: 3 }` (hex colors converted server-side to the gateway's decimal ARGB; font is the WhatsApp text-status font enum 0-10). The targets list is capped at 500 per request (422 bulk_limit_exceeded, no partial effect). Sending is also gated per inbox by the `enable_status_broadcast_posting` feature — a disabled inbox skips its status recipient with reason status_posting_disabled instead of posting.","security":[{"userApiKey":[]}],"responses":{"201":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"inbox_id":{"type":"integer"},"logical_inbox_id":{"type":"integer"},"display_id":{"type":"integer"},"title":{"type":"string"},"message":{"type":"string"},"content_type":{"type":"string","enum":["text","image","video","audio","document","poll","interactive"],"description":"Content type of the broadcast message."},"content_attributes":{"type":"object","additionalProperties":true,"description":"Structured metadata accompanying the message content; the key set depends on content_type (e.g. select items, CSAT submission values, deletion flags, external delivery errors)."},"target_type":{"type":"string","enum":["groups","channels","communities","status","mixed"],"description":"Audience target type of the broadcast."},"targets":{"type":"string"},"schedule_type":{"type":"string","enum":["immediate","scheduled","recurring"],"description":"When the broadcast sends."},"scheduled_at":{"type":"string","format":"date-time"},"recurrence":{"type":"object","additionalProperties":true,"description":"JSONB recurrence rule: frequency (daily|weekly|monthly|yearly), interval, until, count, days."},"recurrence_parent_id":{"type":"integer"},"send_settings":{"type":"string"},"status":{"type":"string","enum":["draft","scheduled","sending","completed","paused","failed","cancelled"],"description":"Lifecycle status of the broadcast."},"sender_id":{"type":"integer"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"stats":{"type":"object","properties":{"total":{"type":"integer"},"set":{"type":"integer"}}},"errors":{"type":"array","description":"Grouped delivery failures/skips: each entry carries the recipient status, the failure/skip reason, and the count.","items":{"type":"object","additionalProperties":true,"description":"One (status, reason) group with its recipient count."}},"engagement":{"type":"object","properties":{"by_type":{"type":"object","additionalProperties":{"type":"integer"},"description":"Engagement counts keyed by activity type (poll_voted, button_clicked, reply_sent, reaction_given, media_shared, ...)."},"engaged_participants":{"type":"string"},"reach":{"type":"string"},"audience":{"type":"string"},"engagement_rate":{"type":"number"}}}}}}},"example":{"payload":{"id":1,"account_id":1,"inbox_id":1,"logical_inbox_id":1,"display_id":1,"title":"Sample title","message":"Sample message text.","content_type":"text","content_attributes":{},"target_type":"groups","targets":"sample targets","schedule_type":"immediate","scheduled_at":"2026-01-15T10:30:00.000Z","recurrence":{},"recurrence_parent_id":1,"send_settings":"sample send settings","status":"draft","sender_id":1,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","stats":{"total":1,"set":1},"errors":[{}],"engagement":{"by_type":{},"engaged_participants":"sample engaged participants","reach":"sample reach","audience":"sample audience","engagement_rate":12.5}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"422":{"description":"Rejected before any side effect. `bulk_limit_exceeded` carries the cap in `limit`; `status_content_unsupported` is returned localized for the Status target with document/poll/interactive content.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Stable code (bulk_limit_exceeded) or a localized message for content unsupported on the Status destination.","example":"bulk_limit_exceeded"},"limit":{"type":["integer","null"],"description":"Present only on bulk_limit_exceeded — the per-request cap.","example":500}}},"example":{"error":"bulk_limit_exceeded","limit":500}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string"},"message":{"type":"string"},"content_type":{"type":"string","enum":["text","image","video","audio","document","poll","interactive"],"description":"Content type of the broadcast message."},"target_type":{"type":"string","enum":["groups","channels","communities","status","mixed"],"description":"Audience target type of the broadcast."},"schedule_type":{"type":"string","enum":["immediate","scheduled","recurring"],"description":"When the broadcast sends."},"scheduled_at":{"type":"string","format":"date-time"},"content_attributes":{"type":"object","additionalProperties":true,"description":"Structured metadata accompanying the message content; the key set depends on content_type (e.g. select items, CSAT submission values, deletion flags, external delivery errors)."},"send_settings":{"type":"object","additionalProperties":true,"description":"Free-form object."},"recurrence":{"type":"object","additionalProperties":true,"description":"JSONB recurrence rule: frequency (daily|weekly|monthly|yearly), interval, until, count, days."},"targets":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Free-form object."}}}},"example":{"title":"Sample title","message":"Sample message text.","content_type":"text","target_type":"groups","schedule_type":"immediate","scheduled_at":"2026-01-15T10:30:00.000Z","content_attributes":{},"send_settings":{},"recurrence":{},"targets":[{}]}}}}}},"/api/v1/accounts/{account_id}/whatsapp_hub/broadcasts/{id}":{"get":{"tags":["WhatsApp Hub"],"operationId":"auto_get_api_v1_accounts_account_id_whatsapp_hub_broadcasts_id","summary":"Get broadcasts","description":"Returns the broadcast identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"inbox_id":{"type":"integer"},"logical_inbox_id":{"type":"integer"},"display_id":{"type":"integer"},"title":{"type":"string"},"message":{"type":"string"},"content_type":{"type":"string","enum":["text","image","video","audio","document","poll","interactive"],"description":"Content type of the broadcast message."},"content_attributes":{"type":"object","additionalProperties":true,"description":"Structured metadata accompanying the message content; the key set depends on content_type (e.g. select items, CSAT submission values, deletion flags, external delivery errors)."},"target_type":{"type":"string","enum":["groups","channels","communities","status","mixed"],"description":"Audience target type of the broadcast."},"targets":{"type":"string"},"schedule_type":{"type":"string","enum":["immediate","scheduled","recurring"],"description":"When the broadcast sends."},"scheduled_at":{"type":"string","format":"date-time"},"recurrence":{"type":"object","additionalProperties":true,"description":"JSONB recurrence rule: frequency (daily|weekly|monthly|yearly), interval, until, count, days."},"recurrence_parent_id":{"type":"integer"},"send_settings":{"type":"string"},"status":{"type":"string","enum":["draft","scheduled","sending","completed","paused","failed","cancelled"],"description":"Lifecycle status of the broadcast."},"sender_id":{"type":"integer"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"stats":{"type":"object","properties":{"total":{"type":"integer"},"set":{"type":"integer"}}},"errors":{"type":"array","description":"Grouped delivery failures/skips: each entry carries the recipient status, the failure/skip reason, and the count.","items":{"type":"object","additionalProperties":true,"description":"One (status, reason) group with its recipient count."}},"engagement":{"type":"object","properties":{"by_type":{"type":"object","additionalProperties":{"type":"integer"},"description":"Engagement counts keyed by activity type (poll_voted, button_clicked, reply_sent, reaction_given, media_shared, ...)."},"engaged_participants":{"type":"string"},"reach":{"type":"string"},"audience":{"type":"string"},"engagement_rate":{"type":"number"}}}}}}},"example":{"payload":{"id":1,"account_id":1,"inbox_id":1,"logical_inbox_id":1,"display_id":1,"title":"Sample title","message":"Sample message text.","content_type":"text","content_attributes":{},"target_type":"groups","targets":"sample targets","schedule_type":"immediate","scheduled_at":"2026-01-15T10:30:00.000Z","recurrence":{},"recurrence_parent_id":1,"send_settings":"sample send settings","status":"draft","sender_id":1,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","stats":{"total":1,"set":1},"errors":[{}],"engagement":{"by_type":{},"engaged_participants":"sample engaged participants","reach":"sample reach","audience":"sample audience","engagement_rate":12.5}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]},"patch":{"tags":["WhatsApp Hub"],"operationId":"auto_patch_api_v1_accounts_account_id_whatsapp_hub_broadcasts_id","summary":"Update broadcasts","description":"Edits a broadcast. Only draft, scheduled and paused broadcasts are editable — a sending broadcast would change under the dispatcher and a terminal one (completed/failed/cancelled) is history; both answer 422 with a localized `error` message.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}},"example":{"error":"sample error"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"422":{"description":"The broadcast is sending or terminal — no longer editable.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Localized message explaining the broadcast is no longer editable.","example":"This broadcast can no longer be edited. Only draft, scheduled or paused broadcasts can be edited."}}},"example":{"error":"This broadcast can no longer be edited. Only draft, scheduled or paused broadcasts can be edited."}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string"},"message":{"type":"string"},"content_type":{"type":"string","enum":["text","image","video","audio","document","poll","interactive"],"description":"Content type of the broadcast message."},"target_type":{"type":"string","enum":["groups","channels","communities","status","mixed"],"description":"Audience target type of the broadcast."},"schedule_type":{"type":"string","enum":["immediate","scheduled","recurring"],"description":"When the broadcast sends."},"scheduled_at":{"type":"string","format":"date-time"},"content_attributes":{"type":"object","additionalProperties":true,"description":"Structured metadata accompanying the message content; the key set depends on content_type (e.g. select items, CSAT submission values, deletion flags, external delivery errors)."},"send_settings":{"type":"object","additionalProperties":true,"description":"Free-form object."},"recurrence":{"type":"object","additionalProperties":true,"description":"JSONB recurrence rule: frequency (daily|weekly|monthly|yearly), interval, until, count, days."},"targets":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Free-form object."}}}},"example":{"title":"Sample title","message":"Sample message text.","content_type":"text","target_type":"groups","schedule_type":"immediate","scheduled_at":"2026-01-15T10:30:00.000Z","content_attributes":{},"send_settings":{},"recurrence":{},"targets":[{}]}}}}},"put":{"tags":["WhatsApp Hub"],"operationId":"auto_put_api_v1_accounts_account_id_whatsapp_hub_broadcasts_id","summary":"Update broadcasts","description":"Edits a broadcast. Only draft, scheduled and paused broadcasts are editable — a sending broadcast would change under the dispatcher and a terminal one (completed/failed/cancelled) is history; both answer 422 with a localized `error` message.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}},"example":{"error":"sample error"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"422":{"description":"The broadcast is sending or terminal — no longer editable.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Localized message explaining the broadcast is no longer editable.","example":"This broadcast can no longer be edited. Only draft, scheduled or paused broadcasts can be edited."}}},"example":{"error":"This broadcast can no longer be edited. Only draft, scheduled or paused broadcasts can be edited."}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string"},"message":{"type":"string"},"content_type":{"type":"string","enum":["text","image","video","audio","document","poll","interactive"],"description":"Content type of the broadcast message."},"target_type":{"type":"string","enum":["groups","channels","communities","status","mixed"],"description":"Audience target type of the broadcast."},"schedule_type":{"type":"string","enum":["immediate","scheduled","recurring"],"description":"When the broadcast sends."},"scheduled_at":{"type":"string","format":"date-time"},"content_attributes":{"type":"object","additionalProperties":true,"description":"Structured metadata accompanying the message content; the key set depends on content_type (e.g. select items, CSAT submission values, deletion flags, external delivery errors)."},"send_settings":{"type":"object","additionalProperties":true,"description":"Free-form object."},"recurrence":{"type":"object","additionalProperties":true,"description":"JSONB recurrence rule: frequency (daily|weekly|monthly|yearly), interval, until, count, days."},"targets":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Free-form object."}}}},"example":{"title":"Sample title","message":"Sample message text.","content_type":"text","target_type":"groups","schedule_type":"immediate","scheduled_at":"2026-01-15T10:30:00.000Z","content_attributes":{},"send_settings":{},"recurrence":{},"targets":[{}]}}}}},"delete":{"tags":["WhatsApp Hub"],"operationId":"auto_delete_api_v1_accounts_account_id_whatsapp_hub_broadcasts_id","summary":"Delete broadcasts","description":"Deletes the broadcast identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}},"example":{"error":"sample error"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/whatsapp_hub/participants":{"get":{"tags":["WhatsApp Hub"],"operationId":"auto_get_api_v1_accounts_account_id_whatsapp_hub_participants","summary":"List participants","description":"Returns the list of participants visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"whatsapp_group_id":{"type":"integer"},"jid":{"type":"string"},"name":{"type":"string"},"display_name":{"type":"string"},"phone":{"type":"string"},"role":{"type":"string","enum":["agent","administrator"]},"status":{"type":"string","enum":["active","left","removed","pending"],"description":"Membership status of the participant."},"contact_id":{"type":"integer"},"avatar_url":{"type":["string","null"]},"engagement_score":{"type":"string"},"messages_count":{"type":"integer"},"replies_count":{"type":"integer"},"reactions_given_count":{"type":"integer"},"reactions_received_count":{"type":"integer"},"poll_votes_count":{"type":"integer"},"button_clicks_count":{"type":"integer"},"media_count":{"type":"integer"},"last_active_at":{"type":"string","format":"date-time"},"joined_at":{"type":"string","format":"date-time"}}}},"meta":{"type":"object","properties":{"count":{"type":"integer"},"current_page":{"type":"string"},"total_pages":{"type":"string"},"per_page":{"type":"string"},"has_more":{"type":"boolean"}}}}},"example":{"payload":[{"id":1,"whatsapp_group_id":1,"jid":"sample jid","name":"Sample Name","display_name":"sample display name","phone":"+5511999998888","role":"agent","status":"active","contact_id":1,"avatar_url":"https://example.com/resource","engagement_score":"sample engagement score","messages_count":5,"replies_count":5,"reactions_given_count":5,"reactions_received_count":5,"poll_votes_count":5,"button_clicks_count":5,"media_count":5,"last_active_at":"2026-01-15T10:30:00.000Z","joined_at":"2026-01-15T10:30:00.000Z"}],"meta":{"count":5,"current_page":"sample current page","total_pages":"sample total pages","per_page":"sample per page","has_more":true}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."}]}},"/api/v1/accounts/{account_id}/whatsapp_hub/sync":{"post":{"tags":["WhatsApp Hub"],"operationId":"auto_post_api_v1_accounts_account_id_whatsapp_hub_sync","summary":"Synchronize WhatsApp Hub data","description":"Queues the full WhatsApp Hub synchronization for the selected Web transport and returns 202 with status enqueued. While WhatsApp is rate limiting this number, no job is queued: the response is 200 with status paused, the whatsapp_rate_limit reason, retry_at and a localized message. The pause starts at 30 minutes and grows up to 6 hours while the limit persists; it ends by itself on the first synchronization that succeeds. logical_inbox_id is present only when the agent-facing unified inbox differs from the physical inbox_id.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","example":"paused","enum":["paused"],"description":"Acknowledges the group/channel sync job was enqueued."},"inbox_id":{"type":"integer"},"logical_inbox_id":{"type":"integer"},"reason":{"type":"string","example":"whatsapp_rate_limit","enum":["whatsapp_rate_limit"]},"retry_at":{"type":"string","format":"date-time"},"message":{"type":"string"}},"required":["status","inbox_id","reason","retry_at","message"],"additionalProperties":false},"example":{"status":"paused","inbox_id":1,"logical_inbox_id":1,"reason":"whatsapp_rate_limit","retry_at":"2026-01-15T10:30:00.000Z","message":"Sample message text."}}}},"202":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","example":"enqueued","enum":["enqueued"],"description":"Acknowledges the group/channel sync job was enqueued."},"inbox_id":{"type":"integer"},"logical_inbox_id":{"type":"integer"}},"required":["status","inbox_id"],"additionalProperties":false},"example":{"status":"enqueued","inbox_id":1,"logical_inbox_id":1}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/whatsapp_hub/engagement":{"get":{"tags":["WhatsApp Hub"],"operationId":"auto_get_api_v1_accounts_account_id_whatsapp_hub_engagement","summary":"Get engagement","description":"Returns the engagement identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"scope":{"type":"string"},"period":{"type":"string"},"tiers":{"type":"string"},"ranking":{"type":"array","items":{"type":"object","properties":{"rank":{"type":"string"},"participant":{"type":"string"}}}}}}}},"example":{"payload":{"scope":"sample scope","period":"sample period","tiers":"sample tiers","ranking":[{"rank":"sample rank","participant":"sample participant"}]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"period","in":"query","required":false,"description":"Window the engagement ranking is computed over.","schema":{"type":"string"},"example":"month"}]}},"/api/v1/accounts/{account_id}/whatsapp_hub/reports":{"get":{"tags":["WhatsApp Hub"],"operationId":"auto_get_api_v1_accounts_account_id_whatsapp_hub_reports","summary":"List reports","description":"Returns the list of reports visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"scope":{"type":"string"},"summary":{"type":"string"},"activity_by_type":{"type":"array","description":"Activity breakdown by event type.","items":{"type":"object","properties":{"type":{"type":"string","description":"Activity/event type."},"count":{"type":"integer"}}}},"activity_over_time":{"type":"string","format":"date-time"},"top_participants":{"type":"string"},"funnel":{"type":"string"}}}}},"example":{"payload":{"scope":"sample scope","summary":"sample summary","activity_by_type":[{"type":"sample type","count":5}],"activity_over_time":"2026-01-15T10:30:00.000Z","top_participants":"sample top participants","funnel":"sample funnel"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."},{"name":"inbox_id","in":"query","required":false,"schema":{"type":"integer"}},{"name":"group_id","in":"query","required":false,"schema":{"type":"integer"}},{"name":"period","in":"query","required":false,"schema":{"type":"string"}},{"name":"kind","in":"query","required":false,"schema":{"type":"string"}},{"name":"scope_type","in":"query","required":false,"schema":{"type":"string"}},{"name":"scope_id","in":"query","required":false,"schema":{"type":"integer"}}]}},"/api/v1/accounts/{account_id}/whatsapp_hub/settings":{"get":{"tags":["WhatsApp Hub"],"operationId":"auto_get_api_v1_accounts_account_id_whatsapp_hub_settings","summary":"Get settings","description":"Returns the setting identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"inbox_id":{"type":["integer","null"]},"logical_inbox_id":{"type":"integer"},"engagement":{"type":"string"},"sync":{"type":"string"},"broadcast":{"type":"string"},"sources":{"type":"object","properties":{"broadcast":{"type":"object","properties":{"distribution_max_confirmed_provision_attempts":{"type":"string"}}}}},"ai":{"type":"string"},"greeting":{"type":"string"}}}}},"example":{"payload":{"inbox_id":1,"logical_inbox_id":1,"engagement":"sample engagement","sync":"sample sync","broadcast":"sample broadcast","sources":{"broadcast":{"distribution_max_confirmed_provision_attempts":"sample distribution max confirmed provision attempts"}},"ai":"sample ai","greeting":"sample greeting"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]},"patch":{"tags":["WhatsApp Hub"],"operationId":"auto_patch_api_v1_accounts_account_id_whatsapp_hub_settings","summary":"Update WhatsApp Hub settings","description":"Deep-merges the submitted sections (engagement, sync, broadcast, ai, greeting) into the settings row of the inbox given by `inbox_id`, or into the account default row when `inbox_id` is omitted, and returns the resolved settings. Changing an AI scope key — `ai.group_ai_policy`, `ai.channel_ai_policy` or `ai.status_ai_policy` — requires a human actor: a person's session or personal access token. The Maestro service user, an agent bot and an MCP tool call are refused with 403 `{ \"error\": \"human_actor_required\", \"keys\": [...] }` and nothing in the request is applied, so an AI cannot widen where it is allowed to answer. Re-sending the value already stored is not a change. Every other settings key keeps accepting those credentials.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"inbox_id":{"type":["integer","null"]},"logical_inbox_id":{"type":"integer"},"engagement":{"type":"string"},"sync":{"type":"string"},"broadcast":{"type":"string"},"sources":{"type":"object","properties":{"broadcast":{"type":"object","properties":{"distribution_max_confirmed_provision_attempts":{"type":"string"}}}}},"ai":{"type":"string"},"greeting":{"type":"string"}}}}},"example":{"payload":{"inbox_id":1,"logical_inbox_id":1,"engagement":"sample engagement","sync":"sample sync","broadcast":"sample broadcast","sources":{"broadcast":{"distribution_max_confirmed_provision_attempts":"sample distribution max confirmed provision attempts"}},"ai":"sample ai","greeting":"sample greeting"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","description":"Only the sections present are changed. Each section is an object; a section that is not an object is refused with 422 invalid_settings_section.","properties":{"inbox_id":{"type":"integer","description":"Inbox whose override row is updated. Omit it to update the account default row."},"engagement":{"type":"object","additionalProperties":true,"description":"Engagement score tunables (weights per interaction, decay_half_life_days, tiers). Deep-merged into the stored section."},"sync":{"type":"object","additionalProperties":true,"description":"Group mirror sync tunables (enabled, interval_minutes, auto_create_group_conversation). Deep-merged into the stored section."},"broadcast":{"type":"object","additionalProperties":true,"description":"Outbound pacing and Launch Group Distribution safeguards. Deep-merged into the stored section; a null distribution_max_confirmed_provision_attempts removes only that inbox/account override so it inherits the next layer.","properties":{"distribution_max_confirmed_provision_attempts":{"type":["integer","null"],"minimum":1,"description":"Maximum explicitly rejected WhatsApp group-create attempts for one launch unit before its distribution pauses. Timeout and ambiguous outcomes never consume or bypass this limit: they require explicit reconciliation.","example":3}}},"ai":{"type":"object","additionalProperties":true,"description":"Maestro scope policies: group_ai_policy, channel_ai_policy and status_ai_policy (all, opt_in or off). Changing them requires a human actor."},"greeting":{"type":"object","additionalProperties":true,"description":"Group greeting tunables (for example name_fallback). Deep-merged into the stored section."}}},"example":{"inbox_id":8,"ai":{"group_ai_policy":"opt_in"},"greeting":{"name_fallback":"Pessoa"},"broadcast":{"distribution_max_confirmed_provision_attempts":3},"engagement":{},"sync":{}}}}}},"put":{"tags":["WhatsApp Hub"],"operationId":"auto_put_api_v1_accounts_account_id_whatsapp_hub_settings","summary":"Update WhatsApp Hub settings","description":"Deep-merges the submitted sections (engagement, sync, broadcast, ai, greeting) into the settings row of the inbox given by `inbox_id`, or into the account default row when `inbox_id` is omitted, and returns the resolved settings. Changing an AI scope key — `ai.group_ai_policy`, `ai.channel_ai_policy` or `ai.status_ai_policy` — requires a human actor: a person's session or personal access token. The Maestro service user, an agent bot and an MCP tool call are refused with 403 `{ \"error\": \"human_actor_required\", \"keys\": [...] }` and nothing in the request is applied, so an AI cannot widen where it is allowed to answer. Re-sending the value already stored is not a change. Every other settings key keeps accepting those credentials.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"inbox_id":{"type":["integer","null"]},"logical_inbox_id":{"type":"integer"},"engagement":{"type":"string"},"sync":{"type":"string"},"broadcast":{"type":"string"},"sources":{"type":"object","properties":{"broadcast":{"type":"object","properties":{"distribution_max_confirmed_provision_attempts":{"type":"string"}}}}},"ai":{"type":"string"},"greeting":{"type":"string"}}}}},"example":{"payload":{"inbox_id":1,"logical_inbox_id":1,"engagement":"sample engagement","sync":"sample sync","broadcast":"sample broadcast","sources":{"broadcast":{"distribution_max_confirmed_provision_attempts":"sample distribution max confirmed provision attempts"}},"ai":"sample ai","greeting":"sample greeting"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","description":"Only the sections present are changed. Each section is an object; a section that is not an object is refused with 422 invalid_settings_section.","properties":{"inbox_id":{"type":"integer","description":"Inbox whose override row is updated. Omit it to update the account default row."},"engagement":{"type":"object","additionalProperties":true,"description":"Engagement score tunables (weights per interaction, decay_half_life_days, tiers). Deep-merged into the stored section."},"sync":{"type":"object","additionalProperties":true,"description":"Group mirror sync tunables (enabled, interval_minutes, auto_create_group_conversation). Deep-merged into the stored section."},"broadcast":{"type":"object","additionalProperties":true,"description":"Outbound pacing and Launch Group Distribution safeguards. Deep-merged into the stored section; a null distribution_max_confirmed_provision_attempts removes only that inbox/account override so it inherits the next layer.","properties":{"distribution_max_confirmed_provision_attempts":{"type":["integer","null"],"minimum":1,"description":"Maximum explicitly rejected WhatsApp group-create attempts for one launch unit before its distribution pauses. Timeout and ambiguous outcomes never consume or bypass this limit: they require explicit reconciliation.","example":3}}},"ai":{"type":"object","additionalProperties":true,"description":"Maestro scope policies: group_ai_policy, channel_ai_policy and status_ai_policy (all, opt_in or off). Changing them requires a human actor."},"greeting":{"type":"object","additionalProperties":true,"description":"Group greeting tunables (for example name_fallback). Deep-merged into the stored section."}}},"example":{"inbox_id":8,"ai":{"group_ai_policy":"opt_in"},"greeting":{"name_fallback":"Pessoa"},"broadcast":{"distribution_max_confirmed_provision_attempts":3},"engagement":{},"sync":{}}}}}}},"/api/v1/accounts/{account_id}/flow_builder/flows/{id}/publish":{"post":{"tags":["Flow Builder"],"operationId":"auto_post_api_v1_accounts_account_id_flow_builder_flows_id_publish","summary":"Publish flows","description":"Performs the publish operation on the targeted flow resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"status":{"type":"string","enum":["draft","published","retired"]},"trigger_type":{"type":"string","enum":["","trigger_conversation_created","trigger_conversation_opened","trigger_conversation_resolved","trigger_conversation_status_changed","trigger_first_reply","trigger_message_received","trigger_keyword","trigger_label_added","trigger_contact_created","trigger_contact_updated","trigger_contact_merged","trigger_api_called","trigger_webhook_received","trigger_scheduled","trigger_payment_charge","trigger_payment_subscription","trigger_payment_installment_plan","trigger_commerce","trigger_crm_item","trigger_task","trigger_order","trigger_contract","trigger_catalog","trigger_follow_up","trigger_engagement","trigger_sales","trigger_ads","trigger_organization","trigger_team","trigger_captain","trigger_campaign","trigger_media_library","trigger_organization_created","trigger_organization_updated","trigger_calendar_booking","trigger_whatsapp_flow_response","trigger_calendar_event"]},"trigger_config":{"type":"string","description":"Free-form trigger configuration; the key set depends on the trigger type."},"settings":{"type":"string","description":"Free-form flow settings merged over the engine defaults."},"published_version_id":{"type":"integer"},"folder_id":{"type":"integer"},"inbox_ids":{"type":"array","items":{"type":"integer"}},"physical_inbox_ids":{"type":"array","items":{"type":"integer"}},"physical_trigger_inbox_ids":{"type":"array","items":{"type":"integer"}},"archived":{"type":"boolean"},"created_by_id":{"type":"integer"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"definition":{"type":"string","description":"The flow graph (nodes and edges) for this version."}}}}},"example":{"payload":{"id":1,"name":"Sample Name","description":"A short description.","status":"draft","trigger_type":"","trigger_config":"sample trigger config","settings":"sample settings","published_version_id":1,"folder_id":1,"inbox_ids":[1],"physical_inbox_ids":[1],"physical_trigger_inbox_ids":[1],"archived":true,"created_by_id":1,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","definition":"sample definition"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"If-Match","in":"header","required":true,"description":"ETag returned by the latest GET or PUT of this flow's draft.","schema":{"type":"string","pattern":"^\"flow-[0-9]+-draft-[0-9]+\"$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["definition_checksum"],"properties":{"definition_checksum":{"type":"string","pattern":"^[a-f0-9]{64}$"}}},"example":{"definition_checksum":"sample definition checksum"}}}}}},"/api/v1/accounts/{account_id}/flow_builder/flows/{id}/unpublish":{"post":{"tags":["Flow Builder"],"operationId":"auto_post_api_v1_accounts_account_id_flow_builder_flows_id_unpublish","summary":"Unpublish flows","description":"Performs the unpublish operation on the targeted flow resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"status":{"type":"string","enum":["draft","published","retired"]},"trigger_type":{"type":"string","enum":["","trigger_conversation_created","trigger_conversation_opened","trigger_conversation_resolved","trigger_conversation_status_changed","trigger_first_reply","trigger_message_received","trigger_keyword","trigger_label_added","trigger_contact_created","trigger_contact_updated","trigger_contact_merged","trigger_api_called","trigger_webhook_received","trigger_scheduled","trigger_payment_charge","trigger_payment_subscription","trigger_payment_installment_plan","trigger_commerce","trigger_crm_item","trigger_task","trigger_order","trigger_contract","trigger_catalog","trigger_follow_up","trigger_engagement","trigger_sales","trigger_ads","trigger_organization","trigger_team","trigger_captain","trigger_campaign","trigger_media_library","trigger_organization_created","trigger_organization_updated","trigger_calendar_booking","trigger_whatsapp_flow_response","trigger_calendar_event"]},"trigger_config":{"type":"string","description":"Free-form trigger configuration; the key set depends on the trigger type."},"settings":{"type":"string","description":"Free-form flow settings merged over the engine defaults."},"published_version_id":{"type":"integer"},"folder_id":{"type":"integer"},"inbox_ids":{"type":"array","items":{"type":"integer"}},"physical_inbox_ids":{"type":"array","items":{"type":"integer"}},"physical_trigger_inbox_ids":{"type":"array","items":{"type":"integer"}},"archived":{"type":"boolean"},"created_by_id":{"type":"integer"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"definition":{"type":"string","description":"The flow graph (nodes and edges) for this version."}}}}},"example":{"payload":{"id":1,"name":"Sample Name","description":"A short description.","status":"draft","trigger_type":"","trigger_config":"sample trigger config","settings":"sample settings","published_version_id":1,"folder_id":1,"inbox_ids":[1],"physical_inbox_ids":[1],"physical_trigger_inbox_ids":[1],"archived":true,"created_by_id":1,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","definition":"sample definition"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/flow_builder/flows/{id}/duplicate":{"post":{"tags":["Flow Builder"],"operationId":"auto_post_api_v1_accounts_account_id_flow_builder_flows_id_duplicate","summary":"Duplicate flows","description":"Performs the duplicate operation on the targeted flow resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"201":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"status":{"type":"string","enum":["draft","published","retired"]},"trigger_type":{"type":"string","enum":["","trigger_conversation_created","trigger_conversation_opened","trigger_conversation_resolved","trigger_conversation_status_changed","trigger_first_reply","trigger_message_received","trigger_keyword","trigger_label_added","trigger_contact_created","trigger_contact_updated","trigger_contact_merged","trigger_api_called","trigger_webhook_received","trigger_scheduled","trigger_payment_charge","trigger_payment_subscription","trigger_payment_installment_plan","trigger_commerce","trigger_crm_item","trigger_task","trigger_order","trigger_contract","trigger_catalog","trigger_follow_up","trigger_engagement","trigger_sales","trigger_ads","trigger_organization","trigger_team","trigger_captain","trigger_campaign","trigger_media_library","trigger_organization_created","trigger_organization_updated","trigger_calendar_booking","trigger_whatsapp_flow_response","trigger_calendar_event"]},"trigger_config":{"type":"string","description":"Free-form trigger configuration; the key set depends on the trigger type."},"settings":{"type":"string","description":"Free-form flow settings merged over the engine defaults."},"published_version_id":{"type":"integer"},"folder_id":{"type":"integer"},"inbox_ids":{"type":"array","items":{"type":"integer"}},"physical_inbox_ids":{"type":"array","items":{"type":"integer"}},"physical_trigger_inbox_ids":{"type":"array","items":{"type":"integer"}},"archived":{"type":"boolean"},"created_by_id":{"type":"integer"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"definition":{"type":"string","description":"The flow graph (nodes and edges) for this version."}}}}},"example":{"payload":{"id":1,"name":"Sample Name","description":"A short description.","status":"draft","trigger_type":"","trigger_config":"sample trigger config","settings":"sample settings","published_version_id":1,"folder_id":1,"inbox_ids":[1],"physical_inbox_ids":[1],"physical_trigger_inbox_ids":[1],"archived":true,"created_by_id":1,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","definition":"sample definition"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/flow_builder/flows/{id}/restore":{"post":{"tags":["Flow Builder"],"operationId":"auto_post_api_v1_accounts_account_id_flow_builder_flows_id_restore","summary":"Restore flows","description":"Performs the restore operation on the targeted flow resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"status":{"type":"string","enum":["draft","published","retired"]},"trigger_type":{"type":"string","enum":["","trigger_conversation_created","trigger_conversation_opened","trigger_conversation_resolved","trigger_conversation_status_changed","trigger_first_reply","trigger_message_received","trigger_keyword","trigger_label_added","trigger_contact_created","trigger_contact_updated","trigger_contact_merged","trigger_api_called","trigger_webhook_received","trigger_scheduled","trigger_payment_charge","trigger_payment_subscription","trigger_payment_installment_plan","trigger_commerce","trigger_crm_item","trigger_task","trigger_order","trigger_contract","trigger_catalog","trigger_follow_up","trigger_engagement","trigger_sales","trigger_ads","trigger_organization","trigger_team","trigger_captain","trigger_campaign","trigger_media_library","trigger_organization_created","trigger_organization_updated","trigger_calendar_booking","trigger_whatsapp_flow_response","trigger_calendar_event"]},"trigger_config":{"type":"string","description":"Free-form trigger configuration; the key set depends on the trigger type."},"settings":{"type":"string","description":"Free-form flow settings merged over the engine defaults."},"published_version_id":{"type":"integer"},"folder_id":{"type":"integer"},"inbox_ids":{"type":"array","items":{"type":"integer"}},"physical_inbox_ids":{"type":"array","items":{"type":"integer"}},"physical_trigger_inbox_ids":{"type":"array","items":{"type":"integer"}},"archived":{"type":"boolean"},"created_by_id":{"type":"integer"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"definition":{"type":"string","description":"The flow graph (nodes and edges) for this version."}}}}},"example":{"payload":{"id":1,"name":"Sample Name","description":"A short description.","status":"draft","trigger_type":"","trigger_config":"sample trigger config","settings":"sample settings","published_version_id":1,"folder_id":1,"inbox_ids":[1],"physical_inbox_ids":[1],"physical_trigger_inbox_ids":[1],"archived":true,"created_by_id":1,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","definition":"sample definition"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/flow_builder/flows/{id}/purge":{"delete":{"tags":["Flow Builder"],"operationId":"auto_delete_api_v1_accounts_account_id_flow_builder_flows_id_purge","summary":"Purge flows","description":"Performs the purge operation on the targeted flow resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Success (no content)"},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/flow_builder/flows/{id}/validate":{"post":{"tags":["Flow Builder"],"operationId":"auto_post_api_v1_accounts_account_id_flow_builder_flows_id_validate","summary":"Validate flows","description":"Performs the validate operation on the targeted flow resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"valid":{"type":"boolean"},"errors":{"type":"string"},"warnings":{"type":"string"}}}}},"example":{"payload":{"valid":true,"errors":"sample errors","warnings":"sample warnings"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/flow_builder/flows/{id}/dry_run":{"post":{"tags":["Flow Builder"],"operationId":"auto_post_api_v1_accounts_account_id_flow_builder_flows_id_dry_run","summary":"Compile and traverse a FlowBuilder draft without side effects","description":"Returns the potential ordered steps and external-effect inventory; no session, executor, provider or domain effect is created.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Side-effect-free compiled plan projection, including canonical errors when invalid.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["payload"],"properties":{"payload":{"type":"object","additionalProperties":false,"required":["valid","side_effects_executed","errors","steps","effects","summary"],"properties":{"valid":{"type":"boolean"},"side_effects_executed":{"type":"boolean","enum":[false]},"errors":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["code","node_id","edge_id","field","params","severity"],"properties":{"code":{"type":"string","description":"Stable machine-readable validation or conflict code."},"node_id":{"type":["string","null"],"description":"Canvas node that caused the issue","when applicable.":null},"edge_id":{"type":["string","null"],"description":"Canvas edge that caused the issue","when applicable.":null},"field":{"type":["string","null"],"description":"Definition or request field associated with the issue."},"params":{"type":"object","additionalProperties":true,"description":"Non-sensitive structured values used to explain or localize the issue."},"severity":{"type":"string","enum":["error","warning"]}}}},"definition_checksum":{"type":"string"},"manifest_version":{"type":"string"},"entrypoint":{"type":"string"},"steps":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"One potential compiled step with node identity, effect mode, retry and outgoing transitions."}},"effects":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"External effect a separately confirmed live run may execute."}},"summary":{"type":"object","additionalProperties":false,"required":["steps","pure_steps","external_effects"],"properties":{"steps":{"type":"integer","minimum":0},"pure_steps":{"type":"integer","minimum":0},"external_effects":{"type":"integer","minimum":0}}}}}}},"example":{"payload":{"valid":true,"side_effects_executed":false,"errors":[{"code":"sample code","node_id":"sample node id","edge_id":"sample edge id","field":"sample field","params":{},"severity":"error"}],"definition_checksum":"sample definition checksum","manifest_version":"sample manifest version","entrypoint":"sample entrypoint","steps":[{}],"effects":[{}],"summary":{"steps":1,"pure_steps":1,"external_effects":1}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/flow_builder/flows/{id}/test_run":{"post":{"tags":["Flow Builder"],"operationId":"auto_post_api_v1_accounts_account_id_flow_builder_flows_id_test_run","summary":"Run a flow's draft once (test run)","description":"Runs the flow's CURRENT editor (draft) definition a single time WITHOUT publishing — parity with Make/n8n's \"Run once\". ⚠️ Real side effects: the flow's actions (messages, charges, records) actually execute, so this is admin-only. The server requires an explicit confirmation bound to the SHA-256 checksum returned by the immediately preceding dry-run; a missing or stale confirmation returns 428 without creating a session. The draft graph is validated first (422 with `errors` on an invalid graph). With no conversation the run seeds an internal skip flag so message nodes are SKIPPED instead of failing (`messages_skipped: true`); pass an optional `conversation_id` (display id or global id) / `contact_id` to run against a real subject. The test session becomes the flow's last_run, so poll GET /flow_builder/flows/{id}/last_run for per-node status (`step_logs`) and mapped values.","security":[{"userApiKey":[]}],"responses":{"201":{"description":"The test session was started.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"session_id":{"type":"integer","description":"The created test session id (poll last_run for progress).","example":1201},"status":{"type":"string","enum":["running","waiting","completed","failed","canceled"],"description":"Lifecycle state of the test session at creation.","example":"running"},"version_id":{"type":"integer","description":"The pinned (draft) version this run executed.","example":88},"messages_skipped":{"type":"boolean","description":"True when the run had no conversation, so message nodes were skipped.","example":true}}}}},"example":{"payload":{"session_id":1201,"status":"running","version_id":88,"messages_skipped":true}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"422":{"description":"The draft graph is invalid, no runnable version exists, or the session could not start.","content":{"application/json":{"schema":{"type":"object","properties":{"errors":{"type":"array","description":"Present when the draft graph failed strict validation.","items":{"type":"object","additionalProperties":false,"required":["code","node_id","edge_id","field","params","severity"],"properties":{"code":{"type":"string"},"node_id":{"type":["string","null"]},"edge_id":{"type":["string","null"]},"field":{"type":["string","null"]},"params":{"type":"object","additionalProperties":true,"description":"Structured, non-secret interpolation parameters for this validation error."},"severity":{"type":"string","enum":["error","warning"]}}}},"error":{"type":"string","description":"Present when there is no runnable version or the session did not start.","enum":["no_runnable_version","session_not_started"],"example":"session_not_started"}}},"example":{"errors":[{"code":"sample code","node_id":"sample node id","edge_id":"sample edge id","field":"sample field","params":{},"severity":"error"}],"error":"session_not_started"}}}},"428":{"description":"Explicit live-effect confirmation is missing or its dry-run checksum is stale.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["code","node_id","edge_id","field","params","severity"],"properties":{"code":{"type":"string"},"node_id":{"type":["string","null"]},"edge_id":{"type":["string","null"]},"field":{"type":["string","null"]},"params":{"type":"object","additionalProperties":true,"description":"Structured, non-secret interpolation parameters for this validation error."},"severity":{"type":"string","enum":["error","warning"]}}}}}},"example":{"errors":[{"code":"sample code","node_id":"sample node id","edge_id":"sample edge id","field":"sample field","params":{},"severity":"error"}]}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["confirmed_effects","definition_checksum"],"properties":{"confirmed_effects":{"type":"boolean","enum":[true],"description":"Explicit acknowledgement that the inventoried live effects may execute.","example":true},"definition_checksum":{"type":"string","pattern":"^[a-f0-9]{64}$","description":"Exact checksum returned by POST /flow_builder/flows/{id}/dry_run.","example":"a3f5d79c4e3b5c18bba763f70ca2bd90d7a59fd12ba0138c019296ea7866f507"},"payload":{"type":"object","additionalProperties":true,"description":"Optional sample payload reachable in the flow as {{ trigger.body.* }} (clamped to 64KB).","example":{"order":{"id":"ABC-1","total":4.97},"status":"paid"}},"conversation_id":{"type":["integer","string"],"description":"Optional conversation to run against (display id first, then global id).","example":173},"contact_id":{"type":"integer","description":"Optional contact subject when there is no conversation.","example":4021}}},"example":{"confirmed_effects":true,"definition_checksum":"a3f5d79c4e3b5c18bba763f70ca2bd90d7a59fd12ba0138c019296ea7866f507","payload":{"order":{"id":"ABC-1","total":4.97},"status":"paid"},"conversation_id":173,"contact_id":4021}}}}}},"/api/v1/accounts/{account_id}/flow_builder/flows/{id}/export":{"get":{"tags":["Flow Builder"],"operationId":"auto_get_api_v1_accounts_account_id_flow_builder_flows_id_export","summary":"Export flows","description":"Performs the export operation on the targeted flow resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"string"}}},"example":{"payload":"sample payload"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/flow_builder/flows/{id}/trigger_sample":{"get":{"tags":["Flow Builder"],"operationId":"auto_get_api_v1_accounts_account_id_flow_builder_flows_id_trigger_sample","summary":"Get a flow's trigger sample payload","description":"Returns the trigger sample the editor uses to map incoming payload fields to named flow variables. `last` is the last signed test event captured from the live webhook receiver (or an API/manual run), stored in Redis with a 24h TTL; `pinned` is the durable sample the operator saved into settings.trigger_sample (it travels with an exported flow). Either side is null when unset. Read-only (admin or agent).","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The last-received and pinned trigger samples.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"last":{"type":["object","null"],"description":"Last-received test event (Redis, 24h TTL); null when nothing arrived in the window.","properties":{"received_at":{"type":"string","format":"date-time","example":"2026-01-15T10:30:00.000Z"},"body":{"type":"object","additionalProperties":true,"description":"The bounded webhook/API payload, reachable in the flow as {{ trigger.body.* }}.","example":{"order":{"id":"ABC-1","total":4.97},"status":"paid"}}}},"pinned":{"type":["object","null"],"description":"Operator-pinned durable sample (settings.trigger_sample); null when unpinned.","properties":{"pinned_at":{"type":"string","format":"date-time","example":"2026-01-15T09:00:00.000Z"},"body":{"type":"object","additionalProperties":true,"description":"The pinned payload used for field mapping when no live event is available.","example":{"order":{"id":"ABC-1"},"status":"paid"}}}},"last_delivery":{"type":["object","null"],"description":"The last inbound webhook delivery outcome (Redis, 24h TTL) for the editor's status panel: whether the last POST was accepted (published run started), captured as a sample (draft), dropped as a replay, or rejected by authentication — plus when and the effective auth mode. Never contains the request body/headers. null when nothing arrived in the window.","properties":{"status":{"type":"string","enum":["accepted","sample_captured","replayed","unauthorized"],"description":"Outcome of the last delivery.","example":"accepted"},"at":{"type":"string","format":"date-time","description":"When the delivery was processed.","example":"2026-01-15T10:30:00.000Z"},"mode":{"type":"string","enum":["signed","bearer","url_secret"],"description":"The effective authentication mode used for the delivery.","example":"signed"}}},"last_discard":{"type":["object","null"],"description":"The last trigger this flow REFUSED to start (Redis, 24h TTL). A refused trigger used to vanish with no trace, so an operator whose flow \"did not run\" had nothing to look at. `active_session_exists` means the flow was already running for that conversation and the active-session index declined a second concurrent run; `duplicate_trigger` means the same delivery arrived twice and the idempotency key collapsed it. Never contains the payload. null when nothing was discarded in the window.","properties":{"at":{"type":"string","format":"date-time","description":"When the trigger was refused.","example":"2026-01-15T10:31:00.000Z"},"reason":{"type":"string","enum":["active_session_exists","duplicate_trigger"],"description":"Why the trigger did not start a run.","example":"active_session_exists"},"trigger":{"type":"string","description":"The trigger family that fired.","example":"trigger_crm_item"},"conversation_id":{"type":["number","null"],"description":"The conversation the refused trigger belonged to, when it had one.","example":4821}},"example":{"at":"2026-01-15T10:31:00.000Z","reason":"active_session_exists","trigger":"trigger_crm_item","conversation_id":4821}}}}}},"example":{"payload":{"last":{"received_at":"2026-01-15T10:30:00.000Z","body":{"order":{"id":"ABC-1","total":4.97},"status":"paid"}},"pinned":{"pinned_at":"2026-01-15T09:00:00.000Z","body":{"order":{"id":"ABC-1"},"status":"paid"}},"last_delivery":{"status":"accepted","at":"2026-01-15T10:30:00.000Z","mode":"signed"},"last_discard":{"at":"2026-01-15T10:31:00.000Z","reason":"active_session_exists","trigger":"trigger_crm_item","conversation_id":4821}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/flow_builder/flows/{id}/last_run":{"get":{"tags":["Flow Builder"],"operationId":"auto_get_api_v1_accounts_account_id_flow_builder_flows_id_last_run","summary":"Get a flow's last real run data","description":"Returns the flow's freshest genuine run so the editor's field-mapping panel can offer LIVE values (not just the static trigger sample): the run's trigger payload, each node's captured output, and the resolved user variables. The run selected is the newest by created_at EXCLUDING an operator-canceled one (a running / waiting / completed / failed run all carry a real payload, and a failed run is exactly what you debug). Every field is null / empty when the flow has never run. Read-only (admin or agent). PII class = sessions#show — step outputs may carry contact / HTTP data (bounded at write time). Staleness: compare session.flow_version_id to the flow's current version — if it drifted (e.g. a node label was renamed since the run) the step keys below may no longer match the current {{ steps.\u003ckey\u003e }} tokens.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The freshest non-canceled run's trigger, step outputs and resolved variables.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"session":{"type":["object","null"],"description":"Summary of the run these values came from; null when the flow has never run.","properties":{"id":{"type":"integer","example":1201},"status":{"type":"string","enum":["running","waiting","completed","failed","canceled"],"description":"Lifecycle state of the run (a canceled run is never selected here).","example":"completed"},"started_at":{"type":["string","null"],"format":"date-time","description":"When the run started.","example":"2026-01-15T10:30:00.000Z"},"completed_at":{"type":["string","null"],"format":"date-time","description":"When the run finished; null while it is still running / waiting.","example":"2026-01-15T10:30:04.000Z"},"flow_version_id":{"type":"integer","description":"Version the run executed — compare to the current version to detect stale step keys.","example":42},"created_at":{"type":"string","format":"date-time","example":"2026-01-15T10:30:00.000Z"}}},"trigger":{"type":["object","null"],"additionalProperties":true,"description":"The trigger payload captured at run start, reachable as {{ trigger.* }} (a webhook run also carries {{ trigger.body.* }}; API / manual runs carry only via / user_id). Null when the flow has never run.","example":{"via":"webhook","body":{"order":{"id":"ABC-1","total":4.97},"status":"paid"}}},"steps":{"type":"object","additionalProperties":true,"description":"Each node's captured output keyed by its step key (the sanitized node label, or the node id on collision) — reachable as {{ steps.\u003ckey\u003e.\u003cfield\u003e }}. Empty when the run produced no step output.","example":{"lookup_price":{"status":200,"body":{"total":4.97}}}},"vars":{"type":"object","additionalProperties":true,"description":"The run's resolved user variables ({{ vars.* }}); internal __-prefixed keys are removed.","example":{"greeted":true,"plan":"pro"}},"step_logs":{"type":"array","description":"Per-node run status for the editor's canvas overlay — the LATEST log per node_id of the run (a looped node shows its final state; the engine 'engine' failure entry marks a run that failed). Empty when the flow has never run. error is truncated (~200 chars).","items":{"type":"object","properties":{"node_id":{"type":"string","description":"The graph node id this entry belongs to.","example":"msg"},"node_type":{"type":"string","description":"The node's type, or 'engine' for an engine-level failure.","example":"message_text"},"status":{"type":"string","enum":["entered","completed","failed","skipped"],"description":"Terminal status of the node's latest execution.","example":"completed"},"duration_ms":{"type":["integer","null"],"description":"Wall time of the node in milliseconds.","example":12},"error":{"type":["string","null"],"description":"Failure message (truncated to about 200 chars); null on success.","example":null},"created_at":{"type":"string","format":"date-time","example":"2026-01-15T10:30:04.000Z"}}},"example":[{"node_id":"msg","node_type":"message_text","status":"completed","duration_ms":12,"error":null,"created_at":"2026-01-15T10:30:04.000Z"}]}}}}},"example":{"payload":{"session":{"id":1201,"status":"completed","started_at":"2026-01-15T10:30:00.000Z","completed_at":"2026-01-15T10:30:04.000Z","flow_version_id":42,"created_at":"2026-01-15T10:30:00.000Z"},"trigger":{"via":"webhook","body":{"order":{"id":"ABC-1","total":4.97},"status":"paid"}},"steps":{"lookup_price":{"status":200,"body":{"total":4.97}}},"vars":{"greeted":true,"plan":"pro"},"step_logs":[{"node_id":"msg","node_type":"message_text","status":"completed","duration_ms":12,"error":null,"created_at":"2026-01-15T10:30:04.000Z"}]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/flow_builder/flows/{id}/history":{"get":{"tags":["Flow Builder"],"operationId":"auto_get_api_v1_accounts_account_id_flow_builder_flows_id_history","summary":"List immutable FlowBuilder versions","description":"Returns published versions and the current draft as metadata-only, paginated history.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Immutable version history.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["payload","meta"],"properties":{"payload":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["id","version","state","revision","runtime_version","definition_checksum","published_at","created_at","updated_at"],"properties":{"id":{"type":"integer"},"version":{"type":"integer","minimum":0},"state":{"type":"string","enum":["draft","published"]},"revision":{"type":"integer","minimum":0},"runtime_version":{"type":"integer","enum":[1,2]},"definition_checksum":{"type":"string","pattern":"^[a-f0-9]{64}$"},"manifest_version":{"type":["string","null"]},"manifest_checksum":{"type":["string","null"]},"published_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}},"meta":{"type":"object","additionalProperties":false,"required":["current_page","total_pages","total_count"],"properties":{"current_page":{"type":"integer","minimum":1},"total_pages":{"type":"integer","minimum":0},"total_count":{"type":"integer","minimum":0}}}}},"example":{"payload":[{"id":1,"version":1,"state":"draft","revision":1,"runtime_version":1,"definition_checksum":"sample definition checksum","manifest_version":"sample manifest version","manifest_checksum":"sample manifest checksum","published_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}],"meta":{"current_page":1,"total_pages":1,"total_count":5}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/flow_builder/flows/{id}/diff":{"get":{"tags":["Flow Builder"],"operationId":"auto_get_api_v1_accounts_account_id_flow_builder_flows_id_diff","summary":"Compare two FlowBuilder versions structurally","description":"Compares nodes and edges by stable identity so reorder-only edits do not appear as semantic changes.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Metadata for both versions and redacted node/edge changes.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["payload"],"properties":{"payload":{"type":"object","additionalProperties":false,"required":["from","to","diff"],"properties":{"from":{"type":"object","additionalProperties":false,"required":["id","version","state","revision","runtime_version","definition_checksum","published_at","created_at","updated_at"],"properties":{"id":{"type":"integer"},"version":{"type":"integer","minimum":0},"state":{"type":"string","enum":["draft","published"]},"revision":{"type":"integer","minimum":0},"runtime_version":{"type":"integer","enum":[1,2]},"definition_checksum":{"type":"string","pattern":"^[a-f0-9]{64}$"},"manifest_version":{"type":["string","null"]},"manifest_checksum":{"type":["string","null"]},"published_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"to":{"type":"object","additionalProperties":false,"required":["id","version","state","revision","runtime_version","definition_checksum","published_at","created_at","updated_at"],"properties":{"id":{"type":"integer"},"version":{"type":"integer","minimum":0},"state":{"type":"string","enum":["draft","published"]},"revision":{"type":"integer","minimum":0},"runtime_version":{"type":"integer","enum":[1,2]},"definition_checksum":{"type":"string","pattern":"^[a-f0-9]{64}$"},"manifest_version":{"type":["string","null"]},"manifest_checksum":{"type":["string","null"]},"published_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"diff":{"type":"object","additionalProperties":true,"description":"Redacted added, removed and changed collections for nodes and edges."}}}}},"example":{"payload":{"from":{"id":1,"version":1,"state":"draft","revision":1,"runtime_version":1,"definition_checksum":"sample definition checksum","manifest_version":"sample manifest version","manifest_checksum":"sample manifest checksum","published_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"},"to":{"id":1,"version":1,"state":"draft","revision":1,"runtime_version":1,"definition_checksum":"sample definition checksum","manifest_version":"sample manifest version","manifest_checksum":"sample manifest checksum","published_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"},"diff":{}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"from_version_id","in":"query","required":true,"schema":{"type":"integer"}},{"name":"to_version_id","in":"query","required":false,"schema":{"type":"integer"}}]}},"/api/v1/accounts/{account_id}/flow_builder/flows/{id}/restore_version":{"post":{"tags":["Flow Builder"],"operationId":"auto_post_api_v1_accounts_account_id_flow_builder_flows_id_restore_version","summary":"Restore an immutable version as a new editable draft","description":"Copies the selected account-scoped version into the optimistic draft without mutating history.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"string"}}}},"example":{"errors":["sample error"]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"201":{"description":"Restored version copied into a new draft revision.","headers":{"ETag":{"schema":{"type":"string"},"description":"New optimistic draft revision token."}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["payload"],"properties":{"payload":{"type":"object","additionalProperties":false,"required":["id","flow_id","state","revision","etag","definition","definition_checksum","updated_at"],"properties":{"id":{"type":["integer","null"]},"flow_id":{"type":"integer"},"state":{"type":"string","enum":["draft"]},"revision":{"type":"integer","minimum":0},"etag":{"type":"string","description":"Same optimistic revision token as the ETag response header. Mirrored into the body because cache-rewriting middleware and proxies can strip the header, which would strand every subsequent If-Match write."},"definition":{"type":"object","additionalProperties":false,"required":["nodes","edges"],"properties":{"nodes":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["id","type","data"],"properties":{"id":{"type":"string"},"type":{"type":"string"},"label":{"type":["string","null"]},"position":{"type":"object","additionalProperties":false,"properties":{"x":{"type":"number"},"y":{"type":"number"}}},"data":{"type":"object","additionalProperties":true,"description":"Manifest-schema-validated configuration for this node type; secrets are forbidden inline. Reply-wait nodes snapshot on_human_takeover; omitted means cancel for existing published flows.","properties":{"on_human_takeover":{"type":"string","enum":["cancel","keep"],"default":"cancel","description":"For wait_for_reply and wait_for_follow_up_reply only. Cancel the reply wait on an attributed human intervention, or keep waiting."}}}}}},"edges":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["id","source","target"],"properties":{"id":{"type":"string"},"source":{"type":"string"},"target":{"type":"string"},"sourceHandle":{"type":["string","null"]},"label":{"type":["string","null"]}}}}},"description":"The flow graph (nodes and edges) for this version."},"definition_checksum":{"type":"string","pattern":"^[a-f0-9]{64}$"},"updated_at":{"type":["string","null"],"format":"date-time"},"restored_from_version_id":{"type":"integer"}}}}},"example":{"payload":{"id":1,"flow_id":1,"state":"draft","revision":1,"etag":"sample etag","definition":{"nodes":[{"id":"sample id","type":"sample type","label":"sample label","position":{"x":12.5,"y":12.5},"data":{"on_human_takeover":"cancel"}}],"edges":[{"id":"sample id","source":"sample source","target":"sample target","sourceHandle":"sample sourceHandle","label":"sample label"}]},"definition_checksum":"sample definition checksum","updated_at":"2026-01-15T10:30:00.000Z","restored_from_version_id":1}}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"If-Match","in":"header","required":true,"description":"ETag returned by the latest GET or PUT of this flow's draft.","schema":{"type":"string","pattern":"^\"flow-[0-9]+-draft-[0-9]+\"$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["version_id"],"properties":{"version_id":{"type":"integer"}}},"example":{"version_id":1}}}}}},"/api/v1/accounts/{account_id}/flow_builder/flows/import":{"post":{"tags":["Flow Builder"],"operationId":"auto_post_api_v1_accounts_account_id_flow_builder_flows_import","summary":"Import a flow from a bundle","description":"Creates a draft flow from an exported bundle (name/description/trigger + definition) and saves its first draft version. Accepts the bundle under `flow`, `bundle`, or at the top level.","security":[{"userApiKey":[]}],"responses":{"201":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"status":{"type":"string","enum":["draft","published","retired"]},"trigger_type":{"type":"string","enum":["","trigger_conversation_created","trigger_conversation_opened","trigger_conversation_resolved","trigger_conversation_status_changed","trigger_first_reply","trigger_message_received","trigger_keyword","trigger_label_added","trigger_contact_created","trigger_contact_updated","trigger_contact_merged","trigger_api_called","trigger_webhook_received","trigger_scheduled","trigger_payment_charge","trigger_payment_subscription","trigger_payment_installment_plan","trigger_commerce","trigger_crm_item","trigger_task","trigger_order","trigger_contract","trigger_catalog","trigger_follow_up","trigger_engagement","trigger_sales","trigger_ads","trigger_organization","trigger_team","trigger_captain","trigger_campaign","trigger_media_library","trigger_organization_created","trigger_organization_updated","trigger_calendar_booking","trigger_whatsapp_flow_response","trigger_calendar_event"]},"trigger_config":{"type":"string","description":"Free-form trigger configuration; the key set depends on the trigger type."},"settings":{"type":"string","description":"Free-form flow settings merged over the engine defaults."},"published_version_id":{"type":"integer"},"folder_id":{"type":"integer"},"inbox_ids":{"type":"array","items":{"type":"integer"}},"physical_inbox_ids":{"type":"array","items":{"type":"integer"}},"physical_trigger_inbox_ids":{"type":"array","items":{"type":"integer"}},"archived":{"type":"boolean"},"created_by_id":{"type":"integer"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"definition":{"type":"string","description":"The flow graph (nodes and edges) for this version."}}}}},"example":{"payload":{"id":1,"name":"Sample Name","description":"A short description.","status":"draft","trigger_type":"","trigger_config":"sample trigger config","settings":"sample settings","published_version_id":1,"folder_id":1,"inbox_ids":[1],"physical_inbox_ids":[1],"physical_trigger_inbox_ids":[1],"archived":true,"created_by_id":1,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","definition":"sample definition"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"flow":{"type":"object","description":"The flow bundle to import.","properties":{"name":{"type":"string","example":"Imported flow"},"description":{"type":["string","null"],"example":"Welcome sequence"},"trigger_type":{"type":"string","enum":["trigger_conversation_created","trigger_conversation_opened","trigger_conversation_resolved","trigger_conversation_status_changed","trigger_first_reply","trigger_message_received","trigger_keyword","trigger_label_added","trigger_contact_created","trigger_contact_updated","trigger_contact_merged","trigger_api_called","trigger_webhook_received","trigger_scheduled","trigger_payment_charge","trigger_payment_subscription","trigger_payment_installment_plan","trigger_commerce","trigger_crm_item","trigger_task","trigger_order","trigger_contract","trigger_catalog","trigger_follow_up","trigger_engagement","trigger_sales","trigger_ads","trigger_organization","trigger_team","trigger_captain","trigger_campaign","trigger_media_library","trigger_organization_created","trigger_organization_updated","trigger_calendar_booking","trigger_calendar_event"],"example":"trigger_conversation_created"},"trigger_config":{"type":"object","additionalProperties":true,"example":{},"description":"Free-form trigger configuration; the key set depends on the trigger type."},"settings":{"type":"object","additionalProperties":true,"example":{},"description":"Free-form flow settings merged over the engine defaults."},"definition":{"type":"object","additionalProperties":true,"description":"The flow graph (nodes / edges).","example":{"nodes":[],"edges":[]}}}}}},"example":{"flow":{"name":"Imported flow","description":"Welcome sequence","trigger_type":"trigger_conversation_created","trigger_config":{},"settings":{},"definition":{"nodes":[],"edges":[]}}}}}}}},"/api/v1/accounts/{account_id}/flow_builder/flows/test_http_request":{"post":{"tags":["Flow Builder"],"operationId":"auto_post_api_v1_accounts_account_id_flow_builder_flows_test_http_request","summary":"Preview an HTTP request with operator sample variables","description":"Administrator-only live HTTP preview using sample variables and the runtime's guarded HTTP client. Requests can have external effects; a timeout is not evidence that the upstream did nothing. No automatic paid-request retry is performed. keep_body=false enables bounded response mapping at runtime. With response_attachment_path, pagination must be disabled and keep_body must be false. The selected strict Base64 PDF (or application/pdf Base64 data URI) is limited to 8 MiB decoded. response_attachment_filename is a safe PDF filename rendered from sample variables; response_attachment_variable names the runtime reference. In PDF preview mode body contains only attachment filename, content_type and byte_size, without Base64, blob_id or a persisted attachment. At runtime the reference is scoped to the account, session and conversation. The synchronous preview also respects its outer request budget, which may be shorter than the worker's configured timeout.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"HTTP status or a bounded validation/transport error; inspect payload.ok and payload.error.","content":{"application/json":{"schema":{"type":"object","required":["payload"],"properties":{"payload":{"type":"object","required":["status","ok","duration_ms","headers","body","items","pages","available_paths","error"],"properties":{"status":{"type":["integer","null"],"description":"Upstream HTTP status, or null on validation/transport failure."},"ok":{"type":"boolean"},"duration_ms":{"type":["number","null"]},"headers":{"type":"object","additionalProperties":true,"description":"Response headers returned by the HTTP client."},"body":{"description":"Parsed JSON or raw text in ordinary mode; null on a validation/transport error. PDF mode returns only an attachment metadata object, never Base64.","oneOf":[{"type":"object","additionalProperties":true,"description":"Upstream JSON object, or attachment metadata in PDF mode."},{"type":"array","items":{"type":["object","array","string","number","boolean","null"],"additionalProperties":true,"description":"An arbitrary upstream JSON value, including nested collections."}},{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"}]},"items":{"type":["array","null"],"items":{"type":["object","array","string","number","boolean","null"],"additionalProperties":true,"description":"An arbitrary upstream pagination item, including nested collections."},"description":"Aggregated sample for pagination; null for PDF mode and ordinary single requests."},"pages":{"type":"integer"},"available_paths":{"type":"array","items":{"type":"string"},"description":"Discovered dotted paths in the returned sample, not in an omitted PDF body."},"error":{"type":["object","null"],"properties":{"code":{"type":"string","description":"Validation or transport failure code."},"message":{"type":"string","description":"Human-readable failure message."}}}}}}},"example":{"payload":{"status":200,"ok":true,"duration_ms":3,"headers":{"content-type":"application/json"},"body":{"attachment":{"filename":"report.pdf","content_type":"application/pdf","byte_size":3028}},"items":null,"pages":1,"available_paths":["attachment.filename","attachment.content_type","attachment.byte_size"],"error":null}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"test":{"type":"object","properties":{"method":{"type":"string"},"url":{"type":"string"},"timeout_seconds":{"type":"integer"},"variable":{"type":"string"},"keep_body":{"type":"string"},"body_mode":{"type":"string","enum":["fields","raw"],"description":"How the HTTP request body is built (structured fields vs a raw templated string)."},"body_content_type":{"type":"string","enum":["json","text","form"],"description":"Encoding of the HTTP request body."},"response_attachment_path":{"type":"string"},"response_attachment_filename":{"type":"string"},"response_attachment_variable":{"type":"string"},"pagination_enabled":{"type":"boolean"},"pagination_mode":{"type":"string","enum":["cursor","page","offset","link_header"],"description":"How the HTTP request paginates across pages."},"pagination_items_path":{"type":"string"},"pagination_cursor_path":{"type":"string"},"pagination_next_url_path":{"type":"string"},"pagination_cursor_param":{"type":"string"},"pagination_page_param":{"type":"string"},"pagination_page_start":{"type":"string"},"pagination_offset_param":{"type":"string"},"pagination_limit_param":{"type":"string"},"pagination_page_size":{"type":"string"},"pagination_max_pages":{"type":"string"},"pagination_max_items":{"type":"string"},"headers":{"type":"object","additionalProperties":true,"description":"Free-form object."},"query":{"type":"object","additionalProperties":true,"description":"Free-form object."},"sample_variables":{"type":"object","additionalProperties":true,"description":"Free-form object."},"body_fields":{"type":"object","additionalProperties":true,"description":"Free-form object."}}}},"required":["test"]},"example":{"test":{"method":"sample method","url":"https://example.com/resource","timeout_seconds":60,"variable":"sample variable","keep_body":"sample keep body","body_mode":"fields","body_content_type":"json","response_attachment_path":"sample response attachment path","response_attachment_filename":"sample response attachment filename","response_attachment_variable":"sample response attachment variable","pagination_enabled":true,"pagination_mode":"cursor","pagination_items_path":"sample pagination items path","pagination_cursor_path":"sample pagination cursor path","pagination_next_url_path":"sample pagination next url path","pagination_cursor_param":"sample pagination cursor param","pagination_page_param":"sample pagination page param","pagination_page_start":"sample pagination page start","pagination_offset_param":"sample pagination offset param","pagination_limit_param":"sample pagination limit param","pagination_page_size":"sample pagination page size","pagination_max_pages":"sample pagination max pages","pagination_max_items":"sample pagination max items","headers":{},"query":{},"sample_variables":{},"body_fields":{}}}}}}}},"/api/v1/accounts/{account_id}/flow_builder/flows/bulk":{"post":{"tags":["Flow Builder"],"operationId":"auto_post_api_v1_accounts_account_id_flow_builder_flows_bulk","summary":"Apply a bulk action to several flows","description":"Runs one lifecycle action over a list of flows in a single call — the multi-select action of the flow list. Archiving also retires the flow; restoring returns it to published when it has a published version and to draft otherwise; activating republishes the flow; deactivating sends a published flow back to draft; moving assigns a destination folder. Flows that are not in a state the action applies to are skipped. On success the endpoint returns HTTP 200 with an EMPTY body — refetch the flow list to read the resulting states.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The action was applied to every eligible flow in the list. Empty body."},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"422":{"description":"The requested action is not one of the accepted values, or a flow failed validation while the action was applied."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"bulk_action":{"type":"string","description":"Lifecycle action applied to every flow in the list.","enum":["archive","restore","activate","deactivate","move_to_folder"]},"ids":{"type":"array","description":"Ids of the flows to act on. Ids outside the account are ignored.","items":{"type":"integer"}},"folder_id":{"type":"integer","description":"Destination folder, used only by the move action. Omit it or send it empty to move the flows back to the folder root. A folder outside the account is treated as the root."}},"required":["bulk_action","ids"]},"example":{"bulk_action":"move_to_folder","ids":[31,32],"folder_id":7}}}}}},"/api/v1/accounts/{account_id}/flow_builder/flows/templates":{"get":{"tags":["Flow Builder"],"operationId":"auto_get_api_v1_accounts_account_id_flow_builder_flows_templates","summary":"Templates flows","description":"Performs the templates operation on the targeted flow resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"string"}}},"example":{"payload":"sample payload"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/flow_builder/flows/{flow_id}/versions":{"post":{"tags":["Flow Builder"],"operationId":"auto_post_api_v1_accounts_account_id_flow_builder_flows_flow_id_versions","summary":"Create a flow draft version","description":"Validates and persists a new draft version of the flow (FlowBuilder::DraftSaveService). Returns the saved version; an invalid definition returns 422 with per-error details.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The saved flow version.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer","example":88},"flow_id":{"type":"integer","example":12},"version":{"type":"integer","example":3},"state":{"type":"string","enum":["draft","published"],"example":"draft"},"definition":{"type":"object","additionalProperties":true,"example":{"nodes":[],"edges":[]},"description":"The flow graph (nodes and edges) for this version."},"published_at":{"type":["string","null"],"format":"date-time","example":null},"created_at":{"type":"string","format":"date-time","example":"2026-01-15T10:30:00.000Z"},"updated_at":{"type":"string","format":"date-time","example":"2026-01-15T10:30:00.000Z"}}}}},"example":{"payload":{"id":88,"flow_id":12,"version":3,"state":"draft","definition":{"nodes":[],"edges":[]},"published_at":null,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"422":{"description":"Invalid flow definition.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"invalid_definition"},"details":{"type":"array","items":{"type":"string"},"example":["node start has no outgoing edge"]}}},"example":{"error":"invalid_definition","details":["node start has no outgoing edge"]}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"flow_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["definition"],"properties":{"definition":{"type":"object","additionalProperties":true,"description":"The flow graph (nodes / edges / node configs).","example":{"nodes":[],"edges":[]}}}},"example":{"definition":{"nodes":[],"edges":[]}}}}}}},"/api/v1/accounts/{account_id}/flow_builder/flows/{flow_id}/versions/{id}":{"get":{"tags":["Flow Builder"],"operationId":"auto_get_api_v1_accounts_account_id_flow_builder_flows_flow_id_versions_id","summary":"Get versions","description":"Returns the version identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"flow_id":{"type":"integer"},"version":{"type":"string"},"state":{"type":"string","enum":["draft","published"]},"definition":{"type":"string","description":"The flow graph (nodes and edges) for this version."},"runtime_version":{"type":"string"},"definition_schema_version":{"type":"string"},"manifest_version":{"type":"string"},"manifest_checksum":{"type":"string"},"definition_checksum":{"type":"string"},"revision":{"type":"string"},"published_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}},"example":{"payload":{"id":1,"flow_id":1,"version":"1.0.0","state":"draft","definition":"sample definition","runtime_version":"sample runtime version","definition_schema_version":"sample definition schema version","manifest_version":"sample manifest version","manifest_checksum":"sample manifest checksum","definition_checksum":"sample definition checksum","revision":"sample revision","published_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"flow_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/flow_builder/flows/{flow_id}/draft/validate":{"post":{"tags":["Flow Builder"],"operationId":"auto_post_api_v1_accounts_account_id_flow_builder_flows_flow_id_draft_validate","summary":"Compile and validate the current FlowBuilder draft","description":"Runs the v2 compiler plus Maestro readiness checks without executing any flow node.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Canonical validation result for the current draft revision.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["payload"],"properties":{"payload":{"type":"object","additionalProperties":false,"required":["valid","errors","revision","definition_checksum","manifest_version","manifest_checksum"],"properties":{"valid":{"type":"boolean"},"errors":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["code","node_id","edge_id","field","params","severity"],"properties":{"code":{"type":"string","description":"Stable machine-readable validation or conflict code."},"node_id":{"type":["string","null"],"description":"Canvas node that caused the issue","when applicable.":null},"edge_id":{"type":["string","null"],"description":"Canvas edge that caused the issue","when applicable.":null},"field":{"type":["string","null"],"description":"Definition or request field associated with the issue."},"params":{"type":"object","additionalProperties":true,"description":"Non-sensitive structured values used to explain or localize the issue."},"severity":{"type":"string","enum":["error","warning"]}}}},"revision":{"type":"integer","minimum":0},"definition_checksum":{"type":["string","null"]},"manifest_version":{"type":"string"},"manifest_checksum":{"type":"string","pattern":"^[a-f0-9]{64}$"}}}}},"example":{"payload":{"valid":true,"errors":[{"code":"sample code","node_id":"sample node id","edge_id":"sample edge id","field":"sample field","params":{},"severity":"error"}],"revision":1,"definition_checksum":"sample definition checksum","manifest_version":"sample manifest version","manifest_checksum":"sample manifest checksum"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"flow_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/flow_builder/flows/{flow_id}/draft":{"get":{"tags":["Flow Builder"],"operationId":"auto_get_api_v1_accounts_account_id_flow_builder_flows_flow_id_draft","summary":"Read the current optimistic FlowBuilder draft","description":"Returns the editable definition and an ETag response header used by every subsequent draft write.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Current draft, or a synthetic revision-zero projection when no draft row exists yet.","headers":{"ETag":{"schema":{"type":"string"},"description":"Optimistic draft revision token."},"Cache-Control":{"schema":{"type":"string","enum":["no-store"]}}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["payload"],"properties":{"payload":{"type":"object","additionalProperties":false,"required":["id","flow_id","state","revision","etag","definition","definition_checksum","updated_at"],"properties":{"id":{"type":["integer","null"]},"flow_id":{"type":"integer"},"state":{"type":"string","enum":["draft"]},"revision":{"type":"integer","minimum":0},"etag":{"type":"string","description":"Same optimistic revision token as the ETag response header. Mirrored into the body because cache-rewriting middleware and proxies can strip the header, which would strand every subsequent If-Match write."},"definition":{"type":"object","additionalProperties":false,"required":["nodes","edges"],"properties":{"nodes":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["id","type","data"],"properties":{"id":{"type":"string"},"type":{"type":"string"},"label":{"type":["string","null"]},"position":{"type":"object","additionalProperties":false,"properties":{"x":{"type":"number"},"y":{"type":"number"}}},"data":{"type":"object","additionalProperties":true,"description":"Manifest-schema-validated configuration for this node type; secrets are forbidden inline. Reply-wait nodes snapshot on_human_takeover; omitted means cancel for existing published flows.","properties":{"on_human_takeover":{"type":"string","enum":["cancel","keep"],"default":"cancel","description":"For wait_for_reply and wait_for_follow_up_reply only. Cancel the reply wait on an attributed human intervention, or keep waiting."}}}}}},"edges":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["id","source","target"],"properties":{"id":{"type":"string"},"source":{"type":"string"},"target":{"type":"string"},"sourceHandle":{"type":["string","null"]},"label":{"type":["string","null"]}}}}},"description":"The flow graph (nodes and edges) for this version."},"definition_checksum":{"type":"string","pattern":"^[a-f0-9]{64}$"},"updated_at":{"type":["string","null"],"format":"date-time"},"restored_from_version_id":{"type":"integer"}}}}},"example":{"payload":{"id":1,"flow_id":1,"state":"draft","revision":1,"etag":"sample etag","definition":{"nodes":[{"id":"sample id","type":"sample type","label":"sample label","position":{"x":12.5,"y":12.5},"data":{"on_human_takeover":"cancel"}}],"edges":[{"id":"sample id","source":"sample source","target":"sample target","sourceHandle":"sample sourceHandle","label":"sample label"}]},"definition_checksum":"sample definition checksum","updated_at":"2026-01-15T10:30:00.000Z","restored_from_version_id":1}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"flow_id","in":"path","required":true,"schema":{"type":"string"}}]},"patch":{"tags":["Flow Builder"],"operationId":"auto_patch_api_v1_accounts_account_id_flow_builder_flows_flow_id_draft","summary":"Save a FlowBuilder draft with optimistic concurrency","description":"Serializes the single draft writer and returns 409 instead of overwriting a newer revision.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Saved draft at its new revision.","headers":{"ETag":{"schema":{"type":"string"},"description":"New optimistic draft revision token."}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["payload"],"properties":{"payload":{"type":"object","additionalProperties":false,"required":["id","flow_id","state","revision","etag","definition","definition_checksum","updated_at"],"properties":{"id":{"type":["integer","null"]},"flow_id":{"type":"integer"},"state":{"type":"string","enum":["draft"]},"revision":{"type":"integer","minimum":0},"etag":{"type":"string","description":"Same optimistic revision token as the ETag response header. Mirrored into the body because cache-rewriting middleware and proxies can strip the header, which would strand every subsequent If-Match write."},"definition":{"type":"object","additionalProperties":false,"required":["nodes","edges"],"properties":{"nodes":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["id","type","data"],"properties":{"id":{"type":"string"},"type":{"type":"string"},"label":{"type":["string","null"]},"position":{"type":"object","additionalProperties":false,"properties":{"x":{"type":"number"},"y":{"type":"number"}}},"data":{"type":"object","additionalProperties":true,"description":"Manifest-schema-validated configuration for this node type; secrets are forbidden inline. Reply-wait nodes snapshot on_human_takeover; omitted means cancel for existing published flows.","properties":{"on_human_takeover":{"type":"string","enum":["cancel","keep"],"default":"cancel","description":"For wait_for_reply and wait_for_follow_up_reply only. Cancel the reply wait on an attributed human intervention, or keep waiting."}}}}}},"edges":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["id","source","target"],"properties":{"id":{"type":"string"},"source":{"type":"string"},"target":{"type":"string"},"sourceHandle":{"type":["string","null"]},"label":{"type":["string","null"]}}}}},"description":"The flow graph (nodes and edges) for this version."},"definition_checksum":{"type":"string","pattern":"^[a-f0-9]{64}$"},"updated_at":{"type":["string","null"],"format":"date-time"},"restored_from_version_id":{"type":"integer"}}}}},"example":{"payload":{"id":1,"flow_id":1,"state":"draft","revision":1,"etag":"sample etag","definition":{"nodes":[{"id":"sample id","type":"sample type","label":"sample label","position":{"x":12.5,"y":12.5},"data":{"on_human_takeover":"cancel"}}],"edges":[{"id":"sample id","source":"sample source","target":"sample target","sourceHandle":"sample sourceHandle","label":"sample label"}]},"definition_checksum":"sample definition checksum","updated_at":"2026-01-15T10:30:00.000Z","restored_from_version_id":1}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"409":{"description":"Another writer saved a newer draft revision.","content":{"application/json":{"schema":{"type":"object","required":["errors","etag"],"properties":{"errors":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["code","node_id","edge_id","field","params","severity"],"properties":{"code":{"type":"string","description":"Stable machine-readable validation or conflict code."},"node_id":{"type":["string","null"],"description":"Canvas node that caused the issue","when applicable.":null},"edge_id":{"type":["string","null"],"description":"Canvas edge that caused the issue","when applicable.":null},"field":{"type":["string","null"],"description":"Definition or request field associated with the issue."},"params":{"type":"object","additionalProperties":true,"description":"Non-sensitive structured values used to explain or localize the issue."},"severity":{"type":"string","enum":["error","warning"]}}}},"etag":{"type":"string","description":"Current draft revision token (also sent as the ETag header) so the editor can recover without an extra read."}}},"example":{"errors":[{"code":"sample code","node_id":"sample node id","edge_id":"sample edge id","field":"sample field","params":{},"severity":"error"}],"etag":"sample etag"}}}},"428":{"description":"The required If-Match precondition was omitted.","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["code","node_id","edge_id","field","params","severity"],"properties":{"code":{"type":"string","description":"Stable machine-readable validation or conflict code."},"node_id":{"type":["string","null"],"description":"Canvas node that caused the issue","when applicable.":null},"edge_id":{"type":["string","null"],"description":"Canvas edge that caused the issue","when applicable.":null},"field":{"type":["string","null"],"description":"Definition or request field associated with the issue."},"params":{"type":"object","additionalProperties":true,"description":"Non-sensitive structured values used to explain or localize the issue."},"severity":{"type":"string","enum":["error","warning"]}}}}}},"example":{"errors":[{"code":"sample code","node_id":"sample node id","edge_id":"sample edge id","field":"sample field","params":{},"severity":"error"}]}}}},"400":{"description":"The If-Match header was present but is not a revision token for this flow.","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["code","node_id","edge_id","field","params","severity"],"properties":{"code":{"type":"string","description":"Stable machine-readable validation or conflict code."},"node_id":{"type":["string","null"],"description":"Canvas node that caused the issue","when applicable.":null},"edge_id":{"type":["string","null"],"description":"Canvas edge that caused the issue","when applicable.":null},"field":{"type":["string","null"],"description":"Definition or request field associated with the issue."},"params":{"type":"object","additionalProperties":true,"description":"Non-sensitive structured values used to explain or localize the issue."},"severity":{"type":"string","enum":["error","warning"]}}}}}},"example":{"errors":[{"code":"sample code","node_id":"sample node id","edge_id":"sample edge id","field":"sample field","params":{},"severity":"error"}]}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"flow_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"If-Match","in":"header","required":true,"description":"ETag returned by the latest GET or PUT of this flow's draft.","schema":{"type":"string","pattern":"^\"flow-[0-9]+-draft-[0-9]+\"$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["definition"],"properties":{"definition":{"type":"object","additionalProperties":false,"required":["nodes","edges"],"properties":{"nodes":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["id","type","data"],"properties":{"id":{"type":"string"},"type":{"type":"string"},"label":{"type":["string","null"]},"position":{"type":"object","additionalProperties":false,"properties":{"x":{"type":"number"},"y":{"type":"number"}}},"data":{"type":"object","additionalProperties":true,"description":"Manifest-schema-validated configuration for this node type; secrets are forbidden inline. Reply-wait nodes snapshot on_human_takeover; omitted means cancel for existing published flows.","properties":{"on_human_takeover":{"type":"string","enum":["cancel","keep"],"default":"cancel","description":"For wait_for_reply and wait_for_follow_up_reply only. Cancel the reply wait on an attributed human intervention, or keep waiting."}}}}}},"edges":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["id","source","target"],"properties":{"id":{"type":"string"},"source":{"type":"string"},"target":{"type":"string"},"sourceHandle":{"type":["string","null"]},"label":{"type":["string","null"]}}}}},"description":"The flow graph (nodes and edges) for this version."}}},"example":{"definition":{"nodes":[{"id":"sample id","type":"sample type","label":"sample label","position":{"x":12.5,"y":12.5},"data":{"on_human_takeover":"cancel"}}],"edges":[{"id":"sample id","source":"sample source","target":"sample target","sourceHandle":"sample sourceHandle","label":"sample label"}]}}}}}},"put":{"tags":["Flow Builder"],"operationId":"auto_put_api_v1_accounts_account_id_flow_builder_flows_flow_id_draft","summary":"Save a FlowBuilder draft with optimistic concurrency","description":"Serializes the single draft writer and returns 409 instead of overwriting a newer revision.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Saved draft at its new revision.","headers":{"ETag":{"schema":{"type":"string"},"description":"New optimistic draft revision token."}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["payload"],"properties":{"payload":{"type":"object","additionalProperties":false,"required":["id","flow_id","state","revision","etag","definition","definition_checksum","updated_at"],"properties":{"id":{"type":["integer","null"]},"flow_id":{"type":"integer"},"state":{"type":"string","enum":["draft"]},"revision":{"type":"integer","minimum":0},"etag":{"type":"string","description":"Same optimistic revision token as the ETag response header. Mirrored into the body because cache-rewriting middleware and proxies can strip the header, which would strand every subsequent If-Match write."},"definition":{"type":"object","additionalProperties":false,"required":["nodes","edges"],"properties":{"nodes":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["id","type","data"],"properties":{"id":{"type":"string"},"type":{"type":"string"},"label":{"type":["string","null"]},"position":{"type":"object","additionalProperties":false,"properties":{"x":{"type":"number"},"y":{"type":"number"}}},"data":{"type":"object","additionalProperties":true,"description":"Manifest-schema-validated configuration for this node type; secrets are forbidden inline. Reply-wait nodes snapshot on_human_takeover; omitted means cancel for existing published flows.","properties":{"on_human_takeover":{"type":"string","enum":["cancel","keep"],"default":"cancel","description":"For wait_for_reply and wait_for_follow_up_reply only. Cancel the reply wait on an attributed human intervention, or keep waiting."}}}}}},"edges":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["id","source","target"],"properties":{"id":{"type":"string"},"source":{"type":"string"},"target":{"type":"string"},"sourceHandle":{"type":["string","null"]},"label":{"type":["string","null"]}}}}},"description":"The flow graph (nodes and edges) for this version."},"definition_checksum":{"type":"string","pattern":"^[a-f0-9]{64}$"},"updated_at":{"type":["string","null"],"format":"date-time"},"restored_from_version_id":{"type":"integer"}}}}},"example":{"payload":{"id":1,"flow_id":1,"state":"draft","revision":1,"etag":"sample etag","definition":{"nodes":[{"id":"sample id","type":"sample type","label":"sample label","position":{"x":12.5,"y":12.5},"data":{"on_human_takeover":"cancel"}}],"edges":[{"id":"sample id","source":"sample source","target":"sample target","sourceHandle":"sample sourceHandle","label":"sample label"}]},"definition_checksum":"sample definition checksum","updated_at":"2026-01-15T10:30:00.000Z","restored_from_version_id":1}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"409":{"description":"Another writer saved a newer draft revision.","content":{"application/json":{"schema":{"type":"object","required":["errors","etag"],"properties":{"errors":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["code","node_id","edge_id","field","params","severity"],"properties":{"code":{"type":"string","description":"Stable machine-readable validation or conflict code."},"node_id":{"type":["string","null"],"description":"Canvas node that caused the issue","when applicable.":null},"edge_id":{"type":["string","null"],"description":"Canvas edge that caused the issue","when applicable.":null},"field":{"type":["string","null"],"description":"Definition or request field associated with the issue."},"params":{"type":"object","additionalProperties":true,"description":"Non-sensitive structured values used to explain or localize the issue."},"severity":{"type":"string","enum":["error","warning"]}}}},"etag":{"type":"string","description":"Current draft revision token (also sent as the ETag header) so the editor can recover without an extra read."}}},"example":{"errors":[{"code":"sample code","node_id":"sample node id","edge_id":"sample edge id","field":"sample field","params":{},"severity":"error"}],"etag":"sample etag"}}}},"428":{"description":"The required If-Match precondition was omitted.","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["code","node_id","edge_id","field","params","severity"],"properties":{"code":{"type":"string","description":"Stable machine-readable validation or conflict code."},"node_id":{"type":["string","null"],"description":"Canvas node that caused the issue","when applicable.":null},"edge_id":{"type":["string","null"],"description":"Canvas edge that caused the issue","when applicable.":null},"field":{"type":["string","null"],"description":"Definition or request field associated with the issue."},"params":{"type":"object","additionalProperties":true,"description":"Non-sensitive structured values used to explain or localize the issue."},"severity":{"type":"string","enum":["error","warning"]}}}}}},"example":{"errors":[{"code":"sample code","node_id":"sample node id","edge_id":"sample edge id","field":"sample field","params":{},"severity":"error"}]}}}},"400":{"description":"The If-Match header was present but is not a revision token for this flow.","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["code","node_id","edge_id","field","params","severity"],"properties":{"code":{"type":"string","description":"Stable machine-readable validation or conflict code."},"node_id":{"type":["string","null"],"description":"Canvas node that caused the issue","when applicable.":null},"edge_id":{"type":["string","null"],"description":"Canvas edge that caused the issue","when applicable.":null},"field":{"type":["string","null"],"description":"Definition or request field associated with the issue."},"params":{"type":"object","additionalProperties":true,"description":"Non-sensitive structured values used to explain or localize the issue."},"severity":{"type":"string","enum":["error","warning"]}}}}}},"example":{"errors":[{"code":"sample code","node_id":"sample node id","edge_id":"sample edge id","field":"sample field","params":{},"severity":"error"}]}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"flow_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"If-Match","in":"header","required":true,"description":"ETag returned by the latest GET or PUT of this flow's draft.","schema":{"type":"string","pattern":"^\"flow-[0-9]+-draft-[0-9]+\"$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["definition"],"properties":{"definition":{"type":"object","additionalProperties":false,"required":["nodes","edges"],"properties":{"nodes":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["id","type","data"],"properties":{"id":{"type":"string"},"type":{"type":"string"},"label":{"type":["string","null"]},"position":{"type":"object","additionalProperties":false,"properties":{"x":{"type":"number"},"y":{"type":"number"}}},"data":{"type":"object","additionalProperties":true,"description":"Manifest-schema-validated configuration for this node type; secrets are forbidden inline. Reply-wait nodes snapshot on_human_takeover; omitted means cancel for existing published flows.","properties":{"on_human_takeover":{"type":"string","enum":["cancel","keep"],"default":"cancel","description":"For wait_for_reply and wait_for_follow_up_reply only. Cancel the reply wait on an attributed human intervention, or keep waiting."}}}}}},"edges":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["id","source","target"],"properties":{"id":{"type":"string"},"source":{"type":"string"},"target":{"type":"string"},"sourceHandle":{"type":["string","null"]},"label":{"type":["string","null"]}}}}},"description":"The flow graph (nodes and edges) for this version."}}},"example":{"definition":{"nodes":[{"id":"sample id","type":"sample type","label":"sample label","position":{"x":12.5,"y":12.5},"data":{"on_human_takeover":"cancel"}}],"edges":[{"id":"sample id","source":"sample source","target":"sample target","sourceHandle":"sample sourceHandle","label":"sample label"}]}}}}}}},"/api/v1/accounts/{account_id}/flow_builder/flows":{"get":{"tags":["Flow Builder"],"operationId":"auto_get_api_v1_accounts_account_id_flow_builder_flows","summary":"List flows","description":"Returns the list of flows visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Paginated list of automation flows.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":["string","null"]},"status":{"type":"string","enum":["draft","published","retired"],"description":"Lifecycle state of the flow."},"trigger_type":{"type":["string","null"],"enum":["trigger_conversation_created","trigger_conversation_opened","trigger_conversation_resolved","trigger_conversation_status_changed","trigger_first_reply","trigger_message_received","trigger_keyword","trigger_label_added","trigger_contact_created","trigger_contact_updated","trigger_contact_merged","trigger_api_called","trigger_webhook_received","trigger_scheduled","trigger_payment_charge","trigger_payment_subscription","trigger_payment_installment_plan","trigger_commerce","trigger_crm_item","trigger_task","trigger_order","trigger_contract","trigger_catalog","trigger_follow_up","trigger_engagement","trigger_sales","trigger_ads","trigger_organization","trigger_team","trigger_captain","trigger_campaign","trigger_media_library","trigger_organization_created","trigger_organization_updated","trigger_calendar_booking","trigger_calendar_event",null],"description":"Trigger node type that starts this flow (null on a draft with no trigger yet)."},"trigger_config":{"type":"object","additionalProperties":true,"description":"Trigger-specific configuration (e.g. keywords, schedule, webhook binding); shape depends on trigger_type."},"settings":{"type":"object","additionalProperties":true,"description":"Flow runtime settings merged over the engine defaults (e.g. max_steps_per_session)."},"published_version_id":{"type":["integer","null"]},"folder_id":{"type":["integer","null"]},"inbox_ids":{"type":"array","items":{"type":"integer"},"description":"Inboxes this flow is bound to."},"archived":{"type":"boolean"},"created_by_id":{"type":["integer","null"]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}},"meta":{"type":"object","properties":{"current_page":{"type":"integer"},"total_count":{"type":"integer"}}}}},"example":{"payload":[{"id":1,"name":"Sample Name","description":"A short description.","status":"draft","trigger_type":"trigger_conversation_created","trigger_config":{},"settings":{},"published_version_id":1,"folder_id":1,"inbox_ids":[1],"archived":true,"created_by_id":1,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}],"meta":{"current_page":1,"total_count":5}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."}]},"post":{"tags":["Flow Builder"],"operationId":"auto_post_api_v1_accounts_account_id_flow_builder_flows","summary":"Create flows","description":"Creates a new flow from the request payload. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"201":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"status":{"type":"string","enum":["draft","published","retired"]},"trigger_type":{"type":"string","enum":["","trigger_conversation_created","trigger_conversation_opened","trigger_conversation_resolved","trigger_conversation_status_changed","trigger_first_reply","trigger_message_received","trigger_keyword","trigger_label_added","trigger_contact_created","trigger_contact_updated","trigger_contact_merged","trigger_api_called","trigger_webhook_received","trigger_scheduled","trigger_payment_charge","trigger_payment_subscription","trigger_payment_installment_plan","trigger_commerce","trigger_crm_item","trigger_task","trigger_order","trigger_contract","trigger_catalog","trigger_follow_up","trigger_engagement","trigger_sales","trigger_ads","trigger_organization","trigger_team","trigger_captain","trigger_campaign","trigger_media_library","trigger_organization_created","trigger_organization_updated","trigger_calendar_booking","trigger_whatsapp_flow_response","trigger_calendar_event"]},"trigger_config":{"type":"string","description":"Free-form trigger configuration; the key set depends on the trigger type."},"settings":{"type":"string","description":"Free-form flow settings merged over the engine defaults."},"published_version_id":{"type":"integer"},"folder_id":{"type":"integer"},"inbox_ids":{"type":"array","items":{"type":"integer"}},"physical_inbox_ids":{"type":"array","items":{"type":"integer"}},"physical_trigger_inbox_ids":{"type":"array","items":{"type":"integer"}},"archived":{"type":"boolean"},"created_by_id":{"type":"integer"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"definition":{"type":"string","description":"The flow graph (nodes and edges) for this version."}}}}},"example":{"payload":{"id":1,"name":"Sample Name","description":"A short description.","status":"draft","trigger_type":"","trigger_config":"sample trigger config","settings":"sample settings","published_version_id":1,"folder_id":1,"inbox_ids":[1],"physical_inbox_ids":[1],"physical_trigger_inbox_ids":[1],"archived":true,"created_by_id":1,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","definition":"sample definition"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"flow":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"status":{"type":"string","enum":["draft","published","retired"]},"trigger_type":{"type":"string","enum":["","trigger_conversation_created","trigger_conversation_opened","trigger_conversation_resolved","trigger_conversation_status_changed","trigger_first_reply","trigger_message_received","trigger_keyword","trigger_label_added","trigger_contact_created","trigger_contact_updated","trigger_contact_merged","trigger_api_called","trigger_webhook_received","trigger_scheduled","trigger_payment_charge","trigger_payment_subscription","trigger_payment_installment_plan","trigger_commerce","trigger_crm_item","trigger_task","trigger_order","trigger_contract","trigger_catalog","trigger_follow_up","trigger_engagement","trigger_sales","trigger_ads","trigger_organization","trigger_team","trigger_captain","trigger_campaign","trigger_media_library","trigger_organization_created","trigger_organization_updated","trigger_calendar_booking","trigger_whatsapp_flow_response","trigger_calendar_event"]},"folder_id":{"type":"integer"},"trigger_config":{"type":"object","additionalProperties":true,"description":"Free-form trigger configuration; the key set depends on the trigger type."},"settings":{"type":"object","additionalProperties":true,"description":"Free-form flow settings merged over the engine defaults."}}},"template_key":{"type":"string"},"inbox_ids":{"type":"array","items":{"type":"integer"}}},"required":["flow"]},"example":{"flow":{"name":"Sample Name","description":"A short description.","status":"draft","trigger_type":"","folder_id":1,"trigger_config":{},"settings":{}},"template_key":"sample-token","inbox_ids":[1]}}}}}},"/api/v1/accounts/{account_id}/flow_builder/flows/{id}":{"get":{"tags":["Flow Builder"],"operationId":"auto_get_api_v1_accounts_account_id_flow_builder_flows_id","summary":"Get flows","description":"Returns the flow identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"status":{"type":"string","enum":["draft","published","retired"]},"trigger_type":{"type":"string","enum":["","trigger_conversation_created","trigger_conversation_opened","trigger_conversation_resolved","trigger_conversation_status_changed","trigger_first_reply","trigger_message_received","trigger_keyword","trigger_label_added","trigger_contact_created","trigger_contact_updated","trigger_contact_merged","trigger_api_called","trigger_webhook_received","trigger_scheduled","trigger_payment_charge","trigger_payment_subscription","trigger_payment_installment_plan","trigger_commerce","trigger_crm_item","trigger_task","trigger_order","trigger_contract","trigger_catalog","trigger_follow_up","trigger_engagement","trigger_sales","trigger_ads","trigger_organization","trigger_team","trigger_captain","trigger_campaign","trigger_media_library","trigger_organization_created","trigger_organization_updated","trigger_calendar_booking","trigger_whatsapp_flow_response","trigger_calendar_event"]},"trigger_config":{"type":"string","description":"Free-form trigger configuration; the key set depends on the trigger type."},"settings":{"type":"string","description":"Free-form flow settings merged over the engine defaults."},"published_version_id":{"type":"integer"},"folder_id":{"type":"integer"},"inbox_ids":{"type":"array","items":{"type":"integer"}},"physical_inbox_ids":{"type":"array","items":{"type":"integer"}},"physical_trigger_inbox_ids":{"type":"array","items":{"type":"integer"}},"archived":{"type":"boolean"},"created_by_id":{"type":"integer"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"definition":{"type":"string","description":"The flow graph (nodes and edges) for this version."}}}}},"example":{"payload":{"id":1,"name":"Sample Name","description":"A short description.","status":"draft","trigger_type":"","trigger_config":"sample trigger config","settings":"sample settings","published_version_id":1,"folder_id":1,"inbox_ids":[1],"physical_inbox_ids":[1],"physical_trigger_inbox_ids":[1],"archived":true,"created_by_id":1,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","definition":"sample definition"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]},"patch":{"tags":["Flow Builder"],"operationId":"auto_patch_api_v1_accounts_account_id_flow_builder_flows_id","summary":"Update a FlowBuilder flow","description":"Updates mutable flow metadata, bindings and trigger/runtime configuration. Publishing goes through the same validated lifecycle as the explicit publish action; retiring must use the archive endpoint.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"status":{"type":"string","enum":["draft","published","retired"]},"trigger_type":{"type":"string","enum":["","trigger_conversation_created","trigger_conversation_opened","trigger_conversation_resolved","trigger_conversation_status_changed","trigger_first_reply","trigger_message_received","trigger_keyword","trigger_label_added","trigger_contact_created","trigger_contact_updated","trigger_contact_merged","trigger_api_called","trigger_webhook_received","trigger_scheduled","trigger_payment_charge","trigger_payment_subscription","trigger_payment_installment_plan","trigger_commerce","trigger_crm_item","trigger_task","trigger_order","trigger_contract","trigger_catalog","trigger_follow_up","trigger_engagement","trigger_sales","trigger_ads","trigger_organization","trigger_team","trigger_captain","trigger_campaign","trigger_media_library","trigger_organization_created","trigger_organization_updated","trigger_calendar_booking","trigger_whatsapp_flow_response","trigger_calendar_event"]},"trigger_config":{"type":"string","description":"Free-form trigger configuration; the key set depends on the trigger type."},"settings":{"type":"string","description":"Free-form flow settings merged over the engine defaults."},"published_version_id":{"type":"integer"},"folder_id":{"type":"integer"},"inbox_ids":{"type":"array","items":{"type":"integer"}},"physical_inbox_ids":{"type":"array","items":{"type":"integer"}},"physical_trigger_inbox_ids":{"type":"array","items":{"type":"integer"}},"archived":{"type":"boolean"},"created_by_id":{"type":"integer"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"definition":{"type":"string","description":"The flow graph (nodes and edges) for this version."}}}}},"example":{"payload":{"id":1,"name":"Sample Name","description":"A short description.","status":"draft","trigger_type":"","trigger_config":"sample trigger config","settings":"sample settings","published_version_id":1,"folder_id":1,"inbox_ids":[1],"physical_inbox_ids":[1],"physical_trigger_inbox_ids":[1],"archived":true,"created_by_id":1,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","definition":"sample definition"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["flow"],"properties":{"flow":{"type":"object","additionalProperties":false,"properties":{"name":{"type":"string","minLength":1},"description":{"type":["string","null"]},"status":{"type":"string","enum":["draft","published"],"description":"Use the explicit archive endpoint to retire a flow; this write only saves a draft or publishes it."},"trigger_type":{"type":"string","enum":["trigger_conversation_created","trigger_conversation_opened","trigger_conversation_resolved","trigger_conversation_status_changed","trigger_first_reply","trigger_message_received","trigger_keyword","trigger_label_added","trigger_contact_created","trigger_contact_updated","trigger_contact_merged","trigger_api_called","trigger_webhook_received","trigger_scheduled","trigger_payment_charge","trigger_payment_subscription","trigger_payment_installment_plan","trigger_commerce","trigger_crm_item","trigger_task","trigger_order","trigger_contract","trigger_catalog","trigger_follow_up","trigger_engagement","trigger_sales","trigger_ads","trigger_organization","trigger_team","trigger_captain","trigger_campaign","trigger_media_library","trigger_organization_created","trigger_organization_updated","trigger_calendar_booking","trigger_calendar_event"],"description":"Trigger node type registered by the server-owned FlowBuilder manifest."},"folder_id":{"type":["integer","null"]},"trigger_config":{"type":"object","additionalProperties":true,"description":"Trigger-specific configuration restored against redacted stored values by the server."},"settings":{"type":"object","additionalProperties":true,"description":"Flow runtime settings restored against redacted stored values by the server."}}},"inbox_ids":{"type":"array","uniqueItems":true,"description":"Account inboxes to bind. Hybrid logical inboxes are expanded server-side to their equivalent physical inboxes.","items":{"type":"integer"}}}},"example":{"flow":{"name":"Sample Name","description":"A short description.","status":"draft","trigger_type":"trigger_conversation_created","folder_id":1,"trigger_config":{},"settings":{}},"inbox_ids":[1]}}}}},"put":{"tags":["Flow Builder"],"operationId":"auto_put_api_v1_accounts_account_id_flow_builder_flows_id","summary":"Update a FlowBuilder flow","description":"Updates mutable flow metadata, bindings and trigger/runtime configuration. Publishing goes through the same validated lifecycle as the explicit publish action; retiring must use the archive endpoint.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"status":{"type":"string","enum":["draft","published","retired"]},"trigger_type":{"type":"string","enum":["","trigger_conversation_created","trigger_conversation_opened","trigger_conversation_resolved","trigger_conversation_status_changed","trigger_first_reply","trigger_message_received","trigger_keyword","trigger_label_added","trigger_contact_created","trigger_contact_updated","trigger_contact_merged","trigger_api_called","trigger_webhook_received","trigger_scheduled","trigger_payment_charge","trigger_payment_subscription","trigger_payment_installment_plan","trigger_commerce","trigger_crm_item","trigger_task","trigger_order","trigger_contract","trigger_catalog","trigger_follow_up","trigger_engagement","trigger_sales","trigger_ads","trigger_organization","trigger_team","trigger_captain","trigger_campaign","trigger_media_library","trigger_organization_created","trigger_organization_updated","trigger_calendar_booking","trigger_whatsapp_flow_response","trigger_calendar_event"]},"trigger_config":{"type":"string","description":"Free-form trigger configuration; the key set depends on the trigger type."},"settings":{"type":"string","description":"Free-form flow settings merged over the engine defaults."},"published_version_id":{"type":"integer"},"folder_id":{"type":"integer"},"inbox_ids":{"type":"array","items":{"type":"integer"}},"physical_inbox_ids":{"type":"array","items":{"type":"integer"}},"physical_trigger_inbox_ids":{"type":"array","items":{"type":"integer"}},"archived":{"type":"boolean"},"created_by_id":{"type":"integer"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"definition":{"type":"string","description":"The flow graph (nodes and edges) for this version."}}}}},"example":{"payload":{"id":1,"name":"Sample Name","description":"A short description.","status":"draft","trigger_type":"","trigger_config":"sample trigger config","settings":"sample settings","published_version_id":1,"folder_id":1,"inbox_ids":[1],"physical_inbox_ids":[1],"physical_trigger_inbox_ids":[1],"archived":true,"created_by_id":1,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","definition":"sample definition"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["flow"],"properties":{"flow":{"type":"object","additionalProperties":false,"properties":{"name":{"type":"string","minLength":1},"description":{"type":["string","null"]},"status":{"type":"string","enum":["draft","published"],"description":"Use the explicit archive endpoint to retire a flow; this write only saves a draft or publishes it."},"trigger_type":{"type":"string","enum":["trigger_conversation_created","trigger_conversation_opened","trigger_conversation_resolved","trigger_conversation_status_changed","trigger_first_reply","trigger_message_received","trigger_keyword","trigger_label_added","trigger_contact_created","trigger_contact_updated","trigger_contact_merged","trigger_api_called","trigger_webhook_received","trigger_scheduled","trigger_payment_charge","trigger_payment_subscription","trigger_payment_installment_plan","trigger_commerce","trigger_crm_item","trigger_task","trigger_order","trigger_contract","trigger_catalog","trigger_follow_up","trigger_engagement","trigger_sales","trigger_ads","trigger_organization","trigger_team","trigger_captain","trigger_campaign","trigger_media_library","trigger_organization_created","trigger_organization_updated","trigger_calendar_booking","trigger_calendar_event"],"description":"Trigger node type registered by the server-owned FlowBuilder manifest."},"folder_id":{"type":["integer","null"]},"trigger_config":{"type":"object","additionalProperties":true,"description":"Trigger-specific configuration restored against redacted stored values by the server."},"settings":{"type":"object","additionalProperties":true,"description":"Flow runtime settings restored against redacted stored values by the server."}}},"inbox_ids":{"type":"array","uniqueItems":true,"description":"Account inboxes to bind. Hybrid logical inboxes are expanded server-side to their equivalent physical inboxes.","items":{"type":"integer"}}}},"example":{"flow":{"name":"Sample Name","description":"A short description.","status":"draft","trigger_type":"trigger_conversation_created","folder_id":1,"trigger_config":{},"settings":{}},"inbox_ids":[1]}}}}},"delete":{"tags":["Flow Builder"],"operationId":"auto_delete_api_v1_accounts_account_id_flow_builder_flows_id","summary":"Delete flows","description":"Deletes the flow identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Success (no content)"},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/flow_builder/folders":{"get":{"tags":["Flow Builder"],"operationId":"auto_get_api_v1_accounts_account_id_flow_builder_folders","summary":"List folders","description":"Returns the list of folders visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"List of flow folders.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"position":{"type":"integer"},"flows_count":{"type":"integer"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}}},"example":{"payload":[{"id":1,"name":"Sample Name","position":1,"flows_count":5,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."}]},"post":{"tags":["Flow Builder"],"operationId":"auto_post_api_v1_accounts_account_id_flow_builder_folders","summary":"Create folders","description":"Creates a new folder from the request payload. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"201":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"position":{"type":"integer"},"flows_count":{"type":"integer"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}},"example":{"payload":{"id":1,"name":"Sample Name","position":1,"flows_count":5,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"folder":{"type":"object","properties":{"name":{"type":"string"},"position":{"type":"integer"}},"required":["name"]}},"required":["folder"]},"example":{"folder":{"name":"Sample Name","position":1}}}}}}},"/api/v1/accounts/{account_id}/flow_builder/folders/{id}":{"patch":{"tags":["Flow Builder"],"operationId":"auto_patch_api_v1_accounts_account_id_flow_builder_folders_id","summary":"Update folders","description":"Updates the folder identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"position":{"type":"integer"},"flows_count":{"type":"integer"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}},"example":{"payload":{"id":1,"name":"Sample Name","position":1,"flows_count":5,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"folder":{"type":"object","properties":{"name":{"type":"string"},"position":{"type":"integer"}}}},"required":["folder"]},"example":{"folder":{"name":"Sample Name","position":1}}}}}},"put":{"tags":["Flow Builder"],"operationId":"auto_put_api_v1_accounts_account_id_flow_builder_folders_id","summary":"Update folders","description":"Updates the folder identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"position":{"type":"integer"},"flows_count":{"type":"integer"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}},"example":{"payload":{"id":1,"name":"Sample Name","position":1,"flows_count":5,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"folder":{"type":"object","properties":{"name":{"type":"string"},"position":{"type":"integer"}}}},"required":["folder"]},"example":{"folder":{"name":"Sample Name","position":1}}}}}},"delete":{"tags":["Flow Builder"],"operationId":"auto_delete_api_v1_accounts_account_id_flow_builder_folders_id","summary":"Delete folders","description":"Deletes the folder identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Success (no content)"},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/flow_builder/database_connections/{id}/test":{"post":{"tags":["Flow Builder"],"operationId":"auto_post_api_v1_accounts_account_id_flow_builder_database_connections_id_test","summary":"Test database connections","description":"Performs the test operation on the targeted database connection resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"string"}}},"example":{"payload":"sample payload"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/flow_builder/database_connections/test_query":{"post":{"tags":["Flow Builder"],"operationId":"auto_post_api_v1_accounts_account_id_flow_builder_database_connections_test_query","summary":"Test a Flow Builder database query","description":"Executes the supplied query against the saved (kept) database connection with sample bind params and a capped row limit, resolving {{variables}} via sample values. Returns the query result payload.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"string"}}},"example":{"payload":"sample payload"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string","description":"The SQL/query template to test.","example":"SELECT id, name FROM users WHERE email = {{email}} LIMIT 5"},"params":{"type":"array","items":{"type":"string"},"description":"Positional bind params (coerced to strings).","example":[]},"sample_variables":{"type":"object","additionalProperties":true,"description":"Sample values used to render {{variable}} placeholders.","example":{"email":"jane@example.com"}},"row_limit":{"type":"integer","description":"Max rows to return (default 50, capped at 200).","example":50}}},"example":{"query":"SELECT id, name FROM users WHERE email = {{email}} LIMIT 5","params":[],"sample_variables":{"email":"jane@example.com"},"row_limit":50}}}}}},"/api/v1/accounts/{account_id}/flow_builder/database_connections/query_templates":{"get":{"tags":["Flow Builder"],"operationId":"auto_get_api_v1_accounts_account_id_flow_builder_database_connections_query_templates","summary":"Query templates database connections","description":"Performs the query templates operation on the targeted database connection resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"string"}}},"example":{"payload":"sample payload"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"adapter","in":"query","required":false,"description":"Database engine the sample queries are rendered for. An unknown value falls back to PostgreSQL.","schema":{"type":"string","enum":["postgresql","mysql2","sqlserver"]},"example":"postgresql"}]}},"/api/v1/accounts/{account_id}/flow_builder/database_connections":{"get":{"tags":["Flow Builder"],"operationId":"auto_get_api_v1_accounts_account_id_flow_builder_database_connections","summary":"List database connections","description":"Returns the list of database connections visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"List of external database connections (passwords are write-only).","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"adapter":{"type":"string","enum":["postgresql","mysql2","sqlserver"],"description":"Database driver."},"host":{"type":"string"},"port":{"type":["integer","null"]},"database":{"type":"string"},"username":{"type":["string","null"]},"options":{"type":"object","additionalProperties":true,"description":"TLS/timeout knobs passed to the adapter; nil values fall back to adapter defaults."},"pool_size":{"type":"integer"},"checkout_timeout_ms":{"type":"integer"},"statement_timeout_ms":{"type":"integer"},"default_row_limit":{"type":"integer"},"has_password":{"type":"boolean","description":"Whether a password is configured (the secret itself is never returned)."},"adapter_available":{"type":"boolean","description":"Whether the adapter's driver gem is installed in this deployment."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}}},"example":{"payload":[{"id":1,"name":"Sample Name","adapter":"postgresql","host":"sample host","port":1,"database":"sample database","username":"sample username","options":{},"pool_size":1,"checkout_timeout_ms":1,"statement_timeout_ms":1,"default_row_limit":1,"has_password":true,"adapter_available":true,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."}]},"post":{"tags":["Flow Builder"],"operationId":"auto_post_api_v1_accounts_account_id_flow_builder_database_connections","summary":"Create database connections","description":"Creates a new database connection from the request payload. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"201":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"adapter":{"type":"string","enum":["postgresql","mysql2","sqlserver"]},"host":{"type":"string"},"port":{"type":"string"},"database":{"type":"string"},"username":{"type":"string"},"options":{"type":"string"},"pool_size":{"type":"string"},"checkout_timeout_ms":{"type":"string"},"statement_timeout_ms":{"type":"string"},"default_row_limit":{"type":"string"},"has_password":{"type":"boolean"},"adapter_available":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}},"example":{"payload":{"id":1,"name":"Sample Name","adapter":"postgresql","host":"sample host","port":"sample port","database":"sample database","username":"sample username","options":"sample options","pool_size":"sample pool size","checkout_timeout_ms":"sample checkout timeout ms","statement_timeout_ms":"sample statement timeout ms","default_row_limit":"sample default row limit","has_password":true,"adapter_available":true,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"database_connection":{"type":"object","properties":{"name":{"type":"string"},"adapter":{"type":"string","enum":["postgresql","mysql2","sqlserver"]},"host":{"type":"string"},"port":{"type":"string"},"database":{"type":"string"},"username":{"type":"string"},"password":{"type":"string"},"pool_size":{"type":"string"},"checkout_timeout_ms":{"type":"string"},"statement_timeout_ms":{"type":"string"},"default_row_limit":{"type":"string"},"options":{"type":"object","additionalProperties":true,"description":"Free-form object."}}}},"required":["database_connection"]},"example":{"database_connection":{"name":"Sample Name","adapter":"postgresql","host":"sample host","port":"sample port","database":"sample database","username":"sample username","password":"sample-password","pool_size":"sample pool size","checkout_timeout_ms":"sample checkout timeout ms","statement_timeout_ms":"sample statement timeout ms","default_row_limit":"sample default row limit","options":{}}}}}}}},"/api/v1/accounts/{account_id}/flow_builder/database_connections/{id}":{"get":{"tags":["Flow Builder"],"operationId":"auto_get_api_v1_accounts_account_id_flow_builder_database_connections_id","summary":"Get database connections","description":"Returns the database connection identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"adapter":{"type":"string","enum":["postgresql","mysql2","sqlserver"]},"host":{"type":"string"},"port":{"type":"string"},"database":{"type":"string"},"username":{"type":"string"},"options":{"type":"string"},"pool_size":{"type":"string"},"checkout_timeout_ms":{"type":"string"},"statement_timeout_ms":{"type":"string"},"default_row_limit":{"type":"string"},"has_password":{"type":"boolean"},"adapter_available":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}},"example":{"payload":{"id":1,"name":"Sample Name","adapter":"postgresql","host":"sample host","port":"sample port","database":"sample database","username":"sample username","options":"sample options","pool_size":"sample pool size","checkout_timeout_ms":"sample checkout timeout ms","statement_timeout_ms":"sample statement timeout ms","default_row_limit":"sample default row limit","has_password":true,"adapter_available":true,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]},"patch":{"tags":["Flow Builder"],"operationId":"auto_patch_api_v1_accounts_account_id_flow_builder_database_connections_id","summary":"Update database connections","description":"Updates the database connection identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"adapter":{"type":"string","enum":["postgresql","mysql2","sqlserver"]},"host":{"type":"string"},"port":{"type":"string"},"database":{"type":"string"},"username":{"type":"string"},"options":{"type":"string"},"pool_size":{"type":"string"},"checkout_timeout_ms":{"type":"string"},"statement_timeout_ms":{"type":"string"},"default_row_limit":{"type":"string"},"has_password":{"type":"boolean"},"adapter_available":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}},"example":{"payload":{"id":1,"name":"Sample Name","adapter":"postgresql","host":"sample host","port":"sample port","database":"sample database","username":"sample username","options":"sample options","pool_size":"sample pool size","checkout_timeout_ms":"sample checkout timeout ms","statement_timeout_ms":"sample statement timeout ms","default_row_limit":"sample default row limit","has_password":true,"adapter_available":true,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"database_connection":{"type":"object","properties":{"name":{"type":"string"},"adapter":{"type":"string","enum":["postgresql","mysql2","sqlserver"]},"host":{"type":"string"},"port":{"type":"string"},"database":{"type":"string"},"username":{"type":"string"},"password":{"type":"string"},"pool_size":{"type":"string"},"checkout_timeout_ms":{"type":"string"},"statement_timeout_ms":{"type":"string"},"default_row_limit":{"type":"string"},"options":{"type":"object","additionalProperties":true,"description":"Free-form object."}}}},"required":["database_connection"]},"example":{"database_connection":{"name":"Sample Name","adapter":"postgresql","host":"sample host","port":"sample port","database":"sample database","username":"sample username","password":"sample-password","pool_size":"sample pool size","checkout_timeout_ms":"sample checkout timeout ms","statement_timeout_ms":"sample statement timeout ms","default_row_limit":"sample default row limit","options":{}}}}}}},"put":{"tags":["Flow Builder"],"operationId":"auto_put_api_v1_accounts_account_id_flow_builder_database_connections_id","summary":"Update database connections","description":"Updates the database connection identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"adapter":{"type":"string","enum":["postgresql","mysql2","sqlserver"]},"host":{"type":"string"},"port":{"type":"string"},"database":{"type":"string"},"username":{"type":"string"},"options":{"type":"string"},"pool_size":{"type":"string"},"checkout_timeout_ms":{"type":"string"},"statement_timeout_ms":{"type":"string"},"default_row_limit":{"type":"string"},"has_password":{"type":"boolean"},"adapter_available":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}},"example":{"payload":{"id":1,"name":"Sample Name","adapter":"postgresql","host":"sample host","port":"sample port","database":"sample database","username":"sample username","options":"sample options","pool_size":"sample pool size","checkout_timeout_ms":"sample checkout timeout ms","statement_timeout_ms":"sample statement timeout ms","default_row_limit":"sample default row limit","has_password":true,"adapter_available":true,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"database_connection":{"type":"object","properties":{"name":{"type":"string"},"adapter":{"type":"string","enum":["postgresql","mysql2","sqlserver"]},"host":{"type":"string"},"port":{"type":"string"},"database":{"type":"string"},"username":{"type":"string"},"password":{"type":"string"},"pool_size":{"type":"string"},"checkout_timeout_ms":{"type":"string"},"statement_timeout_ms":{"type":"string"},"default_row_limit":{"type":"string"},"options":{"type":"object","additionalProperties":true,"description":"Free-form object."}}}},"required":["database_connection"]},"example":{"database_connection":{"name":"Sample Name","adapter":"postgresql","host":"sample host","port":"sample port","database":"sample database","username":"sample username","password":"sample-password","pool_size":"sample pool size","checkout_timeout_ms":"sample checkout timeout ms","statement_timeout_ms":"sample statement timeout ms","default_row_limit":"sample default row limit","options":{}}}}}}},"delete":{"tags":["Flow Builder"],"operationId":"auto_delete_api_v1_accounts_account_id_flow_builder_database_connections_id","summary":"Delete database connections","description":"Deletes the database connection identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Success (no content)"},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/flow_builder/credentials/{id}/rotate":{"post":{"tags":["Flow Builder"],"operationId":"auto_post_api_v1_accounts_account_id_flow_builder_credentials_id_rotate","summary":"Rotate credentials","description":"Performs the rotate operation on the targeted credential resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Sanitized credential metadata after rotation, optionally with a one-time reveal token.","content":{"application/json":{"schema":{"type":"object","required":["payload"],"properties":{"payload":{"type":"object","required":["id","credential_ref","name","kind","revision","has_secret","created_at","updated_at"],"properties":{"id":{"type":"integer"},"credential_ref":{"type":"string","pattern":"^flow_credential:[0-9]+$","description":"Opaque account-scoped reference stored in a flow definition."},"name":{"type":"string"},"kind":{"type":"string","enum":["http_auth","webhook_signing","oauth2"]},"revision":{"type":"integer","minimum":1},"rotated_at":{"type":["string","null"],"format":"date-time"},"has_secret":{"type":"boolean","description":"Whether encrypted secret material exists; the value itself is never returned here."},"reveal_token":{"type":"string","description":"Short-lived one-time token returned only when the server generated new secret material."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}},"example":{"payload":{"id":1,"credential_ref":"sample credential ref","name":"Sample Name","kind":"http_auth","revision":1,"rotated_at":"2026-01-15T10:30:00.000Z","has_secret":true,"reveal_token":"sample-token","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["credential"],"additionalProperties":false,"properties":{"credential":{"type":"object","additionalProperties":false,"properties":{"generate":{"type":"boolean","description":"Generate replacement material server-side and return a short-lived reveal token."},"secrets":{"type":"object","additionalProperties":false,"description":"Write-only credential material; accepted keys depend on the selected credential kind.","properties":{"authorization":{"type":"string","writeOnly":true},"api_key":{"type":"string","writeOnly":true},"token":{"type":"string","writeOnly":true},"secret":{"type":"string","writeOnly":true},"username":{"type":"string","writeOnly":true},"password":{"type":"string","writeOnly":true},"client_id":{"type":"string","writeOnly":true},"client_secret":{"type":"string","writeOnly":true},"access_token":{"type":"string","writeOnly":true},"refresh_token":{"type":"string","writeOnly":true},"token_url":{"type":"string","format":"uri","writeOnly":true},"scope":{"type":"string","writeOnly":true},"audience":{"type":"string","writeOnly":true},"grant_type":{"type":"string","enum":["client_credentials","refresh_token"],"writeOnly":true},"auth_method":{"type":"string","enum":["client_secret_basic","client_secret_post","none"],"writeOnly":true},"headers":{"type":"object","writeOnly":true,"additionalProperties":{"type":"string"},"description":"Bounded HTTP header map held only in the encrypted vault."}}}}}}},"example":{"credential":{"generate":true,"secrets":{"authorization":"sample authorization","api_key":"sample-token","token":"sample-token","secret":"sample-token","username":"sample username","password":"sample-password","client_id":"sample client id","client_secret":"sample-token","access_token":"sample-token","refresh_token":"sample-token","token_url":"https://example.com/resource","scope":"sample scope","audience":"sample audience","grant_type":"client_credentials","auth_method":"client_secret_basic","headers":{}}}}}}}}},"/api/v1/accounts/{account_id}/flow_builder/credentials/{id}/reveal":{"post":{"tags":["Flow Builder"],"operationId":"auto_post_api_v1_accounts_account_id_flow_builder_credentials_id_reveal","summary":"Reveal credentials","description":"Performs the reveal operation on the targeted credential resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"One-time secret reveal. A second use of the same token fails with 422.","content":{"application/json":{"schema":{"type":"object","required":["payload"],"properties":{"payload":{"type":"object","required":["secrets"],"properties":{"secrets":{"type":"object","additionalProperties":false,"description":"Write-only credential material; accepted keys depend on the selected credential kind.","properties":{"authorization":{"type":"string","writeOnly":true},"api_key":{"type":"string","writeOnly":true},"token":{"type":"string","writeOnly":true},"secret":{"type":"string","writeOnly":true},"username":{"type":"string","writeOnly":true},"password":{"type":"string","writeOnly":true},"client_id":{"type":"string","writeOnly":true},"client_secret":{"type":"string","writeOnly":true},"access_token":{"type":"string","writeOnly":true},"refresh_token":{"type":"string","writeOnly":true},"token_url":{"type":"string","format":"uri","writeOnly":true},"scope":{"type":"string","writeOnly":true},"audience":{"type":"string","writeOnly":true},"grant_type":{"type":"string","enum":["client_credentials","refresh_token"],"writeOnly":true},"auth_method":{"type":"string","enum":["client_secret_basic","client_secret_post","none"],"writeOnly":true},"headers":{"type":"object","writeOnly":true,"additionalProperties":{"type":"string"},"description":"Bounded HTTP header map held only in the encrypted vault."}}}}}}},"example":{"payload":{"secrets":{"authorization":"sample authorization","api_key":"sample-token","token":"sample-token","secret":"sample-token","username":"sample username","password":"sample-password","client_id":"sample client id","client_secret":"sample-token","access_token":"sample-token","refresh_token":"sample-token","token_url":"https://example.com/resource","scope":"sample scope","audience":"sample audience","grant_type":"client_credentials","auth_method":"client_secret_basic","headers":{}}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["reveal_token"],"additionalProperties":false,"properties":{"reveal_token":{"type":"string","minLength":64,"maxLength":64,"writeOnly":true,"description":"Short-lived token returned by a generated create or rotate response; consumed once."}}},"example":{"reveal_token":"sample-token"}}}}}},"/api/v1/accounts/{account_id}/flow_builder/credentials":{"get":{"tags":["Flow Builder"],"operationId":"auto_get_api_v1_accounts_account_id_flow_builder_credentials","summary":"List credentials","description":"Returns the list of credentials visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Sanitized metadata for active FlowBuilder credentials. Secret values are never listed.","content":{"application/json":{"schema":{"type":"object","required":["payload"],"properties":{"payload":{"type":"array","items":{"type":"object","required":["id","credential_ref","name","kind","revision","has_secret","created_at","updated_at"],"properties":{"id":{"type":"integer"},"credential_ref":{"type":"string","pattern":"^flow_credential:[0-9]+$","description":"Opaque account-scoped reference stored in a flow definition."},"name":{"type":"string"},"kind":{"type":"string","enum":["http_auth","webhook_signing","oauth2"]},"revision":{"type":"integer","minimum":1},"rotated_at":{"type":["string","null"],"format":"date-time"},"has_secret":{"type":"boolean","description":"Whether encrypted secret material exists; the value itself is never returned here."},"reveal_token":{"type":"string","description":"Short-lived one-time token returned only when the server generated new secret material."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}}},"example":{"payload":[{"id":1,"credential_ref":"sample credential ref","name":"Sample Name","kind":"http_auth","revision":1,"rotated_at":"2026-01-15T10:30:00.000Z","has_secret":true,"reveal_token":"sample-token","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."}]},"post":{"tags":["Flow Builder"],"operationId":"auto_post_api_v1_accounts_account_id_flow_builder_credentials","summary":"Create credentials","description":"Creates a new credential from the request payload. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"201":{"description":"Credential metadata; includes a reveal token only when generate was true.","content":{"application/json":{"schema":{"type":"object","required":["payload"],"properties":{"payload":{"type":"object","required":["id","credential_ref","name","kind","revision","has_secret","created_at","updated_at"],"properties":{"id":{"type":"integer"},"credential_ref":{"type":"string","pattern":"^flow_credential:[0-9]+$","description":"Opaque account-scoped reference stored in a flow definition."},"name":{"type":"string"},"kind":{"type":"string","enum":["http_auth","webhook_signing","oauth2"]},"revision":{"type":"integer","minimum":1},"rotated_at":{"type":["string","null"],"format":"date-time"},"has_secret":{"type":"boolean","description":"Whether encrypted secret material exists; the value itself is never returned here."},"reveal_token":{"type":"string","description":"Short-lived one-time token returned only when the server generated new secret material."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}},"example":{"payload":{"id":1,"credential_ref":"sample credential ref","name":"Sample Name","kind":"http_auth","revision":1,"rotated_at":"2026-01-15T10:30:00.000Z","has_secret":true,"reveal_token":"sample-token","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["credential"],"additionalProperties":false,"properties":{"credential":{"type":"object","required":["name","kind"],"additionalProperties":false,"properties":{"name":{"type":"string","minLength":1},"generate":{"type":"boolean","description":"Generate server-side secret material and return only a short-lived reveal token."},"secrets":{"type":"object","additionalProperties":false,"description":"Write-only credential material; accepted keys depend on the selected credential kind.","properties":{"authorization":{"type":"string","writeOnly":true},"api_key":{"type":"string","writeOnly":true},"token":{"type":"string","writeOnly":true},"secret":{"type":"string","writeOnly":true},"username":{"type":"string","writeOnly":true},"password":{"type":"string","writeOnly":true},"client_id":{"type":"string","writeOnly":true},"client_secret":{"type":"string","writeOnly":true},"access_token":{"type":"string","writeOnly":true},"refresh_token":{"type":"string","writeOnly":true},"token_url":{"type":"string","format":"uri","writeOnly":true},"scope":{"type":"string","writeOnly":true},"audience":{"type":"string","writeOnly":true},"grant_type":{"type":"string","enum":["client_credentials","refresh_token"],"writeOnly":true},"auth_method":{"type":"string","enum":["client_secret_basic","client_secret_post","none"],"writeOnly":true},"headers":{"type":"object","writeOnly":true,"additionalProperties":{"type":"string"},"description":"Bounded HTTP header map held only in the encrypted vault."}}}}}}},"example":{"credential":{"name":"Sample Name","generate":true,"secrets":{"authorization":"sample authorization","api_key":"sample-token","token":"sample-token","secret":"sample-token","username":"sample username","password":"sample-password","client_id":"sample client id","client_secret":"sample-token","access_token":"sample-token","refresh_token":"sample-token","token_url":"https://example.com/resource","scope":"sample scope","audience":"sample audience","grant_type":"client_credentials","auth_method":"client_secret_basic","headers":{}}}}}}}}},"/api/v1/accounts/{account_id}/flow_builder/credentials/{id}":{"get":{"tags":["Flow Builder"],"operationId":"auto_get_api_v1_accounts_account_id_flow_builder_credentials_id","summary":"Get credentials","description":"Returns the credential identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Sanitized metadata for one account-owned FlowBuilder credential.","content":{"application/json":{"schema":{"type":"object","required":["payload"],"properties":{"payload":{"type":"object","required":["id","credential_ref","name","kind","revision","has_secret","created_at","updated_at"],"properties":{"id":{"type":"integer"},"credential_ref":{"type":"string","pattern":"^flow_credential:[0-9]+$","description":"Opaque account-scoped reference stored in a flow definition."},"name":{"type":"string"},"kind":{"type":"string","enum":["http_auth","webhook_signing","oauth2"]},"revision":{"type":"integer","minimum":1},"rotated_at":{"type":["string","null"],"format":"date-time"},"has_secret":{"type":"boolean","description":"Whether encrypted secret material exists; the value itself is never returned here."},"reveal_token":{"type":"string","description":"Short-lived one-time token returned only when the server generated new secret material."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}},"example":{"payload":{"id":1,"credential_ref":"sample credential ref","name":"Sample Name","kind":"http_auth","revision":1,"rotated_at":"2026-01-15T10:30:00.000Z","has_secret":true,"reveal_token":"sample-token","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]},"patch":{"tags":["Flow Builder"],"operationId":"auto_patch_api_v1_accounts_account_id_flow_builder_credentials_id","summary":"Update credentials","description":"Updates the credential identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Sanitized credential metadata after the update.","content":{"application/json":{"schema":{"type":"object","required":["payload"],"properties":{"payload":{"type":"object","required":["id","credential_ref","name","kind","revision","has_secret","created_at","updated_at"],"properties":{"id":{"type":"integer"},"credential_ref":{"type":"string","pattern":"^flow_credential:[0-9]+$","description":"Opaque account-scoped reference stored in a flow definition."},"name":{"type":"string"},"kind":{"type":"string","enum":["http_auth","webhook_signing","oauth2"]},"revision":{"type":"integer","minimum":1},"rotated_at":{"type":["string","null"],"format":"date-time"},"has_secret":{"type":"boolean","description":"Whether encrypted secret material exists; the value itself is never returned here."},"reveal_token":{"type":"string","description":"Short-lived one-time token returned only when the server generated new secret material."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}},"example":{"payload":{"id":1,"credential_ref":"sample credential ref","name":"Sample Name","kind":"http_auth","revision":1,"rotated_at":"2026-01-15T10:30:00.000Z","has_secret":true,"reveal_token":"sample-token","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["credential"],"additionalProperties":false,"properties":{"credential":{"type":"object","additionalProperties":false,"properties":{"name":{"type":"string","minLength":1},"kind":{"type":"string","enum":["http_auth","webhook_signing","oauth2"]}}}}},"example":{"credential":{"name":"Sample Name","kind":"http_auth"}}}}}},"put":{"tags":["Flow Builder"],"operationId":"auto_put_api_v1_accounts_account_id_flow_builder_credentials_id","summary":"Update credentials","description":"Updates the credential identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Sanitized credential metadata after the update.","content":{"application/json":{"schema":{"type":"object","required":["payload"],"properties":{"payload":{"type":"object","required":["id","credential_ref","name","kind","revision","has_secret","created_at","updated_at"],"properties":{"id":{"type":"integer"},"credential_ref":{"type":"string","pattern":"^flow_credential:[0-9]+$","description":"Opaque account-scoped reference stored in a flow definition."},"name":{"type":"string"},"kind":{"type":"string","enum":["http_auth","webhook_signing","oauth2"]},"revision":{"type":"integer","minimum":1},"rotated_at":{"type":["string","null"],"format":"date-time"},"has_secret":{"type":"boolean","description":"Whether encrypted secret material exists; the value itself is never returned here."},"reveal_token":{"type":"string","description":"Short-lived one-time token returned only when the server generated new secret material."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}},"example":{"payload":{"id":1,"credential_ref":"sample credential ref","name":"Sample Name","kind":"http_auth","revision":1,"rotated_at":"2026-01-15T10:30:00.000Z","has_secret":true,"reveal_token":"sample-token","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["credential"],"additionalProperties":false,"properties":{"credential":{"type":"object","additionalProperties":false,"properties":{"name":{"type":"string","minLength":1},"kind":{"type":"string","enum":["http_auth","webhook_signing","oauth2"]}}}}},"example":{"credential":{"name":"Sample Name","kind":"http_auth"}}}}}},"delete":{"tags":["Flow Builder"],"operationId":"auto_delete_api_v1_accounts_account_id_flow_builder_credentials_id","summary":"Delete credentials","description":"Deletes the credential identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Success (no content)"},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/flow_builder/sessions/{id}/cancel":{"post":{"tags":["Flow Builder"],"operationId":"auto_post_api_v1_accounts_account_id_flow_builder_sessions_id_cancel","summary":"Cancel sessions","description":"Performs the cancel operation on the targeted session resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"flow_id":{"type":"integer"},"flow_name":{"type":["string","null"]},"flow_version_id":{"type":"integer"},"runtime_version":{"type":"string"},"definition_schema_version":{"type":["string","null"]},"manifest_version":{"type":["string","null"]},"conversation_id":{"type":"integer"},"contact_id":{"type":"integer"},"inbox_id":{"type":"integer"},"physical_inbox_id":{"type":"integer"},"logical_inbox_id":{"type":"integer"},"status":{"type":"string","enum":["running","waiting","completed","failed","canceled","queued"]},"current_node_id":{"type":"integer"},"variables":{"type":"boolean"},"waiting_for":{"type":"string"},"started_at":{"type":"string","format":"date-time"},"last_step_at":{"type":"string","format":"date-time"},"completed_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"},"evicted_steps":{"type":"array","items":{"type":"string"}},"step_logs":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"node_id":{"type":"integer"},"node_type":{"type":"string","enum":["trigger_conversation_created","trigger_conversation_opened","trigger_conversation_resolved","trigger_conversation_status_changed","trigger_first_reply","trigger_message_received","trigger_keyword","trigger_label_added","trigger_contact_created","trigger_contact_updated","trigger_contact_merged","trigger_api_called","trigger_webhook_received","trigger_scheduled","trigger_payment_charge","trigger_payment_subscription","trigger_commerce","trigger_crm_item","trigger_calendar_booking","message_text","message_buttons","message_list","message_media","typing","condition","switch","ab_test","set_variable","delay","wait_for_reply","chatwoot_action","crm_action","task_action","contact_action","whatsapp_action","calendar_action","payment_action","enroll_in_follow_up","cancel_follow_up","wait_for_follow_up_reply","http_request","outbound_webhook","sql_query","catalog_action","catalog_lookup","commerce_action","ads_action","send_contract","brain_action","maestro_call","handoff_to_human","maestro_pause","maestro_resume","maestro_summarize","goto_flow","end_flow","payment_create_charge","payment_send_charge","payment_wait_for_payment","calendar_send_booking_link","calendar_wait_for_booking","engine"],"description":"Node type executed in this step (the engine catalogue, plus 'engine' for engine-level failures)."},"status":{"type":"string","enum":["entered","completed","failed","skipped"]},"duration_ms":{"type":"string"},"error":{"type":"string"},"input":{"type":"string"},"output":{"type":"string"},"created_at":{"type":"string","format":"date-time"}}}}}}}},"example":{"payload":{"id":1,"flow_id":1,"flow_name":"sample flow name","flow_version_id":1,"runtime_version":"sample runtime version","definition_schema_version":"sample definition schema version","manifest_version":"sample manifest version","conversation_id":1,"contact_id":1,"inbox_id":1,"physical_inbox_id":1,"logical_inbox_id":1,"status":"running","current_node_id":1,"variables":true,"waiting_for":"sample waiting for","started_at":"2026-01-15T10:30:00.000Z","last_step_at":"2026-01-15T10:30:00.000Z","completed_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","evicted_steps":["sample evicted step"],"step_logs":[{"id":1,"node_id":1,"node_type":"trigger_conversation_created","status":"entered","duration_ms":"sample duration ms","error":"sample error","input":"sample input","output":"sample output","created_at":"2026-01-15T10:30:00.000Z"}]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/flow_builder/sessions/{id}/rerun":{"post":{"tags":["Flow Builder"],"operationId":"auto_post_api_v1_accounts_account_id_flow_builder_sessions_id_rerun","summary":"Rerun sessions","description":"Performs the rerun operation on the targeted session resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"flow_id":{"type":"integer"},"flow_name":{"type":["string","null"]},"flow_version_id":{"type":"integer"},"runtime_version":{"type":"string"},"definition_schema_version":{"type":["string","null"]},"manifest_version":{"type":["string","null"]},"conversation_id":{"type":"integer"},"contact_id":{"type":"integer"},"inbox_id":{"type":"integer"},"physical_inbox_id":{"type":"integer"},"logical_inbox_id":{"type":"integer"},"status":{"type":"string","enum":["running","waiting","completed","failed","canceled","queued"]},"current_node_id":{"type":"integer"},"variables":{"type":"boolean"},"waiting_for":{"type":"string"},"started_at":{"type":"string","format":"date-time"},"last_step_at":{"type":"string","format":"date-time"},"completed_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"},"evicted_steps":{"type":"array","items":{"type":"string"}},"step_logs":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"node_id":{"type":"integer"},"node_type":{"type":"string","enum":["trigger_conversation_created","trigger_conversation_opened","trigger_conversation_resolved","trigger_conversation_status_changed","trigger_first_reply","trigger_message_received","trigger_keyword","trigger_label_added","trigger_contact_created","trigger_contact_updated","trigger_contact_merged","trigger_api_called","trigger_webhook_received","trigger_scheduled","trigger_payment_charge","trigger_payment_subscription","trigger_commerce","trigger_crm_item","trigger_calendar_booking","message_text","message_buttons","message_list","message_media","typing","condition","switch","ab_test","set_variable","delay","wait_for_reply","chatwoot_action","crm_action","task_action","contact_action","whatsapp_action","calendar_action","payment_action","enroll_in_follow_up","cancel_follow_up","wait_for_follow_up_reply","http_request","outbound_webhook","sql_query","catalog_action","catalog_lookup","commerce_action","ads_action","send_contract","brain_action","maestro_call","handoff_to_human","maestro_pause","maestro_resume","maestro_summarize","goto_flow","end_flow","payment_create_charge","payment_send_charge","payment_wait_for_payment","calendar_send_booking_link","calendar_wait_for_booking","engine"],"description":"Node type executed in this step (the engine catalogue, plus 'engine' for engine-level failures)."},"status":{"type":"string","enum":["entered","completed","failed","skipped"]},"duration_ms":{"type":"string"},"error":{"type":"string"},"input":{"type":"string"},"output":{"type":"string"},"created_at":{"type":"string","format":"date-time"}}}}}}}},"example":{"payload":{"id":1,"flow_id":1,"flow_name":"sample flow name","flow_version_id":1,"runtime_version":"sample runtime version","definition_schema_version":"sample definition schema version","manifest_version":"sample manifest version","conversation_id":1,"contact_id":1,"inbox_id":1,"physical_inbox_id":1,"logical_inbox_id":1,"status":"running","current_node_id":1,"variables":true,"waiting_for":"sample waiting for","started_at":"2026-01-15T10:30:00.000Z","last_step_at":"2026-01-15T10:30:00.000Z","completed_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","evicted_steps":["sample evicted step"],"step_logs":[{"id":1,"node_id":1,"node_type":"trigger_conversation_created","status":"entered","duration_ms":"sample duration ms","error":"sample error","input":"sample input","output":"sample output","created_at":"2026-01-15T10:30:00.000Z"}]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"dedup":{"type":"string"}}},"example":{"dedup":"sample dedup"}}}}}},"/api/v1/accounts/{account_id}/flow_builder/sessions/{id}/resume":{"post":{"tags":["Flow Builder"],"operationId":"auto_post_api_v1_accounts_account_id_flow_builder_sessions_id_resume","summary":"Resume sessions","description":"Performs the resume operation on the targeted session resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"flow_id":{"type":"integer"},"flow_name":{"type":["string","null"]},"flow_version_id":{"type":"integer"},"runtime_version":{"type":"string"},"definition_schema_version":{"type":["string","null"]},"manifest_version":{"type":["string","null"]},"conversation_id":{"type":"integer"},"contact_id":{"type":"integer"},"inbox_id":{"type":"integer"},"physical_inbox_id":{"type":"integer"},"logical_inbox_id":{"type":"integer"},"status":{"type":"string","enum":["running","waiting","completed","failed","canceled","queued"]},"current_node_id":{"type":"integer"},"variables":{"type":"boolean"},"waiting_for":{"type":"string"},"started_at":{"type":"string","format":"date-time"},"last_step_at":{"type":"string","format":"date-time"},"completed_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"},"evicted_steps":{"type":"array","items":{"type":"string"}},"step_logs":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"node_id":{"type":"integer"},"node_type":{"type":"string","enum":["trigger_conversation_created","trigger_conversation_opened","trigger_conversation_resolved","trigger_conversation_status_changed","trigger_first_reply","trigger_message_received","trigger_keyword","trigger_label_added","trigger_contact_created","trigger_contact_updated","trigger_contact_merged","trigger_api_called","trigger_webhook_received","trigger_scheduled","trigger_payment_charge","trigger_payment_subscription","trigger_commerce","trigger_crm_item","trigger_calendar_booking","message_text","message_buttons","message_list","message_media","typing","condition","switch","ab_test","set_variable","delay","wait_for_reply","chatwoot_action","crm_action","task_action","contact_action","whatsapp_action","calendar_action","payment_action","enroll_in_follow_up","cancel_follow_up","wait_for_follow_up_reply","http_request","outbound_webhook","sql_query","catalog_action","catalog_lookup","commerce_action","ads_action","send_contract","brain_action","maestro_call","handoff_to_human","maestro_pause","maestro_resume","maestro_summarize","goto_flow","end_flow","payment_create_charge","payment_send_charge","payment_wait_for_payment","calendar_send_booking_link","calendar_wait_for_booking","engine"],"description":"Node type executed in this step (the engine catalogue, plus 'engine' for engine-level failures)."},"status":{"type":"string","enum":["entered","completed","failed","skipped"]},"duration_ms":{"type":"string"},"error":{"type":"string"},"input":{"type":"string"},"output":{"type":"string"},"created_at":{"type":"string","format":"date-time"}}}}}}}},"example":{"payload":{"id":1,"flow_id":1,"flow_name":"sample flow name","flow_version_id":1,"runtime_version":"sample runtime version","definition_schema_version":"sample definition schema version","manifest_version":"sample manifest version","conversation_id":1,"contact_id":1,"inbox_id":1,"physical_inbox_id":1,"logical_inbox_id":1,"status":"running","current_node_id":1,"variables":true,"waiting_for":"sample waiting for","started_at":"2026-01-15T10:30:00.000Z","last_step_at":"2026-01-15T10:30:00.000Z","completed_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","evicted_steps":["sample evicted step"],"step_logs":[{"id":1,"node_id":1,"node_type":"trigger_conversation_created","status":"entered","duration_ms":"sample duration ms","error":"sample error","input":"sample input","output":"sample output","created_at":"2026-01-15T10:30:00.000Z"}]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/flow_builder/sessions/{id}/trace":{"get":{"tags":["Flow Builder"],"operationId":"auto_get_api_v1_accounts_account_id_flow_builder_sessions_id_trace","summary":"Read the redacted paginated execution trace","description":"Projects durable v2 step runs, waits, effects and provider deliveries; legacy sessions retain their step-log fallback. A queued session canceled by human takeover before execution projects its skipped cancellation log with zero attempts, including canceled_reason and human_takeover_trigger in the result, without inventing a step run.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Redacted execution steps in ascending ledger order.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["payload","meta"],"properties":{"payload":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Redacted step projection; v2 entries include attempts, wait, effect and deliveries."}},"meta":{"type":"object","additionalProperties":false,"required":["current_page","per_page","total_pages","total_count"],"properties":{"current_page":{"type":"integer","minimum":1},"per_page":{"type":"integer","minimum":1,"maximum":100},"total_pages":{"type":"integer","minimum":0},"total_count":{"type":"integer","minimum":0}}}}},"example":{"payload":[{}],"meta":{"current_page":1,"per_page":1,"total_pages":1,"total_count":5}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/flow_builder/sessions/{id}/attempts":{"get":{"tags":["Flow Builder"],"operationId":"auto_get_api_v1_accounts_account_id_flow_builder_sessions_id_attempts","summary":"Read paginated FlowBuilder step attempts","description":"Returns status, attempts, timing and typed error metadata. Legacy step-log projections retain their redacted input and result; a queued session canceled before execution has zero attempts.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Redacted attempt summaries.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["payload","meta"],"properties":{"payload":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Attempt count, node identity, status, typed error and timestamps."}},"meta":{"type":"object","additionalProperties":false,"required":["current_page","per_page","total_pages","total_count"],"properties":{"current_page":{"type":"integer","minimum":1},"per_page":{"type":"integer","minimum":1,"maximum":100},"total_pages":{"type":"integer","minimum":0},"total_count":{"type":"integer","minimum":0}}}}},"example":{"payload":[{}],"meta":{"current_page":1,"per_page":1,"total_pages":1,"total_count":5}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/flow_builder/sessions/{id}/deliveries":{"get":{"tags":["Flow Builder"],"operationId":"auto_get_api_v1_accounts_account_id_flow_builder_sessions_id_deliveries","summary":"Read paginated FlowBuilder provider deliveries","description":"Returns planned/effective transport and redacted provider correlation without secret material.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Redacted outbound delivery lifecycle rows.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["payload","meta"],"properties":{"payload":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Provider delivery state and non-sensitive correlation metadata."}},"meta":{"type":"object","additionalProperties":false,"required":["current_page","per_page","total_pages","total_count"],"properties":{"current_page":{"type":"integer","minimum":1},"per_page":{"type":"integer","minimum":1,"maximum":100},"total_pages":{"type":"integer","minimum":0},"total_count":{"type":"integer","minimum":0}}}}},"example":{"payload":[{}],"meta":{"current_page":1,"per_page":1,"total_pages":1,"total_count":5}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/flow_builder/sessions/bulk":{"post":{"tags":["Flow Builder"],"operationId":"auto_post_api_v1_accounts_account_id_flow_builder_sessions_bulk","summary":"Apply a bulk action to several flow sessions","description":"Cancels or deletes several running or finished flow sessions in one call. Cancelling closes each still-active session and releases the flow control it holds over its conversation; deleting removes the session row, releasing arbitration first when the session was still active, so a conversation is never left stuck under flow control. A failure on one session is logged and skipped so a single bad record never aborts the batch, and at most the first 200 ids of the list are processed. On success the endpoint returns HTTP 200 with an EMPTY body — refetch the session list to read the result.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The batch finished. Sessions that could not be processed were skipped rather than failing the request. Empty body."},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"422":{"description":"The requested action is not one of the accepted values. Nothing was changed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable reason the batch was rejected.","enum":["unknown_bulk_action"]}},"required":["error"]},"example":{"error":"unknown_bulk_action"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"bulk_action":{"type":"string","description":"Action applied to every session in the list.","enum":["delete","cancel"]},"ids":{"type":"array","description":"Ids of the sessions to act on. Duplicates are removed and only the first 200 ids are processed; ids outside the account are ignored.","items":{"type":"integer"}}},"required":["bulk_action","ids"]},"example":{"bulk_action":"cancel","ids":[8801,8802]}}}}}},"/api/v1/accounts/{account_id}/flow_builder/sessions":{"get":{"tags":["Flow Builder"],"operationId":"auto_get_api_v1_accounts_account_id_flow_builder_sessions","summary":"List sessions","description":"Returns the list of sessions visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Paginated list of flow-execution sessions.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"flow_id":{"type":"integer"},"flow_name":{"type":["string","null"]},"flow_version_id":{"type":["integer","null"]},"conversation_id":{"type":["integer","null"]},"contact_id":{"type":["integer","null"]},"inbox_id":{"type":["integer","null"]},"status":{"type":"string","enum":["running","waiting","completed","failed","canceled"],"description":"Execution state of the session."},"current_node_id":{"type":["string","null"]},"variables":{"type":"object","additionalProperties":true,"description":"Runtime variables collected during the run (internal __ keys are stripped)."},"waiting_for":{"type":"object","additionalProperties":true,"description":"When status is waiting, the pending wait descriptor (node id, handle, timeout)."},"started_at":{"type":["string","null"],"format":"date-time"},"last_step_at":{"type":["string","null"],"format":"date-time"},"completed_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"}}}},"meta":{"type":"object","properties":{"current_page":{"type":"integer"},"total_count":{"type":"integer"}}}}},"example":{"payload":[{"id":1,"flow_id":1,"flow_name":"sample flow name","flow_version_id":1,"conversation_id":1,"contact_id":1,"inbox_id":1,"status":"running","current_node_id":"sample current node id","variables":{},"waiting_for":{},"started_at":"2026-01-15T10:30:00.000Z","last_step_at":"2026-01-15T10:30:00.000Z","completed_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z"}],"meta":{"current_page":1,"total_count":5}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."}]},"post":{"tags":["Flow Builder"],"operationId":"auto_post_api_v1_accounts_account_id_flow_builder_sessions","summary":"Create sessions","description":"Creates a new session from the request payload. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"flow_id":{"type":"integer"},"flow_name":{"type":["string","null"]},"flow_version_id":{"type":"integer"},"runtime_version":{"type":"string"},"definition_schema_version":{"type":["string","null"]},"manifest_version":{"type":["string","null"]},"conversation_id":{"type":"integer"},"contact_id":{"type":"integer"},"inbox_id":{"type":"integer"},"physical_inbox_id":{"type":"integer"},"logical_inbox_id":{"type":"integer"},"status":{"type":"string","enum":["running","waiting","completed","failed","canceled","queued"]},"current_node_id":{"type":"integer"},"variables":{"type":"boolean"},"waiting_for":{"type":"string"},"started_at":{"type":"string","format":"date-time"},"last_step_at":{"type":"string","format":"date-time"},"completed_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"},"evicted_steps":{"type":"array","items":{"type":"string"}},"step_logs":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"node_id":{"type":"integer"},"node_type":{"type":"string","enum":["trigger_conversation_created","trigger_conversation_opened","trigger_conversation_resolved","trigger_conversation_status_changed","trigger_first_reply","trigger_message_received","trigger_keyword","trigger_label_added","trigger_contact_created","trigger_contact_updated","trigger_contact_merged","trigger_api_called","trigger_webhook_received","trigger_scheduled","trigger_payment_charge","trigger_payment_subscription","trigger_commerce","trigger_crm_item","trigger_calendar_booking","message_text","message_buttons","message_list","message_media","typing","condition","switch","ab_test","set_variable","delay","wait_for_reply","chatwoot_action","crm_action","task_action","contact_action","whatsapp_action","calendar_action","payment_action","enroll_in_follow_up","cancel_follow_up","wait_for_follow_up_reply","http_request","outbound_webhook","sql_query","catalog_action","catalog_lookup","commerce_action","ads_action","send_contract","brain_action","maestro_call","handoff_to_human","maestro_pause","maestro_resume","maestro_summarize","goto_flow","end_flow","payment_create_charge","payment_send_charge","payment_wait_for_payment","calendar_send_booking_link","calendar_wait_for_booking","engine"],"description":"Node type executed in this step (the engine catalogue, plus 'engine' for engine-level failures)."},"status":{"type":"string","enum":["entered","completed","failed","skipped"]},"duration_ms":{"type":"string"},"error":{"type":"string"},"input":{"type":"string"},"output":{"type":"string"},"created_at":{"type":"string","format":"date-time"}}}}}}}},"example":{"payload":{"id":1,"flow_id":1,"flow_name":"sample flow name","flow_version_id":1,"runtime_version":"sample runtime version","definition_schema_version":"sample definition schema version","manifest_version":"sample manifest version","conversation_id":1,"contact_id":1,"inbox_id":1,"physical_inbox_id":1,"logical_inbox_id":1,"status":"running","current_node_id":1,"variables":true,"waiting_for":"sample waiting for","started_at":"2026-01-15T10:30:00.000Z","last_step_at":"2026-01-15T10:30:00.000Z","completed_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","evicted_steps":["sample evicted step"],"step_logs":[{"id":1,"node_id":1,"node_type":"trigger_conversation_created","status":"entered","duration_ms":"sample duration ms","error":"sample error","input":"sample input","output":"sample output","created_at":"2026-01-15T10:30:00.000Z"}]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["flow_id"],"properties":{"flow_id":{"type":"integer","description":"The published flow to run. A draft or unknown flow is a 404.","example":12},"conversation_id":{"type":"integer","description":"Subject conversation, resolved by display_id first then id. Optional — omit for a conversation-less run. An id outside this account resolves to no subject (never a 404, so the endpoint cannot be used to probe for existence).","example":4821},"contact_id":{"type":"integer","description":"Subject contact. Optional. When omitted and `crm_item_id` is given, the deal's own contact is adopted. An explicit id always wins over the adopted one.","example":903},"crm_item_id":{"type":"integer","description":"Subject CRM deal, account-scoped and `kept` — an archived deal is refused as a subject, matching the engine's own deal resolution. Rides the trigger payload as `{{ trigger.crm_item_id }}`, the same key the CRM listener emits, so a flow reads the same token whether a deal event or this endpoint started it. Contributes its conversation and contact when neither was passed explicitly.","example":77},"variables":{"type":"object","description":"Author variables seeded into the run, readable as `{{ vars.* }}` and mirrored under `{{ trigger.body.* }}`. Must be an object; any other type is ignored. Keys beginning with the reserved `__` prefix (`__trigger`, `__steps_output`, `__evicted_steps`, `__action_skip`, `__skip_without_conversation`, …) are stripped — that namespace is the engine's own bookkeeping and forging it would let a caller fake a step output another node branches on, or hide a skip the operator needs to see.","additionalProperties":true,"example":{"lead_source":"inbound","priority":"high"}},"dedup":{"type":"string","description":"Optional idempotency token. Manual/API runs are re-runnable by default; passing the same token twice collapses the second call (422 `session_not_started`), which is what makes an n8n/Maestro retry of the same logical run safe.","example":"nightly-sync-2026-07-29"}}},"example":{"flow_id":12,"crm_item_id":77,"variables":{"lead_source":"inbound","priority":"high"},"conversation_id":4821,"contact_id":903,"dedup":"nightly-sync-2026-07-29"}}}}}},"/api/v1/accounts/{account_id}/flow_builder/sessions/{id}":{"get":{"tags":["Flow Builder"],"operationId":"auto_get_api_v1_accounts_account_id_flow_builder_sessions_id","summary":"Get sessions","description":"Returns the session identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"flow_id":{"type":"integer"},"flow_name":{"type":["string","null"]},"flow_version_id":{"type":"integer"},"runtime_version":{"type":"string"},"definition_schema_version":{"type":["string","null"]},"manifest_version":{"type":["string","null"]},"conversation_id":{"type":"integer"},"contact_id":{"type":"integer"},"inbox_id":{"type":"integer"},"physical_inbox_id":{"type":"integer"},"logical_inbox_id":{"type":"integer"},"status":{"type":"string","enum":["running","waiting","completed","failed","canceled","queued"]},"current_node_id":{"type":"integer"},"variables":{"type":"boolean"},"waiting_for":{"type":"string"},"started_at":{"type":"string","format":"date-time"},"last_step_at":{"type":"string","format":"date-time"},"completed_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"},"evicted_steps":{"type":"array","items":{"type":"string"}},"step_logs":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"node_id":{"type":"integer"},"node_type":{"type":"string","enum":["trigger_conversation_created","trigger_conversation_opened","trigger_conversation_resolved","trigger_conversation_status_changed","trigger_first_reply","trigger_message_received","trigger_keyword","trigger_label_added","trigger_contact_created","trigger_contact_updated","trigger_contact_merged","trigger_api_called","trigger_webhook_received","trigger_scheduled","trigger_payment_charge","trigger_payment_subscription","trigger_commerce","trigger_crm_item","trigger_calendar_booking","message_text","message_buttons","message_list","message_media","typing","condition","switch","ab_test","set_variable","delay","wait_for_reply","chatwoot_action","crm_action","task_action","contact_action","whatsapp_action","calendar_action","payment_action","enroll_in_follow_up","cancel_follow_up","wait_for_follow_up_reply","http_request","outbound_webhook","sql_query","catalog_action","catalog_lookup","commerce_action","ads_action","send_contract","brain_action","maestro_call","handoff_to_human","maestro_pause","maestro_resume","maestro_summarize","goto_flow","end_flow","payment_create_charge","payment_send_charge","payment_wait_for_payment","calendar_send_booking_link","calendar_wait_for_booking","engine"],"description":"Node type executed in this step (the engine catalogue, plus 'engine' for engine-level failures)."},"status":{"type":"string","enum":["entered","completed","failed","skipped"]},"duration_ms":{"type":"string"},"error":{"type":"string"},"input":{"type":"string"},"output":{"type":"string"},"created_at":{"type":"string","format":"date-time"}}}}}}}},"example":{"payload":{"id":1,"flow_id":1,"flow_name":"sample flow name","flow_version_id":1,"runtime_version":"sample runtime version","definition_schema_version":"sample definition schema version","manifest_version":"sample manifest version","conversation_id":1,"contact_id":1,"inbox_id":1,"physical_inbox_id":1,"logical_inbox_id":1,"status":"running","current_node_id":1,"variables":true,"waiting_for":"sample waiting for","started_at":"2026-01-15T10:30:00.000Z","last_step_at":"2026-01-15T10:30:00.000Z","completed_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","evicted_steps":["sample evicted step"],"step_logs":[{"id":1,"node_id":1,"node_type":"trigger_conversation_created","status":"entered","duration_ms":"sample duration ms","error":"sample error","input":"sample input","output":"sample output","created_at":"2026-01-15T10:30:00.000Z"}]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]},"delete":{"tags":["Flow Builder"],"operationId":"auto_delete_api_v1_accounts_account_id_flow_builder_sessions_id","summary":"Delete sessions","description":"Deletes the session identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Success (no content)"},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/flow_builder/node_types":{"get":{"tags":["Flow Builder"],"operationId":"auto_get_api_v1_accounts_account_id_flow_builder_node_types","summary":"List node types","description":"Returns the list of node types visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Node-type catalog available to this account (feature-gated and hidden entries removed).","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","description":"One entry per node type the editor palette can add.","items":{"type":"object","properties":{"type":{"type":"string","description":"Stable node-type key (matches the flow definition's node `type`)."},"category":{"type":"string","enum":["trigger","message","logic","chatwoot_action","crm","contact","tasks","whatsapp","catalog","commerce","integration","database","ai","control","payments","agenda","follow_up","contracts","ads"],"description":"Palette grouping for the node."},"label":{"type":"string","description":"Default (English) label; the editor localizes and whitelabels it at render time."},"kind":{"type":"string","enum":["trigger","node"]},"i18n_key":{"type":"string"},"definition_schema":{"type":"object","additionalProperties":true,"description":"JSON Schema applied to this node's persisted data by the v2 compiler."},"defaults":{"type":"object","additionalProperties":true,"description":"Server-owned defaults for newly authored nodes."},"editor":{"type":"string","enum":["fields","rich_message","condition","http_mapping","sql_mapping","brain","transform","action","trigger_mapping"],"description":"Custom editor family; `fields` uses the typed field list directly."},"fields":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"type":{"type":"string"},"labelKey":{"type":"string"},"group":{"type":"string"},"source":{"type":"string"},"options":{"type":"array","items":{"type":["string","number","boolean"]}}}},"description":"Typed inspector controls exposed for the staged migration of schema-driven editors."},"handles":{"type":"array","items":{"type":"string"},"description":"Static branch-output ports the node exposes (e.g. success/error, found/empty/error, met/timeout). Absent for single-output nodes."},"gate":{"type":"string","enum":["payments","calendar","follow_ups","ads_manager","account_brain","contracts"],"description":"Feature flag the node is published under (absent = ungated)."},"permission":{"type":"string"},"available":{"type":"boolean"},"hidden":{"type":"boolean"},"outputs":{"type":"object","description":"Server-driven output schema (single source for the editor's variable picker — no FE drift).","properties":{"keys":{"type":"array","items":{"type":"string"},"description":"Step-output fields the executor writes, readable as `steps.\u003ckey\u003e.\u003cfield\u003e`."},"produces":{"type":"array","description":"Session variables the node creates.","items":{"type":"object","properties":{"field":{"type":"string","description":"Node-data key that names the variable (e.g. `variable`, `item_var`)."},"default":{"type":"string","description":"Variable name used when the field is left blank."},"suffixes":{"type":"array","items":{"type":"string"}}},"description":"Companion variables derived from the base name (e.g. `_count`, `_list`)."}}}}}}},"manifest":{"type":"object","required":["manifest_version","definition_schema_version","checksum","limits","nodes","triggers","actions","channels"],"properties":{"manifest_version":{"type":"string"},"definition_schema_version":{"type":"integer"},"checksum":{"type":"string","pattern":"^[0-9a-f]{64}$"},"limits":{"type":"object","properties":{"definition_bytes":{"type":"integer"},"nodes":{"type":"integer"},"edges":{"type":"integer"},"output_bytes":{"type":"integer"},"session_state_bytes":{"type":"integer"}}},"nodes":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"kind":{"type":"string","enum":["node"]},"category":{"type":"string"},"available":{"type":"boolean"},"handles":{"type":"array","items":{"type":"string"}}}}},"triggers":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"kind":{"type":"string","enum":["trigger"]},"category":{"type":"string","enum":["trigger"]},"available":{"type":"boolean"},"producer":{"type":"string"}}}},"actions":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"category":{"type":"string"},"gate":{"type":"string"},"permission":{"type":"string"},"input_schema":{"type":"object","additionalProperties":true,"description":"JSON Schema for persisted action_params."}}}},"channels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"channel_types":{"type":"array","items":{"type":"string"}},"providers":{"type":"array","items":{"type":"string"}},"available":{"type":"boolean"}}}}}},"liquid_action_params":{"type":"object","description":"Map of action name to the top-level parameters whose value accepts `{{ variables }}`. It is the single variable registry shared by the automation, macro and flow editors: every listed parameter is rendered at execution (by the action handler, by the message pipeline, or pre-rendered by the flow for free text), so the editor offers the variable picker exactly on these parameters and nowhere else.","additionalProperties":{"type":"array","items":{"type":"string"}}},"example":{"payload":[{"type":"http_request","category":"integration","label":"HTTP request","handles":["success","error"],"outputs":{"keys":["status","handle","body"],"produces":[{"field":"variable","default":"http_response"}]}},{"type":"find_contact","category":"contact","label":"Find contact","handles":["found","not_found","error"],"outputs":{"keys":["found","contact_id","reassigned","error"],"produces":[{"field":"variable","default":"found_contact"}]}},{"type":"crm_lookup","category":"crm","label":"CRM lookup","handles":["found","empty","error"],"outputs":{"keys":["found","count","unavailable","reason","error"],"produces":[{"field":"variable","default":"found_deal","suffixes":["_count","_list"]}]}}]}}},"example":{"payload":[{"type":"sample type","category":"trigger","label":"sample label","kind":"trigger","i18n_key":"sample-token","definition_schema":{},"defaults":{},"editor":"fields","fields":[{"key":"sample key","type":"sample type","labelKey":"sample labelKey","group":"sample group","source":"sample source","options":["sample option"]}],"handles":["sample handle"],"gate":"payments","permission":"sample permission","available":true,"hidden":true,"outputs":{"keys":["sample key"],"produces":[{"field":"sample field","default":"sample default","suffixes":["sample suffixe"]}]}}],"manifest":{"manifest_version":"sample manifest version","definition_schema_version":1,"checksum":"sample checksum","limits":{"definition_bytes":1,"nodes":1,"edges":1,"output_bytes":1,"session_state_bytes":1},"nodes":[{"type":"sample type","kind":"node","category":"sample category","available":true,"handles":["sample handle"]}],"triggers":[{"type":"sample type","kind":"trigger","category":"trigger","available":true,"producer":"sample producer"}],"actions":[{"name":"Sample Name","category":"sample category","gate":"sample gate","permission":"sample permission","input_schema":{}}],"channels":[{"id":"sample id","channel_types":["sample channel type"],"providers":["sample provider"],"available":true}]},"liquid_action_params":{},"example":"sample example"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."}]}},"/api/v1/accounts/{account_id}/flow_builder/manifest":{"get":{"tags":["Flow Builder"],"operationId":"auto_get_api_v1_accounts_account_id_flow_builder_manifest","summary":"Get the versioned FlowBuilder authoring manifest","description":"Returns the server-owned node, trigger, action, channel, generic connector, schema, limit and availability contract, optionally overlaid for one account-scoped inbox.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Versioned manifest and optional inbox capability overlay.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["payload","inbox"],"properties":{"payload":{"type":"object","additionalProperties":true,"description":"Full server-owned manifest; every entry carries its schema, handles, gates, permissions and runtime limits."},"inbox":{"type":["object","null"],"additionalProperties":true,"description":"Non-sensitive account-scoped inbox capability projection when inbox_id was supplied."}}},"example":{"payload":{},"inbox":{}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"inbox_id","in":"query","required":false,"schema":{"type":"integer"}}]}},"/api/v1/accounts/{account_id}/flow_builder/reports":{"get":{"tags":["Flow Builder"],"operationId":"auto_get_api_v1_accounts_account_id_flow_builder_reports","summary":"List reports","description":"Returns the list of reports visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"string"}}},"example":{"payload":"sample payload"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."},{"name":"flow_id","in":"query","required":false,"schema":{"type":"integer"}},{"name":"since","in":"query","required":false,"schema":{"type":"string"}},{"name":"until","in":"query","required":false,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/flow_builder/batches/{id}/start":{"post":{"tags":["Flow Builder"],"operationId":"auto_post_api_v1_accounts_account_id_flow_builder_batches_id_start","summary":"Start batches","description":"Performs the start operation on the targeted batch resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"title":{"type":"string"},"status":{"type":"string","enum":["draft","scheduled","running","paused","completed","canceled","failed"]},"flow_id":{"type":"integer"},"flow_name":{"type":["string","null"]},"flow_version_id":{"type":"integer"},"inbox_id":{"type":"integer"},"inbox_name":{"type":["string","null"]},"logical_inbox_id":{"type":"integer"},"conversation_policy":{"type":"string","enum":["auto","reuse_only","actions_only"]},"target_mode":{"type":"string","enum":["per_contact","per_conversation"],"description":"What one target row of the disparo represents (FlowBuilder::Batch#target_mode). `per_contact` (default): one execution per contact, acting on the MATCHED conversation when the audience came from the Conversations family. `per_conversation`: one execution per matched conversation — only valid when every audience entry is of the `conversation` family."},"reuse_preference":{"type":"string","enum":["prefer_open","latest_any"],"description":"Which existing conversation an UNSTAMPED target reuses (FlowBuilder::Batches::SettingsResolver). `prefer_open` (default): the most recently active open/snoozed conversation, else the most recent of any status. `latest_any`: the most recently active conversation regardless of status (the historical behavior)."},"total_targets":{"type":"string"},"stats":{"type":"string"},"audience_degraded":{"type":"array","items":{"type":"string"}},"audience_truncated":{"type":"boolean"},"scheduled_at":{"type":"string","format":"date-time"},"started_at":{"type":"string","format":"date-time"},"completed_at":{"type":"string","format":"date-time"},"created_by_id":{"type":"integer"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"audience":{"type":"string"},"cadence":{"type":"string"},"variables":{"type":"string"},"funnel":{"type":"string"}}}}},"example":{"payload":{"id":1,"title":"Sample title","status":"draft","flow_id":1,"flow_name":"sample flow name","flow_version_id":1,"inbox_id":1,"inbox_name":"sample inbox name","logical_inbox_id":1,"conversation_policy":"auto","target_mode":"per_contact","reuse_preference":"prefer_open","total_targets":"sample total targets","stats":"sample stats","audience_degraded":["sample audience degraded"],"audience_truncated":true,"scheduled_at":"2026-01-15T10:30:00.000Z","started_at":"2026-01-15T10:30:00.000Z","completed_at":"2026-01-15T10:30:00.000Z","created_by_id":1,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","audience":"sample audience","cadence":"sample cadence","variables":"sample variables","funnel":"sample funnel"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/flow_builder/batches/{id}/pause":{"post":{"tags":["Flow Builder"],"operationId":"auto_post_api_v1_accounts_account_id_flow_builder_batches_id_pause","summary":"Pause batches","description":"Performs the pause operation on the targeted batch resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"title":{"type":"string"},"status":{"type":"string","enum":["draft","scheduled","running","paused","completed","canceled","failed"]},"flow_id":{"type":"integer"},"flow_name":{"type":["string","null"]},"flow_version_id":{"type":"integer"},"inbox_id":{"type":"integer"},"inbox_name":{"type":["string","null"]},"logical_inbox_id":{"type":"integer"},"conversation_policy":{"type":"string","enum":["auto","reuse_only","actions_only"]},"target_mode":{"type":"string","enum":["per_contact","per_conversation"],"description":"What one target row of the disparo represents (FlowBuilder::Batch#target_mode). `per_contact` (default): one execution per contact, acting on the MATCHED conversation when the audience came from the Conversations family. `per_conversation`: one execution per matched conversation — only valid when every audience entry is of the `conversation` family."},"reuse_preference":{"type":"string","enum":["prefer_open","latest_any"],"description":"Which existing conversation an UNSTAMPED target reuses (FlowBuilder::Batches::SettingsResolver). `prefer_open` (default): the most recently active open/snoozed conversation, else the most recent of any status. `latest_any`: the most recently active conversation regardless of status (the historical behavior)."},"total_targets":{"type":"string"},"stats":{"type":"string"},"audience_degraded":{"type":"array","items":{"type":"string"}},"audience_truncated":{"type":"boolean"},"scheduled_at":{"type":"string","format":"date-time"},"started_at":{"type":"string","format":"date-time"},"completed_at":{"type":"string","format":"date-time"},"created_by_id":{"type":"integer"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"audience":{"type":"string"},"cadence":{"type":"string"},"variables":{"type":"string"},"funnel":{"type":"string"}}}}},"example":{"payload":{"id":1,"title":"Sample title","status":"draft","flow_id":1,"flow_name":"sample flow name","flow_version_id":1,"inbox_id":1,"inbox_name":"sample inbox name","logical_inbox_id":1,"conversation_policy":"auto","target_mode":"per_contact","reuse_preference":"prefer_open","total_targets":"sample total targets","stats":"sample stats","audience_degraded":["sample audience degraded"],"audience_truncated":true,"scheduled_at":"2026-01-15T10:30:00.000Z","started_at":"2026-01-15T10:30:00.000Z","completed_at":"2026-01-15T10:30:00.000Z","created_by_id":1,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","audience":"sample audience","cadence":"sample cadence","variables":"sample variables","funnel":"sample funnel"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/flow_builder/batches/{id}/resume":{"post":{"tags":["Flow Builder"],"operationId":"auto_post_api_v1_accounts_account_id_flow_builder_batches_id_resume","summary":"Resume batches","description":"Performs the resume operation on the targeted batch resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"title":{"type":"string"},"status":{"type":"string","enum":["draft","scheduled","running","paused","completed","canceled","failed"]},"flow_id":{"type":"integer"},"flow_name":{"type":["string","null"]},"flow_version_id":{"type":"integer"},"inbox_id":{"type":"integer"},"inbox_name":{"type":["string","null"]},"logical_inbox_id":{"type":"integer"},"conversation_policy":{"type":"string","enum":["auto","reuse_only","actions_only"]},"target_mode":{"type":"string","enum":["per_contact","per_conversation"],"description":"What one target row of the disparo represents (FlowBuilder::Batch#target_mode). `per_contact` (default): one execution per contact, acting on the MATCHED conversation when the audience came from the Conversations family. `per_conversation`: one execution per matched conversation — only valid when every audience entry is of the `conversation` family."},"reuse_preference":{"type":"string","enum":["prefer_open","latest_any"],"description":"Which existing conversation an UNSTAMPED target reuses (FlowBuilder::Batches::SettingsResolver). `prefer_open` (default): the most recently active open/snoozed conversation, else the most recent of any status. `latest_any`: the most recently active conversation regardless of status (the historical behavior)."},"total_targets":{"type":"string"},"stats":{"type":"string"},"audience_degraded":{"type":"array","items":{"type":"string"}},"audience_truncated":{"type":"boolean"},"scheduled_at":{"type":"string","format":"date-time"},"started_at":{"type":"string","format":"date-time"},"completed_at":{"type":"string","format":"date-time"},"created_by_id":{"type":"integer"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"audience":{"type":"string"},"cadence":{"type":"string"},"variables":{"type":"string"},"funnel":{"type":"string"}}}}},"example":{"payload":{"id":1,"title":"Sample title","status":"draft","flow_id":1,"flow_name":"sample flow name","flow_version_id":1,"inbox_id":1,"inbox_name":"sample inbox name","logical_inbox_id":1,"conversation_policy":"auto","target_mode":"per_contact","reuse_preference":"prefer_open","total_targets":"sample total targets","stats":"sample stats","audience_degraded":["sample audience degraded"],"audience_truncated":true,"scheduled_at":"2026-01-15T10:30:00.000Z","started_at":"2026-01-15T10:30:00.000Z","completed_at":"2026-01-15T10:30:00.000Z","created_by_id":1,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","audience":"sample audience","cadence":"sample cadence","variables":"sample variables","funnel":"sample funnel"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/flow_builder/batches/{id}/cancel":{"post":{"tags":["Flow Builder"],"operationId":"auto_post_api_v1_accounts_account_id_flow_builder_batches_id_cancel","summary":"Cancel batches","description":"Performs the cancel operation on the targeted batch resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"title":{"type":"string"},"status":{"type":"string","enum":["draft","scheduled","running","paused","completed","canceled","failed"]},"flow_id":{"type":"integer"},"flow_name":{"type":["string","null"]},"flow_version_id":{"type":"integer"},"inbox_id":{"type":"integer"},"inbox_name":{"type":["string","null"]},"logical_inbox_id":{"type":"integer"},"conversation_policy":{"type":"string","enum":["auto","reuse_only","actions_only"]},"target_mode":{"type":"string","enum":["per_contact","per_conversation"],"description":"What one target row of the disparo represents (FlowBuilder::Batch#target_mode). `per_contact` (default): one execution per contact, acting on the MATCHED conversation when the audience came from the Conversations family. `per_conversation`: one execution per matched conversation — only valid when every audience entry is of the `conversation` family."},"reuse_preference":{"type":"string","enum":["prefer_open","latest_any"],"description":"Which existing conversation an UNSTAMPED target reuses (FlowBuilder::Batches::SettingsResolver). `prefer_open` (default): the most recently active open/snoozed conversation, else the most recent of any status. `latest_any`: the most recently active conversation regardless of status (the historical behavior)."},"total_targets":{"type":"string"},"stats":{"type":"string"},"audience_degraded":{"type":"array","items":{"type":"string"}},"audience_truncated":{"type":"boolean"},"scheduled_at":{"type":"string","format":"date-time"},"started_at":{"type":"string","format":"date-time"},"completed_at":{"type":"string","format":"date-time"},"created_by_id":{"type":"integer"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"audience":{"type":"string"},"cadence":{"type":"string"},"variables":{"type":"string"},"funnel":{"type":"string"}}}}},"example":{"payload":{"id":1,"title":"Sample title","status":"draft","flow_id":1,"flow_name":"sample flow name","flow_version_id":1,"inbox_id":1,"inbox_name":"sample inbox name","logical_inbox_id":1,"conversation_policy":"auto","target_mode":"per_contact","reuse_preference":"prefer_open","total_targets":"sample total targets","stats":"sample stats","audience_degraded":["sample audience degraded"],"audience_truncated":true,"scheduled_at":"2026-01-15T10:30:00.000Z","started_at":"2026-01-15T10:30:00.000Z","completed_at":"2026-01-15T10:30:00.000Z","created_by_id":1,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","audience":"sample audience","cadence":"sample cadence","variables":"sample variables","funnel":"sample funnel"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/flow_builder/batches/{id}/retry_failures":{"post":{"tags":["Flow Builder"],"operationId":"auto_post_api_v1_accounts_account_id_flow_builder_batches_id_retry_failures","summary":"Retry failures batches","description":"Performs the retry failures operation on the targeted batch resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"title":{"type":"string"},"status":{"type":"string","enum":["draft","scheduled","running","paused","completed","canceled","failed"]},"flow_id":{"type":"integer"},"flow_name":{"type":["string","null"]},"flow_version_id":{"type":"integer"},"inbox_id":{"type":"integer"},"inbox_name":{"type":["string","null"]},"logical_inbox_id":{"type":"integer"},"conversation_policy":{"type":"string","enum":["auto","reuse_only","actions_only"]},"target_mode":{"type":"string","enum":["per_contact","per_conversation"],"description":"What one target row of the disparo represents (FlowBuilder::Batch#target_mode). `per_contact` (default): one execution per contact, acting on the MATCHED conversation when the audience came from the Conversations family. `per_conversation`: one execution per matched conversation — only valid when every audience entry is of the `conversation` family."},"reuse_preference":{"type":"string","enum":["prefer_open","latest_any"],"description":"Which existing conversation an UNSTAMPED target reuses (FlowBuilder::Batches::SettingsResolver). `prefer_open` (default): the most recently active open/snoozed conversation, else the most recent of any status. `latest_any`: the most recently active conversation regardless of status (the historical behavior)."},"total_targets":{"type":"string"},"stats":{"type":"string"},"audience_degraded":{"type":"array","items":{"type":"string"}},"audience_truncated":{"type":"boolean"},"scheduled_at":{"type":"string","format":"date-time"},"started_at":{"type":"string","format":"date-time"},"completed_at":{"type":"string","format":"date-time"},"created_by_id":{"type":"integer"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"audience":{"type":"string"},"cadence":{"type":"string"},"variables":{"type":"string"},"funnel":{"type":"string"}}}}},"example":{"payload":{"id":1,"title":"Sample title","status":"draft","flow_id":1,"flow_name":"sample flow name","flow_version_id":1,"inbox_id":1,"inbox_name":"sample inbox name","logical_inbox_id":1,"conversation_policy":"auto","target_mode":"per_contact","reuse_preference":"prefer_open","total_targets":"sample total targets","stats":"sample stats","audience_degraded":["sample audience degraded"],"audience_truncated":true,"scheduled_at":"2026-01-15T10:30:00.000Z","started_at":"2026-01-15T10:30:00.000Z","completed_at":"2026-01-15T10:30:00.000Z","created_by_id":1,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","audience":"sample audience","cadence":"sample cadence","variables":"sample variables","funnel":"sample funnel"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/flow_builder/batches/{id}/batch_targets":{"get":{"tags":["Flow Builder"],"operationId":"auto_get_api_v1_accounts_account_id_flow_builder_batches_id_batch_targets","summary":"Batch targets batches","description":"Performs the batch targets operation on the targeted batch resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"contact_id":{"type":"integer"},"contact_name":{"type":"string"},"contact_phone":{"type":"string"},"conversation_id":{"type":"integer"},"conversation_display_id":{"type":["integer","null"]},"flow_session_id":{"type":"integer"},"session_status":{"type":["string","null"],"enum":["running","waiting","completed","failed","canceled",null]},"status":{"type":"string","enum":["draft","scheduled","running","paused","completed","canceled","failed"]},"error_reason":{"type":"string"},"processed_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"}}}},"meta":{"type":"object","properties":{"current_page":{"type":"string"},"total_count":{"type":"integer"}}}}},"example":{"payload":[{"id":1,"contact_id":1,"contact_name":"sample contact name","contact_phone":"+5511999998888","conversation_id":1,"conversation_display_id":1,"flow_session_id":1,"session_status":"running","status":"draft","error_reason":"sample error reason","processed_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z"}],"meta":{"current_page":"sample current page","total_count":5}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"status","in":"query","required":false,"description":"Restrict to targets in one dispatch state.","schema":{"type":"string","enum":["pending","enqueued","started","completed","failed","skipped"]},"example":"failed"},{"name":"page","in":"query","required":false,"description":"Page of targets.","schema":{"type":"integer","default":1},"example":1}]}},"/api/v1/accounts/{account_id}/flow_builder/batches/preview_audience":{"post":{"tags":["Flow Builder"],"operationId":"auto_post_api_v1_accounts_account_id_flow_builder_batches_preview_audience","summary":"Estimate the audience of a mass run before creating it","description":"Resolves the given audience entries to a target count without persisting anything, so the wizard can show the reach before the operator confirms. The unit follows `target_mode` — contacts in `per_contact` (default), matched conversations in `per_conversation`. The selected inbox is mandatory because the same channel-specific LGPD consent gate used during materialization is applied to the preview. Accepts the entries either at the top level (`entries`) or nested under the batch payload (`batch.audience.entries`); the top-level form is canonical.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The resolved estimate. Nothing is persisted.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"count":{"type":"integer","description":"Estimated targets in the unit of `target_mode` — contacts in `per_contact`, matched conversations in `per_conversation`."},"target_mode":{"type":"string","enum":["per_contact","per_conversation"],"description":"The counting unit this estimate was resolved under."},"degraded":{"type":"array","description":"Names of audience sources that could not be resolved and contributed zero targets (e.g. `conversation_filter` for a saved folder that no longer exists). Empty when every entry resolved cleanly.","items":{"type":"string"}}},"required":["count","target_mode","degraded"]}},"required":["payload"]},"example":{"payload":{"count":312,"target_mode":"per_contact","degraded":[]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"inbox_id":{"type":"integer","description":"Account-scoped inbox whose delivery channel determines consent eligibility."},"target_mode":{"type":"string","enum":["per_contact","per_conversation"],"description":"Counting unit for the estimate — one target per contact (default) or one per matched conversation. Same value the batch will persist under `audience.target_mode`."},"entries":{"type":"array","description":"Audience entries to resolve. Same shape the batch persists.","items":{"type":"object","description":"One audience source. `type` picks the family and `mode` picks how it is read; the remaining fields qualify it and are ignored where they do not apply. An unknown value falls back to its safe default rather than failing the request. Every family resolves to CONTACTS — a conversation, CRM or company audience is turned into the people behind it, and the dispatcher reuses or opens one conversation per contact on the chosen inbox.","properties":{"type":{"type":"string","enum":["contact","conversation","crm_item","organization","imported_list"],"example":"conversation","description":"The audience family: the account's `contact` list, their `conversation`s, the open deals of a CRM pipeline (`crm_item`), the people of one or more companies (`organization`), or an `imported_list` of contact ids already materialized from a pasted number list."},"mode":{"type":"string","enum":["all","label","segment","filter","pick"],"example":"label","description":"How the family is read. `contact`: all · label · segment · pick. `conversation`: all · filter (a saved conversation folder) · label (a label applied to the CONVERSATIONS, not the contacts). `organization`: segment (a saved company segment) · pick (chosen companies). Not used by `crm_item` or `imported_list`."},"ids":{"type":"array","items":{"type":"integer"},"example":[12],"description":"The records `mode` points at — label ids, saved-filter ids, contact ids or company ids, depending on the family and mode. Ignored when the mode is `all`."},"status":{"type":"string","enum":["all","open","pending","snoozed","resolved"],"example":"open","description":"Narrows a `conversation` entry (`all` and `label` modes) to conversations in one status. Defaults to `all`."},"pipeline_id":{"type":"integer","example":7,"description":"The CRM pipeline a `crm_item` entry targets. Only OPEN deals ever enter the audience."},"stage_id":{"type":"integer","example":21,"description":"Narrows a `crm_item` entry to a single stage. Omitted means every stage of the pipeline."},"contact_ids":{"type":"array","items":{"type":"integer"},"example":[4821],"description":"Contact ids of an `imported_list` entry, as returned by the list-import endpoint. Ignored by every other family."}}}},"batch":{"type":"object","description":"Alternative envelope — the same entries nested under `batch.audience.entries`.","properties":{"audience":{"type":"object","description":"The disparo's audience. Entries are UNIONED — a contact matched by more than one entry is targeted once — and a single `{ type: contact, mode: all }` entry dominates the rest. A saved filter that no longer resolves contributes zero contacts instead of failing the disparo.","properties":{"entries":{"type":"array","items":{"type":"object","description":"One audience source. `type` picks the family and `mode` picks how it is read; the remaining fields qualify it and are ignored where they do not apply. An unknown value falls back to its safe default rather than failing the request. Every family resolves to CONTACTS — a conversation, CRM or company audience is turned into the people behind it, and the dispatcher reuses or opens one conversation per contact on the chosen inbox.","properties":{"type":{"type":"string","enum":["contact","conversation","crm_item","organization","imported_list"],"example":"conversation","description":"The audience family: the account's `contact` list, their `conversation`s, the open deals of a CRM pipeline (`crm_item`), the people of one or more companies (`organization`), or an `imported_list` of contact ids already materialized from a pasted number list."},"mode":{"type":"string","enum":["all","label","segment","filter","pick"],"example":"label","description":"How the family is read. `contact`: all · label · segment · pick. `conversation`: all · filter (a saved conversation folder) · label (a label applied to the CONVERSATIONS, not the contacts). `organization`: segment (a saved company segment) · pick (chosen companies). Not used by `crm_item` or `imported_list`."},"ids":{"type":"array","items":{"type":"integer"},"example":[12],"description":"The records `mode` points at — label ids, saved-filter ids, contact ids or company ids, depending on the family and mode. Ignored when the mode is `all`."},"status":{"type":"string","enum":["all","open","pending","snoozed","resolved"],"example":"open","description":"Narrows a `conversation` entry (`all` and `label` modes) to conversations in one status. Defaults to `all`."},"pipeline_id":{"type":"integer","example":7,"description":"The CRM pipeline a `crm_item` entry targets. Only OPEN deals ever enter the audience."},"stage_id":{"type":"integer","example":21,"description":"Narrows a `crm_item` entry to a single stage. Omitted means every stage of the pipeline."},"contact_ids":{"type":"array","items":{"type":"integer"},"example":[4821],"description":"Contact ids of an `imported_list` entry, as returned by the list-import endpoint. Ignored by every other family."}}}},"target_mode":{"type":"string","enum":["per_contact","per_conversation"],"example":"per_contact","description":"What one target row represents. `per_contact` (default): one execution per contact; when the audience came from the Conversations family the MATCHED conversation is stamped on the target and the flow acts on it. `per_conversation`: one execution per matched conversation — only valid when every audience entry is of the `conversation` family."}}}}}},"required":["inbox_id"]},"example":{"inbox_id":1,"target_mode":"per_contact","entries":[{"type":"conversation","mode":"label","ids":[12],"status":"open","pipeline_id":7,"stage_id":21,"contact_ids":[4821]}],"batch":{"audience":{"entries":[{"type":"conversation","mode":"label","ids":[12],"status":"open","pipeline_id":7,"stage_id":21,"contact_ids":[4821]}],"target_mode":"per_contact"}}}}}}}},"/api/v1/accounts/{account_id}/flow_builder/batches/import_list":{"post":{"tags":["Flow Builder"],"operationId":"auto_post_api_v1_accounts_account_id_flow_builder_batches_import_list","summary":"Import list batches","description":"Performs the import list operation on the targeted batch resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"contact_ids":{"type":"array","items":{"type":"integer"}},"imported":{"type":"string"},"invalid":{"type":"string"}}}}},"example":{"payload":{"contact_ids":[1],"imported":"sample imported","invalid":"sample invalid"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"raw":{"type":"string"},"numbers":{"type":"string"}}},"example":{"raw":"sample raw","numbers":"sample numbers"}}}}}},"/api/v1/accounts/{account_id}/flow_builder/batches/bulk":{"post":{"tags":["Flow Builder"],"operationId":"auto_post_api_v1_accounts_account_id_flow_builder_batches_bulk","summary":"Apply a bulk action to several flow batches","description":"Runs one control action over a list of flow batches (bulk sends) in a single call — pausing or resuming delivery, cancelling the remaining targets, re-queueing the targets that failed, or deleting the batch entirely. A failure on one batch is logged and skipped so a single bad record never aborts the batch, and at most the first 100 ids of the list are processed. The response carries one result row per REQUESTED id — `ok: true` when the action applied, otherwise `ok: false` with the reason (`not_found` for an id outside the account) — so a caller can tell exactly which disparos were left untouched.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The sweep finished. Batches that could not be processed are reported per id rather than failing the request.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"results":{"type":"array","description":"One entry per requested id, in request order.","items":{"type":"object","properties":{"id":{"type":"integer","description":"The batch id this row refers to."},"ok":{"type":"boolean","description":"Whether the action applied to this batch."},"error":{"type":["string","null"],"description":"Failure reason when `ok` is false — `not_found` for an id outside the account, otherwise the recorded per-batch error."}},"required":["id","ok"]}}},"required":["results"]}},"required":["payload"]},"example":{"payload":{"results":[{"id":512,"ok":true,"error":null},{"id":513,"ok":false,"error":"not_found"}]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"422":{"description":"The requested action is not one of the accepted values. Nothing was changed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable reason the batch was rejected.","enum":["unknown_bulk_action"]}},"required":["error"]},"example":{"error":"unknown_bulk_action"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"bulk_action":{"type":"string","description":"Control action applied to every batch in the list.","enum":["pause","resume","cancel","retry_failures","delete"]},"ids":{"type":"array","description":"Ids of the batches to act on. Duplicates are removed and only the first 100 ids are processed; ids outside the account are ignored.","items":{"type":"integer"}}},"required":["bulk_action","ids"]},"example":{"bulk_action":"pause","ids":[512,513]}}}}}},"/api/v1/accounts/{account_id}/flow_builder/batches":{"get":{"tags":["Flow Builder"],"operationId":"auto_get_api_v1_accounts_account_id_flow_builder_batches","summary":"List batches","description":"Returns the list of batches visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"title":{"type":"string"},"status":{"type":"string","enum":["draft","scheduled","running","paused","completed","canceled","failed"]},"flow_id":{"type":"integer"},"flow_name":{"type":["string","null"]},"flow_version_id":{"type":"integer"},"inbox_id":{"type":"integer"},"inbox_name":{"type":["string","null"]},"logical_inbox_id":{"type":"integer"},"conversation_policy":{"type":"string","enum":["auto","reuse_only","actions_only"]},"target_mode":{"type":"string","enum":["per_contact","per_conversation"],"description":"What one target row of the disparo represents (FlowBuilder::Batch#target_mode). `per_contact` (default): one execution per contact, acting on the MATCHED conversation when the audience came from the Conversations family. `per_conversation`: one execution per matched conversation — only valid when every audience entry is of the `conversation` family."},"reuse_preference":{"type":"string","enum":["prefer_open","latest_any"],"description":"Which existing conversation an UNSTAMPED target reuses (FlowBuilder::Batches::SettingsResolver). `prefer_open` (default): the most recently active open/snoozed conversation, else the most recent of any status. `latest_any`: the most recently active conversation regardless of status (the historical behavior)."},"total_targets":{"type":"string"},"stats":{"type":"string"},"audience_degraded":{"type":"array","items":{"type":"string"}},"audience_truncated":{"type":"boolean"},"scheduled_at":{"type":"string","format":"date-time"},"started_at":{"type":"string","format":"date-time"},"completed_at":{"type":"string","format":"date-time"},"created_by_id":{"type":"integer"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}},"meta":{"type":"object","properties":{"current_page":{"type":"string"},"total_count":{"type":"integer"}}}}},"example":{"payload":[{"id":1,"title":"Sample title","status":"draft","flow_id":1,"flow_name":"sample flow name","flow_version_id":1,"inbox_id":1,"inbox_name":"sample inbox name","logical_inbox_id":1,"conversation_policy":"auto","target_mode":"per_contact","reuse_preference":"prefer_open","total_targets":"sample total targets","stats":"sample stats","audience_degraded":["sample audience degraded"],"audience_truncated":true,"scheduled_at":"2026-01-15T10:30:00.000Z","started_at":"2026-01-15T10:30:00.000Z","completed_at":"2026-01-15T10:30:00.000Z","created_by_id":1,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}],"meta":{"current_page":"sample current page","total_count":5}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."}]},"post":{"tags":["Flow Builder"],"operationId":"auto_post_api_v1_accounts_account_id_flow_builder_batches","summary":"Create batches","description":"Creates a new batch from the request payload. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"title":{"type":"string"},"status":{"type":"string","enum":["draft","scheduled","running","paused","completed","canceled","failed"]},"flow_id":{"type":"integer"},"flow_name":{"type":["string","null"]},"flow_version_id":{"type":"integer"},"inbox_id":{"type":"integer"},"inbox_name":{"type":["string","null"]},"logical_inbox_id":{"type":"integer"},"conversation_policy":{"type":"string","enum":["auto","reuse_only","actions_only"]},"target_mode":{"type":"string","enum":["per_contact","per_conversation"],"description":"What one target row of the disparo represents (FlowBuilder::Batch#target_mode). `per_contact` (default): one execution per contact, acting on the MATCHED conversation when the audience came from the Conversations family. `per_conversation`: one execution per matched conversation — only valid when every audience entry is of the `conversation` family."},"reuse_preference":{"type":"string","enum":["prefer_open","latest_any"],"description":"Which existing conversation an UNSTAMPED target reuses (FlowBuilder::Batches::SettingsResolver). `prefer_open` (default): the most recently active open/snoozed conversation, else the most recent of any status. `latest_any`: the most recently active conversation regardless of status (the historical behavior)."},"total_targets":{"type":"string"},"stats":{"type":"string"},"audience_degraded":{"type":"array","items":{"type":"string"}},"audience_truncated":{"type":"boolean"},"scheduled_at":{"type":"string","format":"date-time"},"started_at":{"type":"string","format":"date-time"},"completed_at":{"type":"string","format":"date-time"},"created_by_id":{"type":"integer"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"audience":{"type":"string"},"cadence":{"type":"string"},"variables":{"type":"string"},"funnel":{"type":"string"}}}}},"example":{"payload":{"id":1,"title":"Sample title","status":"draft","flow_id":1,"flow_name":"sample flow name","flow_version_id":1,"inbox_id":1,"inbox_name":"sample inbox name","logical_inbox_id":1,"conversation_policy":"auto","target_mode":"per_contact","reuse_preference":"prefer_open","total_targets":"sample total targets","stats":"sample stats","audience_degraded":["sample audience degraded"],"audience_truncated":true,"scheduled_at":"2026-01-15T10:30:00.000Z","started_at":"2026-01-15T10:30:00.000Z","completed_at":"2026-01-15T10:30:00.000Z","created_by_id":1,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","audience":"sample audience","cadence":"sample cadence","variables":"sample variables","funnel":"sample funnel"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"batch":{"type":"object","properties":{"flow_id":{"type":"integer","example":12,"description":"The PUBLISHED flow every target will run."},"inbox_id":{"type":"integer","example":3,"description":"Inbox the disparo sends on."},"title":{"type":"string","example":"Reativação agosto","description":"Operator-facing name of the disparo."},"conversation_policy":{"type":"string","enum":["auto","reuse_only","actions_only"],"example":"auto","description":"Whether a target without an open conversation gets a new one (`auto`), is skipped (`reuse_only`), or runs the flow's actions without any conversation (`actions_only`)."},"scheduled_at":{"type":"string","format":"date-time","example":"2026-01-15T10:30:00.000Z","description":"When the disparo should start. Interpreted in the account's timezone."},"start":{"type":"boolean","example":false,"description":"Launch immediately after creation instead of leaving the disparo as a draft."},"audience":{"type":"object","description":"The disparo's audience. Entries are UNIONED — a contact matched by more than one entry is targeted once — and a single `{ type: contact, mode: all }` entry dominates the rest. A saved filter that no longer resolves contributes zero contacts instead of failing the disparo.","properties":{"entries":{"type":"array","items":{"type":"object","description":"One audience source. `type` picks the family and `mode` picks how it is read; the remaining fields qualify it and are ignored where they do not apply. An unknown value falls back to its safe default rather than failing the request. Every family resolves to CONTACTS — a conversation, CRM or company audience is turned into the people behind it, and the dispatcher reuses or opens one conversation per contact on the chosen inbox.","properties":{"type":{"type":"string","enum":["contact","conversation","crm_item","organization","imported_list"],"example":"conversation","description":"The audience family: the account's `contact` list, their `conversation`s, the open deals of a CRM pipeline (`crm_item`), the people of one or more companies (`organization`), or an `imported_list` of contact ids already materialized from a pasted number list."},"mode":{"type":"string","enum":["all","label","segment","filter","pick"],"example":"label","description":"How the family is read. `contact`: all · label · segment · pick. `conversation`: all · filter (a saved conversation folder) · label (a label applied to the CONVERSATIONS, not the contacts). `organization`: segment (a saved company segment) · pick (chosen companies). Not used by `crm_item` or `imported_list`."},"ids":{"type":"array","items":{"type":"integer"},"example":[12],"description":"The records `mode` points at — label ids, saved-filter ids, contact ids or company ids, depending on the family and mode. Ignored when the mode is `all`."},"status":{"type":"string","enum":["all","open","pending","snoozed","resolved"],"example":"open","description":"Narrows a `conversation` entry (`all` and `label` modes) to conversations in one status. Defaults to `all`."},"pipeline_id":{"type":"integer","example":7,"description":"The CRM pipeline a `crm_item` entry targets. Only OPEN deals ever enter the audience."},"stage_id":{"type":"integer","example":21,"description":"Narrows a `crm_item` entry to a single stage. Omitted means every stage of the pipeline."},"contact_ids":{"type":"array","items":{"type":"integer"},"example":[4821],"description":"Contact ids of an `imported_list` entry, as returned by the list-import endpoint. Ignored by every other family."}}}},"target_mode":{"type":"string","enum":["per_contact","per_conversation"],"example":"per_contact","description":"What one target row represents. `per_contact` (default): one execution per contact; when the audience came from the Conversations family the MATCHED conversation is stamped on the target and the flow acts on it. `per_conversation`: one execution per matched conversation — only valid when every audience entry is of the `conversation` family."}}},"cadence":{"type":"object","additionalProperties":true,"description":"Pacing configuration — anti-ban send rate, drip, quiet hours and business days. Free map; the resolver applies safe provider defaults for anything omitted.","properties":{"reuse_preference":{"type":"string","enum":["prefer_open","latest_any"],"example":"prefer_open","description":"Which existing conversation an UNSTAMPED target reuses. `prefer_open` (default): the most recently active open/snoozed conversation, else the most recent of any status. `latest_any`: the most recently active conversation regardless of status (the historical behavior)."}}},"variables":{"type":"object","additionalProperties":true,"description":"Flow variables seeded on every session this disparo opens. Free map."}},"required":["flow_id"]}},"required":["batch"]},"example":{"batch":{"flow_id":12,"inbox_id":3,"title":"Reativação agosto","conversation_policy":"auto","scheduled_at":"2026-01-15T10:30:00.000Z","start":false,"audience":{"entries":[{"type":"conversation","mode":"label","ids":[12],"status":"open","pipeline_id":7,"stage_id":21,"contact_ids":[4821]}],"target_mode":"per_contact"},"cadence":{"reuse_preference":"prefer_open"},"variables":{}}}}}}}},"/api/v1/accounts/{account_id}/flow_builder/batches/{id}":{"get":{"tags":["Flow Builder"],"operationId":"auto_get_api_v1_accounts_account_id_flow_builder_batches_id","summary":"Get batches","description":"Returns the batch identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"title":{"type":"string"},"status":{"type":"string","enum":["draft","scheduled","running","paused","completed","canceled","failed"]},"flow_id":{"type":"integer"},"flow_name":{"type":["string","null"]},"flow_version_id":{"type":"integer"},"inbox_id":{"type":"integer"},"inbox_name":{"type":["string","null"]},"logical_inbox_id":{"type":"integer"},"conversation_policy":{"type":"string","enum":["auto","reuse_only","actions_only"]},"target_mode":{"type":"string","enum":["per_contact","per_conversation"],"description":"What one target row of the disparo represents (FlowBuilder::Batch#target_mode). `per_contact` (default): one execution per contact, acting on the MATCHED conversation when the audience came from the Conversations family. `per_conversation`: one execution per matched conversation — only valid when every audience entry is of the `conversation` family."},"reuse_preference":{"type":"string","enum":["prefer_open","latest_any"],"description":"Which existing conversation an UNSTAMPED target reuses (FlowBuilder::Batches::SettingsResolver). `prefer_open` (default): the most recently active open/snoozed conversation, else the most recent of any status. `latest_any`: the most recently active conversation regardless of status (the historical behavior)."},"total_targets":{"type":"string"},"stats":{"type":"string"},"audience_degraded":{"type":"array","items":{"type":"string"}},"audience_truncated":{"type":"boolean"},"scheduled_at":{"type":"string","format":"date-time"},"started_at":{"type":"string","format":"date-time"},"completed_at":{"type":"string","format":"date-time"},"created_by_id":{"type":"integer"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"audience":{"type":"string"},"cadence":{"type":"string"},"variables":{"type":"string"},"funnel":{"type":"string"}}}}},"example":{"payload":{"id":1,"title":"Sample title","status":"draft","flow_id":1,"flow_name":"sample flow name","flow_version_id":1,"inbox_id":1,"inbox_name":"sample inbox name","logical_inbox_id":1,"conversation_policy":"auto","target_mode":"per_contact","reuse_preference":"prefer_open","total_targets":"sample total targets","stats":"sample stats","audience_degraded":["sample audience degraded"],"audience_truncated":true,"scheduled_at":"2026-01-15T10:30:00.000Z","started_at":"2026-01-15T10:30:00.000Z","completed_at":"2026-01-15T10:30:00.000Z","created_by_id":1,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","audience":"sample audience","cadence":"sample cadence","variables":"sample variables","funnel":"sample funnel"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]},"patch":{"tags":["Flow Builder"],"operationId":"auto_patch_api_v1_accounts_account_id_flow_builder_batches_id","summary":"Update batches","description":"Edits a disparo while it is still a draft; a launched one is immutable (retry or cancel it instead). Changing the audience re-estimates the target count.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"title":{"type":"string"},"status":{"type":"string","enum":["draft","scheduled","running","paused","completed","canceled","failed"]},"flow_id":{"type":"integer"},"flow_name":{"type":["string","null"]},"flow_version_id":{"type":"integer"},"inbox_id":{"type":"integer"},"inbox_name":{"type":["string","null"]},"logical_inbox_id":{"type":"integer"},"conversation_policy":{"type":"string","enum":["auto","reuse_only","actions_only"]},"target_mode":{"type":"string","enum":["per_contact","per_conversation"],"description":"What one target row of the disparo represents (FlowBuilder::Batch#target_mode). `per_contact` (default): one execution per contact, acting on the MATCHED conversation when the audience came from the Conversations family. `per_conversation`: one execution per matched conversation — only valid when every audience entry is of the `conversation` family."},"reuse_preference":{"type":"string","enum":["prefer_open","latest_any"],"description":"Which existing conversation an UNSTAMPED target reuses (FlowBuilder::Batches::SettingsResolver). `prefer_open` (default): the most recently active open/snoozed conversation, else the most recent of any status. `latest_any`: the most recently active conversation regardless of status (the historical behavior)."},"total_targets":{"type":"string"},"stats":{"type":"string"},"audience_degraded":{"type":"array","items":{"type":"string"}},"audience_truncated":{"type":"boolean"},"scheduled_at":{"type":"string","format":"date-time"},"started_at":{"type":"string","format":"date-time"},"completed_at":{"type":"string","format":"date-time"},"created_by_id":{"type":"integer"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"audience":{"type":"string"},"cadence":{"type":"string"},"variables":{"type":"string"},"funnel":{"type":"string"}}}}},"example":{"payload":{"id":1,"title":"Sample title","status":"draft","flow_id":1,"flow_name":"sample flow name","flow_version_id":1,"inbox_id":1,"inbox_name":"sample inbox name","logical_inbox_id":1,"conversation_policy":"auto","target_mode":"per_contact","reuse_preference":"prefer_open","total_targets":"sample total targets","stats":"sample stats","audience_degraded":["sample audience degraded"],"audience_truncated":true,"scheduled_at":"2026-01-15T10:30:00.000Z","started_at":"2026-01-15T10:30:00.000Z","completed_at":"2026-01-15T10:30:00.000Z","created_by_id":1,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","audience":"sample audience","cadence":"sample cadence","variables":"sample variables","funnel":"sample funnel"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"batch":{"type":"object","properties":{"inbox_id":{"type":"integer","example":3,"description":"Inbox the disparo sends on."},"title":{"type":"string","example":"Reativação agosto","description":"Operator-facing name of the disparo."},"conversation_policy":{"type":"string","enum":["auto","reuse_only","actions_only"],"example":"auto","description":"Conversation strategy per target; an unknown value falls back to `auto`."},"scheduled_at":{"type":"string","format":"date-time","example":"2026-01-15T10:30:00.000Z","description":"When the disparo should start. Interpreted in the account's timezone."},"audience":{"type":"object","description":"The disparo's audience. Entries are UNIONED — a contact matched by more than one entry is targeted once — and a single `{ type: contact, mode: all }` entry dominates the rest. A saved filter that no longer resolves contributes zero contacts instead of failing the disparo.","properties":{"entries":{"type":"array","items":{"type":"object","description":"One audience source. `type` picks the family and `mode` picks how it is read; the remaining fields qualify it and are ignored where they do not apply. An unknown value falls back to its safe default rather than failing the request. Every family resolves to CONTACTS — a conversation, CRM or company audience is turned into the people behind it, and the dispatcher reuses or opens one conversation per contact on the chosen inbox.","properties":{"type":{"type":"string","enum":["contact","conversation","crm_item","organization","imported_list"],"example":"conversation","description":"The audience family: the account's `contact` list, their `conversation`s, the open deals of a CRM pipeline (`crm_item`), the people of one or more companies (`organization`), or an `imported_list` of contact ids already materialized from a pasted number list."},"mode":{"type":"string","enum":["all","label","segment","filter","pick"],"example":"label","description":"How the family is read. `contact`: all · label · segment · pick. `conversation`: all · filter (a saved conversation folder) · label (a label applied to the CONVERSATIONS, not the contacts). `organization`: segment (a saved company segment) · pick (chosen companies). Not used by `crm_item` or `imported_list`."},"ids":{"type":"array","items":{"type":"integer"},"example":[12],"description":"The records `mode` points at — label ids, saved-filter ids, contact ids or company ids, depending on the family and mode. Ignored when the mode is `all`."},"status":{"type":"string","enum":["all","open","pending","snoozed","resolved"],"example":"open","description":"Narrows a `conversation` entry (`all` and `label` modes) to conversations in one status. Defaults to `all`."},"pipeline_id":{"type":"integer","example":7,"description":"The CRM pipeline a `crm_item` entry targets. Only OPEN deals ever enter the audience."},"stage_id":{"type":"integer","example":21,"description":"Narrows a `crm_item` entry to a single stage. Omitted means every stage of the pipeline."},"contact_ids":{"type":"array","items":{"type":"integer"},"example":[4821],"description":"Contact ids of an `imported_list` entry, as returned by the list-import endpoint. Ignored by every other family."}}}},"target_mode":{"type":"string","enum":["per_contact","per_conversation"],"example":"per_contact","description":"What one target row represents. `per_contact` (default): one execution per contact; when the audience came from the Conversations family the MATCHED conversation is stamped on the target and the flow acts on it. `per_conversation`: one execution per matched conversation — only valid when every audience entry is of the `conversation` family."}}},"cadence":{"type":"object","additionalProperties":true,"description":"Pacing configuration — anti-ban send rate, drip, quiet hours and business days.","properties":{"reuse_preference":{"type":"string","enum":["prefer_open","latest_any"],"example":"prefer_open","description":"Which existing conversation an UNSTAMPED target reuses. `prefer_open` (default): the most recently active open/snoozed conversation, else the most recent of any status. `latest_any`: the most recently active conversation regardless of status (the historical behavior)."}}},"variables":{"type":"object","additionalProperties":true,"description":"Flow variables seeded on every session this disparo opens. Free map."}}}},"required":["batch"]},"example":{"batch":{"inbox_id":3,"title":"Reativação agosto","conversation_policy":"auto","scheduled_at":"2026-01-15T10:30:00.000Z","audience":{"entries":[{"type":"conversation","mode":"label","ids":[12],"status":"open","pipeline_id":7,"stage_id":21,"contact_ids":[4821]}],"target_mode":"per_contact"},"cadence":{"reuse_preference":"prefer_open"},"variables":{}}}}}}},"put":{"tags":["Flow Builder"],"operationId":"auto_put_api_v1_accounts_account_id_flow_builder_batches_id","summary":"Update batches","description":"Edits a disparo while it is still a draft; a launched one is immutable (retry or cancel it instead). Changing the audience re-estimates the target count.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"title":{"type":"string"},"status":{"type":"string","enum":["draft","scheduled","running","paused","completed","canceled","failed"]},"flow_id":{"type":"integer"},"flow_name":{"type":["string","null"]},"flow_version_id":{"type":"integer"},"inbox_id":{"type":"integer"},"inbox_name":{"type":["string","null"]},"logical_inbox_id":{"type":"integer"},"conversation_policy":{"type":"string","enum":["auto","reuse_only","actions_only"]},"target_mode":{"type":"string","enum":["per_contact","per_conversation"],"description":"What one target row of the disparo represents (FlowBuilder::Batch#target_mode). `per_contact` (default): one execution per contact, acting on the MATCHED conversation when the audience came from the Conversations family. `per_conversation`: one execution per matched conversation — only valid when every audience entry is of the `conversation` family."},"reuse_preference":{"type":"string","enum":["prefer_open","latest_any"],"description":"Which existing conversation an UNSTAMPED target reuses (FlowBuilder::Batches::SettingsResolver). `prefer_open` (default): the most recently active open/snoozed conversation, else the most recent of any status. `latest_any`: the most recently active conversation regardless of status (the historical behavior)."},"total_targets":{"type":"string"},"stats":{"type":"string"},"audience_degraded":{"type":"array","items":{"type":"string"}},"audience_truncated":{"type":"boolean"},"scheduled_at":{"type":"string","format":"date-time"},"started_at":{"type":"string","format":"date-time"},"completed_at":{"type":"string","format":"date-time"},"created_by_id":{"type":"integer"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"audience":{"type":"string"},"cadence":{"type":"string"},"variables":{"type":"string"},"funnel":{"type":"string"}}}}},"example":{"payload":{"id":1,"title":"Sample title","status":"draft","flow_id":1,"flow_name":"sample flow name","flow_version_id":1,"inbox_id":1,"inbox_name":"sample inbox name","logical_inbox_id":1,"conversation_policy":"auto","target_mode":"per_contact","reuse_preference":"prefer_open","total_targets":"sample total targets","stats":"sample stats","audience_degraded":["sample audience degraded"],"audience_truncated":true,"scheduled_at":"2026-01-15T10:30:00.000Z","started_at":"2026-01-15T10:30:00.000Z","completed_at":"2026-01-15T10:30:00.000Z","created_by_id":1,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","audience":"sample audience","cadence":"sample cadence","variables":"sample variables","funnel":"sample funnel"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"batch":{"type":"object","properties":{"inbox_id":{"type":"integer","example":3,"description":"Inbox the disparo sends on."},"title":{"type":"string","example":"Reativação agosto","description":"Operator-facing name of the disparo."},"conversation_policy":{"type":"string","enum":["auto","reuse_only","actions_only"],"example":"auto","description":"Conversation strategy per target; an unknown value falls back to `auto`."},"scheduled_at":{"type":"string","format":"date-time","example":"2026-01-15T10:30:00.000Z","description":"When the disparo should start. Interpreted in the account's timezone."},"audience":{"type":"object","description":"The disparo's audience. Entries are UNIONED — a contact matched by more than one entry is targeted once — and a single `{ type: contact, mode: all }` entry dominates the rest. A saved filter that no longer resolves contributes zero contacts instead of failing the disparo.","properties":{"entries":{"type":"array","items":{"type":"object","description":"One audience source. `type` picks the family and `mode` picks how it is read; the remaining fields qualify it and are ignored where they do not apply. An unknown value falls back to its safe default rather than failing the request. Every family resolves to CONTACTS — a conversation, CRM or company audience is turned into the people behind it, and the dispatcher reuses or opens one conversation per contact on the chosen inbox.","properties":{"type":{"type":"string","enum":["contact","conversation","crm_item","organization","imported_list"],"example":"conversation","description":"The audience family: the account's `contact` list, their `conversation`s, the open deals of a CRM pipeline (`crm_item`), the people of one or more companies (`organization`), or an `imported_list` of contact ids already materialized from a pasted number list."},"mode":{"type":"string","enum":["all","label","segment","filter","pick"],"example":"label","description":"How the family is read. `contact`: all · label · segment · pick. `conversation`: all · filter (a saved conversation folder) · label (a label applied to the CONVERSATIONS, not the contacts). `organization`: segment (a saved company segment) · pick (chosen companies). Not used by `crm_item` or `imported_list`."},"ids":{"type":"array","items":{"type":"integer"},"example":[12],"description":"The records `mode` points at — label ids, saved-filter ids, contact ids or company ids, depending on the family and mode. Ignored when the mode is `all`."},"status":{"type":"string","enum":["all","open","pending","snoozed","resolved"],"example":"open","description":"Narrows a `conversation` entry (`all` and `label` modes) to conversations in one status. Defaults to `all`."},"pipeline_id":{"type":"integer","example":7,"description":"The CRM pipeline a `crm_item` entry targets. Only OPEN deals ever enter the audience."},"stage_id":{"type":"integer","example":21,"description":"Narrows a `crm_item` entry to a single stage. Omitted means every stage of the pipeline."},"contact_ids":{"type":"array","items":{"type":"integer"},"example":[4821],"description":"Contact ids of an `imported_list` entry, as returned by the list-import endpoint. Ignored by every other family."}}}},"target_mode":{"type":"string","enum":["per_contact","per_conversation"],"example":"per_contact","description":"What one target row represents. `per_contact` (default): one execution per contact; when the audience came from the Conversations family the MATCHED conversation is stamped on the target and the flow acts on it. `per_conversation`: one execution per matched conversation — only valid when every audience entry is of the `conversation` family."}}},"cadence":{"type":"object","additionalProperties":true,"description":"Pacing configuration — anti-ban send rate, drip, quiet hours and business days.","properties":{"reuse_preference":{"type":"string","enum":["prefer_open","latest_any"],"example":"prefer_open","description":"Which existing conversation an UNSTAMPED target reuses. `prefer_open` (default): the most recently active open/snoozed conversation, else the most recent of any status. `latest_any`: the most recently active conversation regardless of status (the historical behavior)."}}},"variables":{"type":"object","additionalProperties":true,"description":"Flow variables seeded on every session this disparo opens. Free map."}}}},"required":["batch"]},"example":{"batch":{"inbox_id":3,"title":"Reativação agosto","conversation_policy":"auto","scheduled_at":"2026-01-15T10:30:00.000Z","audience":{"entries":[{"type":"conversation","mode":"label","ids":[12],"status":"open","pipeline_id":7,"stage_id":21,"contact_ids":[4821]}],"target_mode":"per_contact"},"cadence":{"reuse_preference":"prefer_open"},"variables":{}}}}}}},"delete":{"tags":["Flow Builder"],"operationId":"auto_delete_api_v1_accounts_account_id_flow_builder_batches_id","summary":"Delete batches","description":"Deletes the batch identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Success (no content)"},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/calendar/connections/{id}/resync":{"post":{"tags":["Calendar"],"operationId":"auto_post_api_v1_accounts_account_id_calendar_connections_id_resync","summary":"Force an immediate re-sync of a Google connection","description":"Re-enqueues an inbound sync for every mirrored calendar on the connection and flushes pending outbound pushes. Also releases a sync state left wedged in `syncing` by an interrupted run, so this is the operator's first move when a connection appears stuck. Returns how many calendars were re-enqueued.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Sync re-enqueued.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"queued":{"type":"integer","description":"How many mirrored calendars were re-enqueued for syncing.","example":2}}}}},"example":{"payload":{"queued":2}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/calendar/settings/preview":{"post":{"tags":["Calendar"],"operationId":"auto_post_api_v1_accounts_account_id_calendar_settings_preview","summary":"Preview settings","description":"Performs the preview operation on the targeted setting resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The notification rendered per channel, the resolved out-of-window template, the native buttons and the shipped copy. Nothing is persisted.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"locale":{"type":"string","description":"The locale the preview rendered in.","example":"pt_BR"},"sample_present":{"type":"boolean","description":"False when the account has no event yet — every variable then renders blank and the UI says so.","example":true},"variables":{"type":"object","description":"The 8 booking variables Calendar::MessageTemplate resolves, from the account's most recent event.","additionalProperties":{"type":"string"},"example":{"contact_name":"Ana","date":"12/05/2026","datetime":"12/05/2026 10:00","host":"Bruno","link":"https://app.example.com/book/manage/abc123","location":"Sala 2","time":"10:00","title":"Consultoria"}},"rendered":{"type":"string","description":"The body with its variables resolved (before per-channel rendering).","example":"Olá Ana, seu Consultoria é em 12/05/2026 10:00."},"rendered_by_channel":{"type":"object","description":"One entry per channel type the ACCOUNT has an inbox of, rendered by Messages::MarkdownRendererService.","additionalProperties":{"type":"string"},"example":{"Channel::Whatsapp":"Olá Ana, seu Consultoria é em 12/05/2026 10:00."}},"hsm":{"type":["object","null"],"description":"The resolved out-of-window template params, or null when no approved template applies to this kind x locale.","properties":{"name":{"type":"string","example":"agenda_reminder_pt_br"},"language":{"type":"string","example":"pt_BR"},"namespace":{"type":["string","null"],"example":null},"processed_params":{"type":"object","description":"Meta component params: `body` is a 1-indexed map, `buttons` carries the manage token for the dynamic URL button.","additionalProperties":true,"example":{"body":{"1":"Ana","2":"Consultoria"}}}}},"buttons":{"type":"array","description":"The native \"Manage booking\" button the send will attach, already capped to what the chosen provider renders. Empty when the event has no booking (so there is no manage link), the operator turned the switch off, or the channel has no interactive surface.","items":{"type":"object","properties":{"type":{"type":"string","enum":["cta_url","cta_copy"],"example":"cta_url"},"text":{"type":"string","example":"Gerenciar agendamento"},"url":{"type":"string","example":"https://app.example.com/book/manage/abc123"},"code":{"type":"string","description":"Present only for cta_copy.","example":"00020126580014BR.GOV.BCB.PIX"}}},"example":[{"type":"cta_url","text":"Gerenciar agendamento","url":"https://app.example.com/book/manage/abc123"}]},"defaults":{"type":"object","description":"The SHIPPED copy behind each kind named in `types` — what an empty body actually sends. Empty when the account has no event yet (the shipped lines interpolate that event and are never fabricated).","properties":{"bodies":{"type":"object","description":"notification kind -\u003e shipped body, in the previewed locale.","additionalProperties":{"type":"string"},"example":{"reminder":"⏰ Reminder: your appointment “Consultoria” is coming up."}},"labels":{"type":"object","description":"Always empty here — the Agenda exposes no auxiliary labels through the shared reader.","additionalProperties":{"type":"string"},"example":{}}}}}}}},"example":{"payload":{"locale":"pt_BR","sample_present":true,"variables":{"contact_name":"Ana","date":"12/05/2026","datetime":"12/05/2026 10:00","host":"Bruno","link":"https://app.example.com/book/manage/abc123","location":"Sala 2","time":"10:00","title":"Consultoria"},"rendered":"Olá Ana, seu Consultoria é em 12/05/2026 10:00.","rendered_by_channel":{"Channel::Whatsapp":"Olá Ana, seu Consultoria é em 12/05/2026 10:00."},"hsm":{"name":"agenda_reminder_pt_br","language":"pt_BR","namespace":null,"processed_params":{"body":{"1":"Ana","2":"Consultoria"}}},"buttons":[{"type":"cta_url","text":"Gerenciar agendamento","url":"https://app.example.com/book/manage/abc123","code":"00020126580014BR.GOV.BCB.PIX"}],"defaults":{"bodies":{"reminder":"⏰ Reminder: your appointment “Consultoria” is coming up."},"labels":{}}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"The unsaved notification body the operator is looking at — nothing is persisted, nothing is sent.","properties":{"type":{"type":"string","enum":["reminder","confirmation","reschedule","cancel"],"description":"Which booking notification is being previewed.","example":"reminder"},"locale":{"type":"string","description":"Locale to render in; omitted falls back to the contact -\u003e conversation -\u003e account cascade.","example":"pt_BR"},"body":{"type":"string","description":"The body with `{{variable}}` tokens, exactly as authored in the editor. Empty previews the shipped copy.","example":"Olá {{ contact_name }}, seu {{ title }} é em {{ datetime }}."},"provider":{"type":"string","enum":["whatsapp_cloud","whatsapp_web","default"],"description":"The provider of the inbox being configured. It decides how many native buttons the preview may promise (Meta's cta_url carries exactly one). Omitted, the module's own configured WhatsApp inbox is used.","example":"whatsapp_web"},"types":{"type":"array","description":"Notification kinds whose SHIPPED copy should come back in `defaults.bodies`.","items":{"type":"string","enum":["reminder","confirmation","reschedule","cancel"]},"example":["reminder","confirmation","reschedule","cancel"]},"scope":{"type":["string","null"],"description":"Per-event-type override scope (`event_type:\u003cid\u003e`). Omit for the account default.","example":"event_type:9"},"whatsapp_template":{"type":"object","description":"The approved HSM the editor is holding. Omitted, the stored per-kind x per-locale template is resolved instead. `params` is the shared editor's positional list; `body_params` is the name the Agenda's own field stored and is still accepted, so a config written before the two surfaces converged previews exactly as it sends.","properties":{"name":{"type":"string","example":"agenda_reminder_pt_br"},"language":{"type":"string","example":"pt_BR"},"url_button":{"type":"string","description":"Truthy when the template carries a dynamic URL button — it is filled with the booking manage token.","example":"true"},"params":{"type":"array","items":{"type":"string"},"description":"Positional body params: a known variable name resolves from the variable map, anything else is a literal.","example":["contact_name","title","datetime"]},"body_params":{"type":"array","items":{"type":"string"},"description":"Legacy name for `params`, still read.","example":["contact_name","title","datetime"]}}}}},"example":{"type":"reminder","locale":"pt_BR","body":"Olá {{ contact_name }}, seu {{ title }} é em {{ datetime }}.","provider":"whatsapp_web","types":["reminder","confirmation","reschedule","cancel"],"scope":"event_type:9","whatsapp_template":{"name":"agenda_reminder_pt_br","language":"pt_BR","url_button":"true","params":["contact_name","title","datetime"],"body_params":["contact_name","title","datetime"]}}}}}}},"/api/v1/accounts/{account_id}/calendar/settings/test_send":{"post":{"tags":["Calendar"],"operationId":"auto_post_api_v1_accounts_account_id_calendar_settings_test_send","summary":"Test send settings","description":"Performs the test send operation on the targeted setting resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The outcome of the send, which honours the WhatsApp 24h window exactly as the real notification does.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"status":{"type":"string","enum":["sent","skipped","failed"],"description":"sent = a message was created; skipped = nothing was sent (see reason); failed = the send raised.","example":"sent"},"reason":{"type":["string","null"],"description":"Canonical skip/failure reason: `whatsapp_window_closed` (the 24h window is closed and no approved template is configured) or `empty_body`. Null when sent.","example":"whatsapp_window_closed"},"content":{"type":"string","description":"The rendered body that was sent (or would have been).","example":"Olá Ana, seu Consultoria é em 12/05/2026 10:00."},"message_id":{"type":["integer","null"],"description":"The created message id; null on skip/failure.","example":9001}}}}},"example":{"payload":{"status":"sent","reason":"whatsapp_window_closed","content":"Olá Ana, seu Consultoria é em 12/05/2026 10:00.","message_id":9001}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"422":{"description":"No conversation was given (`conversation_required`), so there is nothing to send into.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"conversation_required"}}},"example":{"error":"conversation_required"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["conversation_id"],"description":"Sends ONE real booking notification into an EXISTING conversation. Never creates a conversation, never touches a booking.","properties":{"conversation_id":{"type":"string","description":"Conversation display_id (an internal id is accepted as a fallback).","example":"42"},"type":{"type":"string","enum":["reminder","confirmation","reschedule","cancel"],"example":"reminder"},"locale":{"type":"string","example":"pt_BR"},"body":{"type":"string","description":"The body exactly as authored in the editor.","example":"Olá {{ contact_name }}, seu {{ title }} é em {{ datetime }}."},"scope":{"type":["string","null"],"example":"event_type:9"},"whatsapp_template":{"type":"object","description":"The approved HSM the editor is holding, used when the 24h window is closed.","properties":{"name":{"type":"string","example":"agenda_reminder_pt_br"},"language":{"type":"string","example":"pt_BR"},"url_button":{"type":"string","example":"true"},"params":{"type":"array","items":{"type":"string"},"example":["contact_name","title","datetime"]},"body_params":{"type":"array","items":{"type":"string"},"description":"Legacy name for `params`, still read.","example":["contact_name","title","datetime"]}}}}},"example":{"conversation_id":"42","type":"reminder","locale":"pt_BR","body":"Olá {{ contact_name }}, seu {{ title }} é em {{ datetime }}.","scope":"event_type:9","whatsapp_template":{"name":"agenda_reminder_pt_br","language":"pt_BR","url_button":"true","params":["contact_name","title","datetime"],"body_params":["contact_name","title","datetime"]}}}}}}},"/api/v1/accounts/{account_id}/whatsapp_web/authorizations/pair_phone":{"post":{"tags":["WhatsApp Web"],"operationId":"auto_post_api_v1_accounts_account_id_whatsapp_web_authorizations_pair_phone","summary":"Request a phone linking code","description":"Requests an 8-character phone-linking code from the gateway (/session/pairphone). The gateway envelope is returned verbatim; the code is under data.LinkingCode. Self-heals a reaped session by reconnecting once.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Gateway envelope carrying the linking code.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer","example":200},"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"LinkingCode":{"type":"string","description":"Enter this on the phone under Linked devices → Link with phone number.","example":"ABCD-EFGH"}}}}},"example":{"code":200,"success":true,"data":{"LinkingCode":"ABCD-EFGH"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"403":{"description":"The caller holds an access role that grants neither `inbox_manage` nor `whatsapp_hub_manage`. The request stops there: nothing is sent to the gateway and no linking code is requested. A signed-in caller who is not an administrator and holds no access role at all is answered 401 instead.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","enum":["forbidden"]}}},"example":{"error":"forbidden"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"phone":{"type":"string"},"provider_user_id":{"type":"integer"},"inbox_id":{"type":"integer"}}},"example":{"phone":"+5511999998888","provider_user_id":1,"inbox_id":1}}}}}},"/api/v1/accounts/{account_id}/whatsapp_web/authorizations/regions":{"get":{"tags":["WhatsApp Web"],"operationId":"auto_get_api_v1_accounts_account_id_whatsapp_web_authorizations_regions","summary":"List managed proxy regions for WhatsApp Web provisioning","description":"Returns the safe proxy-routing capabilities available to the current account. When the account feature is disabled, `enabled` is false and the region list is empty. Region entries expose country availability and provider count only; endpoints and credentials remain installation-scoped. feature_defaults contains visible platform defaults only, without selecting or reserving a gateway. Wizard choices are explicit per-inbox overrides; omitted creation feature keys still inherit gateway defaults as before.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Feature state and safe country choices for the inbox wizard.","content":{"application/json":{"schema":{"type":"object","required":["enabled","default","regions","providers_available"],"properties":{"enabled":{"type":"boolean","example":true},"default":{"type":"string","enum":["auto"],"example":"auto"},"providers_available":{"type":"integer","minimum":0,"example":2},"feature_defaults":{"type":"object","description":"Visible platform defaults used as explicit initial wizard choices; does not select a gateway.","properties":{"enable_groups":{"type":"boolean","example":true},"enable_newsletters":{"type":"boolean","example":true},"enable_broadcast":{"type":"boolean","example":false},"enable_status_broadcast_posting":{"type":"boolean","example":true},"enable_media_download":{"type":"boolean","example":true},"enable_auto_presence_unavailable":{"type":"boolean","example":false},"enable_history_sync":{"type":"boolean","example":true},"enable_history_media":{"type":"boolean","example":true},"enable_participant_contacts":{"type":"boolean","example":false},"enable_group_sender_contacts":{"type":"boolean","example":true},"skip_calls":{"type":"boolean","example":false},"history_backfill_count":{"type":"integer","example":1000},"call_reject_type":{"type":"string","enum":["busy","declined","unavailable"],"example":"busy"},"call_reject_message":{"type":"string","example":""}}},"regions":{"type":"array","items":{"type":"object","required":["code","label","provider_count","available"],"properties":{"code":{"type":"string","pattern":"^[A-Z]{2}$","example":"BR"},"label":{"type":"string","example":"BR"},"provider_count":{"type":"integer","minimum":0,"example":2},"available":{"type":"boolean","example":true}}}}}},"example":{"enabled":true,"default":"auto","providers_available":2,"regions":[{"code":"BR","label":"BR","provider_count":2,"available":true}],"feature_defaults":{"enable_groups":true,"enable_newsletters":true,"enable_broadcast":false,"enable_status_broadcast_posting":true,"enable_media_download":true,"enable_auto_presence_unavailable":false,"enable_history_sync":true,"enable_history_media":true,"enable_participant_contacts":false,"enable_group_sender_contacts":true,"skip_calls":false,"history_backfill_count":1000,"call_reject_type":"busy","call_reject_message":""}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"403":{"description":"The caller holds an access role that grants neither `inbox_manage` nor `whatsapp_hub_manage`. The request stops there: no routing capability is returned. A signed-in caller who is not an administrator and holds no access role at all is answered 401 instead.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","enum":["forbidden"]}}},"example":{"error":"forbidden"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/whatsapp_web/authorizations/{id}/connect":{"post":{"tags":["WhatsApp Web"],"operationId":"auto_post_api_v1_accounts_account_id_whatsapp_web_authorizations_id_connect","summary":"Connect a WhatsApp Web session","description":"Asks the WazMeow gateway to start or resume the session of this inbox, subscribing to every event so a QR code or the pairing confirmation is delivered as soon as it is ready. A session the gateway reports as already connected counts as success. The QR pump is restarted on every call. A rejected, timed-out or unreachable gateway returns 422 and is never announced as a successful connection.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The gateway accepted the connection request, or reported the session as already connected. Live health or the Connected event confirms connectivity.","content":{"application/json":{"schema":{"type":"object","required":["success","channel_id","code"],"properties":{"success":{"type":"boolean","enum":[true]},"channel_id":{"type":"integer","description":"Identifier of the WhatsApp Web channel the request was sent for."},"code":{"type":"integer","description":"HTTP status the gateway answered with. Usually 2xx; a gateway that reports the session as already connected may answer with an error status and still succeed."}}},"example":{"success":true,"channel_id":42,"code":200}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"403":{"description":"The caller holds an access role that grants neither `inbox_manage` nor `whatsapp_hub_manage`. The request stops there: nothing is sent to the gateway and the session is left as it was. A signed-in caller who is not an administrator and holds no access role at all is answered 401 instead.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","enum":["forbidden"]}}},"example":{"error":"forbidden"}}}},"422":{"description":"The gateway rejected the connection request, timed out or could not be reached.","content":{"application/json":{"schema":{"type":"object","required":["success","channel_id","code"],"properties":{"success":{"type":"boolean","enum":[false]},"channel_id":{"type":"integer","description":"Identifier of the WhatsApp Web channel the request was sent for."},"code":{"type":["integer","null"],"description":"HTTP status the gateway answered with. Null when the gateway did not answer at all (timeout, refused or reset connection, unresolvable host)."}}},"example":{"success":false,"channel_id":42,"code":500}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"provider_user_id":{"type":"integer"},"inbox_id":{"type":"integer"}}},"example":{"provider_user_id":1,"inbox_id":1}}}}}},"/api/v1/accounts/{account_id}/whatsapp_web/authorizations/{id}/disconnect":{"post":{"tags":["WhatsApp Web"],"operationId":"auto_post_api_v1_accounts_account_id_whatsapp_web_authorizations_id_disconnect","summary":"Pause a WhatsApp Web session without unlinking the device","description":"Asks the WazMeow gateway to close the WhatsApp connection of this inbox while keeping the device link, so a later connect resumes the same paired account without a new QR code. The QR pump is stopped first. A rejected, timed-out or unreachable gateway returns 422 and is never announced as a successful pause.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The gateway paused the session; the device stays linked.","content":{"application/json":{"schema":{"type":"object","required":["success","code"],"properties":{"success":{"type":"boolean","enum":[true]},"code":{"type":"integer","description":"HTTP status the gateway answered with, always 2xx on success."}}},"example":{"success":true,"code":200}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"403":{"description":"The caller holds an access role that grants neither `inbox_manage` nor `whatsapp_hub_manage`. The request stops there: nothing is sent to the gateway and the session is left as it was. A signed-in caller who is not an administrator and holds no access role at all is answered 401 instead.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","enum":["forbidden"]}}},"example":{"error":"forbidden"}}}},"422":{"description":"The gateway rejected the pause request, timed out or could not be reached.","content":{"application/json":{"schema":{"type":"object","required":["success","code"],"properties":{"success":{"type":"boolean","enum":[false]},"code":{"type":["integer","null"],"description":"HTTP status the gateway answered with. Null when the gateway did not answer at all (timeout, refused or reset connection, unresolvable host)."}}},"example":{"success":false,"code":500}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"provider_user_id":{"type":"integer"},"inbox_id":{"type":"integer"}}},"example":{"provider_user_id":1,"inbox_id":1}}}}}},"/api/v1/accounts/{account_id}/whatsapp_web/authorizations/{id}/logout":{"post":{"tags":["WhatsApp Web"],"operationId":"auto_post_api_v1_accounts_account_id_whatsapp_web_authorizations_id_logout","summary":"Log out and unlink the WhatsApp Web device","description":"Asks the WazMeow gateway to log this inbox out of WhatsApp: the device leaves the phone's linked-devices list and the next connect has to go through a new QR pairing. The QR pump is stopped first. On success the inbox is flagged as requiring reauthorization. A rejected, timed-out or unreachable gateway returns 422 and the inbox is not flagged.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The gateway logged the session out and the inbox now requires reauthorization.","content":{"application/json":{"schema":{"type":"object","required":["success","code"],"properties":{"success":{"type":"boolean","enum":[true]},"code":{"type":"integer","description":"HTTP status the gateway answered with, always 2xx on success."}}},"example":{"success":true,"code":200}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"403":{"description":"The caller holds an access role that grants neither `inbox_manage` nor `whatsapp_hub_manage`. The request stops there: nothing is sent to the gateway and the session is left as it was. A signed-in caller who is not an administrator and holds no access role at all is answered 401 instead.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","enum":["forbidden"]}}},"example":{"error":"forbidden"}}}},"422":{"description":"The gateway rejected the logout request, timed out or could not be reached.","content":{"application/json":{"schema":{"type":"object","required":["success","code"],"properties":{"success":{"type":"boolean","enum":[false]},"code":{"type":["integer","null"],"description":"HTTP status the gateway answered with. Null when the gateway did not answer at all (timeout, refused or reset connection, unresolvable host)."}}},"example":{"success":false,"code":500}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"provider_user_id":{"type":"integer"},"inbox_id":{"type":"integer"}}},"example":{"provider_user_id":1,"inbox_id":1}}}}}},"/api/v1/accounts/{account_id}/whatsapp_web/authorizations/{id}/reauthorize":{"post":{"tags":["WhatsApp Web"],"operationId":"auto_post_api_v1_accounts_account_id_whatsapp_web_authorizations_id_reauthorize","summary":"Request soft reconnection or explicitly restart pairing","description":"Soft reconnection is the default and never logs out. force_logout=true explicitly unlinks the device. Successful request acceptance does not clear an authoritative authorization-loss marker; Connected does. HTTP errors at disconnect, logout or connect return 422 rather than a false success.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Reconnection request accepted; connectivity remains subject to live confirmation.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"channel_id":{"type":"integer"},"force_logout":{"type":"boolean"}}},"example":{"success":true,"channel_id":1,"force_logout":true}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"403":{"description":"The caller holds an access role that grants neither `inbox_manage` nor `whatsapp_hub_manage`. The request stops there: nothing is sent to the gateway and the session is left as it was. A signed-in caller who is not an administrator and holds no access role at all is answered 401 instead.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","enum":["forbidden"]}}},"example":{"error":"forbidden"}}}},"422":{"description":"The gateway did not accept the requested recovery step.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"channel_id":{"type":"integer"},"force_logout":{"type":"boolean"}}},"example":{"success":false,"channel_id":1,"force_logout":true}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"force_logout":{"type":"string"},"provider_user_id":{"type":"integer"},"inbox_id":{"type":"integer"}}},"example":{"force_logout":"sample force logout","provider_user_id":1,"inbox_id":1}}}}}},"/api/v1/accounts/{account_id}/whatsapp_web/authorizations/{id}/retry_qr":{"post":{"tags":["WhatsApp Web"],"operationId":"auto_post_api_v1_accounts_account_id_whatsapp_web_authorizations_id_retry_qr","summary":"Retry WhatsApp Web connection without unlinking the paired device","description":"Calls connect without logout. Restarts the QR pump only after a successful gateway response. A gateway rejection or timeout returns 422 and preserves existing authorization and pump state.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Connection request accepted; live health or Connected event confirms connectivity.","content":{"application/json":{"schema":{"type":"object","required":["success","channel_id"],"properties":{"success":{"type":"boolean","enum":[true]},"channel_id":{"type":"integer"}}},"example":{"success":true,"channel_id":1}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"403":{"description":"The caller holds an access role that grants neither `inbox_manage` nor `whatsapp_hub_manage`. The request stops there: nothing is sent to the gateway and the session is left as it was. A signed-in caller who is not an administrator and holds no access role at all is answered 401 instead.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","enum":["forbidden"]}}},"example":{"error":"forbidden"}}}},"422":{"description":"The gateway did not accept the connection request.","content":{"application/json":{"schema":{"type":"object","required":["success","error"],"properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string","enum":["connect_failed"]}}},"example":{"success":false,"error":"connect_failed"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"provider_user_id":{"type":"integer"},"inbox_id":{"type":"integer"}}},"example":{"provider_user_id":1,"inbox_id":1}}}}}},"/api/v1/accounts/{account_id}/whatsapp_web/authorizations/{id}/sync_features":{"post":{"tags":["WhatsApp Web"],"operationId":"auto_post_api_v1_accounts_account_id_whatsapp_web_authorizations_id_sync_features","summary":"Sync features authorizations","description":"Performs the sync features operation on the targeted authorization resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"success":{"type":"string"},"channel_id":{"type":"integer"},"applied":{"type":"string"}}},{"type":"object","properties":{"success":{"type":"boolean","example":false},"channel_id":{"type":"integer"},"applied":{"type":"array","items":{"type":"string"}},"error":{"type":"string"}}}]},"example":{"success":"sample success","channel_id":1,"applied":"sample applied"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"403":{"description":"The caller holds an access role that grants neither `inbox_manage` nor `whatsapp_hub_manage`. The request stops there: nothing is sent to the gateway and the stored feature settings are not re-applied. A signed-in caller who is not an administrator and holds no access role at all is answered 401 instead.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","enum":["forbidden"]}}},"example":{"error":"forbidden"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"provider_user_id":{"type":"integer"},"inbox_id":{"type":"integer"}}},"example":{"provider_user_id":1,"inbox_id":1}}}}}},"/api/v1/accounts/{account_id}/whatsapp_web/authorizations/{id}/update_features":{"patch":{"tags":["WhatsApp Web"],"operationId":"auto_patch_api_v1_accounts_account_id_whatsapp_web_authorizations_id_update_features","summary":"Update WhatsApp Web inbox feature toggles","description":"Persists the per-inbox Recursos toggles into provider_config.features. The body is SHALLOW-MERGED over the stored object, so omitting a key keeps its current value — it does NOT reset it — and keys outside the permitted set are dropped. Two of the toggles decide whether group/community people become platform Contacts, and they are independent with opposite defaults: enable_participant_contacts (member-list/roster import, off unless explicitly true) and enable_group_sender_contacts (whoever sends inside a @g.us chat, on unless explicitly false). See the features schema for the full toggle list. The gateway apply is best-effort: a gateway failure is logged and does not flip success, because the after_update_commit job re-applies idempotently.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The stored feature object after the merge.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"features":{"type":"object","additionalProperties":true,"description":"provider_config.features after the shallow merge."},"error":{"type":"string","description":"Present only when success is false."}}},"example":{"success":true,"features":{},"error":"sample error"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"403":{"description":"The caller holds an access role that grants neither `inbox_manage` nor `whatsapp_hub_manage`. The request stops there: nothing is saved and nothing is sent to the gateway. A signed-in caller who is not an administrator and holds no access role at all is answered 401 instead.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","enum":["forbidden"]}}},"example":{"error":"forbidden"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["features"],"properties":{"provider_user_id":{"type":"string","description":"Alternative channel lookup by the gateway user id, used when the path id does not match a channel.","example":"9d19f6e22fb9b3bfb87119f34698b314"},"inbox_id":{"type":"integer","description":"Alternative channel lookup by the WhatsApp Web inbox id.","example":42},"features":{"type":"object","description":"Toggles to merge into provider_config.features. Only the keys below are permitted; each omitted key keeps its stored value.","properties":{"enable_groups":{"type":"boolean","example":true},"enable_newsletters":{"type":"boolean","example":true},"enable_broadcast":{"type":"boolean","example":false},"enable_auto_presence_unavailable":{"type":"boolean","example":false},"enable_history_sync":{"type":"boolean","example":true},"enable_history_media":{"type":"boolean","example":true},"history_backfill_count":{"type":"integer","description":"Most recent messages imported per chat on a history backfill.","example":1000},"enable_participant_contacts":{"type":"boolean","description":"Import the group/community member list as Contacts. Off unless explicitly true.","example":false},"enable_group_sender_contacts":{"type":"boolean","description":"Create a Contact for whoever sends inside a group/community. On unless explicitly false.","example":true},"enable_status_broadcast_posting":{"type":"boolean","example":true},"skip_calls":{"type":"boolean","description":"Reject incoming calls on the gateway.","example":false},"call_reject_type":{"type":"string","enum":["busy","declined","unavailable"],"description":"Hang-up reason shown to the caller when skip_calls is true.","example":"busy"},"call_reject_message":{"type":"string","description":"Message sent to the caller after a rejected call when skip_calls is true.","example":""}}}}},"example":{"features":{"enable_groups":true,"enable_newsletters":true,"enable_broadcast":false,"enable_auto_presence_unavailable":false,"enable_history_sync":true,"enable_history_media":true,"history_backfill_count":1000,"enable_participant_contacts":false,"enable_group_sender_contacts":true,"enable_status_broadcast_posting":true,"skip_calls":false,"call_reject_type":"busy","call_reject_message":""},"provider_user_id":"9d19f6e22fb9b3bfb87119f34698b314","inbox_id":42}}}}}},"/api/v1/accounts/{account_id}/whatsapp_web/authorizations/{id}/route":{"patch":{"tags":["WhatsApp Web"],"operationId":"auto_patch_api_v1_accounts_account_id_whatsapp_web_authorizations_id_route","summary":"Change the egress route of a provisioned inbox","description":"Moves a live inbox onto a different managed-proxy region, onto a different enrolled phone, or back to direct egress through the server itself. `direct` releases a managed-proxy assignment and is deliberately not gated by the `whatsapp_web_proxy` account feature, so disabling that feature cannot trap an inbox on its previous proxy. A phone route is released explicitly with `mode: proxy`: the gateway revokes the phone route before the platform changes local state, then the inbox moves to the requested managed proxy or to direct egress when the proxy feature is no longer enabled. `mode: direct` does not bypass that guarded phone-release flow and returns 422 when used directly on a phone route. Releasing a phone route is never automatic or a fallback, because the peer starts seeing a different exit IP. A gateway refusal leaves the previous route intact on both sides. Responds 409 when the route fencing token changes during the request.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The route now in force for this inbox.","content":{"application/json":{"schema":{"type":"object","required":["channel_id"],"properties":{"channel_id":{"type":"integer","example":21},"network_route":{"type":["object","null"],"properties":{"desired_mode":{"type":"string","enum":["direct","managed_proxy","mobile_egress"]},"applied_mode":{"type":"string","enum":["direct","managed_proxy","mobile_egress"]},"retry_reason":{"type":["string","null"],"description":"Sanitized route reconciliation reason."},"next_retry_at":{"type":["string","null"],"format":"date-time"},"last_attempt_at":{"type":["string","null"],"format":"date-time"},"attempts":{"type":"integer","minimum":0},"transport_recovery_pending":{"type":"boolean"},"transport_next_retry_at":{"type":["string","null"],"format":"date-time"},"transport_recovery_reason":{"type":["string","null"],"description":"Sanitized connection recovery reason."},"status":{"type":"string","enum":["reserved","active","degraded","direct_fallback","released"],"example":"active"},"route_type":{"type":"string","enum":["managed_proxy","mobile_egress","direct"],"example":"mobile_egress"},"route_version":{"type":"integer","minimum":1,"example":2},"fallback_policy":{"type":"string","enum":["hold","managed_proxy","direct_allowed"],"example":"hold"},"fail_closed":{"type":"boolean","example":true},"provider":{"type":["string","null"],"description":"Managed-proxy provider. Null on a phone route, which has no proxy provider.","enum":["webshare","bright_data","custom",null],"example":null},"region":{"type":["string","null"],"example":null},"proxied":{"type":"boolean","example":false},"mobile_egress":{"type":"boolean","example":true},"fallback":{"type":"boolean","example":false}}},"route_released":{"type":"boolean","description":"True when this change dropped a phone route. The key is omitted entirely when it did not — which reads the same as false — because promising a release to a caller that merely swapped proxy regions would be a lie about where the traffic now exits.","example":true},"reconnect_scheduled":{"type":"boolean","description":"Only meaningful alongside `route_released`, and omitted with it. True means the gateway had to close the session to tear the route down and has already scheduled the reconnect, so a FRESH QR is coming and the screen must point at it. False means the session was not holding the route and nothing has to be paired again.","example":true}}},"examples":{"phone_selected":{"summary":"Inbox moved onto an enrolled phone","value":{"channel_id":21,"network_route":{"status":"active","route_type":"mobile_egress","route_version":2,"fallback_policy":"hold","fail_closed":true,"provider":null,"region":null,"proxied":false,"mobile_egress":true,"fallback":false,"desired_mode":"direct","applied_mode":"direct","retry_reason":"sample retry reason","next_retry_at":"2026-01-15T10:30:00.000Z","last_attempt_at":"2026-01-15T10:30:00.000Z","attempts":1,"transport_recovery_pending":true,"transport_next_retry_at":"2026-01-15T10:30:00.000Z","transport_recovery_reason":"sample transport recovery reason"},"route_released":false,"reconnect_scheduled":false}},"phone_route_released":{"summary":"Phone route dropped; inbox back on a managed proxy, fresh QR coming","value":{"channel_id":21,"network_route":{"status":"active","route_type":"managed_proxy","route_version":3,"fallback_policy":"hold","fail_closed":true,"provider":"webshare","region":"BR","proxied":true,"mobile_egress":false,"fallback":false,"desired_mode":"direct","applied_mode":"direct","retry_reason":"sample retry reason","next_retry_at":"2026-01-15T10:30:00.000Z","last_attempt_at":"2026-01-15T10:30:00.000Z","attempts":1,"transport_recovery_pending":true,"transport_next_retry_at":"2026-01-15T10:30:00.000Z","transport_recovery_reason":"sample transport recovery reason"},"route_released":true,"reconnect_scheduled":true}}}}}},"401":{"description":"The caller is not authorized for this action: not an account administrator, and without an access role that is allowed it. An access role that grants neither inbox nor WhatsApp-hub management is answered 403, not 401.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Sentence for the operator, already translated to the account locale."}}},"example":{"error":"You are not authorized to do this action"}}}},"404":{"description":"No WhatsApp Web inbox with this identifier belongs to the current account. The response has no body."},"403":{"description":"Two refusals share this status. The caller holds an access role that grants neither `inbox_manage` nor `whatsapp_hub_manage`: the body is `error: forbidden` with no `error_code`, the check runs before anything else and the route is left as it was. Or the account feature required by the requested route mode is disabled: `error` is a sentence for the operator and `error_code` is `feature_not_enabled`. A signed-in caller who is not an administrator and holds no access role at all is answered 401 instead, and so is a holder of one of those permissions whose role is scoped to teams or inboxes rather than the whole account.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"The literal `forbidden` on the access-role refusal; otherwise a sentence for the operator.","example":"This route option is not enabled for the account."},"error_code":{"type":"string","enum":["feature_not_enabled"],"description":"Present only on the feature refusal.","example":"feature_not_enabled"}}},"example":{"error":"This route option is not enabled for the account.","error_code":"feature_not_enabled"}}}},"409":{"description":"The gateway route fencing token moved during the change, or the requested phone has no free capacity. Refresh and retry; nothing was changed.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"code":{"type":"string","description":"Stable symbol for this refusal — the dashboard maps it to copy and to an affordance.","enum":["stale_route_version","capacity_exhausted","device_has_active_lease"]}}},"example":{"error":"The mobile route changed while this operation was running. Refresh and try again.","code":"stale_route_version"}}}},"422":{"description":"The requested mode, phone, or account configuration cannot serve this change. Repeating the same request cannot succeed — something has to be corrected first.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"code":{"type":"string","description":"Stable symbol for this refusal — the dashboard maps it to copy and to an affordance.","enum":["route_mode_invalid","device_not_found","configuration","feature_disabled","account_mismatch","channel_has_active_lease","already_claimed","invalid_credentials","tailnet_not_found","oauth_token_not_issued","provider_response_malformed","device_inventory_invalid","exit_routes_not_enabled","route_key_not_issued"]}}},"example":{"error":"Choose a managed proxy or a phone as the exit route.","code":"route_mode_invalid"}}}},"503":{"description":"No safe route could be reserved, the gateway did not become ready, the gateway refused to drop the phone route, or the request ran out of time budget before the hop could start safely. The previous route is unchanged on both sides, so the same call can be retried. `reason` carries the gateway's own code when it reported one.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"code":{"type":"string","description":"Stable symbol for this refusal. `timeout_budget_exhausted` means the hop never started; the managed-proxy symbols come from the endpoint allocator.","enum":["timeout_budget_exhausted","route_not_ready","network_error","provider_error","invalid_response","capacity_unavailable","allocation_failed"]},"reason":{"type":"string","description":"Gateway error code, absent when the gateway did not report one.","example":"network_route_prepare_failed"}}},"example":{"error":"The phone route did not become ready. No direct connection was made.","code":"route_not_ready","reason":"network_route_prepare_failed"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["mode"],"properties":{"mode":{"type":"string","enum":["proxy","mobile_egress","direct"],"description":"`proxy` — managed-proxy region change. `mobile_egress` — route through an enrolled phone. `direct` — release the managed proxy and exit through the server IP; responds 200 with a null `network_route`, and is a no-op when the inbox already exits direct.","example":"mobile_egress"},"region":{"type":"string","pattern":"^(auto|[A-Z]{2})$","description":"Managed-proxy region. Only read when `mode` is `proxy`.","example":"BR"},"device_id":{"type":"string","format":"uuid","description":"Enrolled phone to route through. Required when `mode` is `mobile_egress`.","example":"7da824a9-4be1-4ff2-bf65-4bd0fa453918"},"fallback_policy":{"type":"string","enum":["hold"],"description":"Only the fail-closed hold policy is available for phone routes.","example":"hold"}}},"example":{"mode":"mobile_egress","device_id":"7da824a9-4be1-4ff2-bf65-4bd0fa453918","region":"BR","fallback_policy":"hold"}}}}}},"/api/v1/accounts/{account_id}/whatsapp_web/authorizations/{id}/egress_check":{"get":{"tags":["WhatsApp Web"],"operationId":"auto_get_api_v1_accounts_account_id_whatsapp_web_authorizations_id_egress_check","summary":"Egress check authorizations","description":"Performs the egress check operation on the targeted authorization resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The public IP the phone route is exiting through at this moment, observed by the gateway going out through the route itself — not the node that was configured.","content":{"application/json":{"schema":{"type":"object","required":["supported","checked_at"],"properties":{"egress_ip":{"type":["string","null"],"description":"Public IP observed through the route. Null when the probe could not run.","example":"189.40.65.119"},"supported":{"type":"boolean","description":"False when the gateway is too old to answer the probe, which is not a broken route.","example":true},"probe_error":{"type":["string","null"],"description":"Gateway-side probe failure code, when it ran and failed.","example":"network_route_egress_probe_failed"},"checked_at":{"type":"string","format":"date-time","description":"When the observation was made. An IP without a timestamp is a claim without validity.","example":"2026-08-17T19:41:07Z"},"route":{"type":"object","description":"The route state at observation time.","properties":{"status":{"type":"string","enum":["preparing","ready","blocked"],"example":"ready"},"ready":{"type":"boolean","example":true},"exit_node_id":{"type":"string","example":"n9GxYx7EYB21CNTRL"},"fail_closed":{"type":"boolean","example":false}},"additionalProperties":false}}},"example":{"egress_ip":"189.40.65.119","supported":true,"probe_error":null,"checked_at":"2026-08-17T19:41:07Z","route":{"status":"ready","ready":true,"exit_node_id":"n9GxYx7EYB21CNTRL","fail_closed":false}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"403":{"description":"The caller holds an access role that grants neither `inbox_manage` nor `whatsapp_hub_manage`. The request stops there: the gateway is not asked. A signed-in caller who is not an administrator and holds no access role at all is answered 401 instead.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","enum":["forbidden"]}}},"example":{"error":"forbidden"}}}},"422":{"description":"The inbox is not on a phone route, so there is no phone exit to observe.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","example":"This inbox is not on a phone route, so there is no phone exit to check."}}},"example":{"error":"This inbox is not on a phone route, so there is no phone exit to check."}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/whatsapp_web/authorizations":{"post":{"tags":["WhatsApp Web"],"operationId":"auto_post_api_v1_accounts_account_id_whatsapp_web_authorizations","summary":"Provision a WhatsApp Web inbox","description":"Creates a whatsapp_web Channel::Whatsapp (auto-provisions a WazMeow gateway user via the resolved WazmeowInstance) and returns the serialized channel plus the initial QR image so the pairing wizard can render it inside the 201 response. `mode: direct` explicitly creates the inbox without a proxy, even if proxy providers are configured. The explicit direct preference survives pairing and automatic reconciliation until a successful operator-requested route change. `mode: proxy` requires the managed-proxy feature and available capacity; it never substitutes direct routing. When mode is omitted, legacy allocation behavior is preserved: no configured provider permits direct provisioning, while a configured but unavailable provider fails closed. With proxy routing, `proxy_region` reserves an installation-managed endpoint before the gateway user is created. `auto` selects by account signals and is refined from the phone DDI after pairing. If no managed capacity exists, provisioning stops with 503; it never silently uses the platform server IP. Alternatively, `mobile_egress_device_id` binds this inbox to an enrolled phone owned by the same account. Mobile provisioning is TCP-only, forces WhatsApp calls off, accepts only the fail-closed `hold` policy, and reaches 201 only after WazMeow confirms the exact route version as ready. A selected mobile device takes precedence over `proxy_region`. Provider, gateway, enrollment, and route bootstrap credentials are never returned; provider_config is masked.","security":[{"userApiKey":[]}],"responses":{"401":{"description":"The caller is not authorized for this action: not an account administrator, and without an access role that is allowed it. An access role that grants neither inbox nor WhatsApp-hub management is answered 403, not 401.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Sentence for the operator, already translated to the account locale."}}},"example":{"error":"You are not authorized to do this action"}}}},"404":{"description":"Account or resource not found"},"201":{"description":"The provisioned channel plus the first pairing QR (data URI) or null.","content":{"application/json":{"schema":{"type":"object","properties":{"channel_id":{"type":"integer","example":42},"inbox_id":{"type":"integer","example":87},"pubsub_token":{"type":"string","example":"kj3h4kjh34kjh34"},"provider":{"type":"string","example":"whatsapp_web","enum":["whatsapp_web"],"description":"Channel provider (WhatsApp Web via the WazMeow gateway)."},"provider_user_id":{"type":"string","description":"WazMeow gateway user id linked to this channel.","example":"9d19f6e22fb9b3bfb87119f34698b314"},"phone_number":{"type":"string","description":"E.164 once paired; a `pending:\u003cid\u003e` placeholder before pairing.","example":"pending:87"},"inbox":{"type":"object","properties":{"id":{"type":"integer","example":87},"name":{"type":"string","example":"WhatsApp Web"},"account_id":{"type":"integer","example":1}}},"provider_config":{"type":"object","description":"Masked provider config — api_key/admin_token/webhook_verify_token are stripped and surfaced as has_api_key/has_admin_token booleans.","additionalProperties":true,"properties":{"wazmeow_url":{"type":"string","example":"https://go.example.com"},"has_api_key":{"type":"boolean","example":true},"has_admin_token":{"type":"boolean","example":true},"features":{"type":"object","additionalProperties":true,"description":"WhatsApp Web (WazMeow gateway) per-inbox feature toggles, stored in provider_config.features. update_features SHALLOW-MERGES this object, so an omitted key keeps its stored value and any key outside the list below is ignored. Booleans: enable_groups, enable_newsletters, enable_broadcast, enable_history_sync, enable_history_media, enable_auto_presence_unavailable, skip_calls. history_backfill_count (integer, messages backfilled per chat on HistorySync). call_reject_type (busy | declined | unavailable) and call_reject_message (string) apply when skip_calls is true. Two INDEPENDENT contact toggles with OPPOSITE defaults: enable_participant_contacts governs importing the group/community MEMBER LIST (roster) as Contacts and is OFF unless explicitly true; enable_group_sender_contacts governs whether whoever SENDS a message inside a @g.us group/community becomes a Contact and is ON unless explicitly false (turning it off keeps the message and the sender name and phone on the bubble, it only stops the Contact from being created)."}}},"qr_code":{"type":["string","null"],"description":"data:image/png;base64 QR image, or null if not ready yet.","example":"data:image/png;base64,iVBORw0KGgoAAAANS..."},"proxy":{"type":["object","null"],"description":"Safe managed-proxy assignment summary, or null for direct/mobile provisioning.","properties":{"desired_mode":{"type":"string","enum":["direct","managed_proxy","mobile_egress"]},"applied_mode":{"type":"string","enum":["direct","managed_proxy","mobile_egress"]},"retry_reason":{"type":["string","null"],"description":"Sanitized route reconciliation reason."},"next_retry_at":{"type":["string","null"],"format":"date-time"},"last_attempt_at":{"type":["string","null"],"format":"date-time"},"attempts":{"type":"integer","minimum":0},"transport_recovery_pending":{"type":"boolean"},"transport_next_retry_at":{"type":["string","null"],"format":"date-time"},"transport_recovery_reason":{"type":["string","null"],"description":"Sanitized connection recovery reason."},"status":{"type":"string","enum":["reserved","active","degraded","direct_fallback","released"],"example":"active"},"route_type":{"type":"string","enum":["managed_proxy","mobile_egress","direct"],"example":"managed_proxy"},"route_version":{"type":"integer","minimum":1,"example":1},"fallback_policy":{"type":"string","enum":["hold","managed_proxy","direct_allowed"],"example":"hold"},"fail_closed":{"type":"boolean","example":true},"provider":{"type":["string","null"],"enum":["webshare","bright_data","custom",null],"example":"webshare","description":"Channel provider (WhatsApp Web via the WazMeow gateway)."},"region":{"type":["string","null"],"example":"BR"},"proxied":{"type":"boolean","example":true},"mobile_egress":{"type":"boolean","example":false},"fallback":{"type":"boolean","example":false}}},"network_route":{"type":["object","null"],"description":"Safe summary of the active managed or mobile network route. It never contains proxy URLs, Tailscale keys, SOCKS credentials, or gateway tokens.","properties":{"desired_mode":{"type":"string","enum":["direct","managed_proxy","mobile_egress"]},"applied_mode":{"type":"string","enum":["direct","managed_proxy","mobile_egress"]},"retry_reason":{"type":["string","null"],"description":"Sanitized route reconciliation reason."},"next_retry_at":{"type":["string","null"],"format":"date-time"},"last_attempt_at":{"type":["string","null"],"format":"date-time"},"attempts":{"type":"integer","minimum":0},"transport_recovery_pending":{"type":"boolean"},"transport_next_retry_at":{"type":["string","null"],"format":"date-time"},"transport_recovery_reason":{"type":["string","null"],"description":"Sanitized connection recovery reason."},"status":{"type":"string","enum":["reserved","active","degraded","direct_fallback","released"],"example":"active"},"route_type":{"type":"string","enum":["managed_proxy","mobile_egress","direct"],"example":"mobile_egress"},"route_version":{"type":"integer","minimum":1,"example":1},"fallback_policy":{"type":"string","enum":["hold","managed_proxy","direct_allowed"],"example":"hold"},"fail_closed":{"type":"boolean","example":true},"provider":{"type":["string","null"],"enum":["webshare","bright_data","custom",null],"example":null,"description":"Channel provider (WhatsApp Web via the WazMeow gateway)."},"region":{"type":["string","null"],"example":null},"proxied":{"type":"boolean","example":false},"mobile_egress":{"type":"boolean","example":true},"fallback":{"type":"boolean","example":false}}},"session_pending":{"type":"boolean","description":"Present and true ONLY when the inbox was created but the request ran out of budget before the gateway session came up, so no QR was produced. The wizard must stop waiting for a QR that nobody asked for and offer the existing \"generate a new QR\" action instead. Absent on a normal provisioning.","example":true},"session_pending_code":{"type":"string","description":"Why the session is still pending, using the same vocabulary as every other mobile-egress failure so the screen picks copy and affordance the same way. Present exactly when `session_pending` is.","enum":["timeout_budget_exhausted"],"example":"timeout_budget_exhausted"}},"example":{"channel_id":42,"inbox_id":87,"pubsub_token":"kj3h4kjh34kjh34","provider":"whatsapp_web","provider_user_id":"9d19f6e22fb9b3bfb87119f34698b314","phone_number":"pending:wweb:2e2b1f0c-4574-43e8-b230-ccbd3886ab70","inbox":{"id":87,"name":"WhatsApp Sales","account_id":1},"provider_config":{"wazmeow_url":"https://gateway.example.com","has_api_key":true,"features":{"enable_groups":true}},"qr_code":null,"proxy":null,"network_route":{"status":"active","route_type":"mobile_egress","route_version":1,"fallback_policy":"hold","fail_closed":true,"provider":null,"region":null,"proxied":false,"mobile_egress":true,"fallback":false},"session_pending":true,"session_pending_code":"timeout_budget_exhausted"}},"example":{"channel_id":42,"inbox_id":87,"pubsub_token":"kj3h4kjh34kjh34","provider":"whatsapp_web","provider_user_id":"9d19f6e22fb9b3bfb87119f34698b314","phone_number":"pending:wweb:2e2b1f0c-4574-43e8-b230-ccbd3886ab70","inbox":{"id":87,"name":"WhatsApp Sales","account_id":1},"provider_config":{"wazmeow_url":"https://gateway.example.com","has_api_key":true,"features":{"enable_groups":true},"has_admin_token":true},"qr_code":null,"proxy":null,"network_route":{"status":"active","route_type":"mobile_egress","route_version":1,"fallback_policy":"hold","fail_closed":true,"provider":null,"region":null,"proxied":false,"mobile_egress":true,"fallback":false,"desired_mode":"direct","applied_mode":"direct","retry_reason":"sample retry reason","next_retry_at":"2026-01-15T10:30:00.000Z","last_attempt_at":"2026-01-15T10:30:00.000Z","attempts":1,"transport_recovery_pending":true,"transport_next_retry_at":"2026-01-15T10:30:00.000Z","transport_recovery_reason":"sample transport recovery reason"},"session_pending":true,"session_pending_code":"timeout_budget_exhausted"}}}},"403":{"description":"Two refusals share this status. The caller holds an access role that grants neither `inbox_manage` nor `whatsapp_hub_manage`: the body is `error: forbidden` with no `error_code`, the check runs before anything else and no inbox is provisioned. Or `mode: proxy` was requested while the managed-proxy feature is disabled for the account: `error` is a sentence for the operator and `error_code` is `feature_not_enabled`. A signed-in caller who is not an administrator and holds no access role at all is answered 401 instead, and so is a holder of one of those permissions whose role is scoped to teams or inboxes rather than the whole account.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"The literal `forbidden` on the access-role refusal; otherwise a sentence for the operator.","example":"This route option is not enabled for the account."},"error_code":{"type":"string","enum":["feature_not_enabled"],"description":"Present only on the feature refusal.","example":"feature_not_enabled"}}},"example":{"error":"This route option is not enabled for the account.","error_code":"feature_not_enabled"}}}},"409":{"description":"The selected phone has no free capacity, or the route fencing token moved underneath the request. Nothing was provisioned; the compensation already ran.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"code":{"type":"string","description":"Stable symbol for this refusal — the dashboard maps it to copy and to an affordance.","enum":["capacity_exhausted","device_has_active_lease","stale_route_version"]}}},"example":{"error":"This phone is already assigned to its allowed number of inboxes.","code":"capacity_exhausted"}}}},"422":{"description":"The selected phone, account configuration, fallback policy, or gateway credentials are invalid. Repeating the same request cannot succeed — something has to be corrected first. `error_code` is the historical field and is kept; `code` is the one the dashboard reads.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"error_code":{"type":["string","null"],"enum":["invalid_gateway_credentials",null],"example":"invalid_gateway_credentials"},"code":{"type":"string","description":"Stable symbol for this refusal. Absent only when the request is rejected before the provisioning logic runs (a model validation answers the framework's standard `{ message, attributes }` envelope instead).","enum":["invalid_gateway_credentials","missing_credentials","record_invalid","feature_disabled","configuration","device_not_found","account_mismatch","channel_has_active_lease","already_claimed","invalid_credentials","tailnet_not_found","oauth_token_not_issued","provider_response_malformed","device_inventory_invalid","exit_routes_not_enabled","route_key_not_issued"]}}},"example":{"error":"The WhatsApp Web service credentials are invalid. Ask the platform operator to check them.","error_code":"invalid_gateway_credentials","code":"invalid_gateway_credentials"}}}},"502":{"description":"WazMeow was reachable but could not provision the gateway user or event delivery.","content":{"application/json":{"schema":{"type":"object","required":["error","error_code"],"properties":{"error":{"type":"string","example":"The WhatsApp Web service could not create the connection."},"error_code":{"type":"string","enum":["gateway_provisioning_failed"],"example":"gateway_provisioning_failed"},"code":{"type":"string","enum":["gateway_provisioning_failed"],"example":"gateway_provisioning_failed"}}},"example":{"error":"The WhatsApp Web service could not create the connection.","error_code":"gateway_provisioning_failed","code":"gateway_provisioning_failed"}}}},"503":{"description":"No active online WazMeow instance exists, managed capacity is unavailable, the request ran out of time budget before a step could start, or the gateway did not prove the mobile route ready. Nothing was left half-created: the compensation runs before this is answered, and the same call tends to work in a less loaded moment — the affordance is \"try again\", not \"correct the connection\". `reason` carries the gateway's own code (`network_route_prepare_failed`, `network_route_exit_node_unavailable`, …) when it reported one. It exists because the translated `error` sentence is the same for every route failure, which made a refusal impossible to diagnose without server access.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","example":"The phone route did not become ready. No direct connection was made."},"error_code":{"type":["string","null"],"enum":["gateway_unavailable",null],"example":"gateway_unavailable"},"code":{"type":"string","description":"Stable symbol for this refusal. `timeout_budget_exhausted` means the step never started; the managed-proxy symbols come from the endpoint allocator.","enum":["gateway_unavailable","timeout_budget_exhausted","route_not_ready","network_error","provider_error","invalid_response","capacity_unavailable","allocation_failed"]},"reason":{"type":"string","description":"Gateway error code, absent when the gateway did not report one.","example":"network_route_prepare_failed"}}},"example":{"error":"No WhatsApp Web service is available right now. Ask the platform operator to check the gateways.","error_code":"gateway_unavailable","code":"gateway_unavailable","reason":"network_route_prepare_failed"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["inbox_name"],"properties":{"inbox_name":{"type":"string","minLength":3,"example":"WhatsApp Sales"},"mode":{"type":"string","enum":["direct","proxy","mobile_egress"],"description":"Explicit connection choice. Direct bypasses allocation; proxy fails closed if unavailable; mobile_egress requires mobile_egress_device_id. Conflicting choices are rejected. Omission preserves legacy behavior.","example":"direct"},"proxy_region":{"type":"string","pattern":"^(auto|[A-Z]{2})$","default":"auto","description":"Automatic routing or an ISO 3166-1 alpha-2 country code. Ignored when the account feature is disabled.","example":"BR"},"mobile_egress_device_id":{"type":"string","format":"uuid","description":"Public identifier of an online phone enrolled in this account. When present, mobile egress is used exclusively and proxy_region is ignored.","example":"7da824a9-4be1-4ff2-bf65-4bd0fa453918"},"mobile_egress_fallback_policy":{"type":"string","enum":["hold"],"default":"hold","description":"Fail-closed behavior while the phone route is unavailable; direct fallback is not accepted.","example":"hold"},"features":{"type":"object","additionalProperties":true,"description":"WhatsApp Web feature toggles accepted by the provisioning service."},"wazmeow_url":{"type":"string","format":"uri","description":"Optional per-inbox WazMeow gateway URL; omitted to use the installation pool.","example":"https://gateway.example.com"},"admin_token":{"type":"string","writeOnly":true,"description":"Required only when registering a new per-inbox WazMeow gateway URL.","example":"gateway-admin-token"}}},"example":{"inbox_name":"WhatsApp Sales","mobile_egress_device_id":"7da824a9-4be1-4ff2-bf65-4bd0fa453918","mobile_egress_fallback_policy":"hold","features":{"enable_groups":true,"enable_history_sync":false,"skip_calls":true},"mode":"direct","proxy_region":"BR","wazmeow_url":"https://gateway.example.com","admin_token":"gateway-admin-token"}}}}}},"/api/v1/accounts/{account_id}/whatsapp_web/mobile_egress/capabilities":{"get":{"tags":["WhatsApp Web"],"operationId":"auto_get_api_v1_accounts_account_id_whatsapp_web_mobile_egress_capabilities","summary":"Inspect phone-egress capabilities","description":"Returns whether this account may use phone egress, whether its Super Admin infrastructure is configured, the safe enrolled-phone inventory, and the pilot's fixed fail-closed policy. No Tailscale credential, invite link, node management identifier, or route bootstrap is exposed.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Safe phone-egress capability and inventory state.","content":{"application/json":{"schema":{"type":"object","required":["enabled","configured","available","status","devices_available","devices","policies"],"properties":{"enabled":{"type":"boolean","example":true},"configured":{"type":"boolean","example":true},"available":{"type":"boolean","description":"Whether phone egress can be used right now — the feature is on AND a configuration resolves and is active.","example":true},"unavailable_reason":{"type":["string","null"],"description":"WHY it cannot be used, as a symbol the screen maps to copy and to a next step. Null when it can. `feature_disabled` — only the operator can turn it on; `permission_missing` — a connection is missing or switched off and this caller cannot set it up; `configuration` — same, but this caller can fix it. It rides in the payload because the banners that used to explain it live inside a section that refuses to expand in exactly these states, leaving \"Unavailable\" and nothing else on screen.","enum":["feature_disabled","permission_missing","configuration",null],"example":null},"provider":{"type":["string","null"],"enum":["tailscale",null],"example":"tailscale"},"status":{"type":"string","enum":["unconfigured","unknown","online","offline","invalid_credentials"],"example":"online"},"configuration":{"description":"The resolved configuration, or null when the account has neither its own nor a shared one.","allOf":[{"type":"object","required":["id","provider","tailnet","active","status","scope","managed_by","credentials_configured"],"properties":{"id":{"type":"integer","example":12},"account_id":{"type":["integer","null"],"description":"Null on the operator's shared configuration, which belongs to no single account.","example":41},"provider":{"type":"string","enum":["tailscale"],"example":"tailscale"},"tailnet":{"type":"string","example":"acme.example.com"},"active":{"type":"boolean","example":true},"status":{"type":"string","enum":["unknown","online","offline","invalid_credentials"],"example":"online"},"scope":{"type":"string","enum":["account","global"],"description":"`account` — connected by this account. `global` — the operator default shared with every account that has not connected its own.","example":"account"},"managed_by":{"type":"string","enum":["operator","account"],"description":"Who may edit it. An `operator` row is read-only through this API and is changed in Super Admin.","example":"account"},"auth_key_tags":{"type":"array","description":"Tailscale tags applied to the ephemeral WazMeow exit-node keys. Must exist under `tagOwners` in the customer's own policy file.","items":{"type":"string","pattern":"^tag:[a-z0-9][a-z0-9-]{0,62}$"},"example":["tag:cw-egress-acct-41"]},"credentials_configured":{"type":"boolean","example":true},"authentication_mode":{"type":"string","enum":["oauth","api_access_token"],"example":"oauth"},"oauth_configured":{"type":"boolean","example":true},"api_access_token_configured":{"type":"boolean","description":"Whether a personal API access token is stored. A boolean, never the value. It matters on its own because no published Tailscale OAuth scope covers inviting a user, so an OAuth-only connection can read devices and mint route keys but can never invite a phone — and the setup screen has to be able to say so BEFORE the operator hits that wall mid-enrollment.","example":true},"api_access_token_expires_at":{"type":["string","null"],"format":"date-time","example":null},"credential_rotation_due":{"type":"boolean","example":false},"last_checked_at":{"type":["string","null"],"format":"date-time","example":"2026-08-18T09:00:00Z"},"capability_check":{"description":"The last pre-flight: the three capabilities this connection needs, each exercised for real, with the moment they were measured. Null until one has run. Capability names, verdicts, codes and a timestamp — never a credential value.","allOf":[{"type":"object","required":["ok","checked_at"],"properties":{"ok":{"type":"boolean","description":"True only when every capability passed. A capability that was not exercised keeps it false.","example":false},"device_count":{"type":["integer","null"],"minimum":0,"description":"Devices the inventory read returned. Absent when that capability was not exercised.","example":2},"tailnet":{"type":"string","example":"acme.example.com"},"authentication_mode":{"type":"string","enum":["oauth","api_access_token"],"example":"oauth"},"api_access_token_configured":{"type":"boolean","example":false},"api_access_token_expires_at":{"type":["string","null"],"format":"date-time","description":"Absent when no expiry is on record.","example":"2026-11-01T00:00:00Z"},"checked_at":{"type":"string","format":"date-time","example":"2026-08-18T09:00:00Z"},"capabilities":{"type":"object","description":"One verdict per capability. Absent when the whole probe failed before any capability could be exercised, in which case the top-level `error` and `code` are the only answer there is.","required":["devices_read","user_invite","route_key"],"properties":{"devices_read":{"type":"object","required":["ok"],"properties":{"ok":{"type":["boolean","null"],"description":"True passed, false failed, null not exercised (no budget left, or the provider refused the probe body).","example":true},"code":{"type":["string","null"],"description":"Why it did not pass. `not_checked` means it was never exercised. Absent when the capability passed.","enum":["not_checked","invite_permission_missing","invalid_credentials","device_inventory_invalid","route_key_not_issued","invite_not_created","invite_url_missing","tailnet_not_found","oauth_token_not_issued","provider_response_malformed","network_error","provider_error","configuration",null],"example":"not_checked"}}},"user_invite":{"type":"object","required":["ok"],"properties":{"ok":{"type":["boolean","null"],"description":"True passed, false failed, null not exercised (no budget left, or the provider refused the probe body).","example":true},"code":{"type":["string","null"],"description":"Why it did not pass. `not_checked` means it was never exercised. Absent when the capability passed.","enum":["not_checked","invite_permission_missing","invalid_credentials","device_inventory_invalid","route_key_not_issued","invite_not_created","invite_url_missing","tailnet_not_found","oauth_token_not_issued","provider_response_malformed","network_error","provider_error","configuration",null],"example":"not_checked"}}},"route_key":{"type":"object","required":["ok"],"properties":{"ok":{"type":["boolean","null"],"description":"True passed, false failed, null not exercised (no budget left, or the provider refused the probe body).","example":true},"code":{"type":["string","null"],"description":"Why it did not pass. `not_checked` means it was never exercised. Absent when the capability passed.","enum":["not_checked","invite_permission_missing","invalid_credentials","device_inventory_invalid","route_key_not_issued","invite_not_created","invite_url_missing","tailnet_not_found","oauth_token_not_issued","provider_response_malformed","network_error","provider_error","configuration",null],"example":"not_checked"}}}}},"error":{"type":["string","null"],"description":"The first failed capability's sentence, already redacted for display. Absent when everything passed.","example":"Tailscale refused the invite with HTTP 403"},"code":{"type":["string","null"],"description":"The first failed capability's code. Absent when everything passed.","example":"invite_permission_missing"}}}]}}}]},"can_configure":{"type":"boolean","description":"Whether this account may edit the configuration it resolves to. False for the operator's shared row and for a row the operator provisioned.","example":false},"setup_required":{"type":"boolean","description":"True when no configuration exists at all, so the dashboard offers the setup wizard.","example":false},"suggested_auth_key_tag":{"type":"string","description":"The per-account Tailscale tag quoted verbatim in the setup instructions.","pattern":"^tag:[a-z0-9][a-z0-9-]{0,62}$","example":"tag:cw-egress-acct-41"},"devices_available":{"type":"integer","minimum":0,"example":1},"devices":{"type":"array","items":{"type":"object","required":["id","name","platform","status","capacity","available_capacity"],"properties":{"id":{"type":"string","format":"uuid","example":"7da824a9-4be1-4ff2-bf65-4bd0fa453918"},"name":{"type":"string","example":"Guilherme Android"},"hostname":{"type":["string","null"],"example":"pixel-9"},"platform":{"type":"string","enum":["android","ios"],"example":"android"},"status":{"type":"string","enum":["pending","online","offline","paused","revoked"],"example":"online"},"capacity":{"type":"integer","minimum":1,"maximum":10,"example":1},"available_capacity":{"type":"integer","minimum":0,"example":1},"last_seen_at":{"type":["string","null"],"format":"date-time","example":"2026-08-15T07:00:00Z"},"approved_at":{"type":["string","null"],"format":"date-time","example":"2026-08-15T06:55:00Z"},"paused_at":{"type":["string","null"],"format":"date-time","example":null},"revoked_at":{"type":["string","null"],"format":"date-time","example":null}}}},"policies":{"type":"object","required":["default_fallback","fallback_options","tcp_only","calls_supported","default_capacity"],"properties":{"default_fallback":{"type":"string","enum":["hold"],"example":"hold"},"fallback_options":{"type":"array","items":{"type":"string","enum":["hold"]},"example":["hold"]},"tcp_only":{"type":"boolean","example":true},"calls_supported":{"type":"boolean","example":false},"default_capacity":{"type":"integer","minimum":1,"example":1}}}}},"example":{"enabled":true,"configured":true,"available":true,"unavailable_reason":null,"provider":"tailscale","status":"online","configuration":{"id":12,"account_id":41,"provider":"tailscale","tailnet":"acme.example.com","active":true,"status":"online","scope":"account","managed_by":"account","auth_key_tags":["tag:cw-egress-acct-41"],"credentials_configured":true,"authentication_mode":"oauth","oauth_configured":true,"api_access_token_expires_at":null,"api_access_token_configured":true,"credential_rotation_due":false,"last_checked_at":"2026-08-18T09:00:00Z","capability_check":{"ok":false,"device_count":2,"tailnet":"acme.example.com","authentication_mode":"oauth","api_access_token_configured":false,"api_access_token_expires_at":null,"checked_at":"2026-08-18T09:00:00Z","capabilities":{"devices_read":{"ok":true,"code":null},"user_invite":{"ok":false,"code":"invite_permission_missing"},"route_key":{"ok":true,"code":null}},"error":"Tailscale refused the invite with HTTP 403","code":"invite_permission_missing"}},"can_configure":true,"setup_required":false,"suggested_auth_key_tag":"tag:cw-egress-acct-41","devices_available":1,"devices":[{"id":"7da824a9-4be1-4ff2-bf65-4bd0fa453918","name":"Guilherme Android","hostname":"pixel-9","platform":"android","status":"online","capacity":1,"available_capacity":1,"last_seen_at":"2026-08-15T07:00:00Z","approved_at":"2026-08-15T06:55:00Z","paused_at":null,"revoked_at":null}],"policies":{"default_fallback":"hold","fallback_options":["hold"],"tcp_only":true,"calls_supported":false,"default_capacity":1}}}}},"401":{"description":"The caller is not authorized for this action: not an account administrator, and without an access role that is allowed it. An access role that grants neither inbox nor WhatsApp-hub management is answered 403, not 401.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Sentence for the operator, already translated to the account locale."}}},"example":{"error":"You are not authorized to do this action"}}}},"404":{"description":"Account or resource not found"},"403":{"description":"The caller holds an access role that grants neither `inbox_manage` nor `whatsapp_hub_manage`. The request stops before the action runs: nothing is changed and no provider is contacted.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","enum":["forbidden"]}}},"example":{"error":"forbidden"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/whatsapp_web/mobile_egress/configuration/test":{"post":{"tags":["WhatsApp Web"],"operationId":"auto_post_api_v1_accounts_account_id_whatsapp_web_mobile_egress_configuration_test","summary":"Test the phone-egress network credentials","description":"Reads the Tailscale device inventory with the stored credentials and persists the outcome, so the account learns the connection works before discovering the failure mid-enrolment. Responds 422 with the safe provider message when the credentials are rejected.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The configuration plus the result of the live pre-flight, which every capability passed.","content":{"application/json":{"schema":{"allOf":[{"type":"object","required":["id","provider","tailnet","active","status","scope","managed_by","credentials_configured"],"properties":{"id":{"type":"integer","example":12},"account_id":{"type":["integer","null"],"description":"Null on the operator's shared configuration, which belongs to no single account.","example":41},"provider":{"type":"string","enum":["tailscale"],"example":"tailscale"},"tailnet":{"type":"string","example":"acme.example.com"},"active":{"type":"boolean","example":true},"status":{"type":"string","enum":["unknown","online","offline","invalid_credentials"],"example":"online"},"scope":{"type":"string","enum":["account","global"],"description":"`account` — connected by this account. `global` — the operator default shared with every account that has not connected its own.","example":"account"},"managed_by":{"type":"string","enum":["operator","account"],"description":"Who may edit it. An `operator` row is read-only through this API and is changed in Super Admin.","example":"account"},"auth_key_tags":{"type":"array","description":"Tailscale tags applied to the ephemeral WazMeow exit-node keys. Must exist under `tagOwners` in the customer's own policy file.","items":{"type":"string","pattern":"^tag:[a-z0-9][a-z0-9-]{0,62}$"},"example":["tag:cw-egress-acct-41"]},"credentials_configured":{"type":"boolean","example":true},"authentication_mode":{"type":"string","enum":["oauth","api_access_token"],"example":"oauth"},"oauth_configured":{"type":"boolean","example":true},"api_access_token_configured":{"type":"boolean","description":"Whether a personal API access token is stored. A boolean, never the value. It matters on its own because no published Tailscale OAuth scope covers inviting a user, so an OAuth-only connection can read devices and mint route keys but can never invite a phone — and the setup screen has to be able to say so BEFORE the operator hits that wall mid-enrollment.","example":true},"api_access_token_expires_at":{"type":["string","null"],"format":"date-time","example":null},"credential_rotation_due":{"type":"boolean","example":false},"last_checked_at":{"type":["string","null"],"format":"date-time","example":"2026-08-18T09:00:00Z"},"capability_check":{"description":"The last pre-flight: the three capabilities this connection needs, each exercised for real, with the moment they were measured. Null until one has run. Capability names, verdicts, codes and a timestamp — never a credential value.","allOf":[{"type":"object","required":["ok","checked_at"],"properties":{"ok":{"type":"boolean","description":"True only when every capability passed. A capability that was not exercised keeps it false.","example":false},"device_count":{"type":["integer","null"],"minimum":0,"description":"Devices the inventory read returned. Absent when that capability was not exercised.","example":2},"tailnet":{"type":"string","example":"acme.example.com"},"authentication_mode":{"type":"string","enum":["oauth","api_access_token"],"example":"oauth"},"api_access_token_configured":{"type":"boolean","example":false},"api_access_token_expires_at":{"type":["string","null"],"format":"date-time","description":"Absent when no expiry is on record.","example":"2026-11-01T00:00:00Z"},"checked_at":{"type":"string","format":"date-time","example":"2026-08-18T09:00:00Z"},"capabilities":{"type":"object","description":"One verdict per capability. Absent when the whole probe failed before any capability could be exercised, in which case the top-level `error` and `code` are the only answer there is.","required":["devices_read","user_invite","route_key"],"properties":{"devices_read":{"type":"object","required":["ok"],"properties":{"ok":{"type":["boolean","null"],"description":"True passed, false failed, null not exercised (no budget left, or the provider refused the probe body).","example":true},"code":{"type":["string","null"],"description":"Why it did not pass. `not_checked` means it was never exercised. Absent when the capability passed.","enum":["not_checked","invite_permission_missing","invalid_credentials","device_inventory_invalid","route_key_not_issued","invite_not_created","invite_url_missing","tailnet_not_found","oauth_token_not_issued","provider_response_malformed","network_error","provider_error","configuration",null],"example":"not_checked"}}},"user_invite":{"type":"object","required":["ok"],"properties":{"ok":{"type":["boolean","null"],"description":"True passed, false failed, null not exercised (no budget left, or the provider refused the probe body).","example":true},"code":{"type":["string","null"],"description":"Why it did not pass. `not_checked` means it was never exercised. Absent when the capability passed.","enum":["not_checked","invite_permission_missing","invalid_credentials","device_inventory_invalid","route_key_not_issued","invite_not_created","invite_url_missing","tailnet_not_found","oauth_token_not_issued","provider_response_malformed","network_error","provider_error","configuration",null],"example":"not_checked"}}},"route_key":{"type":"object","required":["ok"],"properties":{"ok":{"type":["boolean","null"],"description":"True passed, false failed, null not exercised (no budget left, or the provider refused the probe body).","example":true},"code":{"type":["string","null"],"description":"Why it did not pass. `not_checked` means it was never exercised. Absent when the capability passed.","enum":["not_checked","invite_permission_missing","invalid_credentials","device_inventory_invalid","route_key_not_issued","invite_not_created","invite_url_missing","tailnet_not_found","oauth_token_not_issued","provider_response_malformed","network_error","provider_error","configuration",null],"example":"not_checked"}}}}},"error":{"type":["string","null"],"description":"The first failed capability's sentence, already redacted for display. Absent when everything passed.","example":"Tailscale refused the invite with HTTP 403"},"code":{"type":["string","null"],"description":"The first failed capability's code. Absent when everything passed.","example":"invite_permission_missing"}}}]}}},{"type":"object","properties":{"test":{"description":"The pre-flight just run, in the same shape it is persisted as `capability_check`. A capability that fails does NOT stop the ones after it — the operator sees the whole picture in one pass instead of discovering the next wall on the next attempt.","allOf":[{"type":"object","required":["ok","checked_at"],"properties":{"ok":{"type":"boolean","description":"True only when every capability passed. A capability that was not exercised keeps it false.","example":false},"device_count":{"type":["integer","null"],"minimum":0,"description":"Devices the inventory read returned. Absent when that capability was not exercised.","example":2},"tailnet":{"type":"string","example":"acme.example.com"},"authentication_mode":{"type":"string","enum":["oauth","api_access_token"],"example":"oauth"},"api_access_token_configured":{"type":"boolean","example":false},"api_access_token_expires_at":{"type":["string","null"],"format":"date-time","description":"Absent when no expiry is on record.","example":"2026-11-01T00:00:00Z"},"checked_at":{"type":"string","format":"date-time","example":"2026-08-18T09:00:00Z"},"capabilities":{"type":"object","description":"One verdict per capability. Absent when the whole probe failed before any capability could be exercised, in which case the top-level `error` and `code` are the only answer there is.","required":["devices_read","user_invite","route_key"],"properties":{"devices_read":{"type":"object","required":["ok"],"properties":{"ok":{"type":["boolean","null"],"description":"True passed, false failed, null not exercised (no budget left, or the provider refused the probe body).","example":true},"code":{"type":["string","null"],"description":"Why it did not pass. `not_checked` means it was never exercised. Absent when the capability passed.","enum":["not_checked","invite_permission_missing","invalid_credentials","device_inventory_invalid","route_key_not_issued","invite_not_created","invite_url_missing","tailnet_not_found","oauth_token_not_issued","provider_response_malformed","network_error","provider_error","configuration",null],"example":"not_checked"}}},"user_invite":{"type":"object","required":["ok"],"properties":{"ok":{"type":["boolean","null"],"description":"True passed, false failed, null not exercised (no budget left, or the provider refused the probe body).","example":true},"code":{"type":["string","null"],"description":"Why it did not pass. `not_checked` means it was never exercised. Absent when the capability passed.","enum":["not_checked","invite_permission_missing","invalid_credentials","device_inventory_invalid","route_key_not_issued","invite_not_created","invite_url_missing","tailnet_not_found","oauth_token_not_issued","provider_response_malformed","network_error","provider_error","configuration",null],"example":"not_checked"}}},"route_key":{"type":"object","required":["ok"],"properties":{"ok":{"type":["boolean","null"],"description":"True passed, false failed, null not exercised (no budget left, or the provider refused the probe body).","example":true},"code":{"type":["string","null"],"description":"Why it did not pass. `not_checked` means it was never exercised. Absent when the capability passed.","enum":["not_checked","invite_permission_missing","invalid_credentials","device_inventory_invalid","route_key_not_issued","invite_not_created","invite_url_missing","tailnet_not_found","oauth_token_not_issued","provider_response_malformed","network_error","provider_error","configuration",null],"example":"not_checked"}}}}},"error":{"type":["string","null"],"description":"The first failed capability's sentence, already redacted for display. Absent when everything passed.","example":"Tailscale refused the invite with HTTP 403"},"code":{"type":["string","null"],"description":"The first failed capability's code. Absent when everything passed.","example":"invite_permission_missing"}}},{"type":"object","properties":{"persistence_error":{"type":["string","null"],"description":"Present only when the outcome could not be written to the record. The diagnosis is still returned — it exists precisely to describe a row that may be inconsistent. It is the exception class and message, already redacted for display — never a credential.","example":"ActiveRecord::StatementInvalid: PG::ConnectionBad"}}}]}}}]},"example":{"id":12,"account_id":41,"provider":"tailscale","tailnet":"acme.example.com","active":true,"status":"online","scope":"account","managed_by":"account","auth_key_tags":["tag:cw-egress-acct-41"],"credentials_configured":true,"authentication_mode":"oauth","oauth_configured":true,"api_access_token_expires_at":null,"api_access_token_configured":true,"credential_rotation_due":false,"last_checked_at":"2026-08-18T09:00:00Z","capability_check":{"ok":true,"device_count":2,"tailnet":"acme.example.com","authentication_mode":"oauth","api_access_token_configured":true,"api_access_token_expires_at":null,"checked_at":"2026-08-18T09:00:00Z","capabilities":{"devices_read":{"ok":true,"code":null},"user_invite":{"ok":true,"code":null},"route_key":{"ok":true,"code":null}},"error":null,"code":null},"test":{"ok":true,"device_count":2,"tailnet":"acme.example.com","authentication_mode":"oauth","api_access_token_configured":true,"api_access_token_expires_at":null,"checked_at":"2026-08-18T09:00:00Z","capabilities":{"devices_read":{"ok":true,"code":null},"user_invite":{"ok":true,"code":null},"route_key":{"ok":true,"code":null}},"error":null,"code":null,"persistence_error":null}}}}},"401":{"description":"The caller is not authorized for this action: not an account administrator, and without an access role that is allowed it. An access role that grants neither inbox nor WhatsApp-hub management is answered 403, not 401.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Sentence for the operator, already translated to the account locale."}}},"example":{"error":"You are not authorized to do this action"}}}},"404":{"description":"Nothing resolves for this account: no configuration of its own and no shared operator default, or the one that resolves is switched off. The status stays 404 — nothing is there — but the body is typed like every other failure, because a bodiless 404 could not be told apart from a missing endpoint.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"code":{"type":"string","description":"Stable symbol for this refusal — the dashboard maps it to copy and to an affordance.","enum":["configuration"]}}},"example":{"error":"The phone connection is not ready for this account: it was never set up, it is switched off, or its setup is inconsistent. Ask your operator to review this account’s phone-connection setup.","code":"configuration"}}}},"403":{"description":"The caller holds an access role that grants neither `inbox_manage` nor `whatsapp_hub_manage`. The request stops before the action runs: nothing is changed and no provider is contacted.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","enum":["forbidden"]}}},"example":{"error":"forbidden"}}}},"422":{"description":"At least one capability did not pass. The full per-capability outcome stays in `test` — including the ones that DID pass — and `error`/`code` are added alongside it so the screen can pick copy and affordance without re-deriving them from the nested result.","content":{"application/json":{"schema":{"allOf":[{"allOf":[{"type":"object","required":["id","provider","tailnet","active","status","scope","managed_by","credentials_configured"],"properties":{"id":{"type":"integer","example":12},"account_id":{"type":["integer","null"],"description":"Null on the operator's shared configuration, which belongs to no single account.","example":41},"provider":{"type":"string","enum":["tailscale"],"example":"tailscale"},"tailnet":{"type":"string","example":"acme.example.com"},"active":{"type":"boolean","example":true},"status":{"type":"string","enum":["unknown","online","offline","invalid_credentials"],"example":"online"},"scope":{"type":"string","enum":["account","global"],"description":"`account` — connected by this account. `global` — the operator default shared with every account that has not connected its own.","example":"account"},"managed_by":{"type":"string","enum":["operator","account"],"description":"Who may edit it. An `operator` row is read-only through this API and is changed in Super Admin.","example":"account"},"auth_key_tags":{"type":"array","description":"Tailscale tags applied to the ephemeral WazMeow exit-node keys. Must exist under `tagOwners` in the customer's own policy file.","items":{"type":"string","pattern":"^tag:[a-z0-9][a-z0-9-]{0,62}$"},"example":["tag:cw-egress-acct-41"]},"credentials_configured":{"type":"boolean","example":true},"authentication_mode":{"type":"string","enum":["oauth","api_access_token"],"example":"oauth"},"oauth_configured":{"type":"boolean","example":true},"api_access_token_configured":{"type":"boolean","description":"Whether a personal API access token is stored. A boolean, never the value. It matters on its own because no published Tailscale OAuth scope covers inviting a user, so an OAuth-only connection can read devices and mint route keys but can never invite a phone — and the setup screen has to be able to say so BEFORE the operator hits that wall mid-enrollment.","example":true},"api_access_token_expires_at":{"type":["string","null"],"format":"date-time","example":null},"credential_rotation_due":{"type":"boolean","example":false},"last_checked_at":{"type":["string","null"],"format":"date-time","example":"2026-08-18T09:00:00Z"},"capability_check":{"description":"The last pre-flight: the three capabilities this connection needs, each exercised for real, with the moment they were measured. Null until one has run. Capability names, verdicts, codes and a timestamp — never a credential value.","allOf":[{"type":"object","required":["ok","checked_at"],"properties":{"ok":{"type":"boolean","description":"True only when every capability passed. A capability that was not exercised keeps it false.","example":false},"device_count":{"type":["integer","null"],"minimum":0,"description":"Devices the inventory read returned. Absent when that capability was not exercised.","example":2},"tailnet":{"type":"string","example":"acme.example.com"},"authentication_mode":{"type":"string","enum":["oauth","api_access_token"],"example":"oauth"},"api_access_token_configured":{"type":"boolean","example":false},"api_access_token_expires_at":{"type":["string","null"],"format":"date-time","description":"Absent when no expiry is on record.","example":"2026-11-01T00:00:00Z"},"checked_at":{"type":"string","format":"date-time","example":"2026-08-18T09:00:00Z"},"capabilities":{"type":"object","description":"One verdict per capability. Absent when the whole probe failed before any capability could be exercised, in which case the top-level `error` and `code` are the only answer there is.","required":["devices_read","user_invite","route_key"],"properties":{"devices_read":{"type":"object","required":["ok"],"properties":{"ok":{"type":["boolean","null"],"description":"True passed, false failed, null not exercised (no budget left, or the provider refused the probe body).","example":true},"code":{"type":["string","null"],"description":"Why it did not pass. `not_checked` means it was never exercised. Absent when the capability passed.","enum":["not_checked","invite_permission_missing","invalid_credentials","device_inventory_invalid","route_key_not_issued","invite_not_created","invite_url_missing","tailnet_not_found","oauth_token_not_issued","provider_response_malformed","network_error","provider_error","configuration",null],"example":"not_checked"}}},"user_invite":{"type":"object","required":["ok"],"properties":{"ok":{"type":["boolean","null"],"description":"True passed, false failed, null not exercised (no budget left, or the provider refused the probe body).","example":true},"code":{"type":["string","null"],"description":"Why it did not pass. `not_checked` means it was never exercised. Absent when the capability passed.","enum":["not_checked","invite_permission_missing","invalid_credentials","device_inventory_invalid","route_key_not_issued","invite_not_created","invite_url_missing","tailnet_not_found","oauth_token_not_issued","provider_response_malformed","network_error","provider_error","configuration",null],"example":"not_checked"}}},"route_key":{"type":"object","required":["ok"],"properties":{"ok":{"type":["boolean","null"],"description":"True passed, false failed, null not exercised (no budget left, or the provider refused the probe body).","example":true},"code":{"type":["string","null"],"description":"Why it did not pass. `not_checked` means it was never exercised. Absent when the capability passed.","enum":["not_checked","invite_permission_missing","invalid_credentials","device_inventory_invalid","route_key_not_issued","invite_not_created","invite_url_missing","tailnet_not_found","oauth_token_not_issued","provider_response_malformed","network_error","provider_error","configuration",null],"example":"not_checked"}}}}},"error":{"type":["string","null"],"description":"The first failed capability's sentence, already redacted for display. Absent when everything passed.","example":"Tailscale refused the invite with HTTP 403"},"code":{"type":["string","null"],"description":"The first failed capability's code. Absent when everything passed.","example":"invite_permission_missing"}}}]}}},{"type":"object","properties":{"test":{"description":"The pre-flight just run, in the same shape it is persisted as `capability_check`. A capability that fails does NOT stop the ones after it — the operator sees the whole picture in one pass instead of discovering the next wall on the next attempt.","allOf":[{"type":"object","required":["ok","checked_at"],"properties":{"ok":{"type":"boolean","description":"True only when every capability passed. A capability that was not exercised keeps it false.","example":false},"device_count":{"type":["integer","null"],"minimum":0,"description":"Devices the inventory read returned. Absent when that capability was not exercised.","example":2},"tailnet":{"type":"string","example":"acme.example.com"},"authentication_mode":{"type":"string","enum":["oauth","api_access_token"],"example":"oauth"},"api_access_token_configured":{"type":"boolean","example":false},"api_access_token_expires_at":{"type":["string","null"],"format":"date-time","description":"Absent when no expiry is on record.","example":"2026-11-01T00:00:00Z"},"checked_at":{"type":"string","format":"date-time","example":"2026-08-18T09:00:00Z"},"capabilities":{"type":"object","description":"One verdict per capability. Absent when the whole probe failed before any capability could be exercised, in which case the top-level `error` and `code` are the only answer there is.","required":["devices_read","user_invite","route_key"],"properties":{"devices_read":{"type":"object","required":["ok"],"properties":{"ok":{"type":["boolean","null"],"description":"True passed, false failed, null not exercised (no budget left, or the provider refused the probe body).","example":true},"code":{"type":["string","null"],"description":"Why it did not pass. `not_checked` means it was never exercised. Absent when the capability passed.","enum":["not_checked","invite_permission_missing","invalid_credentials","device_inventory_invalid","route_key_not_issued","invite_not_created","invite_url_missing","tailnet_not_found","oauth_token_not_issued","provider_response_malformed","network_error","provider_error","configuration",null],"example":"not_checked"}}},"user_invite":{"type":"object","required":["ok"],"properties":{"ok":{"type":["boolean","null"],"description":"True passed, false failed, null not exercised (no budget left, or the provider refused the probe body).","example":true},"code":{"type":["string","null"],"description":"Why it did not pass. `not_checked` means it was never exercised. Absent when the capability passed.","enum":["not_checked","invite_permission_missing","invalid_credentials","device_inventory_invalid","route_key_not_issued","invite_not_created","invite_url_missing","tailnet_not_found","oauth_token_not_issued","provider_response_malformed","network_error","provider_error","configuration",null],"example":"not_checked"}}},"route_key":{"type":"object","required":["ok"],"properties":{"ok":{"type":["boolean","null"],"description":"True passed, false failed, null not exercised (no budget left, or the provider refused the probe body).","example":true},"code":{"type":["string","null"],"description":"Why it did not pass. `not_checked` means it was never exercised. Absent when the capability passed.","enum":["not_checked","invite_permission_missing","invalid_credentials","device_inventory_invalid","route_key_not_issued","invite_not_created","invite_url_missing","tailnet_not_found","oauth_token_not_issued","provider_response_malformed","network_error","provider_error","configuration",null],"example":"not_checked"}}}}},"error":{"type":["string","null"],"description":"The first failed capability's sentence, already redacted for display. Absent when everything passed.","example":"Tailscale refused the invite with HTTP 403"},"code":{"type":["string","null"],"description":"The first failed capability's code. Absent when everything passed.","example":"invite_permission_missing"}}},{"type":"object","properties":{"persistence_error":{"type":["string","null"],"description":"Present only when the outcome could not be written to the record. The diagnosis is still returned — it exists precisely to describe a row that may be inconsistent. It is the exception class and message, already redacted for display — never a credential.","example":"ActiveRecord::StatementInvalid: PG::ConnectionBad"}}}]}}}]},{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"code":{"type":"string","description":"The first failed capability's code, or `provider_error` when the probe failed without naming one.","enum":["invite_permission_missing","invalid_credentials","device_inventory_invalid","route_key_not_issued","invite_not_created","invite_url_missing","tailnet_not_found","oauth_token_not_issued","provider_response_malformed","network_error","provider_error","configuration"]}}}]},"example":{"id":12,"account_id":41,"provider":"tailscale","tailnet":"acme.example.com","active":true,"status":"online","scope":"account","managed_by":"account","auth_key_tags":["tag:cw-egress-acct-41"],"credentials_configured":true,"authentication_mode":"oauth","oauth_configured":true,"api_access_token_configured":false,"api_access_token_expires_at":null,"credential_rotation_due":false,"last_checked_at":"2026-08-18T09:00:00Z","capability_check":{"ok":false,"device_count":2,"tailnet":"acme.example.com","authentication_mode":"oauth","api_access_token_configured":false,"api_access_token_expires_at":null,"checked_at":"2026-08-18T09:00:00Z","capabilities":{"devices_read":{"ok":true,"code":null},"user_invite":{"ok":false,"code":"invite_permission_missing"},"route_key":{"ok":true,"code":null}},"error":"Tailscale refused the invite with HTTP 403","code":"invite_permission_missing"},"test":{"ok":false,"device_count":2,"tailnet":"acme.example.com","authentication_mode":"oauth","api_access_token_configured":false,"api_access_token_expires_at":null,"checked_at":"2026-08-18T09:00:00Z","capabilities":{"devices_read":{"ok":true,"code":null},"user_invite":{"ok":false,"code":"invite_permission_missing"},"route_key":{"ok":true,"code":null}},"error":"Tailscale refused the invite with HTTP 403","code":"invite_permission_missing","persistence_error":"ActiveRecord::StatementInvalid: PG::ConnectionBad"},"error":"The saved credential can read the network but is not allowed to invite a phone — no Tailscale OAuth scope covers user invites. Store a personal API access token (tskey-api-…) on this connection.","code":"invite_permission_missing"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/whatsapp_web/mobile_egress/configuration":{"get":{"tags":["WhatsApp Web"],"operationId":"auto_get_api_v1_accounts_account_id_whatsapp_web_mobile_egress_configuration","summary":"Inspect the phone-egress network configuration","description":"Returns the configuration this account resolves to: its own when it connected one, otherwise the operator's shared default (`scope: global`). Responds 404 when neither exists, which is the signal for the dashboard to offer the setup wizard. Tailscale OAuth client secrets and personal access tokens are never returned — only `credentials_configured` and `authentication_mode`.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The resolved configuration, with no credential material.","content":{"application/json":{"schema":{"type":"object","required":["id","provider","tailnet","active","status","scope","managed_by","credentials_configured"],"properties":{"id":{"type":"integer","example":12},"account_id":{"type":["integer","null"],"description":"Null on the operator's shared configuration, which belongs to no single account.","example":41},"provider":{"type":"string","enum":["tailscale"],"example":"tailscale"},"tailnet":{"type":"string","example":"acme.example.com"},"active":{"type":"boolean","example":true},"status":{"type":"string","enum":["unknown","online","offline","invalid_credentials"],"example":"online"},"scope":{"type":"string","enum":["account","global"],"description":"`account` — connected by this account. `global` — the operator default shared with every account that has not connected its own.","example":"account"},"managed_by":{"type":"string","enum":["operator","account"],"description":"Who may edit it. An `operator` row is read-only through this API and is changed in Super Admin.","example":"account"},"auth_key_tags":{"type":"array","description":"Tailscale tags applied to the ephemeral WazMeow exit-node keys. Must exist under `tagOwners` in the customer's own policy file.","items":{"type":"string","pattern":"^tag:[a-z0-9][a-z0-9-]{0,62}$"},"example":["tag:cw-egress-acct-41"]},"credentials_configured":{"type":"boolean","example":true},"authentication_mode":{"type":"string","enum":["oauth","api_access_token"],"example":"oauth"},"oauth_configured":{"type":"boolean","example":true},"api_access_token_configured":{"type":"boolean","description":"Whether a personal API access token is stored. A boolean, never the value. It matters on its own because no published Tailscale OAuth scope covers inviting a user, so an OAuth-only connection can read devices and mint route keys but can never invite a phone — and the setup screen has to be able to say so BEFORE the operator hits that wall mid-enrollment.","example":true},"api_access_token_expires_at":{"type":["string","null"],"format":"date-time","example":null},"credential_rotation_due":{"type":"boolean","example":false},"last_checked_at":{"type":["string","null"],"format":"date-time","example":"2026-08-18T09:00:00Z"},"capability_check":{"description":"The last pre-flight: the three capabilities this connection needs, each exercised for real, with the moment they were measured. Null until one has run. Capability names, verdicts, codes and a timestamp — never a credential value.","allOf":[{"type":"object","required":["ok","checked_at"],"properties":{"ok":{"type":"boolean","description":"True only when every capability passed. A capability that was not exercised keeps it false.","example":false},"device_count":{"type":["integer","null"],"minimum":0,"description":"Devices the inventory read returned. Absent when that capability was not exercised.","example":2},"tailnet":{"type":"string","example":"acme.example.com"},"authentication_mode":{"type":"string","enum":["oauth","api_access_token"],"example":"oauth"},"api_access_token_configured":{"type":"boolean","example":false},"api_access_token_expires_at":{"type":["string","null"],"format":"date-time","description":"Absent when no expiry is on record.","example":"2026-11-01T00:00:00Z"},"checked_at":{"type":"string","format":"date-time","example":"2026-08-18T09:00:00Z"},"capabilities":{"type":"object","description":"One verdict per capability. Absent when the whole probe failed before any capability could be exercised, in which case the top-level `error` and `code` are the only answer there is.","required":["devices_read","user_invite","route_key"],"properties":{"devices_read":{"type":"object","required":["ok"],"properties":{"ok":{"type":["boolean","null"],"description":"True passed, false failed, null not exercised (no budget left, or the provider refused the probe body).","example":true},"code":{"type":["string","null"],"description":"Why it did not pass. `not_checked` means it was never exercised. Absent when the capability passed.","enum":["not_checked","invite_permission_missing","invalid_credentials","device_inventory_invalid","route_key_not_issued","invite_not_created","invite_url_missing","tailnet_not_found","oauth_token_not_issued","provider_response_malformed","network_error","provider_error","configuration",null],"example":"not_checked"}}},"user_invite":{"type":"object","required":["ok"],"properties":{"ok":{"type":["boolean","null"],"description":"True passed, false failed, null not exercised (no budget left, or the provider refused the probe body).","example":true},"code":{"type":["string","null"],"description":"Why it did not pass. `not_checked` means it was never exercised. Absent when the capability passed.","enum":["not_checked","invite_permission_missing","invalid_credentials","device_inventory_invalid","route_key_not_issued","invite_not_created","invite_url_missing","tailnet_not_found","oauth_token_not_issued","provider_response_malformed","network_error","provider_error","configuration",null],"example":"not_checked"}}},"route_key":{"type":"object","required":["ok"],"properties":{"ok":{"type":["boolean","null"],"description":"True passed, false failed, null not exercised (no budget left, or the provider refused the probe body).","example":true},"code":{"type":["string","null"],"description":"Why it did not pass. `not_checked` means it was never exercised. Absent when the capability passed.","enum":["not_checked","invite_permission_missing","invalid_credentials","device_inventory_invalid","route_key_not_issued","invite_not_created","invite_url_missing","tailnet_not_found","oauth_token_not_issued","provider_response_malformed","network_error","provider_error","configuration",null],"example":"not_checked"}}}}},"error":{"type":["string","null"],"description":"The first failed capability's sentence, already redacted for display. Absent when everything passed.","example":"Tailscale refused the invite with HTTP 403"},"code":{"type":["string","null"],"description":"The first failed capability's code. Absent when everything passed.","example":"invite_permission_missing"}}}]}}},"example":{"id":12,"account_id":41,"provider":"tailscale","tailnet":"acme.example.com","active":true,"status":"online","scope":"account","managed_by":"account","auth_key_tags":["tag:cw-egress-acct-41"],"credentials_configured":true,"authentication_mode":"oauth","oauth_configured":true,"api_access_token_expires_at":null,"api_access_token_configured":true,"credential_rotation_due":false,"last_checked_at":"2026-08-18T09:00:00Z","capability_check":{"ok":false,"device_count":2,"tailnet":"acme.example.com","authentication_mode":"oauth","api_access_token_configured":false,"api_access_token_expires_at":null,"checked_at":"2026-08-18T09:00:00Z","capabilities":{"devices_read":{"ok":true,"code":null},"user_invite":{"ok":false,"code":"invite_permission_missing"},"route_key":{"ok":true,"code":null}},"error":"Tailscale refused the invite with HTTP 403","code":"invite_permission_missing"}}}}},"401":{"description":"The caller is not authorized for this action: not an account administrator, and without an access role that is allowed it. An access role that grants neither inbox nor WhatsApp-hub management is answered 403, not 401.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Sentence for the operator, already translated to the account locale."}}},"example":{"error":"You are not authorized to do this action"}}}},"404":{"description":"Nothing resolves for this account: no configuration of its own and no shared operator default, or the one that resolves is switched off. The status stays 404 — nothing is there — but the body is typed like every other failure, because a bodiless 404 could not be told apart from a missing endpoint.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"code":{"type":"string","description":"Stable symbol for this refusal — the dashboard maps it to copy and to an affordance.","enum":["configuration"]}}},"example":{"error":"The phone connection is not ready for this account: it was never set up, it is switched off, or its setup is inconsistent. Ask your operator to review this account’s phone-connection setup.","code":"configuration"}}}},"403":{"description":"The caller holds an access role that grants neither `inbox_manage` nor `whatsapp_hub_manage`. The request stops before the action runs: nothing is changed and no provider is contacted.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","enum":["forbidden"]}}},"example":{"error":"forbidden"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]},"patch":{"tags":["WhatsApp Web"],"operationId":"auto_patch_api_v1_accounts_account_id_whatsapp_web_mobile_egress_configuration","summary":"Update the account's own phone-egress network","description":"Edits a configuration this account owns. A credential field left blank keeps the stored value, so re-saving the tailnet never silently unauthenticates the account. Responds 401 for the operator's shared configuration and for any row the operator provisioned on this account's behalf.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The updated configuration, with no credential material.","content":{"application/json":{"schema":{"type":"object","required":["id","provider","tailnet","active","status","scope","managed_by","credentials_configured"],"properties":{"id":{"type":"integer","example":12},"account_id":{"type":["integer","null"],"description":"Null on the operator's shared configuration, which belongs to no single account.","example":41},"provider":{"type":"string","enum":["tailscale"],"example":"tailscale"},"tailnet":{"type":"string","example":"acme.example.com"},"active":{"type":"boolean","example":true},"status":{"type":"string","enum":["unknown","online","offline","invalid_credentials"],"example":"online"},"scope":{"type":"string","enum":["account","global"],"description":"`account` — connected by this account. `global` — the operator default shared with every account that has not connected its own.","example":"account"},"managed_by":{"type":"string","enum":["operator","account"],"description":"Who may edit it. An `operator` row is read-only through this API and is changed in Super Admin.","example":"account"},"auth_key_tags":{"type":"array","description":"Tailscale tags applied to the ephemeral WazMeow exit-node keys. Must exist under `tagOwners` in the customer's own policy file.","items":{"type":"string","pattern":"^tag:[a-z0-9][a-z0-9-]{0,62}$"},"example":["tag:cw-egress-acct-41"]},"credentials_configured":{"type":"boolean","example":true},"authentication_mode":{"type":"string","enum":["oauth","api_access_token"],"example":"oauth"},"oauth_configured":{"type":"boolean","example":true},"api_access_token_configured":{"type":"boolean","description":"Whether a personal API access token is stored. A boolean, never the value. It matters on its own because no published Tailscale OAuth scope covers inviting a user, so an OAuth-only connection can read devices and mint route keys but can never invite a phone — and the setup screen has to be able to say so BEFORE the operator hits that wall mid-enrollment.","example":true},"api_access_token_expires_at":{"type":["string","null"],"format":"date-time","example":null},"credential_rotation_due":{"type":"boolean","example":false},"last_checked_at":{"type":["string","null"],"format":"date-time","example":"2026-08-18T09:00:00Z"},"capability_check":{"description":"The last pre-flight: the three capabilities this connection needs, each exercised for real, with the moment they were measured. Null until one has run. Capability names, verdicts, codes and a timestamp — never a credential value.","allOf":[{"type":"object","required":["ok","checked_at"],"properties":{"ok":{"type":"boolean","description":"True only when every capability passed. A capability that was not exercised keeps it false.","example":false},"device_count":{"type":["integer","null"],"minimum":0,"description":"Devices the inventory read returned. Absent when that capability was not exercised.","example":2},"tailnet":{"type":"string","example":"acme.example.com"},"authentication_mode":{"type":"string","enum":["oauth","api_access_token"],"example":"oauth"},"api_access_token_configured":{"type":"boolean","example":false},"api_access_token_expires_at":{"type":["string","null"],"format":"date-time","description":"Absent when no expiry is on record.","example":"2026-11-01T00:00:00Z"},"checked_at":{"type":"string","format":"date-time","example":"2026-08-18T09:00:00Z"},"capabilities":{"type":"object","description":"One verdict per capability. Absent when the whole probe failed before any capability could be exercised, in which case the top-level `error` and `code` are the only answer there is.","required":["devices_read","user_invite","route_key"],"properties":{"devices_read":{"type":"object","required":["ok"],"properties":{"ok":{"type":["boolean","null"],"description":"True passed, false failed, null not exercised (no budget left, or the provider refused the probe body).","example":true},"code":{"type":["string","null"],"description":"Why it did not pass. `not_checked` means it was never exercised. Absent when the capability passed.","enum":["not_checked","invite_permission_missing","invalid_credentials","device_inventory_invalid","route_key_not_issued","invite_not_created","invite_url_missing","tailnet_not_found","oauth_token_not_issued","provider_response_malformed","network_error","provider_error","configuration",null],"example":"not_checked"}}},"user_invite":{"type":"object","required":["ok"],"properties":{"ok":{"type":["boolean","null"],"description":"True passed, false failed, null not exercised (no budget left, or the provider refused the probe body).","example":true},"code":{"type":["string","null"],"description":"Why it did not pass. `not_checked` means it was never exercised. Absent when the capability passed.","enum":["not_checked","invite_permission_missing","invalid_credentials","device_inventory_invalid","route_key_not_issued","invite_not_created","invite_url_missing","tailnet_not_found","oauth_token_not_issued","provider_response_malformed","network_error","provider_error","configuration",null],"example":"not_checked"}}},"route_key":{"type":"object","required":["ok"],"properties":{"ok":{"type":["boolean","null"],"description":"True passed, false failed, null not exercised (no budget left, or the provider refused the probe body).","example":true},"code":{"type":["string","null"],"description":"Why it did not pass. `not_checked` means it was never exercised. Absent when the capability passed.","enum":["not_checked","invite_permission_missing","invalid_credentials","device_inventory_invalid","route_key_not_issued","invite_not_created","invite_url_missing","tailnet_not_found","oauth_token_not_issued","provider_response_malformed","network_error","provider_error","configuration",null],"example":"not_checked"}}}}},"error":{"type":["string","null"],"description":"The first failed capability's sentence, already redacted for display. Absent when everything passed.","example":"Tailscale refused the invite with HTTP 403"},"code":{"type":["string","null"],"description":"The first failed capability's code. Absent when everything passed.","example":"invite_permission_missing"}}}]}}},"example":{"id":12,"account_id":41,"provider":"tailscale","tailnet":"acme.example.com","active":true,"status":"online","scope":"account","managed_by":"account","auth_key_tags":["tag:cw-egress-acct-41"],"credentials_configured":true,"authentication_mode":"oauth","oauth_configured":true,"api_access_token_expires_at":null,"api_access_token_configured":true,"credential_rotation_due":false,"last_checked_at":"2026-08-18T09:00:00Z","capability_check":{"ok":false,"device_count":2,"tailnet":"acme.example.com","authentication_mode":"oauth","api_access_token_configured":false,"api_access_token_expires_at":null,"checked_at":"2026-08-18T09:00:00Z","capabilities":{"devices_read":{"ok":true,"code":null},"user_invite":{"ok":false,"code":"invite_permission_missing"},"route_key":{"ok":true,"code":null}},"error":"Tailscale refused the invite with HTTP 403","code":"invite_permission_missing"}}}}},"401":{"description":"The caller is not authorized for this action: not an account administrator, and without an access role that is allowed it. An access role that grants neither inbox nor WhatsApp-hub management is answered 403, not 401.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Sentence for the operator, already translated to the account locale."}}},"example":{"error":"You are not authorized to do this action"}}}},"404":{"description":"Nothing resolves for this account: no configuration of its own and no shared operator default, or the one that resolves is switched off. The status stays 404 — nothing is there — but the body is typed like every other failure, because a bodiless 404 could not be told apart from a missing endpoint.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"code":{"type":"string","description":"Stable symbol for this refusal — the dashboard maps it to copy and to an affordance.","enum":["configuration"]}}},"example":{"error":"The phone connection is not ready for this account: it was never set up, it is switched off, or its setup is inconsistent. Ask your operator to review this account’s phone-connection setup.","code":"configuration"}}}},"403":{"description":"The caller holds an access role that grants neither `inbox_manage` nor `whatsapp_hub_manage`. The request stops before the action runs: nothing is changed and no provider is contacted.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","enum":["forbidden"]}}},"example":{"error":"forbidden"}}}},"422":{"description":"The submitted configuration is not valid — a missing or duplicate tailnet, an unreadable token expiry, or encryption not configured on this installation. The record's own sentence is returned because it is more specific than any generic copy; `code` carries the affordance, which is always \"take me back to the form\".","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"code":{"type":"string","description":"Stable symbol for this refusal — the dashboard maps it to copy and to an affordance.","enum":["configuration"]}}},"example":{"error":"Tailnet has already been taken","code":"configuration"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["configuration"],"properties":{"configuration":{"type":"object","required":["tailnet"],"properties":{"tailnet":{"type":"string","example":"acme.example.com"},"active":{"type":"boolean","description":"Defaults to true on creation. Requires Active Record encryption to be configured.","example":true},"auth_key_tags":{"type":"string","description":"Comma-separated Tailscale tags. Omit to derive `tag:cw-egress-acct-\u003caccount_id\u003e`.","example":"tag:cw-egress-acct-41"},"oauth_client_id":{"type":"string","writeOnly":true,"example":"k123CNTRL"},"oauth_client_secret":{"type":"string","writeOnly":true,"example":"tskey-client-REDACTED"},"api_access_token":{"type":"string","writeOnly":true,"example":"tskey-api-REDACTED"}}}}},"example":{"configuration":{"tailnet":"acme.example.com","oauth_client_id":"k123CNTRL","oauth_client_secret":"tskey-client-REDACTED","active":true,"auth_key_tags":"tag:cw-egress-acct-41","api_access_token":"tskey-api-REDACTED"}}}}}},"put":{"tags":["WhatsApp Web"],"operationId":"auto_put_api_v1_accounts_account_id_whatsapp_web_mobile_egress_configuration","summary":"Update the account's own phone-egress network","description":"Edits a configuration this account owns. A credential field left blank keeps the stored value, so re-saving the tailnet never silently unauthenticates the account. Responds 401 for the operator's shared configuration and for any row the operator provisioned on this account's behalf.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The updated configuration, with no credential material.","content":{"application/json":{"schema":{"type":"object","required":["id","provider","tailnet","active","status","scope","managed_by","credentials_configured"],"properties":{"id":{"type":"integer","example":12},"account_id":{"type":["integer","null"],"description":"Null on the operator's shared configuration, which belongs to no single account.","example":41},"provider":{"type":"string","enum":["tailscale"],"example":"tailscale"},"tailnet":{"type":"string","example":"acme.example.com"},"active":{"type":"boolean","example":true},"status":{"type":"string","enum":["unknown","online","offline","invalid_credentials"],"example":"online"},"scope":{"type":"string","enum":["account","global"],"description":"`account` — connected by this account. `global` — the operator default shared with every account that has not connected its own.","example":"account"},"managed_by":{"type":"string","enum":["operator","account"],"description":"Who may edit it. An `operator` row is read-only through this API and is changed in Super Admin.","example":"account"},"auth_key_tags":{"type":"array","description":"Tailscale tags applied to the ephemeral WazMeow exit-node keys. Must exist under `tagOwners` in the customer's own policy file.","items":{"type":"string","pattern":"^tag:[a-z0-9][a-z0-9-]{0,62}$"},"example":["tag:cw-egress-acct-41"]},"credentials_configured":{"type":"boolean","example":true},"authentication_mode":{"type":"string","enum":["oauth","api_access_token"],"example":"oauth"},"oauth_configured":{"type":"boolean","example":true},"api_access_token_configured":{"type":"boolean","description":"Whether a personal API access token is stored. A boolean, never the value. It matters on its own because no published Tailscale OAuth scope covers inviting a user, so an OAuth-only connection can read devices and mint route keys but can never invite a phone — and the setup screen has to be able to say so BEFORE the operator hits that wall mid-enrollment.","example":true},"api_access_token_expires_at":{"type":["string","null"],"format":"date-time","example":null},"credential_rotation_due":{"type":"boolean","example":false},"last_checked_at":{"type":["string","null"],"format":"date-time","example":"2026-08-18T09:00:00Z"},"capability_check":{"description":"The last pre-flight: the three capabilities this connection needs, each exercised for real, with the moment they were measured. Null until one has run. Capability names, verdicts, codes and a timestamp — never a credential value.","allOf":[{"type":"object","required":["ok","checked_at"],"properties":{"ok":{"type":"boolean","description":"True only when every capability passed. A capability that was not exercised keeps it false.","example":false},"device_count":{"type":["integer","null"],"minimum":0,"description":"Devices the inventory read returned. Absent when that capability was not exercised.","example":2},"tailnet":{"type":"string","example":"acme.example.com"},"authentication_mode":{"type":"string","enum":["oauth","api_access_token"],"example":"oauth"},"api_access_token_configured":{"type":"boolean","example":false},"api_access_token_expires_at":{"type":["string","null"],"format":"date-time","description":"Absent when no expiry is on record.","example":"2026-11-01T00:00:00Z"},"checked_at":{"type":"string","format":"date-time","example":"2026-08-18T09:00:00Z"},"capabilities":{"type":"object","description":"One verdict per capability. Absent when the whole probe failed before any capability could be exercised, in which case the top-level `error` and `code` are the only answer there is.","required":["devices_read","user_invite","route_key"],"properties":{"devices_read":{"type":"object","required":["ok"],"properties":{"ok":{"type":["boolean","null"],"description":"True passed, false failed, null not exercised (no budget left, or the provider refused the probe body).","example":true},"code":{"type":["string","null"],"description":"Why it did not pass. `not_checked` means it was never exercised. Absent when the capability passed.","enum":["not_checked","invite_permission_missing","invalid_credentials","device_inventory_invalid","route_key_not_issued","invite_not_created","invite_url_missing","tailnet_not_found","oauth_token_not_issued","provider_response_malformed","network_error","provider_error","configuration",null],"example":"not_checked"}}},"user_invite":{"type":"object","required":["ok"],"properties":{"ok":{"type":["boolean","null"],"description":"True passed, false failed, null not exercised (no budget left, or the provider refused the probe body).","example":true},"code":{"type":["string","null"],"description":"Why it did not pass. `not_checked` means it was never exercised. Absent when the capability passed.","enum":["not_checked","invite_permission_missing","invalid_credentials","device_inventory_invalid","route_key_not_issued","invite_not_created","invite_url_missing","tailnet_not_found","oauth_token_not_issued","provider_response_malformed","network_error","provider_error","configuration",null],"example":"not_checked"}}},"route_key":{"type":"object","required":["ok"],"properties":{"ok":{"type":["boolean","null"],"description":"True passed, false failed, null not exercised (no budget left, or the provider refused the probe body).","example":true},"code":{"type":["string","null"],"description":"Why it did not pass. `not_checked` means it was never exercised. Absent when the capability passed.","enum":["not_checked","invite_permission_missing","invalid_credentials","device_inventory_invalid","route_key_not_issued","invite_not_created","invite_url_missing","tailnet_not_found","oauth_token_not_issued","provider_response_malformed","network_error","provider_error","configuration",null],"example":"not_checked"}}}}},"error":{"type":["string","null"],"description":"The first failed capability's sentence, already redacted for display. Absent when everything passed.","example":"Tailscale refused the invite with HTTP 403"},"code":{"type":["string","null"],"description":"The first failed capability's code. Absent when everything passed.","example":"invite_permission_missing"}}}]}}},"example":{"id":12,"account_id":41,"provider":"tailscale","tailnet":"acme.example.com","active":true,"status":"online","scope":"account","managed_by":"account","auth_key_tags":["tag:cw-egress-acct-41"],"credentials_configured":true,"authentication_mode":"oauth","oauth_configured":true,"api_access_token_expires_at":null,"api_access_token_configured":true,"credential_rotation_due":false,"last_checked_at":"2026-08-18T09:00:00Z","capability_check":{"ok":false,"device_count":2,"tailnet":"acme.example.com","authentication_mode":"oauth","api_access_token_configured":false,"api_access_token_expires_at":null,"checked_at":"2026-08-18T09:00:00Z","capabilities":{"devices_read":{"ok":true,"code":null},"user_invite":{"ok":false,"code":"invite_permission_missing"},"route_key":{"ok":true,"code":null}},"error":"Tailscale refused the invite with HTTP 403","code":"invite_permission_missing"}}}}},"401":{"description":"The caller is not authorized for this action: not an account administrator, and without an access role that is allowed it. An access role that grants neither inbox nor WhatsApp-hub management is answered 403, not 401.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Sentence for the operator, already translated to the account locale."}}},"example":{"error":"You are not authorized to do this action"}}}},"404":{"description":"Nothing resolves for this account: no configuration of its own and no shared operator default, or the one that resolves is switched off. The status stays 404 — nothing is there — but the body is typed like every other failure, because a bodiless 404 could not be told apart from a missing endpoint.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"code":{"type":"string","description":"Stable symbol for this refusal — the dashboard maps it to copy and to an affordance.","enum":["configuration"]}}},"example":{"error":"The phone connection is not ready for this account: it was never set up, it is switched off, or its setup is inconsistent. Ask your operator to review this account’s phone-connection setup.","code":"configuration"}}}},"403":{"description":"The caller holds an access role that grants neither `inbox_manage` nor `whatsapp_hub_manage`. The request stops before the action runs: nothing is changed and no provider is contacted.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","enum":["forbidden"]}}},"example":{"error":"forbidden"}}}},"422":{"description":"The submitted configuration is not valid — a missing or duplicate tailnet, an unreadable token expiry, or encryption not configured on this installation. The record's own sentence is returned because it is more specific than any generic copy; `code` carries the affordance, which is always \"take me back to the form\".","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"code":{"type":"string","description":"Stable symbol for this refusal — the dashboard maps it to copy and to an affordance.","enum":["configuration"]}}},"example":{"error":"Tailnet has already been taken","code":"configuration"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["configuration"],"properties":{"configuration":{"type":"object","required":["tailnet"],"properties":{"tailnet":{"type":"string","example":"acme.example.com"},"active":{"type":"boolean","description":"Defaults to true on creation. Requires Active Record encryption to be configured.","example":true},"auth_key_tags":{"type":"string","description":"Comma-separated Tailscale tags. Omit to derive `tag:cw-egress-acct-\u003caccount_id\u003e`.","example":"tag:cw-egress-acct-41"},"oauth_client_id":{"type":"string","writeOnly":true,"example":"k123CNTRL"},"oauth_client_secret":{"type":"string","writeOnly":true,"example":"tskey-client-REDACTED"},"api_access_token":{"type":"string","writeOnly":true,"example":"tskey-api-REDACTED"}}}}},"example":{"configuration":{"tailnet":"acme.example.com","oauth_client_id":"k123CNTRL","oauth_client_secret":"tskey-client-REDACTED","active":true,"auth_key_tags":"tag:cw-egress-acct-41","api_access_token":"tskey-api-REDACTED"}}}}}},"delete":{"tags":["WhatsApp Web"],"operationId":"auto_delete_api_v1_accounts_account_id_whatsapp_web_mobile_egress_configuration","summary":"Remove the account's own phone-egress network","description":"Deletes a configuration this account owns. Responds 409 while phones are still enrolled — revoke them first, so no lease is left pointing at a network that no longer exists.","security":[{"userApiKey":[]}],"responses":{"204":{"description":"Configuration removed."},"401":{"description":"The caller is not authorized for this action: not an account administrator, and without an access role that is allowed it. An access role that grants neither inbox nor WhatsApp-hub management is answered 403, not 401.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Sentence for the operator, already translated to the account locale."}}},"example":{"error":"You are not authorized to do this action"}}}},"404":{"description":"Nothing resolves for this account: no configuration of its own and no shared operator default, or the one that resolves is switched off. The status stays 404 — nothing is there — but the body is typed like every other failure, because a bodiless 404 could not be told apart from a missing endpoint.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"code":{"type":"string","description":"Stable symbol for this refusal — the dashboard maps it to copy and to an affordance.","enum":["configuration"]}}},"example":{"error":"The phone connection is not ready for this account: it was never set up, it is switched off, or its setup is inconsistent. Ask your operator to review this account’s phone-connection setup.","code":"configuration"}}}},"403":{"description":"The caller holds an access role that grants neither `inbox_manage` nor `whatsapp_hub_manage`. The request stops before the action runs: nothing is changed and no provider is contacted.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","enum":["forbidden"]}}},"example":{"error":"forbidden"}}}},"409":{"description":"Enrolled phones must be removed first.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"code":{"type":"string","description":"Stable symbol for this refusal — the dashboard maps it to copy and to an affordance.","enum":["devices_still_enrolled"]}}},"example":{"error":"Remove the enrolled phones before deleting this mobile connection.","code":"devices_still_enrolled"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]},"post":{"tags":["WhatsApp Web"],"operationId":"auto_post_api_v1_accounts_account_id_whatsapp_web_mobile_egress_configuration","summary":"Connect the account's own phone-egress network","description":"Registers the Tailscale network this account brings itself (BYO). Supply either an OAuth client (preferred — it does not expire) or a personal API access token. When `auth_key_tags` is omitted, a per-account tag is derived so the customer's own ACL can fence one account's exit nodes from another's. Responds 409 when the account already has its own configuration.","security":[{"userApiKey":[]}],"responses":{"401":{"description":"The caller is not authorized for this action: not an account administrator, and without an access role that is allowed it. An access role that grants neither inbox nor WhatsApp-hub management is answered 403, not 401.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Sentence for the operator, already translated to the account locale."}}},"example":{"error":"You are not authorized to do this action"}}}},"404":{"description":"Account or resource not found"},"201":{"description":"The stored configuration, with no credential material.","content":{"application/json":{"schema":{"type":"object","required":["id","provider","tailnet","active","status","scope","managed_by","credentials_configured"],"properties":{"id":{"type":"integer","example":12},"account_id":{"type":["integer","null"],"description":"Null on the operator's shared configuration, which belongs to no single account.","example":41},"provider":{"type":"string","enum":["tailscale"],"example":"tailscale"},"tailnet":{"type":"string","example":"acme.example.com"},"active":{"type":"boolean","example":true},"status":{"type":"string","enum":["unknown","online","offline","invalid_credentials"],"example":"online"},"scope":{"type":"string","enum":["account","global"],"description":"`account` — connected by this account. `global` — the operator default shared with every account that has not connected its own.","example":"account"},"managed_by":{"type":"string","enum":["operator","account"],"description":"Who may edit it. An `operator` row is read-only through this API and is changed in Super Admin.","example":"account"},"auth_key_tags":{"type":"array","description":"Tailscale tags applied to the ephemeral WazMeow exit-node keys. Must exist under `tagOwners` in the customer's own policy file.","items":{"type":"string","pattern":"^tag:[a-z0-9][a-z0-9-]{0,62}$"},"example":["tag:cw-egress-acct-41"]},"credentials_configured":{"type":"boolean","example":true},"authentication_mode":{"type":"string","enum":["oauth","api_access_token"],"example":"oauth"},"oauth_configured":{"type":"boolean","example":true},"api_access_token_configured":{"type":"boolean","description":"Whether a personal API access token is stored. A boolean, never the value. It matters on its own because no published Tailscale OAuth scope covers inviting a user, so an OAuth-only connection can read devices and mint route keys but can never invite a phone — and the setup screen has to be able to say so BEFORE the operator hits that wall mid-enrollment.","example":true},"api_access_token_expires_at":{"type":["string","null"],"format":"date-time","example":null},"credential_rotation_due":{"type":"boolean","example":false},"last_checked_at":{"type":["string","null"],"format":"date-time","example":"2026-08-18T09:00:00Z"},"capability_check":{"description":"The last pre-flight: the three capabilities this connection needs, each exercised for real, with the moment they were measured. Null until one has run. Capability names, verdicts, codes and a timestamp — never a credential value.","allOf":[{"type":"object","required":["ok","checked_at"],"properties":{"ok":{"type":"boolean","description":"True only when every capability passed. A capability that was not exercised keeps it false.","example":false},"device_count":{"type":["integer","null"],"minimum":0,"description":"Devices the inventory read returned. Absent when that capability was not exercised.","example":2},"tailnet":{"type":"string","example":"acme.example.com"},"authentication_mode":{"type":"string","enum":["oauth","api_access_token"],"example":"oauth"},"api_access_token_configured":{"type":"boolean","example":false},"api_access_token_expires_at":{"type":["string","null"],"format":"date-time","description":"Absent when no expiry is on record.","example":"2026-11-01T00:00:00Z"},"checked_at":{"type":"string","format":"date-time","example":"2026-08-18T09:00:00Z"},"capabilities":{"type":"object","description":"One verdict per capability. Absent when the whole probe failed before any capability could be exercised, in which case the top-level `error` and `code` are the only answer there is.","required":["devices_read","user_invite","route_key"],"properties":{"devices_read":{"type":"object","required":["ok"],"properties":{"ok":{"type":["boolean","null"],"description":"True passed, false failed, null not exercised (no budget left, or the provider refused the probe body).","example":true},"code":{"type":["string","null"],"description":"Why it did not pass. `not_checked` means it was never exercised. Absent when the capability passed.","enum":["not_checked","invite_permission_missing","invalid_credentials","device_inventory_invalid","route_key_not_issued","invite_not_created","invite_url_missing","tailnet_not_found","oauth_token_not_issued","provider_response_malformed","network_error","provider_error","configuration",null],"example":"not_checked"}}},"user_invite":{"type":"object","required":["ok"],"properties":{"ok":{"type":["boolean","null"],"description":"True passed, false failed, null not exercised (no budget left, or the provider refused the probe body).","example":true},"code":{"type":["string","null"],"description":"Why it did not pass. `not_checked` means it was never exercised. Absent when the capability passed.","enum":["not_checked","invite_permission_missing","invalid_credentials","device_inventory_invalid","route_key_not_issued","invite_not_created","invite_url_missing","tailnet_not_found","oauth_token_not_issued","provider_response_malformed","network_error","provider_error","configuration",null],"example":"not_checked"}}},"route_key":{"type":"object","required":["ok"],"properties":{"ok":{"type":["boolean","null"],"description":"True passed, false failed, null not exercised (no budget left, or the provider refused the probe body).","example":true},"code":{"type":["string","null"],"description":"Why it did not pass. `not_checked` means it was never exercised. Absent when the capability passed.","enum":["not_checked","invite_permission_missing","invalid_credentials","device_inventory_invalid","route_key_not_issued","invite_not_created","invite_url_missing","tailnet_not_found","oauth_token_not_issued","provider_response_malformed","network_error","provider_error","configuration",null],"example":"not_checked"}}}}},"error":{"type":["string","null"],"description":"The first failed capability's sentence, already redacted for display. Absent when everything passed.","example":"Tailscale refused the invite with HTTP 403"},"code":{"type":["string","null"],"description":"The first failed capability's code. Absent when everything passed.","example":"invite_permission_missing"}}}]}}},"example":{"id":12,"account_id":41,"provider":"tailscale","tailnet":"acme.example.com","active":true,"status":"online","scope":"account","managed_by":"account","auth_key_tags":["tag:cw-egress-acct-41"],"credentials_configured":true,"authentication_mode":"oauth","oauth_configured":true,"api_access_token_expires_at":null,"api_access_token_configured":true,"credential_rotation_due":false,"last_checked_at":"2026-08-18T09:00:00Z","capability_check":{"ok":false,"device_count":2,"tailnet":"acme.example.com","authentication_mode":"oauth","api_access_token_configured":false,"api_access_token_expires_at":null,"checked_at":"2026-08-18T09:00:00Z","capabilities":{"devices_read":{"ok":true,"code":null},"user_invite":{"ok":false,"code":"invite_permission_missing"},"route_key":{"ok":true,"code":null}},"error":"Tailscale refused the invite with HTTP 403","code":"invite_permission_missing"}}}}},"403":{"description":"The caller holds an access role that grants neither `inbox_manage` nor `whatsapp_hub_manage`. The request stops before the action runs: nothing is changed and no provider is contacted.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","enum":["forbidden"]}}},"example":{"error":"forbidden"}}}},"409":{"description":"This account already has its own configuration — edit it instead.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"code":{"type":"string","description":"Stable symbol for this refusal — the dashboard maps it to copy and to an affordance.","enum":["already_configured"]}}},"example":{"error":"This account already has its own mobile connection. Edit it instead of creating another.","code":"already_configured"}}}},"422":{"description":"The submitted configuration is not valid — a missing or duplicate tailnet, an unreadable token expiry, or encryption not configured on this installation. The record's own sentence is returned because it is more specific than any generic copy; `code` carries the affordance, which is always \"take me back to the form\".","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"code":{"type":"string","description":"Stable symbol for this refusal — the dashboard maps it to copy and to an affordance.","enum":["configuration"]}}},"example":{"error":"Tailnet has already been taken","code":"configuration"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["configuration"],"properties":{"configuration":{"type":"object","required":["tailnet"],"properties":{"tailnet":{"type":"string","example":"acme.example.com"},"active":{"type":"boolean","description":"Defaults to true on creation. Requires Active Record encryption to be configured.","example":true},"auth_key_tags":{"type":"string","description":"Comma-separated Tailscale tags. Omit to derive `tag:cw-egress-acct-\u003caccount_id\u003e`.","example":"tag:cw-egress-acct-41"},"oauth_client_id":{"type":"string","writeOnly":true,"example":"k123CNTRL"},"oauth_client_secret":{"type":"string","writeOnly":true,"example":"tskey-client-REDACTED"},"api_access_token":{"type":"string","writeOnly":true,"example":"tskey-api-REDACTED"}}}}},"example":{"configuration":{"tailnet":"acme.example.com","oauth_client_id":"k123CNTRL","oauth_client_secret":"tskey-client-REDACTED","active":true,"auth_key_tags":"tag:cw-egress-acct-41","api_access_token":"tskey-api-REDACTED"}}}}}}},"/api/v1/accounts/{account_id}/whatsapp_web/mobile_egress/enrollments/{id}/claim":{"post":{"tags":["WhatsApp Web"],"operationId":"auto_post_api_v1_accounts_account_id_whatsapp_web_mobile_egress_enrollments_id_claim","summary":"Claim the newly enrolled phone","description":"Polls provider inventory, filters it to new Android/iOS nodes owned by the enrollment email, enables the advertised exit-node routes, and atomically claims one phone for this account. Supply node_id only when multiple safe candidates are returned.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Enrollment state, optional claimed device, and any ambiguous safe candidates.","content":{"application/json":{"schema":{"type":"object","required":["enrollment","candidates"],"properties":{"enrollment":{"type":"object","required":["id","email","status","expires_at","expired"],"properties":{"id":{"type":"string","format":"uuid","example":"65b33191-6098-4d24-8c56-b76e8f1ba15e"},"email":{"type":"string","format":"email","example":"admin@example.com"},"status":{"type":"string","enum":["pending","waiting_device","waiting_exit_node","claimed","expired","revoked","failed"],"example":"claimed"},"expires_at":{"type":"string","format":"date-time","example":"2026-08-15T07:05:00Z"},"consumed_at":{"type":["string","null"],"format":"date-time","example":"2026-08-15T07:02:00Z"},"expired":{"type":"boolean","example":false}}},"device":{"type":"object","required":["id","name","platform","status","capacity","available_capacity"],"properties":{"id":{"type":"string","format":"uuid","example":"7da824a9-4be1-4ff2-bf65-4bd0fa453918"},"name":{"type":"string","example":"Guilherme Android"},"hostname":{"type":["string","null"],"example":"pixel-9"},"platform":{"type":"string","enum":["android","ios"],"example":"android"},"status":{"type":"string","enum":["pending","online","offline","paused","revoked"],"example":"online"},"capacity":{"type":"integer","minimum":1,"maximum":10,"example":1},"available_capacity":{"type":"integer","minimum":0,"example":1},"last_seen_at":{"type":["string","null"],"format":"date-time","example":"2026-08-15T07:00:00Z"},"approved_at":{"type":["string","null"],"format":"date-time","example":"2026-08-15T06:55:00Z"},"paused_at":{"type":["string","null"],"format":"date-time","example":null},"revoked_at":{"type":["string","null"],"format":"date-time","example":null}}},"candidates":{"type":"array","items":{"type":"object","required":["node_id","name","os","connected","advertised_routes"],"properties":{"node_id":{"type":"string","example":"n7uCNp8mL6CNTRL"},"name":{"type":"string","example":"pixel-9.tailnet.ts.net"},"hostname":{"type":["string","null"],"example":"pixel-9"},"os":{"type":"string","enum":["android","ios"],"example":"android"},"connected":{"type":"boolean","example":true},"advertised_routes":{"type":"array","items":{"type":"string","enum":["0.0.0.0/0","::/0"]},"example":["0.0.0.0/0","::/0"]}}}}}},"example":{"enrollment":{"id":"65b33191-6098-4d24-8c56-b76e8f1ba15e","email":"admin@example.com","status":"claimed","expires_at":"2026-08-15T07:05:00Z","consumed_at":"2026-08-15T07:02:00Z","expired":false},"device":{"id":"7da824a9-4be1-4ff2-bf65-4bd0fa453918","name":"Guilherme Android","hostname":"pixel-9","platform":"android","status":"online","capacity":1,"available_capacity":1,"last_seen_at":"2026-08-15T07:02:00Z","approved_at":"2026-08-15T07:02:00Z","paused_at":null,"revoked_at":null},"candidates":[{"node_id":"n7uCNp8mL6CNTRL","name":"pixel-9.tailnet.ts.net","hostname":"pixel-9","os":"android","connected":true,"advertised_routes":["0.0.0.0/0","::/0"]}]}}}},"401":{"description":"The caller is not authorized for this action: not an account administrator, and without an access role that is allowed it. An access role that grants neither inbox nor WhatsApp-hub management is answered 403, not 401.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Sentence for the operator, already translated to the account locale."}}},"example":{"error":"You are not authorized to do this action"}}}},"404":{"description":"No record with this identifier belongs to the current account. An identifier that never existed and one owned by another account answer identically, so this endpoint cannot be used to probe for identifiers.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Sentence for the operator, already translated to the account locale."}}},"example":{"error":"Resource could not be found"}}}},"403":{"description":"The caller holds an access role that grants neither `inbox_manage` nor `whatsapp_hub_manage`. The request stops before the action runs: nothing is changed and no provider is contacted.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","enum":["forbidden"]}}},"example":{"error":"forbidden"}}}},"422":{"description":"The claim could not complete. A still-open enrollment with no phone visible yet is NOT an error — it answers 200 with `status: waiting_device` and an empty `device`. This status is for the dead ends: the enrollment is over, the phone is registered to another account on the same tailnet, exit-node sharing was not enabled, or the provider inventory could not be read.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"code":{"type":"string","description":"Stable symbol for this refusal — the dashboard maps it to copy and to an affordance.","enum":["expired","already_claimed","account_mismatch","claimed_device_missing","exit_routes_not_enabled","device_inventory_invalid","invalid_credentials","tailnet_not_found","oauth_token_not_issued","provider_response_malformed","configuration","network_error","provider_error"]}}},"example":{"error":"This enrollment has expired. Generate a new one-time invitation.","code":"expired"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"node_id":{"type":"string","example":"n7uCNp8mL6CNTRL"}}},"example":{"node_id":"n7uCNp8mL6CNTRL"}}}}}},"/api/v1/accounts/{account_id}/whatsapp_web/mobile_egress/enrollments":{"post":{"tags":["WhatsApp Web"],"operationId":"auto_post_api_v1_accounts_account_id_whatsapp_web_mobile_egress_enrollments","summary":"Start an individual phone enrollment","description":"Creates a five-minute, one-time Tailscale enrollment for the current account administrator. All four consent acknowledgements must be true. The HTTPS join URL and derived SVG QR are returned only in this 201 response and are never persisted or returned by polling.","security":[{"userApiKey":[]}],"responses":{"201":{"description":"Safe enrollment state plus the one-time join URL and QR.","content":{"application/json":{"schema":{"type":"object","required":["id","email","status","expires_at","expired","downloads","join_url","qr_code"],"properties":{"id":{"type":"string","format":"uuid","example":"65b33191-6098-4d24-8c56-b76e8f1ba15e"},"email":{"type":"string","format":"email","example":"admin@example.com"},"status":{"type":"string","enum":["pending","waiting_device","waiting_exit_node","claimed","expired","revoked","failed"],"example":"waiting_device"},"expires_at":{"type":"string","format":"date-time","example":"2026-08-15T07:05:00Z"},"consumed_at":{"type":["string","null"],"format":"date-time","example":null},"expired":{"type":"boolean","example":false},"downloads":{"type":"object","required":["android","ios"],"properties":{"android":{"type":"string","format":"uri","example":"https://tailscale.com/download/android"},"ios":{"type":"string","format":"uri","example":"https://tailscale.com/download/ios"}}},"join_url":{"type":"string","format":"uri","readOnly":true,"example":"https://login.tailscale.com/uinv/example-one-time-code"},"qr_code":{"type":"string","readOnly":true,"description":"Base64-encoded SVG data URI derived from the one-time join URL.","example":"data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciLz4="}}},"example":{"id":"65b33191-6098-4d24-8c56-b76e8f1ba15e","email":"admin@example.com","status":"waiting_device","expires_at":"2026-08-15T07:05:00Z","consumed_at":null,"expired":false,"downloads":{"android":"https://tailscale.com/download/android","ios":"https://tailscale.com/download/ios"},"join_url":"https://login.tailscale.com/uinv/example-one-time-code","qr_code":"data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciLz4="}}}},"401":{"description":"The caller is not authorized for this action: not an account administrator, and without an access role that is allowed it. An access role that grants neither inbox nor WhatsApp-hub management is answered 403, not 401.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Sentence for the operator, already translated to the account locale."}}},"example":{"error":"You are not authorized to do this action"}}}},"404":{"description":"Account or resource not found"},"403":{"description":"The caller holds an access role that grants neither `inbox_manage` nor `whatsapp_hub_manage`. The request stops before the action runs: nothing is changed and no provider is contacted.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","enum":["forbidden"]}}},"example":{"error":"forbidden"}}}},"422":{"description":"The enrollment could not be opened. Every reachable cause is here, and none of them is fixed by repeating the same request: the feature is off, no connection resolves, the consent acknowledgements are incomplete, or the provider refused to mint the invitation. When the invitation WAS created and something afterwards failed, it is revoked before this is answered — no live invitation is ever left circulating without a record pointing at it.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"code":{"type":"string","description":"Stable symbol for this refusal — the dashboard maps it to copy and to the one affordance that can help. Absent only when the request is rejected before the mobile-egress logic runs (a missing `email`, or a model validation, which answer the framework's own envelope).","enum":["feature_disabled","configuration","account_mismatch","consent_required","already_claimed","invite_permission_missing","invite_not_created","invite_url_missing","invalid_credentials","tailnet_not_found","oauth_token_not_issued","provider_response_malformed","network_error","provider_error"]}}},"example":{"error":"The saved credential can read the network but is not allowed to invite a phone — no Tailscale OAuth scope covers user invites. Store a personal API access token (tskey-api-…) on this connection.","code":"invite_permission_missing"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email","consent"],"properties":{"email":{"type":"string","format":"email","example":"admin@example.com"},"consent":{"type":"object","required":["version","network","power","scope","limits"],"properties":{"version":{"type":"string","enum":["2026-08-15"],"example":"2026-08-15"},"network":{"type":"boolean","example":true},"power":{"type":"boolean","example":true},"scope":{"type":"boolean","example":true},"limits":{"type":"boolean","example":true}}}}},"example":{"email":"admin@example.com","consent":{"version":"2026-08-15","network":true,"power":true,"scope":true,"limits":true}}}}}}},"/api/v1/accounts/{account_id}/whatsapp_web/mobile_egress/enrollments/{id}":{"get":{"tags":["WhatsApp Web"],"operationId":"auto_get_api_v1_accounts_account_id_whatsapp_web_mobile_egress_enrollments_id","summary":"Poll a phone enrollment","description":"Returns current account-scoped enrollment state for polling. This operation deliberately never returns the one-time join URL or QR, even when the enrollment remains open.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Safe enrollment state without one-time credentials.","content":{"application/json":{"schema":{"type":"object","required":["id","email","status","expires_at","expired","downloads"],"properties":{"id":{"type":"string","format":"uuid","example":"65b33191-6098-4d24-8c56-b76e8f1ba15e"},"email":{"type":"string","format":"email","example":"admin@example.com"},"status":{"type":"string","enum":["pending","waiting_device","waiting_exit_node","claimed","expired","revoked","failed"],"example":"waiting_exit_node"},"expires_at":{"type":"string","format":"date-time","example":"2026-08-15T07:05:00Z"},"consumed_at":{"type":["string","null"],"format":"date-time","example":null},"expired":{"type":"boolean","example":false},"downloads":{"type":"object","required":["android","ios"],"properties":{"android":{"type":"string","format":"uri","example":"https://tailscale.com/download/android"},"ios":{"type":"string","format":"uri","example":"https://tailscale.com/download/ios"}}}}},"example":{"id":"65b33191-6098-4d24-8c56-b76e8f1ba15e","email":"admin@example.com","status":"waiting_exit_node","expires_at":"2026-08-15T07:05:00Z","consumed_at":null,"expired":false,"downloads":{"android":"https://tailscale.com/download/android","ios":"https://tailscale.com/download/ios"}}}}},"401":{"description":"The caller is not authorized for this action: not an account administrator, and without an access role that is allowed it. An access role that grants neither inbox nor WhatsApp-hub management is answered 403, not 401.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Sentence for the operator, already translated to the account locale."}}},"example":{"error":"You are not authorized to do this action"}}}},"404":{"description":"No record with this identifier belongs to the current account. An identifier that never existed and one owned by another account answer identically, so this endpoint cannot be used to probe for identifiers.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Sentence for the operator, already translated to the account locale."}}},"example":{"error":"Resource could not be found"}}}},"403":{"description":"The caller holds an access role that grants neither `inbox_manage` nor `whatsapp_hub_manage`. The request stops before the action runs: nothing is changed and no provider is contacted.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","enum":["forbidden"]}}},"example":{"error":"forbidden"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]},"delete":{"tags":["WhatsApp Web"],"operationId":"auto_delete_api_v1_accounts_account_id_whatsapp_web_mobile_egress_enrollments_id","summary":"Revoke an open phone enrollment","description":"Revokes the account-scoped enrollment and its external one-time invitation when still open.","security":[{"userApiKey":[]}],"responses":{"204":{"description":"Enrollment revoked; no response body."},"401":{"description":"The caller is not authorized for this action: not an account administrator, and without an access role that is allowed it. An access role that grants neither inbox nor WhatsApp-hub management is answered 403, not 401.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Sentence for the operator, already translated to the account locale."}}},"example":{"error":"You are not authorized to do this action"}}}},"404":{"description":"No record with this identifier belongs to the current account. An identifier that never existed and one owned by another account answer identically, so this endpoint cannot be used to probe for identifiers.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Sentence for the operator, already translated to the account locale."}}},"example":{"error":"Resource could not be found"}}}},"403":{"description":"The caller holds an access role that grants neither `inbox_manage` nor `whatsapp_hub_manage`. The request stops before the action runs: nothing is changed and no provider is contacted.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","enum":["forbidden"]}}},"example":{"error":"forbidden"}}}},"422":{"description":"The provider call this action depends on did not succeed. Nothing local was changed, so the same request can be retried once the cause is addressed.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"code":{"type":"string","description":"Stable symbol for this refusal — the dashboard maps it to copy and to an affordance.","enum":["invalid_credentials","tailnet_not_found","oauth_token_not_issued","provider_response_malformed","device_inventory_invalid","configuration","network_error","provider_error"]}}},"example":{"error":"Tailscale could not be reached. If the network blipped, trying again works; if it keeps failing, DNS, TLS or a firewall is blocking this server and your operator has to unblock it.","code":"network_error"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/whatsapp_web/mobile_egress/devices/sync":{"post":{"tags":["WhatsApp Web"],"operationId":"auto_post_api_v1_accounts_account_id_whatsapp_web_mobile_egress_devices_sync","summary":"Synchronize enrolled phone status","description":"Refreshes account-owned phone connectivity and exit-route metadata from the configured provider. A sync that fails in front of the operator also writes the connection's health, so the panel cannot keep asserting \"online\" while the error is still on screen.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Safe phone inventory.","content":{"application/json":{"schema":{"type":"object","required":["devices"],"properties":{"devices":{"type":"array","items":{"type":"object","required":["id","name","platform","status","capacity","available_capacity"],"properties":{"id":{"type":"string","format":"uuid","example":"7da824a9-4be1-4ff2-bf65-4bd0fa453918"},"name":{"type":"string","example":"Guilherme Android"},"hostname":{"type":["string","null"],"example":"pixel-9"},"platform":{"type":"string","enum":["android","ios"],"example":"android"},"status":{"type":"string","enum":["pending","online","offline","paused","revoked"],"example":"online"},"capacity":{"type":"integer","minimum":1,"maximum":10,"example":1},"available_capacity":{"type":"integer","minimum":0,"example":1},"last_seen_at":{"type":["string","null"],"format":"date-time","example":"2026-08-15T07:00:00Z"},"approved_at":{"type":["string","null"],"format":"date-time","example":"2026-08-15T06:55:00Z"},"paused_at":{"type":["string","null"],"format":"date-time","example":null},"revoked_at":{"type":["string","null"],"format":"date-time","example":null}}}}}},"example":{"devices":[{"id":"7da824a9-4be1-4ff2-bf65-4bd0fa453918","name":"Guilherme Android","hostname":"pixel-9","platform":"android","status":"online","capacity":1,"available_capacity":1,"last_seen_at":"2026-08-15T07:00:00Z","approved_at":"2026-08-15T06:55:00Z","paused_at":null,"revoked_at":null}]}}}},"401":{"description":"The caller is not authorized for this action: not an account administrator, and without an access role that is allowed it. An access role that grants neither inbox nor WhatsApp-hub management is answered 403, not 401.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Sentence for the operator, already translated to the account locale."}}},"example":{"error":"You are not authorized to do this action"}}}},"404":{"description":"Account or resource not found"},"403":{"description":"The caller holds an access role that grants neither `inbox_manage` nor `whatsapp_hub_manage`. The request stops before the action runs: nothing is changed and no provider is contacted.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","enum":["forbidden"]}}},"example":{"error":"forbidden"}}}},"422":{"description":"Nothing resolves for this account (or what resolves is switched off), or the provider read failed. A typed answer, not the bodiless 404 this used to be — which read exactly like a missing endpoint and left the caller unable to tell \"never set up\" from \"broken deploy\".","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"code":{"type":"string","description":"Stable symbol for this refusal — the dashboard maps it to copy and to an affordance.","enum":["invalid_credentials","tailnet_not_found","oauth_token_not_issued","provider_response_malformed","device_inventory_invalid","configuration","network_error","provider_error"]}}},"example":{"error":"The Tailscale credentials are invalid or expired.","code":"invalid_credentials"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/whatsapp_web/mobile_egress/devices/{id}/pause":{"post":{"tags":["WhatsApp Web"],"operationId":"auto_post_api_v1_accounts_account_id_whatsapp_web_mobile_egress_devices_id_pause","summary":"Pause an unused phone-egress device","description":"Pauses an account-owned phone only when it has no current route lease.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Updated safe phone state.","content":{"application/json":{"schema":{"type":"object","required":["id","name","platform","status","capacity","available_capacity"],"properties":{"id":{"type":"string","format":"uuid","example":"7da824a9-4be1-4ff2-bf65-4bd0fa453918"},"name":{"type":"string","example":"Guilherme Android"},"hostname":{"type":["string","null"],"example":"pixel-9"},"platform":{"type":"string","enum":["android","ios"],"example":"android"},"status":{"type":"string","enum":["pending","online","offline","paused","revoked"],"example":"online"},"capacity":{"type":"integer","minimum":1,"maximum":10,"example":1},"available_capacity":{"type":"integer","minimum":0,"example":1},"last_seen_at":{"type":["string","null"],"format":"date-time","example":"2026-08-15T07:00:00Z"},"approved_at":{"type":["string","null"],"format":"date-time","example":"2026-08-15T06:55:00Z"},"paused_at":{"type":["string","null"],"format":"date-time","example":null},"revoked_at":{"type":["string","null"],"format":"date-time","example":null}}},"example":{"id":"7da824a9-4be1-4ff2-bf65-4bd0fa453918","name":"Guilherme Android","hostname":"pixel-9","platform":"android","status":"paused","capacity":1,"available_capacity":1,"last_seen_at":"2026-08-15T07:00:00Z","approved_at":"2026-08-15T06:55:00Z","paused_at":"2026-08-15T07:03:00Z","revoked_at":null}}}},"401":{"description":"The caller is not authorized for this action: not an account administrator, and without an access role that is allowed it. An access role that grants neither inbox nor WhatsApp-hub management is answered 403, not 401.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Sentence for the operator, already translated to the account locale."}}},"example":{"error":"You are not authorized to do this action"}}}},"404":{"description":"No record with this identifier belongs to the current account. An identifier that never existed and one owned by another account answer identically, so this endpoint cannot be used to probe for identifiers.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Sentence for the operator, already translated to the account locale."}}},"example":{"error":"Resource could not be found"}}}},"403":{"description":"The caller holds an access role that grants neither `inbox_manage` nor `whatsapp_hub_manage`. The request stops before the action runs: nothing is changed and no provider is contacted.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","enum":["forbidden"]}}},"example":{"error":"forbidden"}}}},"409":{"description":"The phone is currently carrying the route of an inbox. Unlink it there first — pausing or revoking a phone that traffic is flowing through would take that inbox offline without anyone asking for it.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"code":{"type":"string","description":"Stable symbol for this refusal — the dashboard maps it to copy and to an affordance.","enum":["device_has_active_lease"]}}},"example":{"error":"Unlink this device from its inbox before pausing or revoking it.","code":"device_has_active_lease"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/whatsapp_web/mobile_egress/devices/{id}/resume":{"post":{"tags":["WhatsApp Web"],"operationId":"auto_post_api_v1_accounts_account_id_whatsapp_web_mobile_egress_devices_id_resume","summary":"Resume a paused phone-egress device","description":"Clears the pause and returns the account-owned phone to offline until the next provider sync confirms it online.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Updated safe phone state.","content":{"application/json":{"schema":{"type":"object","required":["id","name","platform","status","capacity","available_capacity"],"properties":{"id":{"type":"string","format":"uuid","example":"7da824a9-4be1-4ff2-bf65-4bd0fa453918"},"name":{"type":"string","example":"Guilherme Android"},"hostname":{"type":["string","null"],"example":"pixel-9"},"platform":{"type":"string","enum":["android","ios"],"example":"android"},"status":{"type":"string","enum":["pending","online","offline","paused","revoked"],"example":"online"},"capacity":{"type":"integer","minimum":1,"maximum":10,"example":1},"available_capacity":{"type":"integer","minimum":0,"example":1},"last_seen_at":{"type":["string","null"],"format":"date-time","example":"2026-08-15T07:00:00Z"},"approved_at":{"type":["string","null"],"format":"date-time","example":"2026-08-15T06:55:00Z"},"paused_at":{"type":["string","null"],"format":"date-time","example":null},"revoked_at":{"type":["string","null"],"format":"date-time","example":null}}},"example":{"id":"7da824a9-4be1-4ff2-bf65-4bd0fa453918","name":"Guilherme Android","hostname":"pixel-9","platform":"android","status":"offline","capacity":1,"available_capacity":1,"last_seen_at":"2026-08-15T07:00:00Z","approved_at":"2026-08-15T06:55:00Z","paused_at":null,"revoked_at":null}}}},"401":{"description":"The caller is not authorized for this action: not an account administrator, and without an access role that is allowed it. An access role that grants neither inbox nor WhatsApp-hub management is answered 403, not 401.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Sentence for the operator, already translated to the account locale."}}},"example":{"error":"You are not authorized to do this action"}}}},"404":{"description":"No record with this identifier belongs to the current account. An identifier that never existed and one owned by another account answer identically, so this endpoint cannot be used to probe for identifiers.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Sentence for the operator, already translated to the account locale."}}},"example":{"error":"Resource could not be found"}}}},"403":{"description":"The caller holds an access role that grants neither `inbox_manage` nor `whatsapp_hub_manage`. The request stops before the action runs: nothing is changed and no provider is contacted.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","enum":["forbidden"]}}},"example":{"error":"forbidden"}}}},"422":{"description":"A revoked phone cannot be resumed — it has to be enrolled again.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"code":{"type":"string","description":"Stable symbol for this refusal — the dashboard maps it to copy and to an affordance.","enum":["device_revoked"]}}},"example":{"error":"This phone was revoked and cannot be used again.","code":"device_revoked"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/whatsapp_web/mobile_egress/devices":{"get":{"tags":["WhatsApp Web"],"operationId":"auto_get_api_v1_accounts_account_id_whatsapp_web_mobile_egress_devices","summary":"List enrolled phone-egress devices","description":"Returns only non-revoked phones owned by the current account, with safe status and capacity fields.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Safe phone inventory.","content":{"application/json":{"schema":{"type":"object","required":["devices"],"properties":{"devices":{"type":"array","items":{"type":"object","required":["id","name","platform","status","capacity","available_capacity"],"properties":{"id":{"type":"string","format":"uuid","example":"7da824a9-4be1-4ff2-bf65-4bd0fa453918"},"name":{"type":"string","example":"Guilherme Android"},"hostname":{"type":["string","null"],"example":"pixel-9"},"platform":{"type":"string","enum":["android","ios"],"example":"android"},"status":{"type":"string","enum":["pending","online","offline","paused","revoked"],"example":"online"},"capacity":{"type":"integer","minimum":1,"maximum":10,"example":1},"available_capacity":{"type":"integer","minimum":0,"example":1},"last_seen_at":{"type":["string","null"],"format":"date-time","example":"2026-08-15T07:00:00Z"},"approved_at":{"type":["string","null"],"format":"date-time","example":"2026-08-15T06:55:00Z"},"paused_at":{"type":["string","null"],"format":"date-time","example":null},"revoked_at":{"type":["string","null"],"format":"date-time","example":null}}}}}},"example":{"devices":[{"id":"7da824a9-4be1-4ff2-bf65-4bd0fa453918","name":"Guilherme Android","hostname":"pixel-9","platform":"android","status":"online","capacity":1,"available_capacity":1,"last_seen_at":"2026-08-15T07:00:00Z","approved_at":"2026-08-15T06:55:00Z","paused_at":null,"revoked_at":null}]}}}},"401":{"description":"The caller is not authorized for this action: not an account administrator, and without an access role that is allowed it. An access role that grants neither inbox nor WhatsApp-hub management is answered 403, not 401.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Sentence for the operator, already translated to the account locale."}}},"example":{"error":"You are not authorized to do this action"}}}},"404":{"description":"Account or resource not found"},"403":{"description":"The caller holds an access role that grants neither `inbox_manage` nor `whatsapp_hub_manage`. The request stops before the action runs: nothing is changed and no provider is contacted.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","enum":["forbidden"]}}},"example":{"error":"forbidden"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."}]}},"/api/v1/accounts/{account_id}/whatsapp_web/mobile_egress/devices/{id}":{"delete":{"tags":["WhatsApp Web"],"operationId":"auto_delete_api_v1_accounts_account_id_whatsapp_web_mobile_egress_devices_id","summary":"Revoke an unused phone-egress device","description":"Disables exit routes and revokes an account-owned phone only when it has no current route lease.","security":[{"userApiKey":[]}],"responses":{"204":{"description":"Phone revoked; no response body."},"401":{"description":"The caller is not authorized for this action: not an account administrator, and without an access role that is allowed it. An access role that grants neither inbox nor WhatsApp-hub management is answered 403, not 401.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Sentence for the operator, already translated to the account locale."}}},"example":{"error":"You are not authorized to do this action"}}}},"404":{"description":"No record with this identifier belongs to the current account. An identifier that never existed and one owned by another account answer identically, so this endpoint cannot be used to probe for identifiers.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Sentence for the operator, already translated to the account locale."}}},"example":{"error":"Resource could not be found"}}}},"403":{"description":"The caller holds an access role that grants neither `inbox_manage` nor `whatsapp_hub_manage`. The request stops before the action runs: nothing is changed and no provider is contacted.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","enum":["forbidden"]}}},"example":{"error":"forbidden"}}}},"409":{"description":"The phone is currently carrying the route of an inbox. Unlink it there first — pausing or revoking a phone that traffic is flowing through would take that inbox offline without anyone asking for it.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"code":{"type":"string","description":"Stable symbol for this refusal — the dashboard maps it to copy and to an affordance.","enum":["device_has_active_lease"]}}},"example":{"error":"Unlink this device from its inbox before pausing or revoking it.","code":"device_has_active_lease"}}}},"422":{"description":"The provider call this action depends on did not succeed. Nothing local was changed, so the same request can be retried once the cause is addressed.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"code":{"type":"string","description":"Stable symbol for this refusal — the dashboard maps it to copy and to an affordance.","enum":["invalid_credentials","tailnet_not_found","oauth_token_not_issued","provider_response_malformed","device_inventory_invalid","configuration","network_error","provider_error"]}}},"example":{"error":"Tailscale could not be reached. If the network blipped, trying again works; if it keeps failing, DNS, TLS or a firewall is blocking this server and your operator has to unblock it.","code":"network_error"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/whatsapp_web/groups/{jid}/leave":{"post":{"tags":["WhatsApp Web"],"operationId":"auto_post_api_v1_accounts_account_id_whatsapp_web_groups_jid_leave","summary":"Leave a WhatsApp group","description":"Gateway /group/leave `data`. On success the matching platform conversation is archived (status resolved) because leaving is irrecoverable on WhatsApp.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Gateway confirmation.","content":{"application/json":{"schema":{"type":"object","properties":{"Details":{"type":"string","example":"Group left successfully"}}},"example":{"Details":"Group left successfully"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"jid","in":"path","required":true,"schema":{"type":"string"}},{"name":"inbox_id","in":"query","required":true,"description":"The WhatsApp Web inbox whose session owns the group. The operation runs only through this inbox's own gateway session, so it can never reach a group of another inbox. Required: without it, or with an id that is not a WhatsApp Web inbox of this account the caller can operate (or the Web sibling of a unified hybrid Cloud inbox), the request answers 404.","schema":{"type":"integer"},"example":8}]}},"/api/v1/accounts/{account_id}/whatsapp_web/groups/{jid}/participants":{"post":{"tags":["WhatsApp Web"],"operationId":"auto_post_api_v1_accounts_account_id_whatsapp_web_groups_jid_participants","summary":"Add / remove / promote / demote group participants","description":"Runs the add/remove/promote/demote action against /group/updateparticipants. For `add`, phones are validated on WhatsApp first (422 if a number is not on WhatsApp). Returns the gateway `data` confirmation.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Gateway confirmation.","content":{"application/json":{"schema":{"type":"object","properties":{"Details":{"type":"string","example":"Group Participants updated successfully"}}},"example":{"Details":"Group Participants updated successfully"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"jid","in":"path","required":true,"schema":{"type":"string"}},{"name":"inbox_id","in":"query","required":true,"description":"The WhatsApp Web inbox whose session owns the group. The operation runs only through this inbox's own gateway session, so it can never reach a group of another inbox. Required: without it, or with an id that is not a WhatsApp Web inbox of this account the caller can operate (or the Web sibling of a unified hybrid Cloud inbox), the request answers 404.","schema":{"type":"integer"},"example":8}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"participant_action":{"type":"string"},"phones":{"type":"array","items":{"type":"string"}},"code":{"type":"string"}}},"example":{"participant_action":"sample participant action","phones":["+5511999998888"],"code":"sample code"}}}}}},"/api/v1/accounts/{account_id}/whatsapp_web/groups/{jid}/photo":{"post":{"tags":["WhatsApp Web"],"operationId":"auto_post_api_v1_accounts_account_id_whatsapp_web_groups_jid_photo","summary":"Set the group photo","description":"Normalizes the image to a JPEG data URI and POSTs /group/photo. Returns the gateway `data` (Details + the new PictureID).","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Gateway confirmation with the new picture id.","content":{"application/json":{"schema":{"type":"object","properties":{"Details":{"type":"string","example":"Group Photo set successfully"},"PictureID":{"type":"string","example":"1603824000"}}},"example":{"Details":"Group Photo set successfully","PictureID":"1603824000"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"jid","in":"path","required":true,"schema":{"type":"string"}},{"name":"inbox_id","in":"query","required":true,"description":"The WhatsApp Web inbox whose session owns the group. The operation runs only through this inbox's own gateway session, so it can never reach a group of another inbox. Required: without it, or with an id that is not a WhatsApp Web inbox of this account the caller can operate (or the Web sibling of a unified hybrid Cloud inbox), the request answers 404.","schema":{"type":"integer"},"example":8}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"image":{"type":"string"}}},"example":{"image":"sample image"}}}}},"delete":{"tags":["WhatsApp Web"],"operationId":"auto_delete_api_v1_accounts_account_id_whatsapp_web_groups_jid_photo","summary":"Remove the group photo","description":"Gateway /group/photo/remove `data`.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Gateway confirmation.","content":{"application/json":{"schema":{"type":"object","properties":{"Details":{"type":"string","example":"Group Photo removed successfully"}}},"example":{"Details":"Group Photo removed successfully"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"jid","in":"path","required":true,"schema":{"type":"string"}},{"name":"inbox_id","in":"query","required":true,"description":"The WhatsApp Web inbox whose session owns the group. The operation runs only through this inbox's own gateway session, so it can never reach a group of another inbox. Required: without it, or with an id that is not a WhatsApp Web inbox of this account the caller can operate (or the Web sibling of a unified hybrid Cloud inbox), the request answers 404.","schema":{"type":"integer"},"example":8}]}},"/api/v1/accounts/{account_id}/whatsapp_web/groups/{jid}/invite":{"get":{"tags":["WhatsApp Web"],"operationId":"auto_get_api_v1_accounts_account_id_whatsapp_web_groups_jid_invite","summary":"Get the group invite link","description":"Gateway /group/invitelink `data` (reset=false).","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The current invite link.","content":{"application/json":{"schema":{"type":"object","properties":{"InviteLink":{"type":"string","example":"https://chat.whatsapp.com/ABCDEFGHIJKLMNO"}}},"example":{"InviteLink":"https://chat.whatsapp.com/ABCDEFGHIJKLMNO"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"jid","in":"path","required":true,"schema":{"type":"string"}},{"name":"inbox_id","in":"query","required":true,"description":"The WhatsApp Web inbox whose session owns the group. The operation runs only through this inbox's own gateway session, so it can never reach a group of another inbox. Required: without it, or with an id that is not a WhatsApp Web inbox of this account the caller can operate (or the Web sibling of a unified hybrid Cloud inbox), the request answers 404.","schema":{"type":"integer"},"example":8}]}},"/api/v1/accounts/{account_id}/whatsapp_web/groups/{jid}/regenerate_invite":{"post":{"tags":["WhatsApp Web"],"operationId":"auto_post_api_v1_accounts_account_id_whatsapp_web_groups_jid_regenerate_invite","summary":"Regenerate the group invite link","description":"Gateway /group/invitelink `data` with reset=true — revokes the old link, mints a new one.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The freshly minted invite link.","content":{"application/json":{"schema":{"type":"object","properties":{"InviteLink":{"type":"string","example":"https://chat.whatsapp.com/XYZ123ABCDEFGHI"}}},"example":{"InviteLink":"https://chat.whatsapp.com/XYZ123ABCDEFGHI"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"jid","in":"path","required":true,"schema":{"type":"string"}},{"name":"inbox_id","in":"query","required":true,"description":"The WhatsApp Web inbox whose session owns the group. The operation runs only through this inbox's own gateway session, so it can never reach a group of another inbox. Required: without it, or with an id that is not a WhatsApp Web inbox of this account the caller can operate (or the Web sibling of a unified hybrid Cloud inbox), the request answers 404.","schema":{"type":"integer"},"example":8}]}},"/api/v1/accounts/{account_id}/whatsapp_web/groups/{jid}/participant_operation_scope":{"get":{"tags":["WhatsApp Web"],"operationId":"auto_get_api_v1_accounts_account_id_whatsapp_web_groups_jid_participant_operation_scope","summary":"Read the group's participant-operation scope","description":"Requires the existing administrative or permitted native-role access and an authorized Web-capable inbox. Reads local WazMeow authority for this account's connection and group, including conflicting operations from another principal. No online WhatsApp Client, roster refresh, reservation, submit or release is requested. A resolvable local physical binding and a valid authority database read are still required. Unavailable or malformed upstream responses return 503, never an idle or null scope. This observation is not permission to mutate participants; writes must reserve authority independently. A confirmation_pending operation has no guaranteed completion deadline. Other groups, messages and unrelated group settings remain available.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Credential-free local scope. idle means no active authority was found by a successful bound read; it does not confirm a remote participant effect. Clients retain their last known scope when a later read fails and discard responses for a previous account, inbox or group.","headers":{"Cache-Control":{"description":"The observation is never cached.","schema":{"type":"string","enum":["no-store"]},"example":"no-store"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["payload"],"properties":{"payload":{"type":"object","additionalProperties":false,"required":["contract_version","scope_ref","group_jid","scope_revision","blocked","active_state","operation_visible_to_caller"],"properties":{"contract_version":{"type":"string","enum":["group-participant-operation.v1"]},"scope_ref":{"type":"string","description":"Opaque physical scope reference; contains no account identifier or credential."},"group_jid":{"type":"string","description":"The literal requested group JID."},"scope_revision":{"type":"integer","description":"Revision supplied by the local gateway authority."},"blocked":{"type":"boolean","description":"True while the group authority is held or fenced."},"active_state":{"type":"string","enum":["idle","reserved","in_flight","confirmation_pending","fenced"],"description":"reserved and in_flight describe work in progress. confirmation_pending requires waiting for evidence, without automatic resending or age-based release. fenced denotes unavailable admission, not a confirmed remote effect."},"operation_ref":{"type":"string","description":"Optional opaque operation identifier. It is not a caller key or permission to retrieve another principal's operation."},"operation_visible_to_caller":{"type":"boolean","description":"Whether the held operation belongs to the authenticated gateway principal."}}}}},"example":{"payload":{"contract_version":"group-participant-operation.v1","scope_ref":"fixture-scope-ref","group_jid":"120363000000001@g.us","scope_revision":1,"blocked":true,"active_state":"confirmation_pending","operation_ref":"fixture-operation-ref","operation_visible_to_caller":true}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"503":{"description":"The scope cannot be read safely: binding, storage, authority or transport is unavailable, or the upstream response does not match the contract. No absence or remote success is inferred. Local authentication and account/inbox authorization failures retain their existing responses.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","enum":["participant_operation_scope_unavailable"]}}},"example":{"error":"participant_operation_scope_unavailable"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"description":"Authenticated Chatwoot account.","schema":{"type":"integer"}},{"name":"jid","in":"path","required":true,"description":"Literal WhatsApp group JID. The connection is selected from the authorized inbox.","schema":{"type":"string"}},{"name":"inbox_id","in":"query","required":true,"description":"Account-scoped inbox; a unified hybrid inbox resolves to its Web capability connection.","schema":{"type":"integer"}}]}},"/api/v1/accounts/{account_id}/whatsapp_web/groups/join":{"post":{"tags":["WhatsApp Web"],"operationId":"auto_post_api_v1_accounts_account_id_whatsapp_web_groups_join","summary":"Join a group via invite code","description":"Gateway /group/join `data`.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Gateway confirmation.","content":{"application/json":{"schema":{"type":"object","properties":{"Details":{"type":"string","example":"Group joined successfully"}}},"example":{"Details":"Group joined successfully"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"inbox_id","in":"query","required":true,"description":"The WhatsApp Web inbox whose session joins the group. Required: without it, or with an id that is not a WhatsApp Web inbox of this account the caller can operate (or the Web sibling of a unified hybrid Cloud inbox), the request answers 404.","schema":{"type":"integer"},"example":8}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"}}},"example":{"code":"sample code"}}}}}},"/api/v1/accounts/{account_id}/whatsapp_web/groups":{"get":{"tags":["WhatsApp Web"],"operationId":"auto_get_api_v1_accounts_account_id_whatsapp_web_groups","summary":"List joined WhatsApp groups","description":"Gateway /group/list `data` — the marshaled whatsmeow GroupCollection. Returns [] for an un-paired channel (graceful no-session degradation).","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The groups the paired account participates in.","content":{"application/json":{"schema":{"type":"object","properties":{"Groups":{"type":"array","items":{"type":"object","properties":{"JID":{"type":"string","example":"120363420116051586@g.us"},"OwnerJID":{"type":"string","example":"5521999999999@s.whatsapp.net"},"Name":{"type":"string","example":"Team Support"},"NameSetAt":{"type":"string","format":"date-time","example":"2026-01-15T10:30:00.000Z"},"Topic":{"type":"string","example":"Support coordination"},"IsLocked":{"type":"boolean","example":false},"IsAnnounce":{"type":"boolean","example":false},"IsEphemeral":{"type":"boolean","example":false},"DisappearingTimer":{"type":"integer","example":0},"IsParent":{"type":"boolean","example":false},"LinkedParentJID":{"type":"string","example":""},"GroupCreated":{"type":"string","format":"date-time","example":"2026-01-15T10:30:00.000Z"},"ParticipantCount":{"type":"integer","example":3},"MemberAddMode":{"type":"string","example":"all_member_add"},"Participants":{"type":"array","items":{"type":"object","properties":{"JID":{"type":"string","example":"5521999999999@s.whatsapp.net"},"PhoneNumber":{"type":"string","example":"5521999999999@s.whatsapp.net"},"LID":{"type":"string","example":"140712372899859@lid"},"IsAdmin":{"type":"boolean","example":false},"IsSuperAdmin":{"type":"boolean","example":false},"DisplayName":{"type":"string","example":""}}}}}}}}},"example":{"Groups":[{"JID":"120363420116051586@g.us","OwnerJID":"5521999999999@s.whatsapp.net","Name":"Team Support","NameSetAt":"2026-01-15T10:30:00.000Z","Topic":"Support coordination","IsLocked":false,"IsAnnounce":false,"IsEphemeral":false,"DisappearingTimer":0,"IsParent":false,"LinkedParentJID":"","GroupCreated":"2026-01-15T10:30:00.000Z","ParticipantCount":3,"MemberAddMode":"all_member_add","Participants":[{"JID":"5521999999999@s.whatsapp.net","PhoneNumber":"5521999999999@s.whatsapp.net","LID":"140712372899859@lid","IsAdmin":false,"IsSuperAdmin":false,"DisplayName":""}]}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"inbox_id","in":"query","required":true,"description":"The WhatsApp Web inbox whose joined groups are listed. Required: without it, or with an id that is not a WhatsApp Web inbox of this account the caller can operate (or the Web sibling of a unified hybrid Cloud inbox), the request answers 404.","schema":{"type":"integer"},"example":8},{"name":"page","in":"query","required":false,"description":"Page number for pagination.","schema":{"type":"integer"},"example":1}]},"post":{"tags":["WhatsApp Web"],"operationId":"auto_post_api_v1_accounts_account_id_whatsapp_web_groups","summary":"Create a WhatsApp group","description":"Gateway /group/create `data` — the marshaled whatsmeow GroupInfo for the new group.","security":[{"userApiKey":[]}],"responses":{"201":{"description":"The created group's whatsmeow GroupInfo.","content":{"application/json":{"schema":{"type":"object","properties":{"JID":{"type":"string","example":"120363420116051586@g.us"},"OwnerJID":{"type":"string","example":"5521999999999@s.whatsapp.net"},"Name":{"type":"string","example":"New Group"},"GroupCreated":{"type":"string","format":"date-time","example":"2026-01-15T10:30:00.000Z"},"IsAnnounce":{"type":"boolean","example":false},"IsLocked":{"type":"boolean","example":false},"ParticipantCount":{"type":"integer","example":2},"Participants":{"type":"array","items":{"type":"object","properties":{"JID":{"type":"string","example":"5521999999999@s.whatsapp.net"},"PhoneNumber":{"type":"string","example":"5521999999999@s.whatsapp.net"},"IsAdmin":{"type":"boolean","example":false},"Error":{"type":"integer","description":"whatsmeow per-participant add error code (0 == ok)","example":0}}}}}},"example":{"JID":"120363420116051586@g.us","OwnerJID":"5521999999999@s.whatsapp.net","Name":"New Group","GroupCreated":"2026-01-15T10:30:00.000Z","IsAnnounce":false,"IsLocked":false,"ParticipantCount":2,"Participants":[{"JID":"5521999999999@s.whatsapp.net","PhoneNumber":"5521999999999@s.whatsapp.net","IsAdmin":false,"Error":0}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"inbox_id","in":"query","required":true,"description":"The WhatsApp Web inbox whose session creates (and owns) the group. Required: without it, or with an id that is not a WhatsApp Web inbox of this account the caller can operate (or the Web sibling of a unified hybrid Cloud inbox), the request answers 404.","schema":{"type":"integer"},"example":8}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"participants":{"type":"array","items":{"type":"string"}},"participant_action":{"type":"string"},"phones":{"type":"array","items":{"type":"string"}},"jid":{"type":"string"}}},"example":{"name":"Sample Name","participants":["sample participant"],"participant_action":"sample participant action","phones":["+5511999998888"],"jid":"sample jid"}}}}}},"/api/v1/accounts/{account_id}/whatsapp_web/groups/{jid}":{"get":{"tags":["WhatsApp Web"],"operationId":"auto_get_api_v1_accounts_account_id_whatsapp_web_groups_jid","summary":"Get a group with enriched participants","description":"Gateway /group/info `data` (whatsmeow GroupInfo) enriched server-side — each participant gains Phone (E.164), Name (platform contact/display/push/phone), and Avatar (already-stored contact photo). Raw whatsmeow keys are preserved.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Full group metadata with enriched participants.","content":{"application/json":{"schema":{"type":"object","properties":{"JID":{"type":"string","example":"120363420116051586@g.us"},"OwnerJID":{"type":"string","example":"5521999999999@s.whatsapp.net"},"Name":{"type":"string","example":"Team Support"},"Topic":{"type":"string","example":"Support coordination"},"TopicSetAt":{"type":"string","format":"date-time","example":"2026-01-15T10:30:00.000Z"},"IsLocked":{"type":"boolean","example":false},"IsAnnounce":{"type":"boolean","example":false},"IsEphemeral":{"type":"boolean","example":false},"DisappearingTimer":{"type":"integer","example":0},"IsParent":{"type":"boolean","example":false},"LinkedParentJID":{"type":"string","example":""},"IsJoinApprovalRequired":{"type":"boolean","example":false},"GroupCreated":{"type":"string","format":"date-time","example":"2026-01-15T10:30:00.000Z"},"ParticipantCount":{"type":"integer","example":3},"MemberAddMode":{"type":"string","example":"all_member_add"},"Participants":{"type":"array","items":{"type":"object","properties":{"JID":{"type":"string","example":"140712372899859@lid"},"PhoneNumber":{"type":"string","example":"5521999999999@s.whatsapp.net"},"LID":{"type":"string","example":"140712372899859@lid"},"IsAdmin":{"type":"boolean","example":true},"IsSuperAdmin":{"type":"boolean","example":false},"DisplayName":{"type":"string","example":""},"Phone":{"type":"string","description":"Enriched E.164 (whatsmeow PhoneNumber even when JID is an @lid).","example":"+5521999999999"},"Name":{"type":"string","description":"Enriched display name (contact \u003e display \u003e push \u003e phone \u003e JID).","example":"Maria Silva"},"Avatar":{"type":["string","null"],"description":"Reused platform contact avatar URL, or null.","example":"https://cdn.example.com/avatar/1.png"}}}}}},"example":{"JID":"120363420116051586@g.us","OwnerJID":"5521999999999@s.whatsapp.net","Name":"Team Support","Topic":"Support coordination","TopicSetAt":"2026-01-15T10:30:00.000Z","IsLocked":false,"IsAnnounce":false,"IsEphemeral":false,"DisappearingTimer":0,"IsParent":false,"LinkedParentJID":"","IsJoinApprovalRequired":false,"GroupCreated":"2026-01-15T10:30:00.000Z","ParticipantCount":3,"MemberAddMode":"all_member_add","Participants":[{"JID":"140712372899859@lid","PhoneNumber":"5521999999999@s.whatsapp.net","LID":"140712372899859@lid","IsAdmin":true,"IsSuperAdmin":false,"DisplayName":"","Phone":"+5521999999999","Name":"Maria Silva","Avatar":"https://cdn.example.com/avatar/1.png"}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"jid","in":"path","required":true,"schema":{"type":"string"}},{"name":"inbox_id","in":"query","required":true,"description":"The WhatsApp Web inbox whose session owns the group. The operation runs only through this inbox's own gateway session, so it can never reach a group of another inbox. Required: without it, or with an id that is not a WhatsApp Web inbox of this account the caller can operate (or the Web sibling of a unified hybrid Cloud inbox), the request answers 404.","schema":{"type":"integer"},"example":8}]},"patch":{"tags":["WhatsApp Web"],"operationId":"auto_patch_api_v1_accounts_account_id_whatsapp_web_groups_jid","summary":"Update group settings","description":"Applies only the supplied fields (name/topic/announce/locked/ephemeral_seconds); each key mirrors the gateway `data` for that mutation. Absent inputs are omitted.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Per-field gateway confirmations for the fields that were changed.","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"object","properties":{"Details":{"type":"string","example":"Group Name set successfully"}}},"topic":{"type":"object","properties":{"Details":{"type":"string","example":"Group Topic set successfully"}}},"announce":{"type":"object","properties":{"Details":{"type":"string","example":"Group Announce set successfully"}}},"locked":{"type":"object","properties":{"Details":{"type":"string","example":"Group Locked setting updated successfully"}}},"ephemeral":{"type":"object","properties":{"Details":{"type":"string","example":"Disappearing timer set successfully"}}}}},"example":{"name":{"Details":"Group Name set successfully"},"topic":{"Details":"Group Topic set successfully"},"announce":{"Details":"Group Announce set successfully"},"locked":{"Details":"Group Locked setting updated successfully"},"ephemeral":{"Details":"Disappearing timer set successfully"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"jid","in":"path","required":true,"schema":{"type":"string"}},{"name":"inbox_id","in":"query","required":true,"description":"The WhatsApp Web inbox whose session owns the group. The operation runs only through this inbox's own gateway session, so it can never reach a group of another inbox. Required: without it, or with an id that is not a WhatsApp Web inbox of this account the caller can operate (or the Web sibling of a unified hybrid Cloud inbox), the request answers 404.","schema":{"type":"integer"},"example":8}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"topic":{"type":"string"},"announce":{"type":"boolean"},"locked":{"type":"boolean"},"ephemeral_seconds":{"type":"integer"}}},"example":{"name":"Sample Name","topic":"sample topic","announce":true,"locked":true,"ephemeral_seconds":60}}}}},"put":{"tags":["WhatsApp Web"],"operationId":"auto_put_api_v1_accounts_account_id_whatsapp_web_groups_jid","summary":"Update group settings","description":"Applies only the supplied fields (name/topic/announce/locked/ephemeral_seconds); each key mirrors the gateway `data` for that mutation. Absent inputs are omitted.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Per-field gateway confirmations for the fields that were changed.","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"object","properties":{"Details":{"type":"string","example":"Group Name set successfully"}}},"topic":{"type":"object","properties":{"Details":{"type":"string","example":"Group Topic set successfully"}}},"announce":{"type":"object","properties":{"Details":{"type":"string","example":"Group Announce set successfully"}}},"locked":{"type":"object","properties":{"Details":{"type":"string","example":"Group Locked setting updated successfully"}}},"ephemeral":{"type":"object","properties":{"Details":{"type":"string","example":"Disappearing timer set successfully"}}}}},"example":{"name":{"Details":"Group Name set successfully"},"topic":{"Details":"Group Topic set successfully"},"announce":{"Details":"Group Announce set successfully"},"locked":{"Details":"Group Locked setting updated successfully"},"ephemeral":{"Details":"Disappearing timer set successfully"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"jid","in":"path","required":true,"schema":{"type":"string"}},{"name":"inbox_id","in":"query","required":true,"description":"The WhatsApp Web inbox whose session owns the group. The operation runs only through this inbox's own gateway session, so it can never reach a group of another inbox. Required: without it, or with an id that is not a WhatsApp Web inbox of this account the caller can operate (or the Web sibling of a unified hybrid Cloud inbox), the request answers 404.","schema":{"type":"integer"},"example":8}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"topic":{"type":"string"},"announce":{"type":"boolean"},"locked":{"type":"boolean"},"ephemeral_seconds":{"type":"integer"}}},"example":{"name":"Sample Name","topic":"sample topic","announce":true,"locked":true,"ephemeral_seconds":60}}}}}},"/api/v1/accounts/{account_id}/whatsapp_web/communities/{jid}/link":{"post":{"tags":["WhatsApp Web"],"operationId":"auto_post_api_v1_accounts_account_id_whatsapp_web_communities_jid_link","summary":"Link a group into a community","description":"Gateway /community/link `data`.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Gateway confirmation.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Group linked to community successfully"},"parent_group":{"type":"string","example":"120363111111111111@g.us"},"child_group":{"type":"string","example":"120363420116051586@g.us"}}},"example":{"success":true,"message":"Group linked to community successfully","parent_group":"120363111111111111@g.us","child_group":"120363420116051586@g.us"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"jid","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"child_group":{"type":"string"}}},"example":{"child_group":"sample child group"}}}}}},"/api/v1/accounts/{account_id}/whatsapp_web/communities/{jid}/unlink":{"post":{"tags":["WhatsApp Web"],"operationId":"auto_post_api_v1_accounts_account_id_whatsapp_web_communities_jid_unlink","summary":"Unlink a group from its community","description":"Gateway /community/unlink `data` (the parent is inferred server-side from group info).","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Gateway confirmation.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Group unlinked from community successfully"},"group":{"type":"string","example":"120363420116051586@g.us"}}},"example":{"success":true,"message":"Group unlinked from community successfully","group":"120363420116051586@g.us"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"jid","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"group":{"type":"string"}}},"example":{"group":"sample group"}}}}}},"/api/v1/accounts/{account_id}/whatsapp_web/communities/{jid}/linked_groups":{"get":{"tags":["WhatsApp Web"],"operationId":"auto_get_api_v1_accounts_account_id_whatsapp_web_communities_jid_linked_groups","summary":"List a community's linked groups","description":"Gateway /community/linked `data.linked_groups` — the community's sub-groups.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Linked sub-groups of the community.","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"jid":{"type":"string","example":"120363420116051586@g.us"},"name":{"type":"string","example":"Team Support"},"is_default_sub":{"type":"boolean","example":false}}}},"example":[{"jid":"120363420116051586@g.us","name":"Team Support","is_default_sub":false}]}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"jid","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/whatsapp_web/communities/{jid}/announcement":{"post":{"tags":["WhatsApp Web"],"operationId":"auto_post_api_v1_accounts_account_id_whatsapp_web_communities_jid_announcement","summary":"Send a community announcement","description":"Gateway /community/announcement `data` — posts to the community announcement group.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Gateway confirmation with the sent message id.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Announcement sent successfully"},"community":{"type":"string","example":"120363111111111111@g.us"},"message_id":{"type":"string","example":"3EB0C767D71D9F1234"},"timestamp":{"type":"string","format":"date-time","example":"2026-01-15T10:30:00.000Z"}}},"example":{"success":true,"message":"Announcement sent successfully","community":"120363111111111111@g.us","message_id":"3EB0C767D71D9F1234","timestamp":"2026-01-15T10:30:00.000Z"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"jid","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"linked_groups":{"type":"string"}}},"example":{"message":"Sample message text.","linked_groups":"sample linked groups"}}}}}},"/api/v1/accounts/{account_id}/whatsapp_web/communities/{jid}/join_requests":{"get":{"tags":["WhatsApp Web"],"operationId":"auto_get_api_v1_accounts_account_id_whatsapp_web_communities_jid_join_requests","summary":"List pending group join requests","description":"Gateway /community/requests `data.pending_requests` — pending join requests for a group.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Pending join requests (user JIDs).","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"jid":{"type":"string","example":"5521988888888@s.whatsapp.net"}}}},"example":[{"jid":"5521988888888@s.whatsapp.net"}]}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"jid","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/whatsapp_web/communities/{jid}/update_join_requests":{"post":{"tags":["WhatsApp Web"],"operationId":"auto_post_api_v1_accounts_account_id_whatsapp_web_communities_jid_update_join_requests","summary":"Approve or reject group join requests","description":"Gateway /community/requests/update `data`.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Gateway confirmation echoing the action and targeted requests.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Successfully approveed 1 request(s)"},"group":{"type":"string","example":"120363420116051586@g.us"},"action":{"type":"string","enum":["approve","reject"],"example":"approve"},"requests":{"type":"array","items":{"type":"string","example":"5521988888888@s.whatsapp.net"}}}},"example":{"success":true,"message":"Successfully approveed 1 request(s)","group":"120363420116051586@g.us","action":"approve","requests":["5521988888888@s.whatsapp.net"]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"jid","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"group":{"type":"string"},"join_action":{"type":"string"},"requests":{"type":"array","items":{"type":"string"}}}},"example":{"group":"sample group","join_action":"sample join action","requests":["sample request"]}}}}}},"/api/v1/accounts/{account_id}/whatsapp_web/communities":{"get":{"tags":["WhatsApp Web"],"operationId":"auto_get_api_v1_accounts_account_id_whatsapp_web_communities","summary":"List communities (not supported by gateway)","description":"The gateway exposes no \"list communities\" endpoint (communities are parent groups). Always returns an empty array; the UI builds a community via create/show.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Always an empty array in v1.","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","description":"Community entry (reserved — mirrors the show contract).","properties":{"jid":{"type":"string","example":"120363043211234567@g.us"}}}},"example":[{"jid":"120363043211234567@g.us"}]}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."}]},"post":{"tags":["WhatsApp Web"],"operationId":"auto_post_api_v1_accounts_account_id_whatsapp_web_communities","summary":"Create a WhatsApp community","description":"Gateway /community/create `data` — creates the parent community group and links initial groups.","security":[{"userApiKey":[]}],"responses":{"201":{"description":"The created community.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Community created successfully"},"community":{"type":"object","properties":{"jid":{"type":"string","example":"120363111111111111@g.us"},"name":{"type":"string","example":"Support Community"},"description":{"type":"string","example":"Customers hub"},"linked_groups":{"type":"array","items":{"type":"string","example":"120363420116051586@g.us"}}}}}},"example":{"success":true,"message":"Community created successfully","community":{"jid":"120363111111111111@g.us","name":"Support Community","description":"Customers hub","linked_groups":["120363420116051586@g.us"]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"groups":{"type":"array","items":{"type":"string"}}}},"example":{"name":"Sample Name","description":"A short description.","groups":["sample group"]}}}}}},"/api/v1/accounts/{account_id}/whatsapp_web/communities/{jid}":{"get":{"tags":["WhatsApp Web"],"operationId":"auto_get_api_v1_accounts_account_id_whatsapp_web_communities_jid","summary":"Get a community's linked groups","description":"Wraps the community JID with its linked sub-groups (gateway /community/linked).","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The community JID and its linked groups.","content":{"application/json":{"schema":{"type":"object","properties":{"jid":{"type":"string","example":"120363111111111111@g.us"},"linked_groups":{"type":"array","items":{"type":"object","properties":{"jid":{"type":"string","example":"120363420116051586@g.us"},"name":{"type":"string","example":"Team Support"},"is_default_sub":{"type":"boolean","example":false}}}}}},"example":{"jid":"120363111111111111@g.us","linked_groups":[{"jid":"120363420116051586@g.us","name":"Team Support","is_default_sub":false}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"jid","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/whatsapp_web/newsletters/{jid}/follow":{"post":{"tags":["WhatsApp Web"],"operationId":"auto_post_api_v1_accounts_account_id_whatsapp_web_newsletters_jid_follow","summary":"Follow a newsletter","description":"Full gateway envelope from POST /newsletter/follow.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Gateway envelope confirming the subscription.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer","example":200},"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Subscribed successfully"}}}}},"example":{"code":200,"success":true,"data":{"success":true,"message":"Subscribed successfully"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"jid","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/whatsapp_web/newsletters/{jid}/unfollow":{"post":{"tags":["WhatsApp Web"],"operationId":"auto_post_api_v1_accounts_account_id_whatsapp_web_newsletters_jid_unfollow","summary":"Unfollow a newsletter","description":"Full gateway envelope from POST /newsletter/unfollow.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Gateway envelope confirming the unfollow.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer","example":200},"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Unsubscribed successfully"}}}}},"example":{"code":200,"success":true,"data":{"success":true,"message":"Unsubscribed successfully"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"jid","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/whatsapp_web/newsletters/{jid}/mute":{"post":{"tags":["WhatsApp Web"],"operationId":"auto_post_api_v1_accounts_account_id_whatsapp_web_newsletters_jid_mute","summary":"Mute or unmute a newsletter","description":"Full gateway envelope from POST /newsletter/mute (muted defaults to true).","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Gateway envelope confirming the mute state.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer","example":200},"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Notifications muted successfully"}}}}},"example":{"code":200,"success":true,"data":{"success":true,"message":"Notifications muted successfully"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"jid","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"muted":{"type":"boolean"}}},"example":{"muted":true}}}}}},"/api/v1/accounts/{account_id}/whatsapp_web/newsletters/{jid}/send_message":{"post":{"tags":["WhatsApp Web"],"operationId":"auto_post_api_v1_accounts_account_id_whatsapp_web_newsletters_jid_send_message","summary":"Send a text message to a newsletter","description":"Full gateway envelope from POST /newsletter/send.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Gateway envelope with the sent message id and epoch timestamp.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer","example":200},"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"success":{"type":"boolean","example":true},"id":{"type":"string","example":"3EB0C767D71D9F1234"},"timestamp":{"type":"integer","description":"Epoch seconds","example":1768472400}}}}},"example":{"code":200,"success":true,"data":{"success":true,"id":"3EB0C767D71D9F1234","timestamp":1768472400}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"jid","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"body":{"type":"string"}}},"example":{"body":"Sample body text."}}}}}},"/api/v1/accounts/{account_id}/whatsapp_web/newsletters/{jid}/react":{"post":{"tags":["WhatsApp Web"],"operationId":"auto_post_api_v1_accounts_account_id_whatsapp_web_newsletters_jid_react","summary":"React to a newsletter message","description":"Full gateway envelope from POST /newsletter/reaction. Targets by server_id (integer), not the wamid. Reaction-REMOVE is a known v1 limitation (add only).","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Gateway envelope confirming the reaction.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer","example":200},"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Reaction sent successfully"}}}}},"example":{"code":200,"success":true,"data":{"success":true,"message":"Reaction sent successfully"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"jid","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"message_id":{"type":"integer"},"emoji":{"type":"string"}}},"example":{"message_id":1,"emoji":"sample emoji"}}}}}},"/api/v1/accounts/{account_id}/whatsapp_web/newsletters/{jid}/subscribe_live":{"post":{"tags":["WhatsApp Web"],"operationId":"auto_post_api_v1_accounts_account_id_whatsapp_web_newsletters_jid_subscribe_live","summary":"Subscribe to newsletter live updates","description":"Full gateway envelope from POST /newsletter/subscribe-live-updates.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Gateway envelope with the live-update subscription duration.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer","example":200},"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"success":{"type":"boolean","example":true},"duration":{"type":"number","description":"Subscription window in seconds","example":300},"message":{"type":"string","example":"Subscribed to live updates"}}}}},"example":{"code":200,"success":true,"data":{"success":true,"duration":300,"message":"Subscribed to live updates"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"jid","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/whatsapp_web/newsletters/{jid}/mark_viewed":{"post":{"tags":["WhatsApp Web"],"operationId":"auto_post_api_v1_accounts_account_id_whatsapp_web_newsletters_jid_mark_viewed","summary":"Mark newsletter messages as viewed","description":"Full gateway envelope from POST /newsletter/mark-viewed.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Gateway envelope confirming the messages were marked viewed.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer","example":200},"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Messages marked as viewed"}}}}},"example":{"code":200,"success":true,"data":{"success":true,"message":"Messages marked as viewed"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"jid","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"message_ids":{"type":"array","items":{"type":"integer"}}}},"example":{"message_ids":[1]}}}}}},"/api/v1/accounts/{account_id}/whatsapp_web/newsletters/{jid}/messages":{"post":{"tags":["WhatsApp Web"],"operationId":"auto_post_api_v1_accounts_account_id_whatsapp_web_newsletters_jid_messages","summary":"Fetch newsletter message history","description":"Full gateway envelope from POST /newsletter/messages; data.messages is the gateway NewsletterMessageItem list. Pagination via count + before (server_id).","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Gateway envelope wrapping the newsletter message page.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer","example":200},"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"success":{"type":"boolean","example":true},"messages":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"3EB0C767D71D9F1234"},"server_id":{"type":"integer","example":101},"type":{"type":"string","example":"text"},"timestamp":{"type":"integer","description":"Epoch seconds","example":1768472400},"text":{"type":"string","example":"New release is out!"},"caption":{"type":"string","example":""},"views_count":{"type":"integer","example":340},"reaction_counts":{"type":"object","additionalProperties":{"type":"integer"},"example":{"👍":12,"❤️":3},"description":"WhatsApp Web (WazMeow gateway) reaction counts keyed by emoji."},"media":{"type":["object","null"],"additionalProperties":true,"description":"WhatsApp Web (WazMeow gateway) newsletter message media descriptor."}}}}}}}},"example":{"code":200,"success":true,"data":{"success":true,"messages":[{"id":"3EB0C767D71D9F1234","server_id":101,"type":"text","timestamp":1768472400,"text":"New release is out!","caption":"","views_count":340,"reaction_counts":{"👍":12,"❤️":3},"media":{}}]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"jid","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"count":{"type":"integer"},"before":{"type":"string"}}},"example":{"count":5,"before":"sample before"}}}}}},"/api/v1/accounts/{account_id}/whatsapp_web/newsletters/{jid}/refresh_state":{"post":{"tags":["WhatsApp Web"],"operationId":"auto_post_api_v1_accounts_account_id_whatsapp_web_newsletters_jid_refresh_state","summary":"Refresh state newsletters","description":"Performs the refresh state operation on the targeted newsletter resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"anyOf":[{"anyOf":[{"type":"object","properties":{"jid":{"type":"string"},"role":{"type":["string","null"]},"read_only":{"type":["string","null"]}}},{"type":"object","properties":{"jid":{"type":"string"},"role":{"type":"string"},"read_only":{"type":"string"}}}]},{"type":"object","properties":{"jid":{"type":"string"},"role":{"type":["string","null"]},"read_only":{"type":["string","null"]}}}]},"example":{"jid":"sample jid","role":"sample role","read_only":"sample read only"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"jid","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/whatsapp_web/newsletters/recommended":{"get":{"tags":["WhatsApp Web"],"operationId":"auto_get_api_v1_accounts_account_id_whatsapp_web_newsletters_recommended","summary":"Recommended newsletters","description":"Performs the recommended operation on the targeted newsletter resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"newsletters":{"type":"boolean"}}},"example":{"newsletters":true}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/whatsapp_web/newsletters":{"get":{"tags":["WhatsApp Web"],"operationId":"auto_get_api_v1_accounts_account_id_whatsapp_web_newsletters","summary":"List followed newsletters (channels)","description":"Normalized list from GET /newsletter/subscribed (picture backfilled from /newsletter/list). 60s cached. Degrades to [] for an un-paired/rate-limited channel.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The newsletters the operator follows.","content":{"application/json":{"schema":{"type":"object","properties":{"newsletters":{"type":"array","items":{"type":"object","properties":{"jid":{"type":"string","example":"120363111111111111@newsletter"},"name":{"type":"string","example":"Product Updates"},"description":{"type":["string","null"],"example":"Latest releases"},"subscribers":{"type":"integer","example":1200},"muted":{"type":"boolean","example":false},"picture":{"type":["string","null"],"example":"https://pps.whatsapp.net/v/t61..."},"role":{"type":["string","null"],"enum":["owner","admin","subscriber","guest",null],"example":"owner"},"invite_code":{"type":["string","null"],"example":"0029Vb..."}}}}}},"example":{"newsletters":[{"jid":"120363111111111111@newsletter","name":"Product Updates","description":"Latest releases","subscribers":1200,"muted":false,"picture":"https://pps.whatsapp.net/v/t61...","role":"owner","invite_code":"0029Vb..."}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."}]},"post":{"tags":["WhatsApp Web"],"operationId":"auto_post_api_v1_accounts_account_id_whatsapp_web_newsletters","summary":"Create a newsletter (channel)","description":"Full gateway envelope from POST /newsletter/create.","security":[{"userApiKey":[]}],"responses":{"201":{"description":"Gateway envelope wrapping the create result.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer","example":200},"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"success":{"type":"boolean","example":true},"jid":{"type":"string","example":"120363111111111111@newsletter"},"name":{"type":"string","example":"Product Updates"},"message":{"type":"string","example":"Newsletter created successfully"}}}}},"example":{"code":200,"success":true,"data":{"success":true,"jid":"120363111111111111@newsletter","name":"Product Updates","message":"Newsletter created successfully"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"picture":{"type":"string"}}},"example":{"name":"Sample Name","description":"A short description.","picture":"sample picture"}}}}}},"/api/v1/accounts/{account_id}/whatsapp_web/newsletters/{jid}":{"get":{"tags":["WhatsApp Web"],"operationId":"auto_get_api_v1_accounts_account_id_whatsapp_web_newsletters_jid","summary":"Get newsletter info","description":"Full gateway envelope from POST /newsletter/info; data is the gateway NewsletterInfo. (Known gateway limitation — this endpoint may 500 upstream; role/picture are resolved from /newsletter/list elsewhere.)","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Gateway envelope wrapping the newsletter info.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer","example":200},"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"jid":{"type":"string","example":"120363111111111111@newsletter"},"name":{"type":"string","example":"Product Updates"},"description":{"type":"string","example":"Latest releases"},"subscribers":{"type":"integer","example":1200},"invite_code":{"type":"string","example":"0029Vb..."},"picture":{"type":"string","example":""},"muted":{"type":"boolean","example":false},"role":{"type":"string","example":"owner"},"created_at":{"type":"integer","description":"Epoch seconds","example":1768472400}}}}},"example":{"code":200,"success":true,"data":{"jid":"120363111111111111@newsletter","name":"Product Updates","description":"Latest releases","subscribers":1200,"invite_code":"0029Vb...","picture":"","muted":false,"role":"owner","created_at":1768472400}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"jid","in":"path","required":true,"schema":{"type":"string"}}]},"patch":{"tags":["WhatsApp Web"],"operationId":"auto_patch_api_v1_accounts_account_id_whatsapp_web_newsletters_jid","summary":"Update a newsletter (mute toggle)","description":"Currently only the `muted` toggle is applied. When `muted` is supplied the body carries the gateway mute envelope under `muted`; otherwise an empty object.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The mute result envelope, or {} when nothing was updated.","content":{"application/json":{"schema":{"type":"object","properties":{"muted":{"type":"object","properties":{"code":{"type":"integer","example":200},"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Notifications muted successfully"}}}}}}},"example":{"muted":{"code":200,"success":true,"data":{"success":true,"message":"Notifications muted successfully"}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"jid","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"muted":{"type":"boolean"}}},"example":{"muted":true}}}}},"put":{"tags":["WhatsApp Web"],"operationId":"auto_put_api_v1_accounts_account_id_whatsapp_web_newsletters_jid","summary":"Update a newsletter (mute toggle)","description":"Currently only the `muted` toggle is applied. When `muted` is supplied the body carries the gateway mute envelope under `muted`; otherwise an empty object.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The mute result envelope, or {} when nothing was updated.","content":{"application/json":{"schema":{"type":"object","properties":{"muted":{"type":"object","properties":{"code":{"type":"integer","example":200},"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Notifications muted successfully"}}}}}}},"example":{"muted":{"code":200,"success":true,"data":{"success":true,"message":"Notifications muted successfully"}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"jid","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"muted":{"type":"boolean"}}},"example":{"muted":true}}}}},"delete":{"tags":["WhatsApp Web"],"operationId":"auto_delete_api_v1_accounts_account_id_whatsapp_web_newsletters_jid","summary":"Unfollow a newsletter","description":"Full gateway envelope from POST /newsletter/unfollow.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Gateway envelope confirming the unfollow.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer","example":200},"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Unsubscribed successfully"}}}}},"example":{"code":200,"success":true,"data":{"success":true,"message":"Unsubscribed successfully"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"jid","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/whatsapp_web/status":{"get":{"tags":["WhatsApp Web"],"operationId":"auto_get_api_v1_accounts_account_id_whatsapp_web_status","summary":"List the status posts published by this inbox","description":"The WhatsApp statuses (24h broadcasts) this inbox published — from the composer, a Hub broadcast or the phone itself — newest first, 25 per page. `source_id` is the WhatsApp message id of the status: a contact's reply quotes it (`wa_quoted_status.stanza_id`) and a reaction references it (`wa_structured.status_id`). `thumbnail_url` is WhatsApp's own thumbnail when the phone echo delivered one, otherwise a 250px variant of an image media; null for text/audio/document. `media_url` is the full media when it was stored. `expires_at` is `posted_at` + 24h (the WhatsApp status lifetime); `revoked_at` is set when the status was deleted for everyone. Same gate as posting: administrator (or the `inbox_manage` / `whatsapp_hub_manage` native access role) on a WhatsApp Web inbox of the account.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"One page of the inbox's status posts, newest first.","content":{"application/json":{"schema":{"type":"object","required":["payload","meta"],"properties":{"payload":{"type":"array","items":{"type":"object","required":["id","source_id","kind","origin","posted_at","expires_at"],"properties":{"id":{"type":"integer","example":91},"source_id":{"type":"string","description":"WhatsApp message id of the status (what replies and reactions quote).","example":"2A5460A9E2B28A7F45D8"},"kind":{"type":"string","enum":["text","image","video","audio","document"],"example":"image"},"caption":{"type":["string","null"],"description":"Media caption, or the text of a text status.","example":"Promo de hoje"},"origin":{"type":"string","enum":["phone","chatwoot"],"description":"Where the status was published from — the phone, or this platform (composer / Hub broadcast).","example":"chatwoot"},"posted_at":{"type":"string","format":"date-time","example":"2026-05-14T06:59:24.000Z"},"expires_at":{"type":"string","format":"date-time","description":"posted_at + 24h — the WhatsApp status lifetime.","example":"2026-05-15T06:59:24.000Z"},"revoked_at":{"type":["string","null"],"format":"date-time","description":"Set when the status was deleted for everyone.","example":null},"thumbnail_url":{"type":["string","null"],"format":"uri","description":"WhatsApp's own thumbnail, else a 250px variant of an image media; null for text/audio/document.","example":"https://app.example.com/rails/active_storage/blobs/proxy/eyJfcmFpbHMi/2A5460A9E2B28A7F45D8_thumb.jpg"},"media_url":{"type":["string","null"],"format":"uri","description":"The stored full media; null for a text status or when the bytes were not stored.","example":"https://app.example.com/rails/active_storage/blobs/redirect/eyJfcmFpbHMi/status_2A5460A9E2B28A7F45D8.jpg"}}}},"meta":{"type":"object","required":["total_count","current_page","per_page"],"properties":{"total_count":{"type":"integer","example":2},"current_page":{"type":"integer","example":1},"per_page":{"type":"integer","example":25}}}}},"example":{"payload":[{"id":91,"source_id":"2A5460A9E2B28A7F45D8","kind":"image","caption":"Promo de hoje","origin":"chatwoot","posted_at":"2026-05-14T06:59:24.000Z","expires_at":"2026-05-15T06:59:24.000Z","revoked_at":null,"thumbnail_url":"https://app.example.com/rails/active_storage/blobs/proxy/eyJfcmFpbHMi/2A5460A9E2B28A7F45D8_thumb.jpg","media_url":"https://app.example.com/rails/active_storage/blobs/redirect/eyJfcmFpbHMi/status_2A5460A9E2B28A7F45D8.jpg"},{"id":90,"source_id":"3EB0C767D71D9F1234","kind":"text","caption":"Bom dia","origin":"phone","posted_at":"2026-05-14T05:57:11.000Z","expires_at":"2026-05-15T05:57:11.000Z","revoked_at":null,"thumbnail_url":null,"media_url":null}],"meta":{"total_count":2,"current_page":1,"per_page":25}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"inbox_id","in":"query","required":true,"description":"The WhatsApp Web inbox whose status posts are listed.","schema":{"type":"integer"},"example":42},{"name":"page","in":"query","required":false,"description":"1-based page number (25 posts per page).","schema":{"type":"integer","minimum":1,"default":1},"example":1}]},"post":{"tags":["WhatsApp Web"],"operationId":"auto_post_api_v1_accounts_account_id_whatsapp_web_status","summary":"Post a WhatsApp status (24h broadcast)","description":"Posts a text/image/audio/video status via /status/send/{type}. Returns the gateway `data`. Audio (voice-note) additionally returns ptt/duration/ has_waveform/mime_type. Posting is allowed by default; it is disabled only when the inbox feature `enable_status_broadcast_posting` (Features tab) or the instance default `allow_status_posting` is explicitly false — then the endpoint answers 403 with the stable code `status_posting_disabled`.","security":[{"userApiKey":[]}],"responses":{"201":{"description":"Gateway status-send result.","content":{"application/json":{"schema":{"type":"object","properties":{"message_id":{"type":"string","example":"3EB0C767D71D9F1234"},"timestamp":{"type":"string","format":"date-time","example":"2026-01-15T10:30:00.000Z"},"status":{"type":"string","example":"sent"},"type":{"type":"string","enum":["text_status","image_status","voice_status","audio_status","video_status"],"example":"text_status"},"ptt":{"type":"boolean","description":"Audio only — always a voice-note.","example":true},"duration":{"type":"integer","description":"Audio only — seconds.","example":5},"has_waveform":{"type":"boolean","description":"Audio only.","example":true},"mime_type":{"type":"string","description":"Audio only.","example":"audio/ogg; codecs=opus"}}},"example":{"message_id":"3EB0C767D71D9F1234","timestamp":"2026-01-15T10:30:00.000Z","status":"sent","type":"text_status","ptt":true,"duration":5,"has_waveform":true,"mime_type":"audio/ogg; codecs=opus"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"403":{"description":"Status posting is disabled for this inbox (explicit opt-out).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["status_posting_disabled"],"description":"Stable machine code — the dashboard maps it to a localized message.","example":"status_posting_disabled"}}},"example":{"error":"status_posting_disabled"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"body":{"type":"string"},"background_color":{"type":"string"},"text_color":{"type":"string"},"font":{"type":"string"},"image":{"type":"string"},"caption":{"type":"string"},"audio":{"type":"string"},"ptt":{"type":"string"},"video":{"type":"string"},"audience":{"type":"array","items":{"type":"string"}},"exclude_list":{"type":"array","items":{"type":"string"}}}},"example":{"type":"sample type","body":"Sample body text.","background_color":"#1F93FF","text_color":"#1F93FF","font":"sample font","image":"sample image","caption":"sample caption","audio":"sample audio","ptt":"sample ptt","video":"sample video","audience":["sample audience"],"exclude_list":["sample exclude list"]}}}}}},"/api/v1/accounts/{account_id}/whatsapp_web/health":{"get":{"tags":["WhatsApp Web"],"operationId":"auto_get_api_v1_accounts_account_id_whatsapp_web_health","summary":"WhatsApp Web channel health snapshot","description":"Read-only per-channel health derived from gateway /session/status plus local ban/error counters. `state` is a 5-value enum. Legacy keys kept for the Connection tab back-compat. A false or missing gateway login/client flag indicates recoverable disconnection, not proof of logout. Only local authorization-loss evidence requests pairing. Route observations are invalidated if their assignment generation changed during the probe.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The channel health snapshot.","content":{"application/json":{"schema":{"type":"object","properties":{"state":{"type":"string","enum":["connected","disconnected","logged_out","awaiting_pair","temp_banned"],"example":"connected"},"jid":{"type":["string","null"],"example":"5521999999999:1@s.whatsapp.net"},"phone_number":{"type":"string","example":"+5521999999999"},"last_seen_at":{"type":"string","format":"date-time","example":"2026-01-15T10:30:00.000Z"},"connection_health":{"type":"string","enum":["healthy","degraded","unreachable"],"example":"healthy"},"push_name":{"type":["string","null"],"example":"Support"},"webhook_subscription":{"type":"boolean","example":true},"webhook_routing":{"type":"object","description":"Secret-free comparison between the callback registered in WazMeow and the route the platform expects. `internal_with_public_fallback` is selected only when a private gateway explicitly advertises the additive fallback capability; legacy and public gateways remain on the public callback.","required":["mode","healthy","primary"],"properties":{"mode":{"type":"string","enum":["public","internal_with_public_fallback"],"example":"internal_with_public_fallback"},"healthy":{"type":"boolean","description":"True when every expected callback URL matches the gateway state.","example":true},"primary":{"type":"string","format":"uri","example":"http://chatwoot_rails:3000/webhooks/whatsapp_web/9d19f6"},"fallback":{"type":["string","null"],"format":"uri","example":"https://app.example.com/webhooks/whatsapp_web/9d19f6"},"active_route":{"type":["string","null"],"enum":["primary","fallback","unknown",null],"example":"primary"},"primary_circuit":{"type":["string","null"],"enum":["closed","open","half_open",null],"example":"closed"},"last_primary_failure_at":{"type":["string","null"],"format":"date-time","example":"2026-09-04T15:30:00Z"}}},"recent_errors_count":{"type":"integer","example":0},"last_inbound_event_at":{"type":["string","null"],"format":"date-time","description":"When the channel last actually RECEIVED a message. This is the honest \"last activity\": `last_seen_at` is the channel row's updated_at and moves on any save, so it reported life on a channel that had delivered nothing for days.","example":"2026-01-15T10:30:00.000Z"},"days_without_delivery":{"type":["integer","null"],"description":"Whole days since the last received message. Null when nothing was ever received.","example":0},"delivery_stalled":{"type":"boolean","description":"Connected but silent past the threshold — the state a panel showing only \"Connected / 0 errors\" could never surface.","example":false},"channel_id":{"type":"integer","example":42},"inbox_id":{"type":["integer","null"],"description":"The inbox this snapshot describes. On a unified hybrid pair a caller may ask with the Cloud inbox id and be answered about the physical WhatsApp Web one, so the snapshot names its own subject rather than leaving it implied by the request.","example":87},"requested_inbox_id":{"type":"integer","description":"Present ONLY when the requested inbox differs from the one answered about — i.e. a unified hybrid pair resolved a Cloud id onto its Web sibling. Absent on a plain WhatsApp Web inbox, where the two are the same.","example":88},"resolved_via":{"type":"string","enum":["hybrid_pair"],"description":"Why the answered inbox differs from the requested one. Absent when nothing was bridged.","example":"hybrid_pair"},"provider":{"type":"string","example":"whatsapp_web","enum":["whatsapp_web"],"description":"Channel provider (WhatsApp Web via the WazMeow gateway)."},"pending_pairing":{"type":"boolean","example":false},"reauth_required":{"type":"boolean","example":false},"network_route":{"type":"object","description":"Where this channel's traffic leaves the server, as the platform recorded it. Secret-free: never a proxy URL, SOCKS credential or Tailscale key. On a hybrid pair it describes the WhatsApp Web half ONLY — the Cloud half always exits through the Rails server.","properties":{"mode":{"type":"string","enum":["direct","managed_proxy","mobile_egress"],"example":"managed_proxy"},"configured":{"type":"boolean","description":"False when no route was ever reserved (the gateway exits through the server itself).","example":true},"mobile_removable":{"type":"boolean","description":"Always false. The gateway's route endpoint only accepts mode \"mobile\" and the one teardown path requires deleting the gateway user, which unpairs WhatsApp.","example":false},"channel_whatsapp_id":{"type":"integer","example":42},"inbox_id":{"type":["integer","null"],"example":87},"status":{"type":"string","enum":["reserved","active","degraded","direct_fallback","released"],"example":"active"},"route_type":{"type":"string","enum":["managed_proxy","mobile_egress","direct"],"example":"managed_proxy"},"route_version":{"type":"integer","minimum":1,"example":1},"fallback_policy":{"type":"string","enum":["hold","managed_proxy","direct_allowed"],"example":"direct_allowed"},"fail_closed":{"type":"boolean","example":false},"provider":{"type":["string","null"],"enum":["webshare","bright_data","custom",null],"example":"webshare","description":"Channel provider (WhatsApp Web via the WazMeow gateway)."},"region":{"type":["string","null"],"example":"US"},"proxied":{"type":"boolean","example":true},"mobile_egress":{"type":"boolean","example":false},"fallback":{"type":"boolean","example":false},"desired_mode":{"type":"string","enum":["direct","managed_proxy","mobile_egress"],"example":"managed_proxy"},"applied_mode":{"type":"string","enum":["direct","managed_proxy","mobile_egress"],"example":"direct"},"observed_mode":{"type":["string","null"],"enum":["direct","managed_proxy","mobile_egress",null],"description":"Null when readback is missing or stale; never inferred from missing proxy fields.","example":"direct"},"observation_stale":{"type":"boolean","example":false},"observed_at":{"type":["string","null"],"format":"date-time"},"desired_route_version":{"type":"integer","minimum":1},"reconciliation_pending":{"type":"boolean","example":true},"retry_reason":{"type":["string","null"],"example":"capacity_unavailable"},"next_retry_at":{"type":["string","null"],"format":"date-time"},"last_attempt_at":{"type":["string","null"],"format":"date-time"},"attempts":{"type":"integer","minimum":0,"example":1},"transport_recovery_pending":{"type":"boolean","example":true},"transport_next_retry_at":{"type":["string","null"],"format":"date-time"},"transport_recovery_reason":{"type":["string","null"],"example":"transport_recovery_exhausted"}}},"ban":{"type":"object","properties":{"banned":{"type":"boolean","example":false},"ttl_seconds":{"type":"integer","description":"Present only when banned.","example":3600}}},"gateway":{"type":"object","description":"Raw gateway /session/status probe result.","properties":{"reachable":{"type":"boolean","example":true},"connected":{"type":["boolean","null"],"example":true},"logged_in":{"type":["boolean","null"],"example":true},"has_client":{"type":["boolean","null"],"example":true},"jid":{"type":["string","null"],"example":"5521999999999:1@s.whatsapp.net"},"push_name":{"type":["string","null"],"example":"Support"},"webhook":{"type":["string","null"],"example":"https://app.example.com/webhooks/whatsapp_web/9d19f6"},"webhook_fallback":{"type":["string","null"],"example":"https://app.example.com/webhooks/whatsapp_web/9d19f6"},"webhook_delivery":{"type":"object","additionalProperties":true,"description":"Additive WazMeow delivery-route state; empty on legacy gateways."},"status_code":{"type":"integer","example":200}}}}},"example":{"state":"connected","jid":"5521999999999:1@s.whatsapp.net","phone_number":"+5521999999999","last_seen_at":"2026-01-15T10:30:00.000Z","connection_health":"healthy","push_name":"Support","webhook_subscription":true,"webhook_routing":{"mode":"internal_with_public_fallback","healthy":true,"primary":"http://chatwoot_rails:3000/webhooks/whatsapp_web/9d19f6","fallback":"https://app.example.com/webhooks/whatsapp_web/9d19f6","active_route":"primary","primary_circuit":"closed","last_primary_failure_at":"2026-09-04T15:30:00Z"},"recent_errors_count":0,"last_inbound_event_at":"2026-01-15T10:30:00.000Z","days_without_delivery":0,"delivery_stalled":false,"channel_id":42,"inbox_id":87,"requested_inbox_id":88,"resolved_via":"hybrid_pair","provider":"whatsapp_web","pending_pairing":false,"reauth_required":false,"network_route":{"mode":"managed_proxy","configured":true,"mobile_removable":false,"channel_whatsapp_id":42,"inbox_id":87,"status":"active","route_type":"managed_proxy","route_version":1,"fallback_policy":"direct_allowed","fail_closed":false,"provider":"webshare","region":"US","proxied":true,"mobile_egress":false,"fallback":false,"desired_mode":"managed_proxy","applied_mode":"direct","observed_mode":"direct","observation_stale":false,"observed_at":"2026-01-15T10:30:00.000Z","desired_route_version":1,"reconciliation_pending":true,"retry_reason":"capacity_unavailable","next_retry_at":"2026-01-15T10:30:00.000Z","last_attempt_at":"2026-01-15T10:30:00.000Z","attempts":1,"transport_recovery_pending":true,"transport_next_retry_at":"2026-01-15T10:30:00.000Z","transport_recovery_reason":"transport_recovery_exhausted"},"ban":{"banned":false,"ttl_seconds":3600},"gateway":{"reachable":true,"connected":true,"logged_in":true,"has_client":true,"jid":"5521999999999:1@s.whatsapp.net","push_name":"Support","webhook":"https://app.example.com/webhooks/whatsapp_web/9d19f6","webhook_fallback":"https://app.example.com/webhooks/whatsapp_web/9d19f6","webhook_delivery":{},"status_code":200}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/whatsapp_web/health/resubscribe":{"post":{"tags":["WhatsApp Web"],"operationId":"auto_post_api_v1_accounts_account_id_whatsapp_web_health_resubscribe","summary":"Re-register the WhatsApp Web webhook","description":"Re-registers this channel's callback on the gateway and returns the refreshed health snapshot in the SAME response, so the panel updates without a second round trip. Idempotent — safe to click whenever delivery looks stalled, which is the situation it exists for: a channel that reports connected while the subscription was silently lost. Admin only (the read-only snapshot is not).","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The refreshed health snapshot, same shape as the GET.","content":{"application/json":{"schema":{"type":"object","properties":{"state":{"type":"string","enum":["connected","disconnected","logged_out","awaiting_pair","temp_banned"],"example":"connected"},"webhook_subscription":{"type":"boolean","description":"True once the callback is registered again.","example":true},"webhook_routing":{"type":"object","required":["mode","healthy","primary"],"properties":{"mode":{"type":"string","enum":["public","internal_with_public_fallback"]},"healthy":{"type":"boolean"},"primary":{"type":"string","format":"uri"},"fallback":{"type":["string","null"],"format":"uri"}}},"delivery_stalled":{"type":"boolean","example":false},"days_without_delivery":{"type":["integer","null"],"example":0},"last_inbound_event_at":{"type":["string","null"],"format":"date-time","example":"2026-01-15T10:30:00.000Z"},"channel_id":{"type":"integer","example":42},"provider":{"type":"string","example":"whatsapp_web","enum":["whatsapp_web"],"description":"Channel provider (WhatsApp Web via the WazMeow gateway)."}}},"example":{"state":"connected","webhook_subscription":true,"webhook_routing":{"mode":"public","healthy":true,"primary":"https://example.com/resource","fallback":"https://example.com/resource"},"delivery_stalled":false,"days_without_delivery":0,"last_inbound_event_at":"2026-01-15T10:30:00.000Z","channel_id":42,"provider":"whatsapp_web"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/whatsapp_web/labels/sync":{"post":{"tags":["WhatsApp Web"],"operationId":"auto_post_api_v1_accounts_account_id_whatsapp_web_labels_sync","summary":"Sync WhatsApp labels","description":"Returns the locally-known label mappings (no remote list endpoint exists, so this is equivalent to #index).","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The channel's known WhatsApp labels.","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"label_1603824000"},"name":{"type":"string","example":"Novo cliente"},"color":{"type":"string","example":"7"}}}},"example":[{"id":"label_1603824000","name":"Novo cliente","color":"7"}]}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/whatsapp_web/labels":{"get":{"tags":["WhatsApp Web"],"operationId":"auto_get_api_v1_accounts_account_id_whatsapp_web_labels","summary":"List known WhatsApp labels","description":"Locally-known WhatsApp labels for this channel (LabelExternalMapping). The gateway exposes no remote list, so this is the authoritative view.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The channel's known WhatsApp labels.","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"WhatsApp label id.","example":"label_1603824000"},"name":{"type":"string","example":"Novo cliente"},"color":{"type":"string","description":"WhatsApp palette index (0-19) as a string.","example":"7"}}}},"example":[{"id":"label_1603824000","name":"Novo cliente","color":"7"}]}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."}]}},"/api/v1/accounts/{account_id}/whatsapp_web/ignore_rules/conversation_status":{"get":{"tags":["WhatsApp Web"],"operationId":"auto_get_api_v1_accounts_account_id_whatsapp_web_ignore_rules_conversation_status","summary":"Read exact ignore status of a conversation target","description":"Reads the persisted ContactInbox source through the existing canonical matcher without gateway HTTP. Returns matching rule receipts without phone, JID, name or undo ownership. Community kind comes only from the local mirror; the rule covers this exact target and never its linked groups. Database failure is an error and is never represented as not ignored.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Authoritative status for the authorized conversation and physical Web inbox.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["payload"],"properties":{"payload":{"type":"object","additionalProperties":false,"required":["conversation_display_id","requested_inbox_id","web_inbox_id","target_kind","scope","available","reason","ignored","matched_count","matched_rules","matches_truncated"],"properties":{"conversation_display_id":{"type":"integer"},"requested_inbox_id":{"type":"integer"},"web_inbox_id":{"type":"integer","description":"Physical WhatsApp Web owner of this list."},"target_kind":{"type":["string","null"],"enum":["contact","group","newsletter","community",null]},"scope":{"type":"string","enum":["target_only"],"description":"Exact target only; a community rule does not cascade to linked groups or participants."},"available":{"type":"boolean"},"reason":{"type":["string","null"],"enum":["blank","too_long","invalid_format","broadcast_unsupported",null]},"ignored":{"type":"boolean"},"matched_count":{"type":"integer","minimum":0},"matched_rules":{"type":"array","maxItems":100,"items":{"type":"object","additionalProperties":false,"required":["id","rule_type"],"properties":{"id":{"type":"integer"},"rule_type":{"type":"string","enum":["contact","group","newsletter"],"description":"Scope of the WhatsApp Web ignore rule."}}}},"matches_truncated":{"type":"boolean"}}}}},"example":{"payload":{"conversation_display_id":42,"requested_inbox_id":8,"web_inbox_id":9,"target_kind":"contact","scope":"target_only","available":true,"reason":null,"ignored":false,"matched_count":0,"matched_rules":[{"id":1,"rule_type":"contact"}],"matches_truncated":false}}}}},"401":{"description":"Authentication or conversation access was denied.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string"}}},"example":{"error":"sample error"}}}},"404":{"description":"Account-scoped inbox or conversation was not found or did not resolve to the same Web owner.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string"}}},"example":{"error":"sample error"}}}},"422":{"description":"Required conversation identifier was omitted.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string"}}},"example":{"error":"sample error"}}}},"403":{"description":"The native inbox or WhatsApp Hub management role is required.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string"}}},"example":{"error":"sample error"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"inbox_id","in":"query","required":true,"schema":{"type":"integer"},"description":"Physical Web inbox or its activated unified Cloud alias; authorization is checked before resolution."},{"name":"conversation_display_id","in":"query","required":true,"schema":{"type":"integer"}}]}},"/api/v1/accounts/{account_id}/whatsapp_web/ignore_rules/from_conversation":{"post":{"tags":["WhatsApp Web"],"operationId":"auto_post_api_v1_accounts_account_id_whatsapp_web_ignore_rules_from_conversation","summary":"Ignore the persisted target of a conversation","description":"Adds a canonical rule to the authorized physical Web inbox list using only ContactInbox.source_id. No client-supplied target is accepted. An existing matching alias or concurrent creator returns created false with a null receipt; only a newly created rule grants a created_rule_id for the existing scoped DELETE. Re-read status after deleting that receipt because other aliases may remain. Existing CRUD cache invalidation and asynchronous LID enrichment policy are retained. This can suppress Web processing for the exact target, including groups or newsletters, and never cascades a community rule to children or mutates the contact globally.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Creation receipt and current exact-target status; a duplicate grants no undo receipt.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["payload"],"properties":{"payload":{"type":"object","additionalProperties":false,"required":["created","created_rule_id","status"],"properties":{"created":{"type":"boolean"},"created_rule_id":{"type":["integer","null"]},"status":{"type":"object","additionalProperties":false,"required":["conversation_display_id","requested_inbox_id","web_inbox_id","target_kind","scope","available","reason","ignored","matched_count","matched_rules","matches_truncated"],"properties":{"conversation_display_id":{"type":"integer"},"requested_inbox_id":{"type":"integer"},"web_inbox_id":{"type":"integer","description":"Physical WhatsApp Web owner of this list."},"target_kind":{"type":["string","null"],"enum":["contact","group","newsletter","community",null]},"scope":{"type":"string","enum":["target_only"],"description":"Exact target only; a community rule does not cascade to linked groups or participants."},"available":{"type":"boolean"},"reason":{"type":["string","null"],"enum":["blank","too_long","invalid_format","broadcast_unsupported",null]},"ignored":{"type":"boolean"},"matched_count":{"type":"integer","minimum":0},"matched_rules":{"type":"array","maxItems":100,"items":{"type":"object","additionalProperties":false,"required":["id","rule_type"],"properties":{"id":{"type":"integer"},"rule_type":{"type":"string","enum":["contact","group","newsletter"],"description":"Scope of the WhatsApp Web ignore rule."}}}},"matches_truncated":{"type":"boolean"}}}}}}},"example":{"payload":{"created":true,"created_rule_id":1,"status":{"conversation_display_id":1,"requested_inbox_id":1,"web_inbox_id":1,"target_kind":"contact","scope":"target_only","available":true,"reason":"blank","ignored":true,"matched_count":5,"matched_rules":[{"id":1,"rule_type":"contact"}],"matches_truncated":true}}}}}},"401":{"description":"Authentication or conversation access was denied.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string"}}},"example":{"error":"sample error"}}}},"404":{"description":"Account-scoped inbox or conversation was not found or did not resolve to the same Web owner.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string"}}},"example":{"error":"sample error"}}}},"422":{"description":"The required conversation parameter is missing or the persisted source is unsupported or a duplicate race could not be resolved.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string"},"reason":{"type":"string","enum":["blank","too_long","invalid_format","broadcast_unsupported","duplicate"],"description":"Present for normalized target errors; omitted for native ParameterMissing."}}},"example":{"error":"broadcast_unsupported","reason":"broadcast_unsupported"}}}},"403":{"description":"The native inbox or WhatsApp Hub management role is required.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string"}}},"example":{"error":"sample error"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"inbox_id","in":"query","required":true,"schema":{"type":"integer"},"description":"Physical Web inbox or its activated unified Cloud alias; authorization is checked before resolution."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["conversation_display_id"],"properties":{"conversation_display_id":{"type":"integer"}}},"example":{"conversation_display_id":42}}}}}},"/api/v1/accounts/{account_id}/whatsapp_web/ignore_rules/bulk":{"post":{"tags":["WhatsApp Web"],"operationId":"auto_post_api_v1_accounts_account_id_whatsapp_web_ignore_rules_bulk","summary":"Bulk create ignore rules","description":"Performs the bulk create operation on the targeted ignore rule resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"created":{"type":"integer"},"duplicates":{"type":"string"},"invalid":{"type":"string"}}},"example":{"created":1,"duplicates":"sample duplicates","invalid":"sample invalid"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"entries":{"type":"array","items":{"type":"object","properties":{"value":{"type":"string"},"rule_type":{"type":"string","enum":["contact","group","newsletter"],"description":"Scope of the WhatsApp Web ignore rule."}}}}}},"example":{"entries":[{"value":"sample value","rule_type":"contact"}]}}}}},"delete":{"tags":["WhatsApp Web"],"operationId":"auto_delete_api_v1_accounts_account_id_whatsapp_web_ignore_rules_bulk","summary":"Bulk destroy ignore rules","description":"Performs the bulk destroy operation on the targeted ignore rule resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"string"}}},"example":{"deleted":"sample deleted"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/whatsapp_web/ignore_rules":{"get":{"tags":["WhatsApp Web"],"operationId":"auto_get_api_v1_accounts_account_id_whatsapp_web_ignore_rules","summary":"List ignore rules","description":"Returns the list of ignore rules visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Free-form object."}},"meta":{"type":"object","properties":{"total_count":{"type":"integer"},"current_page":{"type":"string"},"per_page":{"type":"string"},"counts_by_type":{"type":"object","description":"Ignore-rule counts by rule type.","properties":{"contact":{"type":"integer"},"group":{"type":"integer"},"newsletter":{"type":"integer"}}}}}}},"example":{"payload":[{}],"meta":{"total_count":5,"current_page":"sample current page","per_page":"sample per page","counts_by_type":{"contact":1,"group":1,"newsletter":1}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."}]},"post":{"tags":["WhatsApp Web"],"operationId":"auto_post_api_v1_accounts_account_id_whatsapp_web_ignore_rules","summary":"Create ignore rules","description":"Creates a new ignore rule from the request payload. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"string"}}},"example":{"payload":"sample payload"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"value":{"type":"number"},"rule_type":{"type":"string","enum":["contact","group","newsletter"],"description":"Scope of the WhatsApp Web ignore rule."},"name":{"type":"string"}}},"example":{"value":149.9,"rule_type":"contact","name":"Sample Name"}}}}}},"/api/v1/accounts/{account_id}/whatsapp_web/ignore_rules/{id}":{"delete":{"tags":["WhatsApp Web"],"operationId":"auto_delete_api_v1_accounts_account_id_whatsapp_web_ignore_rules_id","summary":"Delete ignore rules","description":"Deletes the ignore rule identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"boolean","example":true}}},"example":{"deleted":true}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/webhooks/{webhook_id}/deliveries/{id}/replay":{"post":{"tags":["Webhooks"],"operationId":"auto_post_api_v1_accounts_account_id_webhooks_webhook_id_deliveries_id_replay","summary":"Replay webhook deliveries","description":"Performs the replay operation on the targeted webhook delivery resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"202":{"description":"Delivery reset and queued again; the same durable delivery and idempotency id are reused.","content":{"application/json":{"schema":{"type":"object","required":["payload"],"properties":{"payload":{"type":"object","required":["delivery"],"properties":{"delivery":{"$ref":"#/components/schemas/webhook_delivery"}}}}},"example":{"payload":{"delivery":{"id":184,"delivery_id":"5b96d21d-6df7-4bb3-9fbf-254da374f234","event_name":"commerce_payment_confirmed","url":"https://erp.example.com/webhooks/commerce","status":"retrying","attempts":2,"manual_replays":1,"http_status":503,"response_body":"Service unavailable","last_error":"503 Service Unavailable","last_attempted_at":"2026-08-04T15:30:00.000Z","next_attempt_at":"2026-08-04T15:32:00.000Z","delivered_at":null,"created_at":"2026-08-04T15:28:00.000Z"}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"422":{"description":"The queue rejected the replay; failed_ids identifies the account-scoped delivery now recorded as failed."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"webhook_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/webhooks/{webhook_id}/deliveries/bulk_replay":{"post":{"tags":["Webhooks"],"operationId":"auto_post_api_v1_accounts_account_id_webhooks_webhook_id_deliveries_bulk_replay","summary":"Bulk replay webhook deliveries","description":"Performs the bulk replay operation on the targeted webhook delivery resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"processed_ids":{"type":"array","items":{"type":"integer"}},"failed_ids":{"type":"array","items":{"type":"integer"}}}}}},"example":{"payload":{"processed_ids":[1],"failed_ids":[1]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"202":{"description":"Per-delivery replay result; missing, foreign or queue-failed rows remain in failed_ids.","content":{"application/json":{"schema":{"type":"object","required":["payload"],"properties":{"payload":{"type":"object","required":["processed_ids","failed_ids"],"properties":{"processed_ids":{"type":"array","items":{"type":"integer"},"example":[184]},"failed_ids":{"type":"array","items":{"type":"integer"},"example":[185]}}}}},"example":{"payload":{"processed_ids":[184],"failed_ids":[185]}}}}},"422":{"description":"No requested delivery could be queued, or the selection was empty or exceeded 500 unique ids."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"webhook_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["ids"],"properties":{"ids":{"type":"array","minItems":1,"maxItems":500,"uniqueItems":true,"items":{"type":"integer","minimum":1},"example":[184,185]}}},"example":{"ids":[184,185]}}}}}},"/api/v1/accounts/{account_id}/webhooks/{webhook_id}/deliveries":{"get":{"tags":["Webhooks"],"operationId":"auto_get_api_v1_accounts_account_id_webhooks_webhook_id_deliveries","summary":"List webhook deliveries","description":"Returns the list of webhook deliveries visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Page of durable deliveries for the selected account webhook, with payload content intentionally omitted.","content":{"application/json":{"schema":{"type":"object","required":["meta","payload"],"properties":{"meta":{"type":"object","required":["count","current_page","total_pages","per_page"],"properties":{"count":{"type":"integer","example":31},"current_page":{"type":"integer","example":1},"total_pages":{"type":"integer","example":2},"per_page":{"type":"integer","example":25}}},"payload":{"type":"object","required":["deliveries"],"properties":{"deliveries":{"type":"array","items":{"$ref":"#/components/schemas/webhook_delivery"}}}}}},"example":{"meta":{"count":31,"current_page":1,"total_pages":2,"per_page":25},"payload":{"deliveries":[{"id":184,"delivery_id":"5b96d21d-6df7-4bb3-9fbf-254da374f234","event_name":"commerce_payment_confirmed","url":"https://erp.example.com/webhooks/commerce","status":"retrying","attempts":2,"manual_replays":1,"http_status":503,"response_body":"Service unavailable","last_error":"503 Service Unavailable","last_attempted_at":"2026-08-04T15:30:00.000Z","next_attempt_at":"2026-08-04T15:32:00.000Z","delivered_at":null,"created_at":"2026-08-04T15:28:00.000Z"}]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"webhook_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"q","in":"query","required":false,"schema":{"type":"string"},"description":"Case-insensitive search across event name, destination URL and last error."},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["pending","delivering","retrying","delivered","failed"]}},{"name":"sort","in":"query","required":false,"schema":{"type":"string","enum":["created_at","last_attempted_at","attempts","status"],"default":"created_at"}},{"name":"direction","in":"query","required":false,"schema":{"type":"string","enum":["asc","desc"],"default":"desc"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1}},{"name":"per_page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":25}}]}},"/api/v1/accounts/{account_id}/integrations/apps/{id}":{"get":{"tags":["Integrations"],"operationId":"auto_get_api_v1_accounts_account_id_integrations_apps_id","summary":"Get apps","description":"Returns the app identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"short_description":{"type":"string"},"enabled":{"type":"boolean"},"call":{"type":"string"},"action":{"type":"string"},"button":{"type":"string"},"hooks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"app_id":{"type":"integer"},"status":{"type":"boolean"},"inbox":{"type":["string","null"]},"logical_inbox_id":{"type":"integer"},"logical_inbox":{"type":["string","null"]},"account_id":{"type":"integer"},"hook_type":{"type":"string","enum":["account","inbox"]},"settings":{"type":"string"},"reference_id":{"type":"integer"}}}}}},"example":{"id":1,"name":"Sample Name","description":"A short description.","short_description":"sample short description","enabled":true,"call":"sample call","action":"sample action","button":"sample button","hooks":[{"id":1,"app_id":1,"status":true,"inbox":"sample inbox","logical_inbox_id":1,"logical_inbox":"sample logical inbox","account_id":1,"hook_type":"account","settings":"sample settings","reference_id":1}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/integrations/transcription":{"post":{"tags":["Integrations"],"operationId":"auto_post_api_v1_accounts_account_id_integrations_transcription","summary":"Create transcriptions","description":"Creates a new transcription from the request payload. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string"},"provider":{"type":"string","enum":["groq","openai"],"description":"The speech-to-text provider that produced the transcription."}}},"example":{"text":"sample text","provider":"groq"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"audio_base64":{"type":"string"},"filename":{"type":"string"}}},"example":{"audio_base64":"sample audio base64","filename":"sample filename"}}}}}},"/api/v1/accounts/{account_id}/integrations/hooks/{id}/process_event":{"post":{"tags":["Integrations"],"operationId":"auto_post_api_v1_accounts_account_id_integrations_hooks_id_process_event","summary":"Process event hooks","description":"Performs the process event operation on the targeted hook resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"message":{"type":["string","null"]}}},{"type":"object","properties":{"message":{"type":"string"}}}]},"example":{"message":"Sample message text."}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"event":{"type":"string"}}},"example":{"event":"sample event"}}}}}},"/api/v1/accounts/{account_id}/integrations/slack/list_all_channels":{"get":{"tags":["Integrations"],"operationId":"auto_get_api_v1_accounts_account_id_integrations_slack_list_all_channels","summary":"List all channels slack","description":"Performs the list all channels operation on the targeted slack resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"}}}},"example":[{"id":1,"name":"Sample Name"}]}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/integrations/slack":{"patch":{"tags":["Integrations"],"operationId":"auto_patch_api_v1_accounts_account_id_integrations_slack","summary":"Update slack","description":"Updates the slack identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Slack integration app with connected hooks","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","example":"slack"},"name":{"type":"string","example":"Slack"},"description":{"type":"string","example":"Manage conversations in Slack"},"short_description":{"type":["string","null"],"example":"Slack integration"},"enabled":{"type":"boolean","example":true},"action":{"type":"string","description":"Admin-only","example":"/slack"},"button":{"type":"string","description":"Admin-only","example":"/slack"},"hooks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","example":42},"app_id":{"type":"string","example":"slack"},"status":{"type":"boolean","example":true},"account_id":{"type":"integer","example":1},"hook_type":{"type":"string","enum":["account","inbox"],"example":"account"},"reference_id":{"type":["string","null"],"example":"C0123ABC"}}}}}},"example":{"id":"slack","name":"Slack","description":"Manage conversations in Slack","short_description":"Slack integration","enabled":true,"action":"/slack","button":"/slack","hooks":[{"id":42,"app_id":"slack","status":true,"account_id":1,"hook_type":"account","reference_id":"C0123ABC"}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"422":{"description":"Invalid channel id","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Invalid slack channel. Please try again"}}},"example":{"error":"Invalid slack channel. Please try again"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"reference_id":{"type":"integer"}}},"example":{"reference_id":1}}}}},"put":{"tags":["Integrations"],"operationId":"auto_put_api_v1_accounts_account_id_integrations_slack","summary":"Update slack","description":"Updates the slack identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Slack integration app with connected hooks","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","example":"slack"},"name":{"type":"string","example":"Slack"},"description":{"type":"string","example":"Manage conversations in Slack"},"short_description":{"type":["string","null"],"example":"Slack integration"},"enabled":{"type":"boolean","example":true},"action":{"type":"string","description":"Admin-only","example":"/slack"},"button":{"type":"string","description":"Admin-only","example":"/slack"},"hooks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","example":42},"app_id":{"type":"string","example":"slack"},"status":{"type":"boolean","example":true},"account_id":{"type":"integer","example":1},"hook_type":{"type":"string","enum":["account","inbox"],"example":"account"},"reference_id":{"type":["string","null"],"example":"C0123ABC"}}}}}},"example":{"id":"slack","name":"Slack","description":"Manage conversations in Slack","short_description":"Slack integration","enabled":true,"action":"/slack","button":"/slack","hooks":[{"id":42,"app_id":"slack","status":true,"account_id":1,"hook_type":"account","reference_id":"C0123ABC"}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"422":{"description":"Invalid channel id","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Invalid slack channel. Please try again"}}},"example":{"error":"Invalid slack channel. Please try again"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"reference_id":{"type":"integer"}}},"example":{"reference_id":1}}}}},"delete":{"tags":["Integrations"],"operationId":"auto_delete_api_v1_accounts_account_id_integrations_slack","summary":"Delete slack","description":"Deletes the slack identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Success (no content)"},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]},"post":{"tags":["Integrations"],"operationId":"auto_post_api_v1_accounts_account_id_integrations_slack","summary":"Create slack","description":"Creates a new slack from the request payload. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"short_description":{"type":"string"},"enabled":{"type":"boolean"},"call":{"type":"string"},"action":{"type":"string"},"button":{"type":"string"},"hooks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"app_id":{"type":"integer"},"status":{"type":"boolean"},"inbox":{"type":["string","null"]},"logical_inbox_id":{"type":"integer"},"logical_inbox":{"type":["string","null"]},"account_id":{"type":"integer"},"hook_type":{"type":"string","enum":["account","inbox"]},"settings":{"type":"string"},"reference_id":{"type":"integer"}}}}}},"example":{"id":1,"name":"Sample Name","description":"A short description.","short_description":"sample short description","enabled":true,"call":"sample call","action":"sample action","button":"sample button","hooks":[{"id":1,"app_id":1,"status":true,"inbox":"sample inbox","logical_inbox_id":1,"logical_inbox":"sample logical inbox","account_id":1,"hook_type":"account","settings":"sample settings","reference_id":1}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"inbox_id":{"type":"integer"}}},"example":{"code":"sample code","inbox_id":1}}}}}},"/api/v1/accounts/{account_id}/integrations/dyte/create_a_meeting":{"post":{"tags":["Integrations"],"operationId":"auto_post_api_v1_accounts_account_id_integrations_dyte_create_a_meeting","summary":"Create a meeting dyte","description":"Performs the create a meeting operation on the targeted dyte resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Dyte integration message created for the conversation","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer","example":1024},"content":{"type":"string","example":"John started a meeting"},"content_type":{"type":"string","example":"integrations"},"content_attributes":{"type":"object","properties":{"type":{"type":"string","example":"dyte"},"data":{"type":"object","properties":{"meeting_id":{"type":"string","example":"2e3b8f9c-1a2b-4c5d-9e0f-1234567890ab"}}}}},"message_type":{"type":"integer","description":"0 incoming, 1 outgoing, 2 activity, 3 template","example":1},"created_at":{"type":"integer","description":"unix epoch seconds","example":1737800000},"conversation_id":{"type":"integer","description":"conversation display_id","example":33},"inbox_id":{"type":"integer","example":7},"account_id":{"type":"integer","example":1},"private":{"type":"boolean","example":false},"sender":{"type":"object","description":"agent push_event_data","example":{"id":5,"name":"John","type":"user"}}}},"example":{"id":1024,"content":"John started a meeting","content_type":"integrations","content_attributes":{"type":"dyte","data":{"meeting_id":"2e3b8f9c-1a2b-4c5d-9e0f-1234567890ab"}},"message_type":1,"created_at":1737800000,"conversation_id":33,"inbox_id":7,"account_id":1,"private":false,"sender":{"id":5,"name":"John","type":"user"}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"422":{"description":"Dyte API error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Meeting could not be created"},"error_code":{"type":"integer","example":400}}},"example":{"error":"Meeting could not be created","error_code":400}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/integrations/dyte/add_participant_to_meeting":{"post":{"tags":["Integrations"],"operationId":"auto_post_api_v1_accounts_account_id_integrations_dyte_add_participant_to_meeting","summary":"Add participant to meeting dyte","description":"Performs the add participant to meeting operation on the targeted dyte resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Dyte participant auth token (used to join the meeting)","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","example":"7f9a1b2c-3d4e-5f60-7182-9a0b1c2d3e4f"},"token":{"type":"string","description":"Dyte participant auth token","example":"sample-token"}}},"example":{"id":"7f9a1b2c-3d4e-5f60-7182-9a0b1c2d3e4f","token":"sample-token"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"422":{"description":"Invalid message type or Dyte error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Invalid message type. Action not permitted"}}},"example":{"error":"Invalid message type. Action not permitted"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/integrations/shopify/auth":{"post":{"tags":["Integrations"],"operationId":"auto_post_api_v1_accounts_account_id_integrations_shopify_auth","summary":"Start a browser-bound Shopify authorization","description":"Starts Shopify OAuth for an account administrator or a native role with `integration_manage`. The account feature must be enabled. The returned URL contains a short-lived, one-use state bound to this browser and is therefore a native UI handoff, never an MCP capability.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Authorization handoff created. The response is private and non-cacheable.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["redirect_url"],"properties":{"redirect_url":{"type":"string","format":"uri","description":"Shopify authorization URL containing the browser-bound one-use state."}}},"example":{"redirect_url":"https://example.com/resource"}}}},"401":{"description":"The authenticated account member cannot manage integrations."},"404":{"description":"Account or resource not found"},"403":{"description":"The Shopify feature is disabled for this account."},"422":{"description":"Invalid store domain, missing application credentials, or invalid public callback origin."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["shop_domain"],"properties":{"shop_domain":{"type":"string","pattern":"^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.myshopify\\.com\\.?$","example":"support-store.myshopify.com","description":"Permanent myshopify.com host only; schemes, paths, query strings and custom storefront hosts are rejected."}}},"example":{"shop_domain":"support-store.myshopify.com"}}}}}},"/api/v1/accounts/{account_id}/integrations/shopify/orders":{"get":{"tags":["Integrations"],"operationId":"auto_get_api_v1_accounts_account_id_integrations_shopify_orders","summary":"List recent Shopify orders for a contact","description":"Looks up the account contact by email or phone and returns a minimal order projection from the connected Shopify store. No customer/order response is persisted. Shopify normally limits this lookup to the most recent 60 days unless the app has separately approved extended access.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Matching orders, or an empty array when Shopify finds no matching customer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["orders"],"properties":{"orders":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["id","created_at","total_price","currency","admin_url"],"properties":{"id":{"type":"integer","format":"int64","example":456},"created_at":{"type":"string","format":"date-time"},"total_price":{"type":"string","example":"100.00"},"currency":{"type":"string","example":"BRL"},"fulfillment_status":{"type":["string","null"],"enum":["fulfilled","partial","restocked",null],"example":"fulfilled","description":"Shopify REST aggregate fulfillment status; null means no line item has been fulfilled."},"financial_status":{"type":"string","enum":["pending","authorized","partially_paid","paid","partially_refunded","refunded","voided"],"example":"paid","description":"Shopify REST payment status."},"admin_url":{"type":"string","format":"uri","example":"https://support-store.myshopify.com/admin/orders/456"}}}}}},"example":{"orders":[{"id":456,"created_at":"2026-01-15T10:30:00.000Z","total_price":"100.00","currency":"BRL","fulfillment_status":"fulfilled","financial_status":"paid","admin_url":"https://support-store.myshopify.com/admin/orders/456"}]}}}},"401":{"description":"The authenticated member is not authorized to view the requested contact."},"404":{"description":"No Shopify connection exists for this account."},"403":{"description":"The Shopify feature is disabled for this account."},"422":{"description":"Contact information is missing, the saved shop is invalid, or Shopify could not answer safely.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string"}}},"example":{"error":"sample error"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"contact_id","in":"query","required":true,"schema":{"type":"integer","minimum":1},"description":"Account-owned contact visible to the authenticated member."}]}},"/api/v1/accounts/{account_id}/integrations/shopify":{"delete":{"tags":["Integrations"],"operationId":"auto_delete_api_v1_accounts_account_id_integrations_shopify","summary":"Disconnect Shopify from an account","description":"Permanently removes the stored Shopify access token for this account. Available to an account administrator or native integration manager even when the feature has been disabled, so stale credentials can always be removed.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Connection removed. Empty body."},"401":{"description":"The authenticated member cannot manage integrations."},"404":{"description":"No Shopify connection exists for this account."},"422":{"description":"The stored connection could not be removed.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string"}}},"example":{"error":"sample error"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/integrations/linear":{"delete":{"tags":["Integrations"],"operationId":"auto_delete_api_v1_accounts_account_id_integrations_linear","summary":"Delete linear","description":"Deletes the linear identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Success (no content)"},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/integrations/linear/teams":{"get":{"tags":["Integrations"],"operationId":"auto_get_api_v1_accounts_account_id_integrations_linear_teams","summary":"Teams linear","description":"Performs the teams operation on the targeted linear resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Linear teams","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"},"name":{"type":"string","example":"Engineering"}}}},"example":[{"id":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","name":"Engineering"}]}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"422":{"description":"Linear API error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","example":{"errors":[{"message":"Authentication required"}]}}}},"example":{"error":{"errors":[{"message":"Authentication required"}]}}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/integrations/linear/team_entities":{"get":{"tags":["Integrations"],"operationId":"auto_get_api_v1_accounts_account_id_integrations_linear_team_entities","summary":"Team entities linear","description":"Performs the team entities operation on the targeted linear resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Linear team entities (users, projects, workflow states, labels)","content":{"application/json":{"schema":{"type":"object","properties":{"users":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"u1b2c3d4-e5f6-7890-abcd-ef1234567890"},"name":{"type":"string","example":"Jane Doe"}}}},"projects":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"p1b2c3d4-e5f6-7890-abcd-ef1234567890"},"name":{"type":"string","example":"Mobile App"}}}},"states":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"s1b2c3d4-e5f6-7890-abcd-ef1234567890"},"name":{"type":"string","example":"In Progress"}}}},"labels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"l1b2c3d4-e5f6-7890-abcd-ef1234567890"},"name":{"type":"string","example":"Bug"}}}}}},"example":{"users":[{"id":"u1b2c3d4-e5f6-7890-abcd-ef1234567890","name":"Jane Doe"}],"projects":[{"id":"p1b2c3d4-e5f6-7890-abcd-ef1234567890","name":"Mobile App"}],"states":[{"id":"s1b2c3d4-e5f6-7890-abcd-ef1234567890","name":"In Progress"}],"labels":[{"id":"l1b2c3d4-e5f6-7890-abcd-ef1234567890","name":"Bug"}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"team_id","in":"query","required":false,"description":"Team whose entities (states, labels, members, projects) are listed. Omitted, the workspace-wide set is returned.","schema":{"type":"string"},"example":"TEAM-123"}]}},"/api/v1/accounts/{account_id}/integrations/linear/create_issue":{"post":{"tags":["Integrations"],"operationId":"auto_post_api_v1_accounts_account_id_integrations_linear_create_issue","summary":"Create issue linear","description":"Performs the create issue operation on the targeted linear resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Created Linear issue","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","example":"i1b2c3d4-e5f6-7890-abcd-ef1234567890"},"title":{"type":"string","example":"Fix login redirect"},"identifier":{"type":"string","example":"ENG-123"}}},"example":{"id":"i1b2c3d4-e5f6-7890-abcd-ef1234567890","title":"Fix login redirect","identifier":"ENG-123"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"422":{"description":"Linear API error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","example":{"errors":[{"message":"Title is required"}]}}}},"example":{"error":{"errors":[{"message":"Title is required"}]}}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"team_id":{"type":"integer"},"project_id":{"type":"integer"},"conversation_id":{"type":"integer"},"issue_id":{"type":"integer"},"link_id":{"type":"integer"},"title":{"type":"string"},"description":{"type":"string"},"assignee_id":{"type":"integer"},"priority":{"type":"string"},"state_id":{"type":"integer"},"reply_marker":{"type":"string"},"label_ids":{"type":"array","items":{"type":"integer"}}}},"example":{"team_id":1,"project_id":1,"conversation_id":1,"issue_id":1,"link_id":1,"title":"Sample title","description":"A short description.","assignee_id":1,"priority":"sample priority","state_id":1,"reply_marker":"sample reply marker","label_ids":[1]}}}}}},"/api/v1/accounts/{account_id}/integrations/linear/link_issue":{"post":{"tags":["Integrations"],"operationId":"auto_post_api_v1_accounts_account_id_integrations_linear_link_issue","summary":"Link issue linear","description":"Performs the link issue operation on the targeted linear resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Issue linked to the conversation","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Linear issue id","example":"ENG-123"},"link":{"type":"string","example":"https://app.example.com/app/accounts/1/conversations/33"},"link_id":{"type":"string","description":"Linear attachment id","example":"att-1b2c3d4e5f"}}},"example":{"id":"ENG-123","link":"https://app.example.com/app/accounts/1/conversations/33","link_id":"att-1b2c3d4e5f"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"team_id":{"type":"integer"},"project_id":{"type":"integer"},"conversation_id":{"type":"integer"},"issue_id":{"type":"integer"},"link_id":{"type":"integer"},"title":{"type":"string"},"description":{"type":"string"},"assignee_id":{"type":"integer"},"priority":{"type":"string"},"state_id":{"type":"integer"},"reply_marker":{"type":"string"},"label_ids":{"type":"array","items":{"type":"integer"}}}},"example":{"team_id":1,"project_id":1,"conversation_id":1,"issue_id":1,"link_id":1,"title":"Sample title","description":"A short description.","assignee_id":1,"priority":"sample priority","state_id":1,"reply_marker":"sample reply marker","label_ids":[1]}}}}}},"/api/v1/accounts/{account_id}/integrations/linear/unlink_issue":{"post":{"tags":["Integrations"],"operationId":"auto_post_api_v1_accounts_account_id_integrations_linear_unlink_issue","summary":"Unlink issue linear","description":"Performs the unlink issue operation on the targeted linear resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Issue unlinked","content":{"application/json":{"schema":{"type":"object","properties":{"link_id":{"type":"string","example":"att-1b2c3d4e5f"}}},"example":{"link_id":"att-1b2c3d4e5f"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"team_id":{"type":"integer"},"project_id":{"type":"integer"},"conversation_id":{"type":"integer"},"issue_id":{"type":"integer"},"link_id":{"type":"integer"},"title":{"type":"string"},"description":{"type":"string"},"assignee_id":{"type":"integer"},"priority":{"type":"string"},"state_id":{"type":"integer"},"reply_marker":{"type":"string"},"label_ids":{"type":"array","items":{"type":"integer"}}}},"example":{"team_id":1,"project_id":1,"conversation_id":1,"issue_id":1,"link_id":1,"title":"Sample title","description":"A short description.","assignee_id":1,"priority":"sample priority","state_id":1,"reply_marker":"sample reply marker","label_ids":[1]}}}}}},"/api/v1/accounts/{account_id}/integrations/linear/search_issue":{"get":{"tags":["Integrations"],"operationId":"auto_get_api_v1_accounts_account_id_integrations_linear_search_issue","summary":"Search issue linear","description":"Performs the search issue operation on the targeted linear resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Matching Linear issues","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"i1b2c3d4-e5f6-7890-abcd-ef1234567890"},"title":{"type":"string","example":"Fix login redirect"},"description":{"type":["string","null"],"example":"Users cannot log in on Safari"},"identifier":{"type":"string","example":"ENG-123"},"url":{"type":"string","example":"https://linear.app/acme/issue/ENG-123"},"state":{"type":"object","properties":{"name":{"type":"string","example":"In Progress"},"color":{"type":"string","example":"#f2c94c"}}}}}},"example":[{"id":"i1b2c3d4-e5f6-7890-abcd-ef1234567890","title":"Fix login redirect","description":"Users cannot log in on Safari","identifier":"ENG-123","url":"https://linear.app/acme/issue/ENG-123","state":{"name":"In Progress","color":"#f2c94c"}}]}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"422":{"description":"Missing q parameter or Linear error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Specify search string with parameter q"}}},"example":{"error":"Specify search string with parameter q"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"q","in":"query","required":true,"description":"Search term matched against issue titles. A blank term returns 422.","schema":{"type":"string"},"example":"checkout bug"}]}},"/api/v1/accounts/{account_id}/integrations/linear/linked_issues":{"get":{"tags":["Integrations"],"operationId":"auto_get_api_v1_accounts_account_id_integrations_linear_linked_issues","summary":"Linked issues linear","description":"Performs the linked issues operation on the targeted linear resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Issues linked to the conversation","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Linear attachment id","example":"att-1b2c3d4e5f"},"title":{"type":"string","example":"Conversation #33"},"issue":{"type":"object","properties":{"id":{"type":"string","example":"i1b2c3d4-e5f6-7890-abcd-ef1234567890"},"identifier":{"type":"string","example":"ENG-123"},"title":{"type":"string","example":"Fix login redirect"},"description":{"type":["string","null"],"example":"Users cannot log in on Safari"},"priority":{"type":"integer","description":"0..4","example":2},"createdAt":{"type":"string","format":"date-time","example":"2026-01-15T10:30:00.000Z"},"url":{"type":"string","example":"https://linear.app/acme/issue/ENG-123"},"assignee":{"type":["object","null"],"properties":{"name":{"type":"string","example":"Jane Doe"},"avatarUrl":{"type":["string","null"],"example":"https://linear.app/avatars/jane.png"}}},"state":{"type":"object","properties":{"name":{"type":"string","example":"In Progress"},"color":{"type":"string","example":"#f2c94c"}}},"labels":{"type":"object","properties":{"nodes":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"l1b2c3d4-e5f6"},"name":{"type":"string","example":"Bug"},"color":{"type":"string","example":"#eb5757"},"description":{"type":["string","null"],"example":"Something is broken"}}}}}}}}}}},"example":[{"id":"att-1b2c3d4e5f","title":"Conversation #33","issue":{"id":"i1b2c3d4-e5f6-7890-abcd-ef1234567890","identifier":"ENG-123","title":"Fix login redirect","description":"Users cannot log in on Safari","priority":2,"createdAt":"2026-01-15T10:30:00.000Z","url":"https://linear.app/acme/issue/ENG-123","assignee":{"name":"Jane Doe","avatarUrl":"https://linear.app/avatars/jane.png"},"state":{"name":"In Progress","color":"#f2c94c"},"labels":{"nodes":[{"id":"l1b2c3d4-e5f6","name":"Bug","color":"#eb5757","description":"Something is broken"}]}}}]}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/integrations/linear/bug_report_settings":{"get":{"tags":["Integrations"],"operationId":"auto_get_api_v1_accounts_account_id_integrations_linear_bug_report_settings","summary":"Retired account bug-report routing","description":"Bug Reports tracker configuration belongs exclusively to the installation operator. This account endpoint performs no configuration or provider work.","security":[{"userApiKey":[]}],"responses":{"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"410":{"description":"Configuration moved to the installation-only Bug Reports API.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["tracker","managed_by"],"properties":{"tracker":{"type":"string","enum":["install_linear"]},"managed_by":{"type":"string","enum":["installation"]}}},"example":{"tracker":"install_linear","managed_by":"installation"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"deprecated":true},"put":{"tags":["Integrations"],"operationId":"auto_put_api_v1_accounts_account_id_integrations_linear_bug_report_settings","summary":"Retired account bug-report routing write","description":"Always returns410 without changing settings, credentials, webhooks or queued work. The account's general Linear OAuth integration remains a separate function.","security":[{"userApiKey":[]}],"responses":{"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"410":{"description":"Account-scoped Bug Reports writes are retired.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["tracker","managed_by"],"properties":{"tracker":{"type":"string","enum":["install_linear"]},"managed_by":{"type":"string","enum":["installation"]}}},"example":{"tracker":"install_linear","managed_by":"installation"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"deprecated":true}},"/api/v1/accounts/{account_id}/integrations/notion":{"delete":{"tags":["Integrations"],"operationId":"auto_delete_api_v1_accounts_account_id_integrations_notion","summary":"Delete notion","description":"Deletes the notion identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Success (no content)"},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/portals/{id}/archive":{"patch":{"tags":["Help Center"],"operationId":"auto_patch_api_v1_accounts_account_id_portals_id_archive","summary":"Archive portals","description":"Performs the archive operation on the targeted portal resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Success (no content)"},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/portals/{id}/logo":{"delete":{"tags":["Help Center"],"operationId":"auto_delete_api_v1_accounts_account_id_portals_id_logo","summary":"Logo portals","description":"Performs the logo operation on the targeted portal resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Success (no content)"},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/portals/{id}/send_instructions":{"post":{"tags":["Help Center"],"operationId":"auto_post_api_v1_accounts_account_id_portals_id_send_instructions","summary":"Send instructions portals","description":"Performs the send instructions operation on the targeted portal resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}},"example":{"message":"Sample message text."}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"email":{"type":"string","format":"email"}}},"example":{"id":1,"email":"agent@example.com"}}}}}},"/api/v1/accounts/{account_id}/portals/{id}/ssl_status":{"get":{"tags":["Help Center"],"operationId":"auto_get_api_v1_accounts_account_id_portals_id_ssl_status","summary":"Ssl status portals","description":"Performs the ssl status operation on the targeted portal resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Custom-domain SSL/hostname verification status","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","description":"Cloudflare custom-hostname SSL status (from ssl_settings.cf_status)","example":"active"},"verification_errors":{"type":["string","null"],"description":"Custom-hostname verification error (first Cloudflare `verification_errors` entry, or '' when none) — from ssl_settings.cf_verification_errors","example":""}}},"example":{"status":"active","verification_errors":""}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/portals/{portal_id}/categories/reorder":{"post":{"tags":["Help Center"],"operationId":"auto_post_api_v1_accounts_account_id_portals_portal_id_categories_reorder","summary":"Reorder help center categories","description":"Applies a new manual ordering to the categories of a help center portal. The request carries a map of category id to its new zero-based position; each referenced category is repositioned inside a single database transaction, so either every category moves or none does. An empty or omitted map is accepted as a no-op. On success the endpoint returns HTTP 200 with an EMPTY body — the caller should refetch the category list to read the resulting order.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Categories reordered. Empty body."},"401":{"description":"The caller did not provide valid credentials or lacks permission to reorder categories.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false},"example":{"error":"You are not authorized to do this action"}}}},"404":{"description":"The portal slug does not exist in this account, or one of the ids in the map is not a category of that portal. The transaction is rolled back, so no category was moved.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false},"example":{"error":"Resource could not be found"}}}},"422":{"description":"One or more map keys or positions is invalid. The complete reorder is atomic: every submitted position remains unchanged when this response is returned.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"attributes":{"type":"array","items":{"type":"string"}}},"required":["message","attributes"],"additionalProperties":false},"example":{"message":"is invalid","attributes":["base"]}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"portal_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"positions_hash":{"type":"object","description":"Map whose key is the category id (as a string) and whose value is the new position of that category within the portal. Categories omitted from the map keep their current position. Every id must belong to the portal in the path, otherwise the whole request fails with 404 and no category is moved. Omit this property or send null/{} for a no-op. Keys and string values are canonical base-10 decimals only; the mutation boundary additionally enforces the stated numeric upper bounds before any row changes.","propertyNames":{"type":"string","pattern":"^(?:[1-9][0-9]{0,17}|[1-8][0-9]{18}|9[0-1][0-9]{17}|92[0-1][0-9]{16}|922[0-2][0-9]{15}|9223[0-2][0-9]{14}|92233[0-6][0-9]{13}|922337[0-1][0-9]{12}|92233720[0-2][0-9]{10}|922337203[0-5][0-9]{9}|9223372036[0-7][0-9]{8}|92233720368[0-4][0-9]{7}|922337203685[0-3][0-9]{6}|9223372036854[0-6][0-9]{5}|92233720368547[0-6][0-9]{4}|922337203685477[0-4][0-9]{3}|9223372036854775[0-7][0-9]{2}|922337203685477580[0-6]|9223372036854775807)$","maxLength":19},"additionalProperties":{"oneOf":[{"type":"integer","minimum":0,"maximum":2147483647},{"type":"string","pattern":"^(?:0|[1-9][0-9]{0,8}|1[0-9]{9}|20[0-9]{8}|21[0-3][0-9]{7}|214[0-6][0-9]{6}|2147[0-3][0-9]{5}|21474[0-7][0-9]{4}|214748[0-2][0-9]{3}|2147483[0-5][0-9]{2}|21474836[0-3][0-9]|214748364[0-6]|2147483647)$","maxLength":10}],"description":"Canonical zero-based position (0 through 2147483647) of the category identified by the key."}}}},"example":{"positions_hash":{"41":0,"42":1,"43":2}}}}},"x-error-evidence":[{"status":"401","media_type":"application/json","envelope":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false},"response_example":{"error":"You are not authorized to do this action"},"witness":{"id":"categories_reorder_forbidden_role_401","route":{"verb":"POST","path":"/api/v1/accounts/{account_id}/portals/{portal_id}/categories/reorder"},"controller":"api/v1/accounts/categories#reorder","status":"401","response":{"error":"You are not authorized to do this action"},"boundary":{"kind":"around_action","exception":"Pundit::NotAuthorizedError","handler":"RequestExceptionHandler#handle_with_exception"},"serializer":{"kind":"witnessed_json","source":"app/controllers/concerns/request_exception_handler.rb#render_unauthorized"},"source_spec":{"file":"spec/controllers/api/v1/accounts/categories_controller_spec.rb","id":"categories_reorder_forbidden_role_401"},"edge_id":"871b7493584b044870769a8d364f05d11692b7f9579c4d7146a00ff54bf07ba8","render_node":{"source":"app/controllers/concerns/request_exception_handler.rb","owner":"RequestExceptionHandler","method":"render_unauthorized","start_offset":1340,"end_offset":1394,"digest":"14f239ea082cb59290a677377b075e144e0d12e2324c899e3ec996915cd3788d","status":"401"}}},{"status":"404","media_type":"application/json","envelope":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false},"response_example":{"error":"Resource could not be found"},"witness":{"id":"categories_reorder_cross_portal_404","route":{"verb":"POST","path":"/api/v1/accounts/{account_id}/portals/{portal_id}/categories/reorder"},"controller":"api/v1/accounts/categories#reorder","status":"404","response":{"error":"Resource could not be found"},"boundary":{"kind":"around_action","exception":"ActiveRecord::RecordNotFound","handler":"RequestExceptionHandler#handle_with_exception"},"serializer":{"kind":"literal_json","source":"app/controllers/concerns/request_exception_handler.rb#render_not_found_error"},"source_spec":{"file":"spec/controllers/api/v1/accounts/categories_controller_spec.rb","id":"categories_reorder_cross_portal_404"},"edge_id":"45e2131987291c739ce9c386a548c8517ee3cc9d3de5ea2fee65fbdf5a8e0359","render_node":{"source":"app/controllers/concerns/request_exception_handler.rb","owner":"RequestExceptionHandler","method":"render_not_found_error","start_offset":1444,"end_offset":1495,"digest":"44309c8278de5325dbb148656d3ac96a90b90eba0427a5671c6fd0e7ea33e0c3","status":"404"}}},{"status":"422","media_type":"application/json","envelope":{"type":"object","properties":{"message":{"type":"string"},"attributes":{"type":"array"}},"required":["message","attributes"],"additionalProperties":false},"response_example":{"message":"is invalid","attributes":["base"]},"witness":{"id":"categories_reorder_invalid_positions_422","route":{"verb":"POST","path":"/api/v1/accounts/{account_id}/portals/{portal_id}/categories/reorder"},"controller":"api/v1/accounts/categories#reorder","status":"422","response":{"message":"is invalid","attributes":["base"]},"boundary":{"kind":"rescue_from","exception":"ActiveRecord::RecordInvalid","handler":"render_record_invalid"},"serializer":{"kind":"literal_json","source":"app/controllers/concerns/request_exception_handler.rb#render_record_invalid"},"source_spec":{"file":"spec/controllers/api/v1/accounts/categories_controller_spec.rb","id":"categories_reorder_invalid_positions_422"},"edge_id":"5bc4878e6aab0cebbce49c37ec4d1283815e7ab486582af073afbb4eaf6356b3","render_node":{"source":"app/controllers/concerns/request_exception_handler.rb","owner":"RequestExceptionHandler","method":"render_record_invalid","start_offset":1947,"end_offset":2121,"digest":"6de1e89c4117aba5b70ea4b3de88e4cb5bb1533ebf1d5320fc6b473c150bfb05","status":"422"}}}]}},"/api/v1/accounts/{account_id}/portals/{portal_id}/categories/{id}":{"get":{"tags":["Help Center"],"operationId":"auto_get_api_v1_accounts_account_id_portals_portal_id_categories_id","summary":"Get categories","description":"Returns the category identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"slug":{"type":"string"},"locale":{"type":"string"},"description":{"type":"string"},"position":{"type":"integer"},"visibility":{"type":"string","enum":["public","operator"]},"account_id":{"type":"integer"},"icon":{"type":"string"},"icon_color":{"type":"string"},"related_categories":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"slug":{"type":"string"},"locale":{"type":"string"},"description":{"type":"string"},"position":{"type":"integer"},"account_id":{"type":"integer"}}}},"parent_category":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"slug":{"type":"string"},"locale":{"type":"string"},"description":{"type":"string"},"position":{"type":"integer"},"account_id":{"type":"integer"}}},"root_category":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"slug":{"type":"string"},"locale":{"type":"string"},"description":{"type":"string"},"position":{"type":"integer"},"account_id":{"type":"integer"}}},"meta":{"type":"object","properties":{"articles_count":{"type":"integer"}}}}}}},"example":{"payload":{"id":1,"name":"Sample Name","slug":"sample-slug","locale":"en","description":"A short description.","position":1,"visibility":"public","account_id":1,"icon":"sample icon","icon_color":"#1F93FF","related_categories":[{"id":1,"name":"Sample Name","slug":"sample-slug","locale":"en","description":"A short description.","position":1,"account_id":1}],"parent_category":{"id":1,"name":"Sample Name","slug":"sample-slug","locale":"en","description":"A short description.","position":1,"account_id":1},"root_category":{"id":1,"name":"Sample Name","slug":"sample-slug","locale":"en","description":"A short description.","position":1,"account_id":1},"meta":{"articles_count":5}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"portal_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]},"patch":{"tags":["Help Center"],"operationId":"auto_patch_api_v1_accounts_account_id_portals_portal_id_categories_id","summary":"Update categories","description":"Updates the category identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Category updated","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer","example":42},"name":{"type":"string","example":"Getting Started"},"slug":{"type":"string","example":"getting-started"},"locale":{"type":"string","example":"en"},"description":{"type":"string","example":"Onboarding and setup articles"},"position":{"type":"integer","example":1},"account_id":{"type":"integer","example":1},"icon":{"type":"string","example":"rocket"},"icon_color":{"type":"string","example":"#1F93FF"},"related_categories":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","example":43},"name":{"type":"string","example":"Introdução"},"slug":{"type":"string","example":"introducao"},"locale":{"type":"string","example":"pt_BR"},"description":{"type":"string","example":""},"position":{"type":"integer","example":1},"account_id":{"type":"integer","example":1}}}},"parent_category":{"type":["object","null"],"properties":{"id":{"type":"integer","example":40},"name":{"type":"string","example":"Docs"},"slug":{"type":"string","example":"docs"},"locale":{"type":"string","example":"en"},"description":{"type":"string","example":""},"position":{"type":"integer","example":0},"account_id":{"type":"integer","example":1}}},"root_category":{"type":["object","null"],"properties":{"id":{"type":"integer","example":40},"name":{"type":"string","example":"Docs"},"slug":{"type":"string","example":"docs"},"locale":{"type":"string","example":"en"},"description":{"type":"string","example":""},"position":{"type":"integer","example":0},"account_id":{"type":"integer","example":1}}},"meta":{"type":"object","properties":{"articles_count":{"type":"integer","example":12}}}}}}},"example":{"payload":{"id":42,"name":"Getting Started","slug":"getting-started","locale":"en","description":"Onboarding and setup articles","position":1,"account_id":1,"icon":"rocket","icon_color":"#1F93FF","related_categories":[{"id":43,"name":"Introdução","slug":"introducao","locale":"pt_BR","description":"","position":1,"account_id":1}],"parent_category":{"id":40,"name":"Docs","slug":"docs","locale":"en","description":"","position":0,"account_id":1},"root_category":{"id":40,"name":"Docs","slug":"docs","locale":"en","description":"","position":0,"account_id":1},"meta":{"articles_count":12}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"portal_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"category":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"position":{"type":"integer"},"slug":{"type":"string"},"locale":{"type":"string","enum":["en","pt_BR","es"]},"icon":{"type":"string"},"icon_color":{"type":"string"},"parent_category_id":{"type":"integer"},"associated_category_id":{"type":"integer"},"related_category_ids":{"type":"array","items":{"type":"integer"}}}}},"required":["category"]},"example":{"category":{"name":"Sample Name","description":"A short description.","position":1,"slug":"sample-slug","locale":"en","icon":"sample icon","icon_color":"#1F93FF","parent_category_id":1,"associated_category_id":1,"related_category_ids":[1]}}}}}},"put":{"tags":["Help Center"],"operationId":"auto_put_api_v1_accounts_account_id_portals_portal_id_categories_id","summary":"Update categories","description":"Updates the category identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Category updated","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer","example":42},"name":{"type":"string","example":"Getting Started"},"slug":{"type":"string","example":"getting-started"},"locale":{"type":"string","example":"en"},"description":{"type":"string","example":"Onboarding and setup articles"},"position":{"type":"integer","example":1},"account_id":{"type":"integer","example":1},"icon":{"type":"string","example":"rocket"},"icon_color":{"type":"string","example":"#1F93FF"},"related_categories":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","example":43},"name":{"type":"string","example":"Introdução"},"slug":{"type":"string","example":"introducao"},"locale":{"type":"string","example":"pt_BR"},"description":{"type":"string","example":""},"position":{"type":"integer","example":1},"account_id":{"type":"integer","example":1}}}},"parent_category":{"type":["object","null"],"properties":{"id":{"type":"integer","example":40},"name":{"type":"string","example":"Docs"},"slug":{"type":"string","example":"docs"},"locale":{"type":"string","example":"en"},"description":{"type":"string","example":""},"position":{"type":"integer","example":0},"account_id":{"type":"integer","example":1}}},"root_category":{"type":["object","null"],"properties":{"id":{"type":"integer","example":40},"name":{"type":"string","example":"Docs"},"slug":{"type":"string","example":"docs"},"locale":{"type":"string","example":"en"},"description":{"type":"string","example":""},"position":{"type":"integer","example":0},"account_id":{"type":"integer","example":1}}},"meta":{"type":"object","properties":{"articles_count":{"type":"integer","example":12}}}}}}},"example":{"payload":{"id":42,"name":"Getting Started","slug":"getting-started","locale":"en","description":"Onboarding and setup articles","position":1,"account_id":1,"icon":"rocket","icon_color":"#1F93FF","related_categories":[{"id":43,"name":"Introdução","slug":"introducao","locale":"pt_BR","description":"","position":1,"account_id":1}],"parent_category":{"id":40,"name":"Docs","slug":"docs","locale":"en","description":"","position":0,"account_id":1},"root_category":{"id":40,"name":"Docs","slug":"docs","locale":"en","description":"","position":0,"account_id":1},"meta":{"articles_count":12}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"portal_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"category":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"position":{"type":"integer"},"slug":{"type":"string"},"locale":{"type":"string","enum":["en","pt_BR","es"]},"icon":{"type":"string"},"icon_color":{"type":"string"},"parent_category_id":{"type":"integer"},"associated_category_id":{"type":"integer"},"related_category_ids":{"type":"array","items":{"type":"integer"}}}}},"required":["category"]},"example":{"category":{"name":"Sample Name","description":"A short description.","position":1,"slug":"sample-slug","locale":"en","icon":"sample icon","icon_color":"#1F93FF","parent_category_id":1,"associated_category_id":1,"related_category_ids":[1]}}}}}},"delete":{"tags":["Help Center"],"operationId":"auto_delete_api_v1_accounts_account_id_portals_portal_id_categories_id","summary":"Delete categories","description":"Deletes the category identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Success (no content)"},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"portal_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/portals/{portal_id}/articles/bulk_actions/translate":{"post":{"tags":["Help Center"],"operationId":"auto_post_api_v1_accounts_account_id_portals_portal_id_articles_bulk_actions_translate","summary":"Translate bulk actions","description":"Performs the translate operation on the targeted bulk action resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Translation jobs enqueued (one per article)"},"401":{"description":"Authentication or authorization failure — the caller is not a member of the account, the account is suspended, or the effective role is not allowed to create articles in this portal. Returned as `{ error: \u003cmessage\u003e }`.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"You are not authorized to do this action"}}},"example":{"error":"You are not authorized to do this action"}}}},"404":{"description":"No portal matches the `portal_id` slug within this account, or the account itself does not exist.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Resource could not be found"}}},"example":{"error":"Resource could not be found"}}}},"409":{"description":"Existing translations found for one or more articles; resend with force=true to override","content":{"application/json":{"schema":{"type":"object","properties":{"duplicate_articles":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","example":101},"title":{"type":"string","example":"How to connect WhatsApp"}}}}}},"example":{"duplicate_articles":[{"id":101,"title":"How to connect WhatsApp"}]}}}},"422":{"description":"Validation error rendered as `{ error: \u003cmessage\u003e }` — Captain not available (feature captain_tasks disabled), target locale not in the portal's allowed_locales, destination category not found in the target locale, or no matching articles for the given ids.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Translation requires Captain to be enabled for this account"}}},"example":{"error":"Translation requires Captain to be enabled for this account"}}}},"501":{"description":"Translation is provided by the Captain (Enterprise) overlay. An installation running without that overlay answers `501 Not Implemented` with an empty body, whatever the payload."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"portal_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["locale","ids"],"properties":{"locale":{"type":"string","description":"Target locale to translate the selected articles into (must be an allowed portal locale)","example":"es"},"category_id":{"type":["integer","null"],"description":"Optional destination category (must exist in the target locale)","example":55},"force":{"type":"boolean","description":"Proceed even when translations already exist (skips the 409 duplicate guard)","example":false},"ids":{"type":"array","items":{"type":"integer"},"description":"Article ids to translate","example":[101,102]}}},"example":{"locale":"es","category_id":55,"force":false,"ids":[101,102]}}}}}},"/api/v1/accounts/{account_id}/portals/{portal_id}/articles/bulk_actions/update_status":{"patch":{"tags":["Help Center"],"operationId":"auto_patch_api_v1_accounts_account_id_portals_portal_id_articles_bulk_actions_update_status","summary":"Change the publication status of several articles","description":"Moves a list of help center articles to the same publication status in one call — the bulk publish, unpublish (back to draft) and archive action of the article list. Only articles that belong to the portal in the path are affected; ids from another portal are silently ignored by the lookup. Every update runs inside one transaction, so a validation failure on any article leaves all of them unchanged. On success the endpoint returns HTTP 200 with an EMPTY body.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Every listed article now carries the requested status. Empty body."},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"422":{"description":"No article of this portal matched the ids, the status is not one of the accepted values, or an article failed validation. Nothing was changed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Localized reason the bulk update was rejected."}},"required":["error"]},"example":{"error":"No articles found for the given ids"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"portal_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ids":{"type":"array","description":"Ids of the articles to update. Ids outside the portal are ignored.","items":{"type":"integer"}},"status":{"type":"string","description":"Publication status applied to every article in the list.","enum":["draft","published","archived"]}},"required":["ids","status"]},"example":{"ids":[901,902],"status":"published"}}}}}},"/api/v1/accounts/{account_id}/portals/{portal_id}/articles/bulk_actions/update_category":{"patch":{"tags":["Help Center"],"operationId":"auto_patch_api_v1_accounts_account_id_portals_portal_id_articles_bulk_actions_update_category","summary":"Move several articles to another category","description":"Reassigns a list of help center articles to the same category in one call. The target category must belong to the portal in the path; only articles of that portal are affected. Every update runs inside one transaction, so a validation failure on any article leaves all of them unchanged. On success the endpoint returns HTTP 200 with an EMPTY body.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Every listed article now belongs to the requested category. Empty body."},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"422":{"description":"No article of this portal matched the ids, the destination category does not belong to this portal, or an article failed validation. Nothing was changed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Localized reason the bulk move was rejected."}},"required":["error"]},"example":{"error":"Category not found in this portal"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"portal_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ids":{"type":"array","description":"Ids of the articles to move. Ids outside the portal are ignored.","items":{"type":"integer"}},"category_id":{"type":"integer","description":"Id of the destination category. It must belong to the portal in the path."}},"required":["ids","category_id"]},"example":{"ids":[901,902],"category_id":41}}}}}},"/api/v1/accounts/{account_id}/portals/{portal_id}/articles/bulk_actions/delete_articles":{"delete":{"tags":["Help Center"],"operationId":"auto_delete_api_v1_accounts_account_id_portals_portal_id_articles_bulk_actions_delete_articles","summary":"Delete articles bulk actions","description":"Performs the delete articles operation on the targeted bulk action resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Success (no content)"},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"portal_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/portals/{portal_id}/articles/reorder":{"post":{"tags":["Help Center"],"operationId":"auto_post_api_v1_accounts_account_id_portals_portal_id_articles_reorder","summary":"Reorder help center articles","description":"Applies a new manual ordering to the articles of a help center portal — the ordering used when the article list is browsed by category. The request carries a map of article id to its new zero-based position, applied inside a single database transaction. An empty or omitted map is accepted as a no-op. On success the endpoint returns HTTP 200 with an EMPTY body — refetch the article list to read the resulting order.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Articles reordered. Empty body."},"401":{"description":"The caller did not provide valid credentials or lacks permission to reorder articles.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false},"example":{"error":"You are not authorized to do this action"}}}},"404":{"description":"The portal slug does not exist in this account, or one of the ids in the map is not an article of that portal. The transaction is rolled back, so no article was moved.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false},"example":{"error":"Resource could not be found"}}}},"422":{"description":"One or more map keys or positions is invalid. The complete reorder is atomic: every submitted position remains unchanged when this response is returned.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"attributes":{"type":"array","items":{"type":"string"}}},"required":["message","attributes"],"additionalProperties":false},"example":{"message":"is invalid","attributes":["base"]}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"portal_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"positions_hash":{"type":"object","description":"Map whose key is the article id (as a string) and whose value is the new position of that article. Articles omitted from the map keep their current position. Every id must belong to the portal in the path, otherwise the whole request fails with 404 and no article is moved. Omit this property or send null/{} for a no-op. Keys and string values are canonical base-10 decimals only; the mutation boundary additionally enforces the stated numeric upper bounds before any row changes.","propertyNames":{"type":"string","pattern":"^(?:[1-9][0-9]{0,17}|[1-8][0-9]{18}|9[0-1][0-9]{17}|92[0-1][0-9]{16}|922[0-2][0-9]{15}|9223[0-2][0-9]{14}|92233[0-6][0-9]{13}|922337[0-1][0-9]{12}|92233720[0-2][0-9]{10}|922337203[0-5][0-9]{9}|9223372036[0-7][0-9]{8}|92233720368[0-4][0-9]{7}|922337203685[0-3][0-9]{6}|9223372036854[0-6][0-9]{5}|92233720368547[0-6][0-9]{4}|922337203685477[0-4][0-9]{3}|9223372036854775[0-7][0-9]{2}|922337203685477580[0-6]|9223372036854775807)$","maxLength":19},"additionalProperties":{"oneOf":[{"type":"integer","minimum":0,"maximum":2147483647},{"type":"string","pattern":"^(?:0|[1-9][0-9]{0,8}|1[0-9]{9}|20[0-9]{8}|21[0-3][0-9]{7}|214[0-6][0-9]{6}|2147[0-3][0-9]{5}|21474[0-7][0-9]{4}|214748[0-2][0-9]{3}|2147483[0-5][0-9]{2}|21474836[0-3][0-9]|214748364[0-6]|2147483647)$","maxLength":10}],"description":"Canonical zero-based position (0 through 2147483647) of the article identified by the key."}}}},"example":{"positions_hash":{"901":0,"902":1}}}}},"x-error-evidence":[{"status":"401","media_type":"application/json","envelope":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false},"response_example":{"error":"You are not authorized to do this action"},"witness":{"id":"articles_reorder_forbidden_role_401","route":{"verb":"POST","path":"/api/v1/accounts/{account_id}/portals/{portal_id}/articles/reorder"},"controller":"api/v1/accounts/articles#reorder","status":"401","response":{"error":"You are not authorized to do this action"},"boundary":{"kind":"around_action","exception":"Pundit::NotAuthorizedError","handler":"RequestExceptionHandler#handle_with_exception"},"serializer":{"kind":"witnessed_json","source":"app/controllers/concerns/request_exception_handler.rb#render_unauthorized"},"source_spec":{"file":"spec/controllers/api/v1/accounts/articles_controller_spec.rb","id":"articles_reorder_forbidden_role_401"},"edge_id":"871b7493584b044870769a8d364f05d11692b7f9579c4d7146a00ff54bf07ba8","render_node":{"source":"app/controllers/concerns/request_exception_handler.rb","owner":"RequestExceptionHandler","method":"render_unauthorized","start_offset":1340,"end_offset":1394,"digest":"14f239ea082cb59290a677377b075e144e0d12e2324c899e3ec996915cd3788d","status":"401"}}},{"status":"404","media_type":"application/json","envelope":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false},"response_example":{"error":"Resource could not be found"},"witness":{"id":"articles_reorder_cross_portal_404","route":{"verb":"POST","path":"/api/v1/accounts/{account_id}/portals/{portal_id}/articles/reorder"},"controller":"api/v1/accounts/articles#reorder","status":"404","response":{"error":"Resource could not be found"},"boundary":{"kind":"around_action","exception":"ActiveRecord::RecordNotFound","handler":"RequestExceptionHandler#handle_with_exception"},"serializer":{"kind":"literal_json","source":"app/controllers/concerns/request_exception_handler.rb#render_not_found_error"},"source_spec":{"file":"spec/controllers/api/v1/accounts/articles_controller_spec.rb","id":"articles_reorder_cross_portal_404"},"edge_id":"45e2131987291c739ce9c386a548c8517ee3cc9d3de5ea2fee65fbdf5a8e0359","render_node":{"source":"app/controllers/concerns/request_exception_handler.rb","owner":"RequestExceptionHandler","method":"render_not_found_error","start_offset":1444,"end_offset":1495,"digest":"44309c8278de5325dbb148656d3ac96a90b90eba0427a5671c6fd0e7ea33e0c3","status":"404"}}},{"status":"422","media_type":"application/json","envelope":{"type":"object","properties":{"message":{"type":"string"},"attributes":{"type":"array"}},"required":["message","attributes"],"additionalProperties":false},"response_example":{"message":"is invalid","attributes":["base"]},"witness":{"id":"articles_reorder_invalid_positions_422","route":{"verb":"POST","path":"/api/v1/accounts/{account_id}/portals/{portal_id}/articles/reorder"},"controller":"api/v1/accounts/articles#reorder","status":"422","response":{"message":"is invalid","attributes":["base"]},"boundary":{"kind":"rescue_from","exception":"ActiveRecord::RecordInvalid","handler":"render_record_invalid"},"serializer":{"kind":"literal_json","source":"app/controllers/concerns/request_exception_handler.rb#render_record_invalid"},"source_spec":{"file":"spec/controllers/api/v1/accounts/articles_controller_spec.rb","id":"articles_reorder_invalid_positions_422"},"edge_id":"5bc4878e6aab0cebbce49c37ec4d1283815e7ab486582af073afbb4eaf6356b3","render_node":{"source":"app/controllers/concerns/request_exception_handler.rb","owner":"RequestExceptionHandler","method":"render_record_invalid","start_offset":1947,"end_offset":2121,"digest":"6de1e89c4117aba5b70ea4b3de88e4cb5bb1533ebf1d5320fc6b473c150bfb05","status":"422"}}}]}},"/api/v1/accounts/{account_id}/portals/{portal_id}/articles/{id}/edit":{"get":{"tags":["Help Center"],"operationId":"auto_get_api_v1_accounts_account_id_portals_portal_id_articles_id_edit","summary":"Edit articles","description":"Performs the edit operation on the targeted article resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"slug":{"type":"string"},"title":{"type":"string"},"content":{"type":"string"},"description":{"type":"string"},"status":{"type":"string","enum":["draft","published","archived"]},"visibility":{"type":"string","enum":["public","operator"]},"draft_title":{"type":"string"},"draft_content":{"type":"string"},"position":{"type":"integer"},"account_id":{"type":"integer"},"updated_at":{"type":"integer"},"meta":{"type":"string"},"category":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":["string","null"]},"slug":{"type":["string","null"]},"locale":{"type":["string","null"]},"icon":{"type":["string","null"]},"icon_color":{"type":["string","null"]}}},"views":{"type":"string"},"author":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":["integer","null"]},"account_user_id":{"type":["integer","null"]},"availability_status":{"type":"string","enum":["online","offline","busy"],"description":"Realtime availability. Contacts report online/offline (presence-based); agents/users additionally report busy (their configured availability)."},"auto_offline":{"type":"boolean"},"confirmed":{"type":"boolean"},"email":{"type":"string","format":"email"},"provider":{"type":"string","enum":["email","google_oauth2","saml"],"description":"Authentication provider the user signed up through."},"available_name":{"type":"string"},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"name":{"type":"string"},"role":{"type":"string","enum":["agent","administrator"],"description":"The user's role within the account."},"outbound_agent_name_header_policy":{"type":["string","null"]},"thumbnail":{"type":"string"},"custom_role_id":{"type":["integer","null"]},"access_role_id":{"type":["integer","null"]}}},"associated_articles":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"category_id":{"type":"integer"},"title":{"type":"string"},"content":{"type":"string"},"description":{"type":"string"},"status":{"type":"string","enum":["draft","published","archived"],"description":"Publication status of the help-center article."},"visibility":{"type":"string","enum":["public","operator"]},"account_id":{"type":"integer"},"portal":{"type":"object","properties":{"id":{"type":"integer"},"color":{"type":"string"},"custom_domain":{"type":"string"},"header_text":{"type":"string"},"homepage_link":{"type":"string"},"name":{"type":"string"},"page_title":{"type":"string"},"slug":{"type":"string"},"archived":{"type":"boolean"},"account_id":{"type":"integer"},"config":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"articles_count":{"type":"integer"},"categories_count":{"type":"integer"},"draft":{"type":"boolean"}}}},"inbox":{"type":"object","properties":{"id":{"type":"integer"},"avatar_url":{"type":"string"},"channel_id":{"type":"integer"},"name":{"type":"string"},"channel_type":{"type":"string","enum":["Channel::Api","Channel::Email","Channel::FacebookPage","Channel::Instagram","Channel::Line","Channel::Sms","Channel::Telegram","Channel::Tiktok","Channel::TwilioSms","Channel::TwitterProfile","Channel::WebWidget","Channel::Whatsapp"],"description":"The inbox channel class — identifies which messaging channel backs the inbox."},"greeting_enabled":{"type":"boolean"},"greeting_message":{"type":"string"},"working_hours_enabled":{"type":"boolean"},"enable_email_collect":{"type":"string"},"csat_survey_enabled":{"type":"boolean"},"csat_config":{"type":"string"},"enable_auto_assignment":{"type":"string"},"auto_assignment_config":{"type":"string"},"out_of_office_message":{"type":"string"},"working_hours":{"type":"string"},"timezone":{"type":"string","description":"IANA timezone identifier (e.g. \"America/Sao_Paulo\", \"UTC\"). Rails timezone names are also accepted on input; an unrecognized value is ignored in favor of the next fallback.","example":"America/Sao_Paulo"},"callback_webhook_url":{"type":"string"},"allow_messages_after_resolved":{"type":"string"},"lock_to_single_conversation":{"type":"string"},"audio_transcription_enabled":{"type":"boolean"},"preserve_deleted_messages":{"type":"string"},"allow_message_deletion":{"type":"string"},"capture_view_once":{"type":"string"},"sender_name_type":{"type":"string","enum":["friendly","professional"]},"auto_resolve_config":{"type":"object","additionalProperties":true,"oneOf":[{"type":"object","maxProperties":0,"additionalProperties":true,"description":"Empty means inherit the account rule."},{"type":"object","additionalProperties":false,"required":["mode"],"properties":{"mode":{"type":"string","enum":["disabled"],"description":"Disable automatic resolution for this inbox."}},"description":"The disabled rule contains only its mode."},{"type":"object","additionalProperties":false,"required":["mode","after","message","label","allow_waiting"],"properties":{"mode":{"type":"string","enum":["custom"],"description":"Use this complete inbox rule."},"after":{"type":"integer","minimum":10,"maximum":1439856,"description":"Inactivity in minutes; required for custom mode."},"message":{"type":["string","null"],"maxLength":10000,"description":"Optional message; blank normalizes to null."},"label":{"type":["string","null"],"description":"An existing account label title, or null."},"allow_waiting":{"type":"boolean","description":"Whether waiting conversations are included."}},"description":"Complete normalized custom rule."}],"description":"Normalized JSON rule from valid model writes: empty, disabled, or complete custom configuration.","example":{"mode":"custom","after":60,"message":null,"label":null,"allow_waiting":false}},"outbound_agent_name_header_policy":{"type":"string"},"agent_bot_working_hours_mode":{"type":"string","enum":["always","inside_business_hours","outside_business_hours"]},"business_name":{"type":"string"},"responder_policy":{"type":"string"},"help_center":{"type":"object","properties":{"name":{"type":"string"},"slug":{"type":"string"}}},"tweets_enabled":{"type":"boolean"},"allowed_domains":{"type":"string"},"widget_color":{"type":"string"},"website_url":{"type":"string"},"hmac_mandatory":{"type":"string"},"welcome_title":{"type":"string"},"welcome_tagline":{"type":"string"},"web_widget_script":{"type":"string"},"website_token":{"type":"string"},"selected_feature_flags":{"type":"string"},"reply_time":{"type":"string","format":"date-time"},"hmac_token":{"type":"string"},"pre_chat_form_enabled":{"type":"boolean"},"pre_chat_form_options":{"type":"string"},"continuity_via_email":{"type":"string","format":"email"},"page_id":{"type":"integer"},"reauthorization_required":{"type":"string"},"instagram_id":{"type":"integer"},"messaging_service_sid":{"type":"string"},"phone_number":{"type":"string"},"medium":{"type":"string"},"bandwidth_callback_state":{"type":"string","enum":["active","reconnect_required","reconciling","reconciliation_required","encryption_required"]},"bandwidth_api_migration_state":{"type":"string","enum":["oauth2_configured","oauth2_required","configuration_required"]},"bandwidth_legacy_basic_deprecated":{"type":"boolean"},"content_templates":{"type":"string"},"auth_token":{"type":"string"},"account_sid":{"type":"string"},"api_key_sid":{"type":"string"},"twilio_credential_state":{"type":"string","enum":["ready","pending","failed","dead_letter","account_auth_token_required","reconciliation_required"],"description":"Durable Twilio credential lifecycle derived from Channel::TwilioSms. A reconciliation-required state is fail-closed until the provider outcome has been verified."},"api_key_configured":{"type":"boolean"},"email":{"type":"string","format":"email"},"auth_method":{"type":"string"},"forwarding_enabled":{"type":"boolean"},"forward_to_email":{"type":"string","format":"email"},"branded_email_layout":{"type":"string"},"imap_login":{"type":"string"},"imap_password":{"type":"string"},"imap_address":{"type":"string"},"imap_port":{"type":"string"},"imap_enabled":{"type":"boolean"},"imap_enable_ssl":{"type":"string"},"imap_authentication":{"type":"string"},"smtp_login":{"type":"string"},"smtp_password":{"type":"string"},"smtp_address":{"type":"string"},"smtp_port":{"type":"string"},"smtp_enabled":{"type":"boolean"},"smtp_domain":{"type":"string"},"smtp_enable_ssl_tls":{"type":"string"},"smtp_enable_starttls_auto":{"type":"string"},"smtp_openssl_verify_mode":{"type":"string","enum":["none","peer","client_once","fail_if_no_peer_cert"],"description":"OpenSSL peer-certificate verification mode for the email channel's SMTP connection."},"smtp_authentication":{"type":"string"},"secret":{"type":"string"},"webhook_url":{"type":"string"},"inbox_identifier":{"type":"string"},"additional_attributes":{"type":"object","additionalProperties":true,"description":"Channel- and source-specific metadata for this record (e.g. browser info, referer, social profile identifiers). The key set depends on the originating channel."},"provider":{"type":"string","enum":["default","whatsapp_cloud","whatsapp_web","google","microsoft"],"description":"Messaging provider backing the inbox channel (whatsapp_web is the WazMeow gateway; email uses google/microsoft; default otherwise)."},"bot_name":{"type":"string"},"message_templates":{"type":"boolean"},"provider_config":{"type":"string"},"business_management_token_configured":{"type":"boolean"},"hybrid_pair":{"$ref":"#/components/schemas/inbox/properties/hybrid_pair"},"whatsapp_web_session_state":{"$ref":"#/components/schemas/inbox/properties/whatsapp_web_session_state"},"hybrid_hidden":{"type":"string"},"logical_inbox_id":{"type":"integer"},"whatsapp_pending_phone":{"type":"object","nullable":true,"description":"Spec 052 — set only when a WhatsApp phone-number rewrite was REFUSED because a non-sibling channel already holds the number, leaving the inbox on its `pending:` placeholder and inert. `null` in every normal case (including a routine, not-yet-scanned pairing).","additionalProperties":false,"properties":{"awaiting_pair":{"type":"boolean","description":"True while the inbox is still on its `pending:\u003cuuid\u003e` placeholder number."},"phone":{"type":"string","description":"The E.164 number the rewrite tried to claim."},"reason":{"type":"string","enum":["same_account_same_provider","other_account"],"description":"Why the rewrite was refused. `other_account` never carries any identifying detail about the other account."},"sibling_inbox_id":{"type":"integer","nullable":true,"description":"Colliding inbox in the SAME account; absent when the collision is cross-account."},"source":{"type":"string","enum":["pair_success","qr_pump"],"description":"Which path attempted the rewrite."},"at":{"type":"string","format":"date-time","description":"When the refusal was recorded."}}},"whatsapp_sibling_notice":{"type":"string"},"whatsapp_web_contact_request":{"type":"string","enum":["supported","unsupported","unknown"],"description":"WhatsApp Web inboxes only — whether this inbox's WazMeow gateway serves the request that asks a customer to share their phone number. `supported` and `unsupported` come from a no-effect probe of the gateway route, refreshed at most hourly and immediately when a real send finds the route missing; `unknown` means not probed yet or the gateway could not be reached. Only `supported` turns the feature on; with `unknown` the request is refused before any gateway call while the probe runs."},"voice_enabled":{"type":"boolean"},"inbound_calls_enabled":{"type":"boolean"},"voice_configured":{"type":"boolean"},"voice_call_webhook_url":{"type":"string"},"voice_status_webhook_url":{"type":"string"}}},"logo":{"type":"string"},"meta":{"type":"object","properties":{"all_articles_count":{"type":"integer"},"archived_articles_count":{"type":"integer"},"published_count":{"type":"integer"},"draft_articles_count":{"type":"integer"},"mine_articles_count":{"type":"integer"},"categories_count":{"type":"integer"},"default_locale":{"type":"string"}}},"ssl_settings":{"type":"object","properties":{"status":{"type":"string"},"verification_errors":{"type":"string"}}}}},"views":{"type":"string"},"author":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":["integer","null"]},"account_user_id":{"type":["integer","null"]},"availability_status":{"type":"string","enum":["online","offline","busy"],"description":"Realtime availability. Contacts report online/offline (presence-based); agents/users additionally report busy (their configured availability)."},"auto_offline":{"type":"boolean"},"confirmed":{"type":"boolean"},"email":{"type":"string","format":"email"},"provider":{"type":"string","enum":["email","google_oauth2","saml"],"description":"Authentication provider the user signed up through."},"available_name":{"type":"string"},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"name":{"type":"string"},"role":{"type":"string","enum":["agent","administrator"],"description":"The user's role within the account."},"outbound_agent_name_header_policy":{"type":["string","null"]},"thumbnail":{"type":"string"},"custom_role_id":{"type":["integer","null"]},"access_role_id":{"type":["integer","null"]}}}}}}}}}},"example":{"payload":{"id":1,"slug":"sample-slug","title":"Sample title","content":"Sample content text.","description":"A short description.","status":"draft","visibility":"public","draft_title":"sample draft title","draft_content":"sample draft content","position":1,"account_id":1,"updated_at":1,"meta":"sample meta","category":{"id":1,"name":"Sample Name","slug":"sample-slug","locale":"en","icon":"sample icon","icon_color":"#1F93FF"},"views":"sample views","author":{"id":1,"account_id":1,"account_user_id":1,"availability_status":"online","auto_offline":true,"confirmed":true,"email":"agent@example.com","provider":"email","available_name":"sample available name","custom_attributes":{},"name":"Sample Name","role":"agent","outbound_agent_name_header_policy":"sample outbound agent name header policy","thumbnail":"sample thumbnail","custom_role_id":1,"access_role_id":1},"associated_articles":[{"id":1,"category_id":1,"title":"Sample title","content":"Sample content text.","description":"A short description.","status":"draft","visibility":"public","account_id":1,"portal":{"id":1,"color":"#1F93FF","custom_domain":"sample custom domain","header_text":"sample header text","homepage_link":"https://example.com/resource","name":"Sample Name","page_title":"sample page title","slug":"sample-slug","archived":true,"account_id":1,"config":[{"code":"sample code","articles_count":5,"categories_count":5,"draft":true}],"inbox":{"id":1,"avatar_url":"https://example.com/resource","channel_id":1,"name":"Sample Name","channel_type":"Channel::Api","greeting_enabled":true,"greeting_message":"sample greeting message","working_hours_enabled":true,"enable_email_collect":"agent@example.com","csat_survey_enabled":true,"csat_config":"sample csat config","enable_auto_assignment":"sample enable auto assignment","auto_assignment_config":"sample auto assignment config","out_of_office_message":"sample out of office message","working_hours":"sample working hours","timezone":"America/Sao_Paulo","callback_webhook_url":"https://example.com/resource","allow_messages_after_resolved":"sample allow messages after resolved","lock_to_single_conversation":"sample lock to single conversation","audio_transcription_enabled":true,"preserve_deleted_messages":"sample preserve deleted messages","allow_message_deletion":"sample allow message deletion","capture_view_once":"sample capture view once","sender_name_type":"friendly","auto_resolve_config":{"mode":"custom","after":60,"message":null,"label":null,"allow_waiting":false},"outbound_agent_name_header_policy":"sample outbound agent name header policy","agent_bot_working_hours_mode":"always","business_name":"sample business name","responder_policy":"sample responder policy","help_center":{"name":"Sample Name","slug":"sample-slug"},"tweets_enabled":true,"allowed_domains":"sample allowed domains","widget_color":"#1F93FF","website_url":"https://example.com/resource","hmac_mandatory":"sample hmac mandatory","welcome_title":"sample welcome title","welcome_tagline":"sample welcome tagline","web_widget_script":"sample web widget script","website_token":"sample-token","selected_feature_flags":"sample selected feature flags","reply_time":"2026-01-15T10:30:00.000Z","hmac_token":"sample-token","pre_chat_form_enabled":true,"pre_chat_form_options":"sample pre chat form options","continuity_via_email":"agent@example.com","page_id":1,"reauthorization_required":"sample reauthorization required","instagram_id":1,"messaging_service_sid":"sample messaging service sid","phone_number":"+5511999998888","medium":"sample medium","bandwidth_callback_state":"active","bandwidth_api_migration_state":"oauth2_configured","bandwidth_legacy_basic_deprecated":true,"content_templates":"sample content templates","auth_token":"sample-token","account_sid":"sample account sid","api_key_sid":"sample api key sid","twilio_credential_state":"ready","api_key_configured":true,"email":"agent@example.com","auth_method":"sample auth method","forwarding_enabled":true,"forward_to_email":"agent@example.com","branded_email_layout":"agent@example.com","imap_login":"sample imap login","imap_password":"sample imap password","imap_address":"sample imap address","imap_port":"sample imap port","imap_enabled":true,"imap_enable_ssl":"sample imap enable ssl","imap_authentication":"sample imap authentication","smtp_login":"sample smtp login","smtp_password":"sample smtp password","smtp_address":"sample smtp address","smtp_port":"sample smtp port","smtp_enabled":true,"smtp_domain":"sample smtp domain","smtp_enable_ssl_tls":"sample smtp enable ssl tls","smtp_enable_starttls_auto":"sample smtp enable starttls auto","smtp_openssl_verify_mode":"none","smtp_authentication":"sample smtp authentication","secret":"sample-token","webhook_url":"https://example.com/resource","inbox_identifier":"sample inbox identifier","additional_attributes":{},"provider":"default","bot_name":"sample bot name","message_templates":true,"provider_config":"sample provider config","business_management_token_configured":true,"hybrid_pair":{"paired":true,"id":4,"role":"cloud","sibling_inbox_id":18,"canonical_phone":"+5521900000000","primary":"cloud","inbound_authority":"cloud","unified_inbox":true,"unified_state":{"state":"complete","scanned":42,"frozen":40,"reconciled_count":2,"completed_at":"2026-10-03T12:00:00.000Z","blocked_conversations":[]},"routing":{"outbound_default":"cloud","out_of_window":"web","fallback":true,"manual_override":true,"weighted":{"mode":"weighted","web_percent":30,"version":2}},"web_channel_id":12,"web_inbox_id":18,"calling_provider":"whatsapp_web","web_voice_enabled":true,"web_inbound_calls_enabled":true,"web_call_config_sync":{"state":"pending","checked_at":"2026-10-03T12:00:00.000Z"},"web_video_calls_enabled":false,"web_group_calls_enabled":false,"web_reauthorization_required":false,"web_session_state":{"state":"connected","fresh":true,"observed_at":"2026-10-03T12:00:00.000Z","disconnected_since":null},"web_allow_message_deletion":true},"whatsapp_web_session_state":{"state":"connected","fresh":true,"observed_at":"2026-01-15T10:30:00.000Z","disconnected_since":null},"hybrid_hidden":"sample hybrid hidden","logical_inbox_id":1,"whatsapp_pending_phone":{"awaiting_pair":true,"phone":"+5511999998888","reason":"same_account_same_provider","sibling_inbox_id":1,"source":"pair_success","at":"2026-01-15T10:30:00.000Z"},"whatsapp_sibling_notice":"sample whatsapp sibling notice","whatsapp_web_contact_request":"supported","voice_enabled":true,"inbound_calls_enabled":true,"voice_configured":true,"voice_call_webhook_url":"https://example.com/resource","voice_status_webhook_url":"https://example.com/resource"},"logo":"sample logo","meta":{"all_articles_count":5,"archived_articles_count":5,"published_count":5,"draft_articles_count":5,"mine_articles_count":5,"categories_count":5,"default_locale":"sample default locale"},"ssl_settings":{"status":"active","verification_errors":"sample verification errors"}},"views":"sample views","author":{"id":1,"account_id":1,"account_user_id":1,"availability_status":"online","auto_offline":true,"confirmed":true,"email":"agent@example.com","provider":"email","available_name":"sample available name","custom_attributes":{},"name":"Sample Name","role":"agent","outbound_agent_name_header_policy":"sample outbound agent name header policy","thumbnail":"sample thumbnail","custom_role_id":1,"access_role_id":1}}]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"portal_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/portals/{portal_id}/articles/{id}":{"get":{"tags":["Help Center"],"operationId":"auto_get_api_v1_accounts_account_id_portals_portal_id_articles_id","summary":"Get articles","description":"Returns the article identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"slug":{"type":"string"},"title":{"type":"string"},"content":{"type":"string"},"description":{"type":"string"},"status":{"type":"string","enum":["draft","published","archived"]},"visibility":{"type":"string","enum":["public","operator"]},"draft_title":{"type":"string"},"draft_content":{"type":"string"},"position":{"type":"integer"},"account_id":{"type":"integer"},"updated_at":{"type":"integer"},"meta":{"type":"string"},"category":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":["string","null"]},"slug":{"type":["string","null"]},"locale":{"type":["string","null"]},"icon":{"type":["string","null"]},"icon_color":{"type":["string","null"]}}},"views":{"type":"string"},"author":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":["integer","null"]},"account_user_id":{"type":["integer","null"]},"availability_status":{"type":"string","enum":["online","offline","busy"],"description":"Realtime availability. Contacts report online/offline (presence-based); agents/users additionally report busy (their configured availability)."},"auto_offline":{"type":"boolean"},"confirmed":{"type":"boolean"},"email":{"type":"string","format":"email"},"provider":{"type":"string","enum":["email","google_oauth2","saml"],"description":"Authentication provider the user signed up through."},"available_name":{"type":"string"},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"name":{"type":"string"},"role":{"type":"string","enum":["agent","administrator"],"description":"The user's role within the account."},"outbound_agent_name_header_policy":{"type":["string","null"]},"thumbnail":{"type":"string"},"custom_role_id":{"type":["integer","null"]},"access_role_id":{"type":["integer","null"]}}},"associated_articles":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"category_id":{"type":"integer"},"title":{"type":"string"},"content":{"type":"string"},"description":{"type":"string"},"status":{"type":"string","enum":["draft","published","archived"],"description":"Publication status of the help-center article."},"visibility":{"type":"string","enum":["public","operator"]},"account_id":{"type":"integer"},"portal":{"type":"object","properties":{"id":{"type":"integer"},"color":{"type":"string"},"custom_domain":{"type":"string"},"header_text":{"type":"string"},"homepage_link":{"type":"string"},"name":{"type":"string"},"page_title":{"type":"string"},"slug":{"type":"string"},"archived":{"type":"boolean"},"account_id":{"type":"integer"},"config":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"articles_count":{"type":"integer"},"categories_count":{"type":"integer"},"draft":{"type":"boolean"}}}},"inbox":{"type":"object","properties":{"id":{"type":"integer"},"avatar_url":{"type":"string"},"channel_id":{"type":"integer"},"name":{"type":"string"},"channel_type":{"type":"string","enum":["Channel::Api","Channel::Email","Channel::FacebookPage","Channel::Instagram","Channel::Line","Channel::Sms","Channel::Telegram","Channel::Tiktok","Channel::TwilioSms","Channel::TwitterProfile","Channel::WebWidget","Channel::Whatsapp"],"description":"The inbox channel class — identifies which messaging channel backs the inbox."},"greeting_enabled":{"type":"boolean"},"greeting_message":{"type":"string"},"working_hours_enabled":{"type":"boolean"},"enable_email_collect":{"type":"string"},"csat_survey_enabled":{"type":"boolean"},"csat_config":{"type":"string"},"enable_auto_assignment":{"type":"string"},"auto_assignment_config":{"type":"string"},"out_of_office_message":{"type":"string"},"working_hours":{"type":"string"},"timezone":{"type":"string","description":"IANA timezone identifier (e.g. \"America/Sao_Paulo\", \"UTC\"). Rails timezone names are also accepted on input; an unrecognized value is ignored in favor of the next fallback.","example":"America/Sao_Paulo"},"callback_webhook_url":{"type":"string"},"allow_messages_after_resolved":{"type":"string"},"lock_to_single_conversation":{"type":"string"},"audio_transcription_enabled":{"type":"boolean"},"preserve_deleted_messages":{"type":"string"},"allow_message_deletion":{"type":"string"},"capture_view_once":{"type":"string"},"sender_name_type":{"type":"string","enum":["friendly","professional"]},"auto_resolve_config":{"type":"object","additionalProperties":true,"oneOf":[{"type":"object","maxProperties":0,"additionalProperties":true,"description":"Empty means inherit the account rule."},{"type":"object","additionalProperties":false,"required":["mode"],"properties":{"mode":{"type":"string","enum":["disabled"],"description":"Disable automatic resolution for this inbox."}},"description":"The disabled rule contains only its mode."},{"type":"object","additionalProperties":false,"required":["mode","after","message","label","allow_waiting"],"properties":{"mode":{"type":"string","enum":["custom"],"description":"Use this complete inbox rule."},"after":{"type":"integer","minimum":10,"maximum":1439856,"description":"Inactivity in minutes; required for custom mode."},"message":{"type":["string","null"],"maxLength":10000,"description":"Optional message; blank normalizes to null."},"label":{"type":["string","null"],"description":"An existing account label title, or null."},"allow_waiting":{"type":"boolean","description":"Whether waiting conversations are included."}},"description":"Complete normalized custom rule."}],"description":"Normalized JSON rule from valid model writes: empty, disabled, or complete custom configuration.","example":{"mode":"custom","after":60,"message":null,"label":null,"allow_waiting":false}},"outbound_agent_name_header_policy":{"type":"string"},"agent_bot_working_hours_mode":{"type":"string","enum":["always","inside_business_hours","outside_business_hours"]},"business_name":{"type":"string"},"responder_policy":{"type":"string"},"help_center":{"type":"object","properties":{"name":{"type":"string"},"slug":{"type":"string"}}},"tweets_enabled":{"type":"boolean"},"allowed_domains":{"type":"string"},"widget_color":{"type":"string"},"website_url":{"type":"string"},"hmac_mandatory":{"type":"string"},"welcome_title":{"type":"string"},"welcome_tagline":{"type":"string"},"web_widget_script":{"type":"string"},"website_token":{"type":"string"},"selected_feature_flags":{"type":"string"},"reply_time":{"type":"string","format":"date-time"},"hmac_token":{"type":"string"},"pre_chat_form_enabled":{"type":"boolean"},"pre_chat_form_options":{"type":"string"},"continuity_via_email":{"type":"string","format":"email"},"page_id":{"type":"integer"},"reauthorization_required":{"type":"string"},"instagram_id":{"type":"integer"},"messaging_service_sid":{"type":"string"},"phone_number":{"type":"string"},"medium":{"type":"string"},"bandwidth_callback_state":{"type":"string","enum":["active","reconnect_required","reconciling","reconciliation_required","encryption_required"]},"bandwidth_api_migration_state":{"type":"string","enum":["oauth2_configured","oauth2_required","configuration_required"]},"bandwidth_legacy_basic_deprecated":{"type":"boolean"},"content_templates":{"type":"string"},"auth_token":{"type":"string"},"account_sid":{"type":"string"},"api_key_sid":{"type":"string"},"twilio_credential_state":{"type":"string","enum":["ready","pending","failed","dead_letter","account_auth_token_required","reconciliation_required"],"description":"Durable Twilio credential lifecycle derived from Channel::TwilioSms. A reconciliation-required state is fail-closed until the provider outcome has been verified."},"api_key_configured":{"type":"boolean"},"email":{"type":"string","format":"email"},"auth_method":{"type":"string"},"forwarding_enabled":{"type":"boolean"},"forward_to_email":{"type":"string","format":"email"},"branded_email_layout":{"type":"string"},"imap_login":{"type":"string"},"imap_password":{"type":"string"},"imap_address":{"type":"string"},"imap_port":{"type":"string"},"imap_enabled":{"type":"boolean"},"imap_enable_ssl":{"type":"string"},"imap_authentication":{"type":"string"},"smtp_login":{"type":"string"},"smtp_password":{"type":"string"},"smtp_address":{"type":"string"},"smtp_port":{"type":"string"},"smtp_enabled":{"type":"boolean"},"smtp_domain":{"type":"string"},"smtp_enable_ssl_tls":{"type":"string"},"smtp_enable_starttls_auto":{"type":"string"},"smtp_openssl_verify_mode":{"type":"string","enum":["none","peer","client_once","fail_if_no_peer_cert"],"description":"OpenSSL peer-certificate verification mode for the email channel's SMTP connection."},"smtp_authentication":{"type":"string"},"secret":{"type":"string"},"webhook_url":{"type":"string"},"inbox_identifier":{"type":"string"},"additional_attributes":{"type":"object","additionalProperties":true,"description":"Channel- and source-specific metadata for this record (e.g. browser info, referer, social profile identifiers). The key set depends on the originating channel."},"provider":{"type":"string","enum":["default","whatsapp_cloud","whatsapp_web","google","microsoft"],"description":"Messaging provider backing the inbox channel (whatsapp_web is the WazMeow gateway; email uses google/microsoft; default otherwise)."},"bot_name":{"type":"string"},"message_templates":{"type":"boolean"},"provider_config":{"type":"string"},"business_management_token_configured":{"type":"boolean"},"hybrid_pair":{"$ref":"#/components/schemas/inbox/properties/hybrid_pair"},"whatsapp_web_session_state":{"$ref":"#/components/schemas/inbox/properties/whatsapp_web_session_state"},"hybrid_hidden":{"type":"string"},"logical_inbox_id":{"type":"integer"},"whatsapp_pending_phone":{"type":"object","nullable":true,"description":"Spec 052 — set only when a WhatsApp phone-number rewrite was REFUSED because a non-sibling channel already holds the number, leaving the inbox on its `pending:` placeholder and inert. `null` in every normal case (including a routine, not-yet-scanned pairing).","additionalProperties":false,"properties":{"awaiting_pair":{"type":"boolean","description":"True while the inbox is still on its `pending:\u003cuuid\u003e` placeholder number."},"phone":{"type":"string","description":"The E.164 number the rewrite tried to claim."},"reason":{"type":"string","enum":["same_account_same_provider","other_account"],"description":"Why the rewrite was refused. `other_account` never carries any identifying detail about the other account."},"sibling_inbox_id":{"type":"integer","nullable":true,"description":"Colliding inbox in the SAME account; absent when the collision is cross-account."},"source":{"type":"string","enum":["pair_success","qr_pump"],"description":"Which path attempted the rewrite."},"at":{"type":"string","format":"date-time","description":"When the refusal was recorded."}}},"whatsapp_sibling_notice":{"type":"string"},"whatsapp_web_contact_request":{"type":"string","enum":["supported","unsupported","unknown"],"description":"WhatsApp Web inboxes only — whether this inbox's WazMeow gateway serves the request that asks a customer to share their phone number. `supported` and `unsupported` come from a no-effect probe of the gateway route, refreshed at most hourly and immediately when a real send finds the route missing; `unknown` means not probed yet or the gateway could not be reached. Only `supported` turns the feature on; with `unknown` the request is refused before any gateway call while the probe runs."},"voice_enabled":{"type":"boolean"},"inbound_calls_enabled":{"type":"boolean"},"voice_configured":{"type":"boolean"},"voice_call_webhook_url":{"type":"string"},"voice_status_webhook_url":{"type":"string"}}},"logo":{"type":"string"},"meta":{"type":"object","properties":{"all_articles_count":{"type":"integer"},"archived_articles_count":{"type":"integer"},"published_count":{"type":"integer"},"draft_articles_count":{"type":"integer"},"mine_articles_count":{"type":"integer"},"categories_count":{"type":"integer"},"default_locale":{"type":"string"}}},"ssl_settings":{"type":"object","properties":{"status":{"type":"string"},"verification_errors":{"type":"string"}}}}},"views":{"type":"string"},"author":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":["integer","null"]},"account_user_id":{"type":["integer","null"]},"availability_status":{"type":"string","enum":["online","offline","busy"],"description":"Realtime availability. Contacts report online/offline (presence-based); agents/users additionally report busy (their configured availability)."},"auto_offline":{"type":"boolean"},"confirmed":{"type":"boolean"},"email":{"type":"string","format":"email"},"provider":{"type":"string","enum":["email","google_oauth2","saml"],"description":"Authentication provider the user signed up through."},"available_name":{"type":"string"},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"name":{"type":"string"},"role":{"type":"string","enum":["agent","administrator"],"description":"The user's role within the account."},"outbound_agent_name_header_policy":{"type":["string","null"]},"thumbnail":{"type":"string"},"custom_role_id":{"type":["integer","null"]},"access_role_id":{"type":["integer","null"]}}}}}}}}}},"example":{"payload":{"id":1,"slug":"sample-slug","title":"Sample title","content":"Sample content text.","description":"A short description.","status":"draft","visibility":"public","draft_title":"sample draft title","draft_content":"sample draft content","position":1,"account_id":1,"updated_at":1,"meta":"sample meta","category":{"id":1,"name":"Sample Name","slug":"sample-slug","locale":"en","icon":"sample icon","icon_color":"#1F93FF"},"views":"sample views","author":{"id":1,"account_id":1,"account_user_id":1,"availability_status":"online","auto_offline":true,"confirmed":true,"email":"agent@example.com","provider":"email","available_name":"sample available name","custom_attributes":{},"name":"Sample Name","role":"agent","outbound_agent_name_header_policy":"sample outbound agent name header policy","thumbnail":"sample thumbnail","custom_role_id":1,"access_role_id":1},"associated_articles":[{"id":1,"category_id":1,"title":"Sample title","content":"Sample content text.","description":"A short description.","status":"draft","visibility":"public","account_id":1,"portal":{"id":1,"color":"#1F93FF","custom_domain":"sample custom domain","header_text":"sample header text","homepage_link":"https://example.com/resource","name":"Sample Name","page_title":"sample page title","slug":"sample-slug","archived":true,"account_id":1,"config":[{"code":"sample code","articles_count":5,"categories_count":5,"draft":true}],"inbox":{"id":1,"avatar_url":"https://example.com/resource","channel_id":1,"name":"Sample Name","channel_type":"Channel::Api","greeting_enabled":true,"greeting_message":"sample greeting message","working_hours_enabled":true,"enable_email_collect":"agent@example.com","csat_survey_enabled":true,"csat_config":"sample csat config","enable_auto_assignment":"sample enable auto assignment","auto_assignment_config":"sample auto assignment config","out_of_office_message":"sample out of office message","working_hours":"sample working hours","timezone":"America/Sao_Paulo","callback_webhook_url":"https://example.com/resource","allow_messages_after_resolved":"sample allow messages after resolved","lock_to_single_conversation":"sample lock to single conversation","audio_transcription_enabled":true,"preserve_deleted_messages":"sample preserve deleted messages","allow_message_deletion":"sample allow message deletion","capture_view_once":"sample capture view once","sender_name_type":"friendly","auto_resolve_config":{"mode":"custom","after":60,"message":null,"label":null,"allow_waiting":false},"outbound_agent_name_header_policy":"sample outbound agent name header policy","agent_bot_working_hours_mode":"always","business_name":"sample business name","responder_policy":"sample responder policy","help_center":{"name":"Sample Name","slug":"sample-slug"},"tweets_enabled":true,"allowed_domains":"sample allowed domains","widget_color":"#1F93FF","website_url":"https://example.com/resource","hmac_mandatory":"sample hmac mandatory","welcome_title":"sample welcome title","welcome_tagline":"sample welcome tagline","web_widget_script":"sample web widget script","website_token":"sample-token","selected_feature_flags":"sample selected feature flags","reply_time":"2026-01-15T10:30:00.000Z","hmac_token":"sample-token","pre_chat_form_enabled":true,"pre_chat_form_options":"sample pre chat form options","continuity_via_email":"agent@example.com","page_id":1,"reauthorization_required":"sample reauthorization required","instagram_id":1,"messaging_service_sid":"sample messaging service sid","phone_number":"+5511999998888","medium":"sample medium","bandwidth_callback_state":"active","bandwidth_api_migration_state":"oauth2_configured","bandwidth_legacy_basic_deprecated":true,"content_templates":"sample content templates","auth_token":"sample-token","account_sid":"sample account sid","api_key_sid":"sample api key sid","twilio_credential_state":"ready","api_key_configured":true,"email":"agent@example.com","auth_method":"sample auth method","forwarding_enabled":true,"forward_to_email":"agent@example.com","branded_email_layout":"agent@example.com","imap_login":"sample imap login","imap_password":"sample imap password","imap_address":"sample imap address","imap_port":"sample imap port","imap_enabled":true,"imap_enable_ssl":"sample imap enable ssl","imap_authentication":"sample imap authentication","smtp_login":"sample smtp login","smtp_password":"sample smtp password","smtp_address":"sample smtp address","smtp_port":"sample smtp port","smtp_enabled":true,"smtp_domain":"sample smtp domain","smtp_enable_ssl_tls":"sample smtp enable ssl tls","smtp_enable_starttls_auto":"sample smtp enable starttls auto","smtp_openssl_verify_mode":"none","smtp_authentication":"sample smtp authentication","secret":"sample-token","webhook_url":"https://example.com/resource","inbox_identifier":"sample inbox identifier","additional_attributes":{},"provider":"default","bot_name":"sample bot name","message_templates":true,"provider_config":"sample provider config","business_management_token_configured":true,"hybrid_pair":{"paired":true,"id":4,"role":"cloud","sibling_inbox_id":18,"canonical_phone":"+5521900000000","primary":"cloud","inbound_authority":"cloud","unified_inbox":true,"unified_state":{"state":"complete","scanned":42,"frozen":40,"reconciled_count":2,"completed_at":"2026-10-03T12:00:00.000Z","blocked_conversations":[]},"routing":{"outbound_default":"cloud","out_of_window":"web","fallback":true,"manual_override":true,"weighted":{"mode":"weighted","web_percent":30,"version":2}},"web_channel_id":12,"web_inbox_id":18,"calling_provider":"whatsapp_web","web_voice_enabled":true,"web_inbound_calls_enabled":true,"web_call_config_sync":{"state":"pending","checked_at":"2026-10-03T12:00:00.000Z"},"web_video_calls_enabled":false,"web_group_calls_enabled":false,"web_reauthorization_required":false,"web_session_state":{"state":"connected","fresh":true,"observed_at":"2026-10-03T12:00:00.000Z","disconnected_since":null},"web_allow_message_deletion":true},"whatsapp_web_session_state":{"state":"connected","fresh":true,"observed_at":"2026-01-15T10:30:00.000Z","disconnected_since":null},"hybrid_hidden":"sample hybrid hidden","logical_inbox_id":1,"whatsapp_pending_phone":{"awaiting_pair":true,"phone":"+5511999998888","reason":"same_account_same_provider","sibling_inbox_id":1,"source":"pair_success","at":"2026-01-15T10:30:00.000Z"},"whatsapp_sibling_notice":"sample whatsapp sibling notice","whatsapp_web_contact_request":"supported","voice_enabled":true,"inbound_calls_enabled":true,"voice_configured":true,"voice_call_webhook_url":"https://example.com/resource","voice_status_webhook_url":"https://example.com/resource"},"logo":"sample logo","meta":{"all_articles_count":5,"archived_articles_count":5,"published_count":5,"draft_articles_count":5,"mine_articles_count":5,"categories_count":5,"default_locale":"sample default locale"},"ssl_settings":{"status":"active","verification_errors":"sample verification errors"}},"views":"sample views","author":{"id":1,"account_id":1,"account_user_id":1,"availability_status":"online","auto_offline":true,"confirmed":true,"email":"agent@example.com","provider":"email","available_name":"sample available name","custom_attributes":{},"name":"Sample Name","role":"agent","outbound_agent_name_header_policy":"sample outbound agent name header policy","thumbnail":"sample thumbnail","custom_role_id":1,"access_role_id":1}}]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"portal_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]},"patch":{"tags":["Help Center"],"operationId":"auto_patch_api_v1_accounts_account_id_portals_portal_id_articles_id","summary":"Update articles","description":"Updates the article identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Article updated","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer","example":101},"slug":{"type":"string","example":"how-to-connect-whatsapp"},"title":{"type":"string","example":"How to connect WhatsApp"},"content":{"type":"string","example":"## Overview\nStep-by-step guide..."},"description":{"type":"string","example":"Connect your WhatsApp number"},"status":{"type":"string","enum":["draft","published","archived"],"example":"published"},"position":{"type":"integer","example":1},"account_id":{"type":"integer","example":1},"updated_at":{"type":"integer","description":"Unix epoch seconds","example":1737024600},"meta":{"type":"object","properties":{"title":{"type":"string","example":"How to connect WhatsApp"},"description":{"type":"string","example":"Connect your WhatsApp number"},"tags":{"type":"array","items":{"type":"string"},"example":["whatsapp"]}}},"category":{"type":"object","properties":{"id":{"type":["integer","null"],"example":42},"name":{"type":["string","null"],"example":"Getting Started"},"slug":{"type":["string","null"],"example":"getting-started"},"locale":{"type":["string","null"],"example":"en"},"icon":{"type":["string","null"],"example":"rocket"},"icon_color":{"type":["string","null"],"example":"#1F93FF"}}},"views":{"type":"integer","example":128},"author":{"type":"object","properties":{"id":{"type":"integer","example":7},"name":{"type":"string","example":"Jane Agent"},"email":{"type":"string","example":"jane@example.com"},"available_name":{"type":"string","example":"Jane"},"availability_status":{"type":"string","example":"online","enum":["online","offline","busy"],"description":"Realtime availability. Contacts report online/offline (presence-based); agents/users additionally report busy (their configured availability)."},"thumbnail":{"type":"string","example":"https://cdn.example.com/avatars/7.png"},"role":{"type":"string","example":"administrator","enum":["administrator","agent"],"description":"The user's role within the account."}}},"associated_articles":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","example":102},"category_id":{"type":"integer","example":55},"title":{"type":"string","example":"Cómo conectar WhatsApp"},"status":{"type":"string","example":"published","enum":["draft","published","archived"],"description":"Publication status of the help-center article."},"account_id":{"type":"integer","example":1},"views":{"type":"integer","example":3}}}}}}}},"example":{"payload":{"id":101,"slug":"how-to-connect-whatsapp","title":"How to connect WhatsApp","content":"## Overview\nStep-by-step guide...","description":"Connect your WhatsApp number","status":"published","position":1,"account_id":1,"updated_at":1737024600,"meta":{"title":"How to connect WhatsApp","description":"Connect your WhatsApp number","tags":["whatsapp"]},"category":{"id":42,"name":"Getting Started","slug":"getting-started","locale":"en","icon":"rocket","icon_color":"#1F93FF"},"views":128,"author":{"id":7,"name":"Jane Agent","email":"jane@example.com","available_name":"Jane","availability_status":"online","thumbnail":"https://cdn.example.com/avatars/7.png","role":"administrator"},"associated_articles":[{"id":102,"category_id":55,"title":"Cómo conectar WhatsApp","status":"published","account_id":1,"views":3}]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"portal_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"article":{"type":"object","properties":{"title":{"type":"string"},"slug":{"type":"string"},"position":{"type":"integer"},"content":{"type":"string"},"description":{"type":"string"},"category_id":{"type":"integer"},"author_id":{"type":"integer"},"associated_article_id":{"type":"integer"},"status":{"type":"string","enum":["draft","published","archived"]},"locale":{"type":"string","enum":["en","pt_BR","es"]},"draft_title":{"type":"string"},"draft_content":{"type":"string"},"meta":{"type":"object","additionalProperties":true,"description":"Free-form object."}}}},"required":["article"]},"example":{"article":{"title":"Sample title","slug":"sample-slug","position":1,"content":"Sample content text.","description":"A short description.","category_id":1,"author_id":1,"associated_article_id":1,"status":"draft","locale":"en","draft_title":"sample draft title","draft_content":"sample draft content","meta":{}}}}}}},"put":{"tags":["Help Center"],"operationId":"auto_put_api_v1_accounts_account_id_portals_portal_id_articles_id","summary":"Update articles","description":"Updates the article identified by the path parameters with the submitted attributes. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Article updated","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer","example":101},"slug":{"type":"string","example":"how-to-connect-whatsapp"},"title":{"type":"string","example":"How to connect WhatsApp"},"content":{"type":"string","example":"## Overview\nStep-by-step guide..."},"description":{"type":"string","example":"Connect your WhatsApp number"},"status":{"type":"string","enum":["draft","published","archived"],"example":"published"},"position":{"type":"integer","example":1},"account_id":{"type":"integer","example":1},"updated_at":{"type":"integer","description":"Unix epoch seconds","example":1737024600},"meta":{"type":"object","properties":{"title":{"type":"string","example":"How to connect WhatsApp"},"description":{"type":"string","example":"Connect your WhatsApp number"},"tags":{"type":"array","items":{"type":"string"},"example":["whatsapp"]}}},"category":{"type":"object","properties":{"id":{"type":["integer","null"],"example":42},"name":{"type":["string","null"],"example":"Getting Started"},"slug":{"type":["string","null"],"example":"getting-started"},"locale":{"type":["string","null"],"example":"en"},"icon":{"type":["string","null"],"example":"rocket"},"icon_color":{"type":["string","null"],"example":"#1F93FF"}}},"views":{"type":"integer","example":128},"author":{"type":"object","properties":{"id":{"type":"integer","example":7},"name":{"type":"string","example":"Jane Agent"},"email":{"type":"string","example":"jane@example.com"},"available_name":{"type":"string","example":"Jane"},"availability_status":{"type":"string","example":"online","enum":["online","offline","busy"],"description":"Realtime availability. Contacts report online/offline (presence-based); agents/users additionally report busy (their configured availability)."},"thumbnail":{"type":"string","example":"https://cdn.example.com/avatars/7.png"},"role":{"type":"string","example":"administrator","enum":["administrator","agent"],"description":"The user's role within the account."}}},"associated_articles":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","example":102},"category_id":{"type":"integer","example":55},"title":{"type":"string","example":"Cómo conectar WhatsApp"},"status":{"type":"string","example":"published","enum":["draft","published","archived"],"description":"Publication status of the help-center article."},"account_id":{"type":"integer","example":1},"views":{"type":"integer","example":3}}}}}}}},"example":{"payload":{"id":101,"slug":"how-to-connect-whatsapp","title":"How to connect WhatsApp","content":"## Overview\nStep-by-step guide...","description":"Connect your WhatsApp number","status":"published","position":1,"account_id":1,"updated_at":1737024600,"meta":{"title":"How to connect WhatsApp","description":"Connect your WhatsApp number","tags":["whatsapp"]},"category":{"id":42,"name":"Getting Started","slug":"getting-started","locale":"en","icon":"rocket","icon_color":"#1F93FF"},"views":128,"author":{"id":7,"name":"Jane Agent","email":"jane@example.com","available_name":"Jane","availability_status":"online","thumbnail":"https://cdn.example.com/avatars/7.png","role":"administrator"},"associated_articles":[{"id":102,"category_id":55,"title":"Cómo conectar WhatsApp","status":"published","account_id":1,"views":3}]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"portal_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"article":{"type":"object","properties":{"title":{"type":"string"},"slug":{"type":"string"},"position":{"type":"integer"},"content":{"type":"string"},"description":{"type":"string"},"category_id":{"type":"integer"},"author_id":{"type":"integer"},"associated_article_id":{"type":"integer"},"status":{"type":"string","enum":["draft","published","archived"]},"locale":{"type":"string","enum":["en","pt_BR","es"]},"draft_title":{"type":"string"},"draft_content":{"type":"string"},"meta":{"type":"object","additionalProperties":true,"description":"Free-form object."}}}},"required":["article"]},"example":{"article":{"title":"Sample title","slug":"sample-slug","position":1,"content":"Sample content text.","description":"A short description.","category_id":1,"author_id":1,"associated_article_id":1,"status":"draft","locale":"en","draft_title":"sample draft title","draft_content":"sample draft content","meta":{}}}}}}},"delete":{"tags":["Help Center"],"operationId":"auto_delete_api_v1_accounts_account_id_portals_portal_id_articles_id","summary":"Delete articles","description":"Deletes the article identified by the path parameters. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Success (no content)"},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"portal_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/upload":{"post":{"tags":["Upload"],"operationId":"auto_post_api_v1_accounts_account_id_upload","summary":"Upload an account-owned file","description":"Uploads a multipart file or safely fetches an explicitly supplied external URL, stamps the blob with the authenticated account, and returns its signed identifier. External fetches reject private, loopback, link-local, oversized, redirect-unsafe, and unsupported-content targets.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"File stored and bound to the authenticated account.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["file_url","blob_id"],"properties":{"file_url":{"type":"string","format":"uri","description":"Application URL for the stored blob."},"blob_id":{"type":"string","description":"Account-bound Active Storage signed identifier."}}},"example":{"file_url":"https://example.com/resource","blob_id":"sample blob id"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"422":{"description":"Missing input, unsafe URL, failed fetch, oversized file, or unsupported content type.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string"}}},"example":{"error":"sample error"}}}},"500":{"description":"An unexpected storage or external-fetch failure occurred."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","additionalProperties":false,"required":["attachment"],"properties":{"attachment":{"type":"string","format":"binary","description":"File to upload through the application."}}}},"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["external_url"],"properties":{"external_url":{"type":"string","format":"uri","description":"Public HTTP(S) file URL fetched through the server-side safe-fetch policy."}}},"example":{"external_url":"https://example.com/resource"}}}}}},"/api/v1/accounts":{"post":{"tags":["Account"],"operationId":"auto_post_api_v1_accounts","summary":"Create accounts","description":"Creates a new account from the request payload.","security":[{"userApiKey":[]},{}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","format":"email"}}},"example":{"email":"agent@example.com"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"account_name":{"type":"string"},"email":{"type":"string","format":"email"},"name":{"type":"string"},"password":{"type":"string"},"locale":{"type":"string","enum":["en","pt_BR","es"]},"domain":{"type":"string"},"support_email":{"type":"string","format":"email"},"user_full_name":{"type":"string"}},"required":["name"]},"example":{"account_name":"sample account name","email":"agent@example.com","name":"Sample Name","password":"sample-password","locale":"en","domain":"example.com","support_email":"agent@example.com","user_full_name":"sample user full name"}}}}}},"/api/v1/integrations/webhooks":{"post":{"tags":["Integrations"],"operationId":"auto_post_api_v1_integrations_webhooks","summary":"Create webhooks","description":"Creates a new webhook from the request payload.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"For url_verification, echoes the challenge; otherwise processes/enqueues the event.","content":{"application/json":{"schema":{"type":"object","properties":{"challenge":{"type":"string","description":"Echoed on url_verification","example":"3eZbrw1aB..."}}},"example":{"challenge":"3eZbrw1aB..."}}}}},"requestBody":{"required":true,"description":"Slack Events API envelope. `url_verification` returns the challenge; `event_callback` is processed/enqueued.","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","enum":["url_verification","event_callback"],"example":"url_verification"},"challenge":{"type":"string","description":"Present on url_verification","example":"3eZbrw1aB..."},"token":{"type":"string","example":"sample-token"},"team_id":{"type":"string","example":"T0123ABCD"},"api_app_id":{"type":"string","example":"A0123ABCD"},"event":{"type":"object","description":"Present on event_callback","properties":{"type":{"type":"string","enum":["message","link_shared"],"example":"message"},"subtype":{"type":["string","null"],"example":"file_share"},"user":{"type":"string","example":"U0123ABCD"},"channel":{"type":"string","example":"C0123ABCD"},"text":{"type":"string","example":"Hello from Slack"},"thread_ts":{"type":["string","null"],"example":"1737800000.000100"},"files":{"type":"array","description":"File objects from the integration (e.g. Slack) event.","items":{"type":"object","additionalProperties":true,"description":"One file object from the integration event."}},"links":{"type":"array","description":"Link objects from the integration (e.g. Slack) event.","items":{"type":"object","additionalProperties":true,"description":"One link object from the integration event."}}}}}},"example":{"type":"url_verification","challenge":"3eZbrw1aB...","token":"sample-token","team_id":"T0123ABCD","api_app_id":"A0123ABCD","event":{"type":"message","subtype":"file_share","user":"U0123ABCD","channel":"C0123ABCD","text":"Hello from Slack","thread_ts":"1737800000.000100","files":[{}],"links":[{}]}}}}}}},"/api/v1/auth/saml_login":{"post":{"tags":["Auth"],"operationId":"auto_post_api_v1_auth_saml_login","summary":"Saml login auth","description":"Performs the saml login operation on the targeted auth resource.","security":[],"responses":{"307":{"description":"Temporary redirect to the SAML initiation URL (/auth/saml?account_id=...\u0026RelayState=...)."},"403":{"description":"SAML SSO login is not enabled for this account.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"SAML SSO login is not enabled"}}},"example":{"error":"SAML SSO login is not enabled"}}}},"404":{"description":"Account not found for the given email/account."}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"target":{"type":"string"}}},"example":{"target":"sample target"}}}}}},"/api/v1/profile/avatar":{"delete":{"tags":["Profile"],"operationId":"auto_delete_api_v1_profile_avatar","summary":"Avatar profiles","description":"Performs the avatar operation on the targeted profile resource.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/user"},"example":{"id":1,"access_token":"sample-token","account_id":1,"available_name":"sample available name","avatar_url":"https://example.com/resource","confirmed":true,"display_name":"sample display name","message_signature":"sample message signature","email":"agent@example.com","hmac_identifier":"sample hmac identifier","inviter_id":1,"name":"Sample Name","provider":"email","pubsub_token":"sample-token","role":"agent","ui_settings":{"translation_language_by_account":{"1":"pt-BR"}},"uid":"sample uid","type":"sample type","custom_attributes":{},"accounts":[{"id":1,"name":"Sample Name","status":"active","active_at":"2026-01-15T10:30:00.000Z","role":"administrator","outbound_agent_name_header_policy":"inherit","permissions":["sample permission"],"availability":"online","availability_status":"online","auto_offline":true,"custom_role_id":1,"custom_role":{"id":1,"name":"Sample Name","description":"A short description.","permissions":["conversation_manage"]},"onboarding_step":"sample onboarding step","access_role_id":1,"access_role":{"id":1,"name":"Sample Name","field_permissions":{"contact":{},"organization":{}}},"api_and_webhooks":true}]}}}}},"x-authentication":{"kind":"credential","scheme":"userApiKey","location":"header","name":"api_access_token","verification_boundary":"Api::V1::ProfilesController authentication filter","algorithm":"opaque"}}},"/api/v1/profile/availability":{"post":{"tags":["Profile"],"operationId":"auto_post_api_v1_profile_availability","summary":"Set availability in an account","description":"Sets the availability the signed-in user configured for one of their accounts (online, busy or offline) and returns the refreshed user profile. The new value is visible in the matching entry of the returned accounts list, alongside availability_status, which is the realtime status derived from presence.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Availability updated; the refreshed user profile is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/user"},"example":{"id":1,"access_token":"sample-token","account_id":1,"available_name":"sample available name","avatar_url":"https://example.com/resource","confirmed":true,"display_name":"sample display name","message_signature":"sample message signature","email":"agent@example.com","hmac_identifier":"sample hmac identifier","inviter_id":1,"name":"Sample Name","provider":"email","pubsub_token":"sample-token","role":"agent","ui_settings":{"translation_language_by_account":{"1":"pt-BR"}},"uid":"sample uid","type":"sample type","custom_attributes":{},"accounts":[{"id":1,"name":"Sample Name","status":"active","active_at":"2026-01-15T10:30:00.000Z","role":"administrator","permissions":["sample permission"],"availability":"online","availability_status":"online","auto_offline":true,"custom_role_id":null,"custom_role":null,"outbound_agent_name_header_policy":"inherit","onboarding_step":"sample onboarding step","access_role_id":1,"access_role":{"id":1,"name":"Sample Name","field_permissions":{"contact":{},"organization":{}}},"api_and_webhooks":true}]}}}},"404":{"description":"The signed-in user is not a member of the account in the payload."}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"profile":{"type":"object","properties":{"availability":{"type":"string","enum":["online","offline","busy"]}}}},"required":["profile"]},"example":{"profile":{"availability":"online"}}}}},"x-authentication":{"kind":"credential","scheme":"userApiKey","location":"header","name":"api_access_token","verification_boundary":"Api::V1::ProfilesController authentication filter","algorithm":"opaque"}}},"/api/v1/profile/auto_offline":{"post":{"tags":["Profile"],"operationId":"auto_post_api_v1_profile_auto_offline","summary":"Toggle auto-offline in an account","description":"Enables or disables automatic offline switching for the signed-in user in one of their accounts. While enabled, the user is moved to offline automatically once they stop working; while disabled, the availability they configured is kept until they change it. Returns the refreshed user profile, where the flag is visible in the matching entry of the accounts list.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Auto-offline updated; the refreshed user profile is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/user"},"example":{"id":1,"access_token":"sample-token","account_id":1,"available_name":"sample available name","avatar_url":"https://example.com/resource","confirmed":true,"display_name":"sample display name","message_signature":"sample message signature","email":"agent@example.com","hmac_identifier":"sample hmac identifier","inviter_id":1,"name":"Sample Name","provider":"email","pubsub_token":"sample-token","role":"agent","ui_settings":{"translation_language_by_account":{"1":"pt-BR"}},"uid":"sample uid","type":"sample type","custom_attributes":{},"accounts":[{"id":1,"name":"Sample Name","status":"active","active_at":"2026-01-15T10:30:00.000Z","role":"administrator","permissions":["sample permission"],"availability":"online","availability_status":"online","auto_offline":true,"custom_role_id":null,"custom_role":null,"outbound_agent_name_header_policy":"inherit","onboarding_step":"sample onboarding step","access_role_id":1,"access_role":{"id":1,"name":"Sample Name","field_permissions":{"contact":{},"organization":{}}},"api_and_webhooks":true}]}}}},"404":{"description":"The signed-in user is not a member of the account in the payload."}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"profile":{"type":"object","properties":{"auto_offline":{"type":"boolean"}}}},"required":["profile"]},"example":{"profile":{"auto_offline":true}}}}},"x-authentication":{"kind":"credential","scheme":"userApiKey","location":"header","name":"api_access_token","verification_boundary":"Api::V1::ProfilesController authentication filter","algorithm":"opaque"}}},"/api/v1/profile/set_active_account":{"put":{"tags":["Profile"],"operationId":"auto_put_api_v1_profile_set_active_account","summary":"Mark an account as the active one","description":"Stamps the signed-in user's membership of the given account as active at the current time, so the dashboard reopens on that account and the account ordering reflects the most recent use. The response carries no body; a request naming an account the user does not belong to is accepted and changes nothing.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Membership stamped as active. Empty body."}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"profile":{"type":"string"}}},"example":{"profile":"sample profile"}}}},"x-authentication":{"kind":"credential","scheme":"userApiKey","location":"header","name":"api_access_token","verification_boundary":"Api::V1::ProfilesController authentication filter","algorithm":"opaque"}}},"/api/v1/profile/resend_confirmation":{"post":{"tags":["Profile"],"operationId":"auto_post_api_v1_profile_resend_confirmation","summary":"Resend the confirmation e-mail","description":"Sends the e-mail confirmation instructions to the signed-in user again. When the address is already confirmed nothing is sent. The response carries no body in either case, so it never reveals the confirmation state of the address.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Request accepted; instructions sent when the address is still unconfirmed. Empty body."}},"x-authentication":{"kind":"credential","scheme":"userApiKey","location":"header","name":"api_access_token","verification_boundary":"Api::V1::ProfilesController authentication filter","algorithm":"opaque"}}},"/api/v1/profile/reset_access_token":{"post":{"tags":["Profile"],"operationId":"auto_post_api_v1_profile_reset_access_token","summary":"Reset access token profiles","description":"Performs the reset access token operation on the targeted profile resource.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/user"},"example":{"id":1,"access_token":"sample-token","account_id":1,"available_name":"sample available name","avatar_url":"https://example.com/resource","confirmed":true,"display_name":"sample display name","message_signature":"sample message signature","email":"agent@example.com","hmac_identifier":"sample hmac identifier","inviter_id":1,"name":"Sample Name","provider":"email","pubsub_token":"sample-token","role":"agent","ui_settings":{"translation_language_by_account":{"1":"pt-BR"}},"uid":"sample uid","type":"sample type","custom_attributes":{},"accounts":[{"id":1,"name":"Sample Name","status":"active","active_at":"2026-01-15T10:30:00.000Z","role":"administrator","outbound_agent_name_header_policy":"inherit","permissions":["sample permission"],"availability":"online","availability_status":"online","auto_offline":true,"custom_role_id":1,"custom_role":{"id":1,"name":"Sample Name","description":"A short description.","permissions":["conversation_manage"]},"onboarding_step":"sample onboarding step","access_role_id":1,"access_role":{"id":1,"name":"Sample Name","field_permissions":{"contact":{},"organization":{}}},"api_and_webhooks":true}]}}}}},"x-authentication":{"kind":"credential","scheme":"userApiKey","location":"header","name":"api_access_token","verification_boundary":"Api::V1::ProfilesController authentication filter","algorithm":"opaque"}}},"/api/v1/profile/mfa/verify":{"post":{"tags":["Profile"],"operationId":"auto_post_api_v1_profile_mfa_verify","summary":"Verify mfa","description":"Performs the verify operation on the targeted mfa resource.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"enabled":{"type":"boolean"},"backup_codes":{"type":"string"}}},"example":{"enabled":true,"backup_codes":"sample backup codes"}}}}},"x-authentication":{"kind":"credential","scheme":"userApiKey","location":"header","name":"api_access_token","verification_boundary":"Api::V1::ProfilesController authentication filter","algorithm":"opaque"}}},"/api/v1/profile/mfa/backup_codes":{"post":{"tags":["Profile"],"operationId":"auto_post_api_v1_profile_mfa_backup_codes","summary":"Backup codes mfa","description":"Performs the backup codes operation on the targeted mfa resource.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"backup_codes":{"type":"string"}}},"example":{"backup_codes":"sample backup codes"}}}}},"x-authentication":{"kind":"credential","scheme":"userApiKey","location":"header","name":"api_access_token","verification_boundary":"Api::V1::ProfilesController authentication filter","algorithm":"opaque"}}},"/api/v1/profile/mfa":{"get":{"tags":["Profile"],"operationId":"auto_get_api_v1_profile_mfa","summary":"Get mfa","description":"Returns the mfa identified by the path parameters.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"feature_available":{"type":"boolean"},"enabled":{"type":"boolean"},"backup_codes_generated":{"type":"boolean"},"remaining_backup_codes":{"type":"string"}}},"example":{"feature_available":true,"enabled":true,"backup_codes_generated":true,"remaining_backup_codes":"sample remaining backup codes"}}}}},"x-authentication":{"kind":"credential","scheme":"userApiKey","location":"header","name":"api_access_token","verification_boundary":"Api::V1::ProfilesController authentication filter","algorithm":"opaque"}},"delete":{"tags":["Profile"],"operationId":"auto_delete_api_v1_profile_mfa","summary":"Delete mfa","description":"Deletes the mfa identified by the path parameters.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"enabled":{"type":"boolean"}}},"example":{"enabled":true}}}}},"x-authentication":{"kind":"credential","scheme":"userApiKey","location":"header","name":"api_access_token","verification_boundary":"Api::V1::ProfilesController authentication filter","algorithm":"opaque"}},"post":{"tags":["Profile"],"operationId":"auto_post_api_v1_profile_mfa","summary":"Create mfa","description":"Creates a new mfa from the request payload.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"provisioning_url":{"type":"string"},"secret":{"type":"string"}}},"example":{"provisioning_url":"https://example.com/resource","secret":"sample-token"}}}}},"x-authentication":{"kind":"credential","scheme":"userApiKey","location":"header","name":"api_access_token","verification_boundary":"Api::V1::ProfilesController authentication filter","algorithm":"opaque"}}},"/api/v1/profile/sessions":{"get":{"tags":["Profile"],"operationId":"auto_get_api_v1_profile_sessions","summary":"List sessions","description":"Returns the list of sessions visible to the authenticated caller.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"browser_name":{"type":"string"},"browser_version":{"type":"string"},"device_name":{"type":"string"},"platform_name":{"type":"string"},"platform_version":{"type":"string"},"ip_address":{"type":"string"},"city":{"type":"string"},"country":{"type":"integer"},"country_code":{"type":"integer"},"last_activity_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"},"current":{"type":"boolean"}}}},"example":[{"id":1,"browser_name":"sample browser name","browser_version":"sample browser version","device_name":"sample device name","platform_name":"sample platform name","platform_version":"sample platform version","ip_address":"203.0.113.10","city":"São Paulo","country":1,"country_code":1,"last_activity_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","current":true}]}}}},"parameters":[{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."}],"x-authentication":{"kind":"credential","scheme":"userApiKey","location":"header","name":"api_access_token","verification_boundary":"Api::V1::ProfilesController authentication filter","algorithm":"opaque"}}},"/api/v1/profile/sessions/{id}":{"delete":{"tags":["Profile"],"operationId":"auto_delete_api_v1_profile_sessions_id","summary":"Delete sessions","description":"Deletes the session identified by the path parameters.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Success (no content)"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"x-authentication":{"kind":"credential","scheme":"userApiKey","location":"header","name":"api_access_token","verification_boundary":"Api::V1::ProfilesController authentication filter","algorithm":"opaque"}}},"/api/v1/notification_subscriptions":{"delete":{"tags":["Notification Subscriptions"],"operationId":"auto_delete_api_v1_notification_subscriptions","summary":"Delete notification subscriptions","description":"Deletes the notification subscription identified by the path parameters.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Success (no content)"}},"x-authentication":{"kind":"credential","scheme":"userApiKey","location":"header","name":"api_access_token","verification_boundary":"Api::V1::ProfilesController authentication filter","algorithm":"opaque"}},"post":{"tags":["Notification Subscriptions"],"operationId":"auto_post_api_v1_notification_subscriptions","summary":"Create notification subscriptions","description":"Creates a new notification subscription from the request payload.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Notification subscription created (raw record; also returns HTTP 200 in practice)","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer","example":88},"identifier":{"type":["string","null"],"example":"fcm-token-abc123"},"subscription_type":{"type":"string","enum":["browser_push","fcm"],"example":"fcm","description":"Push notification transport for the subscription."},"subscription_attributes":{"type":"object","additionalProperties":true,"example":{"push_token":"fcm-token-abc123"},"description":"Push-subscription attributes; the key set depends on subscription_type."},"user_id":{"type":"integer","example":7},"created_at":{"type":"string","format":"date-time","example":"2026-01-15T10:30:00.000Z"},"updated_at":{"type":"string","format":"date-time","example":"2026-01-15T10:30:00.000Z"}}},"example":{"id":88,"identifier":"fcm-token-abc123","subscription_type":"fcm","subscription_attributes":{"push_token":"fcm-token-abc123"},"user_id":7,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"notification_subscription":{"type":"object","properties":{"subscription_type":{"type":"string","enum":["browser_push","fcm"],"description":"Push notification transport for the subscription."},"subscription_attributes":{"type":"object","additionalProperties":true,"description":"Push-subscription attributes; the key set depends on subscription_type."}}}},"required":["notification_subscription"]},"example":{"notification_subscription":{"subscription_type":"browser_push","subscription_attributes":{}}}}}},"x-authentication":{"kind":"credential","scheme":"userApiKey","location":"header","name":"api_access_token","verification_boundary":"Api::V1::ProfilesController authentication filter","algorithm":"opaque"}}},"/api/v1/widget/direct_uploads":{"post":{"tags":["Widget"],"operationId":"auto_post_api_v1_widget_direct_uploads","summary":"Prepare a direct file upload","description":"First step of the widget attachment flow. It registers the file the visitor picked and returns the storage record plus a pre-signed target the browser uploads the bytes to, without routing them through this application. The client uploads the raw bytes to direct_upload.url with exactly the headers in direct_upload.headers, then sends the returned signed_id as the attachment of the message.","security":[{"widgetWebsiteToken":[],"widgetContactJwt":[]}],"responses":{"204":{"description":"The widget session could not be resolved to a contact and an account; no storage record is created and no body is returned."},"200":{"description":"Storage record created. The bytes are not stored yet — the client must upload them to direct_upload.url before referencing signed_id.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer","description":"Internal identifier of the storage record."},"key":{"type":"string","description":"Key the file is stored under in the storage service."},"filename":{"type":"string"},"content_type":{"type":["string","null"],"description":"MIME type recorded for the file, as submitted by the client."},"metadata":{"type":"object","additionalProperties":true,"description":"Metadata stored with the file, as submitted by the client."},"service_name":{"type":"string","description":"Storage service the file is written to, as configured for this installation."},"byte_size":{"type":"integer"},"checksum":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"},"signed_id":{"type":"string","description":"Tamper-proof reference to the file; send it as the attachment of the message once the bytes are uploaded."},"direct_upload":{"type":"object","description":"Where and how the client must upload the bytes.","properties":{"url":{"type":"string","description":"Pre-signed URL the client PUTs the raw bytes to."},"headers":{"type":"object","additionalProperties":true,"description":"Headers that must accompany the upload exactly as given; the pre-signed URL rejects the request otherwise."}}}}},"example":{"id":42,"key":"xf9pdq0k7z2m4bn6vc1a3s5d","filename":"invoice.pdf","content_type":"application/pdf","metadata":{},"service_name":"amazon","byte_size":20451,"checksum":"qLNbHUmZ6vC0FpHZjkQeBQ==","created_at":"2026-01-15T10:30:00.000Z","signed_id":"eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBCQT09In19","direct_upload":{"url":"https://storage.example.com/uploads/xf9pdq0k7z2m4bn6vc1a3s5d?signature=sample","headers":{"Content-Type":"application/pdf","Content-MD5":"qLNbHUmZ6vC0FpHZjkQeBQ=="}}}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["blob"],"properties":{"blob":{"type":"object","required":["filename","byte_size","checksum"],"properties":{"filename":{"type":"string","description":"Name of the file as picked by the visitor."},"byte_size":{"type":"integer","description":"Exact size of the file in bytes; the pre-signed target only accepts this size."},"checksum":{"type":"string","description":"Base64-encoded MD5 digest of the file, used by the storage service to verify the upload."},"content_type":{"type":"string","description":"MIME type of the file."},"metadata":{"type":"object","additionalProperties":true,"description":"Free-form metadata to store with the file; the widget sends the analysis hints of the picked file, such as image dimensions."}}},"website_token":{"type":"string","description":"Public token of the website inbox the widget belongs to."}}},"example":{"blob":{"filename":"invoice.pdf","byte_size":20451,"checksum":"qLNbHUmZ6vC0FpHZjkQeBQ==","content_type":"application/pdf","metadata":{}},"website_token":"sample-token"}}}},"x-authentication":{"kind":"all_of","branches":[{"kind":"credential","scheme":"widgetWebsiteToken","location":"body","name":"website_token","verification_boundary":"WebsiteTokenHelper#set_web_widget","algorithm":"opaque"},{"kind":"credential","scheme":"widgetContactJwt","location":"header","name":"X-Auth-Token","verification_boundary":"WebsiteTokenHelper#set_contact","algorithm":"JWT"}]}}},"/api/v1/widget/config":{"post":{"tags":["Widget"],"operationId":"auto_post_api_v1_widget_config","summary":"Create configs","description":"Creates a new config from the request payload.","security":[{"widgetWebsiteToken":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"website_channel_config":{"type":"object","properties":{"allow_messages_after_resolved":{"type":"string"},"api_host":{"type":"string"},"auth_token":{"type":"string"},"avatar_url":{"type":"string"},"csat_survey_enabled":{"type":"boolean"},"disable_branding":{"type":"boolean"},"enabled_features":{"type":"string"},"enabled_languages":{"type":"string"},"locale":{"type":"string"},"out_of_office_message":{"type":"string"},"portal":{"type":"string"},"pre_chat_form_enabled":{"type":"boolean"},"pre_chat_form_options":{"type":"string"},"reply_time":{"type":"string","format":"date-time"},"timezone":{"type":"string","description":"IANA timezone identifier (e.g. \"America/Sao_Paulo\", \"UTC\"). Rails timezone names are also accepted on input; an unrecognized value is ignored in favor of the next fallback.","example":"America/Sao_Paulo"},"utc_off_set":{"type":"string"},"website_name":{"type":"string"},"website_token":{"type":"string"},"welcome_tagline":{"type":"string"},"welcome_title":{"type":"string"},"widget_color":{"type":"string"},"working_hours":{"type":"string"},"working_hours_enabled":{"type":"boolean"}}},"contact":{"type":"object","properties":{"email":{"type":"string","format":"email"},"id":{"type":"integer"},"identifier":{"type":"string"},"name":{"type":"string"},"phone_number":{"type":"string"},"pubsub_token":{"type":"string"}}},"global_config":{"type":"string"}}},"example":{"website_channel_config":{"allow_messages_after_resolved":"sample allow messages after resolved","api_host":"sample api host","auth_token":"sample-token","avatar_url":"https://example.com/resource","csat_survey_enabled":true,"disable_branding":true,"enabled_features":"sample enabled features","enabled_languages":"sample enabled languages","locale":"en","out_of_office_message":"sample out of office message","portal":"sample portal","pre_chat_form_enabled":true,"pre_chat_form_options":"sample pre chat form options","reply_time":"2026-01-15T10:30:00.000Z","timezone":"America/Sao_Paulo","utc_off_set":"sample utc off set","website_name":"sample website name","website_token":"sample-token","welcome_tagline":"sample welcome tagline","welcome_title":"sample welcome title","widget_color":"#1F93FF","working_hours":"sample working hours","working_hours_enabled":true},"contact":{"email":"agent@example.com","id":1,"identifier":"sample-identifier","name":"Sample Name","phone_number":"+5511999998888","pubsub_token":"sample-token"},"global_config":"sample global config"}}}}},"x-authentication":{"kind":"credential","scheme":"widgetWebsiteToken","location":"body","name":"website_token","verification_boundary":"WebsiteTokenHelper#set_web_widget","algorithm":"opaque"}}},"/api/v1/widget/campaigns":{"get":{"tags":["Widget"],"operationId":"auto_get_api_v1_widget_campaigns","summary":"List campaigns","description":"Returns the list of campaigns visible to the authenticated caller.","security":[{"widgetWebsiteToken":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"trigger_rules":{"type":"string"},"trigger_only_during_business_hours":{"type":"string"},"message":{"type":"string"},"sender":{"type":["string","null"]}}}},"example":[{"id":1,"trigger_rules":"sample trigger rules","trigger_only_during_business_hours":"sample trigger only during business hours","message":"Sample message text.","sender":"sample sender"}]}}}},"parameters":[{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."}],"x-authentication":{"kind":"credential","scheme":"widgetWebsiteToken","location":"body","name":"website_token","verification_boundary":"WebsiteTokenHelper#set_web_widget","algorithm":"opaque"}}},"/api/v1/widget/events":{"post":{"tags":["Widget"],"operationId":"auto_post_api_v1_widget_events","summary":"Report a widget event","description":"Records an event the widget observed for the current visitor, identified by its name and carrying the caller's own event payload. The installation enriches it with the widget language, the browser language and the browser, device and platform details before dispatching it, so campaigns and automations can react to it. The response carries no body.","security":[{"widgetWebsiteToken":[],"widgetContactJwt":[]}],"responses":{"204":{"description":"Event dispatched. Empty body."}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"website_token":{"type":"string"},"event_info":{"type":"object","additionalProperties":true,"description":"Free-form object."}}},"example":{"name":"Sample Name","website_token":"sample-token","event_info":{}}}}},"x-authentication":{"kind":"all_of","branches":[{"kind":"credential","scheme":"widgetWebsiteToken","location":"body","name":"website_token","verification_boundary":"WebsiteTokenHelper#set_web_widget","algorithm":"opaque"},{"kind":"credential","scheme":"widgetContactJwt","location":"header","name":"X-Auth-Token","verification_boundary":"WebsiteTokenHelper#set_contact","algorithm":"JWT"}]}}},"/api/v1/widget/messages":{"get":{"tags":["Widget"],"operationId":"auto_get_api_v1_widget_messages","summary":"List messages","description":"Returns the list of messages visible to the authenticated caller.","security":[{"widgetWebsiteToken":[],"widgetContactJwt":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"content":{"type":"string"},"message_type":{"type":"string","enum":["incoming","outgoing","activity","template"],"description":"Direction/kind of the message."},"content_type":{"type":"string","enum":["text","input_text","input_textarea","input_email","input_select","cards","form","article","incoming_email","input_csat","integrations","sticker","voice_call","poll"]},"content_attributes":{"type":"object","additionalProperties":true,"description":"Structured metadata accompanying the message content; the key set depends on content_type (e.g. select items, CSAT submission values, deletion flags, external delivery errors)."},"created_at":{"type":"integer"},"conversation_id":{"type":"integer"},"attachments":{"type":"array","items":{"type":"string"}},"sender":{"type":"string"}}}},"meta":{"type":"object","properties":{"contact_last_seen_at":{"type":"integer"}}}}},"example":{"payload":[{"id":1,"content":"Sample content text.","message_type":"incoming","content_type":"text","content_attributes":{},"created_at":1,"conversation_id":1,"attachments":["sample attachment"],"sender":"sample sender"}],"meta":{"contact_last_seen_at":1}}}}}},"parameters":[{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."}],"x-authentication":{"kind":"all_of","branches":[{"kind":"credential","scheme":"widgetWebsiteToken","location":"body","name":"website_token","verification_boundary":"WebsiteTokenHelper#set_web_widget","algorithm":"opaque"},{"kind":"credential","scheme":"widgetContactJwt","location":"header","name":"X-Auth-Token","verification_boundary":"WebsiteTokenHelper#set_contact","algorithm":"JWT"}]}},"post":{"tags":["Widget"],"operationId":"auto_post_api_v1_widget_messages","summary":"Create messages","description":"Creates a new message from the request payload.","security":[{"widgetWebsiteToken":[],"widgetContactJwt":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"content":{"type":"string"},"inbox_id":{"type":"integer"},"conversation_id":{"type":"integer"},"message_type":{"type":"string","enum":["incoming","outgoing","activity","template"],"description":"Direction/kind of the message."},"created_at":{"type":"integer"},"private":{"type":"string"},"source_id":{"type":"integer"},"content_attributes":{"type":"object","additionalProperties":true,"description":"Structured metadata accompanying the message content; the key set depends on content_type (e.g. select items, CSAT submission values, deletion flags, external delivery errors)."},"attachments":{"type":"array","items":{"type":"string"}},"sender":{"type":"string"}}},"example":{"id":1,"content":"Sample content text.","inbox_id":1,"conversation_id":1,"message_type":"incoming","created_at":1,"private":"sample private","source_id":1,"content_attributes":{},"attachments":["sample attachment"],"sender":"sample sender"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"before":{"type":"string"},"after":{"type":"string"},"website_token":{"type":"string"},"contact":{"type":"object","additionalProperties":true,"description":"Free-form object."},"message":{"type":"object","additionalProperties":true,"description":"Free-form object."},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"labels":{"type":"array","items":{"type":"string"}}}},"example":{"id":1,"before":"sample before","after":"sample after","website_token":"sample-token","contact":{},"message":{},"custom_attributes":{},"labels":["sample label"]}}}},"x-authentication":{"kind":"all_of","branches":[{"kind":"credential","scheme":"widgetWebsiteToken","location":"body","name":"website_token","verification_boundary":"WebsiteTokenHelper#set_web_widget","algorithm":"opaque"},{"kind":"credential","scheme":"widgetContactJwt","location":"header","name":"X-Auth-Token","verification_boundary":"WebsiteTokenHelper#set_contact","algorithm":"JWT"}]}}},"/api/v1/widget/messages/{id}":{"patch":{"tags":["Widget"],"operationId":"auto_patch_api_v1_widget_messages_id","summary":"Update messages","description":"Updates the message identified by the path parameters with the submitted attributes.","security":[{"widgetWebsiteToken":[],"widgetContactJwt":[]}],"responses":{"200":{"description":"Message updated; echoes the (possibly re-identified) contact","content":{"application/json":{"schema":{"type":"object","properties":{"contact":{"type":"object","description":"Present when a contact is set","properties":{"id":{"type":"integer","example":55},"name":{"type":"string","example":"Jane Doe"},"email":{"type":["string","null"],"example":"jane@example.com"},"phone_number":{"type":["string","null"],"example":"+15550100100"},"identifier":{"type":["string","null"],"example":"ext-123"},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"additional_attributes":{"type":"object","additionalProperties":true,"description":"Channel- and source-specific metadata for this record (e.g. browser info, referer, social profile identifiers). The key set depends on the originating channel."}}}}},"example":{"contact":{"id":55,"name":"Jane Doe","email":"jane@example.com","phone_number":"+15550100100","identifier":"ext-123","custom_attributes":{},"additional_attributes":{}}}}}},"500":{"description":"Update failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","additionalProperties":true,"description":"Validation error details keyed by field name (each value is an array of messages)."},"message":{"type":"string","example":"Validation failed"}}},"example":{"error":{},"message":"Validation failed"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Free-form object."}}}},"example":{"message":[{}]}}}},"x-authentication":{"kind":"all_of","branches":[{"kind":"credential","scheme":"widgetWebsiteToken","location":"body","name":"website_token","verification_boundary":"WebsiteTokenHelper#set_web_widget","algorithm":"opaque"},{"kind":"credential","scheme":"widgetContactJwt","location":"header","name":"X-Auth-Token","verification_boundary":"WebsiteTokenHelper#set_contact","algorithm":"JWT"}]}},"put":{"tags":["Widget"],"operationId":"auto_put_api_v1_widget_messages_id","summary":"Update messages","description":"Updates the message identified by the path parameters with the submitted attributes.","security":[{"widgetWebsiteToken":[],"widgetContactJwt":[]}],"responses":{"200":{"description":"Message updated; echoes the (possibly re-identified) contact","content":{"application/json":{"schema":{"type":"object","properties":{"contact":{"type":"object","description":"Present when a contact is set","properties":{"id":{"type":"integer","example":55},"name":{"type":"string","example":"Jane Doe"},"email":{"type":["string","null"],"example":"jane@example.com"},"phone_number":{"type":["string","null"],"example":"+15550100100"},"identifier":{"type":["string","null"],"example":"ext-123"},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"additional_attributes":{"type":"object","additionalProperties":true,"description":"Channel- and source-specific metadata for this record (e.g. browser info, referer, social profile identifiers). The key set depends on the originating channel."}}}}},"example":{"contact":{"id":55,"name":"Jane Doe","email":"jane@example.com","phone_number":"+15550100100","identifier":"ext-123","custom_attributes":{},"additional_attributes":{}}}}}},"500":{"description":"Update failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","additionalProperties":true,"description":"Validation error details keyed by field name (each value is an array of messages)."},"message":{"type":"string","example":"Validation failed"}}},"example":{"error":{},"message":"Validation failed"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Free-form object."}}}},"example":{"message":[{}]}}}},"x-authentication":{"kind":"all_of","branches":[{"kind":"credential","scheme":"widgetWebsiteToken","location":"body","name":"website_token","verification_boundary":"WebsiteTokenHelper#set_web_widget","algorithm":"opaque"},{"kind":"credential","scheme":"widgetContactJwt","location":"header","name":"X-Auth-Token","verification_boundary":"WebsiteTokenHelper#set_contact","algorithm":"JWT"}]}}},"/api/v1/widget/conversations/destroy_custom_attributes":{"post":{"tags":["Widget"],"operationId":"auto_post_api_v1_widget_conversations_destroy_custom_attributes","summary":"Destroy custom attributes conversations","description":"Performs the destroy custom attributes operation on the targeted conversation resource.","security":[{"widgetWebsiteToken":[],"widgetContactJwt":[]}],"responses":{"200":{"description":"Conversation after removing a custom attribute (raw model attributes)","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer","example":900},"account_id":{"type":"integer","example":1},"inbox_id":{"type":"integer","example":7},"status":{"type":"string","enum":["open","resolved","pending","snoozed"],"description":"AR enum serialized as string via raw render","example":"open"},"display_id":{"type":"integer","example":33},"uuid":{"type":"string","example":"f47ac10b-58cc-4372-a567-0e02b2c3d479"},"contact_id":{"type":"integer","example":55},"contact_inbox_id":{"type":"integer","example":88},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"additional_attributes":{"type":"object","additionalProperties":true,"description":"Channel- and source-specific metadata for this record (e.g. browser info, referer, social profile identifiers). The key set depends on the originating channel."},"priority":{"type":["string","null"],"enum":["low","medium","high","urgent",null],"description":"AR enum serialized as string via raw render","example":null},"created_at":{"type":"string","format":"date-time","example":"2026-01-15T10:30:00.000Z"},"updated_at":{"type":"string","format":"date-time","example":"2026-01-15T10:30:00.000Z"}}},"example":{"id":900,"account_id":1,"inbox_id":7,"status":"open","display_id":33,"uuid":"f47ac10b-58cc-4372-a567-0e02b2c3d479","contact_id":55,"contact_inbox_id":88,"custom_attributes":{},"additional_attributes":{},"priority":null,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"custom_attribute":{"type":"string"}}},"example":{"custom_attribute":"sample custom attribute"}}}},"x-authentication":{"kind":"all_of","branches":[{"kind":"credential","scheme":"widgetWebsiteToken","location":"body","name":"website_token","verification_boundary":"WebsiteTokenHelper#set_web_widget","algorithm":"opaque"},{"kind":"credential","scheme":"widgetContactJwt","location":"header","name":"X-Auth-Token","verification_boundary":"WebsiteTokenHelper#set_contact","algorithm":"JWT"}]}}},"/api/v1/widget/conversations/set_custom_attributes":{"post":{"tags":["Widget"],"operationId":"auto_post_api_v1_widget_conversations_set_custom_attributes","summary":"Set custom attributes on the widget conversation","description":"Replaces the custom attributes of the conversation the visitor currently has open with the submitted map, so the site can attach its own context (plan, cart value, page section) to the chat. The response carries no body.","security":[{"widgetWebsiteToken":[],"widgetContactJwt":[]}],"responses":{"204":{"description":"Custom attributes replaced. Empty body."},"404":{"description":"The visitor has no conversation open in this inbox."}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"typing_status":{"type":"string","enum":["on","off"],"description":"Typing indicator toggle."},"website_token":{"type":"string"},"email":{"type":"string","format":"email"},"contact":{"type":"object","additionalProperties":true,"description":"Free-form object."},"message":{"type":"object","additionalProperties":true,"description":"Free-form object."},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."}}},"example":{"id":1,"typing_status":"on","website_token":"sample-token","email":"agent@example.com","contact":{},"message":{},"custom_attributes":{}}}}},"x-authentication":{"kind":"all_of","branches":[{"kind":"credential","scheme":"widgetWebsiteToken","location":"body","name":"website_token","verification_boundary":"WebsiteTokenHelper#set_web_widget","algorithm":"opaque"},{"kind":"credential","scheme":"widgetContactJwt","location":"header","name":"X-Auth-Token","verification_boundary":"WebsiteTokenHelper#set_contact","algorithm":"JWT"}]}}},"/api/v1/widget/conversations/update_last_seen":{"post":{"tags":["Widget"],"operationId":"auto_post_api_v1_widget_conversations_update_last_seen","summary":"Mark the widget conversation as seen","description":"Stamps the current time as the visitor's last-seen moment on the conversation they have open and schedules the read receipts for the agent messages up to that moment, which is what turns the delivered ticks into read ticks on the agent side. The response carries no body; when the visitor has no conversation open the call is accepted and does nothing.","security":[{"widgetWebsiteToken":[],"widgetContactJwt":[]}],"responses":{"200":{"description":"Last-seen stamped and read receipts scheduled. Empty body."}},"x-authentication":{"kind":"all_of","branches":[{"kind":"credential","scheme":"widgetWebsiteToken","location":"body","name":"website_token","verification_boundary":"WebsiteTokenHelper#set_web_widget","algorithm":"opaque"},{"kind":"credential","scheme":"widgetContactJwt","location":"header","name":"X-Auth-Token","verification_boundary":"WebsiteTokenHelper#set_contact","algorithm":"JWT"}]}}},"/api/v1/widget/conversations/toggle_typing":{"post":{"tags":["Widget"],"operationId":"auto_post_api_v1_widget_conversations_toggle_typing","summary":"Broadcast the visitor typing status","description":"Broadcasts that the visitor started or stopped typing in the conversation they have open, so the typing indicator appears for the agents handling it. Any value other than on or off is accepted and broadcasts nothing. The response carries no body.","security":[{"widgetWebsiteToken":[],"widgetContactJwt":[]}],"responses":{"200":{"description":"Typing status broadcast. Empty body."},"404":{"description":"The visitor has no conversation open in this inbox."}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"typing_status":{"type":"string","enum":["on","off"],"description":"Typing indicator toggle."},"website_token":{"type":"string"},"email":{"type":"string","format":"email"},"contact":{"type":"object","additionalProperties":true,"description":"Free-form object."},"message":{"type":"object","additionalProperties":true,"description":"Free-form object."},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."}}},"example":{"id":1,"typing_status":"on","website_token":"sample-token","email":"agent@example.com","contact":{},"message":{},"custom_attributes":{}}}}},"x-authentication":{"kind":"all_of","branches":[{"kind":"credential","scheme":"widgetWebsiteToken","location":"body","name":"website_token","verification_boundary":"WebsiteTokenHelper#set_web_widget","algorithm":"opaque"},{"kind":"credential","scheme":"widgetContactJwt","location":"header","name":"X-Auth-Token","verification_boundary":"WebsiteTokenHelper#set_contact","algorithm":"JWT"}]}}},"/api/v1/widget/conversations/transcript":{"post":{"tags":["Widget"],"operationId":"auto_post_api_v1_widget_conversations_transcript","summary":"E-mail the widget conversation transcript","description":"Sends the transcript of the conversation the visitor has open to the e-mail address recorded for them. Nothing is sent when no address is known. The response carries no body.","security":[{"widgetWebsiteToken":[],"widgetContactJwt":[]}],"responses":{"200":{"description":"Transcript accepted for delivery, provided an e-mail address is known for the visitor. Empty body."},"402":{"description":"E-mail transcripts are not available for this account."},"429":{"description":"The visitor has no conversation open, or the account reached its e-mail rate limit for the current window."}},"x-authentication":{"kind":"all_of","branches":[{"kind":"credential","scheme":"widgetWebsiteToken","location":"body","name":"website_token","verification_boundary":"WebsiteTokenHelper#set_web_widget","algorithm":"opaque"},{"kind":"credential","scheme":"widgetContactJwt","location":"header","name":"X-Auth-Token","verification_boundary":"WebsiteTokenHelper#set_contact","algorithm":"JWT"}]}}},"/api/v1/widget/conversations/toggle_status":{"get":{"tags":["Widget"],"operationId":"auto_get_api_v1_widget_conversations_toggle_status","summary":"Let the visitor end the widget conversation","description":"Resolves the conversation the visitor has open, which is how the end-conversation button of the widget closes a chat. It only works while the inbox allows visitors to end conversations, and an already resolved conversation is left untouched. The response carries no body.","security":[{"widgetWebsiteToken":[],"widgetContactJwt":[]}],"responses":{"200":{"description":"Conversation resolved, or already resolved. Empty body."},"403":{"description":"This inbox does not allow visitors to end conversations."},"404":{"description":"The visitor has no conversation open in this inbox."}},"x-authentication":{"kind":"all_of","branches":[{"kind":"credential","scheme":"widgetWebsiteToken","location":"body","name":"website_token","verification_boundary":"WebsiteTokenHelper#set_web_widget","algorithm":"opaque"},{"kind":"credential","scheme":"widgetContactJwt","location":"header","name":"X-Auth-Token","verification_boundary":"WebsiteTokenHelper#set_contact","algorithm":"JWT"}]}}},"/api/v1/widget/conversations":{"get":{"tags":["Widget"],"operationId":"auto_get_api_v1_widget_conversations","summary":"List conversations","description":"Returns the list of conversations visible to the authenticated caller.","security":[{"widgetWebsiteToken":[],"widgetContactJwt":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"inbox_id":{"type":"integer"},"contact_last_seen_at":{"type":"integer"},"status":{"type":"string","enum":["open","resolved","pending","snoozed"]}}},"example":{"id":1,"inbox_id":1,"contact_last_seen_at":1,"status":"open"}}}}},"parameters":[{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."}],"x-authentication":{"kind":"all_of","branches":[{"kind":"credential","scheme":"widgetWebsiteToken","location":"body","name":"website_token","verification_boundary":"WebsiteTokenHelper#set_web_widget","algorithm":"opaque"},{"kind":"credential","scheme":"widgetContactJwt","location":"header","name":"X-Auth-Token","verification_boundary":"WebsiteTokenHelper#set_contact","algorithm":"JWT"}]}},"post":{"tags":["Widget"],"operationId":"auto_post_api_v1_widget_conversations","summary":"Create conversations","description":"Creates a new conversation from the request payload.","security":[{"widgetWebsiteToken":[],"widgetContactJwt":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"inbox_id":{"type":"integer"},"contact_last_seen_at":{"type":"integer"},"status":{"type":"string","enum":["open","resolved","pending","snoozed"]},"messages":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"content":{"type":"string"},"message_type":{"type":"string","enum":["incoming","outgoing","activity","template"],"description":"Direction/kind of the message."},"content_type":{"type":"string","enum":["text","input_text","input_textarea","input_email","input_select","cards","form","article","incoming_email","input_csat","integrations","sticker","voice_call","poll"],"description":"Structured content type of the message (drives how content_attributes is interpreted)."},"content_attributes":{"type":"object","additionalProperties":true,"description":"Structured metadata accompanying the message content; the key set depends on content_type (e.g. select items, CSAT submission values, deletion flags, external delivery errors)."},"created_at":{"type":"integer"},"conversation_id":{"type":"integer"},"attachments":{"type":"array","items":{"type":"string"}},"sender":{"type":"string"}}}},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"contact":{"type":"string"}}},"example":{"id":1,"inbox_id":1,"contact_last_seen_at":1,"status":"open","messages":[{"id":1,"content":"Sample content text.","message_type":"incoming","content_type":"text","content_attributes":{},"created_at":1,"conversation_id":1,"attachments":["sample attachment"],"sender":"sample sender"}],"custom_attributes":{},"contact":"sample contact"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"typing_status":{"type":"string","enum":["on","off"],"description":"Typing indicator toggle."},"website_token":{"type":"string"},"email":{"type":"string","format":"email"},"contact":{"type":"object","additionalProperties":true,"description":"Free-form object."},"message":{"type":"object","additionalProperties":true,"description":"Free-form object."},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."}}},"example":{"id":1,"typing_status":"on","website_token":"sample-token","email":"agent@example.com","contact":{},"message":{},"custom_attributes":{}}}}},"x-authentication":{"kind":"all_of","branches":[{"kind":"credential","scheme":"widgetWebsiteToken","location":"body","name":"website_token","verification_boundary":"WebsiteTokenHelper#set_web_widget","algorithm":"opaque"},{"kind":"credential","scheme":"widgetContactJwt","location":"header","name":"X-Auth-Token","verification_boundary":"WebsiteTokenHelper#set_contact","algorithm":"JWT"}]}}},"/api/v1/widget/contact/destroy_custom_attributes":{"post":{"tags":["Widget"],"operationId":"auto_post_api_v1_widget_contact_destroy_custom_attributes","summary":"Destroy custom attributes contacts","description":"Performs the destroy custom attributes operation on the targeted contact resource.","security":[{"widgetWebsiteToken":[],"widgetContactJwt":[]}],"responses":{"200":{"description":"Contact after removing a custom attribute (raw model attributes)","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer","example":55},"name":{"type":"string","example":"Jane Doe"},"email":{"type":["string","null"],"example":"jane@example.com"},"phone_number":{"type":["string","null"],"example":"+15550100100"},"account_id":{"type":"integer","example":1},"identifier":{"type":["string","null"],"example":"ext-123"},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"additional_attributes":{"type":"object","additionalProperties":true,"description":"Channel- and source-specific metadata for this record (e.g. browser info, referer, social profile identifiers). The key set depends on the originating channel."},"created_at":{"type":"string","format":"date-time","example":"2026-01-15T10:30:00.000Z"},"updated_at":{"type":"string","format":"date-time","example":"2026-01-15T10:30:00.000Z"}}},"example":{"id":55,"name":"Jane Doe","email":"jane@example.com","phone_number":"+15550100100","account_id":1,"identifier":"ext-123","custom_attributes":{},"additional_attributes":{},"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."}}},"example":{"custom_attributes":{}}}}},"x-authentication":{"kind":"all_of","branches":[{"kind":"credential","scheme":"widgetWebsiteToken","location":"body","name":"website_token","verification_boundary":"WebsiteTokenHelper#set_web_widget","algorithm":"opaque"},{"kind":"credential","scheme":"widgetContactJwt","location":"header","name":"X-Auth-Token","verification_boundary":"WebsiteTokenHelper#set_contact","algorithm":"JWT"}]}}},"/api/v1/widget/contact/set_user":{"patch":{"tags":["Widget"],"operationId":"auto_patch_api_v1_widget_contact_set_user","summary":"Set user contacts","description":"Performs the set user operation on the targeted contact resource.","security":[{"widgetWebsiteToken":[],"widgetContactJwt":[]}],"responses":{"200":{"description":"Contact identified (widget_auth_token present when a new token was issued)","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer","example":55},"has_email":{"type":"boolean","example":true},"has_name":{"type":"boolean","example":true},"has_phone_number":{"type":"boolean","example":false},"widget_auth_token":{"type":"string","description":"Present when a new contact/token was created","example":"eyJhbGciOiJIUzI1NiJ9..."}}},"example":{"id":55,"has_email":true,"has_name":true,"has_phone_number":false,"widget_auth_token":"eyJhbGciOiJIUzI1NiJ9..."}}}},"401":{"description":"Invalid identifier hash","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"HMAC failed: Invalid Identifier Hash Provided"}}},"example":{"error":"HMAC failed: Invalid Identifier Hash Provided"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"identifier":{"type":"string","example":"ext-123"},"identifier_hash":{"type":"string","description":"HMAC-SHA256 of identifier (required when HMAC enforced)","example":"9f86d081884c7d659a2feaa0c55ad015..."},"email":{"type":"string","example":"jane@example.com"},"name":{"type":"string","example":"Jane Doe"},"avatar_url":{"type":"string","example":"https://example.com/jane.png"},"phone_number":{"type":"string","example":"+15550100100"},"custom_attributes":{"type":"object","example":{"plan":"pro"},"additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"additional_attributes":{"type":"object","example":{"city":"Lisbon"},"additionalProperties":true,"description":"Channel- and source-specific metadata for this record (e.g. browser info, referer, social profile identifiers). The key set depends on the originating channel."}}},"example":{"identifier":"ext-123","identifier_hash":"9f86d081884c7d659a2feaa0c55ad015...","email":"jane@example.com","name":"Jane Doe","avatar_url":"https://example.com/jane.png","phone_number":"+15550100100","custom_attributes":{"plan":"pro"},"additional_attributes":{"city":"Lisbon"}}}}},"x-authentication":{"kind":"conditional","condition":"identifier_hash is present or the widget requires HMAC.","alternatives":[{"kind":"all_of","branches":[{"kind":"credential","scheme":"widgetWebsiteToken","location":"body","name":"website_token","verification_boundary":"WebsiteTokenHelper#set_web_widget","algorithm":"opaque"},{"kind":"credential","scheme":"widgetContactJwt","location":"header","name":"X-Auth-Token","verification_boundary":"WebsiteTokenHelper#set_contact","algorithm":"JWT"}]},{"kind":"all_of","branches":[{"kind":"all_of","branches":[{"kind":"credential","scheme":"widgetWebsiteToken","location":"body","name":"website_token","verification_boundary":"WebsiteTokenHelper#set_web_widget","algorithm":"opaque"},{"kind":"credential","scheme":"widgetContactJwt","location":"header","name":"X-Auth-Token","verification_boundary":"WebsiteTokenHelper#set_contact","algorithm":"JWT"}]},{"kind":"capability","scheme":"widgetContactHmac","location":"body","name":"identifier_hash","verification_boundary":"Api::V1::Widget::ContactsController#validate_hmac","algorithm":"HMAC-SHA256"}]}]}}},"/api/v1/widget/contact":{"get":{"tags":["Widget"],"operationId":"auto_get_api_v1_widget_contact","summary":"Get contacts","description":"Returns the contact identified by the path parameters.","security":[{"widgetWebsiteToken":[],"widgetContactJwt":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"has_email":{"type":"boolean"},"has_name":{"type":"boolean"},"has_phone_number":{"type":"boolean"},"identifier":{"type":"string"}}},"example":{"id":1,"has_email":true,"has_name":true,"has_phone_number":true,"identifier":"sample-identifier"}}}}},"x-authentication":{"kind":"all_of","branches":[{"kind":"credential","scheme":"widgetWebsiteToken","location":"body","name":"website_token","verification_boundary":"WebsiteTokenHelper#set_web_widget","algorithm":"opaque"},{"kind":"credential","scheme":"widgetContactJwt","location":"header","name":"X-Auth-Token","verification_boundary":"WebsiteTokenHelper#set_contact","algorithm":"JWT"}]}},"patch":{"tags":["Widget"],"operationId":"auto_patch_api_v1_widget_contact","summary":"Update contacts","description":"Updates the contact identified by the path parameters with the submitted attributes.","security":[{"widgetWebsiteToken":[],"widgetContactJwt":[]}],"responses":{"200":{"description":"Contact updated","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer","example":55},"has_email":{"type":"boolean","example":true},"has_name":{"type":"boolean","example":true},"has_phone_number":{"type":"boolean","example":false}}},"example":{"id":55,"has_email":true,"has_name":true,"has_phone_number":false}}}}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"identifier":{"type":"string","example":"ext-123"},"email":{"type":"string","example":"jane@example.com"},"name":{"type":"string","example":"Jane Doe"},"avatar_url":{"type":"string","example":"https://example.com/jane.png"},"phone_number":{"type":"string","example":"+15550100100"},"custom_attributes":{"type":"object","example":{"plan":"pro"},"additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"additional_attributes":{"type":"object","example":{"city":"Lisbon"},"additionalProperties":true,"description":"Channel- and source-specific metadata for this record (e.g. browser info, referer, social profile identifiers). The key set depends on the originating channel."}}},"example":{"identifier":"ext-123","email":"jane@example.com","name":"Jane Doe","avatar_url":"https://example.com/jane.png","phone_number":"+15550100100","custom_attributes":{"plan":"pro"},"additional_attributes":{"city":"Lisbon"}}}}},"x-authentication":{"kind":"all_of","branches":[{"kind":"credential","scheme":"widgetWebsiteToken","location":"body","name":"website_token","verification_boundary":"WebsiteTokenHelper#set_web_widget","algorithm":"opaque"},{"kind":"credential","scheme":"widgetContactJwt","location":"header","name":"X-Auth-Token","verification_boundary":"WebsiteTokenHelper#set_contact","algorithm":"JWT"}]}},"put":{"tags":["Widget"],"operationId":"auto_put_api_v1_widget_contact","summary":"Update contacts","description":"Updates the contact identified by the path parameters with the submitted attributes.","security":[{"widgetWebsiteToken":[],"widgetContactJwt":[]}],"responses":{"200":{"description":"Contact updated","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer","example":55},"has_email":{"type":"boolean","example":true},"has_name":{"type":"boolean","example":true},"has_phone_number":{"type":"boolean","example":false}}},"example":{"id":55,"has_email":true,"has_name":true,"has_phone_number":false}}}}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"identifier":{"type":"string","example":"ext-123"},"email":{"type":"string","example":"jane@example.com"},"name":{"type":"string","example":"Jane Doe"},"avatar_url":{"type":"string","example":"https://example.com/jane.png"},"phone_number":{"type":"string","example":"+15550100100"},"custom_attributes":{"type":"object","example":{"plan":"pro"},"additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"additional_attributes":{"type":"object","example":{"city":"Lisbon"},"additionalProperties":true,"description":"Channel- and source-specific metadata for this record (e.g. browser info, referer, social profile identifiers). The key set depends on the originating channel."}}},"example":{"identifier":"ext-123","email":"jane@example.com","name":"Jane Doe","avatar_url":"https://example.com/jane.png","phone_number":"+15550100100","custom_attributes":{"plan":"pro"},"additional_attributes":{"city":"Lisbon"}}}}},"x-authentication":{"kind":"all_of","branches":[{"kind":"credential","scheme":"widgetWebsiteToken","location":"body","name":"website_token","verification_boundary":"WebsiteTokenHelper#set_web_widget","algorithm":"opaque"},{"kind":"credential","scheme":"widgetContactJwt","location":"header","name":"X-Auth-Token","verification_boundary":"WebsiteTokenHelper#set_contact","algorithm":"JWT"}]}}},"/api/v1/widget/inbox_members":{"get":{"tags":["Widget"],"operationId":"auto_get_api_v1_widget_inbox_members","summary":"List inbox members","description":"Returns the list of inbox members visible to the authenticated caller.","security":[{"widgetWebsiteToken":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"avatar_url":{"type":"string"},"availability_status":{"type":["string","null"],"enum":["online","offline","busy",null],"description":"Realtime availability. Contacts report online/offline (presence-based); agents/users additionally report busy (their configured availability)."}}}}}},"example":{"payload":[{"id":1,"name":"Sample Name","avatar_url":"https://example.com/resource","availability_status":"online"}]}}}}},"parameters":[{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."}],"x-authentication":{"kind":"credential","scheme":"widgetWebsiteToken","location":"body","name":"website_token","verification_boundary":"WebsiteTokenHelper#set_web_widget","algorithm":"opaque"}}},"/api/v1/widget/labels":{"post":{"tags":["Widget"],"operationId":"auto_post_api_v1_widget_labels","summary":"Add a label to the widget conversation","description":"Adds a label to the conversation the visitor currently has open. The label must already exist in the account: a title that matches no account label is ignored, so the widget can never create labels. The response carries no body and does not distinguish the two outcomes.","security":[{"widgetWebsiteToken":[],"widgetContactJwt":[]}],"responses":{"204":{"description":"Request accepted; the label was added when it exists in the account. Empty body."}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"label":{"type":"string"},"website_token":{"type":"string"}}},"example":{"id":1,"label":"sample label","website_token":"sample-token"}}}},"x-authentication":{"kind":"all_of","branches":[{"kind":"credential","scheme":"widgetWebsiteToken","location":"body","name":"website_token","verification_boundary":"WebsiteTokenHelper#set_web_widget","algorithm":"opaque"},{"kind":"credential","scheme":"widgetContactJwt","location":"header","name":"X-Auth-Token","verification_boundary":"WebsiteTokenHelper#set_contact","algorithm":"JWT"}]}}},"/api/v1/widget/labels/{id}":{"delete":{"tags":["Widget"],"operationId":"auto_delete_api_v1_widget_labels_id","summary":"Delete labels","description":"Deletes the label identified by the path parameters.","security":[{"widgetWebsiteToken":[],"widgetContactJwt":[]}],"responses":{"204":{"description":"Success (no content)"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"x-authentication":{"kind":"all_of","branches":[{"kind":"credential","scheme":"widgetWebsiteToken","location":"body","name":"website_token","verification_boundary":"WebsiteTokenHelper#set_web_widget","algorithm":"opaque"},{"kind":"credential","scheme":"widgetContactJwt","location":"header","name":"X-Auth-Token","verification_boundary":"WebsiteTokenHelper#set_contact","algorithm":"JWT"}]}}},"/api/v1/widget/integrations/dyte/add_participant_to_meeting":{"post":{"tags":["Widget"],"operationId":"auto_post_api_v1_widget_integrations_dyte_add_participant_to_meeting","summary":"Add participant to meeting dyte","description":"Performs the add participant to meeting operation on the targeted dyte resource.","security":[{"widgetWebsiteToken":[],"widgetContactJwt":[]}],"responses":{"200":{"description":"Dyte participant auth token","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","example":"7f9a1b2c-3d4e-5f60-7182-9a0b1c2d3e4f"},"token":{"type":"string","description":"Dyte participant auth token","example":"sample-token"}}},"example":{"id":"7f9a1b2c-3d4e-5f60-7182-9a0b1c2d3e4f","token":"sample-token"}}}},"422":{"description":"Invalid message type or Dyte error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Invalid message type. Action not permitted"}}},"example":{"error":"Invalid message type. Action not permitted"}}}}},"x-authentication":{"kind":"all_of","branches":[{"kind":"credential","scheme":"widgetWebsiteToken","location":"body","name":"website_token","verification_boundary":"WebsiteTokenHelper#set_web_widget","algorithm":"opaque"},{"kind":"credential","scheme":"widgetContactJwt","location":"header","name":"X-Auth-Token","verification_boundary":"WebsiteTokenHelper#set_contact","algorithm":"JWT"}]}}},"/api/v2/accounts/{account_id}/summary_reports/label":{"get":{"tags":["Summary Reports"],"operationId":"auto_get_api_v2_accounts_account_id_summary_reports_label","summary":"Get per-label conversation summary","description":"One summary row per account label over the date range. Average metrics are in seconds (business-hours-adjusted when `business_hours=true`). Returns an empty array when the account has no labels.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Array of per-label summary rows.","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Label id.","example":17},"name":{"type":"string","description":"Label title.","example":"billing"},"conversations_count":{"type":"integer","example":84},"avg_resolution_time":{"type":"number","description":"Average resolution time in seconds.","example":5400.0},"avg_first_response_time":{"type":"number","description":"Average first response time in seconds.","example":320.5},"avg_reply_time":{"type":"number","description":"Average reply time in seconds.","example":210.0},"resolved_conversations_count":{"type":"integer","description":"Count of conversation_resolved events tagged with this label.","example":71}}}},"example":[{"id":17,"name":"billing","conversations_count":84,"avg_resolution_time":5400.0,"avg_first_response_time":320.5,"avg_reply_time":210.0,"resolved_conversations_count":71}]}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v2/accounts/{account_id}/reports/bot_summary":{"get":{"tags":["Reports"],"operationId":"auto_get_api_v2_accounts_account_id_reports_bot_summary","summary":"Get bot conversation summary metrics","description":"Aggregate bot metrics for the current period plus the equivalent previous period (window length = until - since, ending at since). Each value is an aggregate count over the selected date range. Requires report:view authorization.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Bot summary metrics for the current period with a nested previous-period block.","content":{"application/json":{"schema":{"type":"object","properties":{"bot_resolutions_count":{"type":"number","description":"Conversations resolved by the bot in the current period (handoffs excluded).","example":128},"bot_handoffs_count":{"type":"number","description":"Conversations handed off from the bot to a human agent in the current period.","example":42},"previous":{"type":"object","description":"Same metrics for the equivalent preceding period.","properties":{"bot_resolutions_count":{"type":"number","example":110},"bot_handoffs_count":{"type":"number","example":51}}}}},"example":{"bot_resolutions_count":128,"bot_handoffs_count":42,"previous":{"bot_resolutions_count":110,"bot_handoffs_count":51}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v2/accounts/{account_id}/reports/agents":{"get":{"tags":["Reports"],"operationId":"auto_get_api_v2_accounts_account_id_reports_agents","summary":"Download the agent report as CSV","description":"Streams an attachment `agents_report.csv`. First line is the reporting period. Columns: Agent name, Conversations count, Avg first response time, Avg resolution time, Avg customer waiting time, Resolution count. Requires `since`/`until` (epoch seconds) and report:view authorization.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"CSV attachment (Content-Disposition attachment; filename=agents_report.csv).","content":{"text/csv":{"schema":{"type":"string","format":"binary"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v2/accounts/{account_id}/reports/inboxes":{"get":{"tags":["Reports"],"operationId":"auto_get_api_v2_accounts_account_id_reports_inboxes","summary":"Download the inbox report as CSV","description":"Streams an attachment `inboxes_report.csv`. Columns: Inbox name, Inbox type, Conversations count, Avg first response time, Avg resolution time.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"CSV attachment (filename=inboxes_report.csv).","content":{"text/csv":{"schema":{"type":"string","format":"binary"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v2/accounts/{account_id}/reports/labels":{"get":{"tags":["Reports"],"operationId":"auto_get_api_v2_accounts_account_id_reports_labels","summary":"Download the label report as CSV","description":"Streams an attachment `labels_report.csv`. Columns: Label title, Conversations count, Avg first response time, Avg resolution time, Avg reply time, Resolution count.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"CSV attachment (filename=labels_report.csv).","content":{"text/csv":{"schema":{"type":"string","format":"binary"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v2/accounts/{account_id}/reports/teams":{"get":{"tags":["Reports"],"operationId":"auto_get_api_v2_accounts_account_id_reports_teams","summary":"Download the team report as CSV","description":"Streams an attachment `teams_report.csv`. Columns: Team name, Conversations count, Avg first response time, Avg resolution time, Avg customer waiting time, Resolution count.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"CSV attachment (filename=teams_report.csv).","content":{"text/csv":{"schema":{"type":"string","format":"binary"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v2/accounts/{account_id}/reports/conversations_summary":{"get":{"tags":["Reports"],"operationId":"auto_get_api_v2_accounts_account_id_reports_conversations_summary","summary":"Download the conversations summary report as CSV","description":"Streams an attachment `conversations_summary_report.csv`. Columns: Conversations count, Incoming messages count, Outgoing messages count, Avg first response time, Avg resolution time, Resolution count, Avg customer waiting time.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"CSV attachment (filename=conversations_summary_report.csv).","content":{"text/csv":{"schema":{"type":"string","format":"binary"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v2/accounts/{account_id}/reports/conversation_traffic":{"get":{"tags":["Reports"],"operationId":"auto_get_api_v2_accounts_account_id_reports_conversation_traffic","summary":"Download the conversation traffic (heatmap) report as CSV","description":"Streams an attachment `conversation_traffic_reports.csv`. First line is the timezone; the remaining rows are the hour-by-day conversation-volume heatmap. Accepts `timezone_offset` (float hours). Requires report:view authorization.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"CSV attachment (filename=conversation_traffic_reports.csv).","content":{"text/csv":{"schema":{"type":"string","format":"binary"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"timezone_offset","in":"query","required":false,"description":"Offset in hours from UTC used to bucket the traffic by local hour. Omitted, buckets are UTC.","schema":{"type":"number","default":0},"example":-3}]}},"/api/v2/accounts/{account_id}/reports/drilldown":{"get":{"tags":["Reports"],"operationId":"auto_get_api_v2_accounts_account_id_reports_drilldown","summary":"List the records behind one report bucket","description":"Expands a single point of a report time series into the underlying records, so a number in a chart can be traced to the conversations or messages that produced it. The bucket is identified by `bucket_timestamp` (the start of the bucket, epoch seconds) and is intersected with the requested `since`/`until` window, so the returned range is never wider than the report the user is looking at. Administrator only: a non-administrator receives 401. The request receives 422 with an empty body when `metric`, `bucket_timestamp`, `since` or `until` is missing; when any of those three timestamps is not a plain run of digits; when `since` is not strictly before `until`; when `metric` is not a supported metric; when `type` is not a supported dimension; or when the bucket the timestamp opens does not overlap the requested window.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The records inside the requested bucket, newest first, plus the pagination and bucket metadata needed to render the drilldown panel.","content":{"application/json":{"schema":{"type":"object","properties":{"meta":{"type":"object","description":"Bucket identity and pagination for the expanded records.","properties":{"metric":{"type":"string","description":"The metric that was expanded (echo of the request).","enum":["conversations_count","incoming_messages_count","outgoing_messages_count","avg_first_response_time","avg_resolution_time","reply_time","resolutions_count","bot_resolutions_count","bot_handoffs_count"],"example":"conversations_count"},"record_type":{"type":"string","description":"The kind of record this metric drills into. Message-shaped metrics (incoming/outgoing message counts, first response time, reply time) resolve to `message`; every other metric resolves to `conversation`.","enum":["message","conversation"],"example":"conversation"},"bucket":{"type":"object","description":"The effective bucket window, already clipped to the requested reporting window.","properties":{"since":{"type":"integer","description":"Inclusive start of the effective bucket, in epoch seconds.","example":1767225600},"until":{"type":"integer","description":"Exclusive end of the effective bucket, in epoch seconds.","example":1767312000}}},"current_page":{"type":"integer","description":"The page that was returned.","example":1},"per_page":{"type":"integer","description":"Page size actually applied (default 25, maximum 100).","example":25},"total_count":{"type":"integer","description":"Total records in the bucket across all pages.","example":137},"conversation_count":{"type":"integer","description":"Distinct conversations represented in the bucket. For `conversations_count` this equals `total_count`; for the other metrics several records can belong to the same conversation.","example":84}}},"payload":{"type":"array","description":"The expanded records, ordered newest first.","items":{"type":"object","properties":{"record_type":{"type":"string","description":"Whether this row carries a message (`message` is populated) or only a conversation (`message` is null).","enum":["message","conversation"],"example":"message"},"conversation":{"type":"object","description":"The conversation the record belongs to. Empty object when the record has no conversation attached.","properties":{"id":{"type":"integer","description":"Internal conversation identifier.","example":90210},"display_id":{"type":"integer","description":"Per-account conversation number shown in the UI.","example":1042},"contact_id":{"type":["integer","null"],"description":"Contact identifier, null when the conversation has no contact.","example":5533},"contact_name":{"type":["string","null"],"description":"Contact display name at read time.","example":"Ana Ribeiro"},"inbox_id":{"type":"integer","description":"Inbox the conversation belongs to.","example":12},"inbox_name":{"type":["string","null"],"description":"Inbox name at read time.","example":"Suporte WhatsApp"},"assignee_id":{"type":["integer","null"],"description":"Assigned agent identifier, null when unassigned.","example":7},"assignee_name":{"type":["string","null"],"description":"Assigned agent name, null when unassigned.","example":"Carla Souza"},"status":{"type":"string","description":"Conversation status at read time.","enum":["open","resolved","pending","snoozed"],"example":"resolved"},"created_at":{"type":"integer","description":"Conversation creation time, in epoch seconds.","example":1767229200},"last_activity_at":{"type":"integer","description":"Last activity on the conversation, in epoch seconds.","example":1767312000},"last_message":{"type":["object","null"],"description":"Most recent non-activity message of the conversation, for preview. Null when the conversation has only activity messages.","properties":{"id":{"type":"integer","description":"Message identifier.","example":778101},"content":{"type":["string","null"],"description":"Message text, null for attachment-only messages.","example":"Obrigado pelo retorno!"},"message_type":{"type":"string","description":"Direction/kind of the message.","enum":["incoming","outgoing","activity","template"],"example":"incoming"},"sender_name":{"type":["string","null"],"description":"Sender display name, null when the sender has no name or was deleted.","example":"Ana Ribeiro"},"created_at":{"type":"integer","description":"Message creation time, in epoch seconds.","example":1767311940}}}}},"message":{"type":["object","null"],"description":"The message this row points at. Populated for message-shaped metrics and for response/reply-time events whose originating message could be matched; null for conversation rows.","properties":{"id":{"type":"integer","description":"Message identifier.","example":778102},"content":{"type":["string","null"],"description":"Message text, null for attachment-only messages.","example":"Já estamos verificando, um instante."},"message_type":{"type":"string","description":"Direction/kind of the message.","enum":["incoming","outgoing","activity","template"],"example":"outgoing"},"sender_name":{"type":["string","null"],"description":"Sender display name, null when the sender has no name or was deleted.","example":"Carla Souza"},"created_at":{"type":"integer","description":"Message creation time, in epoch seconds.","example":1767311980}}},"metric_value":{"type":["number","null"],"description":"The reporting event's recorded value, in seconds (the business-hours value when `business_hours` was requested). Carried by every metric served from reporting events — the three averages and also `resolutions_count`, `bot_resolutions_count` and `bot_handoffs_count`, whose rows report the value of the event they were counted from. Null for `conversations_count`, `incoming_messages_count` and `outgoing_messages_count`, which are read straight from conversations and messages and have no per-record value.","example":42.0},"occurred_at":{"type":["integer","null"],"description":"When the record counted for this bucket, in epoch seconds — the event end time for reporting events, otherwise the record's creation time.","example":1767311980},"event_name":{"type":"string","description":"Present only on rows built from a reporting event that could not be resolved to a message. Names the underlying event.","enum":["first_response","conversation_resolved","reply_time","conversation_bot_resolved","conversation_bot_handoff"],"example":"conversation_resolved"}}}}}},"example":{"meta":{"metric":"conversations_count","record_type":"conversation","bucket":{"since":1767225600,"until":1767312000},"current_page":1,"per_page":25,"total_count":137,"conversation_count":84},"payload":[{"record_type":"message","conversation":{"id":90210,"display_id":1042,"contact_id":5533,"contact_name":"Ana Ribeiro","inbox_id":12,"inbox_name":"Suporte WhatsApp","assignee_id":7,"assignee_name":"Carla Souza","status":"resolved","created_at":1767229200,"last_activity_at":1767312000,"last_message":{"id":778101,"content":"Obrigado pelo retorno!","message_type":"incoming","sender_name":"Ana Ribeiro","created_at":1767311940}},"message":{"id":778102,"content":"Já estamos verificando, um instante.","message_type":"outgoing","sender_name":"Carla Souza","created_at":1767311980},"metric_value":42.0,"occurred_at":1767311980,"event_name":"conversation_resolved"}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"metric","in":"query","required":true,"description":"Report metric to expand. Determines whether the payload lists messages, conversations or reporting events.","schema":{"type":"string","enum":["conversations_count","incoming_messages_count","outgoing_messages_count","avg_first_response_time","avg_resolution_time","reply_time","resolutions_count","bot_resolutions_count","bot_handoffs_count"],"example":"conversations_count"}},{"name":"bucket_timestamp","in":"query","required":true,"description":"Start of the bucket to expand, in epoch seconds. Its length comes from `group_by`.","schema":{"type":"integer","example":1767225600}},{"name":"since","in":"query","required":true,"description":"Start of the reporting window in epoch seconds. The bucket is clipped to this bound.","schema":{"type":"integer","example":1767225600}},{"name":"until","in":"query","required":true,"description":"End of the reporting window in epoch seconds. The bucket is clipped to this bound.","schema":{"type":"integer","example":1769904000}},{"name":"type","in":"query","required":false,"description":"Dimension the report is scoped to. Defaults to `account`; every other value requires `id`.","schema":{"type":"string","enum":["account","inbox","agent","label","team"],"example":"account"}},{"name":"id","in":"query","required":false,"description":"Identifier of the dimension record (inbox, agent, label or team). Ignored when `type` is `account`.","schema":{"type":"integer","example":12}},{"name":"group_by","in":"query","required":false,"description":"Bucket length. Any other value falls back to `day`.","schema":{"type":"string","enum":["hour","day","week","month","year"],"example":"day"}},{"name":"timezone_offset","in":"query","required":false,"description":"Offset in hours used to resolve the bucket start into a local day/week/month boundary.","schema":{"type":"number","example":-3}},{"name":"business_hours","in":"query","required":false,"description":"When true, average metrics report the business-hours value instead of the wall-clock value.","schema":{"type":"boolean","example":false}},{"name":"page","in":"query","required":false,"description":"1-based page number. Values below 1 are raised to 1.","schema":{"type":"integer","minimum":1,"example":1}},{"name":"per_page","in":"query","required":false,"description":"Records per page. Defaults to 25 and is capped at 100.","schema":{"type":"integer","minimum":1,"maximum":100,"example":25}}]}},"/api/v2/accounts/{account_id}/reports/bot_metrics":{"get":{"tags":["Reports"],"operationId":"auto_get_api_v2_accounts_account_id_reports_bot_metrics","summary":"Get bot performance metrics","description":"Volume and effectiveness metrics for bot-activated inboxes over the date range. resolution_rate and handoff_rate are whole-number percentages (rounded down).","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Bot metrics for the selected range.","content":{"application/json":{"schema":{"type":"object","properties":{"conversation_count":{"type":"integer","description":"Conversations in bot-activated inboxes created in the range.","example":320},"message_count":{"type":"integer","description":"Outgoing messages in those conversations within the range.","example":1480},"resolution_rate":{"type":"integer","description":"Percentage of bot conversations resolved by the bot (0-100).","example":62},"handoff_rate":{"type":"integer","description":"Percentage of bot conversations handed off to a human (0-100).","example":18}}},"example":{"conversation_count":320,"message_count":1480,"resolution_rate":62,"handoff_rate":18}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v2/accounts/{account_id}/year_in_review":{"get":{"tags":["Year In Review"],"operationId":"auto_get_api_v2_accounts_account_id_year_in_review","summary":"Get the agent Year in Review summary","description":"Personalized year summary for the current user (defaults to year 2025). The result is cached in the user's ui_settings and returned verbatim on subsequent calls.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Year in review payload for the current user.","content":{"application/json":{"schema":{"type":"object","properties":{"year":{"type":"integer","example":2025},"total_conversations":{"type":"integer","description":"Conversations assigned to the user created in the year.","example":1240},"busiest_day":{"type":["object","null"],"description":"Day with the most assigned conversations (null when none).","properties":{"date":{"type":"string","description":"Formatted as \"%b %d\".","example":"Jan 15"},"count":{"type":"integer","example":27}}},"support_personality":{"type":"object","properties":{"avg_response_time_seconds":{"type":"integer","description":"Average first-response time (seconds) across the year; 0 when none.","example":184}}}}},"example":{"year":2025,"total_conversations":1240,"busiest_day":{"date":"Jan 15","count":27},"support_personality":{"avg_response_time_seconds":184}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"year","in":"query","required":false,"description":"Calendar year the review is built for. Omitted, the shipped default year is used.","schema":{"type":"integer"},"example":2026}]}},"/api/v2/accounts/{account_id}/live_reports/conversation_metrics":{"get":{"tags":["Live Reports"],"operationId":"auto_get_api_v2_accounts_account_id_live_reports_conversation_metrics","summary":"Conversation metrics live reports","description":"Performs the conversation metrics operation on the targeted live report resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"open":{"type":"integer"},"unattended":{"type":"integer"},"unassigned":{"type":"integer"},"pending":{"type":"integer"}}},"example":{"open":1,"unattended":1,"unassigned":1,"pending":1}}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v2/accounts/{account_id}/live_reports/grouped_conversation_metrics":{"get":{"tags":["Live Reports"],"operationId":"auto_get_api_v2_accounts_account_id_live_reports_grouped_conversation_metrics","summary":"Get live conversation metrics grouped by team or assignee","description":"Real-time open-conversation counts grouped by `group_by` (must be `team_id` or `assignee_id`; anything else -\u003e 422). Each element carries the grouping id under a key matching `group_by` (only one of team_id/assignee_id is present per response).","security":[{"userApiKey":[]}],"responses":{"200":{"description":"One entry per group.","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"open":{"type":"integer","description":"Open conversations in this group.","example":12},"unattended":{"type":"integer","description":"Open + unattended conversations in this group.","example":3},"unassigned":{"type":"integer","description":"Open + unassigned conversations in this group.","example":2},"team_id":{"type":["integer","null"],"description":"Present when group_by=team_id (the grouping key).","example":5},"assignee_id":{"type":["integer","null"],"description":"Present when group_by=assignee_id (the grouping key).","example":null}}}},"example":[{"open":12,"unattended":3,"unassigned":2,"team_id":5,"assignee_id":null}]}}},"401":{"description":"Unauthorized"},"404":{"description":"Account or resource not found"},"422":{"description":"Invalid group_by (not team_id or assignee_id).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"invalid group_by"}}},"example":{"error":"invalid group_by"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v2/accounts":{"post":{"tags":["Account"],"operationId":"auto_post_api_v2_accounts","summary":"Create an account (signup)","description":"Public signup endpoint (only when account signup is enabled). Provisions a user + account via AccountBuilder, sets Devise auth headers on the response, and returns the new user with the accounts they belong to. Requires a valid hCaptcha token when captcha is enabled.","security":[{"userApiKey":[]},{}],"responses":{"200":{"description":"Created user with associated accounts (Devise auth headers are set on the response).","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"integer","example":12},"provider":{"type":"string","example":"email","enum":["email","google_oauth2","saml"],"description":"Authentication provider the user signed up through."},"uid":{"type":"string","example":"owner@acme.com"},"name":{"type":"string","example":"Alex Owner"},"display_name":{"type":["string","null"],"example":"Alex"},"email":{"type":"string","example":"owner@acme.com"},"account_id":{"type":"integer","example":1},"created_at":{"type":"string","format":"date-time","example":"2026-01-15T10:30:00.000Z"},"pubsub_token":{"type":"string","example":"xkcd1234pubsubtoken"},"role":{"type":"string","enum":["administrator","agent"],"example":"administrator"},"inviter_id":{"type":["integer","null"],"example":null},"confirmed":{"type":"boolean","example":false},"avatar_url":{"type":"string","example":""},"access_token":{"type":"string","example":"sample-access-token"},"accounts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","example":1},"name":{"type":"string","example":"Acme Support"},"active_at":{"type":["string","null"],"format":"date-time","example":"2026-01-15T10:30:00.000Z"},"role":{"type":"string","enum":["administrator","agent"],"example":"administrator"},"locale":{"type":"string","example":"en"}}}}}}}},"example":{"data":{"id":12,"provider":"email","uid":"owner@acme.com","name":"Alex Owner","display_name":"Alex","email":"owner@acme.com","account_id":1,"created_at":"2026-01-15T10:30:00.000Z","pubsub_token":"xkcd1234pubsubtoken","role":"administrator","inviter_id":null,"confirmed":false,"avatar_url":"","access_token":"sample-access-token","accounts":[{"id":1,"name":"Acme Support","active_at":"2026-01-15T10:30:00.000Z","role":"administrator","locale":"en"}]}}}}},"403":{"description":"Signup failed / invalid email / user already exists. Rendered via RequestExceptionHandler#render_error_response with CustomExceptions::Base#http_status (403 Forbidden).","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"Signup failed"}}},"example":{"message":"Signup failed"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"account_name":{"type":"string","example":"Acme Support"},"email":{"type":"string","format":"email","example":"owner@acme.com"},"name":{"type":"string","example":"Acme"},"password":{"type":"string","format":"password","example":"sample-password"},"locale":{"type":"string","example":"en"},"domain":{"type":"string","example":"acme.com"},"support_email":{"type":"string","format":"email","example":"help@acme.com"},"user_full_name":{"type":"string","example":"Alex Owner"},"h_captcha_client_response":{"type":"string","description":"hCaptcha client response token (required when captcha is enabled).","example":"10000000-aaaa-bbbb-cccc-000000000001"}}},"example":{"account_name":"Acme Support","email":"owner@acme.com","name":"Acme","password":"sample-password","locale":"en","domain":"acme.com","support_email":"help@acme.com","user_full_name":"Alex Owner","h_captcha_client_response":"10000000-aaaa-bbbb-cccc-000000000001"}}}}}},"/enterprise/webhooks/stripe":{"post":{"tags":["Stripe"],"operationId":"auto_post_enterprise_webhooks_stripe","summary":"Receive a signed Stripe billing event","description":"Verifies `Stripe-Signature` against the installation webhook secret before reconciling supported subscription lifecycle events. Unsupported but validly signed event types are acknowledged without changing billing state.","security":[{"stripeWebhookSignature":[]}],"responses":{"200":{"description":"Signature verified and event acknowledged with an empty response body."},"400":{"description":"Missing/invalid signature or malformed JSON payload."}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"required":["id","object","type","data"],"properties":{"id":{"type":"string","minLength":1},"object":{"type":"string","enum":["event"]},"api_version":{"type":["string","null"]},"created":{"type":"integer","minimum":0},"livemode":{"type":"boolean"},"pending_webhooks":{"type":"integer","minimum":0},"type":{"type":"string","minLength":1,"description":"Stripe event type; subscription update/delete events are reconciled locally."},"data":{"type":"object","additionalProperties":true,"required":["object"],"properties":{"object":{"type":"object","additionalProperties":true,"description":"Provider-owned Stripe resource snapshot."},"previous_attributes":{"type":"object","additionalProperties":true,"description":"Changed fields supplied for update events."}}}}},"example":{"id":"sample id","object":"event","api_version":"sample api version","created":1,"livemode":true,"pending_webhooks":1,"type":"sample type","data":{"object":{},"previous_attributes":{}}}}}},"parameters":[{"name":"Stripe-Signature","in":"header","required":true,"description":"Stripe timestamped signature over the exact raw request body.","schema":{"type":"string","minLength":1}}],"x-authentication":{"kind":"credential","scheme":"stripeWebhookSignature","location":"header","name":"Stripe-Signature","verification_boundary":"Stripe timestamped raw-body verifier","algorithm":"HMAC-SHA256"}}},"/enterprise/webhooks/firecrawl":{"post":{"tags":["Firecrawl"],"operationId":"auto_post_enterprise_webhooks_firecrawl","summary":"Receive a Firecrawl crawl event","description":"Verifies the assistant-scoped webhook token before acknowledging the provider event. `crawl.page` events enqueue the first page payload for asynchronous document ingestion; other verified event types are acknowledged without enqueueing page content.","security":[],"responses":{"200":{"description":"Event verified and acknowledged with an empty response body."},"401":{"description":"The assistant-scoped webhook token is absent or invalid.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string"}}},"example":{"error":"sample error"}}}},"404":{"description":"The referenced assistant does not exist."}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["type"],"properties":{"type":{"type":"string","minLength":1,"description":"Provider event type; `crawl.page` carries ingestible page data."},"data":{"type":"array","minItems":1,"description":"Page payloads supplied for a `crawl.page` event.","items":{"type":"object","additionalProperties":false,"properties":{"markdown":{"type":"string"},"metadata":{"type":"object","additionalProperties":true,"description":"Free-form metadata bag; the key set depends on the record and context."}}}},"success":{"type":"boolean"},"id":{"type":"string"},"metadata":{"type":"object","additionalProperties":true,"description":"Free-form metadata bag; the key set depends on the record and context."},"format":{"type":"string"},"firecrawl":{"type":"string"}}},"example":{"type":"sample type","data":[{"markdown":"sample markdown","metadata":{}}],"success":true,"id":"sample id","metadata":{},"format":"sample format","firecrawl":"sample firecrawl"}}}},"parameters":[{"name":"assistant_id","in":"query","required":true,"description":"Assistant that owns the crawl and against which the token is verified.","schema":{"type":"integer","minimum":1}},{"name":"token","in":"query","required":true,"description":"Assistant-scoped Firecrawl webhook verification capability.","schema":{"type":"string","minLength":1}}],"x-authentication":{"kind":"capability","scheme":"firecrawlWebhookToken","location":"query","name":"token","verification_boundary":"Firecrawl webhook token verifier","algorithm":"opaque"}}},"/platform/api/v1/accounts/{id}/setup":{"get":{"tags":["Platform Accounts"],"operationId":"auto_get_platform_api_v1_accounts_id_setup","summary":"Follow an account's provisioning run","description":"Operator/integrator view of the generative-onboarding run created by the one-call account POST (or by the account itself). Same payload contract as the account-side GET setup: headline status + per-item ledger; `{\"status\": \"none\"}` when the account never ran a setup. Requires the account to be permissible to the platform app.","security":[{"platformAppApiKey":[]}],"responses":{"200":{"description":"The latest run (or the cold shape when none exists) — same contract as the account-side GET setup.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":["integer","null"],"description":"Run id."},"status":{"type":"string","enum":["none","pending","running","completed","partial","failed","canceled"],"description":"Run lifecycle."},"source":{"type":"string","enum":["maestro","template","merged","api","clone"],"description":"Where the blueprint came from."},"mode":{"type":"string","enum":["autonomous","interactive","api"],"description":"How the run was driven."},"template_key":{"type":["string","null"],"description":"Vertical template used as the base."},"stats":{"type":"object","additionalProperties":true,"description":"Per-section counters keyed by section name."},"report":{"type":"object","additionalProperties":true,"description":"Run report (warnings, generating, fallback, teardown summary)."},"draft":{"type":"boolean","description":"True while the run is a generated blueprint awaiting review/apply."},"blueprint":{"type":["object","null"],"additionalProperties":true,"description":"The generated SetupBlueprint — present only while draft is true."},"error":{"type":["string","null"],"description":"Engine-level failure message."},"started_at":{"type":["string","null"],"format":"date-time"},"finished_at":{"type":["string","null"],"format":"date-time"},"updated_at":{"type":["string","null"],"format":"date-time"},"items":{"type":"array","description":"The provisioning ledger in application order.","items":{"type":"object","properties":{"id":{"type":"integer"},"section":{"type":"string","description":"Blueprint section the item belongs to."},"key":{"type":"string","description":"The item's stable slug (idempotency key)."},"name":{"type":"string","description":"Human display name."},"status":{"type":"string","enum":["pending","applied","skipped","failed"],"description":"Ledger state of the item."},"error":{"type":["string","null"]},"record_type":{"type":["string","null"],"description":"Class of the materialized record."},"record_id":{"type":["integer","null"]}}}}}},"example":{"id":12,"status":"completed","source":"template","mode":"api","template_key":"ecommerce","stats":{"labels":{"applied":6},"teams":{"applied":2}},"report":{},"draft":false,"blueprint":null,"error":null,"started_at":"2026-07-17T12:00:00.000Z","finished_at":"2026-07-17T12:00:41.000Z","updated_at":"2026-07-17T12:00:41.000Z","items":[{"id":301,"section":"labels","key":"vip","name":"vip","status":"applied","error":null,"record_type":"Label","record_id":88}]}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/platform/api/v1/accounts/{id}/usage":{"get":{"tags":["Platform Accounts"],"operationId":"auto_get_platform_api_v1_accounts_id_usage","summary":"Get an account's monthly usage (operator)","description":"Operator-side consumption read for billing/alerting: monthly buckets per metric plus the configured `\u003cmetric\u003e_monthly` limits. Unlike the account endpoint, this works regardless of the account's metering feature flag (the operator meters). `months` selects the window (1–12, default 3). Requires the account to be permissible to the platform app.","security":[{"platformAppApiKey":[]}],"responses":{"200":{"description":"Monthly buckets, newest month first.","content":{"application/json":{"schema":{"type":"object","properties":{"metrics":{"type":"array","description":"The complete metric set.","items":{"type":"string","enum":["messages","conversations","contacts","ai_requests","ai_tokens"]}},"limits":{"type":"object","additionalProperties":true,"description":"The account's `\u003cmetric\u003e_monthly` limit entries (only configured ones appear)."},"usage":{"type":"object","additionalProperties":true,"description":"Buckets keyed by `YYYY-MM`, each an object of metric → accumulated value."}}},"example":{"metrics":["messages","conversations","contacts","ai_requests","ai_tokens"],"limits":{"messages_monthly":10000},"usage":{"2026-07":{"messages":4210,"conversations":380,"contacts":129,"ai_requests":77,"ai_tokens":91240}}}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"months","in":"query","required":false,"description":"How many months of history to return, clamped to 1-12. Omitted or blank returns 3 months.","schema":{"type":"integer","default":3},"example":6}]}},"/platform/api/v1/accounts/{account_id}/email_channel_migrations":{"post":{"tags":["Platform Accounts"],"operationId":"auto_post_platform_api_v1_accounts_account_id_email_channel_migrations","summary":"Migrate managed email channels for a permissible account","description":"Creates up to 25 Google or Microsoft email channels and their inboxes for an Account explicitly permissible to the PlatformApp. The server fixes the IMAP destination to the selected managed provider (Google: imap.gmail.com; Microsoft: outlook.office365.com), port 993 and TLS. `imap_address`, `imap_port` and `imap_enable_ssl` are not accepted and return 422 `managed_provider_imap_settings`; this bulk provisioning endpoint cannot create an arbitrary network destination for the mail worker.","security":[{"platformAppApiKey":[]}],"responses":{"200":{"description":"One result for each requested mailbox. A failed individual mailbox does not roll back independent successful migrations in the same batch.","content":{"application/json":{"schema":{"type":"object","required":["results"],"properties":{"results":{"type":"array","description":"Per-mailbox migration outcomes in input order.","items":{"type":"object","required":["email","status"],"properties":{"email":{"type":"string","format":"email","description":"Mailbox from the corresponding request entry."},"status":{"type":"string","enum":["success","error"],"description":"Whether this mailbox and its inbox were created."},"inbox_id":{"type":"integer","description":"Created inbox ID; present only when status is success."},"channel_id":{"type":"integer","description":"Created email-channel ID; present only when status is success."},"message":{"type":"string","description":"Sanitized failure reason; present only when status is error."}}}}}},"example":{"results":[{"email":"support@example.com","status":"success","inbox_id":7,"channel_id":22,"message":"Sample message text."}]}}}},"401":{"description":"Missing/invalid PlatformApp credential, or the Account is not permissible to it.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}},"example":{"error":"Non permissible resource"}}}},"403":{"description":"Email channel migration is disabled for this installation.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["Email channel migration is not enabled"]}}},"example":{"error":"Email channel migration is not enabled"}}}},"422":{"description":"The batch is missing, exceeds 25 entries, or tried to override managed IMAP host, port or TLS settings. No channel is created for a request rejected at this boundary.","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"error":{"type":"string","enum":["managed_provider_imap_settings"]},"attributes":{"type":"array","items":{"type":"string","enum":["imap_address","imap_port","imap_enable_ssl"]}}}},{"type":"object","properties":{"error":{"type":"string"}}}]},"examples":{"managed_imap_settings":{"value":{"error":"managed_provider_imap_settings","attributes":["imap_address","imap_port","imap_enable_ssl"]}},"too_many_migrations":{"value":{"error":"Too many migrations (max 25)","attributes":["imap_address"]}}}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/platform_email_channel_migration_create_payload"},"example":{"migrations":[{"email":"support@example.com","provider":"google","inbox_name":"Migrated Support","imap_enabled":true,"imap_login":"support@example.com","provider_config":{"access_token":"sample-access-token","refresh_token":"sample-refresh-token","expires_on":"2026-09-01T12:00:00Z"}}]}}}}}},"/platform/api/v1/mcp":{"get":{"tags":["Platform Mcp"],"operationId":"auto_get_platform_api_v1_mcp","summary":"Open the platform MCP event stream (not available — stateless server)","description":"GET is reserved by the Streamable HTTP transport for the server-initiated SSE stream, which requires a session. The platform MCP server runs stateless, so no session exists and every GET is answered with a JSON-RPC \"Method not allowed\" error under HTTP 405. Use POST for all MCP traffic. There is no success response: the route never returns 2xx.","security":[{"platformAppApiKey":[]}],"responses":{"405":{"description":"Method not allowed — the SSE stream is unavailable on a stateless MCP server.","content":{"application/json":{"schema":{"type":"object","required":["jsonrpc"],"properties":{"jsonrpc":{"type":"string","enum":["2.0"],"description":"JSON-RPC protocol version — always \"2.0\".","example":"2.0"},"id":{"type":["integer","null"],"description":"Always null — a GET carries no JSON-RPC request id.","example":null},"error":{"type":"object","description":"JSON-RPC error object.","properties":{"code":{"type":"integer","description":"JSON-RPC invalid-request code.","example":-32600},"message":{"type":"string","example":"Method not allowed"}}}}},"example":{"jsonrpc":"2.0","id":null,"error":{"code":-32600,"message":"Method not allowed"}}}}},"401":{"description":"Missing or invalid Platform App access token."},"404":{"description":"The MCP server is disabled for this installation.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Why the MCP server is unavailable.","example":"MCP server is disabled on this installation"}}},"example":{"error":"MCP server is disabled on this installation"}}}}},"parameters":[{"$ref":"#/components/parameters/mcp_protocol_version"},{"$ref":"#/components/parameters/mcp_modern_method"},{"$ref":"#/components/parameters/mcp_modern_name"}]},"delete":{"tags":["Platform Mcp"],"operationId":"auto_delete_platform_api_v1_mcp","summary":"Terminate the platform MCP session (no-op)","description":"MCP clients call DELETE to end a session. The platform MCP server is stateless — no session is ever issued — so the call is acknowledged as a no-op. If an `MCP-Protocol-Version` header is sent it must name a supported protocol version, otherwise the transport answers 400.","security":[{"platformAppApiKey":[]}],"responses":{"204":{"description":"Success (no content)"},"200":{"description":"Teardown acknowledged (no-op — the server holds no session state).","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Always true — a stateless server has no session to discard.","example":true}}},"example":{"success":true}}}},"400":{"description":"The `MCP-Protocol-Version` header names a protocol version this server does not support.","content":{"application/json":{"schema":{"type":"object","properties":{"jsonrpc":{"type":"string","enum":["2.0"],"example":"2.0"},"id":{"type":["integer","null"],"description":"Always null — a DELETE carries no JSON-RPC request id.","example":null},"error":{"type":"object","description":"JSON-RPC error object.","properties":{"code":{"type":"integer","example":-32600},"message":{"type":"string","example":"Bad Request: Unsupported protocol version"}}}}},"example":{"jsonrpc":"2.0","id":null,"error":{"code":-32600,"message":"Bad Request: Unsupported protocol version"}}}}},"401":{"description":"Missing or invalid Platform App access token."}},"parameters":[{"$ref":"#/components/parameters/mcp_protocol_version"},{"$ref":"#/components/parameters/mcp_modern_method"},{"$ref":"#/components/parameters/mcp_modern_name"}]},"post":{"tags":["Platform Mcp"],"operationId":"auto_post_platform_api_v1_mcp","summary":"Call the platform MCP server (JSON-RPC)","description":"Model Context Protocol endpoint for platform provisioning. The body is a single JSON-RPC 2.0 message (`initialize`, `tools/list`, `tools/call`, `resources/*`). Authenticate with a Platform App access token — a user token is rejected. The tools are the platform catalog (account, user and agent-bot provisioning); every `tools/call` is replayed through the real platform endpoint, so the Platform App permissible checks apply exactly as they do on the REST API. This is a Streamable HTTP MCP protocol transport, not a REST tool collection. Legacy clients negotiate in `initialize.params.protocolVersion`; modern 2026-07-28 clients send the documented MCP headers and matching `_meta` envelope fields. The transport is stateless: each POST is self-contained. Legacy requests send `Accept: application/json`; modern 2026-07-28 requests must send `Accept: application/json, text/event-stream`. A request is capped at 1 MiB and a chunked request body is rejected before authentication or dispatch. When `initialize` negotiates protocol `2025-11-25`, `result.serverInfo` contains safe installation branding as described by `mcp_initialize_result`; clients can cache or choose not to render its optional visual fields.","security":[{"platformAppApiKey":[]}],"responses":{"204":{"description":"Success (no content)"},"200":{"description":"JSON-RPC 2.0 response from the platform MCP server (`result` on success, `error` on failure).","content":{"application/json":{"schema":{"type":"object","required":["jsonrpc"],"properties":{"jsonrpc":{"type":"string","enum":["2.0"],"description":"JSON-RPC protocol version — always \"2.0\".","example":"2.0"},"id":{"type":["integer","null"],"description":"The id of the request this responds to.","example":1},"result":{"anyOf":[{"$ref":"#/components/schemas/mcp_initialize_result"},{"type":"object","additionalProperties":true,"description":"Result object for another supported MCP method, such as tools/list or resources/read."}],"description":"The method result, shaped by the method — e.g. `{ \"tools\": [...] }` for `tools/list`. For `initialize`, see `mcp_initialize_result`, including optional title, websiteUrl and icons. Absent when `error` is present.","example":{}},"error":{"type":["object","null"],"description":"JSON-RPC error object. Absent on success.","properties":{"code":{"type":"integer","description":"JSON-RPC error code (-32600 invalid request, -32601 not found, -32603 internal error).","example":-32601},"message":{"type":"string","description":"Human-readable error message.","example":"Method not found"}}}}},"example":{"jsonrpc":"2.0","id":1,"result":{"tools":[{"name":"platform_accounts_create","description":"Create an account"}],"nextCursor":null,"protocolVersion":"2025-11-25","capabilities":{"tools":{"listChanged":false}},"serverInfo":{"name":"exampleco","version":"1.0.0","title":"ExampleCo Account MCP","description":"ExampleCo Account MCP server.","websiteUrl":"https://app.example.com","icons":[{"src":"https://app.example.com/brand-assets/logo_thumbnail.svg","mimeType":"image/svg+xml","sizes":["512x512"],"theme":"dark"},{"src":"https://app.example.com/brand-assets/logo.svg","mimeType":"image/svg+xml","theme":"light","sizes":["512x512"]},{"src":"https://app.example.com/brand-assets/logo_dark.svg","mimeType":"image/svg+xml","theme":"dark","sizes":["512x512"]}]}},"error":null}}}},"202":{"description":"Notification accepted (a JSON-RPC message without an `id`). No response body."},"400":{"description":"A modern request used an unsupported MCP-Protocol-Version (-32022) or inconsistent mirrored routing headers/body values (-32020).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/mcp_modern_transport_error"},"example":{"jsonrpc":"2.0","id":1,"error":{"code":-32022,"message":"Unsupported protocol version","data":{"supported":["2026-07-28"],"requested":"2099-01-01"}}}}}},"401":{"description":"Missing or invalid Platform App access token (a user token is rejected here). The `WWW-Authenticate` header advertises the Protected Resource Metadata."},"413":{"description":"The JSON-RPC request or generated transport response exceeds the 1 MiB MCP transport limit. An oversized request is rejected before authentication or dispatch; inspect the underlying resource or audit trail before retrying a write after an oversized generated response.","headers":{"Cache-Control":{"description":"MCP transport errors must not be stored by an intermediary.","schema":{"type":"string","enum":["no-store"],"example":"no-store"}}},"content":{"application/json":{"schema":{"type":"object","required":["error"],"additionalProperties":false,"properties":{"error":{"type":"string","enum":["MCP payload exceeds the supported size"],"example":"MCP payload exceeds the supported size"}}},"example":{"error":"MCP payload exceeds the supported size"}}}},"404":{"description":"The MCP server is disabled, or an authenticated modern client requested `subscriptions/listen`. This per-request stateless deployment rejects that process-local streaming method explicitly with JSON-RPC -32601.","content":{"application/json":{"schema":{"oneOf":[{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Why the MCP server is unavailable.","example":"MCP server is disabled on this installation"}}},{"$ref":"#/components/schemas/mcp_stateless_subscription_error"}]},"example":{"jsonrpc":"2.0","id":73,"error":{"code":-32601,"message":"Method not found","data":"subscriptions/listen is unavailable on this stateless transport"}}}}}},"requestBody":{"required":true,"description":"A single JSON-RPC 2.0 request or notification (Model Context Protocol).","content":{"application/json":{"schema":{"type":"object","required":["jsonrpc","method"],"properties":{"jsonrpc":{"type":"string","enum":["2.0"],"description":"JSON-RPC protocol version — always \"2.0\".","example":"2.0"},"id":{"type":["integer","null"],"description":"Request id echoed back on the response. Omit it to send a notification (202, no body).","example":1},"method":{"type":"string","description":"The MCP method to invoke — e.g. `initialize`, `tools/list`, `tools/call`, `resources/list`, `resources/read`, `ping`.","example":"tools/list"},"params":{"type":"object","additionalProperties":true,"description":"Method parameters, shaped by the method (`{}` or omitted for `tools/list`).","example":{}}}},"example":{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}}}},"parameters":[{"$ref":"#/components/parameters/mcp_protocol_version"},{"$ref":"#/components/parameters/mcp_modern_method"},{"$ref":"#/components/parameters/mcp_modern_name"}]}},"/public/api/v1/csat_survey/{id}":{"get":{"tags":["Public CSAT Survey"],"operationId":"auto_get_public_api_v1_csat_survey_id","summary":"Get csat survey","description":"Returns the csat survey identified by the path parameters.","security":[],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"csat_survey_response":{"type":"string"},"display_type":{"type":"string","enum":["emoji","star"],"description":"The visual style of the CSAT rating widget."},"content":{"type":"string"},"inbox_avatar_url":{"type":"string"},"inbox_name":{"type":"string"},"locale":{"type":"string"},"conversation_id":{"type":"integer"},"created_at":{"type":"string","format":"date-time"}}},"example":{"id":1,"csat_survey_response":"sample csat survey response","display_type":"emoji","content":"Sample content text.","inbox_avatar_url":"https://example.com/resource","inbox_name":"sample inbox name","locale":"en","conversation_id":1,"created_at":"2026-01-15T10:30:00.000Z"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]},"patch":{"tags":["Public CSAT Survey"],"operationId":"auto_patch_public_api_v1_csat_survey_id","summary":"Submit or update a CSAT survey response (public)","description":"Public endpoint used by the survey page to record the customer's rating and feedback on the conversation's input_csat message. Locked 14 days after the message was created (returns 422). The `{id}` path param is the conversation UUID.","security":[],"responses":{"200":{"description":"Updated CSAT message with the embedded survey response.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer","example":9021},"csat_survey_response":{"type":["object","null"],"description":"The persisted survey response (rating + feedback).","properties":{"id":{"type":"integer","example":55},"rating":{"type":"integer","example":5},"feedback_message":{"type":"string","example":"Excellent support!"}}},"display_type":{"type":"string","description":"CSAT widget display style.","example":"emoji","enum":["emoji","star"]},"content":{"type":["string","null"],"description":"CSAT prompt message configured on the inbox.","example":"Please rate your conversation"},"inbox_avatar_url":{"type":"string","example":"https://cdn.example.com/inbox/avatar.png"},"inbox_name":{"type":"string","example":"Website Support"},"locale":{"type":"string","example":"en"},"conversation_id":{"type":"integer","example":812},"created_at":{"type":"string","format":"date-time","example":"2026-01-15T10:30:00.000Z"}}},"example":{"id":9021,"csat_survey_response":{"id":55,"rating":5,"feedback_message":"Excellent support!"},"display_type":"emoji","content":"Please rate your conversation","inbox_avatar_url":"https://cdn.example.com/inbox/avatar.png","inbox_name":"Website Support","locale":"en","conversation_id":812,"created_at":"2026-01-15T10:30:00.000Z"}}}},"422":{"description":"Survey locked (more than 14 days after the message was created).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"You cannot update the CSAT survey after 14 days"}}},"example":{"error":"You cannot update the CSAT survey after 14 days"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"object","properties":{"submitted_values":{"type":"array","description":"Submitted values for the CSAT message.","items":{"type":"object","properties":{"name":{"type":"string","example":"rating"},"title":{"type":"string","example":"How was your experience?"},"value":{"description":"Free-form submitted value.","example":5},"csat_survey_response":{"type":"object","properties":{"rating":{"type":"integer","description":"Customer rating 1-5.","example":5},"feedback_message":{"type":"string","example":"Excellent support!"}}}}}}}}}},"example":{"message":{"submitted_values":[{"name":"rating","title":"How was your experience?","value":5,"csat_survey_response":{"rating":5,"feedback_message":"Excellent support!"}}]}}}}}},"put":{"tags":["Public CSAT Survey"],"operationId":"auto_put_public_api_v1_csat_survey_id","summary":"Submit or update a CSAT survey response (public)","description":"Public endpoint used by the survey page to record the customer's rating and feedback on the conversation's input_csat message. Locked 14 days after the message was created (returns 422). The `{id}` path param is the conversation UUID.","security":[],"responses":{"200":{"description":"Updated CSAT message with the embedded survey response.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer","example":9021},"csat_survey_response":{"type":["object","null"],"description":"The persisted survey response (rating + feedback).","properties":{"id":{"type":"integer","example":55},"rating":{"type":"integer","example":5},"feedback_message":{"type":"string","example":"Excellent support!"}}},"display_type":{"type":"string","description":"CSAT widget display style.","example":"emoji","enum":["emoji","star"]},"content":{"type":["string","null"],"description":"CSAT prompt message configured on the inbox.","example":"Please rate your conversation"},"inbox_avatar_url":{"type":"string","example":"https://cdn.example.com/inbox/avatar.png"},"inbox_name":{"type":"string","example":"Website Support"},"locale":{"type":"string","example":"en"},"conversation_id":{"type":"integer","example":812},"created_at":{"type":"string","format":"date-time","example":"2026-01-15T10:30:00.000Z"}}},"example":{"id":9021,"csat_survey_response":{"id":55,"rating":5,"feedback_message":"Excellent support!"},"display_type":"emoji","content":"Please rate your conversation","inbox_avatar_url":"https://cdn.example.com/inbox/avatar.png","inbox_name":"Website Support","locale":"en","conversation_id":812,"created_at":"2026-01-15T10:30:00.000Z"}}}},"422":{"description":"Survey locked (more than 14 days after the message was created).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"You cannot update the CSAT survey after 14 days"}}},"example":{"error":"You cannot update the CSAT survey after 14 days"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"object","properties":{"submitted_values":{"type":"array","description":"Submitted values for the CSAT message.","items":{"type":"object","properties":{"name":{"type":"string","example":"rating"},"title":{"type":"string","example":"How was your experience?"},"value":{"description":"Free-form submitted value.","example":5},"csat_survey_response":{"type":"object","properties":{"rating":{"type":"integer","description":"Customer rating 1-5.","example":5},"feedback_message":{"type":"string","example":"Excellent support!"}}}}}}}}}},"example":{"message":{"submitted_values":[{"name":"rating","title":"How was your experience?","value":5,"csat_survey_response":{"rating":5,"feedback_message":"Excellent support!"}}]}}}}}}},"/public/api/v1/calendar/bookings/{manage_token}/ics":{"get":{"tags":["Public Calendar"],"operationId":"auto_get_public_api_v1_calendar_bookings_manage_token_ics","summary":"Ics bookings","description":"Performs the ics operation on the targeted booking resource.","security":[],"responses":{"200":{"description":"File download","content":{"text/calendar":{"schema":{"type":"string","format":"binary"}}}}},"parameters":[{"name":"manage_token","in":"path","required":true,"schema":{"type":"string"}}]}},"/public/api/v1/calendar/portal/{slug}":{"get":{"tags":["Public Calendar"],"operationId":"auto_get_public_api_v1_calendar_portal_slug","summary":"Get portal","description":"Returns the portal identified by the path parameters.","security":[],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"account_name":{"type":"string"},"logo_url":{"type":"string"},"brand_color":{"type":"string"},"locale":{"type":"string"},"event_types":{"type":"array","items":{"type":"object","properties":{"public_token":{"type":"string"},"name":{"type":"string"},"duration_minutes":{"type":"integer"},"location_type":{"type":"string","enum":["in_person","phone","google_meet","custom"],"description":"Where a bookable meeting takes place."},"color":{"type":"string"},"payment":{"type":"object","properties":{"amount":{"type":"number"},"currency":{"type":"string"}}}}}}}}}},"example":{"payload":{"account_name":"sample account name","logo_url":"https://example.com/resource","brand_color":"#1F93FF","locale":"en","event_types":[{"public_token":"sample-token","name":"Sample Name","duration_minutes":60,"location_type":"in_person","color":"#1F93FF","payment":{"amount":149.9,"currency":"BRL"}}]}}}}}},"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}]}},"/public/api/v1/growth_social/auth/request_link":{"post":{"tags":["Public Growth Social"],"operationId":"auto_post_public_api_v1_growth_social_auth_request_link","summary":"Request link auth","description":"Performs the request link operation on the targeted auth resource.","security":[],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","example":true}}},"example":{"ok":true}}}}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","format":"email"},"community_slug":{"type":"string"},"invite_token":{"type":"string"}}},"example":{"email":"agent@example.com","community_slug":"sample community slug","invite_token":"sample-token"}}}}}},"/public/api/v1/growth_social/auth/verify":{"post":{"tags":["Public Growth Social"],"operationId":"auto_post_public_api_v1_growth_social_auth_verify","summary":"Verify auth","description":"Performs the verify operation on the targeted auth resource.","security":[],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"token":{"type":"string"},"member":{"type":"object","properties":{"id":{"type":"integer"},"email":{"type":"string","format":"email"},"name":{"type":"string"}}}}},"example":{"token":"sample-token","member":{"id":1,"email":"agent@example.com","name":"Sample Name"}}}}}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"token":{"type":"string"}}},"example":{"token":"sample-token"}}}}}},"/public/api/v1/growth_social/me":{"get":{"tags":["Public Growth Social"],"operationId":"auto_get_public_api_v1_growth_social_me","summary":"Get me","description":"Returns the me identified by the path parameters.","security":[],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"member":{"type":"string"},"memberships":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"community_id":{"type":"integer"},"community_name":{"type":["string","null"]},"community_slug":{"type":["string","null"]},"branding":{"type":["string","null"]},"status":{"type":"string","enum":["pending","active","paused","left"],"description":"Membership state of the public community member."},"role":{"type":"string","enum":["member","captain","admin"],"description":"The member's role in the community."},"tier":{"type":"string","enum":["champion","active","at_risk","dormant"],"description":"Community engagement/retention tier derived from the reputation score."},"points_balance":{"type":"string"},"give_count":{"type":"integer"},"receive_count":{"type":"integer"},"engagement_opt_in":{"type":"string"},"joined_at":{"type":"string","format":"date-time"}},"required":["id","community_id","community_name","community_slug","branding","status","role","tier","points_balance","give_count","receive_count","engagement_opt_in","joined_at"],"additionalProperties":false}}}},"example":{"member":"sample member","memberships":[{"id":1,"community_id":1,"community_name":"sample community name","community_slug":"sample community slug","branding":"sample branding","status":"pending","role":"member","tier":"champion","points_balance":"sample points balance","give_count":5,"receive_count":5,"engagement_opt_in":"sample engagement opt in","joined_at":"2026-01-15T10:30:00.000Z"}]}}}}}}},"/public/api/v1/growth_social/me/consent":{"patch":{"tags":["Public Growth Social"],"operationId":"auto_patch_public_api_v1_growth_social_me_consent","summary":"Consent me","description":"Performs the consent operation on the targeted me resource.","security":[],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"member":{"type":"string"}}},"example":{"member":"sample member"}}}}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"version":{"type":"string"},"accepted":{"type":"string"}}},"example":{"version":"1.0.0","accepted":"sample accepted"}}}}}},"/public/api/v1/growth_social/communities":{"get":{"tags":["Public Growth Social"],"operationId":"auto_get_public_api_v1_growth_social_communities","summary":"List communities","description":"Returns the list of communities visible to the authenticated caller.","security":[],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"community_id":{"type":"integer"},"community_name":{"type":["string","null"]},"community_slug":{"type":["string","null"]},"branding":{"type":["string","null"]},"status":{"type":"string","enum":["draft","active","archived"]},"role":{"type":"string","enum":["member","captain","admin"],"description":"The member's role in the community."},"tier":{"type":"string","enum":["champion","active","at_risk","dormant"],"description":"Community engagement/retention tier derived from the reputation score."},"points_balance":{"type":"string"},"give_count":{"type":"integer"},"receive_count":{"type":"integer"},"engagement_opt_in":{"type":"string"},"joined_at":{"type":"string","format":"date-time"}},"required":["id","community_id","community_name","community_slug","branding","status","role","tier","points_balance","give_count","receive_count","engagement_opt_in","joined_at"],"additionalProperties":false}}}},"example":{"payload":[{"id":1,"community_id":1,"community_name":"sample community name","community_slug":"sample community slug","branding":"sample branding","status":"draft","role":"member","tier":"champion","points_balance":"sample points balance","give_count":5,"receive_count":5,"engagement_opt_in":"sample engagement opt in","joined_at":"2026-01-15T10:30:00.000Z"}]}}}}},"parameters":[{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."}]}},"/public/api/v1/growth_social/communities/join":{"post":{"tags":["Public Growth Social"],"operationId":"auto_post_public_api_v1_growth_social_communities_join","summary":"Join communities","description":"Performs the join operation on the targeted community resource.","security":[],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"community_id":{"type":"integer"},"community_name":{"type":["string","null"]},"community_slug":{"type":["string","null"]},"branding":{"type":["string","null"]},"status":{"type":"string","enum":["draft","active","archived"]},"role":{"type":"string","enum":["member","captain","admin"],"description":"The member's role in the community."},"tier":{"type":"string","enum":["champion","active","at_risk","dormant"],"description":"Community engagement/retention tier derived from the reputation score."},"points_balance":{"type":"string"},"give_count":{"type":"integer"},"receive_count":{"type":"integer"},"engagement_opt_in":{"type":"string"},"joined_at":{"type":"string","format":"date-time"}},"required":["id","community_id","community_name","community_slug","branding","status","role","tier","points_balance","give_count","receive_count","engagement_opt_in","joined_at"],"additionalProperties":false},"example":{"id":1,"community_id":1,"community_name":"sample community name","community_slug":"sample community slug","branding":"sample branding","status":"draft","role":"member","tier":"champion","points_balance":"sample points balance","give_count":5,"receive_count":5,"engagement_opt_in":"sample engagement opt in","joined_at":"2026-01-15T10:30:00.000Z"}}}}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"slug":{"type":"string"},"invite_token":{"type":"string"}}},"example":{"slug":"sample-slug","invite_token":"sample-token"}}}}}},"/public/api/v1/growth_social/memberships/{id}/opt_in":{"post":{"tags":["Public Growth Social"],"operationId":"auto_post_public_api_v1_growth_social_memberships_id_opt_in","summary":"Opt in communities","description":"Performs the opt in operation on the targeted community resource.","security":[],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"community_id":{"type":"integer"},"community_name":{"type":["string","null"]},"community_slug":{"type":["string","null"]},"branding":{"type":["string","null"]},"status":{"type":"string","enum":["draft","active","archived"],"description":"Membership state of the public community member."},"role":{"type":"string","enum":["member","captain","admin"],"description":"The member's role in the community."},"tier":{"type":"string","enum":["champion","active","at_risk","dormant"],"description":"Community engagement/retention tier derived from the reputation score."},"points_balance":{"type":"string"},"give_count":{"type":"integer"},"receive_count":{"type":"integer"},"engagement_opt_in":{"type":"string"},"joined_at":{"type":"string","format":"date-time"}},"required":["id","community_id","community_name","community_slug","branding","status","role","tier","points_balance","give_count","receive_count","engagement_opt_in","joined_at"],"additionalProperties":false},"example":{"id":1,"community_id":1,"community_name":"sample community name","community_slug":"sample community slug","branding":"sample branding","status":"draft","role":"member","tier":"champion","points_balance":"sample points balance","give_count":5,"receive_count":5,"engagement_opt_in":"sample engagement opt in","joined_at":"2026-01-15T10:30:00.000Z"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"opt_in":{"type":"string"}}},"example":{"opt_in":"sample opt in"}}}}}},"/public/api/v1/growth_social/accounts":{"get":{"tags":["Public Growth Social"],"operationId":"auto_get_public_api_v1_growth_social_accounts","summary":"List accounts","description":"Returns the list of accounts visible to the authenticated caller.","security":[],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"Free-form object."}}}},"example":{"payload":[{}]}}}}},"parameters":[{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."}]}},"/public/api/v1/growth_social/accounts/start_login":{"post":{"tags":["Public Growth Social"],"operationId":"auto_post_public_api_v1_growth_social_accounts_start_login","summary":"Start login accounts","description":"Performs the start login operation on the targeted account resource.","security":[],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"account":{"type":"string"},"ok":{"type":"string"},"category":{"type":"string"}}},"example":{"account":"sample account","ok":"sample ok","category":"sample category"}}}}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"username":{"type":"string"},"password":{"type":"string"},"verification_code":{"type":"string"}}},"example":{"username":"sample username","password":"sample-password","verification_code":"sample verification code"}}}}}},"/public/api/v1/growth_social/accounts/submit_challenge":{"post":{"tags":["Public Growth Social"],"operationId":"auto_post_public_api_v1_growth_social_accounts_submit_challenge","summary":"Submit challenge accounts","description":"Performs the submit challenge operation on the targeted account resource.","security":[],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"account":{"type":"string"},"ok":{"type":"string"},"category":{"type":"string"}}},"example":{"account":"sample account","ok":"sample ok","category":"sample category"}}}}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"}}},"example":{"code":"sample code"}}}}}},"/public/api/v1/growth_social/accounts/oauth_start":{"post":{"tags":["Public Growth Social"],"operationId":"auto_post_public_api_v1_growth_social_accounts_oauth_start","summary":"Oauth start accounts","description":"Performs the oauth start operation on the targeted account resource.","security":[],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"status":{"type":"string","example":"unavailable","enum":["ok","unavailable"],"description":"Whether the public OAuth start endpoint could issue an authorization URL."},"reason":{"type":"string","example":"pending_app_review"}}},{"type":"object","properties":{"status":{"type":"string","example":"ok","enum":["ok","unavailable"],"description":"Whether the public OAuth start endpoint could issue an authorization URL."},"oauth_url":{"type":"string"}}}]},"example":{"status":"unavailable","reason":"pending_app_review"}}}}}}},"/public/api/v1/growth_social/accounts/{id}/status":{"get":{"tags":["Public Growth Social"],"operationId":"auto_get_public_api_v1_growth_social_accounts_id_status","summary":"Status accounts","description":"Performs the status operation on the targeted account resource.","security":[],"responses":{"200":{"description":"Connected social account status for the current portal member (secrets masked)","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer","example":4},"platform":{"type":"string","enum":["instagram","tiktok","youtube"],"example":"instagram"},"username":{"type":["string","null"],"example":"@member_handle"},"status":{"type":"string","enum":["connecting","awaiting_challenge","connected","disconnected","blocked","logged_out"],"example":"connected","description":"Connection state of the social account."},"has_credentials":{"type":"boolean","description":"Whether stored credentials exist (raw creds never returned)","example":true},"last_error":{"type":["string","null"],"example":null}}},"example":{"id":4,"platform":"instagram","username":"@member_handle","status":"connected","has_credentials":true,"last_error":null}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/public/api/v1/growth_social/tasks":{"get":{"tags":["Public Growth Social"],"operationId":"auto_get_public_api_v1_growth_social_tasks","summary":"List tasks","description":"Returns the list of tasks visible to the authenticated caller.","security":[],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"action":{"type":"string"},"status":{"type":"string","enum":["backlog","todo","in_progress","in_review","done","cancelled"]},"points_awarded":{"type":"string"},"target_ref":{"type":"string"},"created_at":{"type":"string","format":"date-time"}},"required":["id","action","status","points_awarded","target_ref","created_at"],"additionalProperties":false}}}},"example":{"payload":[{"id":1,"action":"sample action","status":"backlog","points_awarded":"sample points awarded","target_ref":"sample target ref","created_at":"2026-01-15T10:30:00.000Z"}]}}}}},"parameters":[{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."}]}},"/public/api/v1/growth_social/rewards":{"get":{"tags":["Public Growth Social"],"operationId":"auto_get_public_api_v1_growth_social_rewards","summary":"List rewards","description":"Returns the list of rewards visible to the authenticated caller.","security":[],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"balance":{"type":"string"},"payload":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"amount":{"type":"number"},"kind":{"type":"string","enum":["physical","voucher","pix","perk"]},"balance_after":{"type":"string"},"created_at":{"type":"string","format":"date-time"}},"required":["id","amount","kind","balance_after","created_at"],"additionalProperties":false}}}},"example":{"balance":"sample balance","payload":[{"id":1,"amount":149.9,"kind":"physical","balance_after":"sample balance after","created_at":"2026-01-15T10:30:00.000Z"}]}}}}},"parameters":[{"name":"membership_id","in":"query","required":true,"description":"Membership whose reward ledger is returned, resolved through the member token.","schema":{"type":"integer"},"example":77}]}},"/public/api/v1/growth_social/rewards/leaderboard":{"get":{"tags":["Public Growth Social"],"operationId":"auto_get_public_api_v1_growth_social_rewards_leaderboard","summary":"Leaderboard rewards","description":"Performs the leaderboard operation on the targeted reward resource.","security":[],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"string"}}}},"example":{"payload":["sample payload"]}}}}},"parameters":[{"name":"membership_id","in":"query","required":true,"description":"Membership asking for the ranking — it also scopes which community is ranked.","schema":{"type":"integer"},"example":77}]}},"/public/api/v1/contracts/sign/{signing_token}":{"get":{"tags":["Public Contracts"],"operationId":"auto_get_public_api_v1_contracts_sign_signing_token","summary":"Get signatures","description":"Returns the signature identified by the path parameters.","security":[],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"signer":{"type":"object","properties":{"name":{"type":"string"},"role":{"type":"string","enum":["contractor","contracted","witness","guarantor"]},"status":{"type":"string","enum":["pending","viewed","signed","rejected"]},"auth_method":{"type":"string","enum":["none","email_otp","whatsapp_otp","icp_brasil"]},"otp_required":{"type":"string"}}},"progress":{"type":"object","properties":{"total":{"type":"number"},"signed_count":{"type":"integer"},"position":{"type":"integer"}}},"signers":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"role":{"type":"string","enum":["contractor","contracted","witness","guarantor"]},"status":{"type":"string","enum":["pending","viewed","signed","rejected"]},"auto_sign":{"type":"string"},"is_you":{"type":"boolean"}}}},"contract":{"type":"object","properties":{"title":{"type":"string"},"status":{"type":"string","enum":["draft","pending_signature","partially_signed","completed","rejected","expired","voided","canceled"]},"signature_tier":{"type":"string","enum":["simple","advanced","qualified"]},"locale":{"type":"string"},"region":{"type":"string"},"expires_at":{"type":"string","format":"date-time"},"body":{"type":"string"},"verification_url":{"type":"string"},"issuer":{"type":"object","properties":{"name":{"type":"string"},"branding":{"type":"string"},"logo_url":{"type":"string"}}}}}}},"example":{"signer":{"name":"Sample Name","role":"contractor","status":"pending","auth_method":"none","otp_required":"sample otp required"},"progress":{"total":149.9,"signed_count":5,"position":1},"signers":[{"name":"Sample Name","role":"contractor","status":"pending","auto_sign":"sample auto sign","is_you":true}],"contract":{"title":"Sample title","status":"draft","signature_tier":"simple","locale":"en","region":"sample region","expires_at":"2026-01-15T10:30:00.000Z","body":"Sample body text.","verification_url":"https://example.com/resource","issuer":{"name":"Sample Name","branding":"sample branding","logo_url":"https://example.com/resource"}}}}}}},"parameters":[{"name":"signing_token","in":"path","required":true,"schema":{"type":"string"}}]},"post":{"tags":["Public Contracts"],"operationId":"auto_post_public_api_v1_contracts_sign_signing_token","summary":"Submit signatures","description":"Performs the submit operation on the targeted signature resource.","security":[],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"signer":{"type":"object","properties":{"name":{"type":"string"},"role":{"type":"string","enum":["contractor","contracted","witness","guarantor"]},"status":{"type":"string","enum":["pending","viewed","signed","rejected"]},"auth_method":{"type":"string","enum":["none","email_otp","whatsapp_otp","icp_brasil"]},"otp_required":{"type":"string"}}},"progress":{"type":"object","properties":{"total":{"type":"number"},"signed_count":{"type":"integer"},"position":{"type":"integer"}}},"signers":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"role":{"type":"string","enum":["contractor","contracted","witness","guarantor"]},"status":{"type":"string","enum":["pending","viewed","signed","rejected"]},"auto_sign":{"type":"string"},"is_you":{"type":"boolean"}}}},"contract":{"type":"object","properties":{"title":{"type":"string"},"status":{"type":"string","enum":["draft","pending_signature","partially_signed","completed","rejected","expired","voided","canceled"]},"signature_tier":{"type":"string","enum":["simple","advanced","qualified"]},"locale":{"type":"string"},"region":{"type":"string"},"expires_at":{"type":"string","format":"date-time"},"body":{"type":"string"},"verification_url":{"type":"string"},"issuer":{"type":"object","properties":{"name":{"type":"string"},"branding":{"type":"string"},"logo_url":{"type":"string"}}}}}}},"example":{"signer":{"name":"Sample Name","role":"contractor","status":"pending","auth_method":"none","otp_required":"sample otp required"},"progress":{"total":149.9,"signed_count":5,"position":1},"signers":[{"name":"Sample Name","role":"contractor","status":"pending","auto_sign":"sample auto sign","is_you":true}],"contract":{"title":"Sample title","status":"draft","signature_tier":"simple","locale":"en","region":"sample region","expires_at":"2026-01-15T10:30:00.000Z","body":"Sample body text.","verification_url":"https://example.com/resource","issuer":{"name":"Sample Name","branding":"sample branding","logo_url":"https://example.com/resource"}}}}}}},"parameters":[{"name":"signing_token","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"signature":{"type":"object","additionalProperties":true,"description":"Free-form object."}}},"example":{"signature":{}}}}}}},"/public/api/v1/contracts/sign/{signing_token}/otp":{"post":{"tags":["Public Contracts"],"operationId":"auto_post_public_api_v1_contracts_sign_signing_token_otp","summary":"Request the signing one-time code","description":"Generates a one-time code for the signer identified by the signing token in the URL and delivers it on the channel THEIR authentication method defines — an e-mail signer receives an e-mail, a WhatsApp signer receives it in their own conversation. When the configured channel is unreachable the other one is tried as an explicit fallback; when neither exists the call fails instead of reporting success. The response never contains the code, only a masked hint of where it went, and the caller must wait for the 202 before starting any resend countdown.","security":[],"responses":{"202":{"description":"The code was generated and delivered.","content":{"application/json":{"schema":{"type":"object","properties":{"channel":{"type":"string","enum":["email","whatsapp","conversation"],"description":"Where the code was delivered.","example":"email"},"destination_hint":{"type":["string","null"],"description":"Enough for the signer to recognise the destination, never enough for anyone else to use it. Null when the destination cannot be masked meaningfully.","example":"m***@example.com"},"expires_in":{"type":"integer","description":"Seconds until the code stops being valid.","example":600},"retry_after":{"type":"integer","description":"Seconds the signer must wait before requesting another code.","example":45}}},"example":{"channel":"email","destination_hint":"m***@example.com","expires_in":600,"retry_after":45}}}},"422":{"description":"No code was issued and none will be until something is configured: this signer does not use one-time code authentication, or has no e-mail address and no conversation to receive it.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable reason, localized to the signer's language.","example":"There is no e-mail address or conversation to send your code to. Contact whoever sent the contract."},"code":{"type":"string","enum":["otp_not_required","otp_no_destination","otp_no_email","otp_no_conversation","otp_template_missing"],"description":"Canonical token, so a client can branch without parsing prose.","example":"otp_no_destination"}}},"example":{"error":"There is no e-mail address or conversation to send your code to. Contact whoever sent the contract.","code":"otp_no_destination"}}}},"429":{"description":"Too many codes were requested for this token. The `Retry-After` header carries the wait.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Too many codes requested. Wait a moment before trying again."},"code":{"type":"string","enum":["otp_rate_limited"],"example":"otp_rate_limited"},"retry_after":{"type":"integer","description":"Seconds to wait before retrying.","example":45}}},"example":{"error":"Too many codes requested. Wait a moment before trying again.","code":"otp_rate_limited","retry_after":45}}}},"503":{"description":"The channel itself failed right now (mail server, messaging provider). The request is worth repeating; nothing is misconfigured.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"We could not deliver the code right now. Try again in a moment."},"code":{"type":"string","enum":["otp_delivery_failed"],"example":"otp_delivery_failed"}}},"example":{"error":"We could not deliver the code right now. Try again in a moment.","code":"otp_delivery_failed"}}}},"404":{"description":"No signer matches this signing token."}},"parameters":[{"name":"signing_token","in":"path","required":true,"schema":{"type":"string"}}]}},"/public/api/v1/contracts/sign/{signing_token}/document":{"get":{"tags":["Public Contracts"],"operationId":"auto_get_public_api_v1_contracts_sign_signing_token_document","summary":"Document signatures","description":"Performs the document operation on the targeted signature resource.","security":[],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string"},"filename":{"type":"string"},"sha256":{"type":"string"}}},"example":{"url":"https://example.com/resource","filename":"sample filename","sha256":"sample sha256"}}}}},"parameters":[{"name":"signing_token","in":"path","required":true,"schema":{"type":"string"}}]}},"/public/api/v1/contracts/verify/{verification_code}":{"get":{"tags":["Public Contracts"],"operationId":"auto_get_public_api_v1_contracts_verify_verification_code","summary":"Get verifications","description":"Returns the verification identified by the path parameters.","security":[],"responses":{"200":{"description":"Masked public verification view.","content":{"application/json":{"schema":{"type":"object","properties":{"verification_code":{"type":"string","example":"CW-7F3A9B2C"},"title":{"type":"string","example":"Contrato de Prestação de Serviços"},"status":{"type":"string","enum":["draft","pending_signature","partially_signed","completed","rejected","expired","voided","canceled"],"example":"completed"},"signature_tier":{"type":"string","enum":["simple","advanced","qualified"],"example":"advanced"},"issuer":{"type":["string","null"],"description":"Issuing company name.","example":"ACME Serviços LTDA"},"sent_at":{"type":["string","null"],"format":"date-time","example":"2026-01-15T10:30:00.000Z"},"completed_at":{"type":["string","null"],"format":"date-time","example":"2026-01-16T14:20:00.000Z"},"document_sha256":{"type":["string","null"],"example":"e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"},"signers":{"type":"array","items":{"type":"object","properties":{"name":{"type":["string","null"],"description":"Masked (e.g. J*** S****).","example":"J*** S****"},"email":{"type":["string","null"],"description":"Masked (e.g. j***@example.com).","example":"j***@example.com"},"role":{"type":"string","enum":["contractor","contracted","witness","guarantor"],"example":"contractor"},"status":{"type":"string","enum":["pending","viewed","signed","rejected"],"example":"signed"},"signed_at":{"type":["string","null"],"format":"date-time","example":"2026-01-16T14:20:00.000Z"}}}}}},"example":{"verification_code":"CW-7F3A9B2C","title":"Contrato de Prestação de Serviços","status":"completed","signature_tier":"advanced","issuer":"ACME Serviços LTDA","sent_at":"2026-01-15T10:30:00.000Z","completed_at":"2026-01-16T14:20:00.000Z","document_sha256":"e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855","signers":[{"name":"J*** S****","email":"j***@example.com","role":"contractor","status":"signed","signed_at":"2026-01-16T14:20:00.000Z"}]}}}},"404":{"description":"No contract matches the verification code."}},"parameters":[{"name":"verification_code","in":"path","required":true,"schema":{"type":"string"}}]}},"/public/api/v1/contracts/verify/{verification_code}/document":{"get":{"tags":["Public Contracts"],"operationId":"auto_get_public_api_v1_contracts_verify_verification_code_document","summary":"Document verifications","description":"Performs the document operation on the targeted verification resource.","security":[],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string"},"filename":{"type":"string"},"sha256":{"type":"string"}}},"example":{"url":"https://example.com/resource","filename":"sample filename","sha256":"sample sha256"}}}}},"parameters":[{"name":"verification_code","in":"path","required":true,"schema":{"type":"string"}}]}},"/public/api/v1/sales/wallboard/{token}":{"get":{"tags":["Public Sales"],"operationId":"auto_get_public_api_v1_sales_wallboard_token","summary":"Read sales wallboard scenes","description":"Read-only scene data with independent points and revenue. Display mode controls presentation, not the unit of stored numbers. Identity/value masking replaces the corresponding JSON values with null before serialization; private commercial terms and provider/ingest/display tokens are removed recursively. Revenue currency belongs to each row. Public variant resolved only by an opaque rotatable token; missing/stale token or disabled feature returns 404. Mask flags reflect the account configuration, not automatic anonymization.","security":[],"responses":{"200":{"description":"Scene data after server-side presentation privacy.","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"team_goal":{"type":["object","null"],"properties":{"id":{"type":["integer","null"]},"name":{"type":["string","null"]},"metric_type":{"type":"string","enum":["revenue_won","revenue_paid","deals","conversions","resolutions","bookings","combination","points"]},"score_kind":{"type":"string","enum":["money","points"]},"currency":{"type":["string","null"],"minLength":3,"maxLength":3},"target_amount":{"oneOf":[{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},{"type":"number"}],"description":"Decimal serialized as a string or number; values are never currency-converted."},"target_count":{"type":["integer","null"]},"actual_value":{"oneOf":[{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},{"type":"number"}],"description":"Decimal serialized as a string or number; values are never currency-converted."},"actual_count":{"type":["integer","null"]},"actual":{"oneOf":[{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},{"type":"number"}],"description":"Decimal serialized as a string or number; values are never currency-converted."},"target":{"oneOf":[{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},{"type":"number"}],"description":"Decimal serialized as a string or number; values are never currency-converted."},"attainment_pct":{"oneOf":[{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},{"type":"number"}],"description":"Decimal serialized as a string or number; values are never currency-converted."},"tiers":{"type":"array","items":{"type":"object","properties":{"id":{"type":["integer","null"]},"label":{"type":"string"},"medal_band":{"type":["string","null"]},"threshold":{"oneOf":[{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},{"type":"number"}],"description":"Decimal serialized as a string or number; values are never currency-converted."},"threshold_value":{"oneOf":[{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},{"type":"number"}],"description":"Decimal serialized as a string or number; values are never currency-converted."},"reached":{"type":"boolean"}}}}}},"goal_gauges":{"type":"array","items":{"type":"object","properties":{"id":{"type":["integer","null"]},"name":{"type":["string","null"]},"metric_type":{"type":"string","enum":["revenue_won","revenue_paid","deals","conversions","resolutions","bookings","combination","points"]},"score_kind":{"type":"string","enum":["money","points"]},"currency":{"type":["string","null"],"minLength":3,"maxLength":3},"target_amount":{"oneOf":[{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},{"type":"number"}],"description":"Decimal serialized as a string or number; values are never currency-converted."},"target_count":{"type":["integer","null"]},"actual_value":{"oneOf":[{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},{"type":"number"}],"description":"Decimal serialized as a string or number; values are never currency-converted."},"actual_count":{"type":["integer","null"]},"actual":{"oneOf":[{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},{"type":"number"}],"description":"Decimal serialized as a string or number; values are never currency-converted."},"target":{"oneOf":[{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},{"type":"number"}],"description":"Decimal serialized as a string or number; values are never currency-converted."},"attainment_pct":{"oneOf":[{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},{"type":"number"}],"description":"Decimal serialized as a string or number; values are never currency-converted."},"scope_type":{"type":"string","enum":["user","team","account"]}}}},"leaderboard":{"type":"array","items":{"type":"object","properties":{"id":{"type":["integer","null"]},"user_id":{"type":["integer","null"]},"rank":{"type":"integer"},"value":{"oneOf":[{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},{"type":"number"}],"description":"Decimal serialized as a string or number; values are never currency-converted."},"points":{"oneOf":[{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},{"type":"number"}],"description":"Decimal serialized as a string or number; values are never currency-converted."},"revenue":{"oneOf":[{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},{"type":"number"}],"description":"Decimal serialized as a string or number; values are never currency-converted."},"currency":{"type":["string","null"],"minLength":3,"maxLength":3},"trend":{"oneOf":[{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},{"type":"number"}],"description":"Decimal serialized as a string or number; values are never currency-converted."},"attainment_pct":{"oneOf":[{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},{"type":"number"}],"description":"Decimal serialized as a string or number; values are never currency-converted."},"name":{"type":["string","null"]},"avatar_url":{"type":["string","null"]}}}},"pareto":{"type":"array","items":{"type":"object","properties":{"user_id":{"type":["integer","null"]},"rank":{"type":"integer"},"value":{"oneOf":[{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},{"type":"number"}],"description":"Decimal serialized as a string or number; values are never currency-converted."},"points":{"oneOf":[{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},{"type":"number"}],"description":"Decimal serialized as a string or number; values are never currency-converted."},"revenue":{"oneOf":[{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},{"type":"number"}],"description":"Decimal serialized as a string or number; values are never currency-converted."},"currency":{"type":["string","null"],"minLength":3,"maxLength":3},"name":{"type":["string","null"]},"contribution_pct":{"oneOf":[{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},{"type":"number"}],"description":"Decimal serialized as a string or number; values are never currency-converted."}}}},"ticker":{"type":"object","properties":{"today":{"oneOf":[{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},{"type":"number"}],"description":"Decimal serialized as a string or number; values are never currency-converted."},"month":{"oneOf":[{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},{"type":"number"}],"description":"Decimal serialized as a string or number; values are never currency-converted."},"points_today":{"oneOf":[{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},{"type":"number"}],"description":"Decimal serialized as a string or number; values are never currency-converted."},"points_month":{"oneOf":[{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},{"type":"number"}],"description":"Decimal serialized as a string or number; values are never currency-converted."},"currency":{"type":["string","null"],"minLength":3,"maxLength":3}}},"recent_wins":{"type":"array","items":{"type":"object","properties":{"id":{"type":["integer","null"]},"title":{"type":["string","null"]},"value":{"oneOf":[{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},{"type":"number"}],"description":"Decimal serialized as a string or number; values are never currency-converted."},"points":{"oneOf":[{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},{"type":"number"}],"description":"Decimal serialized as a string or number; values are never currency-converted."},"revenue":{"oneOf":[{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},{"type":"number"}],"description":"Decimal serialized as a string or number; values are never currency-converted."},"currency":{"type":["string","null"],"minLength":3,"maxLength":3},"owner_id":{"type":["integer","null"]},"owner_name":{"type":["string","null"]},"owner_avatar_url":{"type":["string","null"]},"closed_at":{"type":"string","format":"date-time","example":"2026-09-01T12:00:00Z"}}}},"top_movers":{"type":"array","items":{"type":"object","properties":{"user_id":{"type":["integer","null"]},"rank":{"type":"integer"},"value":{"oneOf":[{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},{"type":"number"}],"description":"Decimal serialized as a string or number; values are never currency-converted."},"points":{"oneOf":[{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},{"type":"number"}],"description":"Decimal serialized as a string or number; values are never currency-converted."},"revenue":{"oneOf":[{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},{"type":"number"}],"description":"Decimal serialized as a string or number; values are never currency-converted."},"currency":{"type":["string","null"],"minLength":3,"maxLength":3},"trend":{"oneOf":[{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},{"type":"number"}],"description":"Decimal serialized as a string or number; values are never currency-converted."},"name":{"type":["string","null"]},"avatar_url":{"type":["string","null"]}}}},"phrases":{"type":"array","items":{"type":"string"}},"ticker_speed":{"type":"string","enum":["slow","normal","fast"]},"mask_names":{"type":"boolean"},"mask_values":{"type":"boolean"},"display_mode":{"type":"string","enum":["points","money","both"]},"currency":{"type":["string","null"],"minLength":3,"maxLength":3},"scenes":{"type":"array","items":{"type":"string","enum":["ranking","team_goal","recent_wins","top_movers","pareto"]}},"rotate_seconds":{"type":"integer","minimum":5,"maximum":120},"theme":{"type":"string","enum":["dark","light"]},"points_unit_label":{"type":["string","null"]},"points_decimals":{"type":"integer","minimum":0,"maximum":2}}}}},"example":{"payload":{"team_goal":null,"goal_gauges":[{"id":null,"name":null,"metric_type":"revenue_won","score_kind":"money","currency":null,"target_amount":null,"target_count":null,"actual_value":null,"actual_count":null,"actual":null,"target":null,"attainment_pct":null,"scope_type":"user"}],"leaderboard":[{"id":null,"user_id":null,"rank":1,"value":null,"points":null,"revenue":null,"currency":null,"trend":"1.5","attainment_pct":null,"name":null,"avatar_url":null}],"pareto":[{"user_id":null,"rank":1,"value":null,"points":null,"revenue":null,"currency":null,"name":null,"contribution_pct":null}],"ticker":{"today":null,"month":null,"points_today":null,"points_month":null,"currency":null},"recent_wins":[{"id":null,"title":null,"value":null,"points":null,"revenue":null,"currency":null,"owner_id":null,"owner_name":null,"owner_avatar_url":null,"closed_at":"2026-09-01T12:00:00Z"}],"top_movers":[{"user_id":null,"rank":1,"value":null,"points":null,"revenue":null,"currency":null,"trend":"1.5","name":null,"avatar_url":null}],"phrases":["example"],"ticker_speed":"slow","mask_names":true,"mask_values":true,"display_mode":"points","currency":null,"scenes":["ranking"],"rotate_seconds":13,"theme":"dark","points_unit_label":"points","points_decimals":2}}}}},"404":{"description":"Token or account resource unavailable."}},"parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string"}}]}},"/public/api/v1/sales/affiliate/{token}":{"get":{"tags":["Public Sales"],"operationId":"auto_get_public_api_v1_sales_affiliate_token","summary":"Affiliate self-service portal","description":"PUBLIC, unauthenticated read keyed ONLY by the affiliate's portal_token — NOT the referral_code, which is public and therefore not a credential (spec-078 split the two so a report link can be revoked without breaking a referral link already in circulation; there is deliberately no fallback). The affiliate opens their own read-only report with no session. Resolves an ACTIVE affiliate on an account with the affiliate_program feature; a missing, blank, rotated or unknown token, a paused affiliate or a flag-off account all return the SAME 404, so the token can never enumerate accounts. PII-minimal: the affiliate's own attributed order ids plus aggregate revenue, accrued commission and closed statements — never contact PII. Amounts are in MAJOR units. The same payload backs the HTML page a partner actually opens at GET /sales/affiliate/:portal_token, which is outside this API reference because it renders a page rather than JSON.","security":[],"responses":{"200":{"description":"The affiliate's own attributed revenue, accrued commission and closed statements.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"affiliate":{"type":"object","properties":{"name":{"type":"string","example":"João Afiliado"},"referral_code":{"type":"string","example":"AB12CD34"},"status":{"type":"string","enum":["active","paused","archived"],"example":"active"}}},"totals":{"type":"object","properties":{"attributed_orders":{"type":"integer","description":"Count of paid orders attributed to this affiliate.","example":12},"revenue":{"type":"object","additionalProperties":{"type":"number"},"description":"Attributed paid revenue per currency (major units).","example":{"BRL":4970.5}},"commission_accrued":{"type":"object","additionalProperties":{"type":"number"},"description":"Accrued affiliate commission per currency (major units), grouped exactly like revenue. An accrual predating the currency column reports under the key 'unspecified' rather than being folded into a real currency.","example":{"BRL":745.58}}}},"period":{"type":"object","description":"The window the report covers. Both bounds are null when no from/to was given (all time).","properties":{"from":{"type":["string","null"],"format":"date-time","example":null},"to":{"type":["string","null"],"format":"date-time","example":null}}},"statements":{"type":"array","description":"The affiliate's CLOSED commission periods, most recent first (capped at 24). What the partner is actually owed and what has been paid — decision D-1. One row per currency bucket.","items":{"type":"object","properties":{"period_start":{"type":["string","null"],"format":"date","example":"2026-07-01"},"period_end":{"type":["string","null"],"format":"date","example":"2026-07-31"},"currency":{"type":["string","null"],"description":"The currency bucket this statement closes; null on a statement predating the column.","example":"BRL"},"status":{"type":"string","enum":["draft","pending","approved","paid","canceled"],"example":"paid"},"total_accrued":{"type":"number","description":"Commission accrued in the period (major units).","example":745.58},"total_approved":{"type":"number","description":"Of the accrued","how much a manager approved (major units).":null,"example":745.58},"total_paid":{"type":"number","description":"Of the approved","how much was marked paid (major units).":null,"example":745.58}}}},"recent_orders":{"type":"array","description":"One page of the attributed paid orders, most recent first (ids and money only — no contact PII).","items":{"type":"object","properties":{"order_id":{"type":"integer","example":1001},"paid_at":{"type":"string","format":"date-time","example":"2026-07-10T14:03:00Z"},"amount":{"type":"number","example":497.05},"currency":{"type":"string","example":"BRL"},"gateway":{"type":["string","null"],"example":"asaas"}}}},"meta":{"type":"object","description":"Pagination over the attributed-order list.","properties":{"count":{"type":"integer","description":"Total attributed paid orders in the period (the WHOLE set","not the page).":null,"example":12},"current_page":{"type":"integer","example":1},"per_page":{"type":"integer","example":25},"has_more":{"type":"boolean","example":false}}}}}}},"example":{"data":{"affiliate":{"name":"João Afiliado","referral_code":"AB12CD34","status":"active"},"totals":{"attributed_orders":12,"revenue":{"BRL":4970.5},"commission_accrued":{"BRL":745.58}},"period":{"from":null,"to":null},"statements":[{"period_start":"2026-07-01","period_end":"2026-07-31","currency":"BRL","status":"paid","total_accrued":745.58,"total_approved":745.58,"total_paid":745.58}],"recent_orders":[{"order_id":1001,"paid_at":"2026-07-10T14:03:00Z","amount":497.05,"currency":"BRL","gateway":"asaas"}],"meta":{"count":12,"current_page":1,"per_page":25,"has_more":false}}}}}},"404":{"description":"Unknown, blank or stale token, or the account does not have the affiliate program enabled.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"not_found"}}},"example":{"error":"not_found"}}}}},"parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer","default":1},"description":"1-based page of the attributed-order list."},{"name":"per_page","in":"query","required":false,"schema":{"type":"integer","default":25,"maximum":100},"description":"Page size for the attributed-order list (default 25, capped at 100)."},{"name":"from","in":"query","required":false,"schema":{"type":"string","format":"date"},"description":"Restrict the report to orders paid on or after this date (defaults to all time). An unparseable value is treated as no bound rather than an error — this is a URL a human may edit."},{"name":"to","in":"query","required":false,"schema":{"type":"string","format":"date"},"description":"Restrict the report to orders paid on or before this date (defaults to all time)."}]}},"/public/api/v1/orders/ingest/{token}":{"post":{"tags":["Public Orders"],"operationId":"auto_post_public_api_v1_orders_ingest_token","summary":"Ingest an external order into the CRM registry","description":"Resolves one contact inside the token's account, then records or updates the opaque gateway/external identity. This endpoint records financial history only; it never charges, settles, cancels or refunds at the provider.","security":[],"responses":{"201":{"description":"Order accepted and registered.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ok"],"description":"Always `ok` — the order was recorded.","example":"ok"}}},"example":{"status":"ok"}}}},"404":{"description":"Token missing, stale, unknown or bound to an account without the orders registry.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","enum":["not_found"],"example":"not_found"}}},"example":{"error":"not_found"}}}},"422":{"description":"Invalid payload, order status or refund amount; missing contact reference; or an unresolvable contact.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","enum":["invalid_payload","invalid_order_status","invalid_refund_amount","contact_reference_required","contact_unresolvable"],"example":"contact_unresolvable"}}},"example":{"error":"contact_unresolvable"}}}}},"parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["gateway"],"anyOf":[{"required":["contact_id"]},{"required":["email"]},{"required":["phone_number"]}],"properties":{"contact_id":{"type":"integer","minimum":1},"email":{"type":"string","format":"email"},"phone_number":{"type":"string","description":"Phone normalized to E.164 before lookup."},"name":{"type":"string"},"gateway":{"type":"string","description":"Open provider or checkout namespace."},"external_id":{"type":"string","description":"Opaque provider order identifier used for idempotency."},"title":{"type":"string"},"amount":{"type":"number","minimum":0},"amount_refunded":{"type":"number","exclusiveMinimum":0,"description":"Required with partially_refunded and must be lower than amount."},"currency":{"type":"string","example":"BRL"},"status":{"type":"string","enum":["pending","paid","partially_paid","partially_refunded","overdue","refunded","canceled","failed"],"description":"Order status recorded in the registry (log only; never charges)."},"crm_item_id":{"type":"integer","minimum":1},"ordered_at":{"type":"string","format":"date-time"},"paid_at":{"type":"string","format":"date-time"},"affiliate_id":{"type":"integer","minimum":1,"description":"Assigned only when it identifies an active affiliate in the token's account."},"raw":{"type":"object","additionalProperties":true,"description":"Provider facts retained as an opaque audit snapshot."},"metadata":{"type":"object","additionalProperties":true,"description":"Non-secret integration metadata retained with the order."},"line_items":{"type":"array","items":{"type":"object","properties":{"source_item_id":{"type":"string"},"external_id":{"type":"string"},"id":{"type":"integer","minimum":1},"catalog_product_id":{"type":"integer","minimum":1},"catalog_variant_id":{"type":"integer","minimum":1},"name_snapshot":{"type":"string"},"name":{"type":"string"},"quantity":{"type":"number","exclusiveMinimum":0},"unit_price":{"type":"number","minimum":0},"price":{"type":"number","minimum":0},"discount":{"type":"number","minimum":0},"discount_type":{"type":"string","enum":["fixed","percent"]},"currency":{"type":"string","example":"BRL"},"position":{"type":"integer","minimum":0},"metadata":{"type":"object","additionalProperties":true,"description":"Opaque non-secret source metadata for this item."}}}}}},"example":{"email":"ana@example.com","name":"Ana Silva","gateway":"hotmart","external_id":"purchase_123","title":"Annual plan","amount":497,"currency":"BRL","status":"paid","ordered_at":"2026-09-03T14:00:00Z","paid_at":"2026-09-03T14:01:00Z","raw":{"event":"purchase_approved"},"metadata":{"source":"checkout"},"line_items":[{"source_item_id":"annual-plan","name":"Annual plan","quantity":1,"unit_price":497,"discount":0,"discount_type":"fixed","currency":"BRL","position":0,"metadata":{}}]}}}}}},"/public/api/v1/engagement/track/{token}":{"post":{"tags":["Public Engagement"],"operationId":"auto_post_public_api_v1_engagement_track_token","summary":"Create track","description":"Creates a new track from the request payload.","security":[],"responses":{"200":{"description":"Redelivery of an event already tracked. Nothing was written a second time; treat it as success and stop retrying.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["duplicate"],"description":"Always `duplicate` — the event had already been tracked.","example":"duplicate"}}},"example":{"status":"duplicate"}}}},"201":{"description":"Event accepted and tracked.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ok"],"description":"Always `ok` — the event was tracked.","example":"ok"}}},"example":{"status":"ok"}}}}},"parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"token":{"type":"string"},"event":{"type":"string"},"points":{"type":"string"},"channel":{"type":"string"},"contact_id":{"type":"integer"},"email":{"type":"string","format":"email"},"phone_number":{"type":"string"},"name":{"type":"string"}}},"example":{"token":"sample-token","event":"sample event","points":"sample points","channel":"sample channel","contact_id":1,"email":"agent@example.com","phone_number":"+5511999998888","name":"Sample Name"}}}}}},"/hc/{slug}/{locale}":{"get":{"tags":["{locale}"],"operationId":"auto_get_hc_slug_locale","summary":"Read a public Help Center portal","description":"Returns the public portal configuration and visible categories for the requested supported locale. Operator-only categories and articles are never included. This endpoint is unauthenticated and returns JSON only when the caller requests application/json; the browser route remains the Help Center reader.","security":[],"responses":{"200":{"description":"Public portal configuration for the requested locale.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/public_help_center_portal"},"example":{"custom_domain":"sample custom domain","header_text":"sample header text","homepage_link":"https://example.com/resource","name":"Sample Name","page_title":"sample page title","slug":"sample-slug","categories":[{"name":"Sample Name","slug":"sample-slug","locale":"en","description":"A short description.","position":1,"visibility":"public","meta":{"articles_count":5}}],"logo":{"id":1,"portal_id":1,"file_type":"image","account_id":1,"file_url":"https://example.com/resource","blob_id":"sample blob id","filename":"sample filename"},"meta":{"articles_count":5,"categories_count":5,"default_locale":"sample default locale"}}}}}},"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}},{"name":"locale","in":"path","required":true,"schema":{"type":"string"}}]}},"/hc/{slug}/{locale}/articles":{"get":{"tags":["{locale}"],"operationId":"auto_get_hc_slug_locale_articles","summary":"List public Help Center articles","description":"Returns only published public articles for the requested portal and locale. On the nested category route, category_slug must resolve inside the same portal and locale; an unknown or operator-only category is not treated as an unfiltered listing. This endpoint is unauthenticated and returns JSON when requested.","security":[],"responses":{"200":{"description":"Published public articles and pagination metadata.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/public_help_center_article_list_response"},"example":{"payload":[{"id":1,"category_id":1,"title":"Sample title","content":"Sample content text.","description":"A short description.","status":"published","visibility":"public","position":1,"account_id":1,"last_updated_at":"2026-01-15T10:30:00.000Z","slug":"sample-slug","portal":{"custom_domain":"sample custom domain","header_text":"sample header text","homepage_link":"https://example.com/resource","name":"Sample Name","page_title":"sample page title","slug":"sample-slug","categories":[{"name":"Sample Name","slug":"sample-slug","locale":"en","description":"A short description.","position":1,"visibility":"public","meta":{"articles_count":5}}],"logo":{"id":1,"portal_id":1,"file_type":"image","account_id":1,"file_url":"https://example.com/resource","blob_id":"sample blob id","filename":"sample filename"},"meta":{"articles_count":5,"categories_count":5,"default_locale":"sample default locale"}},"category":{"id":1,"slug":"sample-slug","locale":"en"},"views":1,"author":{"available_name":"sample available name","name":"Sample Name","thumbnail":"https://example.com/resource"},"associated_articles":[{"id":1,"category_id":1,"title":"Sample title","content":"Sample content text.","description":"A short description.","status":"published","visibility":"public","account_id":1,"last_updated_at":"2026-01-15T10:30:00.000Z","views":1,"author":{"available_name":"sample available name","name":"Sample Name","thumbnail":"https://example.com/resource"}}],"link":"sample link"}],"meta":{"articles_count":5}}}}}},"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}},{"name":"locale","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."},{"name":"query","in":"query","required":false,"schema":{"type":"string"}},{"name":"locale","in":"query","required":false,"schema":{"type":"string","enum":["en","pt_BR","es"]}},{"name":"sort","in":"query","required":false,"schema":{"type":"string"}},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["draft","published","archived"]}},{"name":"per_page","in":"query","required":false,"schema":{"type":"string"}}]}},"/hc/{slug}/{locale}/categories":{"get":{"tags":["{locale}"],"operationId":"auto_get_hc_slug_locale_categories","summary":"List public Help Center categories","description":"Returns public categories for the requested portal and locale in portal order. Operator-only categories are excluded. This endpoint is unauthenticated and returns JSON when requested; its HTML form redirects to the locale reader.","security":[],"responses":{"200":{"description":"Public categories in portal order.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/public_help_center_category_list_response"},"example":{"payload":[{"name":"Sample Name","slug":"sample-slug","locale":"en","description":"A short description.","position":1,"visibility":"public","meta":{"articles_count":5}}]}}}}},"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}},{"name":"locale","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."}]}},"/hc/{slug}/{locale}/categories/{category_slug}":{"get":{"tags":["{locale}"],"operationId":"auto_get_hc_slug_locale_categories_category_slug","summary":"Read a public Help Center category","description":"Returns one public category scoped by portal, locale, and category slug. An operator-only or unknown category is not disclosed. This endpoint is unauthenticated and returns JSON when requested.","security":[],"responses":{"200":{"description":"Public category for the requested portal, locale, and category slug.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/public_help_center_category"},"example":{"name":"Sample Name","slug":"sample-slug","locale":"en","description":"A short description.","position":1,"visibility":"public","meta":{"articles_count":5}}}}}},"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}},{"name":"locale","in":"path","required":true,"schema":{"type":"string"}},{"name":"category_slug","in":"path","required":true,"schema":{"type":"string"}}]}},"/hc/{slug}/{locale}/categories/{category_slug}/articles":{"get":{"tags":["{locale}"],"operationId":"auto_get_hc_slug_locale_categories_category_slug_articles","summary":"List public Help Center articles","description":"Returns only published public articles for the requested portal and locale. On the nested category route, category_slug must resolve inside the same portal and locale; an unknown or operator-only category is not treated as an unfiltered listing. This endpoint is unauthenticated and returns JSON when requested.","security":[],"responses":{"200":{"description":"Published public articles and pagination metadata.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/public_help_center_article_list_response"},"example":{"payload":[{"id":1,"category_id":1,"title":"Sample title","content":"Sample content text.","description":"A short description.","status":"published","visibility":"public","position":1,"account_id":1,"last_updated_at":"2026-01-15T10:30:00.000Z","slug":"sample-slug","portal":{"custom_domain":"sample custom domain","header_text":"sample header text","homepage_link":"https://example.com/resource","name":"Sample Name","page_title":"sample page title","slug":"sample-slug","categories":[{"name":"Sample Name","slug":"sample-slug","locale":"en","description":"A short description.","position":1,"visibility":"public","meta":{"articles_count":5}}],"logo":{"id":1,"portal_id":1,"file_type":"image","account_id":1,"file_url":"https://example.com/resource","blob_id":"sample blob id","filename":"sample filename"},"meta":{"articles_count":5,"categories_count":5,"default_locale":"sample default locale"}},"category":{"id":1,"slug":"sample-slug","locale":"en"},"views":1,"author":{"available_name":"sample available name","name":"Sample Name","thumbnail":"https://example.com/resource"},"associated_articles":[{"id":1,"category_id":1,"title":"Sample title","content":"Sample content text.","description":"A short description.","status":"published","visibility":"public","account_id":1,"last_updated_at":"2026-01-15T10:30:00.000Z","views":1,"author":{"available_name":"sample available name","name":"Sample Name","thumbnail":"https://example.com/resource"}}],"link":"sample link"}],"meta":{"articles_count":5}}}}}},"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}},{"name":"locale","in":"path","required":true,"schema":{"type":"string"}},{"name":"category_slug","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."},{"name":"query","in":"query","required":false,"schema":{"type":"string"}},{"name":"locale","in":"query","required":false,"schema":{"type":"string","enum":["en","pt_BR","es"]}},{"name":"sort","in":"query","required":false,"schema":{"type":"string"}},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["draft","published","archived"]}},{"name":"per_page","in":"query","required":false,"schema":{"type":"string"}}]}},"/hc/{slug}/articles/{article_slug}":{"get":{"tags":["Help Center"],"operationId":"auto_get_hc_slug_articles_article_slug","summary":"Read a public Help Center article","description":"Returns one published public article by its portal-scoped slug. Operator-only, draft, archived, and articles under an operator-only category return the portal's not-found response rather than exposing their metadata. This endpoint is unauthenticated and returns JSON when requested.","security":[],"responses":{"200":{"description":"Published public article for the requested portal-scoped slug.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/public_help_center_article"},"example":{"id":1,"category_id":1,"title":"Sample title","content":"Sample content text.","description":"A short description.","status":"published","visibility":"public","position":1,"account_id":1,"last_updated_at":"2026-01-15T10:30:00.000Z","slug":"sample-slug","portal":{"custom_domain":"sample custom domain","header_text":"sample header text","homepage_link":"https://example.com/resource","name":"Sample Name","page_title":"sample page title","slug":"sample-slug","categories":[{"name":"Sample Name","slug":"sample-slug","locale":"en","description":"A short description.","position":1,"visibility":"public","meta":{"articles_count":5}}],"logo":{"id":1,"portal_id":1,"file_type":"image","account_id":1,"file_url":"https://example.com/resource","blob_id":"sample blob id","filename":"sample filename"},"meta":{"articles_count":5,"categories_count":5,"default_locale":"sample default locale"}},"category":{"id":1,"slug":"sample-slug","locale":"en"},"views":1,"author":{"available_name":"sample available name","name":"Sample Name","thumbnail":"https://example.com/resource"},"associated_articles":[{"id":1,"category_id":1,"title":"Sample title","content":"Sample content text.","description":"A short description.","status":"published","visibility":"public","account_id":1,"last_updated_at":"2026-01-15T10:30:00.000Z","views":1,"author":{"available_name":"sample available name","name":"Sample Name","thumbnail":"https://example.com/resource"}}],"link":"sample link"}}}}},"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}},{"name":"article_slug","in":"path","required":true,"schema":{"type":"string"}}]}},"/webhooks/twitter":{"get":{"tags":["Inbound Webhooks"],"operationId":"auto_get_webhooks_twitter","summary":"Twitter/X Account Activity webhook challenge","description":"Public Twitter/X CRC challenge endpoint. It signs the supplied `crc_token` with the configured consumer secret and returns only the required response token; no account API or user credential is used for this provider-to-server request.","security":[{"twitterWebhookHmac":[]}],"responses":{"200":{"description":"CRC response token","content":{"application/json":{"schema":{"type":"object","required":["response_token"],"properties":{"response_token":{"type":"string","example":"sha256=JcQd4DTX8K5R03l2c8B6GqAZQY1b0UoKYqDHmL2eOTo="}}},"example":{"response_token":"sha256=JcQd4DTX8K5R03l2c8B6GqAZQY1b0UoKYqDHmL2eOTo="}}}}},"parameters":[{"name":"crc_token","in":"query","required":true,"description":"Challenge token sent by Twitter/X; the response returns its HMAC-SHA256 signature.","schema":{"type":"string"},"example":"abc123"}],"x-authentication":{"kind":"credential","scheme":"twitterWebhookHmac","location":"header","name":"x-twitter-webhooks-signature","verification_boundary":"Twitter/X exact raw-body verifier","algorithm":"HMAC-SHA256"}},"post":{"tags":["Inbound Webhooks"],"operationId":"auto_post_webhooks_twitter","summary":"Twitter/X account activity webhook","description":"Receives a Twitter/X Account Activity envelope after validating the HMAC-SHA256 Base64 signature over the raw request body. The required signature is checked before parsing the body or selecting the subscribed account; a verified delivery is queued without a pre-enqueue claim. Workers deduplicate each supported event by its provider identity after enqueue. Unsupported official Account Activity families are acknowledged without queueing so X does not retry them forever. The receiver accepts at most 256 KiB of raw JSON and 25 supported events per envelope. Invalid or missing signatures return 401, malformed JSON returns 400, oversized bodies return 413, and accepted deliveries return 200.","security":[{"twitterWebhookHmac":[]}],"responses":{"200":{"description":"Verified supported events queued; unsupported official families acknowledged without queueing"},"400":{"description":"Signature is valid but the body is malformed JSON, has no event family, or a consumed family lacks for_user_id"},"401":{"description":"Missing, malformed, or invalid x-twitter-webhooks-signature"},"413":{"description":"Raw request body exceeds the 256 KiB limit before JSON parsing"},"500":{"description":"Unexpected failure after signature verification; X may retry"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","title":"X Account Activity event envelope","additionalProperties":true,"maxProperties":100,"description":"Signed Account Activity envelope. Provider-defined event families remain open and bounded; this installation consumes direct_message_events and tweet_create_events and acknowledges other official families without queueing them. `for_user_id` is required when either consumed family is present, but official lifecycle envelopes such as `user_event` can omit it.","properties":{"for_user_id":{"type":"string","minLength":1,"maxLength":16384,"example":"2244994945","description":"Subscription user id; required for consumed direct-message and tweet-create families."},"direct_message_events":{"type":"array","minItems":1,"maxItems":25,"items":{"type":"object","additionalProperties":true,"description":"X direct-message event. Provider-owned fields remain open; every nested string, object and array is still subject to the receiver's byte, key, item and depth bounds."}},"tweet_create_events":{"type":"array","minItems":1,"maxItems":25,"items":{"type":"object","additionalProperties":true,"description":"X tweet-create event with provider-owned, structurally bounded fields."}},"users":{"type":"object","additionalProperties":true,"description":"Optional X user dictionary carried with Account Activity events."},"user_has_blocked":{"type":"boolean"}}},"example":{"for_user_id":"2244994945","direct_message_events":[{}],"tweet_create_events":[{}],"users":{},"user_has_blocked":true}}}},"parameters":[{"name":"x-twitter-webhooks-signature","in":"header","required":true,"description":"`sha256=` followed by Base64(HMAC-SHA256(raw request body, Twitter/X consumer secret)). Compared in constant time; never log or expose the consumer secret.","schema":{"type":"string","example":"sha256=JcQd4DTX8K5R03l2c8B6GqAZQY1b0UoKYqDHmL2eOTo="}}],"x-authentication":{"kind":"credential","scheme":"twitterWebhookHmac","location":"header","name":"x-twitter-webhooks-signature","verification_boundary":"Twitter/X exact raw-body verifier","algorithm":"HMAC-SHA256"}}},"/webhooks/line/{line_channel_id}":{"post":{"tags":["Inbound Webhooks"],"operationId":"auto_post_webhooks_line_line_channel_id","summary":"LINE channel webhook","description":"Receives the LINE Messaging API webhook envelope for the channel identified by the path id (signature validated downstream).","security":[{"lineWebhookHmac":[]}],"responses":{"200":{"description":"Success (no content)"}},"parameters":[{"name":"line_channel_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"x-line-signature","in":"header","required":true,"description":"LINE's request signature — the base64-encoded `HMAC_SHA256(\u003cchannel secret\u003e, \u003craw request body\u003e)`. It is forwarded verbatim with the raw body to the background job, which validates it against the channel secret before any event is ingested.","schema":{"type":"string","example":"XWmrwMey6OsLMeiZKwP4FppHH3cmMV0rrEisNt7s5rQ="}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"destination":{"type":"string","description":"Bot user id","example":"U4af4980629..."},"events":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"LINE webhook event object"}}}},"example":{"destination":"U4af4980629...","events":[{}]}}}},"x-authentication":{"kind":"credential","scheme":"lineWebhookHmac","location":"header","name":"x-line-signature","verification_boundary":"LINE exact raw-body verifier","algorithm":"HMAC-SHA256"}}},"/webhooks/telegram/{webhook_id}":{"post":{"tags":["Inbound Webhooks"],"operationId":"auto_post_webhooks_telegram_webhook_id","summary":"Telegram bot webhook","description":"Receives a Telegram Bot API Update object addressed by an opaque webhook identifier. Legacy bot-token paths are a time-bounded compatibility path only and must not be used for new integrations.","security":[],"responses":{"200":{"description":"Success (no content)"}},"parameters":[{"name":"webhook_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"update_id":{"type":"integer","example":10000},"message":{"type":"object","additionalProperties":true,"description":"Present for new messages (Telegram Message object)"},"callback_query":{"type":"object","additionalProperties":true,"description":"Present for inline-button callbacks"}}},"example":{"update_id":10000,"message":{},"callback_query":{}}}}},"x-authentication":{"kind":"capability","scheme":"telegramWebhookPath","location":"path","name":"webhook_id","verification_boundary":"Webhooks::TelegramController#process_payload","algorithm":"opaque"}}},"/webhooks/sms/{phone_number}":{"post":{"tags":["Inbound Webhooks"],"operationId":"auto_post_webhooks_sms_phone_number","summary":"SMS (Bandwidth) webhook","description":"Receives a Bandwidth Messaging V2 callback array for the configured number. Every delivery must use the per-channel HTTP Basic credential pair configured in both Bandwidth InboundCallbackCreds and OutboundCallbackCreds. Inbound deliveries bind the path number, envelope `to`, `message.owner`, a recipient in `message.to`, and `message.applicationId` to the same channel; outbound status deliveries bind `message.from` and `message.applicationId`. During the expand/contract rollout only, a channel created before callback credentials existed may deliver without an Authorization header while it remains unverified; the same strict tenant bindings still apply, and any explicitly supplied invalid credential is rejected. A successful provider reconciliation permanently enables Basic enforcement for that channel, including when its local encrypted material later becomes unavailable. The receiver accepts 1–50 events and at most 1 MiB of raw JSON. Duplicate message-id/type deliveries are acknowledged without a second ingestion.","security":[{"bandwidthCallbackBasic":[]}],"responses":{"200":{"description":"Callback delivery accepted for asynchronous processing, or a duplicate acknowledged without reinsertion"},"400":{"description":"Request exceeds the 1 MiB/50-event bounds, is malformed, or fails event type, id, destination-number, or application binding validation"},"401":{"description":"Callback authentication failed; unknown, disabled, post-reconciliation missing-auth and wrong-credential states intentionally share this response and advertise the same HTTP Basic challenge for Bandwidth's authenticated retry.","headers":{"WWW-Authenticate":{"description":"The identical HTTP Basic challenge returned for every authentication failure.","schema":{"type":"string","pattern":"^Basic realm=\"Bandwidth Messaging callback\", charset=\"UTF-8\"$","example":"Basic realm=\"Bandwidth Messaging callback\", charset=\"UTF-8\""}}}},"500":{"description":"Callback enqueue failed before acknowledgment; Bandwidth may retry"}},"parameters":[{"name":"phone_number","in":"path","required":true,"description":"E.164 destination number assigned to the Bandwidth application, without the leading plus sign (6–15 digits).","schema":{"type":"string","pattern":"^[1-9][0-9]{5,14}$","example":"15551234567"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"array","minItems":1,"maxItems":50,"items":{"type":"object","additionalProperties":true,"required":["type","message"],"properties":{"type":{"type":"string","enum":["message-received","message-delivered","message-failed"],"example":"message-received"},"to":{"type":"string","maxLength":32768,"example":"+15551234567"},"message":{"type":"object","additionalProperties":true,"description":"Official Bandwidth Messaging V2 callback message object. The exact required ownership fields depend on the callback type below; provider fields not explicitly handled remain UNVERIFIED.","properties":{"id":{"type":"string","minLength":1,"maxLength":128,"pattern":"^\\\\S+$","example":"msg-7f391bc3"},"applicationId":{"type":"string","format":"uuid","pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$","description":"Bandwidth application UUID; matching is case-insensitive because UUID hex casing is non-semantic.","example":"e5a9e103-097e-4ec4-87a0-50109fb7b4b1"},"direction":{"type":"string","enum":["in","out"]},"owner":{"type":"string","maxLength":32768},"from":{"type":"string","maxLength":32768},"to":{"type":"array","maxItems":20,"items":{"type":"string","maxLength":32768}},"text":{"type":"string","maxLength":32768},"media":{"type":"array","maxItems":10,"description":"At most ten provider media URLs are accepted for one message.","items":{"type":"string","format":"uri","maxLength":32768}}}}},"oneOf":[{"properties":{"type":{"type":"string","enum":["message-received"],"const":"message-received"},"message":{"required":["id","applicationId","direction","owner","to"],"properties":{"direction":{"type":"string","enum":["in"],"const":"in"},"to":{"type":"array","minItems":1}}}},"required":["to"]},{"properties":{"type":{"type":"string","enum":["message-delivered","message-failed"]},"message":{"required":["id","applicationId","direction","from"],"properties":{"direction":{"type":"string","enum":["out"],"const":"out"}}}}}]}},"example":[{"type":"message-received","message":{"direction":"in","to":["sample to"]}}]}}},"x-authentication":{"kind":"credential","scheme":"bandwidthCallbackBasic","location":"header","name":"Authorization","verification_boundary":"Bandwidth per-channel Basic credential verifier","algorithm":"HTTP Basic"}}},"/webhooks/whatsapp":{"get":{"tags":["Inbound Webhooks"],"operationId":"auto_get_webhooks_whatsapp","summary":"WhatsApp Cloud webhook verification (Meta hub.challenge)","description":"Meta subscription handshake — echoes `hub.challenge` back when `hub.verify_token` matches the channel/installation verify token.","security":[],"responses":{"200":{"description":"The hub.challenge value echoed back (JSON-encoded string).","content":{"application/json":{"schema":{"type":"string","example":"158201444"},"example":"158201444"}}},"401":{"description":"Wrong verify token.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error; wrong verify token"}}},"example":{"error":"Error; wrong verify token"}}}}},"x-authentication":{"kind":"conditional","condition":"Meta challenge request.","alternatives":[{"kind":"capability","scheme":"metaHubVerifyToken","location":"query","name":"hub.verify_token","verification_boundary":"Meta webhook verification action","algorithm":"opaque"}]}},"post":{"tags":["Inbound Webhooks"],"operationId":"auto_post_webhooks_whatsapp","summary":"WhatsApp Cloud webhook events","description":"Receives the Meta WhatsApp Cloud webhook envelope (messages, statuses, templates, flows, calls, coexistence/history — see the Cloud API webhooks contract). Signature-checked (X-Hub-Signature-256) when an app secret is configured; processing is asynchronous.","security":[{"metaWebhookHmac":[]}],"responses":{"200":{"description":"Success (no content)"},"422":{"description":"Every WhatsApp number the delivery targets is on the installation's inactive-number list, so the batch is refused instead of being queued and the reason is returned as JSON. A batch that mixes active and inactive numbers is NOT refused: it is accepted with 200 and the inactive units are dropped individually while it is processed, so that active siblings are not lost and the sender is not driven into a retry loop on an unchanging payload.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","description":"Human-readable reason the delivery was refused. The receiver emits the single literal \"Inactive WhatsApp number\" for this condition."}}},"example":{"error":"Inactive WhatsApp number"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"required":["object","entry"],"properties":{"object":{"type":"string","example":"whatsapp_business_account"},"entry":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"id":{"type":"string","description":"WABA id","example":"102290129340398"},"changes":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"field":{"type":"string","example":"messages"},"value":{"type":"object","additionalProperties":true,"description":"Field-specific payload (messages/statuses/etc.)"}}}}}}}}},"example":{"object":"whatsapp_business_account","entry":[{"id":"102290129340398","changes":[{"field":"messages","value":{}}]}]}}}},"parameters":[{"name":"X-Hub-Signature-256","in":"header","required":false,"description":"HMAC-SHA256 of the raw request body, keyed with the app secret, in the form `sha256=\u003chex\u003e`. Verified before any side effect. Optional in the schema only because an installation can run a channel without a configured app secret; whenever a secret IS configured for any channel this delivery resolves, the header is REQUIRED and a missing or wrong value is rejected.","schema":{"type":"string","example":"sha256=7d38cdd689735b008b3c702edd92eea23791c5f6"}}],"x-authentication":{"kind":"conditional","condition":"Meta HMAC requirement depends on the resolved WhatsApp channel and configured strict mode.","alternatives":[{"kind":"capability","scheme":"metaWebhookHmac","location":"header","name":"X-Hub-Signature-256","verification_boundary":"resolved WhatsApp channel strict mode","algorithm":"HMAC-SHA256"}]}}},"/webhooks/whatsapp/{phone_number}":{"get":{"tags":["Inbound Webhooks"],"operationId":"auto_get_webhooks_whatsapp_phone_number","summary":"WhatsApp Cloud webhook verification (Meta hub.challenge)","description":"Meta subscription handshake — echoes `hub.challenge` back when `hub.verify_token` matches the channel/installation verify token.","security":[],"responses":{"200":{"description":"The hub.challenge value echoed back (JSON-encoded string).","content":{"application/json":{"schema":{"type":"string","example":"158201444"},"example":"158201444"}}},"401":{"description":"Wrong verify token.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error; wrong verify token"}}},"example":{"error":"Error; wrong verify token"}}}}},"parameters":[{"name":"phone_number","in":"path","required":true,"schema":{"type":"string"}}],"x-authentication":{"kind":"conditional","condition":"Meta challenge request.","alternatives":[{"kind":"capability","scheme":"metaHubVerifyToken","location":"query","name":"hub.verify_token","verification_boundary":"Meta webhook verification action","algorithm":"opaque"}]}},"post":{"tags":["Inbound Webhooks"],"operationId":"auto_post_webhooks_whatsapp_phone_number","summary":"WhatsApp Cloud webhook events","description":"Receives the Meta WhatsApp Cloud webhook envelope (messages, statuses, templates, flows, calls, coexistence/history — see the Cloud API webhooks contract). Signature-checked (X-Hub-Signature-256) when an app secret is configured; processing is asynchronous.","security":[{"metaWebhookHmac":[]}],"responses":{"200":{"description":"Success (no content)"},"422":{"description":"Every WhatsApp number the delivery targets is on the installation's inactive-number list, so the batch is refused instead of being queued and the reason is returned as JSON. A batch that mixes active and inactive numbers is NOT refused: it is accepted with 200 and the inactive units are dropped individually while it is processed, so that active siblings are not lost and the sender is not driven into a retry loop on an unchanging payload.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","description":"Human-readable reason the delivery was refused. The receiver emits the single literal \"Inactive WhatsApp number\" for this condition."}}},"example":{"error":"Inactive WhatsApp number"}}}}},"parameters":[{"name":"phone_number","in":"path","required":true,"schema":{"type":"string"}},{"name":"X-Hub-Signature-256","in":"header","required":false,"description":"HMAC-SHA256 of the raw request body, keyed with the app secret, in the form `sha256=\u003chex\u003e`. Verified before any side effect. Optional in the schema only because an installation can run a channel without a configured app secret; whenever a secret IS configured for any channel this delivery resolves, the header is REQUIRED and a missing or wrong value is rejected.","schema":{"type":"string","example":"sha256=7d38cdd689735b008b3c702edd92eea23791c5f6"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"required":["object","entry"],"properties":{"object":{"type":"string","example":"whatsapp_business_account"},"entry":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"id":{"type":"string","description":"WABA id","example":"102290129340398"},"changes":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"field":{"type":"string","example":"messages"},"value":{"type":"object","additionalProperties":true,"description":"Field-specific payload (messages/statuses/etc.)"}}}}}}}}},"example":{"object":"whatsapp_business_account","entry":[{"id":"102290129340398","changes":[{"field":"messages","value":{}}]}]}}}},"x-authentication":{"kind":"conditional","condition":"Meta HMAC requirement depends on the resolved WhatsApp channel and configured strict mode.","alternatives":[{"kind":"capability","scheme":"metaWebhookHmac","location":"header","name":"X-Hub-Signature-256","verification_boundary":"resolved WhatsApp channel strict mode","algorithm":"HMAC-SHA256"}]}}},"/webhooks/whatsapp_web/{user_id}":{"post":{"tags":["Inbound Webhooks"],"operationId":"auto_post_webhooks_whatsapp_web_user_id","summary":"Receive a WhatsApp Web gateway event","description":"Ingestion endpoint for the WazMeow WhatsApp Web gateway, which posts every event of a paired number here (messages, receipts, pairing and connection changes). The delivery is authenticated by constant-time comparing the per-inbox token echoed in the envelope, the userID in the body is cross-checked against the path parameter, and the envelope is de-duplicated by its delivery id before the event is handed to a background ingestion job. The response is an empty acknowledgement with no body — the gateway only needs a 2xx to clear the event from its retry buffer, which is why a repeated delivery and a payload above the ingestion size cap are also acknowledged and dropped rather than rejected.","security":[],"responses":{"200":{"description":"Event accepted for ingestion, or acknowledged and dropped because it repeats a delivery already seen or exceeds the ingestion size cap. Empty body."},"400":{"description":"The request body is not valid JSON."},"403":{"description":"The token echoed in the envelope does not match the inbox token, or the userID in the body does not match the one in the path."},"404":{"description":"No WhatsApp Web inbox is provisioned for this gateway user id."},"500":{"description":"Unexpected failure while accepting the event; the gateway should retry."}},"parameters":[{"name":"user_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"X-Event-ID","in":"header","required":false,"description":"Per-delivery identifier used to de-duplicate the envelope for one hour. When absent the `id` field of the envelope is used instead; when neither is present the delivery is not de-duplicated and a gateway retry is ingested twice.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["token","userID"],"additionalProperties":true,"properties":{"token":{"type":"string","description":"Per-inbox token echoed by the gateway and compared in constant time."},"userID":{"type":"string","description":"Gateway user id; it must equal the user_id path parameter."},"id":{"type":"string","description":"Optional delivery id used when X-Event-ID is absent."},"data":{"type":"object","additionalProperties":true,"description":"Provider-owned event payload; its fields depend on the event family."}}},"example":{"token":"whsec_inbox_example","userID":"9d19f6e22fb9b3bfb87119f34698b314","id":"evt_01J5J7Q2A1","data":{}}}}},"x-authentication":{"kind":"capability","scheme":"webhookBodyToken","location":"body","name":"token","verification_boundary":"resolved per-user webhook capability","algorithm":"opaque"}}},"/webhooks/growth_social/{user_id}":{"post":{"tags":["Inbound Webhooks"],"operationId":"auto_post_webhooks_growth_social_user_id","summary":"Receive a social automation gateway event","description":"Ingestion endpoint for the social automation gateway that drives the Instagram and TikTok growth surfaces. The delivery is authenticated by constant-time comparing the per-account gateway token echoed in the envelope, the userID in the body is cross-checked against the path parameter, and the envelope is de-duplicated by its delivery id before the event is handed to a background job. The response is an empty acknowledgement with no body; a repeated delivery is acknowledged the same way so the gateway can clear it from its retry buffer.","security":[],"responses":{"200":{"description":"Event accepted for ingestion, or acknowledged as a repeated delivery. Empty body."},"400":{"description":"The request body is not valid JSON."},"403":{"description":"The token echoed in the envelope does not match the stored gateway token, or the userID in the body does not match the one in the path."},"404":{"description":"No social account is registered for this gateway user id."},"500":{"description":"Unexpected failure while accepting the event; the gateway should retry."}},"parameters":[{"name":"user_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"X-Event-ID","in":"header","required":false,"description":"Per-delivery identifier used to de-duplicate the envelope for one hour. When absent the `id` field of the envelope is used instead; when neither is present the delivery is not de-duplicated and a gateway retry is ingested twice.","schema":{"type":"string"}}],"x-authentication":{"kind":"capability","scheme":"webhookBodyToken","location":"body","name":"token","verification_boundary":"resolved per-user webhook capability","algorithm":"opaque"}}},"/webhooks/bug_reports/linear":{"post":{"tags":["Inbound Webhooks"],"operationId":"auto_post_webhooks_bug_reports_linear","summary":"Receive installation Linear events","description":"Verifies raw-body HMAC-SHA256 with the persisted installation registration secret, organizationId, webhookId and numeric webhookTimestamp within60seconds. Binding restricts issue/workspace/team. Event clocks order provider changes and remove wins an equal clock. The linked official provider documentation supplies the event contract; no live event capture is claimed. This supplier receiver is never an ordinary MCP tool.","security":[{"linearWebhookHmac":[]}],"responses":{"200":{"description":"Processed or deliberately ignored matching event. Empty body."},"401":{"description":"Invalid signature, stale or nonnumeric timestamp, or unknown/mismatched registration identity. Empty body."},"500":{"description":"Local processing failure. Empty body; provider may redeliver the signed event."}},"externalDocs":{"description":"Official Linear webhook event and signature documentation.","url":"https://linear.app/developers/webhooks"},"requestBody":{"required":true,"description":"Signed provider envelope. The data body is provider-owned; this schema is documentation, not a fabricated live capture.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Provider-owned Linear webhook envelope with authenticated installation identity and bounded timestamp freshness.","required":["type","action","data","organizationId","webhookId","webhookTimestamp"],"properties":{"type":{"type":"string","enum":["Issue","Comment","Attachment"]},"action":{"type":"string","enum":["create","update","remove"]},"organizationId":{"type":"string"},"webhookId":{"type":"string"},"webhookTimestamp":{"type":"number"},"createdAt":{"type":"string","format":"date-time"},"data":{"type":"object","additionalProperties":true,"description":"Entity change from Linear; shape depends on the provider event type. The processor reads verified identity and clock fields before applying supported changes."}}},"example":{"type":"Issue","action":"create","organizationId":"sample organizationId","webhookId":"sample webhookId","webhookTimestamp":12.5,"createdAt":"2026-01-15T10:30:00.000Z","data":{}}}}},"parameters":[{"name":"Linear-Signature","in":"header","required":true,"description":"Hex HMAC-SHA256 of exact request bytes using the installation registration secret.","schema":{"type":"string","pattern":"^[a-fA-F0-9]{64}$"}}],"x-authentication":{"kind":"credential","scheme":"linearWebhookHmac","location":"header","name":"Linear-Signature","verification_boundary":"Linear exact raw-body verifier","algorithm":"HMAC-SHA256"}}},"/webhooks/bug_reports/linear/{account_id}":{"post":{"tags":["Inbound Webhooks"],"operationId":"auto_post_webhooks_bug_reports_linear_account_id","summary":"Retired account Linear bug-report webhook","description":"Always returns410 with an empty body and does not verify credentials, create messages or alter any report. Account Linear OAuth is unrelated to installation Bug Reports.","security":[],"responses":{"410":{"description":"Account-scoped Bug Reports webhooks are retired. Empty body."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"deprecated":true}},"/webhooks/whatsapp_flow_endpoint/{identifier}":{"post":{"tags":["Inbound Webhooks"],"operationId":"auto_post_webhooks_whatsapp_flow_endpoint_identifier","summary":"WhatsApp Flow data-exchange endpoint","description":"Meta Flows encrypted data-exchange (per-channel opaque identifier in the path). Body is the standard Meta encrypted triplet; the response is the base64 ENCRYPTED next-screen payload as text/plain. HTTP 421 specifically indicates RSA key unwrap failure so Meta can refresh keys. Malformed encrypted envelopes return 400; server key configuration or authenticated-payload decryption failures return 500. Endpoint identifiers are matched exactly; ambiguous identifiers return 404. Invalid or unrecognized request tokens return HTTP 427 with an encrypted error_msg payload.","security":[],"responses":{"200":{"description":"Base64 encrypted response payload.","content":{"text/plain":{"schema":{"type":"string","example":"kJ8s0d...base64..."}}}},"400":{"description":"Malformed encrypted request envelope."},"421":{"description":"RSA unwrap failed; refresh the registered public key."},"432":{"description":"Missing or invalid configured request signature."},"404":{"description":"Unknown or ambiguous flow endpoint identifier."},"500":{"description":"Missing or invalid server private key, or authenticated payload decryption failure; this is not a public-key refresh instruction."},"427":{"description":"Invalid or unrecognized flow token. The encrypted payload contains error_msg and disables the unavailable flow.","content":{"text/plain":{"schema":{"type":"string","example":"kJ8s0d...base64..."}}}}},"parameters":[{"name":"identifier","in":"path","required":true,"schema":{"type":"string"}},{"name":"X-Hub-Signature-256","in":"header","required":false,"description":"Meta's payload signature — `sha256=` followed by the hex-encoded `HMAC_SHA256(\u003capp secret\u003e, \u003craw request body\u003e)`. The app secret is the channel's own or the installation-wide one. Verified in constant time and rejected with 432 on mismatch whenever an app secret is configured; when none is, the check is skipped and the RSA key exchange is the confidentiality layer, not sender authentication. Operational requests additionally require a persisted token issued for this channel. Meta always sends this header, so configure an app secret.","schema":{"type":"string","example":"sha256=6f3a1c9d05b7e2a48c1f0d63b8e57a92d4c1b0f7e39a6c25d81f4b70a2e6c318"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["encrypted_flow_data","encrypted_aes_key","initial_vector"],"properties":{"encrypted_flow_data":{"type":"string","description":"AES-GCM encrypted request payload (base64)"},"encrypted_aes_key":{"type":"string","description":"RSA-OAEP encrypted AES key (base64)"},"initial_vector":{"type":"string","description":"AES IV (base64)"}}},"example":{"encrypted_flow_data":"sample encrypted flow data","encrypted_aes_key":"sample-token","initial_vector":"sample initial vector"}}}},"x-authentication":{"kind":"capability","scheme":"whatsappFlowRsa","location":"path","name":"identifier","verification_boundary":"WhatsApp Flow endpoint resolver","algorithm":"RSA-OAEP-256","encryption":"RSA-OAEP-256"}}},"/webhooks/maestro_calls/{account_id}":{"post":{"tags":["Inbound Webhooks"],"operationId":"auto_post_webhooks_maestro_calls_account_id","summary":"Receive a Maestro AI call event","description":"Signed callback the Maestro sidecar uses to push the lifecycle and the result of an AI-answered WhatsApp call: the status flip and, when available, the transcript, summary, sentiment and recording URL, which are merged into the voice call message of the matching call and dispatched as call lifecycle events. The delivery is rejected outside the accepted clock-skew window, then verified with a constant-time HMAC-SHA256 comparison, cross-checked against the account in the path and de-duplicated by delivery id. The response is an empty acknowledgement with no body; an event referring to a call this installation does not know is acknowledged and ignored so a late push can never fail.","security":[{"maestroWebhookHmac":[]}],"responses":{"200":{"description":"Event applied, or acknowledged and ignored because it repeats a delivery already seen or refers to an unknown call. Empty body."},"400":{"description":"The request body is not valid JSON."},"401":{"description":"Timestamp outside the accepted skew window, or the signature does not match."},"403":{"description":"The account_id in the body does not match the one in the path."},"404":{"description":"Account not found."},"503":{"description":"The AI call webhook secret is not configured on this installation."},"500":{"description":"Unexpected failure while applying the event; the sidecar should retry."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"X-Maestro-Signature","in":"header","required":true,"description":"`sha256=` followed by the hex-encoded `HMAC_SHA256(\u003cAI call webhook secret\u003e, \"\u003cX-Maestro-Timestamp\u003e.\u003craw request body\u003e\")`. Compared in constant time after the skew check; a missing or mismatching value is rejected with 401.","schema":{"type":"string","example":"sha256=6f3a1c9d05b7e2a48c1f0d63b8e57a92d4c1b0f7e39a6c25d81f4b70a2e6c318"}},{"name":"X-Maestro-Timestamp","in":"header","required":true,"description":"Unix time in seconds at which the delivery was signed. It is part of the signed string and must be within 300 seconds of the receiver's clock; outside that window the delivery is rejected with 401 before any comparison is made (replay defense).","schema":{"type":"string","example":"1778735498"}},{"name":"X-Maestro-Delivery","in":"header","required":false,"description":"Per-delivery identifier used to de-duplicate the push for one hour. When absent the `delivery_id` field of the envelope is used instead; when neither is present the delivery is not de-duplicated and a retry is applied twice.","schema":{"type":"string"}}],"x-authentication":{"kind":"credential","scheme":"maestroWebhookHmac","location":"header","name":"X-Maestro-Signature","verification_boundary":"Maestro timestamped raw-body verifier","algorithm":"HMAC-SHA256"}}},"/webhooks/maestro_call_recordings/{account_id}":{"post":{"tags":["Inbound Webhooks"],"operationId":"auto_post_webhooks_maestro_call_recordings_account_id","summary":"Store an immutable Maestro call recording segment","description":"Receives native version 1 recording segments, signed with the installation's call-webhook secret shared across accounts. Tenant isolation is enforced by account_id in the path and envelope plus the call lookup. The signature is HMAC-SHA256 over timestamp, a dot and the exact JSON body. Timestamps must be within five minutes. Delivery ids do not reserve or acknowledge uploads: idempotency is durable per account and segment id, and order is unique within the physical call. The call must match the account, inbox and provider, and recording must be enabled. A positive ACK is returned only after committed storage is readable and matches the supplied SHA-256. Replays with different bytes, order or metadata conflict. Appending to a legacy unsegmented recording is refused; the legacy recording remains playable. No external recording URL is fetched. A successful ACK includes X-Maestro-Ack-Timestamp and X-Maestro-Ack-Signature headers. Its signature is sha256= followed by lowercase hex HMAC-SHA256 of maestro-recording-ack-v1, a colon, the ACK timestamp, a colon and the exact response body using the same call-webhook secret. Producers must validate this signature and five-minute timestamp window over HTTPS before purging their retained recording.","security":[{"maestroWebhookHmac":[]}],"responses":{"200":{"description":"Durable committed recording stored, or identical replay already stored; storage and digest verified.","headers":{"X-Maestro-Ack-Timestamp":{"description":"UTC Unix timestamp used to authenticate this acknowledgement.","schema":{"type":"string","pattern":"^[0-9]{1,12}$"},"example":"1790899200"},"X-Maestro-Ack-Signature":{"description":"sha256= followed by lowercase hex HMAC-SHA256 of the exact acknowledgement domain, timestamp and response bytes.","schema":{"type":"string","pattern":"^sha256=[0-9a-f]{64}$"},"example":"sha256=0000000000000000000000000000000000000000000000000000000000000000"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["status","segment_id","sha256"],"properties":{"status":{"type":"string","enum":["stored","already_stored"]},"segment_id":{"type":"string","format":"uuid"},"sha256":{"type":"string","pattern":"^[0-9a-f]{64}$"}}},"example":{"status":"stored","segment_id":"7adc39f8-3a3e-4e4f-876a-ef790af25b48","sha256":"e700dfd0455f7fc65a5847792900801c945226449672700b65e1fa8da633a0e7"}}}},"400":{"description":"Envelope schema is missing fields, contains unknown fields or has invalid typed metadata."},"401":{"description":"Signature, delivery id or timestamp is missing, invalid or expired."},"403":{"description":"Account mismatch, owner inconsistency or disabled recording policy."},"404":{"description":"Account or call is absent within the exact account, inbox and provider scope."},"409":{"description":"Segment identity or call ordinal conflicts, or an existing legacy recording has no segment model."},"413":{"description":"Raw request exceeds the bounded JSON transport size."},"422":{"description":"Invalid JSON/Base64, duplicate fields, empty or oversized audio, unsupported content type or digest mismatch."},"503":{"description":"Secret or verified storage is unavailable; no positive ACK is issued and the producer retains its spool."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"in":"header","name":"X-Maestro-Timestamp","required":true,"schema":{"type":"string","pattern":"^[0-9]{1,12}$"},"example":"1790899200"},{"in":"header","name":"X-Maestro-Signature","required":true,"schema":{"type":"string","pattern":"^sha256=[0-9a-f]{64}$"},"description":"Calculated for the exact timestamp and request body using the installation secret.","example":"sha256=0000000000000000000000000000000000000000000000000000000000000000"},{"in":"header","name":"X-Maestro-Delivery","required":true,"schema":{"type":"string","format":"uuid"},"example":"5e489968-f0ab-40f2-938e-5b1f222da8a3"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["schema_version","account_id","inbox_id","provider","provider_call_id","segment_id","ordinal","source","sha256","content_type","partial","audio_base64"],"properties":{"schema_version":{"type":"integer","enum":[1]},"account_id":{"type":"integer","minimum":1},"inbox_id":{"type":"integer","minimum":1},"provider":{"type":"string","enum":["whatsapp","whatsapp_web"]},"provider_call_id":{"type":"string","minLength":1,"maxLength":255},"segment_id":{"type":"string","format":"uuid"},"ordinal":{"type":"integer","minimum":0,"maximum":2147483647},"source":{"type":"string","enum":["ai","human"]},"sha256":{"type":"string","pattern":"^[0-9a-f]{64}$"},"content_type":{"type":"string","enum":["audio/wav","audio/webm","audio/ogg","audio/mpeg"]},"partial":{"type":"boolean"},"audio_base64":{"type":"string","contentEncoding":"base64","maxLength":11184812,"description":"Strict Base64 encoding of nonempty audio, at most 8MiB after decoding; whitespace is refused."}}},"example":{"schema_version":1,"account_id":1,"inbox_id":12,"provider":"whatsapp","provider_call_id":"synthetic-native-call","segment_id":"7adc39f8-3a3e-4e4f-876a-ef790af25b48","ordinal":0,"source":"ai","sha256":"e700dfd0455f7fc65a5847792900801c945226449672700b65e1fa8da633a0e7","content_type":"audio/wav","partial":false,"audio_base64":"UklGRkQAAABXQVZFZm10IBAAAAABAAEAgD4AAAB9AAACABAAZGF0YSAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=="}}}},"x-authentication":{"kind":"credential","scheme":"maestroWebhookHmac","location":"header","name":"X-Maestro-Signature","verification_boundary":"Maestro timestamped raw-body verifier","algorithm":"HMAC-SHA256"}}},"/webhooks/maestro_brain/{account_id}":{"post":{"tags":["Inbound Webhooks"],"operationId":"auto_post_webhooks_maestro_brain_account_id","summary":"Receive a Maestro brain event","description":"Signed ingestion endpoint the Maestro sidecar uses to push account brain events (risks, insights, department runs, profile updates and improvement suggestions). The sidecar never writes to this installation directly: this endpoint is the only writer of the account brain state, and it defers the write to a background job. The delivery is rejected outside the accepted clock-skew window, then verified with a constant-time HMAC-SHA256 comparison over the timestamp and the raw body, cross-checked against the account in the path and de-duplicated by delivery id. The response is an empty acknowledgement with no body.","security":[{"maestroWebhookHmac":[]}],"responses":{"200":{"description":"Event accepted for ingestion, or acknowledged as a repeated delivery. Empty body."},"400":{"description":"The request body is not valid JSON."},"401":{"description":"Timestamp outside the accepted skew window, or the signature does not match."},"403":{"description":"The account_id in the body does not match the one in the path."},"404":{"description":"Account not found."},"503":{"description":"The brain webhook secret is not configured on this installation."},"500":{"description":"Unexpected failure while accepting the event; the sidecar should retry."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"X-Maestro-Signature","in":"header","required":true,"description":"`sha256=` followed by the hex-encoded `HMAC_SHA256(\u003cbrain webhook secret\u003e, \"\u003cX-Maestro-Timestamp\u003e.\u003craw request body\u003e\")`. Compared in constant time after the skew check; a missing or mismatching value is rejected with 401.","schema":{"type":"string","example":"sha256=6f3a1c9d05b7e2a48c1f0d63b8e57a92d4c1b0f7e39a6c25d81f4b70a2e6c318"}},{"name":"X-Maestro-Timestamp","in":"header","required":true,"description":"Unix time in seconds at which the delivery was signed. It is part of the signed string and must be within 300 seconds of the receiver's clock; outside that window the delivery is rejected with 401 before any comparison is made (replay defense).","schema":{"type":"string","example":"1778735498"}},{"name":"X-Maestro-Delivery","in":"header","required":false,"description":"Per-delivery identifier used to de-duplicate the push for one hour. When absent the `delivery_id` field of the envelope is used instead; when neither is present the delivery is not de-duplicated and a retry is ingested twice.","schema":{"type":"string"}}],"x-authentication":{"kind":"credential","scheme":"maestroWebhookHmac","location":"header","name":"X-Maestro-Signature","verification_boundary":"Maestro timestamped raw-body verifier","algorithm":"HMAC-SHA256"}}},"/webhooks/maestro_turn/{account_id}":{"post":{"tags":["Inbound Webhooks"],"operationId":"auto_post_webhooks_maestro_turn_account_id","summary":"Receive a Maestro turn health event","description":"Signed ingestion endpoint the Maestro sidecar uses to report the health of an AI turn — an unverified claim, an altered reply, a failed tool, a failed turn or a requested handoff — so the installation can react (for example by escalating the conversation to a human). It shares the signing scheme and the secret of the brain ingestion endpoint but writes no brain record; the durable record of the turn stays on the sidecar. The delivery is rejected outside the accepted clock-skew window, then verified with a constant-time HMAC-SHA256 comparison over the timestamp and the raw body, cross-checked against the account in the path and de-duplicated by delivery id. An unrecognised event kind is acknowledged and logged rather than rejected. The response is an empty acknowledgement with no body.","security":[{"maestroWebhookHmac":[]}],"responses":{"200":{"description":"Event accepted for ingestion, or acknowledged as a repeated delivery. Empty body."},"400":{"description":"The request body is not valid JSON."},"401":{"description":"Timestamp outside the accepted skew window, or the signature does not match."},"403":{"description":"The account_id in the body does not match the one in the path."},"404":{"description":"Account not found."},"503":{"description":"The turn webhook secret is not configured on this installation."},"500":{"description":"Unexpected failure while accepting the event; the sidecar should retry."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"X-Maestro-Signature","in":"header","required":true,"description":"`sha256=` followed by the hex-encoded `HMAC_SHA256(\u003cturn webhook secret\u003e, \"\u003cX-Maestro-Timestamp\u003e.\u003craw request body\u003e\")`. The turn endpoint shares the signing scheme and the secret of the brain ingestion endpoint. Compared in constant time after the skew check; a missing or mismatching value is rejected with 401.","schema":{"type":"string","example":"sha256=6f3a1c9d05b7e2a48c1f0d63b8e57a92d4c1b0f7e39a6c25d81f4b70a2e6c318"}},{"name":"X-Maestro-Timestamp","in":"header","required":true,"description":"Unix time in seconds at which the delivery was signed. It is part of the signed string and must be within 300 seconds of the receiver's clock; outside that window the delivery is rejected with 401 before any comparison is made (replay defense).","schema":{"type":"string","example":"1778735498"}},{"name":"X-Maestro-Delivery","in":"header","required":false,"description":"Per-delivery identifier used to de-duplicate the push for one hour. When absent the `delivery_id` field of the envelope is used instead; when neither is present the delivery is not de-duplicated and a retry is ingested twice.","schema":{"type":"string"}}],"x-authentication":{"kind":"credential","scheme":"maestroWebhookHmac","location":"header","name":"X-Maestro-Signature","verification_boundary":"Maestro timestamped raw-body verifier","algorithm":"HMAC-SHA256"}}},"/webhooks/payments/{gateway}/{connection_id}":{"post":{"tags":["Inbound Webhooks"],"operationId":"auto_post_webhooks_payments_gateway_connection_id","summary":"Payment gateway webhook (Asaas / Mercado Pago)","description":"Per-connection receiver. Asaas authenticates via the asaas-access-token header and sends `{ id, event, payment }`; Mercado Pago signs via x-signature (HMAC manifest) and sends an id-only notification that is re-fetched. Envelope is deduplicated and processed asynchronously.","security":[{"asaasAccessToken":[]},{"mercadoPagoWebhookHmac":[]}],"responses":{"200":{"description":"Success (no content)"}},"parameters":[{"name":"gateway","in":"path","required":true,"schema":{"type":"string"}},{"name":"connection_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"asaas-access-token","in":"header","required":false,"description":"Asaas only. The `authToken` value registered with the Asaas webhook, echoed back on every delivery (Asaas does not sign its payloads). Compared in constant time with the token stored on the connection; a mismatch is rejected with 401. Required for an Asaas connection, absent on a Mercado Pago delivery.","schema":{"type":"string"}},{"name":"x-signature","in":"header","required":false,"description":"Mercado Pago only. `ts=\u003cunix seconds\u003e,v1=\u003chex HMAC\u003e`, where the HMAC is `HMAC_SHA256(\u003cconnection secret\u003e, \"id:\u003cdata.id\u003e;request-id:\u003cx-request-id\u003e;ts:\u003cts\u003e;\")` — the `data.id` lowercased when alphanumeric, and any segment whose source value is blank omitted from the manifest. Compared in constant time; a mismatch is rejected with 401. Required for a Mercado Pago connection, absent on an Asaas delivery.","schema":{"type":"string","example":"ts=1778735498,v1=6f3a1c9d05b7e2a48c1f0d63b8e57a92d4c1b0f7e39a6c25d81f4b70a2e6c318"}},{"name":"x-request-id","in":"header","required":false,"description":"Mercado Pago only. The delivery's request id, which is part of the signed manifest above. When Mercado Pago omits it, the `request-id` segment is dropped from the manifest before hashing.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"type":"object","title":"Asaas event","additionalProperties":true,"required":["event","payment"],"properties":{"id":{"type":"string","example":"evt_05b708f961d739ea7eba7e4db318f621\u0026368604920"},"event":{"type":"string","example":"PAYMENT_RECEIVED"},"payment":{"type":"object","additionalProperties":true,"properties":{"id":{"type":"string","example":"pay_080225913252"},"status":{"type":"string","example":"RECEIVED","enum":["PENDING","AWAITING_RISK_ANALYSIS","CONFIRMED","RECEIVED","RECEIVED_IN_CASH","OVERDUE","REFUNDED","REFUND_REQUESTED","REFUND_IN_PROGRESS","CHARGEBACK_REQUESTED","CHARGEBACK_DISPUTE","AWAITING_CHARGEBACK_REVERSAL","DUNNING_REQUESTED","DUNNING_RECEIVED","DELETED"],"description":"Raw Asaas payment status echoed in the webhook payload."},"externalReference":{"type":"string","example":"42"},"value":{"type":"number","example":149.9}}}}},{"type":"object","title":"Mercado Pago notification","additionalProperties":true,"required":["type","data"],"properties":{"type":{"type":"string","example":"payment"},"action":{"type":"string","example":"payment.created"},"live_mode":{"type":"boolean","example":true},"data":{"type":"object","properties":{"id":{"type":"string","example":"123456789"}}}}}]},"example":{"id":"evt_05b708f961d739ea7eba7e4db318f621\u0026368604920","event":"PAYMENT_RECEIVED","payment":{"id":"pay_080225913252","status":"RECEIVED","externalReference":"42","value":149.9}}}}},"x-authentication":{"kind":"conditional","condition":"Gateway determines the accepted credential branch.","alternatives":[{"kind":"capability","scheme":"asaasAccessToken","location":"header","name":"asaas-access-token","verification_boundary":"Payments webhook gateway resolver","algorithm":"opaque"},{"kind":"all_of","branches":[{"kind":"capability","scheme":"mercadoPagoWebhookHmac","location":"header","name":"x-signature","verification_boundary":"Mercado Pago signature verifier","algorithm":"HMAC-SHA256"},{"kind":"capability","scheme":"mercadoPagoRequestId","location":"header","name":"x-request-id","verification_boundary":"Mercado Pago signature verifier","algorithm":"opaque"}]}]}}},"/webhooks/flow_builder/{flow_id}":{"post":{"tags":["Inbound Webhooks"],"operationId":"auto_post_webhooks_flow_builder_flow_id","summary":"FlowBuilder inbound webhook trigger","description":"Starts (or samples) a flow whose trigger is `trigger_webhook_received`, identified by the flow id in the path. Authentication is fail-closed in every mode and configured per flow via `trigger_config.auth_mode`: `signed` (default — HMAC-SHA256 of the raw body in the `X-Chatwoot-Signature` header; strongest, proves body integrity + authenticity), `bearer` (`Authorization: Bearer \u003ctoken\u003e`), or `url_secret` (`?token=\u003ctoken\u003e` query param; convenient for no-code tools like Typeform/Zapier — authenticity only, so `signed` is recommended). The token is minted when the flow's trigger config is saved and shown in the editor. A Requests larger than 64 KiB are rejected with 413 before flow lookup, authentication, sampling or enqueue. A PUBLISHED flow starts a session (deduplicated by `X-Idempotency-Key` or the body hash within a 10-minute replay window) and the JSON/form/raw body is reachable as `{{ trigger.body.* }}`. A DRAFT / unpublished flow does NOT start a session — an authenticated delivery is captured as a trigger sample and acked 202 `{ status: 'sample_captured' }` so the editor's \"listen for test event\" works before publishing.","security":[{"flowWebhookHmac":[]},{"flowWebhookBearer":[]},{"flowWebhookUrlToken":[]}],"responses":{"202":{"description":"Draft / unpublished flow — the authenticated delivery was captured as a trigger sample.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["sample_captured"],"example":"sample_captured"}}},"example":{"status":"sample_captured"}}}},"200":{"description":"Published flow — session started (or a replay was acked without starting a second session)."},"401":{"description":"Missing/blank token, or the signature/bearer/url-secret did not match (fail-closed)."},"403":{"description":"The account does not have the flow_builder feature enabled."},"404":{"description":"No flow with this id."},"413":{"description":"Request body exceeds the 64 KiB server-side limit; no flow state was read or changed."}},"parameters":[{"name":"flow_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"X-Chatwoot-Signature","in":"header","required":false,"description":"`signed` auth mode (the default) — the hex-encoded `HMAC_SHA256(\u003cflow webhook token\u003e, \u003craw request body\u003e)`, with no prefix. Compared in constant time. Required in that mode; ignored in `bearer` and `url_secret` mode. A blank or mismatching value is rejected with 401 (fail-closed).","schema":{"type":"string","example":"6f3a1c9d05b7e2a48c1f0d63b8e57a92d4c1b0f7e39a6c25d81f4b70a2e6c318"}},{"name":"Authorization","in":"header","required":false,"description":"`bearer` auth mode — `Bearer \u003cflow webhook token\u003e`. Required in that mode; ignored in `signed` and `url_secret` mode. The presented value is digested before the constant-time compare, so a wrong-length token never leaks its length.","schema":{"type":"string","example":"Bearer sample-token"}},{"name":"token","in":"query","required":false,"description":"`url_secret` auth mode — the flow webhook token as a query parameter, for senders that cannot set headers (no-code tools). Required in that mode; ignored in `signed` and `bearer` mode. It proves authenticity only, not body integrity, so `signed` is recommended.","schema":{"type":"string"}},{"name":"X-Idempotency-Key","in":"header","required":false,"description":"Caller-supplied idempotency key used to de-duplicate the delivery inside a 10-minute replay window. When absent, a SHA-256 of the raw body is used instead — so re-sending an IDENTICAL payload is treated as a replay unless a new key is supplied.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Arbitrary JSON reachable in the flow as {{ trigger.body.* }} (bounded to 64KB; form-urlencoded and raw text are also accepted).","example":{"order":{"id":"ABC-1","total":4.97},"status":"paid"}},"example":{"order":{"id":"ABC-1","total":4.97},"status":"paid"}}}},"x-authentication":{"kind":"conditional","condition":"Per-flow configuration selects one credential branch.","alternatives":[{"kind":"capability","scheme":"flowWebhookHmac","location":"header","name":"X-Flow-Signature","verification_boundary":"Flow webhook credential resolver","algorithm":"HMAC-SHA256"},{"kind":"capability","scheme":"flowWebhookBearer","location":"header","name":"Authorization","verification_boundary":"Flow webhook credential resolver","algorithm":"opaque"},{"kind":"capability","scheme":"flowWebhookUrlToken","location":"path","name":"flow_id","verification_boundary":"Flow webhook credential resolver","algorithm":"opaque"}]}}},"/webhooks/catalog/{account_id}/{source_id}":{"post":{"tags":["Inbound Webhooks"],"operationId":"auto_post_webhooks_catalog_account_id_source_id","summary":"Receive a commerce platform event","description":"Account- and source-scoped inbound webhook for a configured catalog/commerce connector. Both path ids are required and the source must belong to that account; an id-only compatibility route is deliberately unavailable. Managed connectors verify their documented provider contract. A generic connector instead uses the operator-owned event/path map and the timestamped HMAC contract described below; no provider name or payload shape is inferred. Verified payloads become normalized lifecycle events and are de-duplicated before dispatch.","security":[{"catalogSyncHmac":[]},{"hotmartWebhookHmac":[]},{"kiwifyWebhookToken":[]},{"nuvemshopWebhookHmac":[]}],"responses":{"200":{"description":"Payload verified and its lifecycle events dispatched, an explicitly ignored generic mapping acknowledged without dispatch, or a completed generic replay acknowledged idempotently."},"401":{"description":"The saved verification secret is absent, the platform signature does not match, or the source connector does not support signature verification."},"403":{"description":"The account-owned source exists but is disabled or is not configured for inbound/bidirectional ingestion."},"404":{"description":"The account does not exist, or the sync source does not belong to that account."},"422":{"description":"A generic delivery has no delivery id, has a delivery id longer than 255 bytes, or its event is not mapped to a lifecycle stage."},"503":{"description":"Another request is currently processing the same generic delivery; the sender should retry.","headers":{"Retry-After":{"description":"Seconds before the sender should try to claim this delivery again.","schema":{"type":"integer","example":1}}}},"429":{"description":"The account/source/client-IP ingress throttle was exceeded; retry after the response delay."},"500":{"description":"Unexpected failure while ingesting the payload; answered deliberately so the platform retries the delivery."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"source_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"X-Webhook-Signature","in":"header","required":false,"description":"Required for a generic connector. Format `t=\u003cunix\u003e,v1=\u003chex\u003e`, where `v1` is `HMAC_SHA256(\u003csource secret\u003e, \"\u003ct\u003e.\u003craw request body\u003e\")`. It is compared in constant time only after `t` passes the source's configured replay window. Managed connectors use their own documented signature header instead.","schema":{"type":"string"}},{"name":"X-Webhook-Delivery","in":"header","required":false,"description":"Required for a generic connector. Stable sender-owned idempotency key for one logical event; retries must reuse it. A completed duplicate is acknowledged without dispatching it again.","schema":{"type":"string","maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"The saved source configuration defines the event, external id, buyer, product, variation and item paths for a generic connector. Managed connector shapes follow their own verified contracts."},"example":{}}}},"x-authentication":{"kind":"conditional","condition":"Catalog source selects its verified inbound credential.","alternatives":[{"kind":"capability","scheme":"catalogSyncHmac","location":"header","name":"catalogSyncHmac","verification_boundary":"Catalog source resolver","algorithm":"HMAC-SHA256"},{"kind":"capability","scheme":"hotmartWebhookHmac","location":"header","name":"hotmartWebhookHmac","verification_boundary":"Catalog source resolver","algorithm":"HMAC-SHA256"},{"kind":"capability","scheme":"kiwifyWebhookToken","location":"header","name":"kiwifyWebhookToken","verification_boundary":"Catalog source resolver","algorithm":"opaque"},{"kind":"capability","scheme":"nuvemshopWebhookHmac","location":"header","name":"nuvemshopWebhookHmac","verification_boundary":"Catalog source resolver","algorithm":"HMAC-SHA256"}]}}},"/webhooks/sales/ingest/{account_id}":{"post":{"tags":["Inbound Webhooks"],"operationId":"auto_post_webhooks_sales_ingest_account_id","summary":"Sales external-CRM score ingest","description":"Awards sales points from an external CRM. Authenticated by the per-account ingest token (X-Sales-Ingest-Token header or token query param); deliveries are deduplicated by delivery_id (or the request id). Disabled until the operator sets the ingest token.","security":[{"salesIngestHeader":[]},{"salesIngestQuery":[]}],"responses":{"200":{"description":"Success (no content)"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"X-Sales-Ingest-Token","in":"header","required":false,"description":"The per-account ingest token, compared in constant time with the one the operator configured. This header is the preferred carrier; the `token` query parameter below is the fallback for senders that cannot set headers. One of the two must be present or the delivery is rejected.","schema":{"type":"string"}},{"name":"token","in":"query","required":false,"description":"Fallback carrier for the per-account ingest token, used only when the X-Sales-Ingest-Token header is absent.","schema":{"type":"string"}},{"name":"X-Sales-Ingest-Delivery","in":"header","required":false,"description":"Per-delivery identifier used to de-duplicate the ingest for one hour. The `delivery_id` field in the body takes precedence over it; when neither is present the delivery is not de-duplicated and a retry awards the points twice.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["user_id","metric"],"properties":{"user_id":{"type":"integer","description":"Agent (user) id receiving the points","example":7},"metric":{"type":"string","description":"Scoring metric key","example":"deal_won"},"points":{"type":"number","description":"Override the metric default points","example":10},"source_type":{"type":"string","description":"Provenance label","example":"ExternalCrm"},"source_id":{"type":"string","description":"External record id (defaults to the delivery id)","example":"crm-9812"},"delivery_id":{"type":"string","description":"Idempotency key for the delivery","example":"d8a7c1b2"},"metadata":{"type":"object","additionalProperties":true,"description":"PII-free provenance kept on the point event"}}},"example":{"user_id":7,"metric":"deal_won","points":10,"source_type":"ExternalCrm","source_id":"crm-9812","delivery_id":"d8a7c1b2","metadata":{}}}}},"x-authentication":{"kind":"conditional","condition":"Sales source accepts exactly one configured secret location.","alternatives":[{"kind":"capability","scheme":"salesIngestHeader","location":"header","name":"X-Sales-Token","verification_boundary":"Sales ingest verifier","algorithm":"opaque"},{"kind":"capability","scheme":"salesIngestQuery","location":"query","name":"token","verification_boundary":"Sales ingest verifier","algorithm":"opaque"}]}}},"/webhooks/google_calendar":{"post":{"tags":["Inbound Webhooks"],"operationId":"auto_post_webhooks_google_calendar","summary":"Receive a Google Calendar push notification","description":"Push receiver for the Google Calendar watch channels that mirror an agent calendar. The channel is resolved from the X-Goog-Channel-ID header and authenticated by constant-time comparing X-Goog-Channel-Token with the token stored when the channel was opened; the delivery is then de-duplicated by X-Goog-Message-Number and an incremental sync is scheduled. The response is an empty acknowledgement with no body, including for the handshake notification Google sends when a channel opens and for a repeated message number, neither of which carries a change.","security":[{"googleCalendarChannelToken":[]}],"responses":{"200":{"description":"Notification accepted and an incremental sync scheduled, or acknowledged without work because it is the channel-open handshake or a repeated delivery. Empty body."},"400":{"description":"The X-Goog-Channel-ID header is missing."},"403":{"description":"The X-Goog-Channel-Token header does not match the token stored for this channel."},"404":{"description":"No watch channel is registered with this id."},"500":{"description":"Unexpected failure while accepting the notification; Google should retry."}},"parameters":[{"name":"X-Goog-Channel-ID","in":"header","required":true,"description":"The id of the watch channel this notification belongs to, as minted when the channel was opened. Used to resolve the mirrored calendar. A delivery without it is rejected with 400.","schema":{"type":"string"}},{"name":"X-Goog-Channel-Token","in":"header","required":true,"description":"The per-channel secret supplied at watch time. Compared in constant time with the stored token; a mismatch is rejected with 403.","schema":{"type":"string"}},{"name":"X-Goog-Resource-State","in":"header","required":false,"description":"`sync` for the handshake Google sends the moment a channel opens (acknowledged without work), or `exists` for an actual change notification.","schema":{"type":"string","enum":["sync","exists","not_exists"]}},{"name":"X-Goog-Message-Number","in":"header","required":false,"description":"Monotonic per-channel delivery counter. Used to de-duplicate a repeated delivery, which is acknowledged without scheduling another sync.","schema":{"type":"string"}}],"x-authentication":{"kind":"credential","scheme":"googleCalendarChannelToken","location":"header","name":"X-Goog-Channel-Token","verification_boundary":"Google Calendar watch-channel token verifier","algorithm":"opaque"}}},"/webhooks/instagram":{"get":{"tags":["Inbound Webhooks"],"operationId":"auto_get_webhooks_instagram","summary":"Instagram webhook verification (Meta hub.challenge)","description":"Meta subscription handshake — echoes `hub.challenge` back when `hub.verify_token` matches.","security":[],"responses":{"200":{"description":"The hub.challenge value echoed back (JSON-encoded string).","content":{"application/json":{"schema":{"type":"string","example":"158201444"},"example":"158201444"}}},"401":{"description":"Wrong verify token.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error; wrong verify token"}}},"example":{"error":"Error; wrong verify token"}}}}},"x-authentication":{"kind":"conditional","condition":"Meta challenge request.","alternatives":[{"kind":"capability","scheme":"metaHubVerifyToken","location":"query","name":"hub.verify_token","verification_boundary":"Meta webhook verification action","algorithm":"opaque"}]}},"post":{"tags":["Inbound Webhooks"],"operationId":"auto_post_webhooks_instagram","summary":"Instagram webhook events","description":"Receives the HMAC-verified Meta Instagram webhook envelope. Direct messages are processed asynchronously, including text, multiple media attachments, replies, quick replies, shared posts/Stories/Reels, reactions, reads, postbacks, referrals, edits, unsends and handover events. Comment and mention change entries are routed to their dedicated processors. When the private capture directory is configured, the already-verified envelope is also retained temporarily for structure validation; capture never changes acknowledgement behavior.","security":[{"metaWebhookHmac":[]}],"responses":{"200":{"description":"Acknowledged (the literal JSON string \"ok\").","content":{"application/json":{"schema":{"type":"string","example":"ok"},"example":"ok"}}},"422":{"description":"Payload object is not instagram."}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"required":["object","entry"],"properties":{"object":{"type":"string","example":"instagram"},"entry":{"type":"array","description":"Meta webhook entries (per-object change notifications).","items":{"type":"object","additionalProperties":true,"description":"One Meta webhook entry (id, time, changes/messaging,...)."}}}},"example":{"object":"instagram","entry":[{}]}}}},"x-authentication":{"kind":"conditional","condition":"Meta HMAC is required whenever the resolved channel/app has an app secret.","alternatives":[{"kind":"capability","scheme":"metaWebhookHmac","location":"header","name":"X-Hub-Signature-256","verification_boundary":"resolved Meta channel/app secret","algorithm":"HMAC-SHA256"}]},"parameters":[{"name":"X-Hub-Signature-256","in":"header","required":false,"description":"HMAC-SHA256 of the raw request body, keyed with the app secret, in the form `sha256=\u003chex\u003e`. Verified before any side effect. Optional in the schema only because an installation can run a channel without a configured app secret; whenever a secret IS configured for any channel this delivery resolves, the header is REQUIRED and a missing or wrong value is rejected.","schema":{"type":"string","example":"sha256=7d38cdd689735b008b3c702edd92eea23791c5f6"}}]}},"/webhooks/meta_ads":{"get":{"tags":["Inbound Webhooks"],"operationId":"auto_get_webhooks_meta_ads","summary":"Meta Ads webhook verification (hub.challenge)","description":"Meta subscription handshake for ad-object webhooks — echoes `hub.challenge` when the verify token matches.","security":[],"responses":{"200":{"description":"The hub.challenge value echoed back (JSON-encoded string).","content":{"application/json":{"schema":{"type":"string","example":"158201444"},"example":"158201444"}}},"401":{"description":"Wrong verify token."}},"x-authentication":{"kind":"conditional","condition":"Meta challenge request.","alternatives":[{"kind":"capability","scheme":"metaHubVerifyToken","location":"query","name":"hub.verify_token","verification_boundary":"Meta webhook verification action","algorithm":"opaque"}]}},"post":{"tags":["Inbound Webhooks"],"operationId":"auto_post_webhooks_meta_ads","summary":"Meta Ads webhook events","description":"Ad-object status changes (campaign/ad set/ad). HMAC-verified; enqueues a bounded reconcile. Gated by the ads_manager feature flag downstream.","security":[{"metaWebhookHmac":[]}],"responses":{"200":{"description":"Success (no content)"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"required":["object","entry"],"properties":{"object":{"type":"string","example":"ad_account"},"entry":{"type":"array","description":"Meta webhook entries (per-object change notifications).","items":{"type":"object","additionalProperties":true,"description":"One Meta webhook entry (id, time, changes/messaging,...)."}}}},"example":{"object":"ad_account","entry":[{}]}}}},"x-authentication":{"kind":"conditional","condition":"Meta HMAC is required whenever the resolved channel/app has an app secret.","alternatives":[{"kind":"capability","scheme":"metaWebhookHmac","location":"header","name":"X-Hub-Signature-256","verification_boundary":"resolved Meta channel/app secret","algorithm":"HMAC-SHA256"}]}}},"/webhooks/tiktok":{"post":{"tags":["Inbound Webhooks"],"operationId":"auto_post_webhooks_tiktok","summary":"Receive a TikTok messaging event","description":"Inbound webhook for TikTok direct messages. The delivery is authenticated by recomputing the HMAC-SHA256 over the signed timestamp and the raw body and comparing it in constant time with the Tiktok-Signature header, rejecting anything older than the accepted window; the event is then queued for processing. An echo of a message sent from the dashboard is queued with a short delay so it cannot overtake the send that produced it and create a duplicate. The response is an empty acknowledgement with no body.","security":[{"tiktokWebhookHmac":[]}],"responses":{"200":{"description":"Event queued for processing. Empty body."},"401":{"description":"The app secret is not configured, the Tiktok-Signature header is missing or malformed, the signature does not match, or the signed timestamp is outside the accepted window."}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"event":{"type":"string"}}},"example":{"event":"sample event"}}}},"parameters":[{"name":"Tiktok-Signature","in":"header","required":true,"description":"Comma-separated `t=\u003cunix seconds\u003e,s=\u003chex HMAC\u003e` pair, where the HMAC is `HMAC_SHA256(\u003cTikTok app secret\u003e, \"\u003ct\u003e.\u003craw request body\u003e\")`. Compared in constant time; the signed `t` must not trail the receiver's clock by more than 5 seconds. A missing, malformed, mismatching or stale value is rejected with 401.","schema":{"type":"string","example":"t=1778735498,s=6f3a1c9d05b7e2a48c1f0d63b8e57a92d4c1b0f7e39a6c25d81f4b70a2e6c318"}}],"x-authentication":{"kind":"credential","scheme":"tiktokWebhookHmac","location":"header","name":"Tiktok-Signature","verification_boundary":"TikTok timestamped raw-body verifier","algorithm":"HMAC-SHA256"}}},"/webhooks/shopify":{"post":{"tags":["Inbound Webhooks"],"operationId":"auto_post_webhooks_shopify","summary":"Receive a Shopify privacy or shop event","description":"Inbound webhook for the Shopify application. The delivery is authenticated by recomputing the HMAC-SHA256 over the raw body and comparing it in constant time with the X-Shopify-Hmac-SHA256 header. The three mandatory privacy topics are handled explicitly: customer access and redaction are acknowledged as no-ops because this integration persists no Shopify customer/order payload; shop redaction removes stored integration hooks for the normalized shop domain. Other verified topics are acknowledged without mutation. The response is an empty acknowledgement with no body.","security":[{"shopifyWebhookHmac":[]}],"responses":{"200":{"description":"Delivery verified. Customer privacy topics are explicitly acknowledged without mutation because no provider customer/order payload is stored; shop redaction removes the matching connection. Empty body."},"401":{"description":"The client secret is not configured, the X-Shopify-Hmac-SHA256 header is missing, or the signature does not match."}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"required":["shop_id","shop_domain"],"properties":{"shop_id":{"type":"integer","example":954889},"shop_domain":{"type":"string","example":"support-store.myshopify.com"},"customer":{"type":"object","additionalProperties":true,"properties":{"id":{"type":"integer"},"email":{"type":["string","null"],"format":"email"},"phone":{"type":["string","null"]}}},"orders_requested":{"type":"array","items":{"type":"integer"},"description":"Present on a customer data request."},"orders_to_redact":{"type":"array","items":{"type":"integer"},"description":"Present on a customer redaction request."}}},"example":{"shop_id":954889,"shop_domain":"support-store.myshopify.com","customer":{"id":1,"email":"agent@example.com","phone":"+5511999998888"},"orders_requested":[1],"orders_to_redact":[1]}}}},"parameters":[{"name":"X-Shopify-Hmac-SHA256","in":"header","required":true,"description":"Base64-encoded `HMAC_SHA256(\u003cShopify client secret\u003e, \u003craw request body\u003e)`, as sent by Shopify. Compared in constant time; a missing or mismatching value is rejected with 401.","schema":{"type":"string","example":"XWmrwMey6OsLMeiZKwP4FppHH3cmMV0rrEisNt7s5rQ="}},{"name":"X-Shopify-Topic","in":"header","required":true,"description":"Shopify topic. The mandatory privacy topics are `customers/data_request`, `customers/redact`, and `shop/redact`; other correctly signed topics are acknowledged without mutation.","schema":{"type":"string","example":"shop/redact"}}],"x-authentication":{"kind":"credential","scheme":"shopifyWebhookHmac","location":"header","name":"X-Shopify-Hmac-SHA256","verification_boundary":"Shopify exact raw-body verifier","algorithm":"HMAC-SHA256"}}},"/twilio/callback":{"post":{"tags":["Callback"],"operationId":"auto_post_twilio_callback","summary":"Receive an inbound Twilio message","description":"Validates X-Twilio-Signature against the resolved Twilio channel, captures the provider form payload and enqueues asynchronous message processing. A valid delivery is acknowledged without a body.","security":[{"twilioWebhookSignature":[]}],"responses":{"204":{"description":"Payload accepted and queued; no response body."},"401":{"description":"Missing, invalid, or unverifiable Twilio signature."}},"requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","required":["AccountSid"],"properties":{"ApiVersion":{"type":"string","example":"2010-04-01"},"SmsSid":{"type":"string","example":"SM00000000000000000000000000000001"},"MessageSid":{"type":"string","example":"SM00000000000000000000000000000001"},"AccountSid":{"type":"string","example":"AC00000000000000000000000000000001"},"MessagingServiceSid":{"type":"string","example":"MG00000000000000000000000000000001"},"From":{"type":"string","example":"+15551234567"},"To":{"type":"string","example":"+15557654321"},"Body":{"type":"string","example":"Hello"},"NumMedia":{"type":"integer","minimum":0,"maximum":10,"example":0},"MediaUrl0":{"type":"string","format":"uri"},"MediaContentType0":{"type":"string","example":"image/jpeg"},"FromCountry":{"type":"string","example":"US"},"FromState":{"type":"string","example":"CA"},"FromCity":{"type":"string","example":"San Francisco"},"FromZip":{"type":"string","example":"94105"},"ToCountry":{"type":"string","example":"US"},"ToState":{"type":"string","example":"NY"},"ToCity":{"type":"string","example":"New York"},"ToZip":{"type":"string","example":"10001"},"Latitude":{"type":"string","example":"37.7749"},"Longitude":{"type":"string","example":"-122.4194"},"MessageType":{"type":"string","example":"text"},"ProfileName":{"type":"string","example":"Ana"},"ExternalUserId":{"type":"string"},"ParentExternalUserId":{"type":"string"},"ProfileUsername":{"type":"string"},"Username":{"type":"string"},"ReferralBody":{"type":"string"},"ReferralHeadline":{"type":"string"},"ReferralSourceId":{"type":"string"},"ReferralSourceType":{"type":"string"},"ReferralSourceUrl":{"type":"string","format":"uri"},"ReferralMediaId":{"type":"string"},"ReferralMediaContentType":{"type":"string"},"ReferralMediaUrl":{"type":"string","format":"uri"},"ReferralNumMedia":{"type":"integer","minimum":0},"ReferralCtwaClid":{"type":"string"}}}}}},"x-authentication":{"kind":"credential","scheme":"twilioWebhookSignature","location":"header","name":"X-Twilio-Signature","verification_boundary":"Twilio public-URL and form-parameter verifier","algorithm":"HMAC-SHA1"}}},"/twilio/delivery_status":{"post":{"tags":["Delivery Status"],"operationId":"auto_post_twilio_delivery_status","summary":"Receive a Twilio message delivery status","description":"Validates the signed form payload and enqueues delivery-state reconciliation.","security":[{"twilioWebhookSignature":[]}],"responses":{"204":{"description":"Status accepted and queued; no response body."},"401":{"description":"Missing, invalid, or unverifiable Twilio signature."}},"requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","required":["AccountSid","MessageSid","MessageStatus"],"properties":{"AccountSid":{"type":"string","example":"AC00000000000000000000000000000001"},"MessageSid":{"type":"string","example":"SM00000000000000000000000000000001"},"MessagingServiceSid":{"type":"string","example":"MG00000000000000000000000000000001"},"From":{"type":"string","example":"+15557654321"},"MessageStatus":{"type":"string","enum":["accepted","scheduled","queued","sending","sent","receiving","received","delivered","undelivered","failed","read","canceled"],"example":"delivered"},"ErrorCode":{"type":["string","null"],"example":null},"ErrorMessage":{"type":["string","null"],"example":null}}}}}},"x-authentication":{"kind":"credential","scheme":"twilioWebhookSignature","location":"header","name":"X-Twilio-Signature","verification_boundary":"Twilio public-URL and form-parameter verifier","algorithm":"HMAC-SHA1"}}},"/twilio/voice/call/{phone}":{"post":{"tags":["Call"],"operationId":"auto_post_twilio_voice_call_phone","summary":"Resolve the TwiML for a Twilio voice leg","description":"Validates the signed form callback, resolves the phone inbox and returns either the conference instructions for the call leg or an explicit TwiML rejection.","security":[{"twilioWebhookSignature":[]}],"responses":{"200":{"description":"TwiML conference or rejection instructions.","content":{"application/xml":{"schema":{"type":"string"},"example":"\u003cResponse\u003e\u003cDial\u003e\u003cConference\u003ecw-call-42\u003c/Conference\u003e\u003c/Dial\u003e\u003c/Response\u003e"}}},"401":{"description":"Missing, invalid, or unverifiable Twilio signature."},"404":{"description":"The destination phone or active claimed call could not be resolved."}},"parameters":[{"name":"phone","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","required":["CallSid","From","Direction"],"properties":{"CallSid":{"type":"string","example":"CA00000000000000000000000000000001"},"From":{"type":"string","example":"+15551234567"},"To":{"type":"string","example":"+15557654321"},"Direction":{"type":"string","enum":["inbound","outbound-api","outbound-dial"],"example":"inbound"},"ParentCallSid":{"type":["string","null"],"example":null},"call_sid":{"type":"string","description":"Existing provider call id required for an agent client leg."}}}}}},"x-authentication":{"kind":"credential","scheme":"twilioWebhookSignature","location":"header","name":"X-Twilio-Signature","verification_boundary":"Twilio public-URL and form-parameter verifier","algorithm":"HMAC-SHA1"}}},"/twilio/voice/status/{phone}":{"post":{"tags":["Status"],"operationId":"auto_post_twilio_voice_status_phone","summary":"Receive a Twilio voice-leg status","description":"Performs the status operation on the targeted programmable voice resource.","security":[{"twilioWebhookSignature":[]}],"responses":{"204":{"description":"Status reconciled; no response body."},"401":{"description":"Missing, invalid, or unverifiable Twilio signature."},"404":{"description":"The destination phone has no Twilio inbox."}},"parameters":[{"name":"phone","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","required":["CallSid","CallStatus"],"properties":{"CallSid":{"type":"string","example":"CA00000000000000000000000000000001"},"CallStatus":{"type":"string","enum":["queued","initiated","ringing","in-progress","inprogress","answered","completed","busy","no-answer","failed","canceled"],"example":"completed"},"CallDuration":{"type":"integer","minimum":0,"example":42},"Timestamp":{"type":"string","example":"Wed, 26 Aug 2026 20:00:00 +0000"}}}}}},"x-authentication":{"kind":"credential","scheme":"twilioWebhookSignature","location":"header","name":"X-Twilio-Signature","verification_boundary":"Twilio public-URL and form-parameter verifier","algorithm":"HMAC-SHA1"}}},"/twilio/voice/conference_status/{phone}":{"post":{"tags":["Conference Status"],"operationId":"auto_post_twilio_voice_conference_status_phone","summary":"Receive a Twilio conference lifecycle event","description":"Performs the conference status operation on the targeted programmable voice resource.","security":[{"twilioWebhookSignature":[]}],"responses":{"204":{"description":"Conference event processed or safely ignored; no response body."},"401":{"description":"Missing, invalid, or unverifiable Twilio signature."},"404":{"description":"The destination phone or call could not be resolved."}},"parameters":[{"name":"phone","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","required":["CallSid","StatusCallbackEvent"],"properties":{"CallSid":{"type":"string","example":"CA00000000000000000000000000000001"},"ConferenceSid":{"type":"string","example":"CF00000000000000000000000000000001"},"FriendlyName":{"type":"string","example":"cw-call-42"},"ParticipantLabel":{"type":"string","example":"contact"},"StatusCallbackEvent":{"type":"string","enum":["conference-start","participant-join","participant-leave","conference-end"],"example":"participant-join"}}}}}},"x-authentication":{"kind":"credential","scheme":"twilioWebhookSignature","location":"header","name":"X-Twilio-Signature","verification_boundary":"Twilio public-URL and form-parameter verifier","algorithm":"HMAC-SHA1"}}},"/twilio/voice/recording_status/{phone}":{"post":{"tags":["Recording Status"],"operationId":"auto_post_twilio_voice_recording_status_phone","summary":"Receive a completed Twilio recording","description":"Performs the recording status operation on the targeted programmable voice resource.","security":[{"twilioWebhookSignature":[]}],"responses":{"204":{"description":"Recording status processed; no response body."},"401":{"description":"Missing, invalid, or unverifiable Twilio signature."},"404":{"description":"The destination phone has no Twilio inbox. Unknown recordings are acknowledged without creating an attachment."}},"parameters":[{"name":"phone","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","required":["RecordingStatus","RecordingSid"],"properties":{"RecordingStatus":{"type":"string","enum":["in-progress","completed","absent","failed"],"example":"completed"},"ConferenceSid":{"type":"string","example":"CF00000000000000000000000000000001"},"RecordingSid":{"type":"string","example":"RE00000000000000000000000000000001"},"RecordingUrl":{"type":"string","format":"uri","example":"https://api.twilio.com/recordings/RE00000000000000000000000000000001"},"RecordingDuration":{"type":"integer","minimum":0,"example":42}}}}}},"x-authentication":{"kind":"credential","scheme":"twilioWebhookSignature","location":"header","name":"X-Twilio-Signature","verification_boundary":"Twilio public-URL and form-parameter verifier","algorithm":"HMAC-SHA1"}}},"/catalog_oauth/callback":{"get":{"tags":["Callback"],"operationId":"auto_get_catalog_oauth_callback","summary":"Complete a catalog provider OAuth authorization","description":"Exchanges the provider authorization code using the signed source state, stores credentials server-side and redirects back to the catalog import screen. Failures redirect to the application root.","security":[],"responses":{"302":{"description":"Redirects to the account catalog import page on success or to `/` on failure.","headers":{"Location":{"description":"Relative dashboard destination selected by the callback result.","schema":{"type":"string","example":"/app/accounts/1/catalog/import-sync"}}}}},"parameters":[{"name":"code","in":"query","required":true,"schema":{"type":"string"},"description":"Short-lived authorization code issued by the catalog provider."},{"name":"state","in":"query","required":true,"schema":{"type":"string"},"description":"Signed, expiring GlobalID that resolves the account-owned catalog source."}]}},"/.well-known/assetlinks.json":{"get":{"tags":["Assetlinks.json"],"operationId":"auto_get_well_known_assetlinks_json","summary":"Return Android Digital Asset Links","description":"Publishes the configured Android package and signing-certificate fingerprint.","security":[],"responses":{"200":{"description":"Android association statements for this installation.","content":{"application/json":{"schema":{"type":"array","minItems":1,"items":{"type":"object","required":["relation","target"],"properties":{"relation":{"type":"array","minItems":1,"items":{"type":"string","enum":["delegate_permission/common.handle_all_urls"]}},"target":{"type":"object","required":["namespace","package_name","sha256_cert_fingerprints"],"properties":{"namespace":{"type":"string","enum":["android_app"]},"package_name":{"type":"string","example":"com.example.chat"},"sha256_cert_fingerprints":{"type":"array","minItems":1,"items":{"type":"string","example":"AA:BB:CC:DD:EE:FF"}}}}}}},"example":[{"relation":["delegate_permission/common.handle_all_urls"],"target":{"namespace":"android_app","package_name":"com.example.chat","sha256_cert_fingerprints":["AA:BB:CC:DD:EE:FF"]}}]}}}}}},"/.well-known/apple-app-site-association":{"get":{"tags":["Apple-app-site-association"],"operationId":"auto_get_well_known_apple_app_site_association","summary":"Return the Apple universal-link association document","description":"Publishes the installation's configured iOS application identifier and the dashboard conversation paths handled as universal links. Although Rails sends this JSON with a download disposition, it is fixed public association metadata, not an arbitrary binary download.","security":[],"responses":{"200":{"description":"Apple App Site Association document for this installation.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["applinks"],"properties":{"applinks":{"type":"object","additionalProperties":false,"required":["apps","details"],"properties":{"apps":{"type":"array","maxItems":0,"items":{"type":"string"}},"details":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"object","additionalProperties":false,"required":["appID","paths"],"properties":{"appID":{"type":"string","description":"Configured iOS application identifier."},"paths":{"type":"array","minItems":1,"items":{"type":"string","enum":["/app/accounts/*/conversations/*"]}}}}}}}}},"example":{"applinks":{"apps":["sample app"],"details":[{"appID":"sample appID","paths":["/app/accounts/*/conversations/*"]}]}}}}}}}},"/.well-known/microsoft-identity-association.json":{"get":{"tags":["Microsoft-identity-association.json"],"operationId":"auto_get_well_known_microsoft_identity_association_json","summary":"Identity association microsoft","description":"Performs the identity association operation on the targeted microsoft resource.","security":[],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"associatedApplications":{"type":"array","items":{"type":"object","properties":{"applicationId":{"type":"string"}}}}}},"example":{"associatedApplications":[{"applicationId":"sample applicationId"}]}}}}}}},"/.well-known/cf-custom-hostname-challenge/{id}":{"get":{"tags":["{id}"],"operationId":"auto_get_well_known_cf_custom_hostname_challenge_id","summary":"Answer a Cloudflare custom-hostname ownership challenge","description":"Resolves the portal by the request host and returns the stored verification body only when the opaque challenge id matches that portal. No portal or challenge details are exposed on mismatch.","security":[],"responses":{"200":{"description":"Exact Cloudflare verification body stored for this portal.","content":{"text/plain":{"schema":{"type":"string"},"example":"verification-body"}}},"404":{"description":"The request host is not a portal custom domain or the challenge id does not match.","content":{"text/plain":{"schema":{"type":"string","enum":["Domain not found","Challenge ID not found"]},"example":"Domain not found"}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/.well-known/oauth-protected-resource":{"get":{"tags":["Oauth-protected-resource"],"operationId":"auto_get_well_known_oauth_protected_resource","summary":"Get the MCP OAuth Protected Resource Metadata","description":"Generic RFC 9728 Protected Resource Metadata for legacy/static MCP connections. It is public and explains only header bearer authentication for the static account-profile and PlatformApp endpoints; it does not authenticate a caller. The absence of authorization_servers is intentional: a static profile secret or PlatformApp token cannot be exchanged, refreshed or used as an OAuth bearer. Native OAuth, when enabled, is exposed only through separate OAuth resource URLs and their own metadata documents, so clients must never infer an OAuth issuer from this generic static document.","security":[],"responses":{"200":{"description":"The Protected Resource Metadata document.","content":{"application/json":{"schema":{"type":"object","required":["resource","bearer_methods_supported","resource_documentation","mcp_protocol_version","mcp_protocol_versions_supported","x_mcp","x_chatwoot_mcp"],"additionalProperties":false,"properties":{"resource":{"type":"string","description":"The legacy account MCP endpoint template. A client must replace both path placeholders with the profile URL it was given; the generic document is not an OAuth audience.","example":"https://app.example.com/api/v1/accounts/{account_id}/mcp/c/{public_id}"},"bearer_methods_supported":{"type":"array","description":"How the bearer token may be presented. Only the `Authorization` header is supported.","items":{"type":"string","enum":["header"],"example":"header"}},"resource_documentation":{"type":"string","description":"Where a client can read about this resource.","example":"https://app.example.com/"},"mcp_protocol_version":{"type":"string","description":"The latest Model Context Protocol revision the servers implement.","example":"2026-07-28"},"mcp_protocol_versions_supported":{"type":"array","minItems":5,"maxItems":5,"uniqueItems":true,"items":{"type":"string","enum":["2026-07-28","2025-11-25","2025-06-18","2025-03-26","2024-11-05"]},"description":"SDK-supported protocol revisions, spanning the stateless and initialize-handshake lifecycles.","example":["2026-07-28","2025-11-25","2025-06-18","2025-03-26","2024-11-05"]},"x_mcp":{"type":"object","required":["note","account_endpoint","platform_endpoint"],"additionalProperties":false,"description":"Installation-specific hints (non-standard extension to the RFC 9728 document).","properties":{"note":{"type":"string","description":"How to authenticate against the static MCP resources. The product name follows the installation brand, so a white-label install reads its own name here.","example":"Authenticate with an ExampleCo MCP access-profile bearer secret for the account endpoint, or a PlatformApp bearer credential for the Platform endpoint. This static metadata does not advertise an OAuth authorization server."},"account_endpoint":{"type":"string","description":"Template of the static account-level MCP endpoint.","example":"https://app.example.com/api/v1/accounts/{account_id}/mcp/c/{public_id}"},"platform_endpoint":{"type":"string","description":"The platform-level MCP endpoint (Platform App token).","example":"https://app.example.com/platform/api/v1/mcp"}}},"x_chatwoot_mcp":{"type":"object","required":["note","account_endpoint","platform_endpoint"],"additionalProperties":false,"deprecated":true,"description":"Deprecated legacy alias of `x_mcp`; it is always structurally and semantically identical.","properties":{"note":{"type":"string","description":"How to authenticate against the static MCP resources. The product name follows the installation brand, so a white-label install reads its own name here.","example":"Authenticate with an ExampleCo MCP access-profile bearer secret for the account endpoint, or a PlatformApp bearer credential for the Platform endpoint. This static metadata does not advertise an OAuth authorization server."},"account_endpoint":{"type":"string","description":"Template of the static account-level MCP endpoint.","example":"https://app.example.com/api/v1/accounts/{account_id}/mcp/c/{public_id}"},"platform_endpoint":{"type":"string","description":"The platform-level MCP endpoint (Platform App token).","example":"https://app.example.com/platform/api/v1/mcp"}}}}},"example":{"resource":"https://app.example.com/api/v1/accounts/{account_id}/mcp/c/{public_id}","bearer_methods_supported":["header"],"resource_documentation":"https://app.example.com/","mcp_protocol_version":"2026-07-28","mcp_protocol_versions_supported":["2026-07-28","2025-11-25","2025-06-18","2025-03-26","2024-11-05"],"x_mcp":{"note":"Authenticate with an ExampleCo MCP access-profile bearer secret for the account endpoint, or a PlatformApp bearer credential for the Platform endpoint. This static metadata does not advertise an OAuth authorization server.","account_endpoint":"https://app.example.com/api/v1/accounts/{account_id}/mcp/c/{public_id}","platform_endpoint":"https://app.example.com/platform/api/v1/mcp"},"x_chatwoot_mcp":{"note":"Authenticate with an ExampleCo MCP access-profile bearer secret for the account endpoint, or a PlatformApp bearer credential for the Platform endpoint. This static metadata does not advertise an OAuth authorization server.","account_endpoint":"https://app.example.com/api/v1/accounts/{account_id}/mcp/c/{public_id}","platform_endpoint":"https://app.example.com/platform/api/v1/mcp"}}}}}}}}},"components":{"schemas":{"bad_request_error":{"title":"data","type":"object","properties":{"description":{"type":"string"},"errors":{"type":"array","items":{"$ref":"#/components/schemas/request_error"}}}},"request_error":{"type":"object","properties":{"field":{"type":"string"},"message":{"type":"string"},"code":{"type":"string"}}},"generic_id":{"type":"object","properties":{"id":{"type":"number"}}},"active_storage_direct_upload":{"type":"object","additionalProperties":false,"required":["id","key","filename","metadata","service_name","byte_size","created_at","signed_id","direct_upload"],"properties":{"id":{"type":"integer","example":4821},"key":{"type":"string","description":"Opaque object-storage key.","example":"xf9pdq0k7z2m4bn6vc1a3s5d"},"filename":{"type":"string","example":"attachment.pdf"},"content_type":{"type":["string","null"],"example":"application/pdf"},"metadata":{"type":"object","additionalProperties":true,"description":"Server-stamped tenant metadata plus permitted client analysis hints."},"service_name":{"type":"string","example":"amazon"},"byte_size":{"type":"integer","minimum":0,"example":20451},"checksum":{"type":["string","null"],"example":"qLNbHUmZ6vC0FpHZjkQeBQ=="},"created_at":{"type":"string","format":"date-time"},"signed_id":{"type":"string","description":"Account-bound, tamper-proof blob reference accepted by an attachment consumer."},"direct_upload":{"type":"object","additionalProperties":false,"required":["url","headers"],"properties":{"url":{"type":"string","format":"uri","description":"Short-lived pre-signed target to which the raw bytes must be uploaded with PUT."},"headers":{"type":"object","additionalProperties":{"type":"string"},"description":"Storage headers that must be replayed exactly."}}}}},"canned_response":{"type":"object","properties":{"id":{"type":"integer","description":"ID of the canned response"},"account_id":{"type":"integer","description":"Account Id"},"short_code":{"type":"string","description":"Short Code for quick access of the canned response"},"content":{"type":["string","null"],"description":"Message content for canned response"},"visibility":{"type":"string","enum":["personal","global"],"description":"Personal responses are visible only to their author; global responses are available to every user in the account."},"created_by":{"$ref":"#/components/schemas/agent"},"updated_by":{"$ref":"#/components/schemas/agent"},"attachments":{"type":"array","description":"Files saved with the canned response, including retained metadata for media removed by the Media Library lifecycle.","items":{"type":"object","required":["id","file_type","byte_size","data_url","thumb_url","media_deleted"],"properties":{"id":{"type":"integer"},"file_type":{"type":"string","enum":["image","video","audio","file"],"description":"The high-level media class of an attachment, derived from its content type."},"file_name":{"type":["string","null"]},"content_type":{"type":["string","null"]},"byte_size":{"type":"integer"},"data_url":{"type":"string"},"thumb_url":{"type":"string"},"media_deleted":{"type":"boolean"},"deleted_at":{"type":["string","null"],"format":"date-time"}}}},"content_attributes":{"type":"object","additionalProperties":true,"description":"Interactive Quick Reply payload persisted with the canned response (empty object when it is a plain text/attachment reply). Top keys are one of interactive, wa_interactive, poll or items, carrying the buttons/sections/cards/options the reply-box composer reopens or re-sends.","example":{}},"created_at":{"type":"string","format":"date-time","description":"The date and time when the canned response was created"},"updated_at":{"type":"string","format":"date-time","description":"The date and time when the canned response was updated"}}},"custom_attribute":{"type":"object","properties":{"id":{"type":"integer","description":"Identifier"},"attribute_display_name":{"type":"string","description":"Attribute display name"},"attribute_display_type":{"type":"string","enum":["text","number","currency","percent","link","date","list","checkbox"],"description":"Attribute display type"},"attribute_description":{"type":"string","description":"Attribute description"},"attribute_key":{"type":"string","description":"Attribute unique key value"},"regex_pattern":{"type":"string","description":"Regex pattern"},"regex_cue":{"type":"string","description":"Regex cue"},"attribute_values":{"type":"string","description":"Attribute values"},"attribute_model":{"type":"string","description":"Attribute type(conversation_attribute/contact_attribute)"},"default_value":{"type":"string","description":"Attribute default value"},"created_at":{"type":"string","description":"The date and time when the custom attribute was created"},"updated_at":{"type":"string","description":"The date and time when the custom attribute was updated"}}},"automation_rule":{"type":"object","properties":{"payload":{"description":"Response payload that contains automation rule(s)","oneOf":[{"type":"array","description":"Array of automation rules (for listing endpoint)","items":{"$ref":"#/components/schemas/automation_rule_item"}},{"description":"Single automation rule (for show/create/update endpoints)","allOf":[{"$ref":"#/components/schemas/automation_rule_item"}]}]}}},"automation_rule_item":{"type":"object","properties":{"id":{"type":"integer","description":"The ID of the automation rule"},"account_id":{"type":"integer","description":"Account Id"},"name":{"type":"string","description":"The name of the rule","example":"Add label on message create event"},"description":{"type":"string","description":"Description to give more context about the rule","example":"Add label support and sales on message create event if incoming message content contains text help"},"event_name":{"type":"string","description":"Native automation event, including conversation_created, conversation_updated, message_created and crm_item_stage_changed.","example":"message_created"},"conditions":{"type":"array","description":"Array of conditions on which conversation/message filter would work","items":{"type":"object","properties":{"values":{"type":"array","items":{"type":"string"}},"attribute_key":{"type":"string"},"query_operator":{"type":"string"},"filter_operator":{"type":"string"}},"example":{"attribute_key":"content","filter_operator":"contains","values":["help"],"query_operator":"and"}}},"execution_delay":{"type":["integer","null"],"minimum":10,"maximum":43200,"description":"Delay in minutes. Requires delayed_automations when setting a non-null value. For crm_item_stage_changed, the deal must remain in the destination stage and still match the conditions at execution. Pausing the feature preserves pending work; editing or disabling the rule cancels pending actions. Completed actions are not replayed. Delayed work older than three days after its due time is marked expired."},"actions":{"type":"array","description":"Array of actions which we perform when condition matches","items":{"type":"object","properties":{"action_name":{"type":"string"},"action_params":{"oneOf":[{"type":"array","items":{"oneOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"object","additionalProperties":true,"description":"Named arguments interpreted by the selected automation action."}]}},{"type":"object","additionalProperties":true,"description":"Named arguments interpreted by the selected automation action."}],"description":"Action-specific arguments; Meta conversion parameters may be an object inside the array."}},"example":{"action_name":"add_label","action_params":["support","sales"]}}},"created_on":{"type":"integer","description":"The timestamp when the rule was created"},"active":{"type":"boolean","description":"Enable/disable automation rule"}}},"portal":{"type":"object","properties":{"payload":{"type":"array","items":{"$ref":"#/components/schemas/portal_item"}}}},"portal_single":{"type":"object","properties":{"payload":{"$ref":"#/components/schemas/portal_item"}}},"portal_config":{"type":"object","description":"Configuration settings for the portal","properties":{"allowed_locales":{"type":"array","description":"List of allowed locales for the portal","items":{"type":"object","properties":{"code":{"type":"string","description":"The language code"},"articles_count":{"type":"integer","description":"Number of articles in this locale"},"categories_count":{"type":"integer","description":"Number of categories in this locale"}}}}}},"portal_logo":{"type":"object","additionalProperties":false,"required":["id","portal_id","file_type","account_id","file_url","blob_id","filename"],"properties":{"id":{"type":"integer","minimum":1,"description":"ID of the logo file"},"portal_id":{"type":"integer","minimum":1,"description":"ID of the portal this logo belongs to"},"file_type":{"type":"string","minLength":1,"description":"MIME type of the file","enum":["image","audio","video","file"]},"account_id":{"type":"integer","minimum":1,"description":"ID of the account"},"file_url":{"type":"string","format":"uri","description":"URL to access the logo file"},"blob_id":{"type":"string","minLength":1,"description":"Signed Active Storage blob identifier"},"filename":{"type":"string","minLength":1,"description":"Original uploaded filename"}}},"portal_meta":{"type":"object","properties":{"all_articles_count":{"type":"integer","description":"Total number of articles"},"archived_articles_count":{"type":["integer","null"],"description":"Number of archived articles"},"published_count":{"type":["integer","null"],"description":"Number of published articles"},"draft_articles_count":{"type":["integer","null"],"description":"Number of draft articles"},"categories_count":{"type":"integer","description":"Number of categories"},"default_locale":{"type":"string","description":"Default locale for the portal"}}},"portal_item":{"type":"object","properties":{"id":{"type":"integer","description":"The ID of the portal"},"archived":{"type":"boolean","description":"Whether the portal is archived"},"color":{"type":"string","description":"The color code for the portal"},"config":{"$ref":"#/components/schemas/portal_config"},"custom_domain":{"type":"string","description":"Custom domain for the portal"},"header_text":{"type":"string","description":"The header text for the portal"},"homepage_link":{"type":"string","description":"Homepage link for the portal"},"name":{"type":"string","description":"Name of the portal"},"slug":{"type":"string","description":"URL slug for the portal"},"page_title":{"type":"string","description":"Page title for the portal"},"account_id":{"type":"integer","description":"ID of the account the portal belongs to"},"inbox":{"$ref":"#/components/schemas/inbox"},"logo":{"$ref":"#/components/schemas/portal_logo"},"meta":{"$ref":"#/components/schemas/portal_meta"}}},"category":{"type":"object","properties":{"id":{"type":"integer"},"description":{"type":"string","description":"The text content."},"locale":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"position":{"type":"integer"},"visibility":{"type":"string","enum":["public","operator"],"description":"Public-reader visibility of the Help Center category."},"portal_id":{"type":"integer"},"account_id":{"type":"integer"},"associated_category_id":{"type":"integer","description":"To associate similar categories to each other, e.g same category of product documentation in different languages"},"parent_category_id":{"type":"integer","description":"To define parent category, e.g product documentation has multiple level features in sales category or in engineering category."}}},"article":{"type":"object","properties":{"id":{"type":"integer"},"content":{"type":"string","description":"The text content."},"meta":{"type":"object","additionalProperties":true,"description":"Free-form article metadata used for search and listing (e.g. tags, title and description)."},"position":{"type":"integer"},"status":{"type":"string","enum":["draft","published","archived"]},"visibility":{"type":"string","enum":["public","operator"],"description":"Public-reader visibility of the Help Center article."},"title":{"type":"string"},"slug":{"type":"string"},"views":{"type":"integer"},"portal_id":{"type":"integer"},"account_id":{"type":"integer"},"author_id":{"type":"integer"},"category_id":{"type":"integer"},"folder_id":{"type":"integer"},"associated_article_id":{"type":"integer","description":"To associate similar articles to each other, e.g to provide the link for the reference."}}},"contact":{"type":"object","properties":{"payload":{"type":"array","items":{"type":"object","properties":{"additional_attributes":{"type":"object","description":"The object containing additional attributes related to the contact","additionalProperties":true},"availability_status":{"type":"string","description":"The availability status of the contact","enum":["online","offline","busy"]},"email":{"type":"string","description":"The email address of the contact"},"id":{"type":"integer","description":"The ID of the contact"},"name":{"type":"string","description":"The name of the contact"},"phone_number":{"type":"string","description":"The phone number of the contact"},"blocked":{"type":"boolean","description":"Whether the contact is blocked"},"contact_type":{"type":"string","enum":["visitor","lead","customer"],"description":"Native lifecycle stage of the contact. It appeared in every response and in the examples but was never a typed property, so a generated client had no way to know the set was closed. Read-only for a widget-created visitor; an agent promotes it from the contact panel and automation can set it."},"identifier":{"type":"string","description":"The identifier of the contact"},"referred_by_affiliate_id":{"type":"integer","description":"Spec-078 — the affiliate that referred this contact. Present only when the account has the affiliate_program feature; a paid order from this contact inherits the credit unless the order names an affiliate of its own."},"referred_by_affiliate_name":{"type":"string","description":"Display name of that affiliate, so a row can be labelled without a second request. Read-only — referred_by_affiliate_id is what a client writes back."},"legal_type":{"type":"string","enum":["individual","business"],"description":"Whether the contact is a natural person (individual) or a legal entity (business)"},"tax_id":{"type":"string","description":"The fiscal identifier. Returned as the real value to an authenticated human agent; a type-aware mask (e.g. \"***.***.***-09\") when a role field rule masks it or the caller is a bot. A hidden rule omits the key."},"tax_id_type":{"type":"string","enum":["br_cpf","br_cnpj","us_ein","eu_vat","uk_vat","generic"],"description":"The fiscal identifier scheme used to validate and mask tax_id"},"country":{"type":"string","description":"ISO 3166-1 alpha-2 country code used for fiscal-id detection (e.g. \"BR\", \"US\")"},"address":{"type":"object","description":"Native postal address of the contact. Blank components are omitted.","properties":{"zip":{"type":"string","description":"Postal/ZIP code (CEP in Brazil)"},"street":{"type":"string","description":"Street name"},"number":{"type":"string","description":"Street number"},"complement":{"type":"string","description":"Address complement (apartment, suite, block)"},"neighborhood":{"type":"string","description":"Neighborhood/district"},"city":{"type":"string","description":"City name"},"state":{"type":"string","description":"State/province (UF in Brazil)"},"country":{"type":"string","description":"Country of the postal address"}}},"billing_address":{"type":"object","description":"Optional billing address override. An empty object means billing uses the principal address.","properties":{"zip":{"type":"string","description":"Postal/ZIP code (CEP in Brazil)"},"street":{"type":"string","description":"Street name"},"number":{"type":"string","description":"Street number"},"complement":{"type":"string","description":"Address complement (apartment, suite, block)"},"neighborhood":{"type":"string","description":"Neighborhood/district"},"city":{"type":"string","description":"City name"},"state":{"type":"string","description":"State/province (UF in Brazil)"},"country":{"type":"string","description":"Country of the postal address"}}},"thumbnail":{"type":"string","description":"The thumbnail of the contact"},"custom_attributes":{"type":"object","description":"The custom attributes of the contact","example":{"attribute_key":"attribute_value","signed_up_at":"dd/mm/yyyy"},"additionalProperties":true},"last_activity_at":{"type":"integer","description":"The last activity at of the contact"},"created_at":{"type":"integer","description":"The created at of the contact"},"contact_inboxes":{"type":"array","items":{"$ref":"#/components/schemas/contact_inboxes"}}}}}}},"conversation":{"type":"object","properties":{"id":{"type":"number","description":"ID of the conversation"},"messages":{"type":"array","items":{"$ref":"#/components/schemas/message"}},"account_id":{"type":"number","description":"Account Id"},"uuid":{"type":"string","description":"UUID of the conversation"},"additional_attributes":{"type":"object","description":"The object containing additional attributes related to the conversation","additionalProperties":true},"agent_last_seen_at":{"type":"number","description":"The last activity at of the agent"},"assignee_last_seen_at":{"type":"number","description":"The last activity at of the assignee"},"can_reply":{"type":"boolean","description":"Whether the conversation can be replied to"},"contact_last_seen_at":{"type":"number","description":"The last activity at of the contact"},"custom_attributes":{"type":"object","description":"The object to save custom attributes for conversation, accepts custom attributes key and value","additionalProperties":true},"inbox_id":{"type":"number","description":"ID of the inbox"},"labels":{"type":"array","items":{"type":"string"},"description":"The labels of the conversation"},"muted":{"type":"boolean","description":"Whether the conversation is muted"},"snoozed_until":{"type":["number","null"],"description":"The time at which the conversation will be unmuted"},"status":{"type":"string","enum":["open","resolved","pending","snoozed"],"description":"The status of the conversation"},"created_at":{"type":"number","description":"The time at which conversation was created"},"updated_at":{"type":"number","description":"The time at which conversation was updated"},"automation_control_event_cursor":{"type":"integer","format":"int64","readOnly":true,"description":"Exact server-issued conversation revision in microseconds, used to fence automation-control transitions. Clients must preserve the integer instead of deriving it from updated_at."},"timestamp":{"type":"number","description":"The time at which conversation was created"},"first_reply_created_at":{"type":["number","null"],"description":"The time at which the first reply was created"},"unread_count":{"type":"number","description":"The number of unread messages"},"last_non_activity_message":{"oneOf":[{"$ref":"#/components/schemas/message"},{"type":"null"}],"description":"The last non activity message"},"last_activity_at":{"type":"number","description":"The last activity at of the conversation"},"priority":{"type":["string","null"],"enum":["low","medium","high","urgent",null],"description":"The priority of the conversation"},"waiting_since":{"type":["number","null"],"description":"The time at which the conversation was waiting"},"sla_policy_id":{"type":["number","null"],"description":"The ID of the SLA policy"},"applied_sla":{"type":["object","null"],"additionalProperties":true,"description":"The SLA policy applied to the conversation (id, sla_policy_id, status and timing fields), or null when no SLA is applied."},"sla_events":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"An SLA breach/threshold event recorded for the conversation (event type, timing metric and timestamp)."}}}},"message":{"type":"object","properties":{"client_message_id":{"type":["string","null"],"readOnly":true,"description":"Durable author-scoped identity supplied when creating this message."},"client_message_actor":{"type":["string","null"],"readOnly":true,"description":"Server-issued author scope for client_message_id. Compare both fields when reconciling UI messages.","example":"User:7"},"outbound_dispatch":{"type":["object","null"],"readOnly":true,"description":"Public delivery state; provider attempt data is private and cannot be written by clients.","properties":{"state":{"type":"string","enum":["queued","dispatching","accepted","sent","unknown","failed","retry_queued"]},"retryable":{"type":"boolean"}}},"id":{"type":"number","description":"The ID of the message"},"content":{"type":["string","null"],"description":"The text content of the message. Null while governed inbound content is not semantically ready."},"content_readiness":{"type":["object","null"],"description":"Durable semantic readiness for governed inbound content. Absent for legacy and shadow-mode messages.","properties":{"state":{"type":"string","enum":["waiting","materializing","ready","ready_degraded","unavailable","discarded"]},"quality":{"type":"string","enum":["pending","complete","degraded","unavailable","discarded"]},"generation":{"type":"integer","minimum":1},"content_version":{"type":"integer","minimum":0}}},"account_id":{"type":"number","description":"The ID of the account"},"inbox_id":{"type":"number","description":"The ID of the inbox"},"logical_inbox_id":{"type":"integer","readOnly":true,"description":"Unified hybrid inbox identifier, present when different from inbox_id."},"echo_id":{"type":"string","readOnly":true,"description":"Transient composer correlation value when supplied. Durable retries use client_message_id."},"conversation_id":{"type":"number","description":"The ID of the conversation"},"message_type":{"type":"integer","enum":[0,1,2,3],"description":"The type of the message"},"created_at":{"type":"integer","description":"The time at which message was created"},"updated_at":{"type":["integer","string"],"description":"The time at which message was updated"},"private":{"type":"boolean","description":"The flags which shows whether the message is private or not"},"status":{"type":["string","null"],"enum":["sent","delivered","read","failed",null],"description":"The status of the message"},"source_id":{"type":["string","null"],"description":"The source ID of the message"},"content_type":{"type":["string","null"],"enum":["text","input_text","input_textarea","input_email","input_select","cards","form","article","incoming_email","input_csat","integrations","sticker","voice_call",null],"description":"The type of the template message"},"content_attributes":{"$ref":"#/components/schemas/translation_message_content_attributes"},"sender_type":{"type":["string","null"],"enum":["Contact","User","AgentBot","Captain::Assistant",null],"description":"The type of the sender"},"sender_id":{"type":["number","null"],"description":"The ID of the sender"},"external_source_ids":{"type":"object","additionalProperties":true,"description":"External source identifiers for the message, keyed by integration (e.g. slack)."},"additional_attributes":{"type":"object","description":"The additional attributes of the message","additionalProperties":true},"processed_message_content":{"type":["string","null"],"description":"The processed message content"},"sentiment":{"type":["object","null"],"additionalProperties":true,"description":"Sentiment analysis result for the message (e.g. label and score); empty when sentiment analysis has not run."},"conversation":{"type":["object","null"],"additionalProperties":true,"description":"Compact conversation summary embedded in the message (assignee_id, unread_count, last_activity_at and the contact_inbox source_id)."},"attachment":{"type":["object","null"],"additionalProperties":true,"description":"The file object attached to the message; available fields vary by attachment file type."},"attachments":{"type":"array","readOnly":true,"description":"Attachments visible to this principal. Omitted when empty or unavailable under the message visibility policy. Native REST includes media URLs; MCP text projections omit attachments.","items":{"$ref":"#/components/schemas/public_message_attachment"}},"sender":{"type":"object","additionalProperties":true,"description":"The message sender — a Contact, User or AgentBot object; available fields depend on the sender type."}}},"user":{"type":"object","properties":{"id":{"type":"number"},"access_token":{"type":"string"},"account_id":{"type":"number"},"available_name":{"type":"string"},"avatar_url":{"type":"string"},"confirmed":{"type":"boolean"},"display_name":{"type":["string","null"]},"message_signature":{"type":["string","null"]},"email":{"type":"string"},"hmac_identifier":{"type":"string"},"inviter_id":{"type":["number","null"]},"name":{"type":"string"},"provider":{"type":"string","enum":["email","google_oauth2","saml"],"description":"Authentication provider used to sign in the user (email password, Google OAuth or SAML SSO)."},"pubsub_token":{"type":"string"},"role":{"type":"string","enum":["agent","administrator"]},"ui_settings":{"type":"object","additionalProperties":true,"description":"Free-form per-user dashboard UI preferences (keys such as conversation display type and sidebar state).","properties":{"translation_language_by_account":{"type":"object","description":"Per-account BCP-47 viewer language preferences, keyed by numeric account id.","propertyNames":{"pattern":"^\\d+$"},"additionalProperties":{"type":"string","pattern":"^[A-Za-z]{2,3}(?:-[A-Za-z]{4})?(?:-(?:[A-Za-z]{2}|[0-9]{3}))?$"},"example":{"1":"pt-BR"}}}},"uid":{"type":"string"},"type":{"type":["string","null"]},"custom_attributes":{"type":"object","description":"Available for users who are created through platform APIs and has custom attributes associated.","additionalProperties":true},"accounts":{"type":"array","items":{"type":"object","required":["onboarding_step","access_role_id","api_and_webhooks"],"properties":{"id":{"type":"number"},"name":{"type":"string"},"status":{"type":"string","enum":["active","suspended"],"description":"Status of the account the user belongs to."},"active_at":{"type":["string","null"],"format":"date-time"},"role":{"type":"string","enum":["administrator","agent"]},"outbound_agent_name_header_policy":{"type":"string","enum":["inherit","always","never"],"description":"The administrator's rule for this user's name on outgoing messages in this account. It does not bind a user whose role is `administrator`. Present only on the caller's own memberships, or on a membership of an account the caller administers.","example":"inherit"},"permissions":{"type":"array","items":{"type":"string"}},"availability":{"type":"string","enum":["online","offline","busy"],"description":"Availability the user configured for this account."},"availability_status":{"type":"string","enum":["online","offline","busy"],"description":"Realtime availability. Contacts report online/offline (presence-based); agents/users additionally report busy (their configured availability)."},"auto_offline":{"type":"boolean"},"custom_role_id":{"type":["number","null"]},"custom_role":{"type":["object","null"],"additionalProperties":false,"required":["id","name","description","permissions"],"description":"Enterprise custom role on this account membership, or null for a built-in role. Omitted in Community Edition. Only the four fields selected by the account-user serializer are returned; native access-role rules and role scope data are not part of this object.","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":["string","null"]},"permissions":{"type":["array","null"],"items":{"type":"string","enum":["conversation_manage","conversation_unassigned_manage","conversation_participating_manage","contact_manage","report_manage","knowledge_base_manage"]}}}},"onboarding_step":{"type":["string","null"],"description":"Account onboarding step, or null."},"access_role_id":{"type":["integer","null"],"description":"Effective native access role id, or null when none applies."},"access_role":{"type":"object","additionalProperties":false,"required":["id","name","field_permissions"],"properties":{"id":{"type":"integer"},"name":{"type":"string"},"field_permissions":{"oneOf":[{"type":"object","additionalProperties":false,"properties":{"contact":{"type":"object","additionalProperties":{"type":"string","enum":["visible","masked","hidden"]},"description":"Field-name to native visibility rule map."},"organization":{"type":"object","additionalProperties":{"type":"string","enum":["visible","masked","hidden"]},"description":"Field-name to native visibility rule map."}},"description":"Native field visibility overrides, empty when no field is overridden."},{"type":"array","maxItems":0,"description":"An empty array is admitted by the blank-value validation guard."},{"type":"boolean","enum":[false],"description":"False is admitted by the blank-value validation guard."},{"type":"string","pattern":"^[\\u0009-\\u000D\\u0020\\u0085\\u00A0\\u1680\\u2000-\\u200A\\u2028\\u2029\\u202F\\u205F\\u3000]*$","description":"A blank stored string is admitted by the validation guard."}],"description":"Native field visibility map. Empty JSON values accepted by the model blank guard are returned as stored."}},"description":"Present only when this membership has an effective native access role."},"api_and_webhooks":{"type":"boolean","description":"Whether the API and webhook feature is enabled for this membership's account."}}}}}},"agent":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"account_user_id":{"type":["integer","null"],"readOnly":true,"description":"Account membership id used by WFM schedule, shift, adherence, and monitoring APIs."},"availability_status":{"type":"string","enum":["online","busy","offline"],"readOnly":true,"description":"The effective availability status of the agent, derived from the configured availability, auto-offline setting, and current presence. To update an agent's configured availability, use the availability field in create or update requests."},"auto_offline":{"type":"boolean","description":"Whether the agent is automatically marked offline when they are away."},"confirmed":{"type":"boolean","description":"Whether the agent has confirmed their email address."},"email":{"type":"string","description":"The email of the agent"},"available_name":{"type":"string","description":"The available name of the agent"},"name":{"type":"string","description":"The name of the agent"},"role":{"type":"string","enum":["agent","administrator"],"description":"The role of the agent"},"outbound_agent_name_header_policy":{"type":"string","enum":["inherit","always","never"],"description":"The administrator's rule for this agent's name on outgoing messages. `inherit` follows the inbox and account rules, `always` shows the name on every message, `never` hides it. It takes precedence over the inbox and account rules and does not bind an administrator, who decides in their own profile. Returned only when the caller is an administrator of the account.","example":"inherit"},"thumbnail":{"type":"string","description":"The thumbnail of the agent"},"custom_role_id":{"type":["integer","null"],"description":"The custom role id of the agent"}}},"campaign":{"type":"object","description":"Campaign as returned by the authenticated account API.","required":["id","title","account_id","inbox","message","campaign_status","enabled","campaign_type","recipient_stats","media_attachments","created_at","updated_at"],"properties":{"id":{"type":"integer","description":"Account-scoped display identifier used by campaign API paths.","example":31},"title":{"type":"string","example":"Renewal reminder"},"description":{"type":["string","null"],"example":"Reminds customers whose renewal is due this week."},"account_id":{"type":"integer","example":1},"inbox":{"$ref":"#/components/schemas/inbox"},"logical_inbox_id":{"type":"integer","description":"Agent-facing inbox identity when the campaign's physical WhatsApp transport belongs to an activated unified hybrid pair. Omitted when it is identical to the physical inbox id.","example":15},"whatsapp_transport":{"type":"string","enum":["web","cloud"],"description":"Physical WhatsApp transport that owns delivery. Present only for WhatsApp campaigns.","example":"web"},"sender":{"$ref":"#/components/schemas/agent"},"message":{"type":"string","example":"Hello {{contact.name}}, your renewal is due soon."},"template_params":{"type":["object","null"],"additionalProperties":true,"description":"Provider template parameters keyed by component or template variable.","example":{}},"campaign_status":{"type":"string","enum":["active","completed","draft","scheduled","sending","paused","failed","processing"],"example":"scheduled"},"enabled":{"type":"boolean","example":true},"campaign_type":{"type":"string","enum":["ongoing","one_off"],"example":"one_off"},"scheduled_at":{"type":"integer","description":"Unix timestamp for a one-off campaign. Omitted for ongoing campaigns.","example":1786791600},"audience":{"type":"array","description":"Audience sources unioned by the delivery pipeline; duplicate contacts are targeted once.","items":{"type":"object","additionalProperties":false,"properties":{"type":{"type":"string","enum":["Label","Contact","Segment","Crm","Organization","All"],"example":"Label"},"id":{"type":"integer","description":"Source record id. Omitted for an All audience.","example":15},"source":{"type":"string","enum":["contact","conversation","both","organization"],"example":"conversation"},"conversation_status":{"type":"string","enum":["all","open","pending","snoozed","resolved"],"example":"open"},"stage_id":{"type":"integer","description":"Optional CRM stage restriction.","example":21}}},"example":[{"type":"Label","id":15,"source":"conversation","conversation_status":"open"}]},"trigger_rules":{"type":["object","null"],"additionalProperties":true,"description":"Trigger conditions for an ongoing campaign.","example":{}},"trigger_only_during_business_hours":{"type":"boolean","example":false},"message_variants":{"type":"array","description":"Optional WhatsApp Web message variants used for deterministic or randomized delivery.","items":{"type":"object","additionalProperties":true,"description":"One variant. Known fields are body, content_type, content_attributes and attachment_blob_ids; content attributes depend on the selected message type.","properties":{"body":{"type":"string","example":"Hello {{contact.name}}."},"content_type":{"type":"string","example":"text"},"content_attributes":{"type":"object","additionalProperties":true,"description":"Message-type-specific attributes rendered per recipient.","example":{}},"attachment_blob_ids":{"type":"array","items":{"type":"string"},"example":[]}}},"example":[]},"send_settings":{"type":"object","additionalProperties":true,"description":"WhatsApp delivery settings: WhatsApp Web pacing, batching, variant randomization and spintax, plus `conversation`, the policy for the conversation the campaign creates.","properties":{"conversation":{"$ref":"#/components/schemas/campaign_conversation_policy"}},"example":{"conversation":{"initial_status":"pending","on_reply":"open","assignment":"inbox_rules","labels":["black-friday"],"existing":"keep"}}},"recipient_stats":{"type":"object","additionalProperties":false,"description":"Per-recipient delivery counts. Every known state is present, including zero counts.","properties":{"pending":{"type":"integer","example":20},"processing":{"type":"integer","example":2},"sent":{"type":"integer","example":10},"delivered":{"type":"integer","example":8},"read":{"type":"integer","example":5},"replied":{"type":"integer","example":1},"failed":{"type":"integer","example":0},"skipped":{"type":"integer","example":0}}},"estimated_cost":{"type":["string","null"],"description":"Decimal cost estimate serialized without floating-point precision loss.","example":"12.50"},"actual_cost":{"type":["string","null"],"description":"Decimal realized cost serialized without floating-point precision loss.","example":"10.75"},"currency":{"type":["string","null"],"example":"BRL"},"media_attachments":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["id","signed_id","filename","content_type","byte_size"],"properties":{"id":{"type":"integer","example":91},"signed_id":{"type":"string","example":"eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBBQT09In19"},"filename":{"type":"string","example":"renewal.pdf"},"content_type":{"type":"string","example":"application/pdf"},"byte_size":{"type":"integer","example":48192}}}},"created_at":{"type":"string","format":"date-time","example":"2026-08-15T10:00:00.000Z"},"updated_at":{"type":"string","format":"date-time","example":"2026-08-15T10:05:00.000Z"}}},"campaign_conversation_policy":{"type":"object","additionalProperties":false,"description":"What a WhatsApp campaign does to the conversation it creates for each recipient, stored in `send_settings.conversation`. Honored only while the account has the `campaign_conversation_policy` feature and the campaign is on a WhatsApp inbox; otherwise the key is ignored and the conversation is created open, as before. Missing fields take the defaults below.","properties":{"initial_status":{"type":"string","enum":["pending","open","resolved"],"default":"pending","description":"Status the new conversation is created with. `pending` keeps it out of the Open list and notifies nobody until the customer replies; `open` is the historical behavior; `resolved` reopens natively when the customer replies.","example":"pending"},"on_reply":{"type":"string","enum":["open","keep"],"default":"open","description":"Applies to `pending` only. `open` opens the conversation at the customer's first reply, applies `assignment` in the same change and notifies the inbox members once; `keep` leaves it pending.","example":"open"},"assignment":{"type":"string","pattern":"^(inbox_rules|none|agent:[1-9][0-9]*|team:[1-9][0-9]*)$","default":"inbox_rules","description":"Who gets the conversation when the reply opens it: `inbox_rules` (the inbox's automatic assignment), `none` (nobody; an inbox with automatic assignment may still assign it later), `agent:\u003cuser id\u003e` (a member of the campaign inbox or an account administrator) or `team:\u003cteam id\u003e`. Never replaces an agent or team already on the conversation.","example":"inbox_rules"},"labels":{"type":"array","maxItems":10,"description":"Titles of existing account labels added to the conversation when it is created.","items":{"type":"string","minLength":1},"example":["black-friday"]},"existing":{"type":"string","enum":["keep","apply"],"default":"keep","description":"For a conversation the campaign reuses. `keep` leaves it untouched; `apply` sets `initial_status` and adds `labels`. `apply` together with `initial_status: resolved` is refused with 422, because resolving a live conversation would send the satisfaction survey before the campaign message.","example":"keep"}},"example":{"initial_status":"pending","on_reply":"open","assignment":"inbox_rules","labels":["black-friday"],"existing":"keep"}},"campaign_create_update_payload":{"type":"object","additionalProperties":false,"required":["campaign"],"description":"Attributes accepted when creating or updating an account campaign.","properties":{"whatsapp_transport":{"type":"string","enum":["web","cloud"],"description":"Optional transport selected outside the campaign object by hybrid WhatsApp clients. The server resolves it with the selected inbox and rejects an unavailable combination.","example":"web"},"campaign":{"type":"object","additionalProperties":false,"minProperties":1,"properties":{"title":{"type":"string","minLength":1,"example":"Renewal reminder"},"description":{"type":["string","null"],"example":"Reminds customers whose renewal is due this week."},"message":{"type":"string","example":"Hello {{contact.name}}, your renewal is due soon."},"enabled":{"type":"boolean","example":true},"trigger_only_during_business_hours":{"type":"boolean","example":false},"inbox_id":{"type":"integer","minimum":1,"description":"Account-owned inbox used to deliver this campaign.","example":15},"sender_id":{"type":"integer","minimum":1,"description":"Account-owned agent sender when the selected channel supports it.","example":7},"whatsapp_transport":{"type":"string","enum":["web","cloud"],"description":"Physical WhatsApp transport requested for the selected inbox.","example":"web"},"scheduled_at":{"type":"integer","minimum":0,"description":"Unix timestamp used for a one-off campaign schedule.","example":1786791600},"campaign_status":{"type":"string","enum":["active","completed","draft","scheduled","sending","paused","failed","processing"],"example":"scheduled"},"audience":{"type":"array","description":"Audience sources unioned by the delivery pipeline; duplicate contacts are targeted once.","items":{"type":"object","additionalProperties":false,"required":["type"],"properties":{"type":{"type":"string","enum":["Label","Contact","Segment","Crm","Organization","All"],"example":"Label"},"id":{"type":"integer","minimum":1,"description":"Source record identifier. Omit it for an All audience.","example":15},"source":{"type":"string","enum":["contact","conversation","both","organization"],"example":"conversation"},"conversation_status":{"type":"string","enum":["all","open","pending","snoozed","resolved"],"example":"open"},"stage_id":{"type":"integer","minimum":1,"description":"Optional CRM stage restriction.","example":21}}}},"trigger_rules":{"type":["object","null"],"additionalProperties":true,"description":"Trigger conditions for an ongoing campaign.","example":{}},"template_params":{"type":["object","null"],"additionalProperties":true,"description":"Provider template parameters keyed by component or template variable.","example":{}},"send_settings":{"type":["object","null"],"additionalProperties":true,"description":"WhatsApp delivery settings: WhatsApp Web pacing, batching, variant randomization and spintax, plus `conversation`, the policy for the conversation the campaign creates (Cloud and Web). The server-owned `dispatch_control` key is ignored on input.","properties":{"conversation":{"$ref":"#/components/schemas/campaign_conversation_policy"}},"example":{"conversation":{"initial_status":"pending","on_reply":"open","assignment":"inbox_rules","labels":["black-friday"],"existing":"keep"}}},"media_blob_ids":{"type":"array","description":"Account-owned Active Storage signed identifiers returned by a direct-upload endpoint. They are attached atomically after campaign validation and are unavailable through MCP.","items":{"type":"string","minLength":1},"example":[]},"message_variants":{"type":"array","description":"Optional WhatsApp Web message variants. Each attachment signed identifier must belong to this account and is validated before the campaign is saved.","items":{"type":"object","additionalProperties":true,"properties":{"body":{"type":"string","example":"Hello {{contact.name}}."},"content_type":{"type":"string","example":"text"},"content_attributes":{"type":"object","additionalProperties":true,"description":"Message-type-specific attributes rendered per recipient.","example":{}},"attachment_blob_ids":{"type":"array","items":{"type":"string","minLength":1},"example":[]}}}}},"example":{"title":"Renewal reminder","message":"Hello {{contact.name}}, your renewal is due this week.","inbox_id":15,"whatsapp_transport":"web","campaign_status":"scheduled","audience":[{"type":"Label","id":15,"source":"conversation","conversation_status":"open"}],"media_blob_ids":[],"message_variants":[]}}},"example":{"whatsapp_transport":"web","campaign":{"title":"Renewal reminder","message":"Hello {{contact.name}}, your renewal is due this week.","inbox_id":15,"whatsapp_transport":"web","campaign_status":"scheduled","audience":[{"type":"Label","id":15,"source":"conversation","conversation_status":"open"}],"media_blob_ids":[],"message_variants":[]}}},"inbox":{"type":"object","properties":{"navigation_only":{"type":"boolean","description":"When true, this is a minimal member-inbox projection for navigation. It grants no inbox configuration access and includes no credentials or administrative settings; conversation access remains restricted by the effective role."},"id":{"type":"number","description":"ID of the inbox"},"name":{"type":"string","description":"The name of the inbox"},"website_url":{"type":"string","description":"Website URL"},"channel_type":{"type":"string","enum":["Channel::Api","Channel::Email","Channel::FacebookPage","Channel::Instagram","Channel::Line","Channel::Sms","Channel::Telegram","Channel::Tiktok","Channel::TwilioSms","Channel::TwitterProfile","Channel::WebWidget","Channel::Whatsapp"],"description":"The channel class backing the inbox"},"avatar_url":{"type":"string","description":"The avatar image of the inbox"},"widget_color":{"type":"string","description":"Widget Color used for customization of the widget"},"website_token":{"type":"string","description":"Website Token"},"enable_auto_assignment":{"type":"boolean","description":"The flag which shows whether Auto Assignment is enabled or not"},"web_widget_script":{"type":"string","description":"Script used to load the website widget"},"welcome_title":{"type":["string","null"],"description":"Welcome title to be displayed on the widget"},"welcome_tagline":{"type":["string","null"],"description":"Welcome tagline to be displayed on the widget"},"greeting_enabled":{"type":"boolean","description":"The flag which shows whether greeting is enabled"},"greeting_message":{"type":["string","null"],"description":"A greeting message when the user starts the conversation"},"channel_id":{"type":"number","description":"ID of the channel this inbox belongs to"},"working_hours_enabled":{"type":"boolean","description":"The flag which shows whether working hours feature is enabled"},"enable_email_collect":{"type":"boolean","description":"The flag to enable collecting email from contacts"},"csat_survey_enabled":{"type":"boolean","description":"The flag to enable CSAT survey"},"auto_assignment_config":{"type":"object","additionalProperties":true,"description":"Configuration settings for auto assignment (e.g. the maximum number of open conversations assignable per agent)."},"out_of_office_message":{"type":["string","null"],"description":"Message to show when agents are out of office"},"working_hours":{"type":"array","description":"Configuration for working hours of the inbox","items":{"type":"object","properties":{"day_of_week":{"type":"number","description":"Day of the week (0-6, where 0 is Sunday)"},"closed_all_day":{"type":"boolean","description":"Whether the inbox is closed for the entire day"},"open_hour":{"type":["number","null"],"description":"Hour when inbox opens (0-23)"},"open_minutes":{"type":["number","null"],"description":"Minutes of the hour when inbox opens (0-59)"},"close_hour":{"type":["number","null"],"description":"Hour when inbox closes (0-23)"},"close_minutes":{"type":["number","null"],"description":"Minutes of the hour when inbox closes (0-59)"},"open_all_day":{"type":"boolean","description":"Whether the inbox is open for the entire day"}}}},"timezone":{"type":"string","description":"Timezone configuration for the inbox"},"callback_webhook_url":{"type":["string","null"],"description":"Webhook URL for callbacks"},"allow_messages_after_resolved":{"type":"boolean","description":"Whether to allow messages after a conversation is resolved"},"lock_to_single_conversation":{"type":"boolean","description":"Whether to lock a contact to a single conversation"},"sender_name_type":{"type":"string","enum":["friendly","professional"],"description":"Type of sender name to display on outbound messages"},"auto_resolve_config":{"type":"object","additionalProperties":false,"if":{"properties":{"mode":{"const":"custom"}},"required":["mode"]},"then":{"required":["after"]},"description":"Per-inbox override of the account inactivity auto-resolve rule. An empty object means the inbox inherits the account rule. With `mode: custom` the inbox owns a complete rule (the account message, label and waiting preference are not mixed in) and it applies even when the account has no rule. With `mode: disabled` conversations of this inbox are never auto-resolved.","properties":{"mode":{"type":"string","enum":["inherit","custom","disabled"],"description":"How the inbox relates to the account rule. Absent means `inherit`."},"after":{"type":["integer","null"],"minimum":10,"maximum":1439856,"description":"Minutes of inactivity after which an open conversation is resolved. Present only when `mode` is `custom`."},"message":{"type":["string","null"],"maxLength":10000,"description":"Message sent to the contact when the conversation is auto-resolved. Present only when `mode` is `custom`."},"label":{"type":["string","null"],"description":"Title of the label added after auto-resolution. Present only when `mode` is `custom`."},"allow_waiting":{"type":"boolean","description":"Whether conversations still waiting for an agent reply are resolved too. Present only when `mode` is `custom`."}},"example":{"mode":"custom","after":30,"message":"We are closing this conversation due to inactivity.","label":"auto-resolved","allow_waiting":false}},"outbound_agent_name_header_policy":{"type":"string","enum":["inherit","required","optional"],"description":"Per-inbox override of the account policy that makes the agent name header mandatory on outbound messages. `inherit` follows the account, `required` forces the header in this inbox, `optional` leaves the choice to each agent in this inbox.","example":"inherit"},"business_name":{"type":["string","null"],"description":"Business name associated with the inbox"},"branded_email_layout":{"type":["string","null"],"description":"Liquid HTML layout for branded email replies. Available to administrators for Email inbox show/update responses."},"responder_policy":{"type":["object","null"],"description":"The automated responder selected for this logical inbox. A conflict without a complete choice is unresolved and both AI responders fail closed.","properties":{"mode":{"type":"string","enum":["agent_bot","captain","unresolved"]},"conflict":{"type":"boolean"}}},"hmac_mandatory":{"type":"boolean","description":"Whether HMAC verification is mandatory"},"selected_feature_flags":{"type":["array","null"],"description":"Selected feature flags for the inbox","items":{"type":"string"}},"reply_time":{"type":"string","description":"Expected reply time"},"messaging_service_sid":{"type":["string","null"],"description":"Messaging service SID for SMS providers"},"phone_number":{"type":["string","null"],"description":"Phone number associated with the inbox"},"bandwidth_callback_state":{"type":["string","null"],"enum":["active","reconnect_required","reconciling","reconciliation_required","encryption_required",null],"description":"SMS callback security state. This field never exposes the generated per-channel Basic pair; reconciliation_required means a prior provider apply may be ambiguous; reconnect replays the idempotent full-document reconciliation while a bounded prior-pair grace remains active."},"bandwidth_api_migration_state":{"type":["string","null"],"enum":["oauth2_configured","oauth2_required","configuration_required",null],"description":"SMS Bandwidth Account API authentication posture. `oauth2_required` means legacy API-user Basic credentials remain configured and must be replaced with OAuth2 client credentials before 2026-12-02. This field contains no client, API-user, token, or callback secret."},"medium":{"type":"string","description":"Medium of communication (e.g., sms, email)"},"provider":{"type":["string","null"],"enum":["default","whatsapp_cloud","whatsapp_web","google","microsoft",null],"description":"Channel-specific provider of the underlying channel — WhatsApp uses default, whatsapp_cloud or whatsapp_web (WazMeow); Email uses google or microsoft; null for channels that have no provider concept."},"whatsapp_web_session_state":{"type":"object","description":"Secret-free, cached observation of a physical WhatsApp Web session. Present only when `provider` is `whatsapp_web`. It is not a gateway request and must be refreshed by reading this resource again; `unknown` never means disconnected.","required":["state","fresh","observed_at","disconnected_since"],"properties":{"state":{"type":"string","enum":["connected","disconnected","unknown"],"description":"`unknown` covers absent, invalid, stale or temporarily unreadable cached state and does not authorize a disconnected conclusion."},"fresh":{"type":"boolean","description":"Whether the state observation remains inside the server-owned freshness window."},"observed_at":{"type":["string","null"],"format":"date-time","description":"Server observation timestamp, if a valid cached observation exists."},"disconnected_since":{"type":["string","null"],"format":"date-time","description":"Start of the current fresh disconnected episode. Null for connected and unknown states."}},"example":{"state":"connected","fresh":true,"observed_at":"2026-01-15T10:30:00.000Z","disconnected_since":null}},"hybrid_pair":{"description":"Secret-free WhatsApp hybrid-pair summary (WhatsApp Cloud API + WhatsApp Web via WazMeow), null for a non-WhatsApp inbox or when hybrid inbox support is off. A paired Cloud or Web inbox carries the pair, its effective routing (`routing.weighted` is the per-contact Cloud/Web percentage) and the capabilities of the Web side, with `web_session_state` as the physical Web observation; an unpaired inbox carries only the siblings it may be paired with.","oneOf":[{"type":"object","description":"Summary of a paired inbox.","additionalProperties":true,"required":["paired","id","role","sibling_inbox_id","canonical_phone","primary","inbound_authority","unified_inbox","unified_state","routing","web_channel_id","web_inbox_id","calling_provider","web_voice_enabled","web_inbound_calls_enabled","web_call_config_sync","web_video_calls_enabled","web_group_calls_enabled","web_reauthorization_required","web_session_state","web_allow_message_deletion"],"properties":{"paired":{"type":"boolean","enum":[true],"description":"Always true for a paired inbox."},"id":{"type":"integer","description":"Id of the hybrid pair."},"role":{"type":"string","enum":["cloud","web"],"description":"Which side of the pair this inbox is."},"sibling_inbox_id":{"type":["integer","null"],"description":"Inbox of the other side of the pair."},"canonical_phone":{"type":"string","description":"The phone number both sides share, in E.164."},"primary":{"type":"string","enum":["cloud","web"],"description":"Primary transport of the pair."},"inbound_authority":{"type":"string","enum":["cloud","web","both"],"description":"Transport whose inbound events are authoritative."},"unified_inbox":{"type":"boolean","description":"Whether both transports are served through one logical inbox (the Cloud API inbox)."},"unified_state":{"type":"object","additionalProperties":true,"description":"Progress of the unified-inbox activation: state, counters, timestamps, the error code and capability of a failure and the conversations that still block it (display id and reason). Never carries raw error text or credentials. When the pair was never unified it carries only blocked_conversations, as an empty list."},"routing":{"type":"object","additionalProperties":true,"required":["outbound_default","out_of_window","fallback","manual_override","weighted"],"description":"Effective routing of the pair — the stored keys over the product defaults. Keys stored by older versions may appear beside the ones listed.","properties":{"outbound_default":{"type":"string","enum":["cloud","web"],"description":"Transport of a reply inside the Cloud API customer-service window."},"out_of_window":{"type":"string","enum":["cloud","web"],"description":"Transport of a reply outside the Cloud API customer-service window."},"fallback":{"type":"boolean","description":"Whether a definitive rejection may fall back to the sibling transport."},"manual_override":{"type":"boolean","description":"Whether an agent may pick the transport in the conversation."},"weighted":{"type":"object","additionalProperties":false,"required":["mode","web_percent","version"],"description":"Per-contact weighted distribution between the two transports. `legacy` keeps the default outbound rule; `weighted` sends `web_percent`% of the eligible support sends of each contact through WhatsApp Web and the rest through Cloud API. A new percentage bumps `version`, which restarts every contact's count.","properties":{"mode":{"type":"string","enum":["legacy","weighted"],"description":"Distribution mode."},"web_percent":{"type":"integer","minimum":0,"maximum":100,"description":"Share of eligible sends routed through WhatsApp Web, in percent."},"version":{"type":"integer","minimum":1,"description":"Policy version, the optimistic-lock token of the next change."}}}}},"web_channel_id":{"type":"integer","description":"WhatsApp Web channel of the pair."},"web_inbox_id":{"type":["integer","null"],"description":"Inbox of the WhatsApp Web channel."},"calling_provider":{"type":"string","enum":["whatsapp_web"],"description":"Calls on a pair are always signaled and bridged through WhatsApp Web."},"web_voice_enabled":{"type":"boolean","description":"Whether voice calls are enabled on the WhatsApp Web side."},"web_inbound_calls_enabled":{"type":"boolean","description":"Whether the WhatsApp Web side accepts inbound calls."},"web_call_config_sync":{"type":["object","null"],"additionalProperties":true,"description":"State and last check time of the call configuration sync with the WazMeow gateway; null before the first sync."},"web_video_calls_enabled":{"type":"boolean","description":"Whether video calls are enabled on the WhatsApp Web side."},"web_group_calls_enabled":{"type":"boolean","description":"Whether group calls are enabled on the WhatsApp Web side."},"web_reauthorization_required":{"type":"boolean","description":"Whether the WhatsApp Web session must be paired again."},"web_session_state":{"type":"object","required":["state","fresh","observed_at","disconnected_since"],"description":"Cached observation of the physical WhatsApp Web session; `unknown` never means disconnected.","properties":{"state":{"type":"string","enum":["connected","disconnected","unknown"]},"fresh":{"type":"boolean"},"observed_at":{"type":["string","null"],"format":"date-time"},"disconnected_since":{"type":["string","null"],"format":"date-time","description":"Null unless the current reader result is a fresh disconnected episode."}}},"web_allow_message_deletion":{"type":["boolean","null"],"description":"Message-deletion policy of the WhatsApp Web inbox, used for rows WhatsApp Web delivered."}}},{"type":"object","description":"Summary of an inbox that is not paired.","additionalProperties":false,"required":["paired","candidates"],"properties":{"paired":{"type":"boolean","enum":[false],"description":"Always false for an inbox that is not paired."},"candidates":{"type":"array","description":"Same-number inboxes of the other WhatsApp provider this inbox may be paired with.","items":{"type":"object","additionalProperties":false,"required":["inbox_id","provider"],"properties":{"inbox_id":{"type":["integer","null"],"description":"Inbox of the candidate channel."},"provider":{"type":"string","enum":["whatsapp_cloud","whatsapp_web"],"description":"Provider of the candidate channel."}}}}}},{"type":"null"}],"example":{"paired":true,"id":4,"role":"cloud","sibling_inbox_id":18,"canonical_phone":"+5521900000000","primary":"cloud","inbound_authority":"cloud","unified_inbox":true,"unified_state":{"state":"complete","scanned":42,"frozen":40,"reconciled_count":2,"completed_at":"2026-10-03T12:00:00.000Z","blocked_conversations":[]},"routing":{"outbound_default":"cloud","out_of_window":"web","fallback":true,"manual_override":true,"weighted":{"mode":"weighted","web_percent":30,"version":2}},"web_channel_id":12,"web_inbox_id":18,"calling_provider":"whatsapp_web","web_voice_enabled":true,"web_inbound_calls_enabled":true,"web_call_config_sync":{"state":"pending","checked_at":"2026-10-03T12:00:00.000Z"},"web_video_calls_enabled":false,"web_group_calls_enabled":false,"web_reauthorization_required":false,"web_session_state":{"state":"connected","fresh":true,"observed_at":"2026-10-03T12:00:00.000Z","disconnected_since":null},"web_allow_message_deletion":true}}}},"branded_email_layout":{"type":"object","properties":{"branded_email_layout":{"type":["string","null"],"description":"Saved base Liquid HTML override for the account or selected email inbox. Null means inheritance.","example":"\u003chtml\u003e\u003cbody\u003e{{ content_for_layout }}\u003c/body\u003e\u003c/html\u003e"},"effective_layout":{"type":"string","description":"Liquid HTML layout after resolving the selected scope.","example":"\u003chtml\u003e\u003cbody\u003e{{ content_for_layout }}\u003c/body\u003e\u003c/html\u003e"},"inherited_layout":{"type":"string","description":"Liquid HTML layout used when the selected override is cleared.","example":"\u003chtml\u003e\u003cbody\u003e{{ content_for_layout }}\u003c/body\u003e\u003c/html\u003e"},"effective_source":{"type":"string","enum":["inbox","account","installation","default"],"description":"Scope providing the effective saved base layout.","example":"account"},"inherited_source":{"type":"string","enum":["account","installation","default"],"description":"Scope providing the base layout after removing this override.","example":"installation"},"locale":{"type":"string","enum":["en"],"description":"Base layout locale edited by this endpoint. Mailers retain their existing locale fallback rules.","example":"en"}}},"inbox_contact":{"type":"object","properties":{"id":{"type":"number","description":"ID of the inbox"},"avatar_url":{"type":"string","description":"The avatar image of the inbox"},"channel_id":{"type":"number","description":"The ID of the channel"},"name":{"type":"string","description":"The name of the inbox"},"channel_type":{"type":"string","enum":["Channel::Api","Channel::Email","Channel::FacebookPage","Channel::Instagram","Channel::Line","Channel::Sms","Channel::Telegram","Channel::Tiktok","Channel::TwilioSms","Channel::TwitterProfile","Channel::WebWidget","Channel::Whatsapp"],"description":"The channel class backing the inbox"},"provider":{"type":["string","null"],"enum":["default","whatsapp_cloud","whatsapp_web","google","microsoft",null],"description":"Channel-specific provider of the underlying channel — WhatsApp uses default, whatsapp_cloud or whatsapp_web (WazMeow); Email uses google or microsoft; null for channels that have no provider concept."}}},"agent_bot":{"type":"object","properties":{"id":{"type":"number","description":"ID of the agent bot"},"name":{"type":"string","description":"The name of the agent bot"},"description":{"type":"string","description":"The description about the agent bot"},"thumbnail":{"type":"string","description":"The thumbnail of the agent bot"},"outgoing_url":{"type":"string","description":"The webhook URL for the bot"},"bot_type":{"type":"string","enum":["webhook"],"description":"The type of the bot"},"bot_config":{"type":"object","additionalProperties":true,"description":"The native bot configuration. When `maestro_agent_id` is present it is the immutable, account-scoped identity edge to the Maestro sidecar; names are never used as identity.","properties":{"maestro_agent_id":{"type":"integer","minimum":1,"readOnly":true,"description":"Stable Maestro agent id linked through the dedicated administrative endpoint. Generic AgentBot writes may omit or echo it but cannot create, remove, or replace the link.","example":77}}},"receive_incoming_when_assigned":{"type":"boolean","description":"Effective delivery behavior for incoming messages on human-assigned conversations. `false` is the default for external webhook bots; Maestro is always `true` because it uses its own retain-only automation-control contract."},"receive_incoming_when_assigned_configurable":{"type":"boolean","description":"Whether this delivery behavior can be changed for the bot. It is `false` for Maestro."},"account_id":{"type":"number","description":"Account ID if it's an account specific bot"},"access_token":{"type":"string","description":"The access token for the bot"},"system_bot":{"type":"boolean","description":"Whether the bot is a system bot"}}},"agent_bot_slim":{"type":"object","description":"Public view of an AI Robot (agent bot) as returned when it is assigned to a conversation. Contains no credential: the bot's access token and webhook secret are never serialized here.","properties":{"id":{"type":"integer","description":"Stable agent-bot identifier.","example":18},"name":{"type":["string","null"],"description":"Human-readable Robot name, shown wherever the conversation's assignee is displayed.","example":"AI Robot"},"description":{"type":["string","null"],"description":"Optional description of the Robot's role.","example":"Answers pre-sales questions"},"thumbnail":{"type":["string","null"],"format":"uri","description":"Avatar URL for the Robot, or null when it has none.","example":"https://example.com/robot.png"},"outgoing_url":{"type":["string","null"],"format":"uri","description":"Outbound webhook the Robot is wired to. Omitted for system-wide bots, whose endpoint is not an account-level detail.","example":"https://example.com/webhook"},"bot_type":{"type":"string","enum":["webhook"],"description":"How the Robot receives events. Only webhook bots exist today.","example":"webhook"}}},"contact_inboxes":{"type":"object","properties":{"source_id":{"type":"string","description":"Contact Inbox Source Id"},"inbox":{"$ref":"#/components/schemas/inbox_contact"}}},"custom_filter":{"type":"object","properties":{"id":{"type":"number","description":"The ID of the custom filter"},"name":{"type":"string","description":"The name of the custom filter"},"filter_type":{"type":"string","enum":["conversation","contact","report","crm_item","crm_report","catalog_product","catalog_report","task","organization"],"description":"Which listing the saved filter applies to. Always serialized as the name, never the integer."},"query":{"type":"object","additionalProperties":true,"description":"The saved filter query (a payload with a payload array of condition groups — attribute_key, filter_operator, values and query_operator)."},"created_at":{"type":"string","format":"date-time","description":"The time at which the custom filter was created"},"updated_at":{"type":"string","format":"date-time","description":"The time at which the custom filter was updated"}}},"webhook":{"type":"object","properties":{"id":{"type":"number","description":"The ID of the webhook"},"url":{"type":"string","description":"The url to which the events will be send"},"name":{"type":"string","description":"The name of the webhook"},"subscriptions":{"type":"array","items":{"type":"string","enum":["conversation_status_changed","conversation_updated","conversation_created","contact_created","contact_updated","contact_merged","contact_deleted","message_created","message_updated","webwidget_triggered","inbox_created","inbox_updated","conversation_typing_on","conversation_typing_off","crm_item_created","crm_item_updated","crm_item_stage_changed","crm_item_won","crm_item_lost","crm_item_assigned","crm_item_stale","crm_item_reopened","crm_item_priority_changed","crm_item_value_changed","crm_item_health_changed","crm_item_checklist_completed","crm_item_sla_breached","crm_item_close_date_approaching","crm_item_close_date_overdue","whatsapp_group_participant_added","whatsapp_group_participant_removed","whatsapp_group_participant_promoted","whatsapp_group_participant_demoted","whatsapp_group_joined","whatsapp_group_join_request_received","whatsapp_group_info_changed","catalog_product_created","catalog_product_updated","catalog_product_archived","catalog_product_checklist_completed","catalog_variant_low_stock","catalog_variant_out_of_stock","crm_item_quote_total_changed","task_created","task_updated","task_status_changed","task_assigned","task_completed","task_reopened","task_overdue","task_due_soon","task_comment_added","task_unblocked","task_checklist_completed","payment_charge_created","payment_charge_confirmed","payment_charge_paid","payment_charge_partially_refunded","payment_charge_partially_paid","payment_charge_overdue","payment_charge_refunded","payment_charge_failed","payment_charge_canceled","payment_charge_payment_reversed","payment_subscription_created","payment_subscription_renewed","payment_subscription_canceled","payment_subscription_payment_failed","payment_installment_plan_created","payment_installment_plan_installment_paid","payment_installment_plan_installment_overdue","payment_installment_plan_completed","payment_installment_plan_canceled","commerce_cart_abandoned","commerce_order_placed","commerce_payment_pending","commerce_payment_confirmed","commerce_payment_declined","commerce_overdue","commerce_due_soon","commerce_refunded","commerce_chargeback","commerce_subscription_late","commerce_subscription_canceled","commerce_card_delivery","calendar_event_created","calendar_event_updated","calendar_event_rescheduled","calendar_event_cancelled","calendar_event_reminder_due","calendar_event_no_show","calendar_booking_created","calendar_booking_rescheduled","calendar_booking_cancelled","calendar_booking_payment_pending","calendar_booking_paid","calendar_booking_expired","calendar_booking_slot_lost","calendar_sync_failed","calendar_connection_connected","calendar_connection_revoked","follow_up_enrollment_created","follow_up_enrollment_paused","follow_up_enrollment_resumed","follow_up_enrollment_exited","follow_up_enrollment_completed","follow_up_enrollment_failed","follow_up_step_sent","follow_up_step_replied","follow_up_step_skipped","follow_up_step_failed","follow_up_draft_pending","brain_risk_changed","brain_insight_created","brain_department_run_completed","brain_improvement_proposed","routing_assigned","distribution_member_enrolled","distribution_member_invited","distribution_member_added","distribution_member_joined","distribution_member_left","distribution_member_removed","distribution_member_failed","distribution_unit_created","distribution_unit_opened","distribution_unit_full","distribution_completed","social_comment_captured","ads_lead_captured","sales_goal_reached","sales_tier_reached","sales_team_reward_granted","sales_deal_approval_requested","sales_deal_approval_approved","sales_deal_approval_rejected","sales_deal_floor_breached","sales_points_reversed","sales_contest_settled","sales_commission_accrued","sales_portfolio_transferred","sales_badge_awarded","sales_owner_changed","order_registered","order_status_changed","order_paid","order_refund_adjusted","order_refunded","order_payment_reversed","deal_orders_fully_paid","engagement_event_tracked","lead_score_changed","contract_created","contract_sent","contract_viewed","contract_signer_signed","contract_signed","contract_rejected","contract_expired","contract_voided","contract_document_generated","revenue_paid","affiliate_registered","affiliate_attributed","affiliate_commission_accrued","order_reattributed","wfm_status_changed","wfm_break_started","wfm_break_ended","wfm_break_breached","wfm_shift_started","wfm_shift_ended","whatsapp_broadcast_started","whatsapp_broadcast_completed","whatsapp_broadcast_failed","whatsapp_group_member_welcomed","whatsapp_group_member_farewelled","ads_campaign_status_changed","ctwa_conversation_started","ad_window_expiring","whatsapp_call_started","whatsapp_call_ended","whatsapp_call_recording_ready","whatsapp_flow_response_received","flow_session_started","flow_session_updated","flow_session_completed","flow_session_failed","organization_created","organization_updated","organization_archived","organization_membership_created","organization_membership_updated","organization_membership_removed","organization_relationship_created","message_schedule_created","message_schedule_published","message_schedule_paused","message_schedule_resumed","message_schedule_canceled","message_schedule_archived","message_schedule_completed","message_schedule_needs_attention","message_schedule_occurrence_scheduled","message_schedule_occurrence_dispatching","message_schedule_occurrence_queued","message_schedule_occurrence_retry_scheduled","message_schedule_occurrence_sent","message_schedule_occurrence_delivered","message_schedule_occurrence_read","message_schedule_occurrence_skipped","message_schedule_occurrence_failed","message_schedule_occurrence_canceled","message_schedule_occurrence_needs_attention"]},"description":"The list of subscribed events. Each key is a stable technical id; events are grouped by module family with human-readable names in the dashboard and Help Center — Conversation, Contact, CRM (deals), WhatsApp Groups, Catalog, Tasks, Payments, Commerce, Calendar \u0026 Booking, Follow-up, Account Brain, Routing, Distribution, Social \u0026 Ads (including CTWA — Click-to-WhatsApp — and Meta conversions), Sales, Orders, Engagement \u0026 Lead Score, Contracts, Revenue \u0026 Affiliates, Team Management, WhatsApp Broadcast, WhatsApp Calls \u0026 Flows, Flow sessions, and Message Scheduling. Event families whose account feature flag is off never fire."},"include_commerce_details":{"type":"boolean","default":false,"description":"Explicit opt-in for enriched commerce-event payloads. When false, commerce deliveries keep the privacy-minimal identifier payload. When true, normalized buyer, product/variation and sale-item details are included when those canonical values are available; provider secrets and raw gateway payloads are never added."},"secret_configured":{"type":"boolean","readOnly":true,"description":"True when this destination has a signing secret configured. The stored credential is never returned by list or update operations."},"secret":{"type":["string","null"],"readOnly":true,"description":"Create-once secret used to sign webhook requests. It is returned only by the successful create operation and cannot be recovered later. Signed deliveries include `X-Chatwoot-Timestamp`, `X-Chatwoot-Signature` (`sha256=` plus the HMAC-SHA256 of `{timestamp}.{raw_request_body}`), and `X-Chatwoot-Delivery` when available."},"account_id":{"type":"number","description":"The id of the account which the webhook object belongs to"}}},"webhook_delivery":{"type":"object","required":["id","delivery_id","event_name","url","status","attempts","created_at"],"properties":{"id":{"type":"integer","format":"int64","example":184},"delivery_id":{"type":"string","format":"uuid","description":"Stable idempotency identifier sent in the X-Chatwoot-Delivery header.","example":"5b96d21d-6df7-4bb3-9fbf-254da374f234"},"event_name":{"type":"string","example":"commerce_payment_confirmed"},"url":{"type":"string","format":"uri","description":"Destination snapshot shown without credentials, query string or fragment.","example":"https://erp.example.com/webhooks/commerce"},"status":{"type":"string","enum":["pending","delivering","retrying","delivered","failed"],"example":"retrying"},"attempts":{"type":"integer","minimum":0,"description":"Total transport attempts across automatic retries and deliberate manual replays.","example":2},"manual_replays":{"type":"integer","minimum":0,"description":"Number of times an administrator explicitly restarted this delivery's bounded retry cycle.","example":1},"http_status":{"type":["integer","null"],"example":503},"response_body":{"type":["string","null"],"description":"Bounded, credential-redacted diagnostic response captured from the destination.","example":"Service unavailable"},"last_error":{"type":["string","null"],"description":"Bounded, credential-redacted transport or HTTP error diagnostic.","example":"503 Service Unavailable"},"last_attempted_at":{"type":["string","null"],"format":"date-time","example":"2026-08-04T15:30:00.000Z"},"next_attempt_at":{"type":["string","null"],"format":"date-time","example":"2026-08-04T15:32:00.000Z"},"delivered_at":{"type":["string","null"],"format":"date-time","example":null},"created_at":{"type":"string","format":"date-time","example":"2026-08-04T15:28:00.000Z"}}},"contract_delivery_report":{"type":"object","description":"Who was actually reached when a contract was sent or a reminder was issued. It exists so a 200 can never again mean only \"the request did not crash\": both endpoints used to answer with an empty body while delivery failures were swallowed, so an operator was told \"sent\" for a message that never left.","properties":{"status":{"type":"string","enum":["delivered","partial","failed","skipped","blocked"],"description":"delivered = every pending signer was reached · partial = some were, some were not · failed = none were (the contract may still have advanced — that is exactly what the caller must see) · skipped = there was nobody to deliver to, e.g. a contract only the issuing company signs · blocked = the pre-flight refused the send, so nothing changed at all.","example":"partial"},"signers":{"type":"array","description":"One entry per pending signer. Empty when status is `skipped`.","items":{"type":"object","properties":{"signer_id":{"type":"integer","description":"The signer this entry is about.","example":4711},"name":{"type":"string","description":"The signer's name","so the operator reads who instead of an id.":null,"example":"Maria Souza"},"role":{"type":"string","enum":["contractor","contracted","witness","guarantor"],"description":"The party's role in the contract.","example":"contractor"},"status":{"type":"string","enum":["delivered","failed","blocked"],"description":"Whether this specific party received the request.","example":"failed"},"reason":{"type":"string","enum":["no_destination","no_inbox","channel_unavailable","hsm_template_without_url_button","no_signing_link","delivery_error","ai_not_active_in_conversation","ai_email_destination","ai_conversation_to_create","ai_other_conversation"],"description":"A canonical token, never a sentence, so a dashboard and an agentic executor can both branch on it. Absent when the entry succeeded. no_destination = the signer has neither a phone number nor an e-mail address · no_inbox = no WhatsApp inbox is configured to send from · hsm_template_without_url_button = out of the messaging window the approved template carries no link, so the party would receive prose with nothing to tap. The `ai_*` tokens appear only when the caller is the AI agent (an AgentBot) and mean a person must send the contract: ai_email_destination = the signer would be reached by e-mail · ai_conversation_to_create = a conversation would have to be opened · ai_other_conversation = the signer is not the contact of the conversation the agent is handling · ai_not_active_in_conversation = the agent is no longer the active bot of that conversation's inbox.","example":"no_destination"},"channel":{"type":"string","enum":["conversation","email"],"description":"Where the request went. Absent when the entry failed.","example":"email"}}}}}},"inbox_deletion_state":{"type":"object","description":"Recorded state of an asynchronous inbox deletion. An absent record reads as `unknown`, NEVER as success — the only authoritative success signal is the member endpoint answering 404, which comes from the database and cannot be faked by an expired or flushed cache entry.","properties":{"state":{"type":"string","enum":["processing","failed","unknown"],"description":"processing = queued or running; failed = rolled back; unknown = nothing recorded.","example":"failed"},"requested_at":{"type":["string","null"],"format":"date-time","example":"2026-08-11T18:04:11Z"},"failed_at":{"type":["string","null"],"format":"date-time","example":"2026-08-11T18:06:02Z"},"error_class":{"type":["string","null"],"example":"ActiveRecord::RecordNotUnique"},"error_message":{"type":["string","null"],"description":"Truncated to 300 chars.","example":"PG::UniqueViolation: duplicate key value"},"blocked_ids":{"type":"array","description":"Rows that could not be destroyed, as Class#id. Capped at 20.","items":{"type":"string","example":"Conversation#4711"}}}},"commerce_lifecycle_event_operational":{"type":"object","description":"Reversible operator workflow metadata returned alongside the immutable gateway and delivery history.","properties":{"outcome":{"type":["string","null"],"enum":["recovered","lost",null],"description":"Terminal business verdict; null means the opportunity is still open.","example":"recovered"},"owner_id":{"type":["integer","null"],"description":"Account user responsible for the opportunity.","example":7},"owner_name":{"type":["string","null"],"description":"Display name of the responsible account user.","example":"Ana Souza"},"operator_note":{"type":["string","null"],"maxLength":2000,"description":"Internal note visible only through the authenticated account surface.","example":"Customer completed payment after the follow-up call."},"ignored_at":{"type":["string","null"],"format":"date-time","description":"When an operator removed the opportunity from automatic recovery, backlog and metrics.","example":"2026-08-05T14:30:00.000Z"},"ignored_by_id":{"type":["integer","null"],"description":"Account user who ignored the opportunity.","example":9},"ignored_by_name":{"type":["string","null"],"description":"Display name of the account user who ignored the opportunity.","example":"Carlos Lima"}}},"commerce_lifecycle_event_operational_payload":{"type":"object","required":["lifecycle_event"],"properties":{"lifecycle_event":{"type":"object","minProperties":1,"additionalProperties":false,"description":"Operator workflow fields only. Gateway lifecycle and delivery fields are never writable here.","properties":{"outcome":{"type":["string","null"],"enum":["recovered","lost",null],"description":"Terminal business verdict. Null clears the verdict and leaves the opportunity open.","example":"recovered"},"owner_id":{"type":["integer","null"],"minimum":1,"description":"User responsible for the opportunity. The user must belong to this account; null unassigns it.","example":7},"operator_note":{"type":["string","null"],"maxLength":2000,"description":"Internal operator note. Leading/trailing whitespace is normalized; null or blank clears it.","example":"Customer completed payment after the follow-up call."}}}}},"account_detail":{"type":"object","properties":{"id":{"type":"number","description":"Account ID"},"name":{"type":"string","description":"Name of the account"},"locale":{"type":"string","description":"The locale of the account"},"domain":{"type":"string","description":"The domain of the account"},"support_email":{"type":"string","description":"The support email of the account"},"status":{"type":"string","enum":["active","suspended"],"description":"The status of the account"},"created_at":{"type":"string","format":"date-time","description":"The creation date of the account"},"cache_keys":{"type":"object","description":"Realtime cache-invalidation fingerprints keyed by entity — label, inbox and team; the dashboard compares them to decide when to refetch. Each value is an opaque epoch-derived fingerprint string.","additionalProperties":true,"example":{"label":"0000000000","inbox":"0000000000","team":"0000000000"}},"features":{"type":"object","description":"Map of the feature flags currently ENABLED for the account (feature name → true); disabled flags are omitted. The complete set of feature names is enumerated in the account create/update payload schema.","additionalProperties":{"type":"boolean"},"example":{"inbound_emails":true,"help_center":true}},"settings":{"type":"object","description":"Account settings","properties":{"auto_resolve_after":{"type":"number","description":"Auto resolve conversations after specified minutes"},"auto_resolve_message":{"type":"string","description":"Message to send when auto resolving"},"auto_resolve_ignore_waiting":{"type":"boolean","description":"Legacy flag (no longer read) — waiting conversations are protected by default"},"auto_resolve_allow_waiting":{"type":"boolean","description":"Explicit opt-out — also auto-resolve conversations still awaiting an agent reply"},"outbound_agent_name_header_required":{"type":["boolean","null"],"description":"Account-administrator policy: whether every agent's outbound messages must be prefixed with their name. Requires the outbound_agent_name_header account feature (see `features` above) to be enabled by the platform Super Admin — otherwise this setting has no effect."}}},"custom_attributes":{"type":"object","description":"Custom attributes of the account","properties":{"plan_name":{"type":["string","null"],"description":"Subscription plan name"},"subscribed_quantity":{"type":["number","null"],"description":"Subscribed quantity"},"subscription_status":{"type":["string","null"],"description":"Subscription status"},"subscription_ends_on":{"type":["string","null"],"format":"date","description":"Subscription end date"},"industry":{"type":"string","description":"Industry type"},"company_size":{"type":"string","description":"Company size"},"timezone":{"type":"string","description":"Account timezone"},"logo":{"type":"string","description":"Account logo URL"},"onboarding_step":{"type":"string","description":"Current onboarding step"},"guided_tours":{"type":"object","additionalProperties":false,"description":"Account-wide guided-tour presentation settings managed by account administrators.","properties":{"autoplay":{"type":"boolean","description":"Whether eligible unseen tours may start automatically.","example":true},"reset_at":{"type":"string","format":"date-time","description":"Server timestamp of the latest account-wide reset. Per-user progress older than this instant is treated as unseen; the original progress records are preserved.","example":"2026-08-05T12:30:00.000Z"}}},"marked_for_deletion_at":{"type":"string","format":"date-time","description":"When account was marked for deletion"},"marked_for_deletion_reason":{"type":"string","description":"Reason for account deletion"}}}}},"account_show_response":{"allOf":[{"$ref":"#/components/schemas/account_detail"},{"type":"object","properties":{"latest_chatwoot_version":{"type":["string","null"],"description":"Latest platform version available","example":"3.0.0"},"subscribed_features":{"type":"array","items":{"type":"string"},"description":"List of subscribed enterprise features (if enterprise edition is enabled)"}}}]},"account_user":{"type":"array","description":"Array of account users","items":{"type":"object","properties":{"account_id":{"type":"integer","description":"The ID of the account"},"user_id":{"type":"integer","description":"The ID of the user"},"role":{"type":"string","enum":["agent","administrator"],"description":"whether user is an administrator or agent"}}}},"platform_account":{"type":"object","properties":{"id":{"type":"number","description":"Account ID","example":1},"name":{"type":"string","description":"Name of the account","example":"My Account"},"locale":{"type":"string","description":"The locale of the account","example":"en"},"domain":{"type":"string","description":"The domain of the account","example":"example.com"},"support_email":{"type":"string","description":"The support email of the account","example":"support@example.com"},"features":{"type":"object","description":"Map of the feature flags currently ENABLED for the account (feature name → true); disabled flags are omitted. The complete set of feature names is enumerated in the account create/update payload schema.","additionalProperties":{"type":"boolean"},"example":{"inbound_emails":true,"help_center":true}},"custom_attributes":{"type":"object","description":"The custom attributes of the account","additionalProperties":true,"example":{"plan_name":"pro"}},"limits":{"type":"object","description":"Raw per-account caps as stored. Only the dimensions below can be present; values are always whole numbers of 0 or more (a numeric string sent on create/update is coerced). An ABSENT key means UNLIMITED — the installation default applies — which is how a cap left blank in the operator console is persisted. A stored ZERO reads as unlimited too (every enforcement point treats a non-positive cap as absent), so 0 never means \"allow none\". captain_responses, captain_documents and emails are only enforced on the Enterprise build; the `\u003cmetric\u003e_monthly` caps are the soft usage ceilings behind the 80%/100% threshold events and the usage panel.","additionalProperties":false,"properties":{"agents":{"type":"integer","minimum":0,"description":"Maximum number of agents","example":10},"inboxes":{"type":"integer","minimum":0,"description":"Maximum number of inboxes","example":20},"media_storage_mb":{"type":"integer","minimum":0,"description":"Media Library storage quota in MB","example":2048},"captain_responses":{"type":"integer","minimum":0,"description":"Maximum Captain AI responses (enterprise build only)","example":1000},"captain_documents":{"type":"integer","minimum":0,"description":"Maximum Captain knowledge documents (enterprise build only)","example":100},"emails":{"type":"integer","minimum":0,"description":"Maximum outbound conversation emails (enterprise build only)","example":5000},"messages_monthly":{"type":"integer","minimum":0,"description":"Soft monthly cap on messages","example":50000},"conversations_monthly":{"type":"integer","minimum":0,"description":"Soft monthly cap on conversations","example":5000},"contacts_monthly":{"type":"integer","minimum":0,"description":"Soft monthly cap on new contacts","example":10000},"ai_requests_monthly":{"type":"integer","minimum":0,"description":"Soft monthly cap on AI requests","example":2000},"ai_tokens_monthly":{"type":"integer","minimum":0,"description":"Soft monthly cap on AI tokens","example":1000000}},"example":{"agents":10,"inboxes":20,"media_storage_mb":2048,"captain_responses":1000,"captain_documents":100,"emails":5000,"messages_monthly":50000,"conversations_monthly":5000,"contacts_monthly":10000,"ai_requests_monthly":2000,"ai_tokens_monthly":1000000}},"status":{"type":"string","enum":["active","suspended"],"description":"The status of the account","example":"active"}}},"platform_user":{"type":"object","description":"A PlatformApp-scoped managed user. This deliberately excludes reusable credentials and account membership data: `access_token`, `pubsub_token`, `accounts`, `role` and account-scoped identifiers are never serialized by the Platform API.","properties":{"id":{"type":"integer","description":"Stable user identifier.","example":42},"name":{"type":"string","description":"Human-readable name.","example":"Ana Costa"},"display_name":{"type":["string","null"],"description":"Optional display name used in the dashboard.","example":"Ana"},"email":{"type":"string","format":"email","description":"Email address of the managed identity.","example":"ana@example.com"},"available_name":{"type":"string","description":"Name currently used for availability and assignment displays.","example":"Ana Costa"},"avatar_url":{"type":["string","null"],"format":"uri","description":"Avatar URL when the identity has an avatar.","example":"https://app.example.com/rails/active_storage/blobs/avatar.png"},"confirmed":{"type":"boolean","description":"Whether the user account is confirmed.","example":true},"message_signature":{"type":["string","null"],"description":"Optional signature appended to messages created by this user.","example":"Atendimento ConversaLabs"},"provider":{"type":"string","enum":["email","google_oauth2","saml"],"description":"Authentication provider associated with the user identity.","example":"email"},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Optional application-defined attributes attached to the managed user.","example":{"department":"Support"}},"ui_settings":{"type":["object","null"],"additionalProperties":true,"description":"Dashboard presentation preferences for this user, when configured.","example":{"conversation_display_type":"expanded"}},"uid":{"type":"string","description":"Provider-local identifier for the user.","example":"ana@example.com"}}},"platform_agent_bot":{"type":"object","description":"An account-bound bot owned by the calling PlatformApp. The response never contains `access_token`, webhook secrets, or any credential that could authenticate as the bot.","properties":{"id":{"type":"integer","description":"Stable agent-bot identifier.","example":18},"name":{"type":["string","null"],"description":"Human-readable bot name.","example":"Support relay"},"description":{"type":["string","null"],"description":"Optional description of the bot's role.","example":"Relays support events to the managed workflow."},"outgoing_url":{"type":["string","null"],"format":"uri","description":"Optional outbound webhook URL configured for the bot.","example":"https://automation.example.com/chatwoot/events"},"account_id":{"type":"integer","description":"Account the bot belongs to. Platform bots cannot be system-wide.","example":7},"receive_incoming_when_assigned":{"type":"boolean","description":"Effective delivery behavior for incoming messages on human-assigned conversations. External webhook bots default to `false`; Maestro is always `true` under its own control contract.","example":false},"receive_incoming_when_assigned_configurable":{"type":"boolean","description":"Whether the delivery behavior can be changed for this bot. It is `false` for Maestro.","example":true}}},"team":{"type":"object","properties":{"id":{"type":"number","description":"The ID of the team"},"name":{"type":"string","description":"The name of the team"},"description":{"type":["string","null"],"description":"The description about the team"},"allow_auto_assign":{"type":"boolean","description":"If this setting is turned on, the system would automatically assign the conversation to an agent in the team while assigning the conversation to a team"},"account_id":{"type":"number","description":"The ID of the account with the team is a part of"},"is_member":{"type":"boolean","description":"This field shows whether the current user is a part of the team"},"avatar_url":{"type":"string","description":"URL of the uploaded team icon, or an empty string when the team uses generated initials","example":"https://app.example.com/rails/active_storage/representations/team-icon.png"},"thumbnail":{"type":"string","description":"Alias of avatar_url used by avatar-enabled selectors in the dashboard","example":"https://app.example.com/rails/active_storage/representations/team-icon.png"}}},"label":{"type":"object","properties":{"id":{"type":"number","description":"The ID of the label"},"title":{"type":"string","description":"The title of the label"},"description":{"type":"string","description":"The description of the label"},"color":{"type":"string","description":"Hex color code for the label"},"show_on_sidebar":{"type":"boolean","description":"Whether the label should appear in the sidebar"}}},"integrations_app":{"type":"object","properties":{"id":{"type":"string","description":"The ID of the integration"},"name":{"type":"string","description":"The name of the integration"},"description":{"type":"string","description":"The description about the team"},"hook_type":{"type":"string","enum":["account","inbox"],"description":"Whether the integration is an account or inbox integration"},"enabled":{"type":"boolean","description":"Whether the integration is enabled for the account"},"allow_multiple_hooks":{"type":"boolean","description":"Whether multiple hooks can be created for the integration"},"token_url":{"type":"string","format":"uri","description":"Optional provider page where credentials can be created"},"console_url":{"type":"string","format":"uri","description":"Optional provider console used to enable or manage the integration"},"documentation_url":{"type":"string","format":"uri","description":"Optional official credential and setup guide for the integration"},"hooks":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"A hook created for this integration (mirrors the integration hook resource — id, app_id, inbox_id, status and settings)."},"description":"If there are any hooks created for this integration"}}},"integrations_hook":{"type":"object","properties":{"id":{"type":"string","description":"The ID of the integration hook"},"app_id":{"type":"string","description":"The ID of the integration app"},"inbox_id":{"type":"string","description":"Inbox ID if its an Inbox integration"},"account_id":{"type":"string","description":"Account ID of the integration"},"status":{"type":"boolean","description":"Whether the integration hook is enabled for the account"},"hook_type":{"type":"boolean","description":"Whether its an account or inbox integration hook"},"settings":{"type":"object","additionalProperties":true,"description":"The associated settings for the integration (integration-specific keys such as API tokens, webhook URLs and reference IDs)."}}},"audit_log":{"type":"object","properties":{"id":{"type":"integer","description":"Unique identifier for the audit log entry"},"auditable_id":{"type":"integer","description":"The ID of the audited object"},"auditable_type":{"type":"string","enum":["Account","AccountUser","AgentBot","AutomationRule","Conversation","Inbox","InboxMember","Macro","Team","TeamMember","User","Webhook"],"description":"The type of the audited object"},"auditable":{"type":["object","null"],"additionalProperties":true,"description":"The audited object data (the auditable record's push event payload), or null when the record is no longer available."},"associated_id":{"type":"integer","description":"The ID of the associated object (typically the account ID)"},"associated_type":{"type":"string","enum":["Account"],"description":"The type of the associated object"},"user_id":{"type":["integer","null"],"description":"The ID of the actor in the table identified by user_type; null for a text or system actor."},"user_type":{"type":["string","null"],"enum":["User","PlatformApp",null],"description":"The authenticated actor type; PlatformApp identifies a Platform API application, while null identifies a text or system actor."},"username":{"type":["string","null"],"description":"Human email, stable PlatformApp#\u003cid\u003e application label, or text actor; null when no actor is available."},"action":{"type":"string","enum":["create","update","destroy"],"description":"The action performed on the object"},"audited_changes":{"type":"object","additionalProperties":true,"description":"JSON object containing the changes made to the audited object, keyed by attribute name (each value is the new value on create, or a [old, new] pair on update)."},"version":{"type":"integer","description":"Version number of the audit log entry"},"comment":{"type":["string","null"],"description":"Optional comment associated with the audit log entry"},"request_uuid":{"type":"string","description":"UUID to identify the request that generated this audit log"},"created_at":{"type":"integer","description":"Unix timestamp when the audit log entry was created"},"remote_address":{"type":["string","null"],"description":"IP address from which the action was performed"}}},"mcp_oauth_authorization":{"type":"object","description":"Safe account-plane review representation of one native MCP OAuth consent. It intentionally excludes bearer tokens, refresh tokens, authorization codes, client secrets and token digests.","required":["id","plane","status","client","subject","resource","scopes","decided_at","can_revoke"],"additionalProperties":false,"properties":{"id":{"type":"integer","description":"Internal authorization record id, used only to review or revoke this consent through the account API.","example":42},"plane":{"type":"string","enum":["account"],"description":"Authority plane that issued the consent. This account API returns account-plane rows only.","example":"account"},"status":{"type":"string","enum":["active","revoked","denied","inactive"],"description":"Current authorization state derived from the durable consent record.","example":"active"},"client":{"type":"object","description":"Public client identity declared at registration or in verified Client ID Metadata; never a secret.","required":["name"],"additionalProperties":false,"properties":{"name":{"type":"string","description":"Human-readable public client name when declared.","example":"Support desktop client"},"software_id":{"type":"string","description":"Optional public software identifier declared by the client.","example":"com.example.support-desktop"},"software_version":{"type":"string","description":"Optional public software version declared by the client.","example":"1.4.0"}}},"subject":{"type":"object","required":["name","email"],"description":"Human account member who approved the consent.","additionalProperties":false,"properties":{"name":{"type":["string","null"],"example":"Ana Support"},"email":{"type":["string","null"],"format":"email","example":"ana@example.com"}}},"resource":{"type":"object","required":["uri","profile_name","profile_enabled","effective_read_only","toolsets","tool_count"],"description":"Exact account MCP OAuth resource and its current profile-derived effective surface.","additionalProperties":false,"properties":{"uri":{"type":"string","format":"uri","description":"Exact OAuth MCP resource audience approved by the subject.","example":"https://app.example.com/api/v1/accounts/31/mcp/oauth/c/a1b2c3d4e5f6g7h8i9j0"},"profile_name":{"type":["string","null"],"description":"Current access-profile name, if the profile still exists.","example":"support-read-only"},"profile_enabled":{"type":["boolean","null"],"description":"Whether the profile is currently enabled; null when it no longer exists.","example":true},"effective_read_only":{"type":"boolean","description":"True when the profile is read-only, missing, or the approved scopes omit mcp:write.","example":true},"toolsets":{"type":"array","items":{"type":"string"},"description":"Current enabled profile toolsets. They remain constrained by the installation ceiling.","example":["Conversations","Contacts"]},"tool_count":{"type":"integer","minimum":0,"description":"Current number of resolved MCP tools for this consent's effective read-only state.","example":18}}},"scopes":{"type":"array","items":{"type":"string","enum":["mcp:read","mcp:write","offline_access"]},"description":"Scopes actually approved for this exact resource.","example":["mcp:read"]},"decided_at":{"type":["string","null"],"format":"date-time","description":"When the consent decision was made.","example":"2026-08-05T12:00:00Z"},"last_used_at":{"type":["string","null"],"format":"date-time","description":"Last observed use of this consent or one of its access tokens.","example":"2026-08-05T12:10:00Z"},"access_token_expires_at":{"type":["string","null"],"format":"date-time","description":"Expiration of the latest issued access token, not the token value.","example":"2026-08-05T12:15:00Z"},"revoked_at":{"type":["string","null"],"format":"date-time","description":"Revocation timestamp when the consent is revoked.","example":null},"can_revoke":{"type":"boolean","description":"Whether this durable consent has not already been revoked, so a permitted current user may revoke it.","example":true}}},"mcp_oauth_transport_error":{"type":"object","description":"Safe error for a native MCP OAuth request rejected at the transport boundary before OAuth parameters are parsed.","required":["error","error_description"],"additionalProperties":false,"properties":{"error":{"type":"string","enum":["invalid_request"],"description":"Stable OAuth error code.","example":"invalid_request"},"error_description":{"type":"string","description":"Generic size or request-framing error with no credential, account, issuer or network-topology detail.","example":"The OAuth request exceeds the supported size."}}},"mcp_modern_transport_error":{"type":"object","description":"A modern transport request whose protocol version or mirrored routing headers are invalid.","required":["jsonrpc","id","error"],"additionalProperties":false,"properties":{"jsonrpc":{"type":"string","enum":["2.0"],"example":"2.0"},"id":{"type":["integer","null"],"example":1},"error":{"type":"object","required":["code","message"],"additionalProperties":false,"properties":{"code":{"type":"integer","enum":[-32020,-32022],"example":-32022},"message":{"type":"string","example":"Unsupported protocol version"},"data":{"type":"object","description":"Present for -32022; identifies the supported and rejected protocol versions.","additionalProperties":false,"required":["supported","requested"],"properties":{"supported":{"type":"array","items":{"type":"string","enum":["2026-07-28"]},"example":["2026-07-28"]},"requested":{"type":"string","example":"2099-01-01"}}}}}}},"mcp_stateless_subscription_error":{"type":"object","description":"A modern client requested subscriptions/listen from a deployment whose MCP transport is recreated for every request. The method is not advertised and cannot retain a process-local subscription registry.","required":["jsonrpc","id","error"],"additionalProperties":false,"properties":{"jsonrpc":{"type":"string","enum":["2.0"],"example":"2.0"},"id":{"type":["integer","null"],"example":73},"error":{"type":"object","required":["code","message","data"],"additionalProperties":false,"properties":{"code":{"type":"integer","enum":[-32601],"example":-32601},"message":{"type":"string","enum":["Method not found"],"example":"Method not found"},"data":{"type":"string","enum":["subscriptions/listen is unavailable on this stateless transport"],"example":"subscriptions/listen is unavailable on this stateless transport"}}}}},"mcp_initialize_result":{"type":"object","required":["protocolVersion","capabilities","serverInfo"],"additionalProperties":true,"description":"Result returned by the MCP `initialize` method. Visual server metadata is carried only by MCP protocol versions that define it: `2025-11-25` can include title, description, websiteUrl and icons; older negotiated versions retain the technical name and version but can omit the newer visual fields.","properties":{"protocolVersion":{"type":"string","description":"MCP protocol version selected by the server.","example":"2025-11-25"},"capabilities":{"type":"object","additionalProperties":true,"description":"MCP server capabilities negotiated during initialization.","example":{"tools":{"listChanged":false}}},"serverInfo":{"type":"object","required":["name","version"],"additionalProperties":true,"description":"Server identity. The canonical public HTTPS origin is used for websiteUrl and every icon URL; when that origin is unavailable or unsafe, those optional visual fields are omitted rather than exposing an internal or untrusted address. A client is free to cache or not render these fields.","properties":{"name":{"type":"string","description":"Stable technical MCP server identifier derived from the installation brand.","example":"exampleco"},"version":{"type":"string","description":"MCP server implementation version.","example":"1.0.0"},"title":{"type":"string","description":"Human-readable branded server title (protocol `2025-06-18` or newer when supported).","example":"ExampleCo Account MCP"},"description":{"type":"string","description":"Human-readable branded server description (protocol `2025-11-25` when supported).","example":"ExampleCo Account MCP server."},"websiteUrl":{"type":"string","format":"uri","description":"Canonical public HTTPS installation URL (protocol `2025-06-18` or newer when supported).","example":"https://app.example.com"},"icons":{"type":"array","maxItems":3,"description":"Installation brand icons (primary, light and dark) announced by protocol `2025-11-25`. They are server metadata, not an instruction that a client UI must render or refresh an icon immediately.","items":{"type":"object","required":["src"],"additionalProperties":false,"properties":{"src":{"type":"string","format":"uri","description":"Public same-origin HTTPS icon URL.","example":"https://app.example.com/brand-assets/logo_thumbnail.svg"},"mimeType":{"type":"string","description":"MIME type of the icon when known.","example":"image/svg+xml"},"sizes":{"type":"array","items":{"type":"string"},"description":"Optional raster dimensions advertised by the MCP protocol.","example":["512x512"]},"theme":{"type":"string","enum":["light","dark"],"description":"Optional theme variant; the first icon has no theme and is the primary mark.","example":"dark"}}}}},"example":{"name":"exampleco","version":"1.0.0","title":"ExampleCo Account MCP","description":"ExampleCo Account MCP server.","websiteUrl":"https://app.example.com","icons":[{"src":"https://app.example.com/brand-assets/logo_thumbnail.svg","mimeType":"image/svg+xml"},{"src":"https://app.example.com/brand-assets/logo.svg","mimeType":"image/svg+xml","theme":"light"},{"src":"https://app.example.com/brand-assets/logo_dark.svg","mimeType":"image/svg+xml","theme":"dark"}]}}}},"public_contact":{"type":"object","properties":{"id":{"type":"integer","description":"Id of the contact"},"source_id":{"type":"string","description":"The session identifier of the contact"},"name":{"type":["string","null"],"description":"Name of the contact when available"},"email":{"type":["string","null"],"description":"Email of the contact"},"phone_number":{"type":["string","null"],"description":"Phone number of the contact"},"pubsub_token":{"type":"string","description":"The token to be used to connect to the platform websocket"}}},"public_contact_record":{"type":"object","additionalProperties":true,"description":"Full serialized contact record returned when the public API renders a Contact model directly.","properties":{"id":{"type":"integer","description":"Id of the contact"},"name":{"type":["string","null"],"description":"Name of the contact when available"},"email":{"type":["string","null"],"description":"Email of the contact"},"phone_number":{"type":["string","null"],"description":"Phone number of the contact"},"identifier":{"type":["string","null"],"description":"Identifier of the contact"},"blocked":{"type":"boolean","description":"Whether the contact is blocked"},"additional_attributes":{"type":["object","null"],"description":"Additional attributes of the contact when present","additionalProperties":true},"custom_attributes":{"type":["object","null"],"description":"Custom attributes of the contact when present","additionalProperties":true},"contact_type":{"type":["string","null"],"enum":["visitor","lead","customer",null],"description":"Contact type of the contact when available"},"country_code":{"type":["string","null"],"description":"Country code of the contact"},"last_activity_at":{"type":["string","null"],"description":"Last activity timestamp of the contact in ISO 8601 format"},"created_at":{"type":["string","null"],"description":"Created timestamp of the contact in ISO 8601 format"},"updated_at":{"type":["string","null"],"description":"Updated timestamp of the contact in ISO 8601 format"},"last_name":{"type":["string","null"],"description":"Last name of the contact"},"middle_name":{"type":["string","null"],"description":"Middle name of the contact"},"location":{"type":["string","null"],"description":"Location of the contact"},"account_id":{"type":"integer","description":"Account id of the contact"},"company_id":{"type":["integer","null"],"description":"Company id of the contact"},"label_list":{"type":"array","description":"Labels applied to the contact","items":{"type":"string"}}}},"public_conversation":{"type":"object","properties":{"id":{"type":"integer","description":"Id of the conversation"},"uuid":{"type":"string","description":"UUID of the conversation"},"inbox_id":{"type":"integer","description":"The inbox id of the conversation"},"contact_last_seen_at":{"type":"integer","description":"Timestamp of when the contact last seen the conversation (Unix timestamp)"},"status":{"type":"string","enum":["open","resolved","pending","snoozed"],"description":"The status of the conversation"},"agent_last_seen_at":{"type":"integer","description":"Timestamp of when the agent last seen the conversation (Unix timestamp)"},"messages":{"type":"array","items":{"$ref":"#/components/schemas/public_message"},"description":"Messages in the conversation"},"contact":{"$ref":"#/components/schemas/public_contact_record"}}},"public_message":{"type":"object","properties":{"id":{"type":"integer","description":"Id of the message"},"content":{"type":["string","null"],"description":"Text content of the message. Can be null for attachment-only messages."},"message_type":{"type":"integer","description":"Denotes the message type. Possible values: 0 (incoming), 1 (outgoing), 2 (activity), 3 (template)"},"content_type":{"type":"string","enum":["text","input_text","input_textarea","input_email","input_select","cards","form","article","incoming_email","input_csat","integrations","sticker","voice_call","poll"],"description":"Content type of the message"},"content_attributes":{"$ref":"#/components/schemas/translation_message_content_attributes"},"created_at":{"type":"integer","description":"Created at Unix timestamp of the message"},"conversation_id":{"type":"integer","description":"Display Id of the conversation the message belongs to"},"attachments":{"type":"array","description":"Attachments if any","items":{"$ref":"#/components/schemas/public_message_attachment"}},"sender":{"$ref":"#/components/schemas/public_message_sender"}}},"public_message_attachment":{"type":"object","additionalProperties":true,"description":"Attachment payload. Available fields vary by attachment file_type.","properties":{"id":{"type":"integer","description":"Id of the attachment"},"message_id":{"type":"integer","description":"Id of the parent message"},"file_type":{"type":"string","enum":["image","audio","video","file","location","fallback","share","story_mention","contact","ig_reel","ig_post","ig_story","embed"],"description":"Type of the attached file"},"account_id":{"type":"integer","description":"Id of the account"},"extension":{"type":["string","null"],"description":"File extension"},"data_url":{"type":["string","null"],"description":"URL of the file. Can be null when an attachment variant has no external URL."},"media_readiness_revision":{"type":"string","readOnly":true,"description":"Opaque recovery revision. When it changes, reload the displayed media even if its URL is unchanged. Omitted before a recovery has been recorded."},"playable_audio_url":{"type":["string","null"],"description":"Browser-playable URL for audio attachments. Ogg, Opus, and WebM sources may temporarily use data_url while an MP3 rendition is prepared in the background; downloads continue to use the untouched original file."},"playable_video_url":{"type":["string","null"],"description":"Browser-playable URL for video attachments after background inspection. This is either the untouched original when it already is MP4/H.264/AAC, or a separate MP4/H.264/AAC faststart rendition. data_url always continues to identify the original file."},"video_processing":{"type":"boolean","description":"True while the browser-playable video is being inspected or prepared asynchronously."},"video_unavailable":{"type":"boolean","description":"True when the file has no usable video stream, exceeds the preparation limit, or could not be prepared after bounded retries. The original remains available through data_url."},"thumb_url":{"type":"string","description":"URL of the file thumbnail"},"file_size":{"type":"integer","description":"File size in bytes"},"width":{"type":["integer","null"],"description":"Width of the attachment when available"},"height":{"type":["integer","null"],"description":"Height of the attachment when available"},"coordinates_lat":{"type":"number","description":"Latitude for location attachments"},"coordinates_long":{"type":"number","description":"Longitude for location attachments"},"fallback_title":{"type":["string","null"],"description":"Fallback title for location, fallback, and contact attachments when available"},"meta":{"type":"object","additionalProperties":true,"description":"Metadata for contact attachments (e.g. the contact's name and phone numbers parsed from a shared vCard)."},"transcribed_text":{"type":"string","description":"Original speech-to-text transcription for audio attachments."},"transcript_translations":{"type":"object","additionalProperties":{"type":"string"},"description":"Translated transcript text keyed by normalized BCP-47 target language.","example":{"pt-BR":"Você pode me ajudar?","es":"¿Puedes ayudarme?"}},"transcript_translation_states":{"type":"object","additionalProperties":{"type":"object","additionalProperties":false,"properties":{"status":{"type":"string","enum":["translated","source_reuse","failed"]},"source_language":{"type":["string","null"]},"target_language":{"type":"string"},"provider":{"type":"string","enum":["google_translate","source"]},"content_digest":{"type":"string","pattern":"^[0-9a-f]{64}$"},"translated_at":{"type":"string","format":"date-time"},"error_code":{"type":"string","enum":["translation_error","provider_not_configured","missing_target_language","unsupported_language","provider_unavailable","provider_timeout"]},"failed_at":{"type":"string","format":"date-time"}}},"description":"Sanitized per-language transcript translation state; never contains provider credentials or raw exceptions."}}},"public_message_sender":{"type":"object","additionalProperties":true,"description":"Polymorphic sender payload returned by push_event_data. Available fields vary by sender type.","properties":{"id":{"type":"integer","description":"Id of the sender"},"name":{"type":["string","null"],"description":"Name of the sender when available"},"avatar_url":{"type":"string","description":"Avatar URL of the sender. Present for senders of type user, agent_bot, and captain_assistant. Not present for contact senders (use thumbnail instead)."},"thumbnail":{"type":"string","description":"Avatar/thumbnail URL of the sender. Contact senders use this field; user senders may also include it."},"type":{"type":"string","enum":["contact","user","agent_bot","captain_assistant"],"description":"Type of the sender"},"available_name":{"type":["string","null"],"description":"Display name for user senders"},"availability_status":{"type":["string","null"],"description":"Availability status for user senders","enum":["online","offline","busy",null]},"email":{"type":["string","null"],"description":"Email of the sender when the sender is a contact"},"phone_number":{"type":["string","null"],"description":"Phone number of the sender when the sender is a contact"},"identifier":{"type":["string","null"],"description":"Identifier of the sender when the sender is a contact"},"blocked":{"type":"boolean","description":"Whether the sender is blocked when the sender is a contact"},"additional_attributes":{"type":["object","null"],"description":"Additional attributes when the sender is a contact and available","additionalProperties":true},"custom_attributes":{"type":["object","null"],"description":"Custom attributes when the sender is a contact and available","additionalProperties":true},"description":{"type":["string","null"],"description":"Description when the sender is a captain assistant"},"created_at":{"type":["string","null"],"description":"Created timestamp in ISO 8601 format when the sender is a captain assistant"}}},"public_inbox":{"type":"object","properties":{"identifier":{"type":"string","description":"Inbox identifier"},"name":{"type":"string","description":"Name of the inbox"},"timezone":{"type":"string","description":"The timezone defined on the inbox"},"working_hours":{"type":"array","description":"The working hours defined on the inbox","items":{"type":"object","properties":{"day_of_week":{"type":"integer","description":"Day of the week as a number. Sunday -\u003e 0, Saturday -\u003e 6"},"open_all_day":{"type":"boolean","description":"Whether or not the business is open the whole day"},"closed_all_day":{"type":"boolean","description":"Whether or not the business is closed the whole day"},"open_hour":{"type":"integer","description":"Opening hour. Can be null if closed all day"},"open_minutes":{"type":"integer","description":"Opening minute. Can be null if closed all day"},"close_hour":{"type":"integer","description":"Closing hour. Can be null if closed all day"},"close_minutes":{"type":"integer","description":"Closing minute. Can be null if closed all day"}}}},"working_hours_enabled":{"type":"boolean","description":"Whether of not the working hours are enabled on the inbox"},"csat_survey_enabled":{"type":"boolean","description":"Whether of not the Customer Satisfaction survey is enabled on the inbox"},"greeting_enabled":{"type":"boolean","description":"Whether of not the Greeting Message is enabled on the inbox"},"identity_validation_enabled":{"type":"boolean","description":"Whether of not the User Identity Validation is enforced on the inbox"}}},"public_help_center_author":{"type":"object","description":"Public author representation emitted by the Help Center Jbuilder partial.","additionalProperties":false,"required":["available_name","name","thumbnail"],"properties":{"available_name":{"type":["string","null"],"description":"Public display name selected by the author."},"name":{"type":["string","null"],"description":"Account name of the article author."},"thumbnail":{"type":["string","null"],"format":"uri","description":"Avatar URL when the author has a public avatar; otherwise null."}}},"public_help_center_category_summary":{"type":"object","description":"Public category identity embedded in a public article. The public reader only emits this object for a category in the same portal and account whose visibility is public.","additionalProperties":false,"required":["id","slug","locale"],"properties":{"id":{"type":"integer","minimum":1},"slug":{"type":"string","minLength":1},"locale":{"type":"string","minLength":1}}},"public_help_center_category":{"type":"object","description":"A public Help Center category. Public portal routes return only categories whose visibility is public for the requested portal and locale.","additionalProperties":false,"required":["name","slug","locale","description","position","visibility","meta"],"properties":{"name":{"type":["string","null"]},"slug":{"type":"string","minLength":1},"locale":{"type":["string","null"]},"description":{"type":["string","null"]},"position":{"type":["integer","null"],"minimum":0},"visibility":{"type":"string","enum":["public"],"description":"Always public on this unauthenticated representation."},"meta":{"type":"object","additionalProperties":false,"required":["articles_count"],"properties":{"articles_count":{"type":"integer","minimum":0,"description":"Number of published public articles in this category and locale."}}}}},"public_help_center_portal":{"type":"object","description":"Public Help Center portal representation for one locale. Its categories and counters exclude operator-only and non-public articles.","additionalProperties":false,"required":["custom_domain","header_text","homepage_link","name","page_title","slug","categories","meta"],"properties":{"custom_domain":{"type":["string","null"]},"header_text":{"type":["string","null"]},"homepage_link":{"type":["string","null"],"format":"uri"},"name":{"type":["string","null"]},"page_title":{"type":["string","null"]},"slug":{"type":"string","minLength":1},"categories":{"type":"array","items":{"$ref":"#/components/schemas/public_help_center_category"}},"logo":{"$ref":"#/components/schemas/portal_logo"},"meta":{"type":"object","additionalProperties":false,"required":["articles_count","categories_count","default_locale"],"properties":{"articles_count":{"type":"integer","minimum":0},"categories_count":{"type":"integer","minimum":0},"default_locale":{"type":["string","null"]}}}}},"public_help_center_associated_article":{"type":"object","description":"Public associated article. Only published public associated articles whose category belongs to the same public portal are emitted.","additionalProperties":false,"required":["id","category_id","title","content","description","status","visibility","account_id","last_updated_at","views"],"properties":{"id":{"type":"integer","minimum":1},"category_id":{"type":"integer","minimum":1},"title":{"type":"string","minLength":1},"content":{"type":"string"},"description":{"type":["string","null"]},"status":{"type":"string","enum":["published"]},"visibility":{"type":"string","enum":["public"]},"account_id":{"type":"integer","minimum":1},"last_updated_at":{"type":"string","format":"date-time"},"views":{"type":["integer","null"],"minimum":0},"author":{"$ref":"#/components/schemas/public_help_center_author"}}},"public_help_center_article":{"type":"object","description":"Public Help Center article. The public reader emits only a published article with public visibility whose category is public and belongs to the same portal and account.","additionalProperties":false,"required":["id","category_id","title","content","description","status","visibility","position","account_id","last_updated_at","slug","portal","category","views","associated_articles","link"],"properties":{"id":{"type":"integer","minimum":1},"category_id":{"type":"integer","minimum":1},"title":{"type":"string","minLength":1},"content":{"type":"string"},"description":{"type":["string","null"]},"status":{"type":"string","enum":["published"]},"visibility":{"type":"string","enum":["public"]},"position":{"type":["integer","null"],"minimum":0},"account_id":{"type":"integer","minimum":1},"last_updated_at":{"type":"string","format":"date-time"},"slug":{"type":"string","minLength":1},"portal":{"$ref":"#/components/schemas/public_help_center_portal"},"category":{"$ref":"#/components/schemas/public_help_center_category_summary"},"views":{"type":["integer","null"],"minimum":0},"author":{"$ref":"#/components/schemas/public_help_center_author"},"associated_articles":{"type":"array","items":{"$ref":"#/components/schemas/public_help_center_associated_article"}},"link":{"type":"string","pattern":"^hc/[A-Za-z0-9_-]+/articles/[A-Za-z0-9._-]+$","description":"Relative public Help Center path without a leading slash."}}},"public_help_center_search_article":{"type":"object","description":"Compact public article search result. It is returned only when the article-list route receives a non-blank query; the underlying match is still published and public in a public category.","additionalProperties":false,"required":["id","category_id","title","content","link"],"properties":{"id":{"type":"integer","minimum":1},"category_id":{"type":"integer","minimum":1},"title":{"type":"string","minLength":1},"content":{"type":"string","description":"Plain-text excerpt of the public article, not its full Markdown content."},"link":{"type":"string","pattern":"^/hc/[A-Za-z0-9_-]+/articles/[A-Za-z0-9._-]+$"}}},"public_help_center_article_list_response":{"type":"object","description":"Public Help Center article-list response for a portal and locale.","additionalProperties":false,"required":["payload","meta"],"properties":{"payload":{"type":"array","description":"Full public article objects without a query, or compact public search-result objects when the query parameter is non-blank.","items":{"oneOf":[{"$ref":"#/components/schemas/public_help_center_article"},{"$ref":"#/components/schemas/public_help_center_search_article"}]}},"meta":{"type":"object","additionalProperties":false,"required":["articles_count"],"properties":{"articles_count":{"type":"integer","minimum":0,"description":"Number of matching public articles before pagination is applied."}}}}},"public_help_center_category_list_response":{"type":"object","description":"Public Help Center category-list response for a portal and locale.","additionalProperties":false,"required":["payload"],"properties":{"payload":{"type":"array","items":{"$ref":"#/components/schemas/public_help_center_category"}}}},"account_create_update_payload":{"type":"object","properties":{"name":{"type":"string","description":"Name of the account","example":"My Account"},"locale":{"type":"string","description":"The locale of the account","example":"en"},"domain":{"type":"string","description":"The domain of the account","example":"example.com"},"support_email":{"type":"string","description":"The support email of the account","example":"support@example.com"},"status":{"type":"string","enum":["active","suspended"],"description":"The status of the account","example":"active"},"features":{"type":"object","description":"Account features this Platform principal may change. Omitted keys preserve their current value; true enables and false disables only the supplied flag. Super-Admin-only flags are not accepted. Use JSON booleans; legacy 1/0 and true/false/on/off strings are normalized. Other values return 422 invalid_feature_values without changing the account.","additionalProperties":false,"example":{"campaigns":false,"help_center":true,"inbound_emails":true},"properties":{"account_brain":{"type":"boolean","description":"Enables the Account Brain feature."},"ads_conversion_tracking":{"type":"boolean","description":"Enables the Ad Conversion Tracking (Meta CAPI) feature."},"ads_manager":{"type":"boolean","description":"Enables the Ads Manager feature."},"advanced_assignment":{"type":"boolean","description":"Enables the Advanced Assignment feature."},"advanced_search":{"type":"boolean","description":"Enables the Advanced Search feature."},"advanced_search_indexing":{"type":"boolean","description":"Enables the Advanced Search Indexing feature."},"affiliate_program":{"type":"boolean","description":"Enables the Affiliate Program feature."},"agent_bots":{"type":"boolean","description":"Enables the Agent Bots feature."},"agent_management":{"type":"boolean","description":"Enables the Agent Management feature."},"ai_onboarding":{"type":"boolean","description":"Enables the AI Onboarding (Generative Setup) feature."},"api_and_webhooks":{"type":"boolean","description":"Enables the API and Webhooks feature."},"assignment_v2":{"type":"boolean","description":"Enables the Assignment V2 feature."},"audit_logs":{"type":"boolean","description":"Enables the Audit Logs feature."},"auto_resolve_conversations":{"type":"boolean","description":"Enables the Auto Resolve Conversations feature."},"automations":{"type":"boolean","description":"Enables the Automations feature."},"branded_email_templates":{"type":"boolean","description":"Enables the Branded Email Templates feature."},"bug_reports":{"type":"boolean","description":"Enables the Bug Reports feature."},"calendar":{"type":"boolean","description":"Enables the Calendar feature."},"campaign_batched_dispatch":{"type":"boolean","description":"Enables the Campaign Batched Dispatch feature."},"campaign_conversation_policy":{"type":"boolean","description":"Enables the Campaign Conversation Policy feature."},"campaigns":{"type":"boolean","description":"Enables the Campaigns feature."},"canned_responses":{"type":"boolean","description":"Enables the Canned Responses feature."},"captain_document_auto_sync":{"type":"boolean","description":"Enables the Captain Document Auto Sync feature."},"captain_integration":{"type":"boolean","description":"Enables the Captain feature."},"captain_integration_v2":{"type":"boolean","description":"Enables the Captain V2 feature."},"captain_tasks":{"type":"boolean","description":"Enables the Captain Tasks feature."},"captain_v1_action_classifier":{"type":"boolean","description":"Enables the Captain V1 Action Classifier feature."},"catalog":{"type":"boolean","description":"Enables the Product Catalog feature."},"channel_email":{"type":"boolean","description":"Enables the Email Channel feature."},"channel_facebook":{"type":"boolean","description":"Enables the Facebook Channel feature."},"channel_instagram":{"type":"boolean","description":"Enables the Instagram Channel feature."},"channel_tiktok":{"type":"boolean","description":"Enables the TikTok Channel feature."},"channel_voice":{"type":"boolean","description":"Enables the Voice Channel feature."},"channel_website":{"type":"boolean","description":"Enables the Website Channel feature."},"chatwoot_v4":{"type":"boolean","description":"Enables the Dashboard V4 feature."},"commerce_recovery":{"type":"boolean","description":"Enables the Commerce Recovery (Sales Recovery) feature."},"companies":{"type":"boolean","description":"Enables the Companies feature."},"contact_chatwoot_support_team":{"type":"boolean","description":"Enables the Contact support feature."},"contracts":{"type":"boolean","description":"Enables the Contracts \u0026 E-signature feature."},"conversation_glance_signals":{"type":"boolean","description":"Enables the Conversation Glance Signals feature."},"conversation_required_attributes":{"type":"boolean","description":"Enables the Required Conversation Attributes feature."},"conversation_unread_counts":{"type":"boolean","description":"Enables the Conversation Unread Counts feature."},"crm":{"type":"boolean","description":"Enables the CRM feature."},"crm_integration":{"type":"boolean","description":"Enables the CRM Integration feature."},"crm_pipelines":{"type":"boolean","description":"Enables the CRM Pipelines feature."},"crm_v2":{"type":"boolean","description":"Enables the CRM V2 feature."},"csat_review_notes":{"type":"boolean","description":"Enables the CSAT Review Notes feature."},"custom_attributes":{"type":"boolean","description":"Enables the Custom Attributes feature."},"custom_reply_domain":{"type":"boolean","description":"Enables the Custom Reply Domain feature."},"custom_reply_email":{"type":"boolean","description":"Enables the Custom Reply Email feature."},"custom_roles":{"type":"boolean","description":"Enables the Custom Roles feature."},"custom_tools":{"type":"boolean","description":"Enables the Custom Tools feature."},"data_import":{"type":"boolean","description":"Enables the Data Import feature."},"delayed_automations":{"type":"boolean","description":"Enables the Delayed Automations feature."},"disable_branding":{"type":"boolean","description":"Enables the Disable Branding feature. Deprecated flag, kept for backwards compatibility."},"email_continuity_on_api_channel":{"type":"boolean","description":"Enables the Email Continuity on API Channel feature."},"engagement_tracking":{"type":"boolean","description":"Enables the Engagement \u0026 Lead Score feature."},"field_level_permissions":{"type":"boolean","description":"Enables the Field-level Permissions feature."},"flow_builder":{"type":"boolean","description":"Enables the Flow Builder feature."},"flow_builder_runtime_v2":{"type":"boolean","description":"Enables the Flow Builder Runtime V2 feature."},"follow_ups":{"type":"boolean","description":"Enables the Follow-up feature."},"governance_lgpd":{"type":"boolean","description":"Enables the Governance \u0026 LGPD feature."},"granular_permissions":{"type":"boolean","description":"Enables the Granular Permissions feature."},"growth_ads":{"type":"boolean","description":"Enables the Growth Ads (CTWA \u0026 Lead Ads) feature."},"growth_social":{"type":"boolean","description":"Enables the Growth Social (Comment-to-DM) feature."},"growth_social_automation":{"type":"boolean","description":"Enables the Growth Social Automation (IG/TikTok/YouTube) feature."},"guided_tours":{"type":"boolean","description":"Enables the Guided Tours feature."},"help_center":{"type":"boolean","description":"Enables the Help Center feature."},"help_center_embedding_search":{"type":"boolean","description":"Enables the Help Center Embedding Search feature."},"inbound_emails":{"type":"boolean","description":"Enables the Inbound Emails feature."},"inbox_management":{"type":"boolean","description":"Enables the Inbox Management feature."},"inbox_view":{"type":"boolean","description":"Enables the Inbox View feature."},"integrations":{"type":"boolean","description":"Enables the Integrations feature."},"internal_chat":{"type":"boolean","description":"Enables the Internal Chat feature."},"ip_lookup":{"type":"boolean","description":"Enables the IP Lookup feature."},"labels":{"type":"boolean","description":"Enables the Labels feature."},"launch_group_distribution":{"type":"boolean","description":"Enables the Launch Group Distribution feature."},"linear_integration":{"type":"boolean","description":"Enables the Linear Integration feature."},"macros":{"type":"boolean","description":"Enables the Macros feature."},"maestro_byok":{"type":"boolean","description":"Enables the Maestro BYOK (Account LLM Keys) feature."},"maestro_global_keys":{"type":"boolean","description":"Enables the Maestro Installation LLM Keys (Global Fallback) feature."},"mcp":{"type":"boolean","description":"Enables the MCP (Model Context Protocol) feature."},"media_library":{"type":"boolean","description":"Enables the Media Library feature."},"message_reply_to":{"type":"boolean","description":"Enables the Message Reply To feature. Deprecated flag, kept for backwards compatibility."},"message_scheduling":{"type":"boolean","description":"Enables the Message Scheduling feature."},"native_advanced_search":{"type":"boolean","description":"Enables the Advanced Search (Native) feature."},"native_audit_trail":{"type":"boolean","description":"Enables the Audit Trail (Native) feature."},"native_event_pipeline_v2":{"type":"boolean","description":"Enables the Native Event Pipeline V2 feature."},"native_twilio_voice":{"type":"boolean","description":"Enables the Twilio Voice feature."},"notion_integration":{"type":"boolean","description":"Enables the Notion Integration feature."},"orders_registry":{"type":"boolean","description":"Enables the CRM Orders Registry feature."},"organizations":{"type":"boolean","description":"Enables the Organizations (Companies \u0026 Relationships) feature."},"outbound_agent_name_header":{"type":"boolean","description":"Enables the Outbound Agent Name Header feature."},"payment_installment_plans":{"type":"boolean","description":"Enables the Payment installment plans feature."},"payments":{"type":"boolean","description":"Enables the Payments feature."},"platform_governance":{"type":"boolean","description":"Enables the Platform Governance feature."},"realtime_translation":{"type":"boolean","description":"Enables the Realtime Translation feature."},"reply_mailer_migration":{"type":"boolean","description":"Enables the Reply Mailer Migration feature."},"report_rollup":{"type":"boolean","description":"Enables the Report Rollup feature."},"reports":{"type":"boolean","description":"Enables the Reports feature."},"sales_management":{"type":"boolean","description":"Enables the Sales Management feature."},"saml":{"type":"boolean","description":"Enables the SAML feature."},"search_with_gin":{"type":"boolean","description":"Enables the Search messages with GIN feature."},"session_analytics":{"type":"boolean","description":"Enables the Session Analytics feature."},"setup_blueprints":{"type":"boolean","description":"Enables the Setup Blueprints feature."},"shopify_integration":{"type":"boolean","description":"Enables the Shopify Integration feature."},"sla":{"type":"boolean","description":"Enables the SLA feature."},"smart_routing":{"type":"boolean","description":"Enables the Smart Routing feature."},"social_collaboration":{"type":"boolean","description":"Enables the Social Collaboration Network (Matrix) feature."},"tasks":{"type":"boolean","description":"Enables the Tasks feature."},"team_management":{"type":"boolean","description":"Enables the Team Management feature."},"unified_revenue_ledger":{"type":"boolean","description":"Enables the Unified Revenue Ledger feature."},"unread_count_for_filters":{"type":"boolean","description":"Enables the Unread Count For Filters feature."},"usage_metering":{"type":"boolean","description":"Enables the Usage Metering feature."},"voice_recorder":{"type":"boolean","description":"Enables the Voice Recorder feature."},"whatsapp_campaign":{"type":"boolean","description":"Enables the WhatsApp Campaign feature."},"whatsapp_cost_center":{"type":"boolean","description":"Enables the WhatsApp cost center feature."},"whatsapp_embedded_signup":{"type":"boolean","description":"Enables the WhatsApp Embedded Signup feature. Deprecated flag, kept for backwards compatibility."},"whatsapp_embedded_signup_inbox_creation":{"type":"boolean","description":"Enables the WhatsApp Embedded Signup Flow feature."},"whatsapp_hub":{"type":"boolean","description":"Enables the WhatsApp Hub feature."},"whatsapp_hybrid_inbox":{"type":"boolean","description":"Enables the WhatsApp Hybrid Inbox feature."},"whatsapp_hybrid_unified_inbox":{"type":"boolean","description":"Enables the WhatsApp Hybrid Unified Inbox feature."},"whatsapp_hybrid_weighted_routing":{"type":"boolean","description":"Enables the WhatsApp Hybrid Weighted Routing feature."},"whatsapp_inbox_suite":{"type":"boolean","description":"Enables the WhatsApp Inbox Suite feature."},"whatsapp_manual_transfer":{"type":"boolean","description":"Enables the WhatsApp Manual Transfer feature."},"whatsapp_mobile_egress":{"type":"boolean","description":"Enables the WhatsApp Web Mobile Connection feature."},"whatsapp_outbound_batching":{"type":"boolean","description":"Enables the WhatsApp Outbound Batching feature."},"whatsapp_outbound_maestro":{"type":"boolean","description":"Enables the WhatsApp Outbound Maestro Review feature."},"whatsapp_outbound_rich_transform":{"type":"boolean","description":"Enables the WhatsApp Outbound Rich Transform feature."},"whatsapp_reconfigure":{"type":"boolean","description":"Enables the WhatsApp Reconfigure feature."},"whatsapp_web_proxy":{"type":"boolean","description":"Enables the WhatsApp Web Global Proxy feature."},"white_label":{"type":"boolean","description":"Enables the White Label feature."},"workforce_management":{"type":"boolean","description":"Enables the Team Management feature."}},"x-example-sparse":"feature-mutation"},"limits":{"type":"object","description":"Per-account caps. The properties below are the COMPLETE set of dimensions accepted — any other key is rejected with 422 `invalid_limits`. Values are whole numbers of 0 or more; a numeric string (\"10\") is coerced. An OMITTED key means UNLIMITED (the installation default applies), and sending a key with a blank value removes it, which is the same thing. ZERO ALSO MEANS UNLIMITED, not \"allow none\" — every enforcement point treats a non-positive cap as absent, so omit a key (or blank it) to lift a cap and never send 0 to block a dimension. captain_responses, captain_documents and emails are only enforced on the Enterprise build; the `\u003cmetric\u003e_monthly` caps are the soft usage ceilings that drive the 80%/100% threshold events and the usage panel.","additionalProperties":false,"properties":{"agents":{"type":"integer","minimum":0,"description":"Maximum number of agents","example":10},"inboxes":{"type":"integer","minimum":0,"description":"Maximum number of inboxes","example":20},"media_storage_mb":{"type":"integer","minimum":0,"description":"Media Library storage quota in MB","example":2048},"captain_responses":{"type":"integer","minimum":0,"description":"Maximum Captain AI responses (enterprise build only)","example":1000},"captain_documents":{"type":"integer","minimum":0,"description":"Maximum Captain knowledge documents (enterprise build only)","example":100},"emails":{"type":"integer","minimum":0,"description":"Maximum outbound conversation emails (enterprise build only)","example":5000},"messages_monthly":{"type":"integer","minimum":0,"description":"Soft monthly cap on messages","example":50000},"conversations_monthly":{"type":"integer","minimum":0,"description":"Soft monthly cap on conversations","example":5000},"contacts_monthly":{"type":"integer","minimum":0,"description":"Soft monthly cap on new contacts","example":10000},"ai_requests_monthly":{"type":"integer","minimum":0,"description":"Soft monthly cap on AI requests","example":2000},"ai_tokens_monthly":{"type":"integer","minimum":0,"description":"Soft monthly cap on AI tokens","example":1000000}},"example":{"agents":10,"inboxes":20,"media_storage_mb":2048,"captain_responses":1000,"captain_documents":100,"emails":5000,"messages_monthly":50000,"conversations_monthly":5000,"contacts_monthly":10000,"ai_requests_monthly":2000,"ai_tokens_monthly":1000000}},"custom_attributes":{"type":"object","description":"The custom attributes of the account (free-form operator metadata, e.g. plan_name)","additionalProperties":true,"example":{"plan_name":"pro"}}}},"active_storage_direct_upload_payload":{"type":"object","additionalProperties":false,"required":["blob"],"properties":{"blob":{"type":"object","additionalProperties":false,"required":["filename","byte_size","checksum"],"properties":{"filename":{"type":"string","minLength":1,"description":"Original file name selected by the authenticated account member.","example":"attachment.pdf"},"byte_size":{"type":"integer","minimum":0,"description":"Exact number of bytes that will be uploaded to object storage.","example":20451},"checksum":{"type":"string","minLength":1,"description":"Base64-encoded MD5 checksum checked by the configured storage service.","example":"qLNbHUmZ6vC0FpHZjkQeBQ=="},"content_type":{"type":"string","description":"Declared IANA media type.","example":"application/pdf"},"metadata":{"type":"object","additionalProperties":true,"description":"Optional non-security metadata. Reserved `account_id` and `conversation_id` keys are ignored; the server stamps the authenticated account and, on conversation routes, the resolved thread.","example":{}}}}}},"account_update_payload":{"type":"object","properties":{"name":{"type":"string","description":"Name of the account","example":"My Account"},"locale":{"type":"string","description":"The locale of the account","example":"en"},"domain":{"type":"string","description":"The domain of the account","example":"example.com"},"support_email":{"type":"string","description":"The support email of the account","example":"support@example.com"},"auto_resolve_after":{"type":["integer","null"],"minimum":10,"maximum":1439856,"description":"Auto resolve conversations after specified minutes","example":1440},"auto_resolve_message":{"type":["string","null"],"description":"Message to send when auto resolving","example":"This conversation has been automatically resolved due to inactivity"},"auto_resolve_ignore_waiting":{"type":["boolean","null"],"description":"Legacy flag (no longer read) — waiting conversations are protected by default","example":false},"auto_resolve_allow_waiting":{"type":["boolean","null"],"description":"Explicit opt-out — also auto-resolve conversations still awaiting an agent reply","example":false},"outbound_agent_name_header_required":{"type":["boolean","null"],"description":"Account-administrator policy: whether every agent's outbound messages must be prefixed with their name. Requires the outbound_agent_name_header account feature to be enabled by the platform Super Admin — otherwise this setting has no effect.","example":false},"industry":{"type":"string","description":"Industry type","example":"Technology"},"company_size":{"type":"string","description":"Company size","example":"50-100"},"timezone":{"type":"string","description":"Canonical IANA timezone of the account. It is the authority for every business date/time on both paths: a naive datetime sent without a zone (e.g. \"2026-07-21T15:59\") is interpreted in this timezone rather than UTC, and dates rendered by the platform (dashboard, emails, PDFs, CSV exports) are shown in it. A datetime sent WITH an explicit zone (\"...Z\" or \"±HH:MM\") is always honored as given and never re-interpreted. Persisted to both the account settings and custom attributes; when unset, the account falls back to the onboarding timezone, then to the reporting timezone, then to UTC.","example":"America/Sao_Paulo"},"guided_tours":{"type":"object","additionalProperties":false,"description":"Account-wide guided-tour presentation settings.","properties":{"autoplay":{"type":"boolean","description":"Whether eligible unseen tours may start automatically for account users.","example":true},"reset":{"type":"boolean","writeOnly":true,"description":"When true, asks the server to stamp a new reset time. Earlier per-user tour progress is then treated as unseen without deleting the saved progress records.","example":true}}}}},"account_user_create_update_payload":{"type":"object","required":["user_id","role"],"properties":{"user_id":{"type":"integer","description":"The ID of the user","example":1},"role":{"type":"string","enum":["agent","administrator"],"description":"whether user is an administrator or agent","example":"administrator"}}},"platform_agent_bot_create_payload":{"type":"object","description":"Creates an account-bound bot. `account_id` is required and must identify an Account explicitly permissible to the calling PlatformApp; system-wide bots are never creatable through this provisioning API.","required":["account_id"],"properties":{"name":{"type":"string","description":"The name of the agent bot.","example":"Support relay"},"description":{"type":"string","description":"Optional description of the bot.","example":"Relays support events to the managed workflow."},"outgoing_url":{"type":"string","format":"uri","description":"Optional webhook URL for the bot.","example":"https://automation.example.com/chatwoot/events"},"account_id":{"type":"integer","minimum":1,"description":"Account to associate with the bot; it must be permissible to the caller.","example":7},"avatar":{"type":"string","format":"binary","description":"Avatar image binary when the request is sent as form data."},"avatar_url":{"type":"string","format":"uri","description":"URL from which the platform asynchronously fetches the bot avatar.","example":"https://example.com/assets/support-relay.png"},"receive_incoming_when_assigned":{"type":"boolean","default":false,"description":"Opt-in for a non-Maestro webhook bot to keep receiving incoming message events while a human agent owns the conversation. It applies to every linked inbox and does not authorize replies over the human agent.","example":false}}},"platform_agent_bot_update_payload":{"type":"object","description":"Updates an existing account-bound bot. If `account_id` is supplied it must remain an Account explicitly permissible to the PlatformApp; omitting it keeps the current account. Supplying a blank or null account is rejected because PlatformApps cannot create system bots.","properties":{"name":{"type":"string","description":"The name of the agent bot.","example":"Support relay"},"description":{"type":"string","description":"Optional description of the bot.","example":"Relays support events to the managed workflow."},"outgoing_url":{"type":"string","format":"uri","description":"Optional webhook URL for the bot.","example":"https://automation.example.com/chatwoot/events"},"account_id":{"type":"integer","minimum":1,"description":"Replacement account; it must be permissible to the caller.","example":7},"avatar":{"type":"string","format":"binary","description":"Avatar image binary when the request is sent as form data."},"avatar_url":{"type":"string","format":"uri","description":"URL from which the platform asynchronously fetches the bot avatar.","example":"https://example.com/assets/support-relay.png"},"receive_incoming_when_assigned":{"type":"boolean","description":"Opt-in for a non-Maestro webhook bot to keep receiving incoming message events while a human agent owns the conversation. Omit the field to preserve the current value. The setting applies to every linked inbox and does not authorize replies over the human agent.","example":true}}},"platform_user_create_payload":{"type":"object","description":"Creates a new managed PlatformApp identity. Passwords are generated internally and are never accepted from a PlatformApp; an already-existing email is accepted only when that user is already explicitly permissible to the same PlatformApp.","required":["name","email"],"properties":{"name":{"type":"string","description":"Full name of the new managed user.","example":"Ana Costa"},"display_name":{"type":"string","description":"Optional dashboard display name.","example":"Ana"},"email":{"type":"string","format":"email","description":"Email address for the new managed identity.","example":"ana@example.com"},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Optional application-defined attributes attached to the user.","example":{"department":"Support"}}}},"platform_user_update_payload":{"type":"object","description":"Updates non-credential presentation data for a managed user. `email` and `password` are intentionally unsupported and produce `422 platform_identity_credentials_are_not_mutable` when supplied.","properties":{"name":{"type":"string","description":"Full name of the managed user.","example":"Ana Costa"},"display_name":{"type":"string","description":"Optional dashboard display name.","example":"Ana"},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Application-defined attributes merged into the existing attribute map.","example":{"department":"Customer Success"}}}},"platform_email_channel_migration_create_payload":{"type":"object","description":"Bulk migration request for managed Google or Microsoft email channels. Each requested channel uses the provider-managed IMAP host, port 993 and TLS; a PlatformApp cannot choose a network destination for the mail worker.","required":["migrations"],"properties":{"migrations":{"type":"array","minItems":1,"maxItems":25,"description":"Up to 25 managed-provider email channels to create for the permissible account.","items":{"type":"object","additionalProperties":false,"required":["email","provider"],"properties":{"email":{"type":"string","format":"email","description":"Address of the mailbox to migrate.","example":"support@example.com"},"provider":{"type":"string","enum":["google","microsoft"],"description":"Managed OAuth mail provider.","example":"google"},"inbox_name":{"type":"string","description":"Optional name for the resulting inbox.","example":"Migrated Support"},"imap_enabled":{"type":"boolean","default":true,"description":"Whether the managed IMAP connection is enabled after creation.","example":true},"imap_login":{"type":"string","description":"Optional IMAP username; defaults to `email` when omitted.","example":"support@example.com"},"provider_config":{"type":"object","additionalProperties":true,"writeOnly":true,"description":"Provider OAuth configuration used to connect the mailbox. It is write-only and is never returned by this endpoint.","example":{"access_token":"sample-access-token","refresh_token":"sample-refresh-token","expires_on":"2026-09-01T12:00:00Z"}}}}}}},"agent_bot_create_update_payload":{"type":"object","properties":{"name":{"type":"string","description":"The name of the agent bot","example":"My Agent Bot"},"description":{"type":"string","description":"The description of the agent bot","example":"This is a sample agent bot"},"outgoing_url":{"type":"string","description":"The webhook URL for the bot","example":"https://example.com/webhook"},"avatar":{"type":"string","format":"binary","description":"Send the form data with the avatar image binary or use the avatar_url"},"avatar_url":{"type":"string","description":"The url to a jpeg, png file for the agent bot avatar","example":"https://example.com/avatar.png"},"bot_type":{"type":"integer","description":"The type of the bot (0 for webhook)","example":0},"bot_config":{"type":"object","additionalProperties":true,"description":"The extensible configuration for the bot (for example, pre-chat form fields). Use the typed `receive_incoming_when_assigned` property instead of placing that delivery option in this map.","example":{}},"receive_incoming_when_assigned":{"type":"boolean","default":false,"description":"Opt-in for a non-Maestro webhook bot to keep receiving incoming `message_created` and `message_updated` events while the conversation has a human assignee. It is disabled by default, applies to every inbox linked to the bot, and does not authorize the bot to reply over the human agent. When omitted from an update, the existing value is preserved.","example":false}}},"canned_response_create_update_payload":{"type":"object","properties":{"content":{"type":"string","description":"Message content for canned response","example":"Hello, {{contact.name}}! Welcome to our service."},"short_code":{"type":"string","description":"Short Code for quick access of the canned response","example":"welcome"},"visibility":{"type":"string","enum":["personal","global"],"description":"Who can find and use the canned response. Personal responses are visible only to their author; global responses are visible to every user in the account and can be published only by an administrator or a role with canned-response management permission. A non-manager request for global visibility is stored as personal.","example":"personal"},"content_attributes":{"type":"object","additionalProperties":true,"description":"Optional interactive Quick Reply payload authored by an agent. A free-form object whose top keys are one of: interactive (WhatsApp Cloud composer), wa_interactive (WhatsApp Web composer, any kind), poll (WhatsApp Web poll) or items (list/menu). The nested structure carries the buttons/sections/cards/options the reply-box composer reopens or re-sends. Unknown top keys are ignored on save.","example":{"wa_interactive":{"kind":"buttons","body":"Pick one","buttons":[{"id":"b1","text":"Yes","type":"quick_reply"},{"id":"b2","text":"No","type":"quick_reply"}]}}},"library_asset_ids":{"type":"array","description":"Account-scoped Media Library asset ids to attach without uploading the files again.","items":{"type":"integer"},"example":[21,34]},"removed_attachment_ids":{"type":"array","description":"Existing canned-response attachment ids to remove during an update.","items":{"type":"integer"},"example":[18]}}},"canned_response_create_payload":{"allOf":[{"$ref":"#/components/schemas/canned_response_create_update_payload"},{"required":["short_code"]}]},"canned_response_create_update_multipart_payload":{"allOf":[{"$ref":"#/components/schemas/canned_response_create_update_payload"},{"type":"object","properties":{"attachments":{"type":"array","description":"New files uploaded with the request, up to 10 files and 40 MB per file.","items":{"type":"string","format":"binary"}}}}]},"canned_response_create_multipart_payload":{"allOf":[{"$ref":"#/components/schemas/canned_response_create_payload"},{"type":"object","properties":{"attachments":{"type":"array","description":"New files uploaded with the request, up to 10 files and 40 MB per file.","items":{"type":"string","format":"binary"}}}}]},"custom_attribute_create_update_payload":{"type":"object","properties":{"attribute_display_name":{"type":"string","description":"Attribute display name","example":"Custom Attribute"},"attribute_display_type":{"type":"integer","description":"Attribute display type (text- 0, number- 1, currency- 2, percent- 3, link- 4, date- 5, list- 6, checkbox- 7)","example":0},"attribute_description":{"type":"string","description":"Attribute description","example":"This is a custom attribute"},"attribute_key":{"type":"string","description":"Attribute unique key value","example":"custom_attribute"},"attribute_values":{"type":"array","description":"Attribute values","items":{"type":"string"},"example":["value1","value2"]},"attribute_model":{"type":"integer","description":"Attribute type(conversation_attribute- 0, contact_attribute- 1)","example":0},"regex_pattern":{"type":"string","description":"Regex pattern (Only applicable for type- text). The regex pattern is used to validate the attribute value(s).","example":"^[a-zA-Z0-9]+$"},"regex_cue":{"type":"string","description":"Regex cue message (Only applicable for type- text). The cue message is shown when the regex pattern is not matched.","example":"Please enter a valid value"}}},"agent_create_payload":{"type":"object","required":["name","email","role"],"properties":{"name":{"type":"string","description":"Full Name of the agent","example":"John Doe"},"email":{"type":"string","description":"Email of the Agent","example":"john.doe@acme.inc"},"role":{"type":"string","enum":["agent","administrator"],"description":"Whether its administrator or agent","example":"agent"},"availability":{"type":"string","enum":["online","busy","offline"],"description":"The configured availability of the agent.","example":"online"},"auto_offline":{"type":"boolean","description":"Whether the agent is automatically marked offline when they are away.","example":true}}},"agent_update_payload":{"type":"object","required":["role"],"properties":{"role":{"type":"string","enum":["agent","administrator"],"description":"Whether its administrator or agent","example":"agent"},"outbound_agent_name_header_policy":{"type":"string","enum":["inherit","always","never"],"description":"The administrator's rule for this agent's name on outgoing messages. `inherit` follows the inbox and account rules, `always` shows the name on every message, `never` hides it. It takes precedence over the inbox and account rules and does not bind an administrator, who decides in their own profile. Only an administrator can set it; an empty value is stored as `inherit`.","example":"inherit"},"availability":{"type":"string","enum":["online","busy","offline"],"description":"The configured availability of the agent.","example":"online"},"auto_offline":{"type":"boolean","description":"Whether the agent is automatically marked offline when they are away.","example":true}}},"contact_create_payload":{"type":"object","required":["inbox_id"],"properties":{"inbox_id":{"type":"number","description":"ID of the inbox to which the contact belongs","example":1},"name":{"type":"string","description":"name of the contact","example":"Alice"},"email":{"type":"string","description":"email of the contact","example":"alice@acme.inc"},"blocked":{"type":"boolean","description":"whether the contact is blocked or not","example":false},"phone_number":{"type":"string","description":"phone number of the contact","example":"+123456789"},"avatar":{"type":"string","format":"binary","description":"Send the form data with the avatar image binary or use the avatar_url"},"avatar_url":{"type":"string","description":"The url to a jpeg, png file for the contact avatar","example":"https://example.com/avatar.png"},"identifier":{"type":"string","description":"A unique identifier for the contact in external system","example":"1234567890"},"additional_attributes":{"type":"object","description":"An object where you can store additional attributes for contact. example {\"type\":\"customer\", \"age\":30}","example":{"type":"customer","age":30},"additionalProperties":true},"custom_attributes":{"type":"object","description":"An object where you can store custom attributes for contact. example {\"type\":\"customer\", \"age\":30}, this should have a valid custom attribute definition.","example":{},"additionalProperties":true},"referred_by_affiliate_id":{"type":["integer","null"],"description":"Spec-078 — the affiliate that referred this contact. Requires the affiliate_program feature; the affiliate must belong to the same account, and a contact that IS an affiliate cannot refer itself (both are 422). Send null to clear the referral. A paid order from this contact inherits the credit unless the order names an affiliate of its own.","example":42}}},"contact_update_payload":{"type":"object","properties":{"name":{"type":"string","description":"name of the contact","example":"Alice"},"email":{"type":"string","description":"email of the contact","example":"alice@acme.inc"},"blocked":{"type":"boolean","description":"whether the contact is blocked or not","example":false},"phone_number":{"type":"string","description":"phone number of the contact","example":"+123456789"},"avatar":{"type":"string","format":"binary","description":"Send the form data with the avatar image binary or use the avatar_url"},"avatar_url":{"type":"string","description":"The url to a jpeg, png file for the contact avatar","example":"https://example.com/avatar.png"},"identifier":{"type":"string","description":"A unique identifier for the contact in external system","example":"1234567890"},"additional_attributes":{"type":"object","description":"An object where you can store additional attributes for contact. example {\"type\":\"customer\", \"age\":30}","example":{"type":"customer","age":30},"additionalProperties":true},"custom_attributes":{"type":"object","description":"An object where you can store custom attributes for contact. example {\"type\":\"customer\", \"age\":30}, this should have a valid custom attribute definition.","example":{},"additionalProperties":true},"referred_by_affiliate_id":{"type":["integer","null"],"description":"Spec-078 — the affiliate that referred this contact. Requires the affiliate_program feature; the affiliate must belong to the same account, and a contact that IS an affiliate cannot refer itself (both are 422). Send null to clear the referral. A paid order from this contact inherits the credit unless the order names an affiliate of its own.","example":42}}},"conversation_create_payload":{"type":"object","required":["source_id"],"properties":{"source_id":{"type":"string","description":"Conversation source id","example":"1234567890"},"inbox_id":{"type":"integer","description":"Id of inbox in which the conversation is created \u003cbr/\u003e Allowed Inbox Types: Website, Phone, Api, Email","example":1},"contact_id":{"type":"integer","description":"Contact Id for which conversation is created","example":1},"additional_attributes":{"type":"object","description":"Lets you specify attributes like browser information","example":{"browser":"Chrome","browser_version":"89.0.4389.82","os":"Windows","os_version":"10"},"additionalProperties":true},"custom_attributes":{"type":"object","description":"The object to save custom attributes for conversation, accepts custom attributes key and value","example":{"attribute_key":"attribute_value","priority_conversation_number":3},"additionalProperties":true},"status":{"type":"string","enum":["open","resolved","pending","snoozed"],"description":"Initial status of the conversation","example":"open"},"assignee_id":{"type":"integer","description":"Agent Id for assigning a conversation to an agent","example":1},"team_id":{"type":"integer","description":"Team Id for assigning a conversation to a team\\","example":1},"snoozed_until":{"type":"string","format":"date-time","description":"Snoozed until date time","example":"2030-07-21T17:32:28Z"},"message":{"type":"object","description":"The initial message to be sent to the conversation","required":["content"],"properties":{"content":{"type":"string","description":"The content of the message","example":"Hello, how can I help you?"},"template_params":{"type":"object","description":"The template params for the message in case of whatsapp Channel","properties":{"name":{"type":"string","description":"Name of the template","example":"sample_issue_resolution"},"category":{"type":"string","description":"Category of the template","example":"UTILITY"},"language":{"type":"string","description":"Language of the template","example":"en_US"},"processed_params":{"type":"object","additionalProperties":true,"description":"The processed param values for template variables, keyed by the variable position or name.","example":{"1":"Acme"}}}}}}}},"conversation_message_create_payload":{"type":"object","required":["content"],"properties":{"client_message_id":{"type":"string","minLength":1,"maxLength":128,"pattern":"^[a-zA-Z0-9_.:-]+$","description":"Optional durable identity generated once per deliberate send. Scoped to the authenticated author and account. Repeating the same request returns the existing message without another send; incompatible reuse returns 409 and a deleted message returns 410. Preserve this value after a lost response. Never deduplicate different deliberate sends by their text.","example":"2ca48246-20d5-4c17-a5e3-2b5c80c20875"},"echo_id":{"type":"string","description":"Transient UI correlation. Use client_message_id for durable deduplication."},"content":{"type":"string","description":"The content of the message","example":"Hello, how can I help you?"},"message_type":{"type":"string","enum":["outgoing","incoming"],"description":"The type of the message","example":"outgoing"},"private":{"type":"boolean","description":"Flag to identify if it is a private note","example":false},"content_type":{"type":"string","enum":["text","input_email","cards","input_select","form","article"],"description":"Content type of the message","example":"text"},"content_attributes":{"type":"object","description":"Attributes based on the content type. To ask a WhatsApp customer to share their phone number, send `{\"wa_interactive\": {\"kind\": \"contact_request\", \"body\": \"\u003ctext shown above the button, 1 to 1024 characters\u003e\"}}` in a one-to-one WhatsApp conversation: the official WhatsApp channel (Cloud API) sends Meta's native REQUEST_CONTACT_INFO interactive inside the 24-hour customer service window, and a WhatsApp Web inbox sends the WazMeow contact request. Outside the window, send an approved UTILITY or MARKETING template that has the REQUEST_CONTACT_INFO button instead.","example":{},"additionalProperties":true},"campaign_id":{"type":"integer","description":"The campaign id to which the message belongs","example":1},"template_params":{"type":"object","description":"WhatsApp template parameters for sending structured messages","required":["name","category","language","processed_params"],"properties":{"name":{"type":"string","description":"Name of the WhatsApp template (must be approved in WhatsApp Business Manager)","example":"purchase_receipt"},"category":{"type":"string","enum":["UTILITY","MARKETING","SHIPPING_UPDATE","TICKET_UPDATE","ISSUE_RESOLUTION"],"description":"Category of the template","example":"UTILITY"},"language":{"type":"string","description":"Language code of the template (BCP 47 format)","example":"en_US"},"content_mode":{"type":"string","enum":["raw_template","rendered"],"default":"rendered","description":"Format of the top-level `content` field. Existing clients may send rendered\ncontent or omit this field. Set this to `raw_template` only when `content`\ncontains the original template body placeholders.\n"},"processed_params":{"type":"object","description":"Processed template parameters organized by component type","properties":{"body":{"type":"object","description":"Body component parameters with variable placeholders","additionalProperties":{"type":"string"},"example":{"1":"Visa","2":"Nike","3":"Bill"}},"header":{"type":"object","description":"Header component parameters for media templates","properties":{"media_url":{"type":"string","format":"uri","description":"Publicly accessible URL for IMAGE, VIDEO, or DOCUMENT headers","example":"https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf"},"media_type":{"type":"string","enum":["image","video","document"],"description":"Type of media for the header","example":"document"}}},"buttons":{"type":"array","description":"Button component parameters for interactive templates","items":{"type":"object","properties":{"type":{"type":"string","enum":["url","copy_code"],"description":"Type of button parameter"},"parameter":{"type":"string","description":"Dynamic parameter value for the button","example":"SSFSDFSD"}}}}}}}}}},"inbox_create_payload":{"type":"object","properties":{"name":{"type":"string","description":"The name of the inbox.","example":"Support"},"avatar":{"type":"string","format":"binary","description":"Image file for avatar."},"greeting_enabled":{"type":"boolean","description":"Enable greeting message.","example":true},"greeting_message":{"type":"string","description":"Greeting message to send when greeting messages are enabled.","example":"Hello, how can I help you?"},"enable_email_collect":{"type":"boolean","description":"Enable email collection.\n\nAvailable for: `Website`\n","example":true},"csat_survey_enabled":{"type":"boolean","description":"Enable CSAT survey.","example":true},"csat_config":{"type":"object","description":"CSAT survey configuration.","properties":{"display_type":{"type":"string","description":"Display style for the CSAT survey.","enum":["emoji","star"],"example":"emoji"},"message":{"type":"string","description":"Message shown with the CSAT survey.","example":"Please rate your conversation"},"button_text":{"type":"string","description":"Text shown on the CSAT survey button.","example":"Please rate us"},"language":{"type":"string","description":"Language code for the CSAT survey.","example":"en"},"survey_rules":{"type":"object","description":"Rules that decide when to show the CSAT survey.","properties":{"operator":{"type":"string","example":"contains"},"values":{"type":"array","items":{"type":"string"},"example":["billing"]}}}}},"enable_auto_assignment":{"type":"boolean","description":"Enable Auto Assignment.","example":true},"working_hours_enabled":{"type":"boolean","description":"Enable working hours.","example":true},"out_of_office_message":{"type":"string","description":"Out of office message to send outside working hours.","example":"We are currently out of office. Please leave a message and we will get back to you."},"timezone":{"type":"string","description":"Timezone of the inbox.","example":"America/New_York"},"allow_messages_after_resolved":{"type":"boolean","description":"Allow messages after conversation is resolved.\n\nAvailable for: `Website`\n","example":true},"lock_to_single_conversation":{"type":"boolean","description":"Lock contact messages to a single active conversation.\n\nAvailable for: `API` `LINE` `Telegram` `WhatsApp` `SMS`\n","example":true},"portal_id":{"type":"integer","description":"Id of the help center portal to attach to the inbox.","example":1},"sender_name_type":{"type":"string","description":"Sender name type for outbound email replies.\n\nAvailable for: `Website` `Email`\n","enum":["friendly","professional"],"example":"friendly"},"business_name":{"type":"string","description":"Business name for outbound email replies.\n\nAvailable for: `Website` `Email`\n","example":"My Business"},"channel":{"oneOf":[{"$ref":"#/components/schemas/inbox_create_web_widget_channel_payload"},{"$ref":"#/components/schemas/inbox_create_api_channel_payload"},{"$ref":"#/components/schemas/inbox_create_email_channel_payload"},{"$ref":"#/components/schemas/inbox_create_line_channel_payload"},{"$ref":"#/components/schemas/inbox_create_telegram_channel_payload"},{"$ref":"#/components/schemas/inbox_create_whatsapp_channel_payload"},{"$ref":"#/components/schemas/inbox_create_sms_channel_payload"}],"discriminator":{"propertyName":"type","mapping":{"web_widget":"#/components/schemas/inbox_create_web_widget_channel_payload","api":"#/components/schemas/inbox_create_api_channel_payload","email":"#/components/schemas/inbox_create_email_channel_payload","line":"#/components/schemas/inbox_create_line_channel_payload","telegram":"#/components/schemas/inbox_create_telegram_channel_payload","whatsapp":"#/components/schemas/inbox_create_whatsapp_channel_payload","sms":"#/components/schemas/inbox_create_sms_channel_payload"}}}}},"inbox_update_payload":{"type":"object","properties":{"name":{"type":"string","description":"The name of the inbox.","example":"Support"},"avatar":{"type":"string","format":"binary","description":"Image file for avatar."},"greeting_enabled":{"type":"boolean","description":"Enable greeting message.","example":true},"greeting_message":{"type":"string","description":"Greeting message to send when greeting messages are enabled.","example":"Hello, how can I help you?"},"enable_email_collect":{"type":"boolean","description":"Enable email collection.\n\nAvailable for: `Website`\n","example":true},"csat_survey_enabled":{"type":"boolean","description":"Enable CSAT survey.","example":true},"csat_config":{"type":"object","description":"CSAT survey configuration.","properties":{"display_type":{"type":"string","description":"Display style for the CSAT survey.","enum":["emoji","star"],"example":"emoji"},"message":{"type":"string","description":"Message shown with the CSAT survey.","example":"Please rate your conversation"},"button_text":{"type":"string","description":"Text shown on the CSAT survey button.","example":"Please rate us"},"language":{"type":"string","description":"Language code for the CSAT survey.","example":"en"},"survey_rules":{"type":"object","description":"Rules that decide when to show the CSAT survey.","properties":{"operator":{"type":"string","example":"contains"},"values":{"type":"array","items":{"type":"string"},"example":["billing"]}}}}},"enable_auto_assignment":{"type":"boolean","description":"Enable Auto Assignment.","example":true},"working_hours_enabled":{"type":"boolean","description":"Enable working hours.","example":true},"out_of_office_message":{"type":"string","description":"Out of office message to send outside working hours.","example":"We are currently out of office. Please leave a message and we will get back to you."},"timezone":{"type":"string","description":"Timezone of the inbox.","example":"America/New_York"},"allow_messages_after_resolved":{"type":"boolean","description":"Allow messages after conversation is resolved.\n\nAvailable for: `Website`\n","example":true},"lock_to_single_conversation":{"type":"boolean","description":"Lock contact messages to a single active conversation.\n\nAvailable for: `API` `LINE` `Telegram` `WhatsApp` `SMS`\n","example":true},"portal_id":{"type":"integer","description":"Id of the help center portal to attach to the inbox.","example":1},"sender_name_type":{"type":"string","description":"Sender name type for outbound email replies.\n\nAvailable for: `Website` `Email`\n","enum":["friendly","professional"],"example":"friendly"},"auto_resolve_config":{"type":"object","additionalProperties":false,"if":{"properties":{"mode":{"const":"custom"}},"required":["mode"]},"then":{"required":["after"]},"description":"Per-inbox override of the account inactivity auto-resolve rule. An empty object means the inbox inherits the account rule. With `mode: custom` the inbox owns a complete rule (the account message, label and waiting preference are not mixed in) and it applies even when the account has no rule. With `mode: disabled` conversations of this inbox are never auto-resolved.","properties":{"mode":{"type":"string","enum":["inherit","custom","disabled"],"description":"How the inbox relates to the account rule. Absent means `inherit`."},"after":{"type":"integer","minimum":10,"maximum":1439856,"description":"Minutes of inactivity after which an open conversation is resolved. Required and read only when `mode` is `custom`."},"message":{"type":["string","null"],"maxLength":10000,"description":"Message sent to the contact when the conversation is auto-resolved. Read only when `mode` is `custom`."},"label":{"type":["string","null"],"description":"Title of the label added after auto-resolution. Read only when `mode` is `custom`."},"allow_waiting":{"type":"boolean","description":"Whether conversations still waiting for an agent reply are resolved too. Read only when `mode` is `custom`."}},"example":{"mode":"custom","after":30,"message":"We are closing this conversation due to inactivity.","label":"auto-resolved","allow_waiting":false}},"outbound_agent_name_header_policy":{"type":"string","enum":["inherit","required","optional"],"description":"Per-inbox override of the account policy that makes the agent name header mandatory on outbound messages. `inherit` follows the account, `required` forces the header in this inbox, `optional` leaves the choice to each agent in this inbox.","example":"inherit"},"business_name":{"type":"string","description":"Business name for outbound email replies.\n\nAvailable for: `Website` `Email`\n","example":"My Business"},"branded_email_layout":{"type":["string","null"],"maxLength":262144,"description":"Liquid HTML layout for outbound email replies. Must include `{{ content_for_layout }}` and be 262,144 characters or shorter.\n\nAvailable for: `Email`\n","example":"\u003chtml\u003e\u003cbody\u003e{{ content_for_layout }}\u003c/body\u003e\u003c/html\u003e"},"channel":{"anyOf":[{"$ref":"#/components/schemas/inbox_update_web_widget_channel_payload"},{"$ref":"#/components/schemas/inbox_update_api_channel_payload"},{"$ref":"#/components/schemas/inbox_update_email_channel_payload"},{"$ref":"#/components/schemas/inbox_update_line_channel_payload"},{"$ref":"#/components/schemas/inbox_update_telegram_channel_payload"},{"$ref":"#/components/schemas/inbox_update_whatsapp_channel_payload"},{"$ref":"#/components/schemas/inbox_update_sms_channel_payload"}]}}},"account_branded_email_layout_payload":{"type":"object","properties":{"inbox_id":{"type":["integer","null"],"minimum":1,"description":"Optional authorized email inbox in this account; omit or null to edit the account override.","example":7},"branded_email_layout":{"type":["string","null"],"maxLength":262144,"description":"Base Liquid HTML email layout. Maximum 262,144 characters. Blank or null removes only the selected scope override. An omitted field preserves its saved value.","example":"\u003chtml\u003e\u003cbody\u003e{{ content_for_layout }}\u003c/body\u003e\u003c/html\u003e"}}},"inbox_create_web_widget_channel_payload":{"type":"object","title":"Website channel","required":["type","website_url"],"properties":{"type":{"type":"string","enum":["web_widget"],"example":"web_widget"},"website_url":{"type":"string","description":"URL at which the widget will be loaded","example":"https://example.com"},"welcome_title":{"type":"string","description":"Welcome title to be displayed on the widget","example":"Welcome to our support"},"welcome_tagline":{"type":"string","description":"Welcome tagline to be displayed on the widget","example":"We are here to help you"},"widget_color":{"type":"string","description":"A Hex-color string used to customize the widget","example":"#FF5733"},"reply_time":{"type":"string","description":"Expected reply time shown on the widget","enum":["in_a_few_minutes","in_a_few_hours","in_a_day"],"example":"in_a_few_minutes"},"pre_chat_form_enabled":{"type":"boolean","description":"Enable the pre-chat form before starting a conversation","example":false},"pre_chat_form_options":{"type":"object","additionalProperties":true,"description":"Pre-chat form configuration (a pre_chat_message string and a pre_chat_fields array describing each requested field)","example":{"pre_chat_message":"Share your queries or comments here.","pre_chat_fields":[{"field_type":"standard","label":"Email Id","name":"emailAddress","type":"email","required":true,"enabled":true}]}},"continuity_via_email":{"type":"boolean","description":"Continue conversations over email when the contact leaves the website","example":true},"hmac_mandatory":{"type":"boolean","description":"Require HMAC verification for contacts using the widget","example":false},"allowed_domains":{"type":"string","description":"Comma-separated list of domains where the widget is allowed to load","example":"example.com"},"selected_feature_flags":{"type":"array","description":"Enabled widget feature flags","items":{"type":"string","enum":["attachments","emoji_picker","end_conversation","use_inbox_avatar_for_bot","allow_mobile_webview"]},"example":["attachments","emoji_picker","end_conversation"]}}},"inbox_create_api_channel_payload":{"type":"object","title":"API channel","required":["type"],"properties":{"type":{"type":"string","enum":["api"],"example":"api"},"webhook_url":{"type":"string","description":"Webhook URL for API channel inbox callbacks","example":"https://example.com/webhook"},"hmac_mandatory":{"type":"boolean","description":"Require HMAC verification for incoming API channel messages","example":false},"additional_attributes":{"type":"object","description":"Additional attributes stored on contacts created through the API channel","example":{"source":"mobile_app"},"additionalProperties":true}}},"inbox_create_email_channel_payload":{"type":"object","title":"Email channel","required":["type","email"],"properties":{"type":{"type":"string","enum":["email"],"example":"email"},"email":{"type":"string","description":"Email address for the inbox","example":"support@example.com"},"imap_enabled":{"type":"boolean","description":"Enable IMAP for inbound emails","example":true},"imap_login":{"type":"string","description":"IMAP login username","example":"support@example.com"},"imap_password":{"type":"string","description":"IMAP login password","example":"your-imap-password"},"imap_address":{"type":"string","description":"IMAP server address","example":"imap.example.com"},"imap_port":{"type":"integer","description":"IMAP server port","example":993},"imap_enable_ssl":{"type":"boolean","description":"Enable SSL for IMAP","example":true},"imap_authentication":{"type":"string","description":"IMAP authentication method","example":"plain"},"smtp_enabled":{"type":"boolean","description":"Enable SMTP for outbound emails","example":true},"smtp_login":{"type":"string","description":"SMTP login username","example":"support@example.com"},"smtp_password":{"type":"string","description":"SMTP login password","example":"your-smtp-password"},"smtp_address":{"type":"string","description":"SMTP server address","example":"smtp.example.com"},"smtp_port":{"type":"integer","description":"SMTP server port","example":587},"smtp_domain":{"type":"string","description":"SMTP HELO domain","example":"example.com"},"smtp_enable_starttls_auto":{"type":"boolean","description":"Automatically enable STARTTLS for SMTP","example":true},"smtp_enable_ssl_tls":{"type":"boolean","description":"Enable SSL/TLS for SMTP","example":false},"smtp_openssl_verify_mode":{"type":"string","enum":["none","peer","client_once","fail_if_no_peer_cert"],"description":"OpenSSL certificate verification mode for SMTP","example":"none"},"smtp_authentication":{"type":"string","description":"SMTP authentication method","example":"login"},"provider":{"type":"string","enum":["google","microsoft"],"description":"Email provider used for the mailbox","example":"google"},"verified_for_sending":{"type":"boolean","description":"Whether the inbox is verified for sending emails","example":false}}},"inbox_create_line_channel_payload":{"type":"object","title":"LINE channel","required":["type","line_channel_id","line_channel_secret","line_channel_token"],"properties":{"type":{"type":"string","enum":["line"],"example":"line"},"line_channel_id":{"type":"string","description":"LINE channel ID","example":"1234567890"},"line_channel_secret":{"type":"string","description":"LINE channel secret","example":"line-channel-secret"},"line_channel_token":{"type":"string","description":"LINE channel access token","example":"line-channel-token"}}},"inbox_create_telegram_channel_payload":{"type":"object","title":"Telegram channel","required":["type","bot_token"],"properties":{"type":{"type":"string","enum":["telegram"],"example":"telegram"},"bot_token":{"type":"string","description":"Telegram bot token","example":"123456789:telegram-bot-token"}}},"inbox_create_whatsapp_channel_payload":{"oneOf":[{"type":"object","title":"WhatsApp Cloud channel","required":["type","phone_number","provider","provider_config"],"properties":{"type":{"type":"string","enum":["whatsapp"],"example":"whatsapp"},"phone_number":{"type":"string","description":"WhatsApp phone number","example":"+15551234567"},"provider":{"type":"string","description":"WhatsApp provider","enum":["whatsapp_cloud"],"example":"whatsapp_cloud"},"provider_config":{"type":"object","description":"WhatsApp Cloud provider configuration","required":["api_key","phone_number_id","business_account_id"],"properties":{"api_key":{"type":"string","description":"WhatsApp Cloud API key","example":"your-api-key"},"phone_number_id":{"type":"string","description":"Phone number ID for WhatsApp Cloud","example":"your-phone-number-id"},"business_account_id":{"type":"string","description":"Business account ID for WhatsApp Cloud","example":"your-business-account-id"},"app_secret":{"type":"string","writeOnly":true,"description":"Optional App Secret of the Meta app that owns the access token. With it, the signature of every webhook from that app is verified, and the platform subscribes the app's WhatsApp webhook to this installation when the app has no callback yet (an app whose callback points to another host is never changed). Never returned: responses expose only `has_app_secret`.","example":"your-meta-app-secret"}},"example":{"api_key":"your-api-key","phone_number_id":"your-phone-number-id","business_account_id":"your-business-account-id","app_secret":"your-meta-app-secret"}}}},{"type":"object","title":"Legacy 360dialog WhatsApp channel","deprecated":true,"required":["type","phone_number","provider_config"],"properties":{"type":{"type":"string","enum":["whatsapp"],"example":"whatsapp"},"phone_number":{"type":"string","description":"WhatsApp phone number","example":"+15551234567"},"provider":{"type":"string","description":"Legacy 360dialog provider. Omit this field or use `default` only for existing deprecated 360dialog setups.","enum":["default"],"deprecated":true,"example":"default"},"provider_config":{"type":"object","description":"Legacy 360dialog provider configuration","required":["api_key"],"properties":{"api_key":{"type":"string","description":"360dialog API key","example":"your-api-key"}},"example":{"api_key":"your-api-key"}}}}]},"inbox_create_sms_channel_payload":{"type":"object","title":"SMS channel","required":["type","phone_number","provider_config"],"properties":{"type":{"type":"string","enum":["sms"],"example":"sms"},"phone_number":{"type":"string","description":"SMS phone number","example":"+15551234567"},"provider_config":{"type":"object","additionalProperties":false,"required":["account_id","application_id"],"description":"Complete Bandwidth configuration. account_id is exactly seven digits and application_id is the canonical UUID assigned to a Bandwidth Messaging Application. Supply exactly one credential pair: OAuth2 client_id/client_secret or legacy Basic api_key/api_secret. Callback credentials are generated by the server, encrypted at rest, and are never accepted here.","properties":{"account_id":{"type":"string","pattern":"^[0-9]{7}$","example":"1234567"},"application_id":{"type":"string","format":"uuid","pattern":"^[0-9A-Fa-f]{8}-(?:[0-9A-Fa-f]{4}-){3}[0-9A-Fa-f]{12}$","example":"e5a9e103-097e-4ec4-87a0-50109fb7b4b1"},"client_id":{"type":"string","minLength":1,"example":"bandwidth-client-123"},"client_secret":{"type":"string","minLength":1,"format":"password","example":"replace-with-client-secret"},"api_key":{"type":"string","minLength":1,"example":"sample-api-key"},"api_secret":{"type":"string","minLength":1,"format":"password","example":"replace-with-api-secret"}},"oneOf":[{"required":["client_id","client_secret"]},{"required":["api_key","api_secret"]}],"example":{"account_id":"1234567","application_id":"e5a9e103-097e-4ec4-87a0-50109fb7b4b1","client_id":"bandwidth-client-123","client_secret":"replace-with-client-secret"}}}},"inbox_update_web_widget_channel_payload":{"type":"object","title":"Website channel settings","properties":{"website_url":{"type":"string","description":"URL at which the widget will be loaded","example":"https://example.com"},"welcome_title":{"type":"string","description":"Welcome title to be displayed on the widget","example":"Welcome to our support"},"welcome_tagline":{"type":"string","description":"Welcome tagline to be displayed on the widget","example":"We are here to help you"},"widget_color":{"type":"string","description":"A Hex-color string used to customize the widget","example":"#FF5733"},"reply_time":{"type":"string","description":"Expected reply time shown on the widget","enum":["in_a_few_minutes","in_a_few_hours","in_a_day"],"example":"in_a_few_minutes"},"pre_chat_form_enabled":{"type":"boolean","description":"Enable the pre-chat form before starting a conversation","example":false},"pre_chat_form_options":{"type":"object","additionalProperties":true,"description":"Pre-chat form configuration (a pre_chat_message string and a pre_chat_fields array describing each requested field)","example":{"pre_chat_message":"Share your queries or comments here.","pre_chat_fields":[{"field_type":"standard","label":"Email Id","name":"emailAddress","type":"email","required":true,"enabled":true}]}},"continuity_via_email":{"type":"boolean","description":"Continue conversations over email when the contact leaves the website","example":true},"hmac_mandatory":{"type":"boolean","description":"Require HMAC verification for contacts using the widget","example":false},"allowed_domains":{"type":"string","description":"Comma-separated list of domains where the widget is allowed to load","example":"example.com"},"selected_feature_flags":{"type":"array","description":"Enabled widget feature flags","items":{"type":"string","enum":["attachments","emoji_picker","end_conversation","use_inbox_avatar_for_bot","allow_mobile_webview"]},"example":["attachments","emoji_picker","end_conversation"]}}},"inbox_update_api_channel_payload":{"type":"object","title":"API channel settings","properties":{"webhook_url":{"type":"string","description":"Webhook URL for API channel inbox callbacks","example":"https://example.com/webhook"},"hmac_mandatory":{"type":"boolean","description":"Require HMAC verification for incoming API channel messages","example":false},"additional_attributes":{"type":"object","description":"Additional attributes stored on contacts created through the API channel","example":{"source":"mobile_app"},"additionalProperties":true}}},"inbox_update_email_channel_payload":{"type":"object","title":"Email channel settings","properties":{"email":{"type":"string","description":"Email address for the inbox","example":"support@example.com"},"imap_enabled":{"type":"boolean","description":"Enable IMAP for inbound emails","example":true},"imap_login":{"type":"string","description":"IMAP login username","example":"support@example.com"},"imap_password":{"type":"string","description":"IMAP login password","example":"your-imap-password"},"imap_address":{"type":"string","description":"IMAP server address","example":"imap.example.com"},"imap_port":{"type":"integer","description":"IMAP server port","example":993},"imap_enable_ssl":{"type":"boolean","description":"Enable SSL for IMAP","example":true},"imap_authentication":{"type":"string","description":"IMAP authentication method","example":"plain"},"smtp_enabled":{"type":"boolean","description":"Enable SMTP for outbound emails","example":true},"smtp_login":{"type":"string","description":"SMTP login username","example":"support@example.com"},"smtp_password":{"type":"string","description":"SMTP login password","example":"your-smtp-password"},"smtp_address":{"type":"string","description":"SMTP server address","example":"smtp.example.com"},"smtp_port":{"type":"integer","description":"SMTP server port","example":587},"smtp_domain":{"type":"string","description":"SMTP HELO domain","example":"example.com"},"smtp_enable_starttls_auto":{"type":"boolean","description":"Automatically enable STARTTLS for SMTP","example":true},"smtp_enable_ssl_tls":{"type":"boolean","description":"Enable SSL/TLS for SMTP","example":false},"smtp_openssl_verify_mode":{"type":"string","enum":["none","peer","client_once","fail_if_no_peer_cert"],"description":"OpenSSL certificate verification mode for SMTP","example":"none"},"smtp_authentication":{"type":"string","description":"SMTP authentication method","example":"login"},"provider":{"type":"string","enum":["google","microsoft"],"description":"Email provider used for the mailbox","example":"google"},"verified_for_sending":{"type":"boolean","description":"Whether the inbox is verified for sending emails","example":false}}},"inbox_update_line_channel_payload":{"type":"object","title":"LINE channel settings","properties":{"line_channel_id":{"type":"string","description":"LINE channel ID","example":"1234567890"},"line_channel_secret":{"type":"string","description":"LINE channel secret","example":"line-channel-secret"},"line_channel_token":{"type":"string","description":"LINE channel access token","example":"line-channel-token"}}},"inbox_update_telegram_channel_payload":{"type":"object","title":"Telegram channel settings","properties":{"bot_token":{"type":"string","description":"Telegram bot token","example":"123456789:telegram-bot-token"}}},"inbox_update_whatsapp_channel_payload":{"type":"object","title":"WhatsApp channel settings","properties":{"phone_number":{"type":"string","description":"WhatsApp phone number","example":"+15551234567"},"provider":{"type":"string","description":"WhatsApp provider. `default` is supported only for existing deprecated 360dialog setups.","enum":["whatsapp_cloud","default"],"example":"whatsapp_cloud"},"provider_config":{"type":"object","description":"WhatsApp provider configuration. Cloud channels use `api_key`, `phone_number_id`, and `business_account_id`; legacy 360dialog channels use `api_key`.","properties":{"api_key":{"type":"string","description":"Provider API key","example":"your-api-key"},"phone_number_id":{"type":"string","description":"Phone number ID for WhatsApp Cloud","example":"your-phone-number-id"},"business_account_id":{"type":"string","description":"Business account ID for WhatsApp Cloud","example":"your-business-account-id"},"app_secret":{"type":"string","writeOnly":true,"description":"Optional App Secret of the Meta app that owns the Cloud access token (verifies webhook signatures and lets the platform subscribe the app's WhatsApp webhook when it has none). Omit it to keep the stored value; an empty string clears it. Never returned: responses expose only `has_app_secret`.","example":"your-meta-app-secret"}},"example":{"api_key":"your-api-key","phone_number_id":"your-phone-number-id","business_account_id":"your-business-account-id","app_secret":"your-meta-app-secret"}}}},"inbox_update_sms_channel_payload":{"type":"object","title":"SMS channel settings","properties":{"phone_number":{"type":"string","description":"SMS phone number","example":"+15551234567"},"provider_config":{"type":"object","additionalProperties":false,"required":["account_id","application_id"],"description":"Complete replacement configuration for Bandwidth. account_id is exactly seven digits, application_id is the canonical UUID assigned to a Messaging Application, and exactly one complete OAuth2 or legacy Basic credential pair is required. Callback credentials are server-generated, encrypted at rest, and cannot be supplied or retrieved here.","properties":{"account_id":{"type":"string","pattern":"^[0-9]{7}$","example":"1234567"},"application_id":{"type":"string","format":"uuid","pattern":"^[0-9A-Fa-f]{8}-(?:[0-9A-Fa-f]{4}-){3}[0-9A-Fa-f]{12}$","example":"e5a9e103-097e-4ec4-87a0-50109fb7b4b1"},"client_id":{"type":"string","minLength":1,"example":"bandwidth-client-123"},"client_secret":{"type":"string","minLength":1,"format":"password","example":"replace-with-client-secret"},"api_key":{"type":"string","minLength":1,"example":"sample-api-key"},"api_secret":{"type":"string","minLength":1,"format":"password","example":"replace-with-api-secret"}},"oneOf":[{"required":["client_id","client_secret"]},{"required":["api_key","api_secret"]}],"example":{"account_id":"1234567","application_id":"e5a9e103-097e-4ec4-87a0-50109fb7b4b1","client_id":"bandwidth-client-123","client_secret":"replace-with-client-secret"}}}},"team_create_update_payload":{"type":"object","properties":{"name":{"type":"string","description":"The name of the team","example":"Support Team"},"description":{"type":"string","description":"The description of the team","example":"This is a team of support agents"},"allow_auto_assign":{"type":"boolean","description":"If this setting is turned on, the system would automatically assign the conversation to an agent in the team while assigning the conversation to a team","example":true},"remove_avatar":{"type":"boolean","description":"Set to true when updating a team to remove its current icon and return to generated initials","example":false}}},"team_create_update_multipart_payload":{"type":"object","properties":{"name":{"type":"string","description":"The name of the team","example":"Support Team"},"description":{"type":"string","description":"The description of the team","example":"This is a team of support agents"},"allow_auto_assign":{"type":"boolean","description":"If enabled, the system can automatically assign team conversations to an available member","example":true},"avatar":{"type":"string","format":"binary","description":"Team icon image. JPEG, PNG, GIF, and WebP files up to 15 MB are accepted."},"remove_avatar":{"type":"boolean","description":"Set to true when updating a team to remove its current icon and return to generated initials","example":false}}},"label_create_update_payload":{"type":"object","properties":{"title":{"type":"string","description":"The label title","example":"support"},"description":{"type":"string","description":"A short description for the label","example":"Conversations that need support follow-up"},"color":{"type":"string","description":"Hex color code for the label","example":"#1f93ff"},"show_on_sidebar":{"type":"boolean","description":"Whether the label should appear in the sidebar","example":true}}},"internal_chat_member":{"type":"object","additionalProperties":false,"description":"A channel membership together with the account user represented by that membership.","required":["id","channel_id","user_id","role","notification_level","muted_until","muted","pinned","archived","last_read_at","user"],"properties":{"id":{"type":"integer","description":"Unique membership identifier.","example":61},"channel_id":{"type":"integer","description":"Channel that owns this membership.","example":30},"user_id":{"type":"integer","description":"Account user represented by this membership.","example":7},"role":{"type":"string","enum":["member","admin","owner"],"description":"Permission role inside the channel.","example":"owner"},"notification_level":{"type":"string","enum":["all","mentions","none"],"description":"Notifications this member receives while the membership is not muted.","example":"all"},"muted_until":{"type":["string","null"],"format":"date-time","description":"Instant until which notifications are muted, or null when no mute is scheduled.","example":null},"muted":{"type":"boolean","description":"Whether muted_until is currently in the future.","example":false},"pinned":{"type":"boolean","description":"Whether this member pinned the channel in their own list.","example":true},"archived":{"type":"boolean","description":"Whether this member archived the channel in their own list.","example":false},"last_read_at":{"type":["string","null"],"format":"date-time","description":"Timestamp of this member's latest read marker, or null before the first read.","example":"2026-08-24T17:45:00Z"},"user":{"type":"object","additionalProperties":false,"description":"Account user represented by this membership.","required":["id","name","thumbnail","availability_status"],"properties":{"id":{"type":"integer","example":7},"name":{"type":"string","example":"Jane Agent"},"thumbnail":{"type":"string","description":"Avatar URL, or an empty string when the user has no avatar.","example":"https://cdn.example.com/avatars/7.png"},"availability_status":{"type":"string","enum":["online","offline","busy"],"example":"online","description":"Realtime availability. Contacts report online/offline (presence-based); agents/users additionally report busy (their configured availability)."}}}}},"internal_chat_member_list_response":{"type":"object","additionalProperties":false,"description":"Canonical response envelope for the current members of one internal-chat channel.","required":["payload"],"properties":{"payload":{"type":"array","description":"Complete current membership list after the requested operation.","items":{"$ref":"#/components/schemas/internal_chat_member"}}}},"internal_chat_channel_list_item":{"type":"object","additionalProperties":false,"description":"One internal-chat channel row rendered in the active or archived channel list.","required":["id","kind","name","slug","description","topic","visibility","posting_policy","team_id","created_by_id","allowed_poster_ids","avatar_url","avatar_icon","avatar_color","archived","last_message_at","messages_count","members_count","unread_count","created_at","current_member","last_message"],"properties":{"id":{"type":"integer","description":"Unique channel identifier.","example":30},"kind":{"type":"string","enum":["channel","direct","announcement"],"description":"Channel mode.","example":"direct"},"name":{"type":["string","null"],"description":"Display name for a named channel; direct channels return null.","example":null},"slug":{"type":["string","null"],"description":"Account-unique slug for a named channel; direct channels return null.","example":null},"description":{"type":["string","null"],"description":"Longer channel description.","example":null},"topic":{"type":["string","null"],"description":"Short current topic for the channel.","example":null},"visibility":{"type":"string","enum":["public_channel","private_channel"],"description":"Whether a named channel is visible account-wide or only to members.","example":"private_channel"},"posting_policy":{"type":"string","enum":["all_members","admins_only","allowed_list"],"description":"Membership rule that decides who may post.","example":"all_members"},"team_id":{"type":["integer","null"],"description":"Synchronized team identifier, or null when the channel is not team-backed.","example":null},"created_by_id":{"type":["integer","null"],"description":"Account user who created the channel, when recorded.","example":7},"allowed_poster_ids":{"type":"array","description":"Account user ids allowed to post when posting_policy is allowed_list.","items":{"type":"integer"},"example":[]},"avatar_url":{"type":["string","null"],"description":"Uploaded channel avatar URL, or null when none is attached.","example":null},"avatar_icon":{"type":["string","null"],"description":"Optional icon used when there is no uploaded avatar.","example":null},"avatar_color":{"type":["string","null"],"description":"Optional color paired with avatar_icon.","example":null},"archived":{"type":"boolean","description":"Whether the channel is closed and archived for every member.","example":false},"last_message_at":{"type":["string","null"],"format":"date-time","description":"Timestamp of the latest channel message, or null for a new channel.","example":null},"messages_count":{"type":"integer","minimum":0,"description":"Number of messages currently associated with the channel.","example":0},"members_count":{"type":"integer","minimum":0,"description":"Number of current channel memberships.","example":2},"unread_count":{"type":"integer","minimum":0,"description":"Messages unread by the current viewer in this channel.","example":0},"created_at":{"type":"integer","description":"Channel creation time as Unix epoch seconds.","example":1778734800},"current_member":{"type":["object","null"],"additionalProperties":false,"description":"Viewer-specific membership state, or null for a visible public channel the viewer has not joined.","required":["id","role","notification_level","muted_until","muted","pinned","archived"],"properties":{"id":{"type":"integer","example":61},"role":{"type":"string","enum":["member","admin","owner"],"example":"owner","description":"The member's role in the internal-chat channel."},"notification_level":{"type":"string","enum":["all","mentions","none"],"example":"all"},"muted_until":{"type":["string","null"],"format":"date-time","example":null},"muted":{"type":"boolean","example":false},"pinned":{"type":"boolean","example":true},"archived":{"type":"boolean","example":false}}},"last_message":{"type":["object","null"],"additionalProperties":false,"description":"Latest viewer-visible message preview, or null when the channel has no visible message.","required":["id","content","content_type","attachments_count","sender_id","sender_name","is_own","created_at"],"properties":{"id":{"type":"integer","example":9007},"content":{"type":"string","description":"Plain preview text; body-less messages return an empty string.","example":"Deploy is green, shipping now."},"content_type":{"type":"string","enum":["text","shared_entity","system"],"example":"text"},"attachments_count":{"type":"integer","minimum":0,"example":1},"sender_id":{"type":["integer","null"],"description":"Sending user id, or null for a system message.","example":12},"sender_name":{"type":["string","null"],"description":"Sending user's name, or null for a system message.","example":"John Agent"},"is_own":{"type":"boolean","description":"Whether the current viewer sent this message.","example":false},"created_at":{"type":"integer","description":"Message creation time as Unix epoch seconds.","example":1778735160}}},"direct_partner":{"type":["object","null"],"additionalProperties":false,"description":"The other participant for a direct channel; omitted for non-direct channels.","required":["id","name","thumbnail"],"properties":{"id":{"type":"integer","example":12},"name":{"type":"string","example":"John Agent"},"thumbnail":{"type":"string","description":"Avatar URL, or an empty string when the user has no avatar.","example":"https://cdn.example.com/avatars/12.png"}}}}},"internal_chat_channel_list_response":{"type":"object","additionalProperties":false,"description":"Canonical response envelope for the active or archived internal-chat channel list.","required":["payload","meta"],"properties":{"payload":{"type":"array","description":"Channels visible to the current viewer under the requested list filters.","items":{"$ref":"#/components/schemas/internal_chat_channel_list_item"}},"meta":{"type":"object","additionalProperties":false,"description":"Metadata for the rendered list.","required":["count"],"properties":{"count":{"type":"integer","minimum":0,"description":"Number of channel rows returned in this response.","example":1}}}}},"internal_chat_channel":{"type":"object","additionalProperties":false,"description":"A fully rendered internal-chat channel, including viewer state, preview and members.","required":["id","kind","name","slug","description","topic","visibility","posting_policy","team_id","created_by_id","allowed_poster_ids","avatar_url","avatar_icon","avatar_color","archived","last_message_at","messages_count","members_count","unread_count","created_at","current_member","last_message","members"],"properties":{"id":{"type":"integer","description":"Unique channel identifier.","example":30},"kind":{"type":"string","enum":["channel","direct","announcement"],"description":"Channel mode.","example":"direct"},"name":{"type":["string","null"],"description":"Display name for a named channel; direct channels may return null.","example":null},"slug":{"type":["string","null"],"description":"Account-unique slug for a named channel; direct channels may return null.","example":null},"description":{"type":["string","null"],"description":"Longer channel description.","example":null},"topic":{"type":["string","null"],"description":"Short current topic for the channel.","example":null},"visibility":{"type":"string","enum":["public_channel","private_channel"],"description":"Whether a named channel is visible account-wide or only to members.","example":"private_channel"},"posting_policy":{"type":"string","enum":["all_members","admins_only","allowed_list"],"description":"Membership rule that decides who may post.","example":"all_members"},"team_id":{"type":["integer","null"],"description":"Synchronized team identifier, or null when the channel is not team-backed.","example":null},"created_by_id":{"type":["integer","null"],"description":"Account user who created the channel, when recorded.","example":7},"allowed_poster_ids":{"type":"array","description":"Account user ids allowed to post when posting_policy is allowed_list.","items":{"type":"integer"},"example":[]},"avatar_url":{"type":["string","null"],"description":"Uploaded channel avatar URL, or null when none is attached.","example":null},"avatar_icon":{"type":["string","null"],"description":"Optional icon used when there is no uploaded avatar.","example":null},"avatar_color":{"type":["string","null"],"description":"Optional color paired with avatar_icon.","example":null},"archived":{"type":"boolean","description":"Whether the channel is closed and archived for every member.","example":false},"last_message_at":{"type":["string","null"],"format":"date-time","description":"Timestamp of the latest channel message, or null for a new channel.","example":"2026-08-24T17:46:00Z"},"messages_count":{"type":"integer","minimum":0,"description":"Number of messages currently associated with the channel.","example":1284},"members_count":{"type":"integer","minimum":0,"description":"Number of current channel memberships.","example":2},"unread_count":{"type":"integer","minimum":0,"description":"Messages unread by the current viewer in this channel.","example":4},"created_at":{"type":"integer","description":"Channel creation time as Unix epoch seconds.","example":1778734800},"current_member":{"type":["object","null"],"additionalProperties":false,"description":"Viewer-specific membership state, or null for a visible public channel the viewer has not joined.","required":["id","role","notification_level","muted_until","muted","pinned","archived"],"properties":{"id":{"type":"integer","example":61},"role":{"type":"string","enum":["member","admin","owner"],"example":"owner","description":"The member's role in the internal-chat channel."},"notification_level":{"type":"string","enum":["all","mentions","none"],"example":"all"},"muted_until":{"type":["string","null"],"format":"date-time","example":null},"muted":{"type":"boolean","example":false},"pinned":{"type":"boolean","example":true},"archived":{"type":"boolean","example":false}}},"last_message":{"type":["object","null"],"additionalProperties":false,"description":"Latest viewer-visible message preview, or null when the channel has no visible message.","required":["id","content","content_type","attachments_count","sender_id","sender_name","is_own","created_at"],"properties":{"id":{"type":"integer","example":9007},"content":{"type":"string","description":"Plain preview text; body-less messages return an empty string.","example":"Deploy is green, shipping now."},"content_type":{"type":"string","enum":["text","shared_entity","system"],"example":"text"},"attachments_count":{"type":"integer","minimum":0,"example":1},"sender_id":{"type":["integer","null"],"description":"Sending user id, or null for a system message.","example":12},"sender_name":{"type":["string","null"],"description":"Sending user's name, or null for a system message.","example":"John Agent"},"is_own":{"type":"boolean","description":"Whether the current viewer sent this message.","example":false},"created_at":{"type":"integer","description":"Message creation time as Unix epoch seconds.","example":1778735160}}},"direct_partner":{"type":["object","null"],"additionalProperties":false,"description":"The other participant for a direct channel; omitted for non-direct channels.","required":["id","name","thumbnail"],"properties":{"id":{"type":"integer","example":12},"name":{"type":"string","example":"John Agent"},"thumbnail":{"type":"string","description":"Avatar URL, or an empty string when the user has no avatar.","example":"https://cdn.example.com/avatars/12.png"}}},"members":{"type":"array","description":"Current channel memberships.","items":{"$ref":"#/components/schemas/internal_chat_member"}}}},"internal_chat_channel_response":{"type":"object","additionalProperties":false,"description":"Canonical response envelope for one fully rendered internal-chat channel.","required":["payload"],"properties":{"payload":{"$ref":"#/components/schemas/internal_chat_channel"}}},"internal_chat_member_update_payload":{"type":"object","additionalProperties":false,"description":"Canonical partial-update envelope for one internal-chat membership.","required":["member"],"properties":{"member":{"type":"object","additionalProperties":false,"minProperties":1,"description":"Attributes to change. Role changes require channel member-management permission; notification, mute, pin and personal archive state may be changed by the represented member.","properties":{"role":{"type":"string","enum":["member","admin","owner"],"example":"owner","description":"The member's role in the internal-chat channel."},"notification_level":{"type":"string","enum":["all","mentions","none"],"example":"mentions"},"muted_until":{"type":["string","null"],"format":"date-time","description":"Mute deadline; a past timestamp is not currently muted, and null explicitly unmutes.","example":"2026-08-25T18:00:00Z"},"pinned":{"type":"boolean","description":"Pins or unpins the channel only for the represented member.","example":true},"archived":{"type":"boolean","description":"Archives or restores the channel only in the represented member's list.","example":false}}}},"example":{"member":{"role":"owner","notification_level":"mentions","muted_until":"2026-08-25T18:00:00Z","pinned":true,"archived":false}}},"crm_pipeline":{"type":"object","properties":{"id":{"type":"number","description":"The ID of the pipeline"},"name":{"type":"string","description":"The name of the pipeline"},"description":{"type":"string","description":"The description of the pipeline"},"pipeline_type":{"type":"string","description":"The type of the pipeline","enum":["sales","customer_success","onboarding","renewal","support","custom"]},"default":{"type":"boolean","description":"Whether this is the default pipeline for the account"},"position":{"type":"number","description":"The sort position of the pipeline"},"settings":{"type":"object","description":"Arbitrary pipeline settings (authoritative configuration store)","additionalProperties":true},"field_ids":{"type":"array","description":"Custom-attribute definition IDs selected for this pipeline (read-only convenience derived from settings)","items":{"type":"number"}},"required_field_ids":{"type":"array","description":"Subset of field_ids that are required on the deal form","items":{"type":"number"}},"created_at":{"type":"string","format":"date-time","description":"When the pipeline was created"},"updated_at":{"type":"string","format":"date-time","description":"When the pipeline was last updated"}}},"crm_stage":{"type":"object","properties":{"id":{"type":"number","description":"The ID of the stage"},"account_id":{"type":"number","description":"The account the stage belongs to"},"pipeline_id":{"type":"number","description":"The pipeline the stage belongs to"},"name":{"type":"string","description":"The name of the stage"},"color":{"type":"string","description":"Hex color code for the stage"},"position":{"type":"number","description":"The sort position of the stage within the pipeline"},"stage_type":{"type":"string","description":"The type of the stage (e.g. open, won, lost)","enum":["open","won","lost"]},"probability":{"type":"number","description":"Win probability (0-100) used for weighted forecasting"},"sla_in_hours":{"type":"number","description":"SLA in hours for time-in-stage; nil when the stage sets no SLA"},"created_at":{"type":"string","format":"date-time","description":"When the stage was created"},"updated_at":{"type":"string","format":"date-time","description":"When the stage was last updated"}}},"crm_item":{"type":"object","description":"A CRM deal/item with denormalized display fields and primitive badges.","properties":{"id":{"type":"number","description":"The ID of the item"},"account_id":{"type":"number","description":"The account the item belongs to"},"pipeline_id":{"type":"number","description":"The pipeline the item belongs to"},"stage_id":{"type":"number","description":"The current stage of the item"},"title":{"type":"string","description":"The title of the deal"},"description":{"type":"string","description":"The description of the deal"},"status":{"type":"string","description":"The status of the deal (open, won, lost)","enum":["open","won","lost"]},"priority":{"type":"string","description":"The priority (low, medium, high, urgent)","enum":["low","medium","high","urgent","normal"]},"value_amount":{"type":"number","description":"The monetary value of the deal"},"currency":{"type":"string","description":"The ISO currency code of value_amount"},"expected_close_on":{"type":"string","format":"date","description":"The expected close date"},"opened_at":{"type":"string","format":"date-time","description":"The editable business opening date (defaults to created_at)"},"closed_at":{"type":"string","format":"date-time","description":"When the deal was closed (won/lost)"},"stage_entered_at":{"type":"string","format":"date-time","description":"When the item entered its current stage (SLA anchor)"},"position":{"type":"number","description":"The sort position within the stage"},"health_score":{"type":"number","description":"The computed health score"},"health_status":{"type":"string","description":"The health bucket (healthy, at_risk, critical)","enum":["healthy","at_risk","critical"]},"health_computed_at":{"type":"string","format":"date-time","description":"When the health score was last computed"},"custom_attributes":{"type":"object","description":"Custom attributes (pipeline-defined fields)","additionalProperties":true},"additional_attributes":{"type":"object","description":"Additional system attributes","additionalProperties":true},"contact_id":{"type":"number","description":"The linked contact ID"},"conversation_id":{"type":"number","description":"The linked conversation global ID"},"organization_id":{"type":"number","description":"The linked organization ID"},"crm_organization_id":{"type":"number","description":"Deprecated legacy alias of organization_id (same value, kept for one release cycle)"},"assignee_id":{"type":"number","description":"The assigned agent ID"},"team_id":{"type":"number","description":"The assigned team ID"},"pipeline_name":{"type":"string","description":"Denormalized pipeline name (read-only convenience)"},"stage_name":{"type":"string","description":"Denormalized stage name (read-only convenience)"},"stage_sla_in_hours":{"type":"number","description":"The current stage's SLA in hours; nil when no SLA"},"assignee":{"type":"object","description":"Denormalized assignee summary (present when assigned)","properties":{"id":{"type":"number"},"name":{"type":"string"},"available_name":{"type":"string"},"thumbnail":{"type":"string"}}},"contact":{"type":"object","description":"Denormalized contact summary (present when linked)","properties":{"id":{"type":"number"},"name":{"type":"string"}}},"participants":{"type":"array","description":"Deal collaborators (mirror conversation participants)","items":{"$ref":"#/components/schemas/crm_participant"}},"organization":{"type":"object","description":"Denormalized organization summary (present when linked)","properties":{"id":{"type":"number"},"name":{"type":"string"}}},"crm_organization":{"type":"object","description":"Deprecated legacy alias of organization (same value, kept for one release cycle)","properties":{"id":{"type":"number"},"name":{"type":"string"}}},"conversation":{"type":"object","description":"Denormalized conversation summary (present when linked)","properties":{"id":{"type":"number","description":"The conversation global ID"},"display_id":{"type":"number","description":"The per-account conversation display ID for deep-linking"},"inbox":{"type":"object","description":"Secret-free logical inbox identity used by CRM surfaces. For a unified WhatsApp pair this is the public Cloud inbox, even when the linked conversation belongs to the hidden Web history.","properties":{"id":{"type":"number","description":"The logical inbox ID"},"name":{"type":"string","description":"The inbox name shown beside the conversation"},"channel_type":{"type":"string","enum":["Channel::Api","Channel::Email","Channel::FacebookPage","Channel::Instagram","Channel::Line","Channel::Sms","Channel::Telegram","Channel::Tiktok","Channel::TwilioSms","Channel::TwitterProfile","Channel::WebWidget","Channel::Whatsapp"],"description":"The channel class used to select the inbox icon"},"provider":{"type":["string","null"],"description":"Safe provider discriminator used for provider-specific icons","enum":["default","whatsapp_cloud","whatsapp_web","google","microsoft",null]},"medium":{"type":["string","null"],"description":"Safe medium discriminator used for Twilio WhatsApp icons"},"voice_enabled":{"type":"boolean","description":"Whether the inbox supports the voice badge"}}}}},"notes_count":{"type":"number","description":"Counter-cache count of notes"},"attachments_count":{"type":"number","description":"Counter-cache count of attachments"},"checklist_progress":{"type":"object","description":"Checklist completion progress","properties":{"done":{"type":"number"},"total":{"type":"number"}}},"archived_at":{"type":"string","format":"date-time","description":"When the item was soft-deleted (archived); nil when active"},"archived":{"type":"boolean","description":"Whether the item is archived (soft-deleted)"},"created_at":{"type":"string","format":"date-time","description":"When the item was created"},"updated_at":{"type":"string","format":"date-time","description":"When the item was last updated"}}},"crm_bulk_meta":{"type":"object","description":"Accounting for a bulk action on CRM items. `requested` always equals `updated + failed + skipped`: every id the caller sent is reported in exactly one bucket. This is what stops a client from showing success for fewer deals than the operator selected — an id that is archived, outside the user's visibility, or absent from the account is reported as `skipped`, never silently dropped. Shared by bulk_update, bulk_move, bulk_transfer and bulk_status, which all render the same view.","properties":{"requested":{"type":"number","description":"Distinct, non-zero ids received in `item_ids`.","example":12},"updated":{"type":"number","description":"Items the action was applied to successfully.","example":9},"failed":{"type":"number","description":"Items the action was attempted on and which raised.","example":1},"failed_ids":{"type":"array","description":"Ids of the items that were attempted and raised.","items":{"type":"number"},"example":[41]},"skipped":{"type":"number","description":"Items the bulk scope never yielded, so the action was never attempted. A distinct bucket from `failed`: these were refused, not broken.","example":2},"skipped_ids":{"type":"array","description":"Ids that were refused before the action ran.","items":{"type":"number"},"example":[58,63]},"skipped_details":{"type":"array","description":"Per-id reason for every entry in `skipped_ids`.","items":{"type":"object","description":"One refused id and why it was refused.","properties":{"id":{"type":"number","example":58},"reason":{"type":"string","description":"`archived` — the item is soft-deleted; `not_permitted` — the item is outside the current user's visibility scope; `not_found` — no item with that id exists in this account.","enum":["archived","not_permitted","not_found"],"example":"archived"}}},"example":[{"id":58,"reason":"archived"},{"id":63,"reason":"not_permitted"}]}},"example":{"requested":12,"updated":9,"failed":1,"failed_ids":[41],"skipped":2,"skipped_ids":[58,63],"skipped_details":[{"id":58,"reason":"archived"},{"id":63,"reason":"not_permitted"}]}},"crm_bulk_meta_archived_scope":{"type":"object","description":"Accounting for a bulk action that operates on the ARCHIVED set (bulk_restore, bulk_purge). Identical envelope to `crm_bulk_meta` — `requested` always equals `updated + failed + skipped`, so every id the caller sent is reported in exactly one bucket and none is silently dropped. Only the `skipped_details` vocabulary differs: these endpoints select archived items, so the state-based refusal is `not_archived` (the inverse of `crm_bulk_meta`'s `archived`). A separate schema rather than a widened shared enum, so neither direction documents a reason it can never emit.","properties":{"requested":{"type":"number","description":"Distinct, non-zero ids received in `item_ids`.","example":12},"updated":{"type":"number","description":"Items the action was applied to successfully.","example":9},"failed":{"type":"number","description":"Items the action was attempted on and which raised.","example":1},"failed_ids":{"type":"array","description":"Ids of the items that were attempted and raised.","items":{"type":"number"},"example":[41]},"skipped":{"type":"number","description":"Items the archived scope never yielded, so the action was never attempted. A distinct bucket from `failed`: refused, not broken.","example":2},"skipped_ids":{"type":"array","description":"Ids that were refused before the action ran.","items":{"type":"number"},"example":[58,63]},"skipped_details":{"type":"array","description":"Per-id reason for every entry in `skipped_ids`.","items":{"type":"object","description":"One refused id and why it was refused.","properties":{"id":{"type":"number","example":58},"reason":{"type":"string","description":"`not_archived` — the item is live, so there is nothing to restore or purge; `not_permitted` — the item is outside the current user's visibility scope; `not_found` — no item with that id exists in this account. The reason is decided visibility-first, so an item the caller cannot see always reports `not_permitted` and never leaks its archival state.","enum":["not_archived","not_permitted","not_found"],"example":"not_archived"}}},"example":[{"id":58,"reason":"not_archived"},{"id":63,"reason":"not_permitted"}]}},"example":{"requested":12,"updated":9,"failed":1,"failed_ids":[41],"skipped":2,"skipped_ids":[58,63],"skipped_details":[{"id":58,"reason":"not_archived"},{"id":63,"reason":"not_permitted"}]}},"crm_bulk_meta_async":{"type":"object","description":"Accounting for a bulk action whose work is performed ASYNCHRONOUSLY after the response (bulk_execute_macro). `requested` always equals `enqueued + skipped`: every id the caller sent is reported in exactly one bucket, so a selection can never be silently narrowed. Deliberately carries NO `updated`/`failed` counts — the job runs after this response, so per-item outcome is genuinely unknowable at render time, and reporting a success count here would replace a silent loss with a false claim. `enqueued` means \"handed to the queue\", nothing more.","properties":{"requested":{"type":"number","description":"Distinct, non-zero ids received in `item_ids`.","example":12},"enqueued":{"type":"number","description":"Ids handed to the background job. NOT a success count — an item can be enqueued cleanly and still fail inside the job.","example":4},"skipped":{"type":"number","description":"Requested ids the scope declined to enqueue. This is the part that is knowable synchronously, and the part that used to be dropped entirely.","example":8},"skipped_ids":{"type":"array","description":"Ids that were refused before anything was enqueued.","items":{"type":"number"},"example":[58,63,64,65,66,67,68,69]},"skipped_details":{"type":"array","description":"Per-id reason for every entry in `skipped_ids`.","items":{"type":"object","description":"One refused id and why it was refused.","properties":{"id":{"type":"number","example":58},"reason":{"type":"string","description":"`archived` — the item is soft-deleted; `not_permitted` — the item is outside the current user's visibility scope; `not_found` — no item with that id exists in this account. Decided visibility-first, so an item the caller cannot see always reports `not_permitted` and never leaks its archival state.","enum":["archived","not_permitted","not_found"],"example":"archived"}}},"example":[{"id":58,"reason":"archived"},{"id":63,"reason":"not_permitted"}]}},"example":{"requested":12,"enqueued":4,"skipped":8,"skipped_ids":[58,63,64,65,66,67,68,69],"skipped_details":[{"id":58,"reason":"archived"},{"id":63,"reason":"not_permitted"}]}},"crm_note":{"type":"object","description":"A note attached to a CRM item.","properties":{"id":{"type":"number","description":"The ID of the note"},"content":{"type":"string","description":"The note body"},"account_id":{"type":"number","description":"The account the note belongs to"},"crm_item_id":{"type":"number","description":"The CRM item the note belongs to"},"user":{"$ref":"#/components/schemas/agent"},"created_at":{"type":"number","description":"Creation timestamp (epoch seconds)"},"updated_at":{"type":"number","description":"Last update timestamp (epoch seconds)"}}},"crm_attachment":{"type":"object","description":"A file attachment on a CRM item.","properties":{"id":{"type":"number","description":"The ID of the attachment"},"crm_item_id":{"type":"number","description":"The CRM item the attachment belongs to"},"account_id":{"type":"number","description":"The account the attachment belongs to"},"file_name":{"type":"string","description":"The original file name"},"file_type":{"type":"string","description":"The high-level file type","enum":["image","audio","video","file"]},"content_type":{"type":"string","description":"The MIME content type"},"byte_size":{"type":"number","description":"The file size in bytes"},"file_url":{"type":"string","description":"The URL to view the file"},"download_url":{"type":"string","description":"The URL to download the file"},"thumb_url":{"type":"string","description":"The thumbnail URL (for images)"},"created_at":{"type":"number","description":"Creation timestamp (epoch seconds)"}}},"crm_participant":{"type":"object","description":"A deal participant (agent collaborator), mirroring conversation participants.","properties":{"id":{"type":"number","description":"The user ID of the participant"},"name":{"type":"string","description":"The participant's name"},"available_name":{"type":"string","description":"The participant's display/available name"},"thumbnail":{"type":"string","description":"The participant's avatar URL"}}},"crm_checklist_item":{"type":"object","description":"A checklist item on a CRM item.","properties":{"id":{"type":"number","description":"The ID of the checklist item"},"account_id":{"type":"number","description":"The account the checklist item belongs to"},"record_type":{"type":"string","description":"The polymorphic owner type","enum":["Crm::Item"]},"record_id":{"type":"number","description":"The polymorphic owner ID (the CRM item)"},"title":{"type":"string","description":"The checklist item title"},"completed":{"type":"boolean","description":"Whether the item is completed"},"completed_at":{"type":"number","description":"Completion timestamp (epoch seconds); nil when not completed"},"completed_by_id":{"type":"number","description":"The user who completed the item"},"assignee_id":{"type":"number","description":"The assigned agent ID"},"due_on":{"type":"string","format":"date","description":"The due date"},"position":{"type":"number","description":"The sort position"},"assignee":{"$ref":"#/components/schemas/agent"},"created_at":{"type":"number","description":"Creation timestamp (epoch seconds)"},"updated_at":{"type":"number","description":"Last update timestamp (epoch seconds)"}}},"crm_organization":{"type":"object","description":"An organization (Empresas module) — a first-class company-like entity with fiscal identity, N:N contact memberships, typed relationships and matriz/filial hierarchy.","properties":{"id":{"type":"number","description":"The ID of the organization"},"account_id":{"type":"number","description":"The account the organization belongs to"},"name":{"type":"string","description":"The organization display name"},"legal_name":{"type":"string","description":"The registered legal name (razão social)"},"legal_type":{"type":"string","enum":["individual","business"],"description":"Whether the organization is a natural person (individual) or a legal entity (business)"},"tax_id":{"type":"string","description":"The fiscal identifier. Returned as the real value to an authenticated human agent; a type-aware mask (e.g. \"**.***.***/****-81\") when a role field rule masks it or the caller is a bot. A hidden rule omits the key."},"tax_id_type":{"type":"string","enum":["br_cpf","br_cnpj","us_ein","eu_vat","uk_vat","generic"],"description":"The fiscal identifier scheme used to validate and mask tax_id"},"country":{"type":"string","description":"ISO 3166-1 alpha-2 country code used for fiscal-id detection (e.g. \"BR\", \"US\")"},"domain":{"type":"string","description":"The primary web domain (mirror of the primary entry in domains)"},"domains":{"type":"array","description":"All web domains owned by the organization; exactly one is primary","items":{"type":"object","properties":{"domain":{"type":"string","description":"The web domain (e.g. \"acme.com\")"},"primary":{"type":"boolean","description":"Whether this is the primary domain (mirrored into the domain property)"}}}},"website":{"type":"string","description":"The organization website URL"},"industry":{"type":"string","description":"Free-form industry label (e.g. \"Educação\", \"SaaS\")"},"size":{"type":"string","description":"Company-size band. The editor and the segment filter both write the canonical range keys (1-10, 11-50, 51-200, 201-500, 501-1000, 1001-5000, 5000+); the column is free text, so a legacy or API-supplied label is preserved rather than rejected.","example":"11-50"},"lifecycle_stage":{"type":"string","description":"Free-form lifecycle stage label (e.g. \"lead\", \"customer\"); used by list chips and segments"},"parent_id":{"type":"number","description":"The parent organization ID (matriz) when this is a branch (filial); null for root organizations"},"parent_name":{"type":["string","null"],"description":"Display name of the immediate parent organization when present"},"children_count":{"type":"number","description":"Number of active direct child organizations"},"children":{"type":"array","description":"Active direct child organizations returned by the detail endpoint","items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"number","description":"Child organization ID"},"name":{"type":"string","description":"Child organization display name"},"legal_name":{"type":["string","null"],"description":"Child organization registered legal name"},"lifecycle_stage":{"type":["string","null"],"description":"Child organization lifecycle stage"},"domain":{"type":["string","null"],"description":"Child organization primary domain"}}}},"owner_id":{"type":"number","description":"The agent (user) who owns this organization"},"owner_name":{"type":["string","null"],"description":"Display name of the owning agent when one is assigned"},"thumbnail":{"type":["string","null"],"description":"URL of the organization logo (same value as avatar_url; both are emitted so every surface reads one stable field)","example":"https://cdn.example.com/orgs/42.png"},"avatar_url":{"type":["string","null"],"description":"URL of the organization logo","example":"https://cdn.example.com/orgs/42.png"},"email":{"type":"string","description":"The main contact email of the organization"},"phone":{"type":"string","description":"The main contact phone of the organization"},"address":{"type":"object","additionalProperties":false,"description":"Postal address. The keys are the canonical contract shared with the payment gateways (Payments::ChargeValidator::ADDRESS_FIELDS) — snake_case, never camelCase. Blank components are omitted, unknown keys are dropped, and a write MERGES over the stored map (an absent key keeps its stored value; a key sent blank clears it).","properties":{"zip_code":{"type":"string","description":"Postal code (CEP in Brazil), digits or formatted","example":"13338-705"},"street_name":{"type":"string","description":"Street/avenue name (logradouro)","example":"Av. Paulista"},"street_number":{"type":"string","description":"Street number","example":"1000"},"complement":{"type":"string","description":"Complement (apartment, block, suite)","example":"Sala 42"},"neighborhood":{"type":"string","description":"Neighborhood (bairro)","example":"Bela Vista"},"city":{"type":"string","description":"City","example":"Indaiatuba"},"federal_unit":{"type":"string","description":"State/federal unit; the 2-letter UF in Brazil","example":"SP"}},"example":{"zip_code":"13338-705","street_name":"Av. Paulista","street_number":"1000","complement":"Sala 42","neighborhood":"Bela Vista","city":"Indaiatuba","federal_unit":"SP"}},"registrations":{"type":"object","additionalProperties":false,"description":"Fiscal registration numbers. Same merge semantics as address (absent key keeps the stored value, blank clears).","properties":{"state_registration":{"type":"string","description":"Brazilian Inscrição Estadual (IE); \"ISENTO\" when exempt","example":"110042490114"},"municipal_registration":{"type":"string","description":"Brazilian Inscrição Municipal (IM)","example":"1234567"}},"example":{"state_registration":"110042490114","municipal_registration":"1234567"}},"timezone":{"type":"string","description":"IANA timezone of the organization (e.g. \"America/Sao_Paulo\")"},"description":{"type":"string","description":"The organization description"},"custom_attributes":{"type":"object","description":"Account-defined custom attributes for organizations (company attribute model)","additionalProperties":true},"additional_attributes":{"type":"object","description":"Additional system attributes","additionalProperties":true},"contacts_count":{"type":"number","description":"Counter-cache count of linked contacts"},"health_score":{"type":"number","description":"The computed health score"},"created_at":{"type":"string","format":"date-time","description":"When the organization was created"},"updated_at":{"type":"string","format":"date-time","description":"When the organization was last updated"},"field_visibility":{"type":"object","additionalProperties":false,"description":"Present ONLY when the caller's role field rules restrict at least one organization field. Maps the restricted field to how it was rendered, so the client can disable the input instead of round-tripping a masked value back.","properties":{"tax_id":{"type":"string","enum":["masked","hidden"],"description":"How the fiscal id was rendered for this caller"},"email":{"type":"string","enum":["masked","hidden"],"description":"How the email was rendered for this caller"},"phone":{"type":"string","enum":["masked","hidden"],"description":"How the phone was rendered for this caller"},"address":{"type":"string","enum":["masked","hidden"],"description":"How country/address were rendered for this caller"}},"example":{"tax_id":"masked","address":"hidden"}}}},"crm_report":{"type":"object","description":"The complete CRM analytics payload assembled by the CRM report service, optionally scoped to one pipeline and/or a created_at date range. Money figures are grouped by currency (a map of ISO currency code to amount).","properties":{"pipeline_id":{"type":"number","description":"The pipeline the report is scoped to; null for an account-wide report"},"since":{"type":"string","format":"date","description":"The start of the created_at range filter (inclusive); null when unset"},"until":{"type":"string","format":"date","description":"The end of the created_at range filter (inclusive); null when unset"},"overview":{"type":"object","description":"Headline counts, rates, cycle time and value totals","properties":{"total_count":{"type":"number"},"open_count":{"type":"number"},"won_count":{"type":"number"},"lost_count":{"type":"number"},"conversion_rate":{"type":"number","description":"won / (won + lost)"},"win_rate":{"type":"number","description":"won / total"},"avg_cycle_time":{"type":"number","description":"Average time-to-close in seconds for closed items"},"open_value_by_currency":{"type":"object","description":"Sum of open value grouped by currency code","additionalProperties":{"type":"number"}},"won_value_by_currency":{"type":"object","description":"Sum of won value grouped by currency code","additionalProperties":{"type":"number"}},"forecast_by_currency":{"type":"object","description":"Weighted forecast (value x stage probability) over open items, by currency","additionalProperties":{"type":"number"}}}},"funnel":{"type":"array","description":"Per-stage breakdown; only populated when a specific pipeline is selected (empty array otherwise, since stages are pipeline-scoped).","items":{"type":"object","properties":{"stage_id":{"type":"number"},"name":{"type":"string"},"color":{"type":"string"},"stage_type":{"type":"string","enum":["open","won","lost"],"description":"The lifecycle bucket a pipeline stage maps a deal onto."},"probability":{"type":"number"},"sla_in_hours":{"type":"number"},"count":{"type":"number","description":"Total items that have been in this stage"},"open_count":{"type":"number"},"value_by_currency":{"type":"object","additionalProperties":{"type":"number"},"description":"Total deal value in the group, keyed by ISO currency code."},"forecast_by_currency":{"type":"object","additionalProperties":{"type":"number"},"description":"Weighted forecast (value x stage probability) in the group, keyed by ISO currency code."}}}},"sla":{"type":"object","description":"Open-item SLA buckets by time-in-stage vs the stage SLA","properties":{"on_track":{"type":"number"},"due_soon":{"type":"number"},"breached":{"type":"number"},"no_sla":{"type":"number"}}},"health":{"type":"object","description":"Open-item health distribution (zero-filled to known keys)","properties":{"healthy":{"type":"number"},"at_risk":{"type":"number"},"critical":{"type":"number"}}},"by_priority":{"type":"object","description":"Open-item priority distribution (zero-filled to known keys)","properties":{"low":{"type":"number"},"medium":{"type":"number"},"high":{"type":"number"},"urgent":{"type":"number"}}},"by_assignee":{"type":"array","description":"Top owners by open count, with open value by currency","items":{"type":"object","properties":{"assignee_id":{"type":"number"},"name":{"type":"string"},"open_count":{"type":"number"},"open_value_by_currency":{"type":"object","additionalProperties":{"type":"number"},"description":"Open deal value in the group, keyed by ISO currency code."}}}}}},"crm_pipeline_template":{"type":"object","description":"A pipeline template descriptor used to scaffold a new pipeline with predefined stages. The index returns the catalog of available templates; create instantiates one into a real pipeline.","properties":{"id":{"type":"string","description":"The template identifier (used as template_id when creating)"},"name":{"type":"string","description":"The display name of the template"},"description":{"type":"string","description":"A short description of the template"},"pipeline_type":{"type":"string","description":"The pipeline type the template produces","enum":["sales","customer_success","onboarding","renewal","support","custom"]},"stages":{"type":"array","description":"The predefined stages the template creates","items":{"type":"object","properties":{"name":{"type":"string"},"color":{"type":"string"},"stage_type":{"type":"string","enum":["open","won","lost"],"description":"The lifecycle bucket a pipeline stage maps a deal onto."},"probability":{"type":"number"}}}}}},"organization":{"type":"object","description":"An organization (Empresas module) — a first-class company-like entity with fiscal identity, N:N contact memberships, typed relationships and matriz/filial hierarchy.","properties":{"id":{"type":"number","description":"The ID of the organization"},"account_id":{"type":"number","description":"The account the organization belongs to"},"name":{"type":"string","description":"The organization display name"},"legal_name":{"type":"string","description":"The registered legal name (razão social)"},"legal_type":{"type":"string","enum":["individual","business"],"description":"Whether the organization is a natural person (individual) or a legal entity (business)"},"tax_id":{"type":"string","description":"The fiscal identifier. Returned as the real value to an authenticated human agent; a type-aware mask (e.g. \"**.***.***/****-81\") when a role field rule masks it or the caller is a bot. A hidden rule omits the key."},"tax_id_type":{"type":"string","enum":["br_cpf","br_cnpj","us_ein","eu_vat","uk_vat","generic"],"description":"The fiscal identifier scheme used to validate and mask tax_id"},"country":{"type":"string","description":"ISO 3166-1 alpha-2 country code used for fiscal-id detection (e.g. \"BR\", \"US\")"},"domain":{"type":"string","description":"The primary web domain (mirror of the primary entry in domains)"},"domains":{"type":"array","description":"All web domains owned by the organization; exactly one is primary","items":{"type":"object","properties":{"domain":{"type":"string","description":"The web domain (e.g. \"acme.com\")"},"primary":{"type":"boolean","description":"Whether this is the primary domain (mirrored into the domain property)"}}}},"website":{"type":"string","description":"The organization website URL"},"industry":{"type":"string","description":"Free-form industry label (e.g. \"Educação\", \"SaaS\")"},"size":{"type":"string","description":"Company-size band. The editor and the segment filter both write the canonical range keys (1-10, 11-50, 51-200, 201-500, 501-1000, 1001-5000, 5000+); the column is free text, so a legacy or API-supplied label is preserved rather than rejected.","example":"11-50"},"lifecycle_stage":{"type":"string","description":"Free-form lifecycle stage label (e.g. \"lead\", \"customer\"); used by list chips and segments"},"parent_id":{"type":"number","description":"The parent organization ID (matriz) when this is a branch (filial); null for root organizations"},"parent_name":{"type":["string","null"],"description":"Display name of the immediate parent organization when present"},"children_count":{"type":"number","description":"Number of active direct child organizations"},"children":{"type":"array","description":"Active direct child organizations returned by the detail endpoint","items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"number","description":"Child organization ID"},"name":{"type":"string","description":"Child organization display name"},"legal_name":{"type":["string","null"],"description":"Child organization registered legal name"},"lifecycle_stage":{"type":["string","null"],"description":"Child organization lifecycle stage"},"domain":{"type":["string","null"],"description":"Child organization primary domain"}}}},"owner_id":{"type":"number","description":"The agent (user) who owns this organization"},"owner_name":{"type":["string","null"],"description":"Display name of the owning agent when one is assigned"},"thumbnail":{"type":["string","null"],"description":"URL of the organization logo (same value as avatar_url; both are emitted so every surface reads one stable field)","example":"https://cdn.example.com/orgs/42.png"},"avatar_url":{"type":["string","null"],"description":"URL of the organization logo","example":"https://cdn.example.com/orgs/42.png"},"email":{"type":"string","description":"The main contact email of the organization"},"phone":{"type":"string","description":"The main contact phone of the organization"},"address":{"type":"object","additionalProperties":false,"description":"Postal address. The keys are the canonical contract shared with the payment gateways (Payments::ChargeValidator::ADDRESS_FIELDS) — snake_case, never camelCase. Blank components are omitted, unknown keys are dropped, and a write MERGES over the stored map (an absent key keeps its stored value; a key sent blank clears it).","properties":{"zip_code":{"type":"string","description":"Postal code (CEP in Brazil), digits or formatted","example":"13338-705"},"street_name":{"type":"string","description":"Street/avenue name (logradouro)","example":"Av. Paulista"},"street_number":{"type":"string","description":"Street number","example":"1000"},"complement":{"type":"string","description":"Complement (apartment, block, suite)","example":"Sala 42"},"neighborhood":{"type":"string","description":"Neighborhood (bairro)","example":"Bela Vista"},"city":{"type":"string","description":"City","example":"Indaiatuba"},"federal_unit":{"type":"string","description":"State/federal unit; the 2-letter UF in Brazil","example":"SP"}},"example":{"zip_code":"13338-705","street_name":"Av. Paulista","street_number":"1000","complement":"Sala 42","neighborhood":"Bela Vista","city":"Indaiatuba","federal_unit":"SP"}},"registrations":{"type":"object","additionalProperties":false,"description":"Fiscal registration numbers. Same merge semantics as address (absent key keeps the stored value, blank clears).","properties":{"state_registration":{"type":"string","description":"Brazilian Inscrição Estadual (IE); \"ISENTO\" when exempt","example":"110042490114"},"municipal_registration":{"type":"string","description":"Brazilian Inscrição Municipal (IM)","example":"1234567"}},"example":{"state_registration":"110042490114","municipal_registration":"1234567"}},"timezone":{"type":"string","description":"IANA timezone of the organization (e.g. \"America/Sao_Paulo\")"},"description":{"type":"string","description":"The organization description"},"custom_attributes":{"type":"object","description":"Account-defined custom attributes for organizations (company attribute model)","additionalProperties":true},"additional_attributes":{"type":"object","description":"Additional system attributes","additionalProperties":true},"contacts_count":{"type":"number","description":"Counter-cache count of linked contacts"},"health_score":{"type":"number","description":"The computed health score"},"created_at":{"type":"string","format":"date-time","description":"When the organization was created"},"updated_at":{"type":"string","format":"date-time","description":"When the organization was last updated"},"field_visibility":{"type":"object","additionalProperties":false,"description":"Present ONLY when the caller's role field rules restrict at least one organization field. Maps the restricted field to how it was rendered, so the client can disable the input instead of round-tripping a masked value back.","properties":{"tax_id":{"type":"string","enum":["masked","hidden"],"description":"How the fiscal id was rendered for this caller"},"email":{"type":"string","enum":["masked","hidden"],"description":"How the email was rendered for this caller"},"phone":{"type":"string","enum":["masked","hidden"],"description":"How the phone was rendered for this caller"},"address":{"type":"string","enum":["masked","hidden"],"description":"How country/address were rendered for this caller"}},"example":{"tax_id":"masked","address":"hidden"}}}},"organization_membership":{"type":"object","description":"A contact ⟷ organization membership with a niche-specific role. Each contact has at most one primary membership, mirrored into the contact's organization link.","properties":{"id":{"type":"number","description":"The ID of the membership"},"account_id":{"type":"number","description":"The account the membership belongs to"},"organization_id":{"type":"number","description":"The organization side of the membership"},"contact_id":{"type":"number","description":"The contact side of the membership"},"role":{"type":"string","description":"Free-form role of the contact inside the organization (e.g. \"Responsável financeiro\", \"CEO\")"},"title":{"type":"string","description":"Free-form job title of the contact"},"primary":{"type":"boolean","description":"Whether this is the contact's primary organization (at most one per contact)"},"started_on":{"type":"string","format":"date","description":"When the membership started"},"ended_on":{"type":"string","format":"date","description":"When the membership ended; null while active"},"created_at":{"type":"string","format":"date-time","description":"When the membership was created"},"contact":{"type":"object","description":"Denormalized contact summary","properties":{"id":{"type":"number","description":"The contact ID"},"name":{"type":"string","description":"The contact name"},"email":{"type":"string","description":"The contact email"},"phone_number":{"type":"string","description":"The contact phone number"},"thumbnail":{"type":"string","description":"The contact avatar URL"}}}}},"relationship":{"type":"object","description":"A typed, directional edge between two subjects (contact or organization) — e.g. parent ⟷ child, guarantor ⟷ tenant, matriz ⟷ fornecedor. Labels resolve per side via the relationship type's name/inverse_name.","properties":{"id":{"type":"number","description":"The ID of the relationship"},"account_id":{"type":"number","description":"The account the relationship belongs to"},"relationship_type":{"type":"object","description":"The type of the edge","properties":{"id":{"type":"number","description":"The relationship type ID"},"name":{"type":"string","description":"The label seen from the source side (e.g. \"Responsável\")"},"inverse_name":{"type":"string","description":"The label seen from the target side (e.g. \"Dependente\"); falls back to name when empty"},"category":{"type":"string","description":"Free-form grouping of the type (e.g. \"family\", \"business\", \"legal\", \"care\")"}}},"source":{"type":"object","description":"The source subject of the edge","properties":{"type":{"type":"string","enum":["Contact","Organization"],"description":"The subject kind"},"id":{"type":"number","description":"The subject ID"},"name":{"type":"string","description":"The subject display name"}}},"target":{"type":"object","description":"The target subject of the edge","properties":{"type":{"type":"string","enum":["Contact","Organization"],"description":"The subject kind"},"id":{"type":"number","description":"The subject ID"},"name":{"type":"string","description":"The subject display name"}}},"label":{"type":"string","description":"Subject-relative label (list responses only) — the edge label seen from the queried subject's side"},"counterpart":{"type":"object","description":"Subject-relative counterpart (list responses only) — the record on the other end of the edge","properties":{"type":{"type":"string","enum":["Contact","Organization"],"description":"The counterpart kind"},"id":{"type":"number","description":"The counterpart ID"},"name":{"type":"string","description":"The counterpart display name"}}},"notes":{"type":"string","description":"Free-form notes about the relationship"},"started_on":{"type":"string","format":"date","description":"When the relationship started"},"ended_on":{"type":"string","format":"date","description":"When the relationship ended; null while active"},"created_at":{"type":"string","format":"date-time","description":"When the relationship was created"}}},"relationship_type":{"type":"object","description":"An account-scoped named relationship type with an optional inverse label (\"Responsável\" ⟷ \"Dependente\"). Types in use by relationships cannot be deleted.","properties":{"id":{"type":"number","description":"The ID of the relationship type"},"account_id":{"type":"number","description":"The account the type belongs to"},"name":{"type":"string","description":"The label seen from the source side of an edge"},"inverse_name":{"type":"string","description":"The label seen from the target side; falls back to name when empty"},"category":{"type":"string","description":"Free-form grouping of the type (e.g. \"family\", \"business\", \"legal\", \"care\")"},"created_at":{"type":"string","format":"date-time","description":"When the type was created"}}},"organization_payload":{"type":"object","properties":{"name":{"type":"string","description":"The organization display name","example":"Acme Corp"},"legal_name":{"type":"string","description":"The registered legal name (razão social)","example":"Acme Corporation LTDA"},"legal_type":{"type":"string","enum":["individual","business"],"description":"Whether the organization is a natural person (individual) or a legal entity (business)","example":"business"},"tax_id":{"type":"string","description":"The raw fiscal identifier; validated against tax_id_type/country and stored encrypted. Responses return it real to a human agent, masked under a role field rule or for a bot.","example":"12.345.678/0001-95"},"tax_id_type":{"type":"string","enum":["br_cpf","br_cnpj","us_ein","eu_vat","uk_vat","generic"],"description":"The fiscal identifier scheme; auto-detected from country when omitted","example":"br_cnpj"},"country":{"type":"string","description":"ISO 3166-1 alpha-2 country code (drives fiscal-id detection and masking)","example":"BR"},"domain":{"type":"string","description":"The primary web domain","example":"acme.com"},"domains":{"type":"array","description":"All web domains; mark exactly one entry as primary","items":{"type":"object","properties":{"domain":{"type":"string","description":"The web domain","example":"acme.com"},"primary":{"type":"boolean","description":"Whether this is the primary domain","example":true}}}},"website":{"type":"string","description":"The organization website URL","example":"https://acme.com"},"avatar":{"type":"string","format":"binary","description":"The organization logo. Send it as the form-data binary (multipart request, field organization[avatar]) or use avatar_url instead."},"avatar_url":{"type":"string","description":"URL of an image to use as the organization logo. Fetched ASYNCHRONOUSLY after the record is saved (SSRF-filtered), so the logo may appear a moment after the response.","example":"https://cdn.example.com/orgs/42.png"},"industry":{"type":"string","description":"Free-form industry label","example":"SaaS"},"size":{"type":"string","description":"Company-size band. Prefer the canonical range keys (1-10, 11-50, 51-200, 201-500, 501-1000, 1001-5000, 5000+) so segment filters match; any other string is accepted and preserved.","example":"11-50"},"lifecycle_stage":{"type":"string","description":"Free-form lifecycle stage label","example":"customer"},"parent_id":{"type":"number","description":"The parent organization ID (matriz); cycles are rejected"},"owner_id":{"type":"number","description":"The agent (user) who owns this organization"},"email":{"type":"string","description":"The main contact email","example":"contato@acme.com"},"phone":{"type":"string","description":"The main contact phone","example":"+5511999999999"},"address":{"type":"object","additionalProperties":false,"description":"Postal address components — canonical snake_case keys shared with the payment gateways. The write MERGES over the stored map: a key you do not send keeps its stored value, a key sent blank clears it. Unknown keys are dropped. Common aliases (zipCode, cep, street, number, state, uf, district) are canonicalized instead of being silently discarded.","properties":{"zip_code":{"type":"string","description":"Postal code (CEP in Brazil)","example":"13338-705"},"street_name":{"type":"string","description":"Street/avenue name (logradouro)","example":"Av. Paulista"},"street_number":{"type":"string","description":"Street number","example":"1000"},"complement":{"type":"string","description":"Complement (apartment, block, suite)","example":"Sala 42"},"neighborhood":{"type":"string","description":"Neighborhood (bairro)","example":"Bela Vista"},"city":{"type":"string","description":"City","example":"Indaiatuba"},"federal_unit":{"type":"string","description":"State/federal unit; the 2-letter UF in Brazil","example":"SP"}},"example":{"zip_code":"13338-705","street_name":"Av. Paulista","street_number":"1000","complement":"Sala 42","neighborhood":"Bela Vista","city":"Indaiatuba","federal_unit":"SP"}},"registrations":{"type":"object","additionalProperties":false,"description":"Fiscal registration numbers. Same merge semantics as address.","properties":{"state_registration":{"type":"string","description":"Brazilian Inscrição Estadual (IE); \"ISENTO\" when exempt","example":"110042490114"},"municipal_registration":{"type":"string","description":"Brazilian Inscrição Municipal (IM)","example":"1234567"}},"example":{"state_registration":"110042490114","municipal_registration":"1234567"}},"timezone":{"type":"string","description":"IANA timezone","example":"America/Sao_Paulo"},"description":{"type":"string","description":"The organization description"},"custom_attributes":{"type":"object","description":"Account-defined custom attributes for organizations","additionalProperties":true},"additional_attributes":{"type":"object","description":"Additional system attributes","additionalProperties":true}},"required":["name"]},"organization_membership_payload":{"type":"object","properties":{"contact_id":{"type":"number","description":"The contact to link to the organization (create only)","example":42},"role":{"type":"string","description":"Free-form role of the contact inside the organization","example":"Responsável financeiro"},"title":{"type":"string","description":"Free-form job title of the contact","example":"CFO"},"primary":{"type":"boolean","description":"Set this membership as the contact's primary organization (demotes any other primary)","example":true},"started_on":{"type":"string","format":"date","description":"When the membership started","example":"2026-01-15"},"ended_on":{"type":"string","format":"date","description":"When the membership ended"}},"required":["contact_id"]},"relationship_payload":{"type":"object","properties":{"relationship_type_id":{"type":"number","description":"The relationship type of the edge","example":7},"source_type":{"type":"string","enum":["Contact","Organization"],"description":"The source subject kind","example":"Contact"},"source_id":{"type":"number","description":"The source subject ID","example":42},"target_type":{"type":"string","enum":["Contact","Organization"],"description":"The target subject kind","example":"Contact"},"target_id":{"type":"number","description":"The target subject ID","example":43},"notes":{"type":"string","description":"Free-form notes about the relationship","example":"Responsável financeiro do aluno"},"started_on":{"type":"string","format":"date","description":"When the relationship started","example":"2026-02-01"},"ended_on":{"type":"string","format":"date","description":"When the relationship ended"}},"required":["relationship_type_id","source_type","source_id","target_type","target_id"]},"relationship_type_payload":{"type":"object","properties":{"name":{"type":"string","description":"The label seen from the source side of an edge","example":"Responsável"},"inverse_name":{"type":"string","description":"The label seen from the target side; falls back to name when empty","example":"Dependente"},"category":{"type":"string","description":"Free-form grouping of the type","example":"family"}},"required":["name"]},"crm_pipeline_payload":{"type":"object","properties":{"name":{"type":"string","description":"The name of the pipeline","example":"Sales"},"description":{"type":"string","description":"A short description of the pipeline"},"pipeline_type":{"type":"string","description":"The type of the pipeline","enum":["sales","customer_success","onboarding","renewal","support","custom"]},"default":{"type":"boolean","description":"Whether this is the default pipeline for the account"},"settings":{"type":"object","description":"Arbitrary pipeline settings (e.g. selected/required field ids)","additionalProperties":true}},"required":["name"]},"crm_stage_payload":{"type":"object","properties":{"name":{"type":"string","description":"The name of the stage","example":"Qualified"},"color":{"type":"string","description":"Hex color code for the stage","example":"#1f93ff"},"position":{"type":"number","description":"The sort position within the pipeline"},"stage_type":{"type":"string","description":"The type of the stage (e.g. open, won, lost)","enum":["open","won","lost"]},"probability":{"type":"number","description":"Win probability (0-100) for weighted forecasting"},"sla_in_hours":{"type":"number","description":"SLA in hours for time-in-stage"}},"required":["name"]},"crm_item_payload":{"type":"object","properties":{"title":{"type":"string","description":"The title of the deal","example":"Acme Corp - Annual contract"},"description":{"type":"string","description":"The description of the deal"},"value_amount":{"type":"number","description":"The monetary value of the deal"},"currency":{"type":"string","description":"The ISO currency code of value_amount","example":"USD"},"priority":{"type":"string","description":"The priority (low, medium, high, urgent)","enum":["low","medium","high","urgent","normal"]},"expected_close_on":{"type":"string","format":"date","description":"The expected close date"},"opened_at":{"type":"string","format":"date-time","description":"The editable business opening date (defaults to the creation time)"},"closed_at":{"type":"string","format":"date-time","description":"The won/lost close date. On create, applies only when stage_id is a won/lost stage and defaults to the current time when omitted. Editable after close."},"close_reason":{"type":"string","description":"The close reason. Required for a terminal-stage create when the selected pipeline enables require_close_reason; ignored for an open-stage create."},"pipeline_id":{"type":"number","description":"The pipeline to place the deal in"},"stage_id":{"type":"number","description":"The stage to place the deal in. A won/lost stage derives the matching initial lifecycle status."},"contact_id":{"type":"number","description":"The contact to link"},"conversation_id":{"type":"number","description":"The conversation to link (accepts display_id or global id)"},"organization_id":{"type":"number","description":"The organization to link"},"crm_organization_id":{"type":"number","description":"Deprecated legacy alias of organization_id (still accepted; mapped to the same link)"},"assignee_id":{"type":"number","description":"The agent to assign"},"team_id":{"type":"number","description":"The team to assign"},"custom_attributes":{"type":"object","description":"Custom attributes (pipeline-defined fields)","additionalProperties":true},"additional_attributes":{"type":"object","description":"Additional system attributes","additionalProperties":true},"participant_ids":{"type":"array","description":"User IDs of deal collaborators","items":{"type":"number"}}},"required":["title"]},"crm_note_payload":{"type":"object","properties":{"content":{"type":"string","description":"The note body","example":"Customer requested a follow-up call next week"}},"required":["content"]},"crm_checklist_item_payload":{"type":"object","description":"The editable fields of a checklist item. Completion is NOT set here — flip it with `PATCH .../checklist_items/{id}/toggle` (which also stamps who completed it); ordering is changed with `PATCH .../checklist_items/{id}/reposition`. Any other key sent in this body is ignored.","properties":{"title":{"type":"string","description":"The checklist item title","example":"Send proposal"},"assignee_id":{"type":"number","description":"The agent to assign","example":12},"due_on":{"type":"string","format":"date","description":"The due date","example":"2026-08-15"}},"required":["title"]},"crm_organization_payload":{"type":"object","properties":{"name":{"type":"string","description":"The organization display name","example":"Acme Corp"},"legal_name":{"type":"string","description":"The registered legal name (razão social)","example":"Acme Corporation LTDA"},"legal_type":{"type":"string","enum":["individual","business"],"description":"Whether the organization is a natural person (individual) or a legal entity (business)","example":"business"},"tax_id":{"type":"string","description":"The raw fiscal identifier; validated against tax_id_type/country and stored encrypted. Responses return it real to a human agent, masked under a role field rule or for a bot.","example":"12.345.678/0001-95"},"tax_id_type":{"type":"string","enum":["br_cpf","br_cnpj","us_ein","eu_vat","uk_vat","generic"],"description":"The fiscal identifier scheme; auto-detected from country when omitted","example":"br_cnpj"},"country":{"type":"string","description":"ISO 3166-1 alpha-2 country code (drives fiscal-id detection and masking)","example":"BR"},"domain":{"type":"string","description":"The primary web domain","example":"acme.com"},"domains":{"type":"array","description":"All web domains; mark exactly one entry as primary","items":{"type":"object","properties":{"domain":{"type":"string","description":"The web domain","example":"acme.com"},"primary":{"type":"boolean","description":"Whether this is the primary domain","example":true}}}},"website":{"type":"string","description":"The organization website URL","example":"https://acme.com"},"avatar":{"type":"string","format":"binary","description":"The organization logo. Send it as the form-data binary (multipart request, field organization[avatar]) or use avatar_url instead."},"avatar_url":{"type":"string","description":"URL of an image to use as the organization logo. Fetched ASYNCHRONOUSLY after the record is saved (SSRF-filtered), so the logo may appear a moment after the response.","example":"https://cdn.example.com/orgs/42.png"},"industry":{"type":"string","description":"Free-form industry label","example":"SaaS"},"size":{"type":"string","description":"Company-size band. Prefer the canonical range keys (1-10, 11-50, 51-200, 201-500, 501-1000, 1001-5000, 5000+) so segment filters match; any other string is accepted and preserved.","example":"11-50"},"lifecycle_stage":{"type":"string","description":"Free-form lifecycle stage label","example":"customer"},"parent_id":{"type":"number","description":"The parent organization ID (matriz); cycles are rejected"},"owner_id":{"type":"number","description":"The agent (user) who owns this organization"},"email":{"type":"string","description":"The main contact email","example":"contato@acme.com"},"phone":{"type":"string","description":"The main contact phone","example":"+5511999999999"},"address":{"type":"object","additionalProperties":false,"description":"Postal address components — canonical snake_case keys shared with the payment gateways. The write MERGES over the stored map: a key you do not send keeps its stored value, a key sent blank clears it. Unknown keys are dropped. Common aliases (zipCode, cep, street, number, state, uf, district) are canonicalized instead of being silently discarded.","properties":{"zip_code":{"type":"string","description":"Postal code (CEP in Brazil)","example":"13338-705"},"street_name":{"type":"string","description":"Street/avenue name (logradouro)","example":"Av. Paulista"},"street_number":{"type":"string","description":"Street number","example":"1000"},"complement":{"type":"string","description":"Complement (apartment, block, suite)","example":"Sala 42"},"neighborhood":{"type":"string","description":"Neighborhood (bairro)","example":"Bela Vista"},"city":{"type":"string","description":"City","example":"Indaiatuba"},"federal_unit":{"type":"string","description":"State/federal unit; the 2-letter UF in Brazil","example":"SP"}},"example":{"zip_code":"13338-705","street_name":"Av. Paulista","street_number":"1000","complement":"Sala 42","neighborhood":"Bela Vista","city":"Indaiatuba","federal_unit":"SP"}},"registrations":{"type":"object","additionalProperties":false,"description":"Fiscal registration numbers. Same merge semantics as address.","properties":{"state_registration":{"type":"string","description":"Brazilian Inscrição Estadual (IE); \"ISENTO\" when exempt","example":"110042490114"},"municipal_registration":{"type":"string","description":"Brazilian Inscrição Municipal (IM)","example":"1234567"}},"example":{"state_registration":"110042490114","municipal_registration":"1234567"}},"timezone":{"type":"string","description":"IANA timezone","example":"America/Sao_Paulo"},"description":{"type":"string","description":"The organization description"},"custom_attributes":{"type":"object","description":"Account-defined custom attributes for organizations","additionalProperties":true},"additional_attributes":{"type":"object","description":"Additional system attributes","additionalProperties":true}},"required":["name"]},"crm_item_move_payload":{"type":"object","properties":{"stage_id":{"type":"number","description":"The target stage (must belong to the item's pipeline)"},"position":{"type":"number","description":"The sort position within the target stage"}},"required":["stage_id"]},"crm_item_reposition_payload":{"type":"object","properties":{"position":{"type":"number","description":"The new sort position within the current stage"}},"required":["position"]},"crm_item_transfer_payload":{"type":"object","properties":{"pipeline_id":{"type":"number","description":"The target pipeline to transfer the deal into"}},"required":["pipeline_id"]},"crm_item_status_payload":{"type":"object","properties":{"status":{"type":"string","description":"The status transition to apply","enum":["won","lost","reopen"]}},"required":["status"]},"crm_item_bulk_ids_payload":{"type":"object","description":"A list of CRM item IDs to operate on (capped at 500 per request).","properties":{"item_ids":{"type":"array","description":"The CRM item IDs to operate on","items":{"type":"number"}}},"required":["item_ids"]},"crm_item_bulk_update_payload":{"type":"object","description":"Bulk edit of shared fields across a selection of CRM items.","properties":{"item_ids":{"type":"array","description":"The CRM item IDs to update (capped at 500 per request)","items":{"type":"number"}},"fields":{"type":"object","description":"The shared fields to apply; nil values are ignored","properties":{"priority":{"type":"string","description":"The priority (low, medium, high, urgent)","enum":["low","medium","high","urgent","normal"]},"assignee_id":{"type":"number","description":"The agent to assign"},"team_id":{"type":"number","description":"The team to assign"}}}},"required":["item_ids","fields"]},"catalog_product":{"type":"object","properties":{"id":{"type":"number","description":"Product ID"},"account_id":{"type":"number"},"name":{"type":"string","description":"Product or service name"},"description":{"type":"string"},"kind":{"type":"string","enum":["product","service"],"description":"Physical product or service"},"status":{"type":"string","enum":["draft","active","archived"],"description":"Publication status (orthogonal to soft-delete)"},"slug":{"type":"string"},"position":{"type":"number"},"external_id":{"type":"string","description":"Stable ID from an external system (import/sync idempotency)"},"external_source":{"type":"string","description":"Origin system key (import/sync idempotency)"},"catalog_category_id":{"type":"number"},"default_variant_id":{"type":"number"},"category_name":{"type":"string","description":"Denormalized category name"},"variants_count":{"type":"number"},"images_count":{"type":"number"},"attachments_count":{"type":"number"},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"additional_attributes":{"type":"object","additionalProperties":true,"description":"Channel- and source-specific metadata for this record (e.g. browser info, referer, social profile identifiers). The key set depends on the originating channel."},"archived_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"variants":{"type":"array","items":{"$ref":"#/components/schemas/catalog_variant"}}}},"catalog_variant":{"type":"object","additionalProperties":false,"required":["id","account_id","catalog_product_id","sku","name","price","currency","compare_at_price","track_inventory","stock_quantity","barcode","position","options","default","image_id","image","external_id","external_source","retailer_id","meta_validation","available","prices","created_at","updated_at"],"properties":{"id":{"type":"integer","description":"Variant identifier."},"account_id":{"type":"integer","description":"Account that owns the variant."},"catalog_product_id":{"type":"integer","description":"Parent product identifier."},"sku":{"type":["string","null"],"description":"Stock keeping unit."},"name":{"type":["string","null"],"description":"Variant label displayed to operators and customers."},"price":{"type":["number","null"],"description":"Base selling price in major currency units."},"currency":{"type":["string","null"],"maxLength":3,"description":"Base currency code."},"compare_at_price":{"type":["number","null"],"description":"Optional reference price shown struck through."},"track_inventory":{"type":"boolean","description":"Whether availability depends on stock_quantity."},"stock_quantity":{"type":["integer","null"],"description":"Current units on hand."},"barcode":{"type":["string","null"],"description":"Optional EAN","UPC or other barcode.":null},"position":{"type":"integer","minimum":0,"description":"Zero-based display order inside the product."},"options":{"type":"object","description":"Named option values for this exact sellable combination, such as Color and Size.","maxProperties":20,"propertyNames":{"minLength":1,"maxLength":100},"additionalProperties":{"type":"string","minLength":1,"maxLength":200}},"default":{"type":"boolean","description":"Whether this is the product's active default variant."},"image_id":{"type":["integer","null"],"description":"Explicit image from this product's gallery; null uses the primary image."},"image":{"type":["object","null"],"additionalProperties":false,"description":"Resolved image, including the primary-image fallback; null when the product has no image.","required":["id","alt_text","primary","file_url","thumb_url"],"properties":{"id":{"type":"integer"},"alt_text":{"type":["string","null"]},"primary":{"type":"boolean"},"file_url":{"type":"string"},"thumb_url":{"type":"string"}}},"external_id":{"type":["string","null"],"description":"Identifier on the source platform; null for a native variant."},"external_source":{"type":["string","null"],"description":"Source platform key; null for a native variant."},"retailer_id":{"type":["string","null"],"description":"Stable Meta retailer identity, minted when outbound publication begins."},"meta_validation":{"type":"object","description":"Latest Meta validation state keyed by the catalog source's stable external key.","additionalProperties":{"type":"object","additionalProperties":false,"properties":{"status":{"type":"string","enum":["pending","validated","deleted","rejected","unknown","blocked"]},"error":{"type":["string","null"]},"handle":{"type":["string","null"]},"checked_at":{"type":["string","null"],"format":"date-time"},"source_name":{"type":["string","null"],"description":"Operator-facing name of the catalog source that owns this key. Null when the source was removed after the check; the map key remains the stable machine identity."}}}},"available":{"type":"boolean","description":"Always true without inventory tracking; otherwise true only while stock remains."},"prices":{"type":"array","description":"Per-currency overrides of the base price.","items":{"type":"object","additionalProperties":false,"required":["id","currency","amount","compare_at_amount"],"properties":{"id":{"type":"integer"},"currency":{"type":"string"},"amount":{"type":"number"},"compare_at_amount":{"type":["number","null"]}}}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"catalog_category":{"type":"object","properties":{"id":{"type":"number"},"account_id":{"type":"number"},"parent_id":{"type":["number","null"]},"name":{"type":"string"},"slug":{"type":"string"},"position":{"type":"number"},"products_count":{"type":"number"},"depth":{"type":"number","description":"1-based depth (root = 1, max 4)"},"external_id":{"type":"string"},"external_source":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"catalog_sync_source":{"type":"object","properties":{"id":{"type":"number"},"account_id":{"type":"number"},"name":{"type":"string"},"source_type":{"type":"string","enum":["generic","shopify","woocommerce","magento","prestashop","medusa","local","meta_catalog","nuvemshop","mercado_livre","hotmart","kiwify","olx"],"description":"Connector that drives this feed. Any unmapped value falls back to the generic HTTP connector; meta_catalog binds a WhatsApp Business Catalog."},"direction":{"type":"string","enum":["inbound","outbound","bidirectional"]},"status":{"type":"string","enum":["disabled","enabled"]},"schedule_minutes":{"type":"integer","minimum":5},"settings":{"$ref":"#/components/schemas/catalog_sync_source_settings"},"last_synced_at":{"type":["string","null"],"format":"date-time"},"last_pushed_at":{"type":["string","null"],"format":"date-time","description":"Last time the outbound repair scheduler or a manual push queued this source."},"last_status":{"type":["string","null"],"enum":["pending","processing","completed","failed","partial",null],"description":"Outcome of the most recent sync run (null before the first run)."},"last_error":{"type":["string","null"],"description":"Sanitized diagnostic from the latest run; authentication material is removed. It is that run's `error`, copied as is: a product pull may therefore carry several diagnostics joined by ` | `, to be read by the same rule (only leading parts that are exactly a known code stand on their own; the first part that is not takes the rest of the string). To know whether the page limit was reached, read `stats.truncated` rather than comparing this string."},"stats":{"type":"object","additionalProperties":false,"description":"Allowlisted counters and item ledgers of the most recent run, serialized by the same allowlist as the run's own `stats`. A key is present only when that run recorded it.","properties":{"total":{"type":"integer","minimum":0},"scanned":{"type":"integer","minimum":0,"description":"Sales-history import — records read from the provider."},"selected":{"type":"integer","minimum":0,"description":"Sales-history import — records that matched the requested selection."},"created":{"type":"integer","minimum":0},"updated":{"type":"integer","minimum":0},"skipped":{"type":"integer","minimum":0},"failed":{"type":"integer","minimum":0},"repaired":{"type":"integer","minimum":0},"meta_validated":{"type":"integer","minimum":0},"meta_rejected":{"type":"integer","minimum":0,"description":"Variations the asynchronous Meta validation rejected."},"dry_run":{"type":"boolean"},"truncated":{"type":"boolean","description":"True when the run stopped at the page limit before reading the whole source."},"failed_ids":{"type":"array","maxItems":500,"description":"Records the run could not persist; a product pull names at most the first 50.","items":{"type":"object","additionalProperties":false,"required":["external_id"],"properties":{"external_id":{"type":"string","maxLength":200},"name":{"type":"string","maxLength":200,"description":"Present only when the run recorded one."},"reason":{"type":"string","maxLength":120,"description":"Omitted when there is none, never null."}}}},"warning_ids":{"type":"array","maxItems":500,"description":"Catalog records that were synced but whose identity at the source deserves a look.","items":{"type":"object","additionalProperties":false,"required":["external_id"],"properties":{"external_id":{"type":"string","maxLength":200},"name":{"type":"string","maxLength":200,"description":"Present only when the run recorded one."},"reason":{"type":"string","maxLength":120,"description":"Omitted when there is none, never null."}}}},"skipped_ids":{"type":"array","maxItems":500,"items":{"type":"object","additionalProperties":false,"required":["external_id"],"properties":{"external_id":{"type":"string","maxLength":200},"name":{"type":"string","maxLength":200,"description":"Present only when the run recorded one."},"reason":{"type":"string","maxLength":120,"description":"Omitted when there is none, never null."}}}}}},"capabilities":{"type":"object","additionalProperties":true,"description":"Server-derived connector capability matrix used to gate supported controls."},"meta_catalog":{"type":"boolean"},"event_map":{"type":"object","additionalProperties":{"type":"string"},"description":"Effective external-event to canonical-stage mapping when the connector supports it."},"environment":{"type":"string","enum":["production","sandbox"],"description":"Present only for management-capable connectors that expose environments."},"external_source_key":{"type":["string","null"]},"inbound_url":{"type":"string","description":"HMAC-authenticated bulk-upsert endpoint"},"commerce_webhook_url":{"type":"string","description":"Present only for webhook-capable commerce connectors."},"webhook_configured":{"type":"boolean","description":"Indicates that a write-only platform webhook secret is stored; the value is never serialized."},"access_token_preview":{"type":"string","description":"Masked inbound sync secret returned by ordinary reads."},"access_token":{"type":"string","description":"Full inbound sync secret returned only on create or rotation and revealed once by the UI."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"catalog_sync_source_settings":{"type":"object","additionalProperties":false,"description":"Closed, source-specific configuration contract. Unknown keys are discarded by the write endpoint. Authentication secrets supplied in `auth` are accepted only for legacy compatibility, migrated to encrypted credentials and never returned.","properties":{"external_source":{"type":"string"},"http_method":{"type":"string","enum":["get","post"]},"base_url":{"type":"string","format":"uri"},"products_path":{"type":"string"},"products_root":{"type":"string"},"format":{"type":"string","enum":["json","ndjson","xml","csv","tsv"]},"request_body":{"type":"string"},"catalog_id":{"type":"string"},"phone_number_id":{"type":"string"},"waba_id":{"type":"string"},"inbox_id":{"type":"integer","minimum":1},"store_id":{"type":"string"},"user_id":{"type":"string"},"user_agent":{"type":"string"},"environment":{"type":"string","enum":["production","sandbox"]},"api_version":{"type":"string"},"base_host":{"type":"string","format":"uri"},"locale":{"type":"string"},"mapping":{"type":"object","additionalProperties":false,"description":"Local catalog field to the external record's dot path or XPath.","properties":{"name":{"type":"string"},"external_id":{"type":"string"},"description":{"type":"string"},"slug":{"type":"string"},"status":{"type":"string","description":"Dot path or XPath of the provider's source-status field; this is not a local catalog status enum."},"category":{"type":"string"},"price":{"type":"string"},"compare_at_price":{"type":"string"},"currency":{"type":"string"},"sku":{"type":"string"},"stock":{"type":"string"},"brand":{"type":"string"},"external_url":{"type":"string"},"variants":{"type":"string"},"images":{"type":"string"},"attachments":{"type":"string"},"kind":{"type":"string","description":"Dot path or XPath of the provider's source-kind field; this is not a local catalog kind enum."},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."}}},"auth":{"type":"object","additionalProperties":false,"properties":{"type":{"type":"string","enum":["none","bearer","header","basic","query"]},"header":{"type":"string"},"param":{"type":"string"},"user_agent":{"type":"string"},"token":{"type":"string","writeOnly":true,"deprecated":true},"username":{"type":"string","writeOnly":true,"deprecated":true},"password":{"type":"string","format":"password","writeOnly":true,"deprecated":true}}},"pagination":{"type":"object","additionalProperties":false,"properties":{"style":{"type":"string","enum":["link","page","cursor","none"]},"param":{"type":"string"},"cursor_path":{"type":"string"}}},"generic_webhook":{"type":"object","additionalProperties":false,"description":"Explicit, provider-neutral signed commerce ingress and durable catalog egress configuration.","properties":{"event_path":{"type":"string","default":"event"},"external_id_path":{"type":"string","default":"id"},"amount_path":{"type":"string"},"currency_path":{"type":"string"},"payment_method_path":{"type":"string"},"checkout_url_path":{"type":"string"},"contact_email_path":{"type":"string"},"contact_name_path":{"type":"string"},"contact_phone_path":{"type":"string"},"product_id_path":{"type":"string"},"product_name_path":{"type":"string"},"product_sku_path":{"type":"string"},"variation_id_path":{"type":"string"},"variation_name_path":{"type":"string"},"variation_sku_path":{"type":"string"},"items_path":{"type":"string"},"item_id_path":{"type":"string"},"item_product_id_path":{"type":"string"},"item_variant_id_path":{"type":"string"},"item_name_path":{"type":"string"},"item_sku_path":{"type":"string"},"item_quantity_path":{"type":"string"},"item_unit_price_path":{"type":"string"},"item_total_price_path":{"type":"string"},"item_currency_path":{"type":"string"},"replay_window_seconds":{"type":"integer","minimum":60,"maximum":86400,"default":300},"outbound_url":{"type":"string","format":"uri","maxLength":2048,"description":"HTTP(S) destination without URL credentials, query parameters or fragment; authentication uses the shared HMAC secret."},"events":{"type":"object","maxProperties":100,"description":"Operator-defined external event names mapped to a canonical commerce stage or ignore.","additionalProperties":{"type":"string","enum":["cart_abandoned","order_placed","payment_pending","payment_confirmed","payment_declined","overdue","due_soon","refunded","chargeback","subscription_late","subscription_canceled","ignore"]}}}},"hotmart":{"type":"object","additionalProperties":false,"properties":{"events":{"type":"object","additionalProperties":false,"properties":{"PURCHASE_APPROVED":{"type":"string"},"PURCHASE_COMPLETE":{"type":"string"},"PURCHASE_CANCELED":{"type":"string"},"PURCHASE_EXPIRED":{"type":"string"},"PURCHASE_REFUNDED":{"type":"string"},"PURCHASE_CHARGEBACK":{"type":"string"},"PURCHASE_PROTEST":{"type":"string"},"PURCHASE_BILLET_PRINTED":{"type":"string"},"PURCHASE_DELAYED":{"type":"string"},"PURCHASE_OUT_OF_SHOPPING_CART":{"type":"string"},"SUBSCRIPTION_CANCELLATION":{"type":"string"},"SWITCH_PLAN":{"type":"string"},"UPDATE_SUBSCRIPTION_CHARGE_DATE":{"type":"string"},"CLUB_FIRST_ACCESS":{"type":"string"},"CLUB_MODULE_COMPLETED":{"type":"string"}}}}},"kiwify":{"type":"object","additionalProperties":false,"properties":{"events":{"type":"object","additionalProperties":false,"properties":{"compra_aprovada":{"type":"string"},"compra_recusada":{"type":"string"},"compra_reembolsada":{"type":"string"},"chargeback":{"type":"string"},"pix_gerado":{"type":"string"},"boleto_gerado":{"type":"string"},"carrinho_abandonado":{"type":"string"},"subscription_canceled":{"type":"string"},"subscription_late":{"type":"string"},"subscription_renewed":{"type":"string"}}}}},"nuvemshop":{"type":"object","additionalProperties":false,"properties":{"events":{"type":"object","additionalProperties":false,"properties":{"paid":{"type":"string"},"authorized":{"type":"string"},"pending":{"type":"string"},"refunded":{"type":"string"},"partially_refunded":{"type":"string"},"abandoned":{"type":"string"}}}}}}},"catalog_sync_run":{"type":"object","properties":{"id":{"type":"number"},"account_id":{"type":"number"},"catalog_sync_source_id":{"type":["number","null"]},"source_name":{"type":["string","null"]},"direction":{"type":"string","enum":["import","export","inbound","outbound"]},"trigger":{"type":"string","enum":["manual","scheduled","webhook","api","event","backfill","hotmart_sales_backfill","kiwify_sales_backfill","inventory_decrement"]},"status":{"type":"string","enum":["pending","processing","completed","failed","partial"]},"format":{"type":["string","null"]},"stats":{"type":"object","additionalProperties":false,"properties":{"total":{"type":"integer","minimum":0},"scanned":{"type":"integer","minimum":0,"description":"Sales-history import — records read from the provider."},"selected":{"type":"integer","minimum":0,"description":"Sales-history import — records that matched the requested selection."},"created":{"type":"integer","minimum":0},"updated":{"type":"integer","minimum":0},"skipped":{"type":"integer","minimum":0},"failed":{"type":"integer","minimum":0},"repaired":{"type":"integer","minimum":0},"meta_validated":{"type":"integer","minimum":0},"meta_rejected":{"type":"integer","minimum":0,"description":"Variations the asynchronous Meta validation rejected."},"dry_run":{"type":"boolean"},"truncated":{"type":"boolean"},"failed_ids":{"type":"array","maxItems":500,"description":"Records the run could not persist. The `failed` counter is exact; a product pull names at most the first 50 of them here.","items":{"type":"object","additionalProperties":false,"required":["external_id"],"properties":{"external_id":{"type":"string","maxLength":200,"description":"Remote id of the record; a catalog record without one is identified by its slug or name."},"name":{"type":"string","maxLength":200,"description":"Product name as sent by the source. Present only on catalog product runs."},"reason":{"type":"string","maxLength":120,"description":"Omitted when there is none, never null. Stable reason code. Catalog product runs use `record_invalid` (rejected by validation), `record_duplicate` (conflicts with another catalog item) and `record_rejected` (a value the database refused) and `identity_unresolved` (another live product may own the same slug and the feed was not read in full — or the run failed before it was — so nothing was written); sales and inventory runs use their own codes."}}}},"warning_ids":{"type":"array","maxItems":500,"description":"Catalog records that were synced but whose identity at the source deserves a look. A product run names at most the first 50. A shared record is listed on every run; the run only ends `partial` with `catalog_sync_identity_review` when it lists a shared record the previous run of the same kind had not reported (a record that stops being shared never does).","items":{"type":"object","additionalProperties":false,"required":["external_id"],"properties":{"external_id":{"type":"string","maxLength":200,"description":"Remote id of the record; a catalog record without one is identified by its slug or name."},"name":{"type":"string","maxLength":200,"description":"Product name as sent by the source."},"reason":{"type":"string","maxLength":120,"description":"Omitted when there is none, never null. `identity_adopted` — the record took over the local product of another remote id that is absent from a feed read in full; `identity_shared` — it shares a local product with another live remote product, so only its variations that already belong to that product were updated. Both are reported only by pulls of a connector whose handle is the provider's own product identifier (Nuvemshop/Tiendanube); every other source and every inbound API batch keeps grouping records that repeat one slug or name, and never lists any."}}}},"skipped_ids":{"type":"array","maxItems":500,"items":{"type":"object","additionalProperties":false,"required":["external_id"],"properties":{"external_id":{"type":"string","maxLength":200},"name":{"type":"string","maxLength":200,"description":"Present only when the run recorded one."},"reason":{"type":"string","maxLength":120,"description":"Omitted when there is none, never null."}}}}}},"error":{"type":["string","null"],"description":"Sanitized run diagnostic; authentication material is removed. A stable machine code, optionally followed by `: \u003cdetail\u003e`. A `partial` product pull may carry `catalog_sync_page_limit_reached`, `catalog_sync_identity_review` (see `stats.warning_ids`) and `catalog_sync_public_url_unavailable` (products imported, the store's public link could not be derived). When a run has more than one of them they are all present, in that order, joined by ` | `. Read the string from the left: a part is a diagnostic of its own only while it, and every part before it, is exactly one of those codes; the first part that is not takes the whole rest of the string, whether it is a code followed by `: \u003cdetail\u003e` or the free-form message of a failed run. The detail and the failure message are free text that may come from the provider: a ` | ` inside them is replaced with ` / ` before any run is stored, and a code that appears after free text is never a diagnostic. Use `stats.truncated`, not this string, to know whether the page limit was reached."},"started_at":{"type":["string","null"],"format":"date-time"},"finished_at":{"type":["string","null"],"format":"date-time"},"window_from":{"type":["string","null"],"format":"date-time"},"window_to":{"type":["string","null"],"format":"date-time"},"undoable":{"type":"boolean"},"undone_at":{"type":["string","null"],"format":"date-time"},"undone_by_id":{"type":["integer","null"],"minimum":1},"inventory_failure":{"type":"boolean","description":"True only for a terminal automatic stock-decrement failure."},"inventory_sale_type":{"type":["string","null"],"enum":["payment_charge","crm_order",null]},"inventory_sale_id":{"type":["integer","null"],"minimum":1},"inventory_retryable":{"type":"boolean","description":"Whether an administrator can enqueue the idempotent inventory retry now."},"result_file_url":{"type":["string","null"]},"error_file_url":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"task":{"type":"object","description":"A native task with assignees, labels, list, dates and counters.","properties":{"id":{"type":"number"},"account_id":{"type":"number"},"title":{"type":"string"},"description":{"type":"string"},"status":{"type":"string","enum":["backlog","todo","in_progress","in_review","done","cancelled"]},"priority":{"type":"string","enum":["none","low","medium","high","urgent"]},"start_on":{"type":"string","format":"date"},"due_at":{"type":"string","format":"date-time"},"completed_at":{"type":"string","format":"date-time"},"position":{"type":"number"},"task_list_id":{"type":"number","description":"The list/board this task belongs to (nullable)"},"parent_task_id":{"type":"number","description":"The parent task (subtask), nullable"},"recurrence":{"type":"object","description":"JSONB rrule ({ frequency, interval, until, count, days })","additionalProperties":true},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"comments_count":{"type":"number"},"attachments_count":{"type":"number"},"attachments":{"type":"array","description":"File attachments embedded by the task detail response.","items":{"type":"object","properties":{"id":{"type":"number"},"filename":{"type":["string","null"]},"byte_size":{"type":["number","null"]},"content_type":{"type":["string","null"]},"url":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"media_deleted":{"type":"boolean"}}}},"subtasks_count":{"type":"number"},"overdue":{"type":"boolean"},"labels":{"type":"array","items":{"type":"string"}},"assignees":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number"},"name":{"type":"string"},"thumbnail":{"type":"string"}}}},"archived":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"product_payload":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"description":{"type":"string"},"kind":{"type":"string","enum":["product","service"]},"status":{"type":"string","enum":["draft","active","archived"]},"catalog_category_id":{"type":"number"},"default_variant_id":{"type":["number","null"],"description":"Active variant of this same product used as the initial selection."},"slug":{"type":"string"},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"additional_attributes":{"type":"object","additionalProperties":true,"description":"Channel- and source-specific metadata for this record (e.g. browser info, referer, social profile identifiers). The key set depends on the originating channel."},"variants_attributes":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number"},"sku":{"type":"string"},"name":{"type":"string"},"price":{"type":"number"},"currency":{"type":"string"},"compare_at_price":{"type":"number"},"track_inventory":{"type":"boolean"},"stock_quantity":{"type":"number"},"barcode":{"type":"string"},"position":{"type":"number"},"options":{"type":"object","maxProperties":20,"additionalProperties":{"type":"string","minLength":1,"maxLength":200},"description":"Named option values for this exact variant combination."},"catalog_product_image_id":{"type":["number","null"],"description":"Image selected from this product's own gallery; null uses its primary image."},"default":{"type":"boolean","description":"Selects this nested row as the product default, including during product creation."},"_destroy":{"type":"boolean"}}}}}},"product_payload_wrapper":{"type":"object","properties":{"product":{"$ref":"#/components/schemas/product_payload"}}},"variant_payload":{"type":"object","additionalProperties":false,"description":"Attributes accepted when creating or partially updating one catalog variant.","properties":{"sku":{"type":["string","null"],"description":"Stock keeping unit; null clears the current value."},"name":{"type":["string","null"],"description":"Human-readable label for this exact sellable combination."},"price":{"type":["number","null"],"description":"Base selling price in major currency units; null leaves the variant unpriced."},"currency":{"type":["string","null"],"maxLength":3,"description":"Base currency code, stored in at most three characters."},"compare_at_price":{"type":["number","null"],"description":"Optional reference price shown struck through; null removes it."},"track_inventory":{"type":"boolean","description":"Whether availability depends on stock_quantity."},"stock_quantity":{"type":["integer","null"],"description":"Current units on hand; meaningful only when inventory tracking is enabled."},"barcode":{"type":["string","null"],"description":"Optional EAN, UPC or other barcode; null clears the current value."},"position":{"type":"integer","minimum":0,"description":"Zero-based display order inside the parent product."},"catalog_product_image_id":{"type":["integer","null"],"minimum":1,"description":"Image from this product's own gallery; null uses the product's primary image."},"default":{"type":"boolean","description":"When true, selects this active variant as the product default."},"options":{"type":"object","description":"Named text values for this exact combination. Names are unique ignoring case and surrounding whitespace is rejected.","maxProperties":20,"propertyNames":{"minLength":1,"maxLength":100},"additionalProperties":{"type":"string","minLength":1,"maxLength":200}},"prices_attributes":{"type":"array","description":"Nested per-currency price rows. Existing rows use id; `_destroy: true` removes that row.","items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"integer","minimum":1,"description":"Existing nested price identifier; omit when creating a row."},"currency":{"type":"string","minLength":1,"maxLength":3,"description":"Currency code for this override."},"amount":{"type":"number","description":"Selling price in major currency units."},"compare_at_amount":{"type":["number","null"],"description":"Optional reference price for this currency."},"_destroy":{"type":"boolean","description":"Removes the identified nested price row when true."}}}}}},"variant_payload_wrapper":{"type":"object","additionalProperties":false,"required":["variant"],"properties":{"variant":{"$ref":"#/components/schemas/variant_payload"}}},"category_payload":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"parent_id":{"type":"number"},"position":{"type":"number"}}},"category_payload_wrapper":{"type":"object","properties":{"category":{"$ref":"#/components/schemas/category_payload"}}},"sync_source_payload":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"source_type":{"type":"string","enum":["generic","shopify","woocommerce","magento","prestashop","medusa","local","meta_catalog","nuvemshop","mercado_livre","hotmart","kiwify","olx"],"description":"Connector that drives this feed. Any unmapped value falls back to the generic HTTP connector; meta_catalog binds a WhatsApp Business Catalog."},"direction":{"type":"string","enum":["inbound","outbound","bidirectional"]},"status":{"type":"string","enum":["disabled","enabled"]},"schedule_minutes":{"type":"integer","minimum":5},"webhook_secret":{"type":"string","format":"password","writeOnly":true,"description":"Provider or generic-commerce webhook verification secret; encrypted and never serialized back."},"credentials":{"type":"object","additionalProperties":false,"writeOnly":true,"description":"Connector credentials accepted for encrypted storage and never serialized back.","properties":{"graph_token":{"type":"string"},"access_token":{"type":"string"},"store_id":{"type":"string"},"user_id":{"type":"string"},"client_id":{"type":"string"},"client_secret":{"type":"string","format":"password"},"account_id":{"type":"string"},"basic_token":{"type":"string","format":"password"},"sync_auth_token":{"type":"string","format":"password"},"sync_auth_username":{"type":"string"},"sync_auth_password":{"type":"string","format":"password"}}},"settings":{"$ref":"#/components/schemas/catalog_sync_source_settings"}}},"sync_source_payload_wrapper":{"type":"object","properties":{"sync_source":{"$ref":"#/components/schemas/sync_source_payload"}}},"custom_filter_create_update_payload":{"type":"object","properties":{"name":{"type":"string","description":"The name of the custom filter","example":"My Custom Filter"},"filter_type":{"type":["string","integer"],"enum":["conversation","contact","report","crm_item","crm_report","catalog_product","catalog_report","task","organization",0,1,2,3,4,5,6,7,8],"description":"Which listing the saved filter applies to. Omitted on create, the filter is saved as a `conversation` filter. This is the field name the endpoint reads — a payload that sends `type` instead has it silently ignored and falls back to `conversation`. Accepts either the name or its integer position, because both are in use by first-party clients; the values are positional and append-only, so a name always maps to the same number.","example":"conversation"},"query":{"type":"object","additionalProperties":true,"description":"The filter query to save (a payload array of condition groups — attribute_key, filter_operator, values and query_operator).","example":{}}}},"webhook_create_update_payload":{"type":"object","properties":{"url":{"type":"string","description":"The url where the events should be sent","example":"https://example.com/webhook"},"name":{"type":"string","description":"The name of the webhook"},"subscriptions":{"type":"array","items":{"type":"string","enum":["conversation_status_changed","conversation_updated","conversation_created","contact_created","contact_updated","contact_merged","contact_deleted","message_created","message_updated","webwidget_triggered","inbox_created","inbox_updated","conversation_typing_on","conversation_typing_off","crm_item_created","crm_item_updated","crm_item_stage_changed","crm_item_won","crm_item_lost","crm_item_assigned","crm_item_stale","crm_item_reopened","crm_item_priority_changed","crm_item_value_changed","crm_item_health_changed","crm_item_checklist_completed","crm_item_sla_breached","crm_item_close_date_approaching","crm_item_close_date_overdue","whatsapp_group_participant_added","whatsapp_group_participant_removed","whatsapp_group_participant_promoted","whatsapp_group_participant_demoted","whatsapp_group_joined","whatsapp_group_join_request_received","whatsapp_group_info_changed","catalog_product_created","catalog_product_updated","catalog_product_archived","catalog_product_checklist_completed","catalog_variant_low_stock","catalog_variant_out_of_stock","crm_item_quote_total_changed","task_created","task_updated","task_status_changed","task_assigned","task_completed","task_reopened","task_overdue","task_due_soon","task_comment_added","task_unblocked","task_checklist_completed","payment_charge_created","payment_charge_confirmed","payment_charge_paid","payment_charge_partially_refunded","payment_charge_partially_paid","payment_charge_overdue","payment_charge_refunded","payment_charge_failed","payment_charge_canceled","payment_charge_payment_reversed","payment_subscription_created","payment_subscription_renewed","payment_subscription_canceled","payment_subscription_payment_failed","payment_installment_plan_created","payment_installment_plan_installment_paid","payment_installment_plan_installment_overdue","payment_installment_plan_completed","payment_installment_plan_canceled","commerce_cart_abandoned","commerce_order_placed","commerce_payment_pending","commerce_payment_confirmed","commerce_payment_declined","commerce_overdue","commerce_due_soon","commerce_refunded","commerce_chargeback","commerce_subscription_late","commerce_subscription_canceled","commerce_card_delivery","calendar_event_created","calendar_event_updated","calendar_event_rescheduled","calendar_event_cancelled","calendar_event_reminder_due","calendar_event_no_show","calendar_booking_created","calendar_booking_rescheduled","calendar_booking_cancelled","calendar_booking_payment_pending","calendar_booking_paid","calendar_booking_expired","calendar_booking_slot_lost","calendar_sync_failed","calendar_connection_connected","calendar_connection_revoked","follow_up_enrollment_created","follow_up_enrollment_paused","follow_up_enrollment_resumed","follow_up_enrollment_exited","follow_up_enrollment_completed","follow_up_enrollment_failed","follow_up_step_sent","follow_up_step_replied","follow_up_step_skipped","follow_up_step_failed","follow_up_draft_pending","brain_risk_changed","brain_insight_created","brain_department_run_completed","brain_improvement_proposed","routing_assigned","distribution_member_enrolled","distribution_member_invited","distribution_member_added","distribution_member_joined","distribution_member_left","distribution_member_removed","distribution_member_failed","distribution_unit_created","distribution_unit_opened","distribution_unit_full","distribution_completed","social_comment_captured","ads_lead_captured","sales_goal_reached","sales_tier_reached","sales_team_reward_granted","sales_deal_approval_requested","sales_deal_approval_approved","sales_deal_approval_rejected","sales_deal_floor_breached","sales_points_reversed","sales_contest_settled","sales_commission_accrued","sales_portfolio_transferred","sales_badge_awarded","sales_owner_changed","order_registered","order_status_changed","order_paid","order_refund_adjusted","order_refunded","order_payment_reversed","deal_orders_fully_paid","engagement_event_tracked","lead_score_changed","contract_created","contract_sent","contract_viewed","contract_signer_signed","contract_signed","contract_rejected","contract_expired","contract_voided","contract_document_generated","revenue_paid","affiliate_registered","affiliate_attributed","affiliate_commission_accrued","order_reattributed","wfm_status_changed","wfm_break_started","wfm_break_ended","wfm_break_breached","wfm_shift_started","wfm_shift_ended","whatsapp_broadcast_started","whatsapp_broadcast_completed","whatsapp_broadcast_failed","whatsapp_group_member_welcomed","whatsapp_group_member_farewelled","ads_campaign_status_changed","ctwa_conversation_started","ad_window_expiring","whatsapp_call_started","whatsapp_call_ended","whatsapp_call_recording_ready","whatsapp_flow_response_received","flow_session_started","flow_session_updated","flow_session_completed","flow_session_failed","organization_created","organization_updated","organization_archived","organization_membership_created","organization_membership_updated","organization_membership_removed","organization_relationship_created","message_schedule_created","message_schedule_published","message_schedule_paused","message_schedule_resumed","message_schedule_canceled","message_schedule_archived","message_schedule_completed","message_schedule_needs_attention","message_schedule_occurrence_scheduled","message_schedule_occurrence_dispatching","message_schedule_occurrence_queued","message_schedule_occurrence_retry_scheduled","message_schedule_occurrence_sent","message_schedule_occurrence_delivered","message_schedule_occurrence_read","message_schedule_occurrence_skipped","message_schedule_occurrence_failed","message_schedule_occurrence_canceled","message_schedule_occurrence_needs_attention"]},"description":"The events you want to subscribe to. Each key is a stable technical id; events are grouped by module family with human-readable names in the dashboard and Help Center — Conversation, Contact, CRM (deals), WhatsApp Groups, Catalog, Tasks, Payments, Commerce, Calendar \u0026 Booking, Follow-up, Account Brain, Routing, Distribution, Social \u0026 Ads (including CTWA — Click-to-WhatsApp — and Meta conversions), Sales, Orders, Engagement \u0026 Lead Score, Contracts, Revenue \u0026 Affiliates, Team Management, WhatsApp Broadcast, WhatsApp Calls \u0026 Flows, Flow sessions, and Message Scheduling. Event families whose account feature flag is off never fire.","example":["conversation_created","conversation_status_changed"]},"include_commerce_details":{"type":"boolean","default":false,"description":"Explicitly opt in to normalized buyer, product/variation and sale-item details on commerce-event deliveries. Omit it or send false to retain the default privacy-minimal identifier payload."}}},"integrations_hook_create_payload":{"type":"object","properties":{"app_id":{"type":"integer","description":"The ID of app for which integration hook is being created","example":1},"inbox_id":{"type":"integer","description":"The inbox ID, if the hook is an inbox hook","example":1},"status":{"type":"integer","description":"The status of the integration (0 for inactive, 1 for active)","example":1},"settings":{"type":"object","additionalProperties":true,"description":"The settings required by the integration (integration-specific keys such as API tokens, webhook URLs and reference IDs).","example":{}}}},"integrations_hook_update_payload":{"type":"object","properties":{"status":{"type":"integer","description":"The status of the integration (0 for inactive, 1 for active)","example":1},"settings":{"type":"object","additionalProperties":true,"description":"The settings required by the integration (integration-specific keys such as API tokens, webhook URLs and reference IDs).","example":{}}}},"automation_rule_create_update_payload":{"type":"object","properties":{"name":{"type":"string","description":"Rule name","example":"Add label on message create event"},"description":{"type":"string","description":"The description about the automation and actions","example":"Add label support and sales on message create event if incoming message content contains text help"},"event_name":{"type":"string","example":"message_created","description":"Native automation event, including crm_item_stage_changed. The server validates the registered event and action compatibility."},"active":{"type":"boolean","description":"Enable/disable automation rule"},"execution_delay":{"type":["integer","null"],"minimum":10,"maximum":43200,"description":"Delay in minutes. Requires delayed_automations when setting a non-null value. For crm_item_stage_changed, the deal must remain in the destination stage and still match the conditions at execution. Pausing the feature preserves pending work; editing or disabling the rule cancels pending actions. Completed actions are not replayed. Delayed work older than three days after its due time is marked expired."},"actions":{"type":"array","description":"Array of actions which you want to perform when condition matches, e.g add label support if message contains content help.","items":{"type":"object","additionalProperties":true,"description":"A single automation action (an action_name and its action_params).","example":{"action_name":"add_label","action_params":["support"]}}},"conditions":{"type":"array","description":"Array of conditions on which conversation filter would work, e.g message content contains text help.","items":{"type":"object","additionalProperties":true,"description":"A single automation condition (attribute_key, filter_operator, values and query_operator).","example":{"attribute_key":"content","filter_operator":"contains","query_operator":"OR","values":["help"]}}}}},"portal_create_update_payload":{"type":"object","additionalProperties":false,"required":["portal"],"properties":{"portal":{"type":"object","additionalProperties":false,"minProperties":1,"properties":{"id":{"type":"integer","minimum":1,"description":"Legacy portal identifier accepted by the controller.","example":123},"color":{"type":"string","description":"Header color for the help center in hex format.","example":"#FFFFFF"},"custom_domain":{"type":"string","description":"Custom domain used to display the help center.","example":"help.example.com"},"header_text":{"type":"string","description":"Help center header.","example":"Handbook"},"homepage_link":{"type":"string","format":"uri","description":"Link to the main website.","example":"https://www.example.com/"},"name":{"type":"string","description":"Name of the portal.","example":"Handbook"},"page_title":{"type":"string","description":"Page title for the portal.","example":"Handbook"},"slug":{"type":"string","description":"Slug used in the portal URL.","example":"handbook"},"archived":{"type":"boolean","description":"Whether the portal is archived.","example":false},"config":{"type":"object","additionalProperties":false,"description":"Portal locale, layout, localization and social-profile configuration.","properties":{"default_locale":{"type":"string","example":"en"},"layout":{"type":"string","example":"classic"},"allowed_locales":{"type":"array","items":{"type":"string"},"example":["en","es"]},"draft_locales":{"type":"array","items":{"type":"string"},"example":["es"]},"social_profiles":{"type":"object","additionalProperties":false,"properties":{"facebook":{"type":"string","format":"uri"},"x":{"type":"string","format":"uri"},"instagram":{"type":"string","format":"uri"},"linkedin":{"type":"string","format":"uri"},"youtube":{"type":"string","format":"uri"},"tiktok":{"type":"string","format":"uri"},"github":{"type":"string","format":"uri"},"whatsapp":{"type":"string"}},"example":{"instagram":"https://www.instagram.com/exampleco"}},"locale_translations":{"type":"object","additionalProperties":{"type":"object","additionalProperties":false,"properties":{"name":{"type":"string"},"page_title":{"type":"string"},"header_text":{"type":"string"}}},"description":"Translation map keyed by locale code.","example":{"es":{"name":"Centro de ayuda","page_title":"Centro de ayuda","header_text":"¿Cómo podemos ayudar?"}}}},"example":{"allowed_locales":["en","es"],"default_locale":"en","layout":"classic"}}}},"blob_id":{"type":"string","minLength":1,"description":"Account-owned Active Storage signed identifier for the new portal logo. Numeric blob IDs are not accepted when creating a portal because there is no already-attached logo to replay safely."},"inbox_id":{"type":["integer","null"],"minimum":1,"description":"Account-owned web-widget inbox to associate, or null to clear the association."}},"example":{"portal":{"name":"Handbook","slug":"handbook","config":{"allowed_locales":["en","es"],"default_locale":"en"}},"inbox_id":15}},"portal_update_payload":{"type":"object","additionalProperties":false,"minProperties":1,"description":"Portal fields to update. A request may update normal portal attributes, attach a replacement logo, or do both. In particular, a logo-only update does not require a `portal` object.","properties":{"portal":{"type":"object","additionalProperties":false,"minProperties":1,"properties":{"id":{"type":"integer","minimum":1,"description":"Legacy portal identifier accepted by the controller.","example":123},"color":{"type":"string","description":"Header color for the help center in hex format.","example":"#FFFFFF"},"custom_domain":{"type":"string","description":"Custom domain used to display the help center.","example":"help.example.com"},"header_text":{"type":"string","description":"Help center header.","example":"Handbook"},"homepage_link":{"type":"string","format":"uri","description":"Link to the main website.","example":"https://www.example.com/"},"name":{"type":"string","description":"Name of the portal.","example":"Handbook"},"page_title":{"type":"string","description":"Page title for the portal.","example":"Handbook"},"slug":{"type":"string","description":"Slug used in the portal URL.","example":"handbook"},"archived":{"type":"boolean","description":"Whether the portal is archived.","example":false},"config":{"type":"object","additionalProperties":false,"description":"Portal locale, layout, localization and social-profile configuration.","properties":{"default_locale":{"type":"string","example":"en"},"layout":{"type":"string","example":"classic"},"allowed_locales":{"type":"array","items":{"type":"string"},"example":["en","es"]},"draft_locales":{"type":"array","items":{"type":"string"},"example":["es"]},"social_profiles":{"type":"object","additionalProperties":false,"properties":{"facebook":{"type":"string","format":"uri"},"x":{"type":"string","format":"uri"},"instagram":{"type":"string","format":"uri"},"linkedin":{"type":"string","format":"uri"},"youtube":{"type":"string","format":"uri"},"tiktok":{"type":"string","format":"uri"},"github":{"type":"string","format":"uri"},"whatsapp":{"type":"string"}},"example":{"instagram":"https://www.instagram.com/exampleco"}},"locale_translations":{"type":"object","additionalProperties":{"type":"object","additionalProperties":false,"properties":{"name":{"type":"string"},"page_title":{"type":"string"},"header_text":{"type":"string"}}},"description":"Translation map keyed by locale code.","example":{"es":{"name":"Centro de ayuda","page_title":"Centro de ayuda","header_text":"¿Cómo podemos ayudar?"}}}},"example":{"allowed_locales":["en","es"],"default_locale":"en","layout":"classic"}}}},"blob_id":{"oneOf":[{"type":"string","minLength":1},{"type":"integer","minimum":1}],"description":"Account-owned Active Storage signed identifier for a new logo, or the numeric identifier of the logo already attached to this portal for an idempotent retry. Omit it when the logo is unchanged."},"inbox_id":{"type":["integer","null"],"minimum":1,"description":"Account-owned web-widget inbox to associate, or null to clear the association."}},"anyOf":[{"required":["portal"]},{"required":["blob_id"]}],"example":{"blob_id":"eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBBQT09In19--signed"}},"category_create_update_payload":{"type":"object","properties":{"name":{"type":"string","description":"The name of the category","example":"Category Name"},"description":{"type":"string","description":"A description for the category","example":"Category description"},"position":{"type":"integer","description":"Category position in the portal list to sort","example":1},"slug":{"type":"string","description":"The category slug used in the URL","example":"category-name"},"locale":{"type":"string","description":"The locale of the category","example":"en"},"icon":{"type":"string","description":"The icon of the category as a string (emoji)","example":"📚"},"parent_category_id":{"type":"integer","description":"To define parent category, e.g product documentation has multiple level features in sales category or in engineering category.","example":1},"associated_category_id":{"type":"integer","description":"To associate similar categories to each other, e.g same category of product documentation in different languages","example":2}}},"article_create_update_payload":{"type":"object","properties":{"title":{"type":"string","description":"The title of the article","example":"Article Title"},"slug":{"type":"string","description":"The slug of the article","example":"article-title"},"position":{"type":"integer","description":"article position in category","example":1},"content":{"type":"string","description":"The text content.","example":"This is the content of the article"},"description":{"type":"string","description":"The description of the article","example":"This is the description of the article"},"category_id":{"type":"integer","description":"The category id of the article","example":1},"author_id":{"type":"integer","description":"The author agent id of the article","example":1},"associated_article_id":{"type":"integer","description":"To associate similar articles to each other, e.g to provide the link for the reference.","example":2},"status":{"type":"integer","description":"The status of the article. 0 for draft, 1 for published, 2 for archived","example":1},"locale":{"type":"string","description":"The locale of the article","example":"en"},"meta":{"type":"object","additionalProperties":true,"description":"Free-form article metadata used for search and listing (e.g. tags, title and description).","example":{"tags":["article_name"],"title":"article title","description":"article description"}}}},"public_contact_create_update_payload":{"type":"object","properties":{"identifier":{"type":"string","description":"External identifier of the contact","example":"1234567890"},"identifier_hash":{"type":"string","description":"Identifier hash prepared for HMAC authentication","example":"e93275d4eba0e5679ad55f5360af00444e2a888df9b0afa3e8b691c3173725f9"},"email":{"type":"string","description":"Email of the contact","example":"alice@acme.inc"},"name":{"type":"string","description":"Name of the contact","example":"Alice"},"phone_number":{"type":"string","description":"Phone number of the contact","example":"+123456789"},"avatar":{"type":"string","format":"binary","description":"Send the form data with the avatar image binary or use the avatar_url"},"custom_attributes":{"type":"object","description":"Custom attributes of the customer","example":{},"additionalProperties":true}}},"public_message_create_payload":{"type":"object","properties":{"content":{"type":"string","description":"Content for the message","example":"Hello, how can I help you?"},"echo_id":{"type":"string","description":"Temporary identifier which will be passed back via websockets","example":"1234567890"}}},"public_message_update_payload":{"type":"object","properties":{"submitted_values":{"type":"object","description":"Replies to the Bot Message Types","properties":{"name":{"type":"string","description":"The name of the submiitted value","example":"My Name"},"title":{"type":"string","description":"The title of the submitted value","example":"My Title"},"value":{"type":"string","description":"The value of the submitted value","example":"value"},"csat_survey_response":{"type":"object","description":"The CSAT survey response","properties":{"feedback_message":{"type":"string","description":"The feedback message of the CSAT survey response","example":"Great service!"},"rating":{"type":"integer","description":"The rating of the CSAT survey response","example":5}}}}}}},"public_conversation_create_payload":{"type":"object","properties":{"custom_attributes":{"type":"object","description":"Custom attributes of the conversation","example":{},"additionalProperties":true}}},"extended_contact":{"allOf":[{"$ref":"#/components/schemas/contact"},{"type":"object","properties":{"id":{"type":"number","description":"Id of the user"},"availability_status":{"type":"string","enum":["online","offline"],"description":"Availability status of the user"}}}]},"contact_base":{"allOf":[{"$ref":"#/components/schemas/generic_id"},{"$ref":"#/components/schemas/contact"}]},"contact_labels":{"type":"object","properties":{"payload":{"type":"array","description":"Array of labels","items":{"type":"string"}}}},"conversation_list":{"type":"object","properties":{"data":{"type":"object","properties":{"meta":{"type":"object","properties":{"mine_count":{"type":"number"},"unassigned_count":{"type":"number"},"assigned_count":{"type":"number"},"all_count":{"type":"number"},"mine_unread_count":{"type":"number","description":"Conversations assigned to the current user with at least one unread incoming message, across every page of the list."},"unassigned_unread_count":{"type":"number","description":"Unassigned conversations with at least one unread incoming message, across every page of the list."},"all_unread_count":{"type":"number","description":"Conversations of the list with at least one unread incoming message, across every page."}}},"payload":{"type":"array","description":"array of conversations","items":{"allOf":[{"$ref":"#/components/schemas/generic_id"},{"$ref":"#/components/schemas/conversation"},{"type":"object","properties":{"meta":{"type":"object","properties":{"sender":{"type":"object","properties":{"additional_attributes":{"type":"object","description":"The additional attributes of the sender","additionalProperties":true},"availability_status":{"type":"string","description":"The availability status of the sender","enum":["online","offline","busy"]},"email":{"type":["string","null"],"description":"The email of the sender"},"id":{"type":"number","description":"ID fo the sender"},"name":{"type":"string","description":"The name of the sender"},"phone_number":{"type":["string","null"],"description":"The phone number of the sender"},"blocked":{"type":"boolean","description":"Whether the sender is blocked"},"identifier":{"type":["string","null"],"description":"The identifier of the sender"},"thumbnail":{"type":["string","null"],"description":"Avatar URL of the contact"},"custom_attributes":{"type":"object","description":"The custom attributes of the sender","additionalProperties":true},"last_activity_at":{"type":"number","description":"The last activity at of the sender"},"created_at":{"type":"number","description":"The created at of the sender"}}},"channel":{"type":"string","description":"Channel Type"},"assignee":{"$ref":"#/components/schemas/user"},"hmac_verified":{"type":"boolean","description":"Whether the hmac is verified"}}}}}]}}}}}},"conversation_show":{"description":"A single conversation with its contact and additional show-only attributes.","allOf":[{"$ref":"#/components/schemas/conversation"},{"type":"object","properties":{"meta":{"type":"object","properties":{"sender":{"type":"object","properties":{"additional_attributes":{"type":"object","description":"The additional attributes of the sender","additionalProperties":true},"availability_status":{"type":"string","description":"The availability status of the sender","enum":["online","offline","busy"]},"email":{"type":["string","null"],"description":"The email of the sender"},"id":{"type":"number","description":"ID fo the sender"},"name":{"type":"string","description":"The name of the sender"},"phone_number":{"type":["string","null"],"description":"The phone number of the sender"},"blocked":{"type":"boolean","description":"Whether the sender is blocked"},"identifier":{"type":["string","null"],"description":"The identifier of the sender"},"thumbnail":{"type":["string","null"],"description":"Avatar URL of the contact"},"custom_attributes":{"type":"object","description":"The custom attributes of the sender","additionalProperties":true},"last_activity_at":{"type":"number","description":"The last activity at of the sender"},"created_at":{"type":"number","description":"The created at of the sender"}}},"channel":{"type":"string","description":"Channel Type"},"assignee":{"$ref":"#/components/schemas/user"},"hmac_verified":{"type":"boolean","description":"Whether the hmac is verified"}}}}}]},"conversation_labels":{"type":"object","properties":{"payload":{"type":"array","description":"Array of labels","items":{"type":"string"}}}},"account_summary":{"type":"object","properties":{"avg_first_response_time":{"type":"string"},"avg_resolution_time":{"type":"string"},"conversations_count":{"type":"number"},"incoming_messages_count":{"type":"number"},"outgoing_messages_count":{"type":"number"},"resolutions_count":{"type":"number"},"previous":{"type":"object","properties":{"avg_first_response_time":{"type":"string"},"avg_resolution_time":{"type":"string"},"conversations_count":{"type":"number"},"incoming_messages_count":{"type":"number"},"outgoing_messages_count":{"type":"number"},"resolutions_count":{"type":"number"}}}}},"agent_conversation_metrics":{"type":"object","properties":{"id":{"type":"number"},"name":{"type":"string"},"email":{"type":"string"},"thumbnail":{"type":"string"},"availability":{"type":"string","enum":["online","offline","busy"],"description":"Availability of the agent."},"metric":{"type":"object","properties":{"open":{"type":"number"},"unattended":{"type":"number"}}}}},"channel_summary":{"type":"object","description":"Channel summary report containing conversation counts grouped by channel type and status. Available in version 4.10.0+.","additionalProperties":{"type":"object","description":"Conversation statistics for a specific channel type (e.g., Channel::WebWidget, Channel::Api)","properties":{"open":{"type":"number","description":"Number of open conversations"},"resolved":{"type":"number","description":"Number of resolved conversations"},"pending":{"type":"number","description":"Number of pending conversations"},"snoozed":{"type":"number","description":"Number of snoozed conversations"},"total":{"type":"number","description":"Total number of conversations"}}},"example":{"Channel::WebWidget":{"open":10,"resolved":20,"pending":5,"snoozed":2,"total":37},"Channel::Api":{"open":5,"resolved":15,"pending":3,"snoozed":1,"total":24}}},"first_response_time_distribution":{"type":"object","description":"First response time distribution report grouped by channel type. Shows the count of conversations with first response times in different time buckets.","additionalProperties":{"type":"object","description":"First response time distribution for a specific channel type (e.g., Channel::WebWidget, Channel::Api)","properties":{"0-1h":{"type":"number","description":"Number of conversations with first response time less than 1 hour"},"1-4h":{"type":"number","description":"Number of conversations with first response time between 1-4 hours"},"4-8h":{"type":"number","description":"Number of conversations with first response time between 4-8 hours"},"8-24h":{"type":"number","description":"Number of conversations with first response time between 8-24 hours"},"24h+":{"type":"number","description":"Number of conversations with first response time greater than 24 hours"}}},"example":{"Channel::WebWidget":{"0-1h":150,"1-4h":80,"4-8h":45,"8-24h":30,"24h+":15},"Channel::Api":{"0-1h":75,"1-4h":40,"4-8h":20,"8-24h":10,"24h+":5}}},"inbox_label_matrix":{"type":"object","description":"Inbox-label matrix report showing the count of conversations for each inbox-label combination.","properties":{"inboxes":{"type":"array","description":"List of inboxes included in the report","items":{"type":"object","properties":{"id":{"type":"number","description":"The inbox ID"},"name":{"type":"string","description":"The inbox name"}}}},"labels":{"type":"array","description":"List of labels included in the report","items":{"type":"object","properties":{"id":{"type":"number","description":"The label ID"},"title":{"type":"string","description":"The label title"}}}},"matrix":{"type":"array","description":"2D array where matrix[i][j] represents the count of conversations in inboxes[i] with labels[j]","items":{"type":"array","items":{"type":"number"}}}},"example":{"inboxes":[{"id":1,"name":"Website Chat"},{"id":2,"name":"Email Support"}],"labels":[{"id":1,"title":"bug"},{"id":2,"title":"feature-request"},{"id":3,"title":"urgent"}],"matrix":[[10,5,3],[8,12,2]]}},"outgoing_messages_count":{"type":"array","description":"Outgoing messages count report grouped by entity (agent, team, inbox, or label).","items":{"type":"object","properties":{"id":{"type":"number","description":"The ID of the grouped entity (agent, team, inbox, or label)."},"name":{"type":"string","description":"The name of the grouped entity."},"outgoing_messages_count":{"type":"number","description":"The total number of outgoing messages for this entity in the given time range."}}},"example":[{"id":1,"name":"Agent One","outgoing_messages_count":42},{"id":2,"name":"Agent Two","outgoing_messages_count":18}]},"inbox_summary":{"type":"array","description":"Inbox summary report containing conversation statistics grouped by inbox.","items":{"type":"object","properties":{"id":{"type":"number","description":"The inbox ID"},"conversations_count":{"type":"number","description":"Number of conversations created in the inbox during the date range"},"resolved_conversations_count":{"type":"number","description":"Number of conversations resolved in the inbox during the date range"},"avg_resolution_time":{"type":["number","null"],"description":"Average time (in seconds) to resolve conversations. Null if no data available."},"avg_first_response_time":{"type":["number","null"],"description":"Average time (in seconds) for the first response. Null if no data available."},"avg_reply_time":{"type":["number","null"],"description":"Average time (in seconds) between replies. Null if no data available."}}},"example":[{"id":1,"conversations_count":150,"resolved_conversations_count":120,"avg_resolution_time":3600,"avg_first_response_time":300,"avg_reply_time":600},{"id":2,"conversations_count":75,"resolved_conversations_count":60,"avg_resolution_time":1800,"avg_first_response_time":180,"avg_reply_time":420}]},"agent_summary":{"type":"array","description":"Agent summary report containing conversation statistics grouped by agent.","items":{"type":"object","properties":{"id":{"type":"number","description":"The agent (user) ID"},"conversations_count":{"type":"number","description":"Number of conversations assigned to the agent during the date range"},"resolved_conversations_count":{"type":"number","description":"Number of conversations resolved by the agent during the date range"},"avg_resolution_time":{"type":["number","null"],"description":"Average time (in seconds) to resolve conversations. Null if no data available."},"avg_first_response_time":{"type":["number","null"],"description":"Average time (in seconds) for the first response. Null if no data available."},"avg_reply_time":{"type":["number","null"],"description":"Average time (in seconds) between replies. Null if no data available."}}},"example":[{"id":1,"conversations_count":150,"resolved_conversations_count":120,"avg_resolution_time":3600,"avg_first_response_time":300,"avg_reply_time":600},{"id":2,"conversations_count":75,"resolved_conversations_count":60,"avg_resolution_time":1800,"avg_first_response_time":180,"avg_reply_time":420}]},"team_summary":{"type":"array","description":"Team summary report containing conversation statistics grouped by team.","items":{"type":"object","properties":{"id":{"type":"number","description":"The team ID"},"conversations_count":{"type":"number","description":"Number of conversations assigned to the team during the date range"},"resolved_conversations_count":{"type":"number","description":"Number of conversations resolved by the team during the date range"},"avg_resolution_time":{"type":["number","null"],"description":"Average time (in seconds) to resolve conversations. Null if no data available."},"avg_first_response_time":{"type":["number","null"],"description":"Average time (in seconds) for the first response. Null if no data available."},"avg_reply_time":{"type":["number","null"],"description":"Average time (in seconds) between replies. Null if no data available."}}},"example":[{"id":1,"conversations_count":250,"resolved_conversations_count":200,"avg_resolution_time":2800,"avg_first_response_time":240,"avg_reply_time":500},{"id":2,"conversations_count":180,"resolved_conversations_count":150,"avg_resolution_time":2400,"avg_first_response_time":200,"avg_reply_time":450}]},"contact_meta":{"type":"object","properties":{"count":{"type":"integer","description":"Total number of contacts"},"current_page":{"type":["string","integer"],"description":"Current page number"}}},"contact_inbox":{"type":"object","properties":{"source_id":{"type":"string","description":"Source identifier for the contact inbox"},"inbox":{"type":"object","properties":{"id":{"type":"integer","description":"ID of the inbox"},"avatar_url":{"type":"string","description":"URL for the inbox avatar"},"channel_id":{"type":"integer","description":"ID of the channel"},"name":{"type":"string","description":"Name of the inbox"},"channel_type":{"type":"string","enum":["Channel::Api","Channel::Email","Channel::FacebookPage","Channel::Instagram","Channel::Line","Channel::Sms","Channel::Telegram","Channel::Tiktok","Channel::TwilioSms","Channel::TwitterProfile","Channel::WebWidget","Channel::Whatsapp"],"description":"The channel class backing the inbox"},"provider":{"type":["string","null"],"enum":["default","whatsapp_cloud","whatsapp_web","google","microsoft",null],"description":"Channel-specific provider of the underlying channel — WhatsApp uses default, whatsapp_cloud or whatsapp_web (WazMeow); Email uses google or microsoft; null for channels that have no provider concept."}}}}},"contact_list_item":{"type":"object","properties":{"additional_attributes":{"type":"object","description":"The object containing additional attributes related to the contact","properties":{"city":{"type":"string","description":"City of the contact"},"country":{"type":"string","description":"Country of the contact"},"country_code":{"type":["string","null"],"description":"Country code of the contact"},"created_at_ip":{"type":"string","description":"IP address when the contact was created"}}},"availability_status":{"type":"string","description":"Availability status of the contact","enum":["online","offline"]},"email":{"type":["string","null"],"description":"The email address of the contact"},"id":{"type":"integer","description":"The ID of the contact"},"name":{"type":"string","description":"The name of the contact"},"phone_number":{"type":["string","null"],"description":"The phone number of the contact"},"blocked":{"type":"boolean","description":"Whether the contact is blocked"},"identifier":{"type":["string","null"],"description":"The identifier of the contact"},"referred_by_affiliate_id":{"type":["integer","null"],"description":"Spec-078 — the affiliate that referred this contact. Present only when the account has the affiliate_program feature; a paid order from this contact inherits the credit unless the order names an affiliate of its own."},"referred_by_affiliate_name":{"type":["string","null"],"description":"Display name of that affiliate, so a row can be labelled without a second request. Read-only — referred_by_affiliate_id is what a client writes back. Present only with affiliate_program."},"legal_type":{"type":["string","null"],"enum":["individual","business",null],"description":"Whether the contact is a natural person (individual) or a legal entity (business)"},"tax_id":{"type":["string","null"],"description":"The fiscal identifier. Returned as the real value to an authenticated human agent; a type-aware mask (e.g. \"***.***.***-09\") when a role field rule masks it or the caller is a bot. A hidden rule omits the key."},"tax_id_type":{"type":["string","null"],"enum":["br_cpf","br_cnpj","us_ein","eu_vat","uk_vat","generic",null],"description":"The fiscal identifier scheme used to validate and mask tax_id"},"country":{"type":["string","null"],"description":"ISO 3166-1 alpha-2 country code used for fiscal-id detection (e.g. \"BR\", \"US\")"},"address":{"type":"object","description":"Native postal address of the contact. Blank components are omitted.","properties":{"zip":{"type":"string","description":"Postal/ZIP code (CEP in Brazil)"},"street":{"type":"string","description":"Street name"},"number":{"type":"string","description":"Street number"},"complement":{"type":"string","description":"Address complement (apartment, suite, block)"},"neighborhood":{"type":"string","description":"Neighborhood/district"},"city":{"type":"string","description":"City name"},"state":{"type":"string","description":"State/province (UF in Brazil)"},"country":{"type":"string","description":"Country of the postal address"}}},"billing_address":{"type":"object","description":"Optional billing address override. An empty object means billing uses the principal address.","properties":{"zip":{"type":"string","description":"Postal/ZIP code (CEP in Brazil)"},"street":{"type":"string","description":"Street name"},"number":{"type":"string","description":"Street number"},"complement":{"type":"string","description":"Address complement (apartment, suite, block)"},"neighborhood":{"type":"string","description":"Neighborhood/district"},"city":{"type":"string","description":"City name"},"state":{"type":"string","description":"State/province (UF in Brazil)"},"country":{"type":"string","description":"Country of the postal address"}}},"thumbnail":{"type":"string","description":"The thumbnail of the contact"},"custom_attributes":{"type":"object","description":"The custom attributes of the contact","additionalProperties":true},"last_activity_at":{"type":["integer","null"],"description":"Timestamp of last activity"},"created_at":{"type":"integer","description":"Timestamp when contact was created"},"contact_inboxes":{"type":"array","description":"List of inboxes associated with this contact","items":{"$ref":"#/components/schemas/contact_inbox"}}}},"contacts_list_response":{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/contact_meta"},"payload":{"type":"array","items":{"$ref":"#/components/schemas/contact_list_item"},"description":"List of contacts"}}},"contact_show_response":{"type":"object","properties":{"payload":{"$ref":"#/components/schemas/contact_list_item"}}},"contact_conversations_response":{"type":"object","properties":{"payload":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/conversation"},{"type":"object","properties":{"meta":{"type":"object","properties":{"sender":{"type":"object","properties":{"additional_attributes":{"type":"object","description":"The additional attributes of the sender","additionalProperties":true},"availability_status":{"type":"string","description":"The availability status of the sender","enum":["online","offline","busy"]},"email":{"type":["string","null"],"description":"The email of the sender"},"id":{"type":"number","description":"ID fo the sender"},"name":{"type":"string","description":"The name of the sender"},"phone_number":{"type":["string","null"],"description":"The phone number of the sender"},"blocked":{"type":"boolean","description":"Whether the sender is blocked"},"identifier":{"type":["string","null"],"description":"The identifier of the sender"},"thumbnail":{"type":["string","null"],"description":"Avatar URL of the contact"},"custom_attributes":{"type":"object","description":"The custom attributes of the sender","additionalProperties":true},"last_activity_at":{"type":"number","description":"The last activity at of the sender"},"created_at":{"type":"number","description":"The created at of the sender"}}},"channel":{"type":"string","description":"Channel Type"},"assignee":{"$ref":"#/components/schemas/user"},"hmac_verified":{"type":"boolean","description":"Whether the hmac is verified"}}}}}]},"description":"List of conversations for the contact"}}},"contactable_inboxes_response":{"type":"object","properties":{"payload":{"type":"array","items":{"$ref":"#/components/schemas/contact_inbox"},"description":"List of contactable inboxes for the contact"}}},"reporting_event":{"type":"object","properties":{"id":{"type":"number","description":"ID of the reporting event"},"name":{"type":"string","description":"Name of the event (e.g., first_response, resolution, reply_time)"},"value":{"type":"number","format":"double","description":"Value of the metric in seconds"},"value_in_business_hours":{"type":"number","format":"double","description":"Value of the metric in seconds, calculated only for business hours"},"event_start_time":{"type":"string","format":"date-time","description":"The timestamp when the event started"},"event_end_time":{"type":"string","format":"date-time","description":"The timestamp when the event ended"},"account_id":{"type":"number","description":"ID of the account"},"conversation_id":{"type":["number","null"],"description":"ID of the conversation"},"inbox_id":{"type":["number","null"],"description":"ID of the inbox"},"user_id":{"type":["number","null"],"description":"ID of the user/agent"},"created_at":{"type":"string","format":"date-time","description":"The timestamp when the reporting event was created"},"updated_at":{"type":"string","format":"date-time","description":"The timestamp when the reporting event was last updated"}}},"reporting_event_meta":{"type":"object","properties":{"count":{"type":"integer","description":"Total number of reporting events"},"current_page":{"type":"integer","description":"Current page number"},"total_pages":{"type":"integer","description":"Total number of pages"}}},"reporting_events_list_response":{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/reporting_event_meta"},"payload":{"type":"array","items":{"$ref":"#/components/schemas/reporting_event"},"description":"List of reporting events"}}},"payment_connection":{"type":"object","description":"A payment gateway connection (Asaas / Mercado Pago). Credentials are never serialized — only has_* presence flags.","properties":{"id":{"type":"number"},"account_id":{"type":"number"},"name":{"type":"string"},"gateway":{"type":"string","enum":["asaas","mercado_pago"]},"environment":{"type":"string","enum":["sandbox","production"]},"status":{"type":"string","enum":["pending","active","disabled","errored"]},"is_default":{"type":"boolean"},"capabilities":{"type":"object","additionalProperties":true,"description":"Per-gateway capability matrix. Besides payment methods it gates installments, fine, interest, payment_discount, postal_service, callback, subscription_max_payments, subscription_end_date, bimonthly, back_urls and auto_return. `split` is false until a native split implementation exists. Drives the composer UI and is enforced again by the backend."},"has_api_key":{"type":"boolean"},"has_secret_key":{"type":"boolean"},"has_webhook_token":{"type":"boolean"},"last_reconciliation":{"type":["object","null"],"description":"Secret-safe summary of the latest scheduled reconciliation. A partial or failed run includes bounded per-record identifiers and stable reason codes; raw provider exceptions are never persisted or serialized.","properties":{"status":{"type":"string","enum":["success","partial","failed"]},"started_at":{"type":"string","format":"date-time"},"finished_at":{"type":"string","format":"date-time"},"processed_count":{"type":"integer","minimum":0},"failed_count":{"type":"integer","minimum":0},"failed_ids":{"type":"array","maxItems":100,"items":{"type":"object","required":["resource","external_id","reason"],"properties":{"resource":{"type":"string","enum":["charge","charge_listing","subscription","subscription_listing"]},"external_id":{"type":"string","maxLength":200},"local_id":{"type":["integer","null"],"minimum":1},"reason":{"type":"string","enum":["gateway_error","gateway_timeout","invalid_import_window","invalid_provider_record","missing_gateway_id","record_invalid","record_not_saved","reconciliation_error"]}}}}}},"settings":{"type":"object","additionalProperties":true,"description":"Sanitized, server-managed connection metadata. Provider endpoints are fixed by gateway and environment and cannot be overridden here. Ingestion keys are written only through the governed ingestion-settings action; credential keys are stripped before serialization.","properties":{"orphan_adoption_policy":{"type":"string","enum":["disabled","from_watermark","all"],"default":"disabled","example":"disabled","description":"Governs ADOPTION of a gateway charge that arrives by webhook with no local row (created in the gateway panel, or paid through a checkout link). `disabled` never adopts and only logs the refusal; `from_watermark` adopts only records dated on/after `import_from`; `all` adopts everything the gateway sends. An unrecognized value falls back to `disabled`. An adopted charge is recorded as history: it produces no customer message, no ad-platform conversion, no commission and no outbound webhook."},"import_from":{"type":"string","format":"date-time","example":"2026-07-01T00:00:00Z","description":"Watermark for ingestion. Nothing dated before it may enter, by import or by webhook. Absent means no floor. A value that cannot be parsed refuses everything (fail-closed) rather than silently widening `from_watermark` into `all`."}}},"archived_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"max_installments_by_type":{"type":"object","properties":{"credit_card":{"type":["integer","null"]},"boleto":{"type":["integer","null"]},"pix":{"type":["integer","null"]}}},"installable_billing_types":{"type":"array","items":{"type":"string","enum":["credit_card","boleto","pix"]}},"installment_cycles":{"type":"object","properties":{"native_installment":{"type":"array","items":{"type":"string","enum":["monthly"]}},"native_recurrence_capped":{"type":"array","items":{"type":"string","enum":["weekly","biweekly","monthly","bimonthly","quarterly","semiannually","yearly"]}}}},"plan_creation_released":{"type":"object","required":["credit_card","boleto","pix"],"description":"Whether this connection may create an installment plan (boleto or Pix installment, or a capped recurrence) for each method. False means the plan flow is held until its financial flow is verified live, so the composer withholds those options. A credit-card installment on the native monthly schedule is a standalone charge and never depends on this.","properties":{"credit_card":{"type":"boolean","example":false},"boleto":{"type":"boolean","example":false},"pix":{"type":"boolean","example":false}}},"plan_send_released":{"type":"object","required":["credit_card","boleto","pix"],"description":"Whether a plan created on this connection may be sent to a customer, per method. A sandbox connection in a production install creates plans but never delivers them, so the composer offers \"create\" instead of \"create and send\".","properties":{"credit_card":{"type":"boolean","example":false},"boleto":{"type":"boolean","example":false},"pix":{"type":"boolean","example":false}}},"gateway_option_defaults":{"$ref":"#/components/schemas/payment_gateway_options"},"money_unit":{"type":"string","enum":["major","minor"],"description":"Monetary unit used at the provider boundary; the application stores major units."},"webhook_signature_scheme":{"type":"string","enum":["header_token","hmac_manifest","hint_and_refetch","none"],"description":"Declared provider webhook authentication scheme; absent authorization never permits a financial mutation."},"client_certificate":{"type":"object","required":["present","status","days_remaining","subject","issuer","fingerprint","expires_at"],"properties":{"present":{"type":"boolean"},"status":{"type":"string","enum":["missing","valid","expiring","expired"]},"days_remaining":{"type":["integer","null"]},"subject":{"type":["string","null"]},"issuer":{"type":["string","null"]},"fingerprint":{"type":["string","null"]},"expires_at":{"type":["string","null"],"format":"date-time"}}},"capabilities_v2":{"type":"object","required":["money_unit","webhook_signature_scheme","methods"],"properties":{"money_unit":{"type":"string","enum":["major","minor"],"description":"Monetary unit used at the provider boundary; the application stores major units."},"webhook_signature_scheme":{"type":"string","enum":["header_token","hmac_manifest","hint_and_refetch","none"],"description":"Declared provider webhook authentication scheme; absent authorization never permits a financial mutation."},"methods":{"type":"object","description":"Explicit billing-method to action boolean matrix; an absent action is denied.","additionalProperties":{"type":"object","description":"Action names mapped to explicit support booleans for this billing method; absent actions are denied.","additionalProperties":{"type":"boolean"}}}}}}},"payment_charge":{"type":"object","description":"A charge (cobrança) with its normalized settlement status, buyer-facing payment artifacts (PIX copia-e-cola, QR, hosted/boleto links), discount and foreign-exchange audit fields, and catalog or deal line-item snapshots. No gateway secrets are returned. `confirmed` means the customer payment is settled even if the provider has not yet released the balance to the merchant; `paid` means the provider reports the funds as received or available.","required":["id","account_id","payments_connection_id","contact_id","organization_id","organization_name","conversation_id","crm_item_id","crm_item_title","payments_subscription_id","gateway_charge_id","external_reference","billing_type","status","amount","amount_refunded","subtotal_amount","discount","discount_type","discount_reason","currency","original_amount","original_currency","fx_rate","installments","installment_mode","installment_interest_rate","due_date","paid_at","refunded_at","description","hosted_url","pix_payload","pix_qr_base64","boleto_url","metadata","gateway_options","custom_attributes","settled","archived_at","created_at","updated_at","gateway_customer_id","gateway","can_mark_as_paid","manually_paid","conversation_display_id","line_items"],"properties":{"id":{"type":"integer","minimum":1},"account_id":{"type":"integer","minimum":1},"payments_connection_id":{"type":["integer","null"],"minimum":1,"description":"Native gateway connection when this installation owns one; null for an external sale."},"contact_id":{"type":["integer","null"],"minimum":1},"organization_id":{"type":["integer","null"],"minimum":1},"organization_name":{"type":["string","null"]},"conversation_id":{"type":["integer","null"],"minimum":1},"crm_item_id":{"type":["integer","null"],"minimum":1},"crm_item_title":{"type":["string","null"]},"payments_subscription_id":{"type":["integer","null"],"minimum":1},"gateway_charge_id":{"type":["string","null"]},"external_reference":{"type":["string","null"]},"billing_type":{"type":"string","enum":["pix","boleto","credit_card","hosted_link","undefined","debit_card"]},"status":{"type":"string","enum":["pending","awaiting_payment","confirmed","paid","overdue","refunded","partially_refunded","canceled","failed"],"description":"Normalized provider state. `confirmed` is already settled for the customer, while the provider may make the merchant balance available only later; `paid` reports that later received/available state. Both are settlement states and carry paid_at when the provider supplies or preserves it."},"amount":{"type":"number","minimum":0,"description":"Gateway net amount in major currency units after the charge-level discount."},"amount_refunded":{"type":"number","minimum":0},"subtotal_amount":{"type":["number","null"],"minimum":0,"description":"Gross amount before the charge-level discount; null on legacy rows without the snapshot."},"discount":{"type":"number","minimum":0},"discount_type":{"type":"string","enum":["fixed","percent"]},"discount_reason":{"type":["string","null"],"description":"Operator justification recorded with the charge-level discount."},"currency":{"type":["string","null"],"example":"BRL"},"original_amount":{"type":["number","null"],"minimum":0,"description":"Pre-conversion amount when the source currency differed; otherwise null."},"original_currency":{"type":["string","null"],"description":"Pre-conversion currency code when foreign exchange was applied; otherwise null."},"fx_rate":{"type":["number","null"],"exclusiveMinimum":0,"description":"Exchange rate used to reach the settlement currency; null when no conversion was needed."},"installments":{"type":["integer","null"],"minimum":1},"installment_mode":{"type":["string","null"],"enum":["absorb","passthrough",null],"description":"Who bears installment interest; null on legacy charges and interpreted as absorb by the dashboard."},"installment_interest_rate":{"type":["number","null"],"minimum":0,"description":"Monthly installment interest rate captured for this charge."},"due_date":{"type":["string","null"],"format":"date"},"paid_at":{"type":["string","null"],"format":"date-time"},"refunded_at":{"type":["string","null"],"format":"date-time"},"description":{"type":["string","null"]},"hosted_url":{"type":["string","null"]},"pix_payload":{"type":["string","null"],"description":"PIX copia-e-cola."},"pix_qr_base64":{"type":["string","null"]},"boleto_url":{"type":["string","null"]},"metadata":{"type":"object","additionalProperties":true,"description":"Free-form gateway metadata bag. Includes raw_status (the gateway's own status string, before normalization — an open set that differs per gateway), boleto_digitable_line (linha digitável) when the gateway returned it, and origin on a charge that was not created here.","properties":{"origin":{"type":"string","enum":["external_gateway","imported"],"example":"external_gateway","description":"Present only on a charge that entered from the gateway rather than being created here — `external_gateway` when adopted from a webhook and `imported` when pulled by a backfill. Such a charge is recorded as history without replaying customer or attribution side effects."}}},"gateway_options":{"$ref":"#/components/schemas/payment_gateway_options"},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Account-defined non-secret custom fields visible to the caller."},"settled":{"type":"boolean","description":"True for confirmed, paid, refunded and partially_refunded charges."},"contact_name":{"type":["string","null"]},"contact_email":{"type":["string","null"],"format":"email"},"payer_email":{"type":["string","null"],"format":"email","description":"Backwards-compatible display alias for contact_email."},"contact_phone_number":{"type":["string","null"]},"gateway_customer_id":{"type":["string","null"],"description":"Opaque provider customer identifier retained in the sanitized metadata, when known."},"gateway":{"type":["string","null"],"description":"Immutable source namespace stored on the charge or resolved from its native connection.","example":"hotmart"},"can_mark_as_paid":{"type":"boolean","description":"True when the native connection advertises a manual-settlement capability. The current charge status is still validated by the manual-settlement operation."},"manually_paid":{"type":"boolean","description":"True when this installation settled the charge through the audited mark-as-paid operation."},"conversation_display_id":{"type":["integer","null"],"minimum":1,"description":"Human-facing conversation number used by dashboard routes; null when no conversation is linked."},"archived_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"line_items":{"type":"array","items":{"type":"object","required":["id","catalog_variant_id","catalog_product_id","name_snapshot","quantity","unit_price","discount","discount_type","line_total","currency","position","metadata"],"properties":{"id":{"type":"integer","minimum":1},"catalog_variant_id":{"type":["integer","null"],"minimum":1},"catalog_product_id":{"type":["integer","null"],"minimum":1},"name_snapshot":{"type":["string","null"]},"quantity":{"type":"number","exclusiveMinimum":0},"unit_price":{"type":"number","minimum":0},"discount":{"type":"number","minimum":0},"discount_type":{"type":"string","enum":["fixed","percent"]},"line_total":{"type":"number","minimum":0},"currency":{"type":["string","null"],"example":"BRL"},"position":{"type":"integer","minimum":0},"metadata":{"type":"object","additionalProperties":true,"description":"Non-secret per-line audit snapshot, including foreign-exchange facts when applicable."}}}},"installment_plan_id":{"type":["integer","null"]},"installment_number":{"type":["integer","null"]},"installments_count":{"type":["integer","null"]},"installment_plan":{"$ref":"#/components/schemas/payment_installment_plan"},"can_undo_mark_as_paid":{"type":"boolean"},"can_refund":{"type":"boolean"}}},"payment_gateway_options":{"type":"object","additionalProperties":true,"description":"Sanitized gateway-native options applied at creation; never contains credentials."},"payment_charge_event":{"type":"object","description":"An append-only charge lifecycle / audit event.","properties":{"id":{"type":"number"},"payments_charge_id":{"type":"number"},"event_type":{"type":"string","enum":["created","awaiting_payment","confirmed","paid","overdue","refunded","partially_refunded","canceled","failed","refund_requested","updated"]},"user_id":{"type":["number","null"]},"actor":{"type":"object","description":"The operator who caused the event, or a typed system actor for gateway/import activity.","properties":{"type":{"type":"string","enum":["user","system","automation","macro"]},"id":{"type":["number","null"]},"name":{"type":["string","null"]}}},"metadata":{"type":"object","additionalProperties":true,"description":"Free-form context recorded with the event (e.g. refund/discount reason, actor, gateway echo)."},"occurred_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"}}},"payment_subscription":{"type":"object","description":"A subscription (assinatura) — gateway-delegated recurrence mirrored from webhooks.","properties":{"id":{"type":"number"},"account_id":{"type":"number"},"payments_connection_id":{"type":"number"},"contact_id":{"type":"number"},"conversation_id":{"type":["integer","null"],"minimum":1,"description":"Internal id of the conversation the subscription was sold in; every charge the gateway generates for it inherits this link. Null when none."},"conversation_display_id":{"type":["integer","null"],"minimum":1,"description":"Human-facing conversation number used by dashboard routes; null when no conversation is linked."},"payments_plan_id":{"type":"number"},"gateway_subscription_id":{"type":"string"},"status":{"type":"string","enum":["pending","active","paused","overdue","canceled","expired"]},"cycle":{"type":"string","enum":["weekly","biweekly","monthly","bimonthly","quarterly","semiannually","yearly"]},"billing_type":{"type":"string","enum":["pix","boleto","credit_card","hosted_link","undefined","debit_card"]},"amount":{"type":"number"},"subtotal_amount":{"type":["number","null"],"description":"Gross recurring amount before the discount; null on legacy rows."},"discount":{"type":"number","description":"Discount applied on every billing cycle; fixed amount or percentage according to discount_type."},"discount_type":{"type":"string","enum":["fixed","percent"],"description":"How discount is interpreted for every billing cycle."},"discount_reason":{"type":["string","null"],"description":"Operator justification recorded with the recurring discount."},"currency":{"type":"string"},"next_due_date":{"type":"string","format":"date"},"max_payments":{"type":["integer","null"],"minimum":1,"description":"Asaas maximum number of billing cycles."},"end_date":{"type":["string","null"],"format":"date","description":"Asaas subscription end date."},"started_at":{"type":"string","format":"date-time"},"canceled_at":{"type":"string","format":"date-time"},"metadata":{"type":"object","additionalProperties":true,"description":"Free-form gateway metadata mirrored from the subscription webhooks."},"contact_name":{"type":"string"},"gateway":{"type":"string","enum":["asaas","mercado_pago"]},"capabilities":{"type":"object","additionalProperties":true,"description":"Connection capability matrix used to gate edit controls."},"plan_name":{"type":"string"},"archived_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"payment_plan":{"type":"object","description":"A reusable local subscription template. Selecting it for a new subscription reuses its connection, amount, currency and cycle; gateway_plan_id is nullable and does not promise that the template already exists as a reusable resource at the gateway.","properties":{"id":{"type":"number"},"account_id":{"type":"number"},"payments_connection_id":{"type":"number"},"gateway_plan_id":{"type":["string","null"]},"name":{"type":"string"},"cycle":{"type":"string","enum":["weekly","biweekly","monthly","bimonthly","quarterly","semiannually","yearly"]},"amount":{"type":"number"},"currency":{"type":"string"},"metadata":{"type":"object","additionalProperties":true,"description":"Free-form gateway metadata for the plan."},"gateway":{"type":"string","enum":["asaas","mercado_pago"]},"connection_name":{"type":"string"},"capabilities":{"type":"object","additionalProperties":true,"description":"Capability snapshot for rendering only cycles supported by the selected gateway."},"archived_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"payment_offer":{"type":"object","description":"Administrative priced offer used by checkout or contact-scoped post-purchase flows.","properties":{"id":{"type":"integer","example":44},"account_id":{"type":"integer","example":1},"name":{"type":"string","example":"Priority onboarding"},"kind":{"type":"string","enum":["order_bump","upsell","downsell"],"example":"upsell"},"amount":{"type":"number","example":49.9},"currency":{"type":"string","example":"BRL"},"billing_type":{"type":"string","enum":["pix","boleto","credit_card","hosted_link","debit_card"],"example":"pix"},"connection_id":{"type":["integer","null"],"example":5},"catalog_product_id":{"type":["integer","null"],"example":88},"description":{"type":["string","null"],"example":"Add priority onboarding to this purchase."},"active":{"type":"boolean","example":true},"settings":{"type":"object","additionalProperties":true,"description":"Open offer settings reserved for checkout and funnel integrations."},"archived_at":{"type":["string","null"],"format":"date-time","example":null},"created_at":{"type":"string","format":"date-time","example":"2026-08-05T12:00:00Z"},"updated_at":{"type":"string","format":"date-time","example":"2026-08-05T12:00:00Z"},"gateway":{"type":["string","null"],"enum":["asaas","mercado_pago",null],"example":"asaas"},"connection_name":{"type":["string","null"],"example":"Main Asaas"},"capabilities":{"type":"object","additionalProperties":true,"description":"Capability snapshot used to constrain payment methods in the administrative form."},"catalog_product_name":{"type":["string","null"],"example":"Pro plan"}}},"payment_import_run":{"type":"object","description":"Spec-082 — one execution of the governed backfill that pulls gateway charges, customer mappings or subscriptions. A PREVIEW is a real run with dry_run=true: it computes the exact same buckets it would write and writes nothing, so the preview can never drift from the execution.","properties":{"id":{"type":"integer","example":42},"connection_id":{"type":"integer","description":"The gateway connection swept.","example":1},"resource_type":{"type":"string","enum":["charge","customer","subscription"],"description":"Resource represented by the run. Charges affect the money ledger; customer mappings and subscriptions are directory mirrors.","example":"subscription"},"dry_run":{"type":"boolean","description":"true = preview (nothing written); false = the run actually applied its buckets.","example":true},"trigger":{"type":"string","description":"What started the run.","example":"manual"},"status":{"type":"string","enum":["pending","running","completed","failed","canceled"],"description":"Lifecycle of the run. `failed` carries a readable `error` (e.g. the gateway cannot list, or another import is already running for this connection).","example":"completed"},"window_from":{"type":["string","null"],"format":"date-time","example":"2026-07-01T00:00:00Z"},"window_to":{"type":["string","null"],"format":"date-time","example":"2026-07-31T23:59:59Z"},"error":{"type":["string","null"],"description":"Why the run failed","when it did.":null,"example":"gateway_does_not_support_listing"},"started_at":{"type":["string","null"],"format":"date-time"},"finished_at":{"type":["string","null"],"format":"date-time"},"duration_seconds":{"type":["integer","null"],"example":37},"undone_at":{"type":["string","null"],"format":"date-time","description":"Set when the locally created records of this run were safely reversed. A reversal never calls the gateway and is refused if a created record has moved afterwards."},"undone_by_id":{"type":["integer","null"],"description":"Administrator who confirmed the local reversal, when applicable.","example":7},"undoable":{"type":"boolean","description":"Eligibility hint for the UI. The undo endpoint re-checks provenance and later movement under a lock, so true does not bypass the server-side safety checks.","example":true},"created_at":{"type":"string","format":"date-time"},"scanned":{"type":"integer","description":"Gateway records examined.","example":120},"truncated":{"type":"boolean","description":"true when the run stopped at its record ceiling. Reported explicitly so a partial backfill can never be read as \"we got everything\".","example":false},"create":{"$ref":"#/components/schemas/payment_import_bucket"},"update":{"$ref":"#/components/schemas/payment_import_bucket"},"skip":{"$ref":"#/components/schemas/payment_import_bucket"},"failed_ids":{"type":"array","description":"Records that could not be ingested, one entry each. Part of the payload (not just the log) so a partially failed run is visible in the UI instead of reading as clean.","items":{"type":"object","properties":{"external_id":{"type":"string","example":"pay_gbfikms77ucf8on2"},"error":{"type":"string","example":"Validation failed: Amount is not a number"}}}},"failed":{"type":"boolean","description":"Convenience flag — true when failed_ids is non-empty.","example":false},"associations":{"type":"object","description":"Safe existing-record associations detected by a directory import. No contact or organization is ever created automatically.","properties":{"contact":{"type":"integer","example":8},"organization":{"type":"integer","example":2},"charge":{"type":"integer","example":4,"description":"Earlier imported charges linked to a subscription by the exact gateway subscription id."},"unmatched_contact":{"type":"integer","example":3}}}}},"payment_import_bucket":{"type":"object","description":"One outcome bucket of an import run — what would be (or was) created, updated or skipped, with the money it represents so the operator can see the size of what they are letting in.","properties":{"count":{"type":"integer","example":3},"amount":{"type":"string","description":"Legacy scalar sum of every amount in the bucket, as a decimal string. It is retained for compatibility only; consumers must use amounts and never add separate currencies together.","example":"2991.0"},"amounts":{"type":"object","description":"Exact sums keyed by ISO 4217 currency. Use this field for every money display.","additionalProperties":{"type":"string","description":"Decimal amount in the map key's currency."},"example":{"BRL":"2991.0"}},"ids":{"type":"array","description":"Gateway record ids in this bucket. Their resource type is the import run resource_type.","items":{"type":"string"},"example":["pay_gbfikms77ucf8on2"]},"reasons":{"type":"object","description":"Skip bucket only — why records were refused, counted per reason (not_selected, before_watermark, ignored_by_operator, already_in_sync, no_gateway_id).","additionalProperties":{"type":"integer"},"example":{"before_watermark":12,"ignored_by_operator":1}}}},"payment_import_preview_item":{"type":"object","description":"One allowlisted, secrets-free row captured by the governed gateway sweep. It is persisted with the run so server pagination/filtering never re-queries the gateway or drifts from the approved preview.","required":["external_id","resource_type","bucket"],"properties":{"external_id":{"type":"string","description":"Opaque gateway record identifier.","example":"pay_000012345678"},"resource_type":{"type":"string","enum":["charge","customer","subscription"],"example":"charge"},"bucket":{"type":"string","enum":["create","update","skip"],"description":"Decision made by the exact dry-run import path.","example":"create"},"status":{"type":["string","null"],"enum":["pending","awaiting_payment","confirmed","paid","overdue","refunded","partially_refunded","canceled","failed","active","paused","expired",null],"description":"Normalized gateway state when that resource carries a state.","example":"paid"},"amount":{"type":["string","null"],"description":"Major-unit decimal amount.","example":"149.90"},"currency":{"type":["string","null"],"description":"ISO 4217 currency.","example":"BRL"},"billing_type":{"type":["string","null"],"enum":["pix","boleto","credit_card","hosted_link","undefined","debit_card",null],"example":"pix"},"cycle":{"type":["string","null"],"enum":["weekly","biweekly","monthly","quarterly","semiannually","yearly","bimonthly",null],"example":"monthly"},"external_reference":{"type":["string","null"],"example":"order_9821"},"occurred_at":{"type":["string","null"],"description":"Best available provider event date.","example":"2026-07-30T12:00:00Z"},"created_at":{"type":["string","null"],"description":"Provider creation date.","example":"2026-07-28T12:00:00Z"},"paid_at":{"type":["string","null"],"description":"Provider settlement date.","example":"2026-07-30T12:00:00Z"},"due_date":{"type":["string","null"],"description":"Charge due date or subscription next due date.","example":"2026-08-10"},"customer_gateway_id":{"type":["string","null"],"description":"Gateway customer identifier carried by the row. For an Asaas charge this is the ONLY payer fact the listing returns, so it is what identifies the customer when no name is available.","example":"cus_000193068297"},"contact_id":{"type":["integer","null"],"description":"Exact existing contact resolved from the gateway mapping, e-mail, normalized phone or tax document. Absent when no unique match exists — the preview never invents an association.","example":4821},"contact_match":{"type":["string","null"],"enum":["existing_charge","manual","gateway_customer","email","phone","document",null],"description":"Exact signal that selected the contact; null when unresolved or ambiguous.","example":"gateway_customer"},"contact_resolution":{"type":["string","null"],"enum":["resolved","unresolved","ambiguous",null],"description":"Whether this charge is already safe to select or still needs an explicit operator decision.","example":"resolved"},"customer_name":{"type":["string","null"],"example":"Ana Silva"},"customer_email":{"type":["string","null"],"format":"email","example":"ana@example.com"},"customer_phone":{"type":["string","null"],"example":"+5511999999999"},"customer_document":{"type":["string","null"],"example":"19119119100"},"skip_reason":{"type":["string","null"],"enum":["not_selected","before_watermark","ignored_by_operator","already_in_sync","already_in_sync_repaired","no_gateway_id","unmatched_contact","contact_already_linked","unknown_subscription_status","unknown_subscription_cycle","invalid_subscription_amount",null],"description":"Closed reason set for skip rows; null for create/update.","example":"already_in_sync"}}},"payment_ignored_external":{"type":"object","description":"One durable decision to keep a gateway record out of a payment connection. The same exclusion is consulted by governed imports and webhook adoption until an administrator explicitly deletes it. Legacy rows without a connection remain gateway-wide fallbacks.","properties":{"id":{"type":"integer","example":51},"connection_id":{"type":["integer","null"],"description":"Payment connection that owns the provider identity; null only for a legacy gateway-wide fallback.","example":9},"gateway":{"type":"string","enum":["asaas","mercado_pago"],"description":"Gateway namespace that owns the external id.","example":"asaas"},"resource_type":{"type":"string","enum":["charge","customer","subscription"],"description":"Type of gateway record excluded by this decision.","example":"charge"},"external_id":{"type":"string","description":"Gateway record identifier; gateway ids are opaque strings, never local integer ids.","example":"pay_000012345678"},"reason":{"type":["string","null"],"description":"Operator-provided explanation for the durable exclusion.","example":"Not a sale for this account."},"created_by_id":{"type":["integer","null"],"example":7},"import_run_id":{"type":["integer","null"],"description":"Reserved association when an import run originated the decision."},"created_at":{"type":"string","format":"date-time"}}},"crm_order":{"type":"object","description":"Purchase-history record in the CRM Orders Registry. Orders projected from an external source keep that source's financial facts and identity immutable; operator-entered manual orders may be corrected only through the governed manual endpoints and only while their financial side effects still permit it. Voided orders remain available for audit but are excluded from operational queries unless record_state includes them. Monetary fields are major-unit decimals and gateway identifiers are opaque strings.","required":["id","account_id","contact_id","organization_id","organization_name","crm_item_id","crm_item_title","payments_charge_id","source_connection_id","owner_id","owner_name","voided_at","voided_by_id","void_reason","void_kind","gateway","external_id","title","amount","amount_refunded","recognized_amount","currency","status","source","ordered_at","paid_at","metadata","line_items","created_at","updated_at"],"properties":{"id":{"type":"integer","minimum":1},"account_id":{"type":"integer","minimum":1},"contact_id":{"type":"integer","minimum":1},"contact_name":{"type":["string","null"]},"contact_email":{"type":["string","null"],"format":"email"},"contact_phone_number":{"type":["string","null"]},"organization_id":{"type":["integer","null"],"minimum":1},"organization_name":{"type":["string","null"]},"crm_item_id":{"type":["integer","null"],"minimum":1},"crm_item_title":{"type":["string","null"]},"payments_charge_id":{"type":["integer","null"],"minimum":1},"source_connection_id":{"type":["integer","null"],"minimum":1,"description":"Payment connection that owns the order's gateway identity."},"owner_id":{"type":["integer","null"],"minimum":1},"owner_name":{"type":["string","null"]},"voided_at":{"type":["string","null"],"format":"date-time"},"voided_by_id":{"type":["integer","null"],"minimum":1},"void_reason":{"type":["string","null"],"maxLength":1000,"description":"Audited reason for removing the order from operational views."},"void_kind":{"type":["string","null"],"enum":["test_data","duplicate","source_purged","operator_error","legacy_orphan","other",null]},"affiliate_id":{"type":["integer","null"],"minimum":1,"description":"Present only when the affiliate-program feature is enabled for the account."},"affiliate_name":{"type":["string","null"],"description":"Present only when the affiliate-program feature is enabled for the account."},"gateway":{"type":["string","null"],"description":"Open source namespace; native and external connectors may add gateway values."},"external_id":{"type":["string","null"],"description":"Opaque source identifier. Its uniqueness is scoped by account, connection and gateway."},"title":{"type":["string","null"]},"amount":{"type":"number","minimum":0},"amount_refunded":{"type":"number","minimum":0},"recognized_amount":{"type":"number","minimum":0,"description":"Net recognized revenue after any provider-backed refund."},"currency":{"type":["string","null"],"example":"BRL"},"status":{"type":"string","enum":["pending","paid","partially_paid","partially_refunded","overdue","refunded","canceled","failed"],"description":"Recorded payment status; this registry never charges or refunds money."},"source":{"type":"string","enum":["manual","webhook","api","payments","commerce"]},"ordered_at":{"type":["string","null"],"format":"date-time"},"paid_at":{"type":["string","null"],"format":"date-time"},"metadata":{"type":"object","additionalProperties":true,"description":"Free-form metadata bag; the key set depends on the record and context."},"line_items":{"type":"array","items":{"type":"object","required":["id","source_item_id","catalog_product_id","catalog_variant_id","name_snapshot","quantity","unit_price","discount","discount_type","line_total","currency","position","metadata"],"properties":{"id":{"type":"integer","minimum":1},"source_item_id":{"type":"string","description":"Opaque, order-scoped identity supplied by the source."},"catalog_product_id":{"type":["integer","null"],"minimum":1},"catalog_variant_id":{"type":["integer","null"],"minimum":1},"name_snapshot":{"type":["string","null"]},"quantity":{"type":"number","exclusiveMinimum":0},"unit_price":{"type":"number","minimum":0},"discount":{"type":"number","minimum":0},"discount_type":{"type":"string","enum":["fixed","percent"]},"line_total":{"type":"number","minimum":0},"currency":{"type":["string","null"],"example":"BRL"},"position":{"type":"integer","minimum":0},"metadata":{"type":"object","additionalProperties":true,"description":"Free-form metadata bag; the key set depends on the record and context."}}}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"commerce_sales_graph_repair":{"type":"object","description":"Read-before-write plan for repairing the customer-facing associations of one sale across Payments, CRM Orders and Commerce Recovery. Amounts, gateway identifiers, settlement state and timestamps are intentionally absent because this operation never changes canonical financial facts. An optional administrator-reviewed consolidation may archive manual duplicate order rows through the governed void lifecycle while preserving the gateway-backed canonical sale.","required":["source","target_contact","records","changes","conflicts","blocked","historical","commission_impact","consolidation","fingerprint"],"properties":{"source":{"type":"object","required":["type","id"],"properties":{"type":{"type":"string","enum":["payments_charge","crm_order","commerce_event"],"example":"payments_charge"},"id":{"type":"integer","example":5821}}},"target_contact":{"type":"object","required":["id","proposed","matched_by"],"properties":{"id":{"type":["integer","null"],"example":4821},"name":{"type":["string","null"],"example":"Ana Silva"},"email":{"type":["string","null"],"format":"email","example":"ana@example.com"},"phone_number":{"type":["string","null"],"example":"+5511999999999"},"proposed":{"type":"boolean","description":"true when the contact would be created only after the operator confirms apply.","example":false},"matched_by":{"type":"string","enum":["selected","gateway_customer","email","phone","document","new"],"example":"selected"},"created":{"type":"boolean","description":"Present and true only when apply created the proposed contact.","example":false}},"description":"Contact PII fields may be masked or omitted by the caller's field-level permissions."},"records":{"type":"array","description":"Every account-scoped record discovered in the sale graph.","items":{"type":"object","required":["source_type","id","external_id","status","contact","organization_id","crm_item_id","conversation_id","owner_id","affiliate_id","historical"],"properties":{"source_type":{"type":"string","enum":["payments_charge","payments_subscription","crm_order","commerce_event"],"example":"payments_charge"},"id":{"type":"integer","example":5821},"external_id":{"type":["string","null"],"example":"pay_000012345678"},"status":{"type":["string","null"],"enum":["active","paused","expired","pending","awaiting_payment","confirmed","paid","partially_paid","overdue","refunded","partially_refunded","canceled","failed","cart_abandoned","order_placed","payment_pending","payment_confirmed","payment_declined","due_soon","chargeback","subscription_late","subscription_canceled",null],"example":"paid"},"contact":{"type":["object","null"],"required":["id"],"properties":{"id":{"type":"integer","example":4821},"name":{"type":["string","null"],"example":"Ana Silva"},"email":{"type":["string","null"],"format":"email","example":"ana@example.com"},"phone_number":{"type":["string","null"],"example":"+5511999999999"}},"description":"Contact PII fields may be masked or omitted by the caller's field-level permissions."},"organization_id":{"type":["integer","null"],"example":27},"crm_item_id":{"type":["integer","null"],"example":934},"conversation_id":{"type":["integer","null"],"example":11901},"owner_id":{"type":["integer","null"],"example":7},"affiliate_id":{"type":["integer","null"],"example":19},"historical":{"type":"boolean","description":"Historical rows are repaired internally without messages, automations or external conversions.","example":true},"voided":{"type":"boolean","description":"Present for CRM orders; true means the row is a preserved tombstone kept only as archived history.","example":false}}}},"changes":{"type":"array","description":"Field-level diff that apply will execute if the fingerprint still matches.","items":{"type":"object","required":["source_type","source_id","field","from","to"],"properties":{"source_type":{"type":"string","enum":["payments_charge","payments_subscription","crm_order","commerce_event","crm_item","contact","organization_membership"],"example":"crm_order"},"source_id":{"type":"integer","example":9102},"field":{"type":"string","enum":["contact_id","organization_id","crm_item_id","conversation_id","owner_id","affiliate_id","payments_charge_id","source_connection_id"],"example":"contact_id"},"from":{"oneOf":[{"type":"integer"},{"type":"string"},{"type":"null"}],"description":"Current scalar value.","example":4100},"to":{"oneOf":[{"type":"integer"},{"type":"string"},{"type":"null"}],"description":"Proposed scalar value; `new` means the delayed contact creation.","example":4821}}}},"conflicts":{"type":"array","description":"Blocking graph inconsistencies. Apply refuses the operation while this array is non-empty.","items":{"type":"object","required":["code","details"],"properties":{"code":{"type":"string","enum":["multiple_charges_for_external","multiple_orders_for_sale","charge_linked_to_multiple_orders","order_linked_to_different_charge","event_linked_to_different_charge","conversation_contact_mismatch","replacement_conversation_not_found","replacement_conversation_contact_mismatch","crm_item_contact_mismatch","crm_item_organization_mismatch","crm_item_owner_mismatch","source_connection_mismatch","invalid_order_consolidation","order_consolidation_retiring_order_not_manual","order_consolidation_identity_mismatch","order_consolidation_irreversible_dependency"],"example":"conversation_contact_mismatch"},"details":{"type":"object","additionalProperties":true,"description":"Account-scoped record identifiers that explain the conflict.","example":{"source_type":"payments_charge","source_id":5821}}}}},"blocked":{"type":"boolean","description":"true when conflicts prevent apply.","example":false},"historical":{"type":"boolean","description":"true when at least one graph record is governed as historical and side effects remain suppressed.","example":true},"commission_impact":{"type":"array","description":"Explicit attribution diff. A confirmed apply is required before owner or affiliate changes.","items":{"type":"object","required":["order_id","paid","owner_id","affiliate_id","requires_confirmation"],"properties":{"order_id":{"type":"integer","example":9102},"paid":{"type":"boolean","example":true},"owner_id":{"type":"array","minItems":2,"maxItems":2,"items":{"type":["integer","null"]},"description":"Current and proposed owner ids.","example":[7,12]},"affiliate_id":{"type":"array","minItems":2,"maxItems":2,"items":{"type":["integer","null"]},"description":"Current and proposed affiliate ids.","example":[19,31]},"requires_confirmation":{"type":"boolean","example":true}}}},"consolidation":{"type":["object","null"],"description":"Null when no duplicate retirement was requested; otherwise the reviewed canonical order and the full governed void impact of each manual duplicate.","required":["canonical_order_id","retiring_orders","reason"],"properties":{"canonical_order_id":{"type":"integer","minimum":1,"example":9102},"retiring_orders":{"type":"array","description":"Governed void impact for each duplicate order that will be archived.","items":{"type":"object","required":["order_id","paid","commission_accrual_ids","closed_commission_accrual_ids","closed_commission_statement_ids","confirmed_booking_ids","invalidated_team_reward_grant_ids","irreversible_distribution_member_ids","will_ignore_external"],"properties":{"order_id":{"type":"integer","minimum":1,"example":9101},"paid":{"type":"boolean","example":true},"commission_accrual_ids":{"type":"array","items":{"type":"integer"},"example":[]},"closed_commission_accrual_ids":{"type":"array","items":{"type":"integer"},"example":[]},"closed_commission_statement_ids":{"type":"array","items":{"type":"integer"},"example":[]},"stock_movement_id":{"type":["integer","null"],"example":null},"engagement_event_ids":{"type":"array","items":{"type":"integer"},"example":[]},"sales_point_event_ids":{"type":"array","items":{"type":"integer"},"example":[]},"commerce_lifecycle_event_id":{"type":["integer","null"],"example":null},"confirmed_booking_ids":{"type":"array","items":{"type":"integer"},"example":[]},"invalidated_team_reward_grant_ids":{"type":"array","items":{"type":"integer"},"example":[]},"irreversible_distribution_member_ids":{"type":"array","items":{"type":"integer"},"example":[]},"pending_effects":{"type":"object","additionalProperties":true,"description":"Bounded identifiers of pending internal effects that the governed void service will compensate.","example":{}},"will_ignore_external":{"type":"boolean","example":false}}}},"reason":{"type":"string","minLength":1,"maxLength":1000,"example":"Duplicate manual record for the canonical gateway charge."}}},"fingerprint":{"type":"string","minLength":64,"maxLength":64,"description":"SHA-256 of the locked graph and requested changes. Send it unchanged to apply.","example":"57bd093c095c62da2abdc0c8c81a0dfcd9f750c48f3a8f85468a24d517967e6c"}}},"commerce_catalog_line_projection_line":{"type":"object","description":"Immutable catalog snapshot copied from the exact charge or deal line selected by the projection plan.","required":["catalog_product_id","catalog_variant_id","name_snapshot","quantity","unit_price","discount","discount_type","currency","position","line_total","metadata"],"properties":{"source_item_id":{"type":"string","description":"Stable source-line identity written on an order line. It is absent from a newly reconstructed charge line.","example":"payments-charge-line-734"},"catalog_product_id":{"type":"integer","minimum":1,"example":41},"catalog_variant_id":{"type":"integer","minimum":1,"example":87},"name_snapshot":{"type":"string","example":"Plano Comercial"},"quantity":{"type":"string","pattern":"^\\d+(?:\\.\\d+)?$","description":"Positive decimal quantity serialized without loss.","example":"1.0"},"unit_price":{"type":"string","pattern":"^\\d+(?:\\.\\d+)?$","description":"Non-negative unit price in major currency units.","example":"997.0"},"discount":{"type":"string","pattern":"^\\d+(?:\\.\\d+)?$","description":"Fixed major-unit or percentage discount according to discount_type.","example":"0.0"},"discount_type":{"type":"string","enum":["fixed","percent"],"example":"fixed"},"currency":{"type":"string","pattern":"^[A-Z]{3}$","example":"BRL"},"position":{"type":"integer","minimum":0,"example":0},"line_total":{"type":"string","pattern":"^\\d+(?:\\.\\d+)?$","description":"Final line amount in major currency units.","example":"997.0"},"metadata":{"type":"object","additionalProperties":true,"description":"Preserved provider metadata plus server-owned catalog projection provenance.","example":{"provider_item_id":"item_001","catalog_line_projection":{"version":1,"source_type":"Payments::Charge","source_id":5821,"stable_source_item_id":"payments-charge-line-734"}}}}},"commerce_catalog_line_projection":{"type":"object","description":"Deterministic read-before-write plan for projecting exact persisted catalog snapshots onto one account-scoped order. The plan never infers a product from names or prices and never creates an inventory movement.","required":["order","requested_source","mode","blocked","conflicts","planned","digest","fingerprint"],"properties":{"order":{"type":["object","null"],"required":["id","account_id"],"properties":{"id":{"type":"integer","minimum":1,"example":9102},"account_id":{"type":"integer","minimum":1,"example":1}}},"requested_source":{"type":"object","required":["type","id"],"properties":{"type":{"type":"string","enum":["Payments::Charge","Crm::Item"],"example":"Payments::Charge"},"id":{"type":["integer","null"],"minimum":1,"example":5821}}},"mode":{"type":["string","null"],"enum":["direct_charge","deal_reconstruction",null],"example":"direct_charge"},"blocked":{"type":"boolean","description":"true when any conflict makes apply unsafe.","example":false},"conflicts":{"type":"array","description":"Exact validation failures. Apply returns the first code as HTTP 422 and performs no write.","items":{"type":"object","required":["code"],"properties":{"code":{"type":"string","example":"source_line_items_missing"},"line_id":{"type":["integer","null"],"example":734},"count":{"type":["integer","null"],"example":101},"planned_index":{"type":["integer","null"],"example":0},"variant_id":{"type":["integer","null"],"example":87},"receipt_id":{"type":["integer","null"],"example":912},"error_class":{"type":["string","null"],"example":"ArgumentError"}}}},"planned":{"type":"object","required":["operation","charge_line_items","order_line_items","order_metadata"],"properties":{"operation":{"type":"string","enum":["blocked","project_order","reconstruct_charge_and_order","noop"],"example":"project_order"},"charge_line_items":{"type":"array","description":"Charge lines created only by an explicit administrator-reviewed deal reconstruction.","items":{"$ref":"#/components/schemas/commerce_catalog_line_projection_line"}},"order_line_items":{"type":"array","description":"Exact order snapshots that apply writes, or verifies during an idempotent replay.","items":{"$ref":"#/components/schemas/commerce_catalog_line_projection_line"}},"order_metadata":{"type":"object","required":["version","mode","source_type","source_id","line_count","currency","subtotal","charge_discount","charge_discount_type","net_total","line_digest","reconstructed"],"properties":{"version":{"type":"integer","enum":[1],"example":1},"mode":{"type":"string","enum":["direct_charge","deal_reconstruction"],"example":"direct_charge"},"source_type":{"type":"string","enum":["Payments::Charge"],"example":"Payments::Charge"},"source_id":{"type":"integer","minimum":1,"example":5821},"line_count":{"type":"integer","minimum":1,"maximum":100,"example":1},"currency":{"type":"string","pattern":"^[A-Z]{3}$","example":"BRL"},"subtotal":{"type":"string","pattern":"^\\d+(?:\\.\\d+)?$","example":"997.0"},"charge_discount":{"type":"string","pattern":"^\\d+(?:\\.\\d+)?$","example":"0.0"},"charge_discount_type":{"type":"string","enum":["fixed","percent"],"example":"fixed"},"net_total":{"type":"string","pattern":"^\\d+(?:\\.\\d+)?$","example":"997.0"},"line_digest":{"type":"string","minLength":64,"maxLength":64,"example":"5904202fbd937b303d34f366e2bd0149b746be65e80acba0f66a4325735b99fb"},"reconstructed":{"type":"boolean","example":false},"reconstruction":{"type":["object","null"],"required":["source_type","source_id","actor_id","reason"],"properties":{"source_type":{"type":"string","enum":["Crm::Item"],"example":"Crm::Item"},"source_id":{"type":"integer","minimum":1,"example":934},"actor_id":{"type":"integer","minimum":1,"example":12},"reason":{"type":"string","minLength":1,"maxLength":1000,"example":"Contrato conferido pelo administrador."}}}}}}},"digest":{"type":"string","minLength":64,"maxLength":64,"description":"SHA-256 digest of the proposed line and metadata plan.","example":"63430ddc94fb70c5e529111053055c6a0ce2e9685a270998fdca4db6a2aca60d"},"fingerprint":{"type":"string","minLength":64,"maxLength":64,"description":"SHA-256 of the complete account-scoped graph. Send it unchanged to apply.","example":"57bd093c095c62da2abdc0c8c81a0dfcd9f750c48f3a8f85468a24d517967e6c"},"applied":{"type":"boolean","description":"Present and true after a successful apply.","example":true},"replayed":{"type":"boolean","description":"Present after apply and true when the destination already matched exactly.","example":false}}},"commerce_integrity_check_summary":{"type":"object","description":"Exact count plus a bounded list of affected record identifiers.","required":["count","sample_ids"],"properties":{"count":{"type":"integer","minimum":0,"example":2},"sample_ids":{"type":"array","maxItems":100,"items":{"type":"integer","minimum":1},"example":[67,68]}}},"commerce_integrity_profile_summary":{"type":"object","description":"Commercial contacts whose verified profile still has one or more explicit gaps.","required":["count","sample"],"properties":{"count":{"type":"integer","minimum":0,"example":1},"sample":{"type":"array","maxItems":100,"items":{"type":"object","required":["id","missing_fields"],"properties":{"id":{"type":"integer","minimum":1,"example":1704},"missing_fields":{"type":"array","uniqueItems":true,"items":{"type":"string","enum":["name","contact_channel","tax_id","address","owner","organization"]},"example":["tax_id","address"]}}}}}},"commerce_integrity_organization_profile_summary":{"type":"object","description":"Commercial organizations whose verified profile still has one or more explicit gaps.","required":["count","sample"],"properties":{"count":{"type":"integer","minimum":0,"example":1},"sample":{"type":"array","maxItems":100,"items":{"type":"object","required":["id","missing_fields"],"properties":{"id":{"type":"integer","minimum":1,"example":41},"missing_fields":{"type":"array","uniqueItems":true,"items":{"type":"string","enum":["name","legal_name","legal_type","contact_channel","tax_id","address","owner"]},"example":["legal_name","tax_id","address"]}}}}}},"commerce_integrity_audit_response":{"type":"object","required":["payload"],"properties":{"payload":{"type":"object","description":"PII-free, read-only commercial completeness report. Every count is exact; samples contain at most 100 account-scoped record ids and never contain customer identity values. Missing catalog snapshots are reported only when a linked deal or financial counterpart has persisted lines; nullable product and variant references on retained historical snapshots are not gaps.","required":["active_payment_orders_without_charge","charges_without_order","voided_externals_without_ignore","connection_mismatches","paid_orders_without_paid_at","settled_charges_without_paid_at","orders_with_missing_linked_charge","charge_order_contact_mismatches","charge_order_organization_mismatches","charge_order_deal_mismatches","charge_order_amount_mismatches","charge_order_currency_mismatches","charge_order_status_mismatches","charge_order_gateway_mismatches","charge_order_external_id_mismatches","order_deal_contact_mismatches","order_deal_organization_mismatches","order_deal_owner_mismatches","charge_order_owner_mismatches","paid_orders_without_seller_commission","paid_orders_with_multiple_seller_commissions","paid_orders_with_commission_payee_mismatch","commercial_contacts_incomplete","commercial_organizations_incomplete","operational_orders_without_owner","operational_orders_without_deal","operational_orders_without_catalog_items","charges_without_catalog_items","paid_order_contacts_not_customer","paid_order_deals_not_won","contact_primary_organization_without_membership","order_organization_without_membership","charge_organization_without_membership","potential_duplicate_orders"],"properties":{"active_payment_orders_without_charge":{"$ref":"#/components/schemas/commerce_integrity_check_summary"},"charges_without_order":{"$ref":"#/components/schemas/commerce_integrity_check_summary"},"voided_externals_without_ignore":{"$ref":"#/components/schemas/commerce_integrity_check_summary"},"connection_mismatches":{"$ref":"#/components/schemas/commerce_integrity_check_summary"},"paid_orders_without_paid_at":{"$ref":"#/components/schemas/commerce_integrity_check_summary"},"settled_charges_without_paid_at":{"$ref":"#/components/schemas/commerce_integrity_check_summary"},"orders_with_missing_linked_charge":{"$ref":"#/components/schemas/commerce_integrity_check_summary"},"charge_order_contact_mismatches":{"$ref":"#/components/schemas/commerce_integrity_check_summary"},"charge_order_organization_mismatches":{"$ref":"#/components/schemas/commerce_integrity_check_summary"},"charge_order_deal_mismatches":{"$ref":"#/components/schemas/commerce_integrity_check_summary"},"charge_order_amount_mismatches":{"$ref":"#/components/schemas/commerce_integrity_check_summary"},"charge_order_currency_mismatches":{"$ref":"#/components/schemas/commerce_integrity_check_summary"},"charge_order_status_mismatches":{"$ref":"#/components/schemas/commerce_integrity_check_summary"},"charge_order_gateway_mismatches":{"$ref":"#/components/schemas/commerce_integrity_check_summary"},"charge_order_external_id_mismatches":{"$ref":"#/components/schemas/commerce_integrity_check_summary"},"order_deal_contact_mismatches":{"$ref":"#/components/schemas/commerce_integrity_check_summary"},"order_deal_organization_mismatches":{"$ref":"#/components/schemas/commerce_integrity_check_summary"},"order_deal_owner_mismatches":{"$ref":"#/components/schemas/commerce_integrity_check_summary"},"charge_order_owner_mismatches":{"$ref":"#/components/schemas/commerce_integrity_check_summary"},"paid_orders_without_seller_commission":{"$ref":"#/components/schemas/commerce_integrity_check_summary"},"paid_orders_with_multiple_seller_commissions":{"$ref":"#/components/schemas/commerce_integrity_check_summary"},"paid_orders_with_commission_payee_mismatch":{"$ref":"#/components/schemas/commerce_integrity_check_summary"},"commercial_contacts_incomplete":{"$ref":"#/components/schemas/commerce_integrity_profile_summary"},"commercial_organizations_incomplete":{"$ref":"#/components/schemas/commerce_integrity_organization_profile_summary"},"operational_orders_without_owner":{"$ref":"#/components/schemas/commerce_integrity_check_summary"},"operational_orders_without_deal":{"$ref":"#/components/schemas/commerce_integrity_check_summary"},"operational_orders_without_catalog_items":{"$ref":"#/components/schemas/commerce_integrity_check_summary"},"charges_without_catalog_items":{"$ref":"#/components/schemas/commerce_integrity_check_summary"},"paid_order_contacts_not_customer":{"$ref":"#/components/schemas/commerce_integrity_check_summary"},"paid_order_deals_not_won":{"$ref":"#/components/schemas/commerce_integrity_check_summary"},"contact_primary_organization_without_membership":{"$ref":"#/components/schemas/commerce_integrity_check_summary"},"order_organization_without_membership":{"$ref":"#/components/schemas/commerce_integrity_check_summary"},"charge_organization_without_membership":{"$ref":"#/components/schemas/commerce_integrity_check_summary"},"potential_duplicate_orders":{"$ref":"#/components/schemas/commerce_integrity_check_summary"}}}}},"sales_commission_reconciliation_preview":{"type":"object","description":"Fingerprinted, read-only evaluation of an explicit historical order selection.","required":["fingerprint","fingerprint_version","selection","summary","rules","items"],"properties":{"fingerprint":{"type":"string","pattern":"^[0-9a-f]{64}$","example":"8a79d86d6e264ce27e64c9f6f55e489de996f5492d0e5a7c98d63d483e4149a1"},"fingerprint_version":{"type":"integer","enum":[3],"example":3},"selection":{"type":"object","required":["order_ids","count"],"properties":{"order_ids":{"type":"array","items":{"type":"integer"},"example":[101,102]},"count":{"type":"integer","minimum":1,"example":2}}},"summary":{"type":"object","required":["selected","logical_sales_count","eligible","already_reconciled","skipped","economic_gross_by_currency","economic_commission_by_currency","commission_to_apply_by_currency","existing_commission_by_currency","credits_to_create_by_currency","reversals_to_create_by_currency","payable_after_apply_by_currency","period_movements"],"properties":{"selected":{"type":"integer","minimum":1,"example":2},"logical_sales_count":{"type":"integer","minimum":0,"description":"Number of logical sales after consolidating installments and duplicate gateway projections.","example":1},"eligible":{"type":"integer","minimum":0,"example":1},"already_reconciled":{"type":"integer","minimum":0,"example":1},"skipped":{"type":"integer","minimum":0,"example":0},"economic_gross_by_currency":{"type":"array","description":"Gross paid amount represented by the selected logical sales before commission calculation.","items":{"$ref":"#/components/schemas/sales_commission_reconciliation_currency_amount"}},"economic_commission_by_currency":{"type":"array","description":"Expected commission over unique economic sales, including amounts already represented in the ledger.","items":{"$ref":"#/components/schemas/sales_commission_reconciliation_currency_amount"}},"commission_to_apply_by_currency":{"type":"array","description":"Net change in commission payable after compensating eligible open legacy credits.","items":{"$ref":"#/components/schemas/sales_commission_reconciliation_currency_amount"}},"existing_commission_by_currency":{"type":"array","description":"Existing commission history represented by the explicit selection.","items":{"$ref":"#/components/schemas/sales_commission_reconciliation_currency_amount"}},"credits_to_create_by_currency":{"type":"array","description":"Positive order credits appended by apply, including period realignments.","items":{"$ref":"#/components/schemas/sales_commission_reconciliation_currency_amount"}},"reversals_to_create_by_currency":{"type":"array","description":"Negative compensations appended for eligible open legacy deal credits.","items":{"$ref":"#/components/schemas/sales_commission_reconciliation_currency_amount"}},"payable_after_apply_by_currency":{"type":"array","description":"Final net payable represented by the selected economic sales after apply.","items":{"$ref":"#/components/schemas/sales_commission_reconciliation_currency_amount"}},"period_movements":{"type":"array","description":"Open legacy commission amounts moving from their stored month to the order economic month.","items":{"$ref":"#/components/schemas/sales_commission_reconciliation_period_movement"}}}},"rules":{"type":"object","required":["paid_basis","won_basis","existing_history","statement_period","logical_sale_allocation"],"properties":{"paid_basis":{"type":"string","enum":["operational_paid_order"],"example":"operational_paid_order"},"won_basis":{"type":"string","enum":["settled_order_without_deal_or_linked_to_won_deal"],"example":"settled_order_without_deal_or_linked_to_won_deal"},"existing_history":{"type":"string","enum":["closed_history_never_reopened_open_legacy_realigned"],"example":"closed_history_never_reopened_open_legacy_realigned"},"statement_period":{"type":"string","enum":["existing_custom_period_or_account_timezone_calendar_month"],"example":"existing_custom_period_or_account_timezone_calendar_month"},"logical_sale_allocation":{"type":"string","enum":["cumulative_by_deal_owner_currency_provenance_and_frozen_policy"],"example":"cumulative_by_deal_owner_currency_provenance_and_frozen_policy"}}},"items":{"type":"array","items":{"$ref":"#/components/schemas/sales_commission_reconciliation_item"}}}},"sales_commission_reconciliation_result":{"allOf":[{"$ref":"#/components/schemas/sales_commission_reconciliation_preview"},{"type":"object","required":["applied","applied_count","skipped_after_lock_order_ids"],"properties":{"applied":{"type":"array","description":"Accrual receipts created by this apply attempt; empty on an idempotent replay.","items":{"type":"object","required":["order_id","accrual_id","ledger_action","reversal_accrual_ids","statement_period"],"properties":{"order_id":{"type":"integer","minimum":1,"example":101},"accrual_id":{"type":"integer","minimum":1,"example":81},"ledger_action":{"type":"string","enum":["create","replace_legacy_open","adjust_open_order_history"],"example":"create"},"reversal_accrual_ids":{"type":"array","description":"Compensating rows created when an eligible open legacy deal credit was realigned.","items":{"type":"integer","minimum":1},"example":[]},"statement_period":{"type":"array","minItems":2,"maxItems":2,"items":{"type":"string","format":"date"},"example":["2026-08-01","2026-08-31"]}}}},"applied_count":{"type":"integer","minimum":0,"example":1},"skipped_after_lock_order_ids":{"type":"array","description":"Compatibility field; locked fingerprint verification now makes post-preview skips unnecessary.","items":{"type":"integer","minimum":1},"example":[]},"replayed":{"type":"boolean","description":"True when the supplied fingerprint had already been applied completely and no money was written.","example":false}}}]},"sales_commission_reconciliation_currency_amount":{"type":"object","required":["currency","amount"],"properties":{"currency":{"type":"string","pattern":"^[A-Z]{3}$","example":"BRL"},"amount":{"type":"string","description":"Decimal amount in major currency units.","example":"200.00"}}},"sales_commission_reconciliation_period_movement":{"type":"object","required":["currency","amount","from_period_start","from_period_end","to_period_start","to_period_end"],"properties":{"currency":{"type":"string","pattern":"^[A-Z]{3}$","example":"BRL"},"amount":{"type":"string","example":"99.70"},"from_period_start":{"type":"string","format":"date","example":"2026-07-01"},"from_period_end":{"type":"string","format":"date","example":"2026-07-31"},"to_period_start":{"type":"string","format":"date","example":"2026-08-01"},"to_period_end":{"type":"string","format":"date","example":"2026-08-31"}}},"sales_commission_reconciliation_item":{"type":"object","description":"Decision for one selected account order. Fields absent from an unavailable or ineligible order are omitted.","required":["order_id","outcome","ledger_action"],"properties":{"order_id":{"type":"integer","minimum":1,"example":101},"status":{"type":"string","enum":["pending","paid","partially_paid","overdue","refunded","canceled","failed"],"example":"paid"},"owner_id":{"type":"integer","minimum":1,"example":7},"currency":{"type":"string","pattern":"^[A-Z]{3}$","example":"BRL"},"economic_at":{"type":"string","format":"date-time","example":"2026-08-15T14:00:00.000000Z"},"gross_amount":{"type":"string","example":"1000.0"},"recognized_amount":{"type":"string","example":"1000.0"},"assignment_id":{"type":"integer","minimum":1,"example":9},"plan":{"type":"object","required":["id","name","basis","credit_mode"],"properties":{"id":{"type":"integer","minimum":1,"example":3},"name":{"type":"string","example":"Standard commission"},"basis":{"type":"string","enum":["paid","won"],"example":"paid"},"credit_mode":{"type":"string","enum":["single","split"],"example":"single"}}},"expected_commission_amount":{"type":"string","example":"100.0"},"commission_allocation":{"$ref":"#/components/schemas/sales_commission_allocation"},"net_commission_amount":{"type":"string","example":"100.0"},"ledger_action":{"type":"string","enum":["create","replace_legacy_open","adjust_open_order_history","retain","reuse","none"],"description":"Append-only decision; retain and reuse never duplicate existing financial history.","example":"create"},"existing_commission_amount":{"type":"string","example":"100.0"},"existing_commission_currency":{"type":"string","pattern":"^[A-Z]{3}$","example":"BRL"},"existing_source_type":{"type":"string","enum":["Crm::Order","Crm::Item"],"example":"Crm::Order"},"existing_source_id":{"type":"integer","minimum":1,"example":101},"canonical_order_id":{"type":"integer","minimum":1,"example":101},"source_order_id":{"type":"integer","minimum":1,"example":100},"crm_item_id":{"type":"integer","minimum":1,"example":44},"statement_id":{"type":"integer","minimum":1,"example":18},"statement_status":{"type":"string","enum":["approved","paid"],"example":"approved"},"outcome":{"type":"string","enum":["eligible","already_reconciled","skipped"],"example":"eligible"},"reason":{"type":["string","null"],"description":"Stable machine-readable refusal or deduplication reason.","example":null},"reason_label":{"type":["string","null"],"description":"Localized explanation for the authenticated operator.","example":null},"history_reason":{"type":["string","null"],"description":"Existing economic-history classification.","example":null},"legacy_alignment":{"type":"array","description":"Immutable source snapshot bound into the fingerprint when an open legacy deal credit will be realigned.","items":{"type":"object","additionalProperties":true,"description":"Account-scoped accrual identity, value, payee, status and economic timestamp."}},"period_movements":{"type":"array","items":{"$ref":"#/components/schemas/sales_commission_reconciliation_period_movement"}}}},"sales_commission_allocation":{"type":"object","description":"Deterministic allocation of one commission plan across the paid invoices of a logical CRM sale. Cumulative amounts guarantee that installments and mixed payment methods sum to the rounded commission on the sale total while each order remains independently auditable.","required":["scope","order_ids"],"properties":{"scope":{"type":"string","enum":["crm_item","order","duplicate_economic_order"],"example":"crm_item"},"crm_item_id":{"type":"integer","minimum":1,"example":44},"order_ids":{"type":"array","items":{"type":"integer","minimum":1},"example":[101,102]},"position":{"type":"integer","minimum":1,"example":2},"gross_before":{"type":"string","example":"500.0"},"gross_through":{"type":"string","example":"997.0"},"commission_before":{"type":"string","example":"50.0"},"commission_through":{"type":"string","example":"99.7"},"canonical_order_id":{"type":"integer","minimum":1,"example":101}}},"sales_commission_statement_line":{"type":"object","description":"One operator-facing commercial sale within a commission statement. Multiple append-only ledger events are grouped through an explicit CRM deal when present; otherwise each order or source stays separate. Unrelated orders are never inferred from names, values or dates. accrual_ids preserves the complete audit trail behind the summarized amounts.","required":["key","kind","title","order_ids","payments_charge_ids","payment_count","event_count","gross_amount","commission_amount","has_adjustments","accrual_ids"],"properties":{"key":{"type":"string","example":"deal:44"},"kind":{"type":"string","enum":["deal","order","source"],"example":"deal"},"title":{"type":"string","example":"Assinatura anual"},"crm_item_id":{"type":["integer","null"],"example":44},"contact_id":{"type":["integer","null"],"example":19},"organization_id":{"type":["integer","null"],"example":8},"order_ids":{"type":"array","items":{"type":"integer"},"example":[101,102]},"payments_charge_ids":{"type":"array","items":{"type":"integer"},"example":[201,202]},"payment_count":{"type":"integer","minimum":0,"description":"Number of explicitly linked payment charges, or orders when no charge link exists.","example":2},"event_count":{"type":"integer","minimum":1,"description":"Number of append-only commission ledger events summarized by this line.","example":2},"gross_amount":{"type":"number","description":"Net commission basis represented by the events in this statement period.","example":997.0},"commission_amount":{"type":"number","description":"Net commission represented by the events in this statement period.","example":99.7},"effective_rate":{"type":["number","null"],"description":"Net effective rate as a fraction; null when the net gross basis is zero.","example":0.1},"accrued_at":{"type":["string","null"],"format":"date-time","example":"2026-09-05T12:00:00Z"},"has_adjustments":{"type":"boolean","description":"Whether the summarized events include a reversal, partial reversal, reinstatement or allocation adjustment.","example":false},"accrual_ids":{"type":"array","items":{"type":"integer"},"example":[501,502]}}},"sales_commission_statement":{"type":"object","description":"One seller or affiliate commission statement for a closed calendar period. commission_lines is the operator-facing commercial-sale read model; accruals is the append-only financial audit trail.","required":["id","account_id","payee_id","payee_type","currency","period_start","period_end","status","total_accrued","total_approved","total_paid","commission_lines","accruals"],"properties":{"id":{"type":"integer","example":77},"account_id":{"type":"integer","example":1},"payee_id":{"type":"integer","example":7},"payee_type":{"type":"string","enum":["User","Sales::Affiliate"],"example":"User"},"payee_name":{"type":["string","null"],"description":"Display name of the User or Affiliate identified by payee_type and payee_id.","example":"Ana Vendedora"},"currency":{"type":"string","pattern":"^[A-Z]{3}$","example":"BRL"},"period_start":{"type":"string","format":"date","example":"2026-07-01"},"period_end":{"type":"string","format":"date","example":"2026-07-31"},"status":{"type":"string","enum":["open","approved","paid"],"example":"open"},"total_accrued":{"type":"number","description":"Net commission accrued for the period in major currency units.","example":1240.5},"total_approved":{"type":"number","example":0.0},"total_paid":{"type":"number","example":0.0},"approved_by_id":{"type":["integer","null"],"example":null},"approved_at":{"type":["string","null"],"format":"date-time","example":null},"created_at":{"type":"string","format":"date-time","example":"2026-07-31T23:00:00Z"},"updated_at":{"type":"string","format":"date-time","example":"2026-07-31T23:00:00Z"},"commission_lines":{"type":"array","description":"Commercial-sale summary grouped only by explicit durable CRM relations.","items":{"$ref":"#/components/schemas/sales_commission_statement_line"}},"accruals":{"type":"array","description":"Every payable non-reversed-status ledger event for this payee and period, newest first. Closed-period clawbacks remain visible as negative events.","items":{"type":"object","required":["id","source_type","source_label","gross_amount","commission_amount"],"properties":{"id":{"type":"integer","example":501},"source_type":{"type":"string","description":"Polymorphic event class; clients should render source_label instead.","example":"Payments::Charge"},"source_label":{"type":"string","description":"Translated human label for source_type in the account locale.","example":"Cobrança"},"source_id":{"type":["integer","null"],"description":"Source-record id used to trace the financial event.","example":8},"gross_amount":{"type":"number","description":"Net basis represented by this ledger event in major currency units.","example":500.0},"rate_applied":{"type":["number","null"],"description":"Effective rate as a fraction; 0.08 means 8 percent.","example":0.08},"commission_amount":{"type":"number","description":"Net commission represented by this ledger event in major currency units.","example":40.0}}}}}},"commerce_reconciliation_user_summary":{"type":"object","description":"Account-local operator identity shown as commercial context.","required":["id"],"properties":{"id":{"type":"integer","minimum":1,"example":7},"name":{"type":"string","example":"Maria Oliveira"}}},"commerce_reconciliation_item":{"type":"object","description":"One account-scoped reconciliation decision together with the current source record context. Contact and organization fields follow the caller's field-level visibility rules and can therefore be masked or omitted. Missing source means the audited queue row outlived a record that was removed.","required":["id","source_type","source_id","state","reason","suggestions","resolution","resolved_at","resolved_by_id","created_at","updated_at","source"],"properties":{"id":{"type":"integer","minimum":1,"example":41},"source_type":{"type":"string","enum":["payments_charge","crm_order","commerce_event"],"example":"payments_charge"},"source_id":{"type":"integer","minimum":1,"example":5821},"state":{"type":"string","enum":["pending","linked","ignored","duplicate"],"example":"pending"},"reason":{"type":"string","example":"charge_without_order_link"},"suggestions":{"type":"array","description":"Exact stable-identity candidates only; names, e-mails, amounts and dates are never fuzzy matched.","items":{"type":"object","required":["source_type","source_id","confidence","reason"],"properties":{"source_type":{"type":"string","enum":["payments_charge","crm_order","commerce_event"],"example":"crm_order"},"source_id":{"type":"integer","minimum":1,"example":9102},"confidence":{"type":"number","format":"float","minimum":1,"maximum":1,"example":1.0},"reason":{"type":"string","enum":["exact_gateway_external_id"],"example":"exact_gateway_external_id"}}}},"resolution":{"type":"object","description":"Empty while pending; otherwise records the durable automatic or operator decision.","additionalProperties":false,"properties":{"operation":{"type":"string","enum":["link","ignore","merge","sales_graph_repair","detector_auto_resolved","detector_auto_ignored"],"example":"link"},"relationship_key":{"type":"string","example":"charge:5821:order:9102"},"source_type":{"type":"string","enum":["payments_charge","crm_order","commerce_event"],"example":"payments_charge"},"source_id":{"type":"integer","minimum":1,"example":5821},"target_type":{"type":"string","enum":["payments_charge","crm_order","commerce_event"],"example":"crm_order"},"target_id":{"type":"integer","minimum":1,"example":9102},"reason":{"type":"string","example":"operator_ignored"},"ignored_external_id":{"type":["integer","null"],"example":73},"ignored_external_created":{"type":"boolean","example":true},"canonical_item_id":{"type":"integer","minimum":1,"example":40},"fingerprint":{"type":"string","minLength":64,"maxLength":64,"example":"57bd093c095c62da2abdc0c8c81a0dfcd9f750c48f3a8f85468a24d517967e6c"}}},"resolved_at":{"type":["string","null"],"format":"date-time","example":"2026-08-14T12:30:00Z"},"resolved_by_id":{"type":["integer","null"],"example":7},"created_at":{"type":"string","format":"date-time","example":"2026-08-14T11:00:00Z"},"updated_at":{"type":"string","format":"date-time","example":"2026-08-14T12:30:00Z"},"source":{"oneOf":[{"type":"null"},{"type":"object","description":"Current customer, commercial and financial context for the source. Type-specific fields are omitted when they do not apply; protected identity fields can be masked or omitted.","required":["id","type"],"properties":{"id":{"type":"integer","minimum":1,"example":5821},"type":{"type":"string","enum":["payments_charge","crm_order","commerce_event"],"example":"payments_charge"},"amount":{"type":"string","example":"149.90"},"currency":{"type":"string","example":"BRL"},"gateway":{"type":"string","example":"asaas"},"external_id":{"type":"string","example":"pay_000012345678"},"external_reference":{"type":"string","example":"cart-7821"},"status":{"type":"string","enum":["pending","awaiting_payment","confirmed","paid","partially_paid","overdue","refunded","partially_refunded","canceled","failed","cart_abandoned","order_placed","payment_pending","payment_confirmed","payment_declined","due_soon","chargeback","subscription_late","subscription_canceled"],"example":"paid"},"description":{"type":"string","example":"Annual plan"},"title":{"type":"string","example":"Annual plan order"},"billing_type":{"type":"string","enum":["pix","boleto","credit_card","hosted_link","undefined","debit_card"],"example":"pix"},"due_date":{"type":"string","format":"date","example":"2026-08-15"},"ordered_at":{"type":"string","format":"date-time","example":"2026-08-14T11:00:00Z"},"paid_at":{"type":"string","format":"date-time","example":"2026-08-14T11:05:00Z"},"payments_charge_id":{"type":["integer","null"],"example":5821},"delivery_status":{"type":"string","enum":["sent","skipped","failed"],"example":"sent","description":"Outcome of the commerce recovery-card send, written by Commerce::DeliveryOutcome. Null means no send has been attempted for this event yet, which is the case for every event created before the recovery wave and for any event no automation rule ever acted on."},"delivery_reason":{"type":"string","example":"automation_dispatched","description":"Why the recovery card was or was not delivered. For sent/skipped this is a canonical token shared with the follow-up engine (no_contact, no_conversation, no_channel_inbox, whatsapp_window_closed, throttled, maestro_paused, channel_unavailable, sequence_not_published) plus commerce's own already_sent, test_send, operator_ignored and historical_event. Deliberately NOT declared as a closed set — for a failed delivery it carries the truncated provider/error message instead."},"outcome":{"type":"string","enum":["recovered","lost"],"example":"recovered"},"expires_at":{"type":"string","format":"date-time","example":"2026-08-21T11:00:00Z"},"contact":{"type":"object","required":["id"],"description":"Identity fields can be masked or omitted by field-level permissions.","properties":{"id":{"type":"integer","minimum":1,"example":4821},"name":{"type":"string","example":"Ana Silva"},"email":{"type":"string","format":"email","example":"ana@example.com"},"phone_number":{"type":"string","example":"+5511999999999"}}},"organization":{"type":"object","required":["id"],"description":"Organization fields can be masked or omitted by field-level permissions.","properties":{"id":{"type":"integer","minimum":1,"example":27},"name":{"type":"string","example":"ACME Brasil"}}},"crm_item":{"type":"object","required":["id"],"properties":{"id":{"type":"integer","minimum":1,"example":934},"title":{"type":"string","example":"Renewal opportunity"}}},"conversation":{"type":"object","required":["id","display_id"],"properties":{"id":{"type":"integer","minimum":1,"example":11901},"display_id":{"type":"integer","minimum":1,"example":321}}},"created_by":{"$ref":"#/components/schemas/commerce_reconciliation_user_summary"},"owner":{"$ref":"#/components/schemas/commerce_reconciliation_user_summary"},"affiliate":{"type":"object","required":["id"],"properties":{"id":{"type":"integer","minimum":1,"example":19},"name":{"type":"string","example":"Partner South"},"referral_code":{"type":"string","example":"PARTNER-SOUTH"}}}}}]}}},"commerce_reconciliation_item_response":{"type":"object","required":["payload"],"properties":{"payload":{"$ref":"#/components/schemas/commerce_reconciliation_item"}}},"commerce_reconciliation_items_response":{"type":"object","required":["payload","meta"],"properties":{"payload":{"type":"array","items":{"$ref":"#/components/schemas/commerce_reconciliation_item"}},"meta":{"type":"object","required":["count","current_page","total_pages","per_page","has_more"],"properties":{"count":{"type":"integer","minimum":0,"example":42},"current_page":{"type":"integer","minimum":1,"example":1},"total_pages":{"type":"integer","minimum":0,"example":2},"per_page":{"type":"integer","minimum":1,"maximum":100,"example":25},"has_more":{"type":"boolean","example":true}}}}},"calendar_calendar":{"type":"object","description":"A native calendar that groups events.","properties":{"id":{"type":"number"},"account_id":{"type":"number"},"name":{"type":"string"},"color":{"type":"string"},"kind":{"type":"string","enum":["native","google"],"description":"Calendar kind. `native` is a calendar that lives only in the platform; `google` is one mirrored from a connected Google account. These are the ONLY two values the model defines — the contract used to claim `[personal, team, google, booking]`, which does not include `native`, the value almost every row carries, so a response validator rejected the whole listing. Who a calendar belongs to is a separate concern, expressed by `assignments`."},"timezone":{"type":"string","description":"IANA timezone identifier (e.g. \"America/Sao_Paulo\", \"UTC\"). Rails timezone names are also accepted on input; an unrecognized value is ignored in favor of the next fallback.","example":"America/Sao_Paulo"},"description":{"type":"string"},"is_default":{"type":"boolean"},"connection_id":{"type":"number","description":"Google connection id when kind=google."},"google_calendar_id":{"type":"string","description":"Upstream Google calendar id when kind=google."},"google_backed":{"type":"boolean","description":"Whether this calendar is actually wired to Google (an active connection plus an upstream calendar id). It is what decides whether an event is pushed to Google and whether a Meet link can be created."},"prevent_double_booking":{"type":["boolean","null"],"description":"Per-calendar overlap guard. `null` is meaningful and is the default: it means \"inherit the account-wide setting\". `true`/`false` is a deliberate decision for THIS calendar — `false` is how an account with several attendants sharing one calendar keeps booking overlapping appointments."},"assignments":{"type":"array","description":"Who the calendar belongs to. An EMPTY list means account-wide (visible to everyone), which is why the field is always present rather than omitted.","items":{"type":"object","description":"One agent, team or inbox this calendar is scoped to.","properties":{"id":{"type":"number","description":"Assignment row id."},"assignable_type":{"type":"string","enum":["User","Team","Inbox"],"description":"What kind of holder this assignment points at."},"assignable_id":{"type":"number","description":"Id of the agent, team or inbox."}},"additionalProperties":false}},"archived_at":{"type":["string","null"],"format":"date-time","description":"When the calendar was archived (soft delete), or null while it is active."},"archived":{"type":"boolean"},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"additional_attributes":{"type":"object","additionalProperties":true,"description":"Channel- and source-specific metadata for this record (e.g. browser info, referer, social profile identifiers). The key set depends on the originating channel."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"calendar_event":{"type":"object","description":"A calendar event with attendees, recurrence and conferencing.","properties":{"id":{"type":"number"},"account_id":{"type":"number"},"calendar_id":{"type":"number"},"title":{"type":"string"},"description":{"type":"string"},"location":{"type":"string"},"starts_at":{"type":"string","format":"date-time"},"ends_at":{"type":"string","format":"date-time"},"all_day":{"type":"boolean"},"timezone":{"type":"string","description":"IANA timezone identifier (e.g. \"America/Sao_Paulo\", \"UTC\"). Rails timezone names are also accepted on input; an unrecognized value is ignored in favor of the next fallback.","example":"America/Sao_Paulo"},"status":{"type":"string","enum":["tentative","confirmed","cancelled"]},"source":{"type":"string","enum":["native","google","booking"],"description":"Where the event came from. `native` is anything created inside the platform (the agenda drawer, an automation, the API, a Maestro tool); `google` is an event imported from a mirrored Google calendar; `booking` is one created by confirming a bookable event type. These are the only three values the model defines — the contract used to claim `[manual, google, booking, automation]`, which omits `native` (the value almost every row carries) and invents two that cannot occur, so a response validator rejected nearly every event."},"transparency":{"type":"string","description":"Whether the event occupies its host, mirroring Google's own field. `transparent` is what Google shows as \"Livre\"/\"Free\": the appointment is real and is displayed in the agenda, but it does NOT block a bookable slot, so the public booking page will still sell that time. Always present — a natively created event is always `opaque`.","enum":["opaque","transparent"]},"event_type":{"type":"object","description":"The bookable event type this event came from. ABSENT (not null) when the event was not created by a booking — a natively created or Google-imported event has no type.","properties":{"id":{"type":"number"},"name":{"type":"string"},"color":{"type":"string","description":"Hex colour configured for the type; takes precedence over the calendar's colour in the grid."}}},"event_type_id":{"type":"number","description":"Flat id of the same event type, for clients that only need the key. ABSENT (not null) when the event has no booking."},"contact_id":{"type":"number"},"conversation_id":{"type":"number"},"crm_item_id":{"type":"number"},"task_id":{"type":"number"},"recurrence":{"type":"object","description":"JSONB rrule config (frequency, interval, until, count, days).","additionalProperties":true},"conferencing":{"type":"object","description":"JSONB conferencing info (provider, link, etc.).","additionalProperties":true},"meet_url":{"type":["string","null"],"format":"uri","description":"Participant-facing conference join URL; possession can grant meeting access."},"custom_attributes":{"type":"object","additionalProperties":true,"description":"Custom attribute values for this record, keyed by the attribute key defined by the account (see the Custom Attributes API). Value types follow each attribute's definition (text, number, date, list, ...)."},"additional_attributes":{"type":"object","additionalProperties":true,"description":"Channel- and source-specific metadata for this record (e.g. browser info, referer, social profile identifiers). The key set depends on the originating channel."},"attendees":{"type":"array","items":{"$ref":"#/components/schemas/calendar_attendee"}},"archived":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"calendar_event_type":{"type":"object","description":"A bookable event type (Calendly-style) with intake questions and availability rules.","properties":{"id":{"type":"number"},"account_id":{"type":"number"},"name":{"type":"string"},"slug":{"type":"string"},"public_token":{"type":"string","description":"Opaque token used to derive the public booking URL."},"duration_minutes":{"type":"number"},"occupancy":{"type":"string","enum":["slot","availability_window"],"description":"How much of the day ONE booking consumes. `slot` (the default) blocks only the appointment plus its buffers. `availability_window` blocks the WHOLE availability window (shift) containing the chosen start — booking 10:30 inside an 08:00-12:00 morning removes every remaining morning time and leaves the 14:00-18:00 shift for sale. The shift IS the availability window, so two shifts in a day means two ranges separated by a gap. The appointment itself keeps its real start and duration everywhere the customer sees it; the reserved shift is recorded on that appointment under `additional_attributes.shift_window`, never as a second event."},"buffer_before":{"type":["number","null"],"description":"Buffer in minutes before the event. TRI-STATE: `null` means this event type inherits the account default (Agenda settings -\u003e scheduling defaults); a number — INCLUDING 0, which means \"no buffer\" — is this event type's own rule."},"buffer_after":{"type":["number","null"],"description":"Buffer in minutes after the event. Tri-state exactly like `buffer_before`: `null` inherits the account default, a number (0 included) overrides it."},"min_notice_minutes":{"type":["number","null"],"description":"Minimum notice required to book, in minutes. `null` inherits the account default; 0 means a slot can be booked right up to its start."},"max_advance_days":{"type":["number","null"],"description":"How far in the future a booking can be scheduled, in days. `null` inherits the account default."},"min_cancel_notice_minutes":{"type":["number","null"],"description":"Minimum minutes before start that a booking may still be cancelled or rescheduled. `null` inherits the account default; 0 allows cancelling at any time."},"max_reschedules":{"type":["number","null"],"description":"How many times one booking may be moved. `null` means no limit. Counted on the booking itself (`reschedule_count`), so it applies to a booking rescheduled repeatedly by the same visitor."},"auto_no_show_minutes":{"type":["number","null"],"description":"Minutes after the start at which an unattended booking is marked as a no-show. `null` never does it automatically."},"resolved_scheduling_limits":{"type":"object","description":"The EFFECTIVE numbers this event type books by, after inheritance: its own column when set, otherwise the account default, otherwise the shipped default. Read-only — send the raw columns above to change anything.","properties":{"buffer_before":{"type":"number","description":"Effective buffer before","in minutes.":null},"buffer_after":{"type":"number","description":"Effective buffer after","in minutes.":null},"min_notice_minutes":{"type":"number","description":"Effective minimum booking notice","in minutes.":null},"min_cancel_notice_minutes":{"type":"number","description":"Effective cancellation window","in minutes.":null},"max_advance_days":{"type":"number","description":"Effective booking horizon","in days.":null}},"additionalProperties":false},"inherited_scheduling_limits":{"type":"array","description":"Which of the limits above are currently INHERITED (their column is null). Read-only; it is what the dashboard uses to show the inherited number as a placeholder instead of a value.","items":{"type":"string","enum":["buffer_before","buffer_after","min_notice_minutes","min_cancel_notice_minutes","max_advance_days"]}},"location_type":{"type":"string","enum":["in_person","phone","google_meet","custom"],"description":"Where the appointment happens when the booker is offered no choice."},"location_options":{"type":"array","description":"The location menu offered to the booker, as `location_type` keys. EMPTY when the operator offers no choice (a one-item menu is not a choice and is collapsed to `[]` server-side).","items":{"type":"string","enum":["in_person","phone","google_meet","custom"]}},"host_assignment":{"type":"string"},"is_public":{"type":"boolean"},"color":{"type":"string"},"confirmation_message":{"type":"string"},"redirect_url":{"type":"string"},"catalog_product_id":{"type":"number"},"questions":{"type":"array","description":"Intake form questions (JSONB array).","items":{"type":"object","description":"An intake question definition collected on the booking page.","properties":{"id":{"type":"string","description":"Stable key the booking's answers are stored under."},"label":{"type":"string","description":"The question label shown to the visitor."},"type":{"type":"string","description":"Which control the public form renders for this question.","enum":["text","textarea","select","radio","checkbox","number","email","phone","date"]},"required":{"type":"boolean","description":"Whether the visitor must answer the question."},"placeholder":{"type":"string","description":"Hint text shown inside the field."},"options":{"type":"array","description":"Choices for a select, radio or checkbox question.","items":{"type":"string"}}},"additionalProperties":true}},"location_details":{"type":"object","description":"One address, phone number or link per location type, keyed by the `location_type` value. Copied onto the confirmed event so it reaches the .ics file, the confirmation message and Google.","additionalProperties":{"type":"string"}},"intake_phone_required":{"type":"boolean","description":"Whether a booking is refused when it carries no usable phone / WhatsApp number."},"guest_emails_enabled":{"type":"boolean","description":"Whether the booker may invite extra guests to the appointment."},"max_guests":{"type":"number","description":"Upper bound on extra guests accepted per booking."},"google_conflict_calendar_ids":{"type":"array","description":"Ids of the mirrored Google calendars whose busy time blocks this type's slots. Includes the type's own calendar when that one is Google-backed.","items":{"type":"number"}},"google_destination_calendar_id":{"type":"number","description":"Id of the mirrored Google calendar that receives confirmed bookings, or null when the type does not write to Google."},"side_effects":{"type":"object","description":"JSONB automation side-effects config.","additionalProperties":true},"archived":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"calendar_event_type_write":{"type":"object","description":"The writable surface of a bookable event type, shared by create and update. Collection-valued fields follow key-absent semantics on update: omit the key to leave the set alone, send an empty array to clear it.","properties":{"name":{"type":"string","description":"Operator-facing name of the event type."},"slug":{"type":"string","description":"URL slug. Derived from the name when omitted."},"duration_minutes":{"type":"number","description":"Length of the appointment in minutes."},"buffer_before":{"type":"number","description":"Minutes kept free before the appointment. An explicit 0 disables the account default."},"buffer_after":{"type":"number","description":"Minutes kept free after the appointment. An explicit 0 disables the account default."},"occupancy":{"type":"string","enum":["slot","availability_window"],"description":"How much of the day ONE booking consumes. `slot` (the default, and what every event type did before this existed) blocks only [start - buffer_before, start + duration_minutes + buffer_after]. `availability_window` blocks the WHOLE availability window (the shift) that contains the chosen start: booking 10:30 inside an 08:00-12:00 morning removes every remaining morning time and leaves the 14:00-18:00 shift for sale. The shift IS the availability window, so a day with two shifts is a day with two availability ranges separated by a GAP — ranges that touch are merged and would behave as one long shift. The visitor's own appointment keeps its real start and duration in the .ics, the confirmation message, Meet and Google; the reserved shift is recorded on that appointment (`additional_attributes.shift_window`) rather than as a second event."},"min_notice_minutes":{"type":"number","description":"A booker may not choose a slot starting sooner than this."},"max_advance_days":{"type":"number","description":"A booker may not choose a slot further out than this."},"min_cancel_notice_minutes":{"type":"number","description":"Cancelling is refused inside this window before the start."},"max_reschedules":{"type":"number","description":"How many times one booking may be moved. Null means unlimited."},"auto_no_show_minutes":{"type":"number","description":"Mark the booking a no-show this many minutes after the start. Null disables it."},"location_type":{"type":"string","description":"Where the appointment happens when the booker is offered no choice.","enum":["in_person","phone","google_meet","custom"]},"location_options":{"type":"array","description":"The location menu offered to the booker. Fewer than two entries is not a choice and is stored as an empty menu, so `location_type` applies.","items":{"type":"string","enum":["in_person","phone","google_meet","custom"]}},"location_details":{"type":"object","description":"One address, phone number or link per location type, keyed by the `location_type` value. Copied onto the confirmed event so it reaches the .ics file, the confirmation message and Google. `google_meet` needs no entry — its link is generated.","additionalProperties":{"type":"string"},"properties":{"in_person":{"type":"string","description":"Street address of the in-person appointment."},"phone":{"type":"string","description":"Number the host will call","or dialing instructions.":null},"custom":{"type":"string","description":"Free-form link or instructions."}}},"host_assignment":{"type":"string","description":"How a host is picked when the type has more than one.","enum":["round_robin","collective","fixed"]},"is_public":{"type":"boolean","description":"Whether the type is listed on the public booking portal."},"color":{"type":"string","description":"Hex colour used for this type's events in the agenda grid."},"confirmation_message":{"type":"string","description":"Message shown to the booker after confirming, and used as the event description."},"redirect_url":{"type":"string","description":"Send the booker here after confirming instead of showing the confirmation screen."},"catalog_product_id":{"type":"number","description":"Optional link to a catalog product, so a bookable type maps to a sellable service."},"intake_phone_required":{"type":"boolean","description":"Refuse a booking that carries no usable phone / WhatsApp number. Enforced server-side, so a caller hitting the public endpoint directly cannot bypass it."},"guest_emails_enabled":{"type":"boolean","description":"Let the booker invite extra guests to the appointment."},"max_guests":{"type":"number","description":"Upper bound on extra guests. Anything beyond it is dropped, never rejected."},"google_conflict_calendar_ids":{"type":"array","description":"Ids of mirrored Google calendars whose busy time blocks this type's slots. Ids that are not Google-backed are ignored. Send an empty array to clear the set.","items":{"type":"number"}},"google_destination_calendar_id":{"type":"number","description":"Id of the mirrored Google calendar that receives confirmed bookings. Null (or omitted on create) falls back to the type's own calendar when that one is Google-backed."},"host_user_ids":{"type":"array","description":"Agents eligible to host this type.","items":{"type":"number"}},"questions":{"type":"array","description":"Intake questions the booker answers on the public form.","items":{"type":"object","properties":{"id":{"type":"string","description":"Stable key the answers are stored under. Generated positionally when omitted."},"label":{"type":"string","description":"Question text. A question with no label is discarded."},"type":{"type":"string","description":"Which control the public form renders. An unknown value degrades to free text.","enum":["text","textarea","select","radio","checkbox","number","email","phone","date"]},"required":{"type":"boolean","description":"Whether the booker must answer before confirming."},"placeholder":{"type":"string","description":"Hint text shown inside the field."},"options":{"type":"array","description":"Choices for a select, radio or checkbox question. Blank entries and duplicates are dropped.","items":{"type":"string"}}}}},"payment_mode":{"type":"string","description":"Whether and how the booking must be paid for.","enum":["none","one_off","subscription_gate","recurring"]},"payment_hold_mode":{"type":"string","description":"`reserve_and_hold` occupies the slot while payment is pending; `pay_first` holds nothing until the charge clears.","enum":["reserve_and_hold","pay_first"]},"payment_amount":{"type":"string","description":"Price charged for the booking, as a decimal string in major units."},"payment_currency":{"type":"string","description":"ISO-4217 currency code for the price."},"payments_connection_id":{"type":"number","description":"Payment gateway connection used to charge the booker."},"payments_plan_id":{"type":"number","description":"Recurring plan used when the mode is subscription-based."},"payment_billing_types":{"type":"array","description":"Payment methods offered on the public page.","items":{"type":"string"}},"payment_hold_minutes":{"type":"number","description":"How long an unpaid slot stays held before it is released."},"payment_deposit_amount":{"type":"string","description":"Up-front deposit, as a decimal string in major units. Null charges the full amount."},"availability_rules":{"type":"array","description":"Per-type weekly windows overriding the calendar's hours. Send an empty array to clear them and fall back to the calendar.","items":{"type":"object","properties":{"day_of_week":{"type":"number","description":"0 = Sunday through 6 = Saturday."},"start_minute":{"type":"number","description":"Minutes from midnight when the window opens."},"end_minute":{"type":"number","description":"Minutes from midnight when the window closes."}}}}}},"calendar_attendee":{"type":"object","description":"A calendar event attendee (contact, agent user or ad-hoc email).","properties":{"id":{"type":"number"},"event_id":{"type":"number"},"contact_id":{"type":"number"},"user_id":{"type":"number"},"email":{"type":"string"},"response_status":{"type":"string","enum":["accepted","declined","tentative","needs_action"],"description":"Canonical attendee RSVP state. The needsAction input alias is returned as needs_action."},"organizer":{"type":"boolean"},"optional":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"calendar_connection":{"type":"object","description":"A Google OAuth connection linked to the account (oauth tokens are NEVER serialized).","properties":{"id":{"type":"number"},"account_id":{"type":"number"},"provider":{"type":"string","enum":["google"]},"google_account_email":{"type":"string","description":"The Google account email associated with this connection."},"status":{"type":"string","enum":["active","error","revoked"],"description":"Lifecycle status. `error` means the grant is invalid and needs reconnection."},"healthy":{"type":"boolean","description":"Whether the connection can actually reach Google right now: active AND with no recent `oauth.refresh` failure. `status` alone is not enough — a connection whose refresh token died stays `active` until something flips it, which is how a dead grant once went unnoticed for a day while bookings were confirmed with no Meet link. Read this, not `status`, to decide health.\n"},"requires_reconnect":{"type":"boolean","description":"The actionable half of the same verdict: true when only a new OAuth consent fixes it (revoked grant or dead refresh token), as opposed to a single event that merely failed to sync.\n"},"last_error":{"type":["string","null"],"description":"Most recent failure across every calendar on this connection plus the connection-scoped ones (token refresh). Always surfaced, even while `status` is active — that gap is what hid the outage. A value here does NOT by itself mean the connection is broken: check `last_error_at`.\n"},"last_error_at":{"type":["string","null"],"format":"date-time","description":"When `last_error` happened. Use it to tell a live failure from one already resolved."},"recent_error_count":{"type":"number","description":"Failures on this connection in the last 24 hours. 0 with a `last_error` set means recovered."},"connected_by_user_id":{"type":"number","description":"The agent who connected this account (nullable)."},"poll_interval_minutes":{"type":"number","description":"Polling fallback interval (minutes) for inbound sync."},"calendars_count":{"type":"number","description":"Number of mirrored Google calendars on this connection."},"calendars":{"type":"array","description":"Per-calendar sync observability (WS6) — name + sync markers only, never the token blob.","items":{"type":"object","properties":{"id":{"type":"number"},"name":{"type":"string"},"google_calendar_id":{"type":"string"},"archived":{"type":"boolean"},"sync":{"type":["object","null"],"description":"The mirror's sync state, or null when no sync state exists yet.","properties":{"direction":{"type":"string","enum":["two_way","import_only","export_only"]},"status":{"type":"string","enum":["idle","syncing","error"]},"last_synced_at":{"type":["string","null"],"format":"date-time"},"last_full_sync_at":{"type":["string","null"],"format":"date-time"},"watch_active":{"type":"boolean","description":"false → sync falls back to the polling sweep (still works, just slower)."},"watch_error":{"type":["string","null"],"description":"Why the realtime push channel is off (blank webhook receiver, unverified domain…). Not an outage on its own — without a channel the sync falls back to polling.\n"},"last_error":{"type":["string","null"],"description":"The most recent sync error message for this mirrored calendar."},"last_error_at":{"type":["string","null"],"format":"date-time","description":"When this calendar's `last_error` happened."},"recent_error_count":{"type":"number","description":"Failures on this mirrored calendar in the last 24 hours."}}}}}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"calendar_settings_config":{"type":"object","description":"The resolved calendar/booking configuration, one key per section. Resolution order is seed defaults -\u003e account default -\u003e scoped override (scope \"event_type:\u003cid\u003e\"), so a section omitted at a scope inherits the level above it. On PATCH the same shape is deep-merged, so sending one key never clobbers the rest.","properties":{"booking":{"type":"object","description":"Booking engine tunables (slot generation, windows, brand, CRM and task side-effect config).","properties":{"slot_minutes":{"type":"integer","description":"Interval between offered start times, in minutes.","example":30},"buffer_before":{"type":"integer","description":"Minutes blocked before each appointment.","example":0},"buffer_after":{"type":"integer","description":"Minutes blocked after each appointment.","example":0},"min_notice_minutes":{"type":"integer","description":"Minimum minutes before start a slot can still be booked.","example":60},"max_advance_days":{"type":"integer","description":"How many days into the future slots are offered.","example":60},"min_cancel_notice_minutes":{"type":"integer","description":"Minimum minutes before start a booking can still be cancelled.","example":60},"first_day_of_week":{"type":"integer","description":"First day of the week for the pickers (0 = Sunday ... 6 = Saturday).","example":0},"timezone":{"type":"string","description":"Fallback timezone used when the visitor does not supply one.","example":"UTC"},"host_assignment":{"type":"string","description":"Default host-assignment strategy for new bookable types.","enum":["round_robin","collective","fixed"],"example":"round_robin"},"branding":{"type":"object","description":"Public booking-page brand overrides. Empty falls back to the account avatar and name.","properties":{"logo_url":{"type":["string","null"],"description":"Logo shown on the public booking page, or null to use the account avatar.","example":"https://cdn.example.com/logo.png"},"brand_color":{"type":["string","null"],"description":"Accent color (hex) for the public page, or null.","example":"#1f93ff"},"display_name":{"type":["string","null"],"description":"Host name shown publicly, or null to use the account name.","example":"Acme Studio"}}},"crm":{"type":"object","description":"Booking -\u003e CRM deal side-effect configuration.","properties":{"create_if_missing":{"type":"boolean","description":"Create a deal when the booking contact has no open one.","example":false},"default_pipeline_id":{"type":["integer","null"],"description":"Pipeline the created deal lands in, or null for the account default.","example":12},"default_stage_id":{"type":["integer","null"],"description":"Stage the created deal lands in, or null for the first open stage.","example":34}}},"task":{"type":"object","description":"Booking -\u003e task side-effect configuration (title, owner and reminder).","properties":{"title_template":{"type":["string","null"],"description":"Task title template with the safe calendar variables (for example title, contact_name, date, time, host). Null keeps the built-in \"Appointment: \u003ctitle\u003e\" copy.","example":"Appointment: {{title}}"},"assignee":{"type":"string","description":"Who the task is assigned to and who the reminder targets.","enum":["host","creator","unassigned"],"example":"host"},"reminder_offset_minutes":{"type":"integer","description":"Minutes BEFORE the appointment start to fire the task reminder (0 = at start).","example":0},"reminder_channel":{"type":"string","description":"Channel used for the task reminder.","enum":["in_app","email"],"example":"in_app"}}},"payment":{"type":"object","description":"Paid-scheduling defaults (the per-event-type payment_mode is the real gate).","properties":{"enabled":{"type":"boolean","description":"Informational flag that paid scheduling is in use.","example":false},"default_hold_minutes":{"type":"integer","description":"Default slot-hold window while payment is pending.","example":15},"default_connection_id":{"type":["integer","null"],"description":"Default payment connection id, or null.","example":7},"default_billing_types":{"type":"array","description":"Payment methods offered by default (ships as pix, boleto, credit_card). The values are the payment charge billing types; the dashboard picker exposes the first four, while the API accepts any of them.","items":{"type":"string","enum":["pix","boleto","credit_card","hosted_link","undefined","debit_card"],"example":"pix"}},"gate_fallback":{"type":"string","description":"What a non-member gets on a subscription-gated type.","enum":["recurring","needs_subscription"],"example":"recurring"},"cancellation_refund":{"type":"string","description":"Refund policy applied on cancellation. Ships as \"manual\" (an operator issues the refund from the payment module); no automatic refund path is wired yet.","example":"manual"}}}}},"side_effects":{"type":"object","description":"What runs automatically when a booking is confirmed. Each toggle is independent, including whatsapp_web_event: the native WhatsApp invite card is governed by this toggle ALONE and never by the delivery/channel settings - see its description.","properties":{"conversation":{"type":"boolean","description":"Open (or reuse) a conversation for the booking contact.","example":true},"task":{"type":"boolean","description":"Create a task plus its reminder (configured under booking.task).","example":false},"crm_deal":{"type":"boolean","description":"Attach or create a CRM deal (configured under booking.crm).","example":false},"meet":{"type":"boolean","description":"Request a Google Meet link for the event.","example":true},"ics_email":{"type":"boolean","description":"Send the confirmation email with the .ics invite.","example":true},"whatsapp_web_event":{"type":"boolean","description":"Send the FREE native WhatsApp calendar event (Web inboxes only) when a booking is confirmed - a card the customer taps into their phone calendar, in addition to the confirmation message. Ships OFF: it is a second, unsolicited object in the thread, so it is sent only when this toggle is explicitly true. Nothing else turns it on - the WhatsApp delivery/channel settings govern the text notification and have no effect here. When the appointment is later cancelled, the card is revoked in the conversation (within WhatsApp's ~2-day revoke window).","example":false}}},"reminders":{"type":"object","description":"Reminder lead times, operator-authored message texts and the channel-aware delivery config.","properties":{"lead_times_minutes":{"type":"array","description":"How long before the appointment each reminder is sent, in minutes.","items":{"type":"integer","example":60}},"channels":{"type":"array","description":"WHICH channels a contact-facing notification (confirmation, reminder, reschedule, cancellation) goes out on; reminders.delivery decides HOW each one sends it (inbox, approved template, buttons). An empty array notifies the contact on nothing. Omit the key entirely and the list is derived from the delivery toggles, so an account configured before this key was read keeps its current behaviour. The agent-facing notification is NOT governed here - it rides on the calendar.event.reminder_due dispatch, which also feeds automation rules and account webhooks.","items":{"type":"string","enum":["email","whatsapp"],"example":"email"}},"auto_no_show_minutes":{"type":["integer","null"],"description":"Minutes after start to auto-flag a no-show, or null to disable.","example":15},"reminder_template":{"description":"Reminder text with safe variables. DUAL-SHAPED: either a plain string (one wording for every language — how every account was configured before the texts became per-language, still read verbatim) or a `{ locale =\u003e text }` map, resolved for the CONTACT's language with a fallback to the same base language, then the account language, then the `default` slot. null uses the shipped copy.","oneOf":[{"type":["string","null"],"example":"Hi {{contact_name}}, your appointment is on {{datetime}}."},{"type":"object","description":"Per-language wording, keyed by locale (`pt_BR`, `en`, …). `default` is where the first per-language edit lifts the legacy single text.","additionalProperties":{"type":"string"},"example":{"pt_BR":"Hi {{contact_name}}, your appointment is on {{datetime}}."}}],"example":"Hi {{contact_name}}, your appointment is on {{datetime}}."},"confirmation_template":{"description":"Confirmation text. DUAL-SHAPED: either a plain string (one wording for every language — how every account was configured before the texts became per-language, still read verbatim) or a `{ locale =\u003e text }` map, resolved for the CONTACT's language with a fallback to the same base language, then the account language, then the `default` slot. null uses the shipped copy.","oneOf":[{"type":["string","null"],"example":"Your appointment {{title}} is confirmed for {{datetime}}."},{"type":"object","description":"Per-language wording, keyed by locale (`pt_BR`, `en`, …). `default` is where the first per-language edit lifts the legacy single text.","additionalProperties":{"type":"string"},"example":{"pt_BR":"Your appointment {{title}} is confirmed for {{datetime}}."}}],"example":"Your appointment {{title}} is confirmed for {{datetime}}."},"reschedule_template":{"description":"Reschedule text. DUAL-SHAPED: either a plain string (one wording for every language — how every account was configured before the texts became per-language, still read verbatim) or a `{ locale =\u003e text }` map, resolved for the CONTACT's language with a fallback to the same base language, then the account language, then the `default` slot. null uses the shipped copy.","oneOf":[{"type":["string","null"],"example":"Your appointment moved to {{datetime}}."},{"type":"object","description":"Per-language wording, keyed by locale (`pt_BR`, `en`, …). `default` is where the first per-language edit lifts the legacy single text.","additionalProperties":{"type":"string"},"example":{"pt_BR":"Your appointment moved to {{datetime}}."}}],"example":"Your appointment moved to {{datetime}}."},"cancel_template":{"description":"Cancellation text. DUAL-SHAPED: either a plain string (one wording for every language — how every account was configured before the texts became per-language, still read verbatim) or a `{ locale =\u003e text }` map, resolved for the CONTACT's language with a fallback to the same base language, then the account language, then the `default` slot. null uses the shipped copy.","oneOf":[{"type":["string","null"],"example":"Your appointment on {{datetime}} was cancelled."},{"type":"object","description":"Per-language wording, keyed by locale (`pt_BR`, `en`, …). `default` is where the first per-language edit lifts the legacy single text.","additionalProperties":{"type":"string"},"example":{"pt_BR":"Your appointment on {{datetime}} was cancelled."}}],"example":"Your appointment on {{datetime}} was cancelled."},"labels":{"type":"object","description":"Auxiliary single-line texts the operator can reword, per language, keyed by label then locale (`{ manage_button: { pt_BR: 'Gerenciar agendamento' } }`). Today: `manage_prompt` (the line above the native button) and `manage_button` (its caption). The optional `reminder_interactive_title`, `confirmation_interactive_title`, `reschedule_interactive_title` and `cancel_interactive_title` keys hold the header title of each kind's buttons message (60 bytes at most). An absent key inherits through the configured cascade; an explicit empty scalar or selected locale value omits its header.","properties":{"reminder_interactive_title":{"description":"Optional interactive header for the reminder. A plain string applies to every locale; a locale map selects the configured locale. Empty explicitly suppresses this header. No shipped or generic fallback title is created.","oneOf":[{"type":"string"},{"type":"object","description":"The title per locale, keyed by locale code (`pt_BR`, `en`, `es`, or `default`).","additionalProperties":{"type":"string"}}]},"confirmation_interactive_title":{"description":"Optional interactive header for the reminder. A plain string applies to every locale; a locale map selects the configured locale. Empty explicitly suppresses this header. No shipped or generic fallback title is created.","oneOf":[{"type":"string"},{"type":"object","description":"The title per locale, keyed by locale code (`pt_BR`, `en`, `es`, or `default`).","additionalProperties":{"type":"string"}}]},"reschedule_interactive_title":{"description":"Optional interactive header for the reminder. A plain string applies to every locale; a locale map selects the configured locale. Empty explicitly suppresses this header. No shipped or generic fallback title is created.","oneOf":[{"type":"string"},{"type":"object","description":"The title per locale, keyed by locale code (`pt_BR`, `en`, `es`, or `default`).","additionalProperties":{"type":"string"}}]},"cancel_interactive_title":{"description":"Optional interactive header for the reminder. A plain string applies to every locale; a locale map selects the configured locale. Empty explicitly suppresses this header. No shipped or generic fallback title is created.","oneOf":[{"type":"string"},{"type":"object","description":"The title per locale, keyed by locale code (`pt_BR`, `en`, `es`, or `default`).","additionalProperties":{"type":"string"}}]}},"additionalProperties":{"type":"object","description":"One label's wording per locale, keyed by locale code.","additionalProperties":{"type":"string"}},"example":{"manage_button":{"pt_BR":"Gerenciar agendamento"}}},"delivery":{"type":"object","description":"How the CONTACT is notified. WhatsApp Web sends the rich native event; WhatsApp Cloud sends a session message inside the 24h window and the approved template below outside it.","properties":{"email":{"type":"boolean","description":"Legacy mirror of the \"email\" member of reminders.channels, which is what the send now reads. Kept in sync by the dashboard and still used to derive the channel list for an account that has never stored one.","example":true},"whatsapp":{"type":"boolean","description":"Legacy mirror of the \"whatsapp\" member of reminders.channels (see that key). Opt-in, because outside the 24h window it sends a PAID Cloud template. It does NOT affect the native WhatsApp invite card, which is governed solely by side_effects.whatsapp_web_event.","example":false},"whatsapp_inbox_id":{"type":["integer","null"],"description":"The WhatsApp inbox used to reach the contact, or null to use their existing one.","example":42},"templates":{"type":"object","description":"Approved WhatsApp Cloud template per notification kind, used OUTSIDE the 24h window. A kind with no name skips WhatsApp for that notification (email still covers it). DUAL-SHAPED per kind: either the template config itself (the shape written before templates became per-language, still read verbatim) or a `{ locale =\u003e config }` map — Meta matches name + language + approved, so a pt_BR template loses its params for an `en` contact.","additionalProperties":true,"properties":{"reminder":{"$ref":"#/components/schemas/calendar_delivery_template_bucket"},"confirmation":{"$ref":"#/components/schemas/calendar_delivery_template_bucket"},"reschedule":{"$ref":"#/components/schemas/calendar_delivery_template_bucket"},"cancel":{"$ref":"#/components/schemas/calendar_delivery_template_bucket"}}},"interactive_buttons":{"type":"object","description":"Per-kind switch for the NATIVE \"Manage booking\" button, which ships the manage link as a tappable button instead of a bare URL in the text. Default TRUE and stored only when turned OFF, so an untouched account keeps the default and the config stays small.","additionalProperties":{"type":"boolean"},"example":{"cancel":false}}}}}},"sync":{"type":"object","description":"Google Calendar synchronisation policy (account/connection level, never per event type).","properties":{"conflict_strategy":{"type":"string","description":"Reconciliation strategy when both sides changed since the last sync. \"last_write_wins\" (the default) lets the most recent change win; any other value disables last-write-wins and keeps the native record authoritative.","example":"last_write_wins"},"default_direction":{"type":"string","description":"Sync direction applied to newly mirrored Google calendars (seeds the calendar's sync state): two_way imports and exports, import_only only pulls from Google, export_only only pushes.","enum":["two_way","import_only","export_only"],"example":"two_way"},"poll_interval_minutes":{"type":"integer","description":"Fallback poll interval when the push channel is unavailable.","example":2}}}}},"calendar_delivery_template":{"type":"object","description":"An approved WhatsApp Cloud template (HSM) mapped to one calendar notification kind, used when the contact is OUTSIDE Meta's 24h session window. Leave `name` empty to skip WhatsApp for that kind.","properties":{"name":{"type":["string","null"],"description":"The approved template name as registered with Meta, or null to skip WhatsApp for this kind.","example":"agenda_confirmation_pt_br"},"language":{"type":["string","null"],"description":"The template language code, or null to fall back to the account locale.","example":"pt_BR"},"namespace":{"type":["string","null"],"description":"Legacy template namespace (360dialog); null on WhatsApp Cloud.","example":null},"params":{"type":"array","description":"Positional fillers for the template body variables, in order (entry 1 fills {{1}}, and so on). Each entry is either one of the calendar variable names - contact_name, title, date, time, datetime, link, location, host - which is resolved at send time, or any other string, which is sent verbatim as a literal. An unrecognised name is therefore never an error: it is delivered as-is. This is the name the shared message-settings editor writes; `body_params` is the older name and is still read, so a mapping saved before the two surfaces converged keeps sending exactly what it sends today.","items":{"type":"string","example":"contact_name"}},"body_params":{"type":"array","description":"Legacy name for `params`, still read by the send. Prefer `params` for new writes.","items":{"type":"string","example":"contact_name"}},"url_button":{"type":"boolean","description":"True when the template has a dynamic URL button (the \"manage booking\" CTA). The send fills that button with the booking's manage token, producing the public manage link.","example":true}}},"calendar_delivery_template_bucket":{"description":"What one notification kind maps to OUTSIDE Meta's 24h window. DUAL-SHAPED, and read both ways by the send, so nothing has to be migrated:\n\n  * the template config itself — the shape written before templates became per-language, i.e. ONE\n    approved template for the kind whatever the contact's language;\n  * a `{ locale =\u003e config }` map — what the shared message-settings editor writes. Meta matches\n    name + language + approved, so a template approved in `pt_BR` silently loses its params (and gets\n    rejected) for a contact resolving to `en`; the per-language map is what fixes that.\n\nAn entry whose `name` is empty skips WhatsApp for that kind (email still covers it).","oneOf":[{"$ref":"#/components/schemas/calendar_delivery_template"},{"type":"object","description":"Per-language approved templates for this kind, keyed by locale (`pt_BR`, `en`, …).","additionalProperties":{"$ref":"#/components/schemas/calendar_delivery_template"}}],"example":{"pt_BR":{"name":"agenda_reminder_pt_br","language":"pt_BR","params":["contact_name","title","datetime"],"url_button":true}}},"calendar_booking":{"type":"object","description":"The visitor-facing payload for a booking, returned identically by create, show (manage), reschedule and cancel — all four render the same view. Scoped to the manage_token holder: it carries only this booking's own data, never an account id, a host email or any other booking.\n","properties":{"server_now":{"type":"string","format":"date-time","description":"Authoritative response time for the unchanged hold deadline."},"manage_token":{"type":"string","description":"Opaque token that IS the access key — echoed so the page keeps a reschedule/cancel handle."},"status":{"type":"string","description":"Booking lifecycle. The paid-scheduling states (pending_payment while the charge clears, payment_failed when pay_first loses the slot, expired when the hold lapses) exist without an event, unlike the confirmed/rescheduled ones.\n","enum":["confirmed","rescheduled","cancelled","no_show","pending_payment","payment_failed","expired"]},"locale":{"type":"string","description":"The host account's language, so the manage page localizes itself like the booking page."},"visitor_timezone":{"type":["string","null"],"description":"IANA timezone the visitor booked in."},"selected_location":{"type":["string","null"],"description":"What the booker picked when the event type offered a `location_options` menu; null when no choice was offered — `event_type.location_type` then describes the location.\n","enum":["in_person","phone","google_meet","custom",null]},"answers":{"type":"object","description":"The visitor's intake answers, keyed by the question id from the event type (the reserved internal scheduling and recovery metadata is stripped). Free-form: the keys are operator-defined.\n","additionalProperties":{"type":"string"}},"created_at":{"type":"string","format":"date-time"},"payment":{"type":"object","description":"Present only for a booking that requires payment. Carries just what the payer needs to pay (PIX code/QR, boleto, hosted link), the live status and the hold countdown — never a gateway secret. The page polls this until the status flips. A recurring booking instead returns the subscription checkout handle.\n","properties":{"payable":{"type":"boolean","description":"False after hold expiry or terminal payment; payment instruments are omitted."},"status":{"type":"string","description":"The live charge status the page polls on, until it settles. A recurring booking whose first invoice the gateway still owes reports `pending`.\n","enum":["pending","awaiting_payment","confirmed","paid","overdue","refunded","partially_refunded","canceled","failed"]},"amount":{"type":"string","description":"Amount charged up front, decimal in major units (e.g. \"100.0\")."},"currency":{"type":"string","description":"ISO currency code."},"billing_type":{"type":["string","null"],"description":"The payment method the charge was opened with.","enum":["pix","boleto","credit_card","hosted_link",null]},"pix_payload":{"type":["string","null"],"description":"PIX copy-and-paste code."},"pix_qr_base64":{"type":["string","null"],"description":"PIX QR code as a base64 PNG (no data: prefix)."},"boleto_url":{"type":["string","null"],"description":"Printable boleto URL."},"hosted_url":{"type":["string","null"],"description":"Hosted checkout URL for card payments."},"hold_expires_at":{"type":["string","null"],"format":"date-time","description":"When the reserved slot is released if payment does not clear."},"is_deposit":{"type":"boolean","description":"Present and true only when the up-front charge is a deposit, not the full price."},"full_amount":{"type":"string","description":"Full price, decimal in major units — only alongside is_deposit."},"balance_amount":{"type":"string","description":"Remaining balance collected manually on completion — only alongside is_deposit."},"subscription":{"type":"boolean","description":"Present and true only for a recurring booking whose first invoice the gateway issues."},"checkout_url":{"type":["string","null"],"description":"Preapproval checkout the payer authorizes — recurring bookings only."}}},"event":{"type":"object","description":"The booked appointment. Absent when the booking has no event yet (expired hold, failed payment).","properties":{"title":{"type":"string"},"starts_at":{"type":"string","format":"date-time"},"ends_at":{"type":"string","format":"date-time"},"timezone":{"type":"string","description":"IANA timezone identifier (e.g. \"America/Sao_Paulo\", \"UTC\"). Rails timezone names are also accepted on input; an unrecognized value is ignored in favor of the next fallback.","example":"America/Sao_Paulo"},"location":{"type":["string","null"],"description":"The resolved location text for this appointment."},"meet_url":{"type":["string","null"],"description":"The conference link, when the location resolved to google_meet and a link was issued."},"status":{"type":"string","description":"The event's own status, independent of the booking's.","enum":["confirmed","tentative","cancelled"]}}},"event_type":{"type":"object","description":"Public-safe slice of the booked type, so the page re-renders its header and confirmation.","properties":{"public_token":{"type":"string"},"name":{"type":"string"},"duration_minutes":{"type":"integer"},"location_type":{"type":"string","enum":["in_person","phone","google_meet","custom"],"description":"Where a bookable meeting takes place."},"confirmation_message":{"type":["string","null"]},"redirect_url":{"type":["string","null"]}}}}},"maestro_transport_error":{"type":"object","description":"A failure of the hop between this API and the Maestro service, rather than a failure of the request itself. The `code` is stable and safe to branch on; the `error` message is localized to the account language and meant for a human. Nothing was executed when one of these is returned, so the call can be retried once the underlying condition clears.","properties":{"error":{"type":"string","description":"Localized, human-readable explanation of the failure.","example":"Maestro indisponível"},"code":{"type":"string","description":"Stable machine code. `maestro_timeout` — the service did not answer in time. `maestro_unreachable` — the connection was refused, reset or the host did not resolve. `maestro_error` — the service answered in a way the gateway could not use. `maestro_auth_failed` — the service rejected the server-to-server credential (a deployment key mismatch; never the caller's own session). `maestro_disabled` — the operator turned the Maestro area off for this installation. `maestro_not_configured` — no admin key was ever provisioned.","enum":["maestro_timeout","maestro_unreachable","maestro_error","maestro_auth_failed","maestro_disabled","maestro_not_configured"],"example":"maestro_unreachable"}}},"maestro_usage_bucket":{"type":"object","properties":{"key":{"type":"string","description":"Bucket identity — a surface name (`turn`, `dashboards`, `onboarding`, `judge`, `improve`, `copilot`, `call`), a model id, or a Robô id. `total` on the grand total.","example":"turn"},"label":{"type":["string","null"],"description":"Human name for `key`, when the sidecar knows one — today only on the per-Robô breakdown, whose `key` is a row in the sidecar's own agent table (NOT a platform `agent_bot` id) and therefore cannot be resolved on this side. `null` means the key is already the name; a Robô deleted after it spent keeps its id here rather than borrowing another one.","example":"Suporte Nível 1"},"calls":{"type":"integer","description":"Model calls in this bucket.","example":10},"input_tokens":{"type":"integer","description":"Prompt tokens billed.","example":800},"output_tokens":{"type":"integer","description":"Completion tokens billed.","example":100},"cache_read_tokens":{"type":"integer","description":"Subset of `input_tokens` served from the provider's prompt cache, and therefore discounted. Tracked separately so a cache that stopped working and one that never existed do not produce the same numbers.","example":380},"cost_usd":{"type":["number","null"],"format":"float","description":"Complete cost in USD, measured at call time and never re-priced later. Null when any recorded work is unpriced or incomplete; a measured zero remains 0. `measured_subtotal_usd` is a separate known portion, never a replacement for an unknown total or an amount to add to this cost.","example":null},"measured_subtotal_usd":{"type":["number","null"],"format":"float","description":"Sum of only measured, priced portions, including known components of incomplete rows. Null when no measured portion resolved to a rate; a genuinely measured zero remains 0. When `cost_is_floor` is true this is only a lower bound, never the complete cost or an extra charge.","example":0.05},"unpriced_calls":{"type":"integer","description":"Calls on rows whose cost is not a complete priced measurement: a rate or part of the usage is missing. Above zero means `cost_usd` is null; only `measured_subtotal_usd`, when present, is a known lower bound. Calls remain counted even when both monetary amounts are unknown.","example":2},"cost_is_floor":{"type":"boolean","description":"True when `unpriced_calls` is above zero. The complete `cost_usd` is then null and any `measured_subtotal_usd` is only a lower bound. This flag does not turn a missing subtotal into 0.","example":true}},"example":{"key":"turn","label":null,"calls":5,"input_tokens":2400,"output_tokens":600,"cache_read_tokens":0,"cost_usd":null,"measured_subtotal_usd":0.05,"unpriced_calls":2,"cost_is_floor":true},"examples":[{"key":"dashboards","label":null,"calls":1,"input_tokens":0,"output_tokens":0,"cache_read_tokens":0,"cost_usd":null,"measured_subtotal_usd":null,"unpriced_calls":1,"cost_is_floor":true},{"key":"dashboards","label":null,"calls":1,"input_tokens":0,"output_tokens":0,"cache_read_tokens":0,"cost_usd":0.0,"measured_subtotal_usd":0.0,"unpriced_calls":0,"cost_is_floor":false},{"key":"turn","label":null,"calls":5,"input_tokens":2400,"output_tokens":600,"cache_read_tokens":0,"cost_usd":null,"measured_subtotal_usd":0.05,"unpriced_calls":2,"cost_is_floor":true}]},"maestro_agent_config":{"type":"object","description":"The full Maestro agent configuration (the sidecar's AgentConfigIn). Sent whole on PUT /maestro/agents/{id}/config and nested under `config` on agent create/update. Every field is optional - an omitted field keeps the shipped default shown in its description. WRITE-ONLY fields (secrets, provider_keys, chatwoot_native_keys) are never echoed back; their READ-ONLY companions (secret_keys, provider_keys_set, native_keys_set) report only WHICH keys are configured.","properties":{"persona":{"type":"string","description":"Who the agent is - tone, role and boundaries, prepended to every turn. Empty by default.","example":"Você é a atendente virtual da Acme, cordial e objetiva."},"instructions":{"type":"string","description":"Task instructions appended after the persona (the operating playbook). Empty by default.","example":"Sempre confirme o CPF antes de consultar um pedido."},"default_model":{"type":"string","description":"Primary model as \"provider:model\". Defaults to openai:gpt-5.4-mini-2026-03-17. Validated against the provider catalog returned by /maestro/agents/meta.","example":"openai:gpt-5.4-mini-2026-03-17"},"fallback_models":{"type":"array","description":"Models tried in order when the primary fails or is rate-limited. Empty by default.","items":{"type":"string","example":"anthropic:claude-haiku-4-5-20251001"}},"enabled_tools":{"type":"array","description":"Names of the built-in tools this agent may call. Empty by default (no tools).","items":{"type":"string","example":"set_labels"}},"autonomy_level":{"type":"string","description":"How the agent acts: autopilot replies on its own; copilot only drafts suggestions for a human; hybrid replies but parks sensitive actions for approval.","enum":["autopilot","copilot","hybrid"],"example":"autopilot"},"interaction_mode":{"type":"string","description":"Whether the agent SPEAKS. `converse` is the normal agent: it reads the conversation and replies. `silent` runs the same turn — tools, labels, CRM writes, handoff — and sends nothing to the contact, which is how an agent classifies and routes without a human seeing a second voice in the thread. Orthogonal to `autonomy_level`: a silent agent can still be autopilot (it acts freely, it just does not reply) and a converse agent can still be copilot.","enum":["converse","silent"],"example":"converse"},"search_config":{"type":"object","description":"Web search for this agent, served by the installation's Tavily key. Absent or `enabled: false` means the search and page-read tools are unavailable to it, whatever the key situation is.","properties":{"enabled":{"type":"boolean","description":"Whether this agent may search the web at all.","example":true},"search_depth":{"type":"string","description":"`basic` is one pass and is what most answers need; `advanced` digs further per query and costs proportionally more.","enum":["basic","advanced"],"example":"basic"},"max_results":{"type":"integer","description":"How many results come back per query. Higher values buy coverage with context budget.","example":5},"topic":{"type":"string","description":"Which index to search. `news` biases towards recency, `finance` towards market sources; `general` is everything else.","enum":["general","news","finance"],"example":"general"},"include_domains":{"type":"array","description":"When non-empty, results come ONLY from these domains — the way to keep an agent inside your own documentation instead of the open web.","items":{"type":"string","example":"docs.example.com"},"example":["docs.example.com"]},"exclude_domains":{"type":"array","description":"Domains never to return, applied after `include_domains`.","items":{"type":"string","example":"competitor.example.com"},"example":[]}},"example":{"enabled":true,"search_depth":"basic","max_results":5,"topic":"general","include_domains":["docs.example.com"],"exclude_domains":[]}},"locale":{"type":"string","description":"Language the agent replies in. Deliberately a FREE string (not a closed set) - blank means follow the contact's own language, and pinning an enum here used to coerce every other language into one of the catalog locales.","example":"pt_BR"},"quiet_window_seconds":{"type":"number","description":"Seconds of silence to wait before answering, so a burst of messages is handled as one turn.","example":8},"max_window_seconds":{"type":"number","description":"Hard ceiling on that debounce window, however long the contact keeps typing.","example":40},"summary_threshold_tokens":{"type":"integer","description":"Conversation size (tokens) above which the history is summarized before the next turn.","example":3000},"standdown_on_assignment":{"type":"boolean","default":true,"description":"Whether assigning a human agent immediately pauses the Robot. Keep true for the traditional handoff. Set false for a silent transfer that assigns an owner while the Robot keeps working; an actual human reply still pauses it. Legacy configurations default to true.","example":true},"standdown_auto_resume":{"type":"boolean","description":"\"Assumido por humano\": when true the agent takes the conversation back after standdown_ttl_seconds of human silence. False keeps it paused until a human hands it back explicitly. Ships true.","example":true},"standdown_ttl_seconds":{"type":"integer","description":"Idle window (seconds) before the agent resumes a conversation a human took over. Only consulted while standdown_auto_resume is true. Ships 86400 (24h); the sidecar floors it at 60.","example":86400},"paused_inbound_policy":{"type":"string","description":"What happens to inbound messages retained while a human owns the conversation. `discard` drops them (the safe default), `latest` keeps only the most recent eligible message, and `bounded_all` keeps a bounded set. Resuming never replays them automatically; replay is a separate confirmed operator action.","enum":["discard","latest","bounded_all"],"example":"discard"},"paused_inbound_max_messages":{"type":"integer","minimum":1,"maximum":100,"description":"Maximum retained messages when paused_inbound_policy is bounded_all.","example":10},"paused_inbound_max_age_seconds":{"type":"integer","minimum":60,"maximum":604800,"description":"Maximum age of a retained paused-inbound message before it becomes ineligible for explicit replay.","example":3600},"handoff_team_id":{"type":["integer","null"],"description":"Team the conversation is assigned to on handoff, or null to leave assignment untouched.","example":3},"working_hours_policy":{"type":"string","description":"What the agent does outside the inbox's working hours: ignore them and reply anyway, send out_of_office_message, snooze the conversation, or hand off to a human.","enum":["ignore","out_of_office_reply","snooze","handoff"],"example":"ignore"},"out_of_office_message":{"type":"string","description":"Message sent when working_hours_policy is out_of_office_reply. Empty by default.","example":"Nosso atendimento volta às 9h. Já registramos sua mensagem."},"handoff_policy":{"type":"object","description":"What happens to the conversation when the agent hands it to a human.","properties":{"target_status":{"type":"string","description":"Status applied on handoff. \"auto\" leaves the current status untouched.","enum":["open","pending","snoozed","resolved","auto"],"example":"open"},"target_priority":{"type":"string","description":"Priority applied on handoff. \"auto\" leaves the current priority untouched.","enum":["urgent","high","medium","low","none","auto"],"example":"none"},"triggers":{"type":"array","description":"Phrases/conditions that force a handoff when detected in the conversation.","items":{"type":"string","example":"falar com atendente"}}}},"guardrails":{"type":"object","description":"Content limits applied to the agent's reply before it is delivered.","properties":{"banned_topics":{"type":"array","description":"Topics the agent must refuse to discuss.","items":{"type":"string","example":"assuntos jurídicos"}},"blocked_phrases":{"type":"array","description":"Exact phrases that must never appear in a reply.","items":{"type":"string","example":"garantimos 100% de aprovação"}},"max_output_chars":{"type":["integer","null"],"description":"Maximum reply length in characters, or null for no limit.","example":1200},"pii_policy":{"type":"string","description":"off delivers the reply as generated; mask redacts personal data before sending.","enum":[false,"mask"],"example":"off"},"require_handoff_conditions":{"type":"array","description":"Conditions that force a human handoff instead of a reply.","items":{"type":"string","example":"cliente pede cancelamento"}}}},"knowledge_base":{"type":"object","description":"Retrieval (RAG) over the agent's indexed sources.","properties":{"enabled":{"type":"boolean","description":"Whether the agent retrieves from its knowledge base before answering.","example":true},"top_k":{"type":["integer","null"],"description":"How many passages to retrieve per turn, or null for the sidecar default.","example":5},"use_shared":{"type":"boolean","description":"Also retrieve from the account-wide shared knowledge base, not just this agent's.","example":false}}},"database":{"type":"object","description":"Read-only SQL access the agent can query to answer data questions.","properties":{"enabled":{"type":"boolean","description":"Whether the SQL tool is available to this agent.","example":false},"connection_secret":{"type":["string","null"],"description":"Name of the stored secret holding the connection URL (never the URL itself).","example":"ERP_DB_URL"},"read_only":{"type":"boolean","description":"Reject anything that is not a SELECT. Ships true; turning it off is not recommended.","example":true},"max_rows":{"type":"integer","description":"Row cap per query.","example":200},"statement_timeout_seconds":{"type":"integer","description":"Per-statement timeout in seconds.","example":15},"include_tables":{"type":"array","description":"Tables the agent may read. Empty exposes the whole schema.","items":{"type":"string","example":"orders"}},"description":{"type":"string","description":"What this database holds, so the model knows when to query it.","example":"Pedidos e faturas do ERP."},"instructions":{"type":"string","description":"Query guidance for the model (joins to prefer, columns to avoid).","example":"Sempre filtre por account_id."}}},"reactions":{"type":"object","description":"Native emoji reactions.","properties":{"outbound":{"type":"boolean","description":"Let the agent react to contact messages with an emoji.","example":false},"understand_inbound":{"type":"boolean","description":"Feed emoji reactions the contact sends into the agent's understanding of the turn.","example":false}}},"media":{"type":"object","description":"Per-agent inbound media gates. Each field is TRI-state: true/false turn the modality on/off for THIS agent, null (the default) inherits the deploy-wide setting.","properties":{"audio":{"type":["boolean","null"],"description":"Transcribe inbound voice notes (speech-to-text) before the turn.","example":true},"vision":{"type":["boolean","null"],"description":"Let the multimodal model see inbound images.","example":true},"documents":{"type":["boolean","null"],"description":"Extract text from inbound files (documents/OCR).","example":true}}},"close_on_complete":{"type":"string","description":"The status the worker sets on the conversation right after it delivers the turn's reply. off (the default) never touches the status. Deliberately not a model-facing tool: a tool call is dropped whenever the turn hits the tool-iteration cap, which would lose the close on exactly the long conversations that need it.","enum":["off","resolved","pending"],"example":"off"},"verification_policy":{"type":"string","description":"Human-approval gate on the turn's reply — the worker parks the composed reply as a pending action instead of delivering it. off (the default) always delivers. unverified holds only when the turn's reconciliation found a claim with no backing; always holds every reply (a supervised rollout). Also not model-facing: the decision to withhold must not compete for the turn's tool budget, and a model that knows it is being reviewed is a different model.","enum":["off","unverified","always"],"example":"off"},"model_params":{"type":"object","description":"Advanced per-agent tuning applied on top of default_model/fallback_models. Every field is null (unset) by default and an unset field is simply not sent to the provider, so an untouched agent routes exactly as before. reasoning_effort doubles as the manual escape hatch for the OpenAI reasoning-family plus tools rewrite: an operator who sets it explicitly is understood to have already decided how the model reasons, so the router stops forcing the Responses API on their behalf. A knob the chosen provider does not have is discarded rather than passed through.","properties":{"reasoning_effort":{"type":["string","null"],"description":"How hard a reasoning-family model thinks before answering. null = provider default.","enum":["none","low","medium","high",null],"example":"low"},"temperature":{"type":["number","null"],"description":"Sampling temperature, 0 to 2. null = provider default.","example":0.4},"top_p":{"type":["number","null"],"description":"Nucleus sampling, above 0 and up to 1. null = provider default.","example":0.9},"max_output_tokens":{"type":["integer","null"],"description":"Cap on the model's own output for one call. null = provider default.","example":512}}},"service_flow":{"type":"object","description":"Ordered service flow with code-verified checkpoints. Opt-in and inert by default (enabled false, or no steps), in which case the agent behaves exactly as it did before this field existed. When active, the agent is bound ONLY the tools the current step permits — plus the always-on read-only contact/conversation tools and the handoff tool, which are never withheld — and it leaves a step only when that step's exit criterion is satisfied by what the turn ACTUALLY executed. The model asserting it finished advances nothing. The step is stored per conversation and survives pauses, handoffs and restarts.","properties":{"enabled":{"type":"boolean","description":"Whether the sequence constrains this agent. false (the default) = no change.","example":false},"on_exit":{"type":"string","description":"What happens when the last step completes — or when a step exceeds its max_turns without being satisfied. handoff assigns a human, resolve closes the conversation after the reply is delivered, free simply stops constraining the agent.","enum":["handoff","resolve","free"],"example":"handoff"},"strict_tools":{"type":"boolean","description":"true (the default) restricts the bound tools to the step's allowed_tools. false keeps the step as prompt guidance only, without restricting what the model may call.","example":true},"steps":{"type":"array","description":"The steps, in order. The order IS the sequence; `next` is derived from it.","items":{"type":"object","properties":{"key":{"type":"string","description":"Stable identifier stored in the conversation's state — not a visible label. Must be unique within the flow. `__done__` is reserved by the runtime and refused here.","example":"qualificacao"},"name":{"type":"string","description":"The step's name, written by the operator in the operator's language. Reaches the model's prompt verbatim — never translated or rewritten.","example":"Qualificação"},"goal":{"type":"string","description":"What this step is for, in the operator's own words. Also passed verbatim.","example":"Descobrir o segmento e o tamanho da empresa."},"allowed_tools":{"type":"array","description":"The tools the agent may call while on this step. Everything else is unbound, so an out-of-step call is impossible rather than discouraged.","items":{"type":"string","example":"contact_update"}},"exit":{"type":"object","description":"What has to be TRUE to leave this step — checked by code, against real evidence.","properties":{"type":{"type":"string","description":"tools_executed requires the listed tools to have executed successfully (a tool that FAILED does not count). contact_attribute requires the named attributes to be present on the contact. turns leaves after max_turns (a pacing step). manual never advances on its own — it ends when a human takes over or max_turns applies.","enum":["tools_executed","contact_attribute","manual","turns"],"example":"tools_executed"},"tools":{"type":"array","description":"For tools_executed: ALL of these must have executed successfully. When empty, any one of the step's allowed_tools satisfies it.","items":{"type":"string","example":"contact_update"}},"attributes":{"type":"array","description":"For contact_attribute: every one of these must be present and non-empty on the contact record. A blank value does not count as present.","items":{"type":"string","example":"segmento"}},"max_turns":{"type":"integer","description":"Anti-loop net, always in force: the maximum number of turns the conversation may spend on this step before on_exit is applied. A step can never trap a contact.","example":8}}},"next":{"type":["string","null"],"description":"Key of the following step; null on the last one. Derived from the array order by the dashboard rather than typed. A key that does not exist in the flow is refused.","example":"proposta"}}}}}},"max_tool_iterations":{"type":["integer","null"],"description":"Supervisor ReAct budget. null (the default) uses the deploy-wide value. The USABLE tool rounds are one less than this number: the counter increments before routing, so the call from the iteration that reaches the cap goes to the closeout node instead of the tools node.","example":8},"history_limit_messages":{"type":["integer","null"],"description":"Caps the history fetch (in messages) on the full-fold path. null (the default) uses the deploy-wide value.","example":40},"tail_budget_tokens":{"type":["integer","null"],"description":"The verbatim tail kept OUT of the rolling-summary fold. null (the default) is half of summary_threshold_tokens.","example":1500},"hard_cap_tokens":{"type":["integer","null"],"description":"Hard context ceiling safety net. null (the default) is twice summary_threshold_tokens.","example":6000},"chain_same_provider":{"type":"string","readOnly":true,"description":"Read-only diagnostic echoed by the sidecar: the provider the model chain repeats CONSECUTIVELY, or empty. Two links in a row from one provider are not a fallback — one key, one quota, one outage — and that exact shape (openai then openai) is the factory default nobody chose. Sent so the UI can warn inline; never refused, because a cheaper model from the same provider is a legitimate choice and only the operator knows which case is theirs. Ignored on write.","example":""},"delivery":{"type":"object","description":"How the reply is delivered on the channel. Absent keys keep the deploy default.","properties":{"quote_replies":{"type":"boolean","description":"Answer quoting the contact's message (the channel's native reply). On by default.","example":true},"formatting":{"type":"string","description":"Per-channel rich-text formatting: auto applies what the channel supports, off sends plain text everywhere (the kill switch).","enum":["auto","off"],"example":"auto"}}},"stt":{"type":"object","description":"Speech-to-TEXT engine - how this agent LISTENS. Same {provider, model} shape as voice, because \"how it listens\" and \"how it speaks\" are one decision. Both fields empty (the default) use the installation's STT model, so an agent that never sets it transcribes exactly as before. A provider without a model is not a spec and reads as unset: guessing the missing half is how an operator ends up transcribing on an engine they never chose.","properties":{"provider":{"type":"string","description":"Transcription provider. Empty means the installation decides.","enum":["","groq","openai"],"example":"groq"},"model":{"type":"string","description":"The model, as the whole provider:model spec or as a bare name the curated catalogue can attribute to a single provider. Empty means the installation's STT model.","example":"groq:whisper-large-v3-turbo"}}},"embedding":{"type":"object","description":"EMBEDDING engine - how this agent REMEMBERS. Only consulted for the agent the account assigned to the embeddings surface, because a knowledge base is one per account and cannot hold two vector spaces at once; stored and inert on any other agent. Both fields empty (the default) fall through to the account's provider switch, then the operator panel, then the installation's embedding model.\nChanging it invalidates the vectors already stored: even a same-width model writes into a different vector space, so the base needs re-indexing before search means anything again. A model whose vector width is not the installation's is REFUSED on save (422 agent_embedding_dimension_mismatch) - accepting it would save cleanly and then be skipped in silence by the dimension guard at embed time. An unbuildable provider is refused too (422 agent_embedding_unbuildable_provider).","properties":{"provider":{"type":"string","description":"Embedding provider. Open text rather than a closed set: the accepted providers are computed at runtime from what the embedding factory can build plus what the live browser offers, so freezing a list here would refuse a provider the picker had just offered. Empty means the installation decides.","example":"openai"},"model":{"type":"string","description":"The bare model name (no provider prefix). Empty means the installation decides.","example":"text-embedding-3-small"}}},"voice":{"type":"object","description":"Voice-note replies (PTT), call backend selection and pipeline speech synthesis. The existing enabled/mode fields control voice-note replies; call_backend and call_model select AI call answering independently. Saving these settings or receiving catalogue metadata does not prove channel transport, provider connectivity or live-call readiness.","properties":{"enabled":{"type":"boolean","description":"Whether voice replies are available at all.","example":false},"mode":{"type":"string","description":"When to answer with audio: off never; always on every reply; on_inbound_audio only when the contact sent audio; auto lets the agent decide.","enum":["off","always","on_inbound_audio","auto"],"example":"off"},"with_text":{"type":"boolean","description":"Also send the text alongside the voice note.","example":false},"provider":{"type":"string","description":"Text-to-speech provider.","enum":["elevenlabs","openai","google_genai"],"example":"elevenlabs"},"model":{"type":"string","description":"Provider-specific TTS model id. Blank uses the provider default.","example":"eleven_multilingual_v2"},"call_backend":{"type":"string","description":"AI call backend, independent of voice-note mode and the TTS provider/model. auto preserves automatic selection; openai_realtime selects OpenAI Realtime; gemini_live selects the Maestro integration with Gemini Live; stt_tts selects transcription -\u003e agent -\u003e speech synthesis; disabled disables AI call answering. realtime is the preserved legacy alias for openai_realtime. Availability requires the corresponding channel and provider support.","enum":["auto","openai_realtime","gemini_live","stt_tts","disabled","realtime"],"default":"auto","example":"auto"},"call_model":{"type":"string","description":"Call model, separate from the TTS model. Empty uses the selected call backend's default. New model selections use provider:model; in auto this also selects the provider. Legacy stored bare names remain accepted and are not silently rewritten. A catalogue entry is metadata, not proof of a working call transport.","default":"","example":"openai:gpt-realtime"},"voice_id":{"type":"string","description":"ElevenLabs voice id (including a cloned voice). Blank uses the account default.","example":"21m00Tcm4TlvDq8ikWAM"},"openai_voice":{"type":"string","description":"OpenAI voice name, used when provider is openai.","example":"alloy"},"gemini_voice":{"type":"string","description":"Google voice name, used when provider is google_genai.","example":"Kore"},"stability":{"type":"number","description":"ElevenLabs stability (0-1). Lower is more expressive, higher is more consistent.","example":0.5},"similarity_boost":{"type":"number","description":"ElevenLabs similarity to the reference voice (0-1).","example":0.75},"style":{"type":"number","description":"ElevenLabs style exaggeration (0-1).","example":0},"use_speaker_boost":{"type":"boolean","description":"ElevenLabs speaker-boost flag.","example":true},"speed":{"type":"number","description":"Playback rate multiplier (1 is normal).","example":1},"instructions":{"type":"string","description":"Tone/emotion steering for the OpenAI TTS model.","example":"Fale de forma calma e acolhedora."},"style_instructions":{"type":"string","description":"Style prompt for the Google TTS model.","example":"Locução comercial, ritmo animado."}}},"image_gen":{"type":"object","description":"Generative image (the generate_image tool).","properties":{"enabled":{"type":"boolean","description":"Whether the agent may generate images.","example":false},"provider":{"type":"string","description":"Image generation provider.","enum":["openai","google_genai"],"example":"openai"},"model":{"type":"string","description":"Provider-specific image model id. Blank uses the provider default.","example":"gpt-image-1"}}},"video_gen":{"type":"object","description":"Generative video (the asynchronous generate_video tool).","properties":{"enabled":{"type":"boolean","description":"Whether the agent may generate videos.","example":false},"provider":{"type":"string","description":"Video generation provider.","enum":["openai","google_genai"],"example":"openai"},"model":{"type":"string","description":"Provider-specific video model id. Blank uses the provider default.","example":"sora-2"}}},"custom_tools":{"type":"array","description":"Operator-defined external HTTP tools the agent may call.","items":{"type":"object","description":"One HTTP endpoint exposed to the model as a callable tool.","properties":{"name":{"type":"string","description":"Tool name the model calls. Must be unique within the agent.","example":"consultar_pedido"},"description":{"type":"string","description":"What the tool does - this is what the model reads to decide when to call it.","example":"Consulta o status de um pedido pelo número."},"method":{"type":"string","description":"HTTP method used for the call.","enum":["GET","POST","PUT","PATCH","DELETE"],"example":"GET"},"url":{"type":"string","description":"Endpoint URL. Supports {{arg}} and {{secret.NAME}} interpolation.","example":"https://api.acme.com/orders/{{order_id}}"},"sensitive":{"type":"boolean","description":"Park the call for human approval before it runs (HITL).","example":false},"extract":{"type":"string","description":"JSON path of the response fragment to hand back to the model. Blank returns all.","example":"data.status"},"body_type":{"type":"string","description":"How body params are encoded on a write call.","enum":["json","form"],"example":"json"},"body_template":{"type":"object","additionalProperties":true,"description":"Static JSON body skeleton merged with the call arguments, interpolated with {{arg}} and {{secret.NAME}} at call time. Arbitrary operator-authored JSON, so any shape is accepted.","example":{"source":"maestro","order_id":"{{order_id}}"}},"headers":{"type":"object","additionalProperties":{"type":"string"},"description":"Static request headers. Values interpolate {{secret.NAME}}.","example":{"X-Api-Version":"2026-01"}},"query":{"type":"object","additionalProperties":{"type":"string"},"description":"Static query-string parameters. Values interpolate {{secret.NAME}}.","example":{"include":"items"}},"auth":{"type":"object","description":"Credential injection. The *_secret fields are secret-key LOOKUPS (names of stored secrets), never the credential itself and never a {{secret.NAME}} template.","properties":{"type":{"type":"string","description":"Authentication scheme applied to the request.","enum":["none","bearer","basic","header","query","oauth"],"example":"bearer"},"name":{"type":"string","description":"Header or query-parameter name, used when type is header or query.","example":"X-Api-Key"},"token_secret":{"type":"string","description":"Name of the stored secret holding the token (bearer/header/query/oauth).","example":"ACME_API_TOKEN"},"username_secret":{"type":"string","description":"Name of the stored secret holding the username (basic auth).","example":"ACME_USER"},"password_secret":{"type":"string","description":"Name of the stored secret holding the password (basic auth).","example":"ACME_PASS"}}},"params":{"type":"array","description":"Arguments the model may supply, exposed to it as the tool's input schema.","items":{"type":"object","properties":{"name":{"type":"string","description":"Argument name.","example":"order_id"},"type":{"type":"string","description":"Argument JSON type.","enum":["string","number","integer","boolean"],"example":"string"},"description":{"type":"string","description":"What the argument means, read by the model.","example":"Número do pedido."},"required":{"type":"boolean","description":"Whether the model must supply it.","example":true},"location":{"type":"string","description":"Where the value is placed. auto means query for GET/DELETE and body otherwise.","enum":["auto","query","body","header","path"],"example":"auto"}}}},"response_map":{"type":"array","description":"Named fields lifted out of the response so the model reads labelled values.","items":{"type":"object","properties":{"label":{"type":"string","description":"Human-readable name handed to the model.","example":"Status"},"path":{"type":"string","description":"JSON path of the value in the response.","example":"data.status"}}}},"pagination":{"type":"object","description":"How to walk a paginated endpoint. type none disables paging.","properties":{"type":{"type":"string","description":"Paging style of the endpoint.","enum":["none","page","cursor"],"example":"none"},"param":{"type":"string","description":"Query parameter carrying the page number or cursor.","example":"page"},"items_path":{"type":"string","description":"JSON path of the item array in each response.","example":"data"},"next_path":{"type":"string","description":"JSON path of the next cursor (cursor paging).","example":"meta.next"},"start":{"type":"integer","description":"First page number (page paging).","example":1},"max_pages":{"type":"integer","description":"Hard cap on pages fetched per call.","example":5},"size_param":{"type":"string","description":"Query parameter carrying the page size.","example":"per_page"},"size":{"type":"integer","description":"Page size requested.","example":50}}}}}},"mcp_servers":{"type":"array","description":"External MCP servers whose tools the agent may call. The remote tool list is discovered ON THE SIDECAR at save time and stored there, so it is never sent in this payload.","items":{"type":"object","properties":{"name":{"type":"string","description":"Local name for the server, used to prefix its tools.","example":"acme-erp"},"url":{"type":"string","description":"MCP endpoint URL.","example":"https://mcp.acme.com/sse"},"transport":{"type":"string","description":"MCP transport protocol.","enum":["streamable_http","sse"],"example":"streamable_http"},"timeout":{"type":"integer","description":"Per-call timeout in seconds.","example":30},"sensitive":{"type":"boolean","description":"Park every call to this server for human approval (HITL).","example":false},"enabled_tools":{"type":"array","description":"Remote tool names the agent may call. Empty enables all discovered tools.","items":{"type":"string","example":"get_order"}},"headers":{"type":"object","additionalProperties":{"type":"string"},"description":"Static headers sent to the MCP server. Values interpolate {{secret.NAME}}.","example":{"X-Tenant":"acme"}},"auth":{"type":"object","description":"Credential injection for the MCP server (same secret-key lookup as custom tools).","properties":{"type":{"type":"string","description":"Authentication scheme applied to the connection.","enum":["none","bearer","basic","header","query","oauth"],"example":"bearer"},"name":{"type":"string","description":"Header or query-parameter name, used when type is header or query.","example":"X-Api-Key"},"token_secret":{"type":"string","description":"Name of the stored secret holding the token.","example":"ACME_MCP_TOKEN"},"username_secret":{"type":"string","description":"Name of the stored secret holding the username (basic auth).","example":"ACME_USER"},"password_secret":{"type":"string","description":"Name of the stored secret holding the password (basic auth).","example":"ACME_PASS"}}}}}},"media_assets":{"type":"array","description":"Sendable media library - files the agent may attach to a reply by name.","items":{"type":"object","properties":{"name":{"type":"string","description":"Asset name the model refers to.","example":"catalogo_2026"},"description":{"type":"string","description":"What the asset is, so the model knows when to send it.","example":"Catálogo completo em PDF."},"url":{"type":"string","description":"Public URL of the file.","example":"https://cdn.acme.com/catalogo.pdf"},"type":{"type":"string","description":"Media kind, which decides how it is attached.","enum":["image","file","audio","video"],"example":"file"}}}},"sub_agents":{"type":"array","description":"Other agents this one may delegate to. Each becomes an ask_\u003cslug\u003e tool. Delegation is one level - a sub-agent does not delegate further.","items":{"type":"object","properties":{"agent_id":{"type":"integer","description":"Id of the agent being delegated to.","example":7},"name":{"type":"string","description":"Display name of the sub-agent.","example":"Vendas"},"slug":{"type":"string","description":"Slug used to build the ask_\u003cslug\u003e tool name.","example":"vendas"},"description":{"type":"string","description":"When to delegate to it - read by the calling model.","example":"Perguntas sobre planos e preços."},"enabled":{"type":"boolean","description":"Whether the delegation tool is exposed.","example":true},"sensitive":{"type":"boolean","description":"Park the delegation for human approval before it runs (HITL).","example":false}}}},"secrets":{"type":["object","null"],"writeOnly":true,"additionalProperties":{"type":"string"},"description":"WRITE-ONLY. Secret name to value, encrypted at rest and never echoed back. Referenced elsewhere as {{secret.NAME}} or by name in an auth *_secret field. Send only the secrets you are changing.","example":{"ACME_API_TOKEN":"sk-live-xxxxxxxx"}},"secret_keys":{"type":"array","readOnly":true,"description":"READ-ONLY. Names of the secrets currently configured, without their values.","items":{"type":"string","example":"ACME_API_TOKEN"}},"provider_keys":{"type":["object","null"],"writeOnly":true,"additionalProperties":{"type":"string"},"description":"WRITE-ONLY. Model-provider to this agent's own API key, encrypted at rest and never echoed back.","example":{"openai":"sk-proj-xxxxxxxx"}},"chatwoot_native_keys":{"type":["object","null"],"writeOnly":true,"additionalProperties":{"type":"string"},"description":"WRITE-ONLY. Mirror of the installation's native provider keys, pushed so the agent can fall back to them when it has no key of its own and use_global_fallback allows it.","example":{"openai":"sk-proj-xxxxxxxx"}},"provider_keys_set":{"type":"array","readOnly":true,"description":"READ-ONLY. Providers for which this agent has its own key, without the values.","items":{"type":"string","example":"openai"}},"native_keys_set":{"type":"array","readOnly":true,"description":"READ-ONLY. Providers for which a native key is mirrored, without the values.","items":{"type":"string","example":"openai"}},"use_global_fallback":{"type":"boolean","description":"Allow falling back to the installation's native provider key when this agent has none of its own. Ships true.","example":true}}},"maestro_modality_model":{"type":"object","description":"One selectable model of a single modality, from the sidecar's ONE catalogue. The lists are per modality (`stt_models`, `tts_models`, `embedding_models`, `realtime_models`) and not one mixed list on purpose: a field that offers a model its consumer cannot run saves cleanly and then does nothing, which is the failure this split exists to remove.","properties":{"id":{"type":"string","description":"The whole `provider:model` spec — the one shape that names its own vendor.","example":"openai:text-embedding-3-small"},"provider":{"type":"string","description":"Provider prefix of the spec. Genuinely closed here, unlike the free-text `embedding.provider` of the agent config: this list is the sidecar's OWN catalogue, so an entry can only ever name a provider the catalogue knows. Narrower than the catalogue on purpose, because this schema types the NON-chat lists only (`realtime_models`, `stt_models`, `tts_models`, `embedding_models`): what it covers is the providers that publish a model of one of those modalities — the catalogue's own label map plus the media-only providers. A chat-only provider is missing here by definition and not by omission — `deepseek` is in the catalogue and serves text in, text out, so it can only ever be an entry on the chat list, which this schema does not type.","enum":["openai","anthropic","google_genai","groq","xai","cohere","ollama","openrouter","elevenlabs"],"example":"openai"},"provider_label":{"type":"string","description":"Human label for the provider.","example":"OpenAI"},"label":{"type":"string","description":"Human label for the model.","example":"Text Embedding 3 Small"},"description":{"type":"string","description":"Short prose about the model, written where \"which of these do I want\" is a real question — today embeddings, transcription and voice. Empty on the chat entries.","example":"Fast and cheap; the default embedding model."},"dimension":{"type":["integer","null"],"description":"Vector width, on EMBEDDING entries only, and only when it is known as DATA — no provider publishes it in its models API (Google's `outputDimensionality` is a request parameter of `embedContent`, not model metadata), so it comes from the curated catalogue and is null for a model reached only through the live browser. It travels because it decides whether the choice works: the store column is fixed-width, so a mis-sized model is skipped in silence at embed time. null means unknown, never a guessed number.","example":1536}}},"maestro_surface_assignment":{"type":"object","description":"One account-scoped surface and the Robô assigned to it (or none).","properties":{"surface":{"type":"string","description":"The surface id. `blueprint` is deliberately absent: it is a step of the PLATFORM, running while an account is being created, before it owns a Robô, a key or a chain — offering it as a toggle would let an operator tick something that changes nothing.","enum":["brain","copilot","summary","judge","dashboards","calls","embeddings"],"example":"brain"},"agent_id":{"type":["integer","null"],"description":"The assigned Robô, or null when nothing is pointed at this surface.","example":42},"agent_name":{"type":"string","description":"Name of the assigned Robô; empty when there is none.","example":"Atendimento"},"enabled":{"type":"boolean","description":"A disabled assignment falls through exactly like an absent one, but the row survives so the screen can still show what was chosen and restore it. That is why this is a flag and not a delete.","example":true},"assigned":{"type":"boolean","description":"Whether an explicit assignment row exists for this surface at all.","example":true},"cost_sensitive":{"type":"boolean","description":"Marks a surface that runs on volume rather than per conversation, so pointing it at an expensive model is a recurring bill and not a one-off.","example":false},"requires_independence":{"type":"boolean","description":"Marks a surface that should NOT run on the same Robô it evaluates — the improvement judge grading its own output is not a second opinion.","example":false},"updated_at":{"type":["string","null"],"format":"date-time","description":"When the assignment last changed; null when there is none.","example":"2026-07-27T14:03:00Z"}}},"maestro_surfaces":{"type":"object","description":"The account's full surface list — every surface, assigned or not.","properties":{"account_id":{"type":"integer","example":7},"surfaces":{"type":"array","items":{"$ref":"#/components/schemas/maestro_surface_assignment"}}}},"maestro_agent":{"type":"object","description":"A Maestro Robô (AgentBot) as the sidecar stores it: identity, on/off switch, its full configuration and the inbox bindings that decide which conversations it drives.","properties":{"id":{"type":"integer","example":42},"account_id":{"type":"integer","description":"The platform account that owns this robot.","example":7},"name":{"type":"string","example":"Atendimento"},"enabled":{"type":"boolean","description":"The hard kill switch, orthogonal to autonomy and to stand-down: a disabled Robô goes fully silent on the inboxes it is bound to instead of falling through to the collective binding.","example":true},"config":{"$ref":"#/components/schemas/maestro_agent_config"},"bindings":{"type":"array","description":"Which conversations this Robô drives. A row with `inbox_id` null is the COLLECTIVE binding — \"this Robô speaks for the account\" — and a per-inbox row wins over it.","items":{"type":"object","properties":{"id":{"type":"integer","example":9},"inbox_id":{"type":["integer","null"],"description":"The inbox this binding scopes to; null means the account-wide (collective) binding.","example":3}}}},"created_at":{"type":"string","format":"date-time","example":"2026-07-01T12:00:00Z"},"updated_at":{"type":"string","format":"date-time","example":"2026-07-27T14:03:00Z"}}},"maestro_template":{"type":"object","description":"One stored Modelo — a Robô configuration saved to the library so it can be re-applied, duplicated, carried to another installation, or used as the starting point for a new Robô. Mirrors the sidecar's `TemplateOut` field for field. The stored `config` never carries a secret: credentials are stripped on the way IN (on write), so a read can never leak one, and every removal is reported to the caller.","properties":{"id":{"type":"integer","description":"Library id of the Modelo. Use it on the read, update, duplicate and export endpoints.","example":12},"scope":{"type":"string","description":"`account` — private to the account that owns it, the only scope an account-level caller can create. `installation` — the shared library every tenant on this installation can read; promoting into it is an operator action and is deliberately NOT exposed on the account-scoped API.","enum":["account","installation"],"example":"account"},"account_id":{"type":"integer","description":"The platform account that owns this template.","example":7},"slug":{"type":"string","description":"Stable machine key, unique within the scope. Derived from `name` when not supplied.","example":"atendimento_ecommerce"},"name":{"type":"string","example":"Atendimento e-commerce"},"description":{"type":"string","description":"What this Modelo is for, in the operator's own words. Free text, may be empty.","example":"Atendimento com rastreio de pedido e política de troca."},"vertical":{"type":"string","description":"Business vertical this Modelo targets, used to group the library. Free text, may be empty.","example":"ecommerce"},"origin":{"type":"string","description":"How the Modelo entered the library — `custom` (authored here, or saved from a Robô), `imported` (read from a `.maestro-template.json`), `generated` (drafted by the platform). Only `custom` and `imported` are editable; see `editable`.","enum":["custom","imported","generated"],"example":"custom"},"schema_version":{"type":"integer","description":"Version of the Modelo document format. Currently `1`; an export carrying an unsupported version is refused on import rather than half-read.","example":1},"checksum":{"type":"string","description":"Digest of the stored configuration, used to detect that a Modelo changed since it was applied.","example":"8f14e45fceea167a5a36dedd4bea2543"},"editable":{"type":"boolean","description":"Whether this Modelo can be updated or deleted — true only for `custom` and `imported` origins. Read-only entries are still duplicable, which is how you customize one without changing it.","example":true},"created_by":{"type":["string","null"],"description":"Who saved it, taken from the session on write — never from the client payload.","example":"ana@acme.com"},"created_at":{"type":"string","format":"date-time","example":"2026-07-01T12:00:00Z"},"updated_at":{"type":"string","format":"date-time","example":"2026-07-27T14:03:00Z"},"config":{"$ref":"#/components/schemas/maestro_agent_config"}}},"maestro_template_stripped_field":{"type":"object","description":"One secret removed on the way into (or out of) the library. `field` is the dotted PATH inside the configuration — never the secret's name and never its value. A Modelo is portable precisely because credentials do not travel with it, so this list is the honest account of what the receiving side has to re-enter by hand.","properties":{"field":{"type":"string","description":"Dotted path of the configuration key whose value was removed.","example":"tools.http.headers.Authorization"},"kind":{"type":"string","description":"`value` — an inline secret literal. `reference` — a pointer to a credential that does not exist on the destination. `credential` — a whole credential block (a key pair, a token set).","enum":["value","reference","credential"],"example":"value"}}},"maestro_template_reference_outcome":{"type":"object","description":"What happened to one per-installation reference (a team, a contact-attribute key, an inbox) when the Modelo crossed installations. References are re-matched by NAME, never by id — an id from another installation points at a different thing, or at nothing. Anything that found no match is reported here instead of being invented, so the operator sees exactly what still needs wiring.","properties":{"field":{"type":"string","description":"Dotted path of the configuration key that held the reference.","example":"handoff_policy.team"},"action":{"type":"string","description":"`remapped` — matched a local record by name and now points at it. `cleared` — no local match, so the value was emptied. `dropped` — the whole entry was removed. `disabled` — the feature that depended on it was switched off rather than left pointing at nothing.","enum":["remapped","cleared","dropped","disabled"],"example":"remapped"},"name":{"type":"string","description":"The name that was matched, or the one that found no match.","example":"Suporte N2"},"detail":{"type":"string","description":"Short English detail for logs and curl. Never the operator-facing sentence — the UI owns language.","example":"matched team by name"}}},"task_list":{"type":"object","description":"A task list/board container. A task belongs to 0 or 1 list.","properties":{"id":{"type":"number","description":"The ID of the list"},"account_id":{"type":"number","description":"The account the list belongs to"},"name":{"type":"string","description":"The list name"},"color":{"type":"string","description":"The list color (hex string), nullable"},"description":{"type":"string","description":"The list description, nullable"},"position":{"type":"number","description":"The sidebar sort position"},"tasks_count":{"type":"number","description":"Counter cache of tasks in the list"},"archived_at":{"type":"string","format":"date-time","description":"Soft-delete timestamp; null when the list is active"},"archived":{"type":"boolean","description":"Whether the list is soft-deleted (archived)"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"task_sla_policy":{"type":"object","description":"A native Task SLA policy (not the conversation SLA). All thresholds are optional minutes; the policy targets tasks by optional priority and/or list (null = any).","properties":{"id":{"type":"number","description":"The ID of the SLA policy"},"account_id":{"type":"number","description":"The account the policy belongs to"},"name":{"type":"string","description":"The policy name"},"description":{"type":"string","description":"The policy description, nullable"},"due_offset_minutes":{"type":"number","description":"Minutes after creation used to derive a due date, nullable"},"time_to_first_action_minutes":{"type":"number","description":"Threshold in minutes for the first action on the task, nullable"},"time_to_completion_minutes":{"type":"number","description":"Threshold in minutes for task completion, nullable"},"priority":{"type":"number","description":"Targeted task priority as the Task.priorities integer (none: 0, low: 1, medium: 2, high: 3, urgent: 4); null = any priority"},"task_list_id":{"type":"number","description":"Targeted list ID; null = any list"},"active":{"type":"boolean","description":"Whether the policy is applied to matching tasks"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"task_template":{"type":"object","description":"A reusable Task template. `blueprint` is the JSON prefill applied by the create form; nothing is persisted until the user submits.","properties":{"id":{"type":"number","description":"The ID of the template"},"account_id":{"type":"number","description":"The account the template belongs to"},"name":{"type":"string","description":"The template name"},"description":{"type":"string","description":"The template description, nullable"},"blueprint":{"type":"object","description":"JSON prefill payload. Known keys: title, description, priority, task_list_id, labels[], custom_attributes{}, subtasks[]","additionalProperties":true},"active":{"type":"boolean","description":"Whether the template is offered in the create form"},"position":{"type":"number","description":"The sort position"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"task_comment":{"type":"object","description":"A comment on a task.","properties":{"id":{"type":"number","description":"The ID of the comment"},"task_id":{"type":"number","description":"The task the comment belongs to"},"content":{"type":"string","description":"The comment body"},"user_id":{"type":"number","description":"The author user ID"},"user":{"type":"object","description":"Denormalized author (present when set)","properties":{"id":{"type":"number"},"name":{"type":"string"},"available_name":{"type":"string"},"thumbnail":{"type":"string"}}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"task_checklist_item":{"type":"object","description":"A checklist item on a task (polymorphic ChecklistItem with record_type 'Task').","properties":{"id":{"type":"number","description":"The ID of the checklist item"},"account_id":{"type":"number","description":"The account the checklist item belongs to"},"record_type":{"type":"string","description":"The polymorphic owner type ('Task')","enum":["Task"]},"record_id":{"type":"number","description":"The polymorphic owner ID (the task)"},"title":{"type":"string","description":"The checklist item title"},"completed":{"type":"boolean","description":"Whether the item is completed"},"completed_at":{"type":"number","description":"Completion timestamp (epoch seconds); null when not completed"},"completed_by_id":{"type":"number","description":"The user who completed the item"},"assignee_id":{"type":"number","description":"The assigned agent ID"},"due_on":{"type":"string","format":"date","description":"The due date"},"position":{"type":"number","description":"The sort position"},"assignee":{"$ref":"#/components/schemas/agent"},"created_at":{"type":"number","description":"Creation timestamp (epoch seconds)"},"updated_at":{"type":"number","description":"Last update timestamp (epoch seconds)"}}},"task_event":{"type":"object","description":"An append-only task activity/timeline event.","properties":{"id":{"type":"number","description":"The ID of the event"},"task_id":{"type":"number","description":"The task the event belongs to"},"event_type":{"type":"string","enum":["created","status_changed","assigned","completed","reopened","checklist_completed","attachment_added"],"description":"The activity type"},"user_id":{"type":"number","description":"The acting user ID, nullable (automation-sourced events)"},"user":{"type":"object","description":"Denormalized actor (present when set)","properties":{"id":{"type":"number"},"name":{"type":"string"}}},"metadata":{"type":"object","description":"Per-type payload (e.g. status_changed: { from, to }; assigned: { assignee_ids, added, removed }; attachment_added: { filename })","additionalProperties":true},"created_at":{"type":"string","format":"date-time"}}},"task_dependency":{"type":"object","description":"A dependency edge between two tasks — `task` (blocker) must finish before `blocks_task` proceeds.","properties":{"id":{"type":"number","description":"The ID of the dependency edge"},"task_id":{"type":"number","description":"The blocker task ID"},"blocks_task_id":{"type":"number","description":"The blocked task ID"},"blocker":{"type":"object","description":"Denormalized blocker task (nil-safe)","properties":{"id":{"type":"number"},"title":{"type":"string"},"status":{"type":"string","enum":["backlog","todo","in_progress","in_review","done","cancelled"],"description":"The workflow status of the task."}}},"blocks":{"type":"object","description":"Denormalized blocked task (nil-safe)","properties":{"id":{"type":"number"},"title":{"type":"string"},"status":{"type":"string","enum":["backlog","todo","in_progress","in_review","done","cancelled"],"description":"The workflow status of the task."}}},"created_at":{"type":"string","format":"date-time"}}},"task_link":{"type":"object","description":"A polymorphic link from a task to a Conversation, Contact, Organization or CRM item.","properties":{"id":{"type":"number","description":"The ID of the link"},"task_id":{"type":"number","description":"The task the link belongs to"},"linkable_type":{"type":"string","enum":["Conversation","Contact","Organization","Crm::Item"],"description":"The linked record type"},"linkable_id":{"type":"number","description":"The linked record global ID"},"linkable":{"type":"object","description":"Nil-safe preview of the linked record (absent when the linkable was destroyed)","properties":{"type":{"type":"string"},"id":{"type":"number"},"display_id":{"type":"number","description":"Present for Conversation links only"},"label":{"type":"string","description":"Display label (e.g. \"#123\", contact name, organization name or deal title)"}}},"created_at":{"type":"string","format":"date-time"}}},"task_reminder":{"type":"object","description":"A scheduled reminder on a task. Delivered once by the reminder cron (idempotent on sent_at).","properties":{"id":{"type":"number","description":"The ID of the reminder"},"task_id":{"type":"number","description":"The task the reminder belongs to"},"remind_at":{"type":"string","format":"date-time","description":"When the reminder fires"},"channel":{"type":"string","enum":["in_app","email"],"description":"Delivery channel"},"user_id":{"type":"number","description":"Target user; null reminds the task's assignees"},"sent_at":{"type":"string","format":"date-time","description":"Stamped when delivered; null while pending"},"created_at":{"type":"string","format":"date-time"}}},"task_watcher":{"type":"object","description":"A watcher (task + user join). Non-assignees who watch receive the task's notifications.","properties":{"id":{"type":"number","description":"The ID of the watcher row"},"task_id":{"type":"number","description":"The task being watched"},"user_id":{"type":"number","description":"The watching user ID"},"user":{"type":"object","description":"Denormalized watcher (present when set)","properties":{"id":{"type":"number"},"name":{"type":"string"},"available_name":{"type":"string"},"thumbnail":{"type":"string"}}},"created_at":{"type":"string","format":"date-time"}}},"crm_line_item":{"type":"object","description":"A catalog line item on a CRM item (deal) — the deal becomes a quote/order. unit_price, name_snapshot and currency are snapshots taken at add-time, so later catalog edits never retro-alter an existing quote. Any line item change recomputes the deal's auto value (sum of line totals).","properties":{"id":{"type":"number","description":"The ID of the line item"},"account_id":{"type":"number","description":"The account the line item belongs to"},"crm_item_id":{"type":"number","description":"The CRM item (deal) the line belongs to"},"catalog_variant_id":{"type":"number","description":"The source catalog variant; null when the variant was purged or the line was added manually"},"catalog_product_id":{"type":"number","description":"The source catalog product; null when the line was added manually"},"quantity":{"type":"number","description":"The quantity (supports fractional values, up to 3 decimal places); always greater than 0"},"unit_price":{"type":"number","description":"The unit price snapshot taken at add-time (editable — the snapshot belongs to the quote, not the catalog)"},"discount":{"type":"number","description":"The discount applied to the line — a fixed amount or a percentage, per discount_type"},"discount_type":{"type":"string","enum":["fixed","percent"],"description":"How the discount is applied — fixed amount off the line, or percent off the line subtotal"},"currency":{"type":"string","description":"ISO 4217 currency code (3 letters); always matches the deal's currency"},"line_total":{"type":"number","description":"The computed line total: quantity × unit_price − discount, floored at 0"},"position":{"type":"number","description":"The sort position within the deal"},"name_snapshot":{"type":"string","description":"The variant/product name snapshot taken at add-time"},"created_at":{"type":"string","format":"date-time","description":"When the line item was created"},"updated_at":{"type":"string","format":"date-time","description":"When the line item was last updated"}}},"crm_line_item_payload":{"type":"object","description":"Attributes for a deal line item. When catalog_variant_id is given, the variant's product, name, currency and price are snapshotted automatically — any attribute sent explicitly overrides the snapshot. The first line of a deal seeds the deal's currency; subsequent lines must match it.","properties":{"catalog_variant_id":{"type":"number","description":"The catalog variant to add. Must belong to the account (404 otherwise). Omit for a manual (catalog-free) line"},"catalog_product_id":{"type":"number","description":"The catalog product. Defaults to the variant's product when catalog_variant_id is given"},"quantity":{"type":"number","description":"The quantity (supports fractional values); must be greater than 0. Defaults to 1","example":2},"unit_price":{"type":"number","description":"The unit price. Defaults to the variant's price for the line currency"},"discount":{"type":"number","description":"The discount — a fixed amount or a percentage, per discount_type. Defaults to 0"},"discount_type":{"type":"string","enum":["fixed","percent"],"description":"How the discount is applied. Defaults to fixed"},"currency":{"type":"string","description":"ISO 4217 currency code (3 letters). Defaults to the variant's currency, then the deal's; must match the deal's currency once set","example":"USD"},"name_snapshot":{"type":"string","description":"The display name for the line. Defaults to the variant (or product) name"}}},"inbox_translation_settings":{"type":"object","additionalProperties":false,"required":["enabled","agent_language","contact_language","translate_incoming","translate_outgoing","translate_transcripts"],"properties":{"enabled":{"type":"boolean","example":true},"agent_language":{"type":["string","null"],"pattern":"^[A-Za-z]{2,3}(?:-[A-Za-z]{4})?(?:-(?:[A-Za-z]{2}|[0-9]{3}))?$","description":"Shared team fallback language in normalized BCP-47 form.","example":"pt-BR"},"contact_language":{"type":["string","null"],"pattern":"^[A-Za-z]{2,3}(?:-[A-Za-z]{4})?(?:-(?:[A-Za-z]{2}|[0-9]{3}))?$","description":"Delivery target. Null means use the language detected for each conversation.","example":"en"},"translate_incoming":{"type":"boolean","example":true},"translate_outgoing":{"type":"boolean","example":true},"translate_transcripts":{"type":"boolean","example":true}}},"inbox_translation_settings_update":{"type":"object","additionalProperties":false,"minProperties":1,"properties":{"enabled":{"type":"boolean"},"agent_language":{"type":["string","null"],"pattern":"^[A-Za-z]{2,3}(?:-[A-Za-z]{4})?(?:-(?:[A-Za-z]{2}|[0-9]{3}))?$"},"contact_language":{"type":["string","null"],"pattern":"^[A-Za-z]{2,3}(?:-[A-Za-z]{4})?(?:-(?:[A-Za-z]{2}|[0-9]{3}))?$"},"translate_incoming":{"type":"boolean"},"translate_outgoing":{"type":"boolean"},"translate_transcripts":{"type":"boolean"}}},"conversation_translation_override":{"type":"object","additionalProperties":false,"required":["mode"],"properties":{"mode":{"type":"string","enum":["inherit","enabled","disabled"],"example":"enabled"},"agent_language":{"type":["string","null"],"pattern":"^[A-Za-z]{2,3}(?:-[A-Za-z]{4})?(?:-(?:[A-Za-z]{2}|[0-9]{3}))?$","example":"pt-BR"},"contact_language":{"type":["string","null"],"pattern":"^[A-Za-z]{2,3}(?:-[A-Za-z]{4})?(?:-(?:[A-Za-z]{2}|[0-9]{3}))?$","example":"en"},"translate_incoming":{"type":["boolean","null"]},"translate_outgoing":{"type":["boolean","null"]},"translate_transcripts":{"type":["boolean","null"]}}},"effective_translation_settings":{"type":"object","additionalProperties":false,"required":["enabled","source","translate_incoming","translate_outgoing","translate_transcripts","provider_ready","blocking_reasons"],"properties":{"enabled":{"type":"boolean"},"source":{"type":"string","enum":["feature_flag","conversation","inbox","disabled"]},"agent_language":{"type":["string","null"],"example":"pt-BR"},"contact_language":{"type":["string","null"],"example":"en"},"translate_incoming":{"type":"boolean"},"translate_outgoing":{"type":"boolean"},"translate_transcripts":{"type":"boolean"},"provider_ready":{"type":"boolean"},"blocking_reasons":{"type":"array","items":{"type":"string","enum":["provider_not_configured","provider_disabled","project_id_missing","credentials_missing","agent_language_missing","contact_language_missing"]}},"detected_conversation_language":{"type":["string","null"],"example":"en"}}},"translation_provider_readiness":{"type":"object","additionalProperties":false,"required":["provider","ready","blocking_reasons"],"properties":{"provider":{"type":"string","enum":["google_translate"]},"ready":{"type":"boolean"},"blocking_reasons":{"type":"array","uniqueItems":true,"items":{"type":"string","enum":["provider_not_configured","provider_disabled","project_id_missing","credentials_missing"]}}}},"translation_viewer":{"type":"object","additionalProperties":false,"required":["language","source"],"properties":{"language":{"type":"string","example":"pt-BR"},"source":{"type":"string","enum":["profile","conversation","inbox","ui_locale","account","default"]}}},"translation_message_delivery_state":{"type":"object","additionalProperties":false,"required":["status"],"properties":{"status":{"type":"string","enum":["translated","failed"]},"source_language":{"type":["string","null"],"example":"pt"},"target_language":{"type":"string","example":"en"},"provider":{"type":"string","enum":["google_translate","source"]},"content_digest":{"type":"string","pattern":"^[0-9a-f]{64}$"},"translated_at":{"type":"string","format":"date-time"},"error_code":{"type":"string","enum":["translation_failed"]},"cause_code":{"type":"string","enum":["provider_not_configured","missing_target_language","unsupported_language","provider_unavailable","provider_timeout"]},"failed_at":{"type":"string","format":"date-time"}}},"translation_message_view_state":{"type":"object","additionalProperties":false,"required":["status","source_kind","target_language","content_digest"],"properties":{"status":{"type":"string","enum":["translated","source_reuse","failed"]},"source_kind":{"type":"string","enum":["message_content","email_content","typed_original","transmitted"]},"mime_type":{"type":"string","enum":["text/plain","text/html"]},"source_language":{"type":["string","null"],"example":"en"},"target_language":{"type":"string","example":"pt-BR"},"provider":{"type":"string","enum":["google_translate","source","typed_original","transmitted"]},"content_digest":{"type":"string","pattern":"^[0-9a-f]{64}$"},"translated_at":{"type":"string","format":"date-time"},"error_code":{"type":"string","enum":["provider_not_configured","missing_target_language","unsupported_language","provider_unavailable","provider_timeout"]},"failed_at":{"type":"string","format":"date-time"}}},"translation_message_metadata":{"type":"object","additionalProperties":false,"properties":{"original_content":{"type":"string","description":"Exact text typed by the human sender before automatic outbound translation."},"original_html_content":{"type":"string","description":"Exact HTML body authored before automatic outbound translation, retained for idempotent email retry."},"delivery":{"$ref":"#/components/schemas/translation_message_delivery_state"},"views":{"type":"object","description":"Viewer representations keyed by normalized BCP-47 target language.","propertyNames":{"pattern":"^[A-Za-z]{2,3}(?:-[A-Za-z]{4})?(?:-(?:[A-Za-z]{2}|[0-9]{3}))?$"},"additionalProperties":{"$ref":"#/components/schemas/translation_message_view_state"}}}},"translation_message_content_attributes":{"type":"object","additionalProperties":true,"description":"Message attributes. Translation subtrees are presentation data; the parent message content remains canonical.","properties":{"instagram_mention":{"$ref":"#/components/schemas/instagram_mention"},"translations":{"type":"object","propertyNames":{"pattern":"^[A-Za-z]{2,3}(?:-[A-Za-z]{4})?(?:-(?:[A-Za-z]{2}|[0-9]{3}))?$"},"additionalProperties":{"type":"string"},"description":"Viewer representations keyed by normalized BCP-47 target language."},"translation":{"$ref":"#/components/schemas/translation_message_metadata"},"external_error":{"type":"string","description":"Sanitized human-readable delivery failure shown by the dashboard."},"contact_share":{"type":"object","additionalProperties":false,"required":["origin","transport","status"],"description":"What happened to a phone number the contact shared on WhatsApp. Present only on the message of a shared contact card the platform acted on; a third person's card carries no such entry.","properties":{"origin":{"type":"string","enum":["contact_request","self_contact"],"description":"How the number was shared — the contact's answer to a phone request (`contact_request`, WhatsApp Cloud) or the contact's own card (`self_contact`, WhatsApp Web)."},"transport":{"type":"string","enum":["cloud","web"],"description":"WhatsApp transport the card arrived through."},"status":{"type":"string","enum":["linked","unresolved"],"description":"Outcome — the number was linked to the contact (`linked`), or it could not be linked and needs a decision (`unresolved`)."},"reason":{"type":"string","enum":["identity_owned_by_another_contact","shared_phone_differs"],"description":"Why the number was not linked. Present only when `status` is `unresolved`."},"other_contact_ids":{"type":"array","items":{"type":"integer"},"description":"Contacts that already hold the number. Present only when `status` is `unresolved`; empty when the reason is `shared_phone_differs`."},"reconciliation_id":{"type":"string","description":"Identifier of the contact's pending reconciliation entry for this conflict. Present only when `status` is `unresolved`."}}}}},"instagram_mention":{"type":"object","readOnly":true,"description":"Server-enriched Instagram mention. Author identity is scoped to the connected account and inbox; unresolved authors remain in the technical conversation until safely identified. Recovery changes the historical projection without replaying customer messages or commercial automation events.","properties":{"media_id":{"type":"string"},"comment_id":{"type":"string"},"mention_type":{"type":"string","enum":["comment","caption"]},"enrichment_status":{"type":"string","enum":["unresolved","partial","resolved"]},"replyable":{"type":"boolean"},"author_id":{"type":"string"},"author_username":{"type":"string"},"text":{"type":"string"},"media_type":{"type":"string","description":"Media type supplied by Instagram; may be absent during enrichment."},"media_product_type":{"type":"string","description":"Instagram media product designation supplied by the provider."},"permalink":{"type":"string","format":"uri"},"identity_scope":{"type":"object","additionalProperties":false,"required":["account_id","inbox_id","instagram_id"],"properties":{"account_id":{"type":"integer"},"inbox_id":{"type":"integer"},"instagram_id":{"type":"string","description":"Connected Instagram account identifier; not a credential."}}},"recovery":{"type":"object","additionalProperties":false,"description":"Bounded durable enrichment receipt. Only the server can schedule or claim an attempt.","properties":{"state":{"type":"string","enum":["scheduled","processing","resolved","blocked","exhausted"]},"reason":{"type":"string","description":"Sanitized enrichment outcome or recovery reason."},"attempts":{"type":"integer","minimum":0},"checked_at":{"type":"string","format":"date-time"},"next_retry_at":{"type":"string","format":"date-time"},"lease_until":{"type":"string","format":"date-time"}}}}},"instagram_mentions_reconciled":{"type":"object","readOnly":true,"additionalProperties":false,"required":["account_id","conversation_id","version"],"description":"ActionCable-only instagram.mentions_reconciled payload delivered to the authorized conversation audience after a technical projection commit. Refresh the conversation and counters. This is not a commercial webhook, a new inbound message or proof of a new customer interaction.","properties":{"account_id":{"type":"integer"},"conversation_id":{"type":"integer","description":"Account-scoped conversation display identifier."},"version":{"type":"integer","enum":[1]}}},"social_graph_diagnostic":{"type":"object","readOnly":true,"additionalProperties":false,"description":"Sanitized diagnostic for one Graph operation. Provider bodies, credentials and message text are excluded. An uncertain write is not safe to repeat automatically, even when a read could be retried.","properties":{"stage":{"type":"string","description":"Operation stage at which the result was observed."},"code":{"type":"string","description":"Stable local reason or meta_error_\u003cprovider code\u003e."},"provider_code":{"type":"integer"},"provider_subcode":{"type":"integer"},"provider_type":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,128}$","description":"Provider error category when safely representable."},"request_id":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,128}$","description":"Sanitized provider trace identifier."},"http_status":{"type":"integer"},"retryable":{"type":"boolean"},"uncertain":{"type":"boolean"}}},"native_comment_recovery":{"type":"object","readOnly":true,"additionalProperties":false,"description":"Server-owned checkpoint for deliberately enabled recovery of one owned Instagram post. Ordinary rule create/update requests cannot set or replace it. Scope changes block recovery; uncertain delivery receipts are never blindly resent. Absent until an operator configures scoped recovery.","properties":{"actor_id":{"type":"string","description":"Connected Instagram account identifier."},"inbox_id":{"type":"integer"},"post_id":{"type":"string"},"platform":{"type":"string","enum":["instagram"]},"status":{"type":"string","enum":["scheduled","processing","blocked","stopped"]},"since":{"type":"string","format":"date-time"},"initial_since":{"type":"string","format":"date-time"},"cutoff":{"type":["string","null"],"format":"date-time"},"cursor":{"type":["string","null"],"description":"Opaque Graph pagination cursor; not an authorization token."},"pages":{"type":"integer","minimum":0},"attempts":{"type":"integer","minimum":0},"processed":{"type":"integer","minimum":0},"next_run_at":{"type":["string","null"],"format":"date-time"},"lease_until":{"type":["string","null"],"format":"date-time"},"diagnostic":{"anyOf":[{"$ref":"#/components/schemas/social_graph_diagnostic"},{"type":"null"}]}}},"payment_installment_plan":{"type":"object","required":["id","account_id","payments_connection_id","contact_id","organization_id","conversation_id","crm_item_id","payments_subscription_id","installments_count","paid_count","total_amount","installment_amount","last_installment_amount","paid_amount","refunded_amount","installment_interest_rate","strategy","status","billing_type","cycle","installment_mode","currency","gateway_installment_id","gateway","created_at","updated_at","archived_at","first_due_date","projected_schedule","payment_book","allowed_actions","payment_book_degraded","conversation_display_id","notification_preferences","next_due_date"],"properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"payments_connection_id":{"type":["integer","null"]},"contact_id":{"type":["integer","null"]},"organization_id":{"type":["integer","null"]},"conversation_id":{"type":["integer","null"]},"crm_item_id":{"type":["integer","null"]},"payments_subscription_id":{"type":["integer","null"]},"installments_count":{"type":"integer"},"paid_count":{"type":"integer"},"total_amount":{"type":["string","null"],"description":"Decimal major units serialized by Rails."},"installment_amount":{"type":["string","null"],"description":"Decimal major units serialized by Rails."},"last_installment_amount":{"type":["string","null"],"description":"Decimal major units serialized by Rails."},"paid_amount":{"type":["string","null"],"description":"Decimal major units serialized by Rails."},"refunded_amount":{"type":["string","null"],"description":"Decimal major units serialized by Rails."},"installment_interest_rate":{"type":["string","null"],"description":"Decimal major units serialized by Rails."},"strategy":{"type":"string","enum":["native_installment","native_recurrence_capped","local_schedule"]},"status":{"type":"string","enum":["pending","active","partially_paid","completed","overdue","canceled"]},"billing_type":{"type":"string","enum":["pix","boleto","credit_card","debit_card","hosted_link","undefined"]},"cycle":{"type":["string","null"],"enum":["weekly","biweekly","monthly","bimonthly","quarterly","semiannually","yearly",null]},"installment_mode":{"type":["string","null"],"enum":["absorb","passthrough",null]},"currency":{"type":["string","null"]},"gateway_installment_id":{"type":["string","null"]},"gateway":{"type":["string","null"]},"created_at":{"type":["string","null"],"format":"date-time"},"updated_at":{"type":["string","null"],"format":"date-time"},"archived_at":{"type":["string","null"],"format":"date-time"},"first_due_date":{"type":["string","null"],"format":"date"},"projected_schedule":{"type":"array","items":{"type":"object","required":["number","due_date","amount"],"properties":{"number":{"type":"integer"},"due_date":{"type":"string","format":"date"},"amount":{"type":["number","string"]}}}},"payment_book":{"type":"object","required":["state","degraded","stale","refresh_failed","stalled","url"],"properties":{"state":{"type":"string","enum":["pending","ready","failed"]},"degraded":{"type":"boolean"},"stale":{"type":"boolean","description":"True while the payment book on file predates the latest installment change (a payment, cancellation, refund or overdue) and a coalesced regeneration is pending. The previous file stays downloadable; it must not be sent to the customer until this turns false."},"refresh_failed":{"type":"boolean","description":"True when the last attempt to rebuild a stale payment book failed; it is retried and can be requested again with a POST to the payment book endpoint. The previous PDF stays downloadable."},"stalled":{"type":"boolean","description":"True when the book has been pending for longer than a generation takes (10 minutes) with no live job behind it. A POST to the payment book endpoint starts the first build again."},"url":{"type":["string","null"],"description":"Authenticated account-scoped PDF download endpoint."}}},"allowed_actions":{"type":"object","properties":{"payment_book":{"type":"boolean"},"send_to_conversation":{"type":"boolean","description":"Whether the payment book may be sent to a conversation. False while the book is being regenerated (payment_book.stale) and once the plan has nothing left to pay (canceled or completed)."},"send_installment":{"type":"boolean","description":"Whether a single installment of this plan may be sent to a conversation. False when the plan send is not released on its connection (for example a sandbox connection in a production install) or the plan has nothing left to pay. Only open installments (pending, awaiting_payment, overdue) are accepted by the send endpoint."},"update":{"type":"boolean"},"cancel":{"type":"boolean"},"destroy":{"type":"boolean"},"refund":{"type":"boolean"},"update_notification_preferences":{"type":"boolean","description":"Whether this plan's notification preferences may be changed. False once the plan has nothing left to pay."}}},"payment_book_degraded":{"type":"boolean"},"conversation_display_id":{"type":["integer","null"]},"contact_name":{"type":"string","description":"Payer name, present only when the contact exists and the name field is visible to the requester."},"next_due_date":{"type":["string","null"],"format":"date","description":"Due date of the earliest open installment; null when none is open or the next one has not been issued yet."},"gateway_payment_book":{"type":"object","properties":{"url":{"type":["string","null"],"description":"Authenticated operator-only secondary gateway PDF URL. Never use as a customer attachment."}}},"open_installments_count":{"type":"integer","minimum":0,"description":"Authoritative count of materialized open charges (pending, awaiting_payment, overdue)."},"financial_evidence":{"type":"object","additionalProperties":{"type":"string","enum":["live","test_only"]},"description":"Release evidence for new installment financial actions. test_only requires a validated sandbox; sending additionally requires a persistent no-egress sink."},"notification_preferences":{"type":"object","additionalProperties":false,"properties":{"payment_charge_paid":{"type":"boolean","default":false},"installment_plan_completed":{"type":"boolean","default":true}},"required":["payment_charge_paid","installment_plan_completed"]}}},"json_value":{"type":["object","array","string","number","boolean","null"],"description":"A stored JSON value, including nested objects, arrays and scalar values.","additionalProperties":{"$ref":"#/components/schemas/json_value"},"items":{"$ref":"#/components/schemas/json_value"}}},"parameters":{"account_id":{"in":"path","name":"account_id","schema":{"type":"integer"},"required":true,"description":"The numeric ID of the account"},"agent_bot_id":{"in":"path","name":"id","schema":{"type":"integer"},"required":true,"description":"The ID of the agentbot to be updated"},"team_id":{"in":"path","name":"team_id","schema":{"type":"integer"},"required":true,"description":"The ID of the team to be updated"},"inbox_id":{"in":"path","name":"inbox_id","schema":{"type":"integer"},"required":true,"description":"The ID of the Inbox"},"hook_id":{"in":"path","name":"hook_id","schema":{"type":"integer"},"required":true,"description":"The numeric ID of the integration hook"},"contact_sort_param":{"in":"query","name":"sort","schema":{"type":"string","enum":["name","email","phone_number","last_activity_at","-name","-email","-phone_number","-last_activity_at"]},"required":false,"description":"The attribute by which list should be sorted"},"conversation_id":{"in":"path","name":"conversation_id","schema":{"type":"integer"},"required":true,"description":"The numeric ID of the conversation"},"conversation_uuid":{"in":"path","name":"conversation_uuid","schema":{"type":"integer"},"required":true,"description":"The uuid of the conversation"},"custom_filter_id":{"in":"path","name":"custom_filter_id","schema":{"type":"integer"},"required":true,"description":"The numeric ID of the custom filter"},"webhook_id":{"in":"path","name":"webhook_id","schema":{"type":"integer"},"required":true,"description":"The numeric ID of the webhook"},"message_id":{"in":"path","name":"message_id","schema":{"type":"integer"},"required":true,"description":"The numeric ID of the message"},"page":{"in":"query","name":"page","schema":{"type":"integer","default":1},"required":false,"description":"The page parameter"},"platform_user_id":{"in":"path","name":"id","schema":{"type":"integer"},"required":true,"description":"The numeric ID of the user on the platform"},"report_type":{"in":"query","name":"type","schema":{"type":"string","enum":["account","agent","inbox","label","team"]},"required":true,"description":"Type of report"},"report_metric":{"in":"query","name":"metric","schema":{"type":"string","enum":["conversations_count","incoming_messages_count","outgoing_messages_count","avg_first_response_time","avg_resolution_time","resolutions_count"]},"required":true,"description":"The type of metric"},"public_inbox_identifier":{"in":"path","name":"inbox_identifier","schema":{"type":"string"},"required":true,"description":"The identifier obtained from API inbox channel"},"public_contact_identifier":{"in":"path","name":"contact_identifier","schema":{"type":"string"},"required":true,"description":"The source id of contact obtained on contact create"},"portal_id":{"in":"path","name":"id","schema":{"type":"string"},"required":true,"description":"The slug identifier of the portal"},"mcp_oauth_content_length":{"name":"Content-Length","in":"header","required":true,"description":"Exact decimal byte length of the OAuth form body. Browser and HTTP clients normally set it automatically. The server rejects a missing, malformed or chunked body and accepts at most 16 KiB before parsing OAuth parameters.","schema":{"type":"integer","minimum":0,"maximum":16384},"example":243},"mcp_protocol_version":{"name":"MCP-Protocol-Version","in":"header","required":false,"description":"Negotiated MCP protocol revision. Legacy clients negotiate with `initialize.params.protocolVersion`; modern stateless clients send this header and the matching `_meta.io.modelcontextprotocol/protocolVersion` in their JSON-RPC envelope. It is an MCP transport header, not a REST API version. Omit it only while performing the legacy initialize negotiation.","schema":{"type":"string","enum":["2026-07-28","2025-11-25","2025-06-18","2025-03-26","2024-11-05"]},"example":"2026-07-28"},"mcp_modern_method":{"name":"Mcp-Method","in":"header","required":false,"description":"Modern (2026-07-28) MCP routing hint for the JSON-RPC method. It mirrors, rather than replaces, the `method` member of the JSON-RPC envelope; legacy clients must continue to use that envelope.","schema":{"type":"string"},"example":"tools/list"},"mcp_modern_name":{"name":"Mcp-Name","in":"header","required":false,"description":"Modern (2026-07-28) MCP routing hint for the selected tool or resource name when the method needs one. It does not name a REST operation and is ignored for legacy JSON-RPC negotiation.","schema":{"type":"string"},"example":"conversations_list"},"mcp_public_id":{"name":"public_id","in":"path","required":true,"description":"Public, non-secret identifier of the enabled MCP access profile.","schema":{"type":"string","minLength":20,"maxLength":20,"pattern":"^[a-z0-9]{20}$"},"example":"a1b2c3d4e5f6g7h8i9j0"}},"securitySchemes":{"userApiKey":{"type":"apiKey","in":"header","name":"api_access_token","description":"This token can be obtained by visiting the profile page or via rails console. Provides access to endpoints based on the user permissions levels. This token can be saved by an external system when user is created via API, to perform activities on behalf of the user."},"agentBotApiKey":{"type":"apiKey","in":"header","name":"api_access_token","description":"This token should be provided by system admin or obtained via rails console. This token can be used to build bot integrations and can only access limited apis."},"platformAppApiKey":{"type":"apiKey","in":"header","name":"api_access_token","description":"This token can be obtained by the system admin after creating a platformApp. This token should be used to provision agent bots, accounts, users and their roles."},"widgetWebsiteToken":{"type":"apiKey","in":"query","name":"website_token","description":"Public website token used only to bootstrap a widget session."},"widgetContactJwt":{"type":"apiKey","in":"header","name":"X-Auth-Token","description":"Widget contact-session JWT. It is distinct from account API tokens."},"operationsMetricsBearer":{"type":"http","scheme":"bearer","bearerFormat":"opaque","description":"OPERATIONS_METRICS_TOKEN for the Prometheus operations scrape endpoint."},"metaWebhookHmac":{"type":"apiKey","in":"header","name":"X-Hub-Signature-256","description":"Meta raw-body HMAC signature when the resolved integration requires one."},"lineWebhookHmac":{"type":"apiKey","in":"header","name":"x-line-signature","description":"LINE raw-body HMAC signature."},"linearWebhookHmac":{"type":"apiKey","in":"header","name":"Linear-Signature","description":"Linear raw-body HMAC signature."},"maestroWebhookHmac":{"type":"apiKey","in":"header","name":"X-Maestro-Signature","description":"Maestro timestamped raw-body HMAC signature."},"asaasAccessToken":{"type":"apiKey","in":"header","name":"asaas-access-token","description":"Asaas webhook token."},"mercadoPagoWebhookHmac":{"type":"apiKey","in":"header","name":"x-signature","description":"Mercado Pago webhook signature."},"flowWebhookHmac":{"type":"apiKey","in":"header","name":"X-Chatwoot-Signature","description":"Flow Builder per-flow raw-body HMAC signature."},"flowWebhookBearer":{"type":"http","scheme":"bearer","bearerFormat":"opaque","description":"Flow Builder per-flow bearer token."},"flowWebhookUrlToken":{"type":"apiKey","in":"query","name":"token","description":"Flow Builder per-flow URL capability token."},"hotmartWebhookHmac":{"type":"apiKey","in":"header","name":"X-Hotmart-Hottok","description":"Hotmart webhook token."},"kiwifyWebhookToken":{"type":"apiKey","in":"header","name":"x-kiwify-token","description":"Kiwify webhook token."},"nuvemshopWebhookHmac":{"type":"apiKey","in":"header","name":"x-linkedstore-hmac-sha256","description":"Nuvemshop webhook HMAC."},"salesIngestHeader":{"type":"apiKey","in":"header","name":"X-Sales-Ingest-Token","description":"Sales ingest token supplied as a header."},"salesIngestQuery":{"type":"apiKey","in":"query","name":"token","description":"Sales ingest token supplied as a query capability."},"googleCalendarChannelToken":{"type":"apiKey","in":"header","name":"X-Goog-Channel-Token","description":"Google Calendar watch-channel token."},"tiktokWebhookHmac":{"type":"apiKey","in":"header","name":"Tiktok-Signature","description":"TikTok timestamped webhook HMAC."},"shopifyWebhookHmac":{"type":"apiKey","in":"header","name":"X-Shopify-Hmac-SHA256","description":"Shopify raw-body HMAC signature."},"stripeWebhookSignature":{"type":"apiKey","in":"header","name":"Stripe-Signature","description":"Stripe raw-body webhook signature."},"twilioWebhookSignature":{"type":"apiKey","in":"header","name":"X-Twilio-Signature","description":"Twilio request signature."},"bandwidthCallbackBasic":{"type":"http","scheme":"basic","description":"Per-SMS-channel Bandwidth callback credential pair. It is accepted only on the inbound Bandwidth callback route, is encrypted at rest, and is never returned by this API."},"twitterWebhookHmac":{"type":"apiKey","in":"header","name":"x-twitter-webhooks-signature","description":"Twitter/X Account Activity webhook signature in the form `sha256=Base64(HMAC-SHA256(raw request body, consumer secret))`. It is verified against the raw body before JSON parsing, account selection, queueing, or any side effect. The consumer secret is never returned by this API."},"catalogSyncHmac":{"type":"apiKey","in":"header","name":"X-Catalog-Signature","description":"Per-source HMAC-SHA256 signature over the timestamp and exact raw request body. The selected source, timestamp and delivery identifier remain explicit headers; the source access token is never returned by this API."},"whatsappCallTicket":{"type":"apiKey","in":"query","name":"ticket","description":"Short-lived, kind-scoped signed ticket minted by the authenticated WhatsApp Web call action. The server binds it to the account, call and stream kind and rejects expired, mismatched or replayed-across-kind tickets."},"mcpProfileBearer":{"type":"http","scheme":"bearer","description":"The secret of an MCP access profile, sent as `Authorization: Bearer \u003csecret\u003e`. It is created under Settings → MCP and shown once, on create and on rotate; only its hash is stored. This is NOT one of the account API keys and the `api_access_token` header is not read by the MCP connection endpoint — sending it there always fails authentication. Each call executes as the profile's acting user, so that user's permissions still bound what the connection can do."},"superAdminMcpBearer":{"type":"http","scheme":"bearer","bearerFormat":"opaque","description":"Dedicated Super Admin MCP credential (`SuperAdminAccessToken`) sent as `Authorization: Bearer \u003ccredential\u003e`. It is accepted only by `/super_admin/mcp`; account access tokens (including the normal token owned by a Super Admin), Platform App credentials, OAuth MCP bearers, and the separate Operator REST API scheme cannot authenticate this static MCP transport."},"mcpOauth":{"type":"oauth2","description":"Native MCP OAuth 2.1 Authorization Code flow for the separate OAuth MCP resource URLs. It is available only when the installation enables its OAuth server. Public clients use S256 PKCE and identify themselves with `client_id`; no client secret is issued or accepted. A token is bound to one exact resource URL and authority plane, so it cannot be replayed against the static bearer endpoint, another account profile, Platform, or Super Admin.","flows":{"authorizationCode":{"authorizationUrl":"https://chatwoot.losangosolucoes.com.br/oauth/mcp/authorize","tokenUrl":"https://chatwoot.losangosolucoes.com.br/oauth/mcp/token","refreshUrl":"https://chatwoot.losangosolucoes.com.br/oauth/mcp/token","scopes":{"mcp:read":"Read-only MCP tools for the exact approved resource.","mcp:write":"Allows write-capable MCP tools when the resource policy also permits them; requires `mcp:read`.","offline_access":"Requests a rotating refresh token for the exact approved resource."}}}}}},"tags":[{"name":"Accounts","description":"Account management APIs"},{"name":"Account Users","description":"Account user management APIs"},{"name":"AgentBots","description":"Bot integrations"},{"name":"Users","description":"User management APIs"},{"name":"Account AgentBots","description":"Account-specific Agent Bots"},{"name":"Agents","description":"Agent management APIs"},{"name":"Canned Responses","description":"Pre-defined responses for common queries"},{"name":"Contacts","description":"Contact management APIs"},{"name":"Contact Labels","description":"Manage contact labels"},{"name":"Conversation Assignments","description":"Manage conversation assignments"},{"name":"Conversations","description":"Conversation management APIs"},{"name":"Custom Attributes","description":"Custom fields for contacts and conversations"},{"name":"Custom Filters","description":"Saved filters for conversations"},{"name":"Inboxes","description":"Communication channels setup"},{"name":"Integrations","description":"Third-party integrations"},{"name":"Labels","description":"Account label management APIs"},{"name":"Messages","description":"Message management APIs"},{"name":"Profile","description":"User profile APIs"},{"name":"Reports","description":"Analytics and reporting APIs"},{"name":"Teams","description":"Team management APIs"},{"name":"Webhooks","description":"Event notification webhooks"},{"name":"Automation Rule","description":"Workflow automation rules"},{"name":"Help Center","description":"Knowledge base management"},{"name":"CRM Pipelines","description":"CRM pipeline management APIs"},{"name":"CRM Stages","description":"CRM pipeline stage management APIs"},{"name":"CRM Items","description":"CRM item (deal) management APIs"},{"name":"CRM Item Notes","description":"Notes on CRM items"},{"name":"CRM Item Attachments","description":"File attachments on CRM items"},{"name":"CRM Item Participants","description":"Agent collaborators on CRM items"},{"name":"CRM Item Checklist","description":"Checklist items on CRM items"},{"name":"CRM Organizations","description":"Deprecated alias tag for the canonical Organizations APIs"},{"name":"Organizations","description":"Organization (Empresas) management APIs — fiscal identity, hierarchy and 360 overview"},{"name":"Organization Memberships","description":"Contact ⟷ organization membership APIs (roles, primary organization)"},{"name":"Relationships","description":"Typed relationship edges between contacts and organizations"},{"name":"Relationship Types","description":"Relationship-type catalog and niche presets"},{"name":"CRM Reports","description":"CRM analytics and reporting APIs"},{"name":"CRM Templates","description":"CRM pipeline templates and demo data"},{"name":"Catalog Products","description":"Catalog product and service APIs (incl. import/export)"},{"name":"Catalog Categories","description":"Catalog category APIs"},{"name":"Catalog Variants","description":"Catalog product variant and stock APIs"},{"name":"Catalog Reports","description":"Catalog analytics and reporting APIs"},{"name":"Catalog Sync Sources","description":"External catalog sync source configuration (ERP/e-commerce/PIM)"},{"name":"Catalog Sync Runs","description":"Catalog import/export/sync run history"},{"name":"Catalog Sync Inbound","description":"HMAC-authenticated inbound bulk product upsert"},{"name":"Payment Connections","description":"Payment gateway connections (Asaas / Mercado Pago)"},{"name":"Payment Charges","description":"Charges (cobranças) — create, refund, send into a conversation"},{"name":"Payment Subscriptions","description":"Subscriptions (assinantes) — gateway-delegated recurrence"},{"name":"Payment Plans","description":"Reusable subscription plans"},{"name":"Payment Offers","description":"Administrative catalog of order bumps, upsells and downsells"},{"name":"Payment Reports","description":"Payments analytics (revenue, by gateway, MRR, churn)"},{"name":"Payment Demo","description":"Demo payments data seeding/teardown (admin)"},{"name":"Calendar","description":"Native calendars (agenda) + Google Calendar two-way sync"},{"name":"Calendar Events","description":"Calendar events — create, update, reschedule, cancel"},{"name":"Calendar Event Types","description":"Bookable event types (Calendly-style) + slots + booking link"},{"name":"Calendar Connections","description":"Google Calendar OAuth connections (permanent, self-refreshing)"},{"name":"Calendar Availability","description":"Weekly availability windows + date overrides"},{"name":"Calendar Settings","description":"Account-level scheduling configuration"},{"name":"Calendar Reports","description":"Scheduling analytics (bookings, no-shows, utilization)"},{"name":"Calendar Bookings","description":"Account-side booking listing with manage links (reschedule/cancel URLs)"},{"name":"Calendar Public Booking","description":"Public Calendly-style booking pages (opaque token-keyed)"},{"name":"Contacts API","description":"Public contact APIs"},{"name":"Conversations API","description":"Public conversation APIs"},{"name":"Messages API","description":"Public message APIs"},{"name":"CSAT Survey Page","description":"Customer satisfaction survey"},{"name":"Tasks","description":"Native tasks — CRUD, board actions, lifecycle (archive/restore/purge), bulk actions and activity timeline"},{"name":"Task Lists","description":"Task list/board containers — CRUD, reorder and archive/restore/purge lifecycle"},{"name":"Task SLA Policies","description":"Native Task SLA policies (admin-only) targeting tasks by priority and/or list"},{"name":"Task Templates","description":"Reusable task blueprints applied at create time, plus the async Tasks demo seed/teardown"},{"name":"Task Comments","description":"Comments on a task"},{"name":"Task Checklist","description":"Checklist items on a task — CRUD, toggle completion and reorder"},{"name":"Task Attachments","description":"File attachments on a task (Active Storage)"},{"name":"Task Dependencies","description":"Blocking/blocked-by dependency edges between tasks (cycle-guarded)"},{"name":"Task Links","description":"Polymorphic links from a task to Conversations, Contacts and CRM items"},{"name":"Task Reminders","description":"Scheduled in-app/email reminders on a task"},{"name":"Task Watchers","description":"Users watching a task to receive its notifications"},{"name":"CRM Item Line Items","description":"Catalog line items on CRM items (deal quotes)"},{"name":"Account","description":"Account-level operations"},{"name":"Audit Logs","description":"Account audit log APIs"},{"name":"Inbox API","description":"Inbox channel APIs"},{"name":"API","description":"API endpoints"},{"name":"Access Roles","description":"Access Roles endpoints"},{"name":"Ads","description":"Ads endpoints"},{"name":"Agent Bots","description":"Agent Bots endpoints"},{"name":"Agent Capacity Policies","description":"Agent Capacity Policies endpoints"},{"name":"Apple-app-site-association","description":"Apple-app-site-association endpoints"},{"name":"Assetlinks.json","description":"Assetlinks.json endpoints"},{"name":"Assignable Agents","description":"Assignable Agents endpoints"},{"name":"Assignment Policies","description":"Assignment Policies endpoints"},{"name":"Auth","description":"Auth endpoints"},{"name":"Authentication","description":"Authentication endpoints"},{"name":"Branded Email Layout","description":"Branded Email Layout endpoints"},{"name":"Bug Reports","description":"Bug Reports endpoints"},{"name":"Bulk Actions","description":"Bulk Actions endpoints"},{"name":"CRM","description":"CRM endpoints"},{"name":"CSAT Survey Responses","description":"CSAT Survey Responses endpoints"},{"name":"Call","description":"Call endpoints"},{"name":"Callback","description":"Callback endpoints"},{"name":"Callbacks","description":"Callbacks endpoints"},{"name":"Calls","description":"Calls endpoints"},{"name":"Campaign Suppressions","description":"Campaign Suppressions endpoints"},{"name":"Campaigns","description":"Campaigns endpoints"},{"name":"Captain","description":"Captain endpoints"},{"name":"Catalog","description":"Catalog endpoints"},{"name":"Channels","description":"Channels endpoints"},{"name":"Commerce","description":"Commerce endpoints"},{"name":"Companies","description":"Companies endpoints"},{"name":"Conference Status","description":"Conference Status endpoints"},{"name":"Contact Inboxes","description":"Contact Inboxes endpoints"},{"name":"Contextual Help","description":"Contextual Help endpoints"},{"name":"Contracts","description":"Contracts endpoints"},{"name":"Conversation Sidebar Layout","description":"Conversation Sidebar Layout endpoints"},{"name":"Custom Roles","description":"Custom Roles endpoints"},{"name":"Custom Scripts","description":"Custom Scripts endpoints"},{"name":"Dashboard App SDK","description":"Dashboard App SDK endpoints"},{"name":"Dashboard Apps","description":"Dashboard Apps endpoints"},{"name":"Data Imports","description":"Data Imports endpoints"},{"name":"Delivery Status","description":"Delivery Status endpoints"},{"name":"Engagement","description":"Engagement endpoints"},{"name":"Firecrawl","description":"Firecrawl endpoints"},{"name":"Flow Builder","description":"Flow Builder endpoints"},{"name":"Follow-up","description":"Follow-up endpoints"},{"name":"Google","description":"Google endpoints"},{"name":"Governance","description":"Governance endpoints"},{"name":"Growth Distribution","description":"Growth Distribution endpoints"},{"name":"Growth Social","description":"Growth Social endpoints"},{"name":"Guided Tours","description":"Guided Tours endpoints"},{"name":"Health","description":"Health endpoints"},{"name":"Inbound Webhooks","description":"Inbound Webhooks endpoints"},{"name":"Instagram","description":"Instagram endpoints"},{"name":"Internal Chat","description":"Internal Chat endpoints"},{"name":"Limits","description":"Limits endpoints"},{"name":"Live Reports","description":"Live Reports endpoints"},{"name":"Macros","description":"Macros endpoints"},{"name":"Maestro","description":"Maestro endpoints"},{"name":"Mcp","description":"Mcp endpoints"},{"name":"Media Library","description":"Media Library endpoints"},{"name":"Message Schedules","description":"Message Schedules endpoints"},{"name":"Message Scheduling","description":"Message Scheduling endpoints"},{"name":"Messaging","description":"Messaging endpoints"},{"name":"Microsoft","description":"Microsoft endpoints"},{"name":"Microsoft-identity-association.json","description":"Microsoft-identity-association.json endpoints"},{"name":"Monitoring","description":"Monitoring endpoints"},{"name":"Notification Subscriptions","description":"Notification Subscriptions endpoints"},{"name":"Notifications","description":"Notifications endpoints"},{"name":"Notion","description":"Notion endpoints"},{"name":"Oauth-protected-resource","description":"Oauth-protected-resource endpoints"},{"name":"Onboarding","description":"Onboarding endpoints"},{"name":"Payment Installment Plans","description":"Payment Installment Plans endpoints"},{"name":"Payment Public Page","description":"Payment Public Page endpoints"},{"name":"Payments","description":"Payments endpoints"},{"name":"Platform Accounts","description":"Platform Accounts endpoints"},{"name":"Platform Mcp","description":"Platform Mcp endpoints"},{"name":"Platform Notifications","description":"Platform Notifications endpoints"},{"name":"Public CSAT Survey","description":"Public CSAT Survey endpoints"},{"name":"Public Calendar","description":"Public Calendar endpoints"},{"name":"Public Contracts","description":"Public Contracts endpoints"},{"name":"Public Engagement","description":"Public Engagement endpoints"},{"name":"Public Growth Social","description":"Public Growth Social endpoints"},{"name":"Public Inboxes","description":"Public Inboxes endpoints"},{"name":"Public Orders","description":"Public Orders endpoints"},{"name":"Public Sales","description":"Public Sales endpoints"},{"name":"Recording Status","description":"Recording Status endpoints"},{"name":"Routing Policies","description":"Routing Policies endpoints"},{"name":"SAML","description":"SAML endpoints"},{"name":"SLA Policies","description":"SLA Policies endpoints"},{"name":"Sales","description":"Sales endpoints"},{"name":"Search","description":"Search endpoints"},{"name":"Setup","description":"Setup endpoints"},{"name":"Status","description":"Status endpoints"},{"name":"Stripe","description":"Stripe endpoints"},{"name":"Summary Reports","description":"Summary Reports endpoints"},{"name":"Team Management","description":"Team Management endpoints"},{"name":"TikTok","description":"TikTok endpoints"},{"name":"Twitter","description":"Twitter endpoints"},{"name":"Upload","description":"Upload endpoints"},{"name":"Usage","description":"Usage endpoints"},{"name":"WhatsApp","description":"WhatsApp endpoints"},{"name":"WhatsApp Calls","description":"WhatsApp Calls endpoints"},{"name":"WhatsApp Hub","description":"WhatsApp Hub endpoints"},{"name":"WhatsApp Web","description":"WhatsApp Web endpoints"},{"name":"WhatsApp Web Calls","description":"WhatsApp Web Calls endpoints"},{"name":"Widget","description":"Widget endpoints"},{"name":"Year In Review","description":"Year In Review endpoints"},{"name":"{id}","description":"{id} endpoints"},{"name":"{locale}","description":"{locale} endpoints"}],"x-tagGroups":[{"name":"Platform","tags":["Accounts","Account Users","AgentBots","Users"]},{"name":"Application","tags":["Account AgentBots","Account","Agents","Audit Logs","Canned Responses","Contacts","Contact Labels","Conversation Assignments","Conversations","Custom Attributes","Custom Filters","Inboxes","Integrations","Labels","Messages","Profile","Reports","Teams","Webhooks","Automation Rule","Help Center","CRM Pipelines","CRM Stages","CRM Items","CRM Item Notes","CRM Item Attachments","CRM Item Participants","CRM Item Checklist","CRM Organizations","Organizations","Organization Memberships","Relationships","Relationship Types","CRM Reports","CRM Templates","Catalog Products","Catalog Categories","Catalog Variants","Catalog Reports","Catalog Sync Sources","Catalog Sync Runs","Catalog Sync Inbound","Payment Connections","Payment Charges","Payment Subscriptions","Payment Plans","Payment Offers","Payment Reports","Payment Demo","Calendar","Calendar Events","Calendar Event Types","Calendar Connections","Calendar Availability","Calendar Settings","Calendar Reports","Calendar Bookings","Calendar Public Booking"]},{"name":"Client","tags":["Contacts API","Conversations API","Messages API"]},{"name":"Others","tags":["CSAT Survey Page"]},{"name":"ConversaLabs Modules","tags":["API","Access Roles","Ads","Agent Bots","Agent Capacity Policies","Apple-app-site-association","Assetlinks.json","Assignable Agents","Assignment Policies","Auth","Authentication","Branded Email Layout","Bug Reports","Bulk Actions","CRM","CRM Item Line Items","CSAT Survey Responses","Call","Callback","Callbacks","Calls","Campaign Suppressions","Campaigns","Captain","Catalog","Channels","Commerce","Companies","Conference Status","Contact Inboxes","Contextual Help","Contracts","Conversation Sidebar Layout","Custom Roles","Custom Scripts","Dashboard App SDK","Dashboard Apps","Data Imports","Delivery Status","Engagement","Firecrawl","Flow Builder","Follow-up","Google","Governance","Growth Distribution","Growth Social","Guided Tours","Health","Inbound Webhooks","Inbox API","Instagram","Internal Chat","Limits","Live Reports","Macros","Maestro","Mcp","Media Library","Message Schedules","Message Scheduling","Messaging","Microsoft","Microsoft-identity-association.json","Monitoring","Notification Subscriptions","Notifications","Notion","Oauth-protected-resource","Onboarding","Payment Installment Plans","Payment Public Page","Payments","Platform Accounts","Platform Mcp","Platform Notifications","Public CSAT Survey","Public Calendar","Public Contracts","Public Engagement","Public Growth Social","Public Inboxes","Public Orders","Public Sales","Recording Status","Routing Policies","SAML","SLA Policies","Sales","Search","Setup","Status","Stripe","Summary Reports","Task Attachments","Task Checklist","Task Comments","Task Dependencies","Task Links","Task Lists","Task Reminders","Task SLA Policies","Task Templates","Task Watchers","Tasks","Team Management","TikTok","Twitter","Upload","Usage","WhatsApp","WhatsApp Calls","WhatsApp Hub","WhatsApp Web","WhatsApp Web Calls","Widget","Year In Review","{id}","{locale}"]}]}